From 02a5fbecdd022d7009e12eaf05a42f808b30f205 Mon Sep 17 00:00:00 2001 From: "Kittl, Chris" Date: Mon, 29 Nov 2021 12:06:52 +0100 Subject: [PATCH 1/5] Propose two variants for a protocol --- docs/protocol/protocol_variantA.puml | 57 +++++++++++++++++++++++++ docs/protocol/protocol_variantB.puml | 63 ++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 docs/protocol/protocol_variantA.puml create mode 100644 docs/protocol/protocol_variantB.puml diff --git a/docs/protocol/protocol_variantA.puml b/docs/protocol/protocol_variantA.puml new file mode 100644 index 00000000..7858f201 --- /dev/null +++ b/docs/protocol/protocol_variantA.puml @@ -0,0 +1,57 @@ +@startuml +'https://plantuml.com/sequence-diagram + +!theme plain + +autonumber + +boundary Main +database Input +participant InputDataProvider +participant OsmoGridGuardian +participant LvGenerator +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(...) + +== LV generation == +OsmoGridGuardian --> LvGenerator: //Spawn// +OsmoGridGuardian -> LvGenerator: !Init(cfg) +LvGenerator -> OsmoGridGuardian: !InitComplete + +OsmoGridGuardian -> LvGenerator: !Run(cfg, ...) + +LvGenerator -> InputDataProvider: !GetOsm(...) +LvGenerator -> InputDataProvider: !GetAssetTypes(...) +note right: Contains information,\n that LV level is targeted +InputDataProvider <--> Input: //Read// +InputDataProvider -> LvGenerator: !ProvideOsm(...) +activate LvGenerator +... ... +note right: Start graph handling, clustering\nand scissor to sub-graphs +InputDataProvider -> LvGenerator: !ProvideAssetTypes(...) +LvGenerator --> LvGridGenerator: //Spawn// +LvGenerator -> LvGridGenerator: !Init(...) +LvGridGenerator -> LvGenerator: !InitComplete +LvGenerator -> LvGridGenerator: !BuildSubGrid(...) +deactivate LvGenerator +LvGridGenerator -> ResultListener: !PersistSubGrid(...) +LvGridGenerator -> LvGenerator: !SubGridBuilt(...) + +LvGenerator -> OsmoGridGuardian: !Done(...) + +== Finalize == +OsmoGridGuardian -> ResultListener: ?Finalize +ResultListener -> OsmoGridGuardian: !Done + +OsmoGridGuardian -> Main: !Done +@enduml diff --git a/docs/protocol/protocol_variantB.puml b/docs/protocol/protocol_variantB.puml new file mode 100644 index 00000000..b473ea82 --- /dev/null +++ b/docs/protocol/protocol_variantB.puml @@ -0,0 +1,63 @@ +@startuml +'https://plantuml.com/sequence-diagram + +!theme plain + +autonumber + +boundary Main +database Input +participant InputDataProvider +participant OsmoGridGuardian +participant LvGenerator +collections LvGraphHandler +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(...) + +== LV generation == +OsmoGridGuardian --> LvGenerator: //Spawn// +OsmoGridGuardian -> LvGenerator: !Init(cfg) +LvGenerator -> OsmoGridGuardian: !InitComplete + +OsmoGridGuardian -> LvGenerator: !Run(cfg, ...) + +LvGenerator -> InputDataProvider: !GetOsm(...) +LvGenerator -> InputDataProvider: !GetAssetTypes(...) +note right: Contains information,\n that LV level is targeted +InputDataProvider <--> Input: //Read// +InputDataProvider -> LvGenerator: !ProvideOsm(...) +note right: Scissor osm along\nmunicipality boundaries + +InputDataProvider -> LvGenerator: !ProvideAssetTypes(...) +LvGenerator --> LvGridGenerator: //Spawn// +LvGenerator -> LvGridGenerator: !Init(...) +LvGridGenerator -> LvGenerator: !InitComplete + +LvGenerator -> LvGraphHandler: !Run(...) +note right: Start graph handling, clustering\nand scissor to sub-graphs +activate LvGraphHandler +... ... +LvGraphHandler -> LvGridGenerator: !BuildSubGrid(...) +deactivate LvGraphHandler +LvGridGenerator -> ResultListener: !PersistSubGrid(...) +LvGridGenerator -> LvGraphHandler: !SubGridBuilt(...) + +LvGraphHandler -> LvGenerator: !Done(...) +LvGenerator -> OsmoGridGuardian: !Done(...) + +== Finalize == +OsmoGridGuardian -> ResultListener: ?Finalize +ResultListener -> OsmoGridGuardian: !Done + +OsmoGridGuardian -> Main: !Done +@enduml From 63d3f4a2798a998c4339d10b6c98fda019506abc Mon Sep 17 00:00:00 2001 From: "Kittl, Chris" Date: Mon, 29 Nov 2021 12:17:43 +0100 Subject: [PATCH 2/5] Add high level description --- docs/readthedocs/concept.md | 38 +++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/readthedocs/concept.md diff --git a/docs/readthedocs/concept.md b/docs/readthedocs/concept.md new file mode 100644 index 00000000..de81b9c2 --- /dev/null +++ b/docs/readthedocs/concept.md @@ -0,0 +1,38 @@ +# 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 routine +- Error handling + +### InputDataProvider +- Connects to OpenStreeMap (either via pbf file or API) +- Acquires needed data and filters it (dependent on the purpose) + +### LvGenerator +#### Variant A +- Transferring OSM data into suitable graph representation +- Clustering of nodes to transformer areas +- Scissoring graph into sub graphs + +### Variant B +- Scissoring OSM data along municipality boundaries +- Settlements only rarely cross municipality boundaries +- The concept of concessional agreements on serving a municipality incentive to not let grids cross boundaries +- Transferring OSM data into suitable graph representation + +### LvGraphHandler +**Only in variant B** +- Clustering of nodes to transformer areas +- Scissoring graph into sub graphs + +### LvGridGenerator +- Transfers a sub-graph into a sub-grid model +- Realized as worker pools held by `LvGenerator` + +### ResultListener +- Collecting and consolidating electrical grid structures +- Persisting them to sinks From 6f39275f52e2383e29171ca1a5dd39ddd05e9dc0 Mon Sep 17 00:00:00 2001 From: "Kittl, Chris" Date: Mon, 29 Nov 2021 12:18:24 +0100 Subject: [PATCH 3/5] Add high-level description to toc --- docs/readthedocs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/readthedocs/index.rst b/docs/readthedocs/index.rst index 058ec8af..a716f599 100644 --- a/docs/readthedocs/index.rst +++ b/docs/readthedocs/index.rst @@ -11,6 +11,7 @@ Welcome to OSMoGrid's documentation! :caption: Contents: legacy/legacy.md + concept.md Indices and tables ================== From e0b4096c7b8cfaad6b4eef09d2c1e2c1f8282170 Mon Sep 17 00:00:00 2001 From: "Kittl, Chris" Date: Tue, 30 Nov 2021 07:31:03 +0100 Subject: [PATCH 4/5] Fix formatting for markdown files --- gradle/scripts/spotless.gradle | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/gradle/scripts/spotless.gradle b/gradle/scripts/spotless.gradle index 0792fdd4..9ae13909 100644 --- a/gradle/scripts/spotless.gradle +++ b/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() + } } From 6868b67c202e743247ba9eb1fecabab90acb7f05 Mon Sep 17 00:00:00 2001 From: "Kittl, Chris" Date: Tue, 30 Nov 2021 08:01:44 +0100 Subject: [PATCH 5/5] Adapting protocol and high-level documentation according to discussion Co-authored-by: johanneshiry Co-authored-by: t-ober --- docs/protocol/protocol.puml | 69 ++++++++++++++++++++++++++++ docs/protocol/protocol_variantA.puml | 57 ----------------------- docs/protocol/protocol_variantB.puml | 63 ------------------------- docs/readthedocs/concept.md | 48 +++++++++---------- 4 files changed, 94 insertions(+), 143 deletions(-) create mode 100644 docs/protocol/protocol.puml delete mode 100644 docs/protocol/protocol_variantA.puml delete mode 100644 docs/protocol/protocol_variantB.puml diff --git a/docs/protocol/protocol.puml b/docs/protocol/protocol.puml new file mode 100644 index 00000000..90627db4 --- /dev/null +++ b/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 diff --git a/docs/protocol/protocol_variantA.puml b/docs/protocol/protocol_variantA.puml deleted file mode 100644 index 7858f201..00000000 --- a/docs/protocol/protocol_variantA.puml +++ /dev/null @@ -1,57 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -!theme plain - -autonumber - -boundary Main -database Input -participant InputDataProvider -participant OsmoGridGuardian -participant LvGenerator -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(...) - -== LV generation == -OsmoGridGuardian --> LvGenerator: //Spawn// -OsmoGridGuardian -> LvGenerator: !Init(cfg) -LvGenerator -> OsmoGridGuardian: !InitComplete - -OsmoGridGuardian -> LvGenerator: !Run(cfg, ...) - -LvGenerator -> InputDataProvider: !GetOsm(...) -LvGenerator -> InputDataProvider: !GetAssetTypes(...) -note right: Contains information,\n that LV level is targeted -InputDataProvider <--> Input: //Read// -InputDataProvider -> LvGenerator: !ProvideOsm(...) -activate LvGenerator -... ... -note right: Start graph handling, clustering\nand scissor to sub-graphs -InputDataProvider -> LvGenerator: !ProvideAssetTypes(...) -LvGenerator --> LvGridGenerator: //Spawn// -LvGenerator -> LvGridGenerator: !Init(...) -LvGridGenerator -> LvGenerator: !InitComplete -LvGenerator -> LvGridGenerator: !BuildSubGrid(...) -deactivate LvGenerator -LvGridGenerator -> ResultListener: !PersistSubGrid(...) -LvGridGenerator -> LvGenerator: !SubGridBuilt(...) - -LvGenerator -> OsmoGridGuardian: !Done(...) - -== Finalize == -OsmoGridGuardian -> ResultListener: ?Finalize -ResultListener -> OsmoGridGuardian: !Done - -OsmoGridGuardian -> Main: !Done -@enduml diff --git a/docs/protocol/protocol_variantB.puml b/docs/protocol/protocol_variantB.puml deleted file mode 100644 index b473ea82..00000000 --- a/docs/protocol/protocol_variantB.puml +++ /dev/null @@ -1,63 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -!theme plain - -autonumber - -boundary Main -database Input -participant InputDataProvider -participant OsmoGridGuardian -participant LvGenerator -collections LvGraphHandler -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(...) - -== LV generation == -OsmoGridGuardian --> LvGenerator: //Spawn// -OsmoGridGuardian -> LvGenerator: !Init(cfg) -LvGenerator -> OsmoGridGuardian: !InitComplete - -OsmoGridGuardian -> LvGenerator: !Run(cfg, ...) - -LvGenerator -> InputDataProvider: !GetOsm(...) -LvGenerator -> InputDataProvider: !GetAssetTypes(...) -note right: Contains information,\n that LV level is targeted -InputDataProvider <--> Input: //Read// -InputDataProvider -> LvGenerator: !ProvideOsm(...) -note right: Scissor osm along\nmunicipality boundaries - -InputDataProvider -> LvGenerator: !ProvideAssetTypes(...) -LvGenerator --> LvGridGenerator: //Spawn// -LvGenerator -> LvGridGenerator: !Init(...) -LvGridGenerator -> LvGenerator: !InitComplete - -LvGenerator -> LvGraphHandler: !Run(...) -note right: Start graph handling, clustering\nand scissor to sub-graphs -activate LvGraphHandler -... ... -LvGraphHandler -> LvGridGenerator: !BuildSubGrid(...) -deactivate LvGraphHandler -LvGridGenerator -> ResultListener: !PersistSubGrid(...) -LvGridGenerator -> LvGraphHandler: !SubGridBuilt(...) - -LvGraphHandler -> LvGenerator: !Done(...) -LvGenerator -> OsmoGridGuardian: !Done(...) - -== Finalize == -OsmoGridGuardian -> ResultListener: ?Finalize -ResultListener -> OsmoGridGuardian: !Done - -OsmoGridGuardian -> Main: !Done -@enduml diff --git a/docs/readthedocs/concept.md b/docs/readthedocs/concept.md index de81b9c2..cbd8ee32 100644 --- a/docs/readthedocs/concept.md +++ b/docs/readthedocs/concept.md @@ -5,34 +5,36 @@ Here, we want to focus on the overall structure of the tool and which part does ## Actors ### OsmoGridGuardian -- Coordination of routine +- 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 (dependent on the purpose) - -### LvGenerator -#### Variant A -- Transferring OSM data into suitable graph representation -- Clustering of nodes to transformer areas -- Scissoring graph into sub graphs - -### Variant B -- Scissoring OSM data along municipality boundaries -- Settlements only rarely cross municipality boundaries -- The concept of concessional agreements on serving a municipality incentive to not let grids cross boundaries -- Transferring OSM data into suitable graph representation - -### LvGraphHandler -**Only in variant B** -- Clustering of nodes to transformer areas -- Scissoring graph into sub graphs +- 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 -- Transfers a sub-graph into a sub-grid model -- Realized as worker pools held by `LvGenerator` +- 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 -- Collecting and consolidating electrical grid structures -- Persisting them to sinks +- Persisting overall grid model to sinks