Simulation

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.

Physical Foundation

In real fluid-solid interactions, the boundary condition determines how velocity behaves at the wall:

• No-slip (high friction): Fluid velocity matches wall velocity exactly. The fluid "sticks" to the surface. This is the standard assumption for most Navier-Stokes solvers.
• Free-slip (zero friction): Fluid slides freely along the wall with no tangential resistance. Only normal velocity is constrained (no penetration). Like water on perfectly smooth ice.
• Partial slip (intermediate friction): A blend between no-slip and free-slip. The tangential velocity is partially damped based on a friction coefficient.

Mathematically, friction introduces a tangential force proportional to the relative velocity between fluid and surface:

F_tangent = -μ_friction · v_tangent

Where μ_friction is the friction coefficient and v_tangent is the fluid velocity component parallel to the boundary.

Parameter Range and Behavior

Surface Friction is normalized to a 0.0 – 1.0 range for artist-friendly control:

Artistic and Technical Use Cases

Low Friction (0.0 – 0.3): Slippery Surfaces

Use when:

• Simulating water on ice, glass, or polished metal
• Creating fast-flowing rivers or waterfalls where boundary drag is negligible
• Stylized fluid that needs to look frictionless and energetic
• Reducing unwanted damping at walls in high-velocity flows

Visual effect: Fluid maintains speed near boundaries, creates less turbulence at walls, and flows smoothly around obstacles without sticking.

Medium Friction (0.4 – 0.6): Realistic General-Purpose

Use when:

• Simulating water on typical surfaces (concrete, wood, soil)
• General-purpose setups where realistic boundary interaction is desired
• Balancing performance and physical accuracy
• Creating natural-looking velocity gradients near walls

Visual effect: Believable drag at boundaries, visible boundary layer separation, natural-looking flow around corners and obstacles.

High Friction (0.7 – 1.0): Sticky, Absorbent Surfaces

Use when:

• Simulating honey, syrup, or thick liquids on porous materials
• Modeling fluid on fabric, sponge, or rough stone
• Creating "sticky" artistic effects where fluid clings to walls
• Emphasizing boundary layer separation and vortex shedding
• Slowing down fluid near colliders to prevent unrealistic sliding

Visual effect: Strong grip on surfaces, slow creeping flow near walls, pronounced velocity gradients, boundary layer instabilities, vortex formation behind obstacles.

Interaction with Viscosity

Surface Friction and Viscosity work together to control fluid behavior near boundaries:

• Low Viscosity + Low Friction: Fast, slippery flow. Water on ice. Minimal boundary effects.
• Low Viscosity + High Friction: Water on rough, absorbent surfaces. Fast bulk flow but strong drag at walls. Pronounced boundary layers.
• High Viscosity + Low Friction: Thick fluid (honey) on a slippery surface (Teflon). Slow bulk motion but slides freely at boundaries.
• High Viscosity + High Friction: Thick fluid (molasses) on porous material (cloth). Maximum drag everywhere — both internal (viscosity) and boundary (friction). Very slow, sticky flow.

Physically, viscosity controls internal shear resistance within the fluid, while surface friction controls boundary shear resistance at solid interfaces. Together, they determine the velocity profile from the wall into the bulk fluid.

Performance Considerations

Surface Friction is computationally cheap — it is applied as a velocity damping term at particle-collider interaction points during the boundary collision stage. Unlike viscosity (which requires a global solve), friction is a local operation.

• Cost: Negligible. Safe to adjust freely without impacting solve time.
• Stability: Does not affect CFL or substep count. Purely dissipative (removes energy).
• Iteration: Excellent parameter for rapid artistic iteration. Change it, scrub playback, see immediate results.

Advanced: Anisotropic and Spatially-Varying Friction

In advanced workflows, friction can be varied per collider or even spatially across a surface:

• Per-collider friction: Different collider objects can have different friction values (e.g., ice floor = 0.1, cloth curtain = 0.9).
• Texture-driven friction: Use a texture map to modulate friction spatially — creating patches of high and low grip on the same surface.
• Direction-dependent friction: Anisotropic friction along vs. across surface grooves (like brushed metal or wood grain). Check collider material settings for this option.

Consult the Colliders documentation for per-material friction overrides.

Troubleshooting

Fluid slides unrealistically on rough surfaces

• Increase Surface Friction to 0.6–0.9.
• Check that collider SDF resolution is high enough to capture surface detail.
• Verify that the collider is tagged correctly and not being ignored.

Fluid sticks too much at walls, looks frozen

• Reduce Surface Friction to 0.2–0.4.
• Check if Viscosity is also set too high — the combination may be over-damping the flow.
• Ensure particles are not trapped inside the collider SDF (collision margin too tight).

Inconsistent friction behavior across colliders

• Check per-collider material overrides — individual colliders may have custom friction values.
• Verify that all colliders are using the same SDF bake settings (narrow band width, resolution).
• Review the Debug panel for collision stage diagnostics.

Physical Foundation

Viscosity arises from internal friction within a fluid. Molecularly, it represents momentum transfer between fluid layers moving at different speeds. Macroscopically, it appears as a diffusion-like term in the Navier-Stokes momentum equation:

∂u/∂t + (u·∇)u = -∇p/ρ + ν∇²u + g

The viscous term ν∇²u diffuses velocity across the domain, smoothing out sharp velocity gradients. The coefficient ν is the kinematic viscosity, measured in m²/s.

Common kinematic viscosity values:

UI Controls

Undine exposes viscosity through a percentage slider (0–100%) for artist-friendly interaction and displays the corresponding kinematic viscosity in m²/s for scientific validation.

When Viscosity > 0%, the advanced viscosity panel appears, exposing solver method, quality settings, rheology models, and numerical parameters.

Viscosity Percentage Reference Table

Quick reference for common materials mapped to the percentage slider:

Control Reference

Viscosity Modes

Undine supports multiple viscosity solver paths, each with different computational cost, stability, and accuracy trade-offs.

Off

Viscosity stage is completely disabled. The fluid behaves as inviscid (zero internal friction). Use for thin water, splashes, or when viscous effects are negligible.

Simple (Explicit Integration)

Forward Euler integration of the viscous term: u_new = u_old + Δt·ν·∇²u.

• Stability: Conditionally stable. Requires Δt ≤ h²/(2dν) where d is spatial dimension (3). For small h or large ν, this can force many substeps.
• Cost: Cheapest per substep. Single Laplacian evaluation per iteration.
• Use when: Viscosity is low (water, thin oils), voxel size is large, or iteration speed is critical.
• Avoid when: Viscosity is high (honey, cream) or voxel size is small — the timestep restriction becomes prohibitive.

Advanced (Implicit Integration)

Backward Euler or semi-implicit integration: (I - Δt·ν·∇²)u_new = u_old. Solves a linear system per substep.

• Stability: Unconditionally stable. Can take large timesteps without blowing up.
• Cost: More expensive per substep due to linear solve (PCG, Jacobi, or direct methods).
• Use when: Viscosity is moderate to high, or when the explicit stability limit would require excessive substeps.
• Quality settings: Fast uses fewer iterations, Quality uses tighter convergence tolerances.

Weighted Implicit

Particle-based implicit viscosity solve with weighted least-squares or SPH-style kernel coupling. Preserves Lagrangian particle structure while solving the viscous system implicitly.

• Stability: Unconditionally stable like Advanced, but operates on particle neighborhoods instead of grid.
• Cost: Depends on particle count and neighbor density. Can be more expensive than grid-based implicit for very dense particle fields.
• Use when: Particle-level detail matters (anisotropic flows, free surfaces with complex topology), or when grid-based viscosity introduces unwanted diffusion.

Legacy

Preserves older viscosity solver behavior for compatibility with scenes from earlier Undine versions. Not recommended for new work.

Method Parameters

When Advanced or Weighted Implicit modes are active, additional numerical controls appear:

Rheology: Non-Newtonian Behavior

Real-world fluids are often non-Newtonian: their effective viscosity changes with shear rate, stress history, or deformation. Undine supports rheological models for yield-stress plasticity, shear-thinning, and shear-thickening.

Newtonian (Default)

Viscosity is constant regardless of shear rate. Water, simple oils, and glycerin are Newtonian. The stress-strain relationship is linear: τ = μ·(du/dy).

Bingham Plastic

Material does not flow until stress exceeds a yield stress τ_y. Below yield, it behaves like a solid. Above yield, it flows like a Newtonian fluid with constant plastic viscosity.

• Use cases: Toothpaste, mud, thick paint, lava, mayonnaise.
• Parameters: Yield Stress (Pa), Consistency (plastic viscosity).
• Visual behavior: Holds shape under low stress, flows smoothly once yield threshold is exceeded.

Herschel-Bulkley

Generalization of Bingham: combines yield stress with power-law shear dependence. τ = τ_y + K·(du/dy)^n.

• Use cases: Drilling mud, food pastes, cosmetic creams.
• Parameters: Yield Stress, Flow Index n (shear-thinning if n < 1, shear-thickening if n > 1), Consistency K.
• Visual behavior: Complex flow regime transitions depending on stress and shear rate.

Additional Models

The Rheology dropdown may expose additional models such as Power-Law, Cross, Carreau, or custom presets. Consult the model tooltip or preset documentation for parameter definitions.

Advanced Rheology Controls

The rheology system exposes fine-grained control over solver behavior, temporal blending, and adaptive refinement.

Practical Workflows

Water and Thin Liquids

Set Viscosity: 0–5%. Use Viscosity Mode: Off or enable Fast water bypass. Viscous effects are negligible; save cost by disabling the stage entirely.

Olive Oil, Light Syrup

Set Viscosity: 10–30%, Viscosity Mode: Simple. Explicit integration is stable enough for moderate viscosity. Monitor substep count; if CFL or viscous timestep restriction becomes expensive, switch to Advanced.

Honey, Thick Cream

Set Viscosity: 40–70%, Viscosity Mode: Advanced, Quality: Balanced or Quality. Implicit solve handles the stiff viscous diffusion without requiring excessive substeps. Increase Max Iterations if convergence warnings appear.

Toothpaste, Mud, Lava (Yield-Stress Materials)

Set Viscosity: 60–90%, Viscosity Mode: Advanced, Rheology: Bingham or Herschel-Bulkley. Tune Yield Stress to control when the material starts flowing. Use Temporal Blending to smooth yield transitions. Enable Use Phi if the material interacts heavily with colliders.

Scale-Aware Viscosity

Kinematic viscosity scales as ν → s²·ν under Cinematic Scale Lock (where s is the scale factor). This preserves the diffusion timescale across domain resizing. When using Fixed Voxels Per Meter + Cinematic Scale Lock, the effective viscosity changes to maintain visual proportionality, but CFL and diffusion constraints may relax for smaller domains.

Diagnostics and Troubleshooting

Viscosity solver fails to converge

• Increase Max Iterations (try 250–500 for very stiff regimes).
• Relax Relative Tolerance slightly (e.g., from 1e-5 to 1e-4).
• Switch Preconditioner to MG-Style for large grids.
• Increase Min Substeps to give the solver more temporal resolution.
• Check that Nu Max is not clamping the effective viscosity too aggressively.

Fluid looks overly damped or frozen

• Reduce Viscosity percentage.
• Check Effective method display — ensure you're not accidentally using a much higher viscosity than intended.
• If using rheology, verify Yield Stress is not so high that the entire fluid is below yield threshold.
• Disable Temporal Blending if it's over-smoothing dynamic behavior.

Viscosity is expensive (low FPS)

• Switch from Advanced to Simple if viscosity is low enough for explicit stability.
• Enable Fast water bypass for near-zero viscosity regimes.
• Use Fast quality preset instead of Quality.
• Increase voxel size (lower VPM) — viscous timestep restriction scales as h².
• Reduce Min Substeps if rheology is forcing excessive inner iterations.

Yield-stress transitions look jittery

• Enable Temporal Blending and increase Tau to 2.0–3.0.
• Increase Outer Iters for rheology model convergence.
• Reduce Outer Relax slightly (e.g., from 1.0 to 0.8) to stabilize nonlinear iterations.
• Use Adaptive Rebalance to let the solver adjust strategy when stuck.

Scientific Validation

Undine's viscosity solver is designed to match published fluid mechanics behavior for validation and VFX credibility:

• Poiseuille flow: Parabolic velocity profile in pipe flow matches analytical solution for Newtonian fluids.
• Couette flow: Linear velocity gradient between parallel plates under shear matches expected viscous dissipation.
• Dam break with viscosity: Flow front speed and profile match experimental data for glycerin and honey.
• Bingham plug flow: Central unyielded plug region in pipe flow matches Bingham plastic theory.

When matching real-world data, use the m²/s display to set kinematic viscosity directly from published material tables. For dynamic viscosity μ (Pa·s), convert via ν = μ/ρ where ρ is density in kg/m³.

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.

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.