ZackTully · ZackTully · Apr 24, 2025 · Jan 24, 2025 · Mar 21, 2025 · Mar 21, 2025
diff --git a/.github/workflows/gh_pages.yml b/.github/workflows/gh_pages.yml
@@ -42,11 +42,11 @@ jobs:
 
     # Upload the book's HTML as an artifact
     - name: Upload artifact
-      uses: actions/upload-pages-artifact@v2
+      uses: actions/upload-pages-artifact@v3
       with:
-        path: "_build/html"
+        path: "docs/_build/html"
 
     # Deploy the book's HTML to GitHub Pages
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v2
+      uses: actions/deploy-pages@v4
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -4,6 +4,9 @@
 
 # Required
 version: 2
+sphinx:
+  # Path to your Sphinx configuration file.
+  configuration: docs/conf.py
 
 # Set the version of Python and other tools you might need
 build:

diff --git a/README.md b/README.md
@@ -6,12 +6,12 @@
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
 As part of NREL's [Hybrid Energy Systems Research](https://www.nrel.gov/wind/hybrid-energy-systems-research.html), this
-software assesses optimal designs for the deployment of utility-scale hybrid energy plants, particularly considering wind,
+software assesses optimal designs for the deployment of distributed, commercial, and utility-scale hybrid energy plants, particularly considering wind,
 solar and storage.
 
 ## Software requirements
 
-- Python version 3.10, and 3.11 only (PySAM 4.2 is incompatible with 3.12)
+- Python version 3.10, and 3.11 only
 
 ## Installing from Package Repositories
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -1,5 +1,49 @@
 # Release Notes
 
+## Version 3.2.0, March 21, 2025
+
+* Updates related to PySAM:
+    + Updated PySAM version from 4.2.0 to >6.0.0. Main changes noted in [PR #425](https://github.com/NREL/HOPP/pull/425)
+    + PySAM generation plant defaults have been updated. Current defaults can be found [here](https://github.com/NREL/SAM/tree/develop/api/api_autogen/library/defaults)
+    + PySAM SingleOwner financial model update investment-tax credit and depreciation basis calculations to remove financing fees and reserve account funding from basis.
+    + PySAM MHKWave update marine energy device cost curves.
+    + PySAM Detailed PV update module and inverter libraries, snow module, tracking, losses.
+
+* Wind-focused usability additions that are detailed [here](https://github.com/NREL/HOPP/pull/429#issue-2852391571)
+    + Feature add: new wind layout method called `basicgrid` that makes the most-square layout that has the option to be site-constrained.
+    + Updated wind layout methods to classes
+    + Bug-fix: grid angle converted from degrees to radians in `make_grid_lines()` function in `wind_layout_tools.py`
+    + Updated floris initialization to set attributes from `floris_config`
+    + Update: raise errors when using floris if theres a discrepancy between inputs in `WindConfig` and information in `floris_config` (such as `num_turbines` and the `floris_config` layout, and turbine parameters like rotor diameter and turbine rating.)
+    + Integrated wind layout functionality when using floris
+    + Updated wind layout parameters.
+    + Minor clean up to floris.py - removed unnecessary data exportation and fixed bug in value()
+
+* Integrated [turbine-models library](https://github.com/NREL/turbine-models/tree/master). For further details see [here](https://github.com/NREL/HOPP/pull/435)
+    + Wind turbines from the turbine-models library can now be simulated by specifying the turbine name. This feature is compatible with floris and PySAM WindPower simulations.
+    + Added wind turbine power-curve tools to estimate thrust coefficient, power coefficient, and power-curve.
+* Added two distributed wind-hybrid examples that highlight the turbine-models library package and other recent features for wind system modeling and simulations. These examples are:
+    - `examples/08-distributed-residential-example.ipynb` 
+    - `examples/09-distributed-residential-midsize.ipynb` 
+* Added tidal models
+    + Added TidalResource to load tidal resource data for simulating tidal energy.
+    + Added MHKTidalPlant to simulate tidal energy.
+    + Add tidal energy to HybridSimulation.
+    + Add tidal energy to dispatch.
+
+* Other feature additions:
+    + Added option and functionality to load wind and solar resource data from NSRDB and Wind Toolkit data files if user-specified.
+    + Added ability and option to initialize site_info with preloaded and formatted wind and solar resource data
+    + Feature add: added alternative method to defining site boundary.
+    + Feature add: added function to adjust air density based on site elevation
+    + Added weighted average wind resource parsing method option when using floris.
+    + Update deprecated methods in wave_resource.py 
+
+* Bug fixes:
+    + Remove erroneous 100 multiples for percentages and add clarifying parentheses for correct 100 multiples for percentages.
+    + Fixed a bug in site_info that set resource year to 2012 even if otherwise specified.
+    + Bug fix in load following heuristic method: only using beginning of variable load signals 
+
 ## Version 3.1.1, Dec. 18, 2024
 
 * Enhanced PV plant functionality: added tilting solar panel support, improved system design handling, and refined tilt angle calculations.

diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -14,6 +14,15 @@ parts:
   chapters:
   - file: api/hopp_interface
   - file: api/site_info
+    sections:
+    - file: api/resource/index
+      sections:
+      - file: api/resource/solar_api
+      - file: api/resource/wind_api
+      - file: api/resource/solar_hpc
+      - file: api/resource/wind_hpc
+      - file: api/resource/wave_data
+      - file: api/resource/tidal_data
   - file: api/hybrid_simulation
   - file: api/technology/index
     sections:
@@ -23,6 +32,7 @@ parts:
     - file: api/technology/battery
     - file: api/technology/grid
     - file: api/technology/mhk_wave_plant
+    - file: api/technology/mhk_tidal_plant
   - file: api/dispatch/index
     sections:
     - file: api/dispatch/storage/index
@@ -38,8 +48,11 @@ parts:
       - file: api/dispatch/sources/pv_dispatch
       - file: api/dispatch/sources/wind_dispatch
       - file: api/dispatch/sources/wave_dispatch
+      - file: api/dispatch/sources/tidal_dispatch
       - file: api/dispatch/sources/csp_dispatch
 - caption: Additional Tools
   chapters:
   - file: api/technology/flicker
-  - file: api/cost_calculator
+  - file: api/cost_calculator
+  - file: api/tools/site_shape_tools
+  - file: api/tools/mhk_cost
diff --git a/docs/api/dispatch/sources/index.md b/docs/api/dispatch/sources/index.md
@@ -9,6 +9,7 @@ HOPP includes a variety of power source (technology) dispatch options based on t
   - [Molten Salt Tower Power Plant](dispatch:csp-molten-tower)
   - [Parabolic Trough Plant](dispatch:csp-parabolic-trough)
 - [Wave Plant](dispatch:wave)
+- [Wave Plant](dispatch:tidal)
 
 (dispatch:power-source-dispatch)=
 ## Power Source Dispatch

diff --git a/docs/api/dispatch/sources/tidal_dispatch.md b/docs/api/dispatch/sources/tidal_dispatch.md
@@ -0,0 +1,7 @@
+(dispatch:tidal)=
+# Tidal Dispatch
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.dispatch.power_sources.tidal_dispatch.TidalDispatch
+    :members:
+```
diff --git a/docs/api/resource/index.md b/docs/api/resource/index.md
@@ -0,0 +1,41 @@
+# Resource Data
+
+These are the primary methods for accessing wind and solar resource data.
+
+- [Solar Resource (API)](resource:solar-resource)
+- [Wind Resource (API)](resource:wind-resource)
+- [Solar Resource (NSRDB Dataset on NREL HPC)](resource:nsrdb-data)
+- [Wind Resource (Wind Toolkit Dataset on NREL HPC)](resource:wtk-data)
+- [Wave Resource (Data)](resource:wave-resource)
+- [Tidal Resource (Data)](resource:tidal-resource)
+
+## NREL API Keys
+
+An NREL API key is required to use the functionality for [Solar Resource (API)](resource:solar-resource) and [Wind Resource (API)](resource:wind-resource).
+
+An NREL API key can be obtained from [here](https://developer.nrel.gov/signup/).
+
+Once an API key is obtained, create a file ".env" in the HOPP root directory (/path/to/HOPP/.env) that contains the lines:
+
+```bash
+NREL_API_KEY=key
+NREL_API_EMAIL=your.name@email.com
+```
+
+where `key` is your API key and `your.name@email.com` is the email that was used to get the API key.
+
+## NREL HPC Datasets
+
+To load resource data from datasets hosted on NREL's HPC, HOPP must be installed and run from the NREL HPC. Currently, loading resource data from HPC is only enabled for [wind](resource:wtk-data) and [solar](resource:nsrdb-data) resource.
+
+
+(resource:resource-base)=
+## Resource Base Class
+
+Base class for resource data
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.resource.Resource
+    :members:
+    :exclude-members: copy, plot, _abc_impl
+```
diff --git a/docs/api/resource/solar_api.md b/docs/api/resource/solar_api.md
@@ -0,0 +1,10 @@
+(resource:solar-resource)=
+# Solar Resource (API)
+
+By default, solar resource data is downloaded from the NREL Developer Network hosted National Solar Radiation Database (NSRDB) dataset [Physical Solar Model (PSM) v3.2.2](https://developer.nrel.gov/docs/solar/nsrdb/psm3-2-2-download/). Using this functionality requires an NREL API key.
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.resource.solar_resource.SolarResource
+    :members:
+    :exclude-members: _abc_impl, check_download_dir
+```
diff --git a/docs/api/resource/solar_hpc.md b/docs/api/resource/solar_hpc.md
@@ -0,0 +1,11 @@
+(resource:nsrdb-data)=
+# Solar Resource (NSRDB Dataset on NREL HPC)
+
+If enabled, solar resource data can be loaded from the NREL HPC (Kestrel) hosted National Solar Radiation Database (NSRDB) dataset. This functionality leverages the [NREL REsource eXtraction (rex) tool](https://github.com/NREL/rex). Information on NREL HPC file systems and datasets can be found [here](https://nrel.github.io/HPC/Documentation/Systems/Kestrel/Filesystems/#projectfs).
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.resource.nsrdb_data.HPCSolarData
+    :members:
+    :undoc-members:
+    :exclude-members: _abc_impl, check_download_dir, call_api
+```
diff --git a/docs/api/resource/tidal_data.md b/docs/api/resource/tidal_data.md
@@ -0,0 +1,11 @@
+(resource:tidal-resource)=
+# Tidal Resource
+
+**NOTE: Downloading tidal resource data is not yet enabled** but can still be loaded from existing data files.
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.resource.tidal_resource.TidalResource
+    :members:
+    :undoc-members:
+    :exclude-members: _abc_impl, check_download_dir, call_api
+```
diff --git a/docs/api/resource/wave_data.md b/docs/api/resource/wave_data.md
@@ -0,0 +1,11 @@
+(resource:wave-resource)=
+# Wave Resource
+
+**NOTE: Downloading wave resource data is not yet enabled** but can still be loaded from existing data files.
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.resource.wave_resource.WaveResource
+    :members:
+    :undoc-members:
+    :exclude-members: _abc_impl, check_download_dir, call_api
+```
diff --git a/docs/api/resource/wind_api.md b/docs/api/resource/wind_api.md
@@ -0,0 +1,10 @@
+(resource:wind-resource)=
+# Wind Resource (API)
+
+By default, wind resource data is downloaded from the NREL Developer Network hosted Wind Integration National Dataset (WIND) Toolkit dataset [Wind Toolkit Data - SAM format (srw)](https://developer.nrel.gov/docs/wind/wind-toolkit/wtk-srw-download/). Using this functionality requires an NREL API key.
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.resource.wind_resource.WindResource
+    :members:
+    :exclude-members: _abc_impl, check_download_dir
+```
diff --git a/docs/api/resource/wind_hpc.md b/docs/api/resource/wind_hpc.md
@@ -0,0 +1,11 @@
+(resource:wtk-data)=
+# Wind Resource (Wind Toolkit Dataset on NREL HPC)
+
+If enabled, wind resource data can be loaded from the NREL HPC (Kestrel) hosted Wind Integration National Dataset (WIND) Toolkit dataset. This functionality leverages the [NREL REsource eXtraction (rex) tool](https://github.com/NREL/rex). Information on NREL HPC file systems and datasets can be found [here](https://nrel.github.io/HPC/Documentation/Systems/Kestrel/Filesystems/#projectfs).
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.resource.wind_toolkit_data.HPCWindData
+    :members:
+    :undoc-members: 
+    :exclude-members: _abc_impl, check_download_dir, call_api
+```
diff --git a/docs/api/site_info.rst → docs/api/site_info.md b/docs/api/site_info.rst → docs/api/site_info.md
@@ -1,11 +1,9 @@
-.. _SiteInfo:
-
-
-Hybrid Plant Site Information
-==============================
+# Hybrid Plant Site Information
 
 The purpose of this class is to house all site specific data, e.g., weather data.
 
+```{eval-rst}
 .. autoclass:: hopp.simulation.technologies.sites.SiteInfo
     :members:
-    :undoc-members:
+    :undoc-members:
+```
diff --git a/docs/api/technology/index.md b/docs/api/technology/index.md
@@ -13,6 +13,7 @@ These are the primary technologies that may be configured for a standard HOPP si
   - [Stateless Battery](tech:battery-stateless)
 - [Grid](tech:grid)
 - [Wave Plant](tech:wave)
+- [Tidal Plant](tech:tidal)
 
 (tech:power-source)=
 ## Power Source Base Class

diff --git a/docs/api/technology/mhk_tidal_plant.md b/docs/api/technology/mhk_tidal_plant.md
@@ -0,0 +1,24 @@
+(tech:tidal)=
+# MHK Tidal Plant
+
+MHK Tidal Generator class
+
+## Tidal Plant Model
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.tidal.mhk_tidal_plant.MHKTidalPlant
+    :members:
+    :undoc-members:
+```
+
+## Tidal Plant Configuration
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.tidal.mhk_tidal_plant.MHKTidalConfig
+    :members:
+    :undoc-members:
+```
+
+## Tidal Plant Cost Model
+
+For details on the cost model used in MHK Tidal Plants, refer to the [MHK Cost Model](tools:mhk_costs).
diff --git a/docs/api/technology/mhk_wave_plant.md b/docs/api/technology/mhk_wave_plant.md
@@ -21,16 +21,5 @@ MHK Wave Generator class
 
 ## Wave Plant Cost Model
 
-```{eval-rst}
-.. autoclass:: hopp.simulation.technologies.financial.mhk_cost_model.MHKCosts
-    :members:
-    :undoc-members:
-```
-
-## Wave Plant Cost Model Inputs
+For details on the cost model used in MHK Wave Plants, refer to the [MHK Cost Model](tools:mhk_costs).
 
-```{eval-rst}
-.. autoclass:: hopp.simulation.technologies.financial.mhk_cost_model.MHKCostModelInputs
-    :members:
-    :undoc-members:
-```
diff --git a/docs/api/tools/mhk_cost.md b/docs/api/tools/mhk_cost.md
@@ -0,0 +1,19 @@
+(tools:mhk_costs)=
+# MHK Cost Model
+
+This section documents the cost model for MHK technologies.
+
+## MHK Plant Cost Model
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.financial.mhk_cost_model.MHKCosts
+    :members:
+    :undoc-members:
+```
+
+## MHK Plant Cost Model Inputs
+
+```{eval-rst}
+.. autoclass:: hopp.simulation.technologies.financial.mhk_cost_model.MHKCostModelInputs
+    :members:
+    :undoc-members:
+```
diff --git a/docs/api/tools/site_shape_tools.md b/docs/api/tools/site_shape_tools.md
@@ -0,0 +1,50 @@
+(tools:site_shape)=
+# Site Shape Tools
+
+If the site is defined as user-provided vertices, the vertices are [checked for validity](tools:check_verts).
+
+The site shape can be defined as a variety of default shapes:
+- [Square](tools:square_site)
+- [Circle](tools:circle_site)
+- [Rectangle](tools:rectangle_site)
+- [Hexagon](tools:hexagon_site)
+<!-- 
+```{eval-rst}
+.. automodule:: hopp.simulation.technologies.sites.site_shape_tools
+``` -->
+
+(tools:square_site)=
+## Square Site Boundary
+
+```{eval-rst}
+.. autofunction:: hopp.simulation.technologies.sites.site_shape_tools.make_square
+```
+
+(tools:circle_site)=
+## Circle Site Boundary
+
+```{eval-rst}
+.. autofunction:: hopp.simulation.technologies.sites.site_shape_tools.make_circle
+```
+
+(tools:rectangle_site)=
+## Rectangle Site Boundary
+
+```{eval-rst}
+.. autofunction:: hopp.simulation.technologies.sites.site_shape_tools.make_rectangle
+```
+
+(tools:hexagon_site)=
+## Hexagon Site Boundary
+
+```{eval-rst}
+.. autofunction:: hopp.simulation.technologies.sites.site_shape_tools.make_hexagon
+```
+
+
+(tools:check_verts)=
+## Check Site Vertices
+
+```{eval-rst}
+.. autofunction:: hopp.simulation.technologies.sites.site_shape_tools.check_site_verts
+```