Merge branch 'dev_geospatial_templates' into dev_geospatialtesting

NREL · Aug 1, 2024 · bc0d354 · bc0d354
2 parents e14c239 + 0dc5089
commit bc0d354
Show file tree

Hide file tree

Showing 33 changed files with 6,119 additions and 85 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -20,6 +20,7 @@ Please delete options that are not relevant.
 - [ ] I have performed a self-review of my code
 - [ ] Code changes are covered by tests.
 - [ ] Code changes have been evaluated for compatibility/integration with Scenario analysis (for future PRs)
+- [ ] Code changes have been evaluated for compatibility/integration with geospatial autotemplating (for future PRs)
 - [ ] New functions added to __init__.py
 - [ ] API.rst is up to date, along with other sphinx docs pages
 - [ ] Example notebooks are rerun and differences in results scrutinized

diff --git a/docs/source/_autosummary/pvdeg.geospatial.analysis.rst b/docs/source/_autosummary/pvdeg.geospatial.analysis.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.analysis
+=========================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: analysis
diff --git a/docs/source/_autosummary/pvdeg.geospatial.auto_template.rst b/docs/source/_autosummary/pvdeg.geospatial.auto_template.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.auto\_template
+===============================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: auto_template
diff --git a/docs/source/_autosummary/pvdeg.geospatial.calc_block.rst b/docs/source/_autosummary/pvdeg.geospatial.calc_block.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.calc\_block
+============================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: calc_block
diff --git a/docs/source/_autosummary/pvdeg.geospatial.calc_gid.rst b/docs/source/_autosummary/pvdeg.geospatial.calc_gid.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.calc\_gid
+==========================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: calc_gid
diff --git a/docs/source/_autosummary/pvdeg.geospatial.output_template.rst b/docs/source/_autosummary/pvdeg.geospatial.output_template.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.output\_template
+=================================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: output_template
diff --git a/docs/source/_autosummary/pvdeg.geospatial.plot_Europe.rst b/docs/source/_autosummary/pvdeg.geospatial.plot_Europe.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.plot\_Europe
+=============================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: plot_Europe
diff --git a/docs/source/_autosummary/pvdeg.geospatial.plot_USA.rst b/docs/source/_autosummary/pvdeg.geospatial.plot_USA.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.plot\_USA
+==========================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: plot_USA
diff --git a/docs/source/_autosummary/pvdeg.geospatial.rst b/docs/source/_autosummary/pvdeg.geospatial.rst
@@ -0,0 +1,125 @@
+.. Please when editing this file make sure to keep it matching the
+   docs in ../configuration.rst:reference_to_examples
+
+pvdeg.geospatial
+================
+
+.. automodule:: pvdeg.geospatial
+
+   .. this is crazy  
+
+   
+   
+
+   Function Overview
+   -----------------
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+
+
+      pvdeg.geospatial.analysis
+      pvdeg.geospatial.auto_template
+      pvdeg.geospatial.calc_block
+      pvdeg.geospatial.calc_gid
+      pvdeg.geospatial.output_template
+      pvdeg.geospatial.plot_Europe
+      pvdeg.geospatial.plot_USA
+      pvdeg.geospatial.start_dask
+      pvdeg.geospatial.template_parameters
+      pvdeg.geospatial.zero_template
+
+
+
+
+   .. this is crazy  
+
+   
+   
+
+.. 
+   Functions
+   ---------
+
+
+
+   .. autofunction:: analysis
+
+   .. _sphx_glr_backref_pvdeg.geospatial.analysis:
+
+   .. minigallery:: pvdeg.geospatial.analysis
+       :add-heading:
+
+   .. autofunction:: auto_template
+
+   .. _sphx_glr_backref_pvdeg.geospatial.auto_template:
+
+   .. minigallery:: pvdeg.geospatial.auto_template
+       :add-heading:
+
+   .. autofunction:: calc_block
+
+   .. _sphx_glr_backref_pvdeg.geospatial.calc_block:
+
+   .. minigallery:: pvdeg.geospatial.calc_block
+       :add-heading:
+
+   .. autofunction:: calc_gid
+
+   .. _sphx_glr_backref_pvdeg.geospatial.calc_gid:
+
+   .. minigallery:: pvdeg.geospatial.calc_gid
+       :add-heading:
+
+   .. autofunction:: output_template
+
+   .. _sphx_glr_backref_pvdeg.geospatial.output_template:
+
+   .. minigallery:: pvdeg.geospatial.output_template
+       :add-heading:
+
+   .. autofunction:: plot_Europe
+
+   .. _sphx_glr_backref_pvdeg.geospatial.plot_Europe:
+
+   .. minigallery:: pvdeg.geospatial.plot_Europe
+       :add-heading:
+
+   .. autofunction:: plot_USA
+
+   .. _sphx_glr_backref_pvdeg.geospatial.plot_USA:
+
+   .. minigallery:: pvdeg.geospatial.plot_USA
+       :add-heading:
+
+   .. autofunction:: start_dask
+
+   .. _sphx_glr_backref_pvdeg.geospatial.start_dask:
+
+   .. minigallery:: pvdeg.geospatial.start_dask
+       :add-heading:
+
+   .. autofunction:: template_parameters
+
+   .. _sphx_glr_backref_pvdeg.geospatial.template_parameters:
+
+   .. minigallery:: pvdeg.geospatial.template_parameters
+       :add-heading:
+
+   .. autofunction:: zero_template
+
+   .. _sphx_glr_backref_pvdeg.geospatial.zero_template:
+
+   .. minigallery:: pvdeg.geospatial.zero_template
+       :add-heading:
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/source/_autosummary/pvdeg.geospatial.start_dask.rst b/docs/source/_autosummary/pvdeg.geospatial.start_dask.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.start\_dask
+============================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: start_dask
diff --git a/docs/source/_autosummary/pvdeg.geospatial.template_parameters.rst b/docs/source/_autosummary/pvdeg.geospatial.template_parameters.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.template\_parameters
+=====================================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: template_parameters
diff --git a/docs/source/_autosummary/pvdeg.geospatial.zero_template.rst b/docs/source/_autosummary/pvdeg.geospatial.zero_template.rst
@@ -0,0 +1,6 @@
+pvdeg.geospatial.zero\_template
+===============================
+
+.. currentmodule:: pvdeg.geospatial
+
+.. autofunction:: zero_template
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -22,6 +22,7 @@ Modules, methods, classes and attributes are explained here.
     humidity
     letid
     montecarlo
+    geospatial
     spectral
     standards
     temperature

diff --git a/docs/source/user_guide/geospatial-templates.rst b/docs/source/user_guide/geospatial-templates.rst
@@ -0,0 +1,40 @@
+.. _geospatial-templates:
+
+Geospatial Analysis
+===================
+Using 3 dimensional labeled arrays (`Xarray`) we are able to run calculations using meteorological data across many points at once. This process has been parallelized using `dask` and `xarray`. Both of these packages can be run locally or on cloud HPC environments. 
+
+This presents a new issue, our models produce outputs in many different shapes and sizes. We can have single numerical results, multiple numeric results or a timeseries of numeric results at each location. To parallelize this process, we cannot wait until runtime to know what shape to store the outputs in. This is where the need for `templates` arises.
+
+Previously, ``pvdeg.geospatial`` provided minimal templates and forced users to create their own for each function they wanted to use in a geospatial calculation.
+
+Auto-templating: allows users to skip creating templates for most functions within pvdeg by using ``pvdeg.geospatial.autotemplate`` to generate templates on the spot, instead of figuring out the output shape. For any given function within the source code decorated with `geospatial_result_type`, we can use `pvdeg.geospatial.autotemplate`
+
+
+Example
+--------
+
+Here we are providing a function to autotemplate along with an ``Xarray.Dataset`` of weather data. Combining these two will give us enough information to produce an output template.
+
+Autotemplate approach to creating a template
+
+.. code-block:: Python
+
+    edge_seal_template = pvdeg.geospatial.auto_template(
+        func=pvdeg.design.edge_seal_width,
+        ds_gids=geo_weather
+    )
+
+Manual Approach to Creating the Sample Template
+
+.. code-block:: Python
+
+    shapes = {
+        "width" : ("gid",) # one return value at each datapoint, only dependent on datapoint, not time
+    }
+
+    template = pvdeg.geospatial.output_template(
+        ds_gids=geo_weather, # xarray dataset 
+        shapes=shapes, # output shapes
+    )
+
diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst
@@ -10,6 +10,7 @@ User Guide
    package_overview
    NSRDB_API_Key
    montecarlo
+   geospatial-templates
    pv-variables-terms
    contributing
 

diff --git a/docs/source/user_guide/montecarlo.rst b/docs/source/user_guide/montecarlo.rst
@@ -21,12 +21,12 @@ If your variables are correlated form a list of correlations using pvdeg.monteca
 Defining Mean and Standard Deviation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Each variable passed to a Corr object in string form must have its own dictionary entry containing its mean and standard deviation in the following form.
-```
-my_dict = {
-<var_1> : {'mean' : <float>, 'stdev' : <float>}
-}
-```
-*why are there extra backticks this is upsetting*
+
+.. code-block:: Python
+
+    my_dict = {
+    <var_1> : {'mean' : <float>, 'stdev' : <float>}
+    }
 
 Generating Correlated Samples
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -39,13 +39,13 @@ Generating Uncorrelated Samples
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To create uncorrelated samples the ``corr`` parameter of ``pvdeg.montecarlo.generateCorrelatedSamples()`` provided with an empty list, while still providing the other arguments. like the following.  
 
-```
+.. code-block:: Python
+
     pvdeg.montecarlo.generateCorrelatedSamples(
         corr = [], 
         ...
         ...
     )
-```
 
 3rd Party Samples/Data
 ^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/source/whatsnew/index.rst b/docs/source/whatsnew/index.rst
@@ -4,7 +4,10 @@ What's New
 ==========
 PVDegradationTools (pvdeg) change log:
 
+
+.. include:: releases/v0.4.0.rst
 .. include:: releases/v0.3.5.rst
+.. include:: releases/v0.3.4.rst
 .. include:: releases/v0.3.3.rst
 .. include:: releases/v0.3.2.rst
 .. include:: releases/v0.3.1.rst

diff --git a/docs/source/whatsnew/releases/v0.3.3.rst b/docs/source/whatsnew/releases/v0.3.3.rst
@@ -1,4 +1,4 @@
-v0.3.1 (2024-05-06)
+v0.3.3 (2024-05-06)
 =======================
 
 Bug Fixes

diff --git a/docs/source/whatsnew/releases/v0.3.4.rst b/docs/source/whatsnew/releases/v0.3.4.rst
@@ -0,0 +1,11 @@
+v0.3.4 (2024-07-26)
+=======================
+
+Bug Fixes
+---------
+* Fix incorrect keyword arguments in `pvdeg.standards.T98_estimate`
+
+Contributors
+~~~~~~~~~~~~
+* Tobin Ford (:ghuser:`tobin-ford`)
+
diff --git a/docs/source/whatsnew/releases/v0.3.5.rst b/docs/source/whatsnew/releases/v0.3.5.rst
@@ -7,5 +7,5 @@ Enhancements
 
 Contributors
 ~~~~~~~~~~~~
-* Martin Springer (:ghuser:`tobin-ford`)
+* Tobin Ford (:ghuser:`tobin-ford`)
 
diff --git a/docs/source/whatsnew/releases/v0.4.0.rst b/docs/source/whatsnew/releases/v0.4.0.rst
@@ -0,0 +1,21 @@
+v0.4.0 (2024-07-29)
+=======================
+
+Enhancements
+---------
+* Autotemplating system for geospatial analysis using `pvdeg.geospatial.autotemplate`
+* New module `pvdeg.decorators` that contains `pvdeg` specific decorator functions.
+* Implemented `geospatial_result_type` decorator to update functions and preform runtime introspection to determine if a function is autotemplate-able. 
+* `Geospatial Templates.ipynb` notebook to showcase new and old templating functionality for users.
+
+Bug Fixes
+---------
+* Added type hinting to many `pvdeg` functions
+* Replaced deprecated numba `jit(nopython=True)` calls with `njit`
+* Fixed whatsnew `v0.3.5` author
+
+Contributors
+~~~~~~~~~~~~
+* Tobin Ford (:ghuser:`tobin-ford`)
+
+