[BUGFIX] Improve handling of multidimensional turbine conditions

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: operation_models_user
+      - file: floating_wind_turbine
+      - file: multidimensional_wind_turbine
+      - file: input_reference_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/input_reference_main.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/multidimensional_wind_turbine.ipynb

@@ -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/references.bib

@@ -334,3 +334,29 @@ @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},
+}
+
+@article{kainz_IEA10MW_2024,
+	title = {{IEA}-{Wind} 740-{10MW} Reference Offshore Wind Plants},
+	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 = {2004},
+  institution = {International Energy Agency},
+}
+
+@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},
+}

docs/turbine_library.md

@@ -0,0 +1,57 @@
+
+# Turbine Library
+
+FLORIS includes a library of predefined wind turbine models that can be used to quickly set up
+simulations without needing to define the turbine characteristics manually. These include standard
+reference wind turbines as well as fictional wind turbine models for the purpose of demonstrating
+various features of FLORIS. These turbines are stored in the `floris.turbine_library` module.
+
+## NREL 5MW reference wind turbine
+
+FLORIS representation of the NREL 5MW reference wind turbine {cite:t}`jonkman_NREL5MW_2009`. Data
+based on https://github.com/NREL/turbine-models/blob/master/Offshore/NREL_5MW_126_RWT_corrected.csv.
+Specified as `"nrel_5MW"` in the `turbine_type` field of the FLORIS input dictionary.
+
+The NREL 5MW turbine is the default turbine model used in most FLORIS examples and tutorials. It is
+also the model used if FLORIS is instantiated in the defaults configuration using
+`FlorisModel("defaults")`.
+
+
+## IEA 15MW reference wind turbine
+
+FLORIS representation of the IEA 15MW reference wind turbine {cite:t}`gaertner_IEA15MW_2020`. Data
+based on https://github.com/IEAWindTask37/IEA-15-240-RWT/blob/master/Documentation/IEA-15-240-RWT_tabular.xlsx.
+Specified as `"iea_15MW"` in the `turbine_type` field of the FLORIS input dictionary.
+
+The IEA 15MW turbine is used in the following examples:
+- examples/examples_control_types/004_helix_active_wake_mixing.py
+
+## IEA 10MW reference wind turbine
+
+FLORIS representation of the IEA 10MW reference wind turbine {cite:t}`kainz_IEA10MW_2024`. Data
+based on https://github.com/NREL/turbine-models/blob/master/Offshore/IEA_10MW_198_RWT.csv.
+Specified as `"iea_10MW"` in the `turbine_type` field of the FLORIS input dictionary.
+
+The IEA 10MW turbine is used in the following examples:
+- examples/examples_turbine/002_multiple_turbine_types.py
+
+## IEA 15MW multidimensional
+
+Fictional IEA 15MW turbine model used to demonstrate the use of multidimensional power and thrust
+coefficient data. Reads in fictional multidimensional data describing the power and thrust coefficient
+relationships on wave period `Tp` and wave height `Hs` from `iea_15MW_multi_dim_Tp_Hs.csv` in the
+`turbine_library` folder. Specified as `"iea_15MW_multi_dim"` in the `turbine_type` field of the FLORIS
+input dictionary. This data should be treated as fictional and for demonstrative purposes only.
+
+This fictional turbine model is not currently used in examples.
+
+## IEA 15MW floating, multidimensional
+
+The same as the multidimensional IEA 15MW turbine model above, but with an additional fictional
+floating platform tilt table. This model is used to demonstrate the floating wind turbine capabilities
+in FLORIS. Specified as `"iea_15MW_floating_multi_dim"` in the `turbine_type` field of the FLORIS input
+dictionary. This data should be treated as fictional and for demonstrative purposes only.
+
+This fictional turbine model is used in the following examples:
+- examples/examples_multidim/001_multi_dimensional_cp_ct.py
+- examples/examples_multidim/002_multi_dimensional_cp_ct_2Hs.py