Options Reference

AMR/LB Options Reference

This page documents all configuration options for the blastAMR library. These options apply to both the adaptiveFvMesh route (configured in constant/dynamicMeshDict) and the loadBalancedAMR function object route (configured in system/controlDict).

AMR Settings

These options control the adaptive mesh refinement behavior:

Option	Type	Default	Description
refiner	word	required	Refinement engine: hexRefiner or polyRefiner
errorEstimator	word	required	Cell selector: delta, coded, etc. See ErrorEstimatorOptions
maxRefinement	label	required	Maximum refinement level
maxCells	label	labelMax	Maximum total cell count
refine	bool	true	Enable mesh refinement
unrefine	bool	true	Enable mesh unrefinement
refineInterval	label	1	Timesteps between refinement checks
unrefineInterval	label	refineInterval	Timesteps between unrefinement checks
beginRefine	scalar	0	Simulation time (s) to start refinement
endRefine	scalar	GREAT	Simulation time (s) to stop refinement
beginUnrefine	scalar	0	Simulation time (s) to start unrefinement
endUnrefine	scalar	GREAT	Simulation time (s) to stop unrefinement

Cell Selection (Error Estimator) Settings

Option	Type	Default	Description
lowerRefineLevel	scalar	required	Lower bound for refinement
upperRefineLevel	scalar	required	Upper bound for refinement
unrefineLevel	scalar	lowerRefineLevel	Lower bound for unrefinement
upperUnrefineLevel	scalar	upperRefineLevel	Upper bound for unrefinement
nBufferLayers	label	0	Buffer layers (used if specific ones not set)
nRefinementBufferLayers	label	nBufferLayers	Buffer layers for refinement
nUnrefinementBufferLayers	label	nBufferLayers	Buffer layers for unrefinement
protectedPatches	wordList	()	Patches protected from refinement
nPatchesBuffers	label	3	Cells protected next to protected patches

Load Balancing Settings

Option	Type	Default	Description
balance	bool	true (adaptiveFvMesh) / false (FO)	Enable load balancing
allowableImbalance	scalar	0.2	Imbalance threshold (0.2 = 20%)
balanceInterval	label	refineInterval	Timesteps between balance checks
beginBalance	scalar	0	Simulation time (s) to start balancing
endBalance	scalar	GREAT	Simulation time (s) to stop balancing
loadPolicy	word	cellCount	Load calculation policy
method	word	from decomposeParDict	Decomposition method override

Load Policies

The loadPolicy option controls how processor load is calculated for determining imbalance.

cellCount (Default)

Simple cell-based load balancing. The load is the number of cells per processor.

When Lagrangian clouds are present, particle contribution can be included:

Option	Type	Default	Description
particleCoeff	scalar	1.0	Particle weight in load calculation
minCellsPerProc	label	5	Minimum cells per processor

The load is calculated as: load = cellCount + particleCoeff * particleCount

See Lagrangian Cloud Support for more details.

cpuLoad (Advanced)

CPU time-based load balancing. Measures actual computational time (excluding MPI communication) to determine processor load imbalance.

Caution

The cpuLoad policy requires LD_PRELOAD to intercept MPI calls. Loading libamrCPULoad.so overrides MPI calls even if you don't use cpuLoad for load balancing! This is necessary for accurate timing but affects all MPI operations in your simulation.

Required PRELOAD Command

LD_PRELOAD="$FOAM_USER_LIBBIN/libamrLoadPolicies.so $FOAM_USER_LIBBIN/libamrCPULoad.so" yourSolver

Library loading order matters - libamrCPULoad.so must load before MPI libraries. If MPI call interception isn't working (null load), the solver will abort with an error after a few timesteps.

cpuLoad-Specific Options

Option	Type	Default	Description
maxLBCycleLength	label	50	Timesteps over which load is measured before reset
timeUnit	word	milli	Time unit for reporting: nano, micro, or milli

Example Configuration

loadPolicy          cpuLoad;
maxLBCycleLength    50;      // Measure load over 50 timesteps, should be a multiplier of balanceInterval
timeUnit            milli;   // Report in milliseconds

How cpuLoad Works

1. MPI calls (Send, Recv, Allreduce, Barrier, etc.) are intercepted to measure communication time
2. Computational load = wall-clock time − MPI communication time
3. Imbalance is calculated as deviation from ideal average load across processors
4. Load statistics are reset every maxLBCycleLength timesteps

Advanced Settings

Option	Type	Default	Description
correctFluxes	List	()	Flux correction mappings
expireSampledSurfacesOnLB	bool	false	Expire sampled surfaces after LB
dumpLevel	bool	false	Write cellLevel/pointLevel fields
protectRefinementHistory	bool	false	Protect refinement history
refineProbes	bool	false	Propagate refinement to probe function objects

Flux Correction

To specify how fluxes should be reconstructed on new faces:

correctFluxes
(
    ( phi none )        // Don't correct phi
    ( phi U )           // Reconstruct phi from velocity U
);

Route-Specific Differences

Feature	adaptiveFvMesh	loadBalancedAMR FO
Configuration file	constant/dynamicMeshDict	system/controlDict
Mesh type	Built-in (replaces dynamicFvMesh)	Works with any dynamicFvMesh
Mesh motion support	No	Yes
Default balance	true	false
Execution timing	First mesh.update() call	Function object execution