DOCSEARCHbyAlgolia
Submit Docs

SPlisHSPlasH Documentation

repository·master·Indexed 21 days ago

https://github.com/interactivecomputergraphics/splishsplash

An open-source SPH-based fluid simulation library supporting 2D/3D simulations, various pressure solvers (WCSPH, PCISPH, PBF, IISPH, DFSPH, and PF), and coupling with rigid or deformable bodies. The library supports viscosity, surface tension, vorticity, and multi-phase fluids. It includes a command line simulator, a Python wrapper (pySPlisHSPlasH), and a Maya plugin for scene generation.

Tokens
30.3K
Snippets
65
Records
149
Agent score
82%

What's inside SPlisHSPlasH

  1. Overview of SPlisHSPlasH fluid simulation features

    master

    SPlisHSPlasH is an open-source library for physically-based fluid simulation using the Smoothed Particle Hydrodynamics (SPH) method. It supports both 2D and 3D simulations and provides several key capabilities:

    Simulation Methods

    • Pressure Solvers (Incompressibility): Implements state-of-the-art solvers including WCSPH, PCISPH, PBF, IISPH, DFSPH, and PF.
    • Fluid Dynamics: Supports explicit and implicit viscosity, various surface tension approaches, and different vorticity methods.
    • Coupling & Solids: Supports multi-phase simulations, deformable solids, rigid-fluid coupling (static and dynamic bodies), and two-way coupling with deformable solids.
    • Forces: Computation of drag forces.

    Technical Capabilities

    • Performance: Neighborhood search available on CPU or GPU; supports AVX vectorization.
    • Extensibility: Python bindings and support for embedded Python scripts.
    • Interoperability:
      • JSON-based scene file importer.
      • Export of particle data via partio and VTK (for ParaView).
      • Rigid body export.
      • Maya plugin for scene generation.
      • ParaView plugin for particle data import.

    Tools & Animation

    • Fluid emitters.
    • Scripted animation fields.
    • Automatic surface sampling.
    • Volume sampling tool for closed geometries.

  2. Overview of SPlisHSPlasH

    master
    SPlisHSPlasH is an open-source library for the physically-based simulation of fluids using the Smoothed Particle Hydrodynamics (SPH) method. It supports both 2D and 3D simulations and implements various state-of-the-art pressure solvers to simulate incompressibility, including WCSPH, PCISPH, PBF, IISPH, DFSPH, and PF. The library is capable of simulating viscosity, surface tension, vorticity, and multi-phase fluids, and supports coupling with rigid and deformable bodies.

  4. What is pybind11 and its core features

    master

    pybind11 is a lightweight, header-only C++ library designed to create seamless Python bindings for existing C++ code. It uses compile-time introspection to minimize boilerplate by inferring type information.

    Core mapping capabilities include:

    • Functions (accepting/returning custom data structures via value, reference, or pointer)
    • Instance and static methods/attributes
    • Overloaded functions
    • Arbitrary exception types
    • Enumerations and Callbacks
    • Iterators, ranges, and custom operators
    • Single and multiple inheritance
    • STL data structures
    • Smart pointers (e.g., std::shared_ptr) with reference counting
    • C++ classes with virtual/pure virtual methods
    • Integrated NumPy support (Note: NumPy 2 requires pybind11 2.12+)

  6. Configure Animation Field shapes and scaling

    master

    The scale vector (vec3) is interpreted differently depending on the shapeType selected:

    • shapeType: 0 (box): The scale vector defines the [width, height, depth] of the box.
    • shapeType: 1 (sphere): The x component of the scale vector defines the radius. The y and z components are ignored.
    • shapeType: 2 (cylinder): The x component defines the height and the y component defines the radius. The z component is ignored.

  7. How BoundaryModel handles rigid-fluid coupling

    master

    The BoundaryModel class is a base class for boundary handling. It stores a reference to a RigidBodyObject, which can be either a stationary or dynamic rigid body.

    RigidBodyObject is an abstract class with two implementations:

    1. StaticRigidBody: Represents stationary objects handled internally.
    2. PBDRigidBody: Represents moving rigid bodies simulated externally via the PositionBasedDynamics library.

    SPlisHSPlasH defines a boundary as a combination of a list of rigid bodies and a specific coupling algorithm. Supported boundary models include:

    • Particle-based rigid-fluid coupling
    • Density maps
    • Volume maps

  8. How the SPlisHSPlasH simulation architecture works

    master

    SPlisHSPlasH uses a modular design inspired by the Model-View-Controller (MVC) pattern. The core of the software is the Simulation class, which acts as a central coordinator for all simulation components.

    Key components managed by the Simulation class include:

    • TimeStep: Defines the simulation loop and the pressure solver.
    • FluidModel: Represents one or more fluid phases.
    • BoundaryModel: Represents static or dynamic boundaries.
    • AnimationFieldSystem: Manages particle animation in predefined areas.

    The Simulation class is implemented as a singleton, meaning only one instance exists during runtime. It is responsible for evaluating SPH kernel methods, updating time step sizes via CFL conditions, invoking EmitterSystem instances, and saving/loading simulation states.

  9. How to implement a new pressure solver

    master

    In SPlisHSPlasH, pressure solvers are not strictly distinguished from the simulation algorithm. Instead, they are implemented as subclasses of the TimeStep class. Each TimeStep class manages a complete simulation step, including the pressure solver, non-pressure forces, and advection.

    Implementation Strategy

    • Follow File Organization: Place your new solver in its own folder within the /SPlisHSPlasH/ directory (e.g., /SPlisHSPlasH/MyPressureSolver/).
    • Reuse Existing Code: It is highly recommended to copy and modify an existing solver (like WCSPH) rather than writing from scratch.
    • Decouple Data: Use SimulationData classes to separate simulation data from the algorithm logic.
    • Operator Splitting: SPlisHSPlasH design assumes the simulation can be split into non-pressure forces, the pressure solver, and advection. While you can implement these together, it is best practice to follow the existing pattern of dividing these tasks within the step() method.
    void TimeStepWCSPH::step()
{
	Simulation *sim = Simulation::getCurrent();
	const unsigned int nModels = sim->numberOfFluidModels();
	TimeManager *tm = TimeManager::getCurrent ();
	const Real h = tm->getTimeStepSize();

    // 1. Perform a neighborhood search
	performNeighborhoodSearch();

    // 2. Compute non-pressure forces and SPH densities
	for (unsigned int fluidModelIndex = 0; fluidModelIndex < nModels; fluidModelIndex++)
	{
		clearAccelerations(fluidModelIndex);
		computeDensities(fluidModelIndex);
	}
	sim->computeNonPressureForces();

    // 3. Compute pressure forces
	computePressureForces();

    // 4. Update time step size with CFL condition
	sim->updateTimeStepSize();

    // 5. Advect particles
	sim->advectParticles();

    // 6. Emit and/or animate particles if necessary
	sim->emitParticles();
	sim->animateParticles();

    // 7. Advect time
	tm->setTime(tm->getTime() + h);
}

  10. How the TimeStep class defines simulation algorithms

    master

    The TimeStep class is an abstract base class used to implement different simulation methods. Any new simulation algorithm must derive from this class and implement the required interface, most importantly the step() function, which contains the core simulation algorithm called in the main loop.

    Currently implemented TimeStep algorithms include:

    • WCSPH
    • PCISPH
    • PBF
    • IISPH
    • DFSPH
    • Projective Fluids

  11. Configure bounding box behavior for foam particles

    master

    Because foam particles are advected using the fluid velocity field without explicit boundary handling, they can drift outside the simulation domain. You can define an axis-aligned bounding box to manage this using --bbsize and --bbtype.

    Parameters:

    • --bbsize <minX> <minY> <minZ> <maxX> <maxY> <maxZ>: Defines the spatial limits.
    • --bbtype <type>: Defines the handling strategy. Supported types are:
      • kill: Removes particles that leave the box.
      • lifesteal: Reduces the lifetime of particles that leave the box.
      • clamp: Clamps particles to the box boundaries.

  12. Advanced pybind11 features and goodies

    master

    Beyond basic bindings, pybind11 offers several advanced features for performance and ease of use:

    • Lambda Support: Bind C++11 lambda functions with captured variables; the capture data is stored in the resulting Python function object.
    • Efficient Data Transfer: Uses C++11 move constructors and move assignment operators to transfer custom types efficiently.
    • Buffer Protocol Support: Easily expose internal storage of custom types to Python's buffer protocol, enabling fast, zero-copy conversions between C++ matrix classes (like Eigen) and NumPy.
    • Automatic Vectorization: Transparently apply functions to all entries of one or more NumPy array arguments.
    • Slice Support: Support Python's slice-based access and assignment with minimal code.
    • Pickling: C++ types can be pickled and unpickled like regular Python objects with minimal effort.
    • Header-only: No need to link against additional libraries; everything is contained in a few headers.