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,deviceandhypreare 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_heightwithterrain.type = flat).
All errors are reported together.
Quick reference
Input |
Default |
Description |
|---|---|---|
Mesh (mesh) |
||
|
required |
Number of cells in x, y, z |
|
|
Low corner of the domain (m) |
|
required |
High corner of the domain (m) |
|
|
Periodic directions |
|
|
Largest box size in x and y |
|
|
First layer thickness of a stretched grid (m) |
|
none |
Fixed ratio between successive layers |
|
none |
File with the vertical levels |
|
|
Number of grid-hierarchy levels |
Terrain (terrain) |
||
|
|
Terrain source |
|
none |
Terrain file |
|
|
Terrain-following mapping (0 BTF, 1 STF, 2 Sullivan) |
|
|
Smallest layer thickness under STF, relative to flat |
|
required for |
Hill height (m) |
|
required for |
Hill half-width (m) |
|
|
Ridge or round hill |
|
|
Points used per height for |
|
|
Inverse-distance weight exponent |
|
|
Terrain smoothing on coarse hierarchy levels |
Initial conditions (init) |
||
|
|
Initial profile: |
|
|
Mass-consistent adjustment on or off |
|
|
Horizontal and vertical transmissivity |
|
|
Lowest height at which the profile is evaluated (m) |
|
|
Height above which the initial TKE decays (m) |
|
|
O’Brien vertical-velocity correction |
|
|
Convergence tolerance of the single-column solve |
|
|
Step limit of the single-column solve |
|
|
The column’s surface: Obukhov length (0: neutral, θ held), heat flux or surface θ |
|
|
Target wind of the column: the forcing is adjusted to reach it (0: off) |
|
|
Bounds of the bulk Richardson number at the stratified column’s surface |
|
|
The time-marching column: end time and step (s; 0: the steady column) |
|
|
The time-marching column’s first-cell k: the wall value or solved |
Boundary conditions (bc) |
||
|
|
Side boundary types |
|
|
Ground boundary type |
|
|
Top boundary type |
|
|
Velocity of a no-slip wall (m/s) |
|
|
Inflow profile type |
|
0.4 m/s, 0.1 m |
Log-law friction velocity and roughness |
|
10 m/s, 10 m, 0.14 |
Power-law speed, reference height and exponent |
|
|
Wind direction (degrees from the x axis) |
|
none |
Tabulated inflow profile |
|
|
Length of the inflow profile’s equilibrium \(k\) and \(\nu_t\) |
|
|
Potential-temperature sounding (m, K) |
|
|
θ gradient through the top (K/m) |
|
|
Rayleigh layer start height (m) and strength (1/s) |
|
|
Fields the Rayleigh layer damps |
|
|
Height used by the Rayleigh layer |
|
|
Side sponge width (m) and strength (1/s) |
|
|
Transport fluxes of the ghost cells outside outflow faces |
|
0.1 m |
Ground roughness length |
|
none |
Ground roughness map, |
|
|
Wall-model reference height (0: first cell centre) |
|
|
|
|
|
Kinematic surface heat flux (K m/s) |
|
|
Wall treatment of the TKE |
|
|
Floor of the MOST denominator |
|
|
Stable-side MOST functions: |
|
|
QNSE coefficients |
Forest canopy (canopy) |
||
|
|
|
|
required for |
Patch file, |
|
required for |
Canopy height (m) and leaf area index, |
|
one required for |
Drag coefficient: one value or |
|
|
Leaf area density shape: |
|
|
Height of the largest leaf area density, as a fraction of the canopy height |
|
|
Implicit drag term on the momentum diagonal: |
|
|
Canopy terms of the k–L closure: wake production, short-circuit sink, length cap |
|
|
Wake production fraction, short-circuit coefficient, length cap \(L \le \alpha/f\) |
Buildings (buildings) |
||
|
|
|
|
required when on |
Height map, heights above the local ground (m) |
|
|
|
|
|
Solid fractions within this of 0 or 1 become 0 or 1 |
|
|
Roughness of the wall law on buildings and, with |
|
|
|
|
|
The wall law’s speed in a cell from its faces that are not fixed rows ( |
|
|
The closure sees the buildings: wall value of k, solid cells at the floor, distance to buildings in the length scale |
|
|
How theta meets a building: no terms, or walls at the reference profile’s or a given temperature |
|
none |
The walls’ temperature with |
|
|
Zone around each building where |
Named set-ups (abl) |
||
|
none |
What pushes the flow: a name that sets defaults and checks the deck |
|
none |
How θ is treated: a name that sets defaults and checks the deck |
Forcing (forcing) |
||
|
|
Gravitational acceleration (m/s²) |
|
|
Boussinesq reference temperature (K) |
|
|
Coriolis force on or off |
|
|
Latitude (degrees) |
|
|
Earth’s rotation period (s) |
|
|
Include the cos(latitude) Coriolis terms |
|
|
Geostrophic forcing on or off |
|
|
Geostrophic wind (m/s) |
|
|
Constant pressure-gradient force (m/s²) |
Turbulence model (turb) |
||
|
|
Model constant \(C_{\mu 0}\) |
|
|
Model constant \(C_b\) |
|
|
Richardson-number smoothing limits |
|
30 m |
Cap on the geometric length scale |
|
|
Lower bound on k (0: machine epsilon) |
|
|
TKE diffusion Schmidt number |
|
|
Molecular viscosity and heat diffusivity (m²/s) |
|
|
von Kármán constant |
|
|
Under-relaxation of \(\nu_t\) |
|
|
Freeze the k-floor decisions in the Newton stage |
|
|
Stratification gate \(Ri_0\) (0: off) |
|
|
Eddy-viscosity cap \(\nu_t \le C_r k/S\) (0: off; recommended 0.309 for the lee) |
|
|
Face average of the diffusivities |
|
|
Wall-distance method |
Convection (convection) |
||
|
|
Slope limiter for momentum and θ |
|
|
Smoothing constants of |
|
|
Blend towards upwind near the ground where the \(\nu_t\) cap is active (0: off) |
Steady solver (steady) |
||
|
|
|
|
|
Iteration limit |
|
|
Scaled residual tolerance |
|
|
Required residual drop (orders of magnitude) |
|
|
Iterations over which the reference residual is taken |
|
|
Confidence-percentage stop: share of converged cells (0: off), height limit of the others (0: anywhere) |
|
|
Monitor tolerance and window |
|
|
Initial and largest CFL number |
|
|
CFL ramp exponent and largest growth per iteration |
|
|
Local step floor: a cell steps at most as the level’s fastest cell does, 1/ |
|
|
Stage-switching rules ( |
|
|
Monitors settled before the switch to Newton; failed Newton steps before the fallback |
|
|
The Newton stage’s CFL cap |
|
|
Line solver: |
|
|
Sweeps per iteration |
|
|
LU-SGS coupling across box faces |
|
|
LU-SGS visiting order |
|
|
Alternate the LU-SGS sweep direction |
|
|
Grid sequencing, coarse to fine |
|
|
Residual drop for the loose stop of a coarse level |
|
|
Optional monitor test of the loose stop (0: off) |
|
|
Keep the reference hold on the seeded levels |
|
|
CFL of a seeded level’s first iteration |
|
|
Machine and node count for the allocation accounting |
|
see steady |
Newton–Krylov inputs ( |
|
|
Newton preconditioner: |
Unsteady runs (unsteady) |
||
|
— |
Physical time the run ends at (s); required with |
|
—, |
Fixed physical step (s), or a target convective CFL for a global step |
|
|
Inner stop of each physical step: residual drop (orders) and iteration limit |
|
|
Physical time the running averages and variances start at (s) |
|
|
A plotfile, a checkpoint every so many physical steps (0: at the end only) |
|
— |
File of probe points |
SIMPLEC (simplec) |
||
|
|
Tolerance of the pressure-correction solve |
|
|
Pressure under-relaxation |
|
|
Point-implicit rotation step |
|
|
Vertical-velocity cap (0: off) |
|
|
The cap’s safety margin on sloping ground (0: off) |
|
|
|
Poisson solver (solver) |
||
|
|
Poisson solver |
|
|
Relative and absolute tolerance |
|
|
Iteration limit |
|
|
GMRES restart length |
|
|
Preconditioner of |
|
|
Output level |
Input/output (io) |
||
|
|
Plotfile and checkpoint prefixes |
|
|
Write the plotfile and checkpoint |
|
none |
Prefix of the turbulence plotfile |
|
|
Layout of the per-iteration log |
|
|
File of the converged column’s table |
|
none |
Checkpoint to restart from |
mesh
Input |
Default |
Range and meaning |
|---|---|---|
|
required |
Three integers ≥ 1: cells in x, y and z. |
|
|
Three finite values: the low corner of the domain (m). The z value must be 0. |
|
required |
Three finite values, each greater than |
|
|
Three values, each 0 or 1. z must be 0. |
|
|
One or two integers ≥ 1: the largest box size in x and y. Boxes are never split in z. |
|
|
Finite, ≥ 0 (m). First layer thickness of a stretched grid; 0 gives uniform layers. Without
|
|
none |
Finite, ≥ 1; needs |
|
none |
A file of |
|
|
Integer from 1 to 10: the levels \(L\) of the grid hierarchy (Grid hierarchy). With
\(L > 1\), |
terrain
Input |
Default |
Range and meaning |
|---|---|---|
|
|
|
|
required for |
The point file ( |
|
|
0 (BTF), 1 (STF) or 2 (Sullivan). |
|
|
> 0 and < 1; STF only. Smallest layer thickness as a fraction of the flat layer. |
|
required for |
Finite, > 0 (m). |
|
required for |
Finite, > 0 (m). Distance from the crest at which the hill is half as high. |
|
|
|
|
|
≥ 1; |
|
|
Finite, > 0; |
|
|
Integer from 0 to 64; only with |
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 |
|---|---|---|
|
|
|
|
|
0 or 1: the mass-consistent adjustment. With 0, |
|
|
Finite, > 0. Horizontal transmissivity \(\alpha_h\). |
|
|
Finite, > 0. Vertical transmissivity \(\alpha_v\). Only \(\alpha_v/\alpha_h\) matters. Ratios below
0.1 need more than the default |
|
|
Finite, ≥ 0 (m). Lowest height above the ground at which the profile is evaluated. |
|
|
Finite, ≥ 0 (m). Height \(z_i\) above which the initial \(k\) decays; 0: no decay. Not with
|
|
|
0 or 1. The O’Brien correction of the vertical velocity before the adjustment. |
|
|
Finite, > 0; |
|
|
≥ 1; |
|
|
|
|
|
0 (neutral: θ held at the sounding, the column before this input) or finite with |L| ≥ 1 (m); |
|
|
Finite, > 0 (K), required with |
|
|
Finite (m/s); |
|
|
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. |
|
|
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( |
|
|
Finite, < 0; a stratified column only. The lower bound (ERF’s value). Both bounds are refused with
|
|
|
Finite, ≥ 0 (s); |
|
|
Finite, > 0 (s); with |
|
|
|
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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Three finite values (m/s): the velocity of a |
|
|
|
|
0.4 m/s |
Finite, > 0; |
|
0.1 m |
Finite, > 0. Roughness of the log law, and of the equilibrium \(k\) of every profile type. Normally equal
to |
|
10 m/s, 10 m, 0.14 |
|
|
|
Finite (degrees). The direction the wind blows towards, counter-clockwise from the x axis. |
|
none |
Required with |
|
|
|
|
|
Lists of equal length: finite, strictly increasing heights (m) and θ > 0 (K). The reference sounding. |
|
|
Finite (K/m): θ gradient through a |
|
|
In [0, top level): start height of the Rayleigh layer (m); > 0 needs |
|
|
Finite, ≥ 0 (1/s); needs |
|
|
One or more of |
|
|
|
|
|
Finite, ≥ 0 (m); > 0 needs an inflow or outflow face and |
|
|
Finite, ≥ 0 (1/s); needs |
|
|
|
|
0.1 m |
Finite, > 0. Roughness length of the wall model. The |
|
none ( |
A file of |
|
|
Finite. ≤ 0: each column’s first cell centre. Otherwise a height between the first and last cell-centre heights of every column (m). |
|
|
|
|
|
Finite (K m/s); |
|
|
|
|
|
|
|
|
|
|
|
\(a_m, b_m\) of \(\phi_m = (1 + a_m\zeta)/(1 + b_m\zeta)\): \(b_m > 0\), \(a_m \ge b_m\),
finite. |
|
|
\(a_h, b_h\) of \(\phi_h\), as \(a_m, b_m\). |
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 |
|---|---|---|
|
|
|
|
required for |
A readable file of patches, one per line, |
|
required for |
A readable file of |
|
required for |
A readable file of |
|
none |
Finite, > 0; |
|
none |
|
|
|
|
|
|
Finite, in [0, 1); |
|
|
|
|
|
|
|
|
Finite, in [0, 1]; |
|
|
Finite, ≥ 0; |
|
|
Finite, in [0, 1]; |
|
|
|
|
none |
In [150, 400] (K: a value in °C is refused); required with |
|
|
|
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 |
|---|---|---|
|
|
|
|
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. |
|
|
|
|
|
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. |
|
|
Finite and > 0 (m). Refused with |
|
|
|
|
|
|
|
|
|
|
|
|
|
none |
Finite and > 0 (K). Required with |
|
|
0 (off) or finite, ≥ 0.5 and ≤ 20 (building heights). With |
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 |
|---|---|---|
|
none |
|
|
none |
|
forcing
See Governing equations. Read with the SIMPLEC stage only.
Input |
Default |
Range and meaning |
|---|---|---|
|
|
Finite, ≥ 0 (m/s²). 0 switches buoyancy off. |
|
|
Finite, > 0 (K). Boussinesq reference temperature. Refused with |
|
|
0 or 1: the Coriolis force. |
|
|
In [−90, 90] (degrees). With |
|
|
Finite, > 0 (s); \(f = 4\pi\sin\varphi/T\). With |
|
|
0 or 1: the \(\cos\varphi\) terms on \(u\) and \(w\). With |
|
|
0 or 1: geostrophic forcing. Needs |
|
|
Finite (m/s): the geostrophic wind. With |
|
|
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 |
|---|---|---|
|
|
Finite, > 0: \(C_{\mu 0}\); also used by the wall k and the inflow profile’s equilibrium \(k\). |
|
|
Finite, > 0: \(C_b\) of the stable and unstable length scales. |
|
|
Finite, ≤ 0: \(R_t\) is smoothed below this value. |
|
|
Finite, < |
|
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 |
|
|
0 (machine epsilon) or ≥ machine epsilon (m²/s²): lower bound on \(k\). |
|
|
Finite, > 0: \(\gamma_k = \nu_\mathrm{mol} + \nu_t/\sigma_k\). |
|
|
Finite, ≥ 0 (m²/s): molecular viscosity and heat diffusivity. |
|
|
Finite, > 0: von Kármán constant; also used by the wall law and the inflow profile’s \(\nu_t\). |
|
|
In (0, 1]: under-relaxation of \(\nu_t\) (1: none). |
|
|
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 |
|
|
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). |
|
|
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 |
|
|
|
|
|
|
convection
See Spatial discretization. Read with the SIMPLEC stage only. \(k\) always uses first-order upwinding.
Input |
Default |
Range and meaning |
|---|---|---|
|
|
|
|
|
> 0 (m/s), with a finite square: the \(\epsilon\) of |
|
|
The same for θ (K). |
|
|
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 |
|
none |
Finite, > 0 (m), required with |
|
|
In (0, 1]: under-relaxation of \(\sigma\) per iteration. Refused unless |
|
|
0 (never) or in (0, 1): \(\sigma\) is frozen once the relative residual falls below it. Refused unless
|
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 |
|---|---|---|
|
|
|
|
|
≥ 1. Iteration limit over the whole run, restarts included. With grid sequencing it applies to each level. |
|
|
Finite, > 0. Every scaled residual must be below it. The scales divide by the depth of the layers, not
|
|
|
≥ 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 |
|
|
≥ 1. The reference is the largest residual over this many first iterations. During them the CFL stays at
|
|
|
Finite, > 0. Relative tolerance of the monitors. |
|
|
≥ 2. Monitor window (iterations). |
|
|
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. |
|
|
0 (anywhere) or finite, > 0 (m), only with |
|
|
Finite, > 0. CFL number of the first iterations. |
|
|
Finite, ≥ |
|
|
Finite, ≥ 0. Exponent \(p\) of the CFL ramp; 0 holds the CFL at |
|
|
Finite, ≥ 1. Largest CFL growth factor per iteration. |
|
|
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. Iterations below |
|
|
> 0 and ≤ 1. Relative residual at which the Newton stage starts (it was |
|
|
Finite, > 1. Residual growth over a window that returns the run to the previous stage. |
|
|
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. |
|
|
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. |
|
|
Finite, ≥ |
|
|
|
|
|
Sweeps per iteration: 2 to 100 with |
|
|
|
|
|
Integer from 0 to 8, and at most the narrowest box width (on every hierarchy level with grid sequencing);
> 0 only with |
|
|
|
|
|
0 or 1; |
|
|
0 or 1. 1: grid sequencing over the |
|
|
Finite, > 0 and ≤ |
|
|
0, or finite, > 0 and < 1; with |
|
|
0 or 1; with |
|
|
|
|
|
|
|
|
≥ 1. Nodes of the run, for the allocation units. |
|
|
Integer from 5 to 200. GMRES restart length of the Newton step. |
|
\(\sqrt{\epsilon_\mathrm{mach}}\) |
≥ \(\epsilon_\mathrm{mach}^{3/4}\) and ≤ 1e-2. Relative step of the Jacobian–vector product. |
|
|
> 0 and < 1. GMRES tolerance in each Newton step. |
|
|
> 0 and ≤ 80. Krylov memory per rank (GB); the run stops if the estimate exceeds it. |
|
|
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. |
|
|
|
|
|
> 0 and < 0.5. Armijo constant \(c\) of the continuation’s line search. |
|
|
> 0 and < 1. Backtracking factor \(\beta\): \(\lambda = 1, \beta, \beta^2, \ldots\) |
|
|
> 0 and < 1. The smallest \(\lambda\) tried; below it the attempt is rejected. |
|
|
> 0 and < 1. A rejected or skipped attempt multiplies the CFL by this factor (from infinite
\(\Delta\tau\): |
|
|
Integer, ≥ 1. Retries of one continuation step; after the last the step returns failed. |
|
|
0 or 1. 1: once the CFL reaches |
|
|
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 |
|---|---|---|
|
— |
Required; finite and > 0 (s). The physical time the run ends at; the last step is shortened to end there. |
|
— |
Finite and > 0 with a finite 1/dt (s). The physical step. Required unless |
|
|
0 (use |
|
|
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 |
|
|
≥ 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). |
|
|
Finite, ≥ 0 and < |
|
|
≥ 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 |
|
|
≥ 0. A checkpoint after every so many physical steps, as |
|
— |
A file of probe points, one |
simplec
See Solution algorithm. Read with steady.stage = simplec or simplec_newton.
Input |
Default |
Range and meaning |
|---|---|---|
|
|
≥ 10 machine epsilon and < 1: relative tolerance of the pressure-correction solve. Looser values can be unstable in stratified flow. |
|
|
> 0 and ≤ 1: pressure under-relaxation. |
|
|
> 0 and ≤ 1: step of the point-implicit rotation, in inertial times. 1 often converges faster (the hill cases use it). |
|
|
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. |
|
|
0 (off), or finite and ≥ 1; refused unless |
|
|
|
solver
See Solution algorithm. Read when init.first_guess is not none or with the SIMPLEC stage; refused
otherwise.
Input |
Default |
Range and meaning |
|---|---|---|
|
|
|
|
|
≥ 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. |
|
|
Finite, ≥ 0. Converged when the residual is below this value. |
|
|
≥ 1. GMRES iterations, or multigrid cycles with |
|
|
≥ 1. GMRES restart length; not with |
|
|
|
|
|
≥ 0. 1 prints each solve; 2 also prints the residual at each GMRES restart. |
io
Input |
Default |
Range and meaning |
|---|---|---|
|
|
Plotfile prefix; not empty. |
|
|
Checkpoint prefix; not empty. |
|
|
0 or 1: write the plotfile at the end of the run. |
|
|
0 or 1: write the checkpoint at the end of the run (and, in an unsteady run, every
|
|
none |
Prefix of the turbulence plotfile with ERF’s variable names (Output files). Needs the SIMPLEC stage. |
|
|
|
|
|
Not empty. The file the converged column’s table ( |
|
none |
Checkpoint directory to restart from (Running a simulation). A run that would write a checkpoint into this
directory ( |
refavg (reference-averaging tool)
The separate tool gust_refavg (ERF reference solutions) reads only the refavg namespace.
Input |
Default |
Range and meaning |
|---|---|---|
|
required |
At least 3 single-level plotfiles with the same variables, domain and box layout, in increasing time. |
|
required |
Archive directory to create; must not exist. |
|
required |
Case name, one word. |
|
required |
Full 40-character ERF commit, lower-case hexadecimal. |
|
|
|
|
|
≥ 1. |
|
|
≥ 1. MPI ranks (CPU) or GPUs of the run. |
|
|
Finite, ≥ 0. |
|
none |
Files to copy into the archive; each must exist, with distinct names. |
|
none |
Instead of building, check this archive and print its metadata. The other keys are then refused. |