AMR Design

🗂️ AMR Design

GRANITE v0.6.8 | ← Home | Architecture Overview →

Technical reference for the Berger-Oliger Adaptive Mesh Refinement implementation.

---

1. Berger-Oliger Subcycling

GRANITE's AMR follows the Berger-Oliger (1984) algorithm. The domain is divided into a hierarchy of nested GridBlock patches at refinement levels ℓ = 0, 1, …, ℓ_max.

Subcycling: Each level advances with its own timestep:

dt_ℓ = dt_0 / 2^ℓ

A single level-0 step requires 2^ℓ fine-level substeps. The subcycle function recurses down the hierarchy:

subcycle(level ℓ):
    advance level ℓ by dt_ℓ
    if (ℓ < ℓ_max and has_children):
        subcycle(ℓ+1)
        subcycle(ℓ+1)   ← two fine steps per one coarse step
    restrict(ℓ+1 → ℓ)  ← update coarse with fine solution

---

2. Prolongation (Coarse → Fine)

When a fine patch needs ghost zones filled from a coarser parent, trilinear interpolation is used:

f(x, y, z) = Σ_{ijk} c_{ijk} f_{i,j,k}

Weights: c_{ijk} = (1-ξ)(1-η)(1-ζ), ξ(1-η)(1-ζ), ..., ξ·η·ζ
where ξ = (x - x_i)/dx, η = (y - y_j)/dy, ζ = (z - z_k)/dz

This is second-order accurate, consistent with the overall truncation error budget. Full-domain prolongation is the load-bearing behavior — prolongateGhostOnly() was introduced and reverted in v0.6.5 due to physics regressions (see CHANGELOG v0.6.5).

---

3. Restriction (Fine → Coarse)

Fine-level data is injected to the coarse level using volume-weighted averaging:

f_coarse = (1/8) Σ_{8 children} f_fine   [in 3D]

Volume weighting ensures conservation of extensive quantities (baryon number, energy) across level boundaries. This is essential for GRMHD correctness at refinement interfaces.

---

4. Ghost Zone Filling Order (Within Each RK3 Stage)

1. fillGhostZones(level)
   a. MPI_Isend: pack ghost face, send to same-level neighbor rank
   b. MPI_Irecv: receive from same-level neighbor rank
   c. prolongate: fill ghost zones from parent level (coarser)
   d. MPI_Waitall: ensure MPI transfers complete
   
2. applyOuterBC(level)
   a. Sommerfeld or copy BC on outermost ghost cells

Order matters: MPI exchange must complete before outer BCs are applied. Prolongation from parent must happen before MPI exchange (parent data must be current).

---

5. Refinement Criteria

Cells are tagged for refinement when criteria are met:

Variable	Criterion	Interpretation
chi	χ < threshold	Conformal factor suppressed near punctures
alpha	α < threshold	Lapse collapsed near BH
rho	ρ > threshold	Dense matter (neutron stars)
ham	‖H‖ > threshold	Large local constraint violation

Tracking spheres override refinement criteria near BH punctures, ensuring minimum refinement level min_level is maintained throughout the run.

---

6. Block-Merging Algorithm

For binary systems where the two tracking spheres are close, proposed refinement patches may overlap. The block-merging algorithm (v0.6.0):

1. List all proposed fine patches (bounding boxes around tracking spheres)
2. Iteratively union-merge patches that touch or overlap
3. Create final merged blocks

This prevents duplicate cells and eliminates the MPI deadlock that occurred before the fix for close binaries.

---

7. Current Limitations (v0.6.8)

Limitation	Impact	Planned Fix
Dynamic regridding not fully implemented	AMR block count fixed at initialization	v0.7
Max levels = 4 for stable production runs	dx_finest limited by initial setup	v0.7 (with dynamic regrid)
No adaptive timestep per level	CFL violation possible at finest level	v0.7
Regrid frequency not configurable	Regrid runs at fixed intervals	v0.7

---

See also: Architecture Overview | Parameter Reference | Simulation Health & Debugging