Figure: where the rotation lives under rotated boundary conditions

[lmoresi]

Drawn for R1 in the technical-notes writing plan (Boundary conditions on non-planar boundaries), which is not yet written. Parked here rather than left in a scratch directory that would not survive the session — it follows the per-figure layout the cetz skill documents, and moves to the note's own examples/ and figures/ when that article is created.

What it argues

Left: a free surface with an inflection — rising on the left, falling on the right — so the outward normal swings through a wide range and the curvature changes sign. That is precisely the case no global coordinate system straightens out, which is why a per-node rotation is the general answer and solving in spherical components is not.

Right: where the rotation lives, and the point is that it is contained. The velocity solve is rotated and carries its multigrid with it. The fieldsplit / Schur solve abuts it and never handles a rotated vector, because the pressure block carries no boundary condition of this kind. A single un-rotation sits on the boundary between them and branches — into the Schur solve, and out to output, advection and the surface update.

Four operations genuinely carry Q: the operator, the right-hand side, the solution, and the prolongation. The Galerkin coarse operators inherit it via RAP and the SVD coarse solve follows from what they inherit, so those are drawn as consequences rather than as further obligations.

Reproducibility

generate-rotated-basis.py → rotated-basis-data.json → rotated-basis.typ → PNG and SVG. Geometry is computed in Python and handed to Typst as JSON, per the skill's rule: a real Delaunay triangulation, culled by centroid against the non-convex surface, with alternate rows staggered so the triangles are not degenerate. Verified to rebuild from the committed sources.

Companion to #598, which corrects the cetz gotchas this figure turned up.

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