Basic Concepts | Docs

Addon vocabulary

Domain

The bounding box where the fluid is allowed to live. Anything that leaves the domain is discarded. Defines the maximum simulation grid resolution.

Particle

Each fluid sample in the Lagrangian solver. Stores position, velocity, and affine matrix (C in APIC) for angular momentum preservation.

A typical scene runs with 1M–10M particles. The Actions panel shows the live count.

Emitter

Any Blender object tagged as Emitter. Each substep, it spawns particles inside its volume while it's active.

Collider

Solid geometry the fluid has to avoid. Internally converted to an SDF (signed distance field). Can be static (baked once) or animated (rebaked per frame).

Object role

Every scene object can carry one of three Undine roles: Domain, Emitter, or Collider. The role is assigned from the Objects tab.

The Active Object Params block in the panel switches based on the selected object's role — there's no global panel, everything is scoped to the active object.

Playback cache

On-disk frames produced by a solve. They let you scrub the simulation in the viewport without recomputing, and they're the input to meshing.

Clear wipes the cache, Store accepts a new mesh, Discard rejects it.

Meshify

The process of turning cached particles into a renderable polygonal surface. It runs as a separate pass from the solver, over the playback cache frames.

Deliberately deferred: the solver doesn't waste time meshing while you simulate, and you don't waste time simulating if you only want to retune the mesh.

Substep

A simulation between two Blender frames is split into several internal substeps based on CFL. Each substep runs the full pipeline (P2G → pressure → G2P → collisions) once.

The substep count auto-adjusts to keep CFL ≤ 1.0; watching it climb is the early warning that the scene is accelerating.

Numerical methods

Undine isn't a single-method solver. It blends multiple particle↔grid transfer schemes depending on what the scene needs.

Hybrid FLIP / PIC

PIC is stable but over-smooths. FLIP keeps detail but accumulates noise. The configurable blend (flip_ratio) lets you pick the balance per scene: thin water → more FLIP, thick honey or oil → more PIC.

APIC

Affine Particle-In-Cell. Each particle carries a 3×3 affine matrix on top of its velocity, which preserves angular momentum across long advections. The default in scenes with vorticity.

Viscosity & Rheology

Undine beta supports Newtonian viscosity and non-Newtonian rheology models (Bingham, Herschel-Bulkley) for production materials like honey, chocolate, and slime. These use host-authoritative or implicit solver routes when needed, with explicit logging.

Pressure (PCG / Multigrid)

Pressure projection that enforces incompressibility. PCG by default, multigrid optional for heavy scenes. Includes density correction running on device.

One substep, end to end

Every solver substep is a fixed sequence. Knowing it helps you read the Debug panel and figure out which stage is producing an artifact.

Substep pipeline (GPU-resident)

The whole sequence runs on device. Particle state doesn't leave the GPU between frames.

graph LR
    P0["Particles t"]
    P2G["P2G transfer"]
    Press["Pressure (PCG)"]
    G2P["G2P transfer"]
    Coll["SDF collisions"]
    Vort["Vorticity confinement"]
    P1["Particles t+dt"]

    P0 --> P2G
    P2G --> Press
    Press --> G2P
    G2P --> Coll
    Coll --> Vort
    Vort --> P1

Solver Architecture How the solver is split internally and what runs on CPU vs GPU. Simulation Sim Params panel controls mapped to each stage of the pipeline.

Metrics that matter

The Debug panel exposes a handful of numbers that decide whether a scene is stable before you commit to caching it. Worth learning.

Metric	What it measures	Red flag
CFL	How far a particle moves per substep, relative to cell size	Sustained > 1.0 — dt is too large; Undine will substep harder, but velocity is winning
Residual	Pressure solver error at convergence	Doesn't drop below the FP32 floor (≈ √N · ε_f32) — Poisson is ill-conditioned or noise-bound
‖∇·u‖	Velocity field divergence after projection	Grows over time — fluid is leaking compressibility, density correction isn't keeping up
Active cells	Number of grid cells holding particles	Sudden drop — particles are escaping the domain
Active bricks	Sparse regions currently allocated	Unbounded growth — the active region is sprawling beyond what was expected
Retry step	Position in the pressure breakdown chain	Sustained at FP64 / MG / CPU — the GPU PCG path isn't holding for this scene

Other vocabulary you'll meet

Streamflow

The live-preview mode. Particles produced by the solver flow into Blender's playback as they're computed; you don't wait for the end of the bake to scrub.

Two flavors: Streamflow Points (cheap point cloud, full sim speed) and Mesh Every Frame (lockstep meshing using the preset selected in the Meshify tab).

Whitewater FX (Beta)

A secondary one-way particle layer for spray, foam, bubbles, and aerated whitewater. The primary FLIP/APIC particles remain the real water mass; secondary particles add visual richness without entering pressure, viscosity, density correction, reseeding, the primary cache, or Meshify.

Use it when impacts, waterfalls, wakes, or fast-moving sheets need visible air-water detail without changing the stability of the main simulation.

Bricks

Sparse active regions of the simulation grid. Empty space costs nothing; the solver only allocates and moves the cells that hold particles, plus a halo wide enough to satisfy the pressure stencil.

The current backend is velocity-pages (velocity fields are paged), with a future-only full-pages mode reserved internally.

Runtime contract

A locked agreement between the panel and the solver about what's going to run: end-mode (points / mesh), preset, profile, input policy, world version. The contract is resolved at run time and asserted before dispatch — so the preset you saw in the panel is the preset that actually executed.

FP32 tolerance floor

The smallest residual the FP32 pressure solver can meaningfully resolve, scaled by √N (cell count) times machine epsilon. Below the floor, iterations are fighting noise — Undine clamps the requested tolerance from below to keep the solver from spinning.

Retry chain

When PCG breaks down, the solver promotes through: tighter tolerance → FP64 path → multigrid V-cycle → CPU fallback. Each step has its own log entry; nothing is silent.