Merge pull request #1144 from NREL/develop

FLORIS v4.5

Author: misi9170

README.md

@@ -3,14 +3,24 @@
 FLORIS is a controls-focused wind farm simulation software incorporating
 steady-state engineering wake models into a performance-focused Python
 framework. It has been in active development at NREL since 2013 and the latest
-release is [FLORIS v.4.4.2](https://github.com/NREL/floris/releases/latest).
+release is [FLORIS v.4.5](https://github.com/NREL/floris/releases/latest).
 Online documentation is available at https://nrel.github.io/floris.
 
 The software is in active development and engagement with the development team
 is highly encouraged. If you are interested in using FLORIS to conduct studies
 of a wind farm or extending FLORIS to include your own wake model, please join
 the conversation in [GitHub Discussions](https://github.com/NREL/floris/discussions/)!
 
+## WETO software
+
+FLORIS is primarily developed with the support from the U.S. Department of Energy and
+is part of the `WETO Software Stack <https://nrel.github.io/WETOStack>`_.
+For more information and other integrated modeling software, see:
+
+- [Portfolio Overview](https://nrel.github.io/WETOStack/portfolio_analysis/overview.html)
+- [Entry Guide](https://nrel.github.io/WETOStack/_static/entry_guide/index.html)
+- [Wind Farm Controls Workshop](https://www.youtube.com/watch?v=f-w6whxIBrA&list=PL6ksUtsZI1dwRXeWFCmJT6cEN1xijsHJz)
+
 ## Installation
 
 **If upgrading from a previous version, it is recommended to install FLORIS v4 into a new virtual environment**.
@@ -79,7 +89,7 @@ PACKAGE CONTENTS
     wind_data
 
 VERSION
-    4.4.2
+    4.5
 
 FILE
     ~/floris/floris/__init__.py

docs/_toc.yml

@@ -14,14 +14,17 @@ parts:
     - file: intro_concepts
     - file: wind_data_user
     - file: floris_models
+    - file: input_reference_main
+    - file: turbine_models
+      sections:
+      - file: input_reference_turbine
+      - file: operation_models_user
+      - file: floating_wind_turbine
+      - file: multidimensional_wind_turbine
+      - file: turbine_library
     - file: advanced_concepts
     - file: heterogeneous_map
-    - file: floating_wind_turbine
-    - file: turbine_interaction
-    - file: operation_models_user
     - file: layout_optimization
-    - file: input_reference_main
-    - file: input_reference_turbine
     - file: examples
 
   - caption: Theory and Background

docs/api_docs.md

@@ -1,11 +1,10 @@
 # API Documentation
 
-FLORIS is divided into two primary packages.
-{py:mod}`floris.simulation` is the core code that models the wind turbines
-and wind farms. It is low-level code that generally is not accessed
-by typical users. {py:mod}`floris.tools` is the set of analysis routines
-that define, drive, and post process a simulation. This is where
-more users will interface with the software.
+FLORIS is primarily divided into the {py:mod}`floris` package, which contains the user-level API,
+and {py:mod}`floris.core` is the core code that models the wind turbines and wind farms.
+Additionally, the {py:mod}`turbine_library` package contains turbine models that ship with FLORIS;
+and the {py:mod}`optimization` package contains high-level optimization routines that accept and
+work on instantiated `FlorisModel` objects.
 
 ```{eval-rst}
 .. autosummary::

docs/floating_wind_turbine.md

@@ -3,22 +3,14 @@
 
 The FLORIS wind turbine description includes a definition of the performance curves
 (`power` and `thrust_coefficient`) as a function of wind speed, and this lookup table is used
-directly in
-the calculation of power production for a steady-state atmospheric condition
+directly in the calculation of power production for a steady-state atmospheric condition
 (wind speed and wind direction). The power curve definition typically assumes a
-fixed-bottom wind turbine with no active or controllable tilt. However, floating
-wind turbines have additional rotational degrees of freedom including pitch which
+fixed-bottom wind turbine with a fixed shaft tilt. However, floating
+wind turbines have an additional rotational degrees of freedom in the platform pitch, which
 adds a tilt angle to the rotor. As the turbine tilts, its performance is affected
-similar to a yawed condition. The turbine is no longer operating on its defined
-performance curve, and corrections must be included to accurately predict the power
-production.
+because the turbine is no longer operating on its defined performance curve.
 
-Support for modeling this impact on a floating wind turbine were added in
-[PR#518](https://github.com/NREL/floris/pull/518/files) and allow for correcting the
-user-supplied performance curve for the average tilt. This is accomplished by including
-an additional input, `floating_tilt_table`, in the turbine definition which sets the
-steady tilt angle of the turbine based on wind speed. An interpolation is created and
-the tilt angle is computed for each turbine based on effective velocity. Taking into
-account the turbine rotor's built-in tilt, the absolute tilt change can then be used
-to correct the power and thrust coefficient.
-This tilt angle is then used directly in the selected wake models.
+FLORIS allows the user to correct for the tilt angle of the turbine as a function of wind speed.
+This is accomplished by including an additional input, `floating_tilt_table`, in the turbine definition that sets the steady tilt angle of the turbine based on wind speed. An interpolation is created and the tilt angle is computed for each turbine based on its rotor effective velocity. Taking into account the turbine rotor's built-in tilt, the absolute tilt is used to compute the power and thrust coefficient. To enable the use of the `floating_tilt_table`, the `correct_cp_ct_for_tilt` input on the turbine definition should be set to `True`.
+
+The tilt angle is then used directly in the selected wake models to compute wake effects of tilted turbines.

docs/heterogeneous_map.ipynb

@@ -13,6 +13,16 @@ Support for python version 3.8 was dropped in FLORIS v4.3, and support for pytho
 See {ref}`installation` for details. FLORIS v4.3 also made the move to requiring `numpy` version 2. See the [numpy documentation for details](https://numpy.org/doc/stable/numpy_2_0_migration_guide.html).
 ```
 
+## WETO software
+
+FLORIS is primarily developed with the support from the U.S. Department of Energy and
+is part of the `WETO Software Stack <https://nrel.github.io/WETOStack>`_.
+For more information and other integrated modeling software, see:
+
+- [Portfolio Overview](https://nrel.github.io/WETOStack/portfolio_analysis/overview.html)
+- [Entry Guide](https://nrel.github.io/WETOStack/_static/entry_guide/index.html)
+- [Wind Farm Controls Workshop](https://www.youtube.com/watch?v=f-w6whxIBrA&list=PL6ksUtsZI1dwRXeWFCmJT6cEN1xijsHJz)
+
 ## Quick Start
 
 FLORIS is a Python package run on the command line typically by providing

docs/index.md

@@ -1,6 +1,6 @@
 # Main Input File Reference
 
-In additional to reinitializing {py:class}`FlorisInterface`, users can configure FLORIS
+In addition to calling the `set()` method on {py:class}`FlorisModel`, users can configure FLORIS
 with an input file. The file must be YAML format with either "yaml" or "yml" extension.
 The below definitions guide a user to the top, mid, and lower level parameterizations. A few
 reference input files are available in the

docs/input_reference_main.md

@@ -0,0 +1,129 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "ab10767e",
+   "metadata": {},
+   "source": [
+    "# Multidimensional Wind Turbine\n",
+    "\n",
+    "Many external factors can affect the power and thrust curves of wind turbines. FLORIS supports the\n",
+    "ability to define \"multidimensional\" wind turbines, where the power and thrust curves are defined\n",
+    "as a function of external parameters. To enable this functionality, rather than defining `power`\n",
+    "and `thrust_coefficient` as a function of `wind_speed` on the `power_thrust_table`, users should\n",
+    "instead provide a path to a data file (described below) as `power_thrust_data_file`. Additionally,\n",
+    "users must set the `multi_dimensional_cp_ct` option on the turbine definition to `True`.\n",
+    "\n",
+    "The power thrust data file should be a CSV file with the following columns:\n",
+    "(`<external_parameter_1>`, `<external_parameter_2>`, ..., `ws`, `power`,\n",
+    "`thrust_coefficient`). The external parameters can be any relevant factors that affect the turbine\n",
+    "performance, and the values to be used will be specified at run time or in the FLORIS input file.\n",
+    "For example, the external parameters could be air density, wave height, etc. The `ws` column should\n",
+    "contain the wind speed values for specification of the power and thrust coefficient (stored in the\n",
+    "`power` and `thrust_coefficient` columns, respectively). The wind speed, power, and thrust\n",
+    "coefficient values should be defined for each combination of the external parameters.\n",
+    "\n",
+    "The user can then specify the values of the external parameters either on the FLORIS input file\n",
+    "or using the `multidim_conditions` argument of `FlorisModel.set()`. The power and thrust coefficient\n",
+    "are determined based on the specified conditions using a nearest-neighbor approach.\n",
+    "\n",
+    "The following code snippet shows an example of a multidimensional wind turbine definition and its\n",
+    "corresponding power thrust data file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cc97a774",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "from floris import FlorisModel, TimeSeries\n",
+    "\n",
+    "n_wind_speeds = 100\n",
+    "wind_speeds = np.linspace(0.1, 30, n_wind_speeds)\n",
+    "\n",
+    "fmodel = FlorisModel(\"defaults\") # Defaults to NREL 5MW turbine\n",
+    "fmodel.set(\n",
+    "    wind_data=TimeSeries(\n",
+    "        wind_directions=np.zeros(n_wind_speeds),\n",
+    "        wind_speeds=wind_speeds,\n",
+    "        turbulence_intensities=0.06\n",
+    "    ),\n",
+    "    layout_x=[0],\n",
+    "    layout_y=[0],\n",
+    "    wind_shear=0.0,\n",
+    "    turbine_type=[\"iea_15MW_floating_multi_dim_cp_ct\"],\n",
+    "    reference_wind_height=-1,\n",
+    ")\n",
+    "\n",
+    "# Now, we need to specify what external parameters to run the model for\n",
+    "fmodel.set(multidim_conditions={\"Tp\": 2, \"Hs\": 1})\n",
+    "fmodel.run()\n",
+    "\n",
+    "powers = fmodel.get_turbine_powers()\n",
+    "thrust_coefficients = fmodel.get_turbine_thrust_coefficients()\n",
+    "\n",
+    "fig, ax = plt.subplots(2, 1, sharex=True)\n",
+    "ax[0].plot(wind_speeds, powers, label=\"First condition\")\n",
+    "ax[0].grid()\n",
+    "ax[0].set_ylabel(\"Power [kW]\")\n",
+    "ax[1].plot(wind_speeds, thrust_coefficients)\n",
+    "ax[1].grid()\n",
+    "ax[1].set_ylabel(\"Thrust coefficient [-]\")\n",
+    "ax[1].set_xlabel(\"Wind speed [m/s]\")\n",
+    "ax[1].set_xlim([0, 30])\n",
+    "\n",
+    "# Set a second multidimensional condition and rerun\n",
+    "fmodel.set(multidim_conditions={\"Tp\": 4, \"Hs\": 5})\n",
+    "fmodel.run()\n",
+    "\n",
+    "powers = fmodel.get_turbine_powers()\n",
+    "thrust_coefficients = fmodel.get_turbine_thrust_coefficients()\n",
+    "ax[0].plot(wind_speeds, powers, label=\"Second condition\")\n",
+    "ax[0].legend(loc=\"upper left\")\n",
+    "ax[1].plot(wind_speeds, thrust_coefficients)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "98fd51f6",
+   "metadata": {},
+   "source": [
+    "Note that this example is not meant to be represntative of a real turbine, but rather to illustrate\n",
+    "the functionality. At this time, FLORIS only support a single external condition combination at a\n",
+    "time, but multiple combinations can be run sequentially as is shown above."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8c21f432",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "floris",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/multidimensional_wind_turbine.ipynb

@@ -141,10 +141,14 @@
     "The `\"cosine-loss\"` operation model describes the decrease in power and thrust produced by a \n",
     "wind turbine as it yaws (or tilts) away from the incoming wind. The thrust is reduced by a factor of \n",
     "$\\cos \\gamma$, where $\\gamma$ is the yaw misalignment angle, while the power is reduced by a factor \n",
-    "of $(\\cos\\gamma)^{p_P}$, where $p_P$ is the cosine loss exponent, specified by `cosine_loss_exponent_yaw`\n",
-    "(or `cosine_loss_exponent_tilt` for tilt angles). The power and thrust produced by the turbine\n",
+    "of $(\\cos\\gamma)^{p_P}$, where $p_P$ is the cosine loss exponent, specified by `cosine_loss_exponent_yaw`.\n",
+    "Similarly, the thrust and power are reduced by factors of $(\\cos \\theta / \\cos \\theta_{ref})$ and\n",
+    "$(\\cos \\theta / \\cos \\theta_{ref})^{p_T}$, respectively, where $\\theta$ is the tilt angle, \n",
+    "$\\theta_{ref}$ is the reference tilt angle under which the power and thrust curves are specified, and\n",
+    "$p_T$ is the cosine loss exponent for tilt, specified by `cosine_loss_exponent_tilt`.\n",
+    "The power and thrust produced by the turbine\n",
     "thus vary as a function of the turbine's yaw angle, set using the `yaw_angles` argument to \n",
-    "`FlorisModel.set()`."
+    "`FlorisModel.set()`, and tilt angle (if applicable, for example for floating wind turbines)."
    ]
   },
   {

docs/operation_models_user.ipynb

@@ -334,3 +334,30 @@ @article{HeckJohlasHowland2023_yawed_adm
 title = {Modelling the induction, thrust and power of a yaw-misaligned actuator disk},
 journal = {Journal of Fluid Mechanics},
 }
+
+@techreport{jonkman_NREL5MW_2009,
+	title = {Definition of a 5-{MW} Reference Wind Turbine for Offshore System Development},
+  institution = {National Renewable Energy Laboratory},
+	url = {http://www.osti.gov/servlets/purl/947422-nhrlni/},
+	number = {NREL/TP-500-38060},
+	author = {Jonkman, J. and Butterfield, S. and Musial, W. and Scott, G.},
+	year = {2009},
+	doi = {10.2172/947422},
+}
+
+@techreport{kainz_IEA10MW_2024,
+	title = {{IEA}-{Wind} 740-{10MW} Reference Offshore Wind Plants},
+  url = {https://research-hub.nrel.gov/en/publications/iea-wind-tcp-task-55-the-iea-wind-740-10-mw-reference-offshore-wi},
+	institution = {International Energy Agency},
+  author = {Kainz, Samuel and Quick, Julian and Souza de Alencar, Mauricio and Sanchez Perez-Moreno, Sebastian and Dykes, Katherine and Bay, Christopher and Zaaijer, Michiel B. and Bortolotti, Pietro},
+  year = {2024},
+}
+
+@techreport{gaertner_IEA15MW_2020,
+	title = {{IEA} {Wind} {TCP} {Task} 37: {Definition} of the {IEA} 15-{Megawatt} Offshore Reference Wind Turbine},
+	url = {https://research-hub.nrel.gov/en/publications/iea-wind-tcp-task-37-definition-of-the-iea-15-megawatt-offshore-r},
+	number = {NREL/TP-5000-75698},
+	institution = {International Energy Agency},
+	author = {Gaertner, Evan and Sethuraman, Latha and Anderson, Benjamin and Barter, Garrett and Abbas, Nikhar and Bortolotti, Pietro and Scott, George and Feil, Roland and Shields, Matthew and Rinker, Jennifer and Zahle, Frederik and Meng, Fanzhong and Skrzypinski, Witold and Bredmose, Henrik and Dykes, Katherine and Allen, Christopher and Viselli, Anthony},
+	year = {2020},
+}