Function Object Route

Function Object Route for AMR/LB

The loadBalancedAMR function object provides an alternative to using adaptiveFvMesh for adaptive mesh refinement and load balancing. This is particularly useful when you need to combine AMR/LB with other dynamicFvMesh types, such as dynamicMotionSolverFvMesh for mesh motion.

This feature was added in STFS-TUDa/blastAMR#29.

When to Use

As the dynamic mesh classes have been around for much longer, the function object should be considered as an "experimental" feature:

Use Case	Recommended Approach
Simple AMR/LB	adaptiveFvMesh (well tested)
Combining AMR with other mesh motion types	loadBalancedAMR function object
Load balancing only (no AMR)	Either route works

Basic Configuration

Add the following to system/controlDict:

libs (libamrFunctionObjects);

functions
{
    loadBalancedAMR
    {
        type            loadBalancedAMR;
        libs            (libamrFunctionObjects);

        // Execution control (standard OpenFOAM function object settings)
        executeControl  timeStep;
        executeInterval 1; // <- recommended to be 1 or some divisor of balanceInterval

        // --- AMR Settings (same as adaptiveFvMesh) ---
        refiner         hexRefiner;     // or polyRefiner
        errorEstimator  delta;
        field           alpha.water;

        // Refinement control
        refine          true;
        unrefine        true;
        maxRefinement   3;
        lowerRefineLevel 0.01;
        upperRefineLevel 0.99;

        // --- Load Balancing ---
        balance             true;
        allowableImbalance  0.1;

        // --- Particle-aware settings (optional; these are the defaults) ---
        loadPolicy          cellCount;
        particleCoeff       1.0;
        minCellsPerProc     5;
    }
}

You also need a constant/dynamicMeshDict with a dynamicFvMesh type:

// For mesh motion
dynamicFvMesh   dynamicMotionSolverFvMesh;
motionSolverLibs (libfvMotionSolvers);
motionSolver    solidBody;
// ... motion solver settings ...

// Or for static topology (AMR handles refinement)
dynamicFvMesh   staticFvMesh;

Note

The function object requires the solver to have a dynamicFvMesh mesh. This constraint may be lifted as the code matures though.

Options Reference

All AMR/LB configuration options are documented on the Options Reference page. These options are shared between the adaptiveFvMesh and loadBalancedAMR function object routes.

Key differences for the function object route:

• Default balance is false (must be explicitly enabled)
• Configuration is in system/controlDict instead of constant/dynamicMeshDict

Required Libraries

libs
(
    libamrDynamicMesh
    libamrIndicators
    libamrLoadPolicies
    libamrCloudSupport      // For Lagrangian support
    libamrFunctionObjects   // Required for function object route
);

Example Case

See tutorials/MPPICcolumn for a complete example of MPPIC particles with AMR and load balancing using the function object route.