Houdini 20.5 Nodes Geometry nodes

Shallow Water Solver geometry node

Runs shallow water simulations on height fields.

On this page
Since 19.5

The Shallow Water Solver SOP can simulate bulk behavior of water on height fields. It can be used both for large-scale scenarios, like flooding a valley in terrain, or to simulate small-scale effects, such as a stream flowing into a storm drain. Water is represented by its depth at each point; as such, the Shallow Water Solver is not able to capture spray or splashes.

This operator uses an explicit method to integrate the dynamics on the OpenCL device. Although this is fast, it can suffer from stability problems when working at higher resolutions. There are several safety features that can be enabled on the solver to mitigate such stability issues.

The Shallow Water Solver is fairly faithful across different resolutions. Thus, it’s recommended to start at a lower resolution (corresponding to larger Voxel Size Scale values), which will also let you get away with fewer Substeps. Once the desired motion is achieved with these lower quality settings, you can ramp down the Voxel Size Scale and run a full resolution simulation. You will also have to increase Substeps to ensure that the simulation remains stable. As a rough rule of thumb, if you decrease Voxel Size Scale by a factor of X, then you should multiply Substeps by X to retain stability.

Inputs

Height Fields

Height field layers used for simulation. The purpose of the incoming layers can be set in the Bindings tab.

The exception is the hard-coded vel vector volume. If it exists, it will be treated as the starting velocities for the simulation. Additionally, if forces are set to be applied (that is, Forces Frequency is enabled), the vel vector field acts like the goal velocity field. Specifically, simulation velocities will be driven towards these goal values inside the Force Mask Layer.

Outputs

Height Fields with Simulated Water

Input height fields, along with simulation results for the Water Layer.

Parameters

Reset Simulation

Clears the entire simulation cache.

Start Frame

The simulation will begin at this frame on the Houdini playbar.

Setup

Input Water Height Is Absolute

When this toggle is enabled, incoming values in the Water Layer are assumed to contain location of the water surface; in this case, height of the water column at each voxel is the difference between Water Layer and Seabed Layer. If this is disabled, then Water Layer should contain height of the water column at each voxel.

Input Terrain Includes Water Height

When enabled, Seabed Layer is assumed to also incorporate the water; in this case, height values for the bottom collider are the difference between Seabed Layer and Water Layer. If this is disabled, Seabed Layer should be the pure bottom collider.

Up Axis

Normal axis for the height fields. This applies to inputs and outputs.

Gravity

Acceleration due to gravity. Larger values of Gravity will more quickly flatten the water surface and also result in faster wave speeds.

Velocity Diffusion

Controls the amount of blurring done to the velocity field. Larger values will make the liquid more viscous. Small amounts of diffusion can also help to stabilize a simulation.

Time Scale

A scaling factor for time inside the solver. 1 is normal speed, greater than 1 speeds up the simulation, while less than 1 slows it down.

Boundaries

Controls behavior of waves that hit the domain boundaries. When set to Reflective, waves will bounce off of boundaries and move back in the direction they came from. Periodic results in waves wrapping around the domain and continuing their motion on the other side.

Damping Layer

Enable Damping Layer

Waves normally reflect when they hit the boundaries or continue moving on the other side (as set by the Boundaries parameter). A damping layer can be used to slow down waves as they approach the boundary, making it appear as if waves are freely exiting the domain. Turning on this parameter allows you to selectively add such damping layers on the four sides of the simulation region.

Damp Water Depths

When this toggle is enabled, water depths are also decayed within the damping layers. This prevents accumulation of water in the damping layer and can be used to let water to seamlessly flow out. Damp Water Depths should be turned off if water is meant to remain in the domain (for example, when working on a sea patch); otherwise, water will be siphoned off on the damped sides.

-X Axis

Toggles the damping layer on the negative X side. This parameter is not available if Up Axis is X.

+X Axis

Toggles the damping layer on the positive X side. This parameter is not available if Up Axis is X.

-Y Axis

Toggles the damping layer on the negative Y side. This parameter is not available if Up Axis is Y.

+Y Axis

Toggles the damping layer on the positive Y side. This parameter is not available if Up Axis is Y.

-Z Axis

Toggles the damping layer on the negative Z side. This parameter is not available if Up Axis is Z.

+Z Axis

Toggles the damping layer on the positive Z side. This parameter is not available if Up Axis is Z.

Layer Size

Size of damping layers. Damping layer must be large enough to allow for gradual slowing of the waves. If the damping layer is not sufficiently large, waves may still reach the boundary and reflect back into the domain.

Damping Strength

Controls how fast velocities decay inside the damping layers. Damping Strength must be high enough to properly slow down waves that enter the damping layer; but setting this value too high will stop the waves too abruptly, causing them to reflect within the layer.

Constraint Updates

Additive Sourcing

When enabled, scaled values in the Source Layer will be added to the Water Layer during the simulation. If this toggle is disabled, Source Layer instead acts like a minimum water level (that is, Water Layer is not allowed to fall below the prescribed source).

Source Scale

A multiplier applied to values in the Source Layer before using them to inject new water into the simulation.

Source Frequency

Specifies how frequently to update sources used in the simulation from the Source Layer. Initialize Only copies the field at the start of the simulation and uses it throughout; this is the fastest option and should be used with a static source (or if animation can be delegated to Source Scale). Once per Frame refreshes the simulation source on the first substep of each frame; this should be used with changing sources whenever possible. Every Substep is the slowest option, and should be avoided, except for special cases with very rapidly changing sources.

Sink Frequency

Specifies how frequently to update the simulation sink from the Sink Layer. The sink will be used to remove water from the simulation in relative amounts. For example, value of 0.1 indicates that the amount of water in the voxel should be reduced by 10% in one frame at the canonical frame rate of 24 per second.

Initialize Only copies the field at the start of the simulation and uses it throughout; this is the fastest option and should be used with a static sink. Once per Frame refreshes the simulation sink on the first substep of each frame; this should be used with changing sinks whenever possible. Every Substep is the slowest option, and should be avoided, except for special cases with very rapidly changing sinks.

Forces Frequency

When enabled, the simulation velocities in areas marked by the Force Mask Layer are driven towards the goal velocities contained in the incoming vel vector layer. Where Force Mask Layer is 0, no forces are applied. Larger values, up to 1, speed up the rate at which the simulation velocities match the goal values in vel.

Initialize Only copies the force mask and goal velocity fields at the start of the simulation and uses them throughout. This is the fastest option and should be used with a static force field. Once per Frame refreshes the simulation sink on the first substep of each frame; this should be used with changing force fields whenever possible. Every Substep is the slowest option, and should be avoided, except in special cases with very rapidly changing force fields.

Speed Limits

Max Wave Speed

When enabled, each component of velocity will be clamped against this value. This parameter can be used to stabilize the simulation, as well as to prevent unrealistically large velocity values.

Max Surface Speed

When enabled, the change in water depth is clamped against this value. This parameter can be used to stabilize the simulation, but can give rise to unphysical behavior.

Simulation

Voxel Size Scale

Controls resolution of the simulation. More precisely, this value acts as a multiplier on voxel size of the incoming height fields; their product forms the voxel size used for simulation. As such, larger values of this parameter correspond to lower resolutions.

Substeps

Each frame of the simulation is subdivided into this number of substeps when performing the solve. Larger values produce more accurate results, but take longer to run. If the simulation is unstable, Substeps need to be increased.

Global Substeps

Controls global substeps at the simulation level. Global Substeps are best used when you need to export the substepped geometry. They will use more memory per frame, but all substeps will be kept rather than just the final results for each frame.

Cache Memory (MB)

Controls whether or not the simulation is cached to memory. If turned on, the value represents the maximum size of the memory cache.

Output

Output Water Height Is Absolute

When this toggle is enabled, output Water Layer will contain location of the water surface. If this is turned off, then Water Layer will hold height of the water column at each voxel.

Output Terrain Includes Water Height

When enabled, output Seabed Layer will be adjusted to include the water (that is, Water Layer will be added to it).

Visualization

Controls visualization of the height fields in the viewport. If set to Unchanged, incoming visualization settings will be preserved. When this parameter is set to Color by Water Layer or Color by Height Layer, then the height fields will be tinted by values in the respective layer.

Visualize Range

Controls tinting of the height fields when Visualization is set to Color by Water Layer or Color by Height Layer. First value in this range is mapped to white, and the second value is mapped to blue.

Output Velocity (vel)

When enabled, the vel vector field will be exported by the solver. This field stores the flow velocities.

Output Acceleration (accel)

When enabled, the acceleration vector field (accel) will be exported by the solver. This field stores the Lagrangian accelerations–the change in velocity in the frame of the liquid.

Note

Toggling this parameter will invalidate the cache, since these accelerations need to be computed during the simulation.

Output Vorticity (vorticity)

The solver’s output will contain the vorticity layer when this option is enabled. Vorticity is curl of the velocity field, and it measures the amount of local spinning at every voxel.

Bindings

Seabed Layer

Name of the input layer containing the collision terrain.

Water Layer

Name of the water layer. This layer in the output contains the simulation results. If this layer exists in the input, it will be used as the initial state.

Source Layer

Name of the input layer containing water sources. You can use the Source Layer to inject new water into the simulation.

Sink Layer

Name of the input layer containing water sinks. You can use the Sink Layer to remove water from the simulation.

Force Mask Layer

Name of the input layer containing the force mask. Values of 0 in this layer mark places where no forces are applied. Larger values (up to 1) speed up the rate at which the simulation velocities match the goal velocities in the incoming vel vector field. You must enable Forces Frequency under Constraint Updates for force application to take place.

Note

If there is no incoming vel vector field, then 0 goal velocities will be used. This will act as a drag force that slows down the flow.

Examples

CanyonFlooding Example for Shallow Water Solver geometry node

This example contains a simulation network to flood canyon terrain using the shallow water solver.

ShallowWaterFountain Example for Shallow Water Solver geometry node

This is a simple example that uses the shallow water solver to fill a fountain.

Geometry nodes