Add pole creation utility (#1025)

* Update gridlabd-version

* Add stub for create_poles utility

* Update ieee13.glm

* Update create_poles.py

* Move ieee13 test model

* Update create_poles.py

* Update create_poles.py

* Update create_poles.py

* Update create_poles.py

* Update create_poles.py

* Create Create_poles.md

* Update Create_poles.md

* Update Create_poles.md

* Update Create_poles.md

* Update create_poles.py

* Update Create_poles.md

* Update create_poles.py

* Update Create_poles.md

* Update create_poles.py

* Update create_poles.py

* Update Create_poles.md

* Update create_poles.py

* Update Create_poles.md

* Update Create_poles.md

* Update Create_poles.md

* Update create_poles.py

* Update create_poles.py

* Update noaa_forecast.py

* Add reset of clock and new clock directive is encountered

* Update Create_poles.md

* Update pole_mount.cpp

* Update noaa_forecast.py

* Update create_poles.py

* Update create_poles.py

* Update Create_poles.md

* Update create_poles.py

* Update ieee13.glm

* Add support for node-like equipment mounts

* Update docs

* Fix player so it accept CSV file header as property list

* Update Player.md

* Update noaa_forecast.py

* Update nsrdb_weather.py

* Update Create_poles.md

Co-authored-by: Alyona Teyber <[email protected]>

docs/GLM/Directive/Clock.md

@@ -50,6 +50,10 @@ clock {
 }
 ~~~
 
+# Caveat
+
+Introducing more than one clock directive in a model is allowed. However, all elements of previous clock directives are reset when a new clock directive is encountered.  As a result, all previous parameters of previous settings are lost after the new directive is processed.
+
 # See also
 
 * [share/tzinfo.txt](https://github.com/slacgismo/gridlabd/blob/master/gldcore/tzinfo.txt)

docs/Module/Tape/Player.md

@@ -69,6 +69,8 @@ class player{
 
 The object properties that will be updated based on value in the player's input file. Property names are case sensitive, and whitespace between properties is verboten. Properties with units may be converted to compatible internal units, if necessary. Complex properties may be written as their individual real and imaginary parts by appending ".real" or ".imag" to the property name, such as "power.real", but those parts cannot convert their units, if the associated complex property has an internal unit specified.
 
+The property object must be omitted when the CSV file contains a header line with the property list.  In this case, looping is not permitted.
+
 ### `file`
 
 ~~~

docs/Utilities/Create_poles.md

@@ -0,0 +1,116 @@
+[[/Utilities/Create_poles]] -- Creates poles and pole mounts for networks
+
+# Synopsis
+
+Shell:
+
+~~~
+bash$ gridlabd create_poles INPUTFILE OPTIONS ...
+~~~
+
+GLM:
+
+~~~
+#python -m create_poles INPUTFILE OPTIONS ...
+~~~
+
+Python
+
+~~~
+>>> import create_poles
+>>> create_poles.main(INPUTFILE,OPTIONS)
+~~~
+
+Output options:
+
+  * `--include_network`                 include the input network in the output GLM file
+  * `--output=GLMNAME`                  set the output GLM file name (default is /dev/stdout)
+  * `--format={GLM,JSON}`               specify the output format (default is GLM)
+
+Pole options:
+
+  * `--ignore_length`                   ignore the line length when computing pole locations
+  * `--ignore_location`                 ignore node latitude/longitude when computer pole locations
+  * `--pole_type=CONFIGURATION_NAME`    set the pole type to use
+  * `--pole_data=POLEDATA_CSV`          use CSV data of pole properties
+
+  * `--mount_data=MOUNTDATA_CSV`        use CSV data for equipment and line mounts
+
+  * `--spacing=FEET`                    set the pole spacing in feet on overhead power lines
+
+Weather options:
+
+  * `--include_weather`                 include automatically downloaded weather for poles
+  * `--location=LAT,LON`                specify the weather location
+  * `--timezone=TZSPEC`                 specify the timezone (overrides default based on location)
+  * `--weather_name=NAME`               use named weather object
+  * `--year=YEAR`                       specify the weather year (default is forecasted)
+
+# Description
+
+The `create_poles` subcommand automatically generates a pole model for a network model and
+mounts the overhead lines and equipment to the newly created poles.  The output is written to
+`/dev/stdout` unless the `--output=GLMNAME` option is given.
+
+The `--pole_type=CONFIGURATION_NAME` and `--spacing=FEET` options are required.  Configuration names
+may be obtained from the `pole_configuration.glm` library (see [[/Subcommand/Library]] for details
+on using libraries.
+
+Some network models include latitude and longitude information.  When this information is present,
+the line length information checked.  If there is a discrepancy between these, a warning is printed
+and the latitude/longitude information is used.  The `--ignore_length` option will suppress this
+warning. The `--ignore_location` warning will cause the model to use the line length data instead.
+
+The `--include_network` adds a `#include "FILENAME"` directive in the output to ensure that the 
+resulting GLM file contains all the objects required to run the simulation, e.g.,
+
+~~~
+$ gridlabd create_poles example.glm --output=model.glm --spacing=100 --pole_type=WOOD-EC-45/4
+$ gridlabd example.glm model.glm
+~~~
+
+Alternative, when the input is a GLM, the two GLM files can be used together in a single command, e.g.,
+
+~~~
+$ gridlabd create_poles example.glm --output=model.glm  --spacing=100 --pole_type=WOOD-EC-45/4 --include_network
+$ gridlabd model.glm
+~~~
+
+The python usage requires the options be provided as a keyword arguments where the leading `--` is
+omitted, e.g., the command `gridlabd create_poles example.glm --output=model.glm  --spacing=100 --pole_type=WOOD-EC-45/4 --include_network` is equivalent to `create_poles.main('example.glm',output='model.glm',spacing=100,pole_type='WOOD-EC-45/4',include_network=True)`
+
+## Default properties
+
+Pole and pole_mount objects are created with the following default properties:
+
+  * pole
+    - install_year: 2000
+    - tilt_angle: 0 deg
+    - tilt_direction: 0 deg
+  * pole_mount
+    height: 40 ft
+    offset: 0 ft
+    area: 0 sf
+    direction: 0 deg
+    weight: 0 lb
+
+The properties may be set at the command line using the option `--TYPE.PROPERTY=VALUE`, e.g. `--pole.install_year=2010`.
+
+## Weather
+
+If `--include_weather` is specified, then the weather forecast data is linked based on location, if any, and the clock is automatically set based on the weather window.  If the `--weather_name` option is provided, all poles created will use the specified weather object instead of using downloaded weather, and the clock will not set.  If the `--year` option is specified, then the historical weather data for that year and location is used, and the clock is set to run the entire year.  Without the `--year` specification, a realtime weather forecast is used, and the clock is set to the forecast window. By default the timezone is determined from the location, unless the `--timezone=TZSPEC` option is used to override it. If `--ignore_location` is specified, then the local system timezone specification is used.
+
+# Caveat
+
+When saving to JSON, only the new pole data is included.  Options that
+change the clock or include networks and weather are ignored.
+
+The `create_poles` subcommand is a python extra command. It is not supported directly using the `#subcommand` macro.  To use python extras as subcommand, use the `#gridlabd` macro instead.
+
+# See also
+
+* [[/Module/Powerflow/Pole]]
+* [[/Module/Powerflow/Pole_mount]]
+* [[/Utilities/Library]]
+* [[/Utilities/Noaa_forecast]]
+* [[/Utilities/Nsrdb_weather]]

docs/Utilities/Noaa_forecast.md

@@ -0,0 +1,115 @@
+[[/Utilities/Noaa_forecast]] -- NOAA weather forecast utility
+
+# Synopsis
+
+Shell:
+
+~~~
+    bash$ gridlabd noaa_forecast -p|-position=LAT,LON [-i|--interpolate=TIME|METHOD]
+        [-g|--glm=GLMNAME] [-n|--name=OBJECTNAME] [-c|--csv=CSVNAME] [--test] [-h|--help|help]
+~~~
+
+GLM:
+
+~~~
+    #python -m noaa_forecast -p|-position=LAT,LON [-i|--interpolate=TIME|METHOD]
+        [-g|--glm=GLMNAME] [-n|--name=OBJECTNAME] [-c|--csv=CSVNAME] [--test] [-h|--help|help]
+    #include "GLMNAME"
+~~~
+
+Python:
+
+~~~
+    bash$ gridlabd python
+    >>> import noaa_forecast as nf
+    >>> ns.getforecast(37.5,-122.3)
+                                   temperature[degF]  wind_speed[m/s]  wind_dir[deg]
+    2021-10-21 14:00:00-07:00          68.000000         4.470400     202.500000
+    2021-10-21 15:00:00-07:00          65.327601         4.275738     201.983153
+    2021-10-21 16:00:00-07:00          62.990829         4.099336     201.673044
+    ...                                      ...              ...            ...
+    2021-10-28 06:00:00-07:00          57.284721         2.770949     315.450517
+    2021-10-28 07:00:00-07:00          55.246212         2.946331     315.403079
+    2021-10-28 08:00:00-07:00          53.000000         3.129280     315.000000
+    [163 rows x 3 columns]
+~~~
+
+# Description
+
+This module downloads weather forecasts from NOAA and writes GLM files.  This can be done from
+the command line or using call the python API.
+
+Interpolation is usually necessary because the data samples received from NOAA span several hours.
+The default interval is 60 minutes, but can be set to any integer value in minutes. The sampling
+method is by default `linear`.  Interpolation methods supported include 
+
+  - `linear`
+
+    Ignore the index and treat the values as equally spaced. This is the only method 
+    supported on MultiIndexes.
+
+  - `time`
+
+    Works on daily and higher resolution data to interpolate given length of interval.
+
+  - `index`, `values`
+
+    Use the actual numerical values of the index.
+
+  - `pad`
+
+    Fill in NaNs using existing values.
+
+  - `nearest`, `zero`, `slinear`, `quadratic`, `cubic`, `spline`, `barycentric`, `polynomial`
+
+    Passed to `scipy.interpolate.interp1d`. These methods use the numerical values of the index. 
+    Both `polynomial` and `spline` require that you also specify an order (`int`), e.g. 
+    `df.interpolate(method='polynomial', order=5)`.
+
+  - `krogh`, `piecewise_polynomial`, `spline`, `pchip`, `akima`, `cubicspline`
+
+    Wrappers around the SciPy interpolation methods of similar names.
+
+  - `from_derivatives`
+
+    Refers to `scipy.interpolate.BPoly.from_derivatives` which replaces `piecewise_polynomial` 
+    interpolation method in scipy 0.18.
+
+## Parameters
+
+The module uses several parameters to control its behavior. 
+
+~~~
+    server = "https://api.weather.gov/points/{latitude},{longitude}" # NOAA location server (provides forecast URL)
+    user_agent = "(gridlabd.us, [email protected])" # default user agent to report to NOAA
+    date_format = "%Y-%m-%d %H:%M:%S"
+    float_format="%.1f" # float format to use 
+    interpolate_time = 60
+    interpolate_method = 'quadratic'
+~~~
+
+The parameters can be changed before obtained the forecast.
+
+~~~
+    >>> import noaa_forecast as nf
+    >>> nf.interpolate = 5
+    >>> nf.getforecast(37.5,-122.3)
+~~~
+
+# Example
+
+The following command downloads only the CSV data for a location:
+
+~~~
+    bash$ gridlabd noaa_forecast -p=45.62,-122.70 -c=test.csv
+~~~
+
+The following command downloads the CSV data and creates a GLM file with the data linked and weather object named:
+
+~~~
+    bash$ gridlabd noaa_forecast -p=45.62,-122.70 -c=test.csv -n=test -g=test.glm
+~~~
+
+# See also
+
+* [https://www.weather.gov/documentation/services-web-api]