Merge pull request #318 from NatLabRockies/develop

Release 3.2

Author: RHammond2

.pre-commit-config.yaml

@@ -1,4 +1,12 @@
 repos:
+  - repo: https://github.com/psf/black
+    rev: 26.1.0
+    hooks:
+        - id: black
+          name: black
+          stages: [pre-commit]
+          language_version: python3
+
   - repo: https://github.com/pycqa/isort
     rev: 7.0.0
     hooks:
@@ -20,14 +28,6 @@ repos:
     - id: pyupgrade
       args: [--py38-plus]
 
-  - repo: https://github.com/psf/black
-    rev: 26.1.0
-    hooks:
-        - id: black
-          name: black
-          stages: [pre-commit]
-          language_version: python3
-
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:

CHANGELOG.md

@@ -1,6 +1,36 @@
 # Changelog
 All notable changes to this project will be documented in this file. If you make a notable change to the project, please add a line describing the change to the "unreleased" section. The maintainers will make an effort to keep the [Github Releases](https://github.com/NREL/OpenOA/releases) page up to date with this changelog. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## v3.2 - 2026-01-29
+
+- Features and updates:
+  - `WakeLosses` updates
+    - Option added to the `WakeLosses` analysis method to correct for freestream wind speed
+      heterogeneity across a wind plant when estimating internal wake losses. The method relies on
+      a user-provided freestream wind speedup csv file. The wake loss example notebook has been
+      updated to illustrate how to use this option.
+    - `WakeLosses` analysis method updated to flag and exclude unrealistic turbine wind speed
+      measurements
+  - `MonteCarloAEP` updates
+    - Add an `n_jobs` input to the Monte Carlo AEP method to allow for the underlying models to be
+      parallelized during each iteration for faster ML model computation.
+    - Add an `apply_iav` input to the Monte Carlo AEP analysis method to toggle the addition of the
+      IAV factor at the end of the analysis.
+    - Add a `progress_bar` flag to `MonteCarloAEP.run()` to allow for turing on or off the
+      simulation's default progress bar.
+  - Option added to the IEC power curve model in the `openoa/utils/power_curve/functions` module to
+    linearly interpolate power between wind speed bin centers
+  - Implement missing `compute_wind_speed` in `openoa/utils/met_data_processing.py` and apply it to
+    the `PlantData` reanalysis validation steps in place of the manual calculation.
+  - Functions for downloading hourly ERA5 and MERRA-2 reanalysis data added to the
+    `openoa/utils/downloader` module.
+- Fixes:
+  - Add a default value for `PlantData`'s `asset_distance_matrix` and `asset_direction_matrix` to
+    ensure projects not utilizing location data are compatible.
+  - Fix miscellaneous pandas warnings.
+  - Rerun pre-commit and update code styling for adherence to 3.10+ standards.
+  - Replace mutable default arguments with None and handle Nones internally.
+
 ## v3.1.4 - 2026-01-29
 
 - During the custom test collection, convert the `Path` objects to `str` to avoid issues with the

README.md

@@ -65,8 +65,8 @@ OpenOA is primarily developed with the support of the U.S. Department of Energy
 | `TurbineLongTermGrossEnergy`| This routine estimates the long-term turbine ideal energy (TIE) of a wind plant, defined as the long-term AEP that would be generated by the wind plant if all turbines operated normally (i.e., no downtime, derating, or severe underperformance, but still subject to wake losses and moderate performance losses), along with the uncertainty. | [^5] |
 | `ElectricalLosses`| The ElectricalLosses routine estimates the average electrical losses at a wind plant, along with the uncertainty, by comparing the energy produced at the wind turbines to the energy delivered to the grid. | [^5] |
 | `EYAGapAnalysis`| This class is used to perform a gap analysis between the estimated AEP from a pre-construction energy yield estimate (EYA) and the actual AEP. The gap analysis compares different wind plant performance categories to help understand the sources of differences between EYA AEP estimates and actual AEP, specifically availability losses, electrical losses, and TIE. | [^5] |
-| `WakeLosses`| This routine estimates long-term internal wake losses experienced by a wind plant and for each individual turbine, along with the uncertainty. | [^6]. Based in part on approaches in [^7], [^8], [^9] |
-| `StaticYawMisalignment`| The StaticYawMisalignment routine estimates the static yaw misalignment for individual wind turbines as a function of wind speed by comparing the estimated wind vane angle at which power is maximized to the mean wind vane angle at which the turbines operate. The routine includes uncertainty quantification. **Warning: This method has not been validated using data from wind turbines with known static yaw misalignments and the results should be treated with caution.** | Based in part on approaches in [^10], [^11], [^12], [^13], [^14] |
+| `WakeLosses`| This routine estimates long-term internal wake losses experienced by a wind plant and for each individual turbine, along with the uncertainty. | [^6]. Based in part on approaches in [^7], [^8], [^9], [^10] |
+| `StaticYawMisalignment`| The StaticYawMisalignment routine estimates the static yaw misalignment for individual wind turbines as a function of wind speed by comparing the estimated wind vane angle at which power is maximized to the mean wind vane angle at which the turbines operate. The routine includes uncertainty quantification. **Warning: This method has not been validated using data from wind turbines with known static yaw misalignments and the results should be treated with caution.** | Based in part on approaches in [^11], [^12], [^13], [^14], [^15] |
 
 ### PlantData Schema
 
@@ -122,7 +122,7 @@ effort more broadly,** please use citation [^1], which is provided below in BibT
 
 ### Requirements
 
-- Python 3.8-3.11 with pip.
+- Python 3.9-3.12 with pip.
 
 We strongly recommend using the Anaconda Python distribution and creating a new conda environment
 for OpenOA. You can download Anaconda through
@@ -174,10 +174,6 @@ is also allowed).
 - `nrel-wind`: for accessing the NREL WIND Toolkit
 - `all`: for the complete dependency stack
 
-> **Important**
-> If using Python 3.11, install `openoa` only, then reinstall adding the modifiers to reduce
-> the amount of time it takes for pip to resolve the dependency stack.
-
 #### Common Installation Issues
 
 - In Windows, you may get an error regarding geos_c.dll. To fix this, install Shapely using:
@@ -342,20 +338,22 @@ This project follows the [all-contributors](https://github.com/all-contributors/
 
 [^5]: Todd, A. C., Optis, M., Bodini, N., Fields, M. J., Lee, J. C. Y., Simley, E., and Hammond, R. An independent analysis of bias sources and variability in wind plant pre‐construction energy yield estimation methods. *Wind Energy*, 25(10):1775-1790 (2022). https://doi.org/10.1002/we.2768.
 
-[^6]: Simley, E., Fields, M. J., Perr-Sauer, J., Hammond, R., and Bodini, N. A Comparison of Preconstruction and Operational Wake Loss Estimates for Land-Based Wind Plants. Presented at the NAWEA/WindTech 2022 Conference, Newark, DE, September 20-22 (2022). https://www.nrel.gov/docs/fy23osti/83874.pdf.
+[^6]: Simley, E., Fields, M. J., Young, E., Allen, J., Hammond, R., Perr-Sauer, J., and Bodini, N. A comparison of preconstruction and operational wake loss estimates for land-based wind plants. *Wind Energy*, 28(11) (2025). https://doi.org/10.1002/we.70067.
 
 [^7]: Barthelmie, R. J. and Jensen, L. E. Evaluation of wind farm efficiency and wind turbine wakes at the Nysted offshore wind farm, *Wind Energy* 13(6):573–586 (2010). https://doi.org/10.1002/we.408.
 
 [^8]: Nygaard, N. G. Systematic quantification of wake model uncertainty. Proc. EWEA Offshore, Copenhagen, Denmark, March 10-12 (2015).
 
 [^9]: Walker, K., Adams, N., Gribben, B., Gellatly, B., Nygaard, N. G., Henderson, A., Marchante Jimémez, M., Schmidt, S. R., Rodriguez Ruiz, J., Paredes, D., Harrington, G., Connell, N., Peronne, O., Cordoba, M., Housley, P., Cussons, R., Håkansson, M., Knauer, A., and Maguire, E.: An evaluation of the predictive accuracy of wake effects models for offshore wind farms. *Wind Energy* 19(5):979–996 (2016). https://doi.org/10.1002/we.1871.
 
-[^10]: Bao, Y., Yang, Q., Fu, L., Chen, Q., Cheng, C., and Sun, Y. Identification of Yaw Error Inherent Misalignment for Wind Turbine Based on SCADA Data: A Data Mining Approach. Proc. 12th Asian Control Conference (ASCC), Kitakyushu, Japan, June 9-12 (2019). 1095-1100.
+[^10]: Kassebaum, J. Wake Validation Through SCADA Data Analysis. Proc. American Clean Power Resource & Project Energy Assessment Virtual Summit 2021 (2021).
+
+[^11]: Bao, Y., Yang, Q., Fu, L., Chen, Q., Cheng, C., and Sun, Y. Identification of Yaw Error Inherent Misalignment for Wind Turbine Based on SCADA Data: A Data Mining Approach. Proc. 12th Asian Control Conference (ASCC), Kitakyushu, Japan, June 9-12 (2019). 1095-1100.
 
-[^11]: Xue, J. and Wang, L. Online data-driven approach of yaw error estimation and correction of horizontal axis wind turbine. *IET J. Eng.* 2019(18):4937–4940 (2019). https://doi.org/10.1049/joe.2018.9293.
+[^12]: Xue, J. and Wang, L. Online data-driven approach of yaw error estimation and correction of horizontal axis wind turbine. *IET J. Eng.* 2019(18):4937–4940 (2019). https://doi.org/10.1049/joe.2018.9293.
 
-[^12]: Astolfi, D., Castellani, F., and Terzi, L. An Operation Data-Based Method for the Diagnosis of Zero-Point Shift of Wind Turbines Yaw Angle. *J. Solar Energy Engineering* 142(2):024501 (2020). https://doi.org/10.1115/1.4045081.
+[^13]: Astolfi, D., Castellani, F., and Terzi, L. An Operation Data-Based Method for the Diagnosis of Zero-Point Shift of Wind Turbines Yaw Angle. *J. Solar Energy Engineering* 142(2):024501 (2020). https://doi.org/10.1115/1.4045081.
 
-[^13]: Jing, B., Qian, Z., Pei, Y., Zhang, L., and Yang, T. Improving wind turbine efficiency through detection and calibration of yaw misalignment. *Renewable Energy* 160:1217-1227 (2020). https://doi.org/10.1016/j.renene.2020.07.063.
+[^14]: Jing, B., Qian, Z., Pei, Y., Zhang, L., and Yang, T. Improving wind turbine efficiency through detection and calibration of yaw misalignment. *Renewable Energy* 160:1217-1227 (2020). https://doi.org/10.1016/j.renene.2020.07.063.
 
-[^14]: Gao, L. and Hong, J. Data-driven yaw misalignment correction for utility-scale wind turbines. *J. Renewable Sustainable Energy* 13(6):063302 (2021). https://doi.org/10.1063/5.0056671.
+[^15]: Gao, L. and Hong, J. Data-driven yaw misalignment correction for utility-scale wind turbines. *J. Renewable Sustainable Energy* 13(6):063302 (2021). https://doi.org/10.1063/5.0056671.

examples/00_intro_to_plant_data.ipynb

@@ -1006,7 +1006,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.11.8"
+      "version": "3.13.11"
     },
     "toc": {
       "base_numbering": 1,

examples/01_utils_examples.ipynb

@@ -949,7 +949,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.11.8"
+      "version": "3.13.11"
     },
     "toc": {
       "base_numbering": 1,

examples/02a_plant_aep_analysis.ipynb

@@ -1176,7 +1176,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.11.8"
+      "version": "3.13.11"
     },
     "toc": {
       "base_numbering": 1,

examples/02b_plant_aep_analysis_cubico.ipynb

@@ -760,7 +760,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.11.8"
+      "version": "3.13.11"
     },
     "toc": {
       "base_numbering": 1,