// undine docs
Introduction
Fluid solvers inside Blender have been stuck in the same loop for years: minutes per frame, overnight bakes, finding out the next day that the timing is off, repeat.
Undine exists to break that loop. The goal isn't to ship a 'better' solver in the abstract — it's to ship one you can actually iterate on, with numerics you can read while the sim is still running.
The problem it solves
The first test of a solver isn't the final quality of the water. It's how many times you can re-tweak a parameter before you give up.
Mantaflow and the commercial addons available in Blender today do solve the sim, but they force you to wait minutes per frame and, on heavy shots, hours per take. Real iteration becomes impossible.
Undine targets exactly that: GPU-resident pipeline, no blocking D2H transfers, live metrics. The goal is for the test → adjust → test loop to last seconds, not hours.
Project focus
- Interactive viewport iteration (up to 15 FPS with 8M particles on RTX 4070 for water fast-path)
- GPU-resident fast path for water and lighter fluids — explicit logged fallback routes for production viscosity/rheology
- Numerical metrics exposed per substep (CFL, residual, divergence, retry chain step, brick state)
- Strict separation between Python UI and C++/CUDA solver — runtime contract between them
- Consistent stability in tough regimes (high viscosity, non-Newtonian rheology, animated colliders)
- Live preview via Streamflow — solver and viewport share one cache
- Native motion blur via per-vertex .velocities baked into the Alembic export
Who it's built for
Artists who need to iterate fast
Tweak viscosity, gravity, emission, and see the result on the next viewport playback. You don't need to understand the solver to use it well — the presets cover the common cases.
Technical artists
Access to the Debug panel with CFL, Poisson residual, divergence, particle count, and per-stage GPU profile. For tuning, validating before a serious bake, or investigating what's happening in a weird scene.
Small studios and indie production
No per-seat licensing, no distributed pipeline, no farm. A decent GPU and Blender. The price fits inside an indie project's budget.
Research and experimentation
The solver is structured around replaceable stages. If you want to try a new transfer scheme or a different pressure method, you don't have to rewrite the rest of the pipeline.
Design decisions
GPU-resident fast path
Particle data lives on device between frames for the water fast-path. The Python addon never reads buffers inside the simulation loop; it only dispatches work, collects scalar metrics, and pulls data back at end of bake or on a mesh request.
This eliminates the ~2.3 ms per-frame D2H bottleneck that was blocking interactive FPS in scenes with density correction. When production viscosity or rheology require host-authoritative or implicit routes, the solver logs the decision and handles the transfer explicitly; those routes are slower but stable.
Metrics as a first-class citizen
The Debug panel isn't an extra: it's part of the solver. Watching the Poisson residual converge or seeing CFL creep toward 1.0 tells you whether the scene will be stable before you commit to caching it.
Stability over raw speed
When there's a choice between a numerical shortcut that saves 0.2 ms per substep and a branch that holds up in tricky regimes, Undine takes stability.
The speed comes from the pipeline (everything on GPU, no useless syncs), not from compromising consistency.
Presets to start, sliders to refine
Presets are tuned for real scenarios (water, oil, honey, chocolate, slime — and MPM material families like snow and dough). An artist can start from scratch, apply a preset, and have something reasonable in 30 seconds.
When tuning is needed, parameters are organized per panel and documented without hiding what they actually do under the hood. Override readouts make it visible when a scene has drifted away from the preset that was applied.
Runtime contract
What runs is what the panel said would run. The runtime contract is a small explicit object — end-mode, preset, profile, input policy, world version — that the addon resolves and the solver asserts before dispatch.
This rules out a class of subtle bugs where the panel says one thing and the solver silently does another. If the contract fails, the run aborts cleanly with a diagnostic; nothing 'works but produces a crude mesh because a global preference overrode the scene-level setting'.
Technical-artistic premise
A fluid simulation is a numerical system before it's a visual one. The visuals come out the way they do because the numerics resolve the way they do — pressure incompressibility, transfer dissipation, vorticity preservation, surface reconstruction.
Undine takes that seriously. The Debug panel isn't decoration; it's the loop. CFL tells you whether dt is too large. The pressure residual tells you whether the solve actually converged. The retry-chain step tells you whether you're on the GPU happy path or you've already escalated twice. Once you can read those, the visuals stop fighting you.
The artistic dividend is iteration speed. Every minute you don't spend waiting for a bake is a minute spent looking at the result and deciding what to change next.