yield_anchor: which side of exact Min the soft-min yield law sits on

[lmoresi]

What this is

A soft-min rounds the yield corner by δ, and rounding a corner moves the whole curve — so
each soft-min family has one free constant. Until now it was fixed implicitly, and
differently in each family, with the consequence buried in the algebra: both families
ended up sitting BELOW exact Min at and above the yield point.

For a homotopy that is the wrong direction. The entry problem is supposed to be an easier
version of the sharp problem; a law that sits below it is a weaker problem, which is a
different thing. The sqrt family undershoots for overstress ratios $f < 2$ — a third
under-stressed at nominal yield — and the power mean degenerates to the p-norm
$(\eta_{ve}^{-s} + \eta_{pl}^{-s})^{-1/s}$, whose viscosity falls away toward zero as δ
grows.

yield_anchor names the choice and makes it explicit, for both families:

yield_anchor	pinned exactly at	sqrt family	power mean
"onset" (default, historical)	$f \to 0$, the unyielded branch	undershoots for $f<2$	the p-norm; $\eta \to 0$ as δ grows
"yield"	$f = 1$, the yield point	offset $\delta/2$; $\ge$ Min	the true power mean; $\ge$ Min

The power-mean case is the neat one: it needs no offset at all. Averaging the two
terms — the /2 — is exactly what makes it a generalised mean rather than a norm, and
a generalised mean returns the common value when its arguments are equal. So
$\eta = \eta_{ve} = \eta_{pl}$ at $f = 1$ falls out of the algebra.

The cost, stated plainly

"yield" stiffens unyielded material: bounded by a factor 2 for the sqrt family, and by
$2^{\delta}$ for the power mean. At the power mean's own entry δ₀ = 1 that is a factor 2
on the entire background. Both decay to 1 as δ → 0, so the endpoint is unchanged, but the
entry problem is not merely "the sharp problem with a rounded corner" — the background is
genuinely stiffer along the path. That bound is also why the two families' entry δ are not
the same number, which is the second half of this change.

δ is not one parameter

For the power mean the sharpness is $s = 1/(\delta + 0.001)$, so δ ≤ 1 and δ = 1 is the
harmonic mean. For the sqrt family δ is a percentage stress deviation and a generous entry
is O(10). A sqrt-family δ = 16 handed to the power mean asks for a law a factor 2^16 away
from Min. The entry now comes from the family (_YIELD_HOMOTOPY_DELTA0) rather than
from a caller carrying one number across both, and yield_continuation grows smoother=
and anchor= so a march can pick both — refusing them, rather than silently ignoring
them, when handed a ready-made control.

What is NOT changed

The default stays "onset". Flipping it changes results for every existing
yield_mode="softmin" user, and that is a maintainer decision rather than a side effect of
naming the knob. Left open deliberately — see the question below.

Tests

34 passed. test_1059_yield_anchor.py is new and parametrised over both families; each
test that pins the new behaviour also asserts the OLD anchor fails it, so none of them
can pass against a no-op implementation. test_1055 now sets the anchor explicitly where
it exercises the below-Min side, rather than relying on the default.

Open question for the maintainer

Should the default flip to "yield"? The argument for: it is the correct direction for a
homotopy, and it is what any new user opting into softmin for continuation will want.
The argument against: it changes converged results (within tolerance, but not identically)
for anyone already using softmin as a plain regularisation rather than as a march, and
for the power mean it stiffens the background by up to 2^δ.

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

Read against the diff, not the description. Four findings, none blocking; the two worth acting on before merge are R1 and R4.

R1 — yield_anchor rebuilds the δ atom, so an already-built YieldHomotopyControl holds a stale handle.
The setter nulls both _yield_offset_expr and _yield_softness_expr and calls _reset(). That is correct for the value — _get_yield_softness rebuilds from self._yield_softness, which the setter does not touch — but it creates a new expression object. control.delta is captured at construction, so

control = cm._yield_homotopy_control()
cm.yield_anchor = "yield"          # rebuilds the atom
control.delta                      # now detached from the model

leaves the diagnostics handle pointing at an orphan. set_delta is safe (it goes through the yield_softness property, which re-fetches), and _yield_homotopy_control sets the anchor before it reads delta=, so the driver path is correct — and yield_continuation already refuses anchor= alongside a ready-made control, which closes the obvious footgun. What is left is the hand-rolled path. Cheapest honest fix is a line in the YieldHomotopyControl.delta docstring saying it is a snapshot; the better one is to make it a property that re-reads.

R2 — the power mean's 2^δ background stiffening deserves a cross-reference, not just a bound.
The description and docstrings both state it, and the algebra checks out (as eta_pl → ∞, softmin → a^-s/2, so η → η_ve · 2^(δ+0.001)). But at the family's own entry δ0 = 1 that is a factor 2 on the entire unyielded domain — which makes the entry problem a materially different problem, not a rounded version of the target. That is very likely relevant to #473's first defect (the cold power-mean entry at delta0 = 1 failing at all four notch regime points). Worth a See also between them so the next person does not diagnose it twice.

R3 — _yield_offset_for_anchor reads self._yield_softness_expr directly.
It is only ever called from inside _get_yield_softness, on the line after that attribute is assigned, so it cannot currently see None. But the coupling is implicit and the function name does not suggest it. Taking δ as an argument would make it total.

R4 — no test that the anchor survives a δ update.
This is the coverage gap that matches the risk R1 describes. The setter rebuilds the offset atom from the anchor's formula, and the whole design rests on that atom continuing to track δ symbolically afterwards. Every test in test_1059 sets the anchor and then evaluates; none does

set anchor → set δ → check the pin → set δ again → check the pin again

which is exactly the sequence a march performs. A no-op rebuild bug (offset frozen at its construction-time δ) would pass the current suite and fail every homotopy. Cheap to add and it guards the one mechanism that is genuinely subtle here.

Checked and clean:

• The /2 does what it claims: at a = b, ((2a^-s)/2)^(-1/s) = a exactly.
• Sides are right in both directions — the generalised mean M_{-s} ≥ min, the p-norm ≤ min.
• The sqrt family's δ/2 offset gives g → 1/2 as δ → ∞, hence the stated factor-2 bound.
• Ordering in _yield_homotopy_control (smoother → anchor → read δ) is correct; reversing the first two would lose the power mean's δ bump.
• test_1055's new explicit anchor="onset" lines are the right move — they stop those assertions from silently inverting if the default is ever flipped, which is precisely the open maintainer question.

[lmoresi]

Heads-up from the solver configuration audit: unpushed commits, and a collision with #471

Two coordination points found while auditing the solver configuration surface against development (report: docs/reviews/2026-07/solver-configuration-reachability-audit.md on branch docs/solver-config-audit).

1. Three commits are local only

feature/regime-diagram carries three commits that are not on origin:

954ff4f3 fix(solver): make Eisenstat-Walker switchable
5ad68b2f docs(solvers): the Stokes fieldsplit is two nested Krylov loops
f1555b3a fix(solver): make the Stokes solver settings reachable (#477, D-22/D2)

So this PR does not show the #477 fix. Auditing development or reading the PR list rediscovers a solved problem — which is exactly what happened here before we checked the local branch. Worth pushing so the fix is visible to anyone else working this surface.

Verified what it covers: snes_max_it and the two fieldsplit_*_ksp_rtol keys. It does not cover the MG bundle keys (fieldsplit_velocity_mg_levels_ksp_type / _max_it / mg_coarse_pc_type), which are clobbered at build time by _apply_preconditioner_options rather than at solve time — a different mechanism. That half is fixed in #471 (commit 5a390efe).

2. This PR and #471 both edit the same stale-key list, and #471 subsumes it

This PR patches the hand-written GAMG stale-key clear in _apply_preconditioner_options:

-                        "mg_levels_pc_type", "mg_coarse_pc_type",
+                        "mg_levels_pc_type", "mg_levels_ksp_norm_type",
+                        "mg_coarse_pc_type",

#471 deletes that list entirely and derives it — every key a sibling bundle sets that this one does not — and the derived GAMG stale set already contains mg_levels_ksp_norm_type. So the fix here is correct and already covered by the derivation.

They will conflict textually. Whichever lands second should take #471's derivation rather than merging the two lists, otherwise the hand-written list comes back and so does the class of bug that produced this patch.

3. Adjacent findings routed here

Filed as #483: Stokes and Stokes_Constrained disagree about which options are reachable, in opposite directions (ksp_rtol settable on one and not the other; the fieldsplit rtols the reverse) — plus snes_rtol, which _reassert_outer_tolerances() deliberately re-writes, so it is owned by design but still looks like a settable knob. Both belong on this branch, next to the fix they are adjacent to.

Underworld development team with AI support from Claude Code