# import_scenario

> Read a .json file that contains the configurations

---

## Description
A .json file contains basic simulation parameters,
and the filenames of EV data, and a demand (base load) or a price
of electricity, both of which are written in .xlsx (MS-Excel) files.

## Syntax
```matlab
sc = import_scenario('my_json_file.json')
sc = import_scenario("my_json_file.json")
```

## Input Arguments
| Name | Type | Description |
|------|------|--------------|
| `jsonfile` | See Additional Explanation | The .json file name with extension .json. |

## Output Arguments
| Name | Type | Description |
|------|------|--------------|
| `sc` | *Scenario object* | Validated class variable |

## Additional Explanation

Manual creation of a scenario may be a hard job. In order to facilitate the job, one can use Microsoft Excel program for managing EV list and their properties, for the base loads, and the electricity prices. The simulator presents a function `import_scenario` which read the Excel file as well as a JSON file that contains basic parameters for the simulation.

### 1. Components of JSON file

A text file, called a JSON file, can be located in a working directory, whose sample looks like:
```
{
  "Problem_type": "Lf",
  "N_c": 50,
  "N_ev": 50,
  "T": 24,
  "N_g": 1,
  "Delta": 60,
  "P_min": -200,
  "P_max":  200,
  "Baseload_file": "Baseload.xlsx",
  "EV_file": "EV_Lf.xlsx"
}
```

The JSON file should contain the following components. 

| **Key** | **Type** | **Description** | **Note** |
|----------|-----------|----------------|-----------|
| `Problem_type` | *"Lf"* \| *"Uf"* | Type of the optimization problem to be solved: either load flattening or user-friendly problem |  |
| `N_c` | *positive integer* | Number of chargers |  |
| `N_ev` | *positive integer* | Number of EVs |  |
| `N_g` | *positive integer* | Number of groups (default: 1) | used for analysis |
| `T` | *positive integer* | Number of time slots. Since each time slot corresponds `Delta` minutes, the length of the scenario is `Delta` x `T` min. |  |
| `Delta` | *positive integer* | Time interval of a time slot (min) |  |
| `P_max` | *positive integer* | Maximal charging power of aggregate EV load (kW) |  |
| `P_min` | *negative integer* | Maximal discharging power aggregate EV load (kW) |  |
| `graph_type` | *"star"* \| *"ring"* \| *"complete"* | Shape of communication graph | Only for distributed optimization |
| `stareye` | *positive integer* | Node index of the center for the star graph | Only for the case of star graph |
| `EV_file` | *excel file (.xlsx)* | File name of EVs data |  |
| `Baseload_file` | *excel file (.xlsx)* | File name of the base load profile | Only for "Lf" case |
| `Price_file` | *excel file (.xlsx)* | File name of the electricity price profile | Only for "Uf" case |


### 2. Excel File Constraints

Two excel files are required to complete a scenario. One contains the base load or the electricity price for the optimization horizon (e.g., 24 hours) depending on the problem type to be solved. The other file contains the data of all EVs whose charging/discharging schedules are to be computed.

```{note}
The column headers of the excel files must be the reserved keywords, which are listed below. It is recommended to use the sample excel files.
```

**Base load (excel file)** 

| **Column name**       | **Type** | **Description**   | 
|------------------|-------------------| ---------| 
| `time_slot`    | *positive integer* | Starting from 1, this number indicates the id of the time slot whose length is ``Delta``. |
| `base_load`      | *positive integer* | Predicted power load used for the load flattening problem |

**Electricity price (excel file)**

| **Column name**       | **Type** | **Description**   | 
|------------------|-------------------| ---------| 
| `time_slot`    | *positive integer* | Starting from 1, this number indicates the id of the time slot whose length is ``Delta``. |
| `electricity_price` | *positive integer* | Electricity price of the corresponding time slot, predicted or announced ahead, for the use of the user-friendly scheduling problem |


**EV information (excel file)** 

| **Column**       | **Type** | **Description**   | 
|------------------|-------------------| ---------| 
| `Charger_ind`    | *positive integer* | Index of charger |
| `Group_ind`      | *positive integer* | Index of group to which the EV belongs |
| `Arr_time`       | *positive integer* | Index of arrival time slot |
| `Dep_time`       | *positive integer* | Index of departure time slot |
| `E_min`          | *nonnegative integer* | Minimum required battery energy (kWh) |
| `E_cap`          | *positive integer* | Battery energy capacity (kWh) |
| `E_ini`          | *nonnegative integer* | Initial energy at arrival (kWh) |
| `E_ref`          | *nonnegative integer* | Reference (target) energy at departure (kWh) |
| `U_max`          | *positive integer* | Maximum charging power (kW) |
| `U_min`          | *nonpositive integer* | Maximum discharging power (kW) |

``Goup_ind`` is introduced for the convenience of the analysis after the optimal scheduling problem is solved. By indicating the group id for individual EV, one can compute different statistics depending on the group id. For example, one can assign group 1 to all the cars made by Hyundai Motors, and compute average discharing power for the group.


- `Price_file`: The number of rows in the electricity price data must be equal to `T` in the `Scenario`.