Add PETSc nullspace support to Stokes

[gthyagi]

Summary

This PR adds generalized PETSc nullspace support to the Underworld Stokes saddle-point solver.

What changed

• Added petsc_use_pressure_nullspace to register the constant-pressure gauge mode on the coupled Stokes operator.
• Added petsc_velocity_nullspace_basis to register one or more exact velocity nullspace modes alongside the pressure mode.
• The solver now builds an orthonormal Stokes nullspace basis and attaches it to the operator and preconditioner matrices before each solve path, including after setFromOptions() reconfiguration.
• Cached nullspace objects are cleared when the solver DM / field layout is rebuilt.
• The solver checks for conflicting pressure Dirichlet BCs and raises a clear error instead of attaching an invalid pressure nullspace.
• The Stokes nullspace docstrings now document exact shell rigid-body rotation modes and how to register them:
  • 2-D annulus: (-y, x)
  • 3-D spherical shell: (0, -z, y), (z, 0, -x), (-y, x, 0)
• Added or updated regression coverage in:
  • tests/test_1013_stokes_pressure_nullspace.py
  • tests/test_1014_stokes_shell_nullspace.py

Why this is important

Incompressible Stokes pressure is only defined up to an additive constant. Making singular Stokes systems solvable by imposing a pressure Dirichlet condition, especially on an entire boundary, is stronger than the mathematical requirement and can change the solution.

This PR follows the standard PETSc approach instead:

• register the algebraic nullspace during the solve, and
• choose the reported pressure gauge afterward by subtracting a mean or applying another normalization.

This matters for annulus and spherical-shell benchmarks, including cases like the Thieulot k=0 branch, where pressure gauge freedom is real and boundary-wide pressure pinning is not the right tool. It also provides a clean path for exact shell rigid-rotation nullspaces when the PDE and boundary conditions truly admit them.

PETSc precedent

This follows the same pattern used in PETSc Stokes examples, where PETSc builds and attaches a nullspace instead of forcing pressure pointwise on a boundary:

• ex62.c CreatePressureNullSpace()
• ex69.c CreatePressureNullSpace()
• MatSetNullSpace manual page

Validation

• pixi run -e amr-dev pytest tests/test_1013_stokes_pressure_nullspace.py tests/test_1014_stokes_shell_nullspace.py -q

These tests pass locally and cover both the pressure-only nullspace path and shell-style pressure-plus-rotation nullspace bases.

[gthyagi]

Copying the reviewer-response summary from #90 here for reference:

Addressing the review items directly:

1. Branch naming

• I renamed the working branch on the fork to feature/stokes-nullspace.
• GitHub does not let me change the head branch of an existing PR, so #90 itself still points to codex/petsc-pressure-nullspace.
• To reopen this review thread, I restored codex/petsc-pressure-nullspace as an alias that points to the same commit as feature/stokes-nullspace.
• So the naming convention is implemented on the branch itself, but this specific PR cannot be retargeted to the renamed head branch.

2. Rigid-body modes design question

• Implemented.
• The Stokes nullspace support is now generalized beyond the constant-pressure mode.
• A new petsc_velocity_nullspace_basis property allows multiple exact velocity nullspace modes to be registered alongside the pressure mode.
• The docstrings now document the annulus rigid rotation (-y, x) and the three spherical-shell rigid rotations (0, -z, y), (z, 0, -x), and (-y, x, 0), plus how to set them on Stokes.

3. @pytest.mark.level_3

• Not changed intentionally.
• This test remains level_3 because it executes a real Stokes solve. The mesh is small and runtime is short, but by the project testing definitions it is still a solver / physics test rather than a lightweight setup-only test.

4. _pressure_dirichlet_bcs field id

• Implemented.
• The old hardcoded {1} fallback is removed.
• _pressure_dirichlet_bcs() now uses self.p.field_id exclusively and raises a clear error if the pressure field is unavailable.

5. Repeated nullspace attach calls after setFromOptions()

• Implemented.
• The repeated reattach calls remain, and there is now an inline comment explaining that PETSc may rebuild operator state after setFromOptions(), so the nullspace must be reattached before each solve path.
• The comment is placed once before the first repeated call rather than duplicated at every identical call site.

6. PETSc-style validation against conflicting pressure BCs

• Implemented.
• The solver now checks for pressure Dirichlet BCs before attaching the Stokes nullspace and raises a clear error if they are present.

7. Extra validation added

• Implemented.
• The original pressure-nullspace regression test was kept and strengthened.
• A new shell test covers pressure plus rigid-rotation nullspace bases for a 2-D annulus and a 3-D spherical shell.

The current fork branches feature/stokes-nullspace and codex/petsc-pressure-nullspace both point to the same latest commit so this reopened PR now includes the recent implementation updates as well.

[lmoresi]

Good - I'm happy to see this generalised to introduce null spaces into the stokes solver for velocity as well. We should add these to the individual meshes, since those are the places where we actually know what the null space should be.