Newton Fluid Support

Prototype implementation of particle-fluid simulation and ViewerGL water rendering for Newton, focused on giving solver developers a reusable fluid visualization path.

Updated 2026-06-07 from branch eric-heiden/fluid-support, based on origin/main a046d613. Media was rendered with ViewerGL.get_frame().

Candidate AS: 1280x720 at 30 Mbps CBR, 26,880 particles, scene-depth floor caustics, tropical shallow/deep absorption, sharper env-map Fresnel reflection, refraction, and screen-space ripple detail.

High-Bitrate Water Fidelity Pass

Variants AS-AX respond to the compression and water-depth feedback directly. These are rendered at 1280x720 with 30 Mbps CBR H.264, trading resolution for far fewer codec artifacts. AS-AV focus on water optics: stronger environment-map reflection/refraction, clearer tropical shallow-to-deep color separation, scene-depth floor caustics, and more visible three-dimensional surface cues. AW-AX use the corrected interactive tank example: the basin is larger/deeper, the initial fluid is carved around the rigid boxes so they do not launch out of the water on frame one, and a gentler scripted picking force keeps the cubes suspended inside the water volume.

AS-AV are high-particle water-optics renders. AW-AX are interactive-tank renders with pickable rigid cubes suspended against the transparent water body.

High-Particle 1080p Realism Sweep

Variants AG-AN are the latest pass. They rerender the dam-break with 26,880 to 42,240 particles at 1920x1080 and use the revised water shader: the repo's ViewerGL environment map is sampled for both Fresnel reflection and refracted transmission, then filtered through a water tint so the indoor panorama contributes highlight structure without turning tropical water brown. The shader also adds optical-depth absorption, procedural ripple distortion, brighter caustic strokes, and softer screen-space foam.

AG-AN broad-view sweep. AG is the balanced candidate, AH pushes environment reflection, AI pushes refraction, AJ pushes deep-blue absorption, AK pushes caustics, AL pushes foam, and AM/AN use 42,240 particles for smoother surfaces.

Close-Up Optical Stress Tests

Variants AO-AR use the same 26,880-particle setup but record an earlier, taller fluid state from a closer camera. These are less useful as final beauty shots, but they make reflection/refraction/caustic/foam artifacts easier to evaluate than a flat puddle.

Architecture

• newton.solvers.SolverSPH is an experimental weakly-compressible SPH solver using Warp kernels and a wp.HashGrid neighbor search.
• ViewerBase.log_fluid() adds a backend-neutral fluid logging API. Backends without fluid support fall back to point rendering.
• ViewerGL.log_fluid() stores particle centers/radii in a GL buffer and renders them through a screen-space fluid pass.
• The ViewerGL pass writes nearest fluid depth and optical thickness, applies separable bilateral depth smoothing, then composites water over the opaque scene using shallow/deep optical absorption, chromatic refraction offsets, screen-color reflection, Fresnel-weighted environment-map reflection, env-map transmission, scene-depth floor caustics, procedural ripple/caustic strokes, screen-space foam, and a specular highlight.
• Additional material controls now include blur radius, shallow/deep colors, gradient strength, absorption strength, depth-cue strength, refraction/reflection strength, environment-map reflection strength/LOD/color preservation, surface caustics, floor caustics, and foam strength/scale, so fluid solver authors can iterate visually without rewriting shaders.
• Particle billboards are expanded in a geometry shader instead of relying on gl_PointCoord, which was unreliable in the target headless GL context.
• example_fluid_sph_interactive_tank.py couples SPH particles to suspended rigid boxes, enables ViewerGL right-click picking, carves the initial SPH particle volume around the boxes to avoid explosive overlap impulses, and exposes water shader controls through the live GUI so solver and rendering parameters can be tuned in one demo.

Visual Variants

The gallery below explores ten rendered directions. Each card is a separate ViewerGL.get_frame() MP4 render with the exact settings shown under the video, so the visual tradeoffs can be compared directly.

Contact sheet of the generated variants. D and I use higher particle counts; the others use the same 1,008-particle SPH setup with different ViewerGL material controls.

Variant Settings Matrix

Beach Water Env-Map Sweep

Variants K-R use the updated shader path. The fluid composite samples the same ViewerGL environment map used by metallic surfaces, then weights it with a water-style Fresnel term. These videos are longer than A-J and include warmup frames so the dam-break surface has moved before recording starts.

Contact sheet for the new environment-map/Fresnel sweep. K is the current recommendation; M, N, O, and R intentionally push one parameter family harder to expose tradeoffs.

Env-Map Settings Matrix

High-Quality Tropical Gradient Sweep

Variants S-X use the new shallow/deep color-gradient controls and were rendered at 1280x720 with 96 frames per clip. The palette options are based on typical tropical beach water: pale mint or emerald shallows, cyan mid-water, deeper blue/teal thickness, white-blue caustic highlights, and subtle Fresnel environment reflection.

Contact sheet for the high-quality tropical gradient videos. These are the preferred clips for visual feedback because they preserve more resolution than the earlier A-R exploration renders.

HQ Gradient Settings Matrix

Translucency, Reflection, and Foam Sweep

Variants Y-AF investigate three material dimensions requested for follow-up: water translucency, shallow/deep color-gradient strength, and reflectiveness. They also prototype foam generation. The current foam pass is intentionally rendering-side and solver-agnostic: it uses screen-space thickness, free-surface edges, normal variation, and a procedural breakup pattern to create edge/crest foam. A physically better next step would be a solver-side foam emitter based on velocity, vorticity, air exposure, and particle lifetime, but this screen-space version is cheap and works for any solver that calls viewer.log_fluid().

Contact sheet for the Y-AF sweep. Y/AB/AA isolate translucency and reflection; AC/AD/AE explore screen-space foam strength and scale; AF is a low-gradient, low-reflection control.

Foam Investigation Matrix

Rendering Prototype

The same SPH state rendered as raw particle spheres and as the new ViewerGL fluid surface. The fluid path is rendering-only; it does not change solver state.

Prototype smoothing comparison. The selected path combines a rendering radius multiplier with bilateral screen-space depth smoothing. Low smoothing preserves every particle; the smoothed path reads more like a continuous liquid surface while remaining cheap.

Solver Prototype

SolverSPH supports active-particle filtering, density/pressure evaluation, pressure forces, viscosity, gravity, external particle forces, axis-aligned world bounds, velocity damping, and velocity clamping. It preallocates density and pressure buffers and reserves the particle hash grid at construction time.

The solver is deliberately not a full production fluid method. It is intended as a first Newton-native fluid solver and as a compact example for solver authors who want to produce particles that can be rendered as liquid through the shared ViewerGL path.

Examples

The branch adds newton/examples/fluid/example_fluid_sph_dam_break.py. It exposes the SPH parameters and ViewerGL fluid controls, including --render-mode, --beach-lighting, --ground-color, --environment-intensity, --fluid-color, --fluid-deep-color, --fluid-color-gradient-strength, --fluid-radius-scale, --fluid-smoothing-iterations, --fluid-smoothing-radius, --fluid-thickness-scale, --fluid-absorption-strength, --fluid-depth-visualization-strength, --fluid-env-map-strength, --fluid-env-reflection-lod, --fluid-env-color-preserve, --fluid-caustic-strength, --fluid-caustic-scale, --fluid-floor-caustic-strength, --fluid-foam-strength, --fluid-foam-scale, and --capture-graph.

The branch also adds newton/examples/fluid/example_fluid_sph_interactive_tank.py. It creates a deeper transparent water body with suspended rigid boxes, carves the initial particle volume around those boxes, applies SPH-to-box coupling forces, enables ViewerGL picking forces, and provides GUI sliders for the water shader, environment intensity/exposure/specular scale, picking stiffness/damping, suspension, and water-box coupling parameters.

Example invocation:

uv run --extra dev -m newton.examples fluid_sph_dam_break --viewer gl --headless --no-show-bounds

uv run --extra dev -m newton.examples fluid_sph_interactive_tank --viewer gl --no-show-bounds

Verification

• uv run --extra dev -m newton.tests -k test_solver_sph: passed on CPU and CUDA, including CUDA graph capture on cuda:0.
• uv run --extra dev -m newton.tests -k test_viewer_fluid: passed.
• uv run --extra dev -m newton.tests -k test_interactive_tank_rollout_keeps_boxes_submerged_and_stable: passed after reproducing the pre-fix failure at 1696.94 m/s maximum box speed; the corrected rollout keeps boxes submerged, under 4 m/s, and inside the larger basin.
• uv run --extra dev -m newton.examples fluid_sph_dam_break --viewer null --test --num-frames 5: passed.
• uv run --extra dev -m newton.examples fluid_sph_interactive_tank --viewer null --test --num-frames 5 --dim-x 10 --dim-y 8 --dim-z 8 --box-count 3: passed.
• Headless OpenGL smoke tests generated nonblank frames through ViewerGL.get_frame() for raw particles, fluid rendering, env-map Fresnel water, scene-depth floor caustics, and the interactive tank renderer.
• Report media check decoded 50 variant MP4 renders: A-J are 960x540 with 54 frames each, K-R are 960x540 with 72 frames each, S-AF are 1280x720 with 96 frames each, AG-AN are 1920x1080 with 120 frames each, AO-AR are 1920x1080 with 90 frames each, AS-AV are 1280x720 with 120 frames each at 30 Mbps CBR, and AW-AX are 1280x720 with 105 frames each at 30 Mbps CBR.

Next Work

• Add fluid collision against arbitrary shapes instead of only axis-aligned bounds.
• Replace or augment screen-space foam with optional solver-side foam/splash particles for high-velocity, high-vorticity free-surface regions.
• Expose per-fluid material presets for water, viscous liquid, and sand-like particle rendering.
• Consider a mesh or neural/splat surface backend later, while keeping log_fluid() as the stable frontend API.