Block-structured AMR with batched fine advance, load-balance and active-box infrastructure

.lychee.toml

@@ -33,5 +33,6 @@ exclude = [
     "https://code\\.visualstudio\\.com/?$",           # Root page returns 403 to automated requests
     "https://stackoverflow\\.com",                    # Returns 403 to automated requests
     "https://marketplace\\.visualstudio\\.com",        # Returns 503 to automated requests
+    "_8md\\.html$",  # Doxygen auto-links backticked *.md filenames in prose to per-file pages it never generates for markdown inputs; the real md_*.html page links are still checked
     "https://web\\.eng\\.ucsd\\.edu",                    # San Diego mechanism page has an untrusted SSL cert
 ]

.typos.toml

@@ -7,6 +7,9 @@ extend-ignore-identifiers-re = [
 AttributeIDSupressMenu = "AttributeIDSupressMenu"
 
 [default.extend-words]
+# Cray CCE spells it this way in the lib-4425 runtime error; quoted verbatim in the AMR ledger so the
+# message stays greppable against what the machine actually prints.
+Unitialized = "Unitialized"
 INOUT = "INOUT"
 WRONLY = "WRONLY"
 nd = "nd"
@@ -22,6 +25,9 @@ TKE = "TKE"
 HSA = "HSA"
 infp = "infp"
 Sur = "Sur"
+thi = "thi"           # AMR clustering local: tagged-box hi index (tlo/thi)
+alo = "alo"           # AMR clustering local: accepted-box lo array (alo/ahi)
+thr = "thr"           # AMR clustering local: min-separation merge threshold
 equil = "equil"       # abbreviation for "equilibrium" (flamelet chemistry)
 chioces = "chioces"   # typo for "choices" - tests constraint key validation
 reqires = "reqires"   # typo for "requires" - tests dependency key validation

cmake/Fypp.cmake

@@ -119,6 +119,7 @@ macro(HANDLE_SOURCES target useCommon)
                                  -D MFC_COMPILER="${CMAKE_Fortran_COMPILER_ID}"
 				                 -D MFC_CASE_OPTIMIZATION=False
                                  -D chemistry=False
+                                 -D eos_state_dependent=False
                                  --line-numbering
                                  --no-folding
 								 --line-length=999

cmake/GPU.cmake

@@ -90,9 +90,15 @@ elseif (CMAKE_Fortran_COMPILER_ID STREQUAL "Cray")
     add_link_options("SHELL:-hkeepfiles")
 
     if (CMAKE_BUILD_TYPE STREQUAL "Debug")
+        # -h bounds: array-bounds and pointer checking, the Cray equivalent of gfortran's
+        # -fcheck=bounds,pointer / Intel's -check bounds / NVHPC's -Mbounds, all of which the
+        # debug branches above already set. Cray was the ONLY compiler whose debug build had no
+        # bounds checking, so an out-of-bounds write showed up here only as a later, unrelated
+        # allocation failing with an uninitialised descriptor.
         add_compile_options(
                 "SHELL:-h acc_model=auto_async_none"
                 "SHELL: -h acc_model=no_fast_addr"
+                "SHELL: -h bounds"
                 "SHELL: -K trap=fp" "SHELL: -g" "SHELL: -O0"
         )
         add_link_options("SHELL: -K trap=fp" "SHELL: -g" "SHELL: -O0")

docs/documentation/contributing.md

@@ -107,10 +107,12 @@ reconfigure.
 
 **Fypp and per-target stubs.**  Fypp resolves `#:include` at parse time, so every `.fpp`
 file sees exactly the include path for the target being compiled.  `src/common/` is
-compiled once per executable with the `MFC_<TARGET>` preprocessor define
-(`MFC_PRE_PROCESS`, `MFC_SIMULATION`, or `MFC_POST_PROCESS`) — this is intentional.
-It is what lets common modules include per-target generated files and gate
-simulation-only code with `#ifdef MFC_SIMULATION` without duplication.
+compiled once per executable, and that include path is how common modules pick up the
+per-target generated files.  Do not gate code on the executable: the per-executable
+preprocessor guards (`MFC_PRE_PROCESS`, `MFC_SIMULATION`, `MFC_POST_PROCESS`) were
+removed from the sources and the source lint rejects them.  Stage-varying behaviour is
+passed in as an argument or an initialization policy, and stage-only code lives in that
+stage's directory.
 
 For which of the 15 files is manual vs. generated and what each contains, see the
 "How to Add a New Simulation Parameter" section below.
@@ -222,6 +224,7 @@ Both human reviewers and AI code reviewers reference this section.
 - **Runtime checks go where they run.** Shared constraints belong in `src/common/m_checker_common.fpp`, simulation-only ones in `src/simulation/m_checker.fpp`, and pre- and post-process ones in their own `m_checker.fpp`. Those two `s_check_inputs` are currently empty; that is still the correct home for their checks, not `m_checker_common`.
 - **Analytic initial conditions are compiled into the binary** and their expressions are AST-validated at case load, so syntax errors and unknown variables surface immediately and by name. Each IC variable maps to an `eqn_idx` expression in `QPVF_IDX_VARS` (`toolchain/mfc/case.py`); adding a patch-settable conserved variable means updating that map and the Fortran `eqn_idx` builder together, because a mismatch is a silent wrong index.
 - **Under `--case-optimization` the baked-in constants are dropped from the namelist**, so changing one requires a rebuild rather than a case-file edit.
+- **A Fypp variable that the generated `case.fpp` sets also needs a default in `cmake/Fypp.cmake`.** `./mfc.sh` writes a per-case `case.fpp` whose `#:set` lines define those variables, so every `./mfc.sh build` sees them. The checked-in fallback `src/common/include/case.fpp` defines none of them, and that is what the documentation build and any bare CMake build use — the `-D <name>=False` list in `cmake/Fypp.cmake` is the only thing keeping those builds alive. A new `#:set` without a matching `-D` therefore preprocesses fine everywhere a developer looks and fails only in the documentation lane, with a bare `name ... is not defined` from the file that reads it.
 
 ### Compiler Portability
 

docs/documentation/gpuParallelization.md

@@ -926,3 +926,16 @@ answer is wrong, or one backend diverges from all the others.
 
 
 <div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-04</div>
+
+## Silent-failure traps (AMD flang)
+
+- NEVER put a `GPU_PARALLEL_LOOP` inside a Fortran `block` construct: amdflang compiles it clean but silently
+  DROPS the region from the device image — the first launch dies with `HSA_STATUS_ERROR_INVALID_SYMBOL_NAME`
+  naming an `__omp_offloading_*` symbol. Hoist the kernel into its own module subroutine.
+- **Never `GPU_UPDATE` a NON-CONTIGUOUS array section.** ``GPU_UPDATE(device='[q%%sf(a:b, c:d, e:f)]')`` on a
+  sub-box emits correct OpenMP, but AMD flang copies it as `size(section)` CONTIGUOUS elements starting at the
+  first: only the leading run lands where it is named and the rest overwrites neighbouring cells with stale data
+  — no error, no warning. A leading section (`arr(1:n)`, or a fixed trailing index like `freg(d)%%lo(:,:,:,k)`)
+  IS contiguous and safe; anything that strides is not. To move a sub-box, pack/unpack it with a device kernel
+  (`s_l0_pack_unpack_block`, `s_amr_restrict_device_wire`) — that is why those exist. Measured: 10 of 60 covered
+  cells delivered in the AMR cross-rank restrict, mass off 1.4e-5 per regrid.

docs/documentation/readme.md

@@ -26,6 +26,7 @@ Welcome to the Multi-component Flow Code (MFC) documentation.
 
 - @ref architecture "Code Architecture" - How the source code is organized, data flow, and module map
 - @ref expectedPerformance "Performance" - Optimization and benchmarks
+- @ref amr "Adaptive Mesh Refinement" - Block-structured AMR: algorithm, physics support, and parameters
 - @ref gpuParallelization "GPU Parallelization" - GPU macro API (developer reference)
 - @ref docker "Containers" - Docker usage
 - @ref troubleshooting "Troubleshooting" - Debugging and common issues

docs/module_categories.json

@@ -1,103 +1,126 @@
 [
-    {
-        "category": "Solver Core",
-        "modules": [
-            "m_rhs",
-            "m_time_steppers",
-            "m_weno",
-            "m_riemann_solvers",
-            "m_riemann_state",
-            "m_riemann_solver_hlld",
-            "m_riemann_solver_hll",
-            "m_riemann_solver_lf",
-            "m_riemann_solver_hllc",
-            "m_riemann_solver_hypo_hlld",
-            "m_muscl",
-            "m_variables_conversion",
-            "m_thinc"
-        ]
-    },
-    {
-        "category": "Physics Models",
-        "modules": [
-            "m_viscous",
-            "m_hb_function",
-            "m_surface_tension",
-            "m_reactive_burn",
-            "m_bubbles",
-            "m_bubbles_EE",
-            "m_bubbles_EL",
-            "m_bubbles_EL_kernels",
-            "m_qbmm",
-            "m_hypoelastic",
-            "m_phase_change",
-            "m_chemistry",
-            "m_acoustic_src",
-            "m_body_forces",
-            "m_pressure_relaxation",
-            "m_collisions"
-        ]
-    },
-    {
-        "category": "Boundary Conditions",
-        "modules": [
-            "m_cbc",
-            "m_compute_cbc",
-            "m_boundary_common",
-            "m_boundary_primitives",
-            "m_boundary_io",
-            "m_ibm",
-            "m_particle_cloud",
-            "m_igr",
-            "m_ib_patches",
-            "m_compute_levelset"
-        ]
-    },
-    {
-        "category": "I/O and Startup",
-        "modules": [
-            "m_start_up",
-            "m_data_output",
-            "m_data_input",
-            "m_delay_file_access"
-        ]
-    },
-    {
-        "category": "Infrastructure",
-        "modules": [
-            "m_derived_types",
-            "m_global_parameters",
-            "m_global_parameters_common",
-            "m_mpi_common",
-            "m_mpi_proxy",
-            "m_constants",
-            "m_precision_select",
-            "m_helper",
-            "m_helper_basic",
-            "m_compile_specific",
-            "m_fftw",
-            "m_nvtx",
-            "m_model",
-            "m_finite_differences",
-            "m_checker",
-            "m_checker_common",
-            "m_sim_helpers",
-            "m_derived_variables",
-            "m_patch_geometries"
-        ]
-    },
-    {
-        "category": "Pre-Process",
-        "modules": [
-            "m_grid",
-            "m_icpp_patches",
-            "m_initial_condition",
-            "m_assign_variables",
-            "m_check_patches",
-            "m_check_ib_patches",
-            "m_perturbation",
-            "m_simplex_noise",
-            "m_boundary_conditions"
-        ]
-    }
+  {
+    "category": "Solver Core",
+    "modules": [
+      "m_rhs",
+      "m_time_steppers",
+      "m_weno",
+      "m_riemann_solvers",
+      "m_riemann_state",
+      "m_riemann_solver_hlld",
+      "m_riemann_solver_hll",
+      "m_riemann_solver_lf",
+      "m_riemann_solver_hllc",
+      "m_riemann_solver_hypo_hlld",
+      "m_muscl",
+      "m_variables_conversion",
+      "m_thinc",
+      "m_active_box"
+    ]
+  },
+  {
+    "category": "Physics Models",
+    "modules": [
+      "m_viscous",
+      "m_hb_function",
+      "m_surface_tension",
+      "m_reactive_burn",
+      "m_bubbles",
+      "m_bubbles_EE",
+      "m_bubbles_EL",
+      "m_bubbles_EL_kernels",
+      "m_qbmm",
+      "m_hypoelastic",
+      "m_phase_change",
+      "m_chemistry",
+      "m_acoustic_src",
+      "m_body_forces",
+      "m_pressure_relaxation",
+      "m_collisions"
+    ]
+  },
+  {
+    "category": "Boundary Conditions",
+    "modules": [
+      "m_cbc",
+      "m_compute_cbc",
+      "m_boundary_common",
+      "m_boundary_primitives",
+      "m_boundary_io",
+      "m_ibm",
+      "m_particle_cloud",
+      "m_igr",
+      "m_ib_patches",
+      "m_compute_levelset"
+    ]
+  },
+  {
+    "category": "I/O and Startup",
+    "modules": [
+      "m_start_up",
+      "m_data_output",
+      "m_data_input",
+      "m_delay_file_access",
+      "m_load_weight",
+      "m_load_balance",
+      "m_sfc_partition"
+    ]
+  },
+  {
+    "category": "Infrastructure",
+    "modules": [
+      "m_derived_types",
+      "m_global_parameters",
+      "m_global_parameters_common",
+      "m_mpi_common",
+      "m_mpi_proxy",
+      "m_constants",
+      "m_precision_select",
+      "m_helper",
+      "m_helper_basic",
+      "m_compile_specific",
+      "m_fftw",
+      "m_nvtx",
+      "m_model",
+      "m_finite_differences",
+      "m_checker",
+      "m_checker_common",
+      "m_sim_helpers",
+      "m_derived_variables",
+      "m_patch_geometries",
+      "m_box",
+      "m_amr",
+      "m_amr_state",
+      "m_amr_distribution",
+      "m_amr_wave",
+      "m_amr_store",
+      "m_amr_exchange",
+      "m_amr_frame",
+      "m_amr_transfer",
+      "m_amr_advance",
+      "m_amr_stage",
+      "m_amr_l0",
+      "m_amr_cluster",
+      "m_amr_regrid",
+      "m_amr_restart",
+      "m_amr_restart_io",
+      "m_amr_registers",
+      "m_amr_xchg_audit",
+      "m_phase_timing"
+    ]
+  },
+  {
+    "category": "Pre-Process",
+    "modules": [
+      "m_grid",
+      "m_icpp_patches",
+      "m_initial_condition",
+      "m_assign_variables",
+      "m_check_patches",
+      "m_check_ib_patches",
+      "m_perturbation",
+      "m_simplex_noise",
+      "m_boundary_conditions"
+    ]
+  }
 ]