// undine docs
Simulation
The simulation core is responsible for all numerical computations in Undine.
It is written in C++ and optimized for heavy numerical workloads, while the Blender addon acts as the bridge that configures and launches the solver.
Simulation Core
The simulation core handles particle integration, pressure solving, viscosity modeling, boundary interaction, particle redistribution, neighbor search, and solver stabilization.
Because fluid simulation is inherently sensitive to numerical instabilities, Undine prioritizes internal consistency and predictable solver behavior over purely heuristic approaches.
The Actions tab starts and monitors the solve, while the Sim Params tab controls the numerical behavior of the solver.
Grid resolution and host memory
Grid Resolution sets the working resolution for grid-based solver stages. It is one of the most important quality and cost controls in the simulation.
The Host pin estimate is shown next to the grid controls so memory impact is visible before committing to a heavy solve.
| Control | Purpose | Practical guidance |
|---|---|---|
| Grid Resolution | Sets the main grid density used by solver stages. | Raise for detail; lower when iteration speed or memory is more important. |
| Host pin est | Estimates pinned host memory for several buffer counts. | Use it to spot settings that may exceed the available system budget. |
| Host Pinning | Chooses how Undine manages pinned host memory. | Auto is the safest starting point for general use. |
| Host Pinning Budget (MB) | Limits the amount of pinned host memory available to the solver. | Increase only when the system has enough memory headroom. |
| Pin FLIP Old Buffers | Keeps older FLIP buffers pinned when enabled. | Useful for workflows that benefit from faster buffer reuse, but it can increase memory pressure. |
Pressure solver
The pressure group controls incompressibility and volume behavior. It is one of the main places to tune stability when the fluid gains energy, compresses too much, or reacts poorly near boundaries.
Preset values can write default pressure settings. Editing an individual pressure field switches that group toward custom behavior.
| Control | Purpose | Notes |
|---|---|---|
| Pressure preset | Chooses the pressure tuning source, such as Custom. | Use presets for broad starting points, then customize only the values needed for the shot. |
| Backend | Chooses CPU or GPU pressure execution. | GPU is the normal high-performance path when available. |
| Method | Chooses the pressure algorithm, such as PCG. | PCG is a standard iterative pressure solve choice. |
| Allow Exact | Allows exact-style pressure behavior where supported. | Use only when the backend and method make it useful for the shot. |
| Iterations | Maximum pressure iterations. | Higher values can improve pressure quality but increase solve time. |
| RelTol | Relative tolerance for pressure convergence. | Lower values ask the solver to converge more tightly. |
| Fallback | Chooses how Undine reacts when a pressure path is unsuitable or fails. | Warn + Fallback preserves progress while surfacing that a fallback occurred. |
| Rhie-Chow | Optional stabilization around pressure/velocity coupling. | Leave disabled unless diagnosing pressure artifacts that this option is meant to address. |
Advanced pressure controls
The advanced pressure section exposes preconditioners, operator behavior, air treatment, and GPU multigrid retry controls.
These controls are technical. Change them one at a time and keep notes on the visual effect and performance impact.
| Group | Visible controls | Purpose |
|---|---|---|
| PCG preconditioning | CPU PCG Precond, GPU PCG Precond | Controls how the iterative pressure solve is prepared for faster or more stable convergence. |
| MG smoother | auto / jacobi / sym_rbgs | When the V-cycle multigrid is in use, selects the smoother. sym_rbgs (symmetric red-black Gauss-Seidel) preserves the SPD invariant PCG requires and typically halves iterations versus Jacobi on Poisson 3D. |
| Operator and air mode | Operator, Air Mode | Controls how solid boundaries and air-side behavior are represented in the pressure system. |
| Phi options | Use Phi, Symmetric Div-Grad, Phi Builder, Phi Reinit | Controls signed-distance or boundary-field inputs used by pressure and solid-aware behavior. |
| GPU MG safe retry | Cap Auto, Target Levels Cap, Vcycles, Smooth Scale | Limits and retries multigrid-style pressure behavior when the GPU path needs a safer configuration. |
| Coarse solve | Coarse Weighted Jacobi Enabled, Coarse Omega Manual | Tunes the coarser pressure solve used by the retry path. |
| Density boost cap | Density Boost Cap | Caps density compensation used by the pressure path to avoid excessive correction. |
FP32 tolerance floor and retry chain
On the GPU happy path, pressure runs in FP32. The FP32 PCG residual accumulates ≈ √N · ε_f32 of relative roundoff, so a requested tolerance of 1e-6 on a 256³ grid is unachievable — the solver would otherwise burn iterations against noise.
Undine clamps the requested tolerance from below by safety · √N · ε_f32 (default safety = 4.0). The floor is logged. When PCG breaks down anyway, the retry chain takes over: relax tolerance → promote to FP64 → escalate to multigrid → fall back to CPU. Each step is logged with code, iters, rel_res, and chosen backend.
When to relax safety
- Bench-comparing against an older run: set UNDINE_PRESSURE_PCG_FP32_TOL_SAFETY=2 to match prior floors.
- Very small grids where √N is small enough that the floor barely moves — the safety factor has little effect.
- Diagnostic runs where you want to see exact convergence behavior unclamped.
Transport, PIC, and vorticity
Transfer and vorticity controls shape how particle motion is carried between solver stages and how small rotational detail is preserved or enhanced.
The visible screenshots show APIC transfer, PIC Blend, Vorticity Confinement, and individual vorticity strength, scale, and time controls.
| Control | Purpose | Practical effect |
|---|---|---|
| Transfer | Chooses the particle/grid transfer model. | APIC generally preserves richer motion than a purely dissipative transfer. |
| PIC Blend | Blends toward PIC-style velocity transfer. | Higher values add damping and can calm noisy motion. |
| Surface Tension | Adds cohesive force at the liquid surface. | Useful for droplets and small-scale surface behavior; high values can look sticky or unstable if overused. |
| Surface Band | Defines the band where surface tension or surface-aware behavior applies. | Wider bands make the effect influence a thicker surface region. |
| Fluid Density | Sets the liquid density in kg/m^3. | Water-like setups typically start near 1000. |
| Vorticity Confinement | Restores or enhances rotational detail. | Useful when motion looks overly damped, but too much can add artificial energy. |
| Vorticity Strength / Scale / Time | Breaks vorticity shaping into separate controls. | Use small changes and compare playback before committing. |
Time stepping and velocity limits
The Numerics group controls how much work is performed per frame and how the solver reacts to fast motion.
Substeps and CFL settings are the first place to look when high velocity flows become unstable.
| Control | Purpose | Guidance |
|---|---|---|
| Substeps | Base number of simulation steps per frame. | Increase for fast motion, thin interactions, or difficult collisions. |
| Auto | Allows automatic substep adjustment. | Useful when velocity varies across the shot. |
| CFL Target | Targets a stable relationship between velocity, cell size, and timestep. | Lower values are usually safer; higher values may be faster but less stable. |
| Max Auto | Caps automatic substeps. | Set high enough for difficult frames but not so high that a bad setup runs indefinitely. |
| Max Velocity | Optional velocity clamp. | A zero value usually means the clamp is disabled. |
| Viscosity Mode | Chooses the viscosity path when viscosity is enabled. | Simple is the visible default in the screenshots. |
| Fast / Balanced / Quality | Chooses the quality bias for enabled viscosity/rheology behavior. | Fast is for iteration; Quality is for final stability and visual polish. |
Modular Solver Stages
The Undine solver is organized as a sequence of well-defined simulation stages.
Each stage performs a specific transformation of the simulation state and is designed to remain compatible with the rest of the pipeline.
Primary step sequence
- Advection
- Boundary interaction
- Viscosity solving
- Pressure projection
- Particle Redistribution
Additional core responsibilities
- Particle integration
- Neighbor search
- Solver stabilization
Why staged design matters
This architecture improves maintainability, allows targeted changes to individual stages, and makes debugging and validation more straightforward because each stage has a clear responsibility.
Particle separation, bricks, and density
Several Sim Params groups control how particles are distributed and how active simulation regions are maintained.
These settings matter most when particle count, density, or sparse active regions produce visible artifacts.
Bricks are Undine's sparse-grid layer: empty space costs nothing, and the solver only allocates and moves cells that hold particles plus a halo wide enough for the pressure stencil. The current backend is velocity-pages; a future-only full-pages mode is reserved internally.
| Group | Visible controls | Purpose |
|---|---|---|
| Separation | Iterations, Radius, Rate | Pushes nearby particles apart to reduce clustering and preserve a more even distribution. |
| Volume Equalization | Enable toggle | Attempts to keep perceived volume more consistent across the solve. |
| Bricks | Brick Size, Halo, TTL Frames | Controls sparse active regions used for performance and locality. |
| Dense fallback | Auto Dense Fallback, Disable Active Brick %, Re-enable Active Brick % | Switches between active-brick behavior and a denser path when active coverage crosses thresholds. |
| Density Mode | P2G | Chooses how density is transferred or estimated for grid-based stages. |
| Density Strength | Scalar density correction strength. | Higher values make density correction more aggressive. |
Simulation Consistency
In many fluid systems, different execution paths may behave slightly differently depending on whether the simulation runs on CPU or GPU.
While these differences may appear minor, they can accumulate over long simulations and lead to visually noticeable divergence.
Undine is designed with the goal of maintaining consistent solver behavior across execution paths whenever possible.
Achieving perfect numerical equivalence between hardware backends is rarely possible in practice, but maintaining comparable solver behavior remains an important design objective.
Numerical Robustness
Fluid simulations often operate in regimes that are difficult for numerical solvers.
Undine prioritizes robustness in these scenarios by favoring stable solver formulations, consistent boundary handling, careful control of particle density, and well-behaved pressure projection.
Difficult regimes
- High velocity flows
- Thin liquid sheets
- High viscosity fluids
- Complex collider interactions
Why the tradeoff matters
This approach may sometimes favor stability over raw speed, but it helps ensure that simulations remain visually believable and numerically stable across a wide range of setups.