Merge pull request #138 from ie3-institute/sp/#137-LvRegionCoordinator

 Implementing `LvRegionCoordinator`, osm splitting

Author: t-ober

.gitattributes

@@ -1,2 +1,3 @@
 # These are explicitly windows files and should use crlf
 *.bat           text eol=crlf
+*.pbf           binary

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

@@ -23,6 +23,10 @@ generation: {
   #@optional
   lv: {
     distinctHouseConnections: Boolean | false # If there shall be distinct lines for house connection
+    boundaryAdminLevel: {
+      starting: Int | 2
+      lowest: Int | 8
+    }
     osm: {
       #@optional
       filter: { # filter to be applied for the LvOsmoGridModel

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

@@ -12,28 +12,28 @@ import org.slf4j.Logger
 
 /** Support trait for executing clean up tasks with stopping an actor
   *
-  * @tparam T
-  *   Behavior type
   * @tparam S
   *   StateData type. Optional, use [[Any]] if not applicable
   */
-trait ActorStopSupport[T, S] {
+trait ActorStopSupport[S] {
 
   /** Function to perform cleanup tasks while shutting down
     */
   protected def cleanUp(stateData: S): Unit
 
   /** Specific stop state with clean up actions issued
+    * @tparam T
+    *   Behavior type
     */
-  protected def stopBehavior(stateData: S): Behavior[T] =
+  protected def stopBehavior[T](stateData: S): Behavior[T] =
     Behaviors.stopped(() => cleanUp(stateData))
 
-  final protected def terminate(log: Logger, stateData: S): Behavior[T] = {
+  final protected def terminate[T](log: Logger, stateData: S): Behavior[T] = {
     log.info("Got request to terminate.")
     stopBehavior(stateData)
   }
 
-  final protected def postStopCleanUp(
+  final protected def postStopCleanUp[T](
       log: Logger,
       stateData: S
   ): Behavior[T] = {

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

@@ -11,25 +11,25 @@ import akka.actor.typed.scaladsl.Behaviors
 import org.slf4j.Logger
 
 /** Support trait for executing clean up tasks with stopping an actor
-  * @tparam T
-  *   Behavior type
   */
-trait ActorStopSupportStateless[T] {
+trait ActorStopSupportStateless {
 
   /** Function to perform cleanup tasks while shutting down
     */
   protected def cleanUp(): Unit
 
   /** Specific stop state with clean up actions issued
+    * @tparam T
+    *   Behavior type
     */
-  protected val stopBehavior: Behavior[T] = Behaviors.stopped(cleanUp)
+  protected def stopBehavior[T]: Behavior[T] = Behaviors.stopped(cleanUp)
 
-  final protected def terminate(log: Logger): Behavior[T] = {
+  final protected def terminate[T](log: Logger): Behavior[T] = {
     log.info("Got request to terminate.")
     stopBehavior
   }
 
-  final protected def postStopCleanUp(log: Logger): Behavior[T] = {
+  final protected def postStopCleanUp[T](log: Logger): Behavior[T] = {
     log.info("Got terminated by ActorSystem.")
     stopBehavior
   }

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

@@ -8,12 +8,12 @@ package edu.ie3.osmogrid.cfg
 
 import akka.actor.typed.ActorRef
 import com.typesafe.scalalogging.LazyLogging
-import edu.ie3.osmogrid.cfg.OsmoGridConfig.{Input, Output}
-import edu.ie3.osmogrid.cfg.OsmoGridConfig.Input.{Asset, Osm}
-import edu.ie3.osmogrid.cfg.OsmoGridConfig.Generation
 import edu.ie3.osmogrid.cfg.OsmoGridConfig.Generation.Lv
 import edu.ie3.osmogrid.cfg.OsmoGridConfig.Input.Asset.File
+import edu.ie3.osmogrid.cfg.OsmoGridConfig.Input.{Asset, Osm}
+import edu.ie3.osmogrid.cfg.OsmoGridConfig.{Generation, Input, Output}
 import edu.ie3.osmogrid.exception.IllegalConfigException
+import edu.ie3.osmogrid.io.input.BoundaryAdminLevel
 import edu.ie3.osmogrid.io.output.ResultListener
 
 import scala.util.Try
@@ -47,19 +47,30 @@ object ConfigFailFast extends LazyLogging {
 
   private def checkLvConfig(lv: OsmoGridConfig.Generation.Lv): Unit = lv match {
     case Lv(
-          amountOfGridGenerators,
-          amountOfRegionCoordinators,
-          distinctHouseConnections,
-          lv.osm
+          Lv.BoundaryAdminLevel(
+            lowest,
+            starting
+          ),
+          _,
+          _
         ) =>
-      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)."
-        )
+      (BoundaryAdminLevel(lowest), BoundaryAdminLevel(starting)) match {
+        case (None, _) =>
+          throw IllegalConfigException(
+            s"The lowest admin level can not be parsed (provided: $lowest)."
+          )
+        case (_, None) =>
+          throw IllegalConfigException(
+            s"The starting admin level can not be parsed (provided: $starting)."
+          )
+        case (Some(lowestParsed), Some(startingParsed))
+            if startingParsed > lowestParsed =>
+          throw IllegalConfigException(
+            s"The starting admin level (provided: $startingParsed) has to be higher than the lowest admin level (provided: $lowestParsed)."
+          )
+        case _ =>
+        // all good, do nothing
+      }
   }
 
   private def checkInputConfig(input: OsmoGridConfig.Input): Unit =

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

@@ -17,12 +17,29 @@ object OsmoGridConfig {
   )
   object Generation {
     final case class Lv(
-        amountOfGridGenerators: scala.Int,
-        amountOfRegionCoordinators: scala.Int,
+        boundaryAdminLevel: OsmoGridConfig.Generation.Lv.BoundaryAdminLevel,
         distinctHouseConnections: scala.Boolean,
         osm: OsmoGridConfig.Generation.Lv.Osm
     )
     object Lv {
+      final case class BoundaryAdminLevel(
+          lowest: scala.Int,
+          starting: scala.Int
+      )
+      object BoundaryAdminLevel {
+        def apply(
+            c: com.typesafe.config.Config,
+            parentPath: java.lang.String,
+            $tsCfgValidator: $TsCfgValidator
+        ): OsmoGridConfig.Generation.Lv.BoundaryAdminLevel = {
+          OsmoGridConfig.Generation.Lv.BoundaryAdminLevel(
+            lowest = if (c.hasPathOrNull("lowest")) c.getInt("lowest") else 8,
+            starting =
+              if (c.hasPathOrNull("starting")) c.getInt("starting") else 2
+          )
+        }
+      }
+
       final case class Osm(
           filter: scala.Option[OsmoGridConfig.Generation.Lv.Osm.Filter]
       )
@@ -75,14 +92,15 @@ 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,
+          boundaryAdminLevel = OsmoGridConfig.Generation.Lv.BoundaryAdminLevel(
+            if (c.hasPathOrNull("boundaryAdminLevel"))
+              c.getConfig("boundaryAdminLevel")
+            else
+              com.typesafe.config.ConfigFactory
+                .parseString("boundaryAdminLevel{}"),
+            parentPath + "boundaryAdminLevel.",
+            $tsCfgValidator
+          ),
           distinctHouseConnections = c.hasPathOrNull(
             "distinctHouseConnections"
           ) && c.getBoolean("distinctHouseConnections"),

src/main/scala/edu/ie3/osmogrid/io/input/BoundaryAdminLevel.scala

@@ -0,0 +1,66 @@
+/*
+ * © 2022. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.osmogrid.io.input
+
+/** Represents the levels of
+  * [[https://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative administrative boundaries]]
+  * in OSM
+  */
+enum BoundaryAdminLevel(val osmLevel: Int) extends Ordered[BoundaryAdminLevel] {
+
+  /** National border (NUTS 0)
+    */
+  case NationLevel extends BoundaryAdminLevel(2)
+
+  /** Federal states border (Bundesland) (NUTS 1)
+    */
+  case FederalStateLevel extends BoundaryAdminLevel(4)
+
+  /** State-district border (Regierungsbezirk) (NUTS 2)
+    */
+  case StateDistrictLevel extends BoundaryAdminLevel(5)
+
+  /** County borders (Landkreis / Kreis / kreisfreie Stadt / Stadtkreis) (NUTS
+    * 3)
+    */
+  case CountyLevel extends BoundaryAdminLevel(6)
+
+  /** Amt (Amtsgemeinde, Verwaltungsgemeinschaft) (LAU 1/NUTS 4)
+    */
+  case AmtLevel extends BoundaryAdminLevel(7)
+
+  /** Towns, Municipalities / City-districts (Stadt, Gemeinde) (LAU 2/NUTS 5)
+    */
+  case MunicipalityLevel extends BoundaryAdminLevel(8)
+
+  /** Parts of a municipality with parish councils / self government
+    * (Stadtbezirk/Gemeindeteil mit Selbstverwaltung)
+    */
+  case Suburb1Level extends BoundaryAdminLevel(9)
+
+  /** Parts of a municipality without parish councils / self government
+    * (Stadtteil/Gemeindeteil ohne Selbstverwaltung)
+    */
+  case Suburb2Level extends BoundaryAdminLevel(10)
+
+  /** Neighbourhoods, statistical or historical (Stadtviertel etc.)
+    */
+  case Suburb3Level extends BoundaryAdminLevel(11)
+
+  def compare(other: BoundaryAdminLevel): Int =
+    osmLevel compareTo other.osmLevel
+}
+
+object BoundaryAdminLevel {
+  def apply(osmLevel: Int): Option[BoundaryAdminLevel] =
+    BoundaryAdminLevel.values.find(_.osmLevel == osmLevel)
+
+  def nextLowerLevel(
+      boundaryAdminLevel: BoundaryAdminLevel
+  ): Option[BoundaryAdminLevel] =
+    BoundaryAdminLevel.values.filter(_ > boundaryAdminLevel).minOption
+}

src/main/scala/edu/ie3/osmogrid/io/input/InputDataProvider.scala

@@ -37,8 +37,7 @@ import scala.collection.mutable.ListBuffer
 import scala.util.{Failure, Success, Try, Using}
 import java.util.UUID
 
-object InputDataProvider
-    extends ActorStopSupport[InputDataEvent, ProviderData] {
+object InputDataProvider extends ActorStopSupport[ProviderData] {
 
   // external requests
   sealed trait Request