diffSPH 0.2.2

A Fully differentiable SPH Solver.

diffSPH is an open-source Smoothed Particle Hydrodynamics simulation framework built for adjoint problem solving and machine learning applications. diffSPH is written mostly in Python using PyTorch but also supports C++/CUDA extensions. The fundamentally differentiable nature of diffSPH make it a versatile basis for many different applications of SPH. Stay tunes for more details on the applications and design of diffSPH! This is the solver at https://diffsph.fluids.dev/. You can also find the preprint of our paper on diffSPH here.

Installation

The only major requirement for this solver is our companion software that handles the neighbor searching and related topics, which you can find more about here. Other than that the solver is straightforward to setup and can also be used in Google colab

conda create -n diffSPHEnv python=3.12
conda activate diffSPHEnv
conda install nvidia/label/cuda-12.8.1::cuda-toolkit
pip install toml scipy numba tqdm h5py matplotlib ipywidgets ipympl imageio scikit-image ipykernel imageio_ffmpeg portalocker
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip install torchCompactRadius
pip install diffSPH

Tutorials

If you would like to know more about

• How to install diffSPH you can find a tutorial under demos/installGuide.md
• How to setup a simulation: demos/firstSimulation.md
• How to perform an inverse simulation: demos/inverseSimulation.md
• How to generate a dataset: demos/datasetGeneration.md
• How to train an offline network: demos/exampleTraining.md

Each tutorial comes (if applicable) with a Jupyter Notebook you can run. For the first simulation example you can also find it on Colab right here.

Examples

Compressible Flows

Rayleigh-Taylor Instability	Kevin-Helmholtz Instability	Sod-Shock Tube	Sedov Blastwave

More examples can be found under examples/compressible

Weakly Compressibe Flows

Taylor Green Vortex	Rotating Square Patch	Lid-Driven Cavity
Driven Square	Flow Past Cylinder	Dam Break

More examples can be found under examples/weaklyCompressible

Incompressible Flows:

Taylor Green Vortex

Other Examples

diffSPH can also be used to simulate a variety of other PDEs such as the wave equation

Wave Equation 2D

Inverse Problems

diffSPH is meant as a framework for differentiable problem solving and supports all the common tasks in adjoint optimization and machine learning, including:

Loss-based Physics	Parameter Optimization	Shape Optimization	Solver In The Loop

Features

diffSPH comes with a large variety of SPH schemes already builtin and can be easily extended to include more solver schemes and SPH properties:

• $\delta$-SPH and $\delta^+$-SPH for weakly compressible simulations
• IISPH and DFSPH for incompressible simulations
• CompSPH, CRKSPH, PESPH and the classic Monaghan scheme for compressible simulations
• mDBC boundary conditions for rigid bodies
• Inlets and Oulets with buffer zones
• Periodic BCs using minimum image conventions
• Neumann and Dirichlet BCs
• grad-H, kernel renormalization and CRK correction schemes
• $\delta^+$ and implicit particle shifting
• Monaghan and Owen schemes for adaptive particle support radii
• Balsara, Morris, Rosswog, Cullen Dehnen artificial viscosity switches
• Sub particle scale turbulence modelling
• Differentiable generation of initial conditions using SDFs
• Hierarchical and compact hashing based neighbor searching
• Verlet lists for neighborhood searches
• Most Common SPH Kernel Functions (Wendland, B-Spline, Poly6) used across the fields

pip install toml scipy numba tqdm h5py matplotlib ipywidgets ipympl imageio scikit-image

Time Integration

diffSPH comes builtin with a large number of temporal integration schemes which we validated against a dampened harmonic oscillator with a hidden state variable:

$$ \begin{aligned} \hat{k} &= k + \alpha e\ \frac{dx}{dt} &= u&\ m \frac{du}{dt} &= -\hat{k} x &- c u\ \frac{de}{dt} &= \beta \text{sgn}(u) u^2 &- \gamma e \end{aligned} $$

Physical Problem	Integrator Accuracy

Datasets

There have been a variety of datasets already generated with diffSPH, including:

SFBC Test Case II	Periodic BCs
No-Slip	Free-Slip

Publications

So far diffSPH has been used in the following publications:

• Symmetric Fourier Basis Convolutions for Learning Lagrangian Fluid Simulations, R. Winchenbach, N. Thuerey, International Conference on Learning Representations 2024 https://arxiv.org/abs/2403.16680

Workshop Papers:

• MoriNet: A Machine Learning-based Mori-Zwanzig Perspective on Weakly Compressible SPH, R. Winchenbach and N. Thuerey, 2025 International SPHERIC Workshop Barcelona, Spain (pdf available under publications)
• Physically-Motivated Machine Learning Models for Lagrangian Fluid Mechanics, R. Winchenbach and N.Thuerey, 2024 International SPHERIC Workshop Berlin, Germany (presentation and more information available here https://fluids.dev/spheric2024/)
• Cross-Validation of SPH-based Machine Learning Models using the Taylor-Green Vortex Case - R. Winchenbach and N. Thuerey - Particle Methods and Applications Conference 2024 Santa Fe, USA (presentation and more information available here: https://pmac.fluids.dev)
• A Hybrid Framework for Fluid Flow Simulations: Combining SPH with Machine Learning - R. Winchenbach and N. Thuerey - 2023 International SPHERIC Workshop Rhodes, Greece (pdf available under publications)

Acknoledgement

This work has been in parts funded by the DFG Individual Research Grant TH 2034/1-2.