Problem Setup

To setup a new problem you must specify:

initial conditions
resolution
problem geometry
boundary conditions
AMR tragging criteria (for multilevel runs only)

Many additional options are available, and are briefly described here and in following sections, Runtime Options and Algorithm Options.

Units

IAMR supports any self-consistent units, as long as the length, time, and mass are consistent with the viscosity and diffusivity.

Initial Conditions

To define the initial conditions, we modify the function prob_initData() within IAMR/Source/prob/prob_init.cpp. prob_initData() reads in initial conditions and problem parameters from the inputs file, and initializes the state data (velocity, density, etc.). The easiest way to get started is to create a new probtype by copying the code for an existing problem and modifying it to apply the desired initial state.

IAMR’s make system puts the build directory ahead of IAMR/Source in its search path, so a problem directory may override any IAMR source file simply by placing its own copy of that file alongside its GNUmakefile. This is the mechanism to use for a problem that needs its own initial conditions (prob_init.cpp) or its own forcing function (NS_getForce.cpp).

The problem is selected with prob.probtype. The values recognized by the default Source/prob/prob_init.cpp are

probtype	Initial state	Example deck
1	Fluid at rest with constant density	LidDrivenCavity
2	Density blob (bubble or drop) in a constant background	Bubble
3	Smoothed density/tracer jump normal to x, plus a tracer blob	–
4	Constant velocity and density with a tracer blob	TracerAdvection, Poiseuille, FlowPastCylinder
5	Double shear layer	DoubleShearLayer, Particles
6	As probtype 2, but with temperature as a state variable	HotSpot
7	Euler vortex tube in a triply periodic domain	Exec/run3d/regtest.3d.euler
8	Convected vortex	ConvectedVortex
10	Rayleigh-Taylor instability	RayleighTaylor
11	Taylor-Green vortex	TaylorGreen

Any other value aborts. Note that 9 is not used, and that a problem directory that supplies its own prob_init.cpp, as described above, defines its own set of values.

The initial state is parameterized by the following, which must be preceded by “prob.” Which of them a given probtype actually reads varies; see prob_init.cpp.

	Description	Type	Default
density_ic	Background density	Real	1.0
velocity_ic	Background velocity, one value per coordinate direction	Reals	0
direction	Coordinate direction used by direction-dependent setups	Int	0
interface_width	Width over which density and tracer jumps are smoothed	Real	1.0
blob_center	Centre of the density/tracer blob, one value per direction	Reals	0
blob_radius	Radius of the density/tracer blob	Real	0.1
rho_1, rho_2	Densities on either side of the interface (probtypes 3 and 10)	Real	1.0, 2.0
tra_1, tra_2	Tracer values on either side of the interface (probtypes 3 and 10)	Real	0.0, 1.0
perturbation_amplitude	Amplitude of the interface perturbation (probtype 10)	Real	1.0
velocity_factor	Another name for the first component of velocity_ic; it is the velocity scale V_0 of the Taylor-Green vortex (probtype 11)	Real	0.0
a, b, c	Problem-specific coefficients (probtype 11)	Real	1.0
xvort, yvort, rvort	Centre and radius of the convected vortex (probtype 8). These override a, b and c, which probtype 8 resets before reading them.	Real	0.5, 0.5, 0.07
forcevort	Strength of the convected vortex (probtype 8)	Real	6.0
meanFlowDir	Direction of the mean flow the vortex is convected by (probtype 8). 0 = no mean flow; +/-1, +/-2, +/-3 = mean flow along x, y, z; +/-4 = diagonal mean flow in the x-y plane. +/-3 requires 3D.	Int	0
meanFlowMag	Magnitude of that mean flow (probtype 8)	Real	0.0

It is also possible to initialize the velocity using data from a previously generated plotfile. To do this you must set USE_VELOCITY=TRUE in the makefile (which in turn defines the BL_USE_VELOCITY compiler macro), and provide the plotfile in the inputs file via ns.velocity_plotfile = my_plotfile_name.

Resolution

The grid resolution is specified by defining the resolution at the coarsest level (level 0), the number of refinement levels, and factor of refinement between levels. The following inputs must be preceded by “amr.”

	Description	Type	Default
n_cell	Number of cells at level 0 in each coordinate direction	Int Int Int	None
max_level	Maximum level of refinement allowed (0 when single-level)	Int	None
ref_ratio	Ratio of coarse to fine grid spacing between subsequent levels (2 or 4)	Int	None

Some examples:

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. (If this line appears in a 2D inputs file then the final number will be ignored.)

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 4

would set factor of 2 refinement between levels 0 and 1, and factor of 4 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).

Problem Geometry

The following inputs must be preceded by “geometry.”

	Description	Type	Default
coord_sys	0 for Cartesian	Int	0
is_periodic	1 for true, 0 for false (one value for each coordinate direction)	Ints	0 0 0
prob_lo	Low corner of physical domain (physical not index space)	Reals	None
prob_hi	High corner of physical domain (physical not index space)	Reals	None

As an example, the following:

geometry.prob_lo = 0 0 0
geometry.prob_hi = 10.0 10.0 10.0
geometry.coord_sys = 0
geometry.is_periodic = 0 1 0

defines the domain to run from \((0,0,0)\) at the lower left to \((10,10,10)\) at the upper right in physical space, specifies a Cartesian geometry, and makes the domain periodic in the \(y\)-direction only.

Domain Boundary Conditions

IAMR provides two ways to specify boundary condition types: integer keys or keywords. An inputs file must choose one style or the other, they cannot be mixed. Here we provide examples of both styles. We then discuss how to provide Dirichlet boundary conditions. For a more detailed discussion of boundaries, see Boundaries

Boundary conditions with integer keys

To specify boundary conditions with integer keys we use

ns.lo_bc: boundary type of each low face
ns.hi_bc: boundary type of each high face

The valid boundary types are:

0 – Interior / Periodic	3 – Symmetry
1 – Inflow	4 – Slip Wall
2 – Outflow	5 – No Slip Wall

Note: ns.lo_bc and ns.hi_bc must be consistent with geometry.is_periodic—if the domain is periodic in a particular direction then the low and high bc’s must be set to 0 for that direction.

As an example, the following:

ns.lo_bc = 1 4 0
ns.hi_bc = 2 4 0

geometry.is_periodic = 0 0 1

would define a problem with inflow (1) in the low- \(x\) direction, outflow (2) in the high- \(x\) direction, slip wall (4) on the low and high \(y\)-faces, and periodic in the \(z\)-direction.

Boundary conditions with keywords

To specify boundary conditions with keywords, we use the following options preceded by “xlo”, “xhi”, “ylo”, “yhi”, “zlo”, and “zhi”:

Description

Type

Default

type

Used to define boundary type. Available options include:

‘po’ or ‘pressure_outflow’
‘mi’ or ‘mass_inflow’
‘sw’ or ‘slip_wall’
‘nsw’ or ‘no_slip_wall’

String

None

To use the same example problem as above, the following:

xlo.type = mi
xhi.type = po
ylo.type = sw
yhi.type = sw

geometry.is_periodic = 0 0 1

would define a problem with inflow in the low-\(x\) direction, outflow in the high-\(x\) direction, slip wall on the low and high \(y\)-faces, and periodic in the \(z\)-direction. Note that no keyword is needed for a periodic boundary, here only the specification in geometry.is_periodic is needed.

Dirichlet Boundary Conditions

IAMR provides the ability to specify constant Dirichlet BCs in the inputs file. We use the following options preceded by “xlo”, “xhi”, “ylo”, “yhi”, “zlo”, and “zhi”:

	Description	Type	Default
velocity	Sets boundary velocity for mass inflows	Real	None
density	Sets boundary density for mass inflows	Real	None
tracer	Sets boundary tracer concentration for mass inflows	Real	None
temp	Sets temperature for mass inflows	Real	None
pressure	Read only for pressure outflows, where it must be 0 (a non-zero value is not yet implemented). Pressure inflows are not yet implemented.	Real	None

As an example,

xlo.type                =   "mass_inflow"
xlo.velocity            =   1.  0.  0.
xlo.density             =   1.
xlo.tracer              =   0.
xlo.temp                =   1.

sets the boundary condition type at the low x face to be an inflow with xlo.type = “mass_inflow”. Then xlo.velocity = 1. 0. 0. sets the inflow velocity, xlo.density = 1. sets the inflow density, xlo.tracer = 0. sets the inflow tracer value, and xlo.temp = 1. sets the inflow temperature. Another example, from the lid driven cavity problem setup, is

ns.lo_bc                =  4 4 5
ns.hi_bc                =  5 5 5

# 0 = Interior/Periodic  3 = Symmetry
# 1 = Inflow             4 = SlipWall
# 2 = Outflow            5 = NoSlipWall

# Boundary condition
zhi.velocity            =   1.  0.  0.

Here, ns.hi_bc = 5 5 5 sets the boundary conditions on all high faces to no slip walls. zhi.velocity = 1. 0. 0. sets the wall at the high z face to be moving in the x-direction. Note that IAMR allows walls to move tangentially, but not in the normal direction.

Users can create more complex Dirichlet boundary conditions by writing their own fill function in NS_bcfill.H, then using that function to create an amrex::StateDescriptor::BndryFunc object and specifying which variables will use it in NS_setup.cpp. More information on boundary conditions is in section Physical Boundaries.

Tagging criteria for creating AMR Levels

If amr.max_level is greater than zero, then user specified tagging criteria are used to define regions for higher levels of refinement. For information on tagging see Tagging for Refinement

Constructing Embedded Boundaries

IAMR uses AMReX’s Embedded Boundary (cut cell) functionality to represent internal or external geometry in the flow. For details on AMReX’s approach to embedded boundaries, see the AMReX EB documentation (Embedded Boundaries).

Here we present a brief example of how to create an embedded boundary (EB) in IAMR. Additional examples and information are in AMReX’s documentation (Initializing the Geometric Database).

Create a new geom_type in the function initialize_eb2 in the file Source/NS_init_eb2.cpp

Construct an implicit function representing the geometry (using the language of constructive solid geometry). For example

amrex::EB2::CylinderIF my_cyl(radius, height, direction, center, inside);
auto gshop_cyl = amrex::EB2::makeShop(my_cyl);

Call amrex::EB2::Build. This function builds the EB levels and fills the implicit function MultiFab (the later being used to construct the level-set function).

Particles Initialization

Particles are initialized from an ASCII file, identified in the IAMR inputs file:

particles.particle_init_file = particle_file

Here particle_file is the user-specified name of the file. The first line in this file is assumed to contain the number of particles. Each line after that contains the position of the particle as x y z

Tracers

IAMR includes one tracer field by default. A second tracer can be added with ns.do_trac2 = 1. IAMR can include additional tracers with only minor code modification: adding them to the state variables in NS_setup.cpp and providing initial conditions.

Temperature

IAMR has the option to solve for temperature, along with a modified divergence constraint on the velocity field (for more information, see Fluid Equations). To include temperature, you must specify two flags, both preceded by “ns.”:

	Description	Type	Default
do_temp	If equal to 0, do not include temperature in the equation set	int	0
temp_cond_coef	Thermal diffusivity divided by specific heat at constant pressure	Real	None

Physics Parameters

IAMR provides support for gravity, viscosity, and diffusivity. Default treatment is given in the table below. More sophiticated treatments are possible; if interested, please open an issue on github: https://github.com/AMReX-Fluids/IAMR/issues

The following inputs must be preceded by “ns.” For information on units, see Units.

	Description	Type	Default
gravity	Gravity, taken to be in the -y direction for 2d and -z direction in 3d	Real	0
vel_visc_coef	Scalar viscosity	Real	None
scal_diff_coefs	Diffusivity of tracer(s). Must specify one value for each tracer.	Real	None