Adaptive Mesh Refinement Module

The amr module refines and coarsens the mesh using solution sensors and geometric regions. Runtime adaptation occurs between physical time steps and transfers the solution to the new mesh. Physics modules used with AMR must support transfer of their solution fields.

Control File Setup

To enable solution-based adaptation, specify one or more sensors and a positive value of maxAdaptSteps. The following example allows up to three adaptations, with the first check at time step 100 and subsequent checks every 100 time steps:

loadModule: amr
{
  ... standard run control file content

  adaptSensor: Perror, Uerror
  adaptStart: 100
  adaptFrequency: 100
  maxAdaptSteps: 3
}

Cavitation

The cavitation_nist module transfers vapor and noncondensable-gas mass fractions, the optional transported bubble population, and BDF2 history during AMR. Use SIMPLEC and momentumInterpolationOptions: <form=old>. Runtime AMR with cavitation and PIMPLE is unsupported.

loadModule: cavitation_nist
loadModule: amr
{
  ... cavitation run control file content

  momentumInterpolationOptions: <form=old>
  adaptSensor: Rerror
  adaptStart: 100
  adaptFrequency: 100
  maxAdaptSteps: 3
  adaptInterpolationOrder: 1
}

adaptInterpolationOrder: 1 preserves parent composition when cells split. Cell-field transfer does not guarantee phase-mass conservation.

Solution Sensors

adaptSensor accepts a comma-separated list of sensor names. Each sensor requires its solution variable to be available.

Solution Sensors for the AMR Module
Sensor	Description
`Perror`	Pressure variation.
`Rerror`	Density variation.
`Uerror`	Velocity variation.
`Terror`	Temperature variation.
`Yerror`	Variation of the full species mass-fraction vector. Requires species transport.
`YspeciesError`	Variation of one species mass fraction. Requires species transport; the species is selected with `adaptSpeciesName`.

For example, to use pressure and the mass fraction of oxygen as refinement criteria:

adaptSensor: Perror, YspeciesError
adaptSpeciesName: O2

The species name must match a name in the simulation’s species list. If adaptSpeciesName is omitted, YspeciesError uses the first species in that list.

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, so sensitivity thresholds are dimensionless.

Sensor Sensitivity Controls
Variable	Default	Description
`adaptSensitivity`	`1.0`	Cells with a combined normalized sensor value above this threshold are candidates for refinement.
`coarsenSensitivity`	`0.5`	In statistical mode, cells below the negative of this normalized threshold are candidates for coarsening.

Lowering adaptSensitivity admits more refinement candidates. Increasing coarsenSensitivity makes coarsening more restrictive; setting it to zero does not disable coarsening. Cell-size and mesh-size controls may further restrict refinement. Coarsening also requires a compatible group of previously refined cells, so a coarsening request does not necessarily reduce the cell count.

There is no default solution sensor. Select sensors or geometric refinement regions to request adaptation.

Tolerance-Based Coarsening

Set coarsenMode: tolerance to coarsen when every selected sensor’s magnitude is at or below its specified limit. Refinement continues to use adaptSensitivity and takes precedence. The default mode is statistical.

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

These limits are 10 Pa for the pressure jump and 0.01 m/s for the velocity jump. Limits apply before normalization or weighting; Rerror uses kg/m³, Terror uses K, and species sensors are dimensionless. Each selected sensor requires a finite, nonnegative limit. Zero permits only an exactly zero sensor. coarsenSensitivity is unused in tolerance mode.

A sensor above its limit also blocks coarsening requested by geometry or distance controls. With no selected sensors, those controls remain active. Coarsening still requires compatible siblings and passes through the other protection masks. Add amrCoarsenBlocked to plot_output to inspect the sensor veto.

Regional Sensor Controls

Use adaptRegionControls to set sensors, sensitivities, and minimum cell sizes by region:

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 Control Entries
Entry	Default	Meaning
`region`	Required	`inBox` or `inSphere`.
`volumeTags`	All cells	List of mesh volume-tag names restricting the region.
`priority`	`0`	Integer priority for overlaps; highest wins. Equal highest priorities are errors.
`sensors`	Global selection	List of distinct sensor names replacing the global selection; `none` disables sensor-based requests.
`minSize`	`adaptMinEdgeLength`	Positive, finite minimum size for refinement, with length units, measured using `adaptCellSizeMetric`.
`adaptSensitivity`	Global value	Refinement sensitivity; finite and zero or greater.
`coarsenSensitivity`	Global value	Coarsening sensitivity; finite and zero or greater.
`coarsenMode`	Global value	`statistical` or `tolerance`.
`coarsenTolerances`	Global limits	Per-sensor overrides, for example `[Uerror=0.005,Rerror=0.01]`. Omitted sensors inherit their global limits.

Outside all regions, global settings apply. Omitted entries in the selected region use global values. Sensors retain mesh-wide normalization; species and CMIM material selections also remain global.

minSize limits refinement from all sources in the region. Use adaptRegionRequests below to request refinement to a target size. Geometric requests remain active with sensors=none.

Geometric Regions

Use adaptRegionRequests to request a target cell size inside a named region. No solution sensor is required. For example, request a 1 mm background wake mesh:

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

region and a positive, finite edgeLength are required. Optional volumeTags restricts the region to the listed mesh volume tags. Several named regions can be supplied. Region and source names must start with a letter and contain only letters, digits, and underscores; volume-tag lists must contain distinct existing names.

Cells inside a region request refinement when their size exceeds edgeLength by more than a relative tolerance of 1e-8, using adaptCellSizeMetric. Minimum sizes, adaptation limits, and the shared cell budget still apply. Multiple adaptations may be needed to reach the target. These regions do not request coarsening.

To restrict requests from all sources, use adaptIncludeRegions and adaptExcludeRegions. For example, permit refinement and coarsening only inside a box, while protecting a sphere inside that box:

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

Inclusion permits the selected actions inside any listed region. Exclusion blocks them and takes precedence where regions overlap. actions defaults to [refine]; use [coarsen] or [refine,coarsen] as needed. Blocked refinement leaves the cell unchanged.

All region controls use current cell centers and regions fixed in physical coordinates, including during motion and remeshing. They accept inBox(p1=...,p2=...) and inSphere(center=...,radius=...) with length units. Boxes must span all three directions, including the thickness of a layered 2D mesh. Coordinates and radii must be finite; radii must be positive. Box boundaries are included; sphere boundaries are excluded.

Mesh balancing may refine neighboring cells outside the permitted regions.

Adaptation Frequency and Limits

All time-step counts refer to physical time steps.

Adaptation Timing Controls
Variable	Default	Description
`adaptStart`	`100`	First physical time-step number at which runtime adaptation is permitted.
`adaptFrequency`	`100`	Interval between runtime adaptation checks. A value of zero disables runtime adaptation.
`maxAdaptSteps`	`0`	Maximum number of adaptations during the run, including initial adaptation. Zero disables adaptation.
`adaptInitializationSteps`	`0`	Maximum number of adaptations before the first physical time step. Must not exceed `maxAdaptSteps`.

Runtime checks occur at time-step numbers that are multiples of adaptFrequency and are at least adaptStart. For example, adaptStart: 150 with adaptFrequency: 100 makes time step 200 the first eligible check. A mesh change is requested only if cells are marked for refinement or coarsening and the adaptation limit has not been reached.

Initial Adaptation

To adapt the initial mesh before advancing the solution, set adaptInitializationSteps to a positive integer. The following example allows up to two initial adaptations and disables subsequent runtime adaptation:

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

Initial conditions are re-evaluated on each new mesh before physical time advances. Initial adaptation stops at the specified limit or when no cells are marked. To allow later runtime adaptation, increase maxAdaptSteps and set a positive adaptFrequency; adaptStart applies only to runtime adaptation.

Initial adaptation can be used with reconstructible initial conditions, including uniform or analytic states, regional initial conditions, and PuT-interpolated initial conditions. The original initial-condition data must remain available throughout the run. Set numTimeSteps to a positive value.

Mesh Controls

Mesh Adaptation Controls
Variable	Default	Description
`adaptMode`	`anisotropic`	Refinement mode: `anisotropic`, `isotropic`, or `2D`. The `2D` mode is for layered meshes in the x-y plane.
`adaptMinEdgeLength`	`1.0e-6`	Positive minimum size, in meters. Suppresses refinement at or below this size, within relative tolerance `1e-8`.
`adaptCellSizeMetric`	`edge`	`edge` uses the face-edge estimate; `diameter` uses the greatest vertex separation, projected onto XY in `2D` mode.
`maxAdaptCellCount`	`-1.0`	Target cell count in millions; fractional values are permitted. Zero or negative values disable the limit.
`adaptFaceFold`	`1.5708`	Positive face-fold threshold used by the remesher to restrict refinement of highly twisted faces.
`adaptBalanceType`	`0`	Mesh-balance option: `0`, `1`, or `2`. Higher values impose additional face-splitting constraints.

Minimum-size settings limit refinement of the current cells; the resulting mesh may contain smaller cells.

diameter avoids size underestimation caused by 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 sets a target of 500,000 cells shared by all refinement sources. Requests with target sizes take priority over other requests. Mesh balancing can exceed this cell-count target.

For overset component-geometry refinement, two additional variables are available:

Overset Geometry Adaptation Controls
Variable	Default	Description
`adaptGeometryEdgeLength`	Not set	Target selected cell size, in meters, near overset component surfaces. Requires the overset component geometry.
`adaptGeometryLayers`	`8`	Controls the thickness of the transition from the target cell size near component surfaces to coarser cells farther away.

For rigid overset motion, use momentumInterpolationOptions: <form=old> and BDF or BDF2. BDF2 takes one first-order step after each remesh. Deforming meshes, automatic overlap protection, and conservative phase transport across overset interfaces are unsupported. Overset sensors sample only solved cells, excluding fringe and hole cells.

Solution Transfer

adaptInterpolationOrder controls cell solution transfer after runtime adaptation:

Solution Transfer Order
Value	Description
`1`	Parent injection: each child cell receives the parent cell’s value.
`2`	Limited linear reconstruction from the parent cell. This is the default.

Coarsening uses volume-weighted averaging for either order. Physics modules may provide their own transfer methods.

The base compressible gas solver (eos_type: gas) uses conservative cell-state transfer with the total-energy or total-enthalpy equation on fixed Cartesian meshes without axisymmetry or interface boundaries. No additional transfer setting is required. Double-flux, temperature-equation, moving-mesh, and module-owned EOS or pressure-equation configurations retain their independent-field or module-owned transfer paths. Turbulence scalars retain their independent transfer rules.

The conservative path transfers species mass, momentum, and total energy per unit volume at both accepted cell time levels. Density, mass fractions, velocity, pressure, and temperature are reconstructed together from that state and the EOS. Density is the sum of species densities. The total-enthalpy form transfers total energy using rho*h - p.

Reconstructed species densities must be nonnegative, total density positive, and the EOS temperature within TclipMin and TclipMax. These bounds validate the state without clipping its energy. If second-order interpolation fails this check, the complete affected time-level payload is retried at first order on every MPI rank. Failure at first order stops the run.

Conservative transfer applies to cell states only. It does not reconstruct accepted face-flux history used by momentum interpolation. BDF2 retains its one-step history fallback after each runtime remesh.

Restart

AMR checkpoints restore the adapted mesh with the solution. Keep amr loaded, set adaptInitializationSteps: 0, and retain the complete restart directory. The original VOG and grid options must remain unchanged. For example, restart case at step 200:

stream -q solution case 200

Output Variables

Request AMR fields with plot_output:

plot_output: refFlag, combinedErrorFactor

Field Variable Output for the AMR Module
Variable	Description
`refFlag`	Request after size masks and the refinement budget, before mesh balancing: `1` refine, `-1` coarsen, `0` unchanged.
`combinedErrorFactor`	Combined normalized sensor value.
`amrPolicy`	Active region ID; `0` denotes global settings. The log maps IDs to region names.
`amrMinSize`	Effective minimum cell size, in meters.
`amrRefineThreshold`	Effective refinement sensitivity.
`amrCoarsenThreshold`	Effective coarsening sensitivity.

All fields are optional and use the maximum of adjacent cell values at each node.

Post-Processing

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

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 for the original mesh. For example, extract the output preserved on the original mesh at step 200 with:

extract -vtk case 200_amr0

With plot_output_iteration: on or a nonzero plot_modulo, all retained numeric output labels are preserved at each mesh change. Preserved frames and mesh files are outside the plot_modulo limit and require additional disk space. Use a separate directory to retain results from earlier runs; rerunning resets mesh numbering and can overwrite output.