Merge pull request #132 from ie3-institute/sp/#131-adapt-scheduler

Adapting to new scheduling protocol

Author: sebastian-peter

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Updating to gradle 8.4 [#133](https://github.com/ie3-institute/simonaAPI/issues/133)
+- Adapted to changed SIMONA scheduler protocol [#131](https://github.com/ie3-institute/simonaAPI/issues/131)
 
 ## [0.2.0] - 2023-08-01
 
@@ -17,8 +18,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - JavaDoc for many message classes [#59](https://github.com/ie3-institute/simonaAPI/issues/59)
 - Implemented `ExtEvDataTest` as part of [#77](https://github.com/ie3-institute/simonaAPI/issues/77)
 
-### Fixed
-
 ### Changed
 - Refactored `ExtTrigger` -> `ExtSimMessage` and `ExtTriggerResponse` -> `ExtSimMessageResponse` [#5](https://github.com/ie3-institute/simonaAPI/issues/5)
 - Renamed messages to ease understanding [#62](https://github.com/ie3-institute/simonaAPI/issues/62)

src/main/java/edu/ie3/simona/api/simulation/ExtSimulation.java

@@ -12,6 +12,7 @@
 import edu.ie3.simona.api.simulation.ontology.*;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * Every external simulation must extend this class in order to get triggered by the main
@@ -48,24 +49,24 @@ private boolean takeAndHandleMessage() throws InterruptedException {
     // take() will block until an object is ready for us
     final ControlMessageToExt msg = data.receiveMessageQueue.take();
 
-    if (msg.getClass().equals(ActivityStartTrigger.class)) {
-      final ActivityStartTrigger activityStartTrigger = (ActivityStartTrigger) msg;
-      List<Long> newTriggers;
+    if (msg.getClass().equals(ActivationMessage.class)) {
+      final ActivationMessage activationMessage = (ActivationMessage) msg;
+      Optional<Long> newTrigger;
 
-      if (activityStartTrigger.tick() == -1L) {
-        newTriggers = initialize(); // this is blocking until initialization has finished
+      if (activationMessage.tick() == -1L) {
+        newTrigger = initialize(); // this is blocking until initialization has finished
       } else {
-        newTriggers =
+        newTrigger =
             doActivity(
-                activityStartTrigger
+                activationMessage
                     .tick()); // this is blocking until processing of this tick has finished
       }
-      data.send(new CompletionMessage(newTriggers));
+      data.send(new CompletionMessage(newTrigger));
 
-      return newTriggers.isEmpty();
-    } else if (msg.getClass().equals(Terminate.class)) {
-      final Terminate terminateMsg = (Terminate) msg;
-      terminate(terminateMsg.simulationSuccessful());
+      return newTrigger.isEmpty();
+    } else if (msg.getClass().equals(TerminationMessage.class)) {
+      final TerminationMessage terminationMsg = (TerminationMessage) msg;
+      terminate(terminationMsg.simulationSuccessful());
       data.send(new TerminationCompleted());
 
       return true;
@@ -77,22 +78,23 @@ private boolean takeAndHandleMessage() throws InterruptedException {
   /**
    * This method is called when the external simulation needs to be initialized
    *
-   * @return a list of future ticks at which this external simulation wants to be triggered.
+   * @return The first regular tick at which this external simulation wants to be triggered, if
+   *     applicable.
    */
-  protected abstract List<Long> initialize();
+  protected abstract Optional<Long> initialize();
 
   /**
    * This method is called for every tick of the external simulation that is triggered.
    *
    * @param tick The current tick
-   * @return a list of future ticks at which this external simulation wants to be triggered.
+   * @return The next tick at which this external simulation wants to be triggered, if applicable.
    */
-  protected abstract List<Long> doActivity(long tick);
+  protected abstract Optional<Long> doActivity(long tick);
 
   /**
    * This method is called when the main simulation wants to terminate.
    *
-   * @param simulationSuccessful whether the simulation was run successfully or has ended with an
+   * @param simulationSuccessful Whether the simulation was run successfully or has ended with an
    *     error
    */
   protected void terminate(Boolean simulationSuccessful) {

src/main/java/edu/ie3/simona/api/simulation/ontology/ActivityStartTrigger.java renamed to src/main/java/edu/ie3/simona/api/simulation/ontology/ActivationMessage.java

@@ -6,4 +6,9 @@
 
 package edu.ie3.simona.api.simulation.ontology;
 
-public record ActivityStartTrigger(long tick) implements ControlMessageToExt {}
+/**
+ * Message that the external simulation is activated with by SIMONA
+ *
+ * @param tick The current tick
+ */
+public record ActivationMessage(long tick) implements ControlMessageToExt {}

src/main/java/edu/ie3/simona/api/simulation/ontology/CompletionMessage.java

@@ -6,7 +6,12 @@
 
 package edu.ie3.simona.api.simulation.ontology;
 
-import java.util.Collection;
+import java.util.Optional;
 
-public record CompletionMessage(Collection<Long> newTriggers)
+/**
+ * Message that is returned to SIMONA
+ *
+ * @param nextActivation The tick that the external simulation would like to be activated at again
+ */
+public record CompletionMessage(Optional<Long> nextActivation)
     implements ControlResponseMessageFromExt {}

src/main/java/edu/ie3/simona/api/simulation/ontology/Terminate.java

@@ -6,4 +6,5 @@
 
 package edu.ie3.simona.api.simulation.ontology;
 
+/** Message returned to SIMONA indicating that the external simulation terminated */
 public record TerminationCompleted() implements ControlResponseMessageFromExt {}

src/main/java/edu/ie3/simona/api/simulation/ontology/TerminationCompleted.java

@@ -0,0 +1,15 @@
+/*
+ * © 2022. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.api.simulation.ontology;
+
+/**
+ * Message that is sent once SIMONA is terminating, indicating that the external simulation should
+ * shut down as well
+ *
+ * @param simulationSuccessful Whether SIMONA terminated successfully
+ */
+public record TerminationMessage(Boolean simulationSuccessful) implements ControlMessageToExt {}

src/main/java/edu/ie3/simona/api/simulation/ontology/TerminationMessage.java

@@ -4,10 +4,10 @@ import akka.actor.ActorSystem
 import akka.testkit.TestProbe
 import akka.testkit.javadsl.TestKit
 import edu.ie3.simona.api.data.ExtData
-import edu.ie3.simona.api.simulation.ontology.ActivityStartTrigger
+import edu.ie3.simona.api.simulation.ontology.ActivationMessage
 import edu.ie3.simona.api.simulation.ontology.CompletionMessage
 import edu.ie3.simona.api.simulation.ontology.ControlMessageToExt
-import edu.ie3.simona.api.simulation.ontology.Terminate
+import edu.ie3.simona.api.simulation.ontology.TerminationMessage
 import edu.ie3.simona.api.simulation.ontology.TerminationCompleted
 import spock.lang.Shared
 import spock.lang.Specification
@@ -28,22 +28,22 @@ class ExtSimulationSpec extends Specification {
      */
     private class TestSimulation extends ExtSimulation {
 
-        private List<Long> initReturnTicks
-        private List<Long> activityReturnTicks
+        private Optional<Long> initReturnTicks
+        private Optional<Long> activationReturnTick
 
-        TestSimulation(List<Long> initReturnTicks, List<Long> activityReturnTicks) {
-            this.initReturnTicks = initReturnTicks
-            this.activityReturnTicks = activityReturnTicks
+        TestSimulation(Optional<Long> initReturnTick, Optional<Long> activationReturnTick) {
+            this.initReturnTicks = initReturnTick
+            this.activationReturnTick = activationReturnTick
         }
 
         @Override
-        protected List<Long> initialize() {
+        protected Optional<Long> initialize() {
             return this.initReturnTicks
         }
 
         @Override
-        protected List<Long> doActivity(long tick) {
-            return this.activityReturnTicks
+        protected Optional<Long> doActivity(long tick) {
+            return this.activationReturnTick
         }
     }
 
@@ -63,39 +63,41 @@ class ExtSimulationSpec extends Specification {
     def "An ExtSimulation should handle initialization"() {
         given:
             def tick = -1L
-            def newTicks = [0L]
+            def newTick = Optional.of(0L)
             def testProbe = new TestProbe(actorSystem)
             def extSimData = new ExtSimAdapterData(testProbe.ref(), new String[0])
-            def extSim = new TestSimulation(newTicks, [-2L])
+            def extSim = new TestSimulation(newTick, Optional.of(-2L))
             extSim.setup(extSimData, new ArrayList<ExtData>())
 
         when:
-            extSimData.queueExtMsg(new ActivityStartTrigger(tick))
+            extSimData.queueExtMsg(new ActivationMessage(tick))
             def finishedActual = handleMessage.invoke(extSim)
 
         then:
             finishedActual == false
-            testProbe.expectMsg(new CompletionMessage(newTicks))
+            testProbe.expectMsg(new CompletionMessage(newTick))
     }
 
     def "An ExtSimulation should handle activation and return given new triggers"() {
         given:
             def testProbe = new TestProbe(actorSystem)
             def extSimData = new ExtSimAdapterData(testProbe.ref(), new String[0])
-            def extSim = new TestSimulation([-2L], newTicks)
+            def newTickOpt = newTick.isEmpty() ?
+                    Optional.<Long>empty() : Optional.of(newTick.first())
+            def extSim = new TestSimulation(Optional.of(-2L), newTickOpt)
             extSim.setup(extSimData, new ArrayList<ExtData>())
 
         when:
-            extSimData.queueExtMsg(new ActivityStartTrigger(tick))
+            extSimData.queueExtMsg(new ActivationMessage(tick))
             def finishedActual = handleMessage.invoke(extSim)
 
         then:
             finishedActual == finished
-            testProbe.expectMsg(new CompletionMessage(newTicks))
+            testProbe.expectMsg(new CompletionMessage(newTickOpt))
 
         where:
-            tick   | newTicks      || finished
-            0L     | [900L, 1800L] || false
+            tick   | newTick       || finished
+            0L     | [900L]        || false
             3600L  | [7200L]       || false
             7200L  | []            || true
             10800L | []            || true
@@ -105,11 +107,11 @@ class ExtSimulationSpec extends Specification {
         given:
             def testProbe = new TestProbe(actorSystem)
             def extSimData = new ExtSimAdapterData(testProbe.ref(), new String[0])
-            def extSim = new TestSimulation([], [])
+            def extSim = new TestSimulation(Optional.empty(), Optional.empty())
             extSim.setup(extSimData, new ArrayList<ExtData>())
 
         when:
-            extSimData.queueExtMsg(new Terminate(simlulationSuccessful))
+            extSimData.queueExtMsg(new TerminationMessage(simlulationSuccessful))
             def finishedActual = handleMessage.invoke(extSim)
 
         then:
@@ -128,7 +130,7 @@ class ExtSimulationSpec extends Specification {
         given:
             def testProbe = new TestProbe(actorSystem)
             def extSimData = new ExtSimAdapterData(testProbe.ref(), new String[0])
-            def extSim = new TestSimulation([], [])
+            def extSim = new TestSimulation(Optional.empty(), Optional.empty())
             extSim.setup(extSimData, new ArrayList<ExtData>())
 
         when: