Skill: refinement=R is a factor on the background spacing, not a grading ratio

[lmoresi]

The adaptive-meshing skill described refinement=R as the finest:coarsest cell-size ratio.

It is the maximum local refinement on the background cell size h0. The metric targets the envelope h ∈ [h0/R, h0·coarsening], and coarsening="auto" takes the budget-conserving R**(1/d). The realised finest:coarsest ratio is R**(1+1/d) — about 11 for R=5 in 2-D and 8.5 in 3-D, not 5.

Source of truth: metric_density_from_gradient in src/underworld3/meshing/smoothing/metrics.py.

The skill is the first thing a session reads about the mover, so anyone sizing a mesh from it was asking for roughly twice the grading they thought. Also records that passing refinement takes the envelope branch, which ignores amp, lo/hi_percentile, mode and power.

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 — documentation, skills and tooling (#476, #580, #598, #599)

Reviewed together because none of them changes library behaviour and the useful
question is the same for all four: is the claim they make true of the code as it
stands today.

#580 — refinement=R is a factor on the background spacing

Verified against the source. The correction says coarsening="auto" is the
budget-conserving R**(1/d), so the envelope is h in [h0/R, h0·R**(1/d)] and
the finest:coarsest ratio is R**(1+1/d). metrics.py:587 reads

coar_val = ref_val ** (1.0 / cdim)

which is exactly that, and the arithmetic in the text checks: R=5 at d=2 gives
2.236 and a ratio of 11.18; at d=3, 1.71 and 8.55. The previous wording — "the
finest:coarsest grading ratio" — was wrong by that factor, so anyone who tuned R
against an observed ratio was tuning against a number roughly twice what they
asked for.

One thing the correction does not say: whether any existing example or notebook
was written against the old reading and now wants its R adjusted. Worth a grep
before this lands, since the doc change alone will make previously-tuned scripts
look wrong rather than making them right.

#476 — adapt cost microbenchmark

Its red CI is stale, not a defect in the change. The failures are in
test_0851_fault_network_3d.py and test_0851_std_reduction_method.py, neither
of which this PR touches — it changes one script. The run is from 2026-08-12
against a trunk that was red at the time. We re-triggered it; if it comes back
green the PR is a one-file update with nothing to argue about.

scalar_dt is the substantive addition: it coerces estimate_dt() output to a
float, taking nanmin over an array, and raises on a non-finite or non-positive
result. That is a benchmark script defending itself against an API that returns
different shapes, which is reasonable here — but the same coercion is what a
caller of estimate_dt() in a model script would have to write, and it belongs
behind the API rather than in each consumer. Worth an issue rather than a change
to this PR.

#598, #599 — cetz figure skill and the rotated-basis figure

These two are a pair: #598 corrects the skill's anchor guidance and adds
gotchas, #599 is a figure built to that skill's rule that geometry is computed
in Python and Typst only draws. #599's own docstring records why — an earlier
version connected nodes by a distance threshold and silently dropped several
from the mesh — which is the kind of failure the rule exists to prevent, and it
is good that the script says so where the next author will read it.

The reviewable question for the pair is whether #598's corrected guidance
matches what #599 actually does, since one is the rule and the other is the
worked example. They were authored together, so agreement is likely and
unchecked; if the skill is meant to be normative it would be worth having the
example's JSON schema referenced from the skill rather than described twice.

Neither changes library code, so the risk is confined to what a future author is
told.

Underworld development team with AI support from Claude Code