Underworld3 v3.2.0

Highlights

• Free surface in three dimensions on a spherical shell. Surface height relaxes toward the
  equilibrium topography implied by the stress field, using an exponential integrator that is
  L-stable and cannot overshoot. The scheme is now dimension-general. Preview: the method and its
  validation are written up in full, but there is no runnable example yet.

• The viscoelastic-plastic regressions reported at v3.1.0 are fixed. All seven tests suspended
  for that release now pass, without the tests being altered — the fixes came from #493 (Stokes
  uu_G3 transposed tangent and TI un-frozen Picard, closing #457 at source), #535 (TI-VEP
  yield-limited weak-plane viscosity) and #475 (yield_anchor), closing #390.

• Full multigrid preconditioning is now Supported, the only capability promoted since v3.1.0.
  It keeps the Stokes velocity solve at a steady ~5 iterations as the mesh distorts, where the
  algebraic alternative runs a volatile 64–131. The gain is predictability rather than raw speed.

• Faults as real discontinuities in the mesh, rather than smeared weak zones. A fault is
  specified once — a trace, its place in a hierarchy, the properties it carries — then realised
  either as a split-node cut with node-pair contact laws or as a volumetric weak plane. The largest
  single body of work this quarter. Preview.

• Particle proxy updates are dramatically faster. The IndexSwarmVariable proxy update was
  vectorised (#374): 77× for particle-to-node and 17× for node-to-particle, measured on a 60×60
  mesh with 130k particles. It shows up directly in any multi-material model carrying material
  indices on a swarm.

• A materials registry that separates what a material is from where it is, so one rheology can
  be attached to particles or to regions without being rewritten.

• A rebuilt container that cannot drift from the development environment. Two-stage pixi build,
  multi-architecture (amd64 and arm64), resolved from pixi.lock — the drift between container and
  Binder that broke the v3.1.0 container build is no longer possible. Automated Gadi/HPC images
  alongside it.

• Fifteen fixes to collective participation under MPI, covering the failure mode where one rank
  takes a shortcut and every other rank waits forever in the matching collective. Includes the
  empty-rank swarm-save deadlock (#680).

Supported (validated)

• Units and Scaling System — Pint-backed dimensional quantities, non-dimensionalisation, and unit-aware expression arithmetic.
• Winslow Mesh Smoother — Parallel-safe interior mesh smoothing (smooth_mesh_interior) — the foundation the adaptive movers and geometric multigrid build on.
• Geometric Multigrid / FMG Preconditioner — Automatic geometric full-multigrid preconditioning for the SNES solvers on refinement meshes (the preconditioner property).
• Constant Nullspace (singular scalar solvers) — SNES_Scalar.constant_nullspace returns the minimum-norm solution for pure-Neumann / closed-manifold scalar problems whose operator has a constant kernel (the singular Poisson case).
• Boundary Conditions on Curved Surfaces — Free-slip and traction BCs applied with true geometric normals rather than the flat-facet approximation, via a nodal rotation of the solution space.
• SUPG-Stabilised Transport — Streamline-upwind Petrov-Galerkin stabilisation as a transport plugin, the default for both advection-diffusion and Navier-Stokes.
• Variable Data Access Contract — One canonical write path for mesh and swarm variable data: a read-only snapshot, intercepted ufunc writes, and a context manager that flushes every dirty variable collectively.
• Checkpoint and Restart — In-memory snapshots, on-disk checkpoints, and exact same-mesh reload through the PETSc DMPlex section/vector path.
• Analytic Benchmark Solutions — Closed-form solutions (SolKx, SolKz, SolDB, Richards, transport, Zhong2008 shell response) used to verify solver convergence rates.
• Materials Registry and Distribution — Separates what a material is (a named property table) from where it is (particle-carried or region-based), so one rheology can be attached either way without rewriting it.
• Stress Tensor Visualisation — Principal-stress glyphs and stress trajectories from projected deviatoric stress plus pressure.
• Constitutive Models — Viscous, viscoplastic, viscoelastic-plastic, diffusion and Darcy relationships plugged into the SNES solvers. Transverse isotropy is a separate entry: it carries an unresolved accuracy drift.
• Material History Transport — Semi-Lagrangian, backward-differentiation and Adams-Moulton flux forms behind one D/Dt interface. Storage of history at quadrature points is a separate entry.

Preview (present, unguaranteed)

• MMPDE Mesh Mover / Adaptive Remeshing — follow_metric / OT mesh movement and variable transfer for anisotropic mesh adaptation.
• Transverse-Isotropic Rheology — Anisotropic viscosity with a director, including transverse-isotropic VEP reporting the yield-limited weak-plane viscosity. Present and much improved this release; one accuracy drift remains unexplained.
• Fault Networks and Split-Node Faults — Faults as real mesh discontinuities rather than smeared weak zones: specified once as a trace and hierarchy, then realised as a split-node cut with contact laws or as a volumetric weak plane.
• Integration-Point Variables — Material history stored at quadrature points rather than at mesh nodes, with particle repopulation, mid-time swarm stepping and viscoelastic stress history carried on particles.
• Point Location and Function Evaluation — Locating points in a distributed mesh and evaluating symbolic functions there, with an RBF fallback ladder and cheap rejection of foreign points.
• Solver Control and Reporting — Per-iteration solver callbacks, convergence and tolerance reporting, and detection of runs that stall.
• Consistent Boundary Flux Recovery — Recovers a pointwise surface flux (heat flux, or traction) from the interior residual at essential-BC nodes, de-smeared with the boundary mass matrix.
• Prognostic Free Surface — Surface height relaxes toward the stress-derived equilibrium topography using an L-stable exponential integrator that cannot overshoot; now dimension-general and running on a 3-D spherical shell.
• Geoid and Self-Gravity Response (experimental) — Coefficient-only geoid and self-gravity response functions for spherical shells and cylindrical annuli, independent of the Stokes discretisation.

Bug Fixes

• Point evaluation recovered boundary-face query points that DMLocatePoints silently dropped on
  quadrilateral and hexahedral meshes (#391, #392)
• read_timestep now keeps one coordinate frame across sessions — DG0 fields no longer collapse on
  reload (#398, #269)
• The MMPDE mover was a silent no-op on graded meshes; a per-cell collapse floor fixes it (#420, #419)
• Finite SPD fallback for fully-degenerate metric evaluations in MMPDE (#368, #352)
• Swarm save no longer deadlocks when a rank holds no particles, and estimate_dt no longer crashes
  on reshape (#680)
• Cell-family detection corrected on empty MPI ranks (#691)
• Parallel plex-point to coordinate-row mapping in kd-tree and face navigation (#363, #360)
• Swarm proxy refresh under an active units model (#434, #426)
• Three-dimensional boundary reaction flux recovery (#404)
• Seam-cone reconciliation and recovered orientation — parallel finite elements now work on placed
  meshes (#521, #520)
• GenericFluxModel flux storage preserves symbolic field dependencies (#455)
• flux_jacobian is settable, for custom Jacobian tangents (#362)
• The SNES converged-reason table was off by one against PETSc (#444)

New Features

• Geoid and self-gravity postprocessing for spherical shells, with a cylindrical-annulus
  counterpart and a reaction-based shell projection (#591, #648, #686)
• Zhong (2008) propagator-matrix analytic response (#594)
• dmfield_evaluate exposed from PETSc (#436)
• Mesh-files-only internal spherical-shell generation (#592)
• Custom multigrid parallel support with NVB adapt-on-top (#369, #365)
• Measured point-location capability with a NaN/RBF fallback ladder (#395, #392)

Improvements

• IndexSwarmVariable proxy updates vectorised — 77× particle-to-node, 17× node-to-particle (#374)
• Adaptation and redistribution renamed for intent: node_redistribution alongside an engine-less
  adapt() (#372)
• Solve reporting is on by default, with bounded and resumable difficulty solves (#377)
• Style gates in CI: a deprecated-pattern scanner with an allowlist ratchet (#364)

Breaking Changes

• The Null_Boundary fake natural BC, and the label it was built on, are removed (#503)
• synchronised_array_update now performs a collective dirty-variable flush, replacing rank-local
  event replay (#383, #379)
• Rotated and block constraints are now mutually exclusive (#590)
• SemiLagrangian no longer accepts the unused swarm_degree, swarm_continuous or _workVar
  arguments (#705, #704)
• Slip normals are now taken per boundary rather than from mesh.Gamma_P1, and the mesh factories
  no longer recommend it. Gamma_P1 itself remains, deprecated — use Gamma in integrands and BCs,
  or boundary_normal for a per-boundary P1 normal field (#659, #654, #538)

Contributors

Thanks to everyone who contributed to this release:

• Louis Moresi (@lmoresi)
• Thyagarajulu Gollapalli (@gthyagi)
• Ben Knight (@bknight1)
• Neng Lu (@NengLu)
• Julian Giordani (@julesghub)
• Juan Carlos Graciosa (@jcgraciosa)
• Saurabh Shukla (@ss2098)
• @tiannh7

461 commits since v3.1.0, touching 136 files under src/.