Salva Fluid Simulation Engine

Salva is a 2D and 3D particle-based fluid simulation engine designed for games and animations. It provides high-fidelity fluid dynamics through various pressure resolution and viscosity models.

Key technical details:

• Math Library: Uses nalgebra for vector and matrix mathematics.
• Physics Coupling: Can optionally interface with rapier to enable two-way coupling between fluids and rigid bodies, multibodies, or deformable bodies.
• Dimensionality: Supports both 2D and 3D simulations using a largely shared codebase.
• Platform Support: Includes WASM support, making it suitable for web-based applications.

Salva implements several advanced fluid simulation techniques:

• Pressure Resolution: Supports DFSPH and IISPH.
• Viscosity Models: Includes DFSPH viscosity, Artificial viscosity, and XSPH viscosity.
• Surface Tension: Implements WCSPH surface tension, as well as methods from He et al. 2014 and Akinci et al. 2013.
• Elasticity: Implements the method from Becker et al. 2009.
• Multiphase Fluids: Allows mixing multiple fluids with different characteristics (e.g., varying densities and viscosities).
• Two-way Coupling: Optional integration with rapier for interaction with physics bodies.
• WASM Support: Optimized for web deployment.

You can run the provided examples for both 2D and 3D simulations using cargo. The examples are located in the examples2d and examples3d directories and are designed to work with WASM and WebGL 1.0.

cargo run --release -p examples2d --bin all_examples2
cargo run --release -p examples3d --bin all_examples3

The FluidsRenderingMode enum determines how fluid particles are visually represented in the testbed. You can set this using FluidsTestbedPlugin::set_fluid_rendering_mode.

Available modes:

• StaticColor: Renders particles using a plain color (either the assigned fluid color or the default).
• VelocityColor { min, max }: Renders particles with a red tint based on their velocity. Particles with velocity $\le$ min have no red tint; particles with velocity $\ge$ max are completely red.
• VelocityArrows { min, max }: Renders particles as arrows indicating the direction and magnitude of velocity, with the same red tinting logic as VelocityColor.

// Example: Velocity-based coloring
plugin.set_fluid_rendering_mode(FluidsRenderingMode::VelocityColor {
    min: 0.0,
    max: 50.0,
});

Salva uses InteractionGroups to perform pairwise filtering between elements (like particles). This allows you to specify which elements should interact and which should ignore each other using bitmasks.

An interaction between two objects a and b is permitted if:

1. The memberships of a share at least one bit with the filter of b.
2. OR the memberships of b share at least one bit with the filter of a.

This logic is implemented via the test method. If neither condition is met, the objects will ignore each other.

// Example logic for interaction:
// (a.memberships & b.filter) != 0 || (b.memberships & a.filter) != 0

A BoundarySet is a collection of Boundary objects managed via a ContiguousArena. It uses BoundaryHandle as the key to access specific boundaries.

// BoundarySet is a type alias for ContiguousArena<BoundaryHandle, Boundary>
// Use it to store and retrieve Boundary objects using their handles.

The FluidsPipeline is the primary entry point for integrating particle-based fluid simulations with the Rapier physics engine. It manages both the LiquidWorld (the fluid simulation) and a ColliderCouplingSet (the interaction between fluids and Rapier rigid bodies).

To use it, you initialize the pipeline with particle properties and then call step during your physics loop. Note that step applies forces to rigid bodies but does not integrate them; you must use Rapier's own physics pipeline to integrate those forces into motion.

// Example initialization and stepping
let mut pipeline = FluidsPipeline::new(particle_radius, smoothing_factor);

// In your simulation loop:
pipeline.step(&gravity, dt, &colliders, &mut bodies);

Salva provides a math module that exposes type aliases for common mathematical structures (vectors, matrices, rotations, isometries) based on the enabled compilation features (dim2 or dim3 and f32 or f64). This allows you to write code that adapts to the simulation's dimensionality and precision.

Key concepts in the math module:

• Real: The scalar type (either f32 or f64).
• Vector<Real>: The standard spatial vector type.
• Isometry<Real>: The transformation type (combining rotation and translation).
• SpatialVector<Real>: A vector representing both rotation and translation (dimension is SPATIAL_DIM).
• gcross_matrix(v): Returns the cross-product matrix for a given vector, specialized for 2D or 3D.

use salva::math::{Vector, Real, gcross_matrix};

let v: Vector<Real> = Vector::new(1.0, 0.0, 0.0);
let m = gcross_matrix(&v);

When managing multiple fluid objects, Salva uses a FluidSet (which is a ContiguousArena) and FluidHandles to provide efficient access and identification.

• FluidHandle: A unique identifier for a fluid object. It can be converted to and from a ContiguousArenaIndex.
• FluidSet: A collection of all fluid objects in the simulation.

// FluidHandle is a wrapper around ContiguousArenaIndex
// FluidSet is a type alias for ContiguousArena<FluidHandle, Fluid>