Shallow Water Demo: Settings Guide

This page explains the various settings in the Shallow Water Demo and their meanings. It is intended as a reference guide.

"Presets" tab

Each button on this tab loads a preset "scenario" (group of predefined settings) for your convenience. These are:

• Valley: Creates a valley featuring a river channel and a dam. Water feeds into the valley from the top where it forms a small lake behind the dam. The dam has a small break in the middle, which creates a waterfall and allows water to drain down to the bottom of the valley. (One fun thing to do in this scenario is to go to "Terrain" and turn off the "Dam_On" setting. This removes the dam causing all the water to flow down to the bottom of the valley.)
• Valley (High Res): Like "Valley" but the simulation runs at a much higher resolution. This runs very slowly, since the resolution is a bit too high to run in real time on current hardware.
• Flat Plane: Just creates a simple flat landscape with a chunk of water placed in the centre of it initially. "Solid wall" boundary conditions are used meaning that wave patterns can reflect off the boundaries.
• Sea + Waves: An experimental setup consisting of a "beach" with wave patterns being generated at one end. (To be honest, this didn't work out as well as I had hoped.)

"Settings" tab

Contains general simulation and boundary condition settings.

• Mesh_Size_X and Mesh_Size_Y: Control the resolution (number of grid points) used in the simulation.
• Solid_Walls: If this is on, the "side" boundaries of the domain will be solid walls, so that water cannot escape and wave patterns will reflect off the walls. If off, the boundaries will be "open" so water will be able to leak out through the sides of the domain.
• Inflow_Width and Inflow_Height: These set the width and height of the "inflow" region at the top of the domain. Basically, setting these to large values will cause a lot of water to start pouring in to the domain from the "upper" boundary. Setting them to zero disables inflow.
• Gravity: Acceleration due to gravity in metres per second squared.
• Friction: Controls the friction between the water and the ground. (The simulation uses a very simple, and unrealistic, friction model currently.)
• Theta: This is a parameter used in the Kurganov-Petrova method. Lower values improve the simulation stability, but may be more diffusive.
• Max_CFL_Number: This controls the size of the simulation timesteps. Higher values will take bigger timesteps and therefore run faster, but using too high a value will make the simulation unstable.
• Timesteps_Per_Frame: This controls how many simulation timesteps will be taken between one graphics frame and the next. Using a higher number may improve simulation speed, but will cause the FPS to drop (because we are allocating more GPU time to simulation and less to rendering).
• Time_Acceleration: If set to a value greater than 1, then we will attempt to run the simulation faster than real-time. This only works if your computer is fast enough (which typically means you need a fairly low mesh size).
• Clip_Camera: If this is enabled the camera is kept within the "valley" area, otherwise it can move a short distance outside the valley for an "outside" view of the simulation.

"Terrain" tab

This controls the shape of the landscape.

• Valley_Length: The length of the simulation domain, in metres, in the Y direction.
• Valley_Width: The length of the simulation domain, in metres, in the X direction.
• Valley_Wall_Height: The difference in altitude between the "walls" of the valley (i.e. the "left" and "right" edges along the X direction) and its centre point.
• Gradient_Top and Gradient_Bottom: The rate at which the valley slopes downward (along the Y direction), at the top and bottom of the valley respectively.
• Valley_Shape: A number between 1, which represents a perfect V-shaped valley, and 4, which represents a more U-shaped valley.
• Channel_Depth_Top and Channel_Depth_Bottom: Controls the depth of the river channel which is carved through the centre of the valley. (This can be different at the top and bottom ends of the valley; the value is linearly interpolated between the two).
• Channel_Width_Top and Channel_Width_Bottom: Controls the width of the river channel.
• Dam_On: Click to enable or disable the "dam" feature.
• Dam_Height: Controls the height of the dam (in metres).
• Dam_Position: Sets the Y position of the dam (0 represents the bottom of the valley).
• Dam_Middle_Width and Dam_Middle_Height: Allows a break, or raised middle section, to be added to the dam.
• Dam_Thickness: Controls the "thickness" (i.e. length in the Y-direction) of the dam.
• Meander_Wavelength: Controls the wavelength of the "meander" in the river channel (in metres).
• Meander_Amplitude: The amplitude of the channel meander (in metres). Set to zero to make a straight river channel.
• Meander_Fractal: If set to a nonzero value, the river meander will not be a perfect sine wave but will instead be fractal in nature.

"Sea" tab

This was mostly an experiment. It allows a fixed "sea level" to be used, and sea waves to be generated.

• Use_Sea_Level: If enabled, the "south" boundary (Y=0) will become a "fixed water height" boundary condition.
• Sea_Level: This sets the height used in the "fixed water height" boundary condition (in metres).
• SAj, SKj, SKj_Dir, and SOj (where j = 1 to 4): These allow "sea waves" to be generated by perturbing the sea level as a function of time. Each set of waves (j=1 to 4) are considered independent and are added together. SA sets the wave amplitude, SK sets the wavenumber, SK_Dir allows the waves to be rotated to face different directions, and SO sets the frequency in Hz. Set all SA's to zero to disable the sea waves.

"Graphics" tab

This controls parameters for the rendering.

• FOV: Sets the camera field of view in degrees.
• Sun_Alt and Sun_Az: Sets the altitude and azimuth of the sun position (this affects the lighting of both the water and the terrain).
• Ambient: Sets the level of ambient lighting.
• Fresnel_Coeff and Fresnel_Exponent: Controls the Fresnel term for the water. The Fresnel term is approximated by the formula: F = (1 - Fc) + Fc * pow(max(0, 1 - dot(e, n)), Fe), where Fc is the value of Fresnel_Coeff and Fe is the value of Fresnel_Exponent.
• Specular_Intensity and Specular_Exponent: These control the specular lighting on the water.
• Refractive_Index: Sets the refractive index of the water.
• Attenuation_1 and Attenuation_2: Controls attenuation, i.e. the dimming of light rays that pass through the water. High attenuation levels will make the water "darker" and less clear. The formula for attenuation is: A = (1 - A1) * exp(-A2 * dist), where A1 and A2 are the values of the two attenuation settings, and dist is the distance the light ray has travelled through the water.
• Deep_R, Deep_G and Deep_B control the colour of the water. Basically, if the attenuation factor is very large, the water takes on the Deep_RGB colour, else it takes on the colour of the bottom texture underneath the water.

Left mouse settings

These control the functioning of the left mouse button.

• Left_Mouse_Action: Controls whether the left mouse button is used to add water, remove water, "stir" water (this removes water from directly under the mouse pointer, but adds it back again in a circle around the mouse pointer), raise terrain or lower terrain.
  • Please note that any changes made by using "raise/lower terrain" will be lost if you subsequently change any of the settings on the Terrain tab.
• Left_Mouse_Radius: Controls the radius of effect of the left mouse action.
• Left_Mouse_Strength: Controls the "strength" of the left mouse action (i.e. the rate at which water is added/removed, or the speed at which the terrain is raised/lowered).

Information displays

Below the Left Mouse settings there are a few real-time displays which give information about the current state of the simulation.

• Mass: Gives the total mass of water currently in the simulation, in kg. If all boundaries are closed (Solid_Walls is on, Use_Sea_Level is off and the Inflow settings are zero) then this should remain roughly constant during the simulation. (Otherwise, mass will vary since water is entering or leaving through the boundaries.)
• X_Momentum and Y_Momentum: The total momentum (in the X and Y directions) in kg m s^-1.
• Kinetic_Energy, Potential_Energy and Total_Energy: Give the kinetic, potential (gravitational) and total energy of the water in the simulation, in Joules. Assuming the mass is constant, then the total energy should slowly fall over time, due to friction.
• Max_Speed: The highest water speed currently in the simulation, in m s^-1.
• Max_Depth: The water depth at the deepest point, in m.
• Max_Froude_Number: The highest Froude number in the simulation. (The Froude number is defined as water speed divided by wave speed, where the wave speed is sqrt(g*h) with g = gravity and h = water depth.)
• FPS: The current Frames Per Second.
• Timestep: Current simulation timestep in seconds.
• CFL_Number: The current Courant-Friedrichs-Lewy number (this is the timestep divided by the minimum time for a wave to propagate across one grid cell).
• Time_Ratio: This tells you whether the simulation is running at real time or not. A value of 1 indicates real time, while a value of 0.25 (for example) means that we are running at one quarter of real time, i.e. every four seconds of wall clock time corresponds to one second of time in the simulation.
• X, Y, Z: These indicate the x, y and z coordinates of the point under the mouse cursor.
• Depth: Indicates the water depth at the point under the mouse cursor, in metres.
• U, V: Indicates the X- and Y-components of water velocity, in metres per second, at the point under the mouse cursor.
• Froude: Indicates the Froude number at the point under the mouse cursor.

Other buttons

• Reset Simulation: This removes all the water from the simulation, allowing you to "start from scratch". The settings will be left unchanged, however.
• Hide GUI: This hides the GUI allowing a better view of the simulation. A "Show GUI" button will be displayed allowing you to get back again.