refactor(custom-mg): D-79..D-87 readability + minimal-control multigrid design note (PROPOSED)

[lmoresi]

Third PR of the 2026-07-16 maintainer-ruled series (#371 retire movers → #372 purposeful naming → this). Based directly on origin/development (6ca0e60): the file set is disjoint from #371/#372, so it can merge independently; merge order 371 → 372 → 373 is still the tidy sequence.

Part 1 — the nine D-custom_mg worklist rows (behaviour-neutral, Wave D rules)

All nine rows (docs/reviews/2026-07/REMEDIATION-WORKLIST.md, D-custom_mg table) re-verified live at the post-#369 base before editing — #369 rewrote much of this file, but every anchor still existed (at moved line numbers):

Row	Finding	Action taken
D-79	READ-59	LevelLayout NamedTuple (l2g, rstart, rend, n_full) returned by _level_dof_layout / _coarse_dof_layout; lay.n_full replaces lay[3]; the serial-vs-parallel two-shapes note now sits at the maps fill site
D-80	READ-106	_clone_dm_with_solver_discretisation(solver, coarse_mesh) extracted; the copyFields/copyDS/createDS "trick" explanation lives once, on the helper
D-81	READ-107	_assert_no_zero_columns_serial extracted beside _assert_no_zero_columns_parallel, shared wording
D-82	READ-108	except Exception around getNumFields() narrowed to PETSc.Error + sanctioned-failure comment (uncreated DS cannot report field count)
D-83	READ-109	_build_parallel_transfer / _build_crosspart_transfer / _gather_coarse_cloud parameters renamed to the serial vocabulary (coarse_coords, fine_coords, coarse_layout, fine_layout); call sites are positional, updated in the same commit
D-84	READ-111	Semicolon-packed lines split (6 sites; pure formatting)
D-85	READ-113	sub (options-prefix string) renamed vel_prefix and moved inside the if verbose: block, ending the collision with sub = sub-DM
D-86	READ-110	One-line comment on the RBF r == 0 clamp (r² log r → 0; clamp only keeps log finite)
D-87	READ-112	TODO(deprecate) lifespan marker on the legacy finest-only inject_custom_mg path, stating the one behavioural difference (no BC-per-level reduction — valid only for non-nested/unconstrained coarse levels)

Bit-identical verification: the custom-MG suites are identical pre/post edit in this worktree — serial test_1015_custom_mg_prolongation + test_1016_custom_mg_hierarchy + test_1017_custom_mg_stokes: 14 passed both times; np2 tests/parallel/test_1017_custom_mg_parallel_mpi.py: 6 passed both times. The diff contains no arithmetic changes (renames, extractions, comments only — audited).

Part 2 — multigrid minimal-control design note (PROPOSED, no implementation)

docs/developer/design/MULTIGRID_MINIMAL_CONTROL_2026-07.md (added to the design toctree). It surveys the five existing MG paths (solver.preconditioner auto/fmg/gamg with the #276 single-field lock-out; raw PETSc options with the user-override latch; set_custom_fmg; #369's mesh-owned auto-injection on adapt children; the deprecated legacy set_custom_mg), proposes a minimal-control "auto" resolution ladder (the only new machinery: auto-routing single-field solvers with a refinement hierarchy to custom-P FMG instead of the GAMG fallback), and ends with seven numbered maintainer questions: (1) adopt the single-field custom-P auto-route?, (2) failure loudness of explicit vs automatic MG, (3) utility-solver exclusion mechanism, (4) purposeful naming of the knob (solver.multigrid?) under the naming ruling, (5) legacy set_custom_mg removal timeline, (6) SNESFAS scope, (7) whether common constructors should build a default hierarchy so geometric MG is reachable without refinement=.

Gates (strictly serial; amr-dev env)

Gate	Base (6ca0e60)	This PR
pytest tests/ -m "level_1 and tier_a"	386 passed / 12 skipped / 2 xfailed / 1 xpassed	identical: 386 / 12 / 2 / 1
Custom-MG serial suite (1015+1016+1017)	14 passed	14 passed
np2 tests/parallel/test_1017_custom_mg_parallel_mpi.py	6 passed	6 passed
Style-gate scanner	green	green (no allowlist change)
pixi run docs-build	—	green

Underworld development team with AI support from Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[lmoresi]

Finalises changes to UW-multigrid to allow: rotated bcs, hierarchical adapted meshes (coarse plus non-uniform refinement), etc. Note, the adaptation is 2D only at the moment, but the MG changes are general.