Merge pull request #363 from ie3-institute/rel/sp/#362-release-0.11.0

Release 0.11.0

Author: sebastian-peter

CHANGELOG.md

@@ -6,8 +6,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased/Snapshot]
 
+## [0.11.0] - 2025-10-23
+
+### Added
+- General flex options [#348](https://github.com/ie3-institute/simonaAPI/issues/348)
+- Enhanced em set points [#357](https://github.com/ie3-institute/simonaAPI/issues/348)
+- Added dedicated flex communication classes [#358](https://github.com/ie3-institute/simonaAPI/issues/348)
+
 ### Changed
 - Updated the maven central publishing scripts [#339](https://github.com/ie3-institute/simonaAPI/issues/339)
+- Refactoring `ExtSimAdapterData` [#347](https://github.com/ie3-institute/simonaAPI/issues/347)
+- Enhanced `ExtEntityMapping` [#355](https://github.com/ie3-institute/simonaAPI/issues/355)
 
 ## [0.10.0] - 2025-09-10
 
@@ -96,7 +105,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.10.0...HEAD
+[Unreleased/Snapshot]: https://github.com/ie3-institute/simonaapi/compare/0.11.0...HEAD
+[0.11.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.10.0...0.11.0
 [0.10.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.9.0...0.10.0
 [0.9.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.8.0...0.9.0
 [0.8.0]: https://github.com/ie3-institute/powersystemdatamodel/compare/0.7.0...0.8.0

build.gradle

@@ -1,10 +1,10 @@
 plugins {
   id 'groovy' // groovy support
   id 'java' // java support
-  id 'com.diffplug.spotless' version '7.2.1'//code format
+  id 'com.diffplug.spotless' version '8.0.0'//code format
   id 'pmd' // code check, working on source code
-  id 'com.github.spotbugs' version '6.3.0' // code check, working on byte code
-  id "org.sonarqube" version "6.3.1.5724" // sonarqube
+  id 'com.github.spotbugs' version '6.4.4' // code check, working on byte code
+  id "org.sonarqube" version "7.0.0.6105" // 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
@@ -19,7 +19,7 @@ ext {
   // required for pekko
   scalaVersion = '3'
   scalaBinaryVersion = '3.7.3'
-  pekkoVersion = "1.2.0"
+  pekkoVersion = "1.2.1"
 }
 
 group = 'com.github.ie3-institute'
@@ -71,7 +71,7 @@ dependencies{
   }
 
   // logging
-  implementation platform('org.apache.logging.log4j:log4j-bom:2.25.1')
+  implementation platform('org.apache.logging.log4j:log4j-bom:2.25.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

docs/readthedocs/gettingstarted.md

@@ -8,8 +8,7 @@ SimonaAPI requires Java to be at least Version 21.
 
 ## Where to get
 
-Checkout latest from [GitHub](https://github.com/ie3-institute/simonaAPI) or use maven for dependency
-management:
+Checkout latest from [GitHub](https://github.com/ie3-institute/simonaAPI) or use our releases on maven central:
 
 ### Stable releases
 
@@ -19,34 +18,19 @@ On [Maven central](https://search.maven.org/artifact/com.github.ie3-institute/si
 <dependency>
   <groupId>com.github.ie3-institute</groupId>
   <artifactId>simonaAPI</artifactId>
-  <version>0.9.0</version>
+  <version>0.11.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.10-SNAPSHOT</version>
-</dependency>
-```
+There are currently no snapshot releases.
 
 ## 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`.
 
 With the release of version `0.10.0` there was a lot of refactoring, which breaks compatibility with older simulations.
+
+Additional breaking changes in version `0.11.0`

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

@@ -6,8 +6,8 @@
 
 package edu.ie3.simona.api;
 
+import edu.ie3.simona.api.data.ExtSimAdapterData;
 import edu.ie3.simona.api.exceptions.NoExtSimulationException;
-import edu.ie3.simona.api.simulation.ExtSimAdapterData;
 import edu.ie3.simona.api.simulation.ExtSimulation;
 
 /**

src/main/java/edu/ie3/simona/api/simulation/ExtSimAdapterData.java renamed to src/main/java/edu/ie3/simona/api/data/ExtSimAdapterData.java

@@ -4,8 +4,10 @@
  * Research group Distribution grid planning and operation
  */
 
-package edu.ie3.simona.api.simulation;
+package edu.ie3.simona.api.data;
 
+import com.typesafe.config.Config;
+import edu.ie3.datamodel.models.input.container.JointGridContainer;
 import edu.ie3.simona.api.ontology.simulation.ControlMessageToExt;
 import edu.ie3.simona.api.ontology.simulation.ControlResponseMessageFromExt;
 import java.util.concurrent.LinkedBlockingQueue;
@@ -23,12 +25,23 @@ public class ExtSimAdapterData {
   /** CLI arguments with which SIMONA is initiated */
   private final String[] mainArgs;
 
+  /** The parsed simona config. */
+  private final Config simonaConfig;
+
+  /** The electrical grid. */
+  private final JointGridContainer grid;
+
   // important trigger queue must be the same as held in actor
   // to make it safer one might consider asking the actor for a reference on its trigger queue?!
   public ExtSimAdapterData(
-      ActorRef<ControlResponseMessageFromExt> extSimAdapter, String[] mainArgs) {
+      ActorRef<ControlResponseMessageFromExt> extSimAdapter,
+      String[] mainArgs,
+      Config simonaConfig,
+      JointGridContainer grid) {
     this.extSimAdapter = extSimAdapter;
     this.mainArgs = mainArgs;
+    this.simonaConfig = simonaConfig;
+    this.grid = grid;
   }
 
   public ActorRef<ControlResponseMessageFromExt> getAdapter() {
@@ -59,4 +72,12 @@ public void send(ControlResponseMessageFromExt msg) {
   public String[] getMainArgs() {
     return mainArgs;
   }
+
+  public Config getSimonaConfig() {
+    return simonaConfig;
+  }
+
+  public JointGridContainer getGrid() {
+    return grid;
+  }
 }

src/main/java/edu/ie3/simona/api/data/connection/ExtEmDataConnection.java

@@ -6,10 +6,7 @@
 
 package edu.ie3.simona.api.data.connection;
 
-import edu.ie3.simona.api.data.model.em.EmSetPoint;
-import edu.ie3.simona.api.data.model.em.ExtendedFlexOptionsResult;
-import edu.ie3.simona.api.data.model.em.FlexOptionRequest;
-import edu.ie3.simona.api.data.model.em.FlexOptions;
+import edu.ie3.simona.api.data.model.em.*;
 import edu.ie3.simona.api.ontology.em.*;
 import java.util.*;
 
@@ -58,6 +55,45 @@ public boolean sendEmData(
     return false;
   }
 
+  /**
+   * Tries to send flex option requests to SIMONA. A message is sent, if at least one entity is
+   * given.
+   *
+   * @param tick current tick
+   * @param entities for which flex options should be requested
+   * @param disaggregated if disaggregated flex option should be returned
+   * @return true, if data was sent
+   */
+  public boolean sendFlexRequest(long tick, Collection<UUID> entities, boolean disaggregated) {
+    // send message only if at least one value is present
+    if (!entities.isEmpty()) {
+      sendExtMsg(new RequestEmFlexResults(tick, new ArrayList<>(entities), disaggregated));
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Tries to send communication messages to SIMONA. A message is sent, if at least one message is
+   * given.
+   *
+   * @param tick current tick
+   * @param emCommunicationMessages that should be sent
+   * @param maybeNextTick an option for the next tick
+   * @return true, if data was sent
+   */
+  public boolean sendCommunicationMessage(
+      long tick,
+      List<EmCommunicationMessage<?>> emCommunicationMessages,
+      Optional<Long> maybeNextTick) {
+    // send message only if at least one value is present
+    if (!emCommunicationMessages.isEmpty()) {
+      sendExtMsg(new EmCommunicationMessages(tick, emCommunicationMessages, maybeNextTick));
+      return true;
+    }
+    return false;
+  }
+
   /**
    * Tries to send the em set points to SIMONA.
    *

src/main/java/edu/ie3/simona/api/data/container/ExtDataContainer.java

@@ -6,7 +6,9 @@
 
 package edu.ie3.simona.api.data.container;
 
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 /** Interface for data that are exchanged between an external simulation and SimonaAPI */
@@ -28,4 +30,17 @@ default <K, V> Map<K, V> copyAndClear(Map<K, V> map) {
     map.clear();
     return result;
   }
+
+  /**
+   * Method to copy a given list and clear the original.
+   *
+   * @param list to be copied and cleared
+   * @return the copy
+   * @param <V> type of value
+   */
+  default <V> List<V> copyAndClear(List<V> list) {
+    List<V> result = new ArrayList<>(list);
+    list.clear();
+    return result;
+  }
 }

src/main/java/edu/ie3/simona/api/data/container/ExtInputContainer.java

@@ -8,6 +8,7 @@
 
 import edu.ie3.datamodel.models.value.PValue;
 import edu.ie3.datamodel.models.value.Value;
+import edu.ie3.simona.api.data.model.em.EmCommunicationMessage;
 import edu.ie3.simona.api.data.model.em.EmSetPoint;
 import edu.ie3.simona.api.data.model.em.FlexOptionRequest;
 import edu.ie3.simona.api.data.model.em.FlexOptions;
@@ -36,6 +37,9 @@ public final class ExtInputContainer implements ExtDataContainer {
   /** Map uuid to em set points. */
   private final Map<UUID, EmSetPoint> setPoints = new HashMap<>();
 
+  /** List of em communication messages. */
+  private final List<EmCommunicationMessage<?>> emMessages = new ArrayList<>();
+
   /**
    * Container class for input data for SIMONA which can be read by SimonaAPI
    *
@@ -82,15 +86,18 @@ public void addPrimaryValue(UUID asset, Value value) {
     primaryData.put(asset, value);
   }
 
+  public void addFlexComMessage(EmCommunicationMessage<?> message) {
+    emMessages.add(message);
+  }
+
   /**
    * Method for adding flex option requests. No disaggregated flex option will be requested using
    * this method.
    *
    * @param receiver the uuid of the agent, that will receive the request
-   * @param sender option for the uuid of the sender
    */
-  public void addRequest(UUID receiver, UUID sender) {
-    flexRequests.put(receiver, new FlexOptionRequest(receiver, sender, false));
+  public void addRequest(UUID receiver) {
+    flexRequests.put(receiver, new FlexOptionRequest(receiver, false));
   }
 
   public void addRequest(UUID receiver, FlexOptionRequest request) {
@@ -104,12 +111,7 @@ public void addRequest(UUID receiver, FlexOptionRequest request) {
    * @param flexOption that will be added
    */
   public void addFlexOptions(UUID receiver, List<FlexOptions> flexOption) {
-    if (!flexOptions.containsKey(receiver)) {
-      List<FlexOptions> flexOptionValues = new ArrayList<>(flexOption);
-      flexOptions.put(receiver, flexOptionValues);
-    } else {
-      flexOptions.get(receiver).addAll(flexOption);
-    }
+    flexOptions.computeIfAbsent(receiver, k -> new ArrayList<>()).addAll(flexOption);
   }
 
   /**
@@ -118,8 +120,8 @@ public void addFlexOptions(UUID receiver, List<FlexOptions> flexOption) {
    * @param asset that will receive the set point
    * @param power of the set point
    */
-  public void addSetPoint(UUID asset, UUID sender, PValue power) {
-    setPoints.put(asset, new EmSetPoint(asset, sender, power));
+  public void addSetPoint(UUID asset, PValue power) {
+    setPoints.put(asset, new EmSetPoint(asset, power));
   }
 
   /**
@@ -160,6 +162,13 @@ public Map<UUID, EmSetPoint> extractSetPoints() {
     return copyAndClear(setPoints);
   }
 
+  /**
+   * Extracts the em message input data from this container. All other input data remains the same.
+   */
+  public List<EmCommunicationMessage<?>> extractEmMessages() {
+    return copyAndClear(emMessages);
+  }
+
   /**
    * Returns a string representation of the primary input data without changing the data. To extract
    * (remove) the primary input data, use {@link #extractPrimaryData()} instead.

src/main/java/edu/ie3/simona/api/data/model/em/EmCommunicationMessage.java

@@ -0,0 +1,33 @@
+/*
+ * © 2025. 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.model.em;
+
+import java.util.UUID;
+
+/**
+ * Model of communication messages that can be sent between em agents.
+ *
+ * @param receiver of the data
+ * @param sender of the data
+ * @param msgId the message id of this message
+ * @param content the actual em data that is sent
+ * @param <D> type of the em data
+ */
+public record EmCommunicationMessage<D extends EmData>(
+    UUID receiver, UUID sender, UUID msgId, D content) implements EmData {
+
+  /**
+   * Constructor for {@link EmCommunicationMessage} that will generate a random message id.
+   *
+   * @param receiver of the data
+   * @param sender of the data
+   * @param content the actual em data that is sent
+   */
+  public EmCommunicationMessage(UUID receiver, UUID sender, D content) {
+    this(receiver, sender, UUID.randomUUID(), content);
+  }
+}

src/main/java/edu/ie3/simona/api/data/model/em/EmData.java

@@ -6,14 +6,5 @@
 
 package edu.ie3.simona.api.data.model.em;
 
-import java.util.UUID;
-
 /** Interface that is extended by all em data models. */
-public interface EmData {
-
-  /** Returns the uuid of the receiver. */
-  UUID getReceiver();
-
-  /** Returns the uuid of the sender. */
-  UUID getSender();
-}
+public interface EmData {}