Merge pull request #121 from ie3-institute/ck/#90-lvCoordinator

Lv Coordinator according to updated concept

CHANGELOG.md

@@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A `RunGuardian` takes care of a distinct simulation run and spawns all its needed services
   - Spawn an `InputDataProvider` and a `ResultListener`(if required) per run
   - Spawn `LvCoordinator` and trigger it
+- A `LvCoordinator` coordinates the generation of the low voltage grid level
+  - Acquires needed osm and asset input data
+  - Starts the process chain by spawning a `LvRegionCoordinator`
 - Coordinated shut down phase
   - Only terminate OSMoGrid internal result event listener and let additional listeners alive
   - Post stop phase for terminated children (to shut down data connections, ...)

docs/puml/actors/LvCoordinator.puml

@@ -0,0 +1,22 @@
+@startuml
+'https://plantuml.com/state-diagram
+
+!theme plain
+hide empty description
+
+idle: Awaiting arbitrary requests
+awaitInputData: Await OSM and\nasset information
+awaitResults: Await results
+
+[*] --> idle
+idle --> awaitInputData: !ReqLvGrids
+idle --> [*]: !Terminate\n//unsupported msg//
+
+awaitInputData --> awaitInputData: !WrappedInputDataResponse\n//if data missing//
+awaitInputData --> awaitResults: !WrappedInputDataResponse\n//if data complete//
+awaitInputData --> [*]: !Terminate\n//unsupported msg//
+
+awaitResults --> awaitResults: !StartGeneration
+awaitResults --> [*]: !WrappedRegionResponse
+awaitResults --> [*]: !Terminate\n//unsupported msg//
+@enduml

docs/readthedocs/dev/concept.md

@@ -36,10 +36,12 @@ Following this concept, the following actor hierarchy is implemented:
 
 ### LvCoordinator
 - Coordinates the generation of the whole low voltage level
-- Determines the highest available administrative boundary within the region of interest
-- Spawns an `LvRegionCoordinator` to split up the region of interest according to this administrative level
+- Spawns an `LvRegionCoordinator` to split up the region of interest
 - Collects results and checks completeness
-- *Outcome*: Complete region of interest + the highest available administrative boundary
+- *Outcome*: Complete region of interest to treat
+
+#### Finite state representation
+![](../_static/figures/puml/LvCoordinator.svg)
 
 ### LvRegionCoordinator
 - Splits up the region of interest according to a given administrative boundary

src/main/resources/config/config-template.conf

@@ -22,8 +22,6 @@ output: {
 generation: {
   #@optional
   lv: {
-    amountOfGridGenerators: Int | 10 # Amount of actors actually building the grids
-    amountOfRegionCoordinators: Int | 5 # Amount of actors coordinating generation per municipality
     distinctHouseConnections: Boolean | false # If there shall be distinct lines for house connection
   }
 }

src/main/scala/edu/ie3/osmogrid/ActorStopSupport.scala

@@ -0,0 +1,33 @@
+/*
+ * © 2022. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.osmogrid
+
+import akka.actor.typed.Behavior
+import akka.actor.typed.scaladsl.Behaviors
+import edu.ie3.osmogrid.io.input.InputDataProvider.Request
+import org.slf4j.Logger
+
+trait ActorStopSupport[T] {
+
+  /** Partial function to perform cleanup tasks while shutting down
+    */
+  protected val cleanUp: () => Unit
+
+  protected def terminate(log: Logger): Behavior[T] = {
+    log.info("Got request to terminate.")
+    stopBehavior
+  }
+
+  /** Specific stop state with clean up actions issued
+    */
+  protected val stopBehavior: Behavior[T] = Behaviors.stopped(cleanUp)
+
+  protected def postStopCleanUp(log: Logger): Behavior[T] = {
+    log.info("Got terminated by ActorSystem.")
+    stopBehavior
+  }
+}

src/main/scala/edu/ie3/osmogrid/cfg/ConfigFailFast.scala

@@ -47,18 +47,8 @@ object ConfigFailFast extends LazyLogging {
 
   private def checkLvConfig(lv: OsmoGridConfig.Generation.Lv): Unit = lv match {
     case Lv(
-          amountOfGridGenerators,
-          amountOfRegionCoordinators,
           distinctHouseConnections
         ) =>
-      if (amountOfGridGenerators < 1)
-        throw IllegalConfigException(
-          s"The amount of lv grid generation actors needs to be at least 1 (provided: $amountOfGridGenerators)."
-        )
-      if (amountOfRegionCoordinators < 1)
-        throw IllegalConfigException(
-          s"The amount of lv region coordination actors needs to be at least 1 (provided: $amountOfRegionCoordinators)."
-        )
   }
 
   private def checkInputConfig(input: OsmoGridConfig.Input): Unit =

src/main/scala/edu/ie3/osmogrid/cfg/OsmoGridConfig.scala

@@ -17,8 +17,6 @@ object OsmoGridConfig {
   )
   object Generation {
     final case class Lv(
-        amountOfGridGenerators: scala.Int,
-        amountOfRegionCoordinators: scala.Int,
         distinctHouseConnections: scala.Boolean
     )
     object Lv {
@@ -28,14 +26,6 @@ object OsmoGridConfig {
           $tsCfgValidator: $TsCfgValidator
       ): OsmoGridConfig.Generation.Lv = {
         OsmoGridConfig.Generation.Lv(
-          amountOfGridGenerators =
-            if (c.hasPathOrNull("amountOfGridGenerators"))
-              c.getInt("amountOfGridGenerators")
-            else 10,
-          amountOfRegionCoordinators =
-            if (c.hasPathOrNull("amountOfRegionCoordinators"))
-              c.getInt("amountOfRegionCoordinators")
-            else 5,
           distinctHouseConnections = c.hasPathOrNull(
             "distinctHouseConnections"
           ) && c.getBoolean("distinctHouseConnections")

src/main/scala/edu/ie3/osmogrid/exception/RequestFailedException.scala

@@ -0,0 +1,12 @@
+/*
+ * © 2022. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.osmogrid.exception
+
+case class RequestFailedException(
+    msg: String = "",
+    cause: Throwable = None.orNull
+) extends Exception(msg, cause)

src/main/scala/edu/ie3/osmogrid/guardian/OsmoGridGuardian.scala

@@ -21,8 +21,7 @@ import edu.ie3.osmogrid.guardian.run.RunGuardian
 import edu.ie3.osmogrid.io.input.InputDataProvider
 import edu.ie3.osmogrid.io.output.ResultListener
 import edu.ie3.osmogrid.io.output.ResultListener.{GridResult, Request}
-import edu.ie3.osmogrid.lv.LvCoordinator
-import edu.ie3.osmogrid.lv.LvCoordinator.ReqLvGrids
+import edu.ie3.osmogrid.lv.coordinator.LvCoordinator
 import org.slf4j.Logger
 
 import java.util.UUID

src/main/scala/edu/ie3/osmogrid/guardian/run/RunGuardian.scala

@@ -17,7 +17,7 @@ import edu.ie3.osmogrid.guardian.run.MessageAdapters.{
 import edu.ie3.osmogrid.guardian.run.{RunSupport, StopSupport, SubGridHandling}
 import edu.ie3.osmogrid.io.input.InputDataProvider
 import edu.ie3.osmogrid.io.output.ResultListener
-import edu.ie3.osmogrid.lv.LvCoordinator
+import edu.ie3.osmogrid.lv.coordinator
 
 import java.util.UUID
 import scala.util.{Failure, Success}
@@ -103,7 +103,7 @@ object RunGuardian extends RunSupport with StopSupport with SubGridHandling {
     case (
           ctx,
           WrappedLvCoordinatorResponse(
-            LvCoordinator.RepLvGrids(subGridContainers)
+            coordinator.RepLvGrids(subGridContainers)
           )
         ) =>
       /* Handle the grid results and wait for the listener to report back */