diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e2ffdef..048f8117 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,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) #### Changed - Updated PSDM to 6.0.0 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..970514b7 100644 --- a/docs/readthedocs/connections/connections.md +++ b/docs/readthedocs/connections/connections.md @@ -1 +1,34 @@ # 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 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/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/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 e6a59247..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,7 +13,8 @@ createextsims extlinkinterface simulations/externalsimulation - +simulations/extcosimulation +simulations/mapping simulations/extsimadapterdata connections/connections 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. diff --git a/docs/readthedocs/simulations/mapping.md b/docs/readthedocs/simulations/mapping.md new file mode 100644 index 00000000..b6bccc36 --- /dev/null +++ b/docs/readthedocs/simulations/mapping.md @@ -0,0 +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.