SPHinXsys

Project status

Project communication

Repository Description

SPHinXsys (pronunciation: s'fink-sis) is an acronym from Smoothed Particle Hydrodynamics for industrial compleX systems. The multi-physics library uses SPH (smoothed particle hydrodynamics) as the underlying numerical method for both particle-based and mesh-based discretization. Due to the unified computational framework, SPHinXsys is able to carry out simulation and optimization at the same time. For more information on the SPHinXsys project, please check the project website: https://www.sphinxsys.org.

You are also welcomed to check SPHinXsim, which is an multi-physics simulator based on SPHinXsys with interactive visualization and particle generation. SPHinXsim provides independent C++, Python and large language model (LLM) user interfaces.

Examples at a glance

Using SPHinXsys library, straightforward and fast multi-physics modeling can be achieved. Here, we present several short examples in flow, solid dynamics, fluid structure interactions (FSI) and dynamic solid contact.

Fully compatible to classical FVM method

Through the unified computational framework in SPHinXsys, the algorithms for particle methods are full compatible to those in the classical finite volume method (FVM). The following gives an example of the flow around cylinder problem solved by FVM in SPHinXsys.

Note that the code for FVM algorithm is exact the same one for particle interaction in SPHinXsys. The only difference is that SPHinXsys reads a predefined mesh, other than generate particles, before the computation.

Target-driven optimization

The unique target-driven optimization is able to achieve the optimization target and physical solution all-in-once, which is able to accelerate optimization process greatly. The following gives an example of optimizing the conductivity distribution for a thermal domain problem targeting minimum average temperature.

Note that the physical solution of the thermal domain (right) and the optimal distribution of conductivity (left) are obtained at the same time when optimization is finished. Also note that the entire optimization process is very fast and only several times slower than that for a single physical solution with given conductivity distribution.

Python interface

While SPHinXsys is written in C++, it provides a python interface for users to write python scripts to control the simulation, including carry out regression tests for continuous integration (CI) and other tasks. One example is given below for the dambreak case. Please check the source code of 2D Dambreak case with python interface for the usage.

Publications

Main publication on the library:

1. C. Zhang, M. Rezavand, Y. Zhu, Y. Yu, D. Wu, W. Zhang, J. Wang, X. Hu, "SPHinXsys: an open-source multi-physics and multi-resolution library based on smoothed particle hydrodynamics", Computer Physics Communications, 267, 108066, 2021.
   
   Google Scholar citations

The numerical methods and computational algorithms in SPHinXsys are based on the following publications.

Software architecture

SPHinXsys is cross-platform can be compiled and used in Windows, Linux and McOS systems.

Installation, tutorial and documentation

For installation, program manual and tutorials, please check https://www.sphinxsys.org/html/sphinx_index.html. Please check the documentation of the code at https://xiangyu-hu.github.io/SPHinXsys/. For a Docker image, check https://hub.docker.com/r/toshev/sphinxsys.

Interaction with SPHinXsys and the team

Thank you for using and supporting our open-source project! We value each feedback.

For SPHinXsys users

Your input is crucial to us. We encourage you to report any issues you encounter with the library, including:

• Bug reports
• Poorly written code or algorithm designs
• Benchmark test issues, whether within the library or from literature, especially those highlighting potential deficiencies
• Other issues

We particularly appreciate feedback stemming from practical simulations or projects, as these insights are essential for improving SPHinXsys.

For SPHinXsys developers

If you don't have a GitHub account yet, please register for one. Fork the SPHinXsys repository to add new features or improve existing ones. Once your changes are ready, commit them and initiate a pull request to have your contributions merged into the main repository.

We’re a small team maintaining this library in the open, and we love seeing the creative ways people extend or adapt it. To make the best use of everyone’s time, we ask for your help in shaping the conversation.

If you have a quick question—a documentation gap, a conceptual doubt, or a short “is this a bug?”—feel free to open a Discussion or Issue. We’ll answer as we can.

If you need in-depth technical guidance on your own fork or customization—for example, code review, design feedback, or help debugging an extension you’re building—we’ll be far more effective if we can see the code in context. In those cases, please open a Draft Pull Request against the main repository. A draft PR gives us a concrete, shared workspace where we can comment line-by-line and iterate on ideas together. It’s completely fine if the code is rough, untested, or just an experiment—draft PRs exist precisely for that.

This approach isn’t about forcing contributions (though we’re delighted when that happens). It’s about making sure that any deep technical investment we make feeds back into the project and remains visible to the whole community. If your solution turns out to be a great fit for upstream, merging it becomes seamless. If it remains a one-off exploration, the record of the discussion still helps others who might follow a similar path.

We’re genuinely excited to collaborate. Turning a help request into a draft PR is the fastest way to get our focused attention—and often the start of a longer-term contribution journey.

You are also welcomed to join us as a formal collaborator, enabling you to branch directly within the main repository and review pull requests.

If you have any further question, please contact xiangyu.hu@tum.de.