Setting up the Boundaries

Boundaries are an important part of the ANUGA model. They are used to set the boundary conditions for the model.

To set up the boundaries you first need to create boundary objects. These boundary objects are then assigned to the edges of the domain using the set_boundary method of the Domain class.

For example, to set up reflective boundaries on all sides of a rectangular domain, you would do the following:

from anuga import Domain, Reflective_boundary

# Create a rectangular domain
domain = Domain(...)

# Create a reflective boundary object
Br = Reflective_boundary(domain)

# Set the boundaries of the domain
domain.set_boundary({'left': Br, 'right': Br, 'top': Br, 'bottom': Br})

Standard Boundary Types

Class	Description
Reflective_boundary	Returns the same conserved quantities as the neighbouring interior triangle but with the normal momentum negated, so that no mass crosses the boundary (a “wall”). Suitable for closed edges such as coastlines and levees.
Dirichlet_boundary	Holds stage and momenta at fixed, constant values for the full simulation. Useful for specifying a steady inflow or maintaining a constant water level on an open boundary.
Time_boundary	Like Dirichlet_boundary but the conserved quantities are specified as a Python function of simulation time t. Use this when you want a time-varying stage or discharge that you can express as a formula (e.g. a tide signal or a gate opening schedule).
Transmissive_n_momentum_zero_t_momentum_set_stage_boundary	Sets the stage from a user-supplied function of time, transmits the normal momentum from the adjacent interior cell, and zeros the tangential momentum. Approximates a weakly-reflective open boundary where the outgoing signal can leave with minimal reflection.
Flather_external_stage_zero_velocity_boundary	Implements a Flather-type radiation condition (Blayo & Debreu 2005): the external stage is set by a function of time and the external velocity is zero, but the boundary flux is blended with the interior state using characteristic-like variables. Useful as a weakly reflecting open-ocean boundary where the stage should be approximately specified but outgoing waves are allowed to leave.
File_boundary	Reads stage and momentum time series from an SWW file and interpolates them spatially to each boundary midpoint and linearly in time. Used to nest a fine-resolution domain inside a coarser simulation.
Field_boundary	A thin wrapper around File_boundary that additionally applies a mean_stage offset to the stage read from the SWW file. Useful when you want to re-use one boundary SWW file across multiple tide scenarios without regenerating the file.

Usage examples

Reflective boundary (closed wall)

import anuga

Br = anuga.Reflective_boundary(domain)
domain.set_boundary({'left': Br, 'right': Br, 'top': Br, 'bottom': Br})

Dirichlet boundary (fixed values)

import anuga

# stage = 0.5 m, xmomentum = 0, ymomentum = 0
Bd = anuga.Dirichlet_boundary([0.5, 0.0, 0.0])
Br = anuga.Reflective_boundary(domain)
domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br})

Time boundary (time-varying stage)

import anuga
import math

def tide(t):
    """Sinusoidal tide with 12-hour period and 1 m amplitude."""
    return [math.sin(2 * math.pi * t / 43200.0), 0.0, 0.0]

Bt = anuga.Time_boundary(domain, function=tide)
domain.set_boundary({'ocean': Bt, 'land': anuga.Reflective_boundary(domain)})

File boundary (nesting from an SWW file)

import anuga

Bf = anuga.File_boundary('coarse_run.sww', domain)
Br = anuga.Reflective_boundary(domain)
domain.set_boundary({'ocean': Bf, 'land': Br})

Field boundary (SWW file with tide offset)

import anuga

# Reuse an SWW file generated at mean sea level; add 0.8 m for high tide
Bff = anuga.Field_boundary('boundary_msl.sww', domain, mean_stage=0.8)
domain.set_boundary({'ocean': Bff, 'land': anuga.Reflective_boundary(domain)})

Flather boundary (weakly reflecting open ocean)

import anuga

sea_level = 0.0

def waveform(t):
    return sea_level + 0.5 / math.cosh(t - 25.0) ** 2

Bfl = anuga.Flather_external_stage_zero_velocity_boundary(domain, waveform)
domain.set_boundary({'ocean': Bfl, 'land': anuga.Reflective_boundary(domain)})

See also

ANUGA User Manual — Chapter 9: Boundary Conditions and set_boundary gives extended examples of each boundary type, discusses time-varying stage specifications in detail, and explains how to diagnose common boundary-tag errors.

Reference

class anuga.Reflective_boundary(domain=None)

Reflective boundary condition object

Reflective boundary returns same conserved quantities as those present in its neighbour volume but with normal momentum negated so the mass flux is zero.

class anuga.Dirichlet_boundary(dirichlet_values=None)

Dirichlet boundary returns constant values for the conserved quantities

class anuga.Time_boundary(domain=None, function=None, default_boundary=None, verbose=False)

Time dependent boundary returns values for the conserved quantities as a function of time. Must specify domain to get access to model time and a function of t which must return conserved quantities as a function time.

Example:

B = Time_boundary(domain,

function=lambda t: [(60<t<3660)*2, 0, 0])

This will produce a boundary condition with is a 2m high square wave starting 60 seconds into the simulation and lasting one hour. Momentum applied will be 0 at all times.

class anuga.Transmissive_n_momentum_zero_t_momentum_set_stage_boundary(domain=None, function=None, default_boundary=0.0)

Bounday condition object that returns transmissive normal momentum and sets stage

Returns the same normal momentum as that present in neighbour volume edge. Zero out the tangential momentum. Sets stage by specifying a function f of time which may either be a vector function or a scalar function

class anuga.Flather_external_stage_zero_velocity_boundary(domain=None, function=None)

Boundary condition based on a Flather type approach

Setting the external stage with a function, and a zero external velocity,

The idea is similar (but not identical) to that described on page 239 of the following article:

Article{blayo05,
Title       = {Revisiting open boundary conditions from the point of view of characteristic variables},
Author      = {Blayo, E. and Debreu, L.},
Journal     = {Ocean Modelling},
Year        = {2005},
Pages       = {231-252},
Volume      = {9},
}

Approach

1. The external (outside boundary) stage is set with a function, the external velocity is zero, the internal stage and velocity are taken from the domain values.

2. Some ‘characteristic like’ variables are computed, depending on whether the flow is incoming or outgoing. See Blayo and Debreu (2005)

3. The boundary conserved quantities are computed from these characteristic like variables

This has been useful as a ‘weakly reflecting’ boundary when the stage should be approximately specified but allowed to adapt to outgoing waves.

class anuga.File_boundary(filename, domain, time_thinning=1, time_limit=None, boundary_polygon=None, default_boundary=None, use_cache=False, verbose=False)

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. Time dependency is interpolated linearly.

Assumes that file contains a time series and possibly also spatial info. See docstring for File_function in util.py for details about admissible file formats

File boundary must read and interpolate from smoothed version as stored in sww and cannot work with the discontinuous triangles.

Example: Bf = File_boundary(‘source_file.sww’, domain)

Note that the resulting solution history is not exactly the same as if the models were coupled as there is no feedback into the source model.

Optional keyword argument default_boundary must be either None or an instance of class descending from class Boundary. This will be used in case model time exceeds that available in the underlying data.

class anuga.Field_boundary(filename, domain, mean_stage=0.0, time_thinning=1, time_limit=None, boundary_polygon=None, default_boundary=None, use_cache=False, verbose=False)

Set boundary from given field.

Given field is represented in an sww file containing values for stage, xmomentum and ymomentum.

Optionally, the user can specify mean_stage to offset the stage provided in the sww file.

This function is a thin wrapper around the generic File_boundary. The difference between the File_boundary and Field_boundary is only that the Field_boundary will allow you to change the level of the stage height when you read in the boundary condition. This is very useful when running different tide heights in the same area as you need only to convert one boundary condition to a SWW file, ideally for tide height of 0 m (saving disk space). Then you can use Field_boundary to read this SWW file and change the stage height (tide) on the fly depending on the scenario.