projection: unit-aware smoothing_length API on the four Projection classes

[lmoresi]

@benknight — this is the bit you asked me about: a length-scale-aware way to set the smoother on Projection (and friends) instead of the unit-less smoothing knob. Splitting it out of a larger meshing branch so it can land independently.

Summary

Adds an L-valued, unit-aware smoothing_length accessor to the four projection classes:

• SNES_Projection
• SNES_Vector_Projection
• SNES_Tensor_Projection
• SNES_MultiComponent_Projection

The existing smoothing knob is preserved unchanged (units of length², historically used as a tiny numerical regulariser); smoothing_length is a parallel view with the physical convention smoothing = smoothing_length². The two stay consistent: setting one updates both.

Why — the mathematics

The L2-projection solvers all minimise a Tikhonov-regularised misfit

$$\min_u; \tfrac12!\int_\Omega (u-\tilde f)^2 ;+; \tfrac{\alpha}{2}!\int_\Omega |\nabla u|^2 ,$$

whose Euler–Lagrange equation is the screened-Poisson equation

$$u ;-; \nabla!\cdot!\bigl(\alpha,\nabla u\bigr) ;=; \tilde f .$$

The free-space Green's function of $\bigl(1 - \alpha\nabla^2\bigr)$ decays as $\exp(-r/L)$ where

$$L ;=; \sqrt{\alpha},$$

so the projection acts as a Gaussian-like convolution of width $L$, obtained implicitly by one elliptic solve — no kernel is ever assembled. In Fourier space the transfer function is

$$\widehat{u}(k) ;=; \frac{1}{1 + k^{2} L^{2}},\widehat{\tilde f}(k),$$

so features at scale $\ll L$ are damped, features at $\gg L$ pass through, and features at $\sim L$ are attenuated by ≈ 1/2.

This makes $L$ — not $\alpha$ — the natural physical knob: you ask for "smooth this field at scale $L$" and the solver delivers it.

API

proj = uw.systems.Projection(mesh, V)

# L-valued, unit-aware
proj.smoothing_length = 0.05                        # plain ND scalar
proj.smoothing_length = 5 * uw.scaling.units.km     # Pint Quantity → ND'd

print(proj.smoothing)         # α = L²  (sympy)
print(proj.smoothing_length)  # Pint Quantity in m when a scaling
                              # context is set; otherwise √α

Identical surface on Vector_Projection, Tensor_Projection, and MultiComponent_Projection. The class docstrings now carry the screened-Poisson derivation (with guidance: L ≳ h is needed for any real filtering; L ≈ 1–2·h is a useful light de-noising default).

Test plan

tests/test_0505_projection_smoothing_length.py is new and locks:

• L → α = L² round-trip on all four classes
• α → smoothing_length = √α round-trip
• Unit-aware getter returns a Pint Quantity in length units
• End-to-end behaviour: smoothing a step function at successively larger L monotonically shrinks the projected field's peak-to-peak range (the screened-Poisson low-pass behaviour the docstring promises)
• Existing tests/test_0504_projections.py and tests/test_multicomponent_projection.py pass unchanged

tests/test_0505_projection_smoothing_length.py ......       [100%]
6 passed in 6.4s
13 passed in 40.8s   (existing projection tests)

Underworld development team with AI support from Claude Code

[Copilot]

Pull request overview

This PR adds a new, physically meaningful unit-aware smoothing_length accessor across the Projection solver family, intended as a length-scale view of the existing smoothing (α) coefficient with the convention α = smoothing_length². It also expands class/property docstrings to document the screened-Poisson interpretation and introduces a new test module to lock the API.

Changes:

• Adds smoothing_length property (getter/setter) to SNES_Projection, SNES_Vector_Projection, and SNES_MultiComponent_Projection (and therefore to SNES_Tensor_Projection via inheritance), keeping smoothing and smoothing_length consistent.
• Updates projection class/property docstrings with a screened-Poisson / Helmholtz derivation and guidance on choosing the filter scale.
• Adds a new test module to check round-trips and end-to-end monotone smoothing behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
src/underworld3/systems/solvers.py	Adds smoothing_length API and substantial docstring updates for projection solvers.
tests/test_0505_projection_smoothing_length.py	New tests for round-trip behavior and a basic end-to-end smoothing monotonicity check.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.