modifications to kynema interface and setup + docs (#1803)

* modifications to kynema interface and setup

* incorporate generator efficiency

* relax kynema convergence criteria

* more consistent name for hub wind vector initialization

* documenting kynema inputs

* docs issues

* full parameter name in reference

Author: mbkuhn

amr-wind/wind_energy/actuator/turbine/kynema/KynemaIface.cpp

@@ -21,7 +21,10 @@ void build_turbine(
     const int n_blade_nodes,
     const int n_tower_nodes,
     const double rotor_speed_init,
-    const double yaw_init)
+    const double generator_power_init,
+    const double wind_speed_init,
+    const double yaw_init,
+    const double generator_efficiency)
 {
     // WindIO components
     const auto& wio_blade = wio["components"]["blade"];
@@ -50,7 +53,10 @@ void build_turbine(
             wio_drivetrain["outer_shape"]["distance_tt_hub"].as<double>())
         .SetGearBoxRatio(wio_drivetrain["gearbox"]["gear_ratio"].as<double>())
         .SetRotorSpeed(rotor_speed_init)
-        .SetNacelleYawAngle(yaw_init);
+        .SetGeneratorPower(generator_power_init)
+        .SetHubWindSpeed(wind_speed_init)
+        .SetNacelleYawAngle(yaw_init)
+        .SetGeneratorEfficiency(generator_efficiency);
 
     //--------------------------------------------------------------------------
     // Build Blades
@@ -169,10 +175,7 @@ void build_turbine(
     tower_builder
         .SetElementOrder(
             n_tower_nodes - 1) // Set element order to num nodes - 1
-        .SetQuadratureStyle(
-            kynema::interfaces::components::BeamInput::QuadratureStyle::
-                Segmented)
-        .SetSectionRefinement(4)
+        .SetSectionRefinement(2)
         .PrescribedRootMotion(false); // Fix displacement of tower base node
 
     // Add reference axis coordinates (WindIO uses Z-axis as reference axis)
@@ -388,14 +391,14 @@ void update_turbine(::ext_turb::KynemaTurbine& fi, bool advance)
     }
     if (advance) {
         // individual turbine step, do not output every step
-        if (fi.controller_input_file.size() > 0) {
-            const double t = fi.time_index * fi.dt_ext;
-            fi.interface->ApplyController(t);
-        }
         bool converged = fi.interface->Step();
         if (!converged) {
             amrex::Abort("Kynema did not converge\n");
         }
+        if (fi.controller_input_file.size() > 0) {
+            const double t = fi.time_index * fi.dt_ext;
+            fi.interface->ApplyController(t);
+        }
     }
 
     if (fi.substep_counter == fi.num_substeps) {
@@ -657,7 +660,8 @@ void ExtTurbIface<KynemaTurbine, KynemaSolverData>::ext_init_turbine(
     // Builds turbine, including blades, nacelle, and tower
     exw_kynema::build_turbine(
         builder, wio, fi.num_blades, fi.num_blade_elem, num_pts_tower_struct,
-        fi.rotational_speed, fi.yaw);
+        fi.rotational_speed, fi.generator_power, fi.wind_speed, fi.yaw,
+        fi.generator_efficiency);
 
     auto n_aero_sections = exw_kynema::build_aero(builder, wio);
 

amr-wind/wind_energy/actuator/turbine/kynema/kynema_types.H

@@ -243,7 +243,10 @@ struct KynemaTurbine : public ext_turb::ExternalTurbine
 
     double fluid_density{1.};
     double rotational_speed{0.};
+    double generator_power{0.};
+    double wind_speed{0.};
     double yaw{0.};
+    double generator_efficiency{1.};
     int substep_counter{0};
 
     std::string controller_shared_lib_path{""};
@@ -271,8 +274,8 @@ struct KynemaSolverData
 
     double damping_factor{0.};
     int nl_iter_max{12};
-    double abs_err_tol{1e-7};
-    double rel_err_tol{1e-6};
+    double abs_err_tol{1e-5};
+    double rel_err_tol{1e-4};
     amrex::Vector<amrex::Real> gravity{0.0, 0.0, -9.81};
 };
 

amr-wind/wind_energy/actuator/turbine/kynema/turbine_kynema_ops.H

@@ -81,12 +81,22 @@ struct ReadInputsOp<TurbineKynema, SrcTrait>
             pp.query("rot_speed_rpm", tf.rotational_speed);
             tf.rotational_speed *= 2.0 * M_PI / 60.;
         }
+        // Initial generator speed
+        pp.query("generator_power_init", tf.generator_power);
+        // Initial wind speed
+        amrex::Vector<amrex::Real> vel_vec{tf.wind_speed, 0., 0.};
+        pp.queryarr("hub_wind_vector_init", vel_vec);
+        tf.wind_speed = std::sqrt(
+            vel_vec[0] * vel_vec[0] + vel_vec[1] * vel_vec[1] +
+            vel_vec[2] * vel_vec[2]);
         // Initial or constant nacelle yaw
         pp.query("yaw_rad", tf.yaw);
         if (!pp.contains("yaw_rad")) {
             pp.query("yaw_deg", tf.yaw);
             tf.yaw *= M_PI / 180.;
         }
+        // Generator efficiency
+        pp.query("generator_efficiency", tf.generator_efficiency);
     }
 };
 

docs/sphinx/spelling-wordlist.txt

@@ -12,6 +12,7 @@ Fortran
 Joukowsky
 Jupyter
 Karman
+Kynema
 Liungman
 MPI
 Menter 

docs/sphinx/user/inputs_Actuator.rst

@@ -25,7 +25,8 @@ turbines as actuator disks and actuator line models.
    **type:** String, mandatory
 
    This string identifies the type of actuator to use. The ones currently
-   supported are: ``UniformCtDisk``, ``JoukowskyDisk``, ``TurbineFastLine``, ``TurbineFastDisk``, and
+   supported are: ``UniformCtDisk``, ``JoukowskyDisk``, ``TurbineFastLine``,
+   ``TurbineFastDisk``, ``TurbineKynemaLine``, and
    ``FixedWingLine``.
 
 It is recommended to group common parameters across actuators using the ``Actuator.[type].[param]``. For example::
@@ -395,6 +396,188 @@ Example for ``TurbineFastLine``::
 
    This is the name of the openfast input file with all the turbine information.
 
+TurbineKynemaLine
+"""""""""""""""""
+
+This actuator type requires an AMR-Wind build with Kynema coupling
+enabled. This is a similar coupling to OpenFAST, but Kynema
+acts as the turbine solver in this instance. Some turbine quantities
+that the OpenFAST interface needs from the AMR-Wind input file
+are instead found directly by the code within the Kynema input file,
+whereas other quantities that OpenFAST has stored within its inputs
+need to be directly supplied through the AMR-Wind input file for Kynema,
+especially for initialization.
+
+Example for ``TurbineKynemaLine``::
+
+   incflo.physics = FreeStream Actuator
+   Actuator.labels = WTG01
+   Actuator.type = TurbineKynemaLine
+   ## Turbine discretization parameters
+   Actuator.TurbineKynemaLine.num_struct_nodes_blade = 6
+   Actuator.TurbineKynemaLine.num_points_blade = 64
+   Actuator.TurbineKynemaLine.num_points_tower = 0 # not enabled yet
+   ## Turbine setup
+   Actuator.TurbineKynemaLine.rot_speed_rpm    = 12.1
+   Actuator.TurbineKynemaLine.yaw_deg = 30
+   Actuator.WTG01.kynema_input_file = NREL-15MW-aero.yaml
+   Actuator.WTG01.base_position = 5.0191 0. -89.56256
+   ## Turbine - flow coupling parameters
+   Actuator.TurbineKynemaLine.epsilon = 10.0 10.0 10.0
+   Actuator.TurbineKynemaLine.epsilon_chord = 0.25 0.25 0.25
+   Actuator.TurbineKynemaLine.fllc = 0
+   Actuator.TurbineKynemaLine.nacelle_drag_coeff = 0.0
+   Actuator.TurbineKynemaLine.nacelle_area = 0.0
+   Actuator.TurbineKynemaLine.density = 1.225
+   ## Turbine controller parameters and initial state
+   Actuator.TurbineKynemaLine.controller_shared_library_path = /path/to/libdiscon.so # or libdiscon.dylib
+   Actuator.TurbineKynemaLine.generator_power_init = 5e6
+   Actuator.TurbineKynemaLine.hub_wind_vector_init = 9.8726896031426 5.7 0.0
+   Actuator.TurbineKynemaLine.generator_efficiency = 0.944
+   ## Turbine solver numerical parameters
+   Actuator.TurbineKynemaLine.dt = 0.01
+   Kynema.abs_err_tol = 1e-6
+
+   Actuator.TurbineKynemaLine.output_frequency = 10
+
+   ICNS.source_terms = ActuatorForcing
+
+.. input_param:: Actuator.TurbineKynemaLine.num_struct_nodes_blade
+
+   **type:** Int, required
+
+   This is the number of structural nodes for Kynema to use when modeling each turbine blade.
+
+.. input_param:: Actuator.TurbineKynemaLine.num_points_blade
+
+   **type:** Int, required
+
+   This is the number of aerodynamic sections for Kynema to use when modeling each turbine blade.
+   This will correspond to the number of force points and velocity points on each blade in AMR-Wind.
+   This must be the same number as provided in the Kynema input file.
+
+.. input_param:: Actuator.TurbineKynemaLine.num_points_tower
+
+   **type:** Int, required
+
+   This is the number of aerodynamic sections for Kynema to use when modeling the tower.
+   This feature is still under development, so this argument must be set to 0.
+
+.. input_param:: Actuator.TurbineKynemaLine.rot_speed_rpm
+
+   **type:** Real, optional, default = 0
+
+   This is the initial rotational speed of the turbine in RPM. This parameter can
+   alternatively be set in radians per second using the input parameter
+   :input_param:`Actuator.TurbineKynemaLine.rot_speed_radps`.
+
+.. input_param:: Actuator.TurbineKynemaLine.rot_speed_radps
+
+   **type:** Real, optional, default = 0
+
+   This is the initial rotational speed of the turbine in radians per second.
+   If this argument is present,
+   :input_param:`Actuator.TurbineKynemaLine.rot_speed_rpm` will be ignored.
+
+.. input_param:: Actuator.TurbineKynemaLine.yaw_deg
+
+   **type:** Real, optional, default = 0
+
+   This is the initial yaw angle of the turbine in degrees, counterclockwise
+   from the -x direction. This parameter can alternatively be set in radians
+   using the input parameter :input_param:`Actuator.TurbineKynemaLine.yaw_rad`.
+
+.. input_param:: Actuator.TurbineKynemaLine.yaw_rad
+
+   **type:** Real, optional, default = 0
+
+   This is the initial yaw angle of the turbine in radians. If this argument is
+   present, :input_param:`Actuator.TurbineKynemaLine.yaw_deg` will be ignored.
+
+.. input_param:: Actuator.TurbineKynemaLine.kynema_input_file
+
+   **type:** String, required
+
+   This is the input file used to initialize the Kynema turbine model. It
+   conforms to the WindIO format. A pre-processing tool is provided in the
+   Kynema repository to change the number of aerodynamic sections per blade,
+   if needed, as well as to address some format edge cases.
+
+.. input_param:: Actuator.TurbineKynemaLine.controller_shared_library_path
+
+   **type:** String, optional, default = empty
+
+   This is the path to the controller shared library (typically ROSCO).
+   If this parameter is not provided, no controller will be created in
+   the turbine model, and the controller-related input parameters will not be used.
+
+.. input_param:: Actuator.TurbineKynemaLine.generator_power_init
+
+   **type:** Real, optional, default = 0
+
+   Power of the generator at the start of the simulation.
+
+.. input_param:: Actuator.TurbineKynemaLine.hub_wind_vector_init
+
+   **type:** Vector<Real>, optional, default = 0 0 0
+
+   This is the initial wind vector that the turbine hub is exposed to.
+   It does not have to be the actual wind there at initialization; this
+   number is converted to a wind speed that is used as the controller's
+   initial guess.
+
+.. input_param:: Actuator.TurbineKynemaLine.generator_efficiency
+
+   **type:** Real, optional, default = 1
+
+   This is the efficiency of the generator. If not populated,
+   the efficiency is assumed to be 1, i.e., 100%.
+
+.. input_param:: Actuator.TurbineKynemaLine.dt
+
+   **type:** Real, optional, default = same as AMR-Wind dt
+
+   This is the time step size chosen for the Kynema turbine model. It must
+   be a factor of the AMR-Wind time step so that Kynema can take an integer
+   number of sub-steps for each AMR-Wind time step. If not populated, the Kynema time
+   step size will be the same as the flow solver time step, and, due to the
+   robustness of Kynema, this is typically fine.
+
+.. input_param:: Actuator.TurbineKynemaLine.output_frequency
+
+   **type:** Int, optional, default = 10
+
+   This is how often, in time steps, to output actuator data from AMR-Wind.
+   Note, this does not govern how often Kynema outputs turbine data. Kynema
+   automatically outputs data every AMR-Wind time step.
+
+.. input_param:: Kynema.abs_err_tol
+
+   **type:** Real, optional, default = 1e-5
+
+   This turbine solver parameter is not turbine-specific; rather, it informs the
+   solution parameters of Kynema overall. This, in particular, sets the absolute
+   tolerance of the Kynema solver.
+
+.. input_param:: Kynema.rel_err_tol
+
+   **type:** Real, optional, default = 1e-4
+
+   This parameter sets the relative tolerance of the Kynema solver.
+
+.. input_param:: Kynema.max_nonlinear_iterations
+
+   **type:** Int, optional, default = 12
+
+   This parameter sets the maximum number of nonlinear iterations for the Kynema solver.
+
+.. input_param:: Kynema.damping_factor
+
+   **type:** Real, optional, default = 0
+
+   This parameter sets the numerical damping (time-based) of the Kynema solver.
+   Counterintuitively, full damping corresponds to 0 and no damping corresponds to 1.
+
 Active Wake Control with Joukowsky Disk
 """""""""""""""""""""""""""""""""""""""