Inputs.rst

Inputs

.. toctree::
   :maxdepth: 1

The REMORA executable reads run-time information from an “inputs” file which you put on the command line. This section describes the inputs which can be specified either in the inputs file or on the command line. If a value is specified on the command line, that value will override a value specified in the inputs file.

Problem Geometry

The problem geometry can be specified either by a NetCDF grid file or in the inputs. Instructions for setting grid, initial, and Dirichelet boundary conditions from NetCDF file can be found :ref:`here<icbc-parameters>`. If one of these quantities is specified from a NetCDF file, they all must be. Even if the grid is specified in the NetCDF file, the geometry and boundary parameters below must still be set. geometry.prob_lo and geometry.prob_hi do not need to agree with the file in this case.

The z-component of geometry.prob_lo should be more negative than the deepest bathymetry, and the z-compoonent of geometry.prob_hi should be 0.

List of Parameters

Parameter	Definition	Acceptable Values	Default
geometry.prob_lo	physical location of low corner of the domain	[Real Real -Real]	must be set
geometry.prob_hi	physical location of high corner of the domain	[Real Real 0]	must be set
geometry.is_periodic	is the domain periodic in this direction	0 if false, 1 if true. Z-component must be zero	0 0 0

Examples of Usage

• geometry.prob_lo = 0 0 -200 defines the low corner of the domain at (0 m,0 m,-200 m) in physical space.
• geometry.prob_hi = 1.e8 2.e8 0 defines the high corner of the domain at (1.e8 m, 2.e8 m, 0 m) in physical space.
• geometry.is_periodic = 0 1 0 says the domain is periodic in the y-direction only.

Domain Boundary Conditions

Instructions for how to specify domain boundary conditions, with usage examples can be found in :ref:`Domain Boundary Conditions`<sec:domainBCs>`.

Imposing Boundary and Initial Conditions from NetCDF File

Grid, initial, and time-dependent boundary data can be specified using NetCDF files, as in ROMS. REMORA expects files in the same format as ROMS, in NetCDF classic format (32- or 64-bit). Other versions of NetCDF files can be converted to 64-bit NetCDF classic by running the command:

ncks -5 old_file.nc converted_file.nc

The utility ncks is part of the NCO suite.

Currently, if one of these are specified in a file, they all must be. Boundary condition options with NetCDF boundary data are equivalent to ROMS clamped, Chapman-Flather, and Orlanski + Nudging boundary conditions. Options and examples can be found in the section on :ref:`Domain Boundary Conditions`<sec:domainBCs>`.

--

List of Parameters

Parameter	Definition	Acceptable Values	Default
remora.ic_bc_type	read initial, grid, and boundary data from NetCDF files	true/false	false
remora.nc_init_file_0	initial data NetCDF file name	string	must be set if remora.ic_bc_type is true
remora.nc_grid_file_0	grid data NetCDF file name	string	must be set if remora.ic_bc_type is true
remora.nc_bdry_file_0	boundary data NetCDF file name	string	must be set if remora.ic_bc_type is true

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 :ref:`MeshRefinement` 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 REMORA 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
stop_time	final simulation time	Real >= 0	-1.0
remora.start_time	initial simulation time	Real >= 0	0.0

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 for Single-Rate

Parameter	Definition	Acceptable Values	Default
remora.cfl	CFL number for hydro	Real > 0 and <= 1	0.8
remora.fixed_dt	set level 0 dt as this value regardless of cfl or other settings	Real > 0	unused if not set
remora.fixed_fast_dt	set fast dt as this value	real > 0	inferred from fixed_dt and fixed_ndfast_ratio if not set
remora.fixed_ndfast_ratio	set fast dt as slow dt / this ratio	int	inferred from fixed_dt and fixed_fast_dt if not set
remora.change_max	factor by which dt can grow in subsequent steps	Real >= 1	1.1

Examples of Usage

• remora.cfl = 0.9

  defines the timestep as dt = cfl * dx / (u+c). Only relevant if fixed_dt not set
• remora.change_max = 1.1

  allows the 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.
• remora.fixed_dt = 1.e-4

  sets the level-0 time step to be 1.e-4 for the entire simulation, ignoring the other timestep controls. Note that if remora.init_shrink \neq 1 then the first time step will in fact be remora.init_shrink * remora.fixed_dt.

Restart Capability

See :ref:`sec:Checkpoint` for how to control the checkpoint/restart capability.

PlotFiles

See :ref:`sec: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
remora.v	verbosity of REMORA functions	0: none 1: integrated/max quantities 2: print boxes	0
remora.sum_interval	how often (in level-0 time steps) to compute integral quantities	Integer	-1

Examples of Usage

• remora.sum_interval = 2

  if remora.sum_interval > 0 then the code computes and prints certain integral quantities, such as total mass, momentum and energy in the domain every remora.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 or if remora.v <= 0 then it will not compute and print these quantities.

Included terms

List of Parameters

Parameter	Definition	Acceptable Values	Default
remora.use_coriolis	Include Coriolis terms.	true / false	false
remora.flat_bathymetry	Use flat bathymetry.	true / false	true
remora.use_prestep	Do prestep terms. Only for debugging purposes.	true / false	true
remora.use_uv3dmix	Include harmonic viscosity. Only for debugging purposes.	true / false	true
remora.use_barotropic	Include 2d barotropic step. Only for debugging purposes.	true / false	true

Physics Parameters

List of Parameters

Parameter	Definition	Acceptable Values	Default
remora.ggrav	Gravitational field strength [kg m/s^2]	Real number	9.81
remora.eos_type	Which equation of state to use. Nonlinear corresponds to UNESCO	Linear or Nonlinear	Linear
remora.R0	Background density [kg/m^3] used in Linear Equation of State. May be used in setup of some problems.	Real number	1028
remora.S0	Background salinity (nondimensional) used in Linear Equation of State State. May be used in setup of some problems.	Real number	35
remora.T0	Background temperature (Celsius) used in Linear Equation of State State. May be used in setup of some problems.	Real number	5
remora.Tcoef	Linear EOS parameter (1/Celsius)	Real number	1.7e-4
remora.Scoef	Linear EOS parameter (nondimensional)	Real number	0.0
remora.rho0	Mean density (kg/m^3) used when Boussinesq approx is inferred	Real number	1025
remora.coriolis_type	Type of Coriolis forcing. beta_plane uses a linear approximation. custom is calculated from a function in prob.cpp, and real is read from the netcdf grid file	beta_plane / custom / real	beta_plane
remora.coriolis_f0	f-plane constant for Coriolis param f = f_0 + \beta y when using beta plane Coriolis type	Real number	0.0
remora.coriolis_beta	beta-plane constant for Coriolis param f = f_0 + \beta y when using beta plane Coriolis type	Real number	0.0
remora.horizontal_mixing_type	Horizontal mixing type. analytical function is specified in prob.cpp.	analytical / constant	analytical
remora.visc2	Constant horizontal viscosity, everywhere. Needed when horizontal_mixing_type is constant.	Real number	0.0
remora.tnu2_salt	Constant horizontal diffusivity, everywhere for salt. Needed when horizontal_mixing_type is constant.	Real number	0.0
remora.tnu2_temp	Constant horizontal diffusivity, everywhere for temperature. Needed when horizontal_mixing_type is constant.	Real number	0.0
remora.tnu2_scalar	Constant horizontal diffusivity, everywhere for passive scalar. Needed when horizontal_mixing_type is constant.	Real number	0.0
remora.vertical_mixing_type	Vertical mixing type. analytical function is specified in prob.cpp.	analytical / GLS	analytical
remora.gls_stability_type	Stability function to use for GLS	Canuto_A / Canuto_B / Galperin	Canuto_A
remora.Akv_bak	Minimum/initial value of Akv	Real number	5.0e-6
remora.Akt_bak	Minimum/initial value of Akt	Real number	1.0e-6

List of drag-related parameters

Parameter	Definition	Acceptable Values	Default
remora.bottom_stress_type	Bottom drag type	linear / quadratic / logarithmic	linear
remora.rdrag	Linear drag coefficient (used if remora.bottom_stress_type = linear)	Positive real number	3.0e-4
remora.rdrag2	Quadratic drag coefficient (used if remora.bottom_stress_type = quadratic)	Positive real number	3.0e-3
remora.Zob	Bottom roughness [m] (used if remora.bottom_stress_type = logarithmic and for GLS	Positive real number	0.02
remora.Zos	Surface roughness [m] (used for GLS)	Positive real number	0.02
remora.Cdb_min	Minimum threshold for transfer coefficient of momentum	Positive real number	1.0e-6
remora.Cdb_max	Maximum threshold for transfer coefficient of momentum	Positive real number	0.5

List of GLS-specific parameters

Parameter	Definition	Acceptable Values	Default
remora.gls_P		Real number	3.0
remora.gls_M		Real number	1.5
remora.gls_N		Real number	-1.0
remora.gls_Kmin		Real number	7.6e-6
remora.gls_Pmin		Real number	1.0e-12
remora.gls_cmu0		Real number	0.5477
remora.gls_c1		Real number	1.44
remora.gls_c2		Real number	1.92
remora.gls_c3m		Real number	-0.4
remora.gls_c3p		Real number	1.0
remora.gls_sigk		Real number	1.0
remora.gls_sigp		Real number	1.3
remora.Akk_bak	Initial/minimum value of Akk	Real number	5.0e-6
remora.Akp_bak	Initial/minimum value of Akp	Real number	5.0e-6

Numerical Algorithms

List of Parameters

Parameter	Definition	Acceptable Values	Default
remora.tracer_horizontal_advection_scheme	Scheme for horizontal advection of tracers	upstream3, centered4	upstream3
remora.uv_horizontal_advection_scheme	Scheme for horizontal advection of momenta	upstream3, centered2	upstream3

Vertical Stretch parameters

List of Parameters

Parameter	Definition	Acceptable Values	Default
remora.theta_s	Stretching parameter for surface refinement of vertical S-grid	0 \leq \theta_S \leq 10	3.0
remora.theta_b	Stretching parameter for bottom refinement of vertical S-grid	0 \leq \theta_B \leq 4	0.0
remora.tcline	Surface/bottom layer width (m) in vertical S-grid	Positive number	150

These parameters are used to calculate the vertical S-grid stretch/transform functions detailed in :ref:`Vertical S-Coordinate<VerticalSCoord>`.

Runtime Error Checking

Through AMReX functionality, REMORA 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
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