Release 0.7.0

.github/dependabot.yml

@@ -9,6 +9,15 @@ updates:
   target-branch: dev
   reviewers:
   - t-ober
-  - sensarmad
+  - jo-bao
   - danielfeismann
   - sebastian-peter
+  - staudtMarius
+
+- package-ecosystem: pip
+  directory: "/docs/readthedocs"
+  schedule:
+    interval: daily
+    time: "04:00"
+  open-pull-requests-limit: 8
+  target-branch: dev

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Configure python
+python:
+  install:
+    - requirements: docs/readthedocs/requirements.txt
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/readthedocs/conf.py
+  fail_on_warning: true

CHANGELOG.md

@@ -6,6 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased/Snapshot]
 
+## [0.7.0] - 2025-03-11
+
+### 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)
+
+#### Changed
+- Updated PSDM to 6.0.0
+
 ## [0.6.0] - 2024-12-02
 
 ### Added
@@ -47,7 +56,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Renamed messages to ease understanding [#62](https://github.com/ie3-institute/simonaAPI/issues/62)
 - Separating departures and arrivals in message protocol, properly handling exceptions [#77](https://github.com/ie3-institute/simonaAPI/issues/77)
 
-[Unreleased/Snapshot]: https://github.com/ie3-institute/simonaapi/compare/0.6.0...HEAD
+[Unreleased/Snapshot]: https://github.com/ie3-institute/simonaapi/compare/0.7.0...HEAD
+[0.7.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.6.0...0.7.0
 [0.6.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.5.0...0.6.0
 [0.5.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.4.0...0.5.0
 [0.4.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.3.0...0.4.0

build.gradle

@@ -1,14 +1,15 @@
 plugins {
   id 'groovy' // groovy support
   id 'java' // java support
-  id 'com.diffplug.spotless' version '6.25.0'//code format
+  id 'com.diffplug.spotless' version '7.0.2'//code format
   id 'pmd' // code check, working on source code
-  id 'com.github.spotbugs' version '6.0.26' // code check, working on byte code
+  id 'com.github.spotbugs' version '6.1.7' // code check, working on byte code
   id "org.sonarqube" version "6.0.1.5171" // sonarqube
   id 'signing'
   id 'maven-publish' // publish to a maven repo (local or mvn central, has to be defined)
   id 'jacoco' // java code coverage plugin
   id 'net.thauvin.erik.gradle.semver' version '1.0.4' // semantic versioning
+  id 'kr.motd.sphinx' version '2.10.1' // documentation generation
 }
 
 ext {
@@ -17,8 +18,8 @@ ext {
 
   // required for pekko
   scalaVersion = "2.13"
-  scalaBinaryVersion = "2.13.15"
-  pekkoVersion = "1.1.2"
+  scalaBinaryVersion = "2.13.16"
+  pekkoVersion = "1.1.3"
 }
 
 group = 'com.github.ie3-institute'
@@ -46,7 +47,7 @@ repositories {
 
 dependencies{
 
-  implementation 'tech.units:indriya:2.2.1' // quantities
+  implementation 'tech.units:indriya:2.2.2' // quantities
 
   // scala (needed for pekko)
   implementation "org.scala-lang:scala-library:${scalaBinaryVersion}"
@@ -60,15 +61,15 @@ dependencies{
   }
 
   //PSDM
-  implementation('com.github.ie3-institute:PowerSystemDataModel:5.1.0') {
+  implementation('com.github.ie3-institute:PowerSystemDataModel:6.0.0') {
     exclude group: 'org.apache.logging.log4j'
     exclude group: 'org.slf4j'
     /* Exclude our own nested dependencies */
     exclude group: 'com.github.ie3-institute'
   }
 
   // logging
-  implementation platform('org.apache.logging.log4j:log4j-bom:2.24.2')
+  implementation platform('org.apache.logging.log4j:log4j-bom:2.24.3')
   implementation 'org.apache.logging.log4j:log4j-api' // log4j
   implementation 'org.apache.logging.log4j:log4j-core' // log4j
   implementation 'org.apache.logging.log4j:log4j-slf4j-impl' // log4j -> slf4j

docs/readthedocs/_static/css/theme_override.css

@@ -0,0 +1,17 @@
+/* Suppress spacing after multi-line entries in tables
+ * Inspired by this issue: https://github.com/readthedocs/sphinx_rtd_theme/issues/117 */
+.wy-table-responsive table td div.line-block {
+    margin-bottom: 0;
+    font-size: 90%;
+}
+.wy-table-responsive table th div.line-block {
+    margin-bottom: 0;
+    font-size: 90%;
+}
+.wy-table-responsive table th p {
+    margin-bottom: 0;
+}
+
+table.wrapping td {
+    white-space: normal;
+}

docs/readthedocs/conf.py

@@ -0,0 +1,73 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'simonaAPI'
+copyright = u'2023. TU Dortmund University, Institute of Energy Systems, Energy Efficiency and Energy Economics, Research group Distribution grid planning and operation '
+author = 'Institute of Energy Systems, Energy Efficiency and Energy Economics'
+
+# The full version, including alpha/beta/rc tags
+version = '0.6.0'
+release = '0.6.0'
+
+pygments_style = 'tango'
+add_function_parentheses = True
+# Will point sphinx to use 'index.rst' as the master document
+master_doc = 'index'
+
+# -- General configuration ---------------------------------------------------
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.intersphinx',
+    'myst_parser'
+]
+
+myst_enable_extensions = ["dollarmath", "amsmath"]
+myst_heading_anchors = 4
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv']
+exclude_trees = ['.build']
+source_suffix = ['.rst', '.md']
+source_encoding = 'utf-8-sig'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+html_short_title = "simonaAPI"
+htmlhelp_basename = 'simonaAPI-doc'
+html_use_index = True
+html_show_sourcelink = False
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+def setup(app):
+    app.add_css_file("css/theme_override.css")

docs/readthedocs/connections/connections.md

@@ -0,0 +1 @@
+# Data connections

docs/readthedocs/createextsims.md

@@ -0,0 +1,21 @@
+# How to create external simulations for SIMONA
+
+This page contains all information on how to create external simulations.
+
+SIMONA uses the java service loader, to load external simulations. Each external simulations needs to have an
+implementation of the [ExtLinkInterface](/extlinkinterface), that is provided to the service loader as a service.
+
+
+## Defining the service
+
+To define a service for an external simulation you need to create the following path inside your project:
+`resources/META-INF/services/edu.ie3.simona.api.ExtLinkInterface`. Inside this file you need to add the implementation
+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.

docs/readthedocs/extlinkinterface.md

@@ -0,0 +1,27 @@
+# External link interface
+
+The external link interface, or short `ExtLinkInterface`, is used to provide SIMONA with all methods necessary to load
+the external simulation.
+
+Currently, these methods exist:
+1. [setup](#setting-up-the-external-simulation)
+2. [getExtSimulation](#getting-the-external-simulation)
+
+Both method will be called by SIMONA to initialize and retrieve the external simulation.
+
+
+## Setting up the external simulation
+
+This method receives an [external simulation adapter data](/simulations/extsimadapterdata) that contains the following
+information:
+- CLI arguments SIMONA is initiated with
+- Reference to the actor that handles scheduler control flow in SIMONA
+- Queue with triggers the external simulation needs to handle
+
+The method can use these data, if necessary, to set up the external simulation. In all cases, this method needs to
+forward the adapter data to the external simulation.
+
+
+## Getting the external simulation
+
+This method should return the [external simulation](/simulations/externalsimulation).

docs/readthedocs/gettingstarted.md

@@ -0,0 +1,50 @@
+# Getting started
+Welcome, this section is meant to give you some help getting hands on our project.
+If you feel, something is missing, please contact us!
+
+## Requirements
+
+Java > v 17
+
+## Where to get
+
+Checkout latest from [GitHub](https://github.com/ie3-institute/simonaAPI) or use maven for dependency
+management:
+
+### Stable releases
+
+On [Maven central](https://search.maven.org/artifact/com.github.ie3-institute/simonaAPI):
+
+```xml
+<dependency>
+  <groupId>com.github.ie3-institute</groupId>
+  <artifactId>simonaAPI</artifactId>
+  <version>0.6.0</version>
+</dependency>
+```
+
+### Snapshot releases
+
+Available on [OSS Sonatype](https://s01.oss.sonatype.org/).
+Add the correct repository:
+
+```xml
+<repositories>
+  <repository>https://s01.oss.sonatype.org/content/repositories/snapshots</repository>
+</repositories>
+```
+
+and add the dependency:
+
+```xml
+<dependency>
+  <groupId>com.github.ie3-institute</groupId>
+  <artifactId>simonaAPI</artifactId>
+  <version>0.7-SNAPSHOT</version>
+</dependency>
+```
+
+## Important changes
+
+With the release of version `0.6.0` there were major changes in the way external simulations are
+set up. Therefore, older simulations no longer work with the version `0.6.0`.

docs/readthedocs/index.md

@@ -0,0 +1,39 @@
+# 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.
+
+
+```{toctree}
+:caption: 'Contents:'
+:maxdepth: 2
+
+gettingstarted
+createextsims
+extlinkinterface
+
+simulations/externalsimulation
+
+simulations/extsimadapterdata
+
+connections/connections
+```
+
+## Contact the (Main) Maintainers
+
+If you feel, something this missing, wrong or misleading, please contact one of our main contributors:
+
+> - [@t-ober](https://github.com/t-ober)
+> - [@danielfeismann](https://github.com/danielfeismann)
+> - [@sebastian-peter](https://github.com/sebastian-peter)
+> - [@jo-bao](https://github.com/jo-bao)
+> - [@staudtMarius](https://github.com/staudtMarius)
+
+Hat tip to all other contributors!
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`

docs/readthedocs/requirements.txt

@@ -0,0 +1,6 @@
+commonmark==0.9.1
+recommonmark==0.7.1
+Sphinx==8.2.3
+sphinx-rtd-theme==3.0.2
+myst-parser==4.0.1
+markdown-it-py==3.0.0

docs/readthedocs/simulations/externalsimulation.md

@@ -0,0 +1,34 @@
+# External simulation
+
+An external simulation needs to extend the class `edu.ie3.simona.api.simulation.ExtSimulation`. This class extends the
+java `Runnable` interface, because each external simulation is running in its own thread. The class contains the code to
+run the external simulation and to exchange messages with SIMONA.
+
+It will provide the following three abstract methods, that needs to be implemented by the subclass:
+1. [initialize](#initializing-the-external-simulation)
+2. [doActivity](#performing-an-activity)
+3. [getDataConnections](#returning-the-data-connections)
+
+There is also a `terminate` method that receives information is the simulation was successfully finished. This method
+can be used e.g. to release resources, that are used by your external simulation.
+
+
+## Initializing the external simulation
+
+This method is called to initialize the external simulation. In this step, every data or connection, that is needed, is
+loaded and/or set up.
+
+After everything is initialized, this method should return the first tick, for which this external simulation should be
+triggered by SIMONA.
+
+
+## Performing an activity
+
+The method `doActivity(long tick)` is called for every tick this external simulation should perform an activity. This
+method should provide a new tick as long as there are future activities.
+
+
+## Returning the data connections
+
+The method `getDataConnections` returns all [data connections](/connections/connections) that are used to connect the
+external simulation to SIMONA.