.. _inputs_actuator: Section: Actuator ~~~~~~~~~~~~~~~~~ This section controls the actuator type models. This includes the actuator disk and line models. The prefix is the label set in ``incflo.physics``. For example ``incflo.physics = FreeStream Actuator`` Actuator models are meant to simulate aerodynamic objects by using body forces in the momentum equation. There are capabilities to simulate fixed wings as actuator lines and wind turbines as actuator disks and actuator line models. .. input_param:: Actuator.labels **type:** String, mandatory This string is used as an identifier for the current actuator. .. input_param:: Actuator.type **type:** String, mandatory This string identifies the type of actuator to use. The ones currently supported are: ``UniformCtDisk``, ``JoukowskyDisk``, ``TurbineFastLine``, ``TurbineFastDisk``, ``TurbineKynemaFMBLine``, ``TurbineKynemaFMBDisk``, ``FixedWingLine``, ``ActuatorSector``, and ``Drone``. The Kynema-FMB coupled actuator turbine types are documented in the dedicated reference page :doc:`inputs_Actuator_KynemaFMB`. It is recommended to group common parameters across actuators using the ``Actuator.[type].[param]``. For example:: Actuator.Turb1.type = UniformCtDisk" Actuator.Turb1.epsilon = 5.0 5.0 5.0" Actuator.Turb2.type = UniformCtDisk" Actuator.Turb2.epsilon = 5.0 5.0 5.0" becomes:: Actuator.UniformCtDisk.epsilon = 5.0 5.0 5.0" Actuator.Turb1.type = UniformCtDisk" Actuator.Turb2.type = UniformCtDisk" FixedWingLine """"""""""""" Example for ``FixedWingLine``:: incflo.physics = FreeStream Actuator Actuator.labels = F1 Actuator.type = FixedWingLine Actuator.FixedWingLine.num_points = 21 Actuator.FixedWingLine.epsilon = 3.0 3.0 3.0 Actuator.FixedWingLine.epsilon_chord = 0.25 0.25 0.25 Actuator.FixedWingLine.fllc = 0 Actuator.FixedWingLine.pitch = 4.0 Actuator.FixedWingLine.span_locs = 0.0 1.0 Actuator.FixedWingLine.chord = 2.0 2.0 Actuator.FixedWingLine.airfoil_table = DU21_A17.txt Actuator.FixedWingLine.airfoil_type = openfast Actuator.F1.start = 0.0 -4.0 0.0 Actuator.F1.end = 0.0 4.0 0.0 Actuator.F1.output_frequency = 10 ICNS.source_terms = ActuatorForcing .. input_param:: Actuator.FixedWingLine.num_points **type:** int, mandatory This is the number of actuator points along the wing to be used in the simulation. .. input_param:: Actuator.FixedWingLine.epsilon **type:** List of 3 real numbers, mandatory This is the value of epsilon in the chord, thickness and spanwise directions. .. input_param:: Actuator.FixedWingLine.epsilon_chord **type:** List of 3 real numbers, optional This is the value of epsilon/chord. This value will be used to compute epsilon as a function of the chord at every actuator point. A value of epsilon / chord ~ 0.25 is recommended for an optimal representation of the blade aerodynamics. When this variable is specified, the code will choose the maximum value between ``epsilon_chord * chord`` and ``epsilon`` for every actuator point. .. input_param:: Actuator.FixedWingLine.fllc **type:** Bool, optional This option will activate the filtered lifting line correction (fllc). The correction follows the implementation of `Martinez-Tossas and Meneveau (2019) `_ and `Blaylock et al (2022) `_. The use of the fllc requires ``epsilon`` and an optimal ``epsilon_chord`` as an input. The recommended value is 0.25 in all directions for ``epsilon_chord`` and a value of ``epsilon`` in all directions that would be greater than at least 2.5 times the grid size ``dx``. The default is `0`. .. input_param:: Actuator.FixedWingLine.fllc_type **type:** String, optional, default = ``variable_chord`` This option tells whether to use the original fllc formulation outlined in `Martinez-Tossas and Meneveau (2019) `_, which assumes a constant chord length across blade (specified as ``constant_chord``), or to use a new formulation outlined in `Martinez-Tossas et al. (2023) `_, which accounts for chord variations (specified as ``variable_chord``). .. input_param:: Actuator.FixedWingLine.fllc_relaxation_factor **type:** Double, optional The relaxation factor to be applied to the updated velocity see: `Martinez-Tossas and Meneveau (2019) `_ The default value is `0.1`. .. input_param:: Actuator.FixedWingLine.fllc_start_time **type:** Double, optional The time in the simulation from when to start using the correction. The default value is `0`. .. input_param:: Actuator.FixedWingLine.fllc_nonuniform **type:** Bool The flag to specify if the actuator points used to compute the correction should be non-uniformly distributed. This helps in using less points for the fllc while still maintaining the accuracy of the fllc. The default value is `true`. .. input_param:: Actuator.FixedWingLine.fllc_epsilon_dr_ratio **type:** Double, optional The ratio of epsilon to actuator point spacing used to create a non-uniform distribution. A value of `1` or greater is recommended. The default value is `1`. .. input_param:: Actuator.FixedWingLine.pitch **type:** Real number, mandatory This is the pitch angle of the blade in degrees. All coordinates will be pitched by this angle. In the case of a fixed wing, this would be the angle of attack of the wing with respect to the inflow velocity. This argument is mandatory unless a pitch timetable is specified. .. input_param:: Actuator.FixedWingLine.span_locs **type:** List of real numbers, mandatory These are non-dimensional span locations from 0 to 1. These locations are used to specify the chord values at every span location of the blade. .. input_param:: Actuator.FixedWingLine.chord **type:** List of real numbers, mandatory These are the chord values at every span location. The length of this array needs to be the same length as ``span_locs``. .. input_param:: Actuator.FixedWingLine.airfoil_table **type:** String, mandatory This is the name of the file that contains the lookup table for lift and drag coefficients. .. input_param:: Actuator.FixedWingLine.airfoil_type **type:** String, mandatory This is the type of airfoil table lookup. The currently supported options are ``openfast`` and ``text``. .. input_param:: Actuator.F1.start **type:** List of 3 real numbers, mandatory This is the starting point of the wing where the first actuator point will be. .. input_param:: Actuator.F1.end **type:** List of 3 real numbers, mandatory This is the end point of the wing where the last actuator point will be. .. input_param:: Actuator.F1.output_frequency **type:** int, optional This is how often to write actuator output. The default is ``10``. .. input_param:: Actuator.FixedWingLine.motion_type **type:** String, optional The FixedWingLine actuator allows for motion, though other aspects of the actuator remain fixed (such as the orientation and the dimensions). The currently supported options are ``none`` (default), ``linear``, and ``sine``. Linear motion moves the actuator at a constant velocity in a straight line whereas sine motion oscillates the actuator according to a temporal sine signal. .. input_param:: Actuator.FixedWingLine.velocity **type:** List of 3 real numbers, mandatory when motion_type = ``linear`` This vector provides the prescribed constant velocity of the actuator motion. .. input_param:: Actuator.FixedWingLine.sine_vector **type:** List of 3 real numbers, mandatory when motion_type = ``sine`` This vector provides the actuator displacement from its initial, specified location as it moves according to the oscillatory sine signal. The range of motion of the actuator will be between (initial location + sine vector) and (initial location - sine vector). .. input_param:: Actuator.FixedWingLine.sine_period **type:** Real number, mandatory when motion_type = ``linear`` This value specifies the temporal period of the sine signal. .. input_param:: Actuator.FixedWingLine.pitch_timetable **type:** String, optional File name of pitch timetable. This file must specify pitch angles at different times below a one-line header. When this argument is present, the ``pitch`` argument is no longer mandatory, and it will not be used. .. input_param:: Actuator.FixedWingLine.disable_spanwise_gaussian **type:** Boolean, optional, default = false When this option is turned on, the actuator Gaussian is disabled in the spanwise Gaussian, making the force distribution uniform in that direction. This option enables quasi-2D simulations with a fixed wing. The code will print warning statements if the detected spanwise direction is not periodic. .. input_param:: Actuator.FixedWingLine.normalize_spanwise **type:** Boolean, optional, default = true When the ``disable_spanwise_gaussian`` is true, the default behavior is to normalize the Gaussian and force quantities in the spanwise direction, preventing the number of actuator points or the actuator point spacing from affecting the results. When this option is false, the ordinary treatment of the Gaussian and force quantities in the spanwise direction is used instead. Setting this option to false can be useful for verification studies. .. input_param:: Actuator.FixedWingLine.prescribed_uinf **type:** Real, optional, default = -1.0 This input allows the freestream velocity sampled by the actuator routines to be overwritten with a user-prescribed value. This feature becomes active when the prescribed value is non-negative. .. input_param:: Actuator.FixedWingLine.active_force_dirs **type:** List of 3 real numbers, optional, default = 1.0 1.0 1.0 By default, the actuator force is computed and applied in every coordinate direction. This input allows actuator force coordinate directions to be deactivated by specifying a 0.0 in for the x, y, or z component of this vector. Prescribed actuator motion """""""""""""""""""""""""" ``ActuatorSector`` and ``Drone`` support constant or time-dependent rigid-body motion. Timetable files are whitespace-delimited text files. The first line is a header and each subsequent line begins with time in seconds. Times must be strictly increasing. Values are linearly interpolated; velocity histories are integrated with the corresponding piecewise-linear, trapezoidal rule. Translation must be specified using no more than one of ``translation_velocity``, ``velocity_timetable``, and ``position_timetable``. When a velocity source is used, ``center`` is the position at time zero. ``center`` must not be combined with ``position_timetable`` because the position history supplies the complete position. Similarly, orientation must be specified using no more than one of a constant angular velocity, ``angular_velocity_timetable``, and ``orientation_timetable``. Angular velocities are expressed in the global frame; this is currently the only supported angular-velocity frame. For example, a position history has three coordinates in meters:: Time X Y Z 0.0 0.0 0.0 1.0 1.0 0.0 0.0 2.0 The recommended orientation format is roll, pitch, and yaw in degrees:: Time Roll Pitch Yaw 0.0 0.0 0.0 0.0 1.0 0.0 5.0 10.0 These angles define the body-to-global rotation ``Rz(yaw) Ry(pitch) Rx(roll)``. A quaternion history is also supported using scalar-first ``W X Y Z`` unit quaternions. Input quaternions are normalized before they are interpolated. Both orientation formats are interpolated with quaternion spherical linear interpolation. .. input_param:: Actuator.ActuatorSector.position_timetable **type:** String, optional File containing ``Time X Y Z``, where position is in meters in the global frame. .. input_param:: Actuator.ActuatorSector.velocity_timetable **type:** String, optional File containing ``Time U V W``, where translational velocity is in m/s in the global frame. ``center`` is required and supplies the initial position. .. input_param:: Actuator.ActuatorSector.orientation_timetable **type:** String, optional File containing either ``Time Roll Pitch Yaw`` in degrees or ``Time W X Y Z``, as selected by ``orientation_format``. .. input_param:: Actuator.ActuatorSector.orientation_format **type:** String, optional, default = ``roll_pitch_yaw`` Format of ``orientation_timetable``. Valid values are ``roll_pitch_yaw`` and ``quaternion``. .. input_param:: Actuator.ActuatorSector.angular_velocity_timetable **type:** String, optional File containing ``Time OmegaX OmegaY OmegaZ``, where angular velocity is in rad/s in the global frame. .. input_param:: Actuator.ActuatorSector.angular_velocity_frame **type:** String, optional, default = ``global`` Coordinate frame for constant and tabulated body angular velocity. Only ``global`` is currently supported. .. input_param:: Actuator.ActuatorSector.rotor_speed_timetable **type:** String, optional Rotor-speed history in rad/s. For ``ActuatorSector`` the file contains ``Time Omega`` and replaces ``omega``. For ``Drone`` it contains one angular-speed column per rotor and replaces ``rotor_omegas``. Rotor azimuth is obtained by integrating this history. .. input_param:: Actuator.ActuatorSector.initial_azimuth_degrees **type:** Real number, optional, default = 0.0 Initial blade azimuth in degrees. A Drone accepts either one value shared by every rotor or ``num_rotors`` values. .. input_param:: Actuator.ActuatorSector.timetable_extrapolation **type:** String, optional, default = ``hold`` Behavior outside a timetable's time range. ``hold`` holds the nearest endpoint value and prints a warning the first time each bound is crossed. ``error`` terminates the simulation instead. ActuatorSector """""""""""""" The ``ActuatorSector`` model represents rotating blades by computing blade loads at the midpoint blade locations and sweeping those loads through the time step during Gaussian projection. If the time step is small enough, the adaptive swept quadrature uses one point per radial station and the model naturally reduces to an actuator-line-like projection. Example for ``ActuatorSector``:: incflo.physics = FreeStream Actuator ICNS.source_terms = ActuatorForcing Actuator.labels = R1 Actuator.type = ActuatorSector Actuator.ActuatorSector.rotor_diameter = 0.10 Actuator.ActuatorSector.root_radius_fraction = 0.18 Actuator.ActuatorSector.num_blades = 2 Actuator.ActuatorSector.omega = 2500.0 Actuator.ActuatorSector.center = 0.0 0.0 0.0 Actuator.ActuatorSector.translation_velocity = 0.0 0.0 0.0 Actuator.ActuatorSector.rotor_normal = 1.0 0.0 0.0 Actuator.ActuatorSector.rotor_rotation_degrees_per_revolution = 0.0 2.0 0.0 Actuator.ActuatorSector.epsilon_chord = 0.5 Actuator.ActuatorSector.epsilon_dr = 1.5 Actuator.ActuatorSector.epsilon_dl = 1.5 Actuator.ActuatorSector.min_chord_dr = 2.0 Actuator.ActuatorSector.span_locs = 0.0 1.0 Actuator.ActuatorSector.chord = 0.01 0.006 Actuator.ActuatorSector.twist = 12.0 4.0 Actuator.ActuatorSector.airfoil_table = airfoil.txt Actuator.ActuatorSector.airfoil_type = openfast Actuator.ActuatorSector.gaussian_type = table Actuator.ActuatorSector.gaussian_table_error = 1.0e-4 Actuator.ActuatorSector.output_frequency = 1 .. input_param:: Actuator.ActuatorSector.rotor_diameter **type:** Real number, mandatory Rotor diameter in meters. .. input_param:: Actuator.ActuatorSector.root_radius_fraction **type:** Real number, optional, default = 0.18 Inboard cutoff radius divided by rotor radius. The generated radial grid covers ``root_radius_fraction * rotor_radius <= r <= rotor_radius``. .. input_param:: Actuator.ActuatorSector.num_blades **type:** int, optional, default = 2 Number of rotor blades. .. input_param:: Actuator.ActuatorSector.omega **type:** Real number, mandatory Rotor angular speed in rad/s. Positive values follow the clockwise-positive blade convention used by the actuator-sector theory. .. input_param:: Actuator.ActuatorSector.center **type:** List of 3 real numbers, optional, default = 0.0 0.0 0.0 Initial rotor hub center in meters in the global frame. .. input_param:: Actuator.ActuatorSector.translation_velocity **type:** List of 3 real numbers, optional, default = 0.0 0.0 0.0 Prescribed drone/body translational velocity in m/s in the global frame. .. input_param:: Actuator.ActuatorSector.rotor_normal **type:** List of 3 real numbers, optional, default = 1.0 0.0 0.0 Initial rotor-axis normal direction in the fixed frame. The vector is normalized internally and must be nonzero. The default places the rotor disk in the fixed-frame y-z plane, with the rotor normal pointing along +x. .. input_param:: Actuator.ActuatorSector.rotor_rotation_degrees_per_revolution **type:** List of 3 real numbers, optional, default = 0.0 0.0 0.0 Prescribed rotor-frame/body rotation rate in fixed-frame XYZ degrees per blade revolution. This is converted to ``rotor_angular_velocity`` internally using ``omega``. For example, the vector ``0.0 2.0 0.0`` rotates the rotor normal about fixed-frame y by two degrees per blade revolution. .. input_param:: Actuator.ActuatorSector.rotor_angular_velocity **type:** List of 3 real numbers, optional Rotor-frame/body angular velocity in rad/s in the global frame. If specified, this overrides ``rotor_rotation_degrees_per_revolution``. .. input_param:: Actuator.ActuatorSector.epsilon **type:** Real number, optional Fixed Gaussian width in meters. At least one of ``epsilon`` or ``epsilon_chord`` must be specified. When ``epsilon`` is specified, the same constant width is used at every radial station. If both ``epsilon`` and ``epsilon_chord`` are specified, ``epsilon`` takes precedence and a warning is printed. .. input_param:: Actuator.ActuatorSector.epsilon_chord **type:** Real number, optional Gaussian width divided by local chord. At least one of ``epsilon`` or ``epsilon_chord`` must be specified. When ``epsilon_chord`` is used, the local Gaussian width is ``max(epsilon_min, epsilon_chord * chord)``. .. input_param:: Actuator.ActuatorSector.epsilon_min **type:** Real number, optional, default = 0.0 Minimum Gaussian width in meters when using ``epsilon_chord``. This value is ignored when constant ``epsilon`` is specified. .. input_param:: Actuator.ActuatorSector.epsilon_dr **type:** Real number, optional, default = 1.5 Radial grid requirement. The radial grid is built automatically so that ``epsilon / dr >= epsilon_dr``. Users do not specify the number of radial stations directly; it is derived from the local smoothing width, chord, and rotor radius. .. input_param:: Actuator.ActuatorSector.epsilon_dl **type:** Real number, optional, default = 1.5 Swept arc length requirement. Swept quadrature is selected automatically so that ``epsilon / dl >= epsilon_dl`` over the rotor sweep in the current timestep. When the timestep is sufficiently small, each radial station uses one swept point and the projection reduces to an actuator-line-like limit. .. note:: The actuator-sector model is intended to permit larger timesteps than a conventional actuator-line representation of a rotating blade. The swept forcing sector is set by the CFD timestep, ``delta_theta = omega * dt``, so increasing ``dt`` increases the azimuthal sector covered during each force update. In practice, the timestep is still limited by the CFD stability constraint. Users may often run sector-model cases with a larger CFL number than an actuator-line case, but the final timestep will depend on the mesh spacing, resolved and induced velocities, solver settings, and boundary conditions. If the CFD timestep becomes small, for example after grid refinement, the swept sector narrows and the model naturally approaches the actuator-line limit. .. input_param:: Actuator.ActuatorSector.min_chord_dr **type:** Real number, optional, default = 2.0 Additional radial grid requirement. The radial grid also satisfies ``chord / dr >= min_chord_dr``. .. input_param:: Actuator.ActuatorSector.span_locs **type:** List of real numbers, optional, default = 0.0 1.0 Non-dimensional radial locations for chord and twist interpolation. .. input_param:: Actuator.ActuatorSector.chord **type:** List of real numbers, optional, default = 1.0 1.0 Chord distribution in meters at ``span_locs``. .. input_param:: Actuator.ActuatorSector.twist **type:** List of real numbers, optional, default = 0.0 0.0 Twist distribution in degrees at ``span_locs``. .. input_param:: Actuator.ActuatorSector.airfoil_table **type:** String, mandatory Airfoil lookup table. The same loader as ``FixedWingLine`` is used. .. input_param:: Actuator.ActuatorSector.airfoil_type **type:** String, optional, default = ``openfast`` Airfoil lookup table format. The currently supported options are the same as for ``FixedWingLine``. .. input_param:: Actuator.ActuatorSector.support_radius_over_epsilon **type:** Real number, optional, default = 3.0 Compact Gaussian support radius divided by the local Gaussian width. Force contributions are ignored outside this radius. .. input_param:: Actuator.ActuatorSector.radial_quadrature **type:** String, optional, default = ``midpoint`` Radial quadrature rule used to place blade-section force points. The current implementation supports ``midpoint``. .. input_param:: Actuator.ActuatorSector.swept_quadrature **type:** String, optional, default = ``midpoint`` Swept-sector quadrature rule used to distribute the blade-section force through the timestep. The current implementation supports ``midpoint``. .. input_param:: Actuator.ActuatorSector.gaussian_type **type:** String, optional, default = ``direct`` Gaussian evaluation mode. Valid options are ``direct`` and ``table``. The table mode interpolates the normalized ``exp(-r^2)`` kernel. .. input_param:: Actuator.ActuatorSector.gaussian_table_error **type:** Real number, optional, default = ``1.0e-4`` Maximum absolute interpolation error for the tabulated ``exp(-x)`` Gaussian kernel, where ``x = (r / epsilon)^2``. The code derives the number of table intervals from the linear interpolation error bound over ``0 <= x <= support_radius_over_epsilon^2``. .. input_param:: Actuator.ActuatorSector.output_frequency **type:** int, optional, default = 1 Blade-load NetCDF output interval in timesteps. The output is written under ``post_processing/actuatorXXXXX/