Release 0.6.0

CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased/Snapshot]
 
+## [0.6.0] - 2024-12-02
+
+### Added
+- Enable initialization of external data simulation [#167](https://github.com/ie3-institute/simonaAPI/issues/167)
+- `ExtResultContainer` returns result map [#217](https://github.com/ie3-institute/simonaAPI/issues/217)
+
+### Changed
+- Renaming power fields in `EvModel` [#208](https://github.com/ie3-institute/simonaAPI/issues/208)
+- Enhancing external data connections [#219](https://github.com/ie3-institute/simonaAPI/issues/219)
+
 ## [0.5.0] - 2024-08-09
 
 ### Added
@@ -37,7 +47,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.5.0...HEAD
+[Unreleased/Snapshot]: https://github.com/ie3-institute/simonaapi/compare/0.6.0...HEAD
+[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
 [0.3.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.2.0...0.3.0

build.gradle

@@ -3,8 +3,8 @@ plugins {
   id 'java' // java support
   id 'com.diffplug.spotless' version '6.25.0'//code format
   id 'pmd' // code check, working on source code
-  id 'com.github.spotbugs' version '6.0.20' // code check, working on byte code
-  id "org.sonarqube" version "5.1.0.4882" // sonarqube
+  id 'com.github.spotbugs' version '6.0.26' // 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
@@ -17,8 +17,8 @@ ext {
 
   // required for pekko
   scalaVersion = "2.13"
-  scalaBinaryVersion = "2.13.14"
-  pekkoVersion = "1.0.3"
+  scalaBinaryVersion = "2.13.15"
+  pekkoVersion = "1.1.2"
 }
 
 group = 'com.github.ie3-institute'
@@ -46,33 +46,39 @@ repositories {
 
 dependencies{
 
-  implementation 'tech.units:indriya:2.2' // quantities
+  implementation 'tech.units:indriya:2.2.1' // quantities
 
   // scala (needed for pekko)
   implementation "org.scala-lang:scala-library:${scalaBinaryVersion}"
 
-  //PSDM
+  //PSU
   implementation('com.github.ie3-institute:PowerSystemUtils:2.2.1') {
     exclude group: 'org.apache.logging.log4j'
     exclude group: 'org.slf4j'
     /* Exclude our own nested dependencies */
     exclude group: 'com.github.ie3-institute'
   }
+
+  //PSDM
   implementation('com.github.ie3-institute:PowerSystemDataModel:5.1.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 '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
+
   // pekko
   implementation "org.apache.pekko:pekko-actor_${scalaVersion}:${pekkoVersion}"
   testImplementation "org.apache.pekko:pekko-testkit_${scalaVersion}:${pekkoVersion}" // pekko testkit
 
   // TESTING
   testImplementation 'org.spockframework:spock-core:2.3-groovy-4.0'
-
-  implementation group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.17.2'
 }
 
 task printVersion {

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

gradlew

@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+# SPDX-License-Identifier: Apache-2.0
+#
 
 ##############################################################################
 #
@@ -55,7 +57,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -84,7 +86,8 @@ done
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
 # Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
-APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum

gradlew.bat

@@ -13,6 +13,8 @@
 @rem See the License for the specific language governing permissions and
 @rem limitations under the License.
 @rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
 
 @if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
@@ -43,11 +45,11 @@ set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
 if %ERRORLEVEL% equ 0 goto execute
 
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 
@@ -57,11 +59,11 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
 if exist "%JAVA_EXE%" goto execute
 
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 

src/main/java/edu/ie3/simona/api/ExtLinkInterface.java

@@ -6,20 +6,25 @@
 
 package edu.ie3.simona.api;
 
-import edu.ie3.simona.api.data.ExtDataSimulation;
+import edu.ie3.simona.api.exceptions.NoExtSimulationException;
+import edu.ie3.simona.api.simulation.ExtSimAdapterData;
 import edu.ie3.simona.api.simulation.ExtSimulation;
-import java.util.List;
 
 /**
  * Every external simulation has to provide a class {@code edu.ie3.simona.api.ExtLink} which
  * implements this interface.
- *
- * <p>{@link #getExtSimulation()} and {@link #getExtDataSimulations()} can return references to the
- * same object, if that object implements both {@link ExtSimulation} and one or more variants of
- * {@link ExtDataSimulation}.
  */
 public interface ExtLinkInterface {
-  ExtSimulation getExtSimulation();
+  /** Returns the external simulation. */
+  default ExtSimulation getExtSimulation() {
+    throw new NoExtSimulationException(this.getClass());
+  }
 
-  List<ExtDataSimulation> getExtDataSimulations();
+  /**
+   * Method to set up an external simulation. Everything that needs to be set up before the external
+   * simulation can be retrieved should be done here.
+   *
+   * @param data used for setting up the external simulation
+   */
+  void setup(ExtSimAdapterData data);
 }

src/main/java/edu/ie3/simona/api/data/DataQueueExtSimulationExtSimulator.java

@@ -0,0 +1,22 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.api.data;
+
+import java.util.concurrent.LinkedBlockingQueue;
+
+/** Data queue to allow data flow between SimonaAPI and an external simulation */
+public class DataQueueExtSimulationExtSimulator<V extends ExtDataContainer> {
+  private final LinkedBlockingQueue<V> receiverTriggerQueue = new LinkedBlockingQueue<>();
+
+  public void queueData(V data) throws InterruptedException {
+    this.receiverTriggerQueue.put(data);
+  }
+
+  public V takeData() throws InterruptedException {
+    return this.receiverTriggerQueue.take();
+  }
+}

src/main/java/edu/ie3/simona/api/data/ExtData.java → src/main/java/edu/ie3/simona/api/data/ExtDataConnection.java

@@ -6,4 +6,5 @@
 
 package edu.ie3.simona.api.data;
 
-public interface ExtData {}
+/** Interface that defines a data connection between SIMONA and an external simulation. */
+public interface ExtDataConnection {}

src/main/java/edu/ie3/simona/api/exceptions/ConvertionException.java → src/main/java/edu/ie3/simona/api/data/ExtDataContainer.java

@@ -4,11 +4,7 @@
  * Research group Distribution grid planning and operation
  */
 
-package edu.ie3.simona.api.exceptions;
+package edu.ie3.simona.api.data;
 
-public class ConvertionException extends Exception {
-
-  public ConvertionException(final String message) {
-    super(message);
-  }
-}
+/** Interface for data that are exchanged between an external simulation and SimonaAPI */
+public interface ExtDataContainer {}

src/main/java/edu/ie3/simona/api/data/ExtInputDataConnection.java

@@ -0,0 +1,21 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.api.data;
+
+import org.apache.pekko.actor.ActorRef;
+
+public interface ExtInputDataConnection extends ExtDataConnection {
+
+  /**
+   * Sets the actor refs for data and control flow.
+   *
+   * @param dataService actor ref to the adapter of the data service for schedule activation
+   *     messages
+   * @param extSimAdapter actor ref to the extSimAdapter
+   */
+  void setActorRefs(ActorRef dataService, ActorRef extSimAdapter);
+}

src/main/java/edu/ie3/simona/api/data/ExtInputDataContainer.java

@@ -0,0 +1,69 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.api.data;
+
+import edu.ie3.datamodel.models.value.Value;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+/** Contains all inputs for SIMONA for a certain tick */
+public class ExtInputDataContainer implements ExtDataContainer {
+
+  /** The tick, the input data is meant for */
+  private final long tick;
+
+  /** Map external id to an input value for SIMONA */
+  private final Map<String, Value> dataMap;
+
+  /** The next tick, when data will be provided, if available */
+  private final Optional<Long> maybeNextTick;
+
+  /**
+   * Container class for input data for SIMONA which can be read by SimonaAPI
+   *
+   * @param tick The tick, the input data is meant for
+   * @param dataMap data to be provided to SIMONA
+   * @param nextTick tick, when the next data will be provided
+   */
+  public ExtInputDataContainer(long tick, Map<String, Value> dataMap, long nextTick) {
+    this.tick = tick;
+    this.dataMap = dataMap;
+    this.maybeNextTick = Optional.of(nextTick);
+  }
+
+  public ExtInputDataContainer(long tick, Map<String, Value> dataMap) {
+    this.tick = tick;
+    this.dataMap = dataMap;
+    this.maybeNextTick = Optional.empty();
+  }
+
+  public ExtInputDataContainer(long tick) {
+    this(tick, new HashMap<>());
+  }
+
+  public ExtInputDataContainer(long tick, long nextTick) {
+    this(tick, new HashMap<>(), nextTick);
+  }
+
+  public long getTick() {
+    return tick;
+  }
+
+  public Map<String, Value> getSimonaInputMap() {
+    return dataMap;
+  }
+
+  public Optional<Long> getMaybeNextTick() {
+    return maybeNextTick;
+  }
+
+  /** Adds a value to the input map */
+  public void addValue(String id, Value value) {
+    dataMap.put(id, value);
+  }
+}

src/main/java/edu/ie3/simona/api/data/ExtOutputDataConnection.java

@@ -0,0 +1,27 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.api.data;
+
+import org.apache.pekko.actor.ActorRef;
+
+/**
+ * Interface for a connection between SIMONA and an external simulation with data flow from SIMONA
+ * to external
+ */
+public interface ExtOutputDataConnection extends ExtDataConnection {
+
+  /**
+   * Sets the actor refs for data and control flow
+   *
+   * @param extResultDataService actor ref to the adapter of the data service for data messages
+   * @param dataServiceActivation actor ref to the adapter of the data service for schedule
+   *     activation messages
+   * @param extSimAdapter actor ref to the extSimAdapter
+   */
+  void setActorRefs(
+      ActorRef extResultDataService, ActorRef dataServiceActivation, ActorRef extSimAdapter);
+}