Docs: the integration-point history's low Courant number limit, and the choice between transport managers

[lmoresi]

The oversampling section of integration-point-variables.md explains the growth mechanism but never says what it means for use. This adds the limit, the measurements that bound it, and a section naming the transport managers and what each is for.

The limit

Two measurements bound it, both against exact solutions.

Rotating Gaussian, Courant 0.1, pure advection, one revolution (503 steps): energy finishes 0.92 % above the analytic value with a -3.7 % undershoot. Adding physical diffusion removes it, and the ringing goes faster than the energy: -0.04 % undershoot at cell diffusion number D = 1e-3, and energy ratio 0.9934 at D = 1e-2.

C and Pe are not independent within a run. Pe = C/D with D = κΔt/h² carrying no velocity, so a cell at low Courant number sits at proportionally low Péclet number. A Courant-limited timestep fixes D = C_max/Pe_max and cannot reach the growth region; a timestep imposed by a coupled free surface or an elastic timescale can.

LeVeque single vortex at T = 8 (h = 1/48, P2, one-cell tanh level set, no diffusion, no reinitialisation), where the filament thins below the cell: at Courant 2 the returned field has L2 1.54e-1, peak 1.080, undershoot -0.068. Eulerian SUPG at Crank-Nicolson reaches 1.50e-1 and holds the enclosed volume to 4e-5 against this scheme's 5e-3. Both approach ~1.45e-1, which is what the mesh resolves at that spacing, so on a sharp interface the two are equivalent in accuracy and SUPG is cheaper.

The suggested damping does not work

κ = ε h²/(π² Δt) was suggested for the growth. Measured on LeVeque T = 8 at Courant 2:

ε	D	cell Pe	L2 rel	peak	undershoot	band mass
0 (control)	—	—	1.543e-1	1.0797	-6.77e-2	1.168
1e-3	1.0e-4	19700	1.684e-1	1.0522	-5.35e-2	1.275
1e-2	1.0e-3	1970	3.190e-1	0.8804	-2.85e-3	1.896
1e-1	1.0e-2	197	7.053e-1	0.4275	-1.59e-7	3.002
1	1.0e-1	19.7	9.000e-1	0.1619	0	3.120

L2 rises with ε throughout, so the unstabilised run is the most accurate row. At the suggested ε = 1e-3 the overshoot moves a third of the way while error and interface width each grow 9 %. There is no intermediate setting: the peak goes 1.052 to 0.880 between 1e-3 and 1e-2. The damping is applied to the whole field, so it reaches the sharp interface more strongly than the spurious mode. Recorded as a negative result so it is not re-proposed.

The three managers

docs/advanced/eulerian-advection-diffusion.md gains a section naming what to use:

• Eulerian SUPG, the general choice: error falls as Δt², no lower Courant limit, conserves the integral to solver tolerance.
• Integration-point semi-Lagrangian, for larger Courant numbers (error flat between 0.5 and 2) and the natural candidate for tensor transport. Carries the low Courant limit above.
• Lagrangian on a swarm, flagged in development — accuracy and cost still being measured in the particle-in-cell work, so the entry states the intended role rather than a recommendation.
• Nodal semi-Lagrangian, described as superseded: it diverges on a deforming flow below a Courant number that depends on the problem (below C = 0.5 at T = 2, at C = 1 at T = 8), reproduced with the solver building its own history.

Notes

Docs only, no code. Class names checked against systems/ddt.py. Costs measured on #707, which changes them substantially: at h = 1/48 nodal 149 → 78 s and integration point 273 → 156 s, SUPG unchanged.

Scripts, per-step logs and raw JSON: ~/+Simulations/slcn-ip-real-cases/.

Underworld development team with AI support from Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01E87Q7KrpapxeQiLD1RiNXv

[Copilot]

🟡 Changes recommended

A couple of new headings/introductions are internally inconsistent (notably “three managers” while describing four, and an “added diffusion” heading that reads as contradicting the preceding paragraph) and should be clarified before merging.

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

Pull request overview

Adds practical guidance on the integration-point semi-Lagrangian history’s low-Courant-number limitation and documents how to choose between the available transport managers for advection–diffusion problems.

Changes:

• Documented the observed low-Courant growth regime (and when it matters) for the integration-point history, including bounding measurements against reference solutions.
• Recorded (as a negative result) that a proposed stabilising diffusivity worsens accuracy across tested strengths for the LeVeque case.
• Added a comparison section naming transport managers and summarising when to use each.

File summaries

File	Description
docs/developer/subsystems/integration-point-variables.md	Adds “low Courant limit in practice” guidance plus measured outcome of proposed stabilising diffusion.
docs/advanced/eulerian-advection-diffusion.md	Adds a manager-selection section describing the intended roles of Eulerian SUPG vs semi-Lagrangian and swarm-based transport.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.