Experimental performance family (default-off): load-balance infrastructure, active-box windowing, block-structured AMR, hybrid WENO/Riemann sensors

.typos.toml

@@ -22,6 +22,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
 chioces = "chioces"   # typo for "choices" - tests constraint key validation
 reqires = "reqires"   # typo for "requires" - tests dependency key validation
 choises = "choises"   # appears in comment explaining validation purpose

docs/documentation/amr_fine_distribution.md

@@ -0,0 +1,55 @@
+# AMR fine-level distribution (design note)
+
+**Status:** in progress on `up/mega` (part of the AMR effort). Phase 1 landed (map computed, not applied); Phase 2 is the apply + gather/scatter checkpoint.
+
+## Problem
+
+MFC's AMR uses a **mirror decomposition**: the fine level reuses the coarse rank
+decomposition, so each rank owns exactly the fine cells over its coarse subdomain's
+intersection with the blocks (`s_amr_compute_isect` → `amr_rank_owns_block`). This makes
+coarse↔fine coupling entirely rank-local (zero communication) but leaves fine work
+**unbalanced**: if refinement concentrates in a sub-region, only the ranks owning that
+region do the fine advance while the rest idle. At scale this caps AMR speedup.
+
+## Target
+
+Give the fine level its **own distribution**, decoupled from the coarse decomposition, so
+fine blocks spread across all ranks by measured work — the AMReX per-level
+`DistributionMapping` idea. MFC already enforces an invariant that makes this far simpler
+than the general case: **blocks are kept ≥ `buff_size` apart** (regrid merge), so with
+**whole-block-per-rank** assignment there is *no fine–fine halo at all*
+(`s_mpi_sendrecv_amr_fine_halo` disappears). The only coupling that becomes communication
+is coarse↔fine, block-granular.
+
+## Coupling changes (whole-block-per-rank)
+
+| Step | Today (mirror, local) | Decoupled |
+|---|---|---|
+| Ownership | intersection, multi-owner (`amr_rank_owns_block`) | single owner (`amr_block_owner(k) == proc_rank`) |
+| Ghost fill / prolong (coarse→fine) | read local coarse `q_cons` | **gather** coarse patch (block + `buff_size` halo) from coarse owner(s) to block owner |
+| Reflux + restriction (fine→coarse) | write local coarse cells | **scatter** corrections from block owner back to coarse owner(s) |
+| Fine–fine halo | coarse Cartesian neighbors | none (blocks separated) |
+| Regrid | cluster (global) → mirror | cluster → **assign** (`amr_block_owner`) → **migrate** fine state |
+
+The gather/scatter is the only new communication surface. SFC-ordered assignment keeps a
+block's coarse patch on an SFC-nearby rank, bounding the cost. Conservation exactness is
+preserved because the scatter applies the *same* reflux add / restrict overwrite the
+mirror model applied locally — a pure data-movement change, not a numerics change.
+
+## Reuse
+
+`m_load_weight` (per-cell cost field) and `m_sfc_partition` (Morton order + chains-on-chains
+balanced partition) already exist as an init-time diagnostic. They become the fine-level
+distributor: feed the block list + per-block fine-work weight, return `amr_block_owner(:)`.
+
+## Phasing (each independently mergeable)
+
+1. **Distribution map, computed but not applied** (behavior-preserving). Add
+   `amr_block_owner(:)` + SFC assignment + an imbalance diagnostic; mirror ownership and all
+   coupling unchanged. Goldens bit-identical. *(this note's first increment)*
+2. **Apply the map**: switch `amr_rank_owns_block` to single-owner, add the coarse↔fine
+   gather/scatter, drop the fine–fine halo. Validate conservation + assignment-independence.
+3. **Dynamic rebalance each regrid**; optionally drop the fixed max-size slot pool for
+   right-sized boxes.
+
+Phase 2 carries the correctness risk (gather/scatter exactness) and is the checkpoint gate.

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

@@ -3,6 +3,7 @@
         "category": "Solver Core",
         "modules": [
             "m_rhs",
+            "m_active_box",
             "m_time_steppers",
             "m_weno",
             "m_riemann_solvers",
@@ -58,7 +59,11 @@
             "m_start_up",
             "m_data_output",
             "m_data_input",
-            "m_delay_file_access"
+            "m_delay_file_access",
+            "m_load_weight",
+            "m_load_balance",
+            "m_sfc_partition",
+            "m_rank_timing"
         ]
     },
     {
@@ -69,6 +74,9 @@
             "m_global_parameters_common",
             "m_mpi_common",
             "m_mpi_proxy",
+            "m_box",
+            "m_amr",
+            "m_amr_registers",
             "m_constants",
             "m_precision_select",
             "m_helper",

src/common/m_boundary_common.fpp

@@ -73,6 +73,10 @@ contains
         type(integer_field), dimension(1:num_dims,1:2), intent(in)                                           :: bc_type
         type(scalar_field), optional, intent(inout)                                                          :: q_T_sf
 
+#ifdef MFC_SIMULATION
+        if (amr_in_fine_advance) return  ! AMR fine block: ghosts pre-filled from the coarse level
+#endif
+
         call s_populate_bc_direction(1, -1, bc_x, bc_type(1, 1), q_prim_vf, pb_in, mv_in, q_T_sf)
         call s_populate_bc_direction(1, 1, bc_x, bc_type(1, 2), q_prim_vf, pb_in, mv_in, q_T_sf)
 

src/common/m_box.fpp

@@ -0,0 +1,85 @@
+!>
+!!@file
+!!@brief Contains module m_box
+
+#:include 'macros.fpp'
+
+!> @brief Owned domain-decomposition Box abstraction and partition arithmetic (v1: one box per rank).
+module m_box
+
+    use m_derived_types, only: t_box
+    use m_global_parameters, only: wp
+
+    implicit none
+
+    private
+    public :: t_box, f_equal_splits, f_weighted_splits, f_box_from_splits
+
+contains
+
+    !> Cumulative equal-cell offsets for g cells over n_parts ranks: off(r) = r*(g/n_parts) + min(r, mod(g,n_parts)). Reproduces
+    !! MFC's block distribution (remainder to the first ranks) exactly. Pure integer path.
+    pure function f_equal_splits(g, n_parts) result(off)
+
+        integer, intent(in)           :: g, n_parts
+        integer, dimension(0:n_parts) :: off
+        integer                       :: q, rem, r
+
+        q = g/n_parts
+        rem = mod(g, n_parts)
+        do r = 0, n_parts
+            off(r) = r*q + min(r, rem)
+        end do
+
+    end function f_equal_splits
+
+    !> Cumulative offsets splitting marginal w into n_parts contiguous chunks of near-equal weight, each >= l_min cells. off(0)=0,
+    !! off(n_parts)=size(w). Feasibility (size(w) >= n_parts*l_min) is the caller's responsibility (pure; no abort).
+    pure function f_weighted_splits(w, n_parts, l_min) result(off)
+
+        real(wp), dimension(0:), intent(in) :: w
+        integer, intent(in)                 :: n_parts, l_min
+        integer, dimension(0:n_parts)       :: off
+        real(wp)                            :: csum, total
+        integer                             :: g, i, r
+
+        g = size(w)
+        off(0) = 0
+        off(n_parts) = g
+        if (n_parts == 1) return
+        total = sum(w)
+        r = 1
+        csum = 0._wp
+        do i = 0, g - 1
+            csum = csum + w(i)
+            do while (r < n_parts .and. csum >= real(r, wp)*total/real(n_parts, wp))
+                off(r) = i + 1
+                r = r + 1
+            end do
+        end do
+        do while (r < n_parts)
+            off(r) = g; r = r + 1
+        end do
+        do r = 1, n_parts - 1
+            if (off(r) < r*l_min) off(r) = r*l_min
+            if (off(r) > g - (n_parts - r)*l_min) off(r) = g - (n_parts - r)*l_min
+            if (off(r) <= off(r - 1)) off(r) = off(r - 1) + l_min
+        end do
+
+    end function f_weighted_splits
+
+    !> Assemble this rank's box from per-axis cumulative offsets and the rank's Cartesian coords (0-based). lo(d) =
+    !! off_d(coords(d)); hi(d) = off_d(coords(d)+1) - 1. Works for collapsed axes (off_d = [0,1] -> lo=hi=0).
+    pure function f_box_from_splits(off_x, off_y, off_z, coords) result(box)
+
+        integer, dimension(0:), intent(in) :: off_x, off_y, off_z
+        integer, intent(in)                :: coords(3)
+        type(t_box)                        :: box
+
+        box%lo(1) = off_x(coords(1)); box%hi(1) = off_x(coords(1) + 1) - 1
+        box%lo(2) = off_y(coords(2)); box%hi(2) = off_y(coords(2) + 1) - 1
+        box%lo(3) = off_z(coords(3)); box%hi(3) = off_z(coords(3) + 1) - 1
+
+    end function f_box_from_splits
+
+end module m_box

src/common/m_derived_types.fpp

@@ -537,4 +537,11 @@ module m_derived_types
         real(wp), dimension(1:num_fluids_max)   :: perturb_dens_scale
         real(wp), dimension(1:num_fluids_max,3) :: perturb_dens_offset
     end type simplex_noise_params
+
+    !> An index-space rectangle in global cell indices. In v1, one t_box = one rank's subdomain. Flat leaf: no allocatable/pointer
+    !! components, host-only, never namelist/broadcast.
+    type t_box
+        integer :: lo(3)  !< global low cell index per axis (x,y,z)
+        integer :: hi(3)  !< global high cell index per axis
+    end type t_box
 end module m_derived_types

src/common/m_global_parameters_common.fpp

@@ -104,6 +104,7 @@ module m_global_parameters_common
         $:GPU_DECLARE(create='[mapped_weno, wenoz, teno, wenoz_q, mhd, relativity]')
         $:GPU_DECLARE(create='[igr_iter_solver, igr_order, viscous, igr_pres_lim, igr]')
         $:GPU_DECLARE(create='[recon_type, muscl_order, muscl_polyn, muscl_lim]')
+        $:GPU_DECLARE(create='[hybrid_weno, hybrid_riemann, hybrid_weno_eps, hybrid_smooth_flux]')
     #:endif
 #endif
 
@@ -348,6 +349,11 @@ contains
 
         allocate (proc_coords(1:num_dims))
 
+        ! start_idx is read by decomposition-aware features (amr, sfc_partition_wrt) in ALL builds;
+        ! the serial/single-rank offset is 0 and the MPI decomposition overwrites it
+        allocate (start_idx(1:num_dims))
+        start_idx = 0
+
         if (parallel_io .neqv. .true.) return
 
 #ifdef MFC_MPI
@@ -359,8 +365,6 @@ contains
 
         ! Option for UNIX file system (Hooke/Thomson) WRITE(mpiiofs, '(A)') '/ufs_' mpiiofs = TRIM(mpiiofs) mpi_info_int =
         ! MPI_INFO_NULL
-
-        allocate (start_idx(1:num_dims))
 #endif
 
     end subroutine s_initialize_parallel_io_common
@@ -371,12 +375,7 @@ contains
     impure subroutine s_finalize_global_parameters_common
 
         deallocate (proc_coords)
-
-#ifdef MFC_MPI
-        if (parallel_io) then
-            deallocate (start_idx)
-        end if
-#endif
+        deallocate (start_idx)
 
     end subroutine s_finalize_global_parameters_common