Adaptive Mesh Refinement Module

The amr module refines and coarsens the mesh using solution sensors or geometric regions. It can adapt the initial mesh or adapt between physical time steps and transfer the solution to the new mesh.

Basic Setup

Load amr, select a sensor, and allow a positive number of adaptations. Add the module load before the run-control block and these settings inside it:

loadModule: amr
{
  adaptSensor: Perror, Uerror
  adaptStart: 100
  adaptFrequency: 100
  maxAdaptSteps: 3
}

This example checks pressure and velocity sensors every 100 physical time steps, starting at step 100, and permits up to three adaptations. A mesh change occurs only when cells are marked. There is no default sensor; geometric regions can also request refinement.

Adaptation Timing

Timing controls

Input	Default	Meaning
adaptStart	100	First physical time-step number eligible for runtime adaptation
adaptFrequency	100	Interval between runtime checks; 0 disables runtime adaptation
maxAdaptSteps	0	Maximum adaptations, including initial adaptation; 0 disables adaptation
adaptInitializationSteps	0	Maximum adaptations before time stepping; must not exceed maxAdaptSteps

Runtime checks occur at multiples of adaptFrequency at or after adaptStart. For example, adaptStart: 150 and adaptFrequency: 100 make step 200 the first eligible check.

Initial Adaptation

To adapt before advancing the solution, set adaptInitializationSteps. For two initial adaptations with no subsequent runtime adaptation:

adaptSensor: Rerror
adaptInitializationSteps: 2
maxAdaptSteps: 2
adaptFrequency: 0

Initial conditions are reevaluated on each new mesh. Keep their source data available, including regional or PuT input data, and set numTimeSteps to a positive value. Adaptation stops at the limit or when no cells are marked.

To allow later runtime adaptation, increase maxAdaptSteps and use a positive adaptFrequency. adaptStart applies only to runtime checks.

Solution Sensors

adaptSensor accepts a comma-separated list. Sensors measure jumps between neighboring cells and require the corresponding solution fields.

Sensors

Sensor	Measures	Units
Perror	Pressure jump	Pa
Rerror	Density jump	kg/m3
Uerror	Velocity-jump magnitude	m/s
Terror	Temperature jump	K
Yerror	Species mass-fraction vector jump; requires species transport	Dimensionless
YspeciesError	One species mass-fraction jump; requires species transport	Dimensionless

For YspeciesError, select a species by name:

adaptSensor: Perror, YspeciesError
adaptSpeciesName: O2

The name must appear in the simulation’s species list. If omitted, the first species is used.

Each sensor is normalized by subtracting its mesh-wide mean and dividing by its standard deviation. Constant sensors contribute zero. Each cell uses the largest normalized value among its selected sensors.

Statistical refinement and coarsening

Input	Default	Meaning
adaptSensitivity	1.0	Refine above this normalized threshold; lowering it selects more cells
coarsenSensitivity	0.5	Coarsen below the negative of this threshold; increasing it selects fewer cells

Both thresholds are dimensionless. coarsenSensitivity: 0 does not disable coarsening. Size limits and regional controls can restrict requests; coarsening also requires compatible groups of previously refined cells. For coarsening based on absolute sensor limits, see Coarsening Tolerances.

Mesh Controls

Mesh settings

Input	Default	Meaning
adaptMode	anisotropic	anisotropic, isotropic, or 2D; 2D is for layered meshes in the x-y plane
adaptMinEdgeLength	1e-6	Positive minimum cell size in meters; suppresses refinement at or below this size
adaptCellSizeMetric	edge	edge uses a face-edge estimate; diameter uses the greatest vertex separation, projected onto XY in 2D mode
maxAdaptCellCount	-1	Target cell count in millions; fractional values allowed. Zero or negative disables the limit.
adaptFaceFold	1.5708	Positive face-fold threshold restricting refinement of highly twisted faces
adaptBalanceType	0	0, 1, or 2; higher values impose additional face-splitting constraints

adaptMinEdgeLength limits refinement of current cells; newly created cells can be smaller. diameter avoids size underestimation from subdivided faces. Adjust size targets when changing metrics: a cube of side h has diameter sqrt(3)*h, or sqrt(2)*h in 2D mode.

maxAdaptCellCount: 0.5 targets 500,000 cells across all refinement sources. Requests with target sizes take priority. Mesh balancing can exceed this target.

Solution Transfer

adaptInterpolationOrder controls transfer to child cells after runtime adaptation. It is separate from the flow solver’s spatial discretization.

Transfer order

Value	Effect
1	Each child receives its parent’s value
2 (default)	Limited linear reconstruction from the parent cell

Coarsening uses volume-weighted averaging for either order. Physics modules must support transfer of their solution fields and may supply their own methods; see Model-Specific Options.

Cell transfer does not preserve face-flux history. BDF2 uses one first-order step after each runtime remesh before resuming second order.

Restart and Output

Restart

AMR checkpoints restore the adapted mesh and solution. Keep amr loaded, set adaptInitializationSteps: 0, and retain the complete restart directory. Keep the original VOG and grid options unchanged. For example:

stream -q solution case 200

Output Variables

Request AMR fields with plot_output:

plot_output: refFlag, combinedErrorFactor

AMR fields

Variable	Meaning
refFlag	Request after size masks and the cell budget, before mesh balancing: 1 refine, -1 coarsen, 0 unchanged
combinedErrorFactor	Combined normalized sensor value
amrPolicy	Active region ID; 0 means global settings. The log maps IDs to names.
amrMinSize	Effective minimum cell size, m
amrRefineThreshold	Effective refinement sensitivity
amrCoarsenThreshold	Effective statistical coarsening sensitivity
amrCoarsenBlocked	1 where a sensor vetoes tolerance-based coarsening, 0 otherwise

All fields are optional. Each node reports the maximum adjacent cell value.

Post-Processing

Use the standard output controls. Keep field, topology, and grid-position files together in output/; extract selects the matching mesh:

extract -vtk case 200

When old and new meshes share an output label, the old output receives an _amrN suffix. N identifies the mesh, starting at zero. To extract the original-mesh output preserved at step 200:

extract -vtk case 200_amr0

With plot_output_iteration: on or nonzero plot_modulo, retained numeric output labels are preserved at each mesh change. These frames and mesh files are outside the plot_modulo limit and consume additional disk space. Rerunning resets mesh numbering and can overwrite output; retain previous runs in separate directories.

Regional Controls

Region controls accept inBox(p1=...,p2=...) and inSphere(center=...,radius=...) with length units. Regions stay fixed in physical coordinates and select cells by their current centers. Boxes must span all three directions, including the thickness of layered 2D meshes. Coordinates and radii must be finite; radii must be positive. Box boundaries are included; sphere boundaries are excluded.

Target Sizes

adaptRegionRequests requests refinement to a target size without a solution sensor. For a 1 mm wake region:

adaptRegionRequests: <
    wake=[region=inBox(p1=[15 mm,-12 mm,-1 mm],p2=[80 mm,12 mm,3 mm]),
          edgeLength=1 mm]
>

Region request entries

Entry	Default	Meaning
region	Required	Box or sphere
edgeLength	Required	Positive, finite target size measured with adaptCellSizeMetric
volumeTags	All cells	Restrict to named mesh volumes, for example [background]

Several named regions may be supplied. Names must start with a letter and contain only letters, digits, or underscores. Volume-tag lists must contain distinct existing names. These naming rules also apply to regional overrides.

Regions request refinement when the selected size exceeds the target. Minimum sizes and adaptation budgets still apply, so reaching the target may require several adaptations. These requests do not coarsen cells.

Refinement and Coarsening Restrictions

adaptIncludeRegions permits selected actions only inside its regions; adaptExcludeRegions blocks them inside its regions. For example:

adaptIncludeRegions: <
    regions=[inBox(p1=[0 m,0 m,0 m],p2=[1 m,1 m,1 m])],
    actions=[refine,coarsen]
>
adaptExcludeRegions: <
    regions=[inSphere(center=[0.5 m,0.5 m,0.5 m],radius=0.1 m)],
    actions=[refine,coarsen]
>

actions defaults to [refine]; it also accepts [coarsen] or [refine,coarsen]. Exclusion takes precedence over inclusion. Restrictions apply to all request sources, but mesh balancing can refine neighboring cells outside the permitted regions.

Sensor and Size Overrides

Use adaptRegionControls to override global settings in named regions:

adaptSensor: Perror
adaptMinEdgeLength: 0.001
adaptRegionControls: <
    shearLayer=[region=inBox(p1=[0 m,-10 mm,-1 mm],p2=[100 mm,10 mm,1 mm]),
                sensors=[Uerror,Rerror],minSize=0.2 mm,
                adaptSensitivity=0.8,coarsenSensitivity=0.3]
>

Regional override entries

Entry	Default	Meaning
region	Required	Box or sphere
volumeTags	All cells	Restrict to named mesh volumes
priority	0	Integer; highest priority wins in overlaps. Equal highest priorities are errors.
sensors	Global selection	Distinct sensor names replacing the global selection; none disables sensor requests
minSize	adaptMinEdgeLength	Positive, finite minimum size with length units, using adaptCellSizeMetric
adaptSensitivity	Global value	Finite, nonnegative refinement threshold
coarsenSensitivity	Global value	Finite, nonnegative statistical coarsening threshold
coarsenMode	Global value	statistical or tolerance; see Coarsening Tolerances
coarsenTolerances	Global limits	Per-sensor overrides, for example [Uerror=0.005,Rerror=0.01]

Outside regions, and for omitted entries or per-sensor tolerances, global settings apply. Sensor normalization and species/material selections remain global. minSize limits refinement from all sources; it does not request refinement. Geometric requests remain active with sensors=none.

Coarsening Tolerances

The default coarsenMode is statistical, using coarsenSensitivity. Select tolerance to coarsen only when every selected sensor’s magnitude is at or below its specified limit:

adaptSensor: Perror, Uerror
coarsenMode: tolerance
coarsenTolerances: <Perror=10, Uerror=0.01>

The example limits are 10 Pa and 0.01 m/s. Limits use the sensor units before normalization or weighting. Each selected sensor needs a finite, nonnegative limit; zero permits only an exactly zero sensor. coarsenSensitivity is unused in this mode.

Refinement still uses adaptSensitivity and takes precedence. A sensor above its limit also blocks coarsening requested by geometry or distance controls. With no selected sensors, those controls remain active.

Model-Specific Options

Compressible Gas

For the base gas solver (eos_type: gas), cell-state transfer conserves species mass, momentum, and total energy when using total energy or total enthalpy on fixed Cartesian meshes, with double flux off, no axisymmetry, and no interface boundaries. This transfer is selected automatically; other configurations use independent-field or module-specific transfer. Turbulence scalars are transferred independently.

The transferred state must have nonnegative species densities, positive total density, and temperature within TclipMin and TclipMax. If second-order transfer violates these bounds, Stream retries at first order. Failure at first order stops the run; energy is not clipped.

Overset Meshes

To refine near overset component surfaces, provide the component geometry and set adaptGeometryEdgeLength:

Overset geometry controls

Input	Default	Meaning
adaptGeometryEdgeLength	Not set	Target cell size near component surfaces, m, using adaptCellSizeMetric
adaptGeometryLayers	8	Thickness of the transition from the target size to coarser cells

For rigid overset motion, use momentumInterpolationOptions: <form=old> and BDF or BDF2. Deforming meshes, automatic overlap protection, and conservative phase transport across overset interfaces are unsupported. Sensors sample solved cells only, excluding fringe and hole cells.

Cavitation

For cavitation, use SIMPLEC and the following settings with the basic AMR controls:

loadModule: cavitation_nist
loadModule: amr
{
  pressureBasedMethod: SIMPLEC
  momentumInterpolationOptions: <form=old>
  adaptInterpolationOrder: 1
}

The module transfers vapor and NCG mass fractions, optional transported nuclei, and BDF2 history. First-order transfer preserves parent composition when cells split; it does not guarantee phase-mass conservation.