Inputs

The ERF executable reads run-time information from an inputs file which you name on the command line. This section describes the inputs which can be specified either in the inputs file or on the command line. A value specified on the command line will override a value specified in the inputs file. An inputs file may include others with FILE = <name> lines, for instance to share one set of settings between two decks. As in AMReX ParmParse, the name is opened relative to the directory ERF runs in, with $AMREX_INPUTS_FILE_PREFIX in front when that is set. A file may re-set a key that a file it included earlier set (a base deck included first and then overridden; the last value wins), and UNSET = <key> drops a key so that it may be set again. Otherwise every input is set in one place: ERF refuses to start when a key appears twice in one file, in two files included side by side, or in a file and again in a file it includes afterwards, and names both places.

Inputs with the prob. prefix are not listed here: they are read by the individual problem setups rather than by ERF itself, so the same name means different things in different problems. They are indexed by problem in Problem-Specific Inputs.

Governing Equations

Parameter	Definition	Acceptable Values	Default
erf.anelastic	Use anelastic equations at the given AMR levels. Sets project_initial_velocity=1, fixed_density=1, and substepping_type=None. The stored buoyancy_type=3 does not select the buoyancy kernel.	0, 1	0
erf.buoyancy_type	Compressible choices: 1=full density departure; 2/3=identical temperature approximations; 4=potential-temperature approximation. Anelastic uses a separate kernel. See Buoyancy.	1, 2, 3, 4	1 (3 if anelastic)
erf.use_fft	Use FFT rather than multigrid to solve the Poisson equations, where supported.	Boolean	false
erf.mg_v	Multigrid Poisson solver verbosity.	Integer >= 0	0
erf.fixed_density	Hold dry density fixed in time (per level). Always 1 on anelastic levels. A user value of 0 there is ignored with a warning.	0, 1	0 (1 if anelastic)
erf.c_p	Runtime dry-air heat capacity [J/(kg K)] for selected thermodynamics and forcing. It does not change fixed EOS exponent Gamma=1.4; nondefault values can make EOS inverse relations inconsistent. See Governing Equations.	Real > 0	1004.5
erf.gradp_type	which horizontal pressure gradient formulation to use with terrain-fitted coordinates: 0 for dp/dx with a dp/dz correction, 1 for the gradient of the vertically interpolated pressure (Klemp 2011)	0, 1	0
erf.use_pert_pres_gradient	if true, the lateral pressure gradient in the momentum equation uses horizontal derivatives of the perturbational pressure; if false, of the full pressure	Boolean	true
erf.transport_scalar	transport the passive scalar component	Boolean	true
erf.use_lagged_delta_rt	use the lagged (rho*theta) increment in the fast integrator; may only be set to false when terrain_type = MovingFittedMesh	Boolean	true

Note

To use the FFT solver if running with anelastic, you must set USE_FFT = TRUE if using gmake or ERF_ENABLE_FFT if using cmake.

Problem Geometry

List of Parameters

Parameter	Definition	Acceptable Values	Default
geometry.prob_lo	physical location of low corner of the domain	Real	0 0 0
geometry.prob_hi	physical location of high corner of the domain	Real	must be set unless prob_extent is set
geometry.prob_extent	physical size of the domain in each direction	Real	must be set unless prob_hi is set
geometry.is_periodic	is the domain periodic in this direction	0 if false, 1 if true	0 0 0

Note

The extent of the domain may be specified either by geometry.prob_hi or by geometry.prob_extent, where prob_hi = prob_lo + prob_extent. Exactly one of the two must be given; specifying both is an error. Since geometry.prob_lo defaults to 0 in every direction, a domain whose low corner is at the origin can be defined by setting geometry.prob_extent alone, i.e. without setting either geometry.prob_lo or geometry.prob_hi.

These parameters may also be given with the erf prefix, i.e. as erf.prob_lo, erf.prob_hi, erf.prob_extent and erf.is_periodic, but the erf- and geometry-prefixed forms may not be mixed. Note that if the erf prefix is used, then erf.prob_lo must be set explicitly along with erf.prob_hi or erf.prob_extent.

Examples of Usage

• geometry.prob_lo = 0 0 0 defines the low corner of the domain at (0,0,0) in physical space.

• geometry.prob_hi = 1.e8 2.e8 2.e8 defines the high corner of the domain at (1.e8,2.e8,2.e8) in physical space.

• geometry.prob_extent = 1.e8 2.e8 2.e8 defines a domain of size (1.e8,2.e8,2.e8) in physical space; combined with the default geometry.prob_lo = 0 0 0, this is equivalent to the two examples above.

• geometry.is_periodic = 0 1 0 says the domain is periodic in the y-direction only.

Domain Boundary Conditions

Domain boundary conditions in ERF may be broadly categorized as ideal or real where the ideal BC types correspond those found in classic fluid solvers and real correspond to an external data source that may be based upon observation data. The inputs for these types of BCs are given in more detail in Domain Boundary Condition Types. We briefly note that the supported ideal BC types are inflow, inflow_outflow, outflow, ho_outflow, open, slipwall, noslipwall, symmetry and surface_layer. The type strings are matched case-insensitively, so e.g. NoSlipWall and noslipwall are equivalent.

The <face> keys above may also be given with an erf. prefix – ERF looks for erf.xlo.type first and falls back to xlo.type – but every inputs file in the repository uses the un-prefixed form shown here.

The inputs that configure a surface_layer boundary are collected in Surface Layer (MOST), and Surface Layer Boundaries gives the formulation.

One further family is documented on its own page rather than here:

• the inputs that configure the inflow perturbation selected by erf.perturbation_type – erf.perturbation_box_dims, erf.perturbation_direction, erf.perturbation_layers, erf.perturbation_offset, erf.perturbation_nondimensional, erf.perturbation_T_infinity, erf.perturbation_T_intensity, erf.perturbation_Ug, erf.perturbation_w_amp, erf.perturbation_klo, erf.perturbation_khi, erf.perturbation_auto, erf.perturbation_auto_period, erf.perturbation_auto_pbl_fraction, erf.perturbation_uniform_refresh, erf.perturbation_refresh_height and erf.perturbation_refresh_wind_period – are described in Inflow Turbulence Generation.

List of Parameters

Parameter	Definition	Acceptable Values	Default
xlo.type	boundary type of the xlo face	inflow, outflow, inflow_outflow, open, ho_outflow, slipwall, noslipwall, symmetry, surface_layer	must be set if the direction is not periodic
xhi.type	boundary type of the xhi face	inflow, outflow, inflow_outflow, open, ho_outflow, slipwall, noslipwall, symmetry, surface_layer	must be set if the direction is not periodic
ylo.type	boundary type of the ylo face	inflow, outflow, inflow_outflow, open, ho_outflow, slipwall, noslipwall, symmetry, surface_layer	must be set if the direction is not periodic
yhi.type	boundary type of the yhi face	inflow, outflow, inflow_outflow, open, ho_outflow, slipwall, noslipwall, symmetry, surface_layer	must be set if the direction is not periodic
zlo.type	boundary type of the zlo face	inflow, outflow, inflow_outflow, open, ho_outflow, slipwall, noslipwall, symmetry, surface_layer	must be set if the direction is not periodic
zhi.type	boundary type of the zhi face	inflow, outflow, inflow_outflow, open, ho_outflow, slipwall, noslipwall, symmetry, surface_layer	must be set if the direction is not periodic
erf.perturbation_type	type of inflow turbulence generation used at a level (per-level). See Inflow Turbulence Generation	None, Source, Direct, CPM, CPM_W	None
<face>.density	density imposed at a slipwall or noslipwall face; may not be combined with <face>.density_grad, and is rejected for anelastic runs	Real > 0	not set
<face>.density_grad	Neumann gradient of density imposed at a slipwall or noslipwall face; may not be combined with <face>.density, and is rejected for anelastic runs	Real	0.0
<face>.theta	potential temperature imposed at a slipwall or noslipwall face; may not be combined with <face>.theta_grad	Real > 0	not set
<face>.theta_grad	Neumann gradient of potential temperature imposed at a slipwall or noslipwall face; a face with neither key defaults to a zero gradient (adiabatic)	Real	0.0
<face>.qv	water-vapor mixing ratio imposed at a noslipwall face; read only for no-slip walls and with an active moisture model	Real >= 0	not set
<face>.velocity	velocity imposed at an inflow face. Required on an inflow face unless <face>.dirichlet_file is given	3 Reals	must be set
<face>.dirichlet_file	file of height-varying Dirichlet inflow data, used in place of <face>.velocity	String	None
<face>.read_prim_theta	the dirichlet_file supplies theta rather than (rho*theta); read only when that file is given	Boolean	true
<face>.nonreflecting	let upstream-propagating acoustic waves leave through the face instead of reflecting off the Dirichlet boundary	Boolean	false
<face>.scalar	passive-scalar value imposed at an inflow face; ignored when the scalar is ingested from boundary planes	Real	0.0
<face>.qc	cloud-water mixing ratio imposed at an inflow face; read only with an active moisture model, and ignored when ingested from boundary planes	Real >= 0	not set
<face>.KE	turbulent kinetic energy imposed at an inflow face; ignored when ingested from boundary planes	Real >= 0	not set

Resolution

List of Parameters

Parameter	Definition	Acceptable Values	Default
amr.n_cell	number of cells in each direction at the coarsest level	Integer > 0	must be set
amr.max_level	number of levels of refinement above the coarsest level	Integer >= 0	must be set
amr.ref_ratio	ratio of coarse to fine grid spacing between subsequent levels, in every direction	Integer >= 1 (one per level)	2 for all levels
amr.ref_ratio_vect	ratio of coarse to fine grid spacing between subsequent levels, per direction	3 integers >= 1 per level, one per coordinate direction	2 for all levels and directions
amr.regrid_int	how often to regrid	Integer > 0 (if negative, no regridding)	-1
amr.regrid_on_restart	should we regrid immediately after restarting	0 or 1	0
amr.regrid_level_0_on_restart	should we regrid level immediately after restarting	Boolean	false
amr.iterate_grids	do we iterate on the grids?	Boolean	true
erf.n_cell	number of cells in each coordinate direction; an accepted alternative to amr.n_cell. Specifying both aborts the run	3 Integers	must set this or amr.n_cell

Note: if amr.max_level = 0 then you do not need to set amr.ref_ratio or amr.regrid_int.

Examples of Usage

• amr.n_cell = 32 64 64

  would define the domain to have 32 cells in the x-direction, 64 cells in the y-direction, and 64 cells in the z-direction at the coarsest level.

• amr.max_level = 2

  would allow a maximum of 2 refined levels in addition to the coarse level. Note that these additional levels will only be created only if the tagging criteria are such that cells are flagged as needing refinement. The number of refined levels in a calculation must be \(\leq\) amr.max_level, but can change in time and need not always be equal to amr.max_level.
• amr.ref_ratio = 2 3

  would set factor 2 refinement between levels 0 and 1, and factor 3 refinement between levels 1 and 2. Note that you must have at least amr.max_level values of amr.ref_ratio (Additional values may appear in that line and they will be ignored).
• amr.ref_ratio_vect = 2 4 3

  with amr.max_level = 1, this would set factor {2 in x-dir, 4 in y-dir, 3 in z-dir} refinement between levels 0 and 1. Note that you must specify 3 values for every refined level, i.e. 3 \(\times\) amr.max_level values in all, ordered (x,y,z) for level 0, then (x,y,z) for level 1, and so on. amr.ref_ratio and amr.ref_ratio_vect may not both be given.
• amr.ref_ratio_vect = 2 2 1

  refines by a factor of 2 in x and y but not at all in z, so the fine level has the same vertical grid spacing as the coarse level. Note that amr.ref_ratio cannot express this, since it applies a single ratio in all three directions; see Mesh Refinement for the distinction between refining in z and creating a finer level over a region. With erf.init_type = WRFInput, the third slot also decides whether the wrfinput data is refined in the vertical as it is read; see Nested Initialization From WRF Input Files.
• amr.regrid_int = 2 2

  tells the code to regrid every 2 steps. Thus in this example, new level-1 grids will be created every 2 level-0 time steps, and new level-2 grids will be created every 2 level-1 time steps.

Grid Stretching

This automatically activates erf.terrain_type = StaticFittedMesh. By default, the problem-specific terrain is initialized to be flat at geometry.prob_lo in z. These inputs are used to automatically generate the staggered z levels used to calculate the grid metric transformation. Alternatively, arbitrary z levels may be specified with the erf.terrain_z_levels parameter, which must start at geometry.prob_lo in z (the surface) and rise to the domain height.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.grid_stretching_ratio	ratio by which each vertical cell size is increased relative to the one below it. If set, the mesh type becomes StretchedDz and erf.initial_dz must also be given	0, or Real >= 1	0 (no stretching)
erf.initial_dz	vertical cell size of the lowest cell when generating a stretched vertical mesh; required when grid_stretching_ratio >= 1. If given without grid_stretching_ratio, the ratio is solved for so that the grid closes on geometry.prob_hi in z	Real > 0	must be set if erf.grid_stretching_ratio is set
erf.terrain_z_levels	explicit list of nominal (terrain-free) staggered z levels; specifying these makes the mesh type StretchedDz. See Meshing	List of Reals	None
erf.mesh_type	vertical mesh type; normally set from the terrain and stretching options rather than directly	ConstantDz, StretchedDz, VariableDz	set from other inputs

Notes

• If both erf.terrain_z_levels and erf.grid_stretching_ratio (or erf.initial_dz) are specified, the simple grid stretching will be ignored.

• With erf.grid_stretching_ratio and erf.initial_dz both given, the top of the grid is wherever the stretched layers end, which need not be geometry.prob_hi in z. ERF then prints a warning giving that top and uses it as the physical top of the domain; on any mesh other than ConstantDz, geometry.prob_lo and geometry.prob_hi in z only bound the computational coordinate. With erf.initial_dz alone, the constant ratio \(r\) is instead solved for so that \(dz_0 (r^{n_z} - 1)/(r - 1)\) fills the domain from geometry.prob_lo to geometry.prob_hi in z exactly. An erf.initial_dz at or above the uniform spacing gives a uniform grid, and an explicit erf.grid_stretching_ratio = 0 turns stretching off even when erf.initial_dz is given. This applies to idealized cases and to cases initialized from met_em files; a wrfinput case builds its grid from the file instead.

• The number of input erf.terrain_z_levels must be equal amr.n_cell in the z direction + 1.

• Every vertical grid – uniform, stretched (erf.grid_stretching_ratio or erf.initial_dz) or given by erf.terrain_z_levels – starts at geometry.prob_lo in z, and a flat surface sits there. The former input erf.zsurface is no longer accepted; set geometry.prob_lo in z instead.

Examples of Usage

• erf.grid_stretching_ratio = 1.025

• erf.initial_dz = 5.0

  the first cell center would be at z=2.5
• erf.initial_dz = 5.0 (with no erf.grid_stretching_ratio)

  the stretching ratio is solved for so the grid closes on geometry.prob_hi

Regridding

Overview

The user defines how to tag individual cells at a given level for refinement. This list of tagged cells is sent to a grid generation routine, which uses the Berger-Rigoutsos algorithm to create rectangular grids that contain the tagged cells.

erf.regrid_int, which sets how often the grids are re-made, is documented in Mesh Refinement together with the tagging criteria.

See Mesh Refinement for more details on how to specify regions for refinement.

List of Parameters

Parameter	Definition	Acceptable Values	Default
amr.regrid_file	name of file from which to read the grids	text	no file
amr.grid_eff	grid efficiency at coarse level at which grids are created	Real > 0, < 1	0.7
amr.n_error_buf	radius of additional tagging around already tagged cells	Integer >= 0	0
amr.n_error_buf_x	radius of additional tagging in the x-direction	Integer >= 0	n_error_buf
amr.n_error_buf_y	radius of additional tagging in the y-direction	Integer >= 0	n_error_buf
amr.n_error_buf_z	radius of additional tagging in the z-direction	Integer >= 0	n_error_buf
amr.n_proper	minimum number of coarse cells between coarse-fine boundaries	Integer > 0	2
amr.max_grid_size	maximum size of a grid in every direction	Integer > 0	2048
amr.max_grid_size_x	maximum size of a grid in the x-direction	Integer > 0	max_grid_size
amr.max_grid_size_y	maximum size of a grid in the y-direction	Integer > 0	max_grid_size
amr.max_grid_size_z	maximum size of a grid in the z-direction	Integer > 0	max_grid_size
amr.blocking_factor	grid size must be a multiple of this in every direction	Integer > 0	1
amr.blocking_factor_x	grid size in x must be a multiple of this	Integer > 0	blocking_factor
amr.blocking_factor_y	grid size in y must be a multiple of this	Integer > 0	blocking_factor
amr.blocking_factor_z	grid size in z must be a multiple of this	Integer > 0	blocking_factor
amr.refine_grid_layout	chop grids further if # of processors > # of grids	0 if false, 1 if true	1
amr.refine_grid_layout_x	chop in x when refining the grid layout	0 if false, 1 if true	1
amr.refine_grid_layout_y	chop in y when refining the grid layout	0 if false, 1 if true	1
amr.refine_grid_layout_z	chop in z when refining the grid layout	0 if false, 1 if true	0
amr.no_box_split_dir	direction (0 for x, 1 for y, 2 for z) in which grids are never split, so that max_grid_size and refine_grid_layout are ignored in that direction; -1 allows grids to be split in every direction	-1, 0, 1 or 2	2
amr.refine_whole_domain_dir	direction (0 for x, 1 for y, 2 for z) in which every level greater than 0 covers the entire domain, no matter where cells are tagged; -1 disables this	-1, 0, 1 or 2	-1
erf.regrid_level_0_on_restart	allow the level-0 grids to be re-made when restarting from a checkpoint	Boolean	false
erf.cf_width	total width, in cells, of the coarse/fine interior ghost region used for the two-way coupling	Integer >= 0	0
erf.cf_set_width	width, in cells, of the region within erf.cf_width in which the fine solution is set from the coarse one	Integer >= 0	0
erf.interpolation_type	what is interpolated when filling a fine level from the coarse one	FullState, Perturbational	FullState
erf.refinement_indicators	names of the refinement indicators to apply; each name becomes the prefix of its own group of options below	List of Strings	None
erf.<indicator>.field_name	field the indicator tests. hurricane_tracker is a reserved indicator name that needs no field	String	None
erf.<indicator>.value_greater	tag cells where the field exceeds this value, one value per level	List of Reals	None
erf.<indicator>.value_less	tag cells where the field falls below this value, one value per level	List of Reals	None
erf.<indicator>.adjacent_difference_greater	tag cells where the difference between adjacent values exceeds this, one value per level	List of Reals	None
erf.<indicator>.max_level	finest level at which the indicator is applied. Optional when the box is given in real coordinates; required when it is given in index space	Integer >= 1	finest level
erf.<indicator>.start_time	simulation time [s] at which the indicator becomes active	Real	start of run
erf.<indicator>.end_time	simulation time [s] after which the indicator is inactive	Real	end of run
erf.<indicator>.in_box_lo	low corner, in physical coordinates, of the region the indicator tags	2 or 3 Reals	None
erf.<indicator>.in_box_hi	high corner, in physical coordinates	2 or 3 Reals	None
erf.<indicator>.in_box_lo_indices	low corner in fine-level index space; may not be combined with the real-coordinate form	3 Integers	None
erf.<indicator>.in_box_hi_indices	high corner in fine-level index space	3 Integers	None
erf.<indicator>.in_box_lo_indices_crse	low corner in coarse-level index space	3 Integers	None
erf.<indicator>.in_box_hi_indices_crse	high corner in coarse-level index space	3 Integers	None
erf.<indicator>.move_speed_x	x-speed at which the tagged box moves	Real	0.0
erf.<indicator>.move_speed_y	y-speed at which the tagged box moves	Real	0.0
erf.<indicator>.move_start_time	start times of the intervals over which the box moves; must pair with move_stop_time, and the intervals must not overlap	List of Reals	None
erf.<indicator>.move_stop_time	stop times of those intervals; each must be later than the matching start time	List of Reals	None
erf.<indicator>.max_radius	radius within which cells are tagged; required by the hurricane_tracker indicator	Real > 0	must be set

Notes

• ERF changes several of the AMReX gridding defaults; the values in the table above are the ERF defaults, and they are set in add_par in Source/main.cpp. In particular amr.max_grid_size defaults to a very large value (so that grids are chopped only when there are more processors than grids), amr.blocking_factor defaults to 1, amr.refine_grid_layout_z defaults to 0 (the AMReX default is 1), and amr.no_box_split_dir defaults to 2 (the AMReX default is -1).

• amr.n_error_buf, amr.max_grid_size and amr.blocking_factor can be read in as a single value which is assigned to every level, or as multiple values, one for each level

• amr.refine_whole_domain_dir makes every level greater than 0 cover the entire domain in the specified direction, whatever the refinement indicators tagged; setting it to 2 is the simplest way to guarantee full-depth refined grids. See Refining the Whole Domain in One Direction.

• amr.no_box_split_dir tells the grid generator never to split a box in the specified direction, at any level; amr.max_grid_size and amr.refine_grid_layout are then ignored in that direction. ERF defaults this to 2 so that no grid is decomposed in the vertical. Set it to -1 to recover the AMReX behavior of allowing boxes to be split in every direction; this is also necessary in builds that use bittree, which does not support amr.no_box_split_dir. See Avoiding Decomposition in the Vertical Direction.

• amr.n_error_buf, amr.max_grid_size and amr.blocking_factor apply to all coordinate directions; the per-direction forms amr.n_error_buf_x/_y/_z, amr.max_grid_size_x/_y/_z and amr.blocking_factor_x/_y/_z override them in the specified direction only, and may also be specified per level

• amr.max_grid_size at every level should be even: ERF does not stop on an odd value, but a box with an odd number of cells cannot be halved for load balancing or coarsened by 2 under a finer level

• amr.blocking_factor at every level must be a power of 2

• the domain size amr.n_cell must be a multiple of amr.blocking_factor at level 0

• amr.max_grid_size must be a multiple of amr.blocking_factor at every level

• the three amr.blocking_factor rules above are not applied in the amr.no_box_split_dir direction (the vertical, by default)

• amr.refine_grid_layout is a single flag that sets all three of amr.refine_grid_layout_x/_y/_z; if a per-direction flag is also specified it takes precedence in that direction

• erf.regrid_level_0_on_restart lets a restart continue on level-0 grids other than the ones the checkpoint was written on, re-made from amr.max_grid_size as a fresh start would make them. The same thing happens automatically, without the flag, when the restart runs on more ranks than level 0 has boxes in the checkpoint – that is, when a run is continued on more ranks than it was written with. Every field the checkpoint carries, including the state of the land-surface models, two-stream radiation and spectral bin microphysics, is read on the grids in the file and redistributed onto the new ones, so the run continues as it would have on the original grids.

Examples of Usage

• amr.regrid_file = fixed_grids

  In this case the list of grids at each fine level are contained in the file fixed_grids, which will be read during the gridding procedure. These grids must not violate the amr.max_grid_size criterion. The rest of the gridding procedure described below will not occur if amr.regrid_file is set.
• amr.grid_eff = 0.9

  During the grid creation process, at least 90% of the cells in each grid at the level at which the grid creation occurs must be tagged cells. Note that this is applied at the coarsened level at which the grids are actually made, and before amr.max_grid_size is imposed.
• amr.max_grid_size = 64

  The final grids will be no longer than 64 cells on a side at every level.
• amr.max_grid_size = 64 32 16

  The final grids will be no longer than 64 cells on a side at level 0, 32 cells on a side at level 1, and 16 cells on a side at level 2.
• amr.blocking_factor = 32

  The dimensions of all the final grids will be multiples of 32 at all levels.
• amr.blocking_factor = 32 16 8

  The dimensions of all the final grids will be multiples of 32 at level 0, multiples of 16 at level 1, and multiples of 8 at level 2.
• amr.max_grid_size_x = 64

  amr.max_grid_size_y = 64

  The final grids will be no longer than 64 cells in the x and y directions, but will not be limited in the z direction. This is the way to limit the horizontal box size without decomposing the grids vertically.
• amr.refine_grid_layout_z = 1

  Allow the grids to be chopped in the vertical direction as well as horizontally when there are more processors than grids. This is not the ERF default.
• amr.no_box_split_dir = 2

  No grid, at any level, is split in the vertical direction; the grid generator merges the boxes it creates along z, and amr.max_grid_size_z and amr.refine_grid_layout_z are ignored. This is the ERF default.
• amr.no_box_split_dir = -1

  Restore the AMReX behavior, in which grids may be split in any direction subject to amr.max_grid_size and amr.refine_grid_layout_x/_y/_z. This is only allowed if no level uses implicit acoustic substepping; see the note below.

Avoiding Decomposition in the Vertical Direction

Many ERF workflows want each box to span the full vertical extent of the domain or of the refined region – for example because a physics package operates on entire columns. (Native SHOC requires this and will abort if any box is split in z.) ERF is set up so that this is the default behavior, in both places where grids are created.

The simplest and strongest control is amr.no_box_split_dir, which names a single direction in which the grid generator is never allowed to split a box. ERF sets this to 2 (the z-direction) by default, so out of the box no grid at any level is decomposed in the vertical. When it is set:

• the boxes produced by clustering the tagged cells are merged along that direction, so no two grids share a face normal to it;

• amr.max_grid_size is ignored in that direction (it is effectively relaxed to the extent of the domain), as is the corresponding amr.refine_grid_layout flag, so neither the box-size limit nor the load-balancing step can reintroduce a split there.

Setting amr.no_box_split_dir = -1 turns this off and restores the AMReX behavior in which grids may be split in any direction. ERF only accepts that if every level has erf.substepping_type = None (which an anelastic level is given automatically): the implicit substep solve inverts one tridiagonal system per column, so no column may be chopped at a box seam, just as for the implicit vertical diffusion, and the code aborts rather than run with a value other than 2 while any level substeps implicitly. With amr.no_box_split_dir = -1, the two places where grids are created behave as follows:

• When the level 0 grids are created, ERF decomposes the domain across the processors itself (see ERFPostProcessBaseGrids). It decomposes in the vertical direction only if amr.max_grid_size_z is smaller than amr.n_cell in the z direction. Since amr.max_grid_size defaults to a very large value, no vertical decomposition is done unless it is requested.

• When grids are chopped to give at least one grid per processor, either during regridding at a finer level or when regridding level 0 on restart, AMReX only chops in the directions for which the corresponding amr.refine_grid_layout_x/_y/_z flag is set. Because ERF defaults amr.refine_grid_layout_z to 0, this load-balancing step never splits a box in the vertical direction.

With amr.no_box_split_dir = -1, the usual way to accidentally introduce a vertical decomposition is to set amr.max_grid_size as a single value, since that limits the box size in all three directions. To limit the box size horizontally only, use the per-direction forms, e.g.

amr.max_grid_size_x = 64
amr.max_grid_size_y = 64

and leave amr.max_grid_size_z at its (large) default. The same holds for amr.blocking_factor versus amr.blocking_factor_x/_y. With the default amr.no_box_split_dir = 2 these z-direction settings are ignored, so a single amr.max_grid_size still limits the box size in x and y only.

Note that this is a different question from how much of the depth a refined level covers. Whether the grids at levels greater than 0 reach from the bottom of the domain to the top is decided by the refinement indicators, or in one step by amr.refine_whole_domain_dir = 2; see Refining the Whole Domain in One Direction. The two are complementary: that parameter makes the refined region cover the full depth, and the defaults described here keep the region from being chopped into several boxes in z, so that each box spans the depth by itself.

Gridding and Load Balancing

The ERF gridding and load balancing strategy is based on that in AMReX. See the Gridding section of the AMReX documentation for details.

Simulation Time

List of Parameters

Parameter	Definition	Acceptable Values	Default
max_step	maximum number of level 0 time steps	Integer >= 0	-1
start_time	starting simulation time	Real >= 0	0.0
stop_time	final simulation time	Real >= 0	Very Large
start_datetime	starting simulation date/time	String (see notes)	None
stop_datetime	final simulation date/time	String (see notes)	None

Notes

• To control the number of time steps, you can limit by the maximum number of level-0 time steps (max_step), or the final simulation time (stop_time), or both. The code will stop at whichever criterion comes first. Note that if the code reaches stop_time then the final time step will be shortened so as to end exactly at stop_time, not pass it.

• For real data cases, the start and stop times is the epoch time in seconds.

• start_datetime and stop_datetime are in UTC and use the following strftime format: “%Y-%m-%d %H:%M:%S”, e.g., “2001-01-01 18:00:00”. The start/stop datetime inputs have precedence over the time inputs.

Examples of Usage

• max_step = 1000

• stop_time = 1.0

will end the calculation when either the simulation time reaches 1.0 or the number of level-0 steps taken equals 1000, whichever comes first.

Time Step

The solver timestep can be fixed by the user or computed dynamically at each timestep based on the user-specified CFL number — i.e., adaptive time stepping. For the compressible equations, the timestep calculation uses the acoustic CFL constraint. We note that when using implicit substepping, the vertical grid spacing does not appear in the time step calculation. The number of acoustic sub-steps per timestep can also be specified by the user as a fixed value or by specifying the number of substeps per RK stage. For the anelastic equations, the timestep calculation uses the advective CFL constraint, which means it is determined by the fluid speed rather than the sound speed and thus allows much larger timesteps. In both cases the horizontal terms use the physical cell widths \(\Delta x / m_x\) and \(\Delta y / m_y\), where \(m_x\) and \(m_y\) are the local map factors, so the timestep is limited by the smallest physical cell.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.substepping_type	acoustic substepping strategy for the compressible solver (per-level). Forced to None at any level where anelastic = 1	None, Implicit	Implicit (None if anelastic)
erf.anelastic_type	two-stage scheme used by the anelastic integrator (per-level); ignored where anelastic = 0. RK2 is SSP (Heun): both stages advance a full timestep and the second averages the two slow sources. MidPoint advances a half timestep in the first stage, which is what makes the implicit vertical diffusion second order – see vert_implicit_fac below	RK2, MidPoint	RK2
erf.vert_implicit	Do vertical implicit solve for diffusion of u, v, theta, KE, and moisture with default time-centering in each stage	Boolean	true
erf.vert_implicit_fac	time-centering factor for the vertical diffusive terms, where 0 is fully explicit and 1 is fully implicit. Specify either one value used in all Runge-Kutta stages, or three values, one per stage. Zeroed at any anelastic level with anelastic_type = RK2; the second and third entries are zeroed with MidPoint	1 or 3 Reals in [0,1]	1.0 1.0 0.0
erf.implicit_thermal_diffusion	include the implicit contribution to vertical thermal diffusion	Boolean	true
erf.implicit_moisture_diffusion	include the implicit contribution to vertical moisture diffusion of every moisture species (qv only with SBM, whose liquid is owned by the spectral solver)	Boolean	true
erf.implicit_ke_diffusion	include the implicit contribution to vertical turbulent kinetic energy diffusion	Boolean	true
erf.implicit_momentum_diffusion	include the implicit contributions in tau13 and tau23 used to correct u and v; the vertical diffusion of w is always explicit	Boolean	true
erf.implicit_terrain_metric	on a terrain-fitted mesh, also solve the compact terrain-metric part of the vertical diffusion, K_h M d2/dz2, in each implicit solve (u, v, theta, KE, qv), and take it out of the explicit fluxes; M is the weighted sum of the squared slopes times map factors (see the notes below)	Boolean; needs vert_implicit_fac > 0 in every stage	false
erf.cfl	CFL number used to compute level 0 dt	Real > 0 and <= 1	0.8
erf.substepping_cfl	CFL number used to compute the number of substeps: the horizontal acoustic Courant number of one substep (the vertical is excluded with implicit substepping); values near 1 are unstable	Real > 0 and <= 1	0.7
erf.fixed_dt	set level 0 dt as this value regardless of cfl or other settings	Real > 0	unused if not set
erf.fixed_fast_dt	set fast dt as this value	Real > 0	unused if not set
erf.fixed_mri_dt_ratio	set fast dt as slow dt / this ratio	even int > 0	only relevant if substepping_type is not None
erf.init_shrink	factor by which to shrink the initial dt	Real > 0 and <= 1	1.0
erf.change_max	factor by which dt can grow in subsequent steps	Real >= 1	1.1
erf.diffusive_dt_check	warn when dt times the largest explicit diffusion rate (eddy and molecular) exceeds erf.diffusive_cfl (see Notes); does not change dt or the answer	Boolean	false
erf.diffusive_dt_limit	also limit an adaptive dt to erf.diffusive_cfl divided by that rate; aborts with erf.fixed_dt, or with neither an eddy-diffusivity closure nor molecular diffusion	Boolean	false
erf.diffusive_cfl	diffusive Fourier number used by the check and the limit; aborts if given with both off	Real > 0 and <= 1	0.5
erf.dt_max	maximum adaptive timestep allowed by time stepping	Real > 0	1e9
erf.dt_max_initial	maximum initial timestep	Real > 0	1.0
erf.dt_ref_ratio	ratio of coarse to fine grid time steps between subsequent levels	Integer >= 1 (one per level)	same as maximum over directions of ref_ratio
erf.substepping_diag	print additional CFL diagnostics for the compressible solver with substepping	Boolean	false
erf.force_stage1_single_substep	if 1, take a single substep in the first Runge-Kutta stage	0, 1	1
erf.ncorr	number of corrector passes in the thin-body projection (anelastic runs with zero-flux faces); each pass adds its pressure change to the stored gradient. Also the number of corrections in the Poisson wall distance	Integer >= 1	1
erf.poisson_abstol	absolute tolerance for the Poisson solve; raised to 1.e-6 in single precision builds	Real > 0	1.e-8
erf.poisson_reltol	relative tolerance for the Poisson solve; raised to 1.e-6 in single precision builds	Real > 0	1.e-8
erf.terrain_poisson_solver	solver for the projection on a terrain-fitted mesh (anelastic, and the initial projection). gmres_fft: GMRES with ERF’s terrain operator and an FFT preconditioner (needs the FFT build). mlmg: amrex::MLTerrainPoisson with multigrid, no FFT needed. gmres_mlmg: GMRES with that multigrid as preconditioner. The three solve the same equations and agree to the solver tolerance. Each region of a level must be a rectangle. No effect on flat or stretched meshes, which still need the FFT build. See Multigrid on terrain-fitted meshes.	“gmres_fft”, “mlmg”, “gmres_mlmg”	“gmres_fft”

Notes

• If erf.anelastic is true then substepping_type is internally set to “None”.
• The implicit vertical diffusion is only second-order in time in an anelastic run when the two stages are the midpoint method and the tridiagonal solve is done in the first stage alone. Solving again in the second stage would collapse to first-order, so erf.vert_implicit_fac is zeroed for that midpoint stage; with erf.anelastic_type = RK2 the implicit solve is turned off entirely.
• The implicit vertical diffusion solves invert one tridiagonal system per column, so a column of the domain must lie entirely within a single grid. If the grids at any level are decomposed in the vertical – for example because amr.max_grid_size_z is smaller than the number of cells in z, or because the grid generator stacked boxes in z to cover a tagged region – then the code will abort rather than solve each piece of a column separately, which would impose spurious internal boundaries and make the answer depend on the grid decomposition. To run such a case, either set erf.vert_implicit_fac = 0 0 0 (equivalently erf.vert_implicit = false), turn off erf.implicit_thermal_diffusion and erf.implicit_momentum_diffusion, or choose grids that are not split in z.
• On a terrain-fitted mesh the flux through a terrain-following face projects the horizontal fluxes onto the face normal, which adds a vertical diffusion with coefficient K_h M to it, where M is a weighted sum of the squared terrain slopes times map factors: (4/3) h_xi^2 + h_eta^2 for u, h_xi^2 + (4/3) h_eta^2 for v (the deviatoric stress keeps 2/3 of the slope term in S11 and S22), and h_xi^2 + h_eta^2 for the scalars (see Momentum stresses on terrain-fitted meshes). The implicit solves treat only K_v, so for K_h M much larger than K_v – steep slopes with erf.les_type = Smagorinsky2D or anisotropic mixing on a coarse grid – this explicit term, whose rate grows as K_h M / Delta z^2, can limit the time step (a note at start-up says so for a terrain-fitted mesh with an LES closure and an explicit stage). With erf.implicit_terrain_metric = true the implicit solves also take K_h M d2/dz2 on the faces inside the domain, and the explicit fluxes give up the same term evaluated at the state they see. The split converges to the same operator as dt goes to zero (first order), but each stage increment, whatever its source, is smoothed vertically with K_h M, an effect of order dt K_h M k_z^2 that is not small near the time-step edge: on the steep 3 km ridge over 6 h, against a 5 s reference, the option at 70 s was within 1.5 % in u and 7 % in w (the WRF slope limiter at 70 s: 13 % and 40 %; without the option at 25 s: 0.5 % and 1.2 %). The difference between the averaged explicit and the compact implicit forms stays explicit; it is small for smooth fields on smooth terrain, but not at the grid scale, where the averaged form does not see a 2 Delta z wave at all. It applies to the quantities that have an implicit solve (w keeps its metric term explicit) and needs that solve in every Runge-Kutta stage: it aborts on a mesh that is not terrain-fitted, and unless erf.vert_implicit_fac is positive in all three stages at every level (use 1 1 1). In a stage without the implicit solve the whole averaged metric term is explicit for that stage. The rule is measured, not derived: with the default 1 1 0 the option gained little on a steep 3 km ridge, and with anelastic MidPoint (which solves in its first stage only) it ran worse than without it, while with 1 1 1 it recovered the time step of a run without LES. Anelastic runs therefore cannot use it. The option is off by default. Independently of it, the u and v implicit solves use the same h_zeta as the correction stress they replace, so default implicit runs on curved terrain that decays with height change slightly (see Momentum stresses on terrain-fitted meshes).
• The implicit acoustic substepping is subject to the same requirement, and for the same reason: its vertical solve is one tridiagonal system per column. Rather than test the grids after they have been made, ERF refuses at input-parsing time to combine erf.substepping_type = Implicit with any amr.no_box_split_dir other than 2, since that parameter is what keeps two grids from sharing a face normal to z in the first place. This is not a requirement of one grid per column: several grids may sit over the same column, as they do where the refined region is a staircase in z, as long as they do not touch, so that each contiguous run of cells in the column is solved by itself. A run that must be decomposed in the vertical has to set erf.substepping_type = None (or be anelastic, which sets it to None).
• A column may, however, end below the top of the domain, as it does on a refined level that does not reach the domain top, or where the refined region is a staircase in z. In that case the physical boundary condition is applied only where the column really does end at the domain boundary; elsewhere the solve is closed with the value on the coarse/fine boundary. This holds for the scalars (theta, moisture, turbulent kinetic energy) as well as for the momenta. For u and v the column of faces along a grid seam is solved over the range covered by both of the cell columns adjacent to it, so the two grids sharing that seam obtain the same answer.
• erf.diffusive_dt_check estimates on every level, at the start of every coarse step, the largest explicit diffusion rate over the cells, from the eddy diffusivities of the previous step plus the molecular ones of erf.molec_diff_type. The eddy diffusivities are zero before the first step and on the first step after a restart (they are not checkpointed). The molecular ones are added to both the horizontal and the vertical diffusivities, as the diffusion operators use them. For momentum that is erf.dynamic_viscosity with Constant and erf.dynamic_viscosity / erf.rho0_trans times the largest density around the cell with ConstantAlpha (the stresses take twice it, as they take twice the eddy viscosity). For theta it is erf.alpha_T, and for moisture and the advected scalar erf.alpha_C, times erf.rho0_trans with Constant and times the largest density around the cell with ConstantAlpha. Turbulent kinetic energy has none. For momentum the rate is the largest of the u, v and w rows, \(\mu_h (2a+b) + e_{uv}\mu_v/\Delta z^2\), \(\mu_h (a+2b) + e_{uv}\mu_v/\Delta z^2\) and \(\mu_v (a+b) + 2 \mu_v/\Delta z^2\) (the vertical diffusion of w is always explicit; its horizontal diffusion uses \(\mu_v\): \(\tau_{31}\) and \(\tau_{32}\) carry the same edge-averaged \(\mu_v\) as \(\tau_{13}\) and \(\tau_{23}\)); each row also counts the explicit u-w and v-w cross derivatives, \(\mu_v\sqrt{a c}\) and \(\mu_v\sqrt{b c}\) with \(c = 1/\Delta z^2\) (added to the w row for both directions), which exceed the vertical term where \(\Delta z > \Delta x/m\); plus \(2 \max(\mu_h,\mu_v) h^2/\Delta z^2\), all divided by \(\rho\); for theta, turbulent kinetic energy, moisture and the advected scalar (where carried) it is \([K_h (a+b) + K_h h^2/\Delta z^2 + e K_v/\Delta z^2]/\rho\), with \(a = (m_x/\Delta x)^2\), \(b = (m_y/\Delta y)^2\), \(h\) the physical terrain slope of the cell (zero without terrain) and \(\Delta z\) the cell thickness. Each diffusivity is the largest over the cell and its 26 neighbours, and \(\rho\) the smallest, whatever face or edge averages the stencils use. With the coefficients frozen this is a Gershgorin bound on the centred interior stencil of the scalar operator (the higher-order one-sided gradients used next to Dirichlet boundaries are not covered: their row is up to about 4/3 larger, so there the rate can be low by that factor); for momentum it is a bound for uniform coefficients when \(\mu_h = \mu_v\) and an estimate otherwise (the operator is then not symmetric), and the terrain cross terms make both estimates. The terrain-metric term \(K h^2 \partial^2/\partial z^2\) is explicit unless erf.implicit_terrain_metric = true. For momentum it is an upper bound: the projected horizontal stresses of u and v carry \(\mu_h\) and those of w \(\mu_v\) (see Momentum stresses on terrain-fitted meshes). With erf.implicit_terrain_metric = true the compact form of the \(K_h\) part is in the implicit solve for u, v, theta, turbulent kinetic energy and the first moisture variable, so for those components it counts with their \(e\) (below), as the vertical term does; the difference between the averaged and the compact forms stays explicit and is not counted, so the rate is then an estimate. \(e\) is 0 when the implicit vertical solve is shown to keep every stage of that component’s vertical diffusion bounded (no stage amplifies a mode), and 1 otherwise. This is decided analytically: with the three-stage scheme (stages from the old state with steps dt/3, dt/2 and dt) every stage is bounded when erf.vert_implicit_fac has \(f_1 \ge 1/2\) and \(f_2 = 1\), whatever \(f_3\), and with the anelastic MidPoint scheme when \(f_1 = 1\). Every other pattern, including factors outside [0, 1], counts as explicit; some of those are in fact bounded, so the rule is sufficient, not necessary. So the default 1 1 0 (Crank-Nicolson for the vertical diffusion) and 1 1 1 (backward Euler) give \(e = 0\), and 0 0 0, anelastic RK2 (no implicit solve), 1 0 0, 0 0 1 or 0.995 0.1 0.0666 (whose last stage amplifies by 1.0008) give \(e = 1\). Every moisture variable is in the implicit solve (with SBM only qv, the one the host diffuses), so the moisture term has \(e = 1\) only when a microphysics model also carries non-water species (packed directly after the water species, these diffuse explicitly), and the advected scalar always does. If dt times this rate exceeds erf.diffusive_cfl a warning is printed, repeated on a level only when the Fourier number has grown by half. The default 0.5 is the forward-Euler bound; the three-stage scheme is stable to about 0.63 for a pure diffusion. With erf.diffusive_dt_limit = true an adaptive dt is also limited to erf.diffusive_cfl divided by the rate (printed with erf.v >= 1 when it applies); on the first step after a restart, when the rate is not known, dt is held at the checkpointed step instead (which the limit bounded only if the run that wrote it used the limit). The limit changes the answer; the check alone does not. With erf.diffusive_dt_check = true and erf.v >= 2 the Fourier number of every step is printed. The check is a safeguard rather than a stability guarantee: it is conservative and can flag runs that stay stable, so a warning is a prompt to look, not a prediction of failure. Cells inside immersed-forcing solids count like fluid cells, and the cut-cell stiffening of EB is not included.
• When erf.diffusive_dt_check, erf.diffusive_dt_limit or a Smagorinsky2D limit (erf.smag2d_slope_limiter, erf.smag2d_kh_cap) is on, on a terrain-fitted mesh where the horizontal and vertical eddy viscosities can differ (Smagorinsky2D, Smagorinsky or Deardorff with erf.mix_isotropic = false, or any PBL scheme), the largest slope factor \(\alpha = h \Delta x/\Delta z\) of each level and the number of cells with \(\alpha > 1\) are printed whenever a level has a new set of grids (at initialisation, on the first step after a restart, and at the coarse step after a regrid), and with erf.terrain_type = MovingFittedMesh also whenever the largest \(\alpha\) changes by more than 1 %. Without those options nothing is computed or printed.
• The time step controls work somewhat differently depending on whether one is using acoustic substepping in time; this is determined by the value of substepping_type.
• If erf.substepping_type = None there is only one time step to be calculated, and erf.fixed_fast_dt and erf.fixed_mri_dt_ratio are not used.
  • If erf.fixed_dt is also specified, the timestep will be set to fixed_dt.
  • If erf.fixed_dt is not specified, the timestep will be computed using the CFL condition for compressible flow. If erf.cfl is specified, that CFL value will be used. If not, the default value will be used.
• If erf.substepping_type is not None we must determine both the slow and fast timesteps.
  • If erf.fixed_dt is specified, the slow timestep will be set to fixed_dt.
  • If erf.fixed_dt is not set, the slow timestep will be computed using the CFL condition for incompressible/anelastic flow. If erf.cfl is specified, that CFL value will be used. If not, the default value will be used.
  • There are several consistency checks before the fast timestep is computed. Specifically, if any of the following are true the code will abort while reading the inputs.
    • If erf.fixed_mri_dt_ratio is specified but is not an even positive integer
    • If erf.fixed_dt and erf.fixed_fast_dt are specified and the ratio of fixed_dt to fixed_fast_dt is not an even positive integer
    • If erf.fixed_dt and erf.fixed_fast_dt and erf.fixed_mri_dt_ratio are all specified but are inconsistent
  • Once the slow timestep is set and the inputs are allowed per the above criteria, the fast timestep is computed in one of several ways:
    • If erf.fixed_fast_dt is specified, the fast timestep will be set to fixed_fast_dt.
    • If erf.fixed_mri_dt_ratio is specified and erf.fixed_fast_dt is not specified, the fast timestep will be the slow timestep divided by fixed_mri_dt_ratio.
    • If neither erf.fixed_mri_dt_ratio nor erf.fixed_fast_dt is specified, then the fast timestep will be computed using the CFL condition for compressible flow with erf.substepping_cfl (default 0.7). The ratio of slow timestep to fast timestep is rounded up, so the fast timestep never exceeds that limit, and then increased to the next even integer (or, if erf.force_stage1_single_substep = 0, to the next multiple of 6).

Examples of Usage of Additional Parameters

• erf.init_shrink = 0.01

  sets the initial slow time step to 1% of what it would be otherwise. Note that if erf.init_shrink \(\neq 1\) and fixed_dt is specified, then the first time step will in fact be erf.init_shrink * erf.fixed_dt.
• erf.change_max = 1.1

  allows the slow time step to increase by no more than 10% in this case. Note that the time step can shrink by any factor; this only controls the extent to which it can grow.

Restart Capability

See Checkpoint / Restart for how to control the checkpoint/restart capability. The parameters documented there, rather than on this page, are

• amr.restart, erf.check_file, erf.check_int, erf.check_per, erf.restart.

Additional Checkpoint Controls

These are AMReX-level checkpoint controls that may be specified either with the erf prefix or the amr prefix.

List of Parameters

Parameter	Definition	Acceptable Values	Default
amr.check_int	Checkpoint interval (steps)	Integer >= 0	-1
amr.check_per	Checkpoint interval (time)	Real >= 0	-1.0

Notes

• If both are specified, amr.check_int takes precedence and amr.check_per is ignored.

• These are in addition to the main checkpoint controls described in Checkpoint / Restart.

PlotFiles

See Plotfiles for how to control the types and frequency of plotfile generation. The parameters documented there, rather than on this page, are

• erf.file_name_digits, erf.plot2d_file_1, erf.plot2d_file_2, erf.plot2d_int_1, erf.plot2d_int_2, erf.plot2d_per_1, erf.plot2d_per_2, erf.plot_face_vels, erf.plot_file_1, erf.plot_file_2, erf.plot_int_1, erf.plot_int_2, erf.plot_per_1, erf.plot_per_2, erf.plotfile2d_type, erf.plotfile2d_type_1, erf.plotfile2d_type_2, erf.plotfile_type, erf.plotfile_type_1, erf.plotfile_type_2, erf.subvol.dxdydz, erf.subvol.chunk_size, erf.subvol.nxnynz, erf.subvol.origin, erf.subvol_file, erf.subvol_int, erf.subvol_per, erf.use_real_time_in_pltname.

The names of the fields that may be selected are listed in 3D plotfile variable reference and 2D plotfile diagnostic reference.

Boundary Files

Parameter	Definition	Acceptable Values	Default
erf.write_erfbdy	Write AMReX-native format boundary file for real-data cases only	Boolean	true for non-restart metgrid cases, otherwise false
erf.use_erfbdy	Read the boundary data from the erfbdy file instead of from nc_bdy_file; applies to the wrfinput pathway only	Boolean	false
erf.erfbdy_file	Name of the boundary file	String	“erfbdy”

Additional Plotfile Controls

List of Parameters

Parameter	Definition	Acceptable values	Default
erf.compute_mean_vars	Accumulate interval first and second moments for resolved plot diagnostics	Boolean	false
erf.mean_vars_reset_mode	Reset moments after a complete 3-D plotfile batch or once at a specified time	plotfile or time	plotfile
erf.mean_vars_reset_time	Reset time when reset mode is time	Real [s], >= 0	-1.0

When erf.compute_mean_vars = true, ERF makes the interval fields u_mean, v_mean, w_mean, theta_mean, the corresponding second moments, resolved variances/covariances, and resolved tke_resolved available to erf.plot_vars_1 and erf.plot_vars_2. See 3D plotfile variable reference for definitions. In time reset mode, the accumulator is reset once, at the first step whose start time is at or beyond erf.mean_vars_reset_time. In plotfile mode, a reset occurs only after all 3-D streams due at the same output event have been written and at least one emitted stream contains an interval diagnostic; a density-only stream does not close the shared averaging window. Also in plotfile mode, the sample taken at initialization is dropped at the end of initialization whether or not an initial plotfile was written, so the first interval covers the steps taken since initialization, just as every later interval covers the steps since the previous output event. An initial plotfile still reports that sample, i.e. the means of the initial state. Dropping it is what keeps the averaging window independent of the output cadence, and so makes the interval fields exact across a checkpoint/restart. In time mode the initialization sample is part of the configured window and is kept. In either mode, regridding keeps the averaging window: a remade level copies its old accumulator wherever its old and new grids overlap, and cells it newly covers, like a newly created level, take the coarser level’s average over the same window (by piecewise-constant interpolation). All levels therefore report the same window; see 3D plotfile variable reference.

Screen Output

List of Parameters

Parameter	Definition	Acceptable Values	Default
amr.v	verbosity of Amr.cpp	0 or 1	0
erf.v	verbosity of ERF.cpp	0, 1 or 2	0
erf.sum_interval	if \(> 0,\) how often (in level-0 time steps) to compute and print integral quantities	Integer	-1

Examples of Usage

• erf.sum_interval = 2

  if erf.sum_interval \(> 0\) then the code computes and prints certain integral quantities, such as total mass, momentum and energy in the domain every erf.sum_interval level-0 steps. In this example the code will print these quantities every two coarse time steps (with erf.v \(\geq 1\)). The print statements have the form

  TIME= 1.91717746

  MASS = 1.7924102790000001e+34

  for example, with a line each for the mass, \(\rho\theta\), the scalar and the total moisture. With more than one level each line holds two values, SL/ML: the integral over level 0 alone and the composite one, which uses the finest data available. Each cell is weighted by its volume, \(\det J/(m_x m_y)\), so these are the quantities the discretization conserves, and they are printed with every digit of the working precision. If this line is commented out then it will not compute and print these quantities.

Diagnostic Outputs

If erf.v is set then one or more additional output files may be requested. These are useful for idealized, horizontally homogeneous simulation domains and include (1) a surface time history file, (2) a history of mean profiles, (3) a history of vertical flux profiles (i.e., variances and covariances), (4) a history of modeled subgrid stresses, and (5) a history of large scale forcing and nudging data. The profiles are calculated from planar averages.

The number of output filenames specified through erf.data_log dictates the level of output. E.g., specifying 3 filenames will give outputs (1), (2), and (3); specifying 5 filenames will also include output (5). Data files are only written if erf.profile_int > 0.

This output functionality has not been implemented for terrain. For real simulation domains, users should use 2-D and 3-D Plotfiles.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.data_log	Output filename(s)	Up to five strings	NONE
erf.der_data_log	Output filename(s) for derived data	Up to four strings	NONE
erf.energy_data_log	Output filename for the level-0 volume-weighted means of the total mass rho_d (1 + q_t) [kg/m3] and the total energy [J/m3], every erf.sum_interval steps or erf.sum_period seconds when erf.v > 0. q_t sums the vapour, liquid (cloud, rain) and ice mixing ratios. The energy is a diagnostic definition (Romps 2008): internal energy with constant heat capacities, from liquid water at the triple point, plus kinetic and potential energy; ERF does not conserve it exactly	One string (the first of up to four is written)	NONE
erf.profile_int	Interval (number) of steps between outputs	Integer	-1
erf.destag_profiles	Interpolate all outputs to cell-center heights	Boolean	true
erf.Ave_Plane	index of the direction normal to the planes used when computing horizontal averages	0, 1, 2	2
erf.time_avg_vel	accumulate and output time-averaged velocity fields	Boolean	false
erf.test_mapfactor	set the map scale factors to 0.5 instead of 1 for testing; see Map Factors (Dry)	Boolean	false
erf.sum_period	wall-clock-independent simulation-time interval [s] between integrated-quantity summaries; an alternative to erf.sum_interval	Real	-1.0 (not used)
erf.pert_interval	number of steps between reports of the perturbational diagnostics	Integer	-1 (not used)
erf.profile_rad_int	number of steps between writes of the radiation profile log; read only in an RRTMGP build	Integer	-1 (not used)
erf.plot_lsm	write the land-surface-model fields to the plotfile	Boolean	false
erf.plot_surfmodel	write SurfaceModel fields to plt_surf_* files; independent of erf.plot_lsm	Boolean	both LSM+Urban active by default false otherwise
erf.plot_rad	write the radiation fields to the plotfile; read only in an RRTMGP build	Boolean	false
erf.plot_face_terrain_blanking	write the face-based terrain blanking mask to the plotfile	Boolean	false
erf.write_eb_surface	write the embedded-boundary surface as a separate file	Boolean	false
erf.rad.datalog	name of the log file to which radiation diagnostics are written	String	None

All profiles are planar-averaged quantities \(\langle\cdot\rangle\) that are destaggered by interpolating to cell centers where appropriate. Setting erf.destag_profiles = false will keep vertically staggered quantities on z faces – quantities already at cell centers or on x/y faces will remain at those locations. Note that all output quantities – whether cell-centered or face-centered – will be output on the staggered grid. The user should discard values at the highest z level (corresponding to the z-dir of amr.n_cell + 1) for destaggered quantities. Staggered quantities are indicated below.

The requested output files have the following columns:

• Surface time history

  1. Time (s)

  2. Friction velocity, \(u_*\) (m/s)

  3. Surface-layer potential temperature scale, \(\theta_*\) (K)

  4. Obukhov length, \(L\) (m)

• Mean flow profiles

  1. Time (s)

  2. Height (m)

  3. X-velocity, \(\langle u \rangle\) (m/s)

  4. Y-velocity, \(\langle v \rangle\) (m/s)

  5. Z-velocity, \(\langle w \rangle\) (m/s) – staggered

  6. Dry air density, \(\langle \rho \rangle\) (kg/m3)

  7. Total (moist) potential temperature, \(\langle \theta \rangle\) (K)

  8. Turbulent kinetic energy (TKE), \(\langle k \rangle\) (m2/s2) from the Deardorff subgrid model only

  9. Eddy diffusivity, \(\langle K \rangle\) (kg/(m-s)) from the subgrid model

  10. Water vapor mixing ratio, \(\langle q_v \rangle\) (kg/kg) from the microphysics model

  11. Cloud water mixing ratio, \(\langle q_c \rangle\) (kg/kg) from the microphysics model

  12. Rain water mixing ratio, \(\langle q_r \rangle\) (kg/kg) from the microphysics model, if available

  13. Ice mixing ratio, \(\langle q_i \rangle\) (kg/kg) from the microphysics model, if available

  14. Snow mixing ratio, \(\langle q_s \rangle\) (kg/kg) from the microphysics model, if available

  15. Graupel mixing ratio, \(\langle q_g \rangle\) (kg/kg) from the microphysics model, if available

• Vertical flux profiles

  1. Time (s)

  2. Height (m)

  3. X-velocity variance, \(\langle u^\prime u^\prime \rangle\) (m2/s2)

  4. X,Y-velocity covariance, \(\langle u^\prime v^\prime \rangle\) (m2/s2)

  5. X,Z-velocity covariance, \(\langle u^\prime w^\prime \rangle\) (m2/s2) – staggered

  6. Y-velocity variance, \(\langle v^\prime v^\prime \rangle\) (m2/s2)

  7. Y,Z-velocity covariance, \(\langle v^\prime w^\prime \rangle\) (m2/s2) – staggered

  8. Z-velocity variance, \(\langle w^\prime w^\prime \rangle\) (m2/s2) – staggered

  9. X-direction heat flux, \(\langle u^\prime \theta^\prime \rangle\) (K m/s)

  10. Y-direction heat flux, \(\langle v^\prime \theta^\prime \rangle\) (K m/s)

  11. Z-direction heat flux, \(\langle w^\prime \theta^\prime \rangle\) (K m/s) – staggered

  12. Temperature variance, \(\langle \theta^\prime \theta^\prime \rangle\) (K m/s)

  13. X-direction turbulent transport of TKE, \(\langle u_i^\prime u_i^\prime u^\prime \rangle\) (m3/s3) – Note: \(u_i u_i = uu + vv + ww\)

  14. Y-direction turbulent transport of TKE, \(\langle u_i^\prime u_i^\prime v^\prime \rangle\) (m3/s3)

  15. Z-direction turbulent transport of TKE, \(\langle u_i^\prime u_i^\prime w^\prime \rangle\) (m3/s3) – staggered

  16. X-direction pressure transport of TKE, \(\langle p^\prime u^\prime \rangle\) (m3/s3)

  17. Y-direction pressure transport of TKE, \(\langle p^\prime v^\prime \rangle\) (m3/s3)

  18. Z-direction pressure transport of TKE, \(\langle p^\prime w^\prime \rangle\) (m3/s3) – staggered

  19. Z-direction flux of water vapor, \(\langle q_v^\prime w^\prime \rangle\) (m/s) – staggered

  20. Z-direction flux of cloud water, \(\langle q_c^\prime w^\prime \rangle\) (m/s) – staggered

  21. Z-direction flux of rain water, \(\langle q_r^\prime w^\prime \rangle\) (m/s) – staggered

  22. Z-direction virtual temperature flux, \(\langle w^\prime \theta_v^\prime \rangle\) (K m/s) – staggered

• Modeled subgrid-scale (SGS) profiles

  1. SGS stress tensor component, \(\tau_{11}\) (m2/s2)

  2. SGS stress tensor component, \(\tau_{12}\) (m2/s2)

  3. SGS stress tensor component, \(\tau_{13}\) (m2/s2) – staggered

  4. SGS stress tensor component, \(\tau_{22}\) (m2/s2)

  5. SGS stress tensor component, \(\tau_{23}\) (m2/s2) – staggered

  6. SGS stress tensor component, \(\tau_{33}\) (m2/s2)

  7. SGS heat flux, \(\tau_{\theta w}\) (K m/s) – staggered

  8. SGS water vapor flux, \(\tau_{q_v w}\) (K m/s) – staggered

  9. SGS cloud water flux, \(\tau_{q_c w}\) (K m/s) – staggered

  10. SGS turbulence dissipation, \(\epsilon\) (m2/s3)

• Large scale forcing and nudging profiles

  1. Time (s)

  2. Height (m)

  3. Total applied temperature tendency, \(\partial \theta / \partial t\) (K/s)

  4. Total applied water vapor tendency, \(\partial q_v / \partial t\) (kg/kg/s)

  5. Large-scale subsidence velocity, \(w_{sub}\) (m/s)

  6. Horizontal temperature tendency, \(\partial \theta / \partial t\) (K/s)

  7. Horizontal water vapor tendency, \(\partial q_v / \partial t\) (kg/kg/s)

  8. Vertical temperature tendency, \(\partial \theta / \partial t\) (K/s)

  9. Vertical water vapor tendency, \(\partial q_v / \partial t\) (kg/kg/s)

  10. Vertical cloud water tendency, \(\partial q_c / \partial t\) (kg/kg/s)

  11. Temperature nudging tendency, \(\theta_{nudge}\) (K/s)

  12. Water vapor nudging tendency, \(q_{v,nudge}\) (kg/kg/s)

  13. X-velocity nudging tendency, \(u_{nudge}\) (m/s2)

  14. Y-velocity nudging tendency, \(v_{nudge}\) (m/s2)

Note

The vertical tendency columns are only populated for interior cells between the bottom and top boundaries; they are zero at the domain edges.

Data Sampling Outputs

Note

For WRF users: The ERF analog of wrfout and auxhist history files are AMReX-format Plotfiles. Unlike WRF, which combines 2-D and 3-D field quantities into a single history file, ERF allows separate outputs at different intervals.

To obtain history files in netcdf format, it is recommended to convert from the native AMReX output using postprocessing tools provided in Exec/Tools if using gmake, or with the ERF_ENABLE_TOOLS flag if using cmake.

The ERF analog of tslist output is the station time series described in Station Time Series below, which samples named points given in latitude and longitude. The line and plane sampling described first in this section writes whole lines and planes rather than points.

Data along query lines or planes may be output during the simulation if erf.do_line_sampling = true or erf.do_plane_sampling = true, respectively. The potential temperature and wind-speed will be written to native plt_line/plane at the step frequency dictated by erf.line_sampling_interval = <int> or erf.plane_sampling_interval = <int>. For line sampling, users must prescribe either sample_line_lo and sample_line_hi inputs, which are 3 integer values corresponding to the (i,j,k) indices at the beginning and end of the line, or sample_line_lo_real and sample_line_hi_real, which are 3 real values corresponding to the physical locations of the beginning and end of the line. These two ways of specifying the line are mutually exclusive. Additionally, users must specify sample_line_dir to prescribed the direction of the line. The same inputs are used for the plane sampling except that sample_plane_lo/hi must be the physical locations of the plane corners. This output functionality has not been implemented for terrain. By default, sampled line and plane data will have the prefixes “plt_line” and “plt_plane”, respectively. Names for sampled data may optionally be provided with sample_line_name and/or sample_plane_name – if provided, each line and/or plane must be named.

Plane samples are written as true multi-level AMReX plotfiles: every refinement level whose grids intersect the plane is written (Level_0, Level_1, …), so a plane that cuts through static refinement patches retains the finer in-plane resolution there. By default all intersecting levels are written; erf.plane_sampling_max_level = <int> caps the finest level (0 forces level-0-only output). The slice-normal direction is resolved natively on each level by replicating the sampled plane across the level’s cells, so the resulting dataset has an isotropic refinement ratio and loads cleanly in amrvis.

Line and plane samples will be default be written to plotfiles, one plotfile per output snapshot, with all output variables in the same file. Alternatively, line sampling has the erf.line_sampling_text_output option, which writes one text file per output variable, with all snapshots appended to the same file over time. This is similar to the tslist output from WRF but output is provided only from the finest domain that contains the entire requested sampling line; velocities are also destaggered.

The sampled variables can be selected with the erf.line_sampling_vars and erf.plane_sampling_vars options and include a subset of the plotfile outputs: density, x_velocity, y_velocity, z_velocity, magvel, theta, qv, qc, and pressure. Line sampling additionally supports sgs_tke, sgs_tau13, sgs_tau23, and sgs_hfx3. The SGS stress and heat-flux values are averaged from their native edge/face locations to cell centers; if their diffusion storage is unavailable, ERF writes zero. Velocities are output at cell centers only. The water vapor mixing ratio qv will only output valid values if a moisture model is used. Pressure is calculated from rho*theta and will account for moisture if qv is requested. sgs_tke is zero unless the selected level has a prognostic TKE closure (Deardorff, k-equation RANS, MYJ/MYNN, or a SHOC-family PBL); Smagorinsky and les_type = None do not provide prognostic TKE and their unused state slot is never sampled.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.line_sampling_interval, erf.plane_sampling_interval	Output frequency (steps)	Integer	-1
erf.line_sampling_per, erf.plane_sampling_per	Output frequency (time)	Real	-1
erf.do_line_sampling	Flag to do line sampling	Boolean	false
erf.do_plane_sampling	Flag to do plane sampling	Boolean	false
erf.sample_line_dir	Directionality of the line	Integer	None
erf.sample_plane_dir	Directionality of the plane	Integer	None
erf.sample_line_lo/hi	Bounding (i,j,k) on the line(s)	3 Integers per line	None
erf.sample_line_lo_real, erf.sample_line_hi_real	Bounding point on the line(s)	3 Reals per line	None
erf.sample_plane_lo/hi	Bounding point on the plane(s)	3 Reals per plane	None
erf.sample_line_name	Output prefix of each line	One string per sample line	None
erf.sample_plane_name	Output prefix of each plane	One string per sample plane	None
erf.line_sampling_text_output	Write text files instead of AMReX plotfiles	Boolean	false
erf.line_sampling_vars	Specify sampled variables; SGS fields are line- only	List of strings	theta, magvel
erf.plane_sampling_vars	Specify sampled variables	List of strings	theta, magvel
erf.plane_sampling_max_level	Cap on finest level written to the plane plotfile	Integer	-1 (all intersecting levels)
erf.sample_point	points at which the state is written to a log, given as flattened (i,j,k) index triples	List of Integers, in triples	None
erf.sample_point_log	log-file name for each sampled point; exactly one name per point is required	List of Strings	None
erf.sample_line	lines along which the state is written to a log, given as flattened (i,j,k) index triples; may not be combined with erf.sample_line_real	List of Integers, in triples	None
erf.sample_line_real	as above, but the lines are given as flattened (x,y,z) physical-coordinate triples; may not be combined with erf.sample_line	List of Reals, in triples	None
erf.sample_line_log	log-file name for each sampled line; exactly one name per line is required	List of Strings	None

Example of Usage

erf.do_line_sampling = true               # Do line sampling
erf.line_sampling_interval = 1            # Write plt files every step
erf.sample_line_lo   = 5 32  5 10   32 5  # Lo points for two lines
erf.sample_line_hi   = 5 32 25 1000 32 5  # Hi points for two lines
erf.sample_line_dir  = 2 0                # One line in z and one in x

erf.do_plane_sampling = true              # Do plane sampling
erf.plane_sampling_interval = 10          # Write plt files every 10 steps
erf.sample_plane_lo   =  48.0  48.0  32.0 # Lo points for one plane
erf.sample_plane_hi   = 320.0 320.0  32.0 # Hi points for one plane
erf.sample_plane_dir  = 2                 # One plane with z normal

Station Time Series

A station is a named set of points at which a chosen set of variables is written to an ASCII time series, one file per station, for comparison against meteorological tower and surface-station observations. This is the ERF analog of WRF’s tslist.

Stations are declared the way refinement indicators are: erf.station_names lists the names, and the keys of each station live under its own prefix.

erf.station_names = Lake1 Forests

erf.Lake1.field    = rain_accum
erf.Lake1.lat      = 45.13
erf.Lake1.long     = -122.34

erf.Forests.field  = magvel local_helicity
erf.Forests.lat    = 45.20 45.41
erf.Forests.long   = -122.10 -122.02
erf.Forests.height_agl = 10.0 80.0

erf.station_sampling_interval = 10

How often the stations are written has no default and must be given, as it must for the line and plane samplers: either erf.station_sampling_interval in steps or erf.station_sampling_per in seconds. A sample is not free – see the note on cost below – so a run with a short time step should not be made to guess at it.

lat and long are paired positionally, so Forests above is two locations, not four; the two lists must have the same number of values. lon is accepted as a synonym for long. A station may instead be placed with .x and .y in domain coordinates, which is the only option for a run that has no latitude/longitude arrays; a station uses one form or the other, never both.

Heights are given one of two ways, and apply to every location of the station. height_agl is in metres above the local terrain, which is what a tower measurement is; height_abs is in metres in the model’s own vertical coordinate, the one geometry.prob_lo and geometry.prob_hi are given in, which is what an aircraft or a sounding level is. A station uses one or the other, never both. One of them is required if the station requests any 3D variable; both are ignored by 2D variables, which are surface quantities.

A vertical profile above a site is a station with a long height list, for example erf.Site.height_agl = 100 250 500 1000 2000 3000 4000 5000. The input parser puts no limit on the number of heights. The file then holds one column for each 3D variable at each height, so n heights and m 3D variables make n * m columns per location (plus one for each 2D variable), and a height above the top of the domain returns the value at the top, as described below. The cadence is erf.station_sampling_interval or erf.station_sampling_per.

The local terrain is the elevation of the ground at the station itself, interpolated bilinearly from the terrain at the nodes around it: the bottom of a terrain-fitted mesh, or, with erf.terrain_type = ImmersedForcing, the terrain surface the immersed boundary is built from (the mesh is then flat, and its bottom is not the ground).

The variable names accepted are the names of the 3D plotfile variables (erf.plot_vars_1) and of the built-in 2D diagnostics (erf.plot2d_vars_1), and the values are produced by the same code, so a station column and the corresponding plotfile component cannot disagree. A 2D plotfile can also carry sampled-level fields, named for the field and the level such as theta_z100m; those are the one thing it can write that a station cannot be asked for, since a station asks for the 3D variable and a height directly. A name that is none of these stops the run and says so, as does a 3D name that this configuration cannot produce; a 2D diagnostic that is valid but not computed in this run is written as the missing value it would have in a 2D plotfile (0 or -999 depending on the diagnostic) rather than being dropped.

A 3D name that this configuration cannot produce – qsnow under Kessler microphysics, for example, since Kessler carries no ice – can be treated the same way by setting erf.station_allow_unavailable = true. Its column is then kept and written as -999 at every height, the header marks it as not available in this run, and the run prints a warning, so one station list can be shared by configurations that carry different fields. The default is false, which stops the run: a column that holds no data is easy to overlook in a long series, so it has to be asked for. A name that is neither a 3D nor a 2D variable still stops the run.

Four more names give earth-relative winds, for comparison with towers, which report them: u_east and v_north (m/s), wind_speed (the horizontal speed, m/s) and wind_dir (the meteorological direction the wind comes from, in degrees clockwise from north; -999 when the wind is calm). They are 3D variables, so they need a height like any other. Each is formed from the station’s interpolated x_velocity and y_velocity, rotated by the orientation of the grid at the station, which is read from the run’s latitude/longitude arrays (a WRF or metgrid initialization, or a restart from one). Without those arrays the grid is taken to be aligned with east and north, so u_east equals x_velocity. The angle is that of the level-0 cell that holds the station, and the header gives it for each column. These are the same formulas as the 2D sampled-level fields of the same names (2D sampled-level output); a 2D level set writes its own missing_value (default -999) for a calm wind_dir, the station always -999. “Calm” means a wind of exactly zero.

Values are interpolated bilinearly in the horizontal and linearly in the vertical, taken from the finest level that covers the interpolation stencil from the bottom of the domain up through the requested heights. Coverage is required from the bottom because height_agl is measured from the local terrain, but not above the heights asked for, so a level that refines only the lower part of the domain still supplies a station within it. Within the outer half cell of a non-periodic boundary there is no second cell to interpolate from, so the horizontal stencil collapses to the edge cell; below the first cell centre and above the top of the domain the vertical interpolation likewise uses the nearest value.

Warning

Below the first cell centre there is nothing to interpolate, so a height there returns the first cell centre’s value unchanged – it is not extrapolated to the requested height by surface-layer similarity. In a run whose first cell is 100 m deep, height_agl = 10.0 and height_agl = 40.0 both report the value 50 m up. For 2 m and 10 m quantities, ask for the 2D diagnostics (temperature_2m, water_vapor_mixing_ratio_2m, the 10 m winds u_10m, v_10m, u_east_10m and v_north_10m, and the other surface-layer diagnostics), which are computed from the surface-layer parameterization; the run warns once if a requested height falls in that first half cell.

Warning

Which level supplies a station follows from the grids, so on a run that regrids it can change mid-series: a station that the refined region grows to cover starts being read from the finer level, at that level’s resolution and from that level’s solution. The series steps at that point rather than changing smoothly, which matters when it is being compared against an observed record. Run with erf.v = 1 to see which level each station was resolved to. A station whose level should not change can be kept on one by placing it away from a refinement boundary, or by refining on a fixed box rather than on a moving indicator.

Each station is written to Output_Stations/<name>.dat. The header names every column, with its units where they are known, the requested position, the position actually sampled, and the height. Columns are ordered by location: for each location, the 2D variables first, then, for each height in the order requested, the 3D variables in the order requested. When erf.use_datetime is set, a UTC timestamp column follows the elapsed-time column.

The series starts at the initial condition, as WRF’s tslist output does; a restart does not repeat that row, since the run that wrote the file before already has it.

Rows are buffered in memory and written out every erf.station_buffer_steps output steps, whenever a 2D or 3D plotfile or a checkpoint is written, and at the end of the run. A run that aborts loses only the rows sampled since the last of these, so the station series reaches at least as far as the plotfiles do; a smaller erf.station_buffer_steps narrows that window further, at the cost of reopening every station file more often. A restart appends to the file the earlier run wrote, so the series is continuous across a restart; the resumption is marked by a comment line. Because the buffer is flushed with every checkpoint, a restart from any checkpoint picks the series up where that checkpoint left it: rows the earlier run wrote past that point are dropped, so the series never runs backwards, and the run reports how many were dropped. A restart into a file whose header describes a different set of columns – a changed field, location or height list – stops the run rather than appending columns the header does not describe.

That comparison is of one line, not of the header as a whole. Each file carries a # format: line holding a format tag and a hash of what the columns are: the variables, their units, the locations as the inputs file asked for them, the heights, and their order. A restart recomputes that signature and compares it, which means rewording the rest of the header does not make an existing series un-restartable, and neither does a coordinate that the setup resolves to a value differing in its last digits – a resolved position is derived from the latitude/longitude arrays, so it can move with the build without the configuration having changed. The check runs at setup, as soon as the columns are resolved, so a configuration that cannot continue an existing series costs a setup rather than a run. When it does fail, the human-readable part of the header is read to report which column differs.

Station names are used as file names, so they are limited to letters, digits, _, - and ., must begin with a letter or an underscore, and must be distinct.

Note

Station output is enabled by naming stations; setting erf.do_station_sampling = false turns it off again without removing the stations from the inputs file. Naming stations without giving erf.station_sampling_interval or erf.station_sampling_per stops the run: there is no default cadence.

Note

A station column costs more than its one value. Each sampled step fills the requested 3D and 2D plot variables over the whole of every level that hosts a station, in the same way a plotfile does, and interpolates a 2x2 column out of the result; it also fillpatches the state on every level up to the highest one a station is on, and re-derives which level and which cells each station is read from, whether or not the grids have moved since the last sample. The cost of a sample therefore scales with the number of field names and the size of the levels, not with the number of stations, and asking for one velocity component fills all three. None of it happens on a step that is not sampled, so the cadence is the control that matters: ask for the variables you will use, and set erf.station_sampling_interval or erf.station_sampling_per to the rate the series actually needs rather than to the time step. The fill is a diagnostic: it does not change the solution, and a run with station output turned on gives the same answer as one without. That is tested rather than asserted – the StationSampling_AnswerParity* regression tests run a deck with the stations off and on and require the plotfiles to be identical bit for bit, on a two-level dry case and on a surface-layer case – with two gaps: no test covers a case with Lagrangian microphysics, and none covers a run driven by time-dependent lateral boundary data, for which no deck can run in CI. See Regression Tests.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.station_names	Names of the stations to write	List of Strings	None
erf.do_station_sampling	Write station output at all; naming stations turns this on, setting it false turns it back off	Boolean	true if stations are named
erf.<name>.field	Variables to write at this station; 3D or 2D plotfile variable names	List of Strings	None
erf.<name>.lat, erf.<name>.long	Locations of this station, paired positionally; not to be combined with .x / .y	List of Reals, degrees	None
erf.<name>.x, erf.<name>.y	Locations of this station in domain coordinates, paired positionally; not to be combined with .lat / .long	List of Reals	None
erf.<name>.height_agl	Heights above the local terrain at which the 3D variables are sampled; not to be combined with .height_abs	List of Reals, metres	None
erf.<name>.height_abs	Heights in the model’s vertical coordinate at which the 3D variables are sampled; not to be combined with .height_agl	List of Reals, metres	None
erf.station_sampling_interval	Output frequency (steps); one of this and station_sampling_per is required	Integer	None
erf.station_sampling_per	Output frequency (time); one of this and station_sampling_interval is required	Real, seconds	None
erf.station_buffer_steps	Output steps buffered before the files are written	Integer	100
erf.station_output_dir	Directory the station files are written to	String	Output_Stations
erf.station_allow_unavailable	Write a 3D variable this configuration cannot produce as -999 instead of stopping the run	Boolean	false

Note

Latitude and longitude need a run that has them: an initialization from a WRF or metgrid file, or a restart from one. Both paths store mass-point values – XLAT and XLONG from wrfinput, XLAT_M and XLONG_M from met_em – so the station sampler uses them directly and a station lands on the cell its coordinates name.

Advection Schemes

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.dycore_horiz_adv_type	Horizontal advection type for dycore vars	see below	Upwind_3rd
erf.dycore_vert_adv_type	Vertical advection type for dycore vars	see below	Upwind_3rd
erf.dryscal_horiz_adv_type	Horizontal advection type for dry scalars	see below	Upwind_3rd
erf.dryscal_vert_adv_type	Vertical advection type for dry scalars	see below	Upwind_3rd
erf.moistscal_horiz_adv_type	Horizontal advection type for moist scalars	see below	WENO3
erf.moistscal_vert_adv_type	Vertical advection type for moist scalars	see below	WENO3
erf.use_efficient_advection	Use efficient advection scheme for scalars	Boolean	false
erf.dycore_horiz_upw_frac	fraction of the upwind stencil blended into the horizontal advection of the dycore variables; 1 is fully upwind-biased and 0 is fully centered	Real in [0,1]	1.0
erf.dycore_vert_upw_frac	as above, for the vertical advection of the dycore variables	Real in [0,1]	1.0
erf.dryscal_horiz_upw_frac	as above, for the horizontal advection of dry scalars	Real in [0,1]	1.0
erf.dryscal_vert_upw_frac	as above, for the vertical advection of dry scalars	Real in [0,1]	1.0
erf.moistscal_horiz_upw_frac	as above, for the horizontal advection of moist scalars	Real in [0,1]	1.0
erf.moistscal_vert_upw_frac	as above, for the vertical advection of moist scalars	Real in [0,1]	1.0
erf.zero_xflux_faces	list of (i,j,k) x-faces across which the advective flux is forced to zero; with erf.anelastic = 1 these faces select the thin-body projection	List of 3-integer triples	none
erf.zero_yflux_faces	list of (i,j,k) y-faces across which the advective flux is forced to zero; with erf.anelastic = 1 these faces select the thin-body projection	List of 3-integer triples	none
erf.zero_zflux_faces	list of (i,j,k) z-faces across which the advective flux is forced to zero; with erf.anelastic = 1 these faces select the thin-body projection	List of 3-integer triples	none

The allowed advection types for the dycore variables are:

• From WRF: “Centered_2nd”, “Upwind_3rd”, “Centered_4th”, “Upwind_5th”, and “Centered_6th”

• Blended schemes: “Blended_3rd4th” and “Blended_5th6th”

• WENO-JS schemes: “WENO3” “WENO5”, and “WENO7”

• WENO-Z schemes: “WENOZ3” “WENOZ5”, and “WENOZ7”

• Third-order WENO-MZQ scheme: “WENOMZQ3”

In addition to the above advection schemes for dycore variables, dry and moist scalars also have the option of using “Upwind_3rd_SL” (slope-limited).

To use the blended schemes, erf.[vartype]_[horiz|vert]_upw_frac for the corresponding erf.[vartype]_[horiz|vert]_adv_type should be set to a scalar between 0 and 1, where 1 is fully upwind and 0 is fully central.

Note: if using WENO schemes, the horizontal and vertical advection types must be set to the same string.

The efficient advection schemes for dry and moist scalars exploit the substages of the time advancing RK3 scheme by using lower order schemes in the first two substages and the solver’s choice of scheme in the final stage. Based on CPU-only runtimes on Perlmutter for the scalar advection routine, the approximate computational savings for the scalar advection schemes are as follows when using efficient advection option: roughly 30% for Centered_4th and Centered_6th, 35% for Upwind_5th, roughly 45% for WENO5 and WENOZ5, and roughly 60% for Upwind_3rd, WENO3, WENOZ3, and WENOMZQ3.

Diffusive Physics

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.alpha_T	Diffusion coeff. for temperature	Real	0.0
erf.alpha_C	Diffusion coeff. for scalar	Real	0.0
erf.rho0_trans	Reference density to compute const. rho*Alpha	Real	1.0
erf.les_type	Using an LES model, and if so, which type?	“None”, “Smagorinsky”, “Smagorinsky2D”, “Deardorff”	“None”
erf.rans_type	Using a RANS model, and if so, which type?	“None” or “kEqn”	“None”
erf.molec_diff_type	Using molecular viscosity and diffusivity?	“None”, “Constant”, or “ConstantAlpha”	“None”
erf.dynamic_viscosity	Viscous coeff. if DNS	Real	0.0
erf.Cs	Constant Smagorinsky coeff.	Real	0.0
erf.smag2d_slope_limiter	Smagorinsky2D on a terrain-fitted mesh: divide K_h by the slope factor alpha or alpha^2 as WRF’s smag2d_km does (see below). Per level; a single value applies at the Smagorinsky2D levels. Aborts if no level uses Smagorinsky2D, if a per-level list turns it on at another level, or without a terrain-fitted mesh	Boolean	false
erf.smag2d_kh_cap	Smagorinsky2D: cap K_h <= smag2d_kh_cap * Delta_h with Delta_h = sqrt(dx dy)/m (WRF: 10 m/s); 0 means no cap. Per level, like erf.smag2d_slope_limiter; aborts if negative or with EB	Real >= 0 [m/s]	0
erf.use_moist_Ri_correction	Apply moist Richardson number limiter to the Smagorinsky model	Boolean	false
erf.Ck	Constant Deardorff k coeff.	Real	0.1
erf.Ce	Constant Deardorff epsilon coeff.	Real	0.93
erf.Ce_wall	Constant Deardorff epsilon coeff. at the wall; if > 0, then set Ce to this at k=0	Real	0.0
erf.sigma_k	Constant Deardorff coeff. in downgradient diffusion term	Real	0.5
erf.theta_ref	Reference potential temperature used to characterize stable stratficiation; constant if > 0, otherwise the instantaneous local value is used	Real	0.0
erf.Pr_t	Turbulent Prandtl Number	Real	1/3
erf.Sc_t	Turbulent Schmidt Number	Real	1.0
erf.num_diff_coeff	coefficient of the sixth-order numerical diffusion; 0 turns it off	Real in [0,1]	0.0
erf.implicit_before_substep	if true, the vertical implicit diffusive solve is done before the acoustic substepping rather than after. Forced to true if any level has substepping_type = None	Boolean	true
erf.thermal_stratification	which potential temperature the subgrid model uses to quantify thermal stratification (per-level). Applies to both the LES closures and the PBL schemes. When it is not set, the LES closures use theta and the PBL schemes use thetav, which is what each has always used.	theta, thetav, thetal	theta (LES), thetav (PBL)
erf.mix_isotropic	use an isotropic mixing length (per-level); automatically turned off for 2-D Smagorinsky	Boolean	true
erf.use_Ri_correction	apply the Richardson-number correction to the Smagorinsky coefficient (per-level)	Boolean	true
erf.Ri_crit	critical Richardson number used by that correction (per-level)	Real	0.25
erf.Cmu0	k-equation RANS closure constant (per-level); with erf.Rt_min it must satisfy erf.Rt_min > -erf.Cmu0/0.108	Real > 0	0.5562
erf.Cb	k-equation buoyancy constant (per-level)	Real	0.35
erf.Rt_crit	critical turbulent Richardson number for the k-equation closure (per-level)	Real <= 0	-1.0
erf.Rt_min	minimum turbulent Richardson number for the k-equation closure (per-level); must lie above the pole of \(c_\mu\) at -3.59869 and above -erf.Cmu0/0.108; values below about -3.5 give a very large \(c_\mu\)	Real in (max(-3.5986889, -erf.Cmu0/0.108), erf.Rt_crit)	-3.0
erf.max_geom_lscale	upper bound [m] on the geometric mixing length (per-level)	Real > 0	30.0
erf.dirichlet_k	k-equation RANS under a surface layer: set the turbulent kinetic energy of the first cell above the wall from u* and t* (Axell & Liungman 2001, Eq. 16) and hold it through the step (per-level)	Boolean	false
erf.tke_floor	runtime floor on the turbulent kinetic energy [m^2/s^2] in the k-equation update and the RANS closure; distinct from erf.tke_min, the initial value (per-level)	Real >= 0	0 (machine epsilon on rho k)
erf.implicit_tke_dissipation	Deardorff or k-equation RANS: treat the TKE dissipation implicitly, eps = (C k_old^1/2 / L) k_new folded into the update, which removes the dissipation time-step limit near the wall (per-level)	Boolean	false
erf.rans_consistent_diffusivities	k-equation RANS: horizontal heat, scalar and moisture diffusivities follow the scalar stability function (Axell & Liungman Eq. 32) like the vertical heat diffusivity, instead of Pr_t and Sc_t times the eddy viscosity (per-level)	Boolean	false
erf.rans_lscale_from_pblh	k-equation RANS: cap the geometric length at kappa times 0.1 times the diagnosed PBL height (needs erf.most.pblh_calc = MYNN25), clamped to [erf.rans_lscale_min, erf.max_geom_lscale] (per-level)	Boolean	false
erf.rans_lscale_min	lower bound [m] of the PBL-height cap above (per-level)	Real > 0	1.0
erf.rans_realizability	k-equation RANS: cap the eddy viscosity at C_r k / S, S the strain-rate magnitude, and every eddy diffusivity by the same factor (SST limiter form); needs erf.rans_type = kEqn and erf.pbl_type = None; C_r = Cmu0^2 = 0.309 (default Cmu0) is the neutral equilibrium value, which leaves a neutral constant- stress layer unchanged and limits the viscosity where production exceeds dissipation, as behind a steep crest; one value for the hierarchy (a single entry, or a list whose entries are all equal) is reset to 0 on levels without the k-eqn closure; a list with different entries that switches it on at such a level stops the run (per-level)	0, or Real in [0.01, 10]	0 (off)
erf.wall_dist_type	wall distance for RANS on a terrain-fitted mesh: Tucker (2003) Poisson distance, or the height above the local surface projected on its normal (no linear solve)	“poisson”, “terrain_height”	“poisson”

Note: in the equations for the evolution of momentum, potential temperature and advected scalars, the diffusion coefficients are written as \(\mu\), \(\rho \alpha_T\) and \(\rho \alpha_C\), respectively.

If we set erf.molec_diff_type to Constant, then

• erf.dynamic_viscosity is used as the value of \(\mu\) in the momentum equation, and

• erf.alpha_T is multiplied by erf.rho0_trans to form the coefficient for potential temperature, and

• erf.alpha_C is multiplied by erf.rho0_trans to form the coefficient for an advected scalar.

If we set erf.molec_diff_type to ConstantAlpha, then

• the dynamic viscosity in the momentum equation is assumed to have the form \(\mu = \rho \alpha_M\) where \(\alpha_M\) is a momentum diffusivity constant with units of kinematic viscosity, calculated as erf.dynamic_viscosity divided by erf.rho0_trans; this diffusivity is multiplied by the instantaneous local density \(\rho\) to form the coefficient in the momentum equation; and

• erf.alpha_T is multiplied by the instantaneous local density \(\rho\) to form the coefficient for potential temperature, and

• erf.alpha_C is multiplied by the instantaneous local density \(\rho\) to form the coefficient for an advected scalar.

With either type, the coefficient formed from erf.alpha_C also applies to every moisture species of the microphysics model, number concentrations included, but not to non-moist species a model appends after them.

Parameters for LES can either be set with one value that applies across all levels, or set with a number of values equal to the number of levels, allowing unique values of the parameter to be set for each level.

On a terrain-fitted mesh the momentum flux through a terrain-following (\(\zeta\)) face combines the vertical stress, which takes the vertical eddy viscosity (Kmv), with the horizontal stresses projected onto the face, which take the horizontal eddy viscosity (Kmh); see Momentum stresses on terrain-fitted meshes. Answers therefore depend on both whenever they differ: with erf.les_type = Smagorinsky2D, with erf.mix_isotropic = false, and with a PBL scheme. No PBL scheme sets Kmh, so with a PBL scheme and no LES closure the projected horizontal stresses carry only the molecular viscosity.

Smagorinsky2D limits on terrain-fitted meshes

With erf.les_type = Smagorinsky2D the horizontal eddy viscosity is \(K_h = C_s^2 \Delta_h^2 |D_h|\), with \(\Delta_h = \sqrt{\Delta x \Delta y}/m\) and the horizontal deformation \(|D_h| = \sqrt{(u_x - v_y)^2 + (u_y + v_x)^2}\). On a terrain-fitted mesh the horizontal stresses along the coordinate surfaces carry a metric term of size \(K_h h^2 \partial^2/\partial z^2\), where \(h\) is the coordinate slope. It is explicit (unless erf.implicit_terrain_metric = true, which solves its compact form implicitly while keeping \(K_h\); see Momentum stresses on terrain-fitted meshes), and where the terrain drops by several cell thicknesses across one cell it is much stiffer than the horizontal diffusion itself. Two opt-in limits taken from WRF’s smag2d_km (dyn_em/module_diffusion_em.F, km_opt = 4) bound it instead:

• erf.smag2d_kh_cap = \(c\) caps \(K_h \le c \Delta_h\) (WRF uses \(c\) = 10 m/s, always on there);

• erf.smag2d_slope_limiter = true divides \(K_h\) by the slope factor of the cell,

  \[\begin{split}\alpha = \max\left(\frac{\sqrt{\delta_x^2 + \delta_y^2}}{\Delta z}, 1\right), \qquad K_h \leftarrow \begin{cases} K_h/\alpha^2 & |D_h| > \max(10/\Delta_h, 10^{-3}) \\ K_h/\alpha & \text{otherwise,} \end{cases}\end{split}\]

  where \(\delta_x\) and \(\delta_y\) are the terrain drops across the cell (the mean of the absolute height differences on its four cell edges in that direction) and \(\Delta z\) is the cell thickness, so that \(\alpha = h \Delta x/\Delta z\). This is WRF’s diff_opt = 2 limiter (“JB August 2014”), applied after the cap, as there.

The scalar diffusivities are formed from the limited \(K_h\) (\(K_\theta = K_h/Pr_t\)), as WRF recomputes xkhh. ERF’s \(|D_h|\) has the same definition as WRF’s sqrt(def2). ERF differs from WRF in these details:

• the vertical viscosity \(K_v\) (from the PBL scheme, or without one \(C_s^2 \Delta z^2 |D_h|\) times the Richardson-number factor) is not limited. WRF sets xkmv = xkmh after limiting and uses it for the horizontal diffusion of w; ERF has no such coefficient (its stresses on w use \(K_v\), while the projected horizontal stresses of u and v use the limited \(K_h\)), so on steep slopes the momentum diffusion keeps its \(K_v\) part;

• the terrain heights are nodal, so the drops are taken on the cell edges rather than from \(z_x\) at the cell faces, and \(\alpha\) carries no map factor (WRF multiplies the drop by \(1/m_x\)), so that it is exactly \(h \Delta x/\Delta z\) with physical spacings; the two agree where the map factor is 1;

• \(\Delta_h\) uses ERF’s map factors at the cell’s low x- and y-faces (as ERF’s Smagorinsky closure always has), WRF’s mlen_h the mass-point factors;

• WRF sets the slopes to zero on specified, open and nested lateral boundaries and skips their outermost columns; ERF limits every cell;

• WRF uses \(K_h/Pr\) for every scalar; ERF forms the moisture and advected-scalar diffusivities with erf.Sc_t (default 1) instead, as it always has.

The strain part of the momentum stresses on terrain-fitted meshes (Momentum stresses on terrain-fitted meshes) dissipates energy for any \(K_h\) and \(K_v\) on a uniform slope with uniform vertical spacing. Where the slope varies, energy can grow transiently when \(K_h \gg K_v\); in the cases analysed there (without the expansion-rate term) no mode grew. So the limits are not needed for that operator: they bound the stiffness of the explicit metric term and match WRF’s mixing on slopes.

Both limits change the physics: they reduce the horizontal mixing on slopes (by \(\alpha^2\), up to two orders of magnitude on a 3 km grid with 50 m cells over steep terrain) and wherever the cap binds. They are off by default, and existing inputs give identical answers. They are implemented for Smagorinsky2D only, as in WRF; the anisotropic Smagorinsky and Deardorff closures (erf.mix_isotropic = false) are not limited. A single value of either input applies at the levels that use Smagorinsky2D; the code aborts if no level does, or if a per-level list turns a limit on at a level that does not. See also erf.diffusive_dt_check in the time-step section, which reports the explicit diffusive limit these terms impose.

PBL Scheme

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.pbl_type	Name of PBL Scheme to be used	“None”, “MYNN25”, “MYNNEDMF”, “MYJ”, “YSU”, “YSUNew”, “MRF”, “NATIVE_SHOC”, “EAMXX_SHOC”; legacy “SHOC” is deprecated and maps to “EAMXX_SHOC”	“None”
erf.tke_min	Minimum initial TKE used when a prognostic-TKE closure is active	Real	1.e-6
erf.pbl_mynn_A1	MYNN Constant A1	Real	1.18
erf.pbl_mynn_A2	MYNN Constant A2	Real	0.665
erf.pbl_mynn_B1	MYNN Constant B1	Real	24.0
erf.pbl_mynn_B2	MYNN Constant B2	Real	15.0
erf.pbl_mynn_C1	MYNN Constant C1	Real	0.137
erf.pbl_mynn_C2	MYNN Constant C2	Real	0.75
erf.pbl_mynn_C3	MYNN Constant C3	Real	0.352
erf.pbl_mynn_C4	MYNN Constant C4	Real	0.0
erf.pbl_mynn_C5	MYNN Constant C5	Real	0.2
erf.pbl_mynn_SQfactor	MYNN ratio of stability functions SQ / SM	Real	3.0
erf.pbl_mynn_config	Which MYNN variant to use. NN09 sets Lt_alpha = 0.23 and forms the master length scale as a 1/l sum; Chen2021 sets Lt_alpha = 0.10 and uses a 1/l^2 sum.	NN09, Chen2021	NN09
erf.pbl_mynn_Lt_alpha	Coefficient on the ABL-depth length scale, l_T = Lt_alpha <zq>/<q> (NN09 Eqn. 54). Defaults from pbl_mynn_config and may be overridden on its own. Mellor-Yamada 1982 uses 0.1.	Real	from pbl_mynn_config
erf.pbl_mynn_Lt_taper_exp	Exponent n in the optional boundary-layer-depth taper of the ABL length scale, l_T -> l_T (1 - z/h)^n. Zero disables the taper. Requires erf.most.pblh_calc to be set, since it needs a diagnosed PBL height h.	Real	0.0
erf.advect_QKE	Include advection terms in QKE eqn	Boolean	true
erf.diffuse_QKE_3D	Include horizontal turb. diffusion terms in QKE eqn.	Boolean	false
erf.pbl_ysu_force_over_water	Treat whole domain as over water for YSU PBL scheme regardless of LSM/other inputs	Boolean	false
erf.pbl_ysu_land_Ribcr	Over land critical Richardson number for YSU PBL Scheme	Real	0.25
erf.pbl_ysu_unst_Ribcr	Unstable critical Richardson number for YSU PBL Scheme	Real	0.0
erf.pbl_ysu_coriolis_freq	Coriolis frq. used for YSU PBL Scheme (1e-4 in WRF)	Real	1.0e-4
erf.pbl_ysu_use_consistent_coriolis	Ignore above param and use the value from ERF coriolis	Boolean	false
erf.enable_ysu_countergradient	YSUNew only: apply the nonlocal countergradient corrections to heat, moisture and momentum (HGAMT, HGAMQ, HGAMU, HGAMV); false gives strict HND06 mixing	Boolean	true
erf.enable_ysu_entrainment	YSUNew only: add the entrainment diffusivity at the first cell above the PBL top (HND06 Eq. 6)	Boolean	true
erf.ysu_moistvars	YSUNew only: give moisture its own diffusivity, from the moisture Prandtl number, and add the entrainment term to it; false uses the heat diffusivity for moisture	Boolean	false
erf.enable_ysu_rad_tend_limiter	YSUNew only: replace a non-finite radiative tendency at cloud top by zero and bound it before the top-down mixing velocity is formed from it	Boolean	false
erf.ysu_rad_tend_limiter_magnitude	Bound on that tendency [K/s]; must be positive	Real	1.0
erf.pbl_mrf_coriolis_freq	Coriolis frq. used for MRF PBL Scheme	Real	1.0e-4
erf.pbl_mrf_Ribcr	Over land critical Richardson number for MRF PBL Scheme	Real	0.5
erf.pbl_ib_aware	MRF and YSUNew only: treat the first fluid cell above an immersed solid column (buildings or terrain by immersed forcing) as that column’s surface: heights, the bulk Richardson depth and the K profile measured from it, zero diffusivity inside the solid, a neutral log law at the top for the surface scales; identical without immersed cells; not with terrain-fitted coordinates (the stored PBL height stays the absolute height; the PBL height smoothing runs on it and keeps every column at or above its own floor)	Boolean	false
erf.pbl_ib_z0	roughness length [m] of that log law	Real > 0	0.01
erf.pbl_mrf_const_b	Coefficient for the countergradient term	Real	7.8
erf.pbl_mrf_sf	ratio of surface layer height to boundary layer height	Real	0.1
erf.enable_mrf_countergradient	Enable countergradient correction terms in MRF PBL scheme	Boolean	false
erf.pbl_mrf_highres_bounds	Enable alternative high-resolution grid-dependent diffusivity bounds	Boolean	false
erf.enable_mrf_unbounded_vpert	Enable physically superior unbounded VPERT in MRF PBL scheme	Boolean	false
erf.enable_mrf_cloud_adjustment	MRF only: adjust the stability functions in cells whose cloud water plus ice exceeds 1e-4 kg/kg (less stable damping, a smaller unstable correction)	Boolean	false
erf.pbl_mrf_use_zero_ri_extent	MRF only: extend the K profile to the PBL height diagnosed with Ribcr = 0, a taller mixing region; false uses the Ribcr = 0.5 corrected height, as WRF does	Boolean	false
erf.advect_tke	advect the turbulent kinetic energy (per-level); read only when the PBL scheme carries TKE	Boolean	true
erf.diffuse_tke_3D	apply three-dimensional numerical diffusion to the turbulent kinetic energy (per-level)	Boolean	true
erf.init_tke_from_ustar	initialize the turbulent kinetic energy from the friction velocity (per-level); read only when a TKE-carrying closure is active	Boolean	false

Note that both PBL schemes must be used in conjunction with a MOST boundary condition at the surface (Zlo) boundary. The YSU scheme is work in progress currently.

If the PBL scheme is activated, it determines the turbulent diffusivity in the vertical direction. If an LES model is also specified, it determines only the horizontal turbulent diffusivity.

ERF uses prognostic TKE for Deardorff LES, k-equation RANS, MYJ, MYNN2.5, MYNN-EDMF, and SHOC. When one of these closures is active, ERF initializes TKE at startup to erf.tke_min (default 1.e-6 m^2/s^2) before any optional problem-specific TKE perturbations or surface-layer-based TKE initialization are applied.

Parameters for PBL schemes can either be set with one value that applies across all levels, or set with a number of values equal to the number of levels, allowing unique values of the parameter to be set for each level.

Forest Canopy

Forest drag can be configured either with the existing discrete-patch text file or with gridded NetCDF fields. The two modes are mutually exclusive. A complete file configuration enables forest drag automatically; if erf.do_forest_drag is specified explicitly, its value must agree with the presence or absence of that configuration. See Forest Model for the LAD profiles and the scoped fixed-leaf-temperature exchange equations.

The gridded mode requires NetCDF support and both forest_lai_file and forest_height_file. Supply exactly one of forest_cd_file and the constant forest_cd. The LAI, height, and optional drag-coefficient files must share the same horizontal grid. ERF reads variables named LAI, height, and cd; each may be two-dimensional or have a leading time dimension, in which case the first time record is used. Coordinates must be projected Cartesian x/y; raw lon/lat coordinates are rejected because ERF does not silently reinterpret degrees as meters. Each horizontal direction must contain at least two finite, strictly increasing, uniformly spaced coordinates. All forest fields must match the LAI dimensions, spacing, and horizontal origin; ERF rejects misregistered fields before interpolation. A coordinate pair is required; ERF does not assume a unit-spacing grid when metadata is absent.

7 Forest canopy parameters

Parameter	Definition	Acceptable values	Default
erf.do_forest_drag	Optional consistency switch for forest drag	Boolean	false
erf.forest_file	Discrete-patch canopy text file	String	None
erf.forest_lai_file	Gridded NetCDF file containing LAI	String	None
erf.forest_height_file	Gridded NetCDF file containing canopy height [m]	String	None
erf.forest_cd_file	Gridded NetCDF file containing cd	String	None
erf.forest_cd	Spatially constant drag coefficient; mutually exclusive with forest_cd_file	Real	None
erf.forest_tree_type	Vertical LAD profile: uniform or Lalic–Mihailovic	1 or 2	1
erf.forest_laimax	Fraction of canopy height at maximum LAD for tree type 2; must satisfy 0 <= laimax < 1	Real	0.8
erf.forest_substep	Apply the forest canopy source terms during the acoustic substeps only	Boolean	false
erf.forest_biophysics	Master switch for the scoped canopy exchange path	Boolean	false
erf.forest_biophysics_heat	Apply fixed-leaf-temperature sensible and latent exchange	Boolean	false
erf.forest_leaf_theta_fixed	Prescribed leaf potential temperature [K]; required and positive when heat exchange is enabled	Real [K]	None
erf.forest_canopy_tke	Add the canopy wake production, short-circuit dissipation and length scale cap to the k-eqn RANS model; needs a forest and erf.rans_type = kEqn on every level, and at least one of the three coefficients below nonzero; with erf.forest_canopy_length_alpha > 0 it needs erf.implicit_tke_dissipation = true on every level (see Forest Model)	Boolean	false
erf.forest_canopy_beta_p	Fraction of the drag work that becomes TKE, \(\beta_p\); must be in [0, 1]; ignored, with a warning, unless erf.forest_canopy_tke = true	Real	1.0
erf.forest_canopy_beta_d	Short-circuit dissipation coefficient \(\beta_d\); must be finite and not negative; ignored, with a warning, unless erf.forest_canopy_tke = true	Real	4.0
erf.forest_canopy_length_alpha	Dimensionless \(\alpha\) of the length scale cap \(L \le \alpha / f\) in the canopy, with \(f = C_d \, \mathrm{LAD}\) [1/m]; must be in [0, 1], 0 disables the cap; ignored, with a warning, unless erf.forest_canopy_tke = true	Real	0.04

erf.forest_biophysics_heat = true requires erf.forest_biophysics = true and a positive erf.forest_leaf_theta_fixed.

For example, a gridded canopy with fixed leaf potential temperature can be configured as follows:

erf.do_forest_drag          = true
erf.forest_lai_file         = canopy_lai.nc
erf.forest_height_file      = canopy_height.nc
erf.forest_cd               = 0.15
erf.forest_tree_type        = 2
erf.forest_laimax           = 0.6
erf.forest_biophysics       = true
erf.forest_biophysics_heat  = true
erf.forest_leaf_theta_fixed = 301.0

Forcing Terms

ABL Driver and Geostrophic Forcing

Parameter	Definition	Acceptable Values	Default
erf.abl_driver_type	type of large-scale forcing used to drive the boundary layer	None, PressureGradient, GeostrophicWind	None
erf.abl_pressure_grad	imposed horizontal pressure gradient vector, used when abl_driver_type = PressureGradient	3 Reals	0.0 0.0 0.0
erf.abl_geo_wind	geostrophic wind vector from which the geostrophic forcing is computed; read only when use_coriolis is true and abl_driver_type = GeostrophicWind, and ignored if abl_geo_wind_table is given	3 Reals	0.0 0.0 0.0
erf.abl_geo_forcing	geostrophic forcing vector applied directly, rather than being computed from a geostrophic wind	3 Reals	0.0 0.0 0.0
erf.abl_geo_wind_table	file containing a height-varying geostrophic wind profile; may not be combined with add_custom_geostrophic_profile. One row per height, z Ug Vg (m, m/s, m/s), heights increasing and covering the domain; blank lines and lines starting with # are skipped, and any other row that does not start with three numbers stops the run. z is the physical height, in the same coordinate as geometry.prob_lo[2] and prob_hi[2]	String	None

Wind Farm Forcing

The wind farm parameterization is selected with erf.windfarm_type.

Parameter	Definition	Acceptable Values	Default
erf.windfarm_type	which wind farm parametrization to use	None, Fitch, EWP, SimpleAD, GeneralAD	None
erf.windfarm_loc_type	coordinate system in which the turbine locations are given	None, lat_lon, x_y	None
erf.windfarm_loc_table	file listing the turbine locations	String	None
erf.windfarm_spec_table	file containing the turbine specifications	String	None
erf.windfarm_spec_table_extra	file containing additional turbine specifications	String	None
erf.windfarm_blade_table	file containing the blade geometry, used by the generalized actuator disk	String	None
erf.windfarm_airfoil_tables	directory containing the airfoil tables, used by the generalized actuator disk	String	None
erf.sampling_distance_by_D	distance upstream of the turbine, as a multiple of the rotor diameter, at which the incoming free stream velocity is sampled; required with windfarm_type = SimpleAD	Real > 0	-1.0 (must be set)
erf.turb_disk_angle_from_x	angle [degrees] of the face of the turbine disk from the x axis; a turbine facing flow in the x direction has a value of 90. Required with windfarm_type = SimpleAD or GeneralAD	Real > 0	-1.0 (must be set)
erf.windfarm_x_shift	distance by which the bounding box of the wind farm is shifted from the x axis; required with windfarm_loc_type = lat_lon	Real > 0	-1.0 (must be set)
erf.windfarm_y_shift	distance by which the bounding box of the wind farm is shifted from the y axis; required with windfarm_loc_type = lat_lon	Real > 0	-1.0 (must be set)

• Wind farm parameterization requires USE_WINDFARM=TRUE (gmake) or -DERF_ENABLE_WINDFARM (cmake) at build time. See Wind farm models for theory and examples.

Constant Mass Flux

Parameter	Definition	Acceptable Values	Default
erf.const_massflux_u	bulk velocity (m/s) whose mass flux through the layer is held in x, by a uniform source that acts like a background pressure gradient; 0 turns it off; requires periodic boundaries in x	Real	0.0
erf.const_massflux_v	the same in y; requires periodic boundaries in y	Real	0.0
erf.const_massflux_layer_lo	height of the bottom of the layer over which the constant mass flux is enforced	Real	bottom of domain
erf.const_massflux_layer_hi	height of the top of the layer over which the constant mass flux is enforced	Real	top of domain
erf.const_massflux_tau	time scale (s) over which the mass flux relaxes to its target	Real > 0; the run stops otherwise	1.0

Gravity and Coriolis

Parameter	Definition	Acceptable Values	Default
erf.use_gravity	include the gravitational source term; primarily an option for unit testing. Forced to true if init_type is WRFInput or Metgrid	Boolean	false
erf.use_coriolis	include the Coriolis forcing	Boolean	false
erf.variable_coriolis	allow the Coriolis frequency to vary spatially rather than using a single latitude	Boolean	false
erf.rotational_time_period	rotational period of the planet [s], used to form the Coriolis factor; read only if use_coriolis is true	Real > 0	86400.0
erf.latitude	latitude [degrees] at which the constant-latitude Coriolis frequency is evaluated; read only if use_coriolis is true	Real	90.0
erf.coriolis_3d	include the vertical (cosine of latitude) Coriolis terms in addition to the traditional terms	Boolean	true

Rayleigh Damping

Parameter	Definition	Acceptable Values	Default
erf.rayleigh_damping_type	how the Rayleigh damping terms are integrated in time: SlowExplicit applies them explicitly in the slow (Runge-Kutta) update, while FastExplicit and FastImplicit apply them explicitly or implicitly within the acoustic substeps. Case sensitive; an unrecognized value aborts	SlowExplicit, FastExplicit, FastImplicit	SlowExplicit
erf.rayleigh_damp_U	Include explicit Rayleigh damping in the x-momentum equation	Boolean	false
erf.rayleigh_damp_V	Include explicit Rayleigh damping in the y-momentum equation	Boolean	false
erf.rayleigh_damp_W	Include Rayleigh damping in the z-momentum equation	Boolean	false
erf.rayleigh_damp_T	Include explicit Rayleigh damping in the potential temperature equation	Boolean	false
erf.rayleigh_dampcoef	inverse damping time scale [1/s] multiplying the vertical damping weight	Real > 0 [1/s]	0.2
erf.rayleigh_zdamp	Depth of upper damping layer below model top where sine-squared ramp is nonzero	Real > 0 [m]	500.0

Sponge Zones

Sponge zones relax the solution toward a target state near a domain boundary, to keep waves from reflecting back into the interior. See Physical Forcings for the formulation and for complete example inputs. Damping may be applied at any of the six domain boundaries; each side that is switched on also requires the coordinate at which its sponge ends or starts.

Parameter	Definition	Acceptable Values	Default
erf.sponge_type	which sponge formulation to use. Standard relaxes toward the constant target values below; Input_Sponge reads a u, v profile from a file	None, Standard, Input_Sponge	Standard
erf.sponge_strength	sponge amplitude A. Setting it to zero disables the sponge, regardless of erf.sponge_type	Real	0.0
erf.input_sponge_file	text file of z, u, v columns giving the sponge target profile; required when erf.sponge_type = Input_Sponge	String	None
erf.use_xlo_sponge_damping	apply sponge damping at the low-x boundary	Boolean	false
erf.use_xhi_sponge_damping	apply sponge damping at the high-x boundary	Boolean	false
erf.use_ylo_sponge_damping	apply sponge damping at the low-y boundary	Boolean	false
erf.use_yhi_sponge_damping	apply sponge damping at the high-y boundary	Boolean	false
erf.use_zlo_sponge_damping	apply sponge damping at the low-z boundary	Boolean	false
erf.use_zhi_sponge_damping	apply sponge damping at the high-z boundary	Boolean	false
erf.xlo_sponge_end	x-coordinate at which the low-x sponge ends; required when erf.use_xlo_sponge_damping is true	Real	must be set
erf.xhi_sponge_start	x-coordinate at which the high-x sponge starts; required when erf.use_xhi_sponge_damping is true	Real	must be set
erf.ylo_sponge_end	y-coordinate at which the low-y sponge ends; required when erf.use_ylo_sponge_damping is true	Real	must be set
erf.yhi_sponge_start	y-coordinate at which the high-y sponge starts; required when erf.use_yhi_sponge_damping is true	Real	must be set
erf.zlo_sponge_end	z-coordinate at which the low-z sponge ends; required when erf.use_zlo_sponge_damping is true	Real	must be set
erf.zhi_sponge_start	z-coordinate at which the high-z sponge starts; required when erf.use_zhi_sponge_damping is true	Real	must be set
erf.sponge_density	target density in the sponge zone	Real	-1.0 (not used)
erf.sponge_rhotheta	target (rho*theta) in the sponge zone	Real	-1.0 (not used)
erf.sponge_rhomoist	target (rho*qv) in the sponge zone; any other moisture species are damped toward zero	Real	-1.0 (not used)
erf.sponge_x_velocity	target x-velocity in the sponge zone	Real	0.0
erf.sponge_y_velocity	target y-velocity in the sponge zone	Real	0.0
erf.sponge_z_velocity	target z-velocity in the sponge zone	Real	0.0

Nudging from Input Soundings

Parameter	Definition	Acceptable Values	Default
erf.nudging_from_input_sounding	nudge the solution towards the time-varying profiles given in the input sounding files	Boolean	false
erf.nudging_u	nudge u,v towards the sounding (takes effect only when nudging_from_input_sounding is true; does not affect LSF-based wind nudging, see large_scale_forcing)	Boolean	true
erf.nudging_t	nudge potential temperature towards the sounding (takes effect only when nudging_from_input_sounding is true)	Boolean	true
erf.nudging_q	nudge water vapor towards the sounding (takes effect only when nudging_from_input_sounding is true)	Boolean	true
erf.nudging_u_z1	Bottom of the height range over which u,v are nudged	Real [m]	-1.0e36
erf.nudging_u_z2	height above which u,v are not nudged	Real [m]	1.0e36
erf.nudging_t_z1	Bottom of the height range over which potential temperature is nudged	Real [m]	0.0
erf.nudging_t_z2	height above which temperature is not nudged	Real [m]	10000.0
erf.nudging_q_z1	Bottom of the height range over which water vapor is nudged	Real [m]	0.0
erf.nudging_q_z2	height above which moisture is not nudged	Real [m]	10000.0
erf.input_sounding_time	Time(s) of the input sounding file(s)	Real(s)	0.0
erf.tau_nudging	Time scale for nudging	Real	5.0

erf.input_sounding_file is documented under Initialization; more than one file may be named there, paired with erf.input_sounding_time.

If erf.nudging_from_input_sounding is true, it is expected that at least one input sounding file is available. If there is only one, and no specification of time is made, it is assumed that the one file corresponds to time = 0.0. If the final time supplied in input_*_sounding_*_time is less than the final time in the calculation, the final sounding supplied in input_*_sounding_*_file will be used for all times later than the final value in in input_*_sounding_*_time.

Every level samples the input sounding at its own cell centres, for the initial state and base state and for nudging, just as a single-level run at that resolution does; the large-scale forcing profiles are likewise interpolated to each level’s own cell centres. A fine cell below the first level-0 cell centre therefore starts from the sounding’s air values there, not from a blend with the surface line of the file (which, with erf.most.pot_surf_temp, holds the surface temperature).

Nudging towards Observations

Near stations such as met masts and lidars, u, v, w and theta can be nudged towards their measured profiles; see Nudging towards observations at stations for the formulation. A station is named in erf.obs_nudging.stations and given by the keys erf.obs_nudging.<name>.*:

erf.nudging_from_observations     = true
erf.obs_nudging.stations          = mast lidar
erf.obs_nudging.tau               = 600.0
erf.obs_nudging.horizontal_radius = 500.0
erf.obs_nudging.vertical_radius   = 25.0
erf.obs_nudging.mast.file         = mast.txt
erf.obs_nudging.mast.x            = 700.0
erf.obs_nudging.mast.y            = 400.0
erf.obs_nudging.lidar.file        = lidar.txt
erf.obs_nudging.lidar.lat         = 39.91
erf.obs_nudging.lidar.long        = -105.23

Parameter	Definition	Acceptable Values	Default
erf.nudging_from_observations	Nudge the solution towards observations at the stations below	Boolean	false
erf.obs_nudging.stations	Names of the stations	List of strings	required
erf.obs_nudging.tau	Relaxation time scale	Real > 0 [s]	required
erf.obs_nudging.horizontal_radius	Horizontal radius R_h of a station’s weight	Real > 0 [m]	500
erf.obs_nudging.vertical_radius	Vertical radius R_z of the taper outside the measured height range	Real > 0 [m]	25
erf.obs_nudging.cutoff	Stations further than this many radii away are not used	Real > 0	6
erf.obs_nudging.sigma_factor	Half-width alpha of the band mean +- alpha sigma inside which the value is left alone; 0 nudges to the mean	Real >= 0	1
erf.obs_nudging.nudge_wind	Nudge u and v where a station measures them	Boolean	true
erf.obs_nudging.nudge_w	Nudge w where a station measures it	Boolean	true
erf.obs_nudging.nudge_theta	Nudge theta where a station measures it	Boolean	true
erf.obs_nudging.time_type	Clock of the time column: elapsed (seconds of run time) or epoch (seconds since 1970, needs start_datetime or a WRF/metgrid start)	elapsed, epoch	elapsed
erf.obs_nudging.missing_value	Entry of a station file that marks a missing measurement (as does nan)	Real	-9999
erf.obs_nudging.<name>.file	The station file	String	required
erf.obs_nudging.<name>.x, .y	Position in domain coordinates	Real [m]	x/y or lat/long
erf.obs_nudging.<name>.lat, .long	Latitude and longitude (needs latitude/longitude arrays); .lon is accepted for .long	Real [deg]	x/y or lat/long
erf.obs_nudging.<name>.wind_frame	earth: the file’s wind is east/north and is rotated into the grid; grid: it is already along the grid axes	earth, grid	earth
erf.obs_nudging.<name>.height_ref	agl: heights above the local terrain; msl: above z = 0	agl, msl	agl

A station file is plain text. Everything from a # to the end of a line is a comment. The first line that is not blank names the columns, in any order, from time z u v w theta su sv sw stheta speed direction: time and z are required, the wind is given as u v or as speed direction (m/s, and the meteorological direction the wind blows from, in degrees clockwise from north), and su sv sw stheta are the standard deviations. A quantity with no column is not nudged at that station. Each following row is one height at one time; the rows are grouped by time in increasing order, with the heights of each time increasing and the same at every time. An entry that is not a number (nan) or equals erf.obs_nudging.missing_value is missing: that quantity is not nudged at that height and time, and a missing standard deviation is 0. For example, a lidar with no temperature:

# time [s]  z [m]  u v w [m/s]      su sv sw [m/s]
time    z       u     v     w      su    sv    sw
0.0     40.0    6.0   0.0   0.40   0.3   0.3   0.05
0.0     80.0    6.2   0.0   0.40   0.3   0.3   0.05
600.0   40.0    6.5   0.5   0.40   0.3   0.3   0.05
600.0   80.0    nan   nan   nan    nan   nan   nan

A file with one time holds for the whole run. A file with several is interpolated linearly in time, a height being used only where both bracketing times have it, and the station is inactive before its first time and after its last. A station none of whose quantities are nudged in the run (a lidar without temperature when only theta is nudged) is skipped with a warning.

Every input is checked at start-up: a missing tau or station list, a value out of range, a malformed file (with the line), a station outside the domain, a lat/long station in a run without latitude/longitude arrays, time_type = epoch without a start date, EB terrain, and, on a terrain-fitted mesh, a refined level whose grids do not reach the ground under them all abort with a message naming the input. The terrain under each level is found again after every regrid, so a refined level that its tagging later moves off the ground aborts at that regrid rather than part-way through the following step. The run prints each station with its position, the rotation of its wind, its heights and times and what it nudges. To compare the model with the measurements, write station time series at the same positions (erf.station_names, Station time series).

Lateral Boundary Nudging

Parameter	Definition	Acceptable Values	Default
erf.bdy_nudge_factor	strength of the Davies relaxation in the lateral boundary region; the nudging rate is 1/(bdy_nudge_factor * dt)	Real > 0	10.0
erf.bdy_rho_nudge_factor	Davies factor used for density specifically; a non-positive value means bdy_nudge_factor is used	Real	-1.0 (use erf.bdy_nudge_factor)
erf.bdy_moist_nudge_type	which approach is used to nudge the moist variables in the boundary region; 3 requires use_wrf_bdy_qc_qi = true	0, 1, 2, 3	1
erf.use_wrf_bdy_density	use the dry-air density reconstructed from the wrfbdy data. Ignored (set to false) unless real boundary conditions are used with init_type = WRFInput	Boolean	true
erf.use_wrf_bdy_qc_qi	ingest cloud water and cloud ice from wrfinput and wrfbdy; requires an active moisture model and real boundary conditions with init_type = WRFInput	Boolean	false

For WRF real boundaries, moisture nudging type 0 relaxes only qv toward QVAPOR. Type 1 applies a qv tendency based on ERF qv+qc+qi versus WRF QVAPOR. Type 2 relaxes qv toward QVAPOR and active qc/qi toward zero with the existing latent-heat terms. Type 3 directly relaxes active qv, qc, and qi toward QVAPOR, QCLOUD, and QICE without an added latent-heat term. Type 3 requires erf.use_wrf_bdy_qc_qi = true.

Custom Forcings

In addition, custom forcings or tendencies may be defined on a problem-specific basis. This affords additional flexibility in defining the RHS source term as a function of time and/or height. Implementation entails modifying problem source code inside the Exec directory and overriding the update_*_sources() function(s).

Parameter	Definition	Acceptable Values	Default
erf.custom_forcing_uses_primitive_vars	User-defined source terms set the tendency of primitive variables instead of conserved quantities (rho*prim_var)	Boolean	false
erf.add_custom_rhotheta_forcing	add the problem-specific (rho*theta) source term	Boolean	false
erf.add_custom_moisture_forcing	add the problem-specific moisture source term	Boolean	false
erf.add_custom_w_subsidence	Apply the user-defined vertical velocity profile for use in calculating subsidence source terms	Boolean	false
erf.add_do_theta_advection	apply the custom subsidence to the (rho*theta) equation; only used with add_custom_w_subsidence	Boolean	true
erf.add_do_mom_advection	apply the custom subsidence to the momentum equations; only used with add_custom_w_subsidence	Boolean	true
erf.add_custom_geostrophic_profile	use the problem-specific height-varying geostrophic wind profile; may not be combined with abl_geo_wind_table	Boolean	false
erf.spatial_rhotheta_forcing	the custom (rho*theta) forcing varies horizontally as well as vertically	Boolean	false
erf.spatial_moisture_forcing	the custom moisture forcing varies horizontally as well as vertically	Boolean	false

Note that erf.add_custom_geostrophic_profile cannot be used in combination with an erf.abl_geo_wind_table.

Large Scale Forcing

Large-scale forcing can be used to prescribe time-varying vertical profiles for temperature, water vapor, horizontal wind, and vertical subsidence.

Parameter	Definition	Acceptable Values	Default
erf.large_scale_forcing	Apply time-varying large-scale tendencies and subsidence read from a forcing file	Boolean	false
erf.large_scale_forcing_file	Name of the large-scale forcing file	String	None
erf.forcing_timescale	Relaxation time scale for the u and v large-scale nudging; 0 disables it	Real [s]	0.0

To enable it, set:

erf.large_scale_forcing      = true
erf.large_scale_forcing_file = lsf.txt
erf.forcing_timescale        = 3600.0

where erf.large_scale_forcing_file is the path to a text file containing the large scale forcing data and erf.forcing_timescale is the relaxation timescale (in seconds) for nudging velocities. The file contains one or more time blocks, where each time block is denoted with a header containing the day, number of levels in the block, and reference pressure for that time. Each row of data in the block contains z, p, tls, qls, uls, vls, wls corresponding to level height, pressure, large scale temperature and moisture tendency, large scale zonal and meridional velocity, and large scale vertical subsidence velocity.

• Either a height grid z[m] or pressure grid p[mb] can be provided, where one can be a negative number to indicate the other grid type should be used (e.g. if the z values are negative, the file is interpreted as pressure-level data instead of height-level data). If both grids are provided, then the z grid is used.

• The large scale forcing grid is interpolated to the ERF grid, similar to the input sounding.

• erf.forcing_timescale is the relaxation time scale used when nudging the horizontal velocities toward the uls and vls profiles. The temperature, moisture, and subsidence tendencies are applied directly and are not scaled by this option.

• Times are converted to elapsed seconds relative to the first timestamp in the file.

• Momentum, temperature, and moisture nudging can each be restricted to a custom height interval instead of the entire domain with the erf.nudging_u_z1/erf.nudging_u_z2, erf.nudging_t_z1/erf.nudging_t_z2, and erf.nudging_q_z1/erf.nudging_q_z2 options, respectively. erf.nudging_u, erf.nudging_t, and erf.nudging_q turn momentum, temperature, and moisture nudging on/off independently (all default to true).

• NOTE: All of the nudging described here, including LSF-based wind nudging, requires erf.nudging_from_input_sounding = true; none of it has any effect otherwise. When both erf.nudging_from_input_sounding and erf.large_scale_forcing are true, the u and v velocities are nudged according to the observed large scale velocity uls and vls instead of the input sounding, using erf.forcing_timescale. Temperature and moisture are still nudged from the input sounding as normal, using the input sounding tau_nudging timescale. In this case, wind nudging is controlled solely by erf.large_scale_forcing and is unaffected by erf.nudging_u, which only turns off/on sounding-based wind nudging (and, likewise, erf.nudging_u_z1/erf.nudging_u_z2 only restrict the sounding-based branch).

Example file format for large scale forcing:

z[m] p[mb]  tls[K/s] qls[kg/kg/s] uls  vls  wls[m/s]
0.0,   4, 1000.0  day, levels, pres0
   0.0  1000.00  0.000e+00  0.000e+00  0.0  0.0  0.000e+00
 100.0   990.00  0.000e+00  0.000e+00  0.5  0.2  0.000e+00
1000.0   900.00 -5.000e-06  0.000e+00  2.0  1.0  0.000e+00
5000.0   500.00 -1.000e-05  0.000e+00  6.0  3.0  0.000e+00
0.5,   4, 1000.0  day, levels, pres0
   0.0  1000.00  0.000e+00  0.000e+00  0.2  0.1  0.000e+00
 100.0   990.00  0.000e+00  0.000e+00  0.7  0.3  0.000e+00
1000.0   900.00 -2.500e-06  0.000e+00  2.5  1.2  0.000e+00
5000.0   500.00 -8.000e-06  0.000e+00  6.5  3.2  0.000e+00

Hindcast Forcing and Hurricane Tracking

Hindcast forcing drives a simulation from a sequence of externally supplied data files, optionally with lateral and upper sponge layers, and can track a hurricane eye through the run.

Parameter	Definition	Acceptable Values	Default
erf.hindcast_lateral_forcing	drive the lateral boundaries from hindcast data	Boolean	false
erf.hindcast_boundary_data_dir	directory containing the hindcast lateral boundary data; required if hindcast_lateral_forcing is true	String	None (must be set)
erf.hindcast_data_interval_in_hrs	time interval [hr] between successive hindcast data files; required if hindcast_lateral_forcing is true	Real > 0	-1.0 (must be set)
erf.hindcast_lateral_sponge_strength	strength of the lateral sponge used with hindcast forcing; required if hindcast_lateral_forcing is true	Real > 0	-1.0 (must be set)
erf.hindcast_lateral_sponge_length	width of the lateral sponge region used with hindcast forcing; required if hindcast_lateral_forcing is true	Real > 0	-1.0 (must be set)
erf.hindcast_zhi_sponge_damping	apply sponge damping near the upper boundary with hindcast forcing	Boolean	false
erf.hindcast_zhi_sponge_length	depth of the upper sponge region; required if hindcast_zhi_sponge_damping is true	Real > 0	-1.0 (must be set)
erf.hindcast_zhi_sponge_strength	strength of the upper sponge; required if hindcast_zhi_sponge_damping is true	Real > 0	-1.0 (must be set)
erf.hindcast_surface_bcs	set the surface boundary conditions from hindcast data	Boolean	false
erf.hindcast_surface_data_dir	directory containing the hindcast surface data; read only if hindcast_surface_bcs is true	String	None
erf.io_hurricane_eye_tracker	write out files tracking the eye of a hurricane	Boolean	false
erf.hurricane_eye_latitude	approximate latitude of the hurricane eye in the initial condition; required if io_hurricane_eye_tracker is true	Real	must be set
erf.hurricane_eye_longitude	approximate longitude of the hurricane eye in the initial condition; required if io_hurricane_eye_tracker is true	Real	must be set

Boundary Plane I/O (Coupling Support)

These options control writing and reading boundary-plane data for coupling workflows (e.g., AMR-Wind). See Coupling To AMR-Wind for examples.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.output_bndry_planes	Enable boundary-plane output	0 or 1	0
erf.input_bndry_planes	Enable boundary-plane input	0 or 1	0
erf.bndry_output_planes_interval	Output interval (steps)	Integer >= 0	-1
erf.bndry_output_planes_per	Output interval (time)	Real >= 0	-1.0
erf.bndry_output_start_time	Start time for output, in seconds of elapsed time (the run’s own start time is not added)	Real >= 0	0.0
erf.bndry_output_planes_file	Output directory	String	None
erf.bndry_output_box_lo	Lower-left (x,y) of output box	2 Reals	None
erf.bndry_output_box_hi	Upper-right (x,y) of output box	2 Reals	None
erf.bndry_output_var_names	Variables to write; any of velocity, density, temperature, theta, scalar, qv, qc and ke. An unknown name aborts at the first write	List of strings	None (no variables)
erf.bndry_file	Input boundary-plane directory	String	None
erf.bndry_input_var_names	Variables to read; any of velocity, density, temperature, theta, scalar, qv, qc and ke. An unknown name aborts at start-up. The passive scalars share one boundary condition, so with more than one (the fire coupling’s smoke) scalar fills all of them	List of strings	None (no variables)
erf.in_rad	width, in cells, of the region inside the domain boundary from which the boundary planes are written and into which they are read	Integer >= 0	1

Notes

• If both interval controls are set, output occurs when either criterion is met.

• Output is written for the finest level that fully contains the requested box.

• In a moist run the temperature planes hold the moist temperature, computed with qv, and the reader converts them back to potential temperature with the qv planes. A moist run that writes temperature must therefore also write qv, and a run that reads temperature from planes that include qv must also read qv; otherwise ERF stops. theta planes need no qv.

Numerical Stability

To enhance numerical stability, e.g., for operational runs, we provide some additional controls.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.beta_s	time off-centering coefficient used in the acoustic substepping; positive values weight the update towards the new time	Real	0.1
erf.use_variable_beta_s	with implicit substepping, use a beta_s that varies on the w-faces, max(beta_s_min, min(beta_s_max, h_xi^2 + h_eta^2)), in place of erf.beta_s	Boolean	false
erf.beta_s_min	lower bound of the spatially varying beta_s	Real in [-1, 1]	0.1
erf.beta_s_max	upper bound of the spatially varying beta_s	Real in [-1, 1]	0.8
erf.beta_d	divergence damping coefficient used in the acoustic substepping; how far (rho theta) is projected forward in the horizontal momentum equations	Real in [0, 1]	0.1
erf.w_damping	enable vertical-velocity damping	Boolean	false
erf.w_damping_cfl	Critical vertical advective CFL for w-damping to be applied, if erf.w_damping is true	Real > 0	1.0
erf.w_damping_const	constant damping coefficient [m/s^2], as used by WRF (which uses 0.3); a positive value selects this formulation	Real	-1.0 (not used)
erf.w_damping_coeff	dimensionless damping factor giving a grid-dependent coefficient proportional to dz/dt^2; a positive value selects this formulation	Real	-1.0 (not used)

If erf.w_damping is true, then either erf.w_damping_const or erf.w_damping_coeff must be specified. For WRF-like damping, set erf.w_damping_const = 0.3 to give

\[f_d = - \rho\,\text{sgn}(w)\,(C-C_{crit}) \cdot \gamma,\]

where \(\gamma\) is a constant damping coefficient with units of m/s2 and the advective Courant number is \(C = |w|\Delta t / \Delta z\).

If erf.w_damping_coeff is specified instead, then

\[f_d = - \rho\,\text{sgn}(w)\,(|w|-w_{crit}) \cdot \frac{\alpha}{\Delta t},\]

where \(\alpha\) is a dimensionless damping factor and \(w_{crit} = C_{crit} \Delta z / \Delta t\). This is equivalent to:

\[f_d = - \rho\,\text{sgn}(w)\,(C-C_{crit}) \cdot \alpha \frac{\Delta z}{(\Delta t)^2}.\]

This approach gives a damping coefficient that is sensitive to the vertical grid spacing and robustly damps towards the critical Courant number.

Initialization

The initialization in ERF has two steps: creation of the background state and creation of initial perturbations from the background state.

The initialization strategy is determined at runtime by init_type, which has ten possible values.

See Initialization Pathways for more detail about how to provide initial conditions for an ERF simulation.

A few inputs read at initialization are documented with the feature they belong to rather than here: erf.init_vels_from_checkpoint reuses the velocity field from a checkpoint while re-initializing the rest of the state (see Initialization Pathways), erf.prob_name selects the built-in problem setup, erf.nc_low_file supplies the low-resolution NetCDF data used by Hindcasting using weather data (and, with erf.init_type = WRFInput, the wrflowinp SST for level 0; erf.nc_low_file_<lev> gives a finer level its own, see Sea surface and skin temperatures at each level), erf.buildings_file_name supplies the building geometry used by the immersed-forcing path (see Physical Forcings), and erf.cloud_chamber_budget_interval controls the budget output of the cloud chamber case (see Cloud Chamber).

In addition, there is a run-time option to project the initial velocity field to make it divergence-free.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.init_type	source of the initial data; must be set. See Initialization Pathways	None, Input_Sounding, NCFile, WRFInput, Metgrid, Uniform, ConstantDensity, ConstantDensityLinearTheta, Isentropic, MoistBaseState, HindCast	None
erf.input_sounding_file	Path to the WRF-style input sounding file. When nudging from input soundings, more than one file may be named, paired with erf.input_sounding_time	String(s)	“input_sounding”
erf.sounding_type	how the profiles in an input sounding file are interpreted; read only when init_type = Input_Sounding	ConstantDensity, Ideal, Isentropic, DryIsentropic	Ideal
erf.use_real_bcs	use the real-data lateral boundary conditions from the boundary file. Defaults to true when init_type is WRFInput or Metgrid, false otherwise, and may only be used to turn the real boundary conditions off	Boolean	true if erf.init_type is WRFInput or Metgrid, else false
erf.nc_bdy_file	name of the NetCDF (wrfbdy) lateral boundary file; read only when init_type = WRFInput. If not given, use_real_bcs is set to false	String	None
erf.project_initial_velocity	if 1, project the initial velocity field to make it satisfy the anelastic constraint (per-level)	0, 1	0 (1 if anelastic)
erf.real_width	Lateral boundary total width if use_real_bcs is true	Integer	0
erf.avg_grid_faces_to_nodes	average the wrfinput / met_em heights onto the nodes rather than reconstructing nodal heights whose four-node average reproduces them	Boolean	false
erf.wrfinput_zlevels_from_file	build the vertical grid from the domain-mean layer thickness profile of the wrfinput file, rescaled to reach the domain top. If false, build it instead by solving for the geometric stretch factor that fills the domain starting from the thickest first layer in the file. Used only when avg_grid_faces_to_nodes is false; a level whose grids do not reach the domain top falls back to the geometric construction	Boolean	true
erf.rebalance_wrf_input	rebalance (hydrostatically re-integrate) the state read from wrfinput and wrfbdy. Forced to true if avg_grid_faces_to_nodes is false	Boolean	true
erf.interp_atmos_from_coarse	For fine levels (lev > 0) with WRFInput initialization, interpolate atmospheric state (U, V, W, theta, density, moisture) from coarse level via FillCoarsePatch instead of reading from file. Terrain, surface fields (SST, TSK, land masks), and LSM variables are still read from the fine-level wrfinput file. Intended for time-mismatched WRF input files (e.g., wrfinput_d01 at t=0h, wrfinput_d02 at t=6h) or regridding during runtime. When starting from scratch with both files at the same time, this option is ignored (with a warning) and atmospheric state is read from file. Only applies to lev > 0 with WRFInput; level 0 always reads full atmospheric state.	Boolean	false
erf.real_extrap_w	First-order extrapolation of vertical velocities on lateral boundaries (instead of setting to 0) if use_real_bcs is true	Boolean	true
erf.metgrid_debug_quiescent	If init_type is Metgrid, overwrite initial conditions and boundary conditions to be quiescent.	Boolean	false
erf.metgrid_debug_isothermal	If init_type is Metgrid, overwrite theta to be 300 in initial conditions and boundary conditions.	Boolean	false
erf.metgrid_debug_dry	If init_type is Metgrid, overwrite qv to be dry in initial conditions and boundary conditions.	Boolean	false
erf.metgrid_debug_msf	If init_type is Metgrid, overwrite map scale factors to be 1.	Boolean	false
erf.metgrid_debug_psfc	If init_type is Metgrid, overwrite surface pressure to be 10**5.	Boolean	false
erf.metgrid_interp_theta	If init_type is Metgrid, calculate theta on origin model vertical levels and then interpolate onto the ERF vertical levels.	Boolean	false
erf.metgrid_basic_linear	If init_type is Metgrid, use linear vertical interpolation and no quality control?	Boolean	false
erf.metgrid_use_below_sfc	If init_type is Metgrid, use the origin data levels below the surface?	Boolean	true
erf.metgrid_use_sfc	If init_type is Metgrid, use the origin data level at the surface?	Boolean	true
erf.metgrid_retain_sfc	If init_type is Metgrid, assign the lowest level directly using the surface value from the origin data?	Boolean	false
erf.metgrid_proximity	If init_type is Metgrid, pressure differential for detecting origin levels that are problematically close together	Real
erf.metgrid_order	If init_type is Metgrid, order of the Lagrange polynomial interpolation scheme for vertical interpolation	Integer	2
erf.metgrid_force_sfc_k	If init_type is Metgrid, force the origin data surface level to be included in the interpolation for this many ERF vertical levels: origin levels between the surface and the centre of the last of these levels are dropped	Integer in [0, number of ERF vertical levels]	6

Notes

If erf.init_type = WRFInput or erf.init_type = NCFile, the problem is initialized with mesoscale data contained in a NetCDF file, provided via erf.nc_init_file_0 (e.g., “wrfinput_d01”).

A file may also be given for each refined level – erf.nc_init_file_1 (e.g., “wrfinput_d02”), erf.nc_init_file_2, and so on. A file at level 0 is required; files at finer levels are optional. A refined level given no file of its own is initialized by interpolation from its parent, and its base state is built from the level-0 reference profile evaluated at that level’s own heights. See Nested Initialization From WRF Input Files for the nesting options and their restrictions.

In addition, if erf.use_real_bcs = true, the lateral boundary conditions must be supplied in a NetCDF files specified by erf.nc_bdy_file (e.g., “wrfbdy_d01”). (If erf.use_real_bcs = false, no file is read for the boundary conditions so they must be specified in the inputs file.)

If erf.use_real_bcs = true, the extent of the relaxation zone may be controlled with erf.real_width (corresponding to WRF’s spec_bdy_width).

Note that the erf.project_initial_velocity option is available for all init_type options. If using the anelastic formulation this will be true regardless of the input; if using the compressible formulation the default is false but that can be over-written.

Map Scale Factors

Map scale factors are always present in the evolution equations, but the values default to one unless specified in the initialization when erf.init_type = WRFInput or erf.init_type = Metgrid.

There is an option to test the map scale factors by setting erf.test_mapfactor = true; this arbitrarily sets the map factors to 0.5 in order to test the implementation.

Terrain

ERF allows the use to specify whether terrain-fitted coordinates should be used by setting erf.terrain_type = StaticFittedMesh (static mesh) or erf.terrain_type = MovingFittedMesh (time-dependent mesh). If using terrain-fitted coordinates, the user also has the option to specify one of three methods for defining how the terrain-fitted coordinates given the topography:

• Basic Terrain Following (BTF):

  The influence of the terrain decreases linearly with height.

• Smoothed Terrain Following (STF):

  Small-scale terrain structures are progressively smoothed out of the coordinate system as height increases.

• Sullivan Terrain Following (name TBD):

  The influence of the terrain decreases with the cube of height.

The user can also specify that terrain should be represented with an immersed forcing method (with an optional wall model, see Physical Forcings for more detail), or with an embedded boundary / cut cell representation. The embedded boundary geometry may be built from the terrain height field, from a three-dimensional STL mesh of buildings, or from the union of the two; see STL-Based Building Geometry.

Note

The embedded boundary / cut cell representation is a work in progress and not ready for use!

The height at the surface nodes can be defined analytically, read from a text file specified by erf.terrain_file_name, or read from a NetCDF file specified by erf.terrain_file_name_nc. The NetCDF option requires NetCDF support and takes precedence when both inputs are present. The explicit Cartesian format uses a height variable named height, z, terrain, HGT_M, or AGL with dimensions (y,x) or (time,y,x) (time must be the leading dimension). It must also provide one-dimensional, finite, strictly increasing, uniformly spaced x and y coordinate variables matching the height dimensions; ERF reads the first time record when one is present.

A genuine WPS geo_em file may instead provide HGT_M(Time,south_north,west_east) without Cartesian x/y variables. It must provide matching first-time-record XLAT_M and XLONG_M fields and the WPS global attributes MAP_PROJ, CEN_LAT, CEN_LON, STAND_LON, DX, DY, WEST-EAST_GRID_DIMENSION, and SOUTH-NORTH_GRID_DIMENSION. ERF supports Lambert (1), polar (2), and Mercator (3) WPS projections; Lambert additionally requires TRUELAT1 and TRUELAT2, while the other two require TRUELAT1. The latitude/longitude projection (6) is rejected, because WPS writes DX/DY in degrees for it while ERF consumes them as metres. HGT_M, XLAT_M, and XLONG_M must have the exact (Time,south_north,west_east) order, and the first time record is selected. The WPS grid dimensions, DX/DY, and domain extent must match the ERF level-0 Cartesian geometry.

WPS fields are mass-point fields. ERF maps their logical mass-point locations to terrain nodes using x_mass = x_lo + (i+1/2) DX and y_mass = y_lo + (j+1/2) DY. At the four outer node edges, where no WPS mass point exists, ERF holds the nearest mass-point value (an explicit one-sided mass-to-node conversion); this is not general extrapolation. For both formats, bilinear interpolation includes the final coordinate. Explicit Cartesian terrain nodes genuinely outside the file grid are assigned zero, and malformed or nonfinite WPS metadata, coordinates, or heights are rejected.

For the text format, the ordering of data in the file is first nx, ny (where nx is the number of values specified in the x-direction and ny is the number of values specified in the y-direction; note that these need not match the resolution of the problem). Then nx x-values are read followed by ny y-values. Finally, the z-coordinates are read in the order z(x1,y1), z(x1,y2), z(x1,y3), … z(x2,y1), … z(nx,ny). An example is given in Exec/CanonicalTests/ABL/erf_terrain_def.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.terrain_type	how terrain and immersed boundaries are represented. Only StaticFittedMesh is allowed with init_type = WRFInput or Metgrid	None, StaticFittedMesh, MovingFittedMesh, EB, ImmersedForcing	None
erf.flat_terrain	require a horizontally flat StaticFittedMesh and permit fixed-index planar averages after validation.	Boolean	false
erf.terrain_smoothing	specify terrain following	0, 1, 2	0
erf.amr_terrain_refinement	terrain refinement strategy for fine levels with terrain_smoothing = 1 or 2. “interpolate” uses coarse-interpolated mesh as-is. “transform” reads fine terrain from wrfinput and blends with interpolated mesh using height-dependent decay. When terrain_smoothing = 1 or 2 with WRFInput initialization on multilevel grids, “transform” is required (code will abort if “interpolate” is used). Ignored when terrain_smoothing = 0.	“interpolate”, “transform”	“interpolate”
erf.terrain_file_name	text file of terrain heights in ERF order (y varies fastest); see the format and the start-up checks below	String	NONE
erf.terrain_file_name_nc	NetCDF terrain filename	String	NONE
erf.buildings_type	how buildings are represented; see Physical Forcings; ImmersedForcing is not supported with erf.terrain_type = EB	None, ImmersedForcing	None
erf.use_rotate_surface_flux	rotate the MOST surface stresses to be normal to the terrain surface; requires that terrain be used	Boolean	false
erf.terrain_file_name_USGS	text file of terrain heights in USGS format (x varies fastest); an alternative to erf.terrain_file_name, checked at start-up as described below	String	None
prob.custom_terrain_type	selects the problem-specific terrain initialization; any value other than None calls init_my_custom_terrain	String	None
prob.dir	direction of variation of the WoA custom terrain: 0 for x, 1 for y	0, 1	0
prob.L	width scale [m] of the WoA and Cos4Hill custom terrain	Real > 0	100.0
prob.hmax	peak height [m] of the WoA and Cos4Hill custom terrain	Real	0.0
prob.z_offset	vertical offset [m] applied by the WoA, RaisedFlat and Cos4Hill custom terrain	Real	0.0
prob.Ampl	amplitude [m] of the MovingSineWave custom terrain	Real	0.0
prob.wavelength	wavelength [m] of the MovingSineWave custom terrain	Real > 0	100.0

Examples of Usage

• erf.terrain_smoothing = 0

  BTF is used when generating the terrain following coordinate.

• erf.terrain_smoothing = 1

  STF is used when generating the terrain-fitted coordinate. Additionally, erf.terrain_gamma_m (default=0.5) may be used to set the minimum allowable fractional grid spacing. From Klemp 2011, MWR: “Values of 0.5-0.6 seem to work best in 2D applications, while values about half this magnitude appear better for 3D real-terrain simulations.”

• erf.terrain_smoothing = 2

  Sullivan TF is used when generating the terrain following coordinate.

erf.amr_terrain_refinement is read only on levels finer than level 0 and only when erf.terrain_smoothing is 1 or 2; it is ignored otherwise. Any value other than "interpolate" or "transform" is an error, so that a misspelled mode cannot silently leave the fine mesh untransformed.

For WRFInput initialization with multilevel AMR: When using erf.init_type = WRFInput with terrain_smoothing = 1 or 2 on multilevel grids, “transform” mode is required. Using “interpolate” mode will cause the code to abort with an error. This requirement ensures fine-scale terrain features from the wrfinput file are properly blended with the smoothed coarse mesh while maintaining C0 continuity at coarse-fine interfaces.

• erf.amr_terrain_refinement = “interpolate”

  Default mode for AMR with STF/Sullivan terrain smoothing (terrain_smoothing=1 or 2). Fine levels use terrain coordinates interpolated from the coarse level, maintaining smooth consistency across refinement levels.

• erf.amr_terrain_refinement = “transform”

  Advanced mode for AMR with STF/Sullivan (terrain_smoothing=1 or 2). Fine levels read the higher-resolution terrain data for the surface (k=0) and add it to the interpolated mesh as a correction that decays linearly to zero at the top of the fine grids, so that the fine mesh still matches the coarse one at the coarse/fine boundary. This captures finer terrain features, at the cost of requiring that every box on a fine level reach the surface; if the fine grids are chopped in the vertical the run aborts and asks you to raise amr.max_grid_size_z or to use "interpolate" instead.

• When setting erf.terrain_file_name (or erf.buildings_file_name, which uses the

  same reader), the file is plain text with one value per line: the integer nx on the first line, the integer ny on the second line, then the nx values of the x-coordinate, then the ny values of the y-coordinate, then the nx times ny heights. The heights are in the order h(x1,y1), h(x1,y2), h(x1,y3), …, h(x2,y1), …, that is y varies fastest and height n sits at (x[n / ny], y[n % ny]). This is contrary to standard Fortran ordering; a file written with x varying fastest is read transposed. nx or ny may be 1: a single value in a direction makes the surface constant in that direction (for example a ridge profile in x with ny = 1 for a run periodic in y). The USGS format of erf.terrain_file_name_USGS is: longitude and latitude of the origin on the first line, nx and ny on the second, then nx times ny lines of x y height with x varying fastest; nx and ny must be at least 2, and every point of a row has the y of the row. Blank lines are skipped in this format. Each file is read once per run, however many levels and regrids use it.

• Both text formats are checked when the file is read, and the run stops with a message

  naming the file if

  • nx or ny is smaller than 1 (ERF format) or 2 (USGS format);

  • a line is missing or is not a number (nan and inf included); a line has text after its value (ERF format) or does not hold exactly x y height (USGS format, including a truncated last line); or the file has more values than nx and ny ask for;

  • (USGS format) the y value changes within a row of nx points;

  • the x or y values do not increase strictly (USGS format: the x values of each row, and y from row to row);

  • the table does not cover the domain: in x and in y, each end of the table may stop at most one table spacing inside geometry.prob_lo or geometry.prob_hi, which allows the common layout of one height per cell starting at prob_lo (with an allowance of 1e-3 of that spacing for coordinates written with few digits). Beyond the table the reader only extends the heights from its edge: linearly before the first point, and in the ERF format by holding the last value after the last point (the USGS format extends linearly at both ends). A direction with a single value is not checked.

  A table larger than the domain is accepted. For each valid file ERF prints once the size and extent of the table, the order its heights are read in, where the lowest and highest heights sit, and the largest slopes |dh/dx| and |dh/dy| between neighbouring table points with where they sit. A transposed file shows up there: the highest point or the steepest slope is not where the terrain should have it.

• On a terrain-fitted mesh (erf.terrain_type = StaticFittedMesh or MovingFittedMesh)

  without real-data lateral boundaries, ERF prints a WARNING when the terrain slope |grad h| exceeds 0.3 (about 17 degrees) in the cells next to an inflow or outflow face (Inflow, Outflow, InflowOutflow, HO_Outflow or Open; not periodic faces and not walls), for terrain from any source. The cells checked are those whose stencils read the face’s ghost cells: the solver’s ghost-cell width, 2 to 4 cells depending on the advection schemes and numerical diffusion. The slope includes the map factors, as in the diffusive limits. Each level that reaches the face is checked on its own mesh whenever it has a new set of grids: at initialisation, on the first step after a restart, and after a regrid, so a fine level created later is checked too; each level and face is reported at most once. A MovingFittedMesh surface is checked only at those times, not as it moves. No warning is printed when erf.implicit_terrain_metric or erf.diffusive_dt_limit is on, nor on a level where erf.smag2d_slope_limiter or erf.smag2d_kh_cap is on; these options limit the terrain-metric diffusion on steep cells and need an eddy-diffusivity closure (the first two Smagorinsky2D, erf.implicit_terrain_metric the implicit vertical solve). None of them changes the terrain at the face; flattening the terrain within those cells of the face does. The warning is a prompt to look: it does not change the run.

Immersed Forcing

These inputs configure the immersed-forcing representation of solid bodies, selected with erf.terrain_type = ImmersedForcing or erf.buildings_type = ImmersedForcing. At most one of erf.if_surf_temp_flux, erf.if_init_surf_temp and erf.if_Olen may be set.

Parameter	Definition	Acceptable Values	Default
erf.immersed_forcing_substep	apply the immersed forcing source terms during the acoustic substeps only	Boolean	true if compressible, false if anelastic
erf.if_Cd_momentum	immersed forcing drag coefficient for momentum	Real > 0	500.0 if compressible, 50.0 if anelastic
erf.if_Cd_scalar	immersed forcing drag coefficient for scalars	Real > 0	50.0 if compressible, 5.0 if anelastic
erf.if_implicit_drag	use a point-implicit (linearly implicit) form of the immersed forcing drag rather than an explicit forward-Euler source	Boolean	false
erf.if_z0	roughness length [m] used by the immersed forcing wall model	Real > 0	0.1
erf.if_surf_temp_flux	surface temperature flux [K m/s] imposed at immersed surfaces; only one of if_surf_temp_flux, if_init_surf_temp and if_Olen may be set	Real	1.e-8
erf.if_init_surf_temp	surface temperature [K] imposed at immersed surfaces; only one of if_surf_temp_flux, if_init_surf_temp and if_Olen may be set	Real	0.0
erf.if_surf_heating_rate	rate of change [K/hr] of the immersed surface temperature (converted internally to K/s)	Real	0.0
erf.if_Olen	Obukhov length [m] imposed at immersed terrain; only one of if_surf_temp_flux, if_init_surf_temp and if_Olen may be set; used as given, the wall law holds \(|z/L| \le 100\) (both heights clamp for \(|L| < 0.005\,\Delta\)); immersed buildings get no temperature forcing from it	Real != 0	1.e-8
erf.if_use_most	use the Monin-Obukhov similarity theory wall model at immersed surfaces	Boolean	false
erf.if_snap_partial_cells	read the blanking snapped to solid or fluid at half, so a height-map building becomes a staircase of whole cells with no sliver cells: the wall law sits on the boundary solid cells (roofs included) with the full log-law target and the drag on the interior cells, a momentum face between a solid and a fluid cell gets the drag toward zero (no penetration), the thermal conditions sit on the same boundary cells; buildings only, terrain by immersed forcing keeps its fractions; false keeps the raw fractions, on which the wall law and the drag disagree at the corners of the reader’s one-cell ramp and grow a checkerboard over hours; set it for buildings from height maps (see Exec/RegTests/ImmersedForcingTest/PartialCells)	Boolean	false
erf.if_stability_correction	include the stability corrections in the immersed forcing similarity functions; use with caution for horizontal walls	Boolean	false
erf.if_ws_floor	lower bound [m/s] on the wind speed in the limit on the per-step change of the building wall-law forcing; the stability estimate has its own, off by default (erf.if_stability_wind_floor)	Real > 0	0.001
erf.if_stability_wind_floor	lower bound [m/s] on the tangential wind behind the friction velocity of the wall law’s stability estimate (Obukhov length) and its heat transfer; WRF and the flat-ground surface layer use 0.1; 0 leaves the wind as it is	Real >= 0	0
erf.if_psi_cap_factor	cap on \(\psi_m\) in the wall law’s velocity target and, before it forms \(u_*\), in its friction velocity, as a fraction of \(\ln(z/z_0)\); WRF uses 0.9; 1 caps the target at \(\ln(z/z_0)\) and leaves \(u_*\) uncapped	0 < Real <= 1	1
erf.if_damp_alpha	damping coefficient used in the immersed forcing wall model	Real	0.5

Surface energy balance on immersed-boundary faces

These inputs configure the surface energy balance on the faces of resolved buildings; see Surface energy balance on immersed-boundary faces for the formulation. They need erf.buildings_type = ImmersedForcing without terrain by immersed forcing (erf.terrain_type = ImmersedForcing is not supported: every solid column would be taken for a building), a uniform vertical grid (no erf.terrain_z_levels or stretched mesh) and no regridding (erf.regrid_int unset); they are off by default.

Parameter	Definition	Acceptable Values	Default
erf.ibseb.enable	build the face set of the resolved buildings and run the balance on it	Boolean	false
erf.ibseb.n_slab_layers	conduction layers per face	Integer in [1, 32]	4
erf.ibseb.T_skin_init	initial skin temperature of every face [K]	Real > 0	300.0
erf.ibseb.T_interior	interior (deep) temperature of the slabs [K]	Real > 0	293.0
erf.ibseb.csv_file	per-building report file; a restart appends from its next report (the step it starts from is not written again). With radiation = two_stream its dni_Wm2 and diffuse_h_Wm2 columns are the means over the level’s faces of what each face takes from its own column, not one sky’s irradiance as with radiation = prescribed	String	“ibseb_buildings.csv”
erf.ibseb.csv_int	steps between report rows; <= 0 disables the report	Integer	100
erf.ibseb.debug	[IBSEB DEBUG] prints: the set’s description at build (per-rank counts, buildings), a summary every step and per-building rows	Boolean	false
erf.ibseb.dump_faces_file	prefix of a per-rank CSV of every face (geometry, view fractions, shadow, shortwave, skin temperature), written at every report; a refined level N adds .levN to the prefix; empty disables	String	“”
erf.ibseb.radiation	where the faces’ sunlight, sky light and longwave come from. prescribed: the clear-sky formulas and inputs below. two_stream: the two-stream radiation’s columns, each face reading the column next to it at its own height; needs erf.radiation_model = TwoStream with its shortwave on, and every level must span the domain in z. Then sw_direct_normal, sw_diffuse, sw_transmission, sw_diffuse_coeff, solar_constant and albedo_ground must not be given	“prescribed”, “two_stream”	“prescribed”
erf.ibseb.sun_mode	the sun’s position, and with the prescribed provider its irradiances: fixed: the given zenith and azimuth (prescribed: with the given irradiances); solar: sun and clear-sky irradiances from the site and time; two_stream: the sun of erf.radiation_model = TwoStream (start_datetime, erf.rad_cons_lat / lon; prescribed: its top-of-atmosphere irradiance with the clear-sky irradiances), required with the two-stream calendar sun; the solar site, day, time and solar constant must not be given with it	“fixed”, “solar”, “two_stream”	“fixed”
erf.ibseb.sun_zenith_deg	fixed sun: zenith angle [deg]	Real in [0, 180]	45.0
erf.ibseb.sun_azimuth_deg	fixed sun: azimuth clockwise from north [deg]; 90 east, 180 south, 270 west	Real	180.0
erf.ibseb.sw_direct_normal	fixed sun: direct-normal irradiance [W/m2]; not with radiation = two_stream	Real >= 0	800.0
erf.ibseb.sw_diffuse	fixed sun: diffuse irradiance on a horizontal surface [W/m2]; not with radiation = two_stream	Real >= 0	100.0
erf.ibseb.latitude_deg	solar: site latitude, north positive	Real in [-90, 90]	40.0
erf.ibseb.longitude_deg	solar: site longitude, east positive	Real in [-180,180]	-105.0
erf.ibseb.day_of_year	solar: day of year (1 = 1 January) of the UTC date at simulation time zero; advances by one at each 00:00 UTC during the run	Real in [1, 366]	172
erf.ibseb.time_zero_utc_s	solar: seconds after 00:00 UTC of day_of_year at simulation time zero (86400 or more starts on a later day)	Real	43200.0
erf.ibseb.solar_constant	solar: solar constant [W/m2]; not with radiation = two_stream	Real > 0	1361.0
erf.ibseb.sw_transmission	prescribed provider, sun_mode solar or two_stream: bulk clear-sky transmission of the Bird form	Real in (0, 1]	0.7
erf.ibseb.sw_diffuse_coeff	prescribed provider, sun_mode solar or two_stream: share of the attenuated beam that arrives as diffuse light	Real in [0, 1]	0.5
erf.ibseb.albedo	shortwave albedo of the faces (uniform until the material library)	Real in [0, 1]	0.3
erf.ibseb.albedo_ground	ground albedo for the reflected diffuse term; not with radiation = two_stream	Real in [0, 1]	0.2
erf.ibseb.emissivity	longwave emissivity of the faces	Real in (0, 1]	0.9
erf.ibseb.emissivity_ground	ground emissivity for the ground term; not with lw_mode = two_stream	Real in (0, 1]	0.95
erf.ibseb.view_n_az	azimuths of the hemisphere sampling for the view fractions	Integer >= 1	16
erf.ibseb.view_n_el	elevations of the hemisphere sampling	Integer >= 1	8
erf.ibseb.sun_min_elev_deg	lowest sun elevation [deg] at which the shadow test is exact everywhere: each rank’s ray map reaches (tallest building) / tan(elevation) beyond its own columns; with the sun lower, a building farther than that from a face casts no shadow on it. The map reaches at least as far as the shallowest view ray (view_n_az, view_n_el) too, and a domain it covers whole is exact whatever the value	Real in (0, 90)	2.0
erf.ibseb.lw_mode	sky longwave. fixed: lw_down. gray: sky_emissivity sigma T_air^4, with the air temperature of the face’s fluid cell. two_stream (only with radiation = two_stream, and the two-stream longwave on): the column’s longwave down and up at the face’s height, for the sky and the ground; then lw_down, sky_emissivity, T_ground and emissivity_ground must not be given	“fixed”, “gray”, “two_stream”	“gray”; “two_stream” with radiation = two_stream
erf.ibseb.lw_down	fixed sky longwave [W/m2]; not with lw_mode = two_stream	Real >= 0	300.0
erf.ibseb.sky_emissivity	gray sky: effective clear-sky emissivity; not with lw_mode = two_stream	Real in (0, 1]	0.83
erf.ibseb.T_ground	ground temperature for the ground longwave term [K]; not with lw_mode = two_stream	Real > 0	300.0
erf.ibseb.z0_wall	momentum roughness length of the faces for the wall function [m]	Real > 0	0.01
erf.ibseb.z0h_wall	heat roughness length of the faces [m]	Real > 0	0.001
erf.ibseb.stability_correction	apply the surface layer’s similarity functions to the wall function on roofs, iterated on the face’s own Obukhov length; walls stay on the log law	Boolean	false
erf.ibseb.couple_heat	add the face sensible flux to the temperature equation; false diagnoses it only	Boolean	true
erf.ibseb.material_file	material library CSV in the SLUCM schema (mat_id, name, albedo, emissivity, k_therm, rho_cp, thickness, description); empty keeps the uniform inputs	String	“”
erf.ibseb.material_default	material id of every building not listed below	Integer	1
erf.ibseb.material_by_building	one material id per building, in level 0’s building order (every level maps its buildings to level 0’s)	Integers	none
erf.ibseb.k_therm	uniform slab conductivity [W/m/K]	Real > 0	1.0
erf.ibseb.rho_cp	uniform slab volumetric heat capacity [J/m3/K]	Real > 0	1.6e6
erf.ibseb.thickness	uniform slab thickness [m]	Real > 0	0.3
erf.ibseb.prognostic	solve the balance for the skin temperature every step; false keeps the skin fixed and diagnoses the terms	Boolean	true
erf.ibseb.T_skin_min	lower bound of the skin temperature [K]	Real > 0	260.0
erf.ibseb.T_skin_max	upper bound of the skin temperature [K]; raise it for faces under a fire	Real > T_skin_min	380.0
erf.ibseb.newton_max_iter	Newton iteration cap per face and step	Integer >= 1	20
erf.ibseb.newton_tol_K	Newton stops when a step changes the skin temperature by less than this [K]	Real > 0	1.0e-3
erf.ibseb.newton_max_step_K	largest Newton step [K]	Real > 0	20.0
erf.ibseb.Q_ext_uniform	external incident flux on every face [W/m2], absorbed with the emissivity (test hook for the fire coupling)	Real >= 0	0.0
erf.ibseb.dump_faces_tag_step	name each face dump by its step so every one is kept	Boolean	false
erf.ibseb.obukhov_seed	with the stability correction, seed the roof’s Obukhov iteration from the ground surface layer’s field at the face’s column (“ground”) or from neutral (“neutral”)	String	“ground”
erf.ibseb.convective_velocity	“deardorff” adds a convective velocity scale to the wind of the wall function, sqrt(U_tan^2 + (beta w*)^2), with w* from the previous step’s flux out of the face; “none” keeps the neutral log law on the tangential wind	String	“none”
erf.ibseb.beta_conv	gustiness factor on w*	Real > 0	1.2
erf.ibseb.z_i_mode	depth in w* on roofs: “bulk_ri” diagnoses the mixed layer on the horizontal-mean profile every step, “pblh” reads the surface layer’s boundary-layer height at the column (falling back to bulk_ri), “fixed” uses z_i; the roof height is subtracted and the building height is the floor; walls use the building height	String	“bulk_ri”
erf.ibseb.z_i	fixed mixed-layer depth [m]	Real > 0	1000.0
erf.ibseb.ri_crit	critical bulk Richardson number of the depth diagnostic	Real > 0	0.25
erf.ibseb.obukhov_relax	under-relaxation of u* between passes of the roof’s Obukhov iteration (1 = none), as the surface layer’s	Real in (0, 1]	0.5

The plotfile variables ibseb_nfaces (wall faces touching each fluid cell), ibseb_tskin (their mean skin temperature), ibseb_sw_abs (their mean absorbed shortwave), ibseb_shadow (their mean shadow flag), ibseb_lw_net (their mean net longwave), ibseb_f_sky (their mean sky view fraction), ibseb_H (their mean sensible flux) and ibseb_G (their mean conduction into the wall) are available when the balance is on. The immersed forcing’s own surface-temperature inputs (erf.if_init_surf_temp, erf.if_surf_temp_flux, erf.if_Olen) must be absent when the balance is on: it owns the temperature condition at the buildings.

Surface Layer (MOST)

These inputs configure the Monin-Obukhov similarity surface layer used by a surface_layer lower boundary. See Surface Layer Boundaries for the formulation and for worked examples. Which of them are read depends on erf.surface_layer.flux_type; the entries below say so where it matters, and the ones marked Required abort the run if they are not given.

Parameter	Definition	Acceptable Values	Default
erf.surface_layer.flux_type	how the surface fluxes are computed	moeng, rico, bulk_coeff, custom	moeng
erf.most.z0	constant surface roughness length [m]	Real > 0	0.1
erf.most.include_wstar	add the free-convection velocity scale w* to the mean surface velocity (Beljaars 1995); requires erf.most.pblh_calc to be set	Boolean	false
erf.most.pblh_calc	which scheme diagnoses the PBL height used by the w* correction	none, MYNN25, MYNNEDMF, YSU, MRF	none
erf.most.pot_surf_temp	prescribed surface potential temperature [K]; a positive value selects the surface-temperature formulation	Real > 0	-1.0 (not set)
erf.most.abs_surf_temp	prescribed surface absolute temperature [K], converted to potential temperature each step with the surface pressure diagnosed from the lowest cell; z-low face only, not with EB terrain, SST/TSK input, erf.most.use_sfc_fluxes, erf.most.use_sfc_sst or custom/rico/bulk_coeff fluxes	Real > 0	-1.0 (not set)
erf.most.surf_temp	deprecated spelling of erf.most.pot_surf_temp; at most one of the three may be given, and a value that is given must be positive	Real > 0	-1.0 (not set)
erf.most.surf_moist	prescribed surface moisture [kg/kg]; read only with an active moisture model	Real >= 0	-1.0 (not set)
erf.most.surf_heating_rate	rate of change [K/h] applied to the prescribed surface temperature (absolute with abs_surf_temp) from the start of the simulation; may not be combined with erf.most.surf_temp_flux	Real	0.0
erf.most.surf_temp_flux	prescribed surface heat flux [K m/s]; may not be combined with erf.most.surf_heating_rate	Real	0.0
erf.most.surf_moist_flux	prescribed surface moisture flux; used when erf.most.surf_moist is not set	Real	0.0
erf.most.ustar	prescribed friction velocity [m/s]. Required when flux_type is custom or rico	Real	must be set
erf.most.tstar	prescribed surface temperature scale [K]. Required when flux_type is custom or rico	Real	must be set
erf.most.qstar	prescribed surface moisture scale. Required when flux_type is custom or rico; a non-zero value requires an active moisture model	Real	must be set
erf.most.rhosurf	surface density used with the prescribed fluxes instead of the density in the first cell; may not be combined with erf.most.use_sfc_fluxes	Real	0.0 (use first cell)
erf.most.Cd	bulk transfer coefficient for momentum. Required when flux_type = bulk_coeff	Real	must be set
erf.most.Ch	bulk transfer coefficient for heat. Required when flux_type = bulk_coeff	Real	must be set
erf.most.Cq	bulk transfer coefficient for moisture. Required when flux_type = bulk_coeff	Real	must be set
erf.most.rico.theta_z0	surface potential temperature [K] used by the RICO formulation	Real	298.0
erf.most.rico.qsat_z0	surface saturation mixing ratio used by the RICO formulation	Real	0.001
erf.most.roughness_type_land	how the roughness length is computed over land	constant	constant
erf.most.roughness_type_sea	how the roughness length is computed over water	charnock, coare3.0, donelan, modified_charnock, wave_coupled, constant	charnock
erf.most.smooth_flow_viscosity	include the viscous term in the variable roughness models used over sea?	Boolean	true
erf.most.charnock_constant	Charnock constant a; a non-positive value selects the variable COARE3.0 parameter. Read only when roughness_type_sea = charnock	Real	0.0185
erf.most.modified_charnock_depth	depth d [m] used by the modified Charnock relation. Read only when roughness_type_sea = modified_charnock. Values outside the range are clamped to the bounds, which follow the fit range of Jiménez & Dudhia (2018).	Real in [10, 100]	30.0
erf.most.roughness_file_name	text file of (x, y, z0) giving a spatially varying roughness length; may be given once or once per level. Read only when flux_type is moeng or when surface-flux rotation is active	String, or list of Strings	None
erf.most.ignore_sst	use the skin temperature rather than the sea-surface temperature from the input data	Boolean	false
erf.most.use_lsm_skin_temperature	take the land model’s skin temperature (SLM tsurf, Noah-MP t_sfc) as an absolute temperature and convert it to potential temperature at the surface pressure. When false, an LSM tsurf, theta or t_surf field is copied unchanged and t_sfc is not used	Boolean	false
erf.most.use_sfc_fluxes	read time-varying sensible and latent heat fluxes and kinematic surface stress from a text file; may not be combined with erf.most.use_sfc_sst or erf.most.rhosurf	Boolean	false
erf.most.use_sfc_sst	read a time-varying sea-surface temperature from a text file; may not be combined with erf.most.use_sfc_fluxes	Boolean	false
erf.most.sfc_file	text file supplying the surface forcing; required when either of the two options above is true. Not supported with EB terrain	String	must be set
erf.most.average_policy	how the MOST average is formed: 0 is a planar average and 1 is a local region average	0, 1	0 (1 if the mesh has variable dz)
erf.most.radius	radius, in cells, of the local region used when erf.most.average_policy = 1	Integer >= 0	0
erf.most.time_average	apply an exponential moving average in time to the MOST average	Boolean	false
erf.most.time_window	width of the exponential filter, normalized by the time step; read only when erf.most.time_average is true	Real > 0	1.0e-16
erf.most.zref	height [m] above the surface at which the MOST quantities are evaluated. If unset, terrain-fitted meshes query 10 m above the surface and other meshes use the first cell center, taken from the z levels on a stretched mesh. A height on a cell face lies in the cell above it. On the low z face of a constant-dz mesh the value given here is an absolute z (the height plus geometry.prob_lo[2]); the surface layer always uses the height above the surface	Real > 0	see description
erf.most.k_arr_in	vertical cell index at which the MOST quantities are evaluated, one per level; an alternative to erf.most.zref; on the low z face an absolute index, on the other faces a number of cells from the wall	List of Integers	None
erf.most.use_interpolation	interpolate to the query point rather than using the containing cell	Boolean	false
erf.most.use_normal_vector	locate the query point along the surface normal rather than vertically; for terrain-fitted meshes	Boolean	false
erf.most.terrain_rotate	rotate the averaged vectors into the terrain-following frame	Boolean	false
erf.most.include_subgrid_vel	add a subgrid contribution to the mean surface velocity	Boolean	false

Land Surface Model

The land surface model provides energy and moisture fluxes at the lower boundary when that lower boundary is land.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.land_surface_model	Enables land surface energy and moisture fluxes	None, SLM, NOAHMP	None
erf.is_land	whether each AMR level is treated as land (1) or water (0) (per-level)	0, 1	1
erf.lsm_nsoil	number of soil layers; must match NSOIL in the Noah-MP namelist, and also sets how many smois_<layer> / sh2o_<layer> / tslb_<layer> 2-D diagnostics exist	Integer >= 1	4

Note

Noah-MP requires USE_NOAHMP=TRUE at build time. See Coupling to Noah-MP for details. See Simplified Land-surface Model (SLM) for the complete set of slm. options.

Note

When the two-stream radiation model is selected via erf.radiation_model = TwoStream, a Simplified Surface Energy Balance (SEB) force-restore method is available as an alternative to Noah-MP for computing surface temperature and moisture evolution. It is enabled via erf.radiation.seb_enable, erf.radiation.seb_diagnostic_enable, and erf.radiation.seb_prognostic_enable and does not require Noah-MP. The SEB method uses a force-restore formulation to evolve surface temperature \(T_s\) and moisture \(q_s\) toward deep-soil reservoir values, given the diagnosed surface energy balance residual (\(R_{net} - H - LE - G\)). When Noah-MP is active, Noah-MP’s surface prognostics take precedence and the force-restore update is automatically skipped at those levels (safeguard against double-counting). See the “Radiation” section below for the full SEB parameter list and the Theory documentation for the governing equations.

Ocean Surface Model

The ocean surface model provides energy fluxes at the lower boundary when that lower boundary is ocean.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.use_coupled_sst	an external ocean coupler supplies the sea surface temperature for some or all water cells; this must be set at problem definition time because the surface layer uses it to select its temperature boundary treatment	Boolean	false

Note

erf.use_coupled_sst is independent of erf.land_surface_model. Coupled SST is applied through the lower-boundary path alongside wrflowinp SST/TSK, and only on the water cells the coupler actually covers: land keeps its land surface model, and water the ocean grid does not reach keeps the wrflowinp value. A coupled run can therefore also run Noah-MP or the SLM over land.

Coupling Type (Data Exchange)

For coupled simulations with AMR-Wind or WaveWatch3, this controls the directionality of data exchange.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.coupling_type	how data is exchanged between AMR levels. Forced to OneWay if some levels are anelastic and others compressible	OneWay, TwoWay	TwoWay

Notes

• TwoWay: Bidirectional coupling - ERF both receives and sends data

• OneWay: ERF receives forcing but doesn’t send data back

See Coupling To AMR-Wind and Coupling To WW3 for more information.

Moisture

ERF supports several Eulerian moisture and microphysics models and, when particle support is enabled, the Lagrangian Super-Droplet Method. ERF also contains the developing Eulerian spectral-bin capability selected with erf.moisture_model = SBM.

The current SBM option transports a liquid-water size distribution by resolved advection on one atmospheric grid level. It is not yet a complete warm-cloud microphysics scheme and does not support operational multilevel spectral transport. See Spectral-Bin Microphysics (SBM) for the spectral representation, configuration, and current limitations.

The following run-time options control the moisture model.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.moisture_model	which moisture / microphysics model to use	None, SatAdj, Kessler, Kessler_NoRain, SAM, SAM_NoIce, SAM_NoPrecip_NoIce, Morrison, Morrison_NoIce, WSM6, WDM6, SuperDroplets, SBM, MoistNoCondensation	None
erf.moisture_tight_coupling	If true, advance microphysics after every slow step in the dycore; otherwise, update after the dycore has been advanced at each timestep	Boolean	false
erf.morrison_ndcnst	Constant cloud-droplet number concentration for Morrison when constant droplet number is active	Positive real (cm^-3)	250 (cm^-3)
wdm6.hail_opt	Graupel/hail regime selector for WDM6: 0 = graupel regime, 1 = hail regime	0, 1	0
wdm6.ccn0	Background CCN number concentration for WDM6	Positive real (m^-3)	100.0e6 (m^-3)
erf.use_morr_cpp_answer	Morrison implementation: true = native C++, false = Fortran bridge. Must be left true unless ERF is built with USE_MORR_FORT=TRUE (GNU Make) or ERF_ENABLE_MORR_FORT=ON (CMake)	Boolean	true
erf.use_wsm6_cpp_answer	WSM6 implementation: true = native C++, false = Fortran bridge. Read only when ERF is built with USE_WSM6_FORT=TRUE (GNU Make) or ERF_ENABLE_WSM6_FORT=ON (CMake); otherwise ignored and native C++ always runs	Boolean	false
erf.use_wdm6_cpp_answer	WDM6 implementation: true = native C++, false = Fortran bridge. Read only when ERF is built with USE_WDM6_FORT=TRUE (GNU Make) or ERF_ENABLE_WDM6_FORT=ON (CMake); otherwise ignored and native C++ always runs	Boolean	false
erf.microphysics_debug	verbosity of the WSM6 and WDM6 microphysics debug output; values outside the range are clamped into it	0, 1, 2	0
erf.micro_diag_target_column	(i,j) column at which the WSM6 and WDM6 per-column microphysics diagnostics are collected	2 Integers	None
erf.micro_diag_mode	which WSM6 microphysics diagnostics are emitted; forensic and both enable the per-process forensic output, matched case-insensitively. Read only in a build with the WSM6 Fortran bridge enabled	canonical, forensic, both	canonical
erf.micro_diag_tags	tags selecting which WSM6 forensic diagnostics are emitted	List of Strings	standing
erf.micro_diag_expr	expressions evaluated for the WSM6 forensic diagnostics	List of Strings	standing
erf.micro_diag_store	which WSM6 forensic diagnostic quantities are stored	List of Strings	standing

SBM inputs

The inputs below are read only when erf.moisture_model = SBM. They configure the current single-level liquid-spectrum advection capability; see Spectral-Bin Microphysics (SBM) for its scientific representation and execution restrictions.

Parameter	Definition	Acceptable values	Default
erf.sbm_zero_transport_fixture	Obsolete switch from an earlier infrastructure-only test mode. Omit it from new input files; an explicitly true value is rejected.	Boolean; omit or use false	false
erf.sbm_nbins	Number of liquid spectral bins when explicit sbm_edges are not supplied. Explicit edges determine the effective bin count.	Integer \(\ge 2\)	4
erf.sbm_moment_mode	Spectral moments stored per bin. 1 stores liquid-water mass; 2 stores liquid-water mass and droplet number.	1 or 2	1
erf.sbm_cloud_rain_split	Interior bin index separating projected cloud water from projected rain water. Bins below the index contribute to qc and bins at or above it contribute to qr.	Integer satisfying \(0 < s < N_{\mathrm{bins}}\)	N_bins / 2 using integer division
erf.sbm_edges	Spectral bin edges in individual-particle liquid-water mass [kg]. Values must be finite, nonnegative, strictly increasing, and numerically well separated. When supplied, the array length determines the number of bins.	List of \(N_{\mathrm{bins}}+1\) real values	Log-spaced from \(10^{-18}\) to \(10^{-12}\) kg
erf.sbm_pivots	Representative particle mass [kg] for each bin. Each pivot must be finite, positive, and lie inside its bin. With explicit edges and no pivots, ERF uses geometric-mean pivots.	List of \(N_{\mathrm{bins}}\) positive real values	Geometric mean of adjacent edges
erf.sbm_fixture_initial_state	Spatially uniform authoritative spectral state. A 1M state contains all bin mass densities [kg m^-3]. A 2M state contains all mass densities followed by all number densities [m^-3]. Two-moment states must satisfy the bin realizability constraints.	\(N_{\mathrm{bins}}\) values for 1M or \(2N_{\mathrm{bins}}\) values for 2M	All zero

Note

erf.sbm_pivots is meaningful as a user input only when explicit erf.sbm_edges are also supplied. If edges are omitted, ERF generates both the default edges and their pivots.

If an explicit first bin begins at zero, its geometric-mean pivot is also zero and is invalid because SBM requires a positive pivot. Supply an explicit positive pivot inside that bin.

The automatically generated spectral grid and the example initial states are qualification defaults rather than recommended atmospheric discretizations. See Spectral-Bin Microphysics (SBM) for the full interpretation of these inputs.

Radiation

ERF offers two radiation model options: the RRTMGP library for full radiative transfer calculations, and a two-stream radiation model for idealized and intermediate-complexity studies. This section describes both models and their runtime configuration.

RRTMGP Radiation Model

ERF allows for radiative heating computations with the RRTMGP library. If building with cmake, the following flags must be enabled: -DERF_ENABLE_RRTMGP:BOOL=ON, -DERF_ENABLE_NETCDF:BOOL=ON, and -DERF_ENABLE_HDF5:BOOL=ON; see ERF/Build/cmake_with_radiation.sh.

If building with gmake, set USE_RRTMGP = TRUE and USE_NETCDF = TRUE in the GNUmakefile.

Notes

• A rule of thumb for the radiation update frequency is 1 min per km of grid spacing (e.g., every 10 min on a 10-km grid)
• For idealized studies, constant latitude/longitude may be specified through erf.rad_cons_lat

  and erf.rad_cons_lon.
• Multilevel/AMR with WRF initialization: When initializing multilevel simulations from WRF input files

  (erf.init_type = WRFInput), radiation computations depend on the vertical extent of each refinement level.

  Finer levels that extend to the model top (or match the vertical extent of level 0) compute radiation normally.

  For finer levels that do not extend to the same height as level 0, heating rates and radiation fluxes are

  interpolated from the parent coarse level rather than computed directly, since the radiative transfer solver

  requires a complete atmospheric column. ERF automatically detects this configuration and applies the appropriate

  method. Full radiation calculations on such partial-column refinement levels are subject to ongoing development work.

List of Parameters

Parameter	Definition	Acceptable Values	Default / Notes
erf.radiation_model	which radiation model to use; Simple is a prescribed cooling/heating profile with no radiative transfer, RRTMGP is the full radiative transfer solver, TwoStream the gray two-stream solver (see below)	None, RRTMGP, Simple, TwoStream	None
erf.rad_nvar	Size of block memory allocation	Integer > 0	12
erf.rad_t_sfc	Absolute surface temperature [K] where no land-surface model or surface layer supplies one	Real > 0	Required (RRTMGP and TwoStream)
erf.rad_freq_in_steps	Radiation update frequency (steps)	Integer >= 1	1
erf.rad_ncol_chunk	Columns per RRTMGP kernel launch. Controls peak GPU memory by processing radiation in batches of this size.	Integer >= 1	1024. Lower values reduce peak GPU memory; higher values reduce kernel launch overhead.
erf.rad_write_fluxes	Write radiation fluxes to plotfiles	Boolean	false
erf.rad_do_subcol_sampling	Enable MCICA subcolumn sampling	Boolean	true
erf.rad_orbital_year	Fixed orbital year for zenith calcs	Integer	< 0 uses timestamp year
erf.rad_orbital_eccentricity	Override orbital eccentricity	Real	< 0 uses computed value
erf.rad_orbital_obliquity	Override orbital obliquity [degrees]	Real	< 0 uses computed value
erf.rad_orbital_mvelp	Override mean longitude of perihelion [degrees]	Real	< 0 uses computed value
erf.rad_cons_lat	Constant latitude [degrees N] for idealized cases (RRTMGP and TwoStream)	Real	39.809860
erf.rad_cons_lon	Constant longitude [degrees E] for idealized cases (RRTMGP and TwoStream)	Real	-98.555183
erf.fixed_total_solar_irradiance	Fixed total solar irradiance (TOA) [W/m^2] (RRTMGP and TwoStream)	Real >= 0	< 0 disables: 1360.9 W/m^2 times the Earth-Sun factor of the date
erf.fixed_solar_zenith_angle	Cosine of the solar zenith angle (mu0), applied to every column (RRTMGP and TwoStream)	Real in (0, 1]	<= 0 disables: the sun follows start_datetime
erf.co2vmr	CO2 volume mixing ratio	Real	388.717e-6
erf.o3vmr	O3 volume mixing ratio profile	Real or list	From dataset if unset
erf.n2ovmr	N2O volume mixing ratio	Real	323.141e-9
erf.covmr	CO volume mixing ratio	Real	1.0e-7
erf.ch4vmr	CH4 volume mixing ratio	Real	1807.851e-9
erf.o2vmr	O2 volume mixing ratio	Real	0.209448
erf.n2vmr	N2 volume mixing ratio	Real	0.7906
erf.rad_do_aerosol	Enable aerosol forcing in radiation	Boolean	true
erf.rad_extra_clnclrsky_diag	Extra clean and clear-sky diagnostics	Boolean	false
erf.rad_extra_clnsky_diag	Extra clean-sky diagnostics	Boolean	false
erf.rrtmgp_file_path	Path to RRTMGP data files	String	“.”
erf.rrtmgp_coeffs_sw	Shortwave k-distribution file	String	rrtmgp-data-sw-g224-2018-12-04.nc
erf.rrtmgp_coeffs_lw	Longwave k-distribution file	String	rrtmgp-data-lw-g256-2018-12-04.nc
erf.rrtmgp_cloud_optics_sw	Shortwave cloud optics file	String	rrtmgp-cloud-optics-coeffs-sw.nc
erf.rrtmgp_cloud_optics_lw	Longwave cloud optics file	String	rrtmgp-cloud-optics-coeffs-lw.nc
erf.four_stream_radiation	use the four-stream radiation approximation	Boolean	false

Notes

• erf.fixed_solar_zenith_angle is passed directly as mu0 (cosine of the zenith angle).

• If erf.rad_orbital_year is negative, the orbital year is taken from the simulation timestamp. This is keyed off the value itself, not off whether the input was specified.

• When orbital parameters are negative, values are computed from the orbital year. Each of erf.rad_orbital_eccentricity, erf.rad_orbital_obliquity and erf.rad_orbital_mvelp is honored independently, so specifying one does not change how the others are obtained.

The lookup data may be downloaded as a package from here. The k-distribution files are also shipped with the RRTMGP submodule in Submodules/RRTMGP/rrtmgp/data, and the cloud optics files in Submodules/RRTMGP/extensions/cloud_optics.

All four files are expected in the single directory named by erf.rrtmgp_file_path, which is resolved relative to the run directory (not to the location of the inputs file). ERF checks for them while constructing the radiation interface and aborts with a message listing the directory and any missing file, so a mis-set path is reported at startup rather than as a netCDF “No such file or directory” error.

Note

Using RRTMGP requires USE_RRTMGP=TRUE at build time. See Building ERF for build instructions.

Two-Stream Radiation Model

The two-stream radiation model is a simplified but physically-consistent radiative transfer solver suitable for idealized and process studies. It includes Beer-Lambert shortwave direct-beam attenuation, Meador-Weaver (1980) two-stream diffuse/scattering approximation, gray-gas longwave two-stream (Toon et al. 1989), prescribed and prognostic cloud optical depth, bulk aerosol/turbidity effects, time-varying solar geometry based on astronomical calculations, heterogeneous/LSM-coupled surface albedo and emissivity, dynamic moisture-dependent optical depth, PBL coupling, and an optional Simplified Surface Energy Balance (SEB) module (diagnostic + prognostic force-restore) for surface temperature and moisture evolution. Select this model via erf.radiation_model = TwoStream; the other values are None, RRTMGP and Simple, so exactly one radiation model runs.

The model runs on a refined hierarchy. A level that carries complete atmospheric columns sweeps them itself; a level whose grids stop short of the domain top or bottom – a nested patch – has its heating rates and fluxes interpolated from its parent, as they are for RRTMGP. Set amr.refine_whole_domain_dir = 2 if you would rather every refinement patch span \(z\) and be solved on its own. The requirement is per box – the sweep needs a whole column inside one box – so a level tagged at different heights in different horizontal regions is interpolated too, not just one that stops below the domain top. The only refusal is on level 0, which has no parent to interpolate from: a box there that does not span \(z\) means grids decomposed in the vertical, which ERF’s default amr.no_box_split_dir = 2 already prevents. The surface energy balance runs on every level. erf.radiation.seb_prognostic_enable – which evolves the surface temperature that the longwave boundary condition reads – may be combined with amr.max_level > 0: a new level’s surface state is interpolated from its parent, the fine levels’ state is averaged down after they advance (under erf.coupling_type = TwoWay), and a regrid keeps what the surface had reached. The average-down is skipped for a level whose boxes do not span the domain in \(z\), since such a level takes its radiation from its parent and never evolves a surface of its own. A fine level therefore starts from its parent’s surface rather than resolving more surface structure than the coarse grid did. The fields are written with the 2D plotfile variables seb_t_sfc and seb_q_sfc.

The balance removes the sensible and latent heat fluxes the zlo surface layer puts into the air (erf.radiation.seb_turbulent_flux_source = surface_layer, the default), where no land-surface model supplies them; seb_turbulent_flux_source = defaults uses the constants seb_hfx_default and seb_lh_default instead. The fluxes it used are written as seb_hfx and seb_lh. With erf.radiation.seb_surface_layer_uses_skin = true the coupling runs both ways: the surface layer also takes its land surface temperature from the balance’s skin, so the heat flux it computes responds to the skin.

Two-Stream Radiation Model Parameters

The sun, the site and the surface temperature are set with the inputs the RRTMGP interface reads (see the table above): erf.fixed_solar_zenith_angle (the cosine of the zenith angle; leave it unset and the sun follows start_datetime over each column, at erf.rad_cons_lat and erf.rad_cons_lon or at the grid’s own latitude and longitude fields), erf.fixed_total_solar_irradiance (leave it unset for 1360.9 W/m² scaled by the Earth-Sun distance factor of the date, or the unscaled 1360.9 W/m² when the zenith angle is fixed and no start date is known), erf.rad_t_sfc (required; with a land-surface model or a surface layer present it is the initial value of the prognostic surface temperature when the surface energy balance evolves one and unused otherwise, and the surface layer’s potential temperature is converted with the Exner function at the physical surface pressure diagnosed from the lowest atmospheric cell), start_datetime and the erf.rad_orbital_* overrides. A deck that still sets one of the former two-stream-only keys (erf.radiation.solar_zenith, erf.radiation.S0, erf.radiation.surface_temp_k, erf.radiation.latitude_deg, erf.radiation.longitude_deg, erf.radiation.day_of_year, erf.radiation.time_zone_offset_hours, erf.radiation.solar_geometry_dynamic_enable, erf.radiation.earth_sun_distance_enable) stops at start-up with the replacement named. erf.rad_freq_in_steps is not read: the two-stream model runs every step.

Parameter	Definition	Acceptable Values	Default
Shortwave/Longwave Base Parameters
erf.radiation.sw_enabled	Enable shortwave (solar) radiation computation	Boolean	true
erf.radiation.lw_enabled	Enable longwave (thermal) radiation computation	Boolean	true
erf.radiation.tau_per_layer	Shortwave optical depth per layer (Beer-Lambert direct beam); uniform for all layers	Real >= 0	0.05
erf.radiation.tau_lw_per_layer	Longwave optical depth per layer (gray-gas two-stream); uniform for all layers	Real >= 0	1.0
erf.radiation.tau_model	Optical depth model: per_layer (fixed tau per layer) or mass (from the layer mass path in both bands; see the sw_k*/lw_k* coefficients)	“per_layer” or “mass”	“per_layer”
erf.radiation.sw_kabs_dry	Mass model: dry-air gray SW absorption coefficient [m^2/kg]	Real >= 0	4.0e-6
erf.radiation.sw_kscat_dry	Mass model: dry-air (Rayleigh) SW scattering coefficient [m^2/kg], omega = 1, g = 0	Real >= 0	3.0e-6
erf.radiation.sw_kabs_vapor	Mass model: water-vapor gray SW absorption coefficient [m^2/kg]	Real >= 0	4.0e-3
erf.radiation.sw_kext_cloud	Mass model: cloud-water SW extinction coefficient [m^2/kg] (~1500 / r_eff[um]; 150 for r_eff = 10 um)	Real >= 0	150.0
erf.radiation.sw_cloud_omega	Mass model: cloud-water SW single-scattering albedo	Real [0,1]	0.9999
erf.radiation.sw_cloud_g	Mass model: cloud-water SW asymmetry factor	Real [-1,1]	0.85
erf.radiation.lw_mass_absorption_enable	Gray LW optical depth from the layer mass path, rho dz (k_dry + k_vapor qv + k_cloud qc), instead of tau_lw_per_layer	Boolean	false
erf.radiation.lw_kabs_dry	Dry-air gray LW mass absorption coefficient [m^2/kg]	Real >= 0	1.0e-4
erf.radiation.lw_kabs_vapor	Water-vapor gray LW mass absorption coefficient [m^2/kg]	Real >= 0	0.1
erf.radiation.lw_kabs_cloud	Cloud-water LW mass absorption coefficient [m^2/kg] (Stephens 1978 emissivity, 0.158 m^2/g)	Real >= 0	158.0
Cloud Optical Depth Parameters
erf.radiation.tau_profile_type	Cloud optical depth profile: constant (uniform) or cloud_layer (height-varying)	“constant” or “cloud_layer”	“constant”
erf.radiation.cloud_base_height_m	Cloud layer base height [m]; only used if tau_profile_type = cloud_layer	Real	500.0
erf.radiation.cloud_top_height_m	Cloud layer top height [m]; must be >= cloud_base_height_m	Real	1000.0
erf.radiation.cloud_tau_per_layer	Additional cloud optical depth per layer (added on top of tau_per_layer/tau_lw_per_layer within cloud layer)	Real.	0.5
erf.radiation.cloud_fraction	Cloud fraction [0,1] for blending clear/cloudy columns	Real [0,1]	0.0
Scattering Parameters
erf.radiation.single_scattering_albedo	Clear-sky single-scattering albedo [0,1] for SW diffuse	Real [0,1]	0.0
erf.radiation.asymmetry_factor	Clear-sky scattering asymmetry factor [-1,1]; 0=isotropic	Real [-1,1]	0.0
erf.radiation.cloud_single_scattering_albedo	Cloud single-scattering albedo [0,1]; used instead of single_scattering_albedo in cloud layers	Real [0,1]	0.0
erf.radiation.cloud_asymmetry_factor	Cloud scattering asymmetry factor [-1,1]; used instead of asymmetry_factor in cloud layers	Real [-1,1]	0.0
Surface Heterogeneity/Fallback Parameters
erf.radiation.surface_albedo_sw	Shortwave surface albedo [0,1] fallback (when LSM/hetero fields unavailable)	Real [0,1]	0.3
erf.radiation.surface_albedo_sw_diffuse	Shortwave surface albedo for diffuse light [0,1]; negative uses surface_albedo_sw for both	Real	-1.0
erf.radiation.surface_emissivity_lw	Longwave surface emissivity [0,1] fallback	Real [0,1]	0.99
Dynamic Optical Depth Parameters
erf.radiation.tau_sw_dynamic_enable	Enable dynamic SW optical depth diagnosis from qv/qc	Boolean	false
erf.radiation.tau_lw_dynamic_enable	Enable dynamic LW optical depth diagnosis from qv/qc	Boolean	false
erf.radiation.tau_sw_coeff_qv	Coefficient for water vapor contribution to SW tau	Real	0.0
erf.radiation.tau_sw_coeff_qc	Coefficient for cloud liquid water contribution to SW tau	Real	0.0
erf.radiation.tau_lw_coeff_qv	Coefficient for water vapor contribution to LW tau	Real	0.0
erf.radiation.tau_lw_coeff_qc	Coefficient for cloud liquid water contribution to LW tau	Real	0.0
Prognostic Cloud Fraction Parameters
erf.radiation.cloud_fraction_prog_enable	Enable prognostic cloud fraction diagnosis from RH/qc	Boolean	false
erf.radiation.cloud_fraction_rh_min	Minimum RH threshold for cloud fraction ramp [0,1]	Real [0,1]	0.0
erf.radiation.cloud_fraction_rh_max	Maximum RH threshold for cloud fraction saturation [0,1]	Real [0,1]	1.0
erf.radiation.cloud_fraction_qc_scale	Cloud water [kg/kg] at which the qc term alone saturates	Real > 0	1.0e-3
Aerosol/Turbidity Parameters
erf.radiation.aerosol_enable	Enable prescribed bulk aerosol optical depth	Boolean	false
erf.radiation.aerosol_profile_type	Aerosol profile type: constant, exponential, or table	“constant”, “exponential”, “table”	“constant”
erf.radiation.aerosol_tau_per_layer	Constant aerosol optical depth per layer (for Constantprofile)	Real	0.0
erf.radiation.aerosol_tau_surface	Total-column aerosol optical depth at surface (for Exponential profile)	Real	0.0
erf.radiation.aerosol_scale_height_m	Scale height for exponential aerosol decay [m]	Real	2000.0
Simplified Surface Energy Balance (SEB) Params
erf.radiation.seb_enable	Master switch for SEB infrastructure	Boolean	false
erf.radiation.seb_use_radiation_fluxes	Take the SEB net surface SW and LW fluxes from the two-stream sweep where the LSM does not supply them	Boolean	false
erf.radiation.seb_turbulent_flux_source	Source of the SEB sensible (H) and latent (LE) heat fluxes where no land-surface model supplies them: surface_layer takes the fluxes the zlo surface layer applies to the air (as sensible_heat_flux and latent_heat_flux), so the ground loses what the air gains; defaults takes seb_hfx_default and seb_lh_default. surface_layer uses the surface layer whenever its flux field exists: a zlo surface layer with any diffusion or closure, not on EB terrain, and for LE a moisture model. An adiabatic surface layer has a zero flux, so H = 0 there; ERF warns when a nonzero default is replaced. With erf.use_rotate_surface_flux only the vertical-face part (cos(slope) of the flux) is removed, with a warning	surface_layer, defaults (case-insensitive, underscores ignored)	surface_layer
erf.radiation.seb_surface_layer_uses_skin	Two-way coupling: the zlo surface layer takes its land surface temperature from the SEB skin T_s (as a potential temperature), so its heat flux responds to T_s. Needs seb_prognostic_enable, seb_turbulent_flux_source = surface_layer and a surface layer in surface-temperature mode (most.*_surf_temp, no surf_heating_rate), not on EB terrain, without erf.use_rotate_surface_flux, with no land or surface model; each is checked at start-up	Boolean	false
erf.radiation.seb_surface_layer_uses_moisture	Two-way coupling of moisture as well: the zlo surface layer takes its land surface mixing ratio from the balance’s soil water q_s, and the balance drains q_s by the LE it removes. Without seb_soil_type it is beta q_sat(T_s) + (1 - beta) q_air, beta the soil-water factor linear from seb_soil_moisture_wilt to seb_soil_moisture_fc. With seb_soil_type the bare soil evaporates from its pore air (Noah-MP’s relative humidity times q_sat) through Noah-MP’s bare-soil resistance, and with seb_vegetation_type the canopy through its own, each in series with the aerodynamic one. Needs seb_surface_layer_uses_skin, a moisture model and erf.most.surf_moist; each is checked at start-up	Boolean	false
erf.radiation.seb_soil_moisture_wilt	Wilting point [m³/m³]: at or below it the soil-water factor is 0, so no transpiration and, without seb_soil_type, no evaporation (with one, the bare soil’s nearly dry pore air keeps its evaporation near zero). Used only with seb_surface_layer_uses_moisture; giving it otherwise stops at start-up	Real, 0 <= wilt < fc	0.066 (Noah-MP loam)
erf.radiation.seb_soil_moisture_fc	Field capacity [m³/m³]: at or above it the soil-water factor is 1 (potential evaporation without seb_soil_type). Used only with seb_surface_layer_uses_moisture; giving it otherwise stops at start-up	Real, wilt < fc <= 1	0.329 (Noah-MP loam)
erf.radiation.seb_soil_type	Noah-MP soil category (STAS, as in NoahmpTable.TBL; ERF_NoahMPSoilTable.H). Sets the wilting point and field capacity (WLTSMC, REFSMC; giving either of those as well stops at start-up), seb_surface_heat_capacity from the soil’s heat capacity and conductivity at seb_q_sfc_default unless that is given, with seb_surface_layer_uses_moisture the bare-soil resistance and pore-air humidity (vegetation or not), and with seb_surface_layer_uses_skin the surface layer’s land roughness, f_veg Z0MVT + (1 - f_veg) Z0SOIL, unless erf.most.z0 is given. Not 14 (water)	Integer 1-19, 0 = unset	0
erf.radiation.seb_vegetation_type	Noah-MP land-use category (modified IGBP MODIS; ERF_NoahMPVegetationTable.H). The vegetated fraction transpires through Noah’s big-leaf Jarvis canopy resistance on Noah-MP’s RS, RGL, HS, TOPT, RSMAX and the leaf area index; the rest evaporates through Noah-MP’s bare-soil resistance. Needs seb_surface_layer_uses_moisture and seb_soil_type. 15, 16 and 17 (snow and ice, barren, water) have no vegetation in the table and stop at start-up: leave it at 0 for bare land	Integer 1-20 but not 15-17, 0 = unset	0
erf.radiation.seb_vegetation_fraction	Vegetated fraction of the surface. Used only with seb_vegetation_type; giving it otherwise stops at start-up	Real [0,1]	1.0
erf.radiation.seb_leaf_area_index	Leaf area index [m²/m²] of the vegetation, fixed for the run. Default: the category’s monthly values interpolated to start_datetime as Noah-MP does (shifted half a year when erf.rad_cons_lat < 0); without start_datetime it must be given. Used only with seb_vegetation_type; giving it otherwise stops at start-up	Real >= 0	from the table
erf.radiation.seb_diagnostic_enable	Enable diagnostic SEB residual computation	Boolean	false
erf.radiation.seb_prognostic_enable	Enable prognostic SEB surface T_s and q_s evolution (force-restore); runs on every level	Boolean	false
erf.radiation.seb_sw_flux_default	Fallback SEB net shortwave flux [W/m²]	Real	0.0
erf.radiation.seb_lw_flux_default	Fallback SEB net longwave flux [W/m²]	Real	0.0
erf.radiation.seb_hfx_default	Fallback SEB sensible heat flux [W/m²]; see seb_turbulent_flux_source	Real	0.0
erf.radiation.seb_lh_default	Fallback SEB latent heat flux [W/m²]; see seb_turbulent_flux_source	Real	0.0
erf.radiation.seb_grdflx_default	Fallback SEB ground heat flux [W/m²]. With seb_prognostic_enable leave it at 0: the force-restore restoring term already carries the ground heat flux, so a nonzero value counts it twice (a warning says so)	Real	0.0
erf.radiation.seb_q_sfc_default	Fallback SEB surface moisture, and the prognostic q_s’s initial value: with seb_prognostic_enable a volumetric soil water content [m³/m³] of the top seb_moisture_layer_depth_m	Real [0,1]	0.0
erf.radiation.seb_t_deep_default	Fallback SEB deep soil temperature [K]	Real	300.0
erf.radiation.seb_q_deep_default	Deep soil moisture q_s restores to, in q_s’s units. With seb_surface_layer_uses_moisture a NOTE at start-up flags a value below the wilting point (the default 0 dries the soil over seb_moisture_restore_timescale_s)	Real [0,1]	0.0
erf.radiation.seb_surface_heat_capacity	Effective surface heat capacity [J/(m²·K)]. With seb_soil_type and not given: sqrt(lambda c tau / pi) / 2 of the soil’s conductivity and heat capacity at seb_q_sfc_default over seb_restore_timescale_s (Deardorff)	Real > 0; stops at start-up if not	2.0e4
erf.radiation.seb_restore_timescale_s	Force-restore timescale for surface temperature [s]	Real > 0; stops at start-up if not	86400.0 (1 day)
erf.radiation.seb_moisture_layer_depth_m	Effective surface moisture layer depth [m]	Real > 0; stops at start-up if not	0.1
erf.radiation.seb_moisture_restore_timescale_s	Force-restore timescale for surface moisture [s]	Real > 0; stops at start-up if not	86400.0 (1 day)
erf.radiation.seb_prognostic_t_min_k	Minimum clamping bound for prognostic surface T [K]	Real	200.0
erf.radiation.seb_prognostic_t_max_k	Maximum clamping bound for prognostic surface T [K]	Real	340.0
erf.radiation.seb_prognostic_q_min	Minimum clamping bound for prognostic surface moisture q_s (m³/m³ with seb_prognostic_enable)	Real [0,1]	0.0
erf.radiation.seb_prognostic_q_max	Maximum clamping bound for prognostic surface moisture q_s (m³/m³ with seb_prognostic_enable)	Real [0,1]	1.0
Diagnostics Control Parameters
erf.radiation.v	Verbosity level for radiation debug output (0=off)	Integer	0
erf.radiation.diag_file	Output file path for radiation diagnostics CSV	String	“radiation_diag .dat”
erf.radiation.diag_enable	Master switch for radiation diagnostics emission; set true to write the CSV and the stdout block	Boolean	false
erf.radiation.diag_stdout_enable	Enable human-readable stdout diagnostics block	Boolean	true
erf.radiation.diag_tagged_enable	Enable tagged [RAD][…] debug lines	Boolean	true
erf.radiation.diag_regtest_line_enable	Enable RADIATION_DIAG: regtest-parsing line	Boolean	true
erf.radiation.diag_csv_enable	Enable CSV file append behavior for diagnostics	Boolean	true
erf.radiation.diag_callsite_mode	Call-site filtering mode: “both” (default), “pre_only”, or “post_only”	“both”, “pre_only”, “post_only”	“both”
erf.radiation.diag_dedup_tol	Tolerance for time equality in duplicate guard [s]	Real	1.0e-12

SHOC

ERF provides two SHOC implementations. Select the ERF-native implementation with erf.pbl_type = NATIVE_SHOC. Select the optional EAMxx implementation with erf.pbl_type = EAMXX_SHOC. The legacy value SHOC is deprecated and is interpreted as EAMXX_SHOC; it does not select native SHOC.

Both SHOC implementations use the erf.shoc namespace for closure tuning. Native SHOC also has transport and native-only numerical controls. EAMxx SHOC has a small number of interface-only controls. See SHOC PBL Model for the model description, coupling restrictions, transport behavior, and diagnostic output.

Shared SHOC closure inputs

The following option names are read by both native SHOC and EAMxx SHOC. The two implementations are separate code paths, so identical input values do not imply bit-for-bit identical calculations.

Parameter	Definition	Acceptable Values	Default
erf.shoc.lambda_low	Lower bound for the SHOC stability-correction coefficient	Real > 0	0.001
erf.shoc.lambda_high	Upper bound for the SHOC stability-correction coefficient	Real >= lambda_low	0.04
erf.shoc.lambda_slope	Slope used to vary the stability-correction coefficient	Real	2.65
erf.shoc.lambda_thresh	Threshold used in the stability-correction calculation	Real	0.02
erf.shoc.thl2tune	Liquid-water potential-temperature variance tuning factor	Real	1.0
erf.shoc.qw2tune	Total-water variance tuning factor	Real	1.0
erf.shoc.qwthl2tune	Total-water / liquid-water-potential-temperature covariance tuning factor	Real	1.0
erf.shoc.w2tune	Vertical-velocity variance tuning factor	Real	1.0
erf.shoc.length_fac	Turbulent length-scale tuning factor	Real > 0	0.5
erf.shoc.c_diag_3rd_mom	Diagnostic third-moment vertical-velocity damping coefficient; the default 7.0 is the tested baseline	Real	7.0
erf.shoc.coeff_kh	Scalar / heat diffusivity tuning coefficient	Real >= 0	0.1
erf.shoc.coeff_km	Momentum diffusivity tuning coefficient	Real >= 0	0.1
erf.shoc.shoc_1p5tke	Use the reduced 1.5-order TKE form instead of the higher-order SHOC moment form	true / false	false
erf.shoc.extra_shoc_diags	Enable additional SHOC diagnostic calculations; plot variables must still be requested explicitly	true / false	false

Warning

For Native SHOC, do not set erf.shoc.c_diag_3rd_mom to zero. The Native third-moment closure contains factors proportional to the inverse of this coefficient. The default value 7.0 is the tested baseline. Changes to this closure coefficient should be treated as sensitivity experiments rather than routine configuration.

Native SHOC inputs

The following controls apply to erf.pbl_type = NATIVE_SHOC.

Parameter	Definition	Acceptable Values	Default
erf.shoc.transport_mode	Selects how native SHOC transports thermodynamic variables, moisture/cloud state, and TKE	state_update	state_update
erf.shoc.momentum_transport	Selects how native SHOC applies horizontal-momentum transport	none, state_update	state_update
erf.shoc.top_taper_depth	Depth below the model top over which native SHOC smoothly tapers TKE/diffusivity and higher-order turbulence quantities [m]; zero disables the taper	Real >= 0	0.0
erf.shoc.top_taper_min_factor	Multiplicative factor at the model top when the native top taper is enabled; the factor reaches 1 below the taper layer	Real in [0, 1]	0.0
erf.shoc.signed_tke_production	If false, clip the sum of native SHOC shear and buoyancy production at zero before dissipation; if true, retain the signed production sum	true / false	false
erf.shoc.debug_summary	Print a synchronized min/max summary after each native SHOC advance; intended for debugging rather than routine production	true / false	false

Native SHOC uses state_update for scalar/cloud/TKE transport. Use erf.shoc.momentum_transport = state_update for the normal/default momentum path, or none to disable Native SHOC horizontal-momentum transport. The former host_diffusion values for either selector are removed and fail at startup with migration guidance. Native state_update rejects moisture layouts containing cloud-water or cloud-ice number concentrations because a number closure has not yet been implemented.

Native SHOC pblh is reported in metres above local ground (AGL).

The old value erf.shoc.transport_mode = tendencies is no longer accepted. Use state_update instead.

Native SHOC debugging controls

The following controls are intended for diagnosis and regression testing rather than routine production runs. The debug_disable_* switches deliberately disable pieces of the coupled state update and are used by the SHOC mutation tests to verify that those updates affect the solution.

Only controls listed here are part of the supported Native-SHOC debugging interface. Some historical or development erf.shoc keys may still be parsed internally but do not currently alter Native SHOC.

Parameter	Definition	Acceptable Values	Default
erf.shoc.debug_bad_column	Detect and report columns whose tendencies or stratification exceed the thresholds below	true / false	false
erf.shoc.debug_bad_column_abort	Abort when such a column is found, rather than only reporting it	true / false	true
erf.shoc.debug_bad_column_max_reports	Maximum number of bad-column reports emitted; must be positive	Integer > 0	8
erf.shoc.debug_bad_column_theta_tend_threshold	Potential-temperature tendency above which a column is flagged; must be positive	Real > 0	10.0
erf.shoc.debug_bad_column_q_tend_threshold	Moisture tendency above which a column is flagged; must be positive	Real > 0	1.0e-2
erf.shoc.debug_bad_column_brunt_threshold	Magnitude of the squared Brunt–Väisälä frequency, \(|N^2|\) [s-2], above which a column is flagged; must be positive	Real > 0	1.0
erf.shoc.debug_bad_column_min_dz	Layer thickness [m] below which a column is flagged; must be positive	Real > 0	1.0
erf.shoc.debug_bad_column_scalar_moment_threshold	Scalar higher-moment magnitude above which a column is flagged; must be positive	Real > 0	1.0e4
erf.shoc.debug_disable_pdf_cloud_increment	Skip the PDF cloud increment. Debugging only	true / false	false
erf.shoc.debug_disable_theta_state_update	Skip the potential-temperature state update. Debugging only	true / false	false
erf.shoc.debug_disable_moisture_state_update	Skip the moisture state update. Debugging only	true / false	false
erf.shoc.debug_disable_tke_state_update	Skip the TKE state update. Debugging only	true / false	false

Each threshold is validated on read, and a non-positive value aborts the run with a message naming the input.

EAMxx SHOC interface inputs

The following controls have a verified runtime effect in the optional EAMXX_SHOC interface and are not native-SHOC controls.

Parameter	Definition	Acceptable Values	Default
erf.shoc.apply_tms	Apply the turbulent mountain stress contribution in the EAMxx SHOC interface	true / false	false
erf.shoc.check_flux_state	Run the EAMxx SHOC interface flux/state consistency check	true / false	false

Only options documented above are part of the supported SHOC user-facing runtime contract. Some historical or development erf.shoc keys may still be parsed internally but are intentionally not documented as active features.

Minimal native SHOC setup

A native SHOC run requires a surface-layer lower boundary:

zlo.type = "surface_layer"
erf.pbl_type = NATIVE_SHOC

The native transport defaults are:

erf.shoc.transport_mode = state_update
erf.shoc.momentum_transport = state_update

These two transport lines may be omitted when the defaults are desired.

Minimal EAMxx SHOC setup

The EAMxx SHOC path requires an executable built with the CMake option ERF_ENABLE_EAMXX_SHOC=ON. For example:

cmake -DERF_ENABLE_EAMXX_SHOC=ON ...

The corresponding runtime selection is:

zlo.type = "surface_layer"
erf.pbl_type = EAMXX_SHOC

Runtime Error Checking

Through AMReX functionality, ERF supports options to raise errors when NaNs, division by zero, and overflow errors are detected. These checks are activated at runtime using the input parameters below.

Note

When running on Macs using the Apple-Clang compilers with optimization (DEBUG = FALSE in the GNUmakefile), these checks may lead to false positives due to optimizations performed by the compiler and the flags should be turned off. It is still possible to run with these error checks with Apple-Clang debug builds.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.check_for_nans	Test solution for NaNs and abort if any are found	int	0
amrex.fpe_trap_invalid	Raise errors for NaNs	0 / 1	0
amrex.fpe_trap_zero	Raise errors for divide by zero	0 / 1	0
amrex.fpe_trap_overflow	Raise errors for overflow	0 / 1	0

Reproducibility

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.fix_random_seed	Use a fixed random seed for reproducible runs	0 or 1	0
erf.random_seed	Seed for the random number generator, offset by MPI rank; ignored if erf.fix_random_seed is 1	Integer >= 0	-1
erf.deterministic_ic_pert	Use index-keyed ABL initial- condition perturbations that are independent of MPI, box, and tile decomposition	0 or 1	0

Embedded Boundary (EB) Tuning

List of Parameters

Parameter	Definition	Acceptable Values	Default
eb2.small_volfrac	Volume-fraction threshold used to treat cells as effectively empty. With immersed forcing it is also the solid fraction below which the forcing treats a cell or face as fluid	Real > 0	1.0e-14; 0.005 with immersed forcing
erf.eb_boundary_type	condition imposed on the embedded boundary	SlipWall, NoSlipWall, SurfaceLayer	NoSlipWall
erf.eb_diff_constraint_x	apply the tangential-diffusion constraint on x-faces at the embedded boundary; read only when erf.eb_boundary_type = SlipWall	Boolean	false
erf.eb_diff_constraint_y	apply the tangential-diffusion constraint on y-faces at the embedded boundary; read only when erf.eb_boundary_type = SlipWall	Boolean	false
erf.eb_diff_constraint_z	apply the tangential-diffusion constraint on z-faces at the embedded boundary; read only when erf.eb_boundary_type = SlipWall	Boolean	false
eb2.geometry	which embedded-boundary shape to build; read only when erf.terrain_type is EB or ImmersedForcing	terrain, plane, box, sphere	terrain
eb2.plane_point	a point on the cutting plane. Read only when eb2.geometry = plane	3 Reals	0.0 0.0 0.0
eb2.plane_normal	normal of the cutting plane, pointing into the solid region. Read only when eb2.geometry = plane	3 Reals	0.0 0.0 -1.0
eb2.box_lo	low corner of the embedded box. Read only when eb2.geometry = box	3 Reals	0.0 0.0 0.0
eb2.box_hi	high corner of the embedded box. Read only when eb2.geometry = box	3 Reals	0.0 0.0 0.0
erf.buildings_stl_file	path to an STL file describing 3D building geometry, which is unioned with the terrain implicit function. Read only when eb2.geometry = terrain	String	None
erf.buildings_stl_scale	uniform scale factor applied to the STL coordinates. Read only when erf.buildings_stl_file is set	Real > 0	1.0
erf.buildings_stl_center	translation [m] applied to the STL coordinates after scaling. Read only when erf.buildings_stl_file is set	3 Reals	0.0 0.0 0.0
erf.buildings_stl_reverse_normal	flip the orientation of the STL triangle normals, for meshes whose normals point into the solid. Read only when erf.buildings_stl_file is set	0 or 1	0
erf.buildings_only	build the embedded boundary from the STL buildings alone, leaving the terrain surface out of the implicit function. Read only when eb2.geometry = terrain Setting it to true without erf.buildings_stl_file is an error	Boolean	true if no terrain surface is specified, false otherwise

STL-Based Building Geometry

When eb2.geometry = terrain (the default), the implicit function used to cut the mesh can include three-dimensional building geometry read from an STL triangle mesh. Unlike the height-field terrain representation, which stores a single surface height per \((x,y)\) location and therefore cannot represent an overhang or a vertical wall exactly, the STL representation resolves vertical walls, roof overhangs and other fully three-dimensional structures.

The STL file is named with erf.buildings_stl_file. ERF reads either binary or ASCII STL, applying erf.buildings_stl_scale to the coordinates, then translating by erf.buildings_stl_center, and flipping the triangle normals if erf.buildings_stl_reverse_normal is set. These three inputs are read only when erf.buildings_stl_file is present.

Note

These inputs use the erf prefix rather than eb2, because eb2 is AMReX’s own namespace and AMReX already reads eb2.stl_file, eb2.stl_scale, eb2.stl_center and eb2.stl_reverse_normal for its separate eb2.geometry = stl path. The ERF inputs described here are read only when eb2.geometry = terrain.

Which geometry is built depends on whether terrain is also requested:

• Terrain only (no erf.buildings_stl_file): the implicit function is the terrain height field, exactly as before.

• Terrain plus buildings (erf.buildings_stl_file set and a terrain surface specified): the terrain and building implicit functions are combined with a union, so a cell is solid if it lies below the terrain surface or inside a building.

• Buildings only (erf.buildings_stl_file set and no terrain surface specified): the terrain surface is not constructed and the STL mesh alone defines the embedded boundary. This is the natural choice for an urban case over flat ground, and it also keeps the embedded boundary from coinciding with the lower-\(z\) domain boundary, so the ground is governed by the zlo boundary condition rather than by erf.eb_boundary_type.

“A terrain surface is specified” means any of the ways ERF can be told about terrain: erf.terrain_file_name_nc, erf.terrain_file_name, erf.terrain_file_name_USGS, or prob.custom_terrain_type set to anything other than None. This is the same set of sources, in the same precedence order, that init_terrain_surface consults, so a case that would run with terrain on its own does not silently lose that terrain when an STL file is added.

You may also state the choice outright instead of relying on that inference, by setting erf.buildings_only. Setting it to false unions the buildings with the terrain surface even when no terrain input is given, which produces a flat ground plane at \(z = 0\); setting it to true without an erf.buildings_stl_file is an error.

ERF prints which of the three modes it selected, together with the STL file name and the scale, center and reverse-normal values, when it builds the EB geometry.

Internally the STL mesh is handled by the BuildingsIF implicit function (Source/EB/ERF_EBIFBuildings.H), which uses the AMReX STLtools infrastructure with bounding-volume-hierarchy acceleration. At construction it samples the signed distance to the mesh onto the finest-level grid, computing the samples in parallel across ranks and then replicating the result so that each rank can evaluate the implicit function locally, including on the GPU. Evaluation is a trilinear interpolation of that sampled field, so the building geometry is resolved at the finest level’s cell size; points outside the sampled region are treated as fluid. Very large or highly detailed meshes will therefore be limited by the mesh resolution rather than by the STL itself.

Fire Coupling

These inputs configure the atmosphere side of the fire coupling described in Fire-Atmosphere Coupling; they need a build with ERF_ENABLE_FIRE=ON (USE_FIRE = TRUE with GNU make). The erf.fire keys are read once at start-up by FireCouplingParams::read(), which stops the run on a value outside the range given here, naming the key; the three plotfile keys are read from erf with the other output keys. A fire engine reads its own inputs besides.

Parameter	Definition	Acceptable Values	Default
erf.fire.enable	Run a fire (needs a fire engine compiled in, see Fire-Atmosphere Coupling)	Boolean	false
erf.fire.engine	The fire engine behind the coupling, one of the engines compiled in (ERF_REGISTER_FIRE_ENGINE); required when several are; with none, setting it stops the run	String	the only one built
erf.fire.fire_debug	Print per-step coupling diagnostics	Boolean	false
erf.fire.grid_ratio	Fire cells per atmospheric cell in x and y; every x,y box length on the fire grid’s level must divide by it	Integer >= 1	5
erf.fire.anchor_level	AMR level whose grid the fire grid refines; -1 is the finest level at start-up. Above level 0 the level must keep its boxes (erf.regrid_int = -1) and cover one rectangle of full-height columns; a level below the finest prints a warning	-1, or 0 to the finest level	-1
erf.fire.coupling_type	Wind used by the fire and whether its heat is injected	“passive”, “lagged”, “synchronous”	“lagged”
erf.fire.heat_flux_alfg	E-folding height of the injected heat [m]	Real > 0	45.0
erf.fire.fire_atm_feedback	Multiplier on the injected fluxes; 0 is one-way coupling	Real >= 0	1.0
erf.fire.inject_latent	Inject the latent flux into the vapour equation when moisture is active	Boolean	true
erf.fire.source_mode	Replace the theta and vapour source slots or add to the rebuilt stage source. Left at the default with another theta source on the fire level (radiation, Rayleigh damping of T, custom forcing or subsidence, slow-step immersed forcing) the run stops: set it explicitly	“overwrite”, “add”	“overwrite”
erf.fire.heat_open_fraction	Place the injected heat by the open fraction and roof height the engine reports per column	Boolean	false
erf.fire.heat_tendency_density	Multiply the injected tendency by the air density (injects rho times the flux; for comparison with runs made in that form)	Boolean	false
erf.fire.heat_tendency_exner	Divide the rho theta tendency by the cell’s Exner function so the column enthalpy integrates to the fire flux; false (WRF-SFIRE’s form) injects Pi times the flux	Boolean	true
erf.fire.heat_profile	How the fire heat is placed in the column: “exponential” (e-folding erf.fire.heat_flux_alfg, WRF-SFIRE) or “bottom_cell” (all of it in the lowest cell, as LSFIRE)	String	exponential
erf.fire.smoke_enable	Inject the smoke tracer (needs erf.transport_scalar = true)	Boolean	false
erf.fire.smoke_emission_factor	Smoke mass per unit fuel burned [kg/kg]; needs erf.fire.smoke_enable = true (set without it the run stops, or warns when smoke_enable = false or erf.fire.enable = false is given)	Real >= 0	0.02
erf.fire.plot_file	Prefix of the engine’s fire plotfile	String	plt_fire_
erf.fire.plot_int	Steps between fire plotfiles; <= 0 disables. With neither this nor plot_per given, both take erf.plot_int_1 and erf.plot_per_1 (the old erf.fire_plot_* keys stop the run)	Integer	erf.plot_int_1
erf.fire.plot_per	Seconds between fire plotfiles; <= 0 disables	Real	erf.plot_per_1

Particles

ERF carries two particle containers. Tracer particles are configured with the inputs below; see Particles for worked examples. The super-droplet container, used by erf.moisture_model = SuperDroplets, has its own set of inputs under the super_droplets_moisture prefix, documented in Super-Droplets.

List of Parameters

Parameter	Definition	Acceptable Values	Default
particles.disable_plt	Disable particle plotfile output	Boolean	false
erf.use_tracer_particles	create the tracer particle container	Boolean	false
tracer_particles.initial_distribution_type	how the initial particle positions are chosen	box, uniform	box
tracer_particles.particle_box_lo	low corner of the region seeded with particles; read only when initial_distribution_type = box	3 Reals	domain low corner
tracer_particles.particle_box_hi	high corner of that region; read only when initial_distribution_type = box	3 Reals	domain high corner
tracer_particles.place_randomly_in_cells	place the particles at random positions within each cell rather than at fixed offsets	Boolean	false
tracer_particles.initial_particles_per_cell	number of particles created per cell	Integer > 0	1
tracer_particles.advect_with_flow	advect the particles with the resolved velocity field	Boolean	true
tracer_particles.advect_with_gravity	add a gravitational contribution to the particle motion	Boolean	false
tracer_particles.start_time	simulation time [s] at which the particles are introduced	Real	0.0
tracer_particles.stable_redistribute	use the stable (order-preserving) particle redistribution	Boolean	false
tracer_particles.verbose	verbosity of the particle container	Integer >= 0	0

Ensemble Initialization

When erf.is_init_for_ensemble is true, the initial state is perturbed with a spatially correlated random field so that each member of an ensemble starts from a slightly different state. In that case all of the ensemble.* parameters below must be set.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.is_init_for_ensemble	Perturb the initial state for an ensemble member	Boolean	false
ensemble.n_members	Number of ensemble members	Integer >= 2	must be set
ensemble.coarse_bckgnd_data_file	Coarse background data file interpolated onto the fine mesh to form the background state	String	must be set
ensemble.ens_pert_amplitude	Amplitude of the perturbation added to the background state	Real > 0	must be set
ensemble.ens_pert_correlated_radius	Spatial correlation radius of the perturbation	Real > 0	must be set

Solver Options in SolverChoice

This section is an index, not a second set of definitions. It lists the complete set of inputs read by SolverChoice in Source/DataStructs/ERF_DataStruct.H, which holds most of the algorithmic and physics-selection options for a run, grouped the way the code reads them. Every parameter is defined exactly once, in the topic section linked beside it; follow the link for its acceptable values, default and meaning. Unless noted otherwise, every parameter uses the erf. prefix.

The one exception is Deprecated and Removed Inputs at the end, which documents inputs that no longer exist and so have no topic section of their own.

Note

Several of these parameters may be specified either as a single value, which is then used at every AMR level, or as a space-separated list with one value per level, e.g. erf.anelastic = 1 0 0. Their definitions are marked “per-level”. For a list, the number of values given must be at least amr.max_level + 1.

Equation Set

• Coupling Type (Data Exchange) – erf.coupling_type

• Forcing Terms – erf.use_gravity

• Governing Equations – erf.anelastic, erf.buoyancy_type, erf.c_p, erf.fixed_density, erf.gradp_type, erf.transport_scalar, erf.use_lagged_delta_rt, erf.use_pert_pres_gradient

• Time Step – erf.anelastic_type

• Initialization – erf.project_initial_velocity

Acoustic Substepping and the Poisson Solve

• Numerical Stability – erf.beta_s

• Time Step – erf.anelastic_type, erf.force_stage1_single_substep, erf.ncorr, erf.poisson_abstol, erf.poisson_reltol, erf.substepping_diag, erf.substepping_type

Initialization, Terrain and Vertical Mesh

• Grid Stretching – erf.grid_stretching_ratio, erf.initial_dz, erf.terrain_z_levels

• Initialization – erf.avg_grid_faces_to_nodes, erf.init_type, erf.nc_bdy_file, erf.rebalance_wrf_input, erf.sounding_type, erf.use_real_bcs, erf.wrfinput_zlevels_from_file

• Terrain – erf.buildings_type, erf.flat_terrain, erf.terrain_type

Physics Model Selection

• Land Surface Model – erf.is_land, erf.land_surface_model

• Moisture – erf.moisture_model, erf.moisture_tight_coupling

• Ocean Surface Model – erf.use_coupled_sst

• Radiation – erf.four_stream_radiation, erf.radiation_model

Implicit Vertical Diffusion

• Diffusive Physics – erf.implicit_before_substep

• Time Step – erf.implicit_ke_diffusion, erf.implicit_moisture_diffusion, erf.implicit_momentum_diffusion, erf.implicit_thermal_diffusion, erf.vert_implicit, erf.vert_implicit_fac

Coriolis and Large-Scale ABL Forcing

• Forcing Terms – erf.abl_driver_type, erf.abl_geo_forcing, erf.abl_geo_wind, erf.abl_geo_wind_table, erf.abl_pressure_grad, erf.const_massflux_layer_hi, erf.const_massflux_layer_lo, erf.const_massflux_tau, erf.const_massflux_u, erf.const_massflux_v, erf.coriolis_3d, erf.latitude, erf.rotational_time_period, erf.use_coriolis, erf.variable_coriolis

Custom, Nudging and Numerical Diffusion Forcing

• Diffusive Physics – erf.num_diff_coeff

• Forcing Terms – erf.add_custom_geostrophic_profile, erf.add_custom_moisture_forcing, erf.add_custom_rhotheta_forcing, erf.add_custom_w_subsidence, erf.add_do_mom_advection, erf.add_do_theta_advection, erf.custom_forcing_uses_primitive_vars, erf.large_scale_forcing, erf.nudging_from_input_sounding, erf.nudging_q, erf.nudging_q_z1, erf.nudging_q_z2, erf.nudging_t, erf.nudging_t_z1, erf.nudging_t_z2, erf.nudging_u, erf.nudging_u_z1, erf.nudging_u_z2, erf.spatial_moisture_forcing, erf.spatial_rhotheta_forcing

Immersed Forcing and Canopy Source Terms

• Forest Canopy – erf.forest_substep

• Terrain – erf.if_Cd_momentum, erf.if_Cd_scalar, erf.if_Olen, erf.if_damp_alpha, erf.if_implicit_drag, erf.if_init_surf_temp, erf.if_stability_correction, erf.if_surf_heating_rate, erf.if_snap_partial_cells, erf.if_surf_temp_flux, erf.if_use_most, erf.if_ws_floor, erf.if_z0, erf.immersed_forcing_substep, erf.use_rotate_surface_flux

Lateral Boundary Nudging for Real-Data Runs

• Forcing Terms – erf.bdy_moist_nudge_type, erf.bdy_nudge_factor, erf.bdy_rho_nudge_factor, erf.use_wrf_bdy_density, erf.use_wrf_bdy_qc_qi

Inflow Perturbation

• Domain Boundary Conditions – erf.perturbation_type

Wind Farm Models

• Forcing Terms – erf.sampling_distance_by_D, erf.turb_disk_angle_from_x, erf.windfarm_airfoil_tables, erf.windfarm_blade_table, erf.windfarm_loc_table, erf.windfarm_loc_type, erf.windfarm_spec_table, erf.windfarm_spec_table_extra, erf.windfarm_type, erf.windfarm_x_shift, erf.windfarm_y_shift

Hindcast Forcing and Hurricane Tracking

• Forcing Terms – erf.hindcast_boundary_data_dir, erf.hindcast_data_interval_in_hrs, erf.hindcast_lateral_forcing, erf.hindcast_lateral_sponge_length, erf.hindcast_lateral_sponge_strength, erf.hindcast_surface_bcs, erf.hindcast_surface_data_dir, erf.hindcast_zhi_sponge_damping, erf.hindcast_zhi_sponge_length, erf.hindcast_zhi_sponge_strength, erf.hurricane_eye_latitude, erf.hurricane_eye_longitude, erf.io_hurricane_eye_tracker

Diagnostics and Testing

• Diagnostic Outputs – erf.Ave_Plane, erf.test_mapfactor, erf.time_avg_vel

Ensemble Initialization

erf.is_init_for_ensemble is read here, and when it is true the remaining ensemble.* parameters listed in Ensemble Initialization are read as well.

Deprecated and Removed Inputs

SolverChoice explicitly checks for the following inputs so that runs using older inputs files fail with an informative message rather than silently ignoring them.

Parameter	Definition	Acceptable Values	Default
erf.use_terrain	removed; set erf.terrain_type instead	none – input removed	aborts if present
erf.use_moist_background	removed; set erf.init_type = MoistBaseState instead	none – input removed	aborts if present
erf.moisture_type	renamed; set erf.moisture_model instead	none – input renamed	aborts if present
erf.no_substepping	removed; set erf.substepping_type instead	none – input removed	aborts if present
erf.init_type	the values Real and Ideal were replaced by WRFInput	WRFInput in place of either retired value	aborts if Real or Ideal is used
erf.terrain_type	the values Static and Moving were replaced by StaticFittedMesh and MovingFittedMesh; the old names still work	StaticFittedMesh, MovingFittedMesh	warns if Static or Moving is used

Damping Options in DampingChoice

This section is an index, not a second set of definitions. It lists the complete set of inputs read by DampingChoice in Source/DataStructs/ERF_DampingStruct.H, which holds the Rayleigh damping and vertical-velocity damping options. Each is defined in the topic section linked beside it. All of them use the erf. prefix.

Rayleigh Damping

• Forcing Terms – erf.rayleigh_damp_T, erf.rayleigh_damp_U, erf.rayleigh_damp_V, erf.rayleigh_damp_W, erf.rayleigh_dampcoef, erf.rayleigh_damping_type, erf.rayleigh_zdamp

Vertical-Velocity Damping

• Numerical Stability – erf.w_damping, erf.w_damping_cfl, erf.w_damping_coeff, erf.w_damping_const