API Reference

This section documents the main classes in the ANUGA public API. For a complete alphabetical index of all names exported by the anuga package see the Index.

The three classes below form the foundation of every ANUGA simulation:

Class	Role
`Domain`	The simulation domain — owns the mesh, quantities, operators, boundary conditions, and the evolve loop. This is the central object in any ANUGA script.
`Quantity`	Represents a single physical field (elevation, stage, friction, xmomentum, ymomentum) on the mesh. Accessed via `domain.quantities['stage']` etc. Provides methods for setting values, computing integrals, interpolation, and extrapolation.
`Region`	A spatial subset of the mesh defined by a polygon or list of triangle indices. Used to apply operators or set quantities over a specific area of the domain.

Domain

The Domain class is the top-level simulation object. A typical script:

Creates a Domain from a mesh (rectangular grid or unstructured mesh from create_domain_from_regions).
Sets initial conditions on its Quantity objects via domain.set_quantity().
Assigns boundary conditions to named boundary tags via domain.set_boundary().
Optionally attaches operators (rainfall, culverts, inlets).
Calls domain.evolve() to advance the simulation in time.

Domain

Object which encapulates the shallow water model

Full Domain API

Domain creation functions and the domain methods used throughout this guide:

`rectangular_cross_domain`	Create a rectangular domain.
`create_domain_from_regions`	Create domain from bounding polygons and resolutions.

Quantity

Quantity objects are created automatically by the Domain and are not usually instantiated directly. They are accessed via domain.quantities:

elev = domain.quantities['elevation']
print(elev.centroid_values)     # values at triangle centroids
print(elev.vertex_values)       # values at triangle vertices
print(elev.get_integral())      # integral over the domain

Each quantity allocates only the arrays it needs via the qty_type parameter ('evolved', 'centroid_only', 'edge_diagnostic', or 'coordinate'). Gradient and phi arrays are lazy for all types. See Memory layout (qty_type) for details.

Quantity

Class Quantity - Implements values at each triangular element

Full Quantity API

Region

A Region identifies a spatial subset of the mesh. It is typically created by passing a polygon to an operator or by calling domain.get_region(), and it provides the list of triangle indices that fall inside the polygon. Operators use regions to apply forcing (rainfall, extraction) only over a defined area.

import anuga

polygon = [[0, 0], [5, 0], [5, 5], [0, 5]]
region = anuga.Region(domain, polygon=polygon)
print(region.get_indices())    # triangle IDs inside the polygon

Region

Object which defines a region within the domain

Geo_reference

Geo_reference records the coordinate reference system (CRS) and local origin of an ANUGA domain. It supports WGS84 UTM zones (auto-computed EPSG), national grids such as RD New (EPSG:28992) or British National Grid (EPSG:27700), and arbitrary local systems for wavetank simulations.

geo_ref = anuga.Geo_reference(zone=55, hemisphere='southern',
                              xllcorner=363000.0, yllcorner=8132000.0)
geo_ref.epsg          # 32755  (auto-computed)
geo_ref.is_located()  # True

# Or supply EPSG directly (zone and hemisphere inferred for UTM codes):
geo_ref = anuga.Geo_reference(epsg=32755, xllcorner=363000.0, yllcorner=8132000.0)

# National grids work too:
geo_ref = anuga.Geo_reference(epsg=28992)   # Netherlands RD New

See Coordinate Reference Systems for full usage guidance.

Geo_reference

Coordinate reference system for an ANUGA domain.

Boundary conditions

The boundary classes assigned to named domain edges via domain.set_boundary(). See Setting up the Boundaries for a description of each and when to use it; the full API of each class is below.

`Reflective_boundary`	Reflective boundary condition.
`Dirichlet_boundary`	Dirichlet boundary returns constant values for the conserved quantities
`Time_boundary`	Time dependent boundary returns values for the conserved quantities as a function of time.
`Transmissive_n_momentum_zero_t_momentum_set_stage_boundary`	Transmissive normal momentum, zero tangential momentum, prescribed stage.
`Flather_external_stage_zero_velocity_boundary`	Weakly-reflecting open boundary using a Flather-type characteristic approach.
`File_boundary`	The File_boundary reads values for the conserved quantities from an sww NetCDF file, and returns interpolated values at the midpoints of each associated boundary segment.
`Field_boundary`	Boundary condition driven by an SWW field file with optional stage offset.
`Absorbing_wave_boundary`	Active-absorption open boundary with prescribed incoming wave.
`Characteristic_wave_boundary`	Nonlinear characteristic open boundary with prescribed incoming wave.

Operators

Operators modify domain quantities each timestep (rainfall/extraction, inlets, culverts, setting quantities, viscosity). See Operators for categories and usage; the full API of each is below.

`Rate_operator`
`Inlet_operator`	Inlet Operator - add water to an inlet.
`Set_quantity_operator`	Set the elevation in a region (careful to maintain continuitiy of elevation)
`Set_stage_operator`	Set the stage over a region, enforcing stage >= elevation.
`Set_elevation_operator`
`Boyd_box_operator`	Culvert flow - transfer water from one rectangular box to another.
`Boyd_pipe_operator`	Culvert flow - transfer water from one location to another via a circular pipe culvert.
`Weir_orifice_trapezoid_operator`	Culvert flow - transfer water from one trapezoidal section to another.
`Internal_boundary_operator`	Internal boundary operator driven by a user-supplied discharge function.
`Kinematic_viscosity_operator`	Class for setting up structures and matrices for kinematic viscosity differential operator using centroid values.

Logging

Configuring ANUGA’s log output. See Logging for usage.

`set_logfile`	Enable logging to path, tee-ing all print() output as well.
`utilities.log.TeeStream`	Tee sys.stdout to a file: every write goes to both terminal and file.
`utilities.log.file_only`	Context manager: send all print() output to the log file only.
`utilities.log.verbose`	Log a verbose/internal message — goes to file only (not screen).
`utilities.log.info`	Log an INFO-level message (terminal and file).
`utilities.log.warning`	Log a WARNING-level message (terminal and file).
`utilities.log.debug`	Log a DEBUG-level message (file only by default).
`utilities.log.critical`	Log a CRITICAL-level message (terminal and file).

File format reference

Reference documentation for all file formats read and written by ANUGA — SWW, STS, TMS, mesh files (TSH/MSH), DEM formats, and point data.

File format reference

Validation test suite

Description of the validation tests in validation_tests/, how to run them, and what physical benchmarks they cover.

Validation test suite