// undine docs
Viscosity & VISC-PRO
Viscosity in Undine is built in four cooperating layers: the numerical solver that damps motion, the rheology model that describes the material, the optional viscoelastic memory that lets a material remember its shape, and the collider response that decides how a viscous fluid behaves on contact.
Everything viscoelastic is opt-in and OFF by default. With memory disabled, every property resolves to OFF/0 and the exported job is byte-identical to the classic water path — the advanced routes never migrate existing scenes silently.
The four layers of viscosity
Reading the panel top to bottom, four layers stack on top of each other. Knowing which layer a control belongs to is the fastest way to predict cost and behavior.
Layers 1 and 2 are stable. Layer 3 is experimental and host-only. Layer 4 is stable and applies to any fluid, viscous or not — it has its own chapter.
| Layer | What it controls | Maturity |
|---|---|---|
| 1 · Viscosity solver | The numerical "how": a Simple quality preset (Fast / Balanced / PRO Lite / Thick Exact) or a directly chosen Advanced method. | Stable production. |
| 2 · Rheology | The "what material": Newtonian / Bingham / Herschel-Bulkley, yield-stress and shear-thinning behavior. | Stable production. |
| 3 · Viscoelastic memory (VISC-PRO) | The material's "memory": Maxwell/Oldroyd-B elasticity plus a regularized yield↔elastic hold-shape coupling. | Experimental, CPU-only, opt-in. |
| 4 · Collider (SDF) | How a viscous fluid responds on contact: friction, no-slip, slip capture. | Stable; see the Colliders chapter. |
Quality presets (Simple mode)
In Simple mode the viscosity quality is chosen with a single control (viscosity_pro_quality). Four presets trade speed for fidelity, from cheapest to most expensive.
These are quality biases, not material models. They decide how carefully the viscous operator is built and solved, not what the material is.
What Thick Exact is — and is not
- It is a purely numerical preset. It does NOT add viscoelastic memory, material tensors, cohesion, adhesion, wetting, contact angle, EVP, MPM, or persistent chocolate/frosting memory. Those are layer 3 or future work.
- It does NOT force the viscosity stage on its own. If the material is still Newtonian water with base viscosity 0 and no active rheology, Undine keeps the water fast-path and exports viscosity_mode=off. To exercise PRO Exact you need a positive base viscosity OR an active rheology model.
- It is a final-bake / shot preset, not an interactive preview. It builds a larger CPU operator — preview with a lighter preset and switch to Thick Exact for the final pass.
| Preset | Internal value | What it does | When to use |
|---|---|---|---|
| Fast | FAST | Quick implicit solve. | Water and low-viscosity fluids. Interactive preview. |
| Balanced (default) | BALANCED | Good quality/performance balance. | Most fluids. The recommended starting point. |
| PRO Lite | QUALITY | Weighted implicit path (weighted Laplacian) with better free-surface and solid handling. This is not PRO Exact. | Thick fluids where Fast/Balanced look too diffusive, without paying for the exact solve. |
| Thick Exact | THICK_EXACT | Selects the PRO Exact route (exact strain-rate operator): viscosity_mode=pro_strain_rate, rel_tol=1e-5, max_iter=800, min_substeps=4, quality bias = quality. | Very thick materials (honey, syrups, pasta-style extrusion, thick sauces, base chocolate) where viscous damping and deformation quality matter more than speed. |
Advanced methods (viscosity_mode)
Advanced mode exposes the backend directly through viscosity_mode. The product labels map to runtime routes as follows.
Differences not to confuse
- PRO Lite ≠ PRO Exact. PRO Lite is the supported lightweight approximation (weighted Laplacian). PRO Exact is the strain-rate operator with exact variable-µ coupling.
- Experimental Wrapper is not PRO Exact, and there is no "Experimental 3N" PRO Exact.
- PRO Exact is host CPU only. Any GPU-resident request for pro_strain_rate resolves to an explicit host route or to a "not supported" reason. There is no GPU/resident PRO Exact.
- mg is not real multigrid for PRO Exact. Under warn it degrades to block_jacobi; under strict it fails cleanly before mutating state. Use block_jacobi as the preconditioner in final presets.
| Method (UI) | viscosity_mode | Runtime backend | Meaning |
|---|---|---|---|
| Off | off | — | Bypass. Preserved for the water fast-path. Active rheology or a positive base viscosity resolves it to an active method. |
| Legacy | legacy_explicit | explicit | Explicit diffusion. Fast but unstable at high viscosity. Water / thin fluids only. |
| Implicit | implicit_laplacian | implicit per-component | Robust production baseline for medium/high viscosity. Not a coupled tensor solve. |
| PRO Lite Weighted | variational | variational_weighted_laplacian | Weighted implicit solve with better surface/solid handling. This is PRO Lite. GPU-resident-capable. |
| PRO Exact Host | pro_strain_rate | pro_strain_rate_exact (Newtonian) / pro_strain_rate_non_newtonian (HB/Bingham) | Exact strain-rate route. CPU/host only; GPU-resident is disabled until parity is proven. |
| Experimental Wrapper | stokes_unified | stokes_unified_experimental_wrapper | Experimental iterative wrapper (hidden unless a flag is set). Not PRO Exact and not a monolithic Stokes solve. |
Solver tradeoffs
A quick map of where each route earns its cost.
| Route | Pros | Cons |
|---|---|---|
| Fast / Legacy | Interactive, cheap. | Diffusive; Legacy is unstable at high viscosity. |
| Balanced / Implicit | Robust, good default. | Does not capture fine thick-material structure. |
| PRO Lite (variational) | Better surface/solids, GPU-capable. | Still a weighted approximation. |
| PRO Exact (Thick Exact) | Maximum viscous/deformation fidelity. | Slow, CPU-only, large operator; for final bakes. |
Rheology (material model)
Rheology mounts on top of the viscosity solver and is visible once viscosity is active. The master property is rheology_model.
Herschel-Bulkley is the most complete model: it combines a yield-stress with shear-thinning or shear-thickening.
Rheology controls
Defaults shown are safe; soft limits are the recommended working ceilings even where the hard range is wider.
| Model | Value | Describes |
|---|---|---|
| Newtonian (default) | newtonian | Constant viscosity. Preserves current behavior. |
| Bingham | bingham | Yield-stress fluid, n=1 behavior above the threshold. |
| Herschel-Bulkley | herschel_bulkley | Yield-stress plus shear-thinning/thickening — the most complete model. |
Rheology controls in detail
These controls appear under the Rheology section when a non-Newtonian model is selected. Flow Index is only active in Herschel-Bulkley.
Pros and cons
- Pros: real yield-stress (hold-shape), physical shear-thinning, fine control over temporal stability.
- Cons: more parameters to tune; the outer Picard solve adds cost; mis-set gamma_dot_eps or clamps can produce spikes or excessive diffusion.
| Control | Property | Default · Range | What it does / when to tune |
|---|---|---|---|
| Yield Stress | rheology_yield_stress_pa | 0.0 · 0–100000 (soft 500) | Stress threshold (Pa) below which the material tends to hold its shape. 0 = fluid; ~20–100 sauces; ~100–500 pastes. |
| Consistency | rheology_consistency_pa_s_n | 0.0 · 0–100000 (soft 500) | Herschel-Bulkley consistency coefficient K. ~10 ketchup, ~50 chocolate, ~200 pasta dough. |
| Flow Index | rheology_flow_index | 1.0 · 0.05–2.0 | HB index n. <1 shear-thinning (sauces, paint), >1 shear-thickening (oobleck). Active only in Herschel-Bulkley. |
| Density Ref | rheology_density_ref | 1000.0 · 1–100000 | Reference density used to convert apparent dynamic viscosity to kinematic. |
| Gamma-dot Eps | rheology_gamma_dot_eps | 1e-3 · 1e-6–1.0 | Minimum strain-rate epsilon that avoids a singular apparent viscosity (divide-by-near-zero shear). Raise if spikes/NaNs appear; lower for sharper yielded/unyielded contrast. |
| Nu Min | rheology_nu_min | 0.0 · 0–100000 | Lower clamp on apparent kinematic viscosity after rheology evaluation. |
| Nu Max | rheology_nu_max | 1000.0 · 0–100000 (soft 100) | Upper clamp (m²/s). Typical useful range 0–100; raise for extreme materials. Bounds cost/instability in very viscous zones. |
| Outer Iters | rheology_outer_iters | 2 · 1–20 | Outer Picard iterations for the non-Newtonian solve. More = better variable-µ coupling fidelity, more cost. |
| Outer Relax | rheology_outer_relax | 1.0 · 0–1 | Picard blend weight of the freshly rebuilt field. 1.0 = 100% new; 0.35 = 35% new + 65% previous (more stable, slower to converge). |
| Early Exit Rel | rheology_early_exit_rel | 1e-3 · 0–1 | Relative threshold to stop the outer iterations once changes are small. Speeds things up with little visible quality loss. |
| Use Phi | rheology_use_free_surface_phi | True · bool | Uses the free-surface SDF when rebuilding rheology fields where available (better behavior at the fluid edge). |
| Adaptive Rebuild | rheology_adaptive_rebuild | True · bool | Reuses rheology fields and only rebuilds them when the state changes enough. Saves cost without losing fidelity in stable states. |
| Temporal Blend | rheology_temporal_blend_enabled | True · bool | Blends apparent viscosity with the previous substep to reduce flicker in yielded/unyielded zones. |
| Tau | rheology_temporal_tau_frames | 1.5 · 0.1–32 | Time constant (frames) of the temporal blend. Higher = more temporal smoothing (less flicker, more response latency). Active only when Temporal Blend is on. |
Viscoelastic Memory (VISC-PRO)
The Viscoelastic Memory panel (inside Numerics) is experimental, opt-in, and CPU-only. Default OFF, OFF bitwise: with memory off, every property resolves to OFF/0 and the job is identical to the current one. The Advanced rows are gated behind the Enable toggle and appear disabled while memory is off.
What it adds: elastic material memory (Maxwell/Oldroyd-B) plus a regularized yield↔elastic hold-shape coupling. Below the yield, the material retains shape like an elastic solid; above it, it flows. The transition is smooth (Papanastasiou / tanh style, no hard threshold), so there is no substep-sensitive jitter or discontinuity.
What it does NOT add
Neither VISC-PRO nor Thick Exact / PRO Exact provide: conformation tensors beyond a wired Maxwell/Oldroyd-B runtime, cohesion, adhesion, wetting, contact angle, EVP, MPM, or cache/resume of the history tensor. Those are future phases.
State: CPU-only. The GPU memory kernel does not exist yet (viscoelastic_gpu_kernel_available=0). Under FULL Resident strict, memory blocks cleanly unless the user explicitly enables the CPU bridge.
Simple mode — preset and intensity
Enable (viscoelastic_enabled) is the master toggle, default OFF. Preset (viscoelastic_preset) chooses Chocolate Memory MVP or Toothpaste Memory MVP. Intensity (viscoelastic_intensity, 0–1) scales the preset's polymer contribution.
Material memory presets
Two paste material presets (paste_material_preset) turn on memory plus Herschel-Bulkley plus yield without touching the advanced controls. They use viscosity_mode=variational (GPU-resident-capable) and route paste forces through cpu_reference.
They are labelled "(Experimental)" in the enum and kept out of the main list until visual QA is green: CPU-only reference; may be slow; not promoted until visual QA passes. They are reversible — return to off or to a memory-free preset and memory turns off.
| Preset | Yield (Pa) | Relaxation (s) | Polymer ratio |
|---|---|---|---|
| chocolate_memory | 350 | 0.35 | 0.50 |
| toothpaste_memory | 900 | 0.55 | 0.65 |
Viscoelastic Memory — advanced controls
The physical parameters of the constitutive route. Memory only activates with the Maxwell/Oldroyd-B model.
Yield Stress (hold-shape)
rheology_yield_stress_pa also appears in the memory context. The yield↔elastic coupling only acts with memory ON and yield > 0; yield-only behavior (without memory) is unchanged.
| Control | Property | Default · Range | What it does / when to tune |
|---|---|---|---|
| Model | viscoelastic_model | off · off / maxwell_oldroyd_b | Constitutive model. Memory only activates with maxwell_oldroyd_b. |
| Relaxation (s) | viscoelastic_relaxation_time_s | 0.35 · 0–1e6 (soft 5) | Stress relaxation time. High = the material remembers deformation longer (more elastic/sticky); low = relaxes fast (more liquid). The UI warns if relaxation is shorter than the effective dt. |
| Polymer Ratio | viscoelastic_polymer_ratio | 0.5 · 0–100 (soft 2) | Polymer viscosity as a ratio of the current base kinematic viscosity. Raises relative elasticity. |
| Polymer Nu (m²/s) | viscoelastic_polymer_viscosity_m2s | 0.0 · 0–1000 (soft 1) | Direct physical polymer kinematic viscosity. 0 = use Polymer Ratio × base viscosity. |
| Stress Clamp | viscoelastic_stress_clamp | 0.0 · 0–1e12 (soft 100) | Absolute stress clamp. 0 = solver auto-clamp. Raise to tame spikes in violent scenes. |
| Transport Substeps | viscoelastic_transport_substeps | 2 · 1–64 | Substeps of the constitutive stress transport. More = more stable/accurate memory transport, more cost. |
| Debug Metrics | viscoelastic_debug_metrics | False · bool | Serializes diagnostic viscoelastic metrics. Also unlocks the Upper Convected control. |
| Upper Convected (Experimental) | viscoelastic_upper_convected | False · bool | Upper-convected term. Hidden unless Debug Metrics is on. The operator exists but the runtime still passes grad_v=nullptr: it is not wired and produces no effect yet. Do not enable expecting a result. |
Allow CPU Bridge under Strict (Experimental)
Under FULL Resident strict, the CPU memory normally blocks — the resident contract stays intact and speed stays intact. allow_cpu_viscoelastic_bridge (default OFF) is the opt-in that changes this.
With the bridge ON, the CPU viscoelastic coupling runs as a host bridge and the resident contract is declared broken by explicit user opt-in — never silently, with an explicit route_reason. The flag is only written to JSON when it is ON or when memory is active, so a scene without memory stays byte-identical.
| Control | Property | Default |
|---|---|---|
| Allow CPU Bridge under Strict (Experimental) | allow_cpu_viscoelastic_bridge | OFF |
When to use viscoelastic memory
Use it for materials that should remember their deformation: chocolate or cream with persistent folds, toothpaste with a crest that holds, real hold-shape under yield.
Do not use it when plain viscous thickness without memory is enough — Thick Exact / PRO Exact is faster and more stable for that.
Pros and cons
- Pros: real hold-shape, smooth yield transition without jitter, reversible, measurable OFF-vs-ON, safe defaults.
- Cons: CPU-only (slow on large scenes), experimental, upper-convected not wired, and under strict it requires breaking the resident contract via opt-in. Recommended for small / hero scenes until promoted by visual QA.
Collider contact response
Layer 4 — how a viscous fluid responds when it touches an SDF collider (friction, no-slip, slip capture) — is documented in the Colliders chapter. It applies to any fluid, not only viscous ones, which is why it lives there.
What not to expect
To keep expectations aligned with the release base, a few things the viscosity routes do not claim:
- No GPU/resident PRO Exact and no stable multigrid (mg) for PRO Exact — neither exists in the release base.
- No preset names that imply unsupported routes (for example "GPU Exact" or "Frosting Final").
- Thick Exact and PRO Exact are numerical routes, not material memory.
- The entire viscoelastic layer and the Chocolate / Toothpaste Memory presets are experimental and CPU-only.
- Global defaults do not change: water and existing non-Pro viscosity do not migrate to PRO Exact automatically.