feat(mg/adapt): land custom-MG parallel support + NVB adapt-on-top (stranded branch, closes #365)

docs/advanced/mesh-adaptation.md

@@ -30,7 +30,7 @@ metric = uw.adaptivity.metric_from_gradient(
 )
 
 # Adapt the mesh
-mesh.adapt(metric)
+mesh.remesh(metric)
 ```
 
 ## Core Concepts
@@ -65,7 +65,7 @@ for each edge vector $\mathbf{e}$. Edges that are too long get subdivided; regio
 UW3 offers **two complementary** ways to put resolution where it is
 needed:
 
-| | `mesh.adapt(...)` (this page) | `smooth_mesh_interior(method="anisotropic")` |
+| | `mesh.remesh(...)` (this page) | `smooth_mesh_interior(method="anisotropic")` |
 |---|---|---|
 | Mechanism | **Re-mesh** (MMG): insert/remove/retriangulate | **Redistribute** the existing nodes (move only) |
 | Node budget | *Changes* — targets an **absolute** edge length `h` | **Fixed** — relative redistribution to a target *density* |
@@ -75,7 +75,7 @@ needed:
 | Cost | Re-mesh + full variable transfer | A few cheap SPD elliptic solves (no re-mesh) |
 | Parallel | MMG re-partition | O(N), GAMG-parallelisable, no transfer |
 
-Use `mesh.adapt` when you need a genuinely finer mesh (more
+Use `mesh.remesh` when you need a genuinely finer mesh (more
 elements) and can afford to rebuild the problem. Use the
 **node-snuggling** redistribution when you want to *reshape* the
 existing mesh toward a feature every timestep cheaply, keeping the
@@ -241,7 +241,7 @@ metric = fault.refinement_metric(
 )
 
 # Adapt mesh
-mesh.adapt(metric)
+mesh.remesh(metric)
 
 # Check result
 print(f"Adapted mesh: {mesh.X.coords.shape[0]} nodes")
@@ -258,7 +258,7 @@ p = uw.discretisation.MeshVariable("p", mesh, 1, degree=1)
 
 ### Variables Are Reset
 
-After `mesh.adapt()`, all variables on the old mesh become invalid. Variables on the new mesh start uninitialized.
+After `mesh.remesh()`, all variables on the old mesh become invalid. Variables on the new mesh start uninitialized.
 
 **For analytical initialization:**
 ```python
@@ -347,7 +347,7 @@ pixi run -e amr python -c "import underworld3; print('AMR ready')"
 
 | Function | Purpose |
 |----------|---------|
-| `mesh.adapt(metric)` | Adapt mesh using metric field |
+| `mesh.remesh(metric)` | Re-mesh (in place) using metric field |
 | `uw.adaptivity.create_metric(mesh, h)` | Convert h-field to metric |
 | `uw.adaptivity.metric_from_gradient(field, ...)` | Metric from field gradient |
 | `uw.adaptivity.metric_from_field(indicator, ...)` | Metric from indicator field |
@@ -380,7 +380,7 @@ For the mathematically inclined, see the [Developer Design Document](../develope
 When you want to concentrate resolution on an evolving feature
 **every timestep** without re-meshing — keeping the topology and
 all field data intact — use `smooth_mesh_interior` (the node-moving
-mover) instead of `mesh.adapt`:
+mover) instead of `mesh.remesh`:
 
 ```python
 import underworld3 as uw

docs/developer/design/GENERALIZED_FMG_HIERARCHY_AND_ADAPT.md

@@ -76,13 +76,45 @@ The supported parallel path is the **nested, co-partitioned** hierarchy:
   (`localToGlobal` gives the reduced global ordering across ranks).
 - `P` is assembled as an MPIAIJ matrix (fine local rows; coarse local + ghost columns).
 
-**Non-nested / independent-mesh custom-P** (cross-rank point-location) is **serial-only /
-experimental** — it is not on the parallel-supported path. The production case
-(targeted refinement = nested) needs only the rank-local path.
+**Non-nested / independent-mesh custom-P** in parallel (cross-rank point location) is now
+supported via a **cross-partition transfer** (`_build_crosspart_transfer`,
+`_gather_coarse_cloud`). When the coarse and fine meshes are partitioned independently, a
+fine leaf on rank *r* can sit in a coarse cell owned by rank *s*, so the rank-local builder
+either misses it (nearest-DOF fallback — wrong) or leaves a coarse DOF with no fine image
+(zero column). The fix exploits the fact that a coarse MG level is, by definition, **small**:
+
+- **All-gather the coarse node cloud** (coords + each node/component's GLOBAL reduced column
+  index, `-1` for a BC-constrained DOF), deduplicated by rounded coordinate (ghost copies are
+  bit-identical). Every rank then holds the *full* coarse mesh.
+- Each rank locates its **owned** fine nodes against that full cloud → point location spans
+  partitions. Columns are the coarse global reduced indices (off-rank columns are fine for
+  MPIAIJ); constrained coarse DOFs stay as barycentric vertices but drop from the columns
+  (reduced→reduced). Fine rows stay rank-local.
+
+`CustomMGHierarchy(..., cross_partition=...)` / `set_custom_fmg(..., cross_partition=...)`:
+`"auto"` (default) builds the rank-local co-partitioned transfer first and rebuilds a level
+cross-partition **only if it has zero columns** (the signature of a cross-partition miss) —
+so the validated nested/adapt path stays on the fast rank-local builder bit-for-bit, while
+non-nested tails are fixed automatically. `True` forces cross-partition (use when a coarse
+level is known non-nested and might mis-locate without producing a zero column); `False`
+forces the rank-local path. Validated: an independent (non-co-partitioned) coarse box tail
+converges in the same iteration count as serial and matches a GAMG reference to ~1e-8 at
+np2 and np4.
 
 Non-load-balancing SBR → bound the added refinement depth (configurable cap); document the
 imbalance/level trade-off.
 
+### Operator-faithful finest reduced map
+The finest transfer's row space **must** equal the assembled operator's space (PCMG Galerkins
+`PᵀAP` against the real operator). The finest reduced map is read from the DM global section,
+which is that space only **after** `snes.setUp()` finalizes it — critical on an `adapt()`
+child, whose section can otherwise be read before finalization and disagree with the operator
+(a rectangular finest transfer → bare PETSc error 60 in the PtAP). `CustomMGHierarchy.build`
+calls `snes.setUp()` before reading the finest map and asserts its size against the assembled
+operator (`_assert_finest_matches_operator`), failing with an actionable message instead. This
+removed the earlier defensive skip of semi-Lagrangian advection-diffusion on adapt children —
+such solves now install custom-P geometric MG and match a default-preconditioner solve.
+
 ## Correctness invariants (must hold, all levels)
 1. BCs applied at every level; transfers reduced→reduced (no zero columns).
 2. Each prolongation reproduces constants (row-sums = 1 — partition of unity).