Clarify turbine definition terms (#815)

* pP -> cosine_loss_exponent_yaw throughout.

* pT -> cosine_loss_exponent_tilt throughout.

* Remove unused generator_efficiency key on turbine definitions.

* Comments updated to better explain the role of the cosine_loss_exponent_yaw.

* ruff.

Author: misi9170

examples/33_specify_turbine_power_curve.py

@@ -31,8 +31,8 @@
     file_name=None,
     generator_efficiency=1,
     hub_height=90,
-    pP=1.88,
-    pT=1.88,
+    cosine_loss_exponent_yaw=1.88,
+    cosine_loss_exponent_tilt=1.88,
     rotor_diameter=126,
     TSR=8,
     ref_air_density=1.225,

examples/inputs_floating/turbine_files/nrel_5MW_fixed.yaml

@@ -1,14 +1,13 @@
 turbine_type: 'nrel_5MW_floating'
-generator_efficiency: 0.944
 hub_height: 90.0
 rotor_diameter: 125.88
 TSR: 8.0
 correct_cp_ct_for_tilt: True # Apply tilt correction to cp/ct
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 5.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power:
     - 0.0
     - 0.0

examples/inputs_floating/turbine_files/nrel_5MW_floating.yaml

@@ -1,14 +1,13 @@
 turbine_type: 'nrel_5MW_floating'
-generator_efficiency: 0.944
 hub_height: 90.0
 rotor_diameter: 125.88
 TSR: 8.0
 correct_cp_ct_for_tilt: True # Apply tilt correction to cp/ct
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 5.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power:
     - 0.0
     - 0.0

examples/inputs_floating/turbine_files/nrel_5MW_floating_defined_floating.yaml

@@ -1,14 +1,13 @@
 turbine_type: 'nrel_5MW_floating'
-generator_efficiency: 0.944
 hub_height: 90.0
 rotor_diameter: 125.88
 TSR: 8.0
 correct_cp_ct_for_tilt: False # Do not apply tilt correction to cp/ct
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 5.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power:
     - 0.0
     - 0.0

examples/inputs_floating/turbine_files/nrel_5MW_floating_fixedtilt15.yaml

@@ -1,14 +1,13 @@
 turbine_type: 'nrel_5MW_floating'
-generator_efficiency: 0.944
 hub_height: 90.0
 rotor_diameter: 125.88
 TSR: 8.0
 correct_cp_ct_for_tilt: True # Apply tilt correction to cp/ct
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 5.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power:
     - 0.0
     - 0.0

examples/inputs_floating/turbine_files/nrel_5MW_floating_fixedtilt5.yaml

@@ -1,14 +1,13 @@
 turbine_type: 'nrel_5MW_floating'
-generator_efficiency: 0.944
 hub_height: 90.0
 rotor_diameter: 125.88
 TSR: 8.0
 correct_cp_ct_for_tilt: True # Apply tilt correction to cp/ct
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 5.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power:
     - 0.0
     - 0.0

floris/simulation/rotor_velocity.py

@@ -18,12 +18,12 @@
 
 
 def rotor_velocity_yaw_correction(
-    pP: float,
+    cosine_loss_exponent_yaw: float,
     yaw_angles: NDArrayFloat,
     rotor_effective_velocities: NDArrayFloat,
 ) -> NDArrayFloat:
     # Compute the rotor effective velocity adjusting for yaw settings
-    pW = pP / 3.0  # Convert from pP to w
+    pW = cosine_loss_exponent_yaw / 3.0  # Convert from cosine_loss_exponent_yaw to w
     # TODO: cosine loss hard coded
     rotor_effective_velocities = rotor_effective_velocities * cosd(yaw_angles) ** pW
 
@@ -32,7 +32,7 @@ def rotor_velocity_yaw_correction(
 def rotor_velocity_tilt_correction(
     tilt_angles: NDArrayFloat,
     ref_tilt: NDArrayFloat,
-    pT: float,
+    cosine_loss_exponent_tilt: float,
     tilt_interp: NDArrayObject,
     correct_cp_ct_for_tilt: NDArrayBool,
     rotor_effective_velocities: NDArrayFloat,
@@ -50,7 +50,10 @@ def rotor_velocity_tilt_correction(
     # Compute the rotor effective velocity adjusting for tilt
     # TODO: cosine loss hard coded
     relative_tilt = tilt_angles - ref_tilt
-    rotor_effective_velocities = rotor_effective_velocities * cosd(relative_tilt) ** (pT / 3.0)
+    rotor_effective_velocities = (
+        rotor_effective_velocities
+        * cosd(relative_tilt) ** (cosine_loss_exponent_tilt / 3.0)
+    )
     return rotor_effective_velocities
 
 def simple_mean(array, axis=0):
@@ -177,8 +180,8 @@ def rotor_effective_velocity(
     yaw_angle: NDArrayFloat,
     tilt_angle: NDArrayFloat,
     ref_tilt: NDArrayFloat,
-    pP: float,
-    pT: float,
+    cosine_loss_exponent_yaw: float,
+    cosine_loss_exponent_tilt: float,
     tilt_interp: NDArrayObject,
     correct_cp_ct_for_tilt: NDArrayBool,
     turbine_type_map: NDArrayObject,
@@ -198,8 +201,8 @@ def rotor_effective_velocity(
         yaw_angle = yaw_angle[:, ix_filter]
         tilt_angle = tilt_angle[:, ix_filter]
         ref_tilt = ref_tilt[:, ix_filter]
-        pP = pP[:, ix_filter]
-        pT = pT[:, ix_filter]
+        cosine_loss_exponent_yaw = cosine_loss_exponent_yaw[:, ix_filter]
+        cosine_loss_exponent_tilt = cosine_loss_exponent_tilt[:, ix_filter]
         turbine_type_map = turbine_type_map[:, ix_filter]
 
     # Compute the rotor effective velocity adjusting for air density
@@ -212,7 +215,7 @@ def rotor_effective_velocity(
 
     # Compute the rotor effective velocity adjusting for yaw settings
     rotor_effective_velocities = rotor_velocity_yaw_correction(
-        pP,
+        cosine_loss_exponent_yaw,
         yaw_angle,
         rotor_effective_velocities
     )
@@ -222,7 +225,7 @@ def rotor_effective_velocity(
         turbine_type_map,
         tilt_angle,
         ref_tilt,
-        pT,
+        cosine_loss_exponent_tilt,
         tilt_interp,
         correct_cp_ct_for_tilt,
         rotor_effective_velocities,

floris/simulation/turbine/operation_models.py

@@ -167,8 +167,8 @@ class CosineLossTurbine(BaseOperationModel):
     """
     Static class defining an actuator disk turbine model that may be misaligned with the flow.
     Nonzero tilt and yaw angles are handled via cosine relationships, with the power lost to yawing
-    defined by the pP exponent. This turbine submodel is the default, and matches the turbine
-    model in FLORIS v3.
+    defined by the cosine of the yaw misalignment raised to the power of cosine_loss_exponent_yaw.
+    This turbine submodel is the default, and matches the turbine model in FLORIS v3.
 
     As with all turbine submodules, implements only static power() and thrust_coefficient() methods,
     which are called by power() and thrust_coefficient() on turbine.py, respectively. This class is
@@ -211,15 +211,15 @@ def power(
         )
 
         rotor_effective_velocities = rotor_velocity_yaw_correction(
-            pP=power_thrust_table["pP"],
+            cosine_loss_exponent_yaw=power_thrust_table["cosine_loss_exponent_yaw"],
             yaw_angles=yaw_angles,
             rotor_effective_velocities=rotor_effective_velocities,
         )
 
         rotor_effective_velocities = rotor_velocity_tilt_correction(
             tilt_angles=tilt_angles,
             ref_tilt=power_thrust_table["ref_tilt"],
-            pT=power_thrust_table["pT"],
+            cosine_loss_exponent_tilt=power_thrust_table["cosine_loss_exponent_tilt"],
             tilt_interp=tilt_interp,
             correct_cp_ct_for_tilt=correct_cp_ct_for_tilt,
             rotor_effective_velocities=rotor_effective_velocities,

floris/simulation/turbine/turbine.py

@@ -117,12 +117,12 @@ def power(
     """
     # TODO: Change the order of input arguments to be consistent with the other
     # utility functions - velocities first...
-    # Update to power calculation which replaces the fixed pP exponent with
-    # an exponent pW, that changes the effective wind speed input to the power
-    # calculation, rather than scaling the power.  This better handles power
-    # loss to yaw in above rated conditions
+    # Update to power calculation which replaces the fixed cosine_loss_exponent_yaw exponent
+    # (which applies to the cosine of the yaw misalignment) with an exponent pW, that changes the
+    # effective wind speed input to the power calculation, rather than scaling the power.  This
+    # better handles power loss to yaw in above rated conditions
     #
-    # based on the paper "Optimising yaw control at wind farm level" by
+    # Based on the paper "Optimising yaw control at wind farm level" by
     # Ervin Bossanyi
 
     # Down-select inputs if ix_filter is given
@@ -390,8 +390,6 @@ class Turbine(BaseClass):
         rotor_diameter (float): The rotor diameter in meters.
         hub_height (float): The hub height in meters.
         TSR (float): The Tip Speed Ratio of the turbine.
-        generator_efficiency (float): The efficiency of the generator used to scale
-            power production.
         power_thrust_table (dict[str, float]): Contains power coefficient and thrust coefficient
             values at a series of wind speeds to define the turbine performance.
             The dictionary must have the following three keys with equal length values:
@@ -403,10 +401,10 @@ class Turbine(BaseClass):
             or, contain a key "power_thrust_data_file" pointing to the power/thrust data.
             Optionally, power_thrust_table may include parameters for use in the turbine submodel,
             for example:
-                pP (float): The cosine exponent relating the yaw misalignment angle to turbine
-                    power.
-                pT (float): The cosine exponent relating the rotor tilt angle to turbine
-                    power.
+                cosine_loss_exponent_yaw (float): The cosine exponent relating the yaw misalignment
+                    angle to turbine power.
+                cosine_loss_exponent_tilt (float): The cosine exponent relating the rotor tilt angle
+                    to turbine power.
                 ref_air_density (float): The density at which the provided Cp and Ct curves are
                     defined.
                 ref_tilt (float): The implicit tilt of the turbine for which the Cp and Ct
@@ -428,7 +426,6 @@ class Turbine(BaseClass):
     rotor_diameter: float = field()
     hub_height: float = field()
     TSR: float = field()
-    generator_efficiency: float = field()
     power_thrust_table: dict = field(default={}) # conversion to numpy in __post_init__
     power_thrust_model: str = field(default="cosine-loss")
 
@@ -527,7 +524,11 @@ def _initialize_multidim_power_thrust_table(self):
                 key: {
                     "wind_speed": data['ws'].values,
                     "power": (
-                        0.5 * self.rotor_area * data['Cp'].values * self.generator_efficiency
+                        # NOTE: generator_efficiency hardcoded to 0.944 here (NREL 5MW default).
+                        # This code will be
+                        # removed in a separate PR when power is specified as an absolute value for
+                        # mutlidimensional turbines
+                        0.5 * self.rotor_area * data['Cp'].values * 0.944
                         * data['ws'].values ** 3 * power_thrust_table_ref["ref_air_density"] / 1000
                     ), # TODO: convert this to 'power' or 'P' in data tables, as per PR #765
                     "thrust_coefficient": data['Ct'].values,

floris/tools/convert_turbine_v3_to_v4.py

@@ -45,8 +45,8 @@
     valid_properties = [
         "generator_efficiency",
         "hub_height",
-        "pP",
-        "pT",
+        "cosine_loss_exponent_yaw",
+        "cosine_loss_exponent_tilt",
         "rotor_diameter",
         "TSR",
         "ref_air_density",
@@ -55,8 +55,11 @@
 
     turbine_properties = {k:v for k,v in v3_turbine_dict.items() if k in valid_properties}
     turbine_properties["ref_air_density"] = v3_turbine_dict["ref_density_cp_ct"]
+    turbine_properties["cosine_loss_exponent_yaw"] = v3_turbine_dict["pP"]
     if "ref_tilt_cp_ct" in v3_turbine_dict:
         turbine_properties["ref_tilt"] = v3_turbine_dict["ref_tilt_cp_ct"]
+    if "pT" in v3_turbine_dict:
+        turbine_properties["cosine_loss_exponent_tilt"] = v3_turbine_dict["pT"]
 
     # Convert to v4 and print new yaml
     v4_turbine_dict = build_cosine_loss_turbine_dict(

floris/turbine_library/iea_10MW.yaml

@@ -2,16 +2,15 @@
 # https://github.com/NREL/turbine-models/blob/master/Offshore/IEA_10MW_198_RWT.csv
 # Note: Generator efficiency of 94% used. Small power variations above rated removed.
 turbine_type: 'iea_10MW'
-generator_efficiency: 0.94
 hub_height: 119.0
 rotor_diameter: 198.0
 TSR: 8.0
 power_thrust_model: cosine-loss
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 6.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power:
     - 0.0
     - 0.0

floris/turbine_library/iea_15MW.yaml

@@ -2,17 +2,17 @@
 # https://github.com/IEAWindTask37/IEA-15-240-RWT/blob/master/Documentation/
 # IEA-15-240-RWT_tabular.xlsx
 # Note: Small power variations above rated removed.
+# Generator efficiency of 100% used.
 turbine_type: 'iea_15MW'
-generator_efficiency: 1.0
 hub_height: 150.0
 rotor_diameter: 242.24
 TSR: 8.0
 power_thrust_model: cosine-loss
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 6.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power:
     - 0.000000
     - 0.000000

floris/turbine_library/iea_15MW_floating_multi_dim_cp_ct.yaml

@@ -1,14 +1,13 @@
 turbine_type: 'iea_15MW_floating'
-generator_efficiency: 1.0
 hub_height: 150.0
 rotor_diameter: 242.24
 TSR: 8.0
 multi_dimensional_cp_ct: True
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 6.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power_thrust_data_file: 'iea_15MW_multi_dim_Tp_Hs.csv'
 floating_tilt_table:
   tilt:

floris/turbine_library/iea_15MW_multi_dim_cp_ct.yaml

@@ -1,12 +1,11 @@
 turbine_type: 'iea_15MW_multi_dim_cp_ct'
-generator_efficiency: 1.0
 hub_height: 150.0
 rotor_diameter: 242.24
 TSR: 8.0
 multi_dimensional_cp_ct: True
 power_thrust_table:
   ref_air_density: 1.225
   ref_tilt: 6.0
-  pP: 1.88
-  pT: 1.88
+  cosine_loss_exponent_yaw: 1.88
+  cosine_loss_exponent_tilt: 1.88
   power_thrust_data_file: 'iea_15MW_multi_dim_Tp_Hs.csv'

floris/turbine_library/nrel_5MW.yaml

@@ -2,17 +2,14 @@
 # Data based on:
 # https://github.com/NREL/turbine-models/blob/master/Offshore/NREL_5MW_126_RWT_corrected.csv
 # Note: Small power variations above rated removed. Rotor diameter includes coning angle.
+# Note: generator efficiency of 94.4% is assumed for the NREL 5MW turbine.
 
 ###
 # An ID for this type of turbine definition.
 # This is not currently used, but it will be enabled in the future. This should typically
 # match the root name of the file.
 turbine_type: 'nrel_5MW'
 
-###
-# Setting for generator losses to power.
-generator_efficiency: 0.944
-
 ###
 # Hub height.
 hub_height: 90.0
@@ -39,9 +36,9 @@ power_thrust_table:
   # the effects of a floating platform on a turbine's power and wake.
   ref_tilt: 5.0
   # Cosine exponent for power loss due to tilt.
-  pT: 1.88
+  cosine_loss_exponent_tilt: 1.88
   # Cosine exponent for power loss due to yaw misalignment.
-  pP: 1.88
+  cosine_loss_exponent_yaw: 1.88
   ### Power thrust table data
   wind_speed:
     - 0.0