Navier-Stokes with Eulerian SUPG momentum transport, and a partition-independent cell size (#687)

[lmoresi]

uw.systems.NavierStokesSUPG: the incompressible Navier-Stokes equations on the Stokes saddle-point solver with the momentum advection assembled implicitly and stabilised by the vector SUPG term, the counterpart of the scalar Eulerian solver in #673 (this PR stacks on that branch). Crank-Nicolson at order 1, BDF2 at order 2, the velocity history on the mesh; no stress history, the viscous stress at an earlier level is rebuilt from the stored velocity through the constitutive model, and pressure has no history. The advecting velocity is a choice: the second-order extrapolation 2uⁿ − uⁿ⁻¹ (one linear solve per step, the default), Picard passes on the latest iterate, or the unknown itself under Newton.

What the measurements say (design note, "Navier-Stokes with SUPG momentum transport"; study directory ~/+Simulations/navier_stokes_supg/):

• Kovasznay flow at Re 40: SUPG 6.6e-4, 2.6e-4, 6.7e-5 at h = 1/16, 1/32, 1/64; Galerkin (τ = 0) 1.1e-4, 1.6e-5; the semi-Lagrangian solver 5.8e-3, 2.9e-3 at seven times the cost per step. At this Reynolds number the stabilisation is not needed and costs accuracy; the missing viscous term in the first-derivative residual is the O(h²) consistency error. Newton, Picard and Courant 4 give the same steady state, as they must.
• Lid-driven cavity: Re 100 within 4% of Ghia on a 1/32 mesh at a fixed point; Re 400 at 1/48 within 6% (the mesh), where the extrapolated step at Courant 2 keeps a localised alternating mode of the lagged coefficient that one Picard pass, or Courant 1, removes; Re 1000 with geometric multigrid on the velocity block steps at one Krylov iteration per step but needs a longer run than was made here.
• Cylinder wake (DFG 2D-2, Re 100): Strouhal number 0.298 against the reference 0.295 to 0.305, the two fully implicit forms agreeing to three digits and the extrapolated step within 1% in frequency; the lift peak 11% low and the drag 23% low on the finer mesh, a deficit that does not close with resolution and points at the stabilisation's diffusion (the tau weights are the scalar solver's, untuned); the Galerkin control cannot run at this element Reynolds number, which is what the term is for. The semi-Lagrangian solver on the same mesh has the shedding 13% too slow at three times the cost.

Found and fixed on the way

• mesh.cell_size() was partition-dependent (mesh.cell_size() is partition-dependent: the per-cell radius comes from a kd-tree over the rank's centroids, so cells at partition boundaries get a different size on each rank count #687): the kd-tree radius picks the nearest centroid among the rank's cells, so the SUPG τ and the Nitsche penalty differed across a seam (two-rank Kovasznay error 5e-4 off serial, 1e-15 with a constant h), and after a deform it read stale vertex coordinates. The field now reports each cell's own radius from the DM's coordinates; the kd-tree radii still feed get_min_radius.
• The pressure gradient belongs in the SUPG residual: without it the term is O(1) at the exact solution and Kovasznay read three times worse.

Tests: the API contract (construction rules, one linear solve per step, Picard passes, the Stokes limit, runtime-constant timestep and theta), a two-rank Kovasznay error that matches serial to 1e-7, the scalar parallel reference re-recorded for the new cell size, and the Nitsche local-h tests reading the field's definition.

Deferred, recorded in the note: a recovered Laplacian to complete the residual for P2 velocity; the time-dependent (Cahouet-Chabard) pressure Schur approximation for large ρ|a|Δt/η; vector and tensor unknowns for the scalar solver and the viscoelastic stress equation, which is where the DDt V_fn contract gets generalised.

Underworld development team with AI support from Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_018T2VHUGaZiQVJ95qQ4DiSL

Closes #701 (the DDt timestep helper non-dimensionalises a quantity; fixed in 4f65d0f).
Closes #696 (a UWexpression no longer folds on its current value; 92ed8ac). Closes #702 (never-populated swarm advection is a clear error; 15da74b).

[lmoresi]

Adversarial review (self), findings and evidence.

1. The SUPG residual is incomplete for P2 velocity. It carries the time derivative, advection, pressure gradient and body force, not the viscous term. On Kovasznay this is the whole gap to Galerkin (6.6e-4 against 1.1e-4 at 1/16, converging at 1.4 to 2.0 against 3) and it will bias any smooth, resolved flow the same way. We ship it because the term needs second derivatives the kernels do not provide and the stabilisation is meant for convection-dominated cells; a recovered Laplacian is the fix and is on the list. Users at low element Reynolds number should set supg_weight = 0.
2. The theta rule's level-n stress is exact for constant viscosity only. It is formed as 2η ε̇(uⁿ) with the current effective viscosity, so a strain-rate dependent viscosity gets the wrong level-n stress at order 1. Documented; BDF2 avoids it. Not measured.
3. The extrapolated default has a failure mode, and we have seen it. Cavity Re 400 at Courant 2: a localised alternating mode of the lagged coefficient at the lid singularity, saturating at 0.1 in the max norm while the centreline values sit still. One Picard pass or Courant 1 removes it. The default stays extrapolated because Courant 1 is where the scheme is accurate anyway, but a user at Courant 2 and element Reynolds number 8 will meet this.
4. Every linearisation gives the same steady state, so Kovasznay and the cavity cannot rank them. Only the cylinder wake did: fully implicit forms agree to three digits, the extrapolated step is 1% off in frequency and 8% on the lift peak at Courant 1. One time-dependent case, one mesh; more would be better.
5. The cylinder drag is a quarter low and does not close with the mesh (28% at resolution 20, 23% at 40 with the cylinder cells at 1/160), while the Strouhal number and pressure difference sit on the reference. The likely cause is the streamline diffusion at the scalar solver's tau weights, untuned for momentum; the Galerkin control that would isolate it cannot run at this element Reynolds number (four Newton iterations and 22 s for the first step, the second never finishing). The drag against tau is the open measurement and the first thing to do after this lands.
6. The Re 1000 cavity is not a converged comparison: 1200 steps to t = 19 at 89 to 91% of Ghia's extrema and the secondary vortex not yet formed. It shows the solver stepping at one Krylov iteration per step with geometric multigrid at element Reynolds number 16, nothing more. Two earlier attempts failed for driver reasons (a collective inside a rank-0 branch; the hang watchdog on silent ranks), not solver reasons, and the note says so.
7. cell_size() changed meaning for every consumer: the own-centroid radius is 5 to 15% larger than the kd-tree radius on irregular meshes. The Nitsche penalty scaling and the scalar SUPG τ move by that much; test_1077's serial reference moved by 4e-7 relative and was re-recorded, test_1065 now reads the new definition. get_min_radius is untouched. Anyone with a tuned Nitsche γ on an irregular mesh will see a small change.
8. Parallel coverage is two ranks on a small mesh. Four ranks ran the cavity and cylinder without incident but no four-rank number was checked against serial.

[lmoresi]

Added 9d3aa5f: Swarm.advection failed on any rank holding no particles (#693, the reshape of an empty velocity array in estimate_dt), found when releasing passive tracers at the inlet of the cylinder benchmark on four ranks. One-line fix, no behaviour change for non-empty ranks.

[lmoresi]

Retargeted to development. This branch is a strict superset of #673 (no commit of feature/eulerian-supg-transport is missing here), so it carries the scalar SUPG solver, the DDt transport plugin, the Navier-Stokes solver and the naming (AdvDiffusion / NavierStokes are the composing solvers, *SLCN the semi-Lagrangian classes) as one change; #673 is closed as superseded. development is merged in (the landed cell_size of #692 replaces the branch's #687 version, same definition), the Picard loop's reductions are unconditional (test_0052), and the two-rank tests use a refinement hierarchy and a platform-tolerant comparison (they were red on CI at the 1e-8 and GAMG-fallback level); serial, two and four ranks agree to 3e-10. The #695 integral fix is also up separately as #700 for development.

🤖 Generated with Claude Code

https://claude.ai/code/session_018T2VHUGaZiQVJ95qQ4DiSL

[lmoresi]

Adversarial review of the branch head (three reviewers by area: the DDt plugin, the composing solvers and their tests, the development merge and the rename). Findings, evidence, and what was done.

Defects found and fixed (commit after dd17f95):

1. Symbolic.advection() raised TypeError because the base contract's _shape() helper was shadowed by the attribute Symbolic._shape; the helper is renamed. Every history flavour now answers zero.
2. A user-supplied EulerianSUPG on NavierStokes advected the stored level with the new velocity (V_fn_history was set only on the default path), a different scheme from the default and a u^{n+1} dependence in the Jacobian of the history term. The solver now sets the advecting velocity and the level carriers whoever built the manager.
3. The change-rate bookkeeping in both solvers read the manager's psi_star[0].array: with a SemiLagrangian manager under a units model that raised, and with a swarm-backed manager it broadcast particle-shaped data against mesh dofs. It now diffs a copy of the unknown; the drop-in solves under units and with a Lagrangian_Swarm history.
4. A supplied manager silently overrode the order/theta arguments; a mismatch is now an error, and the theta setter refuses a manager without theta.
5. tau() divided by the diffusivity in the two 1-D shapes (zoo at the manager's default of zero); guarded.
6. delta_t and the SUPG knobs were registered as persistent named expressions (never collected, and shared on a repeated name); they are created with unique names like the BDF coefficients.
7. stabilisation_flux accepts a bare scalar residual.
8. Rename: Ex_Navier_Stokes_Lid_Driven_Flow_2d.py imported the bare NavierStokes name and had flipped meaning; it now uses NavierStokesSLCN. Tutorial 9 prose, the solver-unification design table, and the API page (entries for the two composing classes and EulerianSUPG) corrected.

Verified and unchanged: the composed residuals of both solvers are symbolically identical to the pre-refactor ones at uniform SUPG weight for orders 1 and 2 and both advection modes (at the default Péclet weight 4 the flux carries the weight factor, by design, and the recorded rows were re-run with it). The merge with development is exactly the automatic merge with development taken in the seven cell-size conflict hunks, every branch-side change present and nothing from development lost. The advection switch to "implicit" puts the unknown in the manager and Newton converges quadratically. test_1078 runs full geometric multigrid on the velocity block on two ranks with the error at 2e-13 of the serial reference.

Known and not patched here:

• _DDtBase._dt stores the magnitude of a dimensional step; the composing solvers non-dimensionalise before writing it, but a manager driven by an SLCN solver with a Pint step carries an unscaled delta_t. The root is the existing TODO(BUG) on uw.non_dimensionalise receiving a raw quantity in ddt._as_float; to be raised as an issue.
• The repointed generic names change defaults for old scripts: the old NavierStokes was order 2 with discontinuous pressure and accepted flux_order/DFDt; the new one is order 1 with continuous pressure and refuses them. Scripts that need the semi-Lagrangian class use NavierStokesSLCN/AdvDiffusionSLCN. The published post on symbolic time derivatives shows the generic name with the semi-Lagrangian meaning and will need its examples updated at release.
• Restoring a pre-solve snapshot leaves the kernel delta_t at its last value until the next update_pre_solve (which rewrites it).

🤖 Generated with Claude Code

https://claude.ai/code/session_018T2VHUGaZiQVJ95qQ4DiSL

[Copilot]

🟡 Changes recommended

There are at least two correctness issues in the new/modified code (Navier–Stokes estimate_dt() unit semantics and shared mutable bcs list storage) that should be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Introduces Eulerian, fully implicit SUPG transport for both scalar advection–diffusion and incompressible Navier–Stokes by composing solvers from a DDt “transport manager” (history + assembled advection + stabilisation), while also fixing several core infrastructure issues uncovered by the new workflows (partition-independent per-cell size, robust aux-field packing after dropped MeshVariables, and JIT constant propagation into integral kernels).

Changes:

• Add composed Eulerian SUPG solvers: uw.systems.AdvDiffusion (scalar) and uw.systems.NavierStokes (momentum), powered by a new ddt.EulerianSUPG transport manager with runtime-constant timestep/weights.
• Fix correctness bugs affecting stabilisation/integrals and auxiliary-field layout: partition-independent mesh.cell_size(), stable aux packing when DM fields outlive Python variables, and PETSc DS constants set for integrals.
• Update/expand tests, examples, and docs to reflect new solver exports and to validate parallel/temporal-order/contract behavior.

File summaries

File	Description
tests/test_1110_advDiffAnnulus.py	Switch test to AdvDiffusionSLCN naming
tests/test_1100_AdvDiffCartesian.py	Switch test to AdvDiffusionSLCN naming
tests/test_1100_advdiff_supg_rotating_gaussian.py	New accuracy/behavior tests for Eulerian SUPG scalar transport
tests/test_1058_dropped_meshvariable_aux_layout.py	New regression tests for aux-field packing after dropped MeshVariables
tests/test_1057_ddt_transport_plugin.py	New contract tests for DDt “transport plugin” behavior/shapes
tests/test_1056_navier_stokes_supg_api.py	New API/contract tests for Eulerian SUPG Navier–Stokes
tests/test_1055_advdiff_supg_api.py	New API/contract tests for Eulerian SUPG AdvDiffusion
tests/test_0820_template_parameter_propagation.py	Update AdvDiffusion solver reference to SLCN
tests/test_0650_recursion_prevention_regression.py	Update AdvDiffusion solver reference to SLCN
tests/test_0610_navier_stokes_slcn_projection.py	Update NavierStokes solver reference to SLCN
tests/test_0506_tensor_evaluate.py	Update NavierStokes solver reference to SLCN
tests/test_0503_integral_expression_constants.py	New regression tests for expression constants in integrals
tests/test_0200_solver_smoke.py	Update AdvDiffusion solver reference to SLCN
tests/test_0052_collective_guard_scan.py	Add collective-safety reasoning for NavierStokes Picard loop
tests/test_0008_snapshot_realsolver.py	Update AdvDiffusion solver reference to SLCN
tests/test_0006_memory_leak.py	Update AdvDiffusion solver reference to SLCN
tests/parallel/test_1078_navier_stokes_supg_parallel.py	New parallel partition-independence test for NS SUPG
tests/parallel/test_1077_advdiff_supg_parallel.py	New parallel partition-independence test for AdvDiff SUPG
src/underworld3/utilities/custom_mg.py	Prevent MG hierarchy pickup when solver owns its PC (_pc_option_prefix is None)
src/underworld3/utilities/_jitextension.py	Fix aux component offsets using DM field list (handles orphaned DM fields)
src/underworld3/systems/solvers.py	Factor shared adv/diff resolution dt + shared dt dimensionalisation
src/underworld3/systems/navier_stokes_eulerian.py	New composed Eulerian SUPG Navier–Stokes solver implementation
src/underworld3/systems/ddt.py	Add transport-manager contract methods + new EulerianSUPG manager
src/underworld3/systems/advection_diffusion_eulerian.py	New composed Eulerian SUPG advection–diffusion solver
src/underworld3/systems/init.py	Rewire exports: AdvDiffusion/NavierStokes now composed Eulerian; add *SLCN names
src/underworld3/discretisation/discretisation_mesh.py	Partition-independent cell_size() field backed by per-cell radii
src/underworld3/cython/petsc_maths.pyx	Ensure DS constants are set for integral kernels (expression constants)
src/underworld3/analytic/transport.py	Add uw.analytic.RotatingGaussian oracle
src/underworld3/analytic/_base.py	Fix scalar-vs-1x1 symbol mismatch in analytic error calculation
src/underworld3/analytic/init.py	Export/register RotatingGaussian
docs/examples/WIP/developer_tools/SOpt.py	Update AdvDiffusion reference to SLCN
docs/examples/Tutorial_Thermal_Convection_Units.py	Update AdvDiffusion reference to SLCN
docs/examples/heat_transfer/advanced/Ex_Poisson_v.SLCN.py	Update AdvDiffusion reference to SLCN
docs/examples/fluid_mechanics/README.md	Add new Eulerian NS SUPG example entries
docs/examples/fluid_mechanics/advanced/Ex_NavierStokesRotationTest.py	Update NavierStokes reference to SLCN
docs/examples/fluid_mechanics/advanced/Ex_Navier_Stokes_SUPG_Taylor_Green_Vortex.py	New Eulerian NS SUPG validation example
docs/examples/fluid_mechanics/advanced/Ex_Navier_Stokes_SUPG_Lid_Driven_Cavity.py	New Eulerian NS SUPG cavity benchmark example
docs/examples/fluid_mechanics/advanced/Ex_Navier_Stokes_Lid_Driven_Flow_2d.py	Update imports/usage to NavierStokesSLCN
docs/examples/fluid_mechanics/advanced/Ex_Navier_Stokes_Benchmarks_NS_DFG_2d.py	Update NavierStokes reference to SLCN
docs/examples/fluid_mechanics/advanced/Ex_Navier_Stokes_Benchmarks_NS_DFG_2d_SLCN.py	Update NavierStokes reference to SLCN
docs/examples/convection/intermediate/Ex_MoresiSolomatov_Convection_Cartesian.py	Update AdvDiffusion reference to SLCN
docs/examples/convection/intermediate/Ex_Convection_Cartesian_ThermoChem.py	Update AdvDiffusion reference to SLCN
docs/examples/convection/intermediate/Ex_Convection_5_SLCN_Cartesian-Yield.py	Update AdvDiffusion reference to SLCN
docs/examples/convection/intermediate/Ex_Convection_4_SLCN_Cartesian-NL.py	Update AdvDiffusion reference to SLCN
docs/examples/convection/advanced/Ex_Convection_Cylinder.py	Update AdvDiffusion reference to SLCN
docs/examples/convection/advanced/Ex_Convection_Cartesian-Swarm.py	Update AdvDiffusion reference to SLCN
docs/examples/convection/advanced/Ex_AdvectionDiffusionSwarm_RotationTest.py	Update AdvDiffusion reference to SLCN
docs/examples/convection/advanced/Ex_AdvectionDiffusionSUPG_RotationTest.py	New Eulerian AdvDiffusion SUPG example using RotatingGaussian
docs/examples/convection/advanced/Ex_AdvectionDiffusionSLCN_RotationTest.py	Update AdvDiffusion reference to SLCN
docs/developer/index.md	Add Eulerian SUPG design note to toctree
docs/developer/design/SOLVER_UNIFICATION_DESIGN.md	Update naming note for NavierStokesSLCN vs composed NavierStokes
docs/beginner/tutorials/9-Unsteady_Flow.ipynb	Update tutorial to use NavierStokesSLCN
docs/beginner/tutorials/8-Timestepping-coupled.ipynb	Update tutorial to use AdvDiffusionSLCN
docs/beginner/tutorials/7-Timestepping-simple.ipynb	Update tutorial text/code to use AdvDiffusionSLCN
docs/beginner/tutorials/15-Thermal-convection-with-units.ipynb	Update tutorial to use AdvDiffusionSLCN
docs/beginner/tutorials/14-Timestepping-with-physical-units.ipynb	Update tutorial to use AdvDiffusionSLCN
docs/api/solvers.md	Document new composed solvers + EulerianSUPG transport manager
docs/advanced/semi-lagrangian-time-integration.md	Add section describing Eulerian alternative
docs/advanced/index.md	Add Eulerian solver docs to advanced toctree
docs/advanced/eulerian-navier-stokes.md	New advanced doc page for composed Eulerian Navier–Stokes
docs/advanced/eulerian-advection-diffusion.md	New advanced doc page for composed Eulerian AdvDiffusion

Review details

• Files reviewed: 62/62 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[lmoresi]

Fixed in cef446a: the accuracy estimate goes through _dimensionalise_dt, as the scalar solver's does, so both bases return a time quantity under a scaling model and a plain number otherwise (test_1056 test_estimate_dt_carries_time_units_on_both_bases).

[lmoresi]

Fixed in cef446a: the default is bcs=None and becomes a fresh list. A caller's list is kept by reference on purpose, and the code now says so: the solvers pass their live essential_bcs so that conditions added after construction reach the manager's projections; copying would silently drop them. The older flavours (Eulerian, SemiLagrangian, Symbolic) carry the same bcs=[] default and are left as they are in this PR.