Adaptive Mesh Refinement Module

Stream provides adaptive mesh refinement (AMR) through the amr module. The module refines and coarsens the mesh in response to changes in the solution, allowing additional cells to be concentrated near flow features. This capability is enabled by inserting the following loadModule directive into the run control file:

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

The following sections describe the run control file variables used to select refinement criteria, control when adaptation occurs, and process output from an adapting mesh.

Adaptive Mesh Refinement

During a simulation, the AMR module evaluates the selected solution sensors and marks cells for refinement or coarsening. The mesh is adapted between physical time steps, and the solution is transferred to the new mesh before time integration continues. This process takes place within the running solver and does not require writing and reading restart files at each adaptation.

The module can also adapt the mesh before the first physical time step. In this case, the configured initial conditions are evaluated again on each new mesh. Initial adaptation is useful for resolving features already present in the starting solution.

Mesh adaptation does not change the requested simulation duration. The time-step count and physical time continue across mesh changes, and initial adaptation does not consume physical time steps. Additional physics modules must support transferring their own solution variables before they can be combined with runtime AMR; loading amr alone does not provide that support.

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
}

These values illustrate the input syntax; the sensor selection and adaptation interval should be chosen for the flow being modeled. The default value of maxAdaptSteps is zero, so loading the module without changing this value does not adapt the mesh.

Solution Sensors

The variable adaptSensor accepts a comma-separated list of sensor names. The available sensors are listed below. Each selected sensor requires the corresponding solution variable to be available in the simulation.

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. When several sensors are selected, the largest normalized value in each cell is used. Thus, the sensitivity settings below are dimensionless thresholds, not absolute differences in pressure, temperature, or another solution variable.

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	Cells with a combined normalized sensor value below the negative of this 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. Without a selected sensor or another active source of adaptation requests, the mesh is unchanged. Geometric regions specified in initialConditionRegions define initial solution values, not refinement regions. Sensors can respond to the resulting flow features, but region membership alone does not mark cells for adaptation.

Adaptation Frequency and Limits

The following variables control when the AMR module can adapt the mesh. All time-step counts refer to physical time steps, not nonlinear iterations within a time step.

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. This is not the maximum refinement depth of a cell.
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 adaptation does not use adaptStart or adaptFrequency. It stops when the requested number of adaptations is reached or no cells are marked. Each initial adaptation counts toward maxAdaptSteps; to allow later runtime adaptation, increase the total limit and set a positive runtime frequency.

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. For an ordinary restart-file simulation, leave adaptInitializationSteps at zero and use the runtime adaptation controls instead. The simulation must request physical time steps; numTimeSteps: 0 is not a mesh-only adaptation mode.

Mesh Controls

The following variables control the refinement mode and mesh size.

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 length threshold, in meters. Suppresses refinement of cells whose maximum relevant edge length is below this value.
maxAdaptCellCount	-1.0	Target upper cell count in millions. Positive values enable the limit; negative values disable it. Fractional values are permitted.
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.

The adaptMinEdgeLength setting limits refinement requests based on the current cells; it is not a guaranteed minimum edge length in the resulting mesh. It also sets the remesher’s geometric tolerance to one tenth of the specified value.

For example, maxAdaptCellCount: 0.5 sets a target of 500,000 cells. The module adjusts the refinement threshold using an estimate of the added cells. Mesh balancing can require additional refinement, so this setting is not a strict upper bound on the final cell count.

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

Overset Geometry Adaptation Controls

Variable	Default	Description
adaptGeometryEdgeLength	Not set	Target edge length, in meters, near overset component surfaces. Requires the overset component geometry.
adaptGeometryLayers	8	Controls the thickness of the transition from the target edge length near component surfaces to coarser cells farther away.

These controls use overset component surfaces, not arbitrary boxes or other user-defined refinement regions. Their availability does not imply support for transferring moving-component geometry through AMR; moving-mesh AMR is not covered by this setup.

Solution Transfer

The variable adaptInterpolationOrder controls the reconstruction of transferred cell solution values 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.

This option applies to the shared AMR cell-field transfer. It does not select the spatial discretization used to solve the flow equations, and it does not change the re-evaluation of initial conditions during initial adaptation. Coarsening uses volume-weighted averaging for either value. Physics modules with their own transfer methods may impose additional requirements.

Output Variables

The following additional field variables are available when the AMR module is loaded. They can be requested with plot_output:

plot_output: refFlag, combinedErrorFactor

Field Variable Output for the AMR Module

Variable	Description	Default
refFlag	Adaptation request: 1 for refinement, -1 for coarsening, and 0 for no request. Output uses the maximum of adjacent cell values at each node.	No
combinedErrorFactor	Combined normalized sensor value, output as the maximum of adjacent cell values at each node.	No

The refFlag field shows requests before the cell-size mask and the remesher’s eligibility checks are applied. It is useful for viewing where adaptation is requested, but is not a record of which cells were actually refined or coarsened.

Post-Processing

The standard output controls described in Appendix: Output Data also apply to AMR simulations. Field names and the selected plot frequency are unchanged. Each output frame is associated with the mesh on which it was written, so the usual extraction command can be used. For example, to extract the output labeled 200 for a simulation named case:

extract -vtk case 200

Stream automatically writes the topology and grid-position files to the output directory alongside the field data. The original mesh is stored in casename.topo; subsequent meshes use casename_1.topo, casename_2.topo, and so on. The file topo_file.extension_casename identifies the topology for each output label, and extract reads this file automatically. Stationary output on the original mesh uses grid_pos.casename; adapted meshes use grid_pos.extension_casename. The necessary mesh files are also written for boundary-only and end-of-step diagnostic output.

When output from the old mesh would otherwise share a label with output from the new mesh, Stream preserves the old output with an _amrN suffix, where N identifies the old mesh, beginning with zero for the original mesh. For example, if adaptation occurs at time step 200, pre-adaptation diagnostics saved at that label on the original mesh can be extracted with:

extract -vtk case 200_amr0

The label 200 is then available for output on the adapted mesh when that output is scheduled. A preserved frame contains only the variables written on its original mesh; preserving it does not interpolate those variables onto the new mesh.

With plot_output_iteration: on or a nonzero plot_modulo, all retained numeric output labels are preserved at each mesh change because these labels can be reused. Normal overwriting within a mesh is unchanged. Preserved AMR frames and mesh topology files are additional files outside the rolling limit set by plot_modulo, so they require additional disk space.

Use a separate output directory for each independent AMR run. Mesh numbering begins again with each solver execution and does not provide unique names across separate runs.