# Energy System Modelling

## Structure of import files

Each context is represented by a collection of different CSV files. 

<div align="center">

![Import files](../../_static/structure_import_files.png)

</div>


### CONTEXT.csv

The **CONTEXT.csv** file contains the main parameters of your context:

- _name: the name of your context
- TIMESTEP_COUNT: the number of timesteps you want to represent for your energy system. This is the strategic horizon of
the problem and corresponds to the total duration of the entire problem.
- TIMESTEP_DURATION: the duration in minutes of all the timesteps.
- START_DATE: the start date of the energy system you want to model.
- CONTEXT_TYPE: 
  - SIMULATION: useful if you want to simulate an energy system for classic studies.
  - OPTIM_CAPA: useful if you want to optimize the capacity of one or multiple assets for classic studies.
  - PATHWAY_SIMULATION: useful if you want to simulate an energy system for scenarisation studies.
  - PATHWAY_OPTIM: useful if you want to optimize the capacity of one or multiple assets for scenarisation studies.
- OPERATIONAL_HORIZON: only used in SIMULATION and PATHWAY_SIMULATION context type, corresponding to the length of the
interval for which the solutions of the small optimization problem (see TACTICAL_HORIZON) are kept in the full solution.
- TACTICAL_HORIZON: only used in SIMULATION and PATHWAY_SIMULATION context type, corresponding to the length of the
smaller optimization problems horizon.
- SIMU_AFTER_OPTIM_CAPA: only used in OPTIM_CAPA and PATHWAY_OPTIM context type, set to True to have access to correct
marginal costs. See [Capacity optimization documentation](capacity_optimization.md) for more information.

<div align="center">

![Optimization process with rolling horizons](../../_static/optim_process_rolling_horizons.png)

</div>

<blockquote class="calculation-hint">
  <h4>Optimization process with rolling horizons</h4>

  In this case, the resolution consists in solving iteratively smaller simulation problems over a tactical horizon, as
  depicted in the figures above and below. The solution kept over each iteration is defined by the operational horizon.
  At each iteration, the initial states of the assets are set using results obtained from the previous iterations
  (states of the assets at the end of previous operational horizon). This approach allows to reduce computation times
  and resources. 

</blockquote>

<div align="center">

![Optimization process with rolling horizons 2](../../_static/optim_process_rolling_horizons_2.png)

</div>

### Assets folder

The **Assets** folder contains csv files corresponding to the assets of your energy system. One file corresponds to one 
asset type (coal power plant, solar fleet, etc). Each csv file includes all assets of the given type (for example all 
coal power plants assets for the different countries).

- A .csv file contains all the information concerning one object type. 
- Each asset is represented by a row
- Each asset is defined by a set of attributes. The list of attributes depends on the type of the asset. 
Except for INTERFACE attributes which are composed of two objects (one energy and one node), one column corresponds 
to one attribute. For more information on the list of attributes per asset, see the [Assets documentation](../assets/index.rst).

<div align="center">

![CSV example](../../_static/csv_example_coal_fleet.png)

</div>


### Context_data folder

The **Context_data** folder contains all data shared between the different assets as well as timeseries data.

<div align="center">

![Context_data folder](../../_static/context_data_folder.png)

</div>


#### ENERGY.csv

*ENERGY.csv*: this file contains the energies of your system:

- _name: the name of the energy.
- PROD_UNIT: the unit of the production of the energy. Mostly MWh except for co2 for which it is the t.
- POWER_UNIT: the unit of the power of the energy. Mostly MW except for co2 for which it is the t/h. 


#### NODE.csv

*NODE.csv*: this file contains the nodes of your energy system:

- _name: the name of the node.
- ASSET_LAT: the latitude of the node, in decimal degrees (for map representation).
- ASSET_LON: the longitude of the node, in decimal degrees (for map representation).
- ASSET_ZONE: the zone to which the node belongs.


#### SCENARIOS.csv

The **SCENARIOS.csv** file contains the scenarios of your system (climatic years or test cases):

- Scenario name: the name of the scenario.
- Possible values ...: the possible values for the scenario.

<div align="center">

![CSV example](../../_static/scenario_csv.png)

</div>


#### ZONE.csv

The **ZONE.csv** file contains the zones of your energy system:

- _name: the name of the zone.
- GEOM: the geometry of the zone.

.. warning::
   Do not open the ZONE.csv file in Excel, this could brake it. If you want to open or modify it, do so with a word
processing tool.

#### timeseries folder

The **timeseries** folder contains all the timseries used in your energy system:

- The name of each csv file defines the name of a timeseries used in the energy system.
- The first column shows the timesteps.
- All other columns contains the values taken by the timeseries for the different scenarios. 

<div align="center">

![CSV example](../../_static/timeseries_csv.png)

</div>


#### matrix folder

The **matrix** folder contains the matrix used in your energy system.


#### curves folder

The **curves** folder contains the curves used in your energy system.


#### demand folder

The **demand** folder contains the demand model used in your energy system. When calibrating your 
demand assets, you can either do this explicitly with csv files in the **Assets** folder, or implicitly with a disaggregated
representation in this **demand** folder.