From bcf3a1ea32df0028fceebbf6f084ce9e374007ce Mon Sep 17 00:00:00 2001 From: staudtMarius Date: Tue, 7 Jan 2025 15:41:26 +0100 Subject: [PATCH 1/3] Enhancing documentation. --- CHANGELOG.md | 1 + README.md | 2 ++ docs/readthedocs/conf.py | 9 ++++++++ docs/readthedocs/connections/connections.md | 23 +++++++++++++++++++ docs/readthedocs/connections/emconnection.md | 20 ++++++++++++++++ docs/readthedocs/connections/evconnection.md | 11 +++++++++ .../connections/primaryconnection.md | 13 +++++++++++ docs/readthedocs/index.md | 2 +- docs/readthedocs/simulations/mapping.md | 1 + 9 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/readthedocs/connections/emconnection.md create mode 100644 docs/readthedocs/connections/evconnection.md create mode 100644 docs/readthedocs/connections/primaryconnection.md create mode 100644 docs/readthedocs/simulations/mapping.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 841c859a..a519fa71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Added Bao and Staudt to the list of reviewers [#216](https://github.com/ie3-institute/simonaAPI/issues/216) - Documentation for this API [#230](https://github.com/ie3-institute/simonaAPI/issues/230) +- Enhancing documentation [#234](https://github.com/ie3-institute/simonaAPI/issues/234) ## [0.6.0] - 2024-12-02 diff --git a/README.md b/README.md index f668bed0..b68e549f 100644 --- a/README.md +++ b/README.md @@ -9,3 +9,5 @@ API to create modules and add-ons for simona + +For more information visit [ReadTheDocs](https://simonaapi.readthedocs.io/latest/). diff --git a/docs/readthedocs/conf.py b/docs/readthedocs/conf.py index fa091f3c..4c4b1d43 100644 --- a/docs/readthedocs/conf.py +++ b/docs/readthedocs/conf.py @@ -68,6 +68,15 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +# Intersphinx for references to external ReadTheDocs +intersphinx_mapping = { + 'psdm': ('https://powersystemdatamodel.readthedocs.io/en/latest/', None), +} + +hoverxref_intersphinx = [ + "psdm", +] + def setup(app): app.add_css_file("css/theme_override.css") diff --git a/docs/readthedocs/connections/connections.md b/docs/readthedocs/connections/connections.md index a48fb91a..342da0e1 100644 --- a/docs/readthedocs/connections/connections.md +++ b/docs/readthedocs/connections/connections.md @@ -1 +1,24 @@ # Data connections + +In order to send data to or to receive result from SIMONA, each external simulation needs to have at least one data +connection. + + +## Input data connections + +These connections are used to provide SIMONA with data, that is calculated by the external simulation. + +Currently, the following input connections exist: + +```{toctree} +:maxdepth: 2 + +emconnection +evconnection +primaryconnection +``` + +Each input connection has an actor reference to the data service in SIMONA as well as an actor reference to the adapter +that handles the scheduler control flow in SIMONA. + +## Result data connections diff --git a/docs/readthedocs/connections/emconnection.md b/docs/readthedocs/connections/emconnection.md new file mode 100644 index 00000000..4f024d76 --- /dev/null +++ b/docs/readthedocs/connections/emconnection.md @@ -0,0 +1,20 @@ +# Energy management data connection + +This data connection can be used to provide SIMONA with set-points for the {doc}`energy management units `. + +Every energy management data connection needs to have an [external entity mapping](/simulations/mapping). +This information is used to: +- associate a set-point value with an energy management unit in SIMONA. +- tell SIMONA which energy management units will receive external data + + +Currently, all energy management units have to receive a set-point from the same external simulation. Therefore, only +one external simulation can provide em data at once. + + +There are two methods to provide SIMONA with em data: +1. convertAndSend +2. provideEmData + +The first method should be used, if your data is mapped by `strings`. If your data is already mapped by `UUID`, you can +use the second method. diff --git a/docs/readthedocs/connections/evconnection.md b/docs/readthedocs/connections/evconnection.md new file mode 100644 index 00000000..6b958395 --- /dev/null +++ b/docs/readthedocs/connections/evconnection.md @@ -0,0 +1,11 @@ +# Electric vehicle data connection + +This data connection can be used to connect an external ev movement service (e.g.: the +[MobilitySimulator](https://github.com/ie3-institute/MobilitySimulator)) to SIMONA. + +The data connection can request the following information from SIMONA: +- the publicly available {doc}`electric vehicle charging stations ` +- the current prices at every charging station +- a list of all departing electric vehicles + +The data connection provides SIMONA with a list of electric vehicles at every charging station. diff --git a/docs/readthedocs/connections/primaryconnection.md b/docs/readthedocs/connections/primaryconnection.md new file mode 100644 index 00000000..20583467 --- /dev/null +++ b/docs/readthedocs/connections/primaryconnection.md @@ -0,0 +1,13 @@ +# Primary data connection + +This data connection can be used to provide SIMONA with primary data for input models. + +Every primary data connection needs to have an [external entity mapping](/simulations/mapping). +This information is used to: +- tell SIMONA which asset will receive primary data from this connection +- associate a primary value with an asset in SIMONA. + + +Different assets (e.g.: two loads) can receive primary data from different primary data connections and therefore different +external simulations. The rule is, that one asset can only receive data from one connection. Another possibility is, that +different types of assets (e.g.: loads, pv-plants) can each have their own external simulation. diff --git a/docs/readthedocs/index.md b/docs/readthedocs/index.md index e6a59247..283067e8 100644 --- a/docs/readthedocs/index.md +++ b/docs/readthedocs/index.md @@ -14,7 +14,7 @@ createextsims extlinkinterface simulations/externalsimulation - +simulations/mapping simulations/extsimadapterdata connections/connections diff --git a/docs/readthedocs/simulations/mapping.md b/docs/readthedocs/simulations/mapping.md new file mode 100644 index 00000000..bed926bf --- /dev/null +++ b/docs/readthedocs/simulations/mapping.md @@ -0,0 +1 @@ +# External entity mapping From 61da86438b4a956b4bab02bd265bca564b84ea25 Mon Sep 17 00:00:00 2001 From: staudtMarius Date: Wed, 8 Jan 2025 07:55:55 +0100 Subject: [PATCH 2/3] Enhancing documentation. --- docs/readthedocs/connections/connections.md | 14 ++++- docs/readthedocs/simulations/mapping.md | 58 +++++++++++++++++++++ 2 files changed, 70 insertions(+), 2 deletions(-) diff --git a/docs/readthedocs/connections/connections.md b/docs/readthedocs/connections/connections.md index 342da0e1..970514b7 100644 --- a/docs/readthedocs/connections/connections.md +++ b/docs/readthedocs/connections/connections.md @@ -18,7 +18,17 @@ evconnection primaryconnection ``` -Each input connection has an actor reference to the data service in SIMONA as well as an actor reference to the adapter -that handles the scheduler control flow in SIMONA. +Each input data connection has an actor reference to the data service in SIMONA as well as an actor reference to the +adapter that handles the scheduler control flow in SIMONA. ## Result data connections + +The result data connection can be used to provide SIMONA results to the external simulation. Currently, +{doc}`node ` and {doc}`participant ` +results are supported. + +The result data connection has an actor reference to the data service in SIMONA, an actor reference to the data service +activation adapter as well as an actor reference to the adapter that handles the scheduler control flow in SIMONA. + +Unlike the input data connections, the result data connection needs two [external entity mapping](/simulations/mapping) +information. These specify for which grid asset and/or system participant results should be provided by SIMONA. diff --git a/docs/readthedocs/simulations/mapping.md b/docs/readthedocs/simulations/mapping.md index bed926bf..b6bccc36 100644 --- a/docs/readthedocs/simulations/mapping.md +++ b/docs/readthedocs/simulations/mapping.md @@ -1 +1,59 @@ # External entity mapping + +This page contains information about the external entity mapping, that is used to map the identifiers of an external +simulation to the identifiers used by SIMONA. For each mapping entry, the data, that will be exchanged, is also specified. + + +## Column schemes + +The column scheme defines which data can be exchanged by a [data connection](/connections/connections). The available +schemes are defined in the PowersystemDataModel (see: {doc}`Available Classes `). + + +## Data types + +The data type contains information about the data connection, the [externals entity entry](#external-entity-entry) +is used for. + +Currently, the following types exist: +- primary input +- em input +- grid result +- participant result + + +## External entity entry + +Defines the mapping between an externally used `string` and an `uuid` used by SIMONA. + +### Attributes and Remarks + +```{list-table} + :widths: auto + :class: wrapping + :header-rows: 1 + + + * - Attribute + - Remarks + + * - uuid + - Identifier used by SIMONA + + * - id + - Identifier used by the external simulation + + * - columnScheme + - Information which data is exchanged + + * - dataType + - Defines the data type + +``` + +## Sources + +The sources for the external entity mapping is defined in the same format as the PowerSystemDataModel (see: +{doc}`I/O `). + +Currently, only a csv source exist for the external entity mapping. From eeadaf7547e19f4788c82944ba09ef20e45b04aa Mon Sep 17 00:00:00 2001 From: staudtMarius Date: Fri, 17 Jan 2025 13:28:22 +0100 Subject: [PATCH 3/3] Improving the documentation. --- docs/readthedocs/createextsims.md | 10 +++--- docs/readthedocs/index.md | 4 +-- .../simulations/extcosimulation.md | 34 +++++++++++++++++++ 3 files changed, 42 insertions(+), 6 deletions(-) create mode 100644 docs/readthedocs/simulations/extcosimulation.md diff --git a/docs/readthedocs/createextsims.md b/docs/readthedocs/createextsims.md index 8ac99738..b61ddb87 100644 --- a/docs/readthedocs/createextsims.md +++ b/docs/readthedocs/createextsims.md @@ -15,7 +15,9 @@ of the `ExtLinkInterface`. ## Project with multiple external simulations Your project could contain multiple external simulations by creating multiple implementations of the `ExtLinkInterface` -and adding them to the service file. When doing this SIMONA will give you a warning. Each asset in SIMONA can only -receive external data from **one** external simulation. If two external simulations are set up to provide data to the -same asset, SIMONA will exit with an exception. Therefore, it is encouraged to create an own project for each external -simulation. +and adding them to the service file. When doing this SIMONA will give you a warning. + + +**Also**, each asset in SIMONA can only receive external data from **one** external simulation. If two external simulations +are set up to provide data to the same asset, SIMONA will exit with an exception. Therefore, it is encouraged to create +an own project for each external simulation. diff --git a/docs/readthedocs/index.md b/docs/readthedocs/index.md index 283067e8..72c1209f 100644 --- a/docs/readthedocs/index.md +++ b/docs/readthedocs/index.md @@ -1,8 +1,7 @@ # Documentation of the SIMONA API Welcome to the documentation of the SIMONA API. -This API is used to create extensions for [SIMONA](https://github.com/ie3-institute/simona). -One example are external simulations, that can be used in co-simulations with SIMONA. +This API is used to create extensions for [SIMONA](https://github.com/ie3-institute/simona), that can be used in co-simulations with SIMONA. ```{toctree} @@ -14,6 +13,7 @@ createextsims extlinkinterface simulations/externalsimulation +simulations/extcosimulation simulations/mapping simulations/extsimadapterdata diff --git a/docs/readthedocs/simulations/extcosimulation.md b/docs/readthedocs/simulations/extcosimulation.md new file mode 100644 index 00000000..06bc6d41 --- /dev/null +++ b/docs/readthedocs/simulations/extcosimulation.md @@ -0,0 +1,34 @@ +# External Co-Simulation + +This abstract class is an extension to the [external simulation](/simulations/externalsimulation) class. It is primarily +used to couple SIMONA with co-simulation frameworks. The idea behind this class is the simplification of adding SIMONA +to these frameworks. + +## Co-Simulation frameworks + +Currently, SIMONA can be used with the following co-simulation frameworks: +1. [MOSAIk](#mosaik) +2. [OpSim](#opsim) + + +### MOSAIK +[MOSAIK](https://mosaik.offis.de/) is a co-simulation framework from [Offis e.V.](https://www.offis.de/). To connect +SIMONA with MOSAIK see [simosaik](https://github.com/ie3-institute/simosaik). + + +### OpSim +[OpSim](https://www.iee.fraunhofer.de/en/schnelleinstieg-wirtschaft/themen/opsim-homepage.html) is an test- and simulation-environment +for grid control and aggregation strategies from [Fraunhofer IEE](https://www.iee.fraunhofer.de/en.html). To connect +SIMONA with OpSim see [simopsim](https://github.com/ie3-institute/simopsim). + + +## Connectivity + +In order to simplify the connection, this class provides two data queues. One queue is used to provide SIMONA with +external values. The other is used to provide the co-simulation framework with value calculated by SIMONA. + + +## Functionality + +There are some helpful methods to create some [data connections](/connections/connections) and to exchange data between +SIMONA and the co-simulation framework.