Inputs

All keys start with erf.moving_bodies.. Per-body keys sit under erf.moving_bodies.<name>., one block per name in bodies. The tables give the key without the prefix.

General rules:

• erf.structures.model = gale turns the bodies on. Without it the keys are ignored, and amrex.parmparse.verbose = 1 lists them as unused. With it, bodies must be set.

• Every value is range-checked at start-up. The run stops, naming the key, when one is out of range or not finite.

• A key the chosen options do not use gives a warning. One exception aborts: epsilon_tower or epsilon_nacelle given while the tower or nacelle switch is not set at all.

• A restart must keep every key that places or forces a body. A change stops the run, naming the key. A key the body does not use may change: nacelle_area without nacelle_cd, and correction_time with a fixed correction_relax.

• Run requirements (solver, time step, levels, traps) are in Limitations.

• Every key is also in one annotated deck, Master reference deck.

Bodies

Key	Description	Values	Default
bodies	Names of the bodies.	strings	required
<name>.type	Kind of body.	openfast_turbine, ct_disk	required
<name>.base_pos	Tower base x, y, z (m). On a terrain-fitted mesh z is the height above the surface; 0 puts the base on the ground.	3 reals	required
<name>.output_root	Prefix of the body’s log files. Must be unique.	string	<diagnostics_dir>/<name>
<name>.air_density	Density (kg/m³) used in the ct_disk thrust, nacelle drag, FLLC and corrected disk. Must equal the model’s AirDens.	> 0	1.225

OpenFAST turbine

Key	Description	Values	Default
<name>.fst_file	OpenFAST primary file. See the four settings it must hold.	string	required
<name>.mode	How loads reach the flow: as rings (disk), from the moving blade nodes (line), or not at all (one-way).	adm, alm, none	adm
<name>.num_force_points_blade	Force points per blade.	int > 0 (≥ 2 with FLLC)	50
<name>.num_force_points_tower	Tower force points. 0 puts no tower force in the flow.	int ≥ 0	0
<name>.nacelle_cd	Drag coefficient of a nacelle drag point at the hub. 0 is off.	≥ 0	0
<name>.nacelle_area	Nacelle frontal area (m²). Must be positive when nacelle_cd is.	≥ 0	0

Kernel widths

Widths are in cells of the anchor level’s x spacing. See Tower, nacelle and kernel widths for how to choose them.

Key	Description	Values	Default
<name>.epsilon	Width of the rotor’s points (line nodes, disk rings, ct_disk points). Not with fllc = automatic, which sets it.	> 0	2.0
<name>.epsilon_tower	Width of the tower force points.	> 0	epsilon
<name>.epsilon_nacelle	Width of the nacelle point. nacelle_cd × nacelle_area must not exceed \(2\pi\,\epsilon_{nacelle}^2\) (in metres).	> 0	epsilon

Actuator disk

For mode = adm.

Key	Description	Values	Default
<name>.num_points_t	Points per ring.	int ≥ 2	16
<name>.adm_spreading	One ring per blade node, or one shared ring per radial station.	rings, merged_rings	rings
<name>.sampling	Where the velocity handed to OpenFAST comes from. See Actuator disk.	disk, upstream, disk_corrected	disk_corrected (adm), disk (alm, none)
<name>.sample_diameters_upstream	Distance ahead of the hub, in diameters, for upstream sampling (and ct_disk).	> 0	2.0 (turbine), 1.0 (ct_disk)
<name>.correction_relax	Under-relaxation of the recovered free stream. −1 chooses it from the loop gain; 1 is the unrelaxed update.	−1, or (0, 1]	−1
<name>.correction_time	Decay time (s) of a free-stream error with correction_relax = −1. −1 is rotor radius over free stream; 0 is none.	−1, 0, or > 0	−1

Actuator line

For mode = alm. FLLC is the filtered lifting-line correction.

Key	Description	Values	Default
<name>.fllc	Turns the FLLC on. automatic also sets epsilon (0.035 D), fllc_eps_chord (0.15), fllc_eps_dr (3), fllc_start_time (5 s) and 300 blade points. Giving any of them with automatic aborts.	true, false, automatic	true (alm), false (adm, none)
<name>.fllc_relax	Relaxation factor of the correction.	(0, 1]	0.1
<name>.fllc_start_time	Simulation time (s) from which the correction applies. This is ERF’s time, not time since the bodies started.	≥ 0	0
<name>.fllc_eps_chord	Optimal kernel width, in chords.	> 0	0.25
<name>.fllc_eps_dr	Span grid spacing is optimal width / fllc_eps_dr.	> 0	1.0
alm_max_tip_cells	Most cells a blade tip may sweep per step. Above it the run stops and names the largest erf.fixed_dt that passes.	> 0	1.0

Prescribed-Ct disk

For type = ct_disk. num_points_t, sample_diameters_upstream and air_density also apply.

Key	Description	Values	Default
<name>.turbine	Name of a turbine table, <turbine_data_dir>/<name>.txt (NREL_5MW_126, say; the list is in Turbines/Data/PowerCurves/README.md). The radius is half the table’s rotor diameter, and Ct is the table’s Ct(U) at the upstream speed, zero outside the table. The table’s Ct values must lie in [0, 2]. Not with ct or rotor_radius.	table name	unset
<name>.rotor_radius	Disk radius (m). Not with turbine.	> 0	required without turbine
<name>.hub_height	Disk centre above the base (m). With turbine, overrides the table’s; required when the table gives no single hub height.	> rotor_radius	required (table’s with turbine)
<name>.ct	Thrust coefficient on the upstream speed. Not with turbine.	(0, 1)	required without turbine
<name>.yaw	Disk normal, degrees from +x in the horizontal plane.	real	0
<name>.num_points_r	Rings of the polar point grid.	int > 0	8

Run-wide

Key	Description	Values	Default
anchor_level	Level the bodies live on. −1 is amr.max_level.	−1 to amr.max_level	−1
density_tolerance	Allowed relative difference between ERF’s density at a hub (or disk centre) and the model’s.	≥ 0	0.05
turbine_data_dir	Folder of the turbine tables a ct_disk’s turbine names. A relative path is relative to the run directory. An executable moved away from its source tree needs this key. Warned about when no ct_disk names a turbine.	path	Turbines/Data/PowerCurves of the GALE source tree
prescribed_velocity	Testing aid: a uniform velocity given to every node in place of the flow.	3 reals	unset

Diagnostics

Key	Description	Values	Default
diagnostics_int	Steps between log rows.	int > 0	1
diagnostics_dir	Folder of the logs.	string	moving_bodies
diagnostics_format	One file per body, per rank, or per farm.	per_turbine, per_rank, farm	per_turbine
avg_start	Simulation time (s) from which statistics and wake averages accumulate.	≥ 0	0
stats_int	Steps between rewrites of the statistics and wake averages. 0 rewrites them at every write.	int ≥ 0	0
max_open_logs	Most log files a rank keeps open. 0 takes a quarter of the open-file limit.	int ≥ 0	0
timing_int	Steps between timing summaries per phase. 0 is off.	int ≥ 0	0

Wake lines

Lines behind every rotor: one horizontal and one vertical at each distance.

Key	Description	Values	Default
wake.lines_xD	Distances behind the rotor, in diameters.	reals > 0	unset (no lines)
wake.half_width	Half-length of each line, in diameters.	> 0	1.5
wake.num_points	Points per line.	int ≥ 2	61
wake.int	Steps between samples. 0 uses diagnostics_int.	int ≥ 0	diagnostics_int

Debugging and performance

Key	Description	Values	Default
envelope_check_interval	Steps between the collective check of the exchange envelopes. Between checks each owner checks its own points and aborts if they leave.	int ≥ 1	1
verify_tip_cells	Checks the cached tip-travel cell heights against a fresh search every step.	true, false	false

Master reference deck

Exec/CanonicalTests/MovingBodies/inputs_gale_master_reference lists every GALE key in one file, with its default, range and units, grouped as above. Copy the lines a case needs. It is a reference, not a runnable case: some keys in it exclude each other.

inputs_gale_master_reference

# GALE master input reference
#
# Every GALE input, with its default, range and units. GALE's inputs are erf.structures.model and
# the erf.moving_bodies.* keys. ERF's own inputs (mesh, solver, boundaries) are not listed here;
# see the ERF documentation.
#
# This is a reference, not a runnable case. Some keys exclude each other; each one says which.
# Runnable decks are in the folders next to this file.
#
# Conventions:
#   - The value shown is the default. "required" means there is none.
#   - Every value is range-checked at start-up. The run stops, naming the key, when one is out of
#     range or not finite.
#   - A key the chosen options do not use prints a warning.
#   - A restart must keep every key that places or forces a body; a change stops the run. Keys a
#     body does not use are not compared: nacelle_area without nacelle_cd, correction_time with a
#     fixed correction_relax.
#   - Kernel widths (epsilon*) are in cells of the anchor level's x spacing.
#
# Kept in sync with MovingBodiesInputs::read (Turbines/ERF_MovingBodiesInputs.cpp) and
# Docs/sphinx_doc/Inputs.rst.

# =================================================================================================
# 1. Turning GALE on
# =================================================================================================
erf.structures.model     = gale       # selects GALE; without it the keys below are ignored
erf.moving_bodies.bodies = T1 D1      # required: body names, one block per name (no duplicates)

# =================================================================================================
# 2. Every body (openfast_turbine and ct_disk)
# =================================================================================================
erf.moving_bodies.T1.type        = openfast_turbine  # required: openfast_turbine | ct_disk
erf.moving_bodies.T1.base_pos    = 750. 600. 0.      # required: tower base x y z (m); on a terrain-
                                                     #   fitted mesh z is the height above the surface
erf.moving_bodies.T1.epsilon     = 2.0               # > 0 (cells): width of the rotor's points.
                                                     #   Excludes fllc = automatic, which sets it
erf.moving_bodies.T1.output_root = moving_bodies/T1  # log-file prefix; default <diagnostics_dir>/<name>;
                                                     #   must differ between bodies
erf.moving_bodies.T1.num_points_t = 16               # >= 2: points per ring (mode = adm, ct_disk)
erf.moving_bodies.T1.air_density = 1.225             # > 0 (kg/m^3): must equal the model's AirDens;
                                                     #   checked against ERF's density at the hub
erf.moving_bodies.T1.sample_diameters_upstream = 2.0 # > 0 (rotor diameters ahead of the hub);
                                                     #   default 2.0 for a turbine (sampling = upstream),
                                                     #   1.0 for a ct_disk

# =================================================================================================
# 3. OpenFAST turbine (type = openfast_turbine)
# =================================================================================================
# The OpenFAST model must set CompInflow = 2; AirDens = air_density; Wake_Mod = 0 with sampling = disk
# (and mode = alm), 1 with upstream or disk_corrected; TwrShadow = 0 when tower force points are on.
erf.moving_bodies.T1.fst_file = IEA15-land.fst     # required: OpenFAST primary file
erf.moving_bodies.T1.mode     = adm                # adm (disk rings) | alm (actuator line) |
                                                   #   none (one-way: no force into the flow)
erf.moving_bodies.T1.num_force_points_blade = 50   # >= 1 (>= 2 with fllc): force points per blade.
                                                   #   Excludes fllc = automatic (300)
erf.moving_bodies.T1.num_force_points_tower = 0    # >= 0: tower force points; 0 = no tower force
erf.moving_bodies.T1.nacelle_cd   = 0.0            # >= 0: nacelle drag coefficient; 0 = off
erf.moving_bodies.T1.nacelle_area = 0.0            # >= 0 (m^2): must be > 0 when nacelle_cd > 0

# --- 3a. Component kernel widths -----------------------------------------------------------------
erf.moving_bodies.T1.epsilon_tower   = 2.0         # > 0 (cells); default epsilon. Aborts when given
                                                   #   and num_force_points_tower was never set
erf.moving_bodies.T1.epsilon_nacelle = 2.0         # > 0 (cells); default epsilon. Aborts when given
                                                   #   and nacelle_cd was never set; nacelle_cd *
                                                   #   nacelle_area must not exceed 2 pi eps^2 (m)

# --- 3b. Actuator disk (mode = adm) --------------------------------------------------------------
erf.moving_bodies.T1.adm_spreading = rings         # rings (one per blade node) | merged_rings (one
                                                   #   per radial station)
erf.moving_bodies.T1.sampling = disk_corrected     # disk | upstream | disk_corrected; default
                                                   #   disk_corrected (adm), disk (alm, none);
                                                   #   upstream and disk_corrected need mode = adm
erf.moving_bodies.T1.correction_relax = -1         # disk_corrected: -1 (from the loop gain) or (0, 1];
                                                   #   1 = unrelaxed update
erf.moving_bodies.T1.correction_time  = -1         # disk_corrected with correction_relax = -1 (s):
                                                   #   -1 = rotor radius / free stream; 0 = none; or > 0

# --- 3c. Actuator line (mode = alm) --------------------------------------------------------------
erf.moving_bodies.T1.fllc = true                   # true | false | automatic; default true (alm),
                                                   #   false otherwise; needs mode = alm.
                                                   #   automatic sets epsilon = 0.035 D,
                                                   #   fllc_eps_chord = 0.15, fllc_eps_dr = 3,
                                                   #   fllc_start_time = 5 s, num_force_points_blade
                                                   #   = 300; giving any of those with it aborts
erf.moving_bodies.T1.fllc_relax      = 0.1         # (0, 1]: relaxation of the correction
erf.moving_bodies.T1.fllc_start_time = 0.0         # >= 0 (s, simulation time). Excludes automatic
erf.moving_bodies.T1.fllc_eps_chord  = 0.25        # > 0 (chords): optimal kernel width. Excludes automatic
erf.moving_bodies.T1.fllc_eps_dr     = 1.0         # > 0: span spacing = optimal width / fllc_eps_dr.
                                                   #   Excludes automatic

# =================================================================================================
# 4. Prescribed-Ct disk (type = ct_disk)
# =================================================================================================
# Also uses base_pos, epsilon, output_root, num_points_t, air_density, sample_diameters_upstream
# (section 2). OpenFAST keys given for a ct_disk print a warning.
erf.moving_bodies.D1.type         = ct_disk
erf.moving_bodies.D1.base_pos     = 1500. 600. 0.
erf.moving_bodies.D1.rotor_radius = 120.           # required without turbine, > 0 (m)
erf.moving_bodies.D1.hub_height   = 150.           # required, > rotor_radius (m above the base);
                                                   #   with turbine, the table's unless given, and
                                                   #   required when the table gives no single one
erf.moving_bodies.D1.ct           = 0.75           # required without turbine, in (0, 1): thrust
                                                   #   coefficient on the upstream speed
erf.moving_bodies.D2.type         = ct_disk
erf.moving_bodies.D2.base_pos     = 2500. 600. 0.
erf.moving_bodies.D2.turbine      = NREL_5MW_126   # unset by default: name of a table in
                                                   #   turbine_data_dir; rotor_radius = D/2 and Ct(U)
                                                   #   come from it; excludes ct and rotor_radius
erf.moving_bodies.D1.yaw          = 0.0            # degrees from +x in the horizontal plane
erf.moving_bodies.D1.num_points_r = 8              # >= 1: rings of the polar point grid

# =================================================================================================
# 5. Run-wide
# =================================================================================================
erf.moving_bodies.anchor_level      = -1           # level the bodies live on; -1 = amr.max_level;
                                                   #   otherwise 0 .. amr.max_level
erf.moving_bodies.density_tolerance = 0.05         # >= 0 (relative): ERF's density at a hub vs the
                                                   #   model's
erf.moving_bodies.alm_max_tip_cells = 1.0          # > 0: most cells a blade tip may sweep per step;
                                                   #   the abort names the largest erf.fixed_dt
                                                   #   that passes
erf.moving_bodies.turbine_data_dir  = Turbines/Data/PowerCurves  # folder of the turbine tables;
                                                   #   default: that folder of the GALE source tree
                                                   #   (build-time path); relative = from the run
                                                   #   directory
erf.moving_bodies.prescribed_velocity = 10. 0. 0.  # testing aid, unset by default: uniform velocity
                                                   #   given to every node in place of the flow;
                                                   #   no wake lines are then written

# =================================================================================================
# 6. Diagnostics and statistics
# =================================================================================================
erf.moving_bodies.diagnostics_int    = 1           # >= 1 (steps between log rows)
erf.moving_bodies.diagnostics_dir    = moving_bodies
erf.moving_bodies.diagnostics_format = per_turbine # per_turbine | per_rank | farm
erf.moving_bodies.avg_start          = 0.0         # >= 0 (s): statistics and wake averages start here
erf.moving_bodies.stats_int          = 0           # >= 0 (steps between rewrites of _stats and
                                                   #   _wake_avg); 0 = at every write
erf.moving_bodies.max_open_logs      = 0           # >= 0: log files a rank keeps open; 0 = a quarter
                                                   #   of the open-file limit
erf.moving_bodies.timing_int         = 0           # >= 0 (steps between timing summaries); 0 = off

# =================================================================================================
# 7. Wake lines (behind every rotor)
# =================================================================================================
erf.moving_bodies.wake.lines_xD   = 2 4 7          # > 0 (rotor diameters behind the rotor); unset =
                                                   #   no lines
erf.moving_bodies.wake.half_width = 1.5            # > 0 (rotor diameters): half-length of each line
erf.moving_bodies.wake.num_points = 61             # >= 2: points per line
erf.moving_bodies.wake.int        = 0              # >= 0 (steps between samples); 0 = diagnostics_int

# =================================================================================================
# 8. Debugging and performance
# =================================================================================================
erf.moving_bodies.envelope_check_interval = 1      # >= 1 (steps between collective envelope checks)
erf.moving_bodies.verify_tip_cells        = false  # true: check cached tip-travel cell heights
                                                   #   against a fresh search every step (alm)