Update region partitioning concept

docs/puml/protocol/protocol.puml

@@ -9,8 +9,11 @@ database Input
 participant InputDataProvider
 participant OsmoGridGuardian
 participant LvCoordinator
-collections LvRegionCoordinator
-collections LvGridGenerator
+participant LvRegionCoordinator
+participant MunicipalityCoordinator
+participant DistrictCoordinator
+participant SubDistrictCoordinator
+participant LvGridGenerator
 participant ResultListener
 
 == Init ==
@@ -22,43 +25,65 @@ note right: Death watch of\n""ResultListener""
 
 == LV generation ==
 OsmoGridGuardian --> LvCoordinator: //Spawn//
-OsmoGridGuardian -> LvCoordinator: !ReqLvGrids(...)
-LvCoordinator -> InputDataProvider: !ReqOsm(...)
+OsmoGridGuardian -> LvCoordinator: <font color="red">!</font>ReqLvGrids(...)
+LvCoordinator -> InputDataProvider: <font color="red">!</font>ReqOsm(...)
 InputDataProvider <--> Input: //Read//
-LvCoordinator -> InputDataProvider: !ReqAssetTypes(...)
+LvCoordinator -> InputDataProvider: <font color="red">!</font>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 --> LvRegionCoordinator: //Spawn worker pool//
-
-LvCoordinator -> LvRegionCoordinator: !ReqLvGrids(...)
-deactivate LvCoordinator
-LvRegionCoordinator -> LvGridGenerator: !ReqLvGrid(...)
+InputDataProvider -> LvCoordinator: <font color="red">!</font>RepOsm(...)
+InputDataProvider -> LvCoordinator: <font color="red">!</font>RepAssetTypes(...)
+note right: Determine the highest\nadministrative boundary //n//
+LvCoordinator --> LvRegionCoordinator: //Spawn//
+
+LvCoordinator -> LvRegionCoordinator: <font color="red">!</font>Partition(Region)
+note right: //n// is the highest apparent\nadministrative boundary\nwithin OSM data
+LvRegionCoordinator --> LvRegionCoordinator: //Spawn//
+LvRegionCoordinator -> LvRegionCoordinator: <font color="red">!</font>Partition(Region, n')
+... **Recursively spawn and divide regions until administrative boundary of a municipality is reached** ...
+
+LvRegionCoordinator --> MunicipalityCoordinator: //Spawn one per municipality//
+LvRegionCoordinator -> MunicipalityCoordinator: <font color="red">!</font>HandleMunicipality(Region)
+
+MunicipalityCoordinator --> DistrictCoordinator: //Spawn one per district//
+MunicipalityCoordinator -> DistrictCoordinator: <font color="red">!</font>HandleDistrict(Region)
+
+DistrictCoordinator --> SubDistrictCoordinator: //Spawn one per sub district//
+DistrictCoordinator -> SubDistrictCoordinator: <font color="red">!</font>HandleSubDistrict(Region)
+
+SubDistrictCoordinator --> LvGridGenerator: //Spawn one per secondary//\n//substation region//
+SubDistrictCoordinator -> LvGridGenerator: <font color="red">!</font>BuildGridModel(Region)
+
 activate LvGridGenerator
 ... ...
-LvGridGenerator -> LvRegionCoordinator: !PepLvGrid(...)
+LvGridGenerator -> LvCoordinator: <font color="red">!</font>RepLvGrid(...)
+LvGridGenerator -> SubDistrictCoordinator: <font color="red">!</font>Done
+note left: Collects completions until\nall secondarysubstation\nregions are handled\n\nCompletion messages can\nbe realized with death watch!
 deactivate LvGridGenerator
 
-LvRegionCoordinator -> LvCoordinator: !RepLvGrids(...)
-LvCoordinator -> OsmoGridGuardian: !RepLvGrids(...)
+SubDistrictCoordinator -> DistrictCoordinator: <font color="red">!</font>Done
+DistrictCoordinator -> MunicipalityCoordinator: <font color="red">!</font>Done
+MunicipalityCoordinator -> LvRegionCoordinator: <font color="red">!</font>Done
+LvRegionCoordinator -> LvRegionCoordinator: <font color="red">!</font>Done
+... **Report recursively until all intermediate levels are passed** ...
+LvRegionCoordinator -> LvCoordinator: <font color="red">!</font>Done
+note left: All results are apparent;\nassign sub grid numbers
+
+LvCoordinator -> OsmoGridGuardian: <font color="red">!</font>RepLvGrids(...)
 
 == MV generation ==
 ... **To be defined in a later stage** ...
 
 == Result handling ==
-OsmoGridGuardian -> ResultListener: !GridResult(...)
+OsmoGridGuardian -> ResultListener: <font color="red">!</font>GridResult(...)
 activate ResultListener
 ... ...
-ResultListener -> OsmoGridGuardian: !ResultListenerDied
+ResultListener -> OsmoGridGuardian: <font color="red">!</font>ResultListenerDied
 deactivate ResultListener
-OsmoGridGuardian -> InputDataProvider: !Terminate(...)
+OsmoGridGuardian -> InputDataProvider: <font color="red">!</font>Terminate(...)
 InputDataProvider <--> Input: //Close//
-InputDataProvider -> OsmoGridGuardian: !InputDataProviderDied
+InputDataProvider -> OsmoGridGuardian: <font color="red">!</font>InputDataProviderDied
 
-OsmoGridGuardian -> Main: !Done
+OsmoGridGuardian -> Main: <font color="red">!</font>Done
 
 'TODO: Don't forget to spawn and initialize the ResultListener
 

docs/readthedocs/conf.py

@@ -36,8 +36,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'myst_parser',
-    'sphinx.ext.autosectionlabel',
+  'myst_parser',
+  'sphinx.ext.autosectionlabel',
 ]
 
 # Prefix all autogenerated labels wit the document to get unique labels (e.g. `index:Hello`)
@@ -70,4 +70,4 @@
 
 
 def setup(app):
-    app.add_css_file("css/theme_override.css")
+  app.add_css_file("css/theme_override.css")

docs/readthedocs/dev/concept.md

@@ -3,9 +3,27 @@
 ... 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.
 
+The computational heaviest part is connecting households / loads to the street graph as well as clustering the loads based on the distances following the street graph.
+This is why we want to shift those parts to the smallest regions possible.
+To achieve this, a given region of interest is partitioned heuristically as much as possible.
+The concept is as follows:
+
+![](../_static/figures/region_separation.png)
+
+The region of interest is broken down according to the administrative boundaries until the level of municipality boundaries is reached.
+Moreover, these municipal boundaries are further broken down to districts.
+They are defined as local dense groups of houses, that do form disjoint groups.
+However, if those dense groups are very big, computational complexity still can be too big.
+So, if need be, the districts are further broken down into smaller sub-districts.
+Based on those (sub-)districts, cluster of loads are build, that later form the regions of secondary substations.
+Those clusters respect the distance between them according to the street graph, they are connected to.
+Lastly, the street graph is converted into a grid model.
+
+Following this concept, the following actor hierarchy is implemented:
+
 ## Actors
 ### OsmoGridGuardian
-- Coordination of voltage level spanning routine
+- Coordination of multi voltage level spanning routine
 - Error handling
 - Collection of lv grids received from `LvCoordinator` and assigning subnet numbers
 
@@ -18,26 +36,42 @@ Here, we want to focus on the overall structure of the tool and which part does
 
 ### 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 `LvRegionCoordinator`s (needs to know the `LvGridGenerator` worker pool)
-- Hand over regions (here: municipalities) to `LvRegionCoordinator`s
-- Collect results from `LvRegionCoordinator`s and check completeness
+- 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
+- Collects results and checks completeness
+- *Outcome*: Complete region of interest + the highest available administrative boundary
 
 ### LvRegionCoordinator
-- 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`
+- Splits up the region of interest according to a given administrative boundary
+- If the level of a municipality is **NOT** reached:
+  - Spawns new `LvRegionCoordinator`s per new subregion to split up for the next lower administrative boundary
+  - *Outcome*: Subregions on administrative level `n` + the next lowest administrative level `n-1` 
+- If the level of a municipality is reached:
+  - Hand over the "municipalities" to `MunicipalityCoordinator`s
+  - *Outcome*: Subregions on administrative level "municipality"
+
+### MunicipalityCoordinator
+- Coordinates the region partitioning within the administrative boundary of a municipality
+- Determines dense and disjoint groups of houses as local "districts"
+- *Outcome*: Districts within the given municipality
+
+### DistrictCoordinator
+- Breaks down districts even further, if still too big w.r.t. computational measures (to be defined)
+- *Outcome*: (Sub)districts with suitable size
+
+### SubDistrictCoordinator
+- Responsible for handling a sub-district
+- A sub-district can also be a district, if that isn't too big
+- Derives loads from houses
+- Connects loads to street graph
+- Clusters loads while respecting the distance on the street graph
+- Those clusters are the regions of secondary substations
+- Hands over the graph to `GridGenerator`s
+- *Outcome*: Street subgraphs per secondary substation region
 
 ### 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
+- Generates a distinct, galvanically closed lv sub grid model from street graph
+- *Outcome*: Grid model per secondary substation region
 
 ### ResultListener
 - Persisting overall grid model to sinks