A liquid solver for one consumer GPU. It bakes jets, geysers and torrents into a mesh sequence that you can load in Blender or three.js.
| Solver | Bake time | Device |
|---|---|---|
| Spume | 2 min 10 s | GPU |
| Genesis (DFSPH) | 5 min 56 s | GPU |
| Mantaflow (Blender 5.2) | 73 min 44 s | CPU |
All three bake the same scene: 150 frames, a 0.05 m cell and about 500k particles, on one RTX 3060. Spume was tuned for this scene and the others are close to default. Mantaflow's inflow was set higher to match the 8 m/s jet, Genesis used Spume's mesher, and other jobs were running on the machine. Mantaflow still throws a better splash.
Spume uses FLIP on a staggered grid, Ihmsen whitewater (spray, foam and bubbles) and GPU marching cubes, written with NVIDIA Warp. A Blender add-on bakes from a Physics panel.
You need uv and an NVIDIA GPU with a recent driver. uv gets Python 3.12 for you.
git clone https://github.com/codepawl/spume
cd spume
uv run spume --out out/test --cell 0.2 --width 6 --height 20 --frames 40 --mesh-cell 0.25This small test took 140 s on a first run, on an RTX 3060 that other jobs were also using. The mesh of each frame goes to out/test, in the output format. To bake the full geyser, run this command:
uv run spume --out out/geyser --name geyserTo use the spume command outside the checkout, install it from the checkout:
uv tool install .Without an NVIDIA GPU, add --device cpu. That works for a small test and is too slow for real work. The package is not on PyPI yet.
A lateral torrent from a pipe (about 25 s at 0.15 m cells):
uv run spume --out out/outfall --inflow side --length 14 --width 6 --height 5 --cell 0.15 --opening 1.2 --speed 7 --feed 3 --frames 60 --mesh-cell 0.2 --preview out/outfall.png
A surge in a closed culvert:
uv run spume --out out/culvert --inflow side --closed --shape rectangle --opening-size 2.2 1.6 --length 14 --width 3 --height 3 --cell 0.15 --speed 6 --inflow-height 1.0 --frames 60 --mesh-cell 0.2 --preview out/culvert.png
A jet under a concrete slab, drained by a box at the far end (--obstacle-box and --outflow-box take X0 Y0 Z0 X1 Y1 Z1 in domain metres):
uv run spume --out out/slab --width 8 --height 10 --cell 0.1 --inflow-position 3 4 --obstacle-box 2 4.3 3 4 5.5 5 --outflow-box 7.5 0 0 8 2 8 --frames 60
Two inflows from a file (--inflows inflows.json):
[
{"mode": "floor", "position": [3.0, 4.0], "speed": 17, "size": 0.7},
{"mode": "side", "position": [0.0, 1.1, 3.8], "direction": [1, 0, 0], "speed": 7, "size": 1.1, "feed": 3}
]Units are metres, seconds, +Y up, the floor at y = 0 and the domain's low corner at the origin. Every option has a default (--help).
| Group | Options |
|---|---|
| Output | --out folder, --name, --fps, --frames, --skip-seconds (simulate without writing, to start on a steady flow), --preview out.png (point-cloud picture at three moments), --seed |
| Domain | --cell simulation cell, --width (z), --length (x, default = width), --height, --closed (solid walls on all six faces, ceiling included) |
| Inflow | --inflow floor|side, --inflow-position X Z (floor) or X Y Z (side), --inflow-height, --direction X Y Z, --shape circle|rectangle, --opening (diameter), --opening-size WIDE HIGH, --speed, --rise, --feed, --taper, --cone, --turbulence |
| Many inflows | --inflows file.json: a list of {mode, position, direction, shape, size, speed, rise, feed, taper, delay}. Missing keys take the command line values. size is a diameter, or [wide, high] for a rectangle. delay is the seconds before the pulse starts. |
| Obstacles | --obstacle-mask file.npy (bool array (nx, ny, nz) of solid cells on the solver grid, nx = round(length / cell)), --obstacle-box X0 Y0 Z0 X1 Y1 Z1 (repeatable; every cell the box overlaps is solid) |
| Outflow | --outflow-box X0 Y0 Z0 X1 Y1 Z1 (repeatable): liquid and whitewater inside are deleted |
| Pressure | --pressure cg|sor, --iterations, --omega (SOR only) |
| Viscosity | --viscosity (m^2/s), --viscosity-iterations |
| Floor | --floor-friction (per second): slows liquid in the cell row on the floor. A slip floor makes a fast sheet thinner than a cell. Try 1 to 3, higher keeps the water deep |
| Liquid | --liquid-box X0 Y0 Z0 X1 Y1 Z1 (repeatable; liquid at rest in the box at frame 0, solid cells skipped), --particles-per-cell, --flip (FLIP share of the PIC/FLIP blend), --separation (pushes crowded cells apart, so an impact splashes; slow water closes the gaps again, so a pool keeps its volume), --cfl, --max-particles |
| Surface | --mesh-cell, --mesh-radius, --iso |
| Whitewater | --no-whitewater, --ww-capacity, --ww-trapped-rate, --ww-crest-rate, --ww-life MIN MAX, --ww-export (points kept per frame), --ww-buoyancy, --ww-drag |
How the pieces behave:
- Inflow. A floor inflow is a vertical jet out of the floor at
--inflow-position(default the middle). A side inflow is an opening at any point. When its centre lies on a domain face, that face is solid around it (a pipe wall). Every inflow has its own pulse: an optional delay, a smooth rise, a held feed, a smooth taper. An inflow at zero speed does not touch the flow. - Obstacles. Solid cells carry no flow through their faces and no pressure. Liquid and whitewater particles slide along them. The mesher moves surface vertices out of a solid, so the mesh does not enter the obstacle.
- Jet breakup.
--turbulenceputs slow waves across the opening, in the speed and the direction of the water. They change at a Strouhal number of about 0.3 (speed over diameter). The solver has no surface tension or air. With--turbulence 0, a jet stays a smooth rod until it hits something. - Surface. Each particle's kernel takes its shape from its neighbours (after Yu and Turk 2013). The kernel flattens on a sheet and stretches along a rope. Its centre moves towards the mean of its neighbours. A small blur on the density field joins the rest. Droplets with few neighbours go in after the blur, so they stay. The mesher mirrors particles near the floor, so a thin sheet keeps its full kernel. Triangles wind outward, so a renderer with backface culling still shows open sheets.
- Walls. The floor is always solid.
--closedmakes all six faces solid. Every other face is open air (pressure 0), and particles that leave through it are removed. Whitewater bounces off solid side walls and the ceiling. - Progress. The solver prints
frame i/nafter every frame, so a host can show a progress bar. - Determinism. Seeds are fixed, and a hash of each particle's id chooses the whitewater subsample. Particle-to-grid uses GPU atomics, and their order is not fixed. So two GPU runs agree closely, not bit for bit.
--pressure cg (default) is a matrix-free conjugate gradient with a Jacobi preconditioner, all on the GPU (pressure.py). The step lengths stay on the device, so an iteration never waits for the host. --pressure sor is the red-black SOR sweep. Use --iterations 60 with it to get an asset from 0.1 or 0.2 again. Both start from the previous step's pressure. --iterations counts CG iterations or SOR sweeps (two half-sweeps each).
Measured on the street-geyser settings (RTX 3060, 180 frames, 213 thousand liquid particles, grid 113 x 250 x 113 at 8 cm). Residual is the worst divergence left in a liquid cell after projection, in 1/s. The table gives its mean over the frames and its worst frame. sim is the solver time without whitewater and mesh:
| Solver | Iterations | sim | mean residual | worst residual |
|---|---|---|---|---|
| SOR | 60 | 48.4 s | 0.297 | 1.02 |
| CG | 20 | 42.9 s | 0.052 | 0.22 |
| CG | 40 | 51.3 s | 0.027 | 4.19 |
| CG | 60 | 61.7 s | 0.0005 | 0.07 |
CG with 20 iterations is faster and about six times tighter than SOR with 60. The 40 and 60 rows were timed while another program was using the GPU, so read their times as upper bounds.
A spike in the worst residual comes from a lone particle in a cell with a face that holds almost no weight. The particle does not read that face, so the spike does not move the liquid.
--viscosity adds an implicit solve on the liquid faces after gravity and before pressure, by Jacobi sweeps (diffuse_face in flip.py). Solids and solid walls are no-slip. A free surface has no shear. Use a low --flip with it, such as 0.3, because FLIP noise breaks up a thick rope. The value is a kinematic viscosity: about 0.01 m^2/s for honey and 0.1 for thick cream, as a starting point. Few sweeps under-solve a high value, so the liquid is thinner than the number says.
These options set the look, from thin to thick:
| Option | Thinner | Thicker |
|---|---|---|
--floor-friction |
0 to 2: the liquid runs out in a sheet that tears | 8 or more: the liquid stays deep on the floor |
--separation |
1.5: an impact throws water up | 0: an impact loses most of its energy, and the water stays low |
--turbulence |
0.15 to 0.3 on a big jet: the jet tears and spreads | 0: the jet stays a smooth rod |
--flip |
0.97 to 0.99: more splash, more loose droplets | 0.3 to 0.9: slow, smooth motion |
--iso |
0.35 to 0.5: a thin surface | 0.2: a fat surface |
--viscosity |
0 | 0.01 for honey, 0.1 for thick cream |
On a thin faucet stream, keep --turbulence low, about 0.06. A high value twists the stream. --separation also adds to the residual divergence in report.json, because it asks for divergence on purpose in crowded cells. A pool fed by a faucet rose by the pumped volume to within 4% over 500 frames, measured at a 0.05 m cell.
-
launcher.pyrecords each kernel launch and resends only the scalars that changed. On an RTX 3060, a plainwp.launchcosts about 130 microseconds and a recorded one about 20. A step makes more than 100 launches. -
sparse.pyruns the grid kernels only over active blocks of 8 x 8 x 8 cells. A block is active when it or a neighbour holds liquid. The pressure solve runs on a list of the liquid cells. Fields stay dense, so sampling still works anywhere. -
A step extrapolates velocity once, for whitewater. Liquid particles only read faces they splatted to.
-
The step size comes from the fastest inflow or a free fall from the top of the domain. A small scene takes no extra steps.
-
The mesher pushes vertices out of obstacles on the GPU (
push_out_of_solidinsurface.py). A host loop did this before, and it was the slowest step of a mesh. It took 105 to 130 ms a frame at 330k to 470k particles. Marching cubes takes 40 ms, the kernel fit 5 to 13 ms and the blur 8 ms.
The scene at the top of this page uses a 0.025 m mesh and no whitewater. It took 130 s on an RTX 3060 that another job was also using (simulation 31 s, mesh 83 s). With the push on the GPU, the mesh step of frames 40 and 100 takes 61 and 71 ms, down from 161 and 210 ms. These are back-to-back runs on the same particles and GPU. The meshes have the same vertex count and a volume within 0.1%. That 130 s has not been measured again, because other jobs kept the GPU and CPU busy and whole-bake times swung two to four times.
<out>/frame_0000.glb ... one mesh per frame (binary glTF; positions int16 over the accessor min/max, normals int8)
<out>/spray.bin float16 x y z vx vy vz per whitewater point, frames back to back
<out>/spray_ids.bin uint32 per point, stable for the point's life (size and jitter per point in a renderer)
<out>/spray_kinds.bin uint8 per point: 0 spray, 1 foam, 2 bubble (absent in caches from 0.1; treat as optional)
<out>/meta.json fps, frame count, bounds, head height per frame, [first point, count] per frame in spray.index, settings, origin
<out>/report.json time of each phase, video memory peak, residual divergence, byte count
Positions are relative to meta.origin, the first opening's centre on the floor (x and z). A scene can place the asset at the opening. Add origin back to get domain coordinates. With --no-whitewater the spray files are empty. meta.settings.resolved_inflows lists every inflow as it was used.
In spume/:
cli.pythe command line and the simulation loop.flip.pyparticles to grid, gravity, inflow openings, solid walls and obstacles, SOR pressure, grid to particles (PIC/FLIP blend), outflow boxes.pressure.pythe conjugate-gradient pressure solve.sparse.pythe active blocks and liquid cells.launcher.pyrecorded kernel launches.whitewater.pyspray, foam and bubbles from trapped-air, wave-crest and kinetic-energy potentials (Ihmsen, Akinci, Becker and Teschner, "Unified spray, foam and air bubbles for particle-based fluids", 2012): emission, advection, per-point kind.surface.pyanisotropic particle kernels to a density field, marching cubes, field-gradient normals.export.pythe frame sequence writer.preview.pythe point-cloud PNG.
run.py in the root only starts spume for older bake scripts. blender/ holds the add-on.
The tests run one small bake on the CPU, so they need no GPU:
uv run pytest- Floor water is joined more than before but not like Mantaflow's. At frame 100 of the comparison scene, the largest component holds 85% of the floor water, up from 39% (Mantaflow: 81%). The mesh has 346 components, down from 3890 (Mantaflow: 81). At frame 60 the share is 77% (Mantaflow 90%).
MIN_NEIGHBOURS = 8insurface.pycaused the crumbs. The edge of a sheet one cell deep has 3 to 7 neighbours, so its particles became droplets. Water one particle thick at the far edge of a sheet now falls under the iso level. The water is thinner than Mantaflow's (median 6 cm against 10 cm, same measure), and no thicker than before at the 90th percentile (12.7 cm). - The mesh step is still 40 ms of marching cubes over the whole mesh grid. Marching only the active region can cost less.
Surface tension, a multigrid preconditioner, moving obstacles.
Apache-2.0, see LICENSE. Copyright 2026 CodePawl. The code is original. It follows the published methods named above and uses Warp's public API.
Made by CodePawl, an independent 3D studio in Vietnam.
Website ·
X ·
GitHub ·
Hugging Face ·
YouTube ·
Threads
