Forward-from-nodes history; semi-Lagrangian schemes named by trace and launch; every history equals serial in parallel

docs/advanced/eulerian-advection-diffusion.md

@@ -80,11 +80,18 @@ is resolved in time (a fraction of a feature width per step), the Eulerian solve
 is cheaper and more accurate; if the step is deliberately long relative to the
 transported features, the semi-Lagrangian solver is the one that survives it.
 
-## The three transport managers
+## The transport managers
 
-`DuDt` selects the transport, and three managers are worth considering for a
-scalar field. The choice turns on the Courant number the model runs at and on
-whether the model is carrying particles for another reason.
+`DuDt` selects the transport. The choice turns on the Courant number the model
+runs at and on whether the model is carrying particles for another reason.
+
+The semi-Lagrangian schemes are named by two choices, and
+`uw.systems.ddt.SemiLagrangian(..., trace=, launch=)` builds any of them:
+`trace` is `"backward"` (follow the characteristic back from each storage point
+and sample the old field at the departure point) or `"forward"` (launch the old
+field from where it is known, carry it one step, and fit the arrivals in each
+cell); `launch` is `"nodes"` or `"integration_points"`. Called with neither, it
+builds `BackwardNodesSemiLagrangian`, the historical default.
 
 **Eulerian SUPG** (`uw.systems.ddt.EulerianSUPG`, the default) is the general
 choice. Its error falls as $\Delta t^2$, it puts no lower limit on the Courant
@@ -95,7 +102,9 @@ enclosed volume to 4e-5 against that scheme's 5e-3. Use it unless something
 below applies.
 
 **Semi-Lagrangian on the integration points**
-(`uw.systems.ddt.IntegrationPointSemiLagrangian`) is the accurate choice at
+(`uw.systems.ddt.BackwardIntegrationPointsSemiLagrangian`, or
+`SemiLagrangian(trace="backward", launch="integration_points")`) is the
+accurate choice at
 larger Courant numbers. Its error is flat between Courant 0.5 and 2, so a model
 that takes long steps keeps its accuracy where the Eulerian scheme loses it, and
 it loses 45 times less of the second moment than the nodal scheme does. It
@@ -118,11 +127,20 @@ aimed at models that already carry a swarm for material tracking, where the
 transport rides on particles the model is advecting anyway. We would not expect
 to introduce particles in order to use it.
 
-**Semi-Lagrangian at the nodes** (`uw.systems.ddt.SemiLagrangian`) remains the
-historical default of `AdvDiffusionSLCN`. It re-interpolates once per step, which
-costs it accuracy at small Courant numbers, and on a deforming flow with a sharp
-interface it diverges below a Courant number that depends on the problem. Prefer
-one of the three above.
+**Semi-Lagrangian at the nodes**
+(`uw.systems.ddt.BackwardNodesSemiLagrangian`) remains the historical default of
+`AdvDiffusionSLCN`. It re-interpolates once per step, which costs it accuracy at
+small Courant numbers, and on a deforming flow with a sharp interface it
+diverges below a Courant number that depends on the problem. Prefer one of the
+three above.
+
+**Forward traces** (`ForwardIntegrationPointsSemiLagrangian`,
+`ForwardNodesSemiLagrangian`) carry the field from where it is known rather
+than sampling where it is wanted, which is what a stress history needs when the
+departure point falls outside the domain. They are newer than the measurements
+above and are documented with the stress transport, in
+`docs/developer/subsystems/stress-transport.md`. The per-cell fit a forward
+trace performs is unstable where the flow empties a cell (#811).
 
 ## Choosing the time scheme
 

docs/api/solvers.md

@@ -124,8 +124,10 @@ default `EulerianSUPG` manager it is the implicit Eulerian SUPG scheme.
 
 ### SNES_NavierStokes_Composed (`uw.systems.NavierStokes`)
 
-Navier-Stokes composed from a DDt transport manager (Eulerian SUPG momentum
-transport by default); the semi-Lagrangian class above is `uw.systems.NavierStokesSLCN`.
+Navier-Stokes composed from a DDt transport manager: `velocity_transport="eulerian"`
+(SUPG on the mesh, the default) or one of the semi-Lagrangian schemes, and for a
+viscoelastic model `stress_transport` chooses the stress history the same way. The
+former `uw.systems.NavierStokesSLCN` is deprecated and still returns the class above.
 
 ```{eval-rst}
 .. autoclass:: underworld3.systems.navier_stokes_eulerian.SNES_NavierStokes_Composed

docs/api/systems_ddt.md

@@ -37,7 +37,37 @@ bypasses the order ramp, so the first solve runs at full BDF order.
 ### SemiLagrangian
 
 ```{eval-rst}
-.. autoclass:: underworld3.systems.ddt.SemiLagrangian
+.. autofunction:: underworld3.systems.ddt.SemiLagrangian
+```
+
+### BackwardNodesSemiLagrangian
+
+```{eval-rst}
+.. autoclass:: underworld3.systems.ddt.BackwardNodesSemiLagrangian
+   :members:
+   :show-inheritance:
+```
+
+### BackwardIntegrationPointsSemiLagrangian
+
+```{eval-rst}
+.. autoclass:: underworld3.systems.ddt.BackwardIntegrationPointsSemiLagrangian
+   :members:
+   :show-inheritance:
+```
+
+### ForwardIntegrationPointsSemiLagrangian
+
+```{eval-rst}
+.. autoclass:: underworld3.systems.ddt.ForwardIntegrationPointsSemiLagrangian
+   :members:
+   :show-inheritance:
+```
+
+### ForwardNodesSemiLagrangian
+
+```{eval-rst}
+.. autoclass:: underworld3.systems.ddt.ForwardNodesSemiLagrangian
    :members:
    :show-inheritance:
 ```
@@ -63,6 +93,6 @@ bypasses the order ramp, so the first solve runs at full BDF order.
 The following aliases are available via ``underworld3.systems``:
 
 - ``Lagrangian_DDt`` → {class}`~underworld3.systems.ddt.Lagrangian`
-- ``SemiLagragian_DDt`` → {class}`~underworld3.systems.ddt.SemiLagrangian`
+- ``SemiLagragian_DDt`` → {class}`~underworld3.systems.ddt.BackwardNodesSemiLagrangian`
 - ``Lagrangian_Swarm_DDt`` → {class}`~underworld3.systems.ddt.Lagrangian_Swarm`
 - ``Eulerian_DDt`` → {class}`~underworld3.systems.ddt.Eulerian`

docs/api/utilities.md

@@ -117,3 +117,10 @@ Array wrapper that triggers callbacks on modification.
    :members:
    :show-inheritance:
 ```
+
+## Particle projection
+
+```{eval-rst}
+.. automodule:: underworld3.utilities.particle_projection
+   :members:
+```

docs/developer/design/REMESH_FIELD_TRANSFER_DESIGN.md

@@ -204,7 +204,7 @@ REMAP.
 
 ## 7. The band-aid (already landed) and its relationship to the true fix
 
-`ddt.py` `SemiLagrangian._record_psi_star_from_field_data()` + a guarded call:
+`ddt.py` `BackwardNodesSemiLagrangian._copy_tracked_field()` (formerly the parallel-only `_record_psi_star_from_field_data`; since 2026-09-27 used in serial too) + a guarded call:
 under MPI, when `psi_fn` is a single mesh-variable component on this mesh, the
 per-step "record current field into `psi_star[0]`" copies the field's nodal
 data **directly** instead of evaluating it at its own (on-vertex) coords.
@@ -255,6 +255,6 @@ Relationship to the true fix:
 |---|---|---|
 | `discretisation/discretisation_mesh.py` | `_deform_mesh` @2001, `nuke_coords_and_rebuild` @1757 (per-var refill @1890), `vars` registry @3082 | coords/cache rebuild; scoped-refill change (§5) |
 | `meshing/smoothing.py` | movers @1570/1861/2639 (per-outer `_deform_mesh`); `smooth_mesh_interior` @2683; `OT_adapt`, `follow_metric` | adapt op owns transfer; mover sweep refill scope |
-| `systems/ddt.py` | `SemiLagrangian` (history @119, shift @2035, re-record @2085, band-aid `_record_psi_star_from_field_data`); flavors @98/108/119/146 | history policy = REMAP/ALE; `on_remesh` hook |
+| `systems/ddt.py` | `SemiLagrangian` (history @119, shift @2035, re-record @2085, nodal copy `_copy_tracked_field`, formerly `_record_psi_star_from_field_data`); flavors @98/108/119/146 | history policy = REMAP/ALE; `on_remesh` hook |
 | `systems/solvers.py` | `AdvDiffusionSLCN`, NS, VE (`DuDt`/`DFDt` @997/1354) | use DDt; nothing solver-specific for ALE |
 | `swarm.py` | `_proxy_stale` @309, `_update` @1019/2129 | proxy REINIT + adapt-triggered staleness (§8) |

docs/developer/design/lagged-clone-sl-history.md

@@ -208,7 +208,7 @@ despite old-frame being active, because the standard `store_result` path
 **re-records** `psi_star[0]` by evaluating `psi_fn` on the *deformed* mesh at
 centroid-shifted nodes — injecting boundary-layer interpolation error that grows
 with `h_max` and then rides the old-geometry sample. Recording the history by a
-**direct nodal carry** (reusing the parallel `_record_psi_star_from_field_data`
+**direct nodal carry** (reusing the nodal copy `_copy_tracked_field`, formerly `_record_psi_star_from_field_data`
 path) restores the prototype's exact behaviour. This is the "store primitives,
 not re-derived values" principle of invariant 3, in miniature.
 

docs/developer/guides/transport-schemes.md

@@ -1,7 +1,9 @@
 ---
 name: transport-schemes
 description: Which transport scheme and which time history to use in Underworld3, and why — nodal, integration-point or grid histories; semi-Lagrangian, Eulerian SUPG or Lagrangian swarm transport; the Courant number to run at; what each choice does to a settled state and to a peak. The evidence is the tests and notes named beside each ruling.
-families: [AdvDiffusion, NavierStokes, Eulerian, EulerianSUPG, SemiLagrangian, Lagrangian, Lagrangian_Swarm, IntegrationPointSemiLagrangian]
+families: [AdvDiffusion, NavierStokes, Eulerian, EulerianSUPG, Lagrangian, Lagrangian_Swarm,
+  BackwardNodesSemiLagrangian, BackwardIntegrationPointsSemiLagrangian,
+  ForwardIntegrationPointsSemiLagrangian, ForwardNodesSemiLagrangian]
 kind: guide
 status: draft, rulings to be confirmed
 ---

docs/developer/subsystems/integration-point-variables.md

@@ -145,7 +145,7 @@ reading it, `evaluate`, the guards).
 
 ## Semi-Lagrangian history on the integration points
 
-`uw.systems.ddt.IntegrationPointSemiLagrangian` is the SLCN history built on
+`uw.systems.ddt.BackwardIntegrationPointsSemiLagrangian` is the SLCN history built on
 this variable. Its slots `psi_star[k]` are integration-point variables, so
 the value the weak form sees at each integration point is the solution from
 `k+1` steps ago evaluated exactly at the departure point of that
@@ -158,7 +158,7 @@ evaluating the snapshot from time `n-k` at the foot. Every slot carries one
 evaluation error rather than one per generation.
 
 ```python
-DuDt = uw.systems.ddt.IntegrationPointSemiLagrangian(mesh, T, V_fn, degree=2, order=1)
+DuDt = uw.systems.ddt.BackwardIntegrationPointsSemiLagrangian(mesh, T, V_fn, degree=2, order=1)
 adv = uw.systems.AdvDiffusionSLCN(mesh, u_Field=T, V_fn=V_fn, DuDt=DuDt, order=1)
 ```
 
@@ -182,11 +182,11 @@ component per integration point:
 
 ```python
 # a momentum history for Navier-Stokes
-DuDt = uw.systems.ddt.IntegrationPointSemiLagrangian(
+DuDt = uw.systems.ddt.BackwardIntegrationPointsSemiLagrangian(
     mesh, v, v.sym, vtype=uw.VarType.VECTOR, degree=2, order=2)
 
 # a viscoelastic stress history
-DFDt = uw.systems.ddt.IntegrationPointSemiLagrangian(
+DFDt = uw.systems.ddt.BackwardIntegrationPointsSemiLagrangian(
     mesh, stress, v.sym, vtype=uw.VarType.SYM_TENSOR, degree=2, order=1)
 
 DFDt.psi_star[0].sym          # a 2x2 symbolic matrix