From 1564c5fc739b4760903c38f24a7bad0a2ebd1fb6 Mon Sep 17 00:00:00 2001 From: "David P. Chassin" Date: Mon, 13 Jan 2025 10:24:20 -0800 Subject: [PATCH] Update docs --- docs/Makefile.mk | 11 +- docs/{Utilities => Tools}/Create_filter.md | 2 +- docs/{Utilities => Tools}/Create_player.md | 2 +- docs/{Utilities => Tools}/Create_poles.md | 8 +- docs/{Utilities => Tools}/Edit.md | 2 +- docs/{Utilities => Tools}/Fire_danger.md | 2 +- docs/{Utilities => Tools}/Fire_report.md | 0 docs/{Utilities => Tools}/Framework.md | 2 +- docs/{Utilities => Tools}/Glutils.md | 2 +- docs/Tools/Makefile.mk | 6 + docs/{Utilities => Tools}/Mapping.md | 2 +- docs/{Utilities => Tools}/Market_data.md | 4 +- docs/{Utilities => Tools}/Market_model.md | 4 +- docs/{Utilities => Tools}/Metar2glm.md | 2 +- .../{Utilities => Tools}/Meteostat_weather.md | 2 +- docs/Tools/Moutils.md | 262 ++++++++++++++++++ docs/{Utilities => Tools}/Network.md | 2 +- docs/{Utilities => Tools}/Noaa_forecast.md | 2 +- docs/{Utilities => Tools}/Nsrdb_weather.md | 2 +- docs/{Utilities => Tools}/Rest_client.md | 4 +- docs/{Utilities => Tools}/Rest_server.md | 4 +- docs/{Utilities => Tools}/Unitcalc.md | 2 +- tools/create_filter.py | 4 +- 23 files changed, 299 insertions(+), 34 deletions(-) rename docs/{Utilities => Tools}/Create_filter.md (98%) rename docs/{Utilities => Tools}/Create_player.md (98%) rename docs/{Utilities => Tools}/Create_poles.md (96%) rename docs/{Utilities => Tools}/Edit.md (98%) rename docs/{Utilities => Tools}/Fire_danger.md (96%) rename docs/{Utilities => Tools}/Fire_report.md (100%) rename docs/{Utilities => Tools}/Framework.md (98%) rename docs/{Utilities => Tools}/Glutils.md (99%) create mode 100644 docs/Tools/Makefile.mk rename docs/{Utilities => Tools}/Mapping.md (99%) rename docs/{Utilities => Tools}/Market_data.md (97%) rename docs/{Utilities => Tools}/Market_model.md (97%) rename docs/{Utilities => Tools}/Metar2glm.md (93%) rename docs/{Utilities => Tools}/Meteostat_weather.md (94%) create mode 100644 docs/Tools/Moutils.md rename docs/{Utilities => Tools}/Network.md (99%) rename docs/{Utilities => Tools}/Noaa_forecast.md (98%) rename docs/{Utilities => Tools}/Nsrdb_weather.md (98%) rename docs/{Utilities => Tools}/Rest_client.md (88%) rename docs/{Utilities => Tools}/Rest_server.md (92%) rename docs/{Utilities => Tools}/Unitcalc.md (98%) diff --git a/docs/Makefile.mk b/docs/Makefile.mk index e2c793f76..ea2e23968 100644 --- a/docs/Makefile.mk +++ b/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 diff --git a/docs/Utilities/Create_filter.md b/docs/Tools/Create_filter.md similarity index 98% rename from docs/Utilities/Create_filter.md rename to docs/Tools/Create_filter.md index f0fb18e64..3414ab9ef 100644 --- a/docs/Utilities/Create_filter.md +++ b/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]] diff --git a/docs/Utilities/Create_player.md b/docs/Tools/Create_player.md similarity index 98% rename from docs/Utilities/Create_player.md rename to docs/Tools/Create_player.md index a6920b219..b18c7bc30 100644 --- a/docs/Utilities/Create_player.md +++ b/docs/Tools/Create_player.md @@ -1,4 +1,4 @@ -[[/Utilities/Create_player]] - Player object creation tool +[[/Tools/Create_player]] - Player object creation tool # Synopsis diff --git a/docs/Utilities/Create_poles.md b/docs/Tools/Create_poles.md similarity index 96% rename from docs/Utilities/Create_poles.md rename to docs/Tools/Create_poles.md index 2bd5e2915..c203d83d0 100644 --- a/docs/Utilities/Create_poles.md +++ b/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]] diff --git a/docs/Utilities/Edit.md b/docs/Tools/Edit.md similarity index 98% rename from docs/Utilities/Edit.md rename to docs/Tools/Edit.md index 8cb6f18f0..f44fc3593 100644 --- a/docs/Utilities/Edit.md +++ b/docs/Tools/Edit.md @@ -1,4 +1,4 @@ -[[/Utilities/Edit]] -- Model editor tool +[[/Tools/Edit]] -- Model editor tool Syntax: `gridlabd edit FILENAME [COMMANDS ...] [OPTIONS ...]` diff --git a/docs/Utilities/Fire_danger.md b/docs/Tools/Fire_danger.md similarity index 96% rename from docs/Utilities/Fire_danger.md rename to docs/Tools/Fire_danger.md index 9b1fcc1b2..eaeebc32e 100644 --- a/docs/Utilities/Fire_danger.md +++ b/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 diff --git a/docs/Utilities/Fire_report.md b/docs/Tools/Fire_report.md similarity index 100% rename from docs/Utilities/Fire_report.md rename to docs/Tools/Fire_report.md diff --git a/docs/Utilities/Framework.md b/docs/Tools/Framework.md similarity index 98% rename from docs/Utilities/Framework.md rename to docs/Tools/Framework.md index 7be8368d4..5675da66b 100644 --- a/docs/Utilities/Framework.md +++ b/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. diff --git a/docs/Utilities/Glutils.md b/docs/Tools/Glutils.md similarity index 99% rename from docs/Utilities/Glutils.md rename to docs/Tools/Glutils.md index e7830b256..2e1adb261 100644 --- a/docs/Utilities/Glutils.md +++ b/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 ...]` diff --git a/docs/Tools/Makefile.mk b/docs/Tools/Makefile.mk new file mode 100644 index 000000000..705d73fac --- /dev/null +++ b/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 diff --git a/docs/Utilities/Mapping.md b/docs/Tools/Mapping.md similarity index 99% rename from docs/Utilities/Mapping.md rename to docs/Tools/Mapping.md index 89a258e43..69b4cdd54 100644 --- a/docs/Utilities/Mapping.md +++ b/docs/Tools/Mapping.md @@ -1,4 +1,4 @@ -[[/Utilities/Mapping]] -- Mapping utilities +[[/Tools/Mapping]] -- Mapping utilities Syntax: `gridlabd mapping FILENAME [OPTIONS ...]` diff --git a/docs/Utilities/Market_data.md b/docs/Tools/Market_data.md similarity index 97% rename from docs/Utilities/Market_data.md rename to docs/Tools/Market_data.md index 81178e06c..273eda8d2 100644 --- a/docs/Utilities/Market_data.md +++ b/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/) diff --git a/docs/Utilities/Market_model.md b/docs/Tools/Market_model.md similarity index 97% rename from docs/Utilities/Market_model.md rename to docs/Tools/Market_model.md index bffad3f08..0454dd499 100644 --- a/docs/Utilities/Market_model.md +++ b/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]] diff --git a/docs/Utilities/Metar2glm.md b/docs/Tools/Metar2glm.md similarity index 93% rename from docs/Utilities/Metar2glm.md rename to docs/Tools/Metar2glm.md index 1f3b676bd..b49959008 100644 --- a/docs/Utilities/Metar2glm.md +++ b/docs/Tools/Metar2glm.md @@ -1,4 +1,4 @@ -[[/Utilities/Metar2glm]] - METAR to GLM realtime weather +[[/Tools/Metar2glm]] - METAR to GLM realtime weather # Synopsis diff --git a/docs/Utilities/Meteostat_weather.md b/docs/Tools/Meteostat_weather.md similarity index 94% rename from docs/Utilities/Meteostat_weather.md rename to docs/Tools/Meteostat_weather.md index 2a36327f8..336acc214 100644 --- a/docs/Utilities/Meteostat_weather.md +++ b/docs/Tools/Meteostat_weather.md @@ -1,4 +1,4 @@ -[[/Utilities/Meteostat_weather]] - Meteostat weather access +[[/Tools/Meteostat_weather]] - Meteostat weather access # Synopsis diff --git a/docs/Tools/Moutils.md b/docs/Tools/Moutils.md new file mode 100644 index 000000000..8b265430e --- /dev/null +++ b/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 + diff --git a/docs/Utilities/Network.md b/docs/Tools/Network.md similarity index 99% rename from docs/Utilities/Network.md rename to docs/Tools/Network.md index 3fc533ff3..0e909325f 100644 --- a/docs/Utilities/Network.md +++ b/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 ...]` diff --git a/docs/Utilities/Noaa_forecast.md b/docs/Tools/Noaa_forecast.md similarity index 98% rename from docs/Utilities/Noaa_forecast.md rename to docs/Tools/Noaa_forecast.md index 27b364067..4ab67f4d6 100644 --- a/docs/Utilities/Noaa_forecast.md +++ b/docs/Tools/Noaa_forecast.md @@ -1,4 +1,4 @@ -[[/Utilities/Noaa_forecast]] -- NOAA weather forecast utility +[[/Tools/Noaa_forecast]] -- NOAA weather forecast utility # Synopsis diff --git a/docs/Utilities/Nsrdb_weather.md b/docs/Tools/Nsrdb_weather.md similarity index 98% rename from docs/Utilities/Nsrdb_weather.md rename to docs/Tools/Nsrdb_weather.md index 078aced9d..6f5aeab9e 100644 --- a/docs/Utilities/Nsrdb_weather.md +++ b/docs/Tools/Nsrdb_weather.md @@ -1,4 +1,4 @@ -[[/Utilities/Nsrdb_weather]] -- NSRDB weather data utility +[[/Tools/Nsrdb_weather]] -- NSRDB weather data utility # Synopsis diff --git a/docs/Utilities/Rest_client.md b/docs/Tools/Rest_client.md similarity index 88% rename from docs/Utilities/Rest_client.md rename to docs/Tools/Rest_client.md index e0fe153d9..b955e93e6 100644 --- a/docs/Utilities/Rest_client.md +++ b/docs/Tools/Rest_client.md @@ -1,4 +1,4 @@ -[[/Utilities/Rest_client]] -- REST API Client +[[/Tools/Rest_client]] -- REST API Client # Synopsis @@ -20,4 +20,4 @@ The REST API client provide a convenience class to access a `gridlabd rest_serve # See also -* [[/Utilities/Rest_server]] +* [[/Tools/Rest_server]] diff --git a/docs/Utilities/Rest_server.md b/docs/Tools/Rest_server.md similarity index 92% rename from docs/Utilities/Rest_server.md rename to docs/Tools/Rest_server.md index 92a22a37d..d34ab4194 100644 --- a/docs/Utilities/Rest_server.md +++ b/docs/Tools/Rest_server.md @@ -1,4 +1,4 @@ -[[/Utilities/Rest_server]] -- GridLAB-D REST API Server +[[/Tools/Rest_server]] -- GridLAB-D REST API Server # Synopsis @@ -38,4 +38,4 @@ The GridLAB-D REST server provides gridlabd simulation control through a Flask A # See also -* [[/Utilities/Rest_client]] +* [[/Tools/Rest_client]] diff --git a/docs/Utilities/Unitcalc.md b/docs/Tools/Unitcalc.md similarity index 98% rename from docs/Utilities/Unitcalc.md rename to docs/Tools/Unitcalc.md index 732332bf0..215b61c8a 100644 --- a/docs/Utilities/Unitcalc.md +++ b/docs/Tools/Unitcalc.md @@ -1,4 +1,4 @@ -[[/Utilities/Unitcalc]] -- Unit support +[[/Tools/Unitcalc]] -- Unit support Syntax: gridlabd unitcalc VALUE [VALUE OP [...]] [OPTIONS ...] diff --git a/tools/create_filter.py b/tools/create_filter.py index e5ed5ac53..59923fd5a 100644 --- a/tools/create_filter.py +++ b/tools/create_filter.py @@ -1,5 +1,5 @@ # Syntax: create_filter NAME NUMERATOR DENOMINATOR [OPTIONS ...] -"""[[/Utilities/Create_filter]] - Create a filter from a transfer function +"""[[/Tools/Create_filter]] - Create a filter from a transfer function SYNOPSIS @@ -47,7 +47,7 @@ SEE ALSO -* [[/Utilities/Fit_filter]] +* [[/Tools/Fit_filter]] """ import sys, os