GRASS logo

NAME

r.hydro.anuga - Simulates overland flow and flooding with ANUGA's shallow-water solver on a multi-resolution mesh, accelerated with OpenCL.

KEYWORDS

raster, hydrology, flood, shallow water, ANUGA, OpenCL, GPU

SYNOPSIS

r.hydro.anuga
r.hydro.anuga --help
r.hydro.anuga [-poifndmk] elevation=name[,name,...] [domain=name] [dem_offset=float[,float,...]] [dem_bias_tolerance=float] [blend_width=float] [res_min=float] [res_max=float] [fringe=integer] [refine=name] [refine_res=float] [coarsen=name] [relief_tolerance=float] [max_triangles=float] [manning=name] [manning_value=float] [landcover=name] [manning_rules=name] [buildings=name] [building_height=float] [initial_depth=name] [initial_stage=name] [initial_xmom=name] [initial_ymom=name] [infiltration=string] [soil_texture=name] [soil_table=name] [soil_horizon=string] [ks=name] [suction=name] [porosity=name] [initial_saturation=string] [soil_depth=name] [impervious=name] [infil_substep=float] [rain=name] [rain_strds=name] [rain_value=float] [rain_hyetograph=name] [rain_units=string] [evap=name] [evap_strds=name] [evap_units=string] [wind_u_strds=name] [wind_v_strds=name] [pressure_strds=name] [pressure_units=string] [inflow=name] [inflow_series=name] [boundary=side:type[:value][,side:type[:value],...]] [stage_series=name] [start=string] [end=string] [duration=float] [output_step=float] [max_timestep=float] [min_timestep=float] [cfl=float] [algorithm=string] [friction_method=string] [output=string] [outputs=string[,string,...]] [min_depth=float] [max_depth=name] [max_speed=name] [max_stage=name] [max_hazard=name] [arrival_time=name] [arrival_depth=float] [inundation_duration=name] [final_prefix=string] [mesh_level=name] [mesh_output=name] [state_output=name] [gauges=name] [gauge_output=name] [gauge_step=float] [massbalance=name] [device=string] [nprocs=integer] format=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-p
Print device, mesh levels and memory estimate, then exit
-o
Use the elevation maps in the given priority order instead of finest first
-i
Place the resolution fringe inside fine DEM footprints
-f
Also write fine-resolution outputs over fine DEM footprints
-n
Write dry cells as NULL instead of 0
-d
Write DCELL instead of FCELL outputs
-m
Print the mass balance error at the end
-k
Values of ks= are in mm/h instead of m/s
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

elevation=name[,name,...] [required]
One or more DEMs; the mesh uses the finest DEM available at each location
domain=name
Raster map defining the active domain (non-NULL cells)
Name of input raster map
dem_offset=float[,float,...]
Explicit vertical offset per DEM (m), added to its values
dem_bias_tolerance=float
Maximum allowed median vertical difference between overlapping DEMs (m)
Default: 0.5
blend_width=float
Width of the seam blending zone, in coarse DEM cells
Default: 2
res_min=float
Finest mesh cell size (default: finest DEM resolution)
res_max=float
Coarsest mesh cell size, snapped to res_min*2^L (default: coarsest DEM resolution)
fringe=integer
Minimum number of cells of each level between level changes
Default: 4
refine=name
Raster map of areas to refine to refine_res
Name of input raster map
refine_res=float
Target cell size inside refine areas
coarsen=name
Raster map of areas where the mesh may stay coarser than the DEM (value = cell size)
Name of input raster map
relief_tolerance=float
Coarsen cells whose sub-cell relief is below this value (m)
max_triangles=float
Fail if the mesh would exceed this number of triangles
manning=name
Raster map of Manning's n
Name of input raster map
manning_value=float
Constant Manning's n
Default: 0.03
landcover=name
Land cover raster map (with manning_rules)
Name of input raster map
manning_rules=name
File with 'class n' lines mapping land cover to Manning's n
Name of input file
buildings=name
Raster map of building footprints
Name of input raster map
building_height=float
Height added to elevation under buildings (m)
Default: 10
initial_depth=name
Raster map of initial water depth (m)
Name of input raster map
initial_stage=name
Raster map of initial water surface (m)
Name of input raster map
initial_xmom=name
Raster map of initial x momentum (m2/s)
Name of input raster map
initial_ymom=name
Raster map of initial y momentum (m2/s)
Name of input raster map
infiltration=string
Infiltration model
Options: none, ga, gar
Default: none
none: No infiltration
ga: Green-Ampt with ponded head, Rawls et al. (1983) parameters
gar: Green-Ampt with redistribution, Ogden and Saghafian (1997)
soil_texture=name
Raster map of USDA soil texture classes 1-11
Name of input raster map
soil_table=name
CSV soil parameter table overriding the built-in one
Name of input file
soil_horizon=string
Soil horizon rows of Rawls et al. (1983) Table 2
Options: all, A, B, C
Default: all
ks=name
Raster map of saturated hydraulic conductivity (m/s)
Name of input raster map
suction=name
Raster map of wetting front suction head (m)
Name of input raster map
porosity=name
Raster map of effective porosity
Name of input raster map
initial_saturation=string
Initial effective saturation 0-1 (value or raster)
Default: 0
soil_depth=name
Raster map of depth to an impervious layer (m)
Name of input raster map
impervious=name
Raster map of impervious fraction 0-1
Name of input raster map
infil_substep=float
Soil water update interval for GAR (seconds)
Default: 30
rain=name
Raster map of rainfall rate
Name of input raster map
rain_strds=name
Space-time raster dataset of rainfall
Name of the input space time raster dataset
rain_value=float
Constant, spatially uniform rainfall rate
rain_hyetograph=name
CSV file of 'seconds,rate' for spatially uniform rainfall
Name of input file
rain_units=string
Units of the rainfall input
Options: mm/h, mm/d, m/s
evap=name
Raster map of (potential) evaporation rate
Name of input raster map
evap_strds=name
Space-time raster dataset of evaporation
Name of the input space time raster dataset
evap_units=string
Units of the evaporation input
Options: mm/h, mm/d, m/s
wind_u_strds=name
Space-time raster dataset of 10 m U wind (m/s)
Name of the input space time raster dataset
wind_v_strds=name
Space-time raster dataset of 10 m V wind (m/s)
Name of the input space time raster dataset
pressure_strds=name
Space-time raster dataset of surface pressure
Name of the input space time raster dataset
pressure_units=string
Units of the pressure input
Options: Pa, kPa
inflow=name
Vector points of inflow locations
Or data source for direct OGR access
inflow_series=name
CSV file of 'seconds,cat,discharge' inflow hydrographs (m3/s)
Name of input file
boundary=side:type[:value][,side:type[:value],...]
Boundary condition per side, side:type[:value]
Default: north:reflective,south:reflective,east:reflective,west:reflective,null:reflective
stage_series=name
CSV file of 'seconds,stage' for stage/flather boundaries
Name of input file
start=string
Start date and time (ISO 8601; default: first forcing map)
end=string
End date and time (ISO 8601)
duration=float
Simulated duration (seconds)
output_step=float
Interval between outputs (seconds)
Default: 3600
max_timestep=float
Maximum time step (seconds)
min_timestep=float
Minimum time step before a stall is reported (s)
cfl=float
CFL number (default: DE0 0.9, DE1 0.5, DE2 1.0)
algorithm=string
ANUGA flow algorithm
Options: DE0, DE1, DE2
Default: DE1
DE0: Euler, CFL 0.9, beta 0.5
DE1: Runge-Kutta 2, CFL 1.0, beta 1.0
DE2: Runge-Kutta 3
friction_method=string
Manning friction formulation
Options: flat, sloped
Default: flat
output=string
Base name for output space-time raster datasets
outputs=string[,string,...]
Quantities written as time series
Options: depth, stage, xvelocity, yvelocity, speed, direction, discharge, xmomentum, ymomentum, froude, hazard, infiltration
Default: depth
min_depth=float
Depths below this are written as dry (m)
Default: 0.001
max_depth=name
Maximum depth
Name for output raster map
max_speed=name
Maximum speed
Name for output raster map
max_stage=name
Maximum stage
Name for output raster map
max_hazard=name
Maximum hazard rating
Name for output raster map
arrival_time=name
Time water first exceeds arrival_depth (s)
Name for output raster map
arrival_depth=float
Depth threshold for arrival and duration (m)
Default: 0.05
inundation_duration=name
Total time with depth above arrival_depth (s)
Name for output raster map
final_prefix=string
Prefix for final state rasters (stage, xmom, ymom) for hot start
mesh_level=name
Quadtree level used at each cell
Name for output raster map
mesh_output=name
Directory to export the mesh and scaled elevation to
Name for output file
state_output=name
Directory to export the initial and final solver state to
Raw centroid arrays and the time step log, for validation
gauges=name
Vector points where time series are recorded
Or data source for direct OGR access
gauge_output=name
CSV file for gauge time series
Name for output file
gauge_step=float
Interval between gauge records (s)
Default: 60
massbalance=name
CSV file for the mass balance report
Name for output file
device=string
Compute backend
Options: auto, gpu, cpu, omp
Default: auto
auto: GPU, then CPU OpenCL, then OpenMP
gpu: OpenCL GPU with double precision
cpu: OpenCL CPU device (e.g. PoCL)
omp: OpenMP, no OpenCL
nprocs=integer
Number of threads for parallel computing
0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
Default: 0
format=name [required]
Output format
Options: plain, shell
Default: plain
plain: Human readable text
shell: shell script style key=value

Table of contents

DESCRIPTION

r.hydro.anuga simulates overland flow and flooding with the shallow-water solver of ANUGA, the discontinuous-elevation (DE) finite-volume scheme on triangles. It runs in OpenCL on a GPU (or on a CPU OpenCL device such as PoCL), with a plain OpenMP fallback.

The mesh is built directly from one or more DEMs given in elevation. At each location it uses the finest DEM available, for example IGN LiDAR HD or RGE ALTI at 0.5-1 m inside a village and a 30 m DEM around it. Resolution levels are powers of two between res_min and res_max. The transition between levels is graded over fringe cells per level. Every square cell is split into triangles fanned from its centre: 4 triangles (the ANUGA rectangular_cross pattern), or up to 8 next to a finer neighbour, which keeps the mesh conforming.

Forcing can be constant, a raster map, or a space-time raster dataset. The latter covers ERA5 rainfall, evaporation, wind and pressure imported with t.in.era5. Units are always given explicitly (rain_units, evap_units, pressure_units); the module never guesses them. Infiltration uses Green-Ampt with ponded head (infiltration=ga, Rawls et al. 1983 parameters), or Green-Ampt with redistribution between storms (infiltration=gar, Ogden and Saghafian 1997).

Outputs are space-time raster datasets of depth and, on request, stage, velocity, speed, direction, unit discharge, Froude number, hazard rating and cumulative infiltration. The module can also write rasters of maximum depth, speed, stage and hazard, arrival time, inundation duration, the mesh level, gauge time series and a mass balance report.

Development status: phases 0 to 5 of the implementation plan (PLAN.md) are complete. The -p pre-flight report selects the compute device, describes the DEM stack at native resolution, snaps the resolution levels, and estimates the number of triangles and the device memory. Meshes are built from one or several DEMs at different resolutions. The solver runs on the selected OpenCL device or with OpenMP, and its results are bitwise identical to ANUGA's own C kernels (OpenMP; OpenCL too when there is no friction). Raster time series, summary rasters, detail outputs and the mass balance table are written as described below.

Rainfall, evaporation, wind and pressure forcing, inflows, stage boundaries, infiltration, gauges, end, min_timestep, coarsen and relief_tolerance are not implemented yet (PLAN.md, phases 6 to 9). Their options are defined so that -p can estimate the memory of a complete run, but a simulation given any of them stops with an error instead of ignoring it.

NOTES

Compute device

With device=auto, the first GPU with double precision support (cl_khr_fp64) is used, then a CPU OpenCL device, then OpenMP. Devices are chosen by capability, not by platform order. Each candidate must build a small double precision OpenCL C 1.1 probe kernel. For example, with Mesa, the rusticl platform may expose a GPU without double precision next to the Clover platform exposing the same GPU with it; the Clover device is selected. device=gpu or cpu fail if no such device exists, rather than falling back silently.

The solver runs on the selected device. OpenCL guarantees correctly rounded double arithmetic and square roots, so the OpenCL and OpenMP solvers give bitwise identical results without friction. Manning friction uses a power function whose OpenCL accuracy is a few units in the last place, so results then differ at the 1e-15 relative level.

Resolution levels

res_min defaults to the finest DEM resolution. res_max defaults to the coarsest, rounded up to res_min times a power of two, and the rounding is reported: 1 m and 30 m DEMs give levels of 1, 2, 4, 8, 16 and 32 m. The current region must be a whole number of res_max cells. Otherwise the module stops and prints an aligned g.region command. DEMs must have square cells. Latitude-longitude projects are not supported.

Several DEMs

When elevation lists several DEMs, each is read at its own resolution. At each location the finest DEM with data governs the elevation (with -o, the order given is the priority order). Its resolution sets the mesh level there. res_min coarsens the finest level if needed.

Around each finer area the mesh steps down one level at a time, with at least fringe cells of every intermediate level. For example, 2 m cells are surrounded by bands of 4, 8 and 16 m cells before reaching 32 m. Neighbouring cells always differ by at most one level. A cell next to a finer neighbour is split into 5 to 8 triangles instead of 4, so the mesh stays conforming.

refine (with refine_res) requests a finer resolution over any other area, such as a channel or a dike.

Before meshing, each DEM is compared with the next coarser one where they overlap. If the median vertical difference exceeds dem_bias_tolerance (default 0.5 m), the module stops and reports it. Mixing vertical datums (for example NGF-IGN69 altitudes and EGM2008 geoid heights) is a common cause. The difference is never corrected silently: give dem_offset (one value per map of elevation, in the same order) to apply a correction explicitly. Within tolerance, the seam is blended smoothly over blend_width cells of the coarser DEM, inside the finer DEM's footprint. Region edges are not treated as seams.

With -f, every output (time series, summary rasters and final state) is also written on a detail grid over each finer DEM's footprint, at that DEM's mesh resolution. The names get the suffix _detail1, _detail2, and so on.

Mesh-only mode

With mesh_output and/or mesh_level but no output, the module builds the mesh and exits. mesh_level is a raster of the mesh level of each cell of the current region (0 is the coarsest, NULL outside the domain). mesh_output is a directory with manifest.json and one raw binary file per array (node coordinates and elevations, triangles, geometry, neighbours, boundary edges and tags, fp64 and scaled centroid bed). Coordinates are relative to the origin given in the manifest. Arrays follow ANUGA's conventions, so they can be loaded into anuga.Domain directly. For a single DEM without NULL cells, the mesh is identical, bit for bit, to anuga.rectangular_cross (see validation/compare_mesh_anuga.py).

Leaves are active where the DEM has valid cells and, if domain is given, where the leaf centre lies inside the domain. Mesh edges facing an inactive cell carry the boundary tag null; edges on the region edge are tagged north, south, east or west. Node elevations are bilinear between DEM cell centres at leaf corners and the mean of the DEM cells inside the leaf at leaf centres. The triangle bed is the mean of its three vertices.

Solver runs

With state_output and duration (seconds), the module runs the solver and writes a directory with manifest.json and raw arrays: the initial and final centroid stage and momenta, bed, friction, boundary setup, and the time of every step. The manifest holds the mass budget: water volume (positive depths only, as ANUGA reports it, and signed), the integrated boundary flux, and the water added by clamping negative depths. The change of the signed volume equals the boundary flux plus the clamping mass.

algorithm selects ANUGA's DE0 (Euler), DE1 (second-order Runge-Kutta, default) or DE2 (third-order Runge-Kutta) parameter sets. The default CFL numbers are 0.9 (DE0), 0.5 (DE1; ANUGA uses 1.0) and 1.0 (DE2); cfl overrides them. max_timestep caps the time step (default 1000 s, as ANUGA). friction_method is flat (default, as ANUGA) or sloped. boundary sets each side (north, south, east, west, or null for edges facing NULL or masked-out cells) to reflective (default), transmissive or dirichlet:stage[:xmom:ymom]. initial_depth or initial_stage give the initial water; manning or manning_value give Manning's n.

For thin water films on coarse, steep terrain (typical of rain-on-grid), DE1 and DE2 at a CFL of 1 can drive depths negative often; clamping them adds water. This is why DE1 defaults to a CFL of 0.5. The added amount is reported, with a warning above 1% of the initial volume; a lower cfl or DE0 reduces it further. ANUGA behaves identically at the same settings.

Outputs

Output rasters are written on the current region. A region cell at least as large as the mesh cells takes the area-weighted mean of the triangles it contains, so Σ depth × cell area equals the simulated water volume. A finer cell takes the value of the triangle containing its centre. Velocities are momentum-weighted (Σ uh / Σ h). Cells outside the domain are NULL.

With output, each quantity listed in outputs (default depth) is written at t = 0, every output_step seconds and at the end, as maps <output>_<quantity>_<index>. They are registered in a space-time raster dataset <output>_<quantity> with a colour table. With start, times are absolute from that date; otherwise they are relative, in seconds. output_step must then be a whole number of seconds. The quantities are:

Cells shallower than min_depth are dry: depth, velocities and derived quantities are written as 0, or as NULL with -n. -d writes DCELL instead of FCELL maps.

The summary rasters use statistics updated on the compute device at every time step, not only at output times:

Speed is zeroed where the depth is at most min_depth, following ANUGA's maximum-quantities operator, whose threshold defaults to 1e-5 m.

massbalance writes a CSV table with one line per output time:

-m prints the final mass error. Output names are checked before the simulation starts, and existing maps are only replaced with --overwrite.

Elevation precision

On the compute device, elevation is stored as unsigned 32-bit integers in units of 0.1 mm above an integer datum, and converted back exactly. The CPU and GPU paths therefore see bitwise identical terrain. Water levels and velocities remain in double precision.

EXAMPLES

Pre-flight report for a 1 m RGE ALTI tile over a 30 m Copernicus DEM, restricted to a watershed mask:

g.region n=6780000 s=6728992 e=282016 w=230976 res=32
r.hydro.anuga -p elevation=rgealti_1m,dem_glo30 domain=anuga_domain

Dam break in a closed channel, 60 s, with the solver state written out:

g.region n=200 s=0 e=1000 w=0 res=10
r.mapcalc "dem = 0"
r.mapcalc "h0 = if(x() < 500, 2.0, 0.5)"
r.hydro.anuga elevation=dem initial_depth=h0 duration=60 output_step=30 \
    state_output=/tmp/dam_break

Dam break with time series of depth and speed from a given date, peak maps and a mass balance table:

g.region n=200 s=0 e=1000 w=0 res=10
r.mapcalc "dem = -0.002 * x()"
r.mapcalc "h0 = if(x() < 400, 2.0, 0.0)"
r.hydro.anuga elevation=dem initial_depth=h0 duration=600 output_step=60 \
    start="2026-01-15 06:00" output=flood outputs=depth,speed \
    max_depth=flood_max_depth arrival_time=flood_arrival \
    boundary=west:dirichlet:2.5,east:transmissive massbalance=flood.csv
t.rast.list flood_depth

The same report as key=value pairs, for scripts:

r.hydro.anuga -p elevation=rgealti_1m,dem_glo30 domain=anuga_domain format=shell

Build the mesh of a watershed from a 30 m DEM and map it:

g.region raster=dem_glo30
r.hydro.anuga elevation=dem_glo30 domain=anuga_domain \
    mesh_level=mesh_level mesh_output=/tmp/plumergat_mesh

REFERENCES

SEE ALSO

r.hydro.hbv, r.hydro.rri, r.sim.water, r.watershed.opencl, t.in.era5, t.rast.list

AUTHORS

Yann Chemin. The shallow-water numerics are derived from ANUGA (Copyright 2004-2015 Australian National University and Geoscience Australia, Apache License 2.0). This addon was developed with AI assistance (Claude); see PLAN.md.

SOURCE CODE

Available at: r.hydro.anuga source code (history)

Accessed: Sunday Nov 15 11:07:31 2026


Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual