Add marimo utilities and mapping support (#271)

Signed-off-by: David P. Chassin <david.chassin@me.com>
Signed-off-by: David P. Chassin <dchassin@slac.stanford.edu>
Signed-off-by: Alyona Teyber <Ivanova.alyona5@gmail.com>
Signed-off-by: Duncan Ragsdale <88173870+Thistleman@users.noreply.github.com>
Co-authored-by: David P. Chassin <dchassin@slac.stanford.edu>
Co-authored-by: Alyona Teyber <Ivanova.alyona5@gmail.com>
Co-authored-by: snyk-bot <snyk-bot@snyk.io>
Co-authored-by: Duncan Ragsdale <88173870+Thistleman@users.noreply.github.com>

docs/Makefile.mk

@@ -1,14 +1,11 @@
 
-docs: docs/Utilities
+docs: docs/Tools
 
 DOCS_UTILITIES = 
-DOCS_UTILITIES += docs/Utilities/Framework.md
-DOCS_UTILITIES += docs/Utilities/Network.md
-DOCS_UTILITIES += docs/Utilities/Edit.md
-DOCS_UTILITIES += docs/Utilities/Mapping.md
-DOCS_UTILITIES += docs/Utilities/Unitcalc.md
 
-docs/Utilities: $(DOCS_UTILITIES)
+include $(top_srcdir)/docs/Tools/Makefile.mk
+
+docs/Tools: $(DOCS_UTILITIES)
 	echo "Updating $@..."
 
 %.md: FORCE

docs/Utilities/Create_filter.md → docs/Tools/Create_filter.md

@@ -46,4 +46,4 @@ model, with 8 bits of resolution and a dynamic range of (0,1):
 
 # See also
 
-* [[/Utilities/Fit_filter]]
+* [[/Tools/Fit_filter]]

docs/Utilities/Create_player.md → docs/Tools/Create_player.md

@@ -1,4 +1,4 @@
-[[/Utilities/Create_player]] - Player object creation tool
+[[/Tools/Create_player]] - Player object creation tool
 
 # Synopsis
 

docs/Utilities/Create_poles.md → docs/Tools/Create_poles.md

@@ -1,4 +1,4 @@
-[[/Utilities/Create_poles]] -- Creates poles and pole mounts for networks
+[[/Tools/Create_poles]] -- Creates poles and pole mounts for networks
 
 # Synopsis
 
@@ -111,6 +111,6 @@ The `create_poles` subcommand is a python extra command. It is not supported dir
 
 * [[/Module/Powerflow/Pole]]
 * [[/Module/Powerflow/Pole_mount]]
-* [[/Utilities/Library]]
-* [[/Utilities/Noaa_forecast]]
-* [[/Utilities/Nsrdb_weather]]
+* [[/Tools/Library]]
+* [[/Tools/Noaa_forecast]]
+* [[/Tools/Nsrdb_weather]]

docs/Utilities/Edit.md → docs/Tools/Edit.md

@@ -1,4 +1,4 @@
-[[/Utilities/Edit]] -- Model editor tool
+[[/Tools/Edit]] -- Model editor tool
 
 Syntax: `gridlabd edit FILENAME [COMMANDS ...] [OPTIONS ...]`
 

docs/Utilities/Fire_danger.md → docs/Tools/Fire_danger.md

@@ -1,4 +1,4 @@
-[[/Utilities/Fire_danger]] -- Fire danger forecast data tool
+[[/Tools/Fire_danger]] -- Fire danger forecast data tool
 
 # Synopsis
 

docs/Utilities/Framework.md → docs/Tools/Framework.md

@@ -1,4 +1,4 @@
-[[/Utilities/Framework]] -- Tool framework
+[[/Tools/Framework]] -- Tool framework
 
 The `framework` module contains the infrastructure to support standardized
 implementation of tools in GridLAB-D.

docs/Utilities/Glutils.md → docs/Tools/Glutils.md

@@ -1,4 +1,4 @@
-[[/Utilities/Glutils]] -- GridLAB-D model access utilities
+[[/Tools/Glutils]] -- GridLAB-D model access utilities
 
 Syntax: `gridlabd glutils JSONFILE [OPTIONS ...]`
 

docs/Tools/Makefile.mk

@@ -0,0 +1,6 @@
+DOCS_UTILITIES += docs/Tools/Framework.md
+DOCS_UTILITIES += docs/Tools/Network.md
+DOCS_UTILITIES += docs/Tools/Edit.md
+DOCS_UTILITIES += docs/Tools/Mapping.md
+DOCS_UTILITIES += docs/Tools/Moutils.md
+DOCS_UTILITIES += docs/Tools/Unitcalc.md

docs/Utilities/Mapping.md → docs/Tools/Mapping.md

@@ -1,4 +1,4 @@
-[[/Utilities/Mapping]] -- Mapping utilities
+[[/Tools/Mapping]] -- Mapping utilities
 
 Syntax: `gridlabd mapping FILENAME [OPTIONS ...]`
 

docs/Utilities/Market_data.md → docs/Tools/Market_data.md

@@ -1,4 +1,4 @@
-[[/Utilities/Market_data]] - ISO market data download tool
+[[/Tools/Market_data]] - ISO market data download tool
 
 # Synopsis
 
@@ -67,7 +67,7 @@ option.
 
 # See also
 
-* [[/Utilities/Market_model]]
+* [[/Tools/Market_model]]
 
 ISO Data Sources:
 * [CAISO](https://caiso.com/)

docs/Utilities/Market_model.md → docs/Tools/Market_model.md

@@ -1,4 +1,4 @@
-[[/Utilities/Market_model]] -- Create market model from ISO data
+[[/Tools/Market_model]] -- Create market model from ISO data
 
 # Synopsis
 
@@ -96,4 +96,4 @@ omits the LMP data in the input file.
 
 # See also
 
-* [[/Utilities/Market_data]]
+* [[/Tools/Market_data]]

docs/Utilities/Metar2glm.md → docs/Tools/Metar2glm.md

@@ -1,4 +1,4 @@
-[[/Utilities/Metar2glm]] - METAR to GLM realtime weather
+[[/Tools/Metar2glm]] - METAR to GLM realtime weather
 
 # Synopsis
 

docs/Utilities/Meteostat_weather.md → docs/Tools/Meteostat_weather.md

@@ -1,4 +1,4 @@
-[[/Utilities/Meteostat_weather]] - Meteostat weather access
+[[/Tools/Meteostat_weather]] - Meteostat weather access
 
 # Synopsis
 

docs/Tools/Moutils.md

@@ -0,0 +1,262 @@
+[[/Tools/Moutils]] -- Marimo utilities for gridlabd marimo apps
+
+
+# Classes
+
+## Map
+
+Map rendering class
+
+### `Map(model:[typing.Union[str, ~io.TextIOWrapper, NoneType]], nodedata:dict, linkdata:dict, options:dict)`
+
+Construct map rendering object from model object
+
+Arguments:
+
+* `model`: model object
+
+* `nodedata`: node data extraction dictionary (key is property name
+and value is form converter function)
+
+* `linkdata`: link data extraction dictionary (key is property name
+and value is form converter function)
+
+Returns:
+
+* `moutils.Map`: map rendering object
+
+
+### `Map.extract_network(nodedata:dict, linkdata:dict) -> list`
+
+Extract network data
+
+Arguments:
+
+* `data`: model data
+
+* `nodedata`: node data extraction dictionary (key is property name
+and value is form converter function)
+
+* `linkdata`: link data extraction dictionary (key is property name
+and value is form converter function)
+
+Returns:
+
+* `list[str]`: list of swing busses (if any)
+
+
+### `Map.read(data:dict, nodedata:dict, linkdata:dict) -> None`
+
+Read JSON data from model dictionary into model object
+
+Arguments:
+
+* `data`: model data
+
+* `nodedata`: node data extraction dictionary (key is property name
+and value is form converter function)
+
+* `linkdata`: link data extraction dictionary (key is property name
+and value is form converter function)
+
+
+### `Map.render() -> marimo.Html`
+
+Render map
+
+Arguments:
+
+* `**options`: `plotly.express.scatter_map` options
+
+Returns:
+
+* `marimo.Html`: marimo Html object
+
+
+### `Map.save() -> None`
+
+Save a map to a file
+
+Arguments:
+
+* `name`: filename
+
+* `**options`: `plotly.express.scattermap` options
+
+
+### `Map.show(options:dict) -> None`
+
+Show a map in the default web browser
+
+Arguments:
+
+* `**options`: `plotly.express.scattermap` options
+
+
+# Functions
+
+## `complex_unit() -> complex`
+
+Convert complex with units
+
+Arguments:
+
+* `x`: complex number
+
+* `form`: desired format
+
+Valid forms:
+
+* `None`: complex number
+
+* `rect`: return complex value in rectangular form (x,y)
+
+* `polar`: return complex value in polar form (mag,arg)
+
+* `i` or `j`: return rectangular form in `i` or `j` format
+
+* `d` or `r`: return polar form in degree or radians
+
+* `real`: return real part
+
+* `imag`: return imaginary part
+
+* `mag`: return magnitude of z
+
+* `arg`: return angle of x in radians
+
+* `ang`: return angle of x in degree
+
+* *other*: return attribute of `x`
+
+Returns:
+
+Returns:
+
+* `complex`: complex value (`form` is `None`)
+
+* `float`: real value (`form` in [`real`,`imag`,`mag`,`ang`,`arg`])
+
+* `tuple`: complex components (`form` in [`rect`,`polar`])
+
+* `str`: formatting complex value (`form` in [`i`,`j`,`d`,`r`])
+
+
+---
+
+## `float_unit() -> float`
+
+Convert float with units
+
+---
+
+## `gridlabd() -> subprocess.CompletedProcess`
+
+Run gridlabd
+
+Arguments:
+
+* `*args`: command line options
+
+* `bin`: enable direct binary runner (faster but disables subcommands and tools)
+
+* `**kwargs`: subprocess run options
+
+Returns:
+
+* `subprocess.CompletedProcess`: process info on success
+
+* `None`: on failure
+
+
+---
+
+## `model() -> None`
+
+Extract model data
+
+Arguments:
+
+* `source`: marimo upload object
+
+* `folder`: working folder (default is current folder)
+
+Returns:
+
+* `namedtuple`: contents of model dictionary
+
+
+---
+
+## `render_globals() -> marimo.Html`
+
+Render globals
+
+Arguments:
+
+* `model`: model object
+
+Returns:
+
+* `marimo.Html`: rendered Html object
+
+
+---
+
+## `render_map() -> marimo.Html`
+
+Render geodata as map
+
+Arguments:
+
+* `model`: model object
+
+Returns:
+
+* `marimo.Html`: rendered Html object
+
+
+---
+
+## `render_objects() -> marimo.Html`
+
+Render objects
+
+Arguments:
+
+* `model`: model object
+
+Returns:
+
+* `marimo.Html`: rendered Html object
+
+
+---
+
+## `render_sidebar() -> marimo.Html`
+
+Render app sidebar
+
+Arguments:
+
+* `upload`: marimo upload object
+
+Returns:
+
+* `marimo.Html`: rendered Html object
+
+
+---
+
+## `render_status() -> marimo.Html`
+
+Render status
+
+Arguments:
+
+* `model`: model object
+
+Returns:
+
+* `marimo.Html`: rendered Html object
+

docs/Utilities/Network.md → docs/Tools/Network.md

@@ -1,4 +1,4 @@
-[[/Utilities/Network]] -- GridLAB-D model access utilities
+[[/Tools/Network]] -- GridLAB-D model access utilities
 
 Syntax: `gridlabd network JSONFILE [OPTIONS ...]`
 

docs/Utilities/Noaa_forecast.md → docs/Tools/Noaa_forecast.md

@@ -1,4 +1,4 @@
-[[/Utilities/Noaa_forecast]] -- NOAA weather forecast utility
+[[/Tools/Noaa_forecast]] -- NOAA weather forecast utility
 
 # Synopsis