Merge pull request #356 from ie3-institute/ms/#348-abstract-flex-options

Refactoring flex options and em set points.

Author: sebastian-peter

CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased/Snapshot]
 
+### 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)

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 {}

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

@@ -7,6 +7,8 @@
 package edu.ie3.simona.api.data.model.em;
 
 import edu.ie3.datamodel.models.value.PValue;
+import java.util.Collections;
+import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
 import javax.measure.quantity.Power;
@@ -16,51 +18,49 @@
  * Energy management set point that will be sent to SIMONA.
  *
  * @param receiver The receiver of the set point.
- * @param sender The sender of the set point.
  * @param power An option for the em set point.
  */
-public record EmSetPoint(UUID receiver, UUID sender, Optional<PValue> power) implements EmData {
+public record EmSetPoint(UUID receiver, Optional<PValue> power, Map<UUID, PValue> disaggregated)
+    implements EmData {
   /**
    * Constructor for {@link EmSetPoint}.
    *
    * <p>Note: Using this constructor will signal SIMONA, that the current set point should be kept.
    *
    * @param receiver The receiver of the set point.
-   * @param sender The sender of the set point.
    */
-  public EmSetPoint(UUID receiver, UUID sender) {
-    this(receiver, sender, Optional.empty());
+  public EmSetPoint(UUID receiver) {
+    this(receiver, Optional.empty(), Collections.emptyMap());
   }
 
   /**
    * Constructor for {@link EmSetPoint}.
    *
    * @param receiver The receiver of the set point.
-   * @param sender The sender of the set point.
    * @param p Power value of the set point.
    */
-  public EmSetPoint(UUID receiver, UUID sender, ComparableQuantity<Power> p) {
-    this(receiver, sender, Optional.of(new PValue(p)));
+  public EmSetPoint(UUID receiver, ComparableQuantity<Power> p) {
+    this(receiver, Optional.of(new PValue(p)), Collections.emptyMap());
   }
 
   /**
    * Constructor for {@link EmSetPoint}.
    *
    * @param receiver The receiver of the set point.
-   * @param sender The sender of the set point.
-   * @param power value of the set point.
+   * @param power Value of the set point.
    */
-  public EmSetPoint(UUID receiver, UUID sender, PValue power) {
-    this(receiver, sender, Optional.ofNullable(power));
+  public EmSetPoint(UUID receiver, PValue power) {
+    this(receiver, Optional.ofNullable(power), Collections.emptyMap());
   }
 
-  @Override
-  public UUID getReceiver() {
-    return receiver;
-  }
-
-  @Override
-  public UUID getSender() {
-    return sender;
+  /**
+   * Constructor for {@link EmSetPoint}.
+   *
+   * @param receiver The receiver of the set point.
+   * @param power Value of the set point.
+   * @param disaggregated Map: uuid to disaggregated set points.
+   */
+  public EmSetPoint(UUID receiver, PValue power, Map<UUID, PValue> disaggregated) {
+    this(receiver, Optional.of(power), disaggregated);
   }
 }