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.

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

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	2 / 3 / 4 (one per level)	2 for all levels
amr.ref_ratio_vect	ratio of coarse to fine grid spacing between subsequent levels	3 integers (one per dir) 2 / 3 / 4	2 for all directions
amr.regrid_int	how often to regrid	Integer > 0	must be set
amr.regrid_on_restart	should we regrid immediately after restarting	0 or 1	0

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.

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.max_grid_size	maximum size	Integer	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

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.

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

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.no_substepping	Should we turn off substepping in time?	int (0 or 1)	0
erf.cfl	CFL number for hydro	Real > 0 and <= 1	0.8
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	only relevant if use_native_mri is true
erf.fixed_mri_dt_ratio	set fast dt as slow dt / this ratio	even int > 0	only relevant if no_substepping is 0
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

Notes

The time step controls work somewhat differently depending on whether one is using acoustic substepping in time; this is determined by the value of no_substepping.
If erf.no_substepping = 1 there is only one time step to be calculated, and fixed_fast_dt and 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.no_substepping = 0 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 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.fast_fixed_dt are specified and the ratio of fixed_dt to fast_fixed_dt is not an even positive integer
  - If erf.fixed_dt and erf.fast_fixed_dt and erf.fixed_mri_dt_ratio are all specified but are inconsitent
- 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.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.

PlotFiles

See Plotfiles for how to control the types and frequency of plotfile generation.

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.

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.molec_diff_type	Using molecular viscosity and diffusivity?	“None”, “Constant”, or “ConstantAlpha”	“None”
erf.dynamicViscosity	Viscous coeff. if DNS	Real	0.0
erf.Cs	Constant Smagorinsky coeff.	Real	0.0
erf.Pr_t	Turbulent Prandtl Number	Real	1.0
erf.Sc_t	Turbulent Schmidt Number	Real	1.0
erf.spatial_order		2 / 3 / 4 / 5 / 6	2

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.dynamicViscosity 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.dynamicViscosity divided by erf.rho0_trans; this diffusivity is multiplied by the current density \(\rho\) to form the coefficient in the momentum equation; and
erf.alpha_T is multiplied by the current density \(\rho\) to form the coefficient for potential temperature, and
erf.alpha_C is multiplied by the current density \(\rho\) to form the coefficient for an advected scalar.

PBL Scheme

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.pbl_type	Name of PBL Scheme to be used	“None”, “MYNN2.5”	“None”
erf.pbl_A1	MYNN Constant A1	Real	1.18
erf.pbl_A2	MYNN Constant A2	Real	0.665
erf.pbl_B1	MYNN Constant B1	Real	24.0
erf.pbl_B2	MYNN Constant B2	Real	15.0
erf.pbl_C1	MYNN Constant C1	Real	0.137
erf.pbl_C2	MYNN Constant C1	Real	0.75
erf.pbl_C3	MYNN Constant C3	Real	0.352
erf.pbl_C4	MYNN Constant C4	Real	0.0
erf.pbl_C5	MYNN Constant C5	Real	0.2
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

Note that the MYNN2.5 scheme must be used in conjunction with a MOST boundary condition at the surface (Zlo) boundary.

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

Forcing Terms

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.abl_driver_type	Type of external forcing term	None, PressureGradient GeostrophicWind	None
erf.abl_pressure_grad	Pressure gradient forcing term (only if abl.driver_type = PressureGradient)	3 Reals	(0.,0.,0.)
erf.abl_geo_wind	Geostrophic forcing term (only if abl.driver_type = GeostrophicWind)	3 Reals	(0.,0.,0.)
erf.use_gravity	Include gravity in momentum update? If true, there is buoyancy	true / false	false
erf.use_coriolis	Include Coriolis forcing	true / false	false
erf.use_rayleigh_damping	Include explicit Rayleigh damping	true / false	false

Initialization

ERF can be initialized in different ways. These are listed below:

Custom initialization:
Several problems under Exec are initialized in a custom manner. The state and velocity components are specific to the problem. These problems are meant for demonstration and do not include any terrain or map scale factors.
Initialization using a NetCDF file:
Problems in ERF can be initialized using a NetCDF file containing the mesoscale data. The state and velocity components of the ERF domain are ingested from the mesoscale data. This is a more realistic problem with real atmospheric data used for initialization. The typical filename used for initialization is wrfinput_d01, which is the outcome of running ideal.exe or real.exe of the WPS/WRF system. These problems are run with both terrain and map scale factors.
Initialization using an input_sounding file:
Problems in ERF can be initialized using an input_sounding file containing the vertical profile. This file has the same format as used by ideal.exe executable in WRF. Using this option for initialization, running ideal.exe and reading from the resulting wrfinput_d01 file are not needed. This option is used for initializing ERF domain to a horizontally homogeneous mesoscale state and does not include terrain or map scale factors.

In addition, there is a run-time option to project the initial velocity field to make it divergence-free. To take advantage of this option, the code must be built with USE_POISSON_SOLVE = TRUE in the GNUmakefile if using gmake, or with -DERF_ENABLE_POISSON_SOLVE:BOOL=ON in the cmake.sh file if using cmake.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.init_type	Initialization type	“custom”, “ideal”, “real”, “input_sounding”	“custom”
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?	Integer	1

Notes

If erf.init_type = ideal, the problem is initialized with mesoscale data contained in a NetCDF file, provided via erf.nc_init_file. The mesoscale data are horizontally homogeneous, i.e., there is variation only in the vertical direction.

If erf.init_type = real, the problem is initialized with mesoscale data contained in a NetCDF file, provided via erf.nc_init_file. The mesoscale data are realistic with variation in all three directions. In addition, the lateral boundary conditions must be supplied in a NetCDF files specified by erf.nc_bdy_file = wrfbdy_d01

If erf.init_type = custom or erf.init_type = input_sounding, erf.nc_init_file and erf.nc_bdy_file do not need to be set.

Setting erf.project_initial_velocity = 1 will have no effect if the code is not built with ERF_USE_POISSON_SOLVE defined.

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 = real.

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.use_terrain (default false). If terrain-fitted coordinates are chosen, they are defined to be static (default) or moving by setting erf.terrain_type. If using terrain, 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.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.use_terrain	use terrain-fitted coordinates?	true / false	false
erf.terrain_type	static or moving?	0 / 1	0
erf.terrain_smoothing	specify terrain following	0, 1, 2	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 following coordinate.
erf.terrain_smoothing = 2
Sullivan TF is used when generating the terrain following coordinate.

Moisture

ERF has two different moisture models – one that includes only water vapor and cloud water, and a more complete model that includes water vapor, cloud water, cloud ice, rain, snow and graupel.

If ERF is compiled with ERF_USE_WARM_NO_PRECIP defined, then the first model is used and no further inputs are required.

If ERF is compiled with ERF_USE_MOISTURE defined, then the following run-time options control how the full moisture model is used.

List of Parameters

Parameter	Definition	Acceptable Values	Default
erf.do_cloud	use basic moisture model	true / false	true
erf.do_precip	include precipitation in treatment of moisture	true / false	true