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/readthedocs/concept.md b/docs/readthedocs/concept.md new file mode 100644 index 00000000..cbd8ee32 --- /dev/null +++ b/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 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 ================== 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() + } }