Creating a Domain

The first step in running an ANUGA model is to create a domain. This is done by creating a mesh and then creating a domain from that mesh.

rectangular_cross_domain

The domain (mesh) can be created in a number of ways. The simplest way is to create a simple rectangular domain using the rectangular_cross_domain() function.

For instance the following code creates a 1m by 1m rectangular domain, with a 10 by 10 mesh, with the bottom left corner at (0,0).

domain = anuga.rectangular_cross_domain(10, 10)

See the rectangular_cross_domain() API for the full argument list, and the Simple Script Example or Simple Notebook Example for worked examples.

create_domain_from_regions

The usual method for creating a domain for practical problems is to create a domain by defining a boundary polygon and then a set of regions within the domain to define area of different refinement levels and holes in the domain. This is done using the create_domain_from_regions() function.

The regions are defined by a list of polygons. Each polygon is defined by a list of points. The most important polygon is the boundary polygon. This is the outer polygon that defines the boundary of the domain. The segments of the boundary need to be tagged with boundary tags which will allow different boundary conditions to be applied to different segments.

Other polygons are the interior polygons that define the regions within the domain. These other polygons can be used to define regions with different refinement levels and holes in the domain.

The following example creates a domain with a rectangular boundary 20m by 10m with boundary tags on the 4 sides of the rectangle, and the mesh having a maximum triangle area of 0.2 m^2.

import anuga

bounding_polygon = [[0.0, 0.0],
                 [20.0, 0.0],
                 [20.0, 10.0],
                 [0.0, 10.0]]

boundary_tags={'bottom': [0],
             'right': [1],
             'top': [2],
             'left': [3]}

domain = anuga.create_domain_from_regions(bounding_polygon,
                            boundary_tags,
                            maximum_triangle_area = 0.2,
                            )

See the create_domain_from_regions() API for the full argument list, and the Simple Example using Create from Regions for a worked example.

Resolution from a size field

Each polygon in interior_regions becomes part of the mesh: its outline is a ring of segments that the triangulation honours exactly. That is what you want when the outline is a physical feature. Often it is not. A region such as “below 12 m elevation” or “within 500 m of the town” only says where the mesh should be fine, and its outline can do harm: a sharp corner, or two outlines passing close to each other, forces very small triangles, and since ANUGA steps at the smallest radii / wave speed in the mesh, a single such triangle sets the timestep of the whole run.

A size field gives the resolution without adding any segments. It is the maximum triangle area as a function of position, and a triangle is refined whenever its area exceeds the field at its centroid. size_field_from_regions() builds one from the same (polygon, maximum area) list that interior_regions takes:

town = [[8.0, 3.0], [12.0, 3.0], [12.0, 7.0], [8.0, 7.0]]

field = anuga.size_field_from_regions(bounding_polygon,
                            [(town, 0.01)],
                            maximum_triangle_area = 0.2)

domain = anuga.create_domain_from_regions(bounding_polygon,
                            boundary_tags,
                            maximum_triangle_area = 0.2,
                            size_field = field,
                            relax_passes = 30)

The polygons given to size_field_from_regions() may touch, overlap (the finest wins), have sharp corners or extend beyond the bounding polygon. The field is graded: the target edge length holds inside each polygon and grows away from it by grade metres per metre (0.5 by default), so the mesh coarsens smoothly instead of stepping at the outline.

size_field can also be a Size_field built from your own raster of target areas, or any function f(x, y) returning the maximum area at absolute coordinates x, y. A function is called a few times for every triangle in the mesh, so for a large mesh rasterise it into a Size_field. Because the field is only looked at where triangle centroids fall, it should vary smoothly.

A size field works together with the other arguments. Use breaklines and interior_holes for features that must be in the mesh, and interior_regions where the outline is physical; a triangle is refined if either its region’s maximum area or the field calls for it. The field needs the meshpy triangulation backend.

relax_passes is independent of the size field and can be used with any mesh. Triangulation bounds the largest triangle and the smallest angle, but not the smallest triangle, and leaves a few cells much smaller than the rest. Relaxation moves the vertices of those cells, for up to the given number of passes, to enlarge them. Vertices on the boundary, on breaklines and on region outlines do not move, and no triangles are added or removed. On meshes of 0.5 to 4 million triangles built from a size field it has roughly doubled the smallest radii, and with it the timestep.

See also

Choosing a Flow Algorithm

How to choose between DE0, DE1, DE_ader2, and DE2 — trade-offs between cost, accuracy, and robustness.

Coordinate Reference Systems

How to attach a coordinate reference system (UTM zone, national grid, or arbitrary local CRS) to a domain via Geo_reference.

ANUGA User Manual — Chapter 7: The Domain

Covers domain construction in depth, including mesh generation from polygon regions, geo-referencing, flow algorithm choices, and domain attributes.

See also

Domain — full API of the domain-creation functions (rectangular_cross_domain, create_domain_from_regions) and the Domain methods.