skills: adapt engines, band pinning, FMG on adapt children — brought current; plasticity-solvers rewritten (#454)

[lmoresi]

PR #489 body draft (updated for the combined skills tidy)

Title suggestion: skills: parallel adapt engines, band pinning, FMG on adapt children — brought current, plus the #454 plasticity-solvers rewrite

Fixes#454.

What this PR now carries

Two layers on the same branch, so one PR lands a consistent skill set:

1. The original three-file content (unchanged in substance)

• adaptive-meshing: the "PIN THE INTERFACE when you relax" section
  (relax(pin_bands=...), label_interface_band, the +77 % / 1343→965
  straddling-cell measurements). Verified accurate against current development,
  merged as-is — Adapt-review fixes: collective pinned-band verdicts, partition-independent pinning, explicit-GAMG opt-out, the #492 CI disarm #530's collective/partition-independent pinning only made it
  more true.
• adapt-on-top-faults: the engines section (nvb vs edge_split, repair=),
  band pinning, and band sizing (leak = −2 Cov(η, ε̇)).
• nonlinear-solver: the "FMG on an ADAPT-ON-TOP child" section (auto pickup of
  the mesh-owned custom-P tail, the 3D: shape relaxation can break the custom-P FMG build (zero-column transfer) — silent GAMG fallback #424 rbf cliff, repair vs the any-degree
  transfer).

2. Currency fixes (development moved since the branch)

Each correction, with its one-line rationale:

• adapt-on-top-faults — rotated free-slip gotcha row + section: the row said
  FMG under rotated free-slip is "FUNDAMENTAL, not a quick fix"; Rotated free-slip silently ignores a mesh-owned custom-FMG hierarchy (adapt children fall back to GAMG) #467 fixed it —
  the rotated path now resolves hierarchies through the same
  custom_mg.build_transfers rule and picks up an adapt child's tail
  automatically (rotated_bc._build_rotated_custom_Pl). The plain-refined-mesh
  case still needs set_custom_fmg, and the skill now says exactly that.
• adapt-on-top-faults — interface-alignment pointer: the band-sizing section
  named "align the interface with element boundaries" as an exact fix with no way
  to do it; place_sheet / place_thin_volume / remove_embedded
  (utilities/place_surface.py, place_sheet: the 3-D placed surface (serial), with a gated gmsh cavity fill #517–Outcropping zones: the fault zone leaves its band on the surface #526) now exist, so it points at them.
• nonlinear-solver — rotated free-slip claim: "none of this is automatic
  under rotated free-slip" was actively steering users away from a path that now
  works (Rotated free-slip silently ignores a mesh-owned custom-FMG hierarchy (adapt children fall back to GAMG) #467); corrected.
• nonlinear-solver — MG level per generation → per DOUBLING of h: Geometric-MG bundle owns its outer-KSP pairing: fgmres, applied to the live KSP #515 made
  _adapt_nested subsample the tail (mg_coarsening_ratio=2.0 default;
  per-pass levels measured 2.3–7.3× slower). The "don't hand it a base-only
  tail" advice stands.
• nonlinear-solver — the refinement>=1 overstatement: with refinement=0
  the tail is [base] + intermediate doubling levels, so the hierarchy starts at
  the base — deeper uniform tails help, but "no coarse grid" was not true.
• nonlinear-solver — three capabilities that landed since the branch:
  preconditioner="gamg" is respected on adapt children (Adapt-review fixes: collective pinned-band verdicts, partition-independent pinning, explicit-GAMG opt-out, the #492 CI disarm #530 — previously
  silently clobbered, so the skill's own GAMG-probe advice was unfollowable);
  single-field preconditioner="fmg" over mesh.dm_hierarchy (Geometric multigrid is unreachable for every single-field solver, even when explicitly requested (the #276 lockout) #478/Solver options: fallback observability, tolerance ownership, the single-field FMG unlock, and multiplier_schur_pc verified (#478 #483 #484 #486) #534); and
  solver.pc_fallbacks as the observability hook for every degradation,
  including the 3D: shape relaxation can break the custom-P FMG build (zero-column transfer) — silent GAMG fallback #424 barycentric→rbf retry (Solver options: fallback observability, tolerance ownership, the single-field FMG unlock, and multiplier_schur_pc verified (#478 #483 #484 #486) #534).

3. The #454 rewrite of plasticity-solvers

The skill headlined cm.enable_yield_homotopy() — an API that does not exist in
src/ — and taught the in-SNES δ-ramp doctrine in ~8 places. Per the issue's
rescope: the doctrine rested on a unit-scaling error, and the corrected-scaling
evidence runs against it (the δ-march never succeeded where a direct hard-Min
solve failed; direct is 4–5× faster where both work; ruling — regularise the
problem, not the solver).

Rewritten around what the campaigns measured:

• Newton with the automatic Picard entry (Nonlinear solver: automatic warm start, model-advertised yield homotopy, and an inf-safe power-mean yield law #441): a cold consistent-Newton
  start takes one Picard step automatically; Picard is an entry requirement, not
  an accelerator (front-loading it measured pure waste where Newton works).
• Newton-first, rescue on failure OR stagnation with picard=N /
  consistent_jacobian="continuation" — admissible uselessness never trips a
  FAIL reason, so failure-only rescue is not enough.
• Grid sequencing as the validated warm start for hard problems (coarse solve
  → linear-exact RBF transfer → fine; hand-rolled, since -snes_grid_sequence
  does not work on UW3 meshes).
• The yield_anchor: which side of exact Min the soft-min yield law sits on #475 substrate (yield_mode / yield_smoother / yield_anchor, δ as
  a recompile-free constant) presented as a modelling choice, with the
  multi-solve-only discipline for any δ-march (never ramp inside one SNES solve).
• yield_continuation described honestly per open yield_continuation: the documented cold-start guarantee does not hold, and the step control is effectively one-shot #473: the documented
  cold-start guarantee does not hold on a Piecewise yield stress, and the step
  control is effectively one-shot. The latched snes_max_it wart (yield_anchor follow-ups from the #475 review: snes_max_it latch resurrect, side-attribution docstring, small validation gaps #490) is not
  taught as a feature.
• Floors post-yield_anchor: which side of exact Min the soft-min yield law sits on #475: viscosity_min_rounding keeps shear_viscosity_min
  differentiable at δ = 0, where the default rounding vanishes.
• Kept: the per-model tangent table (VEP-indefinite ruling), the
  confirm-you-are-running-Newton check, the SNESFAS ruling, the Picard-folklore
  footnote.

Sanity: enable_yield_homotopy — zero matches across all skill files;
Null_Boundary — zero matches.

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]

Adversarial review

Every command/API/flag the skills teach exists in #488's diff or on development — engine="edge_split", repair=True refusal semantics, relax(pin_bands=[fault] / [(fault, 0.02)], pin_halo=), label_interface_band(surface, offset, halo), child._custom_mg_coarse_meshes auto-pickup, influence_function(profile="step"), the custom_mg barycentric→rbf retry warning text, set_custom_fmg(..., field_id=0), the Mesh(dm, boundaries=...) gotcha. No invented parameters, no stale-API teaching.

Two doc-level overclaims, both tied to #488 defects:

• "raises rather than silently doing nothing otherwise" is false for the adapter="mmg", repair=True corner (Adapt-on-top: closure-free edge_split engine, reconnection repair, and interface-pinned relaxation #488 finding 6).
• The skill teaches child.relax(pin_bands=[fault]) for parallel fault models with no caveat, while Adapt-on-top: closure-free edge_split engine, reconnection repair, and interface-pinned relaxation #488's label_interface_band hangs whenever a rank's subdomain misses the band (Adapt-on-top: closure-free edge_split engine, reconnection repair, and interface-pinned relaxation #488 finding 1). Carry the warning until that is fixed.

Merge strictly after #488 (else the skills document nonexistent features). Holding with it.