Run-time options¶
Run-time options are read from the inputs file, prob/inputs in each case, when the run starts,
and changing them needs no rebuild. The options that do are on
Compile-time options.
The inputs file¶
The file is a list of name = value lines, grouped by prefix. # starts a comment, and a list
is given as values separated by spaces. Per-direction lists take one value per direction; in 2D a
third value is ignored, so the same line works in 2D and 3D.
amr.n_cell = 64 64 8 # base grid
run.lo_bc = 0 0 4
FiniteVolume.Scheme = "MUSCL-MC"
Any parameter can be overridden on the command line, after the inputs file:
mpirun -n 4 ./main2d.gnu.MPI.ex prob/inputs FiniteVolume.Scheme=WENO5 Physics.RiemannSolver=HLL
In the tables below, defaults are in bold. An unrecognized value stops the run at startup with a
message that lists the valid values. Parameters marked (AMReX) are read by AMReX, and their
defaults and details are in the AMReX documentation.
The inputs files in exec/_Tests/ (prob/inputs, and prob/inputs.<label> in the cases with
several builds) are commented and are a good starting point.
Run length and domain¶
Parameter |
Values |
|---|---|
|
stop after this many coarse steps (no limit) |
|
stop at this physical time (no limit) |
|
lower and upper corners of the domain, one value per direction (AMReX) |
|
|
|
|
The run stops at whichever of max_step and stop_time is reached first.
Grid and AMR¶
Parameter |
Values |
|---|---|
|
base grid, cells per direction |
|
number of refinement levels above the base grid (AMReX) |
|
refinement ratio between successive levels, one value per level (AMReX) |
|
patch sizes are multiples of this (AMReX) |
|
largest patch size (AMReX) |
|
cells added around tagged cells before patches are built (AMReX) |
|
fraction of tagged cells a patch must contain (AMReX) |
|
regrid every N steps ( |
|
coarse–fine interpolation: |
|
AMReX verbosity (AMReX) |
Where to refine is set under Refinement.
From level 2 up, the ghost cells of a patch are filled from the next coarser level, which covers
only part of the domain. That level must extend \(R = \lceil N_g/r\rceil + g\) of its own cells past
the patch. \(N_g\) is the number of ghost cells of the scheme: 1 for GODUNOV, 2 for the MUSCL
schemes, WENO3 and WENO3B, and 3 for WENO5 and WENO5B. \(r\) is the refinement ratio, and \(g\)
is 0 for pc_interp, 1 for lincc_interp and 2 for quartic_interp. The Phase-Field step always
uses lincc_interp for its own ghost cells. AMReX keeps a margin of \(a\lceil n_p/a\rceil\) cells,
where \(a\) is the blocking factor of the finer level divided by \(r\) and \(n_p\) is amr.n_proper
(AMReX, default 1). Choose the blocking factor so that this margin is at least \(R\) in every
direction with a coarse–fine boundary. exec/_Tests/ShuOsher-5Eq sets amr.blocking_factor_x = 8
for this reason: WENO5 with lincc_interp needs a margin of 3, and a blocking factor of 4 gives 2.
Time stepping¶
Parameter |
Values |
|---|---|
|
CFL number ( |
|
|
|
|
|
|
|
stability number of the viscous and conductive fluxes, \(\Delta t =\) |
|
after |
|
|
|
|
The time step is shortened to reach stop_time exactly, and to land on the output times set by
amr.t_write_interval and the output windows (Output).
AMR time stepping. With run.do_subcycle = 1, a level takes \(r\) steps of \(\Delta t/r\) for
each step of the level below (\(r\) the refinement ratio), with its coarse–fine ghost cells
interpolated in time between the old and new states of the coarser level, and the reflux then
replaces the coarse fluxes at the coarse–fine faces by the time average of the fine fluxes. With
run.do_subcycle = 0, all levels take the same \(\Delta t\), set by the finest level, and every
Runge–Kutta stage together: each level fills its ghost cells from the stage state (the
coarse–fine ghost cells by spatial interpolation of the coarser level’s stage state), each level
computes its face fluxes, the coarse faces covered by a finer level take the area-weighted average
of its face fluxes (the conservative fluxes with their viscous parts, and the face
quantities of the non-conservative terms, so that both use the same faces; the same in the
Phase-Field step), and then every level is updated, relaxed (six-equation models) and averaged
down. The update is then conservative at every stage, with no reflux, and it keeps the volume
fractions within \([0, 1]\) at a sharp interface where the reflux after a multistage step does not
(six-equation model). Without subcycling the face fluxes of
all levels are held at once during a stage.
Boundary conditions¶
run.lo_bc and run.hi_bc give one code per direction, for the low and high faces of the
domain.
run.lo_bc = 3 3 4 # x, y, z at the low faces
run.hi_bc = 2 2 4 # x, y, z at the high faces
Code |
Boundary |
Ghost cells |
|---|---|---|
|
interior or periodic |
from the periodic image. Used exactly in the directions with |
|
inflow |
from the case’s user boundary function (Boundary conditions), which the case defines |
|
outflow |
zero gradient |
|
symmetry |
mirror image, with the normal velocity reversed |
|
slip wall |
the same as |
|
no-slip wall |
mirror image, with all velocity components reversed |
The Phase-Field step uses its own conditions on the volume fractions: periodic in the periodic directions and zero gradient elsewhere.
Refinement¶
A cell is tagged for refinement when any criterion of any listed variable is met.
run.refine.ref_vars = a1 P
run.refine.a1.max_level = 10
run.refine.a1.value_range = 0.01 0.99 0.01 0.99
run.refine.P.max_level = 10
run.refine.P.grad = 0.25 0.25
Parameter |
Values |
|---|---|
|
variables used for tagging, any names from Output variables |
|
cells are tagged on levels below this one (every level) |
|
tag where the jump to a neighboring cell is at least this value |
|
tag where the value is greater than this |
|
tag where the value is less than this |
|
tag where the value is strictly between a low and a high value |
The thresholds are given per level, one value per level for grad, value_greater and
value_less, and one pair per level for value_range. Level 0 comes first. A list must cover
every level that is tagged, from 0 to the lower of max_level and amr.max_level, minus one, and
a shorter list stops the run at startup. For a region
fixed in space or time, define spatio_temporal_tag in the case’s ProblemICBC.H
(Refinement in space and time).
Output¶
Parameter |
Values |
|---|---|
|
output folder and prefix. |
|
alternatives to a path in |
|
a plotfile every N coarse steps ( |
|
a plotfile every interval of physical time ( |
|
a list of times in increasing order, a plotfile at the first step that reaches each one. Times reached in the same step give one plotfile, and times already passed at a restart are skipped |
|
number of time windows with their own output interval ( |
|
window |
|
variables written to plotfiles (Output variables). Without the list, the state variables are written |
|
checkpoint prefix ( |
|
a checkpoint every N coarse steps ( |
|
checkpoint to restart from, for example |
|
call the case’s |
|
number of files each level of a plotfile or checkpoint is written to in parallel (AMReX’s default when unset) |
|
|
|
|
|
|
|
index of that state variable, in the order of Output variables ( |
The cases set amr.plot_int to a large number together with amr.t_write_interval, which keeps
the plotfiles at the start and the end of the run. UserOutputFunction exists only when the case
defines USER_OUTPUT_FUNC (In-situ diagnostics).
A run also writes config_log_<case>.txt in the output folder, with the build information, the
run-time parameters and copies of the case files.
To restart, give the checkpoint and, if needed, a new stop time:
mpirun -n 4 ./main2d.gnu.MPI.ex prob/inputs amr.restart=./checkpoints/chk00500 stop_time=2.0
Output variables¶
These names are used by run.output_vars and run.refine.ref_vars. \(k\) runs over the phases,
for example a1rho1 a2rho2 a3rho3. The state variables come first, in the order of the state
vector, and are written when run.output_vars is not given. rho_w is a state variable in 3D
only. In 2D, rho_w and w can still be named, and are zero.
|
State variables |
Derived variables |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
P is the mixture pressure, T the temperature, c the mixture sound speed and Mach the
Mach number. a1P1 and a2P2, and a<k>p<k>, are \(\alpha_kP_k\). In the N-phase models,
Phase is \(\sum_k k\,\alpha_k\) and PhaseSq is \(\sum_k \alpha_k^2\).
vorticity_mag is \(\lvert\nabla\times\vec u\rvert\), q_criterion is
\(Q = \tfrac12\left(\lVert\Omega\rVert^2 - \lVert S\rVert^2\right)\) and lambda2 is the middle
eigenvalue of \(S^2 + \Omega^2\), where \(S\) and \(\Omega\) are the symmetric and antisymmetric parts
of \(\nabla\vec u\). They are computed from central differences of \(\vec u\), only when requested,
and can also drive refinement through run.refine.ref_vars.
Numerics¶
Parameter |
Values |
|---|---|
|
|
|
|
|
|
|
THINC steepness \(\beta\) ( |
|
THINC is used only in cells with |
|
|
|
( |
|
|
|
|
|
|
|
|
|
|
|
|
FiniteVolume.Quad = 1 requires FiniteVolume.Scheme = WENO5 and FiniteVolume.ID_Bound = 0,
which the run checks at startup. THINC reconstructs the volume fractions at the interfaces and the
scheme set by FiniteVolume.Scheme is used elsewhere. It is available for every model.
FiniteVolume.THINC.Multi, FaceState and PhaseDensity are implemented for FIVEEQS and
FIVEEQS_NPHASE; the six-equation models stop at startup if any of them is not 0. The defaults,
all three 0, give the one-dimensional THINC, which works along each direction. For the five-equation
models we recommend all three at 1. The multi-dimensional face average keeps curved interfaces
from faceting along the grid directions and stops most of the break-up of interfaces nearly
aligned with the grid, and the face state of the base scheme keeps the velocity and pressure from
switching between the base scheme and minmod at THINC faces. Set PhaseDensity = 1 whenever
FaceState = 1: near an interface the ratio of the face values of the base scheme can be far from
the phase density. With Multi = 1 the default NormalThreshold = 0.25 keeps curved interfaces
rounder than 0.4. The cases that use these options set them in their prob/inputs. Known limits:
sheets and filaments a cell or two wide can still break into beads; with FaceState = 1 a
strongly sheared interface can carry short waves at the scale of the grid, and a mixed cell where
an interface meets a wall at a sharp corner can keep a spurious low pressure for a short time.
The bound-preserving limiter, FiniteVolume.ID_Bound = 1, applies to the five-equation models.
In SIXEQS and SIXEQS_IE_NPHASE the bounds on \(\alpha_k\) and \(\alpha_k\rho_k\) come from
WENO3B and WENO5B.
Physics¶
Parameter |
Values |
|---|---|
|
|
|
set |
|
|
|
|
|
|
What these terms do is on Models and equations.
Phase-Field¶
Parameter |
Values |
|---|---|
|
|
|
|
|
|
|
interface width \(\eta\) in units of the cell size at |
|
a positive value sets \(\eta\) directly and overrides |
|
factor on the CAC and Cahn–Hilliard terms ( |
|
CFL number of the Phase-Field substeps ( |
|
largest number of Phase-Field substeps per time step ( |
|
the Phase-Field step starts once the coarse step and the time reach these values ( |
After each time step of the model, the Phase-Field terms are advanced over the same interval in
substeps limited by PhaseField.cfl. The flux-based mechanisms are CDI, ACDI, CH and their
variants; the CAC mechanisms are implicit only (PhaseField.ID_ExplicitRC = 0). The mechanisms
and the role of \(\eta\) are described under
Phase-Field mechanisms.
With adaptive mesh refinement (amr.max_level above 0), use a PhaseField.Eta_Multiplier of
0.25 to 0.5 with the implicit CAC-Adv mechanism, as the cases provided that turn Phase-Field on
do. On a single level, values up to the default of 1.0 can be used.
include/Physics_PhaseField/PhaseField_Parameter.H also reads Eta_Factor,
ID_DegenerateMobility, ID_Potential, ID_Weight, ID_Flux, ID_FluxPhase2Flux and
ID_Formulation, which select variants of the discretization. Leave them at their defaults
unless you are working on the method.
Linear solver¶
The implicit Phase-Field treatment solves a linear system with the AMReX multigrid solver
(MLMG). Its parameters have the prefix LinearSystem.
Parameter |
Values |
|---|---|
|
relative and absolute tolerances ( |
|
iteration limits ( |
|
solver output ( |
|
|
|
|
|
largest order of the boundary interpolation of the operator ( |
|
MLMG coarsening options ( |
|
( |
|
( |
The case templates change four of these defaults in Parm.H, to max_iter = 10000,
max_fmg_iter = 10000, fixed_iter = 10000 and verbose = 1. A value in the inputs file
takes precedence over both.
Equation of state and materials¶
prob.EOS.EOS selects the equation of state for all phases. The forms are given under
Notation and equations of state.
Parameter |
Values |
|---|---|
|
|
The two-phase models, FIVEEQS and SIXEQS, read one value per phase with the suffixes _1
and _2:
Parameter |
Symbol |
Used by |
Default |
|---|---|---|---|
|
\(\gamma_k\), must be greater than 1 |
EOS |
none, must be given |
|
\(P_{\infty,k}\) |
EOS |
|
|
\(b_k\), covolume, must be 0 or positive |
EOS |
|
|
\(q_k\), heat of formation |
EOS |
|
|
\(\Gamma_k\), must be positive |
EOS |
|
|
\(p_{\mathrm{ref},k}\) |
EOS |
|
|
\(e_{\mathrm{ref},k}\) |
EOS |
|
|
\(c_{v,k}\) |
temperature |
|
|
\(\mu_k\), shear viscosity |
|
|
|
\(\mu_{B,k}\), bulk viscosity |
|
|
|
\(\kappa_k\), thermal conductivity |
|
|
The N-phase models, FIVEEQS_NPHASE and SIXEQS_IE_NPHASE, read lists with one value per
phase, for example prob.EOS.gamma = 1.4 1.6 4.4. The names are prob.EOS.gamma, pinf,
gGamma, pref, eref, b, q, cv, mu, muB and kappa. A list that is given must have
exactly NPHASE values. A list that is not given is zero, including cv, so give cv whenever
the temperature is used.
The covolume and the heat of formation (b_1, b_2, q_1, q_2, or the lists b and q)
are read only with EOS 3, in the units of the case. With \(b = q = 0\) EOS 3 is the stiffened
gas. With EOS 3, FiniteVolume.Quad = 1 is not available.
At startup the run checks that each per-phase list has NPHASE values, that each \(\gamma_k\) is
greater than 1 with EOS 0, 1 or 3, that each \(b_k\) is 0 or positive with EOS 3, and that
each \(c_{v,k}\) is positive where the solver needs the temperature: with -DDIFFUSION=true, and in
SIXEQS with Physics.pressure_temperature_relaxation = 1. Its message names the parameter.
Every other prob.* parameter belongs to the case and is read by its Parm.H
(Parm.H).
Convergence studies¶
With CONVERGENCE defined as true in the case’s ProblemICBC.H, COMPAS compares the solution
at the end of the run with the case’s exact solution and writes the \(L_2\) and
\(L_\infty\) errors of every state variable (Exact solution).
Parameter |
Values |
|---|---|
|
the errors are written to this name with |
|
a label written at the top of that file (empty) |
scripts/convergence.py sets these and runs a case over several resolutions
(Convergence script).