UWTN 2026-014: Setting Up Full Multigrid

[lmoresi]

The G1 note from WRITING-PLAN.md, and the pair to UWTN 2026-011. Ready to merge.

What Underworld's geometric multigrid is worth against the algebraic multigrid it falls back to, measured rather than asserted, and how to get a mesh that can use it.

What it says

• Getting a hierarchy. refinement at mesh construction, what dm_hierarchy holds, and why the same resolution reached through a fine cellSize gives you nothing to coarsen onto. The preconditioner property, and reading preconditioner_settings / pc_fallbacks rather than inferring the configuration from timings.
• Curved boundaries. Why refinement alone leaves a polygon, and the snapping callback that fixes it.
• What the coarse mesh leaves behind, and that relax() loosens the imprint without disturbing the refinement relation — the hand-off to UWTN 2026-011.
• The measurements. Against viscosity contrast and against problem size, in flops per unknown and in seconds, both preconditioners at PETSc's defaults.

The finding

On SolKz, whose viscosity varies smoothly across the box, the geometric hierarchy is worth about a factor of two in arithmetic and nothing in wall clock — 1.8 against 1.9 at 747 007 unknowns. GAMG does more arithmetic in denser, more regular operators and runs at 3.4–4.6 Gflop/s against FMG's 1.6–2.4, and the two effects cancel. Both converge on O(N).

Put the same total contrast into a band a twentieth of the box thick and that changes. FMG is almost indifferent; GAMG's cost climbs with the contrast, and at 10⁶ it does not converge — 20 000 multigrid cycles per velocity solve without reaching tolerance. That is the case for keeping a hierarchy when you can, and it is the figure the note ends on.

What was checked before claiming it

An earlier draft of this note claimed an order of magnitude on the strength of measurements taken against a GAMG that was misconfigured by us. That is fixed, and the fixes are underworld3#584 (pc_mg_type=additive where PETSc defaults to multiplicative; the velocity operator reaching GAMG with block size 1 on a vector field) and #576 (the Stokes outer Krylov inheriting gmres while its sub-blocks are Krylov solves). Correcting the outer alone moved the published contrast table at 10⁶ from 3.8 to 1.8 for FMG and 9.1 to 4.0 for GAMG.

So the baseline here is the fairest one available:

• Both preconditioners run at PETSc's defaults, with GAMG told the velocity field has two components per node.
• Stripping GAMG back to stock PETSc makes it worse on the band, not better — 38.7× FMG against 16.8× — so the finding is not an artefact of our remaining settings. pc_gamg_threshold=0.05 improves it to 11.9× and still does not close the gap.
• The band is resolved: it spans about six cells here, and refining four and sixteen times further moves GAMG's disadvantage on the band relative to the smooth problem at the same size 5.5 → 7.9 → 8.0. It is not an under-resolution artefact.
• Nothing reported is truncated. The default velocity iteration cap silently cuts these solves off (underworld3#585), which cost me one wrong conclusion before it was caught; every number here comes from a run that converged with no count on the cap.

Notes

• Both example scripts and both figures ship in examples/, stamped at underworld3 0addec15. The measurement script sets the corrected options explicitly, so the numbers do not depend on whether #584 has landed — verified identical either way. When #584 merges the script can drop them and the stamp moves; the numbers will not change.
• On publication, UWTN 2026-011 needs a v2 carrying the reciprocal link — it refers to this note in prose because it did not exist yet. WRITING-PLAN.md records that against this entry.
• ID 2026-014: 2026-012 belongs to gthyagi's note on UWTN 2026-012: Benchmarking Stokes Flow in Annulus and Spherical-Shell Geometries #11 and 2026-013 to the news post.

pixi run build clean, pixi run validate clean, 2243 asset references all present, PDF builds.

Underworld development team with AI support from Claude Code

[github-actions]

Preview

• Setting Up Full Multigrid — PDF

Or the whole site.

Built from 6a5b02a. Shows notes at draft and review, which the published site withholds. Not indexed, no comments, and not the citable version. Confirmed serving this commit before this was posted.

[lmoresi]

Adversarial review — UWTN 2026-014

Read against the merged state of the branch. One item blocks, three are wrong as written, one is cosmetic.

1. The cross-reference is a dead link on merge

/testing-a-solver-against-exact-solutions/ is UWTN 2026-015, which is #22 and still open. Merging this note publishes a link to a page that does not exist. scripts/check_links.py will not catch it — it resolves external hosts only, and reported nothing.

Three ways out, in order of preference:

• merge UWTN 2026-015: Testing a solver against exact solutions #22 first;
• merge this and accept a dead link for as long as UWTN 2026-015: Testing a solver against exact solutions #22 takes;
• drop the clause and add it in the same pass that gives UWTN 2026-011 its v2 reciprocal link, which this note already owes.

2. "GAMG does slightly more work" understates the table above it

Both solver configurations handle the whole range ... there is almost no change in the amount of work required or time taken to solve. GAMG does slightly more work but does so a little more efficiently.

The table directly above reads 2.2, 3.3, 4.0, 4.0 against 1.0, 1.3, 1.6, 1.8. That is two to two-and-a-half times the work, not "slightly" more, and GAMG's own row rises by 80% across the sweep rather than showing "almost no change". Twenty lines later the note says the hierarchy is "worth roughly a factor of two", which is the same quantity described a second way. A reader who compares the two sentences finds them in conflict.

Suggested: "Both handle the whole range, and neither degrades relative to the other as the contrast rises. GAMG does a little over twice FMG's arithmetic throughout, and gives about half of that back in rate."

3. "a factor of two in throughput" is backwards

So the geometric hierarchy is worth roughly a factor of two in throughput

Throughput is work per unit time, and it is the one measure on which GAMG wins here — 3.4–4.6 Gflop/s against 1.6–2.4, which the next paragraph says. The factor of two is in arithmetic. As written the sentence claims the opposite of the table.

Suggested: "worth roughly a factor of two in arithmetic".

4. The heading promises what the section then withdraws

## When the choice matters sits over the smooth case, whose finding is that the choice does not much matter — two-fold in flops, nothing in wall clock. The section where it does matter is the next one. Consider ## What it costs on a smooth problem and letting the concentrated section keep the "when it matters" role.

5. Minor

relative to the constant-viscosity FMG run with a fixed target iteration tolerance across the board.

The tolerance clause attaches to "run" rather than to the comparison, so it reads as though the baseline had a special tolerance. Splitting it into its own sentence fixes it.

What we checked and found sound

• Every number traces to examples/fmg-vs-gamg.py output, and both figures ship their scripts.
• The scaling table now runs both preconditioners to the same largest size; the earlier version compared FMG at 747 007 against GAMG at 186 879.
• No reported run is truncated. This matters more than it sounds: the default velocity cap silently cuts these solves off (underworld3#585) and produced one wrong conclusion during the work before it was caught.
• The concentrated-band claim survives the two controls that could have killed it — stripping GAMG back to stock PETSc makes it worse (38.7x against 16.8x), and refining the band from 1.6 to 6.4 cells across moves the penalty 5.5 → 7.9 → 8.0 rather than removing it.
• The exponents quoted match the per-step values the script prints.

Underworld development team with AI support from Claude Code