Input reference

This page lists every input of GUST. The first table is a quick reference; the sections after it give the allowed range and meaning of each input, grouped by namespace.

The same keys, with their defaults and the text of the detailed tables, are in Tests/inputs_reference: a commented file to copy lines from into a deck. It is generated from this page (tools/input_reference.py --write); the CTest input_reference_current fails when the two differ, or when this page and the keys read in Source/ disagree.

Input file format

An input file has one input per line, namespace.key = value. Lists are separated by spaces, and # starts a comment:

mesh.n_cell  = 64 64 32     # cells in x, y, z
bc.zlo       = surface_layer

Inputs can also be given on the command line after the input file (Running a simulation).

The run stops before doing any work, naming the input, when:

  • a key is misspelled or not used by this version;

  • a key’s namespace is unknown (the AMReX namespaces amrex, fab, fabarray, vismf, tiny_profiler, DistributionMapping, device and hypre are allowed);

  • a key is given twice, or a single-value key is given several values;

  • a value is outside its range;

  • a key has no effect with the other inputs (for example terrain.hill_height with terrain.type = flat).

All errors are reported together.

Quick reference

Input

Default

Description

Mesh (mesh)

mesh.n_cell

required

Number of cells in x, y, z

mesh.prob_lo

0 0 0

Low corner of the domain (m)

mesh.prob_hi

required

High corner of the domain (m)

mesh.is_periodic

0 0 0

Periodic directions

mesh.max_grid_size

64

Largest box size in x and y

mesh.dz0

0

First layer thickness of a stretched grid (m)

mesh.stretch_ratio

none

Fixed ratio between successive layers

mesh.zlevels_file

none

File with the vertical levels

mesh.hierarchy_levels

1

Number of grid-hierarchy levels

Terrain (terrain)

terrain.type

flat

Terrain source

terrain.file

none

Terrain file

terrain.smoothing

1

Terrain-following mapping (0 BTF, 1 STF, 2 Sullivan)

terrain.gamma_m

0.5

Smallest layer thickness under STF, relative to flat

terrain.hill_height

required for agnesi

Hill height (m)

terrain.hill_half_width

required for agnesi

Hill half-width (m)

terrain.hill_shape

ridge_x

Ridge or round hill

terrain.idw_neighbors

6

Points used per height for xyz terrain

terrain.idw_power

2

Inverse-distance weight exponent

terrain.hierarchy_passes

1

Terrain smoothing on coarse hierarchy levels

Initial conditions (init)

init.first_guess

none

Initial profile: none, profile or column

init.projection

1

Mass-consistent adjustment on or off

init.alpha_h, init.alpha_v

1, 1

Horizontal and vertical transmissivity

init.z_agl_min

0

Lowest height at which the profile is evaluated (m)

init.k_decay_height

0

Height above which the initial TKE decays (m)

init.obrien

0

O’Brien vertical-velocity correction

init.column_tol

1e-8

Convergence tolerance of the single-column solve

init.column_max_iterations

5000

Step limit of the single-column solve

init.column_stability, column_mol, column_surface_theta

mol, 0, 0

The column’s surface: Obukhov length (0: neutral, θ held), heat flux or surface θ

init.column_target_u, column_target_v, column_target_height

0, 0, 0

Target wind of the column: the forcing is adjusted to reach it (0: off)

init.column_rib_max, column_rib_min

4, -4

Bounds of the bulk Richardson number at the stratified column’s surface

init.column_time, column_dt

0, 1

The time-marching column: end time and step (s; 0: the steady column)

init.column_wall_k

fixed

The time-marching column’s first-cell k: the wall value or solved

Boundary conditions (bc)

bc.xlo … bc.yhi

periodic

Side boundary types

bc.zlo

surface_layer

Ground boundary type

bc.zhi

slip_wall

Top boundary type

bc.<face>_wall_velocity

0 0 0

Velocity of a no-slip wall (m/s)

bc.inflow_profile

log_law

Inflow profile type

bc.inflow_ustar, bc.inflow_z0

0.4 m/s, 0.1 m

Log-law friction velocity and roughness

bc.inflow_speed, bc.inflow_zref, bc.inflow_alpha

10 m/s, 10 m, 0.14

Power-law speed, reference height and exponent

bc.inflow_direction

0

Wind direction (degrees from the x axis)

bc.inflow_file

none

Tabulated inflow profile

bc.inflow_tke_length

closure

Length of the inflow profile’s equilibrium \(k\) and \(\nu_t\)

bc.theta_profile_z, bc.theta_profile

0, 300

Potential-temperature sounding (m, K)

bc.zhi_theta_grad

0

θ gradient through the top (K/m)

bc.rayleigh_zdamp, bc.rayleigh_dampcoef

0, 0

Rayleigh layer start height (m) and strength (1/s)

bc.rayleigh_fields

u v w theta tke

Fields the Rayleigh layer damps

bc.rayleigh_height

absolute

Height used by the Rayleigh layer

bc.sponge_width, bc.sponge_strength

0, 0

Side sponge width (m) and strength (1/s)

bc.outflow_transport

mirror

Transport fluxes of the ghost cells outside outflow faces

bc.surface_z0

0.1 m

Ground roughness length

bc.surface_z0_file

none

Ground roughness map, x y z0 points (instead of bc.surface_z0)

bc.surface_zref

0

Wall-model reference height (0: first cell centre)

bc.surface_stability

neutral

neutral or heat_flux

bc.surface_heat_flux

0

Kinematic surface heat flux (K m/s)

bc.surface_wall_k

dirichlet

Wall treatment of the TKE

bc.surface_denominator_floor

log_law

Floor of the MOST denominator

bc.surface_stable_functions

businger_dyer

Stable-side MOST functions: businger_dyer or qnse

bc.surface_qnse_am, _bm, _ah, _bh

2.5, 0.2, 2.5, 0.2

QNSE coefficients

Forest canopy (canopy)

canopy.type

none

none, patches (ERF’s patch file) or map (point maps)

canopy.file

required for patches

Patch file, type x y height diameter cd lai laimax per line

canopy.height_file, canopy.lai_file

required for map

Canopy height (m) and leaf area index, x y value points

canopy.cd, canopy.cd_file

one required for map

Drag coefficient: one value or x y value points

canopy.profile

uniform

Leaf area density shape: uniform or lalic_mihailovic

canopy.laimax

0.8

Height of the largest leaf area density, as a fraction of the canopy height

canopy.drag_diagonal

derivative

Implicit drag term on the momentum diagonal: derivative, picard or none

canopy.tke

on

Canopy terms of the k–L closure: wake production, short-circuit sink, length cap

canopy.beta_p, canopy.beta_d, canopy.length_alpha

1, 4, 0.04

Wake production fraction, short-circuit coefficient, length cap \(L \le \alpha/f\)

Buildings (buildings)

buildings.type

none

none or immersed_forcing

buildings.file

required when on

Height map, heights above the local ground (m)

buildings.format

erf

erf (ERF’s text layout) or xyz (x y height [zstart] lines)

buildings.small_volfrac

0.005

Solid fractions within this of 0 or 1 become 0 or 1

buildings.z0

0.1

Roughness of the wall law on buildings and, with buildings.wall_tke = on, of the closure’s length beside their walls (m)

buildings.wall_form

fraction_stress

fraction_stress (form 7 wall law on every wall), roof_stress (on roofs and undersides alone) or drag (fixed rows alone)

buildings.wall_speed

open_faces with fraction_stress, all_faces with roof_stress

The wall law’s speed in a cell from its faces that are not fixed rows (open_faces) or from every face (all_faces)

buildings.wall_tke

on with fraction_stress, else off

The closure sees the buildings: wall value of k, solid cells at the floor, distance to buildings in the length scale

buildings.theta_mode

ambient with fraction_stress, else none

How theta meets a building: no terms, or walls at the reference profile’s or a given temperature

buildings.theta_surface

none

The walls’ temperature with buildings.theta_mode = fixed (K)

buildings.limiter_zone

3

Zone around each building where turb.realizability and the upwind blend fade out (building heights)

Named set-ups (abl)

abl.drive

none

What pushes the flow: a name that sets defaults and checks the deck

abl.theta

none

How θ is treated: a name that sets defaults and checks the deck

Forcing (forcing)

forcing.gravity

9.81

Gravitational acceleration (m/s²)

forcing.theta0

300

Boussinesq reference temperature (K)

forcing.coriolis

0

Coriolis force on or off

forcing.latitude

0

Latitude (degrees)

forcing.rotation_period

86400

Earth’s rotation period (s)

forcing.coriolis_3d

1

Include the cos(latitude) Coriolis terms

forcing.geostrophic

0

Geostrophic forcing on or off

forcing.ug, forcing.vg

0, 0

Geostrophic wind (m/s)

forcing.pressure_gradient

0 0 0

Constant pressure-gradient force (m/s²)

Turbulence model (turb)

turb.Cmu0

0.5562

Model constant \(C_{\mu 0}\)

turb.Cb

0.35

Model constant \(C_b\)

turb.Rt_crit, turb.Rt_min

-1, -3

Richardson-number smoothing limits

turb.max_geom_lscale

30 m

Cap on the geometric length scale

turb.tke_floor

0

Lower bound on k (0: machine epsilon)

turb.sigma_k

1

TKE diffusion Schmidt number

turb.nu_molecular, turb.alpha_molecular

0, 0

Molecular viscosity and heat diffusivity (m²/s)

turb.kappa

0.41

von Kármán constant

turb.nut_relax

1

Under-relaxation of \(\nu_t\)

turb.frozen_switch

1

Freeze the k-floor decisions in the Newton stage

turb.ri_gate

0

Stratification gate \(Ri_0\) (0: off)

turb.realizability

0

Eddy-viscosity cap \(\nu_t \le C_r k/S\) (0: off; recommended 0.309 for the lee)

turb.face_mean

arithmetic

Face average of the diffusivities

turb.wall_distance

terrain_height

Wall-distance method

Convection (convection)

convection.limiter

van_leer

Slope limiter for momentum and θ

convection.smooth_eps_velocity, convection.smooth_eps_theta

1e-5, 1e-5

Smoothing constants of van_albada

convection.hybrid_sigma_max, hybrid_height, hybrid_relax, hybrid_freeze

0, —, 0.1, 1e-2

Blend towards upwind near the ground where the \(\nu_t\) cap is active (0: off)

Steady solver (steady)

steady.stage

none

none (build and stop), simplec, simplec_newton (SIMPLEC, then Newton), or unsteady (physical time steps, unsteady)

steady.max_iterations

10000

Iteration limit

steady.residual_tol

5e-5

Scaled residual tolerance

steady.residual_drop_orders

4

Required residual drop (orders of magnitude)

steady.residual_ref_iterations

5

Iterations over which the reference residual is taken

steady.confidence, steady.confidence_height

0, 0

Confidence-percentage stop: share of converged cells (0: off), height limit of the others (0: anywhere)

steady.monitor_rel_tol, steady.monitor_window

1e-3, 50

Monitor tolerance and window

steady.cfl0, steady.cfl_max

1, 8 (lusgs) or 10 (zjacobi)

Initial and largest CFL number

steady.ser_exponent, steady.ser_max_growth

1, 2

CFL ramp exponent and largest growth per iteration

steady.dtau_floor

0.1

Local step floor: a cell steps at most as the level’s fastest cell does, 1/dtau_floor times (0: off)

steady.switch_window, steady.switch_residual, steady.switch_back_growth

20, 1e-4, 10

Stage-switching rules (simplec_newton only)

steady.switch_monitor_tol, steady.newton_fallback_failures

1e-2, 2

Monitors settled before the switch to Newton; failed Newton steps before the fallback

steady.newton_cfl_max

128

The Newton stage’s CFL cap

steady.sweep

lusgs (CPU build), zjacobi (GPU build)

Line solver: zjacobi or lusgs

steady.zline_sweeps

2

Sweeps per iteration

steady.line_ghosts, steady.line_overlap

lagged, 0

LU-SGS coupling across box faces

steady.line_order

sequential

LU-SGS visiting order

steady.line_alternate

0

Alternate the LU-SGS sweep direction

steady.sequencing

0

Grid sequencing, coarse to fine

steady.sequencing_drop_orders

2

Residual drop for the loose stop of a coarse level

steady.sequencing_monitor_tol

0

Optional monitor test of the loose stop (0: off)

steady.sequencing_hold

0

Keep the reference hold on the seeded levels

steady.sequencing_cfl_start

cfl0

CFL of a seeded level’s first iteration

steady.machine, steady.nodes

local, 1

Machine and node count for the allocation accounting

steady.newton_*

see steady

Newton–Krylov inputs (simplec_newton only)

steady.newton_preconditioner

simplec

Newton preconditioner: identity or simplec

Unsteady runs (unsteady)

unsteady.stop_time

—

Physical time the run ends at (s); required with steady.stage = unsteady

unsteady.dt, unsteady.cfl

—, 0

Fixed physical step (s), or a target convective CFL for a global step

unsteady.inner_drop_orders, unsteady.max_inner

3, 50

Inner stop of each physical step: residual drop (orders) and iteration limit

unsteady.average_start

0

Physical time the running averages and variances start at (s)

unsteady.plot_interval, unsteady.checkpoint_interval

0, 0

A plotfile, a checkpoint every so many physical steps (0: at the end only)

unsteady.probes_file

—

File of probe points x y h (h above the ground); one CSV row per step

SIMPLEC (simplec)

simplec.pressure_reltol

1e-3

Tolerance of the pressure-correction solve

simplec.alpha_p

1

Pressure under-relaxation

simplec.rotation_relax

0.3

Point-implicit rotation step

simplec.w_vnn_cap

0

Vertical-velocity cap (0: off)

simplec.w_vnn_cap_slope_margin

4

The cap’s safety margin on sloping ground (0: off)

simplec.theta

solve

frozen: θ prescribed from the inflow profile, buoyancy in the closure only

Poisson solver (solver)

solver.poisson_backend

gmres_mlmg

Poisson solver

solver.poisson_reltol, solver.poisson_abstol

1e-10 (1e-5 single), 0

Relative and absolute tolerance

solver.poisson_max_iter

200

Iteration limit

solver.poisson_restart

50

GMRES restart length

solver.poisson_precond

fft

Preconditioner of gmres_fft

solver.poisson_verbose

0

Output level

Input/output (io)

io.plot_file, io.chk_file

plt, chk

Plotfile and checkpoint prefixes

io.write_plotfile, io.write_checkpoint

1, 1

Write the plotfile and checkpoint

io.turb_plot_file

none

Prefix of the turbulence plotfile

io.iteration_log

table

Layout of the per-iteration log

io.column_guess_file

column_guess.dat

File of the converged column’s table

io.restart

none

Checkpoint to restart from

mesh

Input

Default

Range and meaning

mesh.n_cell

required

Three integers ≥ 1: cells in x, y and z.

mesh.prob_lo

0 0 0

Three finite values: the low corner of the domain (m). The z value must be 0.

mesh.prob_hi

required

Three finite values, each greater than prob_lo: the high corner of the domain (m).

mesh.is_periodic

0 0 0

Three values, each 0 or 1. z must be 0.

mesh.max_grid_size

64

One or two integers ≥ 1: the largest box size in x and y. Boxes are never split in z.

mesh.dz0

0

Finite, ≥ 0 (m). First layer thickness of a stretched grid; 0 gives uniform layers. Without mesh.stretch_ratio it must not exceed prob_hi z / n_cell z (Terrain-following coordinates).

mesh.stretch_ratio

none

Finite, ≥ 1; needs mesh.dz0 > 0. A fixed ratio between successive layers; the top is then where the layers end, and prob_hi z only sets the computational spacing.

mesh.zlevels_file

none

A file of n_cell z + 1 increasing heights starting at 0. Not together with mesh.dz0.

mesh.hierarchy_levels

1

Integer from 1 to 10: the levels \(L\) of the grid hierarchy (Grid hierarchy). With \(L > 1\), n_cell and max_grid_size in x and y must be divisible by \(2^{L-1}\), and the coarsest level must be larger than 1 × 1 cells. The box layout of level 0 can then differ from \(L = 1\), which changes results in the last bits. The solver uses the coarse levels only with steady.sequencing = 1. May change across a restart.

terrain

Input

Default

Range and meaning

terrain.type

flat

flat, agnesi (analytic hill), xyz (point cloud) or erf_grid (ERF’s terrain file) (Terrain-following coordinates).

terrain.file

required for xyz, erf_grid

The point file (x y z per line) or ERF’s structured terrain file.

terrain.smoothing

1

0 (BTF), 1 (STF) or 2 (Sullivan).

terrain.gamma_m

0.5

> 0 and < 1; STF only. Smallest layer thickness as a fraction of the flat layer.

terrain.hill_height

required for agnesi

Finite, > 0 (m).

terrain.hill_half_width

required for agnesi

Finite, > 0 (m). Distance from the crest at which the hill is half as high.

terrain.hill_shape

ridge_x

ridge_x (a ridge along y, varying in x), ridge_y or round; agnesi only.

terrain.idw_neighbors

6

≥ 1; xyz, bc.surface_z0_file or canopy.type = map only. Points used for each height (and each column’s \(z_0\) of the roughness map, and the canopy’s maps).

terrain.idw_power

2

Finite, > 0; xyz, bc.surface_z0_file or canopy.type = map only. Weight exponent \(p\) in \(d^{-p}\).

terrain.hierarchy_passes

1

Integer from 0 to 64; only with mesh.hierarchy_levels > 1. The ground of level \(l\) is smoothed by this number times \((2^l - 1)\) passes (Grid hierarchy).

init

See Initial conditions. The keys other than init.first_guess are refused with init.first_guess = none. A restart cannot be combined with init.* keys.

Input

Default

Range and meaning

init.first_guess

none

none (fluid at rest), profile (the inflow profile by height above the ground) or column (the steady single-column profile; needs a horizontal forcing and steady.stage = simplec or simplec_newton, and with a canopy flat terrain and a canopy that is the same in every column; see Initial conditions for the full list).

init.projection

1

0 or 1: the mass-consistent adjustment. With 0, init.alpha_h and init.alpha_v are refused.

init.alpha_h

1

Finite, > 0. Horizontal transmissivity \(\alpha_h\).

init.alpha_v

1

Finite, > 0. Vertical transmissivity \(\alpha_v\). Only \(\alpha_v/\alpha_h\) matters. Ratios below 0.1 need more than the default solver.poisson_max_iter. With \(\alpha_v \ne \alpha_h\) the adjustment uses the gmres_fft back end.

init.z_agl_min

0

Finite, ≥ 0 (m). Lowest height above the ground at which the profile is evaluated.

init.k_decay_height

0

Finite, ≥ 0 (m). Height \(z_i\) above which the initial \(k\) decays; 0: no decay. Not with column.

init.obrien

0

0 or 1. The O’Brien correction of the vertical velocity before the adjustment.

init.column_tol

1e-8

Finite, > 0; column only. Convergence tolerance of the single-column solve: the largest relative change of \(u, v, k\) over a step. Raised to at least 100 machine epsilon (1.2e-5 single, 2.2e-14 double).

init.column_max_iterations

5000

≥ 1; column only. The run stops if a column has not converged after this many steps. The limit applies to each column solved: the surface search and the target wind solve several (the log gives the total).

init.column_stability

mol

mol, heat_flux or surface_temperature; column only. How the column’s surface sets θ (stratified column). heat_flux takes bc.surface_heat_flux and needs bc.surface_stability = heat_flux. Any non-neutral surface needs forcing.gravity > 0 and, in the steady column, a Rayleigh layer on θ (bc.rayleigh_zdamp > 0, theta in bc.rayleigh_fields).

init.column_mol

0

0 (neutral: θ held at the sounding, the column before this input) or finite with |L| ≥ 1 (m); mol only. The Obukhov length L (> 0 stable, < 0 unstable). With bc.surface_stability = heat_flux the 3-D run takes the column’s flux (bc.surface_heat_flux is then refused).

init.column_surface_theta

0

Finite, > 0 (K), required with surface_temperature and only there: the surface potential temperature.

init.column_target_u, init.column_target_v

0, 0

Finite (m/s); column only. A target wind at init.column_target_height: the geostrophic wind and the column’s Rayleigh reference wind are turned and scaled by the ratio of the target to the column’s wind there, the pressure gradient by that ratio times its magnitude, until they agree to 1e-4; the run then uses that forcing. Both 0: off (giving them as 0 is refused). Refused with what would hold the 3-D wind to the deck’s inflow profile: a Rayleigh layer on u and v, a sponge or an inflow face; and with a stratified column unless bc.surface_stability = heat_flux.

init.column_target_height

0

Finite, > 0 (m) with a target wind, and only then: its height above the ground, at most the top cell centre. Below the first cell centre the wind is MOST’s profile; above, linear in \(\ln(z + z_0)\) between centres.

init.column_rib_max

4

Finite, > 0; a stratified column only. The upper bound of the bulk Richardson number of the column’s surface solve (ERF’s value). With Businger–Dyer’s stable functions the bound used is min(init.column_rib_max, 0.19), below their 0.2 limit (stratified column).

init.column_rib_min

-4

Finite, < 0; a stratified column only. The lower bound (ERF’s value). Both bounds are refused with init.column_time > 0 and heat_flux (the flux is given; no bulk Richardson number is solved).

init.column_time

0

Finite, ≥ 0 (s); column only. 0: the steady column. > 0: the time-marching column (time-marching column), backward Euler steps of init.column_dt in physical time to this time; the table is the column at that time. Refused with init.column_tol, init.column_max_iterations, a target wind and a non-zero init.column_mol.

init.column_dt

1

Finite, > 0 (s); with init.column_time > 0 only. The step; the last step ends at init.column_time. init.column_time / init.column_dt must be at most 1e7 steps.

init.column_wall_k

fixed

fixed or solved; with init.column_time > 0 only. fixed: the first cell’s k is the surface layer’s wall value, as in the steady column and the 3-D run. solved: the first cell’s k is solved with the k equation of the other cells and no k flux through the ground (time-marching column).

bc

See Boundary conditions. Read when init.first_guess is not none or with the SIMPLEC stage; refused otherwise. A key that has no effect for the chosen boundary types is refused. The initial field uses the boundary types, the inflow profile and the sounding; the other keys act in the SIMPLEC stage.

Input

Default

Range and meaning

bc.xlo, bc.xhi, bc.ylo, bc.yhi

periodic

periodic exactly when mesh.is_periodic is 1 in that direction; otherwise inflow, outflow, slip_wall or no_slip_wall.

bc.zlo

surface_layer

surface_layer, slip_wall or no_slip_wall.

bc.zhi

slip_wall

slip_wall, no_slip_wall or geostrophic (needs Coriolis with geostrophic forcing).

bc.<face>_wall_velocity

0 0 0

Three finite values (m/s): the velocity of a no_slip_wall face (<face> is xlo … zhi). The normal component must be 0.

bc.inflow_profile

log_law

log_law, power_law or file. The inflow keys need an inflow face, a damping layer, init.first_guess or a restart.

bc.inflow_ustar

0.4 m/s

Finite, > 0; log_law only.

bc.inflow_z0

0.1 m

Finite, > 0. Roughness of the log law, and of the equilibrium \(k\) of every profile type. Normally equal to bc.surface_z0.

bc.inflow_speed, bc.inflow_zref, bc.inflow_alpha

10 m/s, 10 m, 0.14

power_law only. Speed finite and ≥ 0; height and exponent finite and > 0.

bc.inflow_direction

0

Finite (degrees). The direction the wind blows towards, counter-clockwise from the x axis. log_law and power_law only; refused with file, whose profile gives u and v itself.

bc.inflow_file

none

Required with file: rows of z u v theta [k] (4 or 5 columns, at least 2 rows), z increasing from 0, θ > 0, k ≥ 0. # starts a comment. Every token must be a complete number with nothing attached (300.0K, 1.0D+00 or 1,2 stops the run with the file and line named); a UTF-8 byte-order mark is skipped. Read on the I/O rank and broadcast.

bc.inflow_tke_length

closure

closure or unbounded: the length \(l\) of the equilibrium \(k\) and \(\nu_t\) (Boundary conditions). closure: the turbulence model’s \(\kappa(z + z_0)\) capped by turb.max_geom_lscale. unbounded: \(\kappa(z + z_0)\), the form before this input (for the log law, \(k = u_*^2/C_{\mu 0}^2\) at every height). Refused with a k column in bc.inflow_file (no effect). A checkpoint written before this input continues unchanged only with unbounded: the inflow \(k\) is not stored in the checkpoint.

bc.theta_profile_z, bc.theta_profile

0, 300

Lists of equal length: finite, strictly increasing heights (m) and θ > 0 (K). The reference sounding.

bc.zhi_theta_grad

0

Finite (K/m): θ gradient through a slip_wall or geostrophic top.

bc.rayleigh_zdamp

0 (off)

In [0, top level): start height of the Rayleigh layer (m); > 0 needs bc.rayleigh_dampcoef > 0. The top level is mesh.prob_hi z, or where the layers end with mesh.stretch_ratio or mesh.zlevels_file.

bc.rayleigh_dampcoef

0

Finite, ≥ 0 (1/s); needs bc.rayleigh_zdamp > 0.

bc.rayleigh_fields

u v w theta tke

One or more of u v w theta tke; needs bc.rayleigh_zdamp > 0.

bc.rayleigh_height

absolute

absolute or above_ground: the height used for the layer’s coefficient and for θ’s reference (\(u, v, k\) always use the height above the ground).

bc.sponge_width

0 (off)

Finite, ≥ 0 (m); > 0 needs an inflow or outflow face and bc.sponge_strength > 0.

bc.sponge_strength

0

Finite, ≥ 0 (1/s); needs bc.sponge_width > 0.

bc.outflow_transport

mirror

mirror or from_velocity; needs an outflow face. mirror: each ghost cell outside an outflow face has the transport fluxes of the cell inside it, mirrored through the face (the normal flux continued linearly through its face value), so it has that cell’s divergence. from_velocity: the fluxes are computed from the ghost cells’ copied velocities and their own geometry, the only choice up to v1.0.0. The velocity ghosts are the same either way (Boundary conditions).

bc.surface_z0

0.1 m

Finite, > 0. Roughness length of the wall model. The bc.surface_* keys need bc.zlo = surface_layer.

bc.surface_z0_file

none (bc.surface_z0)

A file of x y z0 points (terrain.file’s format), interpolated to the ground columns in \(\ln z_0\) with terrain.idw_neighbors and terrain.idw_power (roughness map). Not with bc.surface_z0 (both given aborts) or init.first_guess = column. Every value finite and > 0, at least terrain.idw_neighbors points, and the file readable, or the run aborts naming the key. bc.inflow_z0 stays the inflow’s roughness.

bc.surface_zref

0

Finite. ≤ 0: each column’s first cell centre. Otherwise a height between the first and last cell-centre heights of every column (m).

bc.surface_stability

neutral

neutral or heat_flux.

bc.surface_heat_flux

0

Finite (K m/s); heat_flux only.

bc.surface_wall_k

dirichlet

dirichlet or source.

bc.surface_denominator_floor

log_law

log_law (\(m = \min(\ln((d + z_0)/z_0), 1)\)) or one (\(m = 1\)): the floor of the MOST denominator. They differ only where \(\ln((d + z_0)/z_0) < 1\).

bc.surface_stable_functions

businger_dyer

businger_dyer or qnse: the stable side (\(z/L > 0\)) of \(\phi_m, \phi_h, \psi_m, \psi_h\) (stable functions), for the wall model and the column. qnse needs bc.surface_stability = heat_flux or a stratified column (init.column_stability), otherwise the run stops.

bc.surface_qnse_am, bc.surface_qnse_bm

2.5, 0.2

\(a_m, b_m\) of \(\phi_m = (1 + a_m\zeta)/(1 + b_m\zeta)\): \(b_m > 0\), \(a_m \ge b_m\), finite. qnse only (otherwise the run stops).

bc.surface_qnse_ah, bc.surface_qnse_bh

2.5, 0.2

\(a_h, b_h\) of \(\phi_h\), as \(a_m, b_m\). qnse only.

The wall model and the inflow profile’s equilibrium \(k\) and \(\nu_t\) use the turbulence model’s turb.Cmu0 and turb.kappa, and the inflow profile its turb.max_geom_lscale. Without the SIMPLEC stage (turb.* is then refused) they use the defaults, 0.5562, 0.41 and 30 m.

canopy

See Forest canopy. The canopy’s drag field is built in every run (with or without steady.stage) and written to the plotfile as canopy_drag; its drag acts on the momentum equations and, with canopy.tke, on the k–L closure. A key that has no effect with the chosen canopy.type, canopy.profile or canopy.tke is refused. A restart refuses a canopy geometry other than that of the run it continues (canopy.type and the keys that build the drag field); canopy.drag_diagonal, the closure’s canopy terms (canopy.tke, canopy.beta_p, canopy.beta_d, canopy.length_alpha) and the leaf heat (canopy.heat, canopy.leaf_theta; canopy.heat_frozen needs frozen θ, which does not restart) may change across a restart, as the turb.* inputs may (the closure’s inputs then change the answer, not only the path; a checkpoint of fully frozen closure decisions keeps canopy.length_alpha, Forest canopy).

Input

Default

Range and meaning

canopy.type

none

none, patches (round patches from ERF’s forest file) or map (point maps of height, LAI and optionally \(C_d\), interpolated with terrain.idw_neighbors and terrain.idw_power).

canopy.file

required for patches

A readable file of patches, one per line, type x y height diameter cd lai laimax (ERF’s erf.forest_file); # starts a comment. type 1 or 2 (uniform or Lalic–Mihailovic), height and diameter finite and > 0 (m), cd and lai finite and ≥ 0, laimax in [0, 1) on a type 2 line and finite on a type 1 line. Any other line stops the run, naming the file and the line. A patch wider than a periodic direction of the domain is refused.

canopy.height_file

required for map

A readable file of x y h points (terrain.file’s xyz format): the canopy height (m), every value finite and ≥ 0, at least terrain.idw_neighbors points.

canopy.lai_file

required for map

A readable file of x y LAI points: the leaf area index, every value finite and ≥ 0, at least terrain.idw_neighbors points.

canopy.cd

none

Finite, > 0; map only. The drag coefficient of every column. map needs this or canopy.cd_file, not both (no default, as in ERF). 0 is refused: without a canopy, set canopy.type = none. The maps, by contrast, may hold 0 where there is no forest.

canopy.cd_file

none

map only. A readable file of x y cd points, every value finite and ≥ 0, at least terrain.idw_neighbors points.

canopy.profile

uniform

uniform or lalic_mihailovic; map only. The shape of the leaf area density over the canopy height.

canopy.laimax

0.8

Finite, in [0, 1); map with lalic_mihailovic only. The height of the largest leaf area density as a fraction of the canopy height (ERF’s erf.forest_laimax).

canopy.drag_diagonal

derivative

derivative, picard or none; patches or map. The drag’s term on the diagonal of the momentum rows: the exact derivative \(f_c(|U| + u_c^2/|U|)\), \(f_c|U|\) with \(|U|\) frozen, or nothing (the drag explicit, as in ERF). The converged answer does not depend on it; the iterations do. May change across a restart.

canopy.tke

on

on or off; patches or map. The canopy terms of the k–L closure (Forest canopy): the wake production \(\beta_p f |U|^3\), the short-circuit sink \(\beta_d f |U| k\) and the length cap \(L \le \alpha/f\). off keeps the drag only.

canopy.beta_p

1

Finite, in [0, 1]; canopy.tke = on only. The fraction of the drag work \(f|U|^3\) that becomes \(k\) (ERF’s erf.forest_canopy_beta_p).

canopy.beta_d

4

Finite, ≥ 0; canopy.tke = on only. The short-circuit coefficient of the sink \(\beta_d f |U| k\) (ERF’s erf.forest_canopy_beta_d).

canopy.length_alpha

0.04

Finite, in [0, 1]; canopy.tke = on only. The cap \(L \le \alpha/f\) on the turbulent length; 0 turns the cap off and keeps the sources (ERF’s erf.forest_canopy_length_alpha). canopy.beta_p, canopy.beta_d and canopy.length_alpha all 0 with canopy.tke = on is refused (it changes nothing).

canopy.heat

off

off or fixed; patches or map. The leaves’ sensible heat exchange with the air at a fixed leaf temperature (Forest canopy): \(\theta\) gains \(\lambda(\theta_l - \theta)\), \(\lambda = 2a/r_b\). off leaves \(\theta\) as without it, bit for bit.

canopy.leaf_theta

none

In [150, 400] (K: a value in °C is refused); required with canopy.heat = fixed and refused otherwise. The leaves’ potential temperature \(\theta_l\) (ERF’s erf.forest_leaf_theta_fixed); “fixed” names this fixed leaf temperature.

canopy.heat_frozen

skip

skip or blend; canopy.heat = fixed with simplec.theta = frozen only (refused otherwise). skip: the leaf heat is left out, with a warning. blend: in the canopy \(\theta\) is set each iteration to \(\theta_f + w(\theta_l - \theta_f)\), \(w = \lambda k/(\varepsilon + \lambda k)\), from the frozen \(\theta_f\) (Forest canopy).

buildings

See Buildings. The geometry is built in a run without steady.stage and written to the plotfile as building_beta and building_wall. With a stage it acts on momentum: SIMPLEC, z-line sweeps, one level, and solver.poisson_backend other than mlmg; others are refused. It acts on the closure too (buildings.wall_tke) and on theta (buildings.theta_mode). A key that has no effect with buildings.type = none is refused. A restart refuses buildings other than those of the run it continues.

Input

Default

Meaning and range

buildings.type

none

none or immersed_forcing.

buildings.file

required when on

The height map, readable. Heights above the local ground (m), finite and ≥ 0. At least one building in the domain, none reaching the top layer, and in a periodic direction the map no wider than the domain.

buildings.format

erf

erf: nx, ny, the x values, the y values, the heights with x the slow index. xyz: x y height or x y height zstart lines holding each point of a rectangular grid once, in any order; solid from zstart (≥ 0, and below height where height > 0; default 0) to height.

buildings.small_volfrac

0.005

In [0, 0.5). Below it a fraction is 0, within it of 1 the fraction is 1. At 0, round-off alone is clipped.

buildings.z0

0.1

Finite and > 0 (m). Refused with buildings.wall_form = drag. The law reads distances below 10 z0 as 10 z0 (Buildings, Limits). With buildings.wall_tke = on it is also the roughness in the closure’s length beside a wall (Buildings, Length scale).

buildings.wall_form

fraction_stress

fraction_stress: the form 7 wall law on roofs, undersides and sides, with the fixed rows. roof_stress: the law on roofs and undersides alone, the sides with their fixed rows. drag: the fixed rows alone.

buildings.wall_speed

open_faces with buildings.wall_form = fraction_stress, all_faces with roof_stress

open_faces or all_faces. open_faces: each velocity component of a wall cell’s speed is the mean of its two faces that are not fixed rows, so an edge or corner cell takes the open face’s value. all_faces: the mean of both faces, the form before. Either may be given with roof_stress. Refused with buildings.wall_form = drag (no wall law). A restart from a checkpoint written before this key needs all_faces.

buildings.wall_tke

on with buildings.wall_form = fraction_stress, else off

on or off. on: solid cells hold k at turb.tke_floor, wall cells relax k to u*^2 / Cmu0^2 of the wall law, k does not diffuse through blocked faces, and the closure’s length takes the nearer of the ground and the nearest building wall, each with its own roughness. off: the closure does not see the buildings. on is refused unless buildings.wall_form = fraction_stress.

buildings.theta_mode

ambient with buildings.wall_form = fraction_stress, else none

none, ambient or fixed. ambient and fixed: solid cells hold theta at the walls’ temperature, each wall exchanges heat with its cell by the form 7 law for a given surface temperature (neutral, with the wall law’s u*), and theta does not diffuse through blocked faces. ambient: the walls are at the reference profile (bc.theta_profile) at their height. fixed: at buildings.theta_surface. none: theta does not see the buildings. ambient and fixed are refused unless buildings.wall_form = fraction_stress, and with simplec.theta = frozen when given.

buildings.theta_surface

none

Finite and > 0 (K). Required with buildings.theta_mode = fixed; refused otherwise.

buildings.limiter_zone

3

0 (off) or finite, ≥ 0.5 and ≤ 20 (building heights). With turb.realizability > 0, the eddy-viscosity cap is lifted within half the zone of a building and fades back in to its edge, measured by the distance to the nearest building wall in heights of that wall’s building; the upwind blend, which follows the cap, fades with it. When given, refused without buildings.wall_tke = on or without turb.realizability > 0; the default acts only with both.

abl

See Name the boundary-layer set-up. Read with the SIMPLEC stage only; refused otherwise. Without these keys nothing is checked and no default changes. A name that the deck’s other inputs contradict stops the run.

Input

Default

Range and meaning

abl.drive

none

inflow_only, couette, pressure_driven, geostrophic_column or geostrophic_inflow.

abl.theta

none

neutral, capped, frozen or surface_flux. abl.drive = couette needs neutral.

forcing

See Governing equations. Read with the SIMPLEC stage only.

Input

Default

Range and meaning

forcing.gravity

9.81

Finite, ≥ 0 (m/s²). 0 switches buoyancy off.

forcing.theta0

300

Finite, > 0 (K). Boussinesq reference temperature. Refused with forcing.gravity = 0.

forcing.coriolis

0

0 or 1: the Coriolis force.

forcing.latitude

0

In [−90, 90] (degrees). With coriolis = 1 only.

forcing.rotation_period

86400

Finite, > 0 (s); \(f = 4\pi\sin\varphi/T\). With coriolis = 1 only. The default is the solar day (ERF’s value); the sidereal day, 86164 s, gives an f 0.27 % larger.

forcing.coriolis_3d

1

0 or 1: the \(\cos\varphi\) terms on \(u\) and \(w\). With coriolis = 1 only.

forcing.geostrophic

0

0 or 1: geostrophic forcing. Needs coriolis = 1 and a non-zero latitude.

forcing.ug, forcing.vg

0

Finite (m/s): the geostrophic wind. With geostrophic = 1 only.

forcing.pressure_gradient

0 0 0

Three finite values (m/s²): a constant pressure-gradient force on \(u, v, w\).

turb

See Turbulence model. Read with the SIMPLEC stage only.

Input

Default

Range and meaning

turb.Cmu0

0.5562

Finite, > 0: \(C_{\mu 0}\); also used by the wall k and the inflow profile’s equilibrium \(k\).

turb.Cb

0.35

Finite, > 0: \(C_b\) of the stable and unstable length scales.

turb.Rt_crit

-1

Finite, ≤ 0: \(R_t\) is smoothed below this value.

turb.Rt_min

-3

Finite, < turb.Rt_crit and > −3.598: the smoothed \(R_t\) stays above it. \(c_\mu\) has its pole at −3.5987 and grows without bound as turb.Rt_min approaches it (Turbulence model).

turb.max_geom_lscale

30 m

Finite, > 0: the harmonic cap of \(l_g\) (about \(\kappa \times 0.1\delta\), the \(l_g\) at the top of the surface layer, \(\delta\) the boundary-layer depth); also the cap of the inflow profile’s length with bc.inflow_tke_length = closure.

turb.tke_floor

0

0 (machine epsilon) or ≥ machine epsilon (m²/s²): lower bound on \(k\).

turb.sigma_k

1

Finite, > 0: \(\gamma_k = \nu_\mathrm{mol} + \nu_t/\sigma_k\).

turb.nu_molecular, turb.alpha_molecular

0, 0

Finite, ≥ 0 (m²/s): molecular viscosity and heat diffusivity.

turb.kappa

0.41

Finite, > 0: von Kármán constant; also used by the wall law and the inflow profile’s \(\nu_t\).

turb.nut_relax

1

In (0, 1]: under-relaxation of \(\nu_t\) (1: none).

turb.frozen_switch

1

0 or 1: freeze the k-floor decisions of the closure from the switch to Newton to the end of the Newton stage (Solution algorithm). With steady.stage = simplec it aborts as a key with no effect.

turb.ri_gate

0

0 (off) or finite, ≥ 1e-6 and ≤ 1: \(Ri_0\) of the stratification gate \(N^2 \to N^2\,Ri^2/(Ri^2 + Ri_0^2)\) in the closure (Turbulence model).

turb.realizability

0

0 (off) or finite, ≥ 0.01 and ≤ 10: \(C_r\) of the cap \(\nu_t \le C_r k/S\), applied to the new \(\nu_t\) before turb.nut_relax (Eddy-viscosity cap for separated flow). 0.309 is about \(C_{\mu 0}^2\) (the log-layer value) for the default turb.Cmu0.

turb.face_mean

arithmetic

arithmetic or logarithmic (Spatial discretization).

turb.wall_distance

terrain_height

terrain_height or tucker.

convection

See Spatial discretization. Read with the SIMPLEC stage only. \(k\) always uses first-order upwinding.

Input

Default

Range and meaning

convection.limiter

van_leer

van_leer, van_albada or upwind, for momentum and θ.

convection.smooth_eps_velocity

1e-5

> 0 (m/s), with a finite square: the \(\epsilon\) of van_albada for momentum.

convection.smooth_eps_theta

1e-5

The same for θ (K).

convection.hybrid_sigma_max

0

0 (off) or finite, > 0 and ≤ 1: the largest blend \(\sigma\) of the momentum and θ convection towards first-order upwind (Near-ground blend towards upwind). Needs turb.realizability > 0; not with convection.limiter = upwind, steady.stage = simplec_newton or io.restart.

convection.hybrid_height

none

Finite, > 0 (m), required with hybrid_sigma_max > 0: the blend acts below this height above the ground and tapers to 0 at 1.5 times it (recommended: 2.5 terrain heights).

convection.hybrid_relax

0.1

In (0, 1]: under-relaxation of \(\sigma\) per iteration. Refused unless hybrid_sigma_max > 0.

convection.hybrid_freeze

1e-2

0 (never) or in (0, 1): \(\sigma\) is frozen once the relative residual falls below it. Refused unless hybrid_sigma_max > 0.

steady

See Solution algorithm. With steady.stage = none the application builds the mesh and initial field, writes them and stops; the other steady.* keys are then refused.

Input

Default

Range and meaning

steady.stage

none

none, simplec, simplec_newton or unsteady. simplec_newton: SIMPLEC, then the Newton stage once the switch rules allow it, with the fallback to SIMPLEC (Solution algorithm). unsteady: backward-Euler physical steps, each converged by SIMPLEC pseudo-time iterations (unsteady).

steady.max_iterations

10000

≥ 1. Iteration limit over the whole run, restarts included. With grid sequencing it applies to each level.

steady.residual_tol

5e-5

Finite, > 0. Every scaled residual must be below it. The scales divide by the depth of the layers, not mesh.prob_hi z (Convergence criteria).

steady.residual_drop_orders

4

≥ 0 and ≤ the largest decimal exponent of the precision (308 double, 38 single). Every residual must also drop this many orders below its reference. Round-off limits the reachable drop to about 15 orders in double and 6 to 7 in single; a larger value runs to steady.max_iterations.

steady.residual_ref_iterations

5

≥ 1. The reference is the largest residual over this many first iterations. During them the CFL stays at steady.cfl0 (for grid sequencing see steady.sequencing_hold).

steady.monitor_rel_tol

1e-3

Finite, > 0. Relative tolerance of the monitors.

steady.monitor_window

50

≥ 2. Monitor window (iterations).

steady.confidence

0

0 (off) or finite, > 0 and ≤ 1: the run is also steady when this share of the cells meet the residual criterion cell by cell and every monitor criterion is met (confidence stop). SIMPLEC stage only.

steady.confidence_height

0

0 (anywhere) or finite, > 0 (m), only with steady.confidence > 0: every cell that does not meet the criterion must also lie within this height above the ground.

steady.cfl0

1

Finite, > 0. CFL number of the first iterations.

steady.cfl_max

8 with lusgs, 10 with zjacobi

Finite, ≥ steady.cfl0. Largest CFL number. The default depends on steady.sweep (the sweep and CFL-cap study on Askervein, Results); a given value is used with either sweep. With the step floor off (steady.dtau_floor = 0) a dense canopy needs a lower cap (Forest canopy, steep terrain and the boundaries).

steady.ser_exponent

1

Finite, ≥ 0. Exponent \(p\) of the CFL ramp; 0 holds the CFL at cfl0.

steady.ser_max_growth

2

Finite, ≥ 1. Largest CFL growth factor per iteration.

steady.dtau_floor

0.1

Finite, ≥ 0. The local pseudo-time rate is kept at or above this fraction of the level’s fastest convective rate, \(U_{\max} / \min(\Delta x, \Delta y)\), so a cell at rest steps at most 1/dtau_floor times as the fastest cell does (Solution algorithm, local time step). 0 is the plain local step, the form before the floor (a cell at rest then steps cfl / 1e-12 s).

steady.switch_window

20

≥ 1. Iterations below switch_residual before a switch to the next stage; no other switch within this many iterations of the last one (hysteresis), except the Newton stage’s own hand-back.

steady.switch_residual

1e-4

> 0 and ≤ 1. Relative residual at which the Newton stage starts (it was 1e-2 and unused before the Newton stage).

steady.switch_back_growth

10

Finite, > 1. Residual growth over a window that returns the run to the previous stage.

steady.switch_monitor_tol

1e-2

0 (off), or > 0 and < 1. The switch to Newton also needs every monitor to have changed by at most this fraction of max(|value|, scale) over the window.

steady.newton_fallback_failures

2

Integer, ≥ 1. Consecutive failed Newton steps (every retry used) after which the run goes back to SIMPLEC. After three such fallbacks the run stays in SIMPLEC.

steady.newton_cfl_max

128

Finite, ≥ steady.cfl_max (with simplec_newton). The Newton stage’s CFL cap: from steady.cfl_max the CFL is multiplied by steady.ser_max_growth per accepted step up to this cap, then (with steady.newton_dtau_inf_at_cap = 1) \(\Delta\tau\) is infinite. The preconditioner of an infinite \(\Delta\tau\) uses this CFL.

steady.sweep

lusgs (CPU build), zjacobi (GPU build)

zjacobi (z-line Jacobi) or lusgs (line LU-SGS). The default depends on the build (the sweep and CFL-cap study on Askervein, Results): a GPU build keeps zjacobi until the sweeps are measured on H100. zjacobi reproduces the solver used before line LU-SGS became the CPU default. A restart takes the current default, not the sweep of the run that wrote the checkpoint: give steady.sweep = zjacobi to continue a run that used the old default. The steady.line_* keys need lusgs, so a deck that gives them should also give steady.sweep.

steady.zline_sweeps

2

Sweeps per iteration: 2 to 100 with zjacobi, 1 to 100 with lusgs. With zjacobi the stable CFL grows with the sweeps: 0.9 with 2 (the default), 2.4 with 4, 3.7 with 8, 6.1 with 16 (a Fourier analysis, Results). The zjacobi default cap of 10 is above the 2-sweep value; see Results for the runs that set it.

steady.line_ghosts

lagged

lagged or zero; lusgs only. lagged: neighbours across a box face take the previous pass’s values. zero: each box sweeps on its own, without communication.

steady.line_overlap

0

Integer from 0 to 8, and at most the narrowest box width (on every hierarchy level with grid sequencing); > 0 only with line_ghosts = zero. Columns by which each box’s swept region is grown.

steady.line_order

sequential

sequential or diagonal; lusgs only. diagonal runs one column per GPU thread with the same result.

steady.line_alternate

0

0 or 1; lusgs only, with zline_sweeps ≥ 2. 1 reverses the y direction on every second sweep.

steady.sequencing

0

0 or 1. 1: grid sequencing over the mesh.hierarchy_levels levels (Solution algorithm). Needs mesh.hierarchy_levels ≥ 2 and at least 2 cells in x and y on the coarsest level. init.* then acts on the coarsest level only, and steady.max_iterations applies to each level. On a restart the coarse levels are skipped and the steady.sequencing* keys have no effect (the log says so).

steady.sequencing_drop_orders

2

Finite, > 0 and ≤ steady.residual_drop_orders; with sequencing = 1 only. A coarse level stops once every residual is this many orders below its reference, or below steady.residual_tol.

steady.sequencing_monitor_tol

0 (off)

0, or finite, > 0 and < 1; with sequencing = 1 only. A coarse level also stops once every monitor changed by at most this fraction over steady.monitor_window iterations.

steady.sequencing_hold

0

0 or 1; with sequencing = 1 only. 0: the seeded levels (all but the coarsest) skip the reference hold and ramp the CFL from their first iteration. 1: every level holds the CFL at steady.cfl0 for its first steady.residual_ref_iterations iterations. A restart keeps the setting of the checkpoint.

steady.sequencing_cfl_start

cfl0

cfl0 or previous; with sequencing = 1 only. The CFL of a seeded level’s first iteration: steady.cfl0, or the CFL the previous level reached (at least steady.cfl0). previous needs steady.sequencing_hold = 0.

steady.machine

local

local, kestrel-cpu or kestrel-gpu: allocation-unit rate (0, 10, 100 AU per node-hour).

steady.nodes

1

≥ 1. Nodes of the run, for the allocation units.

steady.newton_gmres_restart

30

Integer from 5 to 200. GMRES restart length of the Newton step.

steady.newton_fd_eps_scale

\(\sqrt{\epsilon_\mathrm{mach}}\)

≥ \(\epsilon_\mathrm{mach}^{3/4}\) and ≤ 1e-2. Relative step of the Jacobian–vector product.

steady.newton_krylov_rtol

1e-2

> 0 and < 1. GMRES tolerance in each Newton step.

steady.newton_mem_budget_gb

70

> 0 and ≤ 80. Krylov memory per rank (GB); the run stops if the estimate exceeds it.

steady.newton_gmres_max_iters

2000

Integer, ≥ 1. GMRES iteration limit of one Newton step (all restarts). A solve that reaches it is unconverged; its update goes through the usual usability rule.

steady.newton_preconditioner

simplec

identity or simplec; any other value aborts and names the key. The preconditioner of each GMRES solve of the Newton step (Solution algorithm). simplec: one SIMPLEC iteration with steady.sweep and steady.zline_sweeps. identity: none.

steady.newton_armijo_c

1e-4

> 0 and < 0.5. Armijo constant \(c\) of the continuation’s line search.

steady.newton_backtrack

0.5

> 0 and < 1. Backtracking factor \(\beta\): \(\lambda = 1, \beta, \beta^2, \ldots\)

steady.newton_lambda_min

1e-2

> 0 and < 1. The smallest \(\lambda\) tried; below it the attempt is rejected.

steady.newton_cfl_cut

0.25

> 0 and < 1. A rejected or skipped attempt multiplies the CFL by this factor (from infinite \(\Delta\tau\): steady.newton_cfl_max times it) and retries.

steady.newton_max_retries

4

Integer, ≥ 1. Retries of one continuation step; after the last the step returns failed.

steady.newton_dtau_inf_at_cap

1

0 or 1. 1: once the CFL reaches steady.newton_cfl_max, the next steps run without a pseudo-time term (\(D = 0\), plain Newton) until an attempt fails. 0: the CFL stays at the cap.

steady.newton_ptc_growth

1

Finite, ≥ 1. At a finite \(\Delta\tau\), when no \(\lambda\) meets the Armijo condition, accept the full step if \(|R|\) grows by at most this factor. 1: off. Not used at infinite \(\Delta\tau\).

The steady.newton_* and steady.switch_* keys are read with steady.stage = simplec_newton; with simplec they abort as keys with no effect. Their defaults are provisional. The last seven rows are the pseudo-transient continuation of Solution algorithm. In the Newton stage its CFL ramps from steady.cfl_max to steady.newton_cfl_max with the SER keys; the SER law’s residual term takes steady.newton_cfl_max as its starting CFL, so steady.ser_exponent rarely limits the ramp there.

unsteady

See Time driver. Read with steady.stage = unsteady; without it every unsteady.* key aborts as a key with no effect. In an unsteady run the steady stop does not apply, so steady.max_iterations, steady.residual_drop_orders, steady.monitor_rel_tol, steady.monitor_window, steady.confidence, steady.confidence_height and io.iteration_log abort as keys with no effect; steady.residual_tol is the floor of the inner stop. steady.residual_ref_iterations sets how many inner iterations, counted over the run, hold the CFL at steady.cfl0; the other steady.* keys of the SIMPLEC stage act as in a steady run. steady.sequencing = 1 and convection.hybrid_sigma_max > 0 are not supported yet and abort. A run may start from a steady checkpoint (io.restart): its physical time starts at 0 and the driver’s history (CFL, residual reference, hold) continues from the checkpoint (Time driver). From a checkpoint of an unsteady run it continues that run: its time, step count and averages. The outputs (averages, probes, plotfiles and checkpoints during the run) and the restart are described in Unsteady outputs.

Input

Default

Range and meaning

unsteady.stop_time

—

Required; finite and > 0 (s). The physical time the run ends at; the last step is shortened to end there.

unsteady.dt

—

Finite and > 0 with a finite 1/dt (s). The physical step. Required unless unsteady.cfl > 0; refused with it. The last step takes the time left when that is within 0.1 % of dt.

unsteady.cfl

0

0 (use unsteady.dt) or finite and > 0. The target convective CFL: each step’s \(\Delta t\) is this times the inverse of the largest convective rate over the cells. A field at rest has no such rate and stops the run at the first step.

unsteady.inner_drop_orders

3

Finite, > 0 and ≤ 15. A step ends when every scaled residual is at or below \(10^{-d}\) times its value at the step’s start, or below steady.residual_tol. 3 keeps the algebraic error below the time error when the inner iteration converges slowly; 1 does not (Time driver).

unsteady.max_inner

50

≥ 1. Inner iterations of a step at most; a step that reaches it is reported and the run goes on (it does not fail the run).

unsteady.average_start

0

Finite, ≥ 0 and < unsteady.stop_time (s). The running mean and variance of \(u, v, w, \theta, k\) (cell-centred) are taken over the time after it, each step weighted by its part after this time. They are in every plotfile as u_mean … tke_mean and u_var … tke_var (0 before any time is averaged). A restart must give the checkpoint’s value.

unsteady.plot_interval

0

≥ 0. A plotfile after every so many physical steps, counted from the run’s start (a restart counts on), and the final one at the end. 0: the final one only. Needs io.write_plotfile = 1. The plotfiles are numbered by the total of inner iterations, as the final one.

unsteady.checkpoint_interval

0

≥ 0. A checkpoint after every so many physical steps, as unsteady.plot_interval, and the final one at the end. Needs io.write_checkpoint = 1. A run that diverges writes no final checkpoint.

unsteady.probes_file

—

A file of probe points, one x y h per line (m; # starts a comment), \(h\) > 0 the height above the ground. Each probe takes the cell of its column whose centre is nearest \(h\) (the lower one on a tie); a point outside the domain or above the column’s top aborts. The values of \(u, v, w, \theta, k\) at the start and after each step go to <io.plot_file>_probes.csv; a restart keeps its rows up to the checkpoint’s time.

simplec

See Solution algorithm. Read with steady.stage = simplec or simplec_newton.

Input

Default

Range and meaning

simplec.pressure_reltol

1e-3

≥ 10 machine epsilon and < 1: relative tolerance of the pressure-correction solve. Looser values can be unstable in stratified flow.

simplec.alpha_p

1

> 0 and ≤ 1: pressure under-relaxation.

simplec.rotation_relax

0.3

> 0 and ≤ 1: step of the point-implicit rotation, in inertial times. 1 often converges faster (the hill cases use it).

simplec.w_vnn_cap

0 (off)

0, or finite and ≥ 16: the cap \(V\) on the vertical VNN number of the \(w\) rows. Changes the path, not the answer. May change across a restart.

simplec.w_vnn_cap_slope_margin

4

0 (off), or finite and ≥ 1; refused unless simplec.w_vnn_cap > 0. The safety factor \(s\) that lowers the cap on sloping ground so the pressure operator stays definite (Solution algorithm). 0 is the cap of #32, which can stall where thin cells meet steep slopes; the run then warns over terrain when the mesh aspect ratio is above the tested 50.78. Changes the path, not the answer. May change across a restart.

simplec.theta

solve

solve or frozen. frozen: θ is the inflow profile’s θ by height above the ground on every sequenced level and is not solved (in a canopy with canopy.heat_frozen = blend, blended towards the leaves’ θ, Forest canopy); the momentum equations carry no buoyancy force, the closure keeps \(N^2\) (Solution algorithm, prescribed potential temperature). Needs grid sequencing (steady.sequencing = 1, mesh.hierarchy_levels > 1); refused with steady.stage = simplec_newton, with io.restart and with init.first_guess = column and a non-neutral init.column_stability. With frozen, theta in bc.rayleigh_fields and bc.zhi_theta_grad have no effect.

solver

See Solution algorithm. Read when init.first_guess is not none or with the SIMPLEC stage; refused otherwise.

Input

Default

Range and meaning

solver.poisson_backend

gmres_mlmg

gmres_mlmg (GMRES with multigrid), mlmg (multigrid alone) or gmres_fft (ERF’s operator with an FFT preconditioner).

solver.poisson_reltol

1e-10 (1e-5 single)

≥ 10 machine epsilon and < 1. Converged when the residual is below this fraction of the initial one. In single precision the rounding floor of the residual is about \(\varepsilon N_z^2/2\) (\(\varepsilon\) the machine epsilon, \(N_z\) the vertical cells; 2e-4 on 64 layers), so the default 1e-5 lies below it once \(N_z\) > 13; use about \(4\varepsilon N_z^2\) there.

solver.poisson_abstol

0

Finite, ≥ 0. Converged when the residual is below this value.

solver.poisson_max_iter

200

≥ 1. GMRES iterations, or multigrid cycles with mlmg; the run stops when it is reached.

solver.poisson_restart

50

≥ 1. GMRES restart length; not with mlmg.

solver.poisson_precond

fft

fft or none; only with gmres_fft.

solver.poisson_verbose

0

≥ 0. 1 prints each solve; 2 also prints the residual at each GMRES restart.

io

Input

Default

Range and meaning

io.plot_file

plt

Plotfile prefix; not empty.

io.chk_file

chk

Checkpoint prefix; not empty.

io.write_plotfile

1

0 or 1: write the plotfile at the end of the run.

io.write_checkpoint

1

0 or 1: write the checkpoint at the end of the run (and, in an unsteady run, every unsteady.checkpoint_interval steps).

io.turb_plot_file

none

Prefix of the turbulence plotfile with ERF’s variable names (Output files). Needs the SIMPLEC stage.

io.iteration_log

table

table or full: the per-iteration log (Output files). table: aligned columns (iteration, CFL, line solver, the u, v, w, tke, theta and p residuals, r). full: one gust: it line per row with every diagnostic (the log before this input).

io.column_guess_file

column_guess.dat

Not empty. The file the converged column’s table (z u v theta k, full precision) is written to, on the I/O rank; it reads back as a bc.inflow_file. A table that cannot be written gives a warning, not a stop. Refused without init.first_guess = column (no effect).

io.restart

none

Checkpoint directory to restart from (Running a simulation). A run that would write a checkpoint into this directory (io.chk_file and the step give the same directory, however the paths are spelled) stops.

refavg (reference-averaging tool)

The separate tool gust_refavg (ERF reference solutions) reads only the refavg namespace.

Input

Default

Range and meaning

refavg.plotfiles

required

At least 3 single-level plotfiles with the same variables, domain and box layout, in increasing time.

refavg.output

required

Archive directory to create; must not exist.

refavg.case

required

Case name, one word.

refavg.erf_sha

required

Full 40-character ERF commit, lower-case hexadecimal.

refavg.machine

local

kestrel-cpu, kestrel-gpu or local.

refavg.nodes

1

≥ 1.

refavg.ranks

1

≥ 1. MPI ranks (CPU) or GPUs of the run.

refavg.wall_seconds

0

Finite, ≥ 0.

refavg.inputs_files

none

Files to copy into the archive; each must exist, with distinct names.

refavg.verify

none

Instead of building, check this archive and print its metadata. The other keys are then refused.