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/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..92451df 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,13 +1,28 @@ 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..f70edae --- /dev/null +++ b/docs/source/usage/2_dataset.rst @@ -0,0 +1,129 @@ +******* +Dataset +******* + +.. _introduction: + +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, sinks, storages, conversions and transmissions. + +With one dataset several modeling runs can be performed. + +.. _newDataset: + +Create a new dataset +==================== +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 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 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 + +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. + +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. `.. 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