Allow multidim_conditions to be specified across multiple findices (#1152)

* Working prototype for thrust

* Add handling for power, axial_induction

* Update examples to (optionally) remove looping

* Add multidim_conditions handling to TimeSeries and FlorisModel

* Add placeholders to WindRose

* Add tests for wind data objects (WindRose currently fails

* Check WRG and output WindRose have no multidim_conditions

* FlorisModel integration of multiple conditions

* Tests and code for ParFlorisModel

* support new changes to multdim throuth UncFLORISmodel

* Add utility for checking if dict all scalars

* Tests for wind_ti_rose (may need work)

* wind rose updates to meet tests

* Return None if not defined

* Pass through scalar multidim_conditions to improve performance

* Use is_all_scalar_dict in ParFlorisModel

* Explain new usage of multidim_conditions in script docstrings

* Update mutlidim docs

---------

Co-authored-by: paulf81 <paul.fleming@nrel.gov>

Author: misi9170

docs/multidimensional_wind_turbine.ipynb

@@ -95,19 +95,65 @@
    "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."
+    "time, but multiple combinations can be run sequentially as is shown above.\n",
+    "\n",
+    "As of FLORIS v4.6, users can further specify array-based multidimensional conditions, where a\n",
+    "different multidimensional condition can be specified for each findex. This allows users to run\n",
+    "multiple multidimensional condition combinations in a single call to `fmodel.run()`. Further,\n",
+    "multidimensional conditions can now be passed to `floris.set()` via the `WindData` objects\n",
+    "(`TimeSeries`, in this case)."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "8c21f432",
    "metadata": {},
    "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c0b18ef8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "multidim_conditions = {\n",
+    "    \"Tp\": np.array([2]*n_wind_speeds + [4]*n_wind_speeds),\n",
+    "    \"Hs\": np.array([1]*n_wind_speeds + [5]*n_wind_speeds),\n",
+    "}\n",
+    "\n",
+    "fmodel.set(\n",
+    "    wind_data=TimeSeries(\n",
+    "        wind_directions=np.zeros(n_wind_speeds*2),\n",
+    "        wind_speeds=np.tile(wind_speeds, 2),\n",
+    "        turbulence_intensities=0.06,\n",
+    "        multidim_conditions=multidim_conditions,\n",
+    "    ),\n",
+    ")\n",
+    "# Call fmodel.run() once and run both conditions in one go\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[:n_wind_speeds], label=\"First condition\")\n",
+    "ax[0].grid()\n",
+    "ax[0].set_ylabel(\"Power [kW]\")\n",
+    "ax[1].plot(wind_speeds, thrust_coefficients[:n_wind_speeds])\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",
+    "ax[0].plot(wind_speeds, powers[n_wind_speeds:], label=\"Second condition\")\n",
+    "ax[0].legend(loc=\"upper left\")\n",
+    "ax[1].plot(wind_speeds, thrust_coefficients[n_wind_speeds:])"
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "floris",
+   "display_name": "eni",
    "language": "python",
    "name": "python3"
   },
@@ -121,7 +167,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.2"
+   "version": "3.13.7"
   }
  },
  "nbformat": 4,

examples/examples_multidim/002_multi_dimensional_cp_ct_2Hs.py

@@ -1,6 +1,11 @@
 """Example: Multi-dimensional power/thrust coefficient with 2 Hs values
 This example follows the previous example but shows the effect of changing the Hs setting.
 
+Updated in FLORIS v4.6 to use new array-based multidimensional functionality, where a different
+multidimensional condition can be specified for each findex. Prior to v4.6, when only scalar
+multidimensional conditions were supported, this example used two separate FLORIS runs to compute
+the two Hs cases.
+
 NOTE: The multi-dimensional power/thrust coefficient data used in this example is fictional for the
 purposes of facilitating this example. The power/thrust coefficient values for the different wave
 conditions are scaled values of the original power/thrust coefficient data for the IEA 15MW turbine.
@@ -15,45 +20,48 @@
 
 # Initialize FLORIS with the given input file.
 fmodel = FlorisModel("../inputs/gch_multi_dim_cp_ct.yaml")
-
-# Make a second Floris instance with a different setting for Hs.
-# Note the multi-cp-ct file (iea_15MW_multi_dim_Tp_Hs.csv)
-# for the turbine model iea_15MW_floating_multi_dim_cp_ct.yaml
-# Defines Hs at 1 and 5.
-# The value in gch_multi_dim_cp_ct.yaml is 3.01 which will map
-# to 5 as the nearer value, so we set the other case to 1
-# for contrast.
-fmodel_dict_mod = fmodel.core.as_dict()
-fmodel_dict_mod["flow_field"]["multidim_conditions"]["Hs"] = 1.0
-fmodel_hs_1 = FlorisModel(fmodel_dict_mod)
-
-# Set both cases to 3 turbine layout
 fmodel.set(layout_x=[0.0, 500.0, 1000.0], layout_y=[0.0, 0.0, 0.0])
-fmodel_hs_1.set(layout_x=[0.0, 500.0, 1000.0], layout_y=[0.0, 0.0, 0.0])
 
-# Use a sweep of wind speeds
-wind_speeds = np.arange(5, 20, 1.0)
+# Conditions to evaluate
+n_wind_speeds = 16
+wind_speeds = np.tile(np.linspace(5, 20, n_wind_speeds), 2) # Sweep wind speeds
+multidim_conditions = {
+    "Tp": np.array([2.5]*n_wind_speeds*2),
+    "Hs": np.array([3.1]*n_wind_speeds + [1.0]*n_wind_speeds),
+}
 time_series = TimeSeries(
-    wind_directions=270.0, wind_speeds=wind_speeds, turbulence_intensities=0.06
+    wind_directions=270.0,
+    wind_speeds=wind_speeds,
+    turbulence_intensities=0.06,
+    multidim_conditions=multidim_conditions
 )
+
+# Set wind, multidim conditios onto the FlorisModel
 fmodel.set(wind_data=time_series)
-fmodel_hs_1.set(wind_data=time_series)
 
-# Calculate wakes with baseline yaw
+# Calculate wakes
 fmodel.run()
-fmodel_hs_1.run()
 
 # Collect the turbine powers in kW
 turbine_powers = fmodel.get_turbine_powers() / 1000.0
-turbine_powers_hs_1 = fmodel_hs_1.get_turbine_powers() / 1000.0
 
 # Plot the power in each case and the difference in power
 fig, axarr = plt.subplots(1, 3, sharex=True, figsize=(12, 4))
 
 for t_idx in range(3):
     ax = axarr[t_idx]
-    ax.plot(wind_speeds, turbine_powers[:, t_idx], color="k", label="Hs=3.1 (5)")
-    ax.plot(wind_speeds, turbine_powers_hs_1[:, t_idx], color="r", label="Hs=1.0")
+    ax.plot(
+        wind_speeds[:n_wind_speeds],
+        turbine_powers[:n_wind_speeds, t_idx],
+        color="k",
+        label="Hs=3.1 (5)"
+    )
+    ax.plot(
+        wind_speeds[n_wind_speeds:],
+        turbine_powers[n_wind_speeds:, t_idx],
+        color="r",
+        label="Hs=1.0"
+    )
     ax.grid(True)
     ax.set_xlabel("Wind Speed (m/s)")
     ax.set_title(f"Turbine {t_idx}")

examples/examples_multidim/003_multi_dimensional_cp_ct_TI.py

@@ -2,6 +2,12 @@
 This example follows the previous example, but demonstrating how a multidimensional turbine can be
 used to model the effect of turbulence intensity on power and thrust coefficient.
 
+Updated in FLORIS v4.6 to demonstrate new array-based multidimensional functionality. In the updated
+version, setting loop_over_ti to True will run a single scalar multidimensional condition at a time
+and call fmodel.run() multiple times, similar to the behavior prior to v4.6. Alternatively, users
+may set loop_over_ti to False to use the new (and improved!) functionality and run all TI values in
+a single call to fmodel.run().
+
 NOTE: The multi-dimensional power/thrust coefficient data used in this example is fictional for the
 purposes of facilitating this example and the power values shown should not be taken as
 representative of the actual effect of turbulence intensity on power/thrust coefficient.
@@ -20,25 +26,54 @@
 # Set both cases to 3 turbine layout
 fmodel.set(layout_x=[0.0, 500.0, 1000.0], layout_y=[0.0, 0.0, 0.0])
 
+loop_over_ti = True # Otherwise, will set all TIs at once.
+
 # Use a sweep of wind speeds
 wind_speeds = np.arange(5, 20, 0.1)
-time_series = TimeSeries(
-    wind_directions=270.0, wind_speeds=wind_speeds, turbulence_intensities=0.06
-)
-fmodel.set(wind_data=time_series)
-
-# Loop over different turbulence intensities using set()
-# When running with TI=0.10, the multidimensional data handler will find the nearest defined
-# value of 0.08 and use that data.
-fig, axarr = plt.subplots(1, 3, sharex=True, figsize=(12, 4))
-for ti, col in zip([0.06, 0.10], ["k", "r"]):
-    fmodel.set(multidim_conditions={"TI": ti})
+
+if loop_over_ti:
+    # In this case, we will run() the fmodel multiple times, one for each turbulence intensity.
+    # We set a scalar multidim_conditions, which is broadcast over the wind speeds.
+    time_series = TimeSeries(
+        wind_directions=270.0, wind_speeds=wind_speeds, turbulence_intensities=0.06
+    )
+    fmodel.set(wind_data=time_series)
+
+    # Loop over different turbulence intensities using set()
+    # When running with TI=0.10, the multidimensional data handler will find the nearest defined
+    # value of 0.08 and use that data.
+    fig, axarr = plt.subplots(1, 3, sharex=True, figsize=(12, 4))
+    for ti, col in zip([0.06, 0.10], ["k", "r"]):
+        fmodel.set(multidim_conditions={"TI": ti})
+        fmodel.run()
+        turbine_powers = fmodel.get_turbine_powers() / 1000.0
+
+        for t_idx in range(3):
+            ax = axarr[t_idx]
+            ax.plot(wind_speeds, turbine_powers[:, t_idx], color=col, label="TI={0:.2f}".format(ti))
+else:
+    # Set all conditions to evaluate at once, and call fmodel.run() only once.
+    # We set multidim_conditions to be arrays matching the number of findices of the fmodel.
+
+    # Note that turbulence_intensities on the TimeSeries object is _not_ linked to the
+    # multidim_conditions
+    time_series = TimeSeries(
+        wind_directions=270.0,
+        wind_speeds=np.tile(wind_speeds, 2),
+        turbulence_intensities=0.06, # This value will be used for wake calculations only
+        multidim_conditions={"TI": np.array([0.06]*len(wind_speeds) + [0.10]*len(wind_speeds))},
+    )
+    fmodel.set(wind_data=time_series)
     fmodel.run()
     turbine_powers = fmodel.get_turbine_powers() / 1000.0
 
+    fig, axarr = plt.subplots(1, 3, sharex=True, figsize=(12, 4))
     for t_idx in range(3):
         ax = axarr[t_idx]
-        ax.plot(wind_speeds, turbine_powers[:, t_idx], color=col, label="TI={0:.2f}".format(ti))
+        ax.plot(wind_speeds, turbine_powers[:len(wind_speeds), t_idx], color="k", label="TI=0.06")
+        ax.plot(wind_speeds, turbine_powers[len(wind_speeds):, t_idx], color="r", label="TI=0.10")
+
+# Plot aesthetics
 for t_idx in range(3):
     axarr[t_idx].grid(True)
     axarr[t_idx].set_xlabel("Wind Speed (m/s)")