Swarm proxy as a polynomial per cell, PIC transport, and one characteristic trace per solver

[lmoresi]

Stacked on #703 (merged). Three things, none of which changes a solver's default mathematics.

Efficiency, for every semi-Lagrangian solver

• CharacteristicTrace (systems/ddt.py): one trace per solver per advecting velocity. It holds the departure points of the step per node set and segment chain, and the velocity levels cached by evaluation at the true nodes. The nodal and the integration-point managers trace through it; a solver attaches one trace to every history that follows the same velocity (share_characteristics) and delimits the step; a standalone manager keeps a private trace. Each history term keeps its own symbols, stencils and view.
• AdvDiffusionSLCN skips its flux history when the weak form does not read it (BDF orders, theta = 1). A state history (the viscoelastic stress) is never skipped.
• The parallel evaluator dropped its simplify flag on the way to the local evaluator, so any expression holding a mesh variable was sympy-simplified at every evaluation. Forwarded, and the internal defaults now match the public API (off).

Rotating Gaussian, h = 0.1, C = 0.25, answer identical to every printed digit: nodal SLCN 1350 to 250 ms per step, integration-point SLCN 2250 to 660. The SUPG-versus-SLCN cost ratio measured earlier carried both traps.

Swarm proxy as a polynomial per cell

SwarmVariable(proxy_location="cells", proxy_degree=2): a discontinuous proxy whose every cell holds the least-squares polynomial through the particles it holds (utilities/cell_polynomial_projection.py). Exact for polynomial particle fields, integrated exactly by the default rule, sharp at cell edges, with a gradient, rank-local. Thin cells take a linear patch fit, empty cells hold their previous value. The conservative particle-to-mesh transfer was measured and rejected: with irregular particles its error scales with the field value over the square root of the particle count (25% of a linear field at 21 particles per cell).

Particle transport

Lagrangian_Swarm with the cells proxy composed into AdvDiffusion is a particle-in-cell transport scheme. Two traps fixed on the way: the swarm history sampled itself at the first solve, after the first advection, losing a step (now sampled through a swarm pre-advection hook); and a P2 extrapolation into emptied cells was unbounded. particle_update="flip" is added as an option for the MPM line of work; PIC stays the default. On the rotating Gaussian PIC at 21 particles per cell reaches L2 5.2e-3 against the integration-point history's 9.1e-3 at a fifth of the cost.

Docs: docs/developer/subsystems/integration-point-variables.md, docs/developer/design/eulerian-supg-transport.md. Tests: 0064, 0066, 0067. Study: ~/+Simulations/integration_point_proxy.

Underworld development team with AI support from Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01MSGAFeA7qYXgkuw9ud8F2G

[Copilot]

🟡 Changes recommended

The new FLIP update path can compute residuals against a stale proxy (missing proxy refresh in _proxy_values_at_particles), and there is at least one mutable-default argument that should be corrected before approval.

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

Pull request overview

This PR extends Underworld3’s transport infrastructure to support higher-fidelity and more efficient semi-Lagrangian / PIC-style advection workflows, without changing default solver mathematics. It introduces (1) shared characteristic tracing per solver/velocity, (2) new swarm proxy targets at integration points and as per-cell polynomials, and (3) particle transport updates (PIC by default, optional FLIP-style update) alongside evaluator performance fixes.

Changes:

• Add CharacteristicTrace and sharing (share_characteristics) so multiple histories following the same velocity reuse departure points and cached velocity levels, and allow skipping unread flux histories.
• Add new swarm proxy locations: proxy_location="integration_points" (direct proxy at quadrature points) and proxy_location="cells" (rank-local per-cell least-squares polynomial projection via CellPolynomialProjector).
• Adjust evaluator defaults/forwarding to avoid unintended sympy.simplify costs; expand integration-point variable support to multi-component layouts; add/extend tests and docs.

File summaries

File	Description
tests/test_0067_integration_point_proxy.py	New tests covering integration-point proxies, cells polynomial proxies, and PIC/FLIP transport behaviors.
tests/test_0066_integration_point_slcn.py	Tests for shared characteristic tracing and standalone/private trace semantics.
tests/test_0065_integration_point_variable.py	Updates integration-point variable tests for multi-component support and projection/evaluate behavior.
tests/test_0064_quadrature_point_fe.py	Extends delta FE tests to vector layout and derivative tabulation helpers.
src/underworld3/utilities/cell_polynomial_projection.py	New per-cell least-squares polynomial projection used by proxy_location="cells".
src/underworld3/systems/solvers.py	Shares a characteristic trace across value/flux histories; skips flux-history update when weak form won’t read it.
src/underworld3/systems/ddt.py	Adds CharacteristicTrace, shared-trace wiring, and Lagrangian swarm transport extensions (PIC/FLIP, proxy_location support).
src/underworld3/swarm.py	Adds proxy_location to SwarmVariable, implements integration-point and cell-polynomial proxy updates, and adds pre-advection hooks.
src/underworld3/function/_function.pyx	Changes defaults to simplify=False and forwards simplify through global→local evaluator paths.
src/underworld3/discretisation/enhanced_variables.py	Declares/clarifies integration-point variable support for vector/tensor components.
src/underworld3/discretisation/discretisation_mesh_variables.py	Enables multi-component integration-point variables by creating vector-wrapped delta elements.
src/underworld3/cython/petsc_quadrature_fe.pyx	Adds num_components support to create_delta_fe() and derivative tabulation / affine-map helpers.
docs/developer/subsystems/integration-point-variables.md	Documents new swarm proxy locations and PIC/FLIP transport composition.
docs/developer/design/eulerian-supg-transport.md	Design note describing shared characteristic trace motivation and measured speedups.

Review details

Suppressed comments (1)

src/underworld3/systems/ddt.py:4161

• Same issue as above: this _proxy_values_at_particles() path should refresh the swarm proxy before evaluating the proxy mesh variable; otherwise FLIP can use stale proxy values if slot.sym wasn't accessed earlier in the step.

    def _proxy_values_at_particles(self, slot, coords, evalf):
        """The slot's proxy evaluated at the particles, shaped like ``slot.data``.

        A ``"cells"`` proxy is read through its own fitted polynomials (exact,
        no locator round trip); any other proxy through ``evaluate`` of the
        proxy mesh variable's symbol.
        """

• Files reviewed: 14/14 changed files
• Comments generated: 3
• 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 the follow-up commit: the proxy is refreshed first on every path of _proxy_values_at_particles, the misplaced copy of the helper in the nodal-swarm Lagrangian class is removed, bcs defaults to None, and the create_delta_fe docstring now describes the multi-component element.

[lmoresi]

Fixed in the follow-up commit: the proxy is refreshed first on every path of _proxy_values_at_particles, the misplaced copy of the helper in the nodal-swarm Lagrangian class is removed, bcs defaults to None, and the create_delta_fe docstring now describes the multi-component element.

[lmoresi]

Fixed in the follow-up commit: the proxy is refreshed first on every path of _proxy_values_at_particles, the misplaced copy of the helper in the nodal-swarm Lagrangian class is removed, bcs defaults to None, and the create_delta_fe docstring now describes the multi-component element.