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.

[lmoresi]

Fix pushed — 1c5ef1c

Root cause of the five test failures

The round-trip was asymmetric:

• Setter stored plain-float input as-is (treated it as already non-dim).
• Getter unconditionally called uw.scaling.dimensionalise(L_nd, meter).

Under an active scaling context (which is present in the CI process even when the test fixture doesn't set one — default ~Earth scale ≈ 2.9×10⁶ m), smoothing_length = 0.05 read back as 145000. Same pattern for every failing assertion (0.1 → 290000, 0.2 → 580000, etc.) — all L × 2,900,000.

A second, quieter bug: uw.non_dimensionalise(L) on a Pint Quantity returns a UWQuantity that refuses sympify. The previous try/except fell back to L.magnitude — the dimensional magnitude — and stored it as if it were non-dim, completely ignoring the scaling context. Unit-bearing input was silently broken.

Fix

• Setter tracks _smoothing_is_dimensional based on whether the input has .magnitude / .units.
• For dimensional input: route through non_dimensionalise, then float(getattr(L_nd, "magnitude", L_nd)) to extract the actual non-dim numeric.
• For plain numbers: float(L) and store as-is.
• Getter returns a Pint Quantity in metres iff _smoothing_is_dimensional; otherwise the plain non-dim float that was stored.
• Negative smoothing_length now raises ValueError instead of the getter silently returning None.
• Fix applied to all three concrete sites (SNES_Projection, SNES_Vector_Projection, SNES_MultiComponent_Projection); SNES_Tensor_Projection inherits.

Copilot review notes — disposition

#	Concern	Disposition
1	non_dimensionalise → sympify fails for Pint Quantity	Fixed — extract .magnitude from UWQuantity before squaring
2	Getter returns None for negative smoothing	Fixed — setter validates, getter raises
3	No unit-bearing test	Fixed — new test_smoothing_length_pint_quantity_roundtrip uses uw.Model + use_nondimensional_scaling(True) + uw.quantity(0.05, "m"), asserts α = (0.05/1000)² = 2.5e-9 and Pint round-trip
4	Same issue in vector projector	Fixed
5	Same issue in multi-component projector	Fixed

Local verification

$ pixi run -e runtime python -m pytest -v tests/test_0505_projection_smoothing_length.py
test_scalar_smoothing_length_roundtrip PASSED
test_vector_smoothing_length_roundtrip PASSED
test_tensor_smoothing_length_roundtrip PASSED
test_multicomponent_smoothing_length_roundtrip PASSED
test_smoothing_setter_keeps_alpha_view PASSED
test_smoothing_length_pint_quantity_roundtrip PASSED  ← new
test_smoothing_length_negative_raises PASSED          ← new
test_smoothing_length_smoothes_a_step PASSED
8 passed in 8.54s

Underworld development team with AI support from Claude Code

[bknight1]

Thanks for this @lmoresi, I'll give it a try