Enhancing documentation

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
 

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/).

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")

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 <psdm:models/result/grid/node>` and {doc}`participant <psdm:models/result/participant/systemparticipant>`
+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.

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 <psdm:models/input/em>`.
+
+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.

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 <psdm:models/input/participant/evcs>`
+- 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.

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.

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.

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

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.

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 <psdm:models/input/additionaldata/timeseries>`).
+
+
+## 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 <psdm:io/basiciousage>`). 
+
+Currently, only a csv source exist for the external entity mapping.