SPHinXsys runs particle and mesh simulations through one computational framework

One numerical method, two discretizations

SPHinXsys, pronounced s'fink-sis, is an acronym from Smoothed Particle Hydrodynamics for industrial complex systems. The description in the repository is more specific: it provides C++ APIs for engineering simulation and optimization, aimed at complex systems driven by fluid, structure, multi-body dynamics and beyond.

The central technical claim is that the multi-physics library is based on a unique and unified computational framework by which strong coupling has been achieved for all involved physics, and that the library uses SPH, smoothed particle hydrodynamics, as the underlying numerical method for both particle-based and mesh-based discretization.

That single-method claim is what makes the coupling work. If fluid is discretised one way and structure another, the interface between them is a special case, and every new physics pair means a new interface. Using one method for both means the coupling is a property of the framework rather than of a particular pair of solvers.

The consequence the README draws out is that due to the unified computational framework, SPHinXsys is able to carry out simulation and optimization at the same time. That is the difference between a simulation library and a design tool, and it is the most unusual thing in the project.

Finite volume compatibility means you can check the method against itself

There is a section titled Fully compatible to classical FVM method, and the mechanism it describes is a good way to understand what the framework actually does.

Through the unified computational framework in SPHinXsys, the algorithms for particle methods are fully compatible to those in the classical finite volume method. The README then gives a concrete case, the flow around a cylinder problem solved by FVM inside SPHinXsys, and points at the test file for it.

The stated difference between the two modes is narrow and revealing. The code for the FVM algorithm is exactly the same as the code for particle interaction in SPHinXsys. The only difference is that SPHinXsys reads a predefined mesh, other than generating particles, before the computation.

So the same solver code runs on a mesh or on particles, and the choice is a matter of where the discretisation comes from. For a simulation library, that is a strong claim, and it also gives a practical validation route: you can solve a classical benchmark with the finite volume formulation and compare against a published result, which is a much easier check than validating a particle method against a benchmark of unknown provenance.

Target-driven optimization solves the physics and the design at once

The optimization story is the part of SPHinXsys with no direct equivalent in most simulation libraries, and the README explains it in concrete terms.

The unique target-driven optimization is able to achieve the optimization target and the physical solution all-in-once, which is able to accelerate the optimization process greatly. The example given is optimizing the conductivity distribution for a thermal domain problem targeting minimum average temperature, with the test file for that case linked.

The way to read the example is that the physical solution of the thermal domain and the optimal distribution of conductivity are obtained at the same time when the optimization finishes. The two images in the README's example show the optimal distribution on one side and the resulting physical field on the other, arriving together rather than in sequence.

The performance claim is specific and modest. The README says the entire optimization process is very fast and only several times slower than that for a single physical solution with given conductivity distribution. That is the meaningful comparison, an optimization loop costing a small multiple of one solve rather than a sweep of independent solves.

The practical question for an engineer is what the target space looks like. Here it is a field of conductivity values over a domain, with an objective on the temperature. The same idea applied to geometry or to a distribution of thermal conductivity values is a different implementation, and the README's example is the one case it demonstrates.

The Python interface exists, and v1.3 is where it ends

While SPHinXsys is written in C++, it provides a Python interface for users to write Python scripts to control the simulation, including carrying out regression tests for continuous integration and other tasks. The README gives the dambreak case as the example and links to the source of a 2D dambreak case with a Python interface.

The important detail is in the release tags rather than the README text. The v1.3 tag is titled last version with modules and python interface, published on 2026-07-13. The v1.4 tag, published on 2026-10-12, is titled New isolated Simbody interface. And the v1.2.2-sycl tag from 2026-01-21 is titled Multi-resolution heterogeneous simulation.

So the Python interface and the module system are present in v1.3 and then go away in v1.4, where the new thing is an isolated Simbody interface. The Simbody library is the open source multibody dynamics package, and the third party libraries listed in the container image confirm the direction: libsimbody-dev and libsimbody3.6 are both installed.

That is a significant change for anyone starting fresh, and it is the kind of change that only shows up in the tag names. A team that picked SPHinXsys for its Python control scripts has to decide whether to stay on v1.3 or move to v1.4 and lose that workflow.

A C++ library built on a wide native dependency set

The Dockerfile shows what it takes to build the project, and the dependency list is long enough to be worth reading before you commit to it.

The base is ubuntu:22.04, and the build installs build-essential, git, cmake, libgtest-dev, libtbb-dev, libboost-all-dev, libsimbody-dev, libsimbody3.6, libeigen3-dev, libspdlog-dev and pybind11-dev. Three environment variables point the build at those libraries, TBB_HOME, BOOST_HOME and SIMBODY_HOME, with the last one set to /usr.

The build itself is in two stages. GoogleTest is built from source rather than taken from the package, and the Dockerfile explains the parallelism choice: the default is nproc divided by two, to balance build speed against out of memory risk from parallel compilation. The same jobs calculation is applied to the main build.

The project sources are copied in, the git submodules are initialised, and the configure step passes two options, BUILD_WITH_DEPENDENCIES_SOURCE and STATIC_BUILD, which map to the build_with_dependencies_source and SPH_ONLY_STATIC_BUILD build arguments. The timezone is set to Europe/Berlin in the image.

The repository layout backs this up. There is a src/ directory for the library, tests/ with the 2D and 3D example cases the README links to, build_test/ for the build test configuration, cmake/ for the CMake modules, tools/, tutorials/, docs/ and a Doxyfile for documentation generation, plus shell_model.md at the root. There is also a dev.Dockerfile and a dev.sycl.Dockerfile alongside the main one, so the SYCL and standard development environments are separate images, and CMakePresets.json for configuring builds.

SYCL and heterogeneous computing are the performance story

The badges in the README carry the Heterogeneous Computing and Unified SYCL Kernel labels, and the repository topics list gpu, sycl, high-performance-computing and finite-volume-method, so the GPU path is a first class part of the project rather than an afterthought.

The v1.2.2-sycl release title, Multi-resolution heterogeneous simulation, is the clearest hint at what that means. A multi-resolution scheme lets different parts of a domain carry different discretisation levels, which is a standard way to keep a large simulation affordable, and doing it with a unified kernel is what makes it work across CPU and device.

The dev.sycl.Dockerfile is a separate development image for that path, and the dependency list in the plain Dockerfile still includes the native pieces the SYCL build would need, including Eigen, TBB and Boost, alongside the Simbody packages.

For an engineer evaluating this, the question is whether the heterogeneous path is required by the problem or is an aspiration. A solid body collision or a dam break in 2D does not need a device kernel, and the 2D and 3D test cases in the repository are the reference for what the code looks like without it. The GPU path matters when the mesh or particle count reaches a scale where the CPU solve stops being interactive, and that is also where the build complexity starts to cost you.

The examples are the documentation, and they are runnable test cases

The README presents its examples as short programs with linked videos, and the links point into the tests/ directory rather than a separate examples folder, which is the detail worth noticing.

The dam break case is at tests/2d_examples/test_2d_dambreak/Dambreak.cpp, the fluid structure interaction case at tests/2d_examples/test_2d_fsi2/fsi2.cpp, a shell collision at tests/3d_examples/test_3d_elasticSolid_shell_collision/3d_elasticSolid_shell_collision.cpp, and a half sphere shell stability case at tests/3d_examples/test_3d_shell_stability_half_sphere/. There is also a twisting column, a flow around a fish, a column collapse, and a T-pipe with a shell for the fluid shell interaction case, in the extra_source_and_tests directory.

So the worked examples and the regression tests are the same artifacts. That has two consequences. A case you can watch is a case the project runs in CI, which means the examples cannot silently rot, and it means the test suite doubles as the documentation of the API. The README also mentions the C++ APIs, so the surface is not just a set of scripts.

There is a sibling project, SPHinXsim, described as a multi-physics simulator based on SPHinXsys with interactive visualization and particle generation, providing independent C++, Python and large language model user interfaces. That is the application layer above the library, and it is where the visualisation lives.

On maintenance, the last push was on 2026-10-20 and the repository is not archived, and the licence is Apache-2.0, recorded in the README badge and in the LICENSE file, which is a permissive grant with no copyleft obligation on derived code, a licensing note rather than legal advice.

Editorial conclusion

Adopt SPHinXsys if you are doing multi-physics engineering work where fluid, structure and contact interact and you want one code path rather than a solver per physics, and if you can work in C++ and build with CMake. Do not adopt it if you need the Python interface, because v1.3 is named as the last version with modules and the Python interface, so a new project should target v1.4 and plan around that. Verify first that the Simbody interface in v1.4 covers the multi-body dynamics you need, since that release introduced it as an isolated interface, and that your platform toolchain covers the heterogeneous computing path with SYCL if you intend to move kernels to the GPU.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. Xiangyu-Hu/SPHinXsys on GitHub