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.

Governing Equations¶

Parameter	Definition	Acceptable Values	Default
erf.anelastic	if 1, solve the anelastic equations (instead of the compressible equations); can be a single value (for all amr levels) or a list of values (one per level)	0, 1	0
erf.buoyancy_type	Controls how buoyancy is calculated: 1=density perturbation, 2/3=temp. perturbation, 4=potential temp. perturbation. See Buoyancy for details	1, 2, 3, 4	1 (may be auto-set to 2 or 3 based on moisture and solver)
erf.use_fft	use FFT rather than multigrid to solve the the Poisson equations	true / false	false
erf.mg_v	verbosity of the multigrid solver if used the Poisson equations	Integer >= 0	0

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	must be set
geometry.prob_hi	physical location of high corner of the domain	Real	must be set
geometry.is_periodic	is the domain periodic in this direction	0 if false, 1 if true	0 0 0

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.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, outflow, slipwall, noslipwall, symmetry or MOST.

List of Parameters¶

Parameter	Definition	Default
xlo.type	boundary type of xlo face	must be set if not periodic
xhi.type	boundary type of xhi face	must be set if not periodic
ylo.type	boundary type of ylo face	must be set if not periodic
yhi.type	boundary type of yhi face	must be set if not periodic
zlo.type	boundary type of zlo face	must be set if not periodic
zhi.type	boundary type of zhi face	must be set if not periodic

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	Integer >= 1 (one per level)	2 for all levels
amr.ref_ratio_vect	ratio of coarse to fine grid spacing between subsequent levels	3 integers >= 1 (one per dir)	2 for all 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	true or false	false
amr.iterate_grids	do we iterate on the grids?	true, false	true

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

would set factor {2 in x-dir, 4 in y-dir, 3 in z-dir} refinement between all adjacent levels. Note that you must specify 3 values, one for each coordinate direction.
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 an elevation of z=0. 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 should vary from 0 (at the surface) to the domain height.

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
erf.grid_stretching_ratio	scaling factor applied to delta z at each level	Real > 1	0 (no grid stretching)
erf.initial_dz	vertical grid spacing for the cell above the bottom surface	Real > 0	must be set if grid stretching ratio is set
erf.terrain_z_levels	nominal staggered z levels	List of Real	NONE

Notes¶

If both erf.terrain_z_levels and erf.grid_stretching_ratio are specified, the simple grid stretching will be ignored.
The number of input erf.terrain_z_levels must be equal amr.n_cell in the z direction + 1.

Examples of Usage¶

erf.grid_stretching_ratio = 1.025
erf.initial_dz = 5.0

the first cell center would be at z=2.5

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.

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	1
amr.max_grid_size	maximum size of a grid in any direction	Integer > 0	32
amr.blocking_factor	grid size must be a multiple of this	Integer > 0	2
amr.refine_grid_layout	refine grids more if # of processors \(>\) # of grids	0 if false, 1 if true	1

Notes¶

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.max_grid_size at every level must be even
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

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.

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 mesh 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.

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
erf.substepping_type	Should we substep in each RK stage?	“Implicit” or “None”	“Implicit” if compressible, “None” if anelastic
erf.vert_implicit	Do vertical implicit solve for diffusion of u, v, and theta with default time-centering in each stage	Boolean	false
erf.vert_implicit_fac	How much implicit vertical diffusion to include in each RK stage? Currently, only applies to rho*theta component. Specify either one (the same for all stages) or three values, one per stage	Real >= 0 (explicit) and <= 1 (implicit)	0.0, 0.0, 0.0 (fully explicit)
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	Real > 0 and <= 1	1.0
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
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.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

Notes¶

If erf.anelastic is true then substepping_type is internally set to “None”.
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, then adjusted (reduced if necessary) as above so that the ratio of slow timestep to fine timestep is an even integer. If erf.substepping_cfl is specified, that CFL value will be used. If not, the default value will be used.

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.

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.

Additional Plotfile Controls¶

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
erf.expand_plotvars_to_unif_rr	Expand plot variables to a uniform refinement ratio for mixed-refinement cases	true / false	false

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 or 1	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. The print statements have the form

TIME= 1.91717746 MASS= 1.792410279e+34

for example. 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), and (4) a history of modeled subgrid stresses. 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). 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 four strings	NONE
erf.der_data_log	Output filename(s) for derived data	Up to four strings	NONE
erf.energy_data_log	Output filename(s) for total energy	Up to four strings	NONE
erf.profile_int	Interval (number) of steps between outputs	Integer	-1
erf.destag_profiles	Interpolate all outputs to cell-center heights	Boolean	true

By default, 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)

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 line sampling described in this section.

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.

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 option and includes a subset of the plotfile outputs: “density”, “x_velocity”, “y_velocity”, “z_velocity”, “magvel”, “theta”, “qv”, “qc”, and “pressure”. 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.

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/ 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	List of strings	theta, magvel

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

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	true/false	false

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”

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) and “WENOMZQ3.”

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”, “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.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.0
erf.Sc_t	Turbulent Schmidt Number	Real	1.0
erf.num_diff_coeff	Coefficient for 6th-order numerical diffusion, set to 0 to disable	Real [0.0, 1.0]	0.0

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.

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.

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”, “MRF”, “SHOC”	“None”
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_diffuse_moistvars	Diffuse moisture variables using modeled eddy diffusivity	bool	0
erf.advect_QKE	Include advection terms in QKE eqn	bool	1
erf.diffuse_QKE_3D	Include horizontal turb. diffusion terms in QKE eqn.	bool	0
erf.pbl_ysu_force_over_water	Treat whole domain as over water for YSU PBL scheme regardless of LSM/other inputs	bool	0
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	Bool	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_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.mrf_moistvars	Diffuse moisture variables using modeled eddy diffusivity	bool	0

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.

Right now, the QKE equation is solved if and only if the MYNN2.5 PBL model is selected. In that transport equation, it is optional to advect QKE, and to apply LES diffusive transport for QKE in the horizontal directions (the vertical component is always computed as part of the PBL scheme).

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.

Forcing Terms¶

List of Parameters¶

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.

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)	true or false	false
erf.add_custom_rhotheta_forcing	Apply the user-defined temperature source term	true or false	false
erf.add_custom_moisture_forcing	Apply the user-defined qv source term	true or false	false
erf.add_custom_w_subsidence	Apply the user-defined vertical velocity profile for use in calculating subsidence source terms	true or false	false
erf.add_do_theta_advection	When using custom w subsidence, apply the subsidence source term to the (rho*theta) equation	true or false	true
erf.add_do_mom_advection	When using custom w subsidence, apply the subsidence source terms to the momentum equations	true or false	true
erf.add_custom_geostrophic_profile	Apply the user-defined geostrophic wind profile	true or false	false

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

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

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	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	List of strings	All
erf.bndry_file	Input boundary-plane directory	String	None
erf.bndry_input_var_names	Variables to read	List of strings	All

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.

Numerical Stability¶

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

List of Parameters¶

erf.beta_s	Time off-centering coefficient	Real	0.1
erf.w_damping	Enable vertical-velocity damping	Bool	false
erf.w_damping_cfl	Critical vertical advective CFL for w-damping to be applied, if `erf.w_damping` is true	Real	1.0
erf.w_damping_const	w-damping coefficient (m/s2)	Real	-1
erf.w_damping_coeff	w-damping coefficient (-)	Real	-1

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.

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	Initialization type	“None”, “Uniform” “ConstantDensity”, “Isentropic”, “MoistBaseState”, “Input_Sounding” “Hindcast”, “WRFInput”, “Metgrid” “NCFile”	“None”
erf.input_sounding_file	Path to WRF-style input sounding file	String	“input_sounding”
erf.sounding_type	How to interpret the sounding provided with init_type = “input_sounding”	“Ideal”, “Isentropic”, “DryIsentropic”, “ConstantDensity”	Ideal
erf.use_real_bcs	If init_type is WRFInput or Metgrid do we want to use these bcs?	true or false	true if if init_type is WRFInput or Metgrid; else false
erf.nc_init_file	NetCDF file with initial mesoscale data	String	NONE
erf.nc_bdy_file	NetCDF file with mesoscale data at lateral boundaries	String	NONE
erf.project_initial_velocity	project initial velocity?	0 or 1	1 if anelastic; 0 if compressible
erf.real_width	Lateral boundary total width if use_real_bcs is true	Integer	0
erf.real_set_width	Lateral boundary specified zone width if use_real_bcs is true	Integer	0
erf.real_extrap_w	First-order extrapolation of vertical velocities on lateral boundaries (instead of setting to 0) if use_real_bcs is true	bool	true
erf.metgrid_debug_quiescent	If init_type is Metgrid, overwrite initial conditions and boundary conditions to be quiescent.	true or false	false
erf.metgrid_debug_isothermal	If init_type is Metgrid, overwrite theta to be 300 in initial conditions and boundary conditions.	true or false	false
erf.metgrid_debug_dry	If init_type is Metgrid, overwrite qv to be dry in initial conditions and boundary conditions.	true or false	false
erf.metgrid_debug_msf	If init_type is Metgrid, overwrite map scale factors to be 1.	true or false	false
erf.metgrid_debug_psfc	If init_type is Metgrid, overwrite surface pressure to be 10**5.	true or false	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.	true or false	false
erf.metgrid_basic_linear	If init_type is Metgrid, use linear vertical interpolation and no quality control?	true or false	false
erf.metgrid_use_below_sfc	If init_type is Metgrid, use the origin data levels below the surface?	true or false	true
erf.metgrid_use_sfc	If init_type is Metgrid, use the origin data level at the surface?	true or false	true
erf.metgrid_retain_sfc	If init_type is Metgrid, assign the lowest level directly using the surface value from the origin data?	true or false	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	Integer	0

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 (e.g., “wrfinput_d01”).

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) and erf.real_set_width (corresponding to WRF’s spec_zone, typically set to 1), which corresponds to a relaxation zone with a width of real_width - real_set_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.

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 or read from a text file specified by erf.terrain_file_name. 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	Is there terrain and if so, how is it represented?	None StaticFittedMesh MovingFittedMesh ImmersedForcing EB	None
erf.terrain_smoothing	specify terrain following	0, 1, 2	0
erf.terrain_file_name	filename	String	NONE

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.
When setting erf.terrain_file_name, the format of the file is expected to
be (in raw text): 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) values of the z-coordinate associated with the (x,y) values we have just read in. Note that the z-values are in the order z(x1,y1), z(x1,y2), z(x1,y3), … which is contrary to standard Fortran ordering

Land Surface Model¶

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

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
erf.land_surface_model	Enables land surface energy and moisture fluxes	“None”, “NOAHMP”, “MM5”, “SLM”	“None”

Note

Noah-MP requires USE_NOAHMP=TRUE at build time. See Coupling to Noah-MP for details.

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	Coupling mode for coupled simulations with AMR-Wind or WaveWatch3	“OneWay”, “TwoWay”	“None”

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 has several different moisture models. The models that are currently implemented are Eulerian models; however, ERF has the capability for Lagrangian models when compiled with particles.

The following run-time options control how the full moisture model is used.

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
erf.moisture_model	Name of moisture model	“None”, “SAM”, “Kessler”, “SatAdj” “Kessler_NoRain”, “Morrison”, “Morrison_NoIce”, “SAM_NoPrecip_NoIce”, “SAM_NoIce”, “P3”	“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	Bool	false

Radiation¶

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.

List of Parameters¶

Parameter	Definition	Acceptable Values	Default / Notes
erf.radiation_model	Enable radiation model	“None”, “RRTMGP”	“None”
erf.rad_t_sfc	Surface temperature if no LSM	Real	Must be set without LSM
erf.rad_freq_in_steps	Radiation update frequency (steps)	Integer >= 1	1
erf.rad_write_fluxes	Write radiation fluxes to plotfiles	true / false	false
erf.rad_do_subcol_sampling	Enable MCICA subcolumn sampling	true / false	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	Real	< 0 uses computed value
erf.rad_orbital_mvelp	Override mean longitude of perihelion	Real	< 0 uses computed value
erf.rad_cons_lat	Constant latitude for idealized cases	Real	39.809860
erf.rad_cons_lon	Constant longitude for idealized cases	Real	-98.555183
erf.fixed_total_solar_irradiance	Fixed total solar irradiance (TOA)	Real	< 0 disables
erf.fixed_solar_zenith_angle	Fixed solar zenith (passed as `mu0`)	Real	<= 0 disables
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	true / false	true
erf.rad_extra_clnclrsky_diag	Extra clean and clear-sky diagnostics	true / false	false
erf.rad_extra_clnsky_diag	Extra clean-sky diagnostics	true / false	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

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.
When orbital parameters are negative, values are computed from the orbital year.

The lookup data may be downloaded as a package from here.

Note

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

SHOC¶

SHOC inputs are provided under the erf.shoc prefix. These options control runtime tuning and diagnostics for the SHOC PBL scheme.

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
erf.shoc.lambda_low	Minimum stability correction	Real	0.001
erf.shoc.lambda_high	Maximum stability correction	Real	0.04
erf.shoc.lambda_slope	Slope from low to high correction	Real	2.65
erf.shoc.lambda_thresh	Stability threshold for correction	Real	0.02
erf.shoc.thl2tune	Temperature variance tuning factor	Real	1.0
erf.shoc.qw2tune	Moisture variance tuning factor	Real	1.0
erf.shoc.qwthl2tune	Temperature-moisture covariance tuning	Real	1.0
erf.shoc.w2tune	Vertical velocity variance tuning	Real	1.0
erf.shoc.length_fac	Length-scale factor	Real	0.5
erf.shoc.c_diag_3rd_mom	3rd-moment vertical velocity damping	Real	7.0
erf.shoc.coeff_kh	Eddy diffusivity coefficient for heat	Real	0.1
erf.shoc.coeff_km	Eddy diffusivity coefficient for momentum	Real	0.1
erf.shoc.shoc_1p5tke	Reduce to 1.5 TKE closure	true / false	false
erf.shoc.extra_shoc_diags	Enable extra SHOC diagnostics	true / false	false
erf.shoc.apply_tms	Apply TMS (turbulent mountain stress)	true / false	false
erf.shoc.check_flux_state	Flux state consistency check	true / false	false
erf.shoc.column_conservation_check	Column conservation check	true / false	false

Notes¶

Defaults are set in Source/PhysicsInterfaces/Shoc/ERF_ShocInterface.cpp and may be adjusted in the inputs file using the erf.shoc prefix.

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
erf.check_for_nans	Test solution for NaNs	int
amrex.fpe_trap_invalid	Raise errors for NaNs	0 / 1
amrex.fpe_trap_zero	Raise errors for divide by zero	0 / 1
amrex.fpe_trap_overflow	Raise errors for overflow	0 / 1

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

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	Real > 0	1.0e-14

Particles¶

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
particles.disable_plt	Disable particle plotfile output	true / false	false

Ensemble Initialization¶

List of Parameters¶

Parameter	Definition	Acceptable Values	Default
ensemble.is_init_with_correlated_pert	Use spatially correlated perturbations at init	true / false	false
ensemble.pert_correlated_radius	Correlation radius	Real > 0	None