SPlisHSPlasH SPH Fluid Simulation for C++ and Python

Why SPlisHSPlasH Uses Particle-Based Fluids

SPlisHSPlasH solves the problem of computing physically based fluid motion as a programmable simulation rather than as a fixed end-user application. Its intended users include graphics researchers, developers of animation and visual effects systems, and engineers implementing fluid interaction in C++ or Python. The library supports fluid behavior in both 2D and 3D, including incompressible flow, viscosity, surface tension, vorticity, drag, multiple fluid phases, and deformable solids.

The central method is Smoothed Particle Hydrodynamics, or SPH. The README describes SPH as a meshless Lagrangian approach in which a quantity for one fluid particle is calculated from a finite set of neighboring particles. This is not merely lightweight particle animation. Particles carry physical state and exchange information through local neighborhoods, so the application must establish particle states, solver parameters, forces, and scene conditions.

This design is relevant when the required system includes changing fluid topology, multiple materials, spray and foam processing, or coupling to moving bodies. Those capabilities are listed in the README. However, it does not document engineering tolerances, convergence guarantees, mesh generation, boundary-layer treatments, or industrial CFD certification. The repository presents itself as a simulation library for physically based fluids, not as a validated general CFD package, and that distinction should shape adoption decisions.

Inside the SPlisHSPlasH Solver Architecture

The implementation is organized around fluid particles, neighbor discovery, pressure calculation, and secondary fluid forces. The README identifies `CompactNSearch` as the CPU neighborhood-search library and `cuNSearch` as the GPU alternative. This is the enabling mechanism behind SPH's local particle calculations. A solver can query neighboring particles, apply its pressure or viscosity formulation, update particle states, and continue through simulation steps.

SPlisHSPlasH implements six named pressure solvers: `WCSPH`, `PCISPH`, `PBF`, `IISPH`, `DFSPH`, and `PF`. The README states that these address incompressibility, an important problem in SPH because particle-based representation does not automatically prevent excessive density variation. The selected solver becomes a core project choice rather than a rendering detail. The README lists the methods but does not provide a numerical comparison of their stability, computational cost, convergence, or suitable timestep ranges, so an adopter cannot choose among them from the README alone.

Viscosity is available through explicit and implicit methods. The project also provides surface-tension approaches, vorticity methods, drag-force computation, the `XSPH` velocity filter, fluid emitters, and scripted animation fields. `PositionBasedDynamics` supplies dynamic rigid-body simulation, `Discregrid` handles rigid-body collision detection, and `GenericParameters` handles generic parameters. Two-way coupling with deformable solids is supported. These components indicate that SPlisHSPlasH can be embedded in a larger graphics simulation rather than used only as a standalone fluid demo.

Installing the Python Package on Supported Targets

The documented wheel route is the shortest starting point for Windows and Linux users with a supported Python version. The package is published as `pysplishsplash`, and the README states that prebuilt wheels cover Python 3.6 through 3.10. Install it with the following command:

pip install pysplishsplash

The installation command invokes `pip` with the package name exactly as documented. Users outside the stated Windows and Linux wheel conditions, or outside the listed Python range, must use the native CMake and binding instructions instead.

The native build uses CMake and a compiler that supports C++11. The README lists Windows 10 64-bit with CMake 3.18.3 and Visual Studio 2019, plus Debian 11.5 64-bit with CMake 3.18.4 and GCC 10.2.1, as configurations against which the project tested its code. It also requires a 64-bit target on a 64-bit operating system and does not support 32-bit builds there. The repository's `setup.py` invokes CMake while building the Python extension and checks for a minimum CMake version on Windows, but the truncated source does not expose the complete argument sequence.

For source builds, the README directs users to generate the project and Makefiles with CMake, then compile it with a C++11 compiler. It does not provide a complete command transcript in the README excerpt, so there is no basis for presenting an invented `cmake` or `make` invocation.

Running the SPlisHSPlasH Command-Line Simulator

After installing the Python package or building a supported native configuration, the README identifies `splash` as the command-line simulator. Invoking it without arguments starts that simulator according to the short project description.

splash

The README does not explain the simulator window, required scene assets, rendering controls, or what visual output appears after launch. It therefore does not support a claim that the command opens a particular interface or loads a particular example. For an initial integration check, the more useful documented entry point is help output:

splash --help

This should expose the command-line options accepted by the installed simulator. The README does not show those options, so examples involving flags, scene paths, output files, solver selection, or headless operation would be unsupported.

For application development, the Python binding provides access to the library, but the README links to `doc/py_getting_started.md` without reproducing its API. It would be unsafe to invent an import statement or function call. The concrete documented step is therefore package installation followed by `splash --help`. Deeper scene execution needs the linked Python guide, the project documentation, or the repository's `Simulator/` and `data/` examples.

Scene Files, Particle Export, and Graphics Pipelines

SPlisHSPlasH accepts JSON-based scene files and includes a Maya plugin for modeling and generating scenes. This gives applications a way to describe simulation setup beyond source-level API calls, although the README does not provide a scene-file schema or a complete example. Developers must not assume that arbitrary JSON will load or that every GUI field maps directly to a stable public API.

Particle data can be exported in `partio` and `vtk` formats. `vtk` export supports import into ParaView, while the project also lists a ParaView plugin. For Maya and Blender workflows, the README points to `MayaPartioTools` and the `Blender Sequence Loader` for importing Partio files. These are separate projects, so their capabilities cannot be treated as built-in SPlisHSPlasH features. The core repository exports the files; importing and rendering them depends on the stated companion tooling.

Postprocessing features include automatic surface sampling, spray, foam, and bubble particle generation, and a tool for attaching a visual mesh to particles belonging to an elastic solid. Rigid-body export is also listed. This is useful when a simulation must feed a rendering or animation pipeline, but it also makes particle count and output format a practical adoption concern. The README does not document memory budgets, maximum particle counts, export timing, or automation interfaces for the postprocessing tools. Those details require project-specific validation.

SPlisHSPlasH Limitations and Alternative Simulation Approaches

The clearest limitation is incomplete decision guidance. Six pressure solvers are named, but the README does not explain their parameter requirements, expected failure conditions, performance trade-offs, or recommended scenarios. Likewise, CPU and GPU neighborhood search are both available, but there are no documented criteria for choosing `CompactNSearch` versus `cuNSearch`, and the README names no minimum GPU requirement. This makes it necessary to consult the project documentation and examples before committing to a solver configuration.

SPlisHSPlasH is also the wrong abstraction for a user who only wants to load a scene and adjust a few CFD parameters. It is a C++ library with Python bindings, embedded-script support, and its own command-line simulator. An application is expected to integrate its APIs or documented scene mechanisms. The repository layout contains `SPlisHSPlasH/`, `Simulator/`, `GUI/`, `Tools/`, `Utilities/`, `Tests/`, documentation, and data, which confirms a sizable simulation framework rather than a small standalone command.

A real methodological alternative is a grid-based, Eulerian CFD solver. SPlisHSPlasH is explicitly meshless and Lagrangian: state is represented by discrete particles, and local neighborhoods drive calculations. A grid-based solver instead computes a fluid field over a fixed spatial grid and advances values through control volumes or cells. SPlisHSPlasH therefore changes representation around moving surfaces, free surfaces, and multiple interacting materials, while a grid-based solver changes discretization and resolution around the mesh or computational domain. The README does not claim that either approach is superior for engineering analysis, and it provides no benchmark.

SPlisHSPlasH Releases and Dependency Licensing

The repository is not archived, and its last push was on 2026-10-16. The release history includes `2.18.1` on 2026-09-01, `2.17.0` on 2026-06-08, and `2.16.1` on 2026-05-12. These facts show recent project changes, but the README does not provide upgrade notes, migration procedures, API compatibility promises, or a long-term support policy. The repository's `Changelog.txt` is the first project-specific file to inspect when moving between versions.

The SPlisHSPlasH library code uses the MIT license. The README explicitly says that external dependencies are covered by separate licensing terms and points to the `extern/` folder for each dependency's code and licensing information. The project says all external dependencies are included, and it lists Eigen, json, Partio, zlib, cxxopts, tinyexpr, toojpeg, pybind, GLFW, hapPLY, nativefiledialog-extended, and Dear ImGui. Bundling them simplifies source acquisition, but it does not make their terms identical to the library's MIT license. A distributor must examine the actual dependency files rather than relying on the top-level license alone.

Its own related libraries also add source components to track, including `PositionBasedDynamics`, `Discregrid`, `CompactNSearch`, `cuNSearch`, and `GenericParameters`. Upgrading the main repository may therefore involve matching versions and build assumptions across several components. The README does not define their update cadence or compatibility matrix.

Editorial conclusion

SPlisHSPlasH is appropriate for C++ or Python developers building custom particle-based fluid simulations, visual effects research, multiphase scenes, or fluid-solid coupling systems. It is a poor fit for users seeking a turnkey engineering CFD package because the README centers on a programmable simulation library and its command-line or Python interfaces. Before adoption, verify that the required pressure solver, particle export path, Python version, platform, rendering workflow, and collision setup match the application. On the documented Linux and Windows wheel path, the first decisive check is whether `pip install pysplishsplash` works for the intended Python 3.6 through 3.10 environment.

Frequently asked questions

Official sources

1. InteractiveComputerGraphics/SPlisHSPlasH on GitHub
2. License: MIT
3. Project website
4. README
5. Releases