Implement stage-level coupling for split integration

[efaulhaber]

This PR

• implements stage-level coupling as opposed to the previously used step-level coupling.
• fixes a memory "leak". The sub-integrator was storing the split solution for every single sub-integration call (each fluid time step), which caused massive VRAM allocations for long-running GPU simulations.

In step-level coupling, the fluid is advanced a full step before the structure is advanced a full step. This reduces the stability of the main time integration, reducing the maximum stable time step by a factor of 2 (in my tests with Carpenter-Kennedy).
Stage-level coupling calls the sub-integration in every fluid RK stage. The advantage is that the stability properties of the time integrator are preserved. In the current version, this does not have a significant performance impact and is therefore the default (edit: it does not work for some RK schemes with non-monotonic stage times and is therefore not the default). Only for small ratios (like 2-5x smaller time step for the structure), the step-level coupling might be more efficient. For details on how this is implemented, check out my comment below. The implemented version is the one without "restart", and "predict" is enabled by default but can be disabled via kwarg.

Δt	Step-level coupling	Stage-level coupling
9e-4
1e-3
1.8e-3

For 1.9e-3, I get "instability detected" with stage-level coupling. The maximum stable time step of 1.8e-3 with stage-level coupling is the same as when making the ball a moving solid wall boundary (non-elastic).
Note that we cannot do this with a CFL because the StepsizeCallback has an upper limit of 1.2e-3 due to #1048.

Note that something is still not right, as the larger time step makes the ball fall deeper with stage-level coupling. (Edit: This is fixed with "predict" below.)

[efaulhaber]

I now implemented a slightly different benchmark simulation. A TLSPH square with E=1e8 and rho=1200 is fully submerged in a fluid with rho=1000. It starts with zero velocity and is then slowly sinking. I measure the stability in the form of the largest stable time step and the accuracy in the form of deviation from a simulation with a very small time step.

The version I showed above was stage-coupling with "restart" (the first row in the table below), which means I reset the sub-integrator in every stage to the state of the previous time step. Without "restart", the sub-integrator is integrated to the first stage time with the fluid state prediction of the first stage, and then continues from there in the second stage, etc.
"Predict" means I apply an explicit Euler step with the structure velocity to predict the structure position at the stage time as u += v * (t_new - t_previous). Then I use this prediction to compute $F_\text{fluid}$.
"Deviation" is the (normalized) difference in the y-coordinates of the square at t=1.5 between the split integration and the non-split integration (fluid and structure integrated together at Δt=1.44e-4), which I consider the reference for this simulation (time integration error almost zero). A negative deviation means the square sank too fast, a positive deviation means it didn't sink fast enough.

Stage-coupling	Restart	Predict	max Δt	Deviation @ Δt=8e-4	Deviation @ Δt=1.6e-3	#Sub-steps @ Δt=8e-4	#Sub-steps @ Δt=1.6e-3
✅	✅	❌	1.6e-3	-8.47e-2	-1.91e-1	38k	35.2k
✅	✅	✅	1.6e-3	-2.50e-4	1.47e-3	38k	35.2k
✅	❌	❌	1.6e-3	-2.01e-2	-3.86e-2	15k	12.3k
✅	❌	✅	1.6e-3	-2.91e-4	-3.95e-4	15k	12.3k
❌	—	❌	8.0e-4	-4.39e-2	—	11.2k	—
❌	—	✅	8.0e-4	3.70e-2	—	11.2k	—

Interpreting these results, we can see that the methods without position prediction all have a significant negative deviation (obviously even more pronounced with the larger time step, for the stage-level coupling that is stable at this time step), indicating an underestimation of $F_\text{fluid}$. This is reasonable because $F_\text{fluid}$ is computed at the previous time step (or stage for the "restart" methods), at which the square is higher up, so the forces from the fluid are underestimated. This effect is smaller for non-restart methods because they compute $F_\text{fluid}$ at the previous stage instead of going further back to the previous step. Prediction significantly increases the accuracy.

The "restart" methods compute the final structure state by integrating from $t_n$ to $t_{n+1}$ with a constant $F_\text{fluid}$ computed at $t_n$. The non-restart methods instead compute $F_\text{fluid}$ based on the predicted fluid state for each stage (which can be considered less accurate since it's a prediction), but re-compute $F_\text{fluid}$ for each state (which, in turn, is more accurate). The resulting method has similar accuracy in this benchmark (higher even for the larger time step) and the same stability, but the number of sub-steps is close to the step-coupling method, whereas the restart methods require 2-3x more stub-steps.
Note that a larger ratio between fluid and structure time step further reduces the overhead of the non-restart methods compared to the step-coupling method.

In summary, the non-restart stage-coupling method with prediction is more stable (allows for a 2x larger fluid time step), more accurate, and not more expensive (does not require significantly more structure sub-steps) than the previous implementation of step-level coupling. For testing purposes, I added kwargs, so all methods can still be tested. I am not sure if the non-restart will work as well with every time integrator as it did with Carpenter-Kennedy.

[Copilot]

Pull request overview

This PR implements stage-level coupling for split integration of TotalLagrangianSPHSystems, and refactors the ODE problem parameter p to carry both the semidiscretization and split-integration runtime payload.

Changes:

• Change semidiscretize/ODE p payload from Semidiscretization to a NamedTuple with p.semi plus p.split_integration_data.
• Extend SplitIntegrationCallback with stage_coupling / predict_positions options and stage-time integration support.
• Update callbacks/IO/visualization code paths to use integrator.p.semi / sol.prob.p.semi.

Reviewed changes

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

Show a summary per file

File	Description
test/callbacks/info.jl	Update mock integrator payload to match p.semi access pattern.
src/visualization/recipes_plots.jl	Adapt plotting recipe and solution type alias to the new p payload shape.
src/io/io.jl	Read semidiscretization/metadata from integrator.p.semi.
src/general/semidiscretization.jl	Construct p=(; semi, split_integration_data=nothing) and adjust kick!/drift! signatures accordingly.
src/callbacks/update.jl	Use integrator.p.semi.
src/callbacks/stepsize.jl	Use integrator.p.semi; broaden callback type check for parametric SplitIntegrationCallback.
src/callbacks/steady_state_reached.jl	Use integrator.p.semi.
src/callbacks/split_integration.jl	Implement stage coupling + new payload storage under p.split_integration_data.
src/callbacks/solution_saving.jl	Use integrator.p.semi.
src/callbacks/post_process.jl	Use integrator.p.semi.
src/callbacks/info.jl	Use integrator.p.semi.
src/callbacks/density_reinit.jl	Use integrator.p.semi.
ext/TrixiParticlesOrdinaryDiffEqExt.jl	Adjust extension code to read p.semi.
docs/src/refs.bib	Remove JabRef metadata comments.

---

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

[codecov]

Codecov Report

❌ Patch coverage is 90.31142% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.99%. Comparing base (a3f1139) to head (a674dc6).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/callbacks/split_integration.jl	92.66%	8 Missing ⚠️
src/general/semidiscretization.jl	89.06%	7 Missing ⚠️
...c/schemes/structure/total_lagrangian_sph/system.jl	0.00%	5 Missing ⚠️
test/general/semidiscretization.jl	69.23%	4 Missing ⚠️
src/general/neighborhood_search.jl	0.00%	2 Missing ⚠️
src/preprocessing/particle_packing/system.jl	87.50%	1 Missing ⚠️
src/visualization/recipes_plots.jl	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1049      +/-   ##
==========================================
- Coverage   89.17%   88.99%   -0.19%     
==========================================
  Files         128      128              
  Lines        9925    10013      +88     
==========================================
+ Hits         8851     8911      +60     
- Misses       1074     1102      +28     

Flag	Coverage Δ
total	88.99% <90.31%> (-0.19%)	⬇️
unit	67.37% <36.01%> (-0.24%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

---

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

[efaulhaber]

/run-gpu-tests

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.

---

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

[efaulhaber]

/run-gpu-tests

[svchb]

Since you are changing the extension can you please address this issue #1047

[efaulhaber]

/run-gpu-tests