# ChroniX2Grid - The Extensive PowerGrid Time-serie Generator
Chronix2Grid is a python package, providing a command-line application as well,
that allows to generate synthetic but realistic consumption, renewable production, electricity loss (dissipation)
and economic dispatched productions chronics given a power grid.
Reference data that you provide will serve to calibrate the parameters
so that the synthetic data reproduce some realistic criteria (KPIs) from the reference data.
* [1 Chronix2Grid at a glance](#glance)
* [2 Installation](#installation)
* [3 Getting Started](#getting-started)
* [4 The command-line interface](#the-command-line-interface)
* [5 Configuration](#configuration)
* [6 Running the test suite](#running-the-test-suite)
See the documentation at https://chronix2grid.readthedocs.io/en/latest/
## Chronix2Grid at a glance
## Installation
### Requirements:
* Python >= 3.6
#### (Optional, recommended) Step 1: Create a virtual environment
```commandline
pip3 install -U virtualenv
python3 -m virtualenv venv_chronix2grid
```
#### Step 2 (first option): Install from pypi
```commandline
source venv_chronix2grid/bin/activate
pip install Chronix2Grid
```
#### Step 2 (second option): Install from source
```commandline
source venv_chronix2grid/bin/activate
git clone https://github.com/mjothy/ChroniX2Grid.git
cd ChroniX2Grid/
pip install -U .
```
### Additional install required for dispatch
A backend for dispatch has been implemented with PyPSA
```commandline
pip install pypsa==0.17.0
```
You might need to install cbc solver as well that pypsa will call: https://projects.coin-or.org/Cbc
## Getting Started
Four notebooks are provided to get you started with this package:
* **getting_started_cli.ipynb** guide you through the use of chronix2grid cli
* **getting_started_api.ipynb** is a more detailed notebook that presents chronix2grid api and showcases several ways to
analyze the chronics produced
* **running_chronics_grid2op.ipynb** is a notebook giving an example of how generated chronics can further be used to create power grid scenarios and run them
analyze the chronics produced
* **RenewableNinja_Solar_WInd_KPI_format.ipynb** is an example on how to retrieve Solar and Wind reference chronics from the
[renewable ninja](https://www.renewables.ninja/) api. There will be use to compare the KPI's with the generated chronics.
Additionally, a data starting kit is provided to run an example in the folder
```commandline
getting_started/example
```
The output folder corresponds to the following run of chronix2grid :
```commandline
chronix2grid --mode LRTK --ignore-warnings --weeks 8 --n_scenarios 1 --start-date 2012-01-01 --by-n-weeks 4
```
NB:
* Default input data from package will be used if no --input-data and --case is provided
* Output will be written in the working directory in a folder output/
To provide --input-data and --output-folder folders and specify --case grid case, you would run this kind of command (make sure to change ChroniX2Grid_path with you own path) :
```commandline
chronix2grid --mode RLTK --output-folder ChroniX2Grid_path/getting_started/example/output --input-folder ChroniX2Grid_path/getting_started/example/input --ignore-warnings --weeks 8 --case case118_l2rpn_wcci --n_scenarios 1 --start-date 2012-01-01 --by-n-weeks 4
```
### WARNING
In order to limit the size of the output and the running time for this example, chronics are only generated for 8 weeks.
This implicates that some kpis that defined on a whole year will not be exploitable for this example.
## The command-line interface
```commandline
Usage: chronix2grid [OPTIONS]
Options:
--case TEXT case folder to base generation on
--start-date TEXT Start date to generate chronics
--weeks INTEGER Number of weeks to generate
--by-n-weeks INTEGER Size of the output chunks in weeks
--n_scenarios INTEGER Number of scenarios to generate
--mode TEXT Steps to execute : L(K) for loads only (and KPI);
R(K) for renewables (and KPI) only; LRT (K)
for load, renewable and thermic generation (and KPI);
LRDT(TK) for load, renewable, loss (dissipation) generation
(and thermic and KPI)
--input-folder TEXT Directory to read input files from.
--output-folder TEXT Directory to store output files.
--seed-for-loads TEXT Input seed to ensure reproducibility of loads
generation
--seed-for-res TEXT Input seed to ensure reproducibility of renewables
generation
--seed-for-dispatch TEXT Input seed to ensure reproducibility of dispatch
--ignore-warnings Ignore the warnings related to the existence of
data files in the chosen output directory.
--scenario_name TEXT subname to add to the generated scenario output
folder, as Scenario_subname_i
--nb_core INTEGER number of cores to parallelize the number of
scenarios
--help Show this message and exit.
```
## Launch mode
4 generation submodules and a KPI module are available
* L - load generation
* R - wind and solar production generation
* D - loss generation a priori, that will be used for dispatch and potentially corrected afterwards
* T - thermic and hydro production generation thanks to an economic dispatch (simplified optimal power flow simulation)
* K - KPI generation in order to compare synthetic (generated) chronics to reference (real-life) chronics
The figure below shows how these submodules can be launched together with --mode/-m argument.
Note that D and T submodules can't be launched without previous L and R modules, and that KPIs can always been computed
## Configuration
### Chronic generation detailed configuration
Detailed configuration is made through thematic json files.
For instance you will use in the current implementation of Chronix2grid:
* **params.json** for general generation configuration (generation timestep, noise for forecast chronics)
* **params_load.json** for load generation
* **params_res.json** for solar and wind generation. You will use paramsGAN.json in case you are using the backend with Generative Adversarial Networks
* **params_loss.json** for a priori loss generation
* **params_opf.json** for dispatch and a posteriori loss simulation
Below is an example of **params.json** which will launch a 5 minutes time step generation,
applying a gaussian noise to forecast chronics with a standard deviation of 0.01
```json
{
"dt": 5,
"planned_std": "0.01"
}
```
Below is an example of **params_load.json** that provides parameters to correlated generation algorithm.
```json
{
"Lx": 1000,
"Ly": 1000,
"dx_corr": 250,
"dy_corr": 250,
"temperature_corr": 400,
"std_temperature_noise": 0.06
}
```
You'll find all the details on the parameters used in these json files in the [documentation about implemented models](https://chronix2grid.readthedocs.io/en/latest/DESCRIPTION.html)
### KPI configuration
Some general parameters have to be set in *INPUT_FOLDER/kpi/paramsKPI.json*
- **comparison**: name of benchmark folder to use for KPI reference chronics. For example, benchmark *France* has been implemented with eco2mix and renewable ninja data
- **timestep**: timestep for KPI computation. For example, renewable ninja data requires minimum timestep of 60min
- **night_hours**: dictionary to provide night hours for each season of year
- **seasons**: dictionary to provide months in each season of year
## Model interface
All generation submodules (LRDT) have a modular backend.
You can develop your own load, renewable, loss and dispatch model using as input:
* Your json parameters
* Possible pattern files, or trained neural networks
* Grid demand and generator characteristics in csv
## Citing
```
@misc{chronix2grid,
author = {A. Marot, N. Megel, V. Renault, M. Jothy },
title = {{ChroniX2Grid - The Extensive PowerGrid Time-serie Generator}},
year = {2020},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/BDonnot/ChroniX2Grid}},
}
```
## Running the test suite
To launch the unit test suite:
```commandline
pipenv run python -m pytest tests/unit_tests/ [--verbose -p no:warnings]
```
To launch integration tests:
```commandline
pipenv run python -m pytest tests/integration_tests/ [--verbose -p no:warnings]
```
To launch the Command Line Interface (CLI) test (only if you installed chronix2grid package from Pypi)
```commandline
pipenv run python -m pytest tests/cli_tests/
```
You can also analyse the coverage of the tests with coverage and generate an html report:
```commandline
pip install coverage
coverage run --source=./chronix2grid -m unittest discover
coverage html
```
This will generate a htmlcov folder containing a static web site with the analysis. Open index.html in a browser
to analyse it.
Raw data
{
"_id": null,
"home_page": "https://github.com/BDonnot/ChroniX2Grid",
"name": "Chronix2Grid",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ML powergrid optmization RL power-systems chronics generation production load network",
"author": "Mario Jothy, Nicolas Megel, Vincent Renault, Benjamin Donnot",
"author_email": "mario.jothy@artelys.com",
"download_url": "https://files.pythonhosted.org/packages/62/33/48d85d3a9d0e884751212b19a814c69fd8e856414bc211870daed0117f41/Chronix2Grid-1.2.0.post1.tar.gz",
"platform": "Windows",
"description": "# ChroniX2Grid - The Extensive PowerGrid Time-serie Generator\n\nChronix2Grid is a python package, providing a command-line application as well, \nthat allows to generate synthetic but realistic consumption, renewable production, electricity loss (dissipation) \nand economic dispatched productions chronics given a power grid.\nReference data that you provide will serve to calibrate the parameters \nso that the synthetic data reproduce some realistic criteria (KPIs) from the reference data.\n\n* [1 Chronix2Grid at a glance](#glance)\n* [2 Installation](#installation)\n* [3 Getting Started](#getting-started)\n* [4 The command-line interface](#the-command-line-interface)\n* [5 Configuration](#configuration)\n* [6 Running the test suite](#running-the-test-suite)\n\nSee the documentation at https://chronix2grid.readthedocs.io/en/latest/\n\n## Chronix2Grid at a glance\n![Chronix2grid_inputs](pictures/ChroniX2Grid_inputs.png \"Chronix2Grid Inputs\") \n\n![Chronix2grid_outputs](pictures/ChroniX2Grid_ouputs.png \"Chronix2Grid Ouputs\") \n\n## Installation\n\n### Requirements:\n* Python >= 3.6\n\n#### (Optional, recommended) Step 1: Create a virtual environment\n```commandline\npip3 install -U virtualenv\npython3 -m virtualenv venv_chronix2grid\n```\n\n#### Step 2 (first option): Install from pypi\n```commandline\nsource venv_chronix2grid/bin/activate\npip install Chronix2Grid\n```\n\n#### Step 2 (second option): Install from source\n```commandline\nsource venv_chronix2grid/bin/activate\ngit clone https://github.com/mjothy/ChroniX2Grid.git\ncd ChroniX2Grid/\npip install -U .\n```\n\n### Additional install required for dispatch\n\nA backend for dispatch has been implemented with PyPSA \n\n ```commandline\npip install pypsa==0.17.0\n```\nYou might need to install cbc solver as well that pypsa will call: https://projects.coin-or.org/Cbc\n\n## Getting Started\nFour notebooks are provided to get you started with this package:\n\n* **getting_started_cli.ipynb** guide you through the use of chronix2grid cli\n* **getting_started_api.ipynb** is a more detailed notebook that presents chronix2grid api and showcases several ways to\n analyze the chronics produced\n* **running_chronics_grid2op.ipynb** is a notebook giving an example of how generated chronics can further be used to create power grid scenarios and run them \n analyze the chronics produced\n* **RenewableNinja_Solar_WInd_KPI_format.ipynb** is an example on how to retrieve Solar and Wind reference chronics from the\n [renewable ninja](https://www.renewables.ninja/) api. There will be use to compare the KPI's with the generated chronics. \n \nAdditionally, a data starting kit is provided to run an example in the folder \n ```commandline\ngetting_started/example\n```\n The output folder corresponds to the following run of chronix2grid : \n ```commandline\nchronix2grid --mode LRTK --ignore-warnings --weeks 8 --n_scenarios 1 --start-date 2012-01-01 --by-n-weeks 4\n```\n\nNB:\n* Default input data from package will be used if no --input-data and --case is provided\n* Output will be written in the working directory in a folder output/\n\nTo provide --input-data and --output-folder folders and specify --case grid case, you would run this kind of command (make sure to change ChroniX2Grid_path with you own path) : \n ```commandline\nchronix2grid --mode RLTK --output-folder ChroniX2Grid_path/getting_started/example/output --input-folder ChroniX2Grid_path/getting_started/example/input --ignore-warnings --weeks 8 --case case118_l2rpn_wcci --n_scenarios 1 --start-date 2012-01-01 --by-n-weeks 4\n```\n\n### WARNING\nIn order to limit the size of the output and the running time for this example, chronics are only generated for 8 weeks.\nThis implicates that some kpis that defined on a whole year will not be exploitable for this example.\n \n## The command-line interface\n```commandline\nUsage: chronix2grid [OPTIONS]\n\nOptions:\n --case TEXT case folder to base generation on\n --start-date TEXT Start date to generate chronics\n --weeks INTEGER Number of weeks to generate\n --by-n-weeks INTEGER Size of the output chunks in weeks\n --n_scenarios INTEGER Number of scenarios to generate\n --mode TEXT Steps to execute : L(K) for loads only (and KPI);\n R(K) for renewables (and KPI) only; LRT (K) \n for load, renewable and thermic generation (and KPI); \n LRDT(TK) for load, renewable, loss (dissipation) generation \n (and thermic and KPI) \n\n --input-folder TEXT Directory to read input files from.\n --output-folder TEXT Directory to store output files.\n --seed-for-loads TEXT Input seed to ensure reproducibility of loads\n generation\n\n --seed-for-res TEXT Input seed to ensure reproducibility of renewables\n generation\n\n --seed-for-dispatch TEXT Input seed to ensure reproducibility of dispatch\n --ignore-warnings Ignore the warnings related to the existence of\n data files in the chosen output directory.\n\n --scenario_name TEXT subname to add to the generated scenario output\n folder, as Scenario_subname_i\n\n --nb_core INTEGER number of cores to parallelize the number of\n scenarios\n\n --help Show this message and exit.\n\n```\n\n## Launch mode\n4 generation submodules and a KPI module are available\n\n* L - load generation\n* R - wind and solar production generation\n* D - loss generation a priori, that will be used for dispatch and potentially corrected afterwards\n* T - thermic and hydro production generation thanks to an economic dispatch (simplified optimal power flow simulation)\n* K - KPI generation in order to compare synthetic (generated) chronics to reference (real-life) chronics\n\nThe figure below shows how these submodules can be launched together with --mode/-m argument. \nNote that D and T submodules can't be launched without previous L and R modules, and that KPIs can always been computed \n\n![Launch_mode](pictures/Launch_mode.png \"Launch mode\") \n\n## Configuration\n\n### Chronic generation detailed configuration\nDetailed configuration is made through thematic json files. \nFor instance you will use in the current implementation of Chronix2grid:\n\n* **params.json** for general generation configuration (generation timestep, noise for forecast chronics)\n* **params_load.json** for load generation\n* **params_res.json** for solar and wind generation. You will use paramsGAN.json in case you are using the backend with Generative Adversarial Networks\n* **params_loss.json** for a priori loss generation\n* **params_opf.json** for dispatch and a posteriori loss simulation\n\nBelow is an example of **params.json** which will launch a 5 minutes time step generation, \napplying a gaussian noise to forecast chronics with a standard deviation of 0.01\n```json\n{\n \"dt\": 5,\n \"planned_std\": \"0.01\"\n}\n```\n\nBelow is an example of **params_load.json** that provides parameters to correlated generation algorithm.\n\n```json\n{\n \"Lx\": 1000,\n \"Ly\": 1000,\n \"dx_corr\": 250,\n \"dy_corr\": 250,\n \"temperature_corr\": 400,\n \"std_temperature_noise\": 0.06\n}\n```\n\nYou'll find all the details on the parameters used in these json files in the [documentation about implemented models](https://chronix2grid.readthedocs.io/en/latest/DESCRIPTION.html)\n\n### KPI configuration\nSome general parameters have to be set in *INPUT_FOLDER/kpi/paramsKPI.json*\n- **comparison**: name of benchmark folder to use for KPI reference chronics. For example, benchmark *France* has been implemented with eco2mix and renewable ninja data\n- **timestep**: timestep for KPI computation. For example, renewable ninja data requires minimum timestep of 60min\n- **night_hours**: dictionary to provide night hours for each season of year\n- **seasons**: dictionary to provide months in each season of year\n\n## Model interface\n\nAll generation submodules (LRDT) have a modular backend. \nYou can develop your own load, renewable, loss and dispatch model using as input: \n* Your json parameters\n* Possible pattern files, or trained neural networks\n* Grid demand and generator characteristics in csv\n\n## Citing\n```\n@misc{chronix2grid,\n author = {A. Marot, N. Megel, V. Renault, M. Jothy },\n title = {{ChroniX2Grid - The Extensive PowerGrid Time-serie Generator}},\n year = {2020},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/BDonnot/ChroniX2Grid}},\n }\n```\n## Running the test suite\n\nTo launch the unit test suite:\n```commandline\npipenv run python -m pytest tests/unit_tests/ [--verbose -p no:warnings]\n```\n\nTo launch integration tests:\n```commandline\npipenv run python -m pytest tests/integration_tests/ [--verbose -p no:warnings]\n```\n\nTo launch the Command Line Interface (CLI) test (only if you installed chronix2grid package from Pypi)\n```commandline\npipenv run python -m pytest tests/cli_tests/\n```\n\nYou can also analyse the coverage of the tests with coverage and generate an html report:\n```commandline\npip install coverage\ncoverage run --source=./chronix2grid -m unittest discover\ncoverage html\n```\nThis will generate a htmlcov folder containing a static web site with the analysis. Open index.html in a browser\n to analyse it.\n",
"bugtrack_url": null,
"license": "Mozilla Public License 2.0 (MPL 2.0)",
"summary": "A python package to generate \"en-masse\" chronics for loads and productions (thermal, renewable)",
"version": "1.2.0.post1",
"project_urls": {
"Homepage": "https://github.com/BDonnot/ChroniX2Grid"
},
"split_keywords": [
"ml",
"powergrid",
"optmization",
"rl",
"power-systems",
"chronics",
"generation",
"production",
"load",
"network"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c9334b09de36c780ea952f476d57213f836a7c38540fb2bbac5a2caa68be721",
"md5": "a3ed55698be4d1a8d874266be53275b3",
"sha256": "ac1412d46c49ed3ac1a04eaf227eabde968689fabac86d3ee2ef614d74a2101a"
},
"downloads": -1,
"filename": "Chronix2Grid-1.2.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a3ed55698be4d1a8d874266be53275b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9990133,
"upload_time": "2023-07-27T09:42:57",
"upload_time_iso_8601": "2023-07-27T09:42:57.521143Z",
"url": "https://files.pythonhosted.org/packages/3c/93/34b09de36c780ea952f476d57213f836a7c38540fb2bbac5a2caa68be721/Chronix2Grid-1.2.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "623348d85d3a9d0e884751212b19a814c69fd8e856414bc211870daed0117f41",
"md5": "ee0230f26a74c67cba54807aab127813",
"sha256": "f218924a744baf994b7c3d8929b891de3069476c94d0fec76366a0cc831877de"
},
"downloads": -1,
"filename": "Chronix2Grid-1.2.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "ee0230f26a74c67cba54807aab127813",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9889507,
"upload_time": "2023-07-27T09:43:00",
"upload_time_iso_8601": "2023-07-27T09:43:00.570328Z",
"url": "https://files.pythonhosted.org/packages/62/33/48d85d3a9d0e884751212b19a814c69fd8e856414bc211870daed0117f41/Chronix2Grid-1.2.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-27 09:43:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BDonnot",
"github_project": "ChroniX2Grid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"requirements": [],
"lcname": "chronix2grid"
}
JSON
