// undine docs
Debug
Fluid simulation systems are inherently sensitive to numerical instability.
This chapter collects the diagnostic readouts and support mindset exposed across the Actions, Sim Params, and Meshify panels.
Why diagnostics matter
Small inconsistencies between solver stages can produce artifacts such as excessive kinetic energy, unstable particle motion, particle clustering, or unrealistic surface behavior.
For this reason, Undine emphasizes consistency between solver subsystems and careful numerical design.
Actions tab readouts
The Actions tab provides the most immediate runtime diagnostics while the solver or meshifier is active.
These values are not final quality metrics, but they are useful for spotting slowdowns, unexpected particle growth, or incomplete caches.
| Readout | What it indicates | Next place to look |
|---|---|---|
| POINTS | Current or recent particle count. | Emitters, particle distribution, density strength, and viewport limits. |
| SNAP FPS / AVG | Viewport playback/update throughput. | SNAP preset and playback expectations. |
| SIM FPS / AVG | Solver throughput. | Grid resolution, substeps, pressure iterations, bricks, and GPU backend. |
| Triangle count during meshify | Current mesh complexity. | Voxel size, influence radius, decimation, smoothing, and anisotropy. |
| Meshify frame progress | Current frame count through the mesh build. | Missing cache frames and backend fallback behavior. |
Preset overrides
The Sim Params panel can show values that override the selected material preset.
Override readouts are useful because they explain why the current scene no longer behaves exactly like Water, Oil, Honey, Chocolate, Slime, or another preset baseline.
| Override type | Meaning | Use |
|---|---|---|
| PIC Blend | Current PIC damping differs from the preset. | Check when motion feels too energetic or too damped. |
| Pressure Iters | Current pressure iteration count differs from the preset. | Check when incompressibility or speed changes unexpectedly. |
| Pressure Fallback | Fallback policy differs from the preset. | Check when GPU or pressure behavior does not match expectations. |
| CFL Target | Time-step safety differs from the preset. | Check when a scene is slower or more unstable than expected. |
| Density Strength | Density correction differs from the preset. | Check when volume or particle distribution appears wrong. |
| Surface Tension | Surface cohesion differs from the preset. | Check when droplets, sheets, or edges look too tight or too loose. |
Viewport limits
Viewport Limits are visual-only controls. They help inspect dense simulations without changing the actual solver result.
Use them to reduce display density while keeping the underlying simulation unchanged.
| Control | Purpose | Notes |
|---|---|---|
| Density % | Scales viewport display density. | The screenshots show 100%, meaning full visual density. |
| Max/Cell | Caps displayed particles per cell. | A value of 0 usually means no display cap. |
| Liquid Only | Restricts display to liquid particles. | Useful when debug or auxiliary particles would clutter the viewport. |
Debug toggles and cache state
Several sections expose Debug Metrics toggles or cache-state readouts.
Enable metrics when diagnosing a specific issue, then disable them when returning to normal iteration so the panel stays focused.
| Area | Visible item | Diagnostic use |
|---|---|---|
| Bricks | Debug Metrics | Inspect active brick behavior and dense fallback decisions. |
| Particle Distribution | Debug Metrics | Inspect reseeding or particle distribution behavior. |
| Meshify | Meshify cache: frames, missing | Identify incomplete frame caches before final mesh creation. |
| Meshify | Done: frames, fallback | Confirm whether mesh creation completed through the preferred path or a fallback path. |
Artifact categories worth watching
Numerical instability
- Excessive kinetic energy
- Unstable particle motion
- Particle clustering
- Unrealistic surface behavior
Why stage boundaries help
The staged design of the solver makes it easier to reason about where divergence begins, because each stage has a defined role within the simulation step.
Current documentation boundary
This page documents the visible readouts from the current screenshots. Future builds can add exact debug overlay descriptions, solver logs, and per-frame diagnostic workflows here.