Protocol proposal

docs/protocol/protocol.puml

@@ -0,0 +1,69 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+!theme plain
+autonumber
+
+boundary Main
+database Input
+participant InputDataProvider
+participant OsmoGridGuardian
+participant LvCoordinator
+collections LvRegionGenerator
+collections LvGridGenerator
+participant ResultListener
+
+== Init ==
+Main -> OsmoGridGuardian: Run(cfg)
+OsmoGridGuardian --> InputDataProvider: //Spawn//
+OsmoGridGuardian -> InputDataProvider: !Init(cfg)
+InputDataProvider -> OsmoGridGuardian: !InitComplete
+
+OsmoGridGuardian --> ResultListener: //Spawn//
+OsmoGridGuardian -> ResultListener: !Init(...)
+ResultListener -> OsmoGridGuardian: !InitComplete(...)
+note right: Death watch of\n""ResultListener""
+
+== LV generation ==
+OsmoGridGuardian --> LvCoordinator: //Spawn//
+OsmoGridGuardian -> LvCoordinator: !ReqLvGrids(...)
+LvCoordinator -> InputDataProvider: !ReqOsm(...)
+InputDataProvider <--> Input: //Read//
+LvCoordinator -> InputDataProvider: !ReqAssetTypes(...)
+InputDataProvider <--> Input: //Read//
+InputDataProvider -> LvCoordinator: !RepOsm(...)
+InputDataProvider -> LvCoordinator: !RepAssetTypes(...)
+activate LvCoordinator
+note right: Partition OSM data\nby municipal boundaries
+LvCoordinator --> LvGridGenerator: //Spawn worker pool//
+LvCoordinator --> LvRegionGenerator: //Spawn worker pool//
+
+LvCoordinator -> LvRegionGenerator: !ReqLvGrids(...)
+deactivate LvCoordinator
+LvRegionGenerator -> LvGridGenerator: !ReqLvGrid(...)
+activate LvGridGenerator
+... ...
+LvGridGenerator -> LvRegionGenerator: !PepLvGrid(...)
+deactivate LvGridGenerator
+
+LvRegionGenerator -> LvCoordinator: !RepLvGrids(...)
+LvCoordinator -> OsmoGridGuardian: !RepLvGrids(...)
+
+== MV generation ==
+... **To be defined in a later stage** ...
+
+== Result handling ==
+OsmoGridGuardian -> ResultListener: !PersistJointGrid(...)
+activate ResultListener
+... ...
+ResultListener -> OsmoGridGuardian: !Terminated(...)
+deactivate ResultListener
+OsmoGridGuardian -> InputDataProvider: !Terminate(...)
+InputDataProvider <--> Input: //Close//
+InputDataProvider -> OsmoGridGuardian: !Terminated(...)
+
+OsmoGridGuardian -> Main: !Done
+
+'TODO: Don't forget to spawn and initialize the ResultListener
+
+@enduml

docs/readthedocs/concept.md

@@ -0,0 +1,40 @@
+# Concept
+
+... of OSMoGrid and it's implementation.
+Here, we want to focus on the overall structure of the tool and which part does serve which purpose.
+
+## Actors
+### OsmoGridGuardian
+- Coordination of voltage level spanning routine
+- Error handling
+- Collection of lv grids received from `LvCoordinator` and assigning subnet numbers
+
+### InputDataProvider
+- Connects to OpenStreeMap (either via pbf file or API)
+- Acquires needed data and filters it (on request and dependent on the purpose)
+
+### LvCoordinator
+- Coordinates the generation of the whole low voltage level
+- Partitions the OSM data by municipal boundaries
+  - Settlements only rarely cross municipality boundaries
+  - The concept of concessional agreements on serving a municipality incentive to not let grids cross boundaries
+- Spawns a pool of `LvGridGenerator`s
+- Spawns a pool of `LvRegionHandler`s (needs to know the `LvGridGenerator` worker pool)
+- Hand over regions (here: municipalities) to `LvRegionGenerator`s
+- Collect results from `LvRegionGenerator`s and check completeness
+
+### LvRegionalGenerator
+- Responsible for generation of lv grids within a defined region (might be a municipality)
+- Generate loads in that region
+- Cluster them to secondary-substation regions
+- Build sub-graphs according to secondary-substation regions and hands them over to `LvGridGenerator`s
+- Collect results from `LvGridGenerator`s, check completeness and forward them to `LvCoordinator`
+
+### LvGridGenerator
+- Generates a distinct, galvanically closed lv sub grid model
+- Building the distance matrix
+- Determining perpendiculars and connect loads to the street graph
+- Transform into electrical grid model
+
+### ResultListener
+- Persisting overall grid model to sinks

docs/readthedocs/index.rst

@@ -11,6 +11,7 @@ Welcome to OSMoGrid's documentation!
    :caption: Contents:
 
    legacy/legacy.md
+   concept.md
 
 Indices and tables
 ==================

gradle/scripts/spotless.gradle

@@ -39,9 +39,17 @@ spotless {
 
   // removes unnecessary whitespace, indents with tabs and ends on new line for gradle, md and gitignore files and config-XMLs
   format 'misc', {
-    target '**/*.md', '**/.gitignore', 'configs/**'
+    target '**/.gitignore', 'configs/**'
     trimTrailingWhitespace()
     indentWithTabs()
     endWithNewline()
   }
+
+  /* Formats markdown files, just like the other misc files, but without trimming trailing white spaces (nested
+   * enumerations) */
+  format 'md', {
+    target '**/*.md'
+    indentWithSpaces 2
+    endWithNewline()
+  }
 }