Inputs

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 here. 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. remora.prob_lo and remora.prob_hi do not need to agree with the file in this case.

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

List of Parameters

Parameter

Definition

Acceptable Values

Default

remora.prob_lo

physical location of low

corner of the domain

[Real Real -Real]

must be set

remora.prob_hi

physical location of

high corner of the domain

[Real Real 0]

must be set

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

  • remora.prob_lo = 0 0 -200 defines the low corner of the domain at (0 m,0 m,-200 m) in physical space.

  • remora.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.

  • remora.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 Domain Boundary Conditions.

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). NetCDF4-classic does not work. If the file format is incorrect, REMORA will exit with the error:

NetCDF: Attempt to use feature that was not turned on when netCDF was built.

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 initial or grid files are specified, they both 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 Domain Boundary Conditions.

List of Parameters

Parameter

Definition

Acceptable

Values

Default

remora.ic_type

read initial and grid

data from files

analytic

or netcdf

analytic

remora.nc_init_file_0

initial data NetCDF

file name

string

must be set

if remora.ic_type

is true

remora.nc_grid_file_0

grid data NetCDF

file name

string

must be set

if remora.ic_type

is true

remora.nc_bdry_file

boundary data NetCDF

file names(s)

string or list

of strings

must be set if

any boundary

condition requires it:

orlanski_rad_nudg,

clamped, chapman,

or flather.

remora.nc_frc_file

forcing data NetCDF

file name

string

must be set

if remora.wind_type

or remora.smflux_type

equal netcdf

remora.bdy_time_varname

default name of time

variable in

boundary file

string

ocean_time

remora.bdy_{var}_time_varname

name of time variable

for variable {var} (one

of temp, salt, u,

v, ubar, vbar,

zeta)

string

None

remora.frc_time_varname

name of time variable

in forcing file

string

wind_time for wind,

sms_time for surface

momentum stress

Notes

  • nc_bdry_file must either be a string or a space-separated list of strings of boundary data files. They must be in time series order.

  • The time variables in the boundary files may be different for each boundary variable. Any that are not individually specified with remora.bdy_{var}_time_varname will default to the variable name given by bdy_time_varname.

Resolution and Tiling

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

List of Parameters

Parameter

Definition

Acceptable Values

Default

remora.n_cell

number of cells in each

direction at the coarsest

level

Triplet of integers > 0

{x,y,z}

must be set

remora.omp_tile_size

target tile size

Triplet of integers > 0

{x,y,z}

CPU: 8 8 1024

GPU: 1024 1024 1024

Notes

  • remora.omp_tile_size is an alias for fabarray.mfiter_tile_size, which controls the distribution of work by OpenMP.

  • The domain may not be tiled in the z direction. That is, the last component of remora.omp_tile_size must be greater than or equal to the number of vertical levels.

Examples of Usage

  • remora.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.

Mesh Refinement and (Re)gridding

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.

Note that because these arguments are primarily used by AMReX and pertain to adaptive mesh refinement, they use the prefix amr.

List of Parameters

Parameter

Definition

Acceptable Values

Default

amr.max_level

number of levels of

refinement above the

coarsest level

Integer >= 0

must be set

amr.ref_ratio_vect

ratio of coarse

to fine grid

spacing between

subsequent levels

3 integers

(one per dir)

per refinement

level. Refinement

in z must be 1

2 for all

directions

amr.regrid_int

how often to regrid

Integer

-1 (don’t regrid)

amr.regrid_on_restart

should we regrid

immediately

after restarting

0 or 1

0

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.n_error_buf_{x,y,z}

radius of additional

tagging around

already tagged

cells in x, y, or z

Integer >= 0;

Can specify up

to one per ref. level

1

amr.blocking_factor

grid size must

be a multiple

of this

Integer > 0

2

amr.blocking_factor_{x,y}

grid size in

{x,y} must be

multiple of this

Integer > 0;

Can specify up to

one per ref. level

1

amr.blocking_factor_z

grid size in

z must be

multiple of this

Integer > 0;

In AMR problems,

recommend it equal

n_cell in z

1

amr.refine_grid_layout

refine grids more if

# of processors

\(>\) # of grids

0 if false, 1 if true

1

amr.do_substep

whether to sub-step finer

levels in time

0 if false, 1 if true

NOTE: true will

trigger Assert

failure

0

Notes

  • if amr.max_level = 0 then you do not need to set amr.ref_ratio_vect or amr.regrid_int.

  • amr.n_error_buf, remora.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 remora.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 substepping turned on by amr.do_substep is NOT implemented yet so will trigger an Assert.

Examples of Usage

  • 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 6
    would set factor 2 refinement between levels 0 and 1, and factor 3 refinement between levels 1 and 2 (6 between levels 0 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 1
    would set factor {2 in x-dir, 4 in y-dir, 1 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.
  • 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.

Simulation Time

List of Parameters

Parameter

Definition

Acceptable Values

Default

remora.max_step

maximum number of level 0 time steps

Integer >= 0

-1

remora.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 (remora.max_step), or the final simulation time (remora.stop_time), or both. The code will stop at whichever criterion comes first. Note that if the code reaches remora.stop_time then the final time step will be shortened so as to end exactly at remora.stop_time, not pass it.

Examples of Usage

  • remora.max_step = 1000

  • remora.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

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.

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

remora.v

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

false

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 is 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. analytic is

calculated from a function in

prob.cpp, and netcdf is

read from the netcdf grid file

beta_plane /

analytic /

netcdf

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.

analytic means function is

specified in prob.cpp.

analytic /

constant

analytic

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

function is specified in

prob.cpp.

analytic /

GLS

analytic

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

remora.bulk_fluxes

Whether to use bulk fluxes

parametrization

true / false

false

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

List of surface forcing parameters

Parameter

Definition

Acceptable Values

Default

remora.smflux_type

Input format for surface momentum

flux if using. analytic specified

in prob.cpp; netcdf from file.

analytic or

netcdf

analytic

remora.wind_type

Input format for surface wind speed,

if using. analytic specified in

prob.cpp; netcdf from file.

analytic or

netcdf

analytic

List of Bulk Fluxes parameters

Parameter

Definition

Acceptable

Values

Default

remora.air_temperature

Air temperature [C] (used as

uniform value if

Tair_from_netcdf is false)

Real number

23.567

remora.air_humidity

Relative humidity of air

(used as uniform value if

qair_from_netcdf is false)

Real number

from 0 to 1

0.776

remora.air_pressure

Air pressure [hPa] (used as

uniform value if

Pair_from_netcdf is false)

Real number

1013.48

remora.surface_radiation_flux

Shortwave radiation flux [W/m^2]

(used as uniform value if

srflx_from_netcdf is false)

Real number

0.0

remora.Tair_from_netcdf

Load air temperature from NetCDF

file (spatially varying)

true / false

false

remora.qair_from_netcdf

Load air humidity from NetCDF

file (spatially varying)

true / false

false

remora.qair_is_percent

Convert qair from percentage

(0-100) to fraction (0-1).

Only used if

qair_from_netcdf is true

true / false

false

remora.Pair_from_netcdf

Load air pressure from NetCDF

file (spatially varying)

true / false

false

remora.srflx_from_netcdf

Load shortwave radiation flux

from NetCDF file

(spatially varying)

true / false

false

remora.longwave_down

Use file-provided downward longwave radiation to compute net longwave (Lnet = Ldown - sigma*epsilon*T^4)

true / false

false
remora.longwave_down_from_netcdf | Load longwave field from NetCDF
file (spatially varying)

true / false

false

remora.longwave_netcdf_is_net

Interpret the NetCDF longwave field as net longwave (use as-is). If false, interpret as downward longwave and compute net in the bulk flux routine

true / false

false
remora.longwave_netcdf_varname | Name of the NetCDF longwave variable
in remora.nc_frc_file

String

lwrad

remora.blk_ZQ

Height [m] of atmospheric

humidity memasurements for

bulk fluxes parametrization

Real number

10.0

remora.blk_ZT

Height [m] of atmospheric

temperature memasurements

bulk fluxes parametrization

Real number

10.0

remora.blk_ZW

Height [m] of atmospheric wind

memasurements for bulk fluxes

parametrization

Real number

10.0

remora.cloud

Cloud cover fraction (0=clear sky,

1=overcast) (used as uniform

value if cloud_from_netcdf

is false)

Real number

from 0 to 1

0.0

remora.rain

Precipitation rate [kg/m^2/s]

(used as uniform value if

rain_from_netcdf is false)

Real number

0.0

remora.cloud_from_netcdf

Load cloud cover from NetCDF

file (spatially varying)

true / false

false

remora.rain_from_netcdf

Load precipitation rate from

NetCDF file (spatially varying)

true / false

false

remora.EminusP_from_netcdf

Load evaporation minus

precipitation from NetCDF file

(spatially varying)

true / false

false

remora.eminusp

Whether to do E-P prescription for

evaporation/precipiation

true / false

false

remora.eminusp_correct_ssh

Whether to adjust sea surface

height for amount of evaporation

and precipitation

true / false

false

Note

When loading atmospheric forcing variables from NetCDF files (by setting Tair_from_netcdf, qair_from_netcdf, Pair_from_netcdf, srflx_from_netcdf, longwave_down_from_netcdf, rain_from_netcdf, cloud_from_netcdf, or EminusP_from_netcdf to true), these variables are read from the file specified by remora.nc_frc_file (see List of surface forcing parameters). The NetCDF file must contain variables named Tair, qair, Pair, swrad, rain, cloud, and EminusP respectively, with the same spatial dimensions as the model grid. Time interpolation is performed automatically based on the simulation time.

For longwave forcing, the variable name is controlled by remora.longwave_netcdf_varname (default lwrad). If remora.longwave_netcdf_is_net is true, that variable is treated as net longwave radiation and used directly. If false, it is treated as downward longwave radiation and net longwave is computed in the bulk-flux routine using sea-surface temperature and emissivity.

The qair_is_percent flag should be set to true if the relative humidity in the NetCDF file is stored as a percentage (0-100) rather than as a fraction (0-1). This conversion is applied after loading and includes proper ghost cell synchronization.

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 Vertical S-Coordinate.

Climatology parameters

List of Parameters

Parameter

Definition

Acceptable

Values

Default

remora.do_m3_clim_nudg

Whether to nudge 3D

momentum variables

to climatology

true / false

false

remora.do_m2_clim_nudg

Whether to nudge 2D

momentum variables

to climatology

true / false

false

remora.do_temp_clim_nudg

Whether to nudge

temperature

to climatology

true / false

false

remora.do_salt_clim_nudg

Whether to nudge

salinity

to climatology

true / false

false

remora.nc_clim_his_file

NetCDF file name for

climatology data

string

must be set if one of

do_*_clim_nudg

flags is true

remora.nc_clim_coeff_file

NetCDF file name for

climatology nudging

coefficients

string

must be set if one of

do_*_clim_nudg

flags is true

remora.clim_ubar_time_varname

name of time variable

for ubar climatology

string

ocean_time

remora.clim_vbar_time_varname

name of time variable

for vbar climatology

string

ocean_time

remora.clim_u_time_varname

name of time variable

for u climatology

string

ocean_time

remora.clim_v_time_varname

name of time variable

for v climatology

string

ocean_time

remora.clim_temp_time_varname

name of time variable

for temperature

climatology

string

ocean_time

remora.clim_salt_time_varname

name of time variable

for salinity

climatology

string

ocean_time

Rivers (point sources)

These parameters are used to configure NetCDF-specified river-like point sources and sinks.

Parameter

Definition

Acceptable

Values

Default

remora.do_rivers

Whether to do rivers.

Equiavlent to LuvSrc in

ROMS. Sources always

apply momentum

true / false

false

remora.nc_river_file

NetCDF file for river sources

string

must be set if

do_rivers

remora.riv_time_varname

Name of time variable

string

river_time

remora.do_rivers_temp

Whether rivers are

temperature sources

true / false

true; only used

if do_rivers

remora.do_rivers_salt

Whether rivers are

salinity sources

true / false

true; only used

if do_rivers

remora.do_rivers_scalar

Whether rivers are passive

scalar sources

true / false

false; only used

if do_rivers

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