From a47d8ea04bfcd4a5ae4610be454eb83fbe9670e5 Mon Sep 17 00:00:00 2001 From: Melanie Ecker Date: Mon, 20 Dec 2021 15:20:10 +0100 Subject: [PATCH 1/3] Updated Usage-Documentation --- docs/source/index.rst | 3 ++- docs/source/usage.rst | 19 ++++++++++++++++--- docs/source/usage/1_installation.rst | 8 ++++++++ docs/source/usage/2_dataset.rst | 21 +++++++++++++++++++++ docs/source/usage/3_model.rst | 5 +++++ docs/source/usage/execute.rst | 5 +++++ docs/source/usage/output.rst | 5 +++++ 7 files changed, 62 insertions(+), 4 deletions(-) create mode 100644 docs/source/usage/1_installation.rst create mode 100644 docs/source/usage/2_dataset.rst create mode 100644 docs/source/usage/3_model.rst create mode 100644 docs/source/usage/execute.rst create mode 100644 docs/source/usage/output.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 7aede79..f36c8c5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,7 +8,7 @@ Welcome to Python-Starter documentation! This project is under active development. Check out the :doc:`usage` section for further information, including how to -:ref:`install ` the project. +install the project. Indices and tables ================== @@ -22,6 +22,7 @@ Indices and tables .. toctree:: :maxdepth: 2 :caption: Contents: + :hidden: usage endpoints diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 6b60553..471d3a4 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,13 +1,26 @@ Usage ===== -.. _installation: +Kurze Einleitung: +Daten einlesen bzw. eingelesene nutzen +Daten sind in unterschiedliche Bereiche aufgeteilt + + +Verweis auf: Installation ------------- +Daten einlesen bzw. Aufbau der Daten in Datensatz + Modell +Modell starten bzw. Optimierung durchführen +Ergebnisse auslesen + -See the `installation instructions on Github `_. +.. toctree:: + :maxdepth: 1 + :caption: Contents: + :glob: + :hidden: + usage/* diff --git a/docs/source/usage/1_installation.rst b/docs/source/usage/1_installation.rst new file mode 100644 index 0000000..8891ac0 --- /dev/null +++ b/docs/source/usage/1_installation.rst @@ -0,0 +1,8 @@ +Installation +------------ + +See the `installation instructions on Github `_. + + + + diff --git a/docs/source/usage/2_dataset.rst b/docs/source/usage/2_dataset.rst new file mode 100644 index 0000000..8bb068d --- /dev/null +++ b/docs/source/usage/2_dataset.rst @@ -0,0 +1,21 @@ +********* +Datensatz +********* + + +hat Regionen, Energiequellen, Energieträger, Energiespeicher, Energieverbraucher, Energieumwandler und Energietransport + + +einlesen bzw. erstellen über (Unterkapitel) +Rest (verweis auf "Endpoints of REST-API") + +Zip-Upload (genaue Beschreibung) + +Rest-Endpoint: POST datasets/xxx/upload (xxx als ID des Datensatzes) +Aufbau Zip-Datei +regions.json und commodities.json (mit Einheiten Erklärung) +source, transmission, sink, storage, conversion Ordner +json-Datei und Excel-Dateien und deren Format! + +Rückmeldung beim Upload: + diff --git a/docs/source/usage/3_model.rst b/docs/source/usage/3_model.rst new file mode 100644 index 0000000..f11e187 --- /dev/null +++ b/docs/source/usage/3_model.rst @@ -0,0 +1,5 @@ +****** +Modell +****** + +hat Kosten und Reduktionsziele \ No newline at end of file diff --git a/docs/source/usage/execute.rst b/docs/source/usage/execute.rst new file mode 100644 index 0000000..d3b5e4e --- /dev/null +++ b/docs/source/usage/execute.rst @@ -0,0 +1,5 @@ +******************* +Optimierung starten +******************* + +Optimierung \ No newline at end of file diff --git a/docs/source/usage/output.rst b/docs/source/usage/output.rst new file mode 100644 index 0000000..cb4219a --- /dev/null +++ b/docs/source/usage/output.rst @@ -0,0 +1,5 @@ +****************** +Ergebnisse abrufen +****************** + +Output \ No newline at end of file From 5d81aefc4cefa2e466e03960b00aaabb34717d8c Mon Sep 17 00:00:00 2001 From: Melanie Ecker Date: Thu, 23 Dec 2021 09:55:27 +0100 Subject: [PATCH 2/3] Added documentation for dataset --- docs/source/endpoints.rst | 2 ++ docs/source/usage.rst | 2 ++ docs/source/usage/2_dataset.rst | 51 ++++++++++++++++++++++++--------- 3 files changed, 42 insertions(+), 13 deletions(-) diff --git a/docs/source/endpoints.rst b/docs/source/endpoints.rst index 6d48e52..f4e4c86 100644 --- a/docs/source/endpoints.rst +++ b/docs/source/endpoints.rst @@ -1,3 +1,5 @@ +.. _rest_endpoints: + Endpoints of REST-API ===================== diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 471d3a4..92451df 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,6 +1,8 @@ Usage ===== + + Kurze Einleitung: Daten einlesen bzw. eingelesene nutzen Daten sind in unterschiedliche Bereiche aufgeteilt diff --git a/docs/source/usage/2_dataset.rst b/docs/source/usage/2_dataset.rst index 8bb068d..e7c6caa 100644 --- a/docs/source/usage/2_dataset.rst +++ b/docs/source/usage/2_dataset.rst @@ -1,21 +1,46 @@ -********* -Datensatz -********* +******* +Dataset +******* +.. _introduction: -hat Regionen, Energiequellen, Energieträger, Energiespeicher, Energieverbraucher, Energieumwandler und Energietransport +Introduction +============ -einlesen bzw. erstellen über (Unterkapitel) -Rest (verweis auf "Endpoints of REST-API") +A dataset has different components. It contains commodities, as which energy source is used in the energy system, and the regions, your energy system is based on. +Furthermore the dataset consists of energy sources and sinks, storages, conversions and transmissions. -Zip-Upload (genaue Beschreibung) +With one dataset several modeling runs can be performed. -Rest-Endpoint: POST datasets/xxx/upload (xxx als ID des Datensatzes) -Aufbau Zip-Datei -regions.json und commodities.json (mit Einheiten Erklärung) -source, transmission, sink, storage, conversion Ordner -json-Datei und Excel-Dateien und deren Format! +.. _newDataset: -Rückmeldung beim Upload: +Create a new dataset +==================== +To create a new dataset, the API REST interface POST /datasets/ is addressed. As query-parameter, the id of the to-be-created dataset is needed. + +.. _readData: + +Read data +========= +There are two ways to collect the data for the dataset. + +Zip-Upload +---------- +With the Zip-Upload, we've created a way to enter the data in the database with only one use of a API REST interface. +Once a zip file is created in a certain format and with certain files, it can be used as a parameter in the body via the rest api interface datasets/xxx/upload. The xxx should be replaced by the ID of the dataset to which the data is linked to. + +The file contains other files and folder in which the components to the energy system are described. +For the regions and commodities there is for each a .json file in which the different regions and commodities are listed with the respective parameters. +A region has as parameter only a name while a commodity has besides a name also a description and a unit, which specifies the unit for the values for the use of this commodity. +For each of the sections for energy sources, sinks, storages, conversions and transmissions exists a folder. These folders contain other folders that are used as a listing of the various objects. For example, there are zwo folder in the source folder that contains data for two different energy sources. +A folder that maps an object contains a .json file that contains the parameters for the object, which are the same across all regions. If there are parameters that are different for each region, these parameters are stored in one Excel file each. Each region is mapped as a column and the value (or values as a time series) is stored in the column according to the region. + +The parameter that are needed for each object are documented here (TODO Link). All of the parameters can be set, but not all of them have to. + +To show the structure of the zip file, we have created an example. This can be found `here `_. + +Upload data per REST API interfaces individually +------------------------------------------------ +Another way is to upload the data in small pieces via the individual REST interfaces. A list of the interfaces can be found :ref:`here. `.. From c45f8d68f5d1ec43e63140e8f47629c3879764eb Mon Sep 17 00:00:00 2001 From: Paule <44635962+V3lop5@users.noreply.github.com> Date: Thu, 23 Dec 2021 10:48:50 +0100 Subject: [PATCH 3/3] Added examples to usage dataset documentation --- docs/source/usage/2_dataset.rst | 101 +++++++++++++++++++++++++++++--- 1 file changed, 92 insertions(+), 9 deletions(-) diff --git a/docs/source/usage/2_dataset.rst b/docs/source/usage/2_dataset.rst index e7c6caa..f70edae 100644 --- a/docs/source/usage/2_dataset.rst +++ b/docs/source/usage/2_dataset.rst @@ -9,7 +9,7 @@ Introduction A dataset has different components. It contains commodities, as which energy source is used in the energy system, and the regions, your energy system is based on. -Furthermore the dataset consists of energy sources and sinks, storages, conversions and transmissions. +Furthermore the dataset consists of energy sources, sinks, storages, conversions and transmissions. With one dataset several modeling runs can be performed. @@ -17,25 +17,108 @@ With one dataset several modeling runs can be performed. Create a new dataset ==================== -To create a new dataset, the API REST interface POST /datasets/ is addressed. As query-parameter, the id of the to-be-created dataset is needed. +To create a new dataset, the API REST interface ``POST /datasets/`` is addressed. You can provide the following +parameters: +- `name`: name of the dataset + +- `description`: description of the dataset + +The endpoint returns the id of the new dataset. That will be needed in the following steps. + +A full documentation of the API is available `as redoc documentation `_. + +.. openapi:: ./../generated/openapi.json + :paths: + /datasets/ .. _readData: Read data ========= -There are two ways to collect the data for the dataset. +There are two ways to add data to a dataset. For both ways you need to provide the id of the dataset. Zip-Upload ---------- With the Zip-Upload, we've created a way to enter the data in the database with only one use of a API REST interface. -Once a zip file is created in a certain format and with certain files, it can be used as a parameter in the body via the rest api interface datasets/xxx/upload. The xxx should be replaced by the ID of the dataset to which the data is linked to. +Once a zip archive is created in a certain format and with certain files, it can be uploaded with the API REST interface. +A dataset id is needed. + +.. openapi:: ./../generated/openapi.json + :include: + /datasets/*/upload + +The zip archive contains other files and folder in which the regions, commodities and components to the energy system +are described. The zip archive is structured as follows: + +.. code-block:: bash + + dataset.zip + │ commodities.json + │ regions.json + ├───conversions/ + ├───sinks/ + ├───sources/ + ├───storages/ + └───transmissions/ + +The ```commodities.json`` contains all commodities, which are used in the energy system. +The json file is structured as a list of commodities with name, unit and description. +The unit is used for all values in the energy system with that specific commodity. +Example: + +.. code-block:: json + + [ + { + "name": "electricity", + "unit": "kWh", + "description": "example description" + }, + { + "name": "heat", + "unit": "kWh" + } + ] + + +The ``regions.json`` contains all regions, which are used in the energy system. +The json file is structured as a list of regions with name and description. Example: + +.. code-block:: json + + [ + { + "name": "region1", + "description": "example description" + }, + { + "name": "region2" + } + ] + + +For each of the sections for energy sources, sinks, storages, conversions and transmissions exists a folder. +These folders contain other folders that are used as a listing of the various objects. + +.. code-block:: bash + + dataset.zip + └───sources/ + ├───source-1/ + │ capacity.xlsx + │ operationRateMax.xlsx + │ source.json + └───source-2/ + capacity.xlsx + operationRateFix.xlsx + source.json -The file contains other files and folder in which the components to the energy system are described. -For the regions and commodities there is for each a .json file in which the different regions and commodities are listed with the respective parameters. -A region has as parameter only a name while a commodity has besides a name also a description and a unit, which specifies the unit for the values for the use of this commodity. -For each of the sections for energy sources, sinks, storages, conversions and transmissions exists a folder. These folders contain other folders that are used as a listing of the various objects. For example, there are zwo folder in the source folder that contains data for two different energy sources. -A folder that maps an object contains a .json file that contains the parameters for the object, which are the same across all regions. If there are parameters that are different for each region, these parameters are stored in one Excel file each. Each region is mapped as a column and the value (or values as a time series) is stored in the column according to the region. +For example, there are two folders in the source folder that contains data for two different energy sources. +A folder that maps an object contains a .json file that contains the parameters for the object, which are the same +across all regions. If there are parameters that are different for each region, these parameters (for example +capacity per region, operation rates, ...) are stored in one Excel file each. +Each region is mapped as a column and the value (or values as a time series) is stored in the column according to the region. The parameter that are needed for each object are documented here (TODO Link). All of the parameters can be set, but not all of them have to.