Changeset 7134


Ignore:
Timestamp:
May 29, 2009, 3:45:23 PM (16 years ago)
Author:
rwilson
Message:

Major wide-spread changes to the user manual.

Location:
anuga_core/documentation/user_manual
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • anuga_core/documentation/user_manual/anuga_user_manual.tex

    r7124 r7134  
    216216regions using symbolic tags.  These tags may then be used to set the
    217217actual boundary conditions and attributes for different regions
    218 (e.g.\ the Manning friction coefficient) for each simulation.
     218(e.g. the Manning friction coefficient) for each simulation.
    219219
    220220Most \anuga components are written in the object-oriented programming
     
    237237  \item The mathematical model is the 2D shallow water wave equation.
    238238  As such it cannot resolve vertical convection and consequently not breaking
    239   waves or 3D turbulence (e.g.\ vorticity).
     239  waves or 3D turbulence (e.g. vorticity).
    240240  %\item The surface is assumed to be open, e.g. \anuga cannot model
    241241  %flow under ceilings or in pipes
     
    251251  \item Frictional resistance is implemented using Manning's formula, but
    252252  \anuga has not yet been fully validated in regard to bottom roughness.
    253 %\item ANUGA contains no tsunami-genic functionality relating to earthquakes.
     253%\item \anuga contains no tsunami-genic functionality relating to earthquakes.
    254254\end{itemize}
    255255
     
    523523          not steady state as replication of momentum at the boundary
    524524          may cause numerical instabilities propagating into the domain and
    525           eventually causing ANUGA to crash. If this occurs,
     525          eventually causing \anuga to crash. If this occurs,
    526526          consider using e.g. a Dirichlet boundary condition with a stage value
    527527          less than the elevation at the boundary.
     
    574574uses different boundary tags -- in general, the possible tags are entirely selectable by the user when generating the mesh and not
    575575limited to 'left', 'right', 'top' and 'bottom' as in this example.)
    576 All segments in bounding polygon must be tagged. If a tag is not supplied, the default tag name 'exterior' will be assigned by ANUGA.
     576All segments in bounding polygon must be tagged. If a tag is not supplied, the default tag name 'exterior' will be assigned by \anuga.
    577577
    578578Using the boundary objects described above, we assign a boundary
     
    629629The output is a NetCDF file with the extension \code{.sww}. It
    630630contains stage and momentum information and can be used with the
    631 ANUGA viewer \code{animate} to generate a visual
     631\anuga viewer \code{animate} to generate a visual
    632632display (see Section \ref{sec:animate}). See Section \ref{sec:file formats}
    633633(page \pageref{sec:file formats}) for more on NetCDF and other file
     
    666666  \centerline{\includegraphics[width=75mm, height=75mm]
    667667    {graphics/bedslopestart.jpg}}
    668   \caption{Runup example viewed with the ANUGA viewer}
     668  \caption{Runup example viewed with the \anuga viewer}
    669669  \label{fig:runupstart}
    670670\end{figure}
     
    727727\end{verbatim}
    728728
    729 returns an \code{m x n} mesh similar to the one used in the previous example, except that now the
     729returns an \code{mxn} mesh similar to the one used in the previous example, except that now the
    730730extent in the x and y directions are given by the value of \code{length} and \code{width}
    731731respectively.
     
    763763  \centerline{\includegraphics[height=75mm]
    764764    {graphics/channel1.png}}%
    765   \caption{Simple channel example viewed with the ANUGA viewer.}
     765  \caption{Simple channel example viewed with the \anuga viewer.}
    766766  \label{fig:channel1}
    767767\end{figure}
     
    928928maximal area of a triangle used for triangulation -- and a triangular
    929929mesh is created inside the polygon using a mesh generation engine.
    930 On any given platform, the same mesh will be returned.
     930On any given platform, the same mesh will be returned each time the
     931script is run.
    931932
    932933Boundary tags are not restricted to \code{'left'}, \code{'bottom'},
     
    10561057
    10571058Since we used \code{create_domain_from_regions} to create the mesh file, we do not need to
    1058 create the domain explicitly, as the above function also does that.
     1059create the domain explicitly, as the above function does both mesh and domain creation.
    10591060
    10601061The following statements specify a basename and data directory, and
    1061 sets a minimum storable height, which helps with visualisation.
    1062 
    1063 \begin{verbatim}
    1064 domain.set_name('cairns_' + project.scenario) # Name of sww file
    1065 domain.set_datadir('.')                       # Store sww output here
     1062sets a minimum storable height, which helps with visualisation and post-processing
     1063if one wants to remove water less than 1cm deep (for instance).
     1064
     1065\begin{verbatim}
     1066domain.set_name('cairns_' + project.scenario) # Name of SWW file
     1067domain.set_datadir('.')                       # Store SWW output here
    10661068domain.set_minimum_storable_height(0.01)      # Store only depth > 1cm
    10671069\end{verbatim}
     
    10731075in this case, many of the values are read from the auxiliary file
    10741076\file{project.py} or, in the case of \code{elevation}, from an
    1075 ancillary points file.
     1077auxiliary points file.
    10761078
    10771079\subsubsection{Stage}
    10781080
    1079 The stage is initially set to 0.0 by the following statements:
     1081The stage is initially set to 0.0 (i.e. Mean Sea Level) by the following statements:
    10801082
    10811083\begin{verbatim}
     
    10831085domain.set_quantity('stage', tide)
    10841086\end{verbatim}
     1087
     1088It could also take the value of the highest astronomical tide.
    10851089
    10861090%For the scenario we are modelling in this case, we use a callable
     
    11091113\subsubsection{Elevation}
    11101114
    1111 The elevation is specified by reading data from a file:
     1115The elevation is specified by reading data from a file with a name derived from
     1116\code{project.demname} with the \code{.pts} extension:
    11121117
    11131118\begin{verbatim}
     
    11181123                    alpha=0.1)
    11191124\end{verbatim}
     1125
     1126The \code{alpha} parameter controls how smooth the elevation surface
     1127should be.  See section \ref{class:alpha_shape}, page \pageref{class:alpha_shape}.
     1128
     1129Setting \code{cache=True} allows \anuga to save the result in order
     1130to make subsequent runs faster.
     1131
     1132Using \code{verbose=True} tells the function to write diagnostics to
     1133the screen.
    11201134
    11211135\subsection{Boundary Conditions}\index{boundary conditions}
     
    11651179\begin{verbatim}
    11661180if project.scenario == 'slide':
     1181    # Initial run without any event
    11671182    for t in domain.evolve(yieldstep=10, finaltime=60):
    11681183        print domain.timestepping_statistics()
    11691184        print domain.boundary_statistics(tags='ocean_east')
    11701185
    1171     # Add slide
    1172     thisstagestep = domain.get_quantity('stage')
     1186    # Add slide to water surface
    11731187    if allclose(t, 60):
    1174         slide = Quantity(domain)
    1175         slide.set_values(tsunami_source)
    1176         domain.set_quantity('stage', slide + thisstagestep)
    1177 
     1188        domain.add_quantity('stage', tsunami_source)
     1189
     1190    # Continue propagating wave
    11781191    for t in domain.evolve(yieldstep=10, finaltime=5000,
    11791192                           skip_initial_step=True):
     
    14641477\label{sec:meshgeneration}
    14651478
    1466 \begin{funcdesc} {create\_mesh\_from\_regions}{bounding_polygon,
    1467                              boundary_tags,
    1468                              maximum_triangle_area,
    1469                              filename=None,
    1470                              interior_regions=None,
    1471                              poly_geo_reference=None,
    1472                              mesh_geo_reference=None,
    1473                              minimum_triangle_angle=28.0}
     1479\begin{funcdesc}{create_mesh_from_regions}{bounding_polygon,
     1480                                           boundary_tags,
     1481                                           maximum_triangle_area=None,
     1482                                           filename=None,
     1483                                           interior_regions=None,
     1484                                           interior_holes=None,
     1485                                           poly_geo_reference=None,
     1486                                           mesh_geo_reference=None,
     1487                                           minimum_triangle_angle=28.0,
     1488                                           fail_if_polygons_outside=True,
     1489                                           use_cache=False,
     1490                                           verbose=True}
    14741491Module: \module{pmesh.mesh\_interface}
    14751492
     
    15031520\end{funcdesc}
    15041521
     1522\begin{funcdesc}{create_domain_from_regions}{bounding_polygon,
     1523                                             boundary_tags,
     1524                                             maximum_triangle_area=None,
     1525                                             mesh_filename=None,
     1526                                             interior_regions=None,
     1527                                             interior_holes=None,
     1528                                             poly_geo_reference=None,
     1529                                             mesh_geo_reference=None,
     1530                                             minimum_triangle_angle=28.0,
     1531                                             fail_if_polygons_outside=True,
     1532                                             use_cache=False,
     1533                                             verbose=True}
     1534
     1535Module: \module{interface.py}
     1536
     1537This higher-level function allows a user to create a domain (and associated mesh)
     1538inside a specified polygon.
     1539
     1540\code{bounding_polygon} is a list of points in Eastings and Northings,
     1541relative to the zone stated in \code{poly_geo_reference} if specified.
     1542Otherwise points are just x, y coordinates with no particular
     1543association to any location.
     1544
     1545\code{boundary_tags} is a dictionary of symbolic tags. For every tag there
     1546is a list of indices referring to segments associated with that tag.
     1547If a segment is omitted it will be assigned the default tag ''.
     1548
     1549\code{maximum_triangle_area} is the maximal area per triangle
     1550for the bounding polygon, excluding the interior regions.
     1551
     1552\code{mesh_filename} is the name of the file to contain the generated
     1553mesh data.
     1554
     1555\code{interior_regions} is a list of tuples consisting of (polygon,
     1556resolution) for each region to be separately refined. Do not have
     1557polygon lines cross or be on-top of each other.  Also do not have
     1558polygons close to each other.
     1559
     1560\code{poly_geo_reference} is the geo_reference of the bounding polygon and
     1561the interior polygons.
     1562If none, assume absolute.  Please pass one though, since absolute
     1563references have a zone.
     1564
     1565\code{mesh_geo_reference} is the geo_reference of the mesh to be created.
     1566If none is given one will be automatically generated.  It will use
     1567the lower left hand corner of  bounding_polygon (absolute)
     1568as the x and y values for the geo_ref.
     1569
     1570\code{minimum_triangle_angle} is the minimum angle allowed for each generated triangle.
     1571This controls the \emph{slimness} allowed for a triangle.
     1572
     1573\code{fail_if_polygons_outside} -- if True (the default) an Exception in thrown
     1574if interior polygons fall outside the bounding polygon. If False, these
     1575will be ignored and execution continues.
     1576
     1577\textbf{WARNING}. Note that the dictionary structure used for the
     1578parameter \code{boundary_tags} is different from that used for the
     1579variable \code{boundary} that occurs in the specification of a mesh.
     1580In the case of \code{boundary}, the tags are the \emph{values} of
     1581the dictionary, whereas in the case of \code{boundary_tags}, the
     1582tags are the \emph{keys} and the \emph{value} corresponding to a
     1583particular tag is a list of numbers identifying boundary edges
     1584labelled with that tag. Because of this, it is theoretically
     1585possible to assign the same edge to more than one tag. However, an
     1586attempt to do this will cause an error.
     1587
     1588\textbf{WARNING}. Do not have polygon lines cross or be on-top of each
     1589    other. This can result in regions of unspecified resolutions. Do
     1590    not have polygon close to each other. This can result in the area
     1591    between the polygons having small triangles.  For more control
     1592    over the mesh outline use the methods described below.
     1593
     1594\end{funcdesc}
     1595
    15051596\subsection{Advanced mesh generation}
    15061597
     
    15081599methods of the class \class{Mesh}.
    15091600
    1510 
    1511 \begin{classdesc}  {Mesh}{userSegments=None,
    1512                  userVertices=None,
    1513                  holes=None,
    1514                  regions=None}
     1601\begin{classdesc}{Mesh}{userSegments=None,
     1602                        userVertices=None,
     1603                        holes=None,
     1604                        regions=None,
     1605                        geo_reference=None}
    15151606Module: \module{pmesh.mesh}
    15161607
    15171608A class used to build a mesh outline and generate a two-dimensional
    15181609triangular mesh. The mesh outline is used to describe features on the
    1519 mesh, such as the mesh boundary. Many of this classes methods are used
    1520 to build a mesh outline, such as \code{add\_vertices} and
    1521 \code{add\_region\_from\_polygon}.
     1610mesh, such as the mesh boundary. Many of this class's methods are used
     1611to build a mesh outline, such as \code{add_vertices()} and
     1612\code{add_region_from_polygon()}.
     1613
     1614\code{userSegments} and \code{userVertices} define the outline enclosing the mesh.
     1615
     1616\code{holes} describes any regions inside the mesh that are not to be included in the mesh.
     1617
     1618\code{geo_reference} defines the geo_reference to which all point information is relative.
     1619If \code{geo_reference} is \code{None} then the default geo_reference is used.
    15221620\end{classdesc}
    15231621
    15241622\subsubsection{Key Methods of Class Mesh}
    15251623
    1526 \begin{methoddesc} {add\_hole}{self, x, y}
    1527 Module: \module{pmesh.mesh},  Class: \class{Mesh}
    1528 
    1529 This method is used to build the mesh outline.  It defines a hole,
    1530 when the boundary of the hole has already been defined, by selecting a
    1531 point within the boundary.
    1532 \end{methoddesc}
    1533 
    1534 \begin{methoddesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None}
    1535 Module: \module{pmesh.mesh},  Class: \class{Mesh}
     1624\begin{methoddesc}{\emph{<mesh>}.add_hole}{x, y, geo_reference=None}
     1625Module: \module{pmesh.mesh}
     1626
     1627This method adds a hole to the mesh outline.
     1628
     1629\code{x} and \code{y} define a point on the already defined hole boundary.
     1630
     1631If \code{geo_reference} is not supplied the points are assumed to be absolute.
     1632\end{methoddesc}
     1633
     1634\begin{methoddesc}{\emph{<mesh>}.add_hole_from_polygon}{polygon,
     1635                                                        segment_tags=None,
     1636                                                        geo_reference=None}
     1637Module: \module{pmesh.mesh}
    15361638
    15371639This method is used to add a 'hole' within a region -- that is, to
     
    15401642the polygon passed in.  Additionally, the user specifies a list of
    15411643boundary tags, one for each edge of the bounding polygon.
    1542 \end{methoddesc}
    1543 
    1544 \begin{methoddesc}  {add\_points_and_segments}{self, points, segments,
    1545     segment\_tags=None}
    1546 Module: \module{pmesh.mesh},  Class: \class{Mesh}
    1547 
    1548 This method is used to build the mesh outline. It adds points and
    1549 segments connecting the points.  Points is a list of points. Segments
    1550 is a list of segments.  Each segment is defined by the start and end
    1551 of the line by it's point index, e.g. use \code{segments =
    1552 [[0,1],[1,2]]} to make a polyline between points 0, 1 and 2. A tag for
    1553 each segment can optionally be added.
    1554 \end{methoddesc}
    1555 
    1556 \begin{methoddesc} {add\_region}{self, x, y}
    1557 Module: \module{pmesh.mesh},  Class: \class{Mesh}
    1558 
    1559 This method is used to build the mesh outline.  It defines a region,
    1560 when the boundary of the region has already been defined, by selecting
    1561 a point within the boundary.  A region instance is returned.  This can
    1562 be used to set the resolution.
    1563 \end{methoddesc}
    1564 
    1565 \begin{methoddesc}  {add\_region\_from\_polygon}{self, polygon,
    1566                      segment_tags=None, region_tag=None, max_triangle_area=None}
    1567 Module: \module{pmesh.mesh},  Class: \class{Mesh}
    1568 
    1569 This method is used to build the mesh outline.  It adds a region to a
     1644
     1645\code{polygon} is the polygon that defines the hole to be added to the \code{<mesh>}.
     1646
     1647\code{segment_tags} -- ??
     1648
     1649If \code{geo_reference} is \code{None} then the default \code{geo_reference} is used.
     1650\end{methoddesc}
     1651
     1652\begin{methoddesc}{\emph{<mesh>}.add_points_and_segments}{points,
     1653                                                          segments=None,
     1654                                                          segment_tags=None}
     1655Module: \module{pmesh.mesh}
     1656
     1657This adds points and segments connecting the points to a mesh.
     1658
     1659\code{points} is a list of points.
     1660
     1661\code{segments} is a list of segments.  Each segment is defined by the start and end
     1662of the line by its point index, e.g. use \code{segments = [[0,1],[1,2]]} to make a
     1663polyline between points 0, 1 and 2.
     1664
     1665\code{segment_tags} may be used to optionally define a tag for each segment.
     1666\end{methoddesc}
     1667
     1668\begin{methoddesc}{\emph{<mesh>}.add_region}{x,y, geo_reference=None, tag=None}
     1669Module: \module{pmesh.mesh}
     1670
     1671This method adds a region to a mesh outline.
     1672
     1673\code{x} and \code{y} define a point on the already-defined region that is to
     1674be added to the mesh.
     1675
     1676If \code{geo_reference} is not supplied the points data is assumed to be absolute.
     1677
     1678\code{tag} -- ??
     1679
     1680A region instance is returned.  This can be used to set the resolution of the added region.
     1681\end{methoddesc}
     1682
     1683\begin{methoddesc}{\emph{<mesh>}.add_region_from_polygon}{polygon,
     1684                                                          segment_tags=None,
     1685                                                          max_triangle_area=None,
     1686                                                          geo_reference=None,
     1687                                                          region_tag=None}
     1688Module: \module{pmesh.mesh}
     1689
     1690This method adds a region to a
    15701691\class{Mesh} instance.  Regions are commonly used to describe an area
    1571 with an increased density of triangles, by setting
    1572 \code{max_triangle_area}.  The
    1573 region boundary is described by the input \code{polygon}.  Additionally, the
    1574 user specifies a list of segment tags, one for each edge of the
    1575 bounding polygon.  The regional tag is set using  \code{region}.
    1576 \end{methoddesc}
    1577 
    1578 \begin{methoddesc} {add\_vertices}{self, point_data}
    1579 Module: \module{pmesh.mesh},  Class: \class{Mesh}
    1580 
    1581 Add user vertices. The point_data can be a list of (x,y) values, a numeric
    1582 array or a geospatial_data instance.
    1583 \end{methoddesc}
    1584 
    1585 \begin{methoddesc} {auto\_segment}{self, raw_boundary=raw_boundary,
    1586                     remove_holes=remove_holes,
    1587                     smooth_indents=smooth_indents,
    1588                     expand_pinch=expand_pinch}
    1589 Module: \module{pmesh.mesh},  Class: \class{Mesh}
     1692with an increased density of triangles by setting \code{max_triangle_area}.
     1693
     1694\code{polygon} describes the region boundary to add to the \code{<mesh>}.
     1695
     1696\code{segment_tags} specifies a list of segment tags, one for each edge of the
     1697bounding polygon.
     1698
     1699If \code{geo_reference} is not supplied the points data is assumed to be absolute.
     1700
     1701\code{region_tag} sets the region tag.
     1702\end{methoddesc}
     1703
     1704\begin{methoddesc}{\emph{<mesh>}.add_vertices}{point_data}
     1705Module: \module{pmesh.mesh}
     1706
     1707Add user vertices to a mesh.
     1708
     1709\code{point_data} is the list of point data, and can be a list of (x,y) values,
     1710a numeric array or a geospatial_data instance.
     1711\end{methoddesc}
     1712
     1713\begin{methoddesc}{\emph{<mesh>}.auto_segment}{alpha=None,
     1714                                               raw_boundary=True,
     1715                                               remove_holes=False,
     1716                                               smooth_indents=False,
     1717                                               expand_pinch=False}
     1718Module: \module{pmesh.mesh}
    15901719
    15911720Add segments between some of the user vertices to give the vertices an
     
    15931722useful since a set of user vertices need to be outlined by segments
    15941723before generate_mesh is called.
    1595 \end{methoddesc}
    1596 
    1597 \begin{methoddesc}  {export\_mesh_file}{self, ofile}
    1598 Module: \module{pmesh.mesh},  Class: \class{Mesh}
    1599 
    1600 This method is used to save the mesh to a file. \code{ofile} is the
    1601 name of the mesh file to be written, including the extension.  Use
    1602 the extension \code{.msh} for the file to be in NetCDF format and
     1724
     1725\code{alpha} determines the $smoothness$ of the alpha shape.
     1726
     1727\code{raw_boundary}, if \code{True} instructs the function to return the raw
     1728boundary, i.e. the regular edges of the alpha shape.
     1729
     1730\code{remove_holes}, if \code{True} enables a filter to remove small holes
     1731(small is defined by  boundary_points_fraction).
     1732
     1733\code{smooth_indents}, if \code{True} removes sharp triangular indents
     1734in the boundary.
     1735
     1736\code{expand_pinch}, if \code{True} tests for pinch-off and corrects
     1737(i.e. a boundary vertex with more than two edges).
     1738\end{methoddesc}
     1739
     1740\begin{methoddesc}{\emph{<mesh>}.export_mesh_file}{ofile}
     1741Module: \module{pmesh.mesh}
     1742
     1743This method is used to save a mesh to a file.
     1744
     1745\code{ofile} is the name of the mesh file to be written, including the extension.
     1746Use the extension \code{.msh} for the file to be in NetCDF format and
    16031747\code{.tsh} for the file to be ASCII format.
    16041748\end{methoddesc}
    16051749
    1606 \begin{methoddesc}  {generate\_mesh}{self,
    1607                       maximum_triangle_area=None,
    1608                       minimum_triangle_angle=28.0,
    1609                       verbose=False}
    1610 Module: \module{pmesh.mesh},  Class: \class{Mesh}
    1611 
    1612 This method is used to generate the triangular mesh.  The  maximal
    1613 area of any triangle in the mesh can be specified, which is used to
    1614 control the triangle density, along with the
    1615 minimum angle in any triangle.
    1616 \end{methoddesc}
    1617 
    1618 \begin{methoddesc}  {import_ungenerate_file}{self, ofile, tag=None,
    1619 region_tag=None}
    1620 Module: \module{pmesh.mesh},  Class: \class{Mesh}
     1750\begin{methoddesc}{\emph{<mesh>}.generate_mesh}{maximum_triangle_area="",
     1751                                                minimum_triangle_angle=28.0,
     1752                                                verbose=True}
     1753Module: \module{pmesh.mesh}
     1754
     1755This method is used to generate the triangular mesh.
     1756
     1757\code{maximum_triangle_area} sets the maximum area of any triangle in the mesh.
     1758
     1759\code{minimum_triangle_angle} sets the minimum area of any triangle in the mesh.
     1760
     1761These two parameters can be used to control the triangle density.
     1762\end{methoddesc}
     1763
     1764\begin{methoddesc}{\emph{<mesh>}.import_ungenerate_file}{ofile,
     1765                                                         tag=None,
     1766                                                         region_tag=None}
     1767Module: \module{pmesh.mesh}
    16211768
    16221769This method is used to import a polygon file in the ungenerate format,
    16231770which is used by arcGIS. The polygons from the file are converted to
    1624 vertices and segments. \code{ofile} is the name of the polygon file.
     1771vertices and segments.
     1772
     1773\code{ofile} is the name of the polygon file.
     1774
    16251775\code{tag} is the tag given to all the polygon's segments.
     1776If \code{tag} is not supplied then the segment will not effect the water
     1777flow, it will only effect the mesh generation.
     1778
    16261779\code{region_tag} is the tag given to all the polygon's segments.  If
    1627 it is a string the one value will be assigned to all regions.  If it
     1780it is a string the tag will be assigned to all regions.  If it
    16281781is a list the first value in the list will be applied to the first
    1629 polygon etc.  If \code{tag} is not given a value it defaults to None,
    1630 which means the segement will not effect the water flow, it will only
    1631 effect the mesh generation.
     1782polygon etc.
    16321783
    16331784This function can be used to import building footprints.
     
    16381789\label{sec:initialising the domain}
    16391790
    1640 %Include description of the class Domain and the module domain.
    1641 
    1642 %FIXME (Ole): This is also defined in a later chapter
    1643 %\declaremodule{standard}{...domain}
    1644 
    1645 \begin{classdesc} {Domain} {source=None,
    1646                  triangles=None,
    1647                  boundary=None,
    1648                  conserved_quantities=None,
    1649                  other_quantities=None,
    1650                  tagged_elements=None,
    1651                  use_inscribed_circle=False,
    1652                  mesh_filename=None,
    1653                  use_cache=False,
    1654                  verbose=False,
    1655                  full_send_dict=None,
    1656                  ghost_recv_dict=None,
    1657                  processor=0,
    1658                  numproc=1}
     1791\begin{classdesc}{Domain}{source=None,
     1792                          triangles=None,
     1793                          boundary=None,
     1794                          conserved_quantities=None,
     1795                          other_quantities=None,
     1796                          tagged_elements=None,
     1797                          geo_reference=None,
     1798                          use_inscribed_circle=False,
     1799                          mesh_filename=None,
     1800                          use_cache=False,
     1801                          verbose=False,
     1802                          full_send_dict=None,
     1803                          ghost_recv_dict=None,
     1804                          processor=0,
     1805                          numproc=1,
     1806                          number_of_full_nodes=None,
     1807                          number_of_full_triangles=None}
    16591808Module: \refmodule{abstract_2d_finite_volumes.domain}
    16601809
    1661 This class is used to create an instance of a data structure used to
     1810This class is used to create an instance of a structure used to
    16621811store and manipulate data associated with a mesh. The mesh is
    16631812specified either by assigning the name of a mesh file to
     
    16681817\subsection{Key Methods of Domain}
    16691818
    1670 \begin{methoddesc} {set\_name}{name}
    1671     Module: \refmodule{abstract\_2d\_finite\_volumes.domain},
    1672     page \pageref{mod:domain}
    1673 
    1674     Assigns the name \code{name} to the domain.
    1675 \end{methoddesc}
    1676 
    1677 \begin{methoddesc} {get\_name}{}
    1678     Module: \module{abstract\_2d\_finite\_volumes.domain}
    1679 
    1680     Returns the name assigned to the domain by \code{set\_name}. If no name has been
    1681     assigned, returns \code{'domain'}.
    1682 \end{methoddesc}
    1683 
    1684 \begin{methoddesc} {set\_datadir}{name}
    1685     Module: \module{abstract\_2d\_finite\_volumes.domain}
    1686 
    1687     Specifies the directory used for SWW files, assigning it to the
    1688     pathname \code{name}. The default value, before
    1689     \code{set\_datadir} has been run, is the value \code{default\_datadir}
    1690     specified in \code{config.py}.
    1691 
    1692     Since different operating systems use different formats for specifying pathnames,
    1693     it is necessary to specify path separators using the Python code \code{os.sep}, rather than
    1694     the operating-specific ones such as '$\slash$' or '$\backslash$'.
    1695     For this to work you will need to include the statement \code{import os}
    1696     in your code, before the first appearance of \code{set\_datadir}.
    1697 
    1698     For example, to set the data directory to a subdirectory
    1699     \code{data} of the directory \code{project}, you could use
    1700     the statements:
    1701 
    1702     \begin{verbatim}
     1819\begin{methoddesc}{\emph{<domain>}.set_name}{name}
     1820Module: \refmodule{abstract_2d_finite_volumes.domain},
     1821page \pageref{mod:domain}
     1822
     1823\code{name} is used to name the domain.  The \code{name} is also used to identify the output SWW file.
     1824If no name is assigned to a domain, the assumed name is \code{'domain'}.
     1825\end{methoddesc}
     1826
     1827\begin{methoddesc}{\emph{<domain>}.get_name}{}
     1828Module: \module{abstract_2d_finite_volumes.domain}
     1829
     1830Returns the name assigned to the domain by \code{set_name()}. If no name has been
     1831assigned, returns \code{'domain'}.
     1832\end{methoddesc}
     1833
     1834\begin{methoddesc}{\emph{<domain>}.set_datadir}{path}
     1835Module: \module{abstract_2d_finite_volumes.domain}
     1836
     1837\code{path} specifies the path to the directory used to store SWW files.
     1838
     1839Before this method is used to set the SWW directory path, the assumed directory
     1840path is \code{default_datadir} specified in \code{config.py}.
     1841
     1842Since different operating systems use different formats for specifying pathnames
     1843it is necessary to specify path separators using the Python code \code{os.sep} rather than
     1844the operating-specific ones such as '$\slash$' or '$\backslash$'.
     1845For this to work you will need to include the statement \code{import os}
     1846in your code, before the first use of \code{set_datadir()}.
     1847
     1848For example, to set the data directory to a subdirectory
     1849\code{data} of the directory \code{project}, you could use
     1850the statements:
     1851
     1852\begin{verbatim}
    17031853import os
    17041854domain.set_datadir{'project' + os.sep + 'data'}
    1705     \end{verbatim}
    1706 \end{methoddesc}
    1707 
    1708 \begin{methoddesc} {get\_datadir}{}
    1709     Module: \module{abstract\_2d\_finite\_volumes.domain}
    1710 
    1711     Returns the data directory set by \code{set\_datadir} or,
    1712     if \code{set\_datadir} has not
    1713     been run, returns the value \code{default\_datadir} specified in
    1714     \code{config.py}.
    1715 \end{methoddesc}
    1716 
    1717 \begin{methoddesc} {set\_minimum_allowed_height}{}
    1718     Module: \module{shallow\_water.shallow\_water\_domain}
    1719 
    1720     Set the minimum depth (in meters) that will be recognised in
    1721     the numerical scheme (including limiters and flux computations)
    1722 
    1723     Default value is $10^{-3}$ m, but by setting this to a greater value,
    1724     e.g.\ for large scale simulations, the computation time can be
    1725     significantly reduced.
    1726 \end{methoddesc}
    1727 
    1728 \begin{methoddesc} {set\_minimum_storable_height}{}
    1729     Module: \module{shallow\_water.shallow\_water\_domain}
    1730 
    1731     Sets the minimum depth that will be recognised when writing
    1732     to an sww file. This is useful for removing thin water layers
    1733     that seems to be caused by friction creep.
    1734 \end{methoddesc}
    1735 
    1736 \begin{methoddesc} {set\_maximum_allowed_speed}{}
    1737     Module: \module{shallow\_water.shallow\_water\_domain}
    1738 
    1739     Set the maximum particle speed that is allowed in water
    1740     shallower than minimum_allowed_height. This is useful for
    1741     controlling speeds in very thin layers of water and at the same time
    1742     allow some movement avoiding pooling of water.
    1743 \end{methoddesc}
    1744 
    1745 \begin{methoddesc} {set\_time}{time=0.0}
    1746     Module: \module{abstract\_2d\_finite\_volumes.domain}
    1747 
    1748     Sets the initial time, in seconds, for the simulation. The
    1749     default is 0.0.
    1750 \end{methoddesc}
    1751 
    1752 \begin{methoddesc} {set\_default\_order}{n}
    1753     Sets the default (spatial) order to the value specified by
    1754     \code{n}, which must be either 1 or 2. (Assigning any other value
    1755     to \code{n} will cause an error.)
    1756 \end{methoddesc}
    1757 
    1758 \begin{methoddesc} {set\_store\_vertices\_uniquely}{flag}
     1855\end{verbatim}
     1856\end{methoddesc}
     1857
     1858\begin{methoddesc}{\emph{<domain>}.get_datadir}{}
     1859Module: \module{abstract_2d_finite_volumes.domain}
     1860
     1861Returns the path to the directory where SWW files will be stored.
     1862
     1863If the path has not previously been set with \code{set_datadir()} this method
     1864will return the value \code{default_datadir} specified in \code{config.py}.
     1865\end{methoddesc}
     1866
     1867\begin{methoddesc}{\emph{<domain>}.set_minimum_allowed_height}{minimum_allowed_height}
     1868Module: \module{shallow_water.shallow_water_domain}
     1869
     1870Set the minimum depth (in metres) that will be recognised in
     1871the numerical scheme (including limiters and flux computations)
     1872
     1873\code{minimum_allowed_height} is the new minimum allowed height value.
     1874
     1875Default value is $10^{-3}$ metre, but by setting this to a greater value,
     1876e.g. for large scale simulations, the computation time can be
     1877significantly reduced.
     1878\end{methoddesc}
     1879
     1880\begin{methoddesc}{\emph{<domain>}.set_minimum_storable_height}{minimum_storable_height}
     1881Module: \module{shallow_water.shallow_water_domain}
     1882
     1883Sets the minimum depth that will be recognised when writing
     1884to an SWW file. This is useful for removing thin water layers
     1885that seems to be caused by friction creep.
     1886
     1887\code{minimum_storable_height} is the new minimum storable height value.
     1888\end{methoddesc}
     1889
     1890\begin{methoddesc}{\emph{<domain>}.set_maximum_allowed_speed}{maximum_allowed_speed}
     1891Module: \module{shallow_water.shallow_water_domain}
     1892
     1893Set the maximum particle speed that is allowed in water
     1894shallower than \code{minimum_allowed_height}. This is useful for
     1895controlling speeds in very thin layers of water and at the same time
     1896allow some movement avoiding pooling of water.
     1897
     1898\code{maximum_allowed_speed} sets the maximum allowed speed value.
     1899\end{methoddesc}
     1900
     1901\begin{methoddesc}{\emph{<domain>}.set_time}{time=0.0}
     1902Module: \module{abstract_2d_finite_volumes.domain}
     1903
     1904\code{time} sets the initial time, in seconds, for the simulation. The
     1905default is 0.0.
     1906\end{methoddesc}
     1907
     1908\begin{methoddesc}{\emph{<domain>}.set_default_order}{n}
     1909Module: \module{abstract_2d_finite_volumes.domain}
     1910
     1911Sets the default (spatial) order to the value specified by
     1912\code{n}, which must be either 1 or 2. (Assigning any other value
     1913to \code{n} will cause an error.)
     1914\end{methoddesc}
     1915
     1916\begin{methoddesc}{\emph{<domain>}.set_store_vertices_uniquely}{flag, reduction=None}
     1917Module: \module{shallow_water.shallow_water_domain}
     1918
    17591919Decide whether vertex values should be stored uniquely as
    17601920computed in the model or whether they should be reduced to one
    17611921value per vertex using averaging.
    17621922
    1763 Triangles stored in the sww file can be discontinuous reflecting
     1923\code{flag} may be \code{True} (meaning do not smooth vertex values) or \code{False}.
     1924
     1925\code{reduction} defines the smoothing operation if \code{flag} is \code{True}.  If not
     1926supplied, \code{reduction} is assumed to be \code{mean}.
     1927
     1928Triangles stored in the SWW file can be discontinuous reflecting
    17641929the internal representation of the finite-volume scheme
    1765 (this is a feature allowing for arbitrary steepness of the water surface gradient as well as the momentum gradients).
    1766 However, for visual purposes and also for use with \code{Field\_boundary}
    1767 (and \code{File\_boundary}) it is often desirable to store triangles
     1930(this is a feature allowing for arbitrary steepness of the water surface gradient
     1931as well as the momentum gradients).
     1932However, for visual purposes and also for use with \code{Field_boundary}
     1933(and \code{File_boundary}), it is often desirable to store triangles
    17681934with values at each vertex point as the average of the potentially
    17691935discontinuous numbers found at vertices of different triangles sharing the
    17701936same vertex location.
    17711937
    1772 Storing one way or the other is controlled in ANUGA through the method
    1773 \code{domain.store\_vertices\_uniquely}. Options are
     1938Storing one way or the other is controlled in \anuga through the method
     1939\code{<domain>.store_vertices_uniquely()}. Options are:
    17741940\begin{itemize}
    1775   \item \code{domain.store\_vertices\_uniquely(True)}: Allow discontinuities in the sww file
    1776   \item \code{domain.store\_vertices\_uniquely(False)}: (Default).
     1941  \item \code{<domain>.store_vertices_uniquely(True)}: Allow discontinuities in the SWW file
     1942  \item \code{<domain>.store_vertices_uniquely(False)}: (Default).
    17771943  Average values
    1778   to ensure continuity in sww file. The latter also makes for smaller
    1779   sww files.
     1944  to ensure continuity in SWW file. The latter also makes for smaller
     1945  SWW files.
    17801946\end{itemize}
    17811947
    1782 Note that when model data in the sww file are averaged (i.e. not stored uniquely),
    1783 then there will most likely be a small discrepancy between values extracted from the sww
     1948Note that when model data in the SWW file are averaged (i.e. not stored uniquely),
     1949then there will most likely be a small discrepancy between values extracted from the SWW
    17841950file and the same data stored in the model domain. This must be borne in mind when comparing
    1785 data from the sww files with that of the model internally.
     1951data from the SWW files with that of the model internally.
    17861952\end{methoddesc}
    17871953
    17881954% Structural methods
    1789 \begin{methoddesc}{get\_nodes}{absolute=False}
    1790     Return x,y coordinates of all nodes in mesh.
    1791 
    1792     The nodes are ordered in an Nx2 array where N is the number of nodes.
    1793     This is the same format they were provided in the constructor
    1794     i.e. without any duplication.
    1795 
    1796     Boolean keyword argument absolute determines whether coordinates
    1797     are to be made absolute by taking georeference into account
    1798     Default is False as many parts of ANUGA expects relative coordinates.
    1799 \end{methoddesc}
    1800 
    1801 \begin{methoddesc}{get\_vertex\_coordinates}{absolute=False}
    1802     \label{pg:get vertex coordinates}
    1803     Return vertex coordinates for all triangles.
    1804 
    1805     Return all vertex coordinates for all triangles as a 3*M x 2 array
    1806     where the jth vertex of the ith triangle is located in row 3*i+j and
    1807     M the number of triangles in the mesh.
    1808 
    1809     Boolean keyword argument absolute determines whether coordinates
    1810     are to be made absolute by taking georeference into account
    1811     Default is False as many parts of ANUGA expects relative coordinates.
    1812 \end{methoddesc}
    1813 
    1814 \begin{methoddesc}{get\_centroid\_coordinates}{absolute=False}
    1815 
    1816     Return centroid coordinates for all triangles.
    1817 
    1818     Return all centroid coordinates for all triangles as a M x 2 array
     1955\begin{methoddesc}{\emph{<domain>}.get_nodes}{absolute=False}
     1956Module: \module{abstract_2d_finite_volumes.domain}
     1957
     1958Return x,y coordinates of all nodes in the domain mesh.  The nodes are ordered
     1959in an \code{Nx2} array where N is the number of nodes.  This is the same format
     1960they were provided in the constructor i.e. without any duplication.
     1961
     1962\code{absolute} is a boolean which determines whether coordinates
     1963are to be made absolute by taking georeference into account.
     1964Default is \code{False} as many parts of \anuga expect relative coordinates.
     1965\end{methoddesc}
     1966
     1967\begin{methoddesc}{\emph{<domain>}.get_vertex_coordinates}{absolute=False}
     1968Module: \module{abstract_2d_finite_volumes.domain}
     1969
     1970\label{pg:get vertex coordinates}
     1971Return vertex coordinates for all triangles as a \code{3*Mx2} array
     1972where the jth vertex of the ith triangle is located in row 3*i+j and
     1973M is the number of triangles in the mesh.
     1974
     1975\code{absolute} is a boolean which determines whether coordinates
     1976are to be made absolute by taking georeference into account.
     1977Default is \code{False} as many parts of \anuga expect relative coordinates.
     1978\end{methoddesc}
     1979
     1980\begin{methoddesc}{\emph{<domain>}.get_centroid_coordinates}{absolute=False}
     1981Module: \module{abstract_2d_finite_volumes.domain}
     1982
     1983Return centroid coordinates for all triangles as an \code{Mx2} array.
    18191984   
    1820     Boolean keyword argument absolute determines whether coordinates
    1821     are to be made absolute by taking georeference into account
    1822     Default is False as many parts of ANUGA expects relative coordinates.
    1823 \end{methoddesc}
    1824 
    1825 \begin{methoddesc}{get\_triangles}{indices=None}
    1826 
    1827     Return Mx3 integer array where M is the number of triangles.
    1828     Each row corresponds to one triangle and the three entries are
    1829     indices into the mesh nodes which can be obtained using the method
    1830     get\_nodes()
    1831 
    1832     Optional argument, indices is the set of triangle ids of interest.
    1833 \end{methoddesc}
    1834 
    1835 \begin{methoddesc}{get\_disconnected\_triangles}{}
    1836     Get mesh based on nodes obtained from get_vertex_coordinates.
    1837 
    1838     Return array Mx3 array of integers where each row corresponds to
    1839     a triangle. A triangle is a triplet of indices into
    1840     point coordinates obtained from get_vertex_coordinates and each
    1841     index appears only once.\\
    1842 
    1843     This provides a mesh where no triangles share nodes
    1844     (hence the name disconnected triangles) and different
    1845     nodes may have the same coordinates.\\
    1846 
    1847     This version of the mesh is useful for storing meshes with
    1848     discontinuities at each node and is e.g. used for storing
    1849     data in sww files.\\
    1850 
    1851     The triangles created will have the format:
    1852 
    1853     \begin{verbatim}
     1985\code{absolute} is a boolean which determines whether coordinates
     1986are to be made absolute by taking georeference into account.
     1987Default is \code{False} as many parts of \anuga expect relative coordinates.
     1988\end{methoddesc}
     1989
     1990\begin{methoddesc}{\emph{<domain>}.get_triangles}{indices=None}
     1991Module: \module{abstract_2d_finite_volumes.domain}
     1992
     1993Return an \code{Mx3} integer array where M is the number of triangles.
     1994Each row corresponds to one triangle and the three entries are
     1995indices into the mesh nodes which can be obtained using the method
     1996\code{get_nodes()}.
     1997
     1998\code{indices}, if specified, is the set of triangle \code{id}s of interest.
     1999\end{methoddesc}
     2000
     2001\begin{methoddesc}{\emph{<domain>}.get_disconnected_triangles}{}
     2002Module: \module{abstract_2d_finite_volumes.domain}
     2003
     2004Get the domain mesh based on nodes obtained from \code{get_vertex_coordinates()}.
     2005
     2006Returns an \code{Mx3} array of integers where each row corresponds to
     2007a triangle. A triangle is a triplet of indices into
     2008point coordinates obtained from \code{get_vertex_coordinates()} and each
     2009index appears only once.
     2010
     2011This provides a mesh where no triangles share nodes
     2012(hence the name disconnected triangles) and different
     2013nodes may have the same coordinates.
     2014
     2015This version of the mesh is useful for storing meshes with
     2016discontinuities at each node and is e.g. used for storing
     2017data in SWW files.
     2018
     2019The triangles created will have the format:
     2020
     2021\begin{verbatim}
    18542022[[0,1,2],
    18552023 [3,4,5],
     
    18572025 ...
    18582026 [3*M-3 3*M-2 3*M-1]]
    1859     \end{verbatim}
     2027\end{verbatim}
    18602028\end{methoddesc}
    18612029
     
    18712039of initial conditions to refer to initial values for variables which need
    18722040prescription to solve the shallow water wave equation. Further, it must be noted
    1873 that \code{set_quantity} does not necessarily have to be used in the initial
     2041that \code{set_quantity()} does not necessarily have to be used in the initial
    18742042condition setting; it can be used at any time throughout the simulation.
    18752043
    1876 \begin{methoddesc}{set\_quantity}{name,
    1877     numeric=None,
    1878     quantity=None,
    1879     function=None,
    1880     geospatial_data=None,
    1881     expression=None,   
    1882     filename=None,
    1883     attribute_name=None,
    1884     alpha=None,
    1885     location='vertices',
    1886     indices=None,
    1887     verbose=False,
    1888     use_cache=False}
    1889   Module: \module{abstract\_2d\_finite\_volumes.domain}
    1890   (see also \module{abstract\_2d\_finite\_volumes.quantity.set\_values})
    1891 
    1892   This function is used to assign values to individual quantities for a
    1893   domain. It is very flexible and can be used with many data types: a
    1894   statement of the form \code{domain.set\_quantity(name, x)} can be used
    1895   to define a quantity having the name \code{name}, where the other
    1896   argument \code{x} can be any of the following:
    1897 
    1898   \begin{itemize}
    1899     \item a number, in which case all vertices in the mesh gets that for
    1900           the quantity in question.
    1901     \item a list of numbers or a numeric array ordered the same way as the mesh vertices.
    1902     \item a function (e.g.\ see the samples introduced in Chapter 2)
    1903     \item an expression composed of other quantities and numbers, arrays, lists (for
    1904           example, a linear combination of quantities, such as
    1905     \code{domain.set\_quantity('stage','elevation'+x))}
    1906     \item the name of a file from which the data can be read. In this case, the optional
    1907           argument attribute\_name will select which attribute to use from the file. If left out,
    1908           set\_quantity will pick one. This is useful in cases where there is only one attribute.
    1909     \item a geospatial dataset (See Section \ref{sec:geospatial}).
    1910           Optional argument attribute\_name applies here as with files.
    1911   \end{itemize}
    1912 
    1913   Exactly one of the arguments
    1914     numeric, quantity, function, points, filename
    1915   must be present.
    1916 
    1917   \code{set_quantity} will look at the type of the second argument (\code{numeric}) and
    1918   determine what action to take.
    1919 
    1920   Values can also be set using the appropriate keyword arguments.
    1921   If x is a function, for example, \code{domain.set\_quantity(name, x)}, \code{domain.set\_quantity(name, numeric=x)},
    1922   and \code{domain.set\_quantity(name, function=x)} are all equivalent.
    1923 
    1924   Other optional arguments are
    1925   \begin{itemize}
    1926     \item \code{indices} which is a list of ids of triangles to which set\_quantity should apply its assignment of values.
    1927     \item \code{location} determines which part of the triangles to assign
    1928                           to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'.
    1929                           If 'vertices' are use, edge and centroid values are automatically computed as the
    1930                           appropriate averages. This option ensures continuity of the surface.
    1931                           If, on the other hand, 'centroids' is used vertex and edge values will be set to the
    1932                           same value effectively creating a piecewise constant surface with possible discontinuities at the edges.
    1933   \end{itemize}
    1934 
    1935   \anuga provides a number of predefined initial conditions to be used
    1936   with \code{set\_quantity}. See for example callable object \code{slump\_tsunami} below.
    1937 \end{methoddesc}
    1938 
    1939 \begin{methoddesc}{add\_quantity}{name,
    1940     numeric=None,
    1941     quantity=None,
    1942     function=None,
    1943     geospatial_data=None,
    1944     expression=None,
    1945     filename=None,
    1946     attribute_name=None,
    1947     alpha=None,
    1948     location='vertices',
    1949     indices=None,
    1950     verbose=False,
    1951     use_cache=False}
    1952   Module: \module{abstract\_2d\_finite\_volumes.domain}
    1953   (see also \module{abstract\_2d\_finite\_volumes.domain.set\_quantity})
    1954 
    1955   \label{add quantity}
    1956   This function is used to \emph{add} values to individual quantities for a
    1957   domain. It has the same syntax as \code{domain.set\_quantity(name, x)}.
    1958 
    1959   A typical use of this function is to add structures to an existing elevation model:
    1960 
    1961   \begin{verbatim}
     2044\begin{methoddesc}{\emph{<domain>}.set_quantity}{numeric=None,
     2045                                                 quantity=None,
     2046                                                 function=None,
     2047                                                 geospatial_data=None,
     2048                                                 filename=None,
     2049                                                 attribute_name=None,
     2050                                                 alpha=None,
     2051                                                 location='vertices',
     2052                                                 polygon=None,
     2053                                                 indices=None,
     2054                                                 smooth=False,
     2055                                                 verbose=False,
     2056                                                 use_cache=False}
     2057Module: \module{abstract_2d_finite_volumes.domain} \\
     2058(This method passes off to \module{abstract_2d_finite_volumes.quantity.set_values()})
     2059
     2060This function is used to assign values to individual quantities for a
     2061domain. It is very flexible and can be used with many data types: a
     2062statement of the form \code{\emph{<domain>}.set_quantity(name, x)} can be used
     2063to define a quantity having the name \code{name}, where the other
     2064argument \code{x} can be any of the following:
     2065
     2066\begin{itemize}
     2067  \item a number, in which case all vertices in the mesh gets that for
     2068        the quantity in question
     2069  \item a list of numbers or a numeric array ordered the same way as the mesh vertices
     2070  \item a function (e.g. see the samples introduced in Chapter 2)
     2071  \item an expression composed of other quantities and numbers, arrays, lists (for
     2072        example, a linear combination of quantities, such as
     2073        \code{\emph{<domain>}.set_quantity('stage','elevation'+x))}
     2074  \item the name of a file from which the data can be read. In this case, the optional
     2075        argument \code{attribute_name} will select which attribute to use from the file. If left out,
     2076        \code{set_quantity()} will pick one. This is useful in cases where there is only one attribute
     2077  \item a geospatial dataset (See Section \ref{sec:geospatial}).
     2078        Optional argument \code{attribute_name} applies here as with files
     2079\end{itemize}
     2080
     2081Exactly one of the arguments \code{numeric}, \code{quantity}, \code{function},
     2082\code{geospatial_data} and \code{filename} must be present.
     2083
     2084\code{set_quantity()} will look at the type of the \code{numeric} and
     2085determine what action to take.
     2086
     2087Values can also be set using the appropriate keyword arguments.
     2088If \code{x} is a function, for example, \code{domain.set_quantity(name, x)}, \code{domain.set_quantity(name, numeric=x)},
     2089and \code{domain.set_quantity(name, function=x)} are all equivalent.
     2090
     2091Other optional arguments are:
     2092\begin{itemize}
     2093  \item \code{indices} which is a list of ids of triangles to which \code{set_quantity()}
     2094        should apply its assignment of values.
     2095  \item \code{location} determines which part of the triangles to assign to.
     2096        Options are 'vertices' (the default), 'edges', 'unique vertices', and 'centroids'.
     2097        If 'vertices' is used, edge and centroid values are automatically computed as the
     2098        appropriate averages. This option ensures continuity of the surface.
     2099        If, on the other hand, 'centroids' is used, vertex and edge values will be set to the
     2100        same value effectively creating a piecewise constant surface with possible
     2101        discontinuities at the edges.
     2102\end{itemize}
     2103
     2104\anuga provides a number of predefined initial conditions to be used
     2105with \code{set_quantity()}. See for example callable object \code{slump_tsunami} below.
     2106\end{methoddesc}
     2107
     2108\begin{methoddesc}{\emph{<domain>}.add_quantity}{numeric=None,
     2109                                                 quantity=None,
     2110                                                 function=None,
     2111                                                 geospatial_data=None,
     2112                                                 filename=None,
     2113                                                 attribute_name=None,
     2114                                                 alpha=None,
     2115                                                 location='vertices',
     2116                                                 polygon=None,
     2117                                                 indices=None,
     2118                                                 smooth=False,
     2119                                                 verbose=False,
     2120                                                 use_cache=False}
     2121Module: \module{abstract_2d_finite_volumes.domain} \\
     2122(passes off to \module{abstract_2d_finite_volumes.domain.set_quantity()})
     2123
     2124\label{add quantity}
     2125This function is used to \emph{add} values to individual quantities for a
     2126domain. It has the same syntax as \code{\emph{<domain>}.set_quantity(name, x)}.
     2127
     2128A typical use of this function is to add structures to an existing elevation model:
     2129
     2130\begin{verbatim}
    19622131# Create digital elevation model from points file
    19632132domain.set_quantity('elevation', filename='elevation_file.pts, verbose=True)
     
    19732142
    19742143domain.add_quantity('elevation', Polygon_function(B, default=0.0))
    1975   \end{verbatim}
    1976 \end{methoddesc}
    1977 
    1978 \begin{funcdesc}{set_region}{tag, quantity, X, location='vertices'}
    1979   Module: \module{abstract\_2d\_finite\_volumes.domain}
    1980 
    1981   (see also \module{abstract\_2d\_finite\_volumes.quantity.set\_values})
    1982 
    1983   This function is used to assign values to individual quantities given
    1984   a regional tag.   It is similar to \code{set\_quantity}.
    1985   For example, if in the mesh-generator a regional tag of 'ditch' was
    1986   used, set\_region can be used to set elevation of this region to
    1987   -10m. X is the constant or function to be applied to the quantity,
    1988   over the tagged region.  Location describes how the values will be
    1989   applied.  Options are 'vertices' (default), 'edges', 'unique
    1990   vertices', and 'centroids'.
    1991 
    1992   This method can also be called with a list of region objects.  This is
    1993   useful for adding quantities in regions, and having one quantity
    1994   value based on another quantity. See  \module{abstract\_2d\_finite\_volumes.region} for
    1995   more details.
     2144\end{verbatim}
     2145\end{methoddesc}
     2146
     2147\begin{methoddesc}{\emph{<domain>}.set_region}{tag, quantity, X, location='vertices'}
     2148Module: \module{abstract_2d_finite_volumes.domain} \\
     2149(see also \module{abstract_2d_finite_volumes.quantity.set_values})
     2150
     2151This function is used to assign values to individual quantities given
     2152a regional tag.   It is similar to \code{set_quantity()}.
     2153
     2154For example, if in the mesh-generator a regional tag of 'ditch' was
     2155used, \code{set_region()} can be used to set elevation of this region to
     2156-10m. \code{X} is the constant or function to be applied to the \code{quantity},
     2157over the tagged region.  \code{location} describes how the values will be
     2158applied.  Options are 'vertices' (the default), 'edges', 'unique
     2159vertices', and 'centroids'.
     2160
     2161This method can also be called with a list of region objects.  This is
     2162useful for adding quantities in regions, and having one quantity
     2163value based on another quantity. See  \module{abstract_2d_finite_volumes.region} for
     2164more details.
     2165\end{methoddesc}
     2166
     2167\begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None,
     2168                                radius=None, dphi=0.48, x0=0.0, y0=0.0, alpha=0.0,
     2169                                gravity=9.8, gamma=1.85,
     2170                                massco=1, dragco=1, frictionco=0,
     2171                                dx=None, kappa=3.0, kappad=1.0, zsmall=0.01, scale=None,
     2172                                domain=None,
     2173                                verbose=False}
     2174Module: \module{shallow\_water.smf}
     2175
     2176This function returns a callable object representing an initial water
     2177displacement generated by a submarine sediment failure. These failures can take the form of
     2178a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead.
     2179
     2180\code{length} is the length of the slide or slump.
     2181
     2182\code{depth} is the water depth to the centre of the sediment mass.
     2183
     2184\code{slope} is the bathymetric slope.
     2185
     2186Other slump or slide parameters can be included if they are known.
    19962187\end{funcdesc}
    19972188
    1998 \begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None,
    1999                 x0=0.0, y0=0.0, alpha=0.0,
    2000                 gravity=9.8, gamma=1.85,
    2001                 massco=1, dragco=1, frictionco=0, psi=0,
    2002                 dx=None, kappa=3.0, kappad=0.8, zsmall=0.01,
    2003                 domain=None,
    2004                 verbose=False}
    2005   Module: \module{shallow\_water.smf}
    2006 
    2007   This function returns a callable object representing an initial water
    2008   displacement generated by a submarine sediment failure. These failures can take the form of
    2009   a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead.
    2010 
    2011   The arguments include as a minimum, the slump or slide length, the water depth to the centre of sediment
    2012   mass, and the bathymetric slope. Other slump or slide parameters can be included if they are known.
     2189\begin{funcdesc}{\emph{<callable_object>} = file_function}{filename,
     2190                                domain=None,
     2191                                quantities=None,
     2192                                interpolation_points=None,
     2193                                time_thinning=1,
     2194                                time_limit=None,
     2195                                verbose=False,
     2196                                use_cache=False,
     2197                                boundary_polygon=None}
     2198Module: \module{abstract_2d_finite_volumes.util}
     2199
     2200Reads the time history of spatial data for specified interpolation points from
     2201a NetCDF file and returns a callable object.  Values returned from the \code{\emph{<callable_object>}}
     2202are interpolated values based on the input file using the underlying \code{interpolation_function}.
     2203
     2204\code{filename} is the name of the input file.  Could be an SWW or STS file.
     2205
     2206\code{quantities} is either the name of a single quantity to be
     2207interpolated or a list of such quantity names. In the second case, the resulting
     2208function will return a tuple of values -- one for each quantity.
     2209
     2210\code{interpolation_points} is a list of absolute coordinates or a
     2211geospatial object for points at which values are sought.
     2212
     2213\code{boundary_polygon} is a list of coordinates specifying the vertices of the boundary.
     2214This must be the same polygon as used when calling \code{create_mesh_from_regions()}.
     2215This argument can only be used when reading boundary data from an STS format file.
     2216
     2217The model time stored within the file function can be accessed using
     2218the method \code{\emph{<callable_object>}.get_time()}
     2219
     2220The underlying algorithm used is as follows:\\
     2221Given a time series (i.e. a series of values associated with
     2222different times), whose values are either just numbers, a set of
     2223numbers defined at the vertices of a triangular mesh (such as those
     2224stored in SWW files) or a set of
     2225numbers defined at a number of points on the boundary (such as those
     2226stored in STS files), \code{Interpolation_function()} is used to
     2227create a callable object that interpolates a value for an arbitrary
     2228time \code{t} within the model limits and possibly a point \code{(x, y)}
     2229within a mesh region.
     2230
     2231The actual time series at which data is available is specified by
     2232means of an array \code{time} of monotonically increasing times. The
     2233quantities containing the values to be interpolated are specified in
     2234an array -- or dictionary of arrays (used in conjunction with the
     2235optional argument \code{quantity_names}) -- called
     2236\code{quantities}. The optional arguments \code{vertex_coordinates}
     2237and \code{triangles} represent the spatial mesh associated with the
     2238quantity arrays. If omitted the function must be created using an STS file
     2239or a TMS file.
     2240
     2241Since, in practice, values need to be computed at specified points,
     2242the syntax allows the user to specify, once and for all, a list
     2243\code{interpolation_points} of points at which values are required.
     2244In this case, the function may be called using the form \code{\emph{<callable_object>}(t, id)},
     2245where \code{id} is an index for the list \code{interpolation_points}.
    20132246\end{funcdesc}
    20142247
    2015 \begin{funcdesc}{file\_function}{filename,
    2016     domain=None,
    2017     quantities=None,
    2018     interpolation_points=None,
    2019     verbose=False,
    2020     use_cache=False}
    2021   Module: \module{abstract\_2d\_finite\_volumes.util}
    2022 
    2023   Reads the time history of spatial data for
    2024   specified interpolation points from a NetCDF file (\code{filename})
    2025   and returns
    2026   a callable object. \code{filename} could be a \code{sww} or \code{sts} file.
    2027   Returns interpolated values based on the input
    2028   file using the underlying \code{interpolation\_function}.
    2029 
    2030   \code{quantities} is either the name of a single quantity to be
    2031   interpolated or a list of such quantity names. In the second case, the resulting
    2032   function will return a tuple of values -- one for each quantity.
    2033 
    2034   \code{interpolation\_points} is a list of absolute coordinates or a
    2035   geospatial object
    2036   for points at which values are sought.
    2037 
    2038   \code{boundary_polygon} is a list of coordinates specifying the vertices of the boundary.
    2039   This must be the same polygon as used when calling \code{create_mesh_from_regions}.
    2040   This argument can only be used when reading boundary data from the STS format.
    2041 
    2042   The model time stored within the file function can be accessed using
    2043   the method \code{f.get\_time()}
    2044 
    2045   The underlying algorithm used is as follows:\\
    2046   Given a time series (i.e.\ a series of values associated with
    2047   different times), whose values are either just numbers, a set of
    2048   numbers defined at the vertices of a triangular mesh (such as those
    2049   stored in SWW files) or a set of
    2050   numbers defined at a number of points on the boundary (such as those
    2051   stored in STS files), \code{Interpolation\_function} is used to
    2052   create a callable object that interpolates a value for an arbitrary
    2053   time \code{t} within the model limits and possibly a point \code{(x,
    2054   y)} within a mesh region.
    2055 
    2056   The actual time series at which data is available is specified by
    2057   means of an array \code{time} of monotonically increasing times. The
    2058   quantities containing the values to be interpolated are specified in
    2059   an array -- or dictionary of arrays (used in conjunction with the
    2060   optional argument \code{quantity\_names}) -- called
    2061   \code{quantities}. The optional arguments \code{vertex\_coordinates}
    2062   and \code{triangles} represent the spatial mesh associated with the
    2063   quantity arrays. If omitted the function must be created using an STS file
    2064   or a TMS file.
    2065 
    2066   Since, in practice, values need to be computed at specified points,
    2067   the syntax allows the user to specify, once and for all, a list
    2068   \code{interpolation\_points} of points at which values are required.
    2069   In this case, the function may be called using the form \code{f(t,
    2070   id)}, where \code{id} is an index for the list
    2071   \code{interpolation\_points}.
    2072 \end{funcdesc}
    2073 
    2074 % FIXME (OLE): Why has this been commented out?
    2075 %%%
    2076 %% \begin{classdesc}{Interpolation\_function}{self,
    2077 %%     time,
    2078 %%     quantities,
    2079 %%     quantity_names = None,
    2080 %%     vertex_coordinates = None,
    2081 %%     triangles = None,
    2082 %%     interpolation_points = None,
    2083 %%     verbose = False}
    2084 %% Module: \module{abstract\_2d\_finite\_volumes.least\_squares}
    2085 
    2086 %% Given a time series (i.e.\ a series of values associated with
    2087 %% different times), whose values are either just numbers or a set of
    2088 %% numbers defined at the vertices of a triangular mesh (such as those
    2089 %% stored in SWW files), \code{Interpolation\_function} is used to
    2090 %% create a callable object that interpolates a value for an arbitrary
    2091 %% time \code{t} within the model limits and possibly a point \code{(x,
    2092 %% y)} within a mesh region.
    2093 
    2094 %% The actual time series at which data is available is specified by
    2095 %% means of an array \code{time} of monotonically increasing times. The
    2096 %% quantities containing the values to be interpolated are specified in
    2097 %% an array -- or dictionary of arrays (used in conjunction with the
    2098 %% optional argument \code{quantity\_names}) -- called
    2099 %% \code{quantities}. The optional arguments \code{vertex\_coordinates}
    2100 %% and \code{triangles} represent the spatial mesh associated with the
    2101 %% quantity arrays. If omitted the function created by
    2102 %% \code{Interpolation\_function} will be a function of \code{t} only.
    2103 
    2104 %% Since, in practice, values need to be computed at specified points,
    2105 %% the syntax allows the user to specify, once and for all, a list
    2106 %% \code{interpolation\_points} of points at which values are required.
    2107 %% In this case, the function may be called using the form \code{f(t,
    2108 %% id)}, where \code{id} is an index for the list
    2109 %% \code{interpolation\_points}.
    2110 
    2111 %% \end{classdesc}
    2112 
    2113 %%%
    2114 %\begin{funcdesc}{set\_region}{functions}
    2115 %[Low priority. Will be merged into set\_quantity]
    2116 
    2117 %Module:\module{abstract\_2d\_finite\_volumes.domain}
    2118 %\end{funcdesc}
     2248\begin{classdesc}{\emph{<callable_object>} = Interpolation_function}{time,
     2249                                          quantities,
     2250                                          quantity_names=None,
     2251                                          vertex_coordinates=None,
     2252                                          triangles=None,
     2253                                          interpolation_points=None,
     2254                                          time_thinning=1,
     2255                                          verbose=False,
     2256                                          gauge_neighbour_id=None}
     2257Module: \module{fit_interpolate.interpolate}
     2258
     2259Given a time series (i.e. a series of values associated with
     2260different times) whose values are either just numbers or a set of
     2261numbers defined at the vertices of a triangular mesh (such as those
     2262stored in SWW files), \code{Interpolation_function} is used to
     2263create a callable object that interpolates a value for an arbitrary
     2264time \code{t} within the model limits and possibly a point \code{(x, y)}
     2265within a mesh region.
     2266
     2267The actual time series at which data is available is specified by
     2268means of an array \code{time} of monotonically increasing times. The
     2269quantities containing the values to be interpolated are specified in
     2270an array -- or dictionary of arrays (used in conjunction with the
     2271optional argument \code{quantity\_names}) -- called
     2272\code{quantities}. The optional arguments \code{vertex_coordinates}
     2273and \code{triangles} represent the spatial mesh associated with the
     2274quantity arrays. If omitted the function created by
     2275\code{Interpolation_function} will be a function of \code{t} only.
     2276
     2277Since, in practice, values need to be computed at specified points,
     2278the syntax allows the user to specify, once and for all, a list
     2279\code{interpolation_points} of points at which values are required.
     2280In this case, the function may be called using the form \code{f(t, id)},
     2281where \code{id} is an index for the list \code{interpolation_points}.
     2282\end{classdesc}
    21192283
    21202284
     
    21232287
    21242288\anuga provides a large number of predefined boundary conditions,
    2125 represented by objects such as \code{Reflective\_boundary(domain)} and
    2126 \code{Dirichlet\_boundary([0.2, 0.0, 0.0])}, described in the examples
     2289represented by objects such as \code{Reflective_boundary(domain)} and
     2290\code{Dirichlet_boundary([0.2, 0.0, 0.0])}, described in the examples
    21272291in Chapter 2. Alternatively, you may prefer to ''roll your own'',
    21282292following the method explained in Section \ref{sec:roll your own}.
    21292293
    2130 These boundary objects may be used with the function \code{set\_boundary} described below
     2294These boundary objects may be used with the function \code{set_boundary} described below
    21312295to assign boundary conditions according to the tags used to label boundary segments.
    21322296
    2133 \begin{methoddesc}{set\_boundary}{boundary_map}
    2134   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2135 
    2136   This function allows you to assign a boundary object (corresponding to a
    2137   pre-defined or user-specified boundary condition) to every boundary segment that
    2138   has been assigned a particular tag.
    2139 
    2140   This is done by specifying a dictionary \code{boundary\_map}, whose values are the boundary objects
    2141   and whose keys are the symbolic tags.
    2142 \end{methoddesc}
    2143 
    2144 \begin{methoddesc} {get\_boundary\_tags}{}
    2145   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2146 
    2147   Returns a list of the available boundary tags.
     2297\begin{methoddesc}{\emph{<domain>}.set_boundary}{boundary_map}
     2298Module: \module{abstract_2d_finite_volumes.domain}
     2299
     2300This function allows you to assign a boundary object (corresponding to a
     2301pre-defined or user-specified boundary condition) to every boundary segment that
     2302has been assigned a particular tag.
     2303
     2304\code{boundary_map} is a dictionary of boundary objects keyed by symbolic tags.
     2305\end{methoddesc}
     2306
     2307\begin{methoddesc} {\emph{<domain>}.get_boundary_tags}{}
     2308Module: \module{abstract\_2d\_finite\_volumes.domain}
     2309
     2310Returns a list of the available boundary tags.
    21482311\end{methoddesc}
    21492312
    21502313\subsection{Predefined boundary conditions}
    21512314
    2152 \begin{classdesc}{Reflective\_boundary}{Boundary}
    2153   Module: \module{shallow\_water}
    2154 
    2155   Reflective boundary returns same conserved quantities as those present in
    2156   the neighbouring volume but reflected.
    2157 
    2158   This class is specific to the shallow water equation as it works with the
    2159   momentum quantities assumed to be the second and third conserved quantities.
     2315\begin{classdesc}{Reflective_boundary}{domain=None}
     2316Module: \module{shallow_water}
     2317
     2318Reflective boundary returns same conserved quantities as those present in
     2319the neighbouring volume but reflected.
     2320
     2321This class is specific to the shallow water equation as it works with the
     2322momentum quantities assumed to be the second and third conserved quantities.
    21602323\end{classdesc}
    21612324
    2162 \begin{classdesc}{Transmissive\_boundary}{domain=None}
     2325\begin{classdesc}{Transmissive_boundary}{domain=None}
    21632326  \label{pg: transmissive boundary}
    2164   Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2165 
    2166   A transmissive boundary returns the same conserved quantities as
    2167   those present in the neighbouring volume.
    2168 
    2169   The underlying domain must be specified when the boundary is instantiated.
     2327Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions}
     2328
     2329A transmissive boundary returns the same conserved quantities as
     2330those present in the neighbouring volume.
     2331
     2332The underlying domain must be specified when the boundary is instantiated.
    21702333\end{classdesc}
    21712334
    2172 \begin{classdesc}{Dirichlet\_boundary}{conserved_quantities=None}
    2173   Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2174 
    2175   A Dirichlet boundary returns constant values for each of conserved
    2176   quantities. In the example of \code{Dirichlet\_boundary([0.2, 0.0, 0.0])},
    2177   the \code{stage} value at the boundary is 0.2 and the \code{xmomentum} and
    2178   \code{ymomentum} at the boundary are set to 0.0. The list must contain
    2179   a value for each conserved quantity.
     2335\begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None}
     2336Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions}
     2337
     2338A Dirichlet boundary returns constant values for each of conserved
     2339quantities. In the example of \code{Dirichlet_boundary([0.2, 0.0, 0.0])},
     2340the \code{stage} value at the boundary is 0.2 and the \code{xmomentum} and
     2341\code{ymomentum} at the boundary are set to 0.0. The list must contain
     2342a value for each conserved quantity.
    21802343\end{classdesc}
    21812344
    2182 \begin{classdesc}{Time\_boundary}{domain = None, f = None}
    2183   Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2184 
    2185   A time-dependent boundary returns values for the conserved
    2186   quantities as a function \code{f(t)} of time. The user must specify
    2187   the domain to get access to the model time.
    2188 
    2189   Optional argument \code{default\_boundary} can be used to specify another boundary object
    2190   to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}.
    2191   The \code{default\_boundary} could be a simple Dirichlet condition or
    2192   even another \code{Time\_boundary} typically using data pertaining to another time interval.
     2345\begin{classdesc}{Time_boundary}{domain=None,
     2346                                 function=None,
     2347                                 default_boundary=None,
     2348                                 verbose=False}
     2349Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions}
     2350
     2351A time-dependent boundary returns values for the conserved
     2352quantities as a function of time \code{function(t)}. The user must specify
     2353the domain to get access to the model time.
     2354
     2355Optional argument \code{default_boundary} can be used to specify another boundary object
     2356to be used in case model time exceeds the time available in the file used by \code{File_boundary}.
     2357The \code{default_boundary} could be a simple Dirichlet condition or
     2358even another \code{Time_boundary} typically using data pertaining to another time interval.
    21932359\end{classdesc}
    21942360
    2195 \begin{classdesc}{File\_boundary}{Boundary}
    2196   Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2197 
    2198   This method may be used if the user wishes to apply a SWW file, STS file or
    2199   a time series file (TMS) to a boundary segment or segments.
    2200   The boundary values are obtained from a file and interpolated to the
    2201   appropriate segments for each conserved quantity.
    2202 
    2203   Optional argument \code{default\_boundary} can be used to specify another boundary object
    2204   to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}.
    2205   The \code{default\_boundary} could be a simple Dirichlet condition or
    2206   even another \code{File\_boundary} typically using data pertaining to another time interval.
     2361\begin{classdesc}{File_boundary}{filename,
     2362                                 domain,
     2363                                 time_thinning=1,
     2364                                 time_limit=None,
     2365                                 boundary_polygon=None,
     2366                                 default_boundary=None,
     2367                                 use_cache=False,
     2368                                 verbose=False}
     2369Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions}
     2370
     2371This method may be used if the user wishes to apply a SWW file, STS file or
     2372a time series file (TMS) to a boundary segment or segments.
     2373The boundary values are obtained from a file and interpolated to the
     2374appropriate segments for each conserved quantity.
     2375
     2376Optional argument \code{default_boundary} can be used to specify another boundary object
     2377to be used in case model time exceeds the time available in the file used by \code{File_boundary}.
     2378The \code{default_boundary} could be a simple Dirichlet condition or
     2379even another \code{File_boundary} typically using data pertaining to another time interval.
    22072380\end{classdesc}
    22082381
    2209 \begin{classdesc}{Field\_boundary}{Boundary}
    2210   Module: \module{shallow\_water.shallow\_water\_domain}
    2211 
    2212   This method works in the same way as \code{File\_boundary} except that it
    2213   allows for the value of stage to be offset by a constant specified in the
    2214   keyword argument \code{mean\_stage}.
    2215 
    2216   This functionality allows for models to be run for a range of tides using
    2217   the same boundary information (from .sts, .sww or .tms files). The tidal value
    2218   for each run would then be specified in the keyword argument
    2219   \code{mean\_stage}.
    2220   If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary}
    2221   behave identically.
    2222 
    2223   Note that if the optional argument \code{default\_boundary} is specified
    2224   it's stage value will be adjusted by \code{mean\_stage} just like the values
    2225   obtained from the file.
    2226 
    2227   See \code{File\_boundary} for further details.
     2382\begin{classdesc}{Field_boundary}{filename,
     2383                                  domain,
     2384                                  mean_stage=0.0,
     2385                                  time_thinning=1,
     2386                                  time_limit=None,
     2387                                  boundary_polygon=None,
     2388                                  default_boundary=None,
     2389                                  use_cache=False,
     2390                                  verbose=False}
     2391Module: \module{shallow_water.shallow_water_domain}
     2392
     2393This method works in the same way as \code{File_boundary} except that it
     2394allows for the value of stage to be offset by a constant specified in the
     2395keyword argument \code{mean_stage}.
     2396
     2397This functionality allows for models to be run for a range of tides using
     2398the same boundary information (from STS, SWW or TMS files). The tidal value
     2399for each run would then be specified in the keyword argument \code{mean_stage}.
     2400If \code{mean_stage} = 0.0, \code{Field_boundary} and \code{File_boundary}
     2401behave identically.
     2402
     2403Note that if the optional argument \code{default_boundary} is specified
     2404its stage value will be adjusted by \code{mean_stage} just like the values
     2405obtained from the file.
     2406
     2407See \code{File_boundary} for further details.
    22282408\end{classdesc}
    22292409
    2230 \begin{classdesc}{Transmissive\_momentum\_set\_stage\_boundary}{Boundary}
    2231   Module: \module{shallow\_water}
    2232   \label{pg: transmissive momentum set stage boundary}
    2233 
    2234   This boundary returns same momentum conserved quantities as
    2235   those present in its neighbour volume but sets stage as in a Time\_boundary.
    2236   The underlying domain must be specified when boundary is instantiated
    2237 
    2238   This type of boundary is useful when stage is known at the boundary as a
    2239   function of time, but momenta (or speeds) aren't.
    2240 
    2241   This class is specific to the shallow water equation as it works with the
    2242   momentum quantities assumed to be the second and third conserved quantities.
    2243 
    2244   In some circumstances, this boundary condition may cause numerical instabilities for similar
    2245   reasons as what has been observed with the simple fully transmissive boundary condition
    2246   (see Page \pageref{pg: transmissive boundary}).
    2247   This could for example be the case if a planar wave is reflected out through this boundary.
     2410\begin{classdesc}{Transmissive_momentum_set_stage_boundary}{domain=None,
     2411                                                            function=None}
     2412Module: \module{shallow_water.shallow_water_domain}
     2413\label{pg: transmissive momentum set stage boundary}
     2414
     2415This boundary returns the same momentum conserved quantities as
     2416those present in its neighbour volume but sets stage as in a \code{Time_boundary}.
     2417The underlying domain must be specified when boundary is instantiated.
     2418
     2419This type of boundary is useful when stage is known at the boundary as a
     2420function of time, but momenta (or speeds) aren't.
     2421
     2422This class is specific to the shallow water equation as it works with the
     2423momentum quantities assumed to be the second and third conserved quantities.
     2424
     2425In some circumstances, this boundary condition may cause numerical instabilities for similar
     2426reasons as what has been observed with the simple fully transmissive boundary condition
     2427(see Page \pageref{pg: transmissive boundary}).
     2428This could for example be the case if a planar wave is reflected out through this boundary.
    22482429\end{classdesc}
    22492430
    2250 \begin{classdesc}{Transmissive\_stage\_zero\_momentum\_boundary}{Boundary}
    2251   Module: \module{shallow\_water}
    2252   \label{pg: transmissive stage zero momentum boundary}
    2253 
    2254   This boundary returns same stage conserved quantities as
    2255   those present in its neighbour volume but sets momentum to zero.
    2256   The underlying domain must be specified when boundary is instantiated
    2257 
    2258   This type of boundary is useful when stage is known at the boundary as a
    2259   function of time, but momentum should be set to zero. This is for example
    2260   the case where a boundary is needed in the ocean on the two sides perpendicular
    2261   to the coast to maintain the wave height of the incoming wave.
    2262 
    2263   This class is specific to the shallow water equation as it works with the
    2264   momentum quantities assumed to be the second and third conserved quantities.
    2265 
    2266   This boundary condition should not cause the numerical instabilities seen with the transmissive momentum
    2267   boundary conditions (see Page \pageref{pg: transmissive boundary} and
    2268   Page \pageref{pg: transmissive momentum set stage boundary}).
     2431\begin{classdesc}{Transmissive_stage_zero_momentum_boundary}{domain=None}
     2432Module: \module{shallow_water}
     2433\label{pg: transmissive stage zero momentum boundary}
     2434
     2435This boundary returns same stage conserved quantities as
     2436those present in its neighbour volume but sets momentum to zero.
     2437The underlying domain must be specified when boundary is instantiated
     2438
     2439This type of boundary is useful when stage is known at the boundary as a
     2440function of time, but momentum should be set to zero. This is for example
     2441the case where a boundary is needed in the ocean on the two sides perpendicular
     2442to the coast to maintain the wave height of the incoming wave.
     2443
     2444This class is specific to the shallow water equation as it works with the
     2445momentum quantities assumed to be the second and third conserved quantities.
     2446
     2447This boundary condition should not cause the numerical instabilities seen with the transmissive momentum
     2448boundary conditions (see Page \pageref{pg: transmissive boundary} and
     2449Page \pageref{pg: transmissive momentum set stage boundary}).
    22692450\end{classdesc}
    22702451
    2271 \begin{classdesc}{Dirichlet\_discharge\_boundary}{Boundary}
    2272   Module: \module{shallow\_water}
    2273 
    2274   Sets stage (stage0)
    2275   Sets momentum (wh0) in the inward normal direction.
     2452\begin{classdesc}{Dirichlet_discharge_boundary}{domain=None, stage0=None, wh0=None}
     2453Module: \module{shallow_water.shallow_water_domain}
     2454
     2455\code{stage0} sets the stage.
     2456
     2457\code{wh0} sets momentum in the inward normal direction.
    22762458\end{classdesc}
    22772459
     
    22802462
    22812463All boundary classes must inherit from the generic boundary class
    2282 \code{Boundary} and have a method called \code{evaluate} which must
    2283 take as inputs \code{self, vol\_id, edge\_id} where self refers to the
    2284 object itself and vol\_id and edge\_id are integers referring to
     2464\code{Boundary} and have a method called \code{evaluate()} which must
     2465take as inputs \code{self}, \code{vol_id} and \code{edge_id} where \code{self} refers to the
     2466object itself and \code{vol_id} and \code{edge_id} are integers referring to
    22852467particular edges. The method must return a list of three floating point
    22862468numbers representing values for \code{stage},
     
    22882470
    22892471The constructor of a particular boundary class may be used to specify
    2290 particular values or flags to be used by the \code{evaluate} method.
     2472particular values or flags to be used by the \code{evaluate()} method.
    22912473Please refer to the source code for the existing boundary conditions
    22922474for examples of how to implement boundary conditions.
     
    22992481Gravity and friction are always calculated using the elevation and friction quantities,
    23002482but the user may additionally add forcing terms to the list
    2301 \code{domain.forcing\_terms} and have them affect the model.
    2302 
    2303 Currently, predefined forcing terms are:
    2304 \begin{funcdesc}{General\_forcing}{}
    2305   Module: \module{shallow\_water.shallow\_water\_domain}
    2306 
    2307   This is a general class to modify any quantity according to a given rate of change.
    2308   Other specific forcing terms are based on this class but it can be used by itself as well (e.g.\ to modify momentum).
    2309 
    2310   The General\_forcing class takes as input:
    2311   \begin{itemize}
    2312     \item \code{domain}: a reference to the domain being evolved
    2313     \item \code{quantity\_name}: The name of the quantity that will be affected by this forcing term
    2314     \item \code{rate}: The rate at which the quantity should change. The parameter \code{rate} can be eithe a constant or a
    2315                 function of time. Positive values indicate increases,
    2316                 negative values indicate decreases.
    2317                 The parametr \code{rate} can be \code{None} at initialisation but must be specified
    2318                 before forcing term is applied (i.e. simulation has started).
    2319                 The default value is 0.0 -- i.e.\ no forcing.
    2320     \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
    2321     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.
    2322   \end{itemize}
    2323   Note specifying both center, radius and polygon will cause an exception to be thrown.
    2324   Moreover, if the specified polygon or circle does not lie fully within the mesh boundary an Exception will be thrown.
    2325 
    2326   \bigskip
    2327   Example:
    2328 
    2329   \begin{verbatim}
     2483\code{domain.forcing_terms} and have them affect the model.
     2484
     2485Currently, predefined forcing terms are: \\
     2486\begin{classdesc}{General_forcing}{domain,
     2487                                  quantity_name,
     2488                                  rate=0.0,
     2489                                  center=None,
     2490                                  radius=None,
     2491                                  polygon=None,
     2492                                  default_rate=None,
     2493                                  verbose=False}
     2494Module: \module{shallow_water.shallow_water_domain}
     2495
     2496This is a general class to modify any quantity according to a given rate of change.
     2497Other specific forcing terms are based on this class but it can be used by itself as well (e.g. to modify momentum).
     2498
     2499\code{domain} is the domain being evolved.
     2500
     2501\code{quantity_name} is the name of the quantity that will be affected by this forcing term.
     2502
     2503\code{rate} is the rate at which the quantity should change. This can be either a constant or a
     2504function of time. Positive values indicate increases, negative values indicate decreases.
     2505The parameter \code{rate} can be \code{None} at initialisation but must be specified
     2506before a forcing term is applied (i.e. simulation has started).
     2507The default value is 0.0 -- i.e. no forcing.
     2508
     2509\code{center} and \code{ radius} optionally restrict forcing to a circle with given center and radius.
     2510
     2511\code{polygon} optionally restricts forcing to an area enclosed by the given polygon.
     2512
     2513Note: specifying \code{center}, \code{radius} and \code{polygon} will cause an exception to be thrown.
     2514Moreover, if the specified polygon or circle does not lie fully within the mesh boundary an Exception will be thrown.
     2515
     2516Example:
     2517
     2518\begin{verbatim}
    23302519P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]]    # Square polygon
    23312520
     
    23382527domain.forcing_terms.append(xmom)
    23392528domain.forcing_terms.append(ymom)
    2340   \end{verbatim}
    2341 
    2342   Here, \code{f}, \code{g} are assumed to be defined as functions of time providing
    2343   a time dependent rate of change for xmomentum and ymomentum respectively.
    2344   P is assumed to be polygon, specified as a list of points.
    2345 \end{funcdesc}
    2346 
    2347 \begin{funcdesc}{Inflow}{}
    2348   Module: \module{shallow\_water.shallow\_water\_domain}
    2349 
    2350   This is a general class for inflow and abstraction of water according to a given rate of change.
    2351   This class will always modify the \code{stage} quantity.
    2352 
    2353   Inflow is based on the General_forcing class so the functionality is similar.
    2354 
    2355   The Inflow class takes as input:
    2356   \begin{itemize}
    2357     \item \code{domain}: a reference to the domain being evolved
    2358     \item \code{rate}: The flow rate in $m^3/s$ at which the stage should change. The parameter \code{rate} can be eithe a constant or a
    2359                 function of time. Positive values indicate inflow,
    2360                 negative values indicate outflow.
    2361 
    2362                 Note: The specified flow will be divided by the area of
    2363                 the inflow region and then applied to update the
    2364                 stage quantity.
    2365     \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
    2366     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.
    2367   \end{itemize}
    2368 
    2369   \bigskip
    2370   Example:
    2371 
    2372   \begin{verbatim}
    2373 hydrograph = Inflow(center=(320, 300), radius=10, rate=file_function('QPMF_Rot_Sub13.tms'))
     2529\end{verbatim}
     2530
     2531Here, \code{f} and \code{g} are assumed to be defined as functions of time providing
     2532a time dependent rate of change for xmomentum and ymomentum respectively.
     2533\code{P} is assumed to be the polygon, specified as a list of points.
     2534\end{classdesc}
     2535
     2536\begin{classdesc}{Inflow}{domain,
     2537                         rate=0.0,
     2538                         center=None, radius=None,
     2539                         polygon=None,
     2540                         default_rate=None,
     2541                         verbose=False}
     2542Module: \module{shallow_water.shallow_water_domain}
     2543
     2544This is a general class for inflow and abstraction of water according to a given rate of change.
     2545This class will always modify the \code{stage} quantity.
     2546
     2547Inflow is based on the \code{General_forcing} class so the functionality is similar.
     2548
     2549\code{domain} is the domain being evolved.
     2550
     2551\code{rate} is the flow rate ($m^3/s$) at which the quantity should change. This can be either a constant or a
     2552function of time. Positive values indicate inflow, negative values indicate outflow.
     2553Note: The specified flow will be divided by the area of the inflow region and then applied to update the
     2554stage quantity.
     2555
     2556\code{center} and \code{ radius} optionally restrict forcing to a circle with given center and radius.
     2557
     2558\code{polygon} optionally restricts forcing to an area enclosed by the given polygon.
     2559
     2560Example:
     2561
     2562\begin{verbatim}
     2563hydrograph = Inflow(center=(320, 300), radius=10,
     2564                    rate=file_function('QPMF_Rot_Sub13.tms'))
    23742565
    23752566domain.forcing_terms.append(hydrograph)
    2376   \end{verbatim}
    2377 
    2378   Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for a hydrograph.
    2379 \end{funcdesc}
    2380 
    2381 \begin{funcdesc}{Rainfall}{}
    2382   Module: \module{shallow\_water.shallow\_water\_domain}
    2383 
    2384   This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon.
    2385   This class will always modify the \code{stage} quantity.
    2386 
    2387   Rainfall is based on the General_forcing class so the functionality is similar.
    2388 
    2389   The Rainfall class takes as input:
    2390   \begin{itemize}
    2391     \item \code{domain}: a reference to the domain being evolved
    2392     \item \code{rate}: Total rain rate over the specified domain.
    2393                   Note: Raingauge Data needs to reflect the time step.
    2394                   For example: if rain gauge is mm read every \code{dt} seconds, then the input
    2395                   here is as \code{mm/dt} so 10 mm in 5 minutes becomes
    2396                   10/(5x60) = 0.0333mm/s.
    2397 
    2398                   This parameter can be either a constant or a
    2399                   function of time. Positive values indicate rain being added (or be used for general infiltration),
    2400                   negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction).
    2401     \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
    2402     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.
    2403   \end{itemize}
    2404 
    2405   \bigskip
    2406   Example:
    2407 
    2408   \begin{verbatim}
     2567\end{verbatim}
     2568
     2569Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the TMS format defining a timeseries for a hydrograph.
     2570\end{classdesc}
     2571
     2572\begin{classdesc}{Rainfall}{domain,
     2573                           rate=0.0,
     2574                           center=None,
     2575                           radius=None,
     2576                           polygon=None,
     2577                           default_rate=None,
     2578                           verbose=False}
     2579Module: \module{shallow_water.shallow_water_domain}
     2580
     2581This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon.
     2582This class will always modify the \code{stage} quantity.
     2583
     2584Rainfall is based on the \code{General_forcing} class so the functionality is similar.
     2585
     2586\code{domain} is the domain being evolved.
     2587
     2588\code{rate} is the total rain rate over the specified domain.
     2589Note: Raingauge Data needs to reflect the time step.
     2590For example, if rain gauge is \code{mm} read every \code{dt} seconds, then the input
     2591here is as \code{mm/dt} so 10 mm in 5 minutes becomes
     259210/(5x60) = 0.0333mm/s.  This parameter can be either a constant or a
     2593function of time. Positive values indicate rain being added (or be used for general infiltration),
     2594negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction).
     2595
     2596\code{center} and \code{ radius} optionally restrict forcing to a circle with given center and radius.
     2597
     2598\code{polygon} optionally restricts forcing to an area enclosed by the given polygon.
     2599
     2600Example:
     2601
     2602\begin{verbatim}
    24092603catchmentrainfall = Rainfall(rate=file_function('Q100_2hr_Rain.tms'))
    24102604domain.forcing_terms.append(catchmentrainfall)
    2411   \end{verbatim}
    2412 
    2413   Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for the rainfall.
    2414 \end{funcdesc}
    2415 
    2416 \begin{funcdesc}{Culvert\_flow}{}
    2417   Module: \module{culver\_flows.culvert\_class}
    2418 
    2419   This is a general class for implementing flow through a culvert.
    2420   This class modifies the quantities \code{stage, xmomentum, ymomentum} in areas at both ends of the culvert.
    2421 
    2422   The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities.
    2423   The flow drection is determined on-the-fly so openings are referenced simple as opening0 and opening1
    2424   with either being able to take the role as Inflow and Outflow.
    2425 
    2426   The Culvert\_flow class takes as input:
    2427   \begin{itemize}
    2428     \item \code{domain}: a reference to the domain being evolved
    2429     \item \code{label}: Short text naming the culvert
    2430     \item \code{description}: Text describing it
    2431     \item \code{end_point0}: Coordinates of one opening
    2432     \item \code{end_point1}: Coordinates of other opening
    2433     \item \code{width}:
    2434     \item \code{height}:
    2435     \item \code{diameter}:
    2436     \item \code{manning}: Mannings Roughness for Culvert
    2437     \item \code{invert_level0}: Invert level if not the same as the Elevation on the Domain
    2438     \item \code{invert_level1}: Invert level if not the same as the Elevation on the Domain
    2439     \item \code{culvert_routine}: Function specifying the calculation of flow based on energy difference between the two openings (see below)
    2440     \item \code{number_of_barrels}: Number of identical pipes in the culvert. Default == 1.
    2441   \end{itemize}
    2442 
    2443   The user can specify different culvert routines. Hower ANUGA currently provides only one, namely the
    2444   \code{boyd\_generalised\_culvert\_model} as used in the example below.
    2445 
    2446   Example:
    2447 
    2448   \begin{verbatim}
     2605\end{verbatim}
     2606
     2607Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the TMS format defining a timeseries for the rainfall.
     2608\end{classdesc}
     2609
     2610\begin{classdesc}{Culvert_flow}{domain,
     2611                 culvert_description_filename=None,
     2612                 culvert_routine=None,
     2613                 end_point0=None,
     2614                 end_point1=None,
     2615                 enquiry_point0=None,
     2616                 enquiry_point1=None,
     2617                 type='box',
     2618                 width=None,
     2619                 height=None,
     2620                 length=None,
     2621                 number_of_barrels=1,
     2622                 trigger_depth=0.01,
     2623                 manning=None,
     2624                 sum_loss=None,
     2625                 use_velocity_head=False,
     2626                 use_momentum_jet=False,
     2627                 label=None,
     2628                 description=None,
     2629                 update_interval=None,
     2630                 log_file=False,
     2631                 discharge_hydrograph=False,
     2632                 verbose=False}
     2633Module: \module{culvert_flows.culvert_class}
     2634
     2635This is a general class for implementing flow through a culvert.
     2636This class modifies the quantities \code{stage}, \code{xmomentum} and \code{ymomentum} in areas at both ends of the culvert.
     2637
     2638The \code{Culvert_flow} forcing term uses \code{Inflow} and \code{General_forcing} to update the quantities.
     2639The flow direction is determined on-the-fly so openings are referenced simple as opening0 and opening1
     2640with either being able to take the role as Inflow or Outflow.
     2641
     2642The Culvert_flow class takes as input:
     2643\begin{itemize}
     2644  \item \code{domain}: a reference to the domain being evolved
     2645  \item \code{culvert_description_filename}:
     2646  \item \code{culvert_routine}:
     2647  \item \code{end_point0}: Coordinates of one opening
     2648  \item \code{end_point1}: Coordinates of other opening
     2649  \item \code{enquiry_point0}:
     2650  \item \code{enquiry_point1}:
     2651  \item \code{type}: (default is 'box')
     2652  \item \code{width}:
     2653  \item \code{height}:
     2654  \item \code{length}:
     2655  \item \code{number_of_barrels}: Number of identical pipes in the culvert (default is 1)
     2656  \item \code{trigger_depth}: (default is 0.01)
     2657  \item \code{manning}: Mannings Roughness for Culvert
     2658  \item \code{sum_loss}:
     2659  \item \code{use_velocity_head}:
     2660  \item \code{use_momentum_jet}:
     2661  \item \code{label}: Short text naming the culvert
     2662  \item \code{description}: Text describing the culvert
     2663  \item \code{update_interval}:
     2664  \item \code{log_file}:
     2665  \item \code{discharge_hydrograph}:
     2666\end{itemize}
     2667
     2668The user can specify different culvert routines. Hower \anuga currently provides only one, namely the
     2669\code{boyd_generalised_culvert_model} as used in the example below:
     2670
     2671\begin{verbatim}
    24492672from anuga.culvert_flows.culvert_class import Culvert_flow
    24502673from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model
     
    24552678                        end_point0=[9.0, 2.5],
    24562679                        end_point1=[13.0, 2.5],
    2457                         width=1.20,height=0.75,
     2680                        width=1.20,
     2681                        height=0.75,
    24582682                        culvert_routine=boyd_generalised_culvert_model,
    24592683                        number_of_barrels=1,
     
    24732697domain.forcing_terms.append(culvert1)
    24742698domain.forcing_terms.append(culvert2)
    2475   \end{verbatim}
    2476 \end{funcdesc}
     2699\end{verbatim}
     2700\end{classdesc}
    24772701
    24782702
     
    24802704\label{sec:evolution}
    24812705
    2482 \begin{methoddesc}{evolve}{yieldstep=None, finaltime=None, duration=None, skip_initial_step=False}
    2483   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2484 
    2485   This function (a method of \class{domain}) is invoked once all the
    2486   preliminaries have been completed, and causes the model to progress
    2487   through successive steps in its evolution, storing results and
    2488   outputting statistics whenever a user-specified period
    2489   \code{yieldstep} is completed (generally during this period the
    2490   model will evolve through several steps internally
    2491   as the method forces the water speed to be calculated
    2492   on successive new cells).
    2493  
    2494   The code specified by the user in the block following the evolve statement is only executed once every \code{yieldstep} even though
    2495   ANUGA typically will take many more internal steps behind the scenes.
    2496  
    2497   The user
    2498   specifies the total time period over which the evolution is to take
    2499   place, by specifying values (in seconds) for either \code{duration}
    2500   or \code{finaltime}, as well as the interval in seconds after which
    2501   results are to be stored and statistics output.
    2502 
    2503   You can include \method{evolve} in a statement of the type:
    2504 
    2505   \begin{verbatim}
     2706\begin{methoddesc}{\emph{<domain>}.evolve}{yieldstep=None,
     2707                                           finaltime=None,
     2708                                           duration=None,
     2709                                           skip_initial_step=False}
     2710Module: \module{abstract_2d_finite_volumes.domain}
     2711
     2712This method is invoked once all the
     2713preliminaries have been completed, and causes the model to progress
     2714through successive steps in its evolution, storing results and
     2715outputting statistics whenever a user-specified period
     2716\code{yieldstep} is completed.  Generally during this period the
     2717model will evolve through several steps internally
     2718as the method forces the water speed to be calculated
     2719on successive new cells.
     2720
     2721\code{yieldstep} is the interval in seconds between yields where results are
     2722stored, statistics written and the domain is inspected or possibly modified.
     2723If omitted an internal predefined \code{yieldstep} is used.  Internally, smaller
     2724timesteps may be taken.
     2725
     2726\code{duration} is the duration of the simulation in seconds.
     2727
     2728\code{finaltime} is the time in seconds where simulation should end. This is currently
     2729relative time, so it's the same as \code{duration}.  If both \code{duration} and
     2730\code{finaltime} are given an exception is thrown.
     2731
     2732\code{skip_initial_step} is a boolean flag that decides whether the first
     2733yield step is skipped or not. This is useful for example to avoid
     2734duplicate steps when multiple evolve processes are dove tailed.
     2735
     2736The code specified by the user in the block following the evolve statement is
     2737only executed once every \code{yieldstep} even though
     2738\anuga typically will take many more internal steps behind the scenes.
     2739
     2740You can include \method{evolve} in a statement of the type:
     2741
     2742\begin{verbatim}
    25062743for t in domain.evolve(yieldstep, finaltime):
    25072744    <Do something with domain and t>
    2508   \end{verbatim}
     2745\end{verbatim}
    25092746\end{methoddesc}
    25102747
     
    25122749\label{sec:diagnostics}
    25132750
    2514 \begin{funcdesc}{statistics}{}
    2515   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2516 
    2517 \end{funcdesc}
    2518 
    2519 \begin{funcdesc}{timestepping\_statistics}{}
    2520   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2521 
    2522   Returns a string of the following type for each timestep:
    2523   \code{Time = 0.9000, delta t in [0.00598964, 0.01177388], steps=12
    2524   (12)}
    2525 
    2526   Here the numbers in \code{steps=12 (12)} indicate the number of steps taken and
    2527   the number of first-order steps, respectively.\\
    2528 
    2529   The optional keyword argument \code{track_speeds=True} will
    2530   generate a histogram of speeds generated by each triangle. The
    2531   speeds relate to the size of the timesteps used by ANUGA and
    2532   this diagnostics may help pinpoint problem areas where excessive speeds
    2533   are generated.
    2534 \end{funcdesc}
    2535 
    2536 \begin{funcdesc}{boundary\_statistics}{quantities=None, tags=None}
    2537   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2538 
    2539   Returns a string of the following type when \code{quantities = 'stage'}
    2540   and \code{tags = ['top', 'bottom']}:
    2541 
    2542   \begin{verbatim}
     2751\begin{methoddesc}{\emph{<domain>}.statistics}{}
     2752Module: \module{abstract\_2d\_finite\_volumes.domain}
     2753
     2754Outputs statistics about the mesh within the \code{Domain}.
     2755\end{methoddesc}
     2756
     2757\begin{methoddesc}{\emph{<domain>}.timestepping_statistics}{track_speeds=False, triangle_id=None}
     2758Module: \module{abstract_2d_finite_volumes.domain}
     2759
     2760Returns a string of the following type for each timestep:\\
     2761\code{Time = 0.9000, delta t in [0.00598964, 0.01177388], steps=12 (12)}
     2762
     2763Here the numbers in \code{steps=12 (12)} indicate the number of steps taken and
     2764the number of first-order steps, respectively.
     2765
     2766The optional keyword argument \code{track_speeds} will
     2767generate a histogram of speeds generated by each triangle if set to \code{True}. The
     2768speeds relate to the size of the timesteps used by \anuga and
     2769this diagnostics may help pinpoint problem areas where excessive speeds
     2770are generated.
     2771
     2772The optional keyword argument \code{triangle_id} can be used to specify a particular
     2773triangle rather than the one with the largest speed.
     2774\end{methoddesc}
     2775
     2776\begin{methoddesc}{\emph{<domain>}.boundary_statistics}{quantities=None,
     2777                                                      tags=None}
     2778Module: \module{abstract_2d_finite_volumes.domain}
     2779
     2780Generates output about boundary forcing at each timestep.
     2781
     2782\code{quantities} names the quantities to be reported -- may be \code{None},
     2783a string or a list of strings.
     2784
     2785\code{tags} names the tags to be reported -- may be either None, a string or a list of strings.
     2786
     2787When \code{quantities = 'stage'} and \code{tags = ['top', 'bottom']}
     2788will return a string like:
     2789
     2790\begin{verbatim}
    25432791Boundary values at time 0.5000:
    25442792    top:
     
    25462794    bottom:
    25472795        stage in [ -0.27098821,  -0.02499974]
    2548   \end{verbatim}
    2549 \end{funcdesc}
    2550 
    2551 \begin{funcdesc}{get\_quantity}{name, location='vertices', indices=None}
    2552   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2553 
    2554   This function returns a Quantity object Q.
    2555   Access to its values should be done through Q.get\__values documented on Page \pageref{pg:get values}.
    2556 \end{funcdesc}
    2557 
    2558 \begin{funcdesc}{set\_quantities\_to\_be\_monitored}{}
    2559   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2560 
    2561   Selects quantities and derived quantities for which extrema attained at internal timesteps
    2562   will be collected.
    2563 
    2564   Information can be tracked in the evolve loop by printing \code{quantity\_statistics} and
    2565   collected data will be stored in the sww file.
    2566 
    2567   Optional parameters \code{polygon} and \code{time\_interval} may be specified to restrict the
    2568   extremum computation.
    2569 \end{funcdesc}
    2570 
    2571 \begin{funcdesc}{quantity\_statistics}{}
    2572   Module: \module{abstract\_2d\_finite\_volumes.domain}
    2573 
    2574   Reports on extrema attained by selected quantities.
    2575 
    2576   Returns a string of the following type for each
    2577   timestep:
    2578 
    2579   \begin{verbatim}
     2796\end{verbatim}
     2797\end{methoddesc}
     2798
     2799\begin{methoddesc}{Q = \emph{<domain>}.get_quantity}{name,
     2800                                               location='vertices',
     2801                                               indices=None}
     2802Module: \module{abstract_2d_finite_volumes.domain}
     2803
     2804This function returns a Quantity object Q.
     2805Access to its values should be done through \code{Q.get_values()} documented on Page \pageref{pg:get values}.
     2806
     2807\code{name} is the name of the quantity to retrieve.
     2808
     2809\code{location} is
     2810
     2811\code{indices} is
     2812\end{methoddesc}
     2813
     2814\begin{methoddesc}{\emph{<domain>}.set_quantities_to_be_monitored}{quantity,
     2815                                             polygon=None,
     2816                                             time_interval=None}
     2817Module: \module{abstract\_2d\_finite\_volumes.domain}
     2818
     2819Selects quantities and derived quantities for which extrema attained at internal timesteps
     2820will be collected.
     2821
     2822\code{quantity} specifies the quantity or quantities to be monitored and must be either:
     2823\begin{itemize}
     2824  \item the name of a quantity or derived quantity such as 'stage-elevation',
     2825  \item a list of quantity names, or
     2826  \item \code{None}.
     2827\end{itemize}
     2828
     2829\code{polygon} can be used to monitor only triangles inside the polygon. Otherwise
     2830all triangles will be included.
     2831
     2832\code{time_interval} will restrict monitoring to time steps in the interval. Otherwise
     2833all timesteps will be included.
     2834
     2835Information can be tracked in the evolve loop by printing \code{quantity_statistics} and
     2836collected data will be stored in the SWW file.
     2837\end{methoddesc}
     2838
     2839\begin{methoddesc}{\emph{<domain>}.quantity_statistics}{precision='\%.4f'}
     2840Module: \module{abstract_2d_finite_volumes.domain}
     2841
     2842Reports on extrema attained by selected quantities.
     2843
     2844Returns a string of the following type for each timestep:
     2845
     2846\begin{verbatim}
    25802847Monitored quantities at time 1.0000:
    25812848  stage-elevation:
     
    25912858    minimum attained at time = 0.00000000, location = (0.16666667, 0.33333333)
    25922859    maximum attained at time = 0.35103646, location = (0.83333333, 0.16666667)
    2593   \end{verbatim}
    2594 
    2595   The quantities (and derived quantities) listed here must be selected at model
    2596   initialisation using the method \code{domain.set_quantities_to_be_monitored}.\\
    2597 
    2598   The optional keyword argument \code{precision='\%.4f'} will
    2599   determine the precision used for floating point values in the output.
    2600   This diagnostics helps track extrema attained by the selected quantities
    2601   at every internal timestep.
    2602 
    2603   These values are also stored in the SWW file for post processing.
    2604 \end{funcdesc}
    2605 
    2606 \begin{funcdesc}{get\_values}{location='vertices', indices=None}
    2607   \label{pg:get values}
    2608   Module: \module{abstract\_2d\_finite\_volumes.quantity}
    2609 
    2610   Extract values for quantity as a numeric array.
    2611 
    2612   \begin{verbatim}
    2613 Inputs:
    2614   interpolation_points: List of x, y coordinates where value is
    2615                         sought (using interpolation). If points
    2616                         are given, values of location and indices
    2617                         are ignored. Assume either absolute UTM
    2618                         coordinates or geospatial data object.
     2860\end{verbatim}
     2861
     2862The quantities (and derived quantities) listed here must be selected at model
     2863initialisation time using the method \code{domain.set_quantities_to_be_monitored()}.
     2864
     2865The optional keyword argument \code{precision='\%.4f'} will
     2866determine the precision used for floating point values in the output.
     2867This diagnostics helps track extrema attained by the selected quantities
     2868at every internal timestep.
     2869
     2870These values are also stored in the SWW file for post-processing.
     2871\end{methoddesc}
     2872
     2873\begin{methoddesc}{\emph{<quantity>}.get_values}{interpolation_points=None,
     2874                   location='vertices',
     2875                   indices=None,
     2876                   use_cache=False,
     2877                   verbose=False}
     2878\label{pg:get values}
     2879Module: \module{abstract_2d_finite_volumes.quantity}
     2880
     2881Extract values for quantity as a numeric array.
     2882
     2883\code{interpolation_points} is a list of (x, y) coordinates where the value is
     2884sought (using interpolation). If \code{interpolation_points} is given, values
     2885for \code{location} and \code{indices} are ignored.
     2886Assume either an absolute UTM coordinates or geospatial data object.
    26192887   
    2620   location: Where values are to be stored.
    2621             Permissible options are: vertices, edges, centroids
    2622             and unique vertices. Default is 'vertices'
    2623   \end{verbatim}
    2624 
    2625   The returned values will have the leading dimension equal to length of the indices list or
    2626   N (all values) if indices is None.
    2627 
    2628   In case of location == 'centroids' the dimension of returned
    2629   values will be a list or a numeric array of length N, N being
    2630   the number of elements.
    2631        
    2632   In case of location == 'vertices' or 'edges' the dimension of
    2633   returned values will be of dimension Nx3
    2634 
    2635   In case of location == 'unique vertices' the average value at
    2636   each vertex will be returned and the dimension of returned values
    2637   will be a 1d array of length "number of vertices"
    2638        
    2639   Indices is the set of element ids that the operation applies to.
    2640 
    2641   The values will be stored in elements following their
    2642   internal ordering.
    2643 \end{funcdesc}
    2644 
    2645 \begin{funcdesc}{set\_values}{location='vertices', indices=None}
    2646   Module: \module{abstract\_2d\_finite\_volumes.quantity}
    2647 
    2648   Assign values to a quantity object.
    2649   This method works the same way as \code{set\_quantity} except that it doesn't take
    2650   a quantity name as the first argument. The reason to use \code{set\_values} is for
    2651   example to assign values to a new quantity that has been created but which is
    2652   not part of the domain's predefined quantities.
    2653 
    2654   The method \code{set\_values} is always called by \code{set\_quantity}
    2655   behind the scenes.
    2656 \end{funcdesc}
    2657 
    2658 \begin{funcdesc}{get\_integral}{}
    2659   Module: \module{abstract\_2d\_finite\_volumes.quantity}
    2660 
    2661   Return computed integral over entire domain for this quantity
    2662 \end{funcdesc}
    2663 
    2664 \begin{funcdesc}{get\_maximum\_value}{indices=None}
    2665   Module: \module{abstract\_2d\_finite\_volumes.quantity}
    2666 
    2667   Return maximum value of quantity (on centroids)
    2668 
    2669   Optional argument indices is the set of element ids that
    2670   the operation applies to. If omitted all elements are considered.
    2671 
    2672   We do not seek the maximum at vertices as each vertex can
    2673   have multiple values -- one for each triangle sharing it.
    2674 \end{funcdesc}
    2675 
    2676 \begin{funcdesc}{get\_maximum\_location}{indices=None}
    2677   Module: \module{abstract\_2d\_finite\_volumes.quantity}
    2678 
    2679   Return location of maximum value of quantity (on centroids)
    2680 
    2681   Optional argument indices is the set of element ids that
    2682   the operation applies to.
    2683 
    2684   We do not seek the maximum at vertices as each vertex can
    2685   have multiple values -- one for each triangle sharing it.
    2686 
    2687   If there are multiple cells with same maximum value, the
    2688   first cell encountered in the triangle array is returned.
    2689 \end{funcdesc}
    2690 
    2691 \begin{funcdesc}{get\_wet\_elements}{indices=None}
    2692   Module: \module{shallow\_water.shallow\_water\_domain}
    2693 
    2694   Return indices for elements where h $>$ minimum_allowed_height
    2695   Optional argument indices is the set of element ids that the operation applies to.
    2696 \end{funcdesc}
    2697 
    2698 \begin{funcdesc}{get\_maximum\_inundation\_elevation}{indices=None}
    2699   Module: \module{shallow\_water.shallow\_water\_domain}
    2700 
    2701   Return highest elevation where h $>$ 0.\\
    2702   Optional argument indices is the set of element ids that the operation applies to.\\
    2703 
    2704   Example to find maximum runup elevation:\\
    2705      z = domain.get_maximum_inundation_elevation()
    2706 \end{funcdesc}
    2707 
    2708 \begin{funcdesc}{get\_maximum\_inundation\_location}{indices=None}
    2709   Module: \module{shallow\_water.shallow\_water\_domain}
    2710 
    2711   Return location (x,y) of highest elevation where h $>$ 0.\\
    2712   Optional argument indices is the set of element ids that the operation applies to.\\
    2713 
    2714   Example to find maximum runup location:\\
    2715      x, y = domain.get_maximum_inundation_location()
    2716 \end{funcdesc}
     2888\code{location} specifies where values are to be stored.
     2889Permissible options are 'vertices', 'edges', 'centroids' or 'unique vertices'.
     2890
     2891The returned values will have the leading dimension equal to length of the \code{indices} list or
     2892N (all values) if \code{indices} is \code{None}.
     2893
     2894If \code{location} is 'centroids' the dimension of returned
     2895values will be a list or a numeric array of length N, N being
     2896the number of elements.
     2897     
     2898If \code{location} is 'vertices' or 'edges' the dimension of
     2899returned values will be of dimension \code{Nx3}.
     2900
     2901If \code{location} is 'unique vertices' the average value at
     2902each vertex will be returned and the dimension of returned values
     2903will be a 1d array of length "number of vertices"
     2904     
     2905\code{indices} is the set of element ids that the operation applies to.
     2906
     2907The values will be stored in elements following their internal ordering.
     2908\end{methoddesc}
     2909
     2910\begin{methoddesc}{\emph{<quantity>}.set_values}{numeric=None,
     2911                               quantity=None,
     2912                               function=None,
     2913                               geospatial_data=None,
     2914                               filename=None,
     2915                               attribute_name=None,
     2916                               alpha=None,
     2917                               location='vertices',
     2918                               polygon=None,
     2919                               indices=None,
     2920                               smooth=False,
     2921                               verbose=False,
     2922                               use_cache=False}
     2923Module: \module{abstract_2d_finite_volumes.quantity}
     2924
     2925Assign values to a quantity object.
     2926
     2927This method works the same way as \code{set_quantity()} except that it doesn't take
     2928a quantity name as the first argument since it is applied directly to the quantity.
     2929Use \code{set_values} is used to assign
     2930values to a new quantity that has been created but which is
     2931not part of the domain's predefined quantities.
     2932
     2933\code{location} is ??
     2934
     2935\code{indices} is ??
     2936
     2937The method \code{set_values()} is always called by \code{set_quantity()}
     2938behind the scenes.
     2939\end{methoddesc}
     2940
     2941\begin{methoddesc}{\emph{<quantity>}.get_integral}{}
     2942Module: \module{abstract_2d_finite_volumes.quantity}
     2943
     2944Return the computed integral over the entire domain for the quantity.
     2945\end{methoddesc}
     2946
     2947\begin{methoddesc}{\emph{<quantity>}.get_maximum_value}{indices=None}
     2948Module: \module{abstract_2d_finite_volumes.quantity}
     2949
     2950Return the maximum value of a quantity (on centroids).
     2951
     2952\code{indices} is the optional set of element \code{id}s that
     2953the operation applies to.
     2954
     2955We do not seek the maximum at vertices as each vertex can
     2956have multiple values -- one for each triangle sharing it.
     2957\end{methoddesc}
     2958
     2959\begin{methoddesc}{\emph{<quantity>}.get_maximum_location}{indices=None}
     2960Module: \module{abstract_2d_finite_volumes.quantity}
     2961
     2962Return the location of the maximum value of a quantity (on centroids).
     2963
     2964\code{indices} is the optional set of element \code{id}s that
     2965the operation applies to.
     2966
     2967We do not seek the maximum at vertices as each vertex can
     2968have multiple values -- one for each triangle sharing it.
     2969
     2970If there are multiple cells with the same maximum value, the
     2971first cell encountered in the triangle array is returned.
     2972\end{methoddesc}
     2973
     2974\begin{methoddesc}{\emph{<domain>}.get_wet_elements}{indices=None}
     2975Module: \module{shallow_water.shallow_water_domain}
     2976
     2977Returns the indices for elements where h $>$ minimum_allowed_height
     2978
     2979\code{indices} is the optional set of element \code{id}s that
     2980the operation applies to.
     2981\end{methoddesc}
     2982
     2983\begin{methoddesc}{\emph{<domain>}.get_maximum_inundation_elevation}{indices=None}
     2984Module: \module{shallow_water.shallow_water_domain}
     2985
     2986Return highest elevation where h $>$ 0.
     2987
     2988\code{indices} is the optional set of element \code{id}s that
     2989the operation applies to.
     2990
     2991Example to find maximum runup elevation:
     2992\begin{verbatim}
     2993z = domain.get_maximum_inundation_elevation()
     2994\end{verbatim}
     2995\end{methoddesc}
     2996
     2997\begin{methoddesc}{\emph{<domain>}.get_maximum_inundation_location}{indices=None}
     2998Module: \module{shallow_water.shallow_water_domain}
     2999
     3000Return location (x,y) of highest elevation where h $>$ 0.
     3001
     3002\code{indices} is the optional set of element \code{id}s that
     3003the operation applies to.
     3004
     3005Example to find maximum runup location:
     3006\begin{verbatim}
     3007x, y = domain.get_maximum_inundation_location()
     3008\end{verbatim}
     3009\end{methoddesc}
    27173010
    27183011
    27193012\section{Queries of SWW model output files}
    2720 After a model has been run, it is often useful to extract various information from the sww
     3013After a model has been run, it is often useful to extract various information from the SWW
    27213014output file (see Section \ref{sec:sww format}). This is typically more convenient than using the
    27223015diagnostics described in Section \ref{sec:diagnostics} which rely on the model running -- something
    2723 that can be very time consuming. The sww files are easy and quick to read and offer much information
     3016that can be very time consuming. The SWW files are easy and quick to read and offer information
    27243017about the model results such as runup heights, time histories of selected quantities,
    27253018flow through cross sections and much more.
    27263019
    2727 \begin{funcdesc}{get\_maximum\_inundation\_elevation}{filename, polygon=None,
    2728     time_interval=None, verbose=False}
    2729   Module: \module{shallow\_water.data\_manager}
    2730 
    2731   Return highest elevation where depth is positive ($h > 0$)
    2732 
    2733   Example to find maximum runup elevation:
    2734 
    2735   \begin{verbatim}
    2736 max_runup = get_maximum_inundation_elevation(filename,
    2737                                              polygon=None,
    2738                                              time_interval=None,
    2739                                              verbose=False)
    2740   \end{verbatim}
    2741 
    2742   filename is a NetCDF sww file containing ANUGA model output.
    2743   Optional arguments polygon and time_interval restricts the maximum runup calculation
    2744   to a points that lie within the specified polygon and time interval.
    2745 
    2746   If no inundation is found within polygon and time_interval the return value
    2747   is None signifying "No Runup" or "Everything is dry".
    2748 
    2749   See doc string for general function get_maximum_inundation_data for details.
     3020\begin{funcdesc}{elevation = get_maximum_inundation_elevation}{filename,
     3021                                     polygon=None,
     3022                                     time_interval=None,
     3023                                     verbose=False}
     3024Module: \module{shallow_water.data_manager}
     3025
     3026Return the highest elevation where depth is positive ($h > 0$).
     3027
     3028\code{filename} is the path to a NetCDF SWW file containing \anuga model output.
     3029
     3030\code{polygon} restricts the query to the points that lie within the polygon.
     3031
     3032\code {time_interval} restricts the query to within the time interval.
     3033
     3034Example to find maximum runup elevation:
     3035
     3036\begin{verbatim}
     3037max_runup = get_maximum_inundation_elevation(filename)
     3038\end{verbatim}
     3039
     3040If no inundation is found (within the \code{polygon} and \code{time_interval}, if specified)
     3041the return value is \code{None}. This indicates "No Runup" or "Everything is dry".
    27503042\end{funcdesc}
    27513043
    2752 \begin{funcdesc}{get\_maximum\_inundation\_location}{filename, polygon=None,
    2753     time_interval=None, verbose=False}
    2754   Module: \module{shallow\_water.data\_manager}
    2755 
    2756   Return location (x,y) of highest elevation where depth is positive ($h > 0$)
    2757 
    2758   Example to find maximum runup location:
    2759 
    2760   \begin{verbatim}
    2761 max_runup_location = get_maximum_inundation_location(filename,
    2762                                                      polygon=None,
    2763                                                      time_interval=None,
    2764                                                      verbose=False)
    2765   \end{verbatim}
    2766 
    2767   \code{filename} is a NetCDF sww file containing ANUGA model output.
    2768   Optional arguments \code{polygon} and \code{time_interval} restricts the maximum runup calculation
    2769   to a points that lie within the specified polygon and time interval.
    2770 
    2771   If no inundation is found within polygon and time_interval the return value
    2772   is None signifying "No Runup" or "Everything is dry".
    2773 
    2774   See the 'doc' string for general function \code{get_maximum_inundation_data} for details.
     3044\begin{funcdesc}{(x, y) = get_maximum_inundation_location}{filename,
     3045                                    polygon=None,
     3046                                    time_interval=None,
     3047                                    verbose=False}
     3048Module: \module{shallow_water.data_manager}
     3049
     3050Return location (x,y) of the highest elevation where depth is positive ($h > 0$).
     3051
     3052\code{filename} is the path to a NetCDF SWW file containing \anuga model output.
     3053
     3054\code{polygon} restricts the query to the points that lie within the polygon.
     3055
     3056\code {time_interval} restricts the query to within the time interval.
     3057
     3058Example to find maximum runup location:
     3059
     3060\begin{verbatim}
     3061max_runup_location = get_maximum_inundation_location(filename)
     3062\end{verbatim}
     3063
     3064If no inundation is found (within the \code{polygon} and \code{time_interval}, if specified)
     3065the return value is \code{None}. This indicates "No Runup" or "Everything is dry".
     3066is \code{None}. This indicates "No Runup" or "Everything is dry".
    27753067\end{funcdesc}
    27763068
    2777 \begin{funcdesc}{sww2timeseries}{swwfiles, gauge_filename, production_dirs, report=None, reportname=None,
    2778 plot_quantity=None, generate_fig=False, surface=None, time_min=None, time_max=None, time_thinning=1,
    2779 time_unit=None, title_on=None, use_cache=False, verbose=False}
    2780   Module: \module{anuga.abstract\_2d\_finite\_volumes.util}
    2781 
    2782   Return csv files for the location in the \code{gauge_filename} and can also return plots of them
    2783 
    2784   See the 'doc' string for general function \code{sww2timeseries} for details.
     3069\begin{funcdesc}{sww2timeseries}{swwfiles,
     3070                                 gauge_filename,
     3071                                 production_dirs,
     3072                                 report=None,
     3073                                 reportname=None,
     3074                                 plot_quantity=None,
     3075                                 generate_fig=False,
     3076                                 surface=None,
     3077                                 time_min=None,
     3078                                 time_max=None,
     3079                                 time_thinning=1,
     3080                                 time_unit=None,
     3081                                 title_on=None,
     3082                                 use_cache=False,
     3083                                 verbose=False}
     3084Module: \module{abstract_2d_finite_volumes.util}
     3085
     3086Read a set of SWW files and plot the time series for the prescribed quantities
     3087at defined gauge locations and prescribed time range.
     3088
     3089\code{swwfiles} is a dictionary of SWW files with keys of \code{label_id}.
     3090
     3091\code{gauge_filename} is the path to a file containing gauge data.
     3092
     3093THIS NEEDS MORE WORK.  WORK ON FUNCTION __DOC__ STRING, IF NOTHING ELSE!
    27853094\end{funcdesc}
    27863095
    2787 \begin{funcdesc}{get\_flow\_through\_cross\_section}{filename, cross\_section, verbose=False}
    2788   Module: \module{shallow\_water.data\_manager}
    2789 
    2790   Obtain flow $[m^3/s]$ perpendicular to specified cross section.
    2791 
    2792   Inputs:
    2793   \begin{itemize}
    2794         \item filename: Name of sww file containing ANUGA model output.
    2795         \item polyline: Representation of desired cross section -- it may contain multiple
    2796                         sections allowing for complex shapes. Assume absolute UTM coordinates.
    2797   \end{itemize}
    2798 
    2799   Output:
    2800   \begin{itemize}
    2801     \item time: All stored times in sww file
    2802     \item Q: Hydrograph of total flow across given segments for all stored times.
    2803   \end{itemize}
    2804 
    2805   The normal flow is computed for each triangle intersected by the polyline and
    2806   added up.  Multiple segments at different angles are specified the normal flows
    2807   may partially cancel each other.
    2808 
    2809   Example to find flow through cross section:
    2810 
    2811   \begin{verbatim}
     3096\begin{funcdesc}{(time, Q) = get_flow_through_cross_section}{filename, polyline, verbose=False}
     3097Module: \module{shallow_water.data_manager}
     3098
     3099Obtain flow ($m^3/s$) perpendicular to specified cross section.
     3100
     3101\code{filename} is the path to the SWW file.
     3102
     3103\code{polyline} is the representation of the desired cross section -- it may contain
     3104multiple sections allowing for complex shapes. Assumes absolute UTM coordinates.
     3105
     3106Returns a tuple \code{time, Q} where:
     3107
     3108\code{time} is all the stored times in the SWW file.
     3109
     3110\code{Q} is a hydrograph of total flow across the given segments for all stored times.
     3111
     3112The normal flow is computed for each triangle intersected by the \code{polyline} and
     3113added up.  If multiple segments at different angles are specified the normal flows
     3114may partially cancel each other.
     3115
     3116Example to find flow through cross section:
     3117
     3118\begin{verbatim}
    28123119cross_section = [[x, 0], [x, width]]
    2813 time, Q = get_flow_through_cross_section(filename,
    2814                                          cross_section,
    2815                                          verbose=False)
    2816   \end{verbatim}
    2817 
    2818   See the 'doc' string for general function \code{get_maximum_inundation_data} for details.
     3120time, Q = get_flow_through_cross_section(filename, cross_section)
     3121\end{verbatim}
    28193122\end{funcdesc}
    28203123
    28213124
    28223125\section{Other}
    2823 \begin{funcdesc}{domain.create\_quantity\_from\_expression}{string}
    2824   Handy for creating derived quantities on-the-fly as for example:
    2825 
    2826   \begin{verbatim}
     3126\begin{methoddesc}{quantity = \emph{<domain>}.create_quantity_from_expression}{string}
     3127Module: \module{abstract_2d_finite_volumes.domain}
     3128
     3129Create a new quantity from other quantities in the domain using an arbitrary expression.
     3130
     3131\code{string} is a string containing an arbitrary quantity expression.
     3132
     3133Returns the new \code{Quantity} object.
     3134
     3135Handy for creating derived quantities on-the-fly:
     3136
     3137\begin{verbatim}
    28273138Depth = domain.create_quantity_from_expression('stage-elevation')
    28283139
    28293140exp = '(xmomentum*xmomentum + ymomentum*ymomentum)**0.5'
    28303141Absolute_momentum = domain.create_quantity_from_expression(exp)
    2831   \end{verbatim}
    2832 
    2833   %See also \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
    2834 \end{funcdesc}
     3142\end{verbatim}
     3143
     3144%See also \file{Analytical_solution_circular_hydraulic_jump.py} for an example.
     3145\end{methoddesc}
    28353146
    28363147%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     
    28453156detail in the paragraphs below.
    28463157
    2847 \bigskip
    28483158\begin{center}
    28493159\begin{tabular}{|ll|}  \hline
     
    28513161  \hline\hline
    28523162  \code{.sww} & NetCDF format for storing model output with mesh information \code{f(t,x,y)}\\
    2853   \code{.sts} & NetCDF format for storing model ouput \code{f(t,x,y)} without any mesh information\\
     3163  \code{.sts} & NetCDF format for storing model ouput \code{f(t,x,y)} without mesh information\\
    28543164  \code{.tms} & NetCDF format for storing time series \code{f(t)}\\
    2855   \code{.csv/.txt} & ASCII format called points csv for storing arbitrary points and associated attributes\\
     3165  \code{.csv/.txt} & ASCII format for storing arbitrary points and associated attributes\\
    28563166  \code{.pts} & NetCDF format for storing arbitrary points and associated attributes\\
    28573167  \code{.asc} & ASCII format of regular DEMs as output from ArcView\\
     
    28633173  \code{.nc} & Native ferret NetCDF format\\
    28643174  \code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
    2865   %\caption{File formats used by \anuga}
    28663175\end{tabular}
    28673176\end{center}
     
    28703179formats of files. However, typically, in referring to a format we
    28713180capitalise the extension and omit the initial full stop -- thus, we
    2872 refer, for example, to 'SWW files' or 'PRJ files'.
     3181refer to 'SWW files' or 'PRJ files', not 'sww files' or '.prj files'.
    28733182
    28743183\bigskip
    28753184
    28763185A typical dataflow can be described as follows:
     3186
     3187SOMETHING MISSING HERE!?
    28773188
    28783189\subsection{Manually Created Files}
     
    28983209\subsection{SWW, STS and TMS Formats}
    28993210\label{sec:sww format}
    2900 The SWW, STS and TMS formats are all NetCDF formats, and are of key importance for \anuga.
     3211The SWW, STS and TMS formats are all NetCDF formats and are of key importance for \anuga.
    29013212
    29023213An SWW file is used for storing \anuga output and therefore pertains
     
    29073218\begin{itemize}
    29083219  \item \code{x} and \code{y}: coordinates of the points, represented as numeric arrays
    2909   \item \code{elevation}, a numeric array storing bed-elevations
    2910   \item \code{volumes}, a list specifying the points at the vertices of each of the triangles
     3220  \item \code{elevation}: a numeric array storing bed-elevations
     3221  \item \code{volumes}: a list specifying the points at the vertices of each of the triangles
    29113222    % Refer here to the example to be provided in describing the simple example
    2912   \item \code{time}, a numeric array containing times for model evaluation
     3223  \item \code{time}: a numeric array containing times for model evaluation
    29133224\end{itemize}
    29143225
    2915 The contents of an SWW file may be viewed using the anuga viewer
    2916 \code{animate}, which creates an on-screen geometric
    2917 representation. See section \ref{sec:animate} (page
    2918 \pageref{sec:animate}) in Appendix \ref{ch:supportingtools} for more
    2919 on \code{animate}.
     3226The contents of an SWW file may be viewed using the anuga viewer \code{animate},
     3227which creates an on-screen visialisation.  See section \ref{sec:animate}
     3228(page \pageref{sec:animate}) in Appendix \ref{ch:supportingtools} for more on \code{animate}.
    29203229
    29213230Alternatively, there are tools, such as \code{ncdump}, that allow
    2922 you to convert an NetCDF file into a readable format such as the
     3231you to convert a NetCDF file into a readable format such as the
    29233232Class Definition Language (CDL). The following is an excerpt from a
    29243233CDL representation of the output file \file{runup.sww} generated
    2925 from running the simple example \file{runup.py} of
    2926 Chapter \ref{ch:getstarted}:
     3234from running the simple example \file{runup.py} of Chapter \ref{ch:getstarted}:
    29273235
    29283236%FIXME (Ole): Should put in example with nonzero xllcorner, yllcorner
     
    29333241\function{file\_function}, described in Chapter \ref{ch:interface}.
    29343242
    2935 An STS file is used for storing a set of points and and associated set of times.
     3243An STS file is used for storing a set of points and associated times.
    29363244It contains, in addition to dimension information, the following
    29373245variables:
    29383246\begin{itemize}
    29393247  \item \code{x} and \code{y}: coordinates of the points, represented as numeric arrays
    2940   \item \code{permutation}: Original indices of the points as specified by the optional \code{ordering\_file}
    2941                             (see the function \code{urs2sts} in Section \ref{sec:basicfileconversions}).
     3248  \item \code{permutation}: Original indices of the points as specified by the optional \code{ordering_file}
     3249                            (see the function \code{urs2sts()} in Section \ref{sec:basicfileconversions})
    29423250  \item \code{elevation}: a numeric array storing bed-elevations
    29433251    % Refer here to the example to be provided in describing the simple example
     
    29593267two formats: it can be either a TSH file, which is an ASCII file, or
    29603268an MSH file, which is a NetCDF file. A mesh file can be generated
    2961 from the function \function{create\_mesh\_from\_regions} (see
     3269from the function \function{create_mesh_from_regions()} (see
    29623270Section \ref{sec:meshgeneration}) and be used to initialise a domain.
    29633271
     
    29763284
    29773285A mesh file can also contain a georeference, which describes an
    2978 offset to be applied to $x$ and $y$ values -- e.g.\ to the vertices.
     3286offset to be applied to $x$ and $y$ values -- e.g. to the vertices.
    29793287
    29803288\subsection{Formats for Storing Arbitrary Points and Attributes}
     
    29913299
    29923300\begin{verbatim}
    2993 x, y, elevation, friction}
    2994 0.6, 0.7, 4.9, 0.3}
    2995 1.9, 2.8, 5, 0.3}
    2996 2.7, 2.4, 5.2, 0.3}
     3301x, y, elevation, friction
     33020.6, 0.7, 4.9, 0.3
     33031.9, 2.8, 5.0, 0.3
     33042.7, 2.4, 5.2, 0.3
    29973305\end{verbatim}
    29983306
    29993307The delimiter is a comma. The first two columns are assumed to
    3000 be x, y coordinates.
     3308be $x$ and $y$ coordinates.
    30013309
    30023310A PTS file is a NetCDF representation of the data held in an points CSV
     
    30383346\label{sec:basicfileconversions}
    30393347
    3040 \begin{funcdesc}{sww2dem}{basename_in, basename_out=None,
     3348\begin{funcdesc}{sww2dem}{(basename_in,
     3349            basename_out=None,
    30413350            quantity=None,
    30423351            timestep=None,
     
    30493358            northing_min=None,
    30503359            northing_max=None,
    3051             expand_search=False,
    30523360            verbose=False,
    30533361            origin=None,
    30543362            datum='WGS84',
    3055             format='ers'}
    3056   Module: \module{shallow\_water.data\_manager}
    3057 
    3058   Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or
    3059   ERS) of a desired grid size \code{cellsize} in metres. The user can select how
    3060   many the decimal places the output data can be written to using \code{number_of_decimal_places},
    3061   with the default being 3.
    3062   The easting and northing values are used if the user wished to determine the output
    3063   within a specified rectangular area. The \code{reduction} input refers to a function
    3064   to reduce the quantities over all time step of the SWW file, example, maximum.
     3363            format='ers',
     3364            block_size=None}
     3365Module: \module{shallow_water.data_manager}
     3366
     3367Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or
     3368ERS) of a desired grid size \code{cellsize} in metres. The user can select how
     3369many decimal places the output data is represented with by using \code{number_of_decimal_places},
     3370with the default being 3.
     3371
     3372The $easting$ and $northing$ values are used if the user wishes to determine the output
     3373within a specified rectangular area. The \code{reduction} input refers to a function
     3374to reduce the quantities over all time step of the SWW file, e.g. maximum.
    30653375\end{funcdesc}
    30663376
     
    33023612$z$ the bed elevation. The latter are assumed to be relative to the
    33033613same height datum.
    3304 The conserved quantities tracked by ANUGA are momentum in the
     3614The conserved quantities tracked by \anuga are momentum in the
    33053615$x$-direction ($\mu = uh$), momentum in the $y$-direction ($\nu = vh$)
    33063616and depth ($h = w-z$).
     
    33383648\]
    33393649
    3340 ANUGA has a global parameter $H_0$ that controls the minimal depth which
     3650\anuga has a global parameter $H_0$ that controls the minimal depth which
    33413651is considered in the various equations. This parameter is typically set to
    33423652$10^{-3}$. Setting
     
    33523662\]
    33533663In general, for multiples of the minimal depth $N H_0$ one obtains
    3354 \begin{equation}
     3664\[
    33553665  \left[ \frac{\mu}{h + h_0/h} \right]_{h = N H_0} =
    3356   \frac{\mu}{N H_0 + H_0/N} = 
    3357   \frac{\mu}{h (1 + 1/N^2)}
    3358   \label{eq:flux limit multiple}
    3359 \end{equation}
     3666  \frac{\mu}{H_0 (1 + 1/N^2)}
     3667\]
    33603668which converges quadratically to the true value with the multiple N.
    3361 
    3362 Although this equation can be used for any depth, we have restricted its use to depths less than $10 * H_0$ (or 1 cm) to computational resources.
    3363 According to Equation \ref{eq:flux limit multiple} this cutoff   
    3364 affects the calculated velocity by less than 1 \%.   
    33653669
    33663670%The developed numerical model has been applied to several test cases
     
    34853789using some relative time (e.g. 0).
    34863790
    3487 The ANUGA domain has an attribute \code{starttime} which is used in cases where the
     3791The \anuga domain has an attribute \code{starttime} which is used in cases where the
    34883792simulation should be started later than the beginning of some input data such as those
    3489 obtained from boundaries or forcing functions (hydrographs, file\_boundary etc).
     3793obtained from boundaries or forcing functions (hydrographs, file_boundary etc).
    34903794
    34913795The \code{domain.startime} may be adjusted in \code{file_boundary} in the case the
     
    35013805All locations must consequently be specified in Cartesian coordinates
    35023806(eastings, northings) or (x,y) where the unit is metres.
    3503 Alternative projections can be assumed, but ANUGA does have the concept of a UTM zone
     3807Alternative projections can be used, but \anuga does have the concept of a UTM zone
    35043808that must be the same for all coordinates in the model.
    35053809
    35063810\subsection{Internal coordinates}
    3507 It is important to realise that ANUGA for numerical precision uses coordinates that are relative
     3811It is important to realise that for numerical precision \anuga uses coordinates that are relative
    35083812to the lower left node of the rectangle containing the mesh ($x_{\mbox{min}}$, $y_{\mbox{min}}$).
    35093813This origin is referred to internally as \code{xllcorner}, \code{yllcorner} following the ESRI ASCII grid notation. 
    3510 The sww file format also includes \code{xllcorner}, \code{yllcorner} and any coordinate in the file should be adjusted
     3814The SWW file format also includes \code{xllcorner}, \code{yllcorner} and any coordinate in the file should be adjusted
    35113815by adding this origin. See Section \ref{sec:sww format}.
    35123816
    3513 Throughout the ANUGA interface, functions have optional boolean arguments \code{absolute} which controls
     3817Throughout the \anuga interface, functions have optional boolean arguments \code{absolute} which controls
    35143818whether spatial data received is using the internal representation (\code{absolute=False}) or the
    3515 user coordinate set (\code{absolute=True}). See e.g. \code{get_vertex_coordinates} on \pageref{pg:get vertex coordinates}.
    3516 
    3517 DEMs, meshes and boundary conditions can have different origins. However, the internal representation in ANUGA
     3819user coordinate set (\code{absolute=True}). See e.g. \code{get_vertex_coordinates()} on \pageref{pg:get vertex coordinates}.
     3820
     3821DEMs, meshes and boundary conditions can have different origins. However, the internal representation in \anuga
    35183822will use the origin of the mesh.
    35193823
     
    35463850%                   native dem and pts formats%
    35473851%
    3548 %  prepare_pts.py: Convert netcdf output from MOST to an sww file suitable
     3852%  prepare_pts.py: Convert netcdf output from MOST to an SWW file suitable
    35493853%                  as boundary condition%
    35503854%
     
    35963900
    35973901If the function definition changes after a result has been cached, this will be
    3598 detected by examining the functions \code{bytecode (co\_code, co\_consts,
    3599 func\_defaults, co\_argcount)} and the function will be recomputed.
     3902detected by examining the functions bytecode and the function will be recomputed.
    36003903However, caching will not detect changes in modules used by \code{func}.
    3601 In this case cache must be cleared manually.
    3602 
    3603 Options are set by means of the function \code{set\_option(key, value)},
     3904In this case the cache must be cleared manually.
     3905
     3906Options are set by means of the function \code{set_option(key, value)},
    36043907where \code{key} is a key associated with a
    36053908Python dictionary \code{options}. This dictionary stores settings such as the name of
     
    36113914%Other features include support for compression and a capability to \ldots
    36123915
    3613 \textbf{USAGE:} \nopagebreak
     3916USAGE: \nopagebreak
    36143917
    36153918\begin{verbatim}
     
    36193922
    36203923
    3621 \section{ANUGA viewer -- animate}
     3924\pagebreak
     3925\section{\anuga viewer -- animate}
    36223926\label{sec:animate}
    36233927
    36243928The output generated by \anuga may be viewed by
    3625 means of the visualisation tool \code{animate}, which takes the
    3626 \code{SWW} file generated by \anuga and creates a visual representation
     3929means of the visualisation tool \code{animate}, which takes an
     3930SWW file generated by \anuga and creates a visual representation
    36273931of the data. Examples may be seen in Figures \ref{fig:runupstart}
    3628 and \ref{fig:runup2}. To view an \code{SWW} file with
     3932and \ref{fig:runup2}. To view an SWW file with
    36293933\code{animate} in the Windows environment, you can simply drag the
    36303934icon representing the file over an icon on the desktop for the
     
    36353939
    36363940Upon starting the viewer, you will see an interactive moving-picture
    3637 display. You can use the keyboard and the mouse to slow down, speed up or
     3941display. You can use the keyboard and mouse to slow down, speed up or
    36383942stop the display, change the viewing position or carry out a number
    36393943of other simple operations. Help is also displayed when you press
     
    36573961% \vfill
    36583962
    3659 The following table describes how to operate \code{animate} from the command line:
    3660 
    3661 Usage: \code{animate [options] swwfile \ldots}\\  \nopagebreak
    3662 Options:\\ \nopagebreak
     3963The following describes how to operate \code{animate} from the command line:
     3964
     3965Usage: \code{animate [options] swwfile \ldots}\\ \nopagebreak
     3966where: \\ \nopagebreak
    36633967\begin{tabular}{ll}
    36643968  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY\_CENTER |}\\
     
    36733977  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
    36743978  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
    3675 \end{tabular}
    3676 
    3677 \begin{tabular}{ll}
    36783979  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
    36793980  \code{-help} & Display this information\\
    36803981  \code{-hmax <float>} & Height above which transparency is set to
    36813982                                     \code{alphamax}\\
    3682 \end{tabular}
    3683 
    3684 \begin{tabular}{ll}
    36853983  \code{-hmin <float>} & Height below which transparency is set to
    36863984                                     zero\\
    3687 \end{tabular}
    3688 
    3689 \begin{tabular}{ll}
    36903985  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
    36913986                                     up, default is overhead)\\
    3692 \end{tabular}
    3693 
    3694 \begin{tabular}{ll}
    36953987  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
    3696 \end{tabular}
    3697 
    3698 \begin{tabular}{ll}
    36993988  \code{-movie <dirname>} & Save numbered images to named directory and
    37003989                                     quit\\
     
    37144003\refmodindex{utilities.polygon}
    37154004
    3716 \begin{classdesc}{Polygon\_function}{regions, default=0.0, geo_reference=None}
    3717   Module: \code{utilities.polygon}
    3718 
    3719   Creates a callable object that returns one of a specified list of values when
    3720   evaluated at a point \code{x, y}, depending on which polygon, from a specified list of polygons, the
    3721   point belongs to. The parameter \code{regions} is a list of pairs
    3722   \code{(P, v)}, where each \code{P} is a polygon and each \code{v}
    3723   is either a constant value or a function of coordinates \code{x}
    3724   and \code{y}, specifying the return value for a point inside \code{P}. The
    3725   optional parameter \code{default} may be used to specify a value
    3726   (or a function)
    3727   for a point not lying inside any of the specified polygons. When a
    3728   point lies in more than one polygon, the return value is taken to
    3729   be the value for whichever of these polygon appears later in the
    3730   list.
    3731   %FIXME (Howard): CAN x, y BE VECTORS?
    3732   The optional parameter geo\_reference refers to the status of points
    3733   that are passed into the function. Typically they will be relative to
    3734   some origin. In ANUGA, a typical call will take the form:
    3735 
    3736   \begin{verbatim}
     4005\begin{classdesc}{<callable> = Polygon_function}{regions,
     4006                                    default=0.0,
     4007                                    geo_reference=None}
     4008Module: \code{utilities.polygon}
     4009
     4010Creates a callable object that returns one of a specified list of values when
     4011evaluated at a point \code{(x, y)}, depending on which polygon, from a specified list of polygons, the
     4012point belongs to.
     4013
     4014\code{regions} is a list of pairs
     4015\code{(P, v)}, where each \code{P} is a polygon and each \code{v}
     4016is either a constant value or a function of coordinates \code{x}
     4017and \code{y}, specifying the return value for a point inside \code{P}.
     4018
     4019\code{default} may be used to specify a value (or a function)
     4020for a point not lying inside any of the specified polygons.
     4021
     4022When a point lies in more than one polygon, the return value is taken to
     4023be the value for whichever of these polygon appears later in the list.
     4024
     4025%FIXME (Howard): CAN x, y BE VECTORS?
     4026
     4027\code{geo_reference} refers to the status of points
     4028that are passed into the function. Typically they will be relative to
     4029some origin.
     4030
     4031Typical usage may take the form:
     4032
     4033\begin{verbatim}
    37374034set_quantity('elevation',
    37384035             Polygon_function([(P1, v1), (P2, v2)],
    37394036                              default=v3,
    37404037                              geo_reference=domain.geo_reference))
    3741   \end{verbatim}
     4038\end{verbatim}
    37424039\end{classdesc}
    37434040
    3744 \begin{funcdesc}{read\_polygon}{filename}
    3745   Module: \code{utilities.polygon}
    3746 
    3747   Reads the specified file and returns a polygon. Each
    3748   line of the file must contain exactly two numbers, separated by a comma, which are interpreted
    3749   as coordinates of one vertex of the polygon.
     4041\begin{funcdesc}{<polygon> = read_polygon}{filename, split=','}
     4042Module: \code{utilities.polygon}
     4043
     4044Reads the specified file and returns a polygon.
     4045Each line of the file must contain exactly two numbers, separated by a delimiter, which are interpreted
     4046as coordinates of one vertex of the polygon.
     4047
     4048\code{filename} is the path to the file to read.
     4049
     4050\code{split} sets the delimiter character between the numbers on one line of
     4051the file.  If not specified, the delimiter is the ',' character.
    37504052\end{funcdesc}
    37514053
    3752 \begin{funcdesc}{populate\_polygon}{polygon, number_of_points, seed = None, exclude = None}
    3753   Module: \code{utilities.polygon}
    3754 
    3755   Populates the interior of the specified polygon with the specified number of points,
    3756   selected by means of a uniform distribution function.
     4054\label{ref:function_populate_polygon}
     4055\begin{funcdesc}{populate_polygon}{polygon, number_of_points, seed=None, exclude=None}
     4056Module: \code{utilities.polygon}
     4057
     4058Populates the interior of the specified polygon with the specified number of points,
     4059selected by means of a uniform distribution function.
     4060
     4061\code{polygon} is the polygon to populate.
     4062
     4063\code{number_of_points} is the (optional) number of points.
     4064
     4065\code{seed}is the optional seed for random number generator.
     4066
     4067\code{exclude} is a list of polygons (inside main polygon) from where points should be excluded.
    37574068\end{funcdesc}
    37584069
    3759 \begin{funcdesc}{point\_in\_polygon}{polygon, delta=1e-8}
    3760   Module: \code{utilities.polygon}
    3761 
    3762   Returns a point inside the specified polygon and close to the edge. The distance between
    3763   the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the
    3764   second argument \code{delta}, which is taken as $10^{-8}$ by default.
     4070\label{ref:function_point_in_polygon}
     4071\begin{funcdesc}{<point> = point_in_polygon}{polygon, delta=1e-8}
     4072Module: \code{utilities.polygon}
     4073
     4074Returns a point inside the specified polygon and close to the edge. The distance between
     4075the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the
     4076second argument \code{delta}, which is taken as $10^{-8}$ by default.
    37654077\end{funcdesc}
    37664078
    3767 \begin{funcdesc}{inside\_polygon}{points, polygon, closed = True, verbose = False}
    3768   Module: \code{utilities.polygon}
    3769 
    3770   Used to test whether the members of a list of points
    3771   are inside the specified polygon. Returns a numeric
    3772   array comprising the indices of the points in the list that lie inside the polygon.
    3773   (If none of the points are inside, returns \code{zeros((0,), 'l')}.)
    3774   Points on the edges of the polygon are regarded as inside if
    3775   \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
     4079\label{ref:function_inside_polygon}
     4080\begin{funcdesc}{<array> = inside_polygon}{points, polygon, closed=True, verbose=False}
     4081Module: \code{utilities.polygon}
     4082
     4083Get a set of points that lie inside a given polygon.
     4084
     4085\code{points} is the list of points to test.
     4086
     4087\code{polygon} is the polygon to test the points against.
     4088
     4089\code{closed} specifies if points on the polygon edge are considered to be inside
     4090or outside the polygon -- \code{True} means they are inside.
     4091
     4092Returns a numeric array comprising the indices of the points in the list
     4093that lie inside the polygon.  If none of the points are inside, returns
     4094\code{zeros((0,), 'l') (ie, an empty numeric array)}.
     4095
     4096Compare with \code{outside_polygon()}, page \pageref{ref:function_outside_polygon}.
    37764097\end{funcdesc}
    37774098
    3778 \begin{funcdesc}{outside\_polygon}{points, polygon, closed = True, verbose = False}
    3779   Module: \code{utilities.polygon}
    3780 
    3781   Exactly like \code{inside\_polygon}, but with the words 'inside' and 'outside' interchanged.
     4099\label{ref:function_outside_polygon}
     4100\begin{funcdesc}{<array> = outside_polygon}{points, polygon, closed=True, verbose=False}
     4101Module: \code{utilities.polygon}
     4102
     4103Get a set of points that lie outside a given polygon.
     4104
     4105\code{points} is the list of points to test.
     4106
     4107\code{polygon} is the polygon to test the points against.
     4108
     4109\code{closed} specifies if points on the polygon edge are considered to be outside
     4110or inside the polygon -- \code{True} means they are outside.
     4111
     4112Returns a numeric array comprising the indices of the points in the list
     4113that lie outside the polygon.  If none of the points are outside, returns
     4114\code{zeros((0,), 'l')} (ie, an empty numeric array).
     4115
     4116Compare with \code{inside_polygon()}, page \pageref{ref:function_inside_polygon}.
    37824117\end{funcdesc}
    37834118
    3784 \begin{funcdesc}{is\_inside\_polygon}{point, polygon, closed=True, verbose=False}
    3785   Module: \code{utilities.polygon}
    3786 
    3787   Returns \code{True} if \code{point} is inside \code{polygon} or
    3788   \code{False} otherwise. Points on the edges of the polygon are regarded as inside if
    3789   \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
     4119\label{ref:function_is_inside_polygon}
     4120\begin{funcdesc}{<boolean> = is_inside_polygon}{point, polygon, closed=True, verbose=False}
     4121Module: \code{utilities.polygon}
     4122
     4123Determines if a single point is inside a polygon.
     4124
     4125\code{point} is the point to test.
     4126
     4127\code{polygon} is the polygon to test \code{point} against.
     4128
     4129\code{closed} is a flag that forces the function to consider a point on the polygon
     4130edge to be inside or outside -- if \code{True} a point on the edge is considered inside the
     4131polygon.
     4132
     4133Returns \code{True} if \code{point} is inside \code{polygon}.
     4134
     4135Compare with \code{inside_polygon()}, page \pageref{ref:function_inside_polygon}.
    37904136\end{funcdesc}
    37914137
    3792 \begin{funcdesc}{is\_outside\_polygon}{point, polygon, closed=True, verbose=False}
    3793   Module: \code{utilities.polygon}
    3794 
    3795   Exactly like \code{is\_outside\_polygon}, but with the words 'inside' and 'outside' interchanged.
     4138\label{ref:function_is_outside_polygon}
     4139\begin{funcdesc}{<boolean> = is_outside_polygon}{point, polygon, closed=True, verbose=False,
     4140%                                                 points_geo_ref=None, polygon_geo_ref=None
     4141                                                }
     4142Module: \code{utilities.polygon}
     4143
     4144Determines if a single point is outside a polygon.
     4145
     4146\code{point} is the point to test.
     4147
     4148\code{polygon} is the polygon to test \code{point} against.
     4149
     4150\code{closed}  is a flag that forces the function to consider a point on the polygon
     4151edge to be outside or inside -- if \code{True} a point on the edge is considered inside the
     4152polygon.
     4153
     4154%\code{points_geo_ref} is ??
     4155%
     4156%\code{polygon_geo_ref} is ??
     4157
     4158Compare with \code{outside_polygon()}, page \pageref{ref:function_outside_polygon}.
    37964159\end{funcdesc}
    37974160
    3798 \begin{funcdesc}{point\_on\_line}{x, y, x0, y0, x1, y1}
    3799   Module: \code{utilities.polygon}
    3800 
    3801   Returns \code{True} or \code{False}, depending on whether the point with coordinates
    3802   \code{x, y} is on the line passing through the points with coordinates \code{x0, y0}
    3803   and \code{x1, y1} (extended if necessary at either end).
     4161\label{ref:function_point_on_line}
     4162\begin{funcdesc}{<boolean> = point_on_line}{point, line, rtol=1.0e-5, atol=1.0e-8}
     4163Module: \code{utilities.polygon}
     4164
     4165Determine if a point is on a line to some tolerance.  The line is considered to
     4166extend past its end-points.
     4167
     4168\code{point} is the point to test ([$x$, $y$]).
     4169
     4170\code{line} is the line to test \code{point} against ([[$x1$,$y1$], [$x2$,$y2$]]).
     4171
     4172\code{rtol} is the relative tolerance to use when testing for coincidence.
     4173
     4174\code{atol} is the absolute tolerance to use when testing for coincidence.
     4175
     4176Returns \code{True} if the point is on the line, else \code{False}.
    38044177\end{funcdesc}
    38054178
    3806 \begin{funcdesc}{separate\_points\_by\_polygon}{points, polygon, closed = True, verbose = False}
    3807     \indexedcode{separate\_points\_by\_polygon}
    3808   Module: \code{utilities.polygon}
    3809 
     4179\label{ref:function_separate_points_by_polygon}
     4180\begin{funcdesc}{(indices, count) = separate_points_by_polygon}{points, polygon,
     4181                                             closed=True,
     4182                                             check_input=True,
     4183                                             verbose=False}
     4184\indexedcode{separate_points_by_polygon}
     4185Module: \code{utilities.polygon}
     4186
     4187Separate a set of points into points that are inside and outside a polygon.
     4188
     4189\code{points} is a list of points to separate.
     4190
     4191\code{polygon} is the polygon used to separate the points.
     4192
     4193\code{closed} determines whether points on the polygon edge should be
     4194regarded as inside or outside the polygon.  \code{True} means they are inside.
     4195
     4196\code{check_input} specifies whether the input parameters are checked -- \code{True}
     4197means check the input parameters.
     4198
     4199The function returns a tuple \code{(indices, count)} where \code{indices} is a list of
     4200point $indices$ from the input \code{points} list, with the indices of points inside the
     4201polygon at the left and indices of points outside the polygon listed at the right.  The
     4202\code{count} value is the count (from the left) of the indices of the points $inside$ the
     4203polygon.
    38104204\end{funcdesc}
    38114205
    3812 \begin{funcdesc}{polygon\_area}{polygon}
    3813   Module: \code{utilities.polygon}
    3814 
    3815   Returns area of arbitrary polygon (reference http://mathworld.wolfram.com/PolygonArea.html)
     4206\begin{funcdesc}{<area> = polygon_area}{polygon}
     4207Module: \code{utilities.polygon}
     4208
     4209Returns area of an arbitrary polygon (reference http://mathworld.wolfram.com/PolygonArea.html).
    38164210\end{funcdesc}
    38174211
    3818 \begin{funcdesc}{plot\_polygons}{polygons, style, figname, verbose = False}
    3819   Module: \code{utilities.polygon}
    3820 
    3821   Plots each polygon contained in input polygon list, e.g.
    3822   \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]}
    3823   etc.  Each polygon can be closed for plotting purposes by assigning the style type to each
    3824   polygon in the list, e.g. \code{style = ['line','line','line']}. The default will be a line
    3825   type when \code{style = None}.
    3826   The subsequent plot will be saved to \code{figname} or defaulted to \code{test_image.png}.
    3827   The function returns a list containing the minimum and maximum of \code{x} and \code{y},
    3828   i.e. \code{[x_{min}, x_{max}, y_{min}, y_{max}]}.
     4212\begin{funcdesc}{[$x_{min}$, $x_{max}$, $y_{min}$, $y_{max}$] = plot_polygons}
     4213                               {polygons_points, style=None,
     4214                                figname=None, label=None, verbose=False}
     4215Module: \code{utilities.polygon}
     4216
     4217Plot a list of polygons to a file.
     4218
     4219\code{polygons_points} is a list of polygons to plot.
     4220
     4221\code{style} is a list of style strings to be applied to the corresponding polygon
     4222in \code{polygons_points}. A polygon can be closed for plotting purposes by assigning
     4223the style string 'line' to it in the appropriate place in the \code{style} list.
     4224The default style is 'line'.
     4225
     4226\code{figname} is the path to the file to save the plot in.  If not specified, use
     4227\file{test_image.png}.
     4228
     4229The function returns a list containing the minimum and maximum of the points in all the
     4230input polygons, i.e. \code{[$x_{min}$, $x_{max}$, $y_{min}$, $y_{max}$]}.
    38294231\end{funcdesc}
    38304232
    38314233
    3832 \section{coordinate\_transforms}
    3833 
    3834 
    3835 \section{geospatial\_data}
     4234\pagebreak
     4235\section{coordinate_transforms}
     4236
     4237
     4238\pagebreak
     4239\section{geospatial_data}
    38364240\label{sec:geospatial}
    38374241
     
    38434247%\refmodindex{geospatial_data}
    38444248
    3845 \begin{classdesc}{Geospatial\_data}
    3846   {data_points=None,
    3847     attributes=None,
    3848     geo_reference=None,
    3849     default_attribute_name=None,
    3850     file_name=None}
    3851   Module: \code{geospatial\_data}
    3852 
    3853   This class is used to store a set of data points and associated
    3854   attributes, allowing these to be manipulated by methods defined for
    3855   the class.
    3856 
    3857   The data points are specified either by reading them from a NetCDF
    3858   or CSV file, identified through the parameter \code{file\_name}, or
    3859   by providing their \code{x}- and \code{y}-coordinates in metres,
    3860   either as a sequence of 2-tuples of floats or as an $M \times 2$
    3861   numeric array of floats, where $M$ is the number of points.
    3862   Coordinates are interpreted relative to the origin specified by the
    3863   object \code{geo\_reference}, which contains data indicating the UTM
    3864   zone, easting and northing. If \code{geo\_reference} is not
    3865   specified, a default is used.
    3866 
    3867   Attributes are specified through the parameter \code{attributes},
    3868   set either to a list or array of length $M$ or to a dictionary whose
    3869   keys are the attribute names and whose values are lists or arrays of
    3870   length $M$. One of the attributes may be specified as the default
    3871   attribute, by assigning its name to \code{default\_attribute\_name}.
    3872   If no value is specified, the default attribute is taken to be the
    3873   first one.
    3874 
    3875   Note that the Geospatial\_data object currently reads entire datasets
    3876   into memory i.e.\ no memomry blocking takes place.
    3877   For this we refer to the set\_quantity method which will read .pts and .csv
    3878   files into \anuga using memory blocking allowing large files to be used.
     4249\begin{classdesc}{Geospatial_data}
     4250                {data_points=None,
     4251                 attributes=None,
     4252                 geo_reference=None,
     4253                 default_attribute_name=None,
     4254                 file_name=None,
     4255                 latitudes=None,
     4256                 longitudes=None,
     4257                 points_are_lats_longs=False,
     4258                 max_read_lines=None,
     4259                 load_file_now=True,
     4260                 verbose=False}
     4261Module: \code{geospatial_data.geospatial_data}
     4262
     4263This class is used to store a set of data points and associated
     4264attributes, allowing these to be manipulated by methods defined for
     4265the class.
     4266
     4267The data points are specified either by reading them from a NetCDF
     4268or CSV file, identified through the parameter \code{file_name}, or
     4269by providing their \code{x}- and \code{y}-coordinates in metres,
     4270either as a sequence of 2-tuples of floats or as an $M \times 2$
     4271numeric array of floats, where $M$ is the number of points.
     4272
     4273Coordinates are interpreted relative to the origin specified by the
     4274object \code{geo_reference}, which contains data indicating the UTM
     4275zone, easting and northing. If \code{geo_reference} is not
     4276specified, a default is used.
     4277
     4278Attributes are specified through the parameter \code{attributes},
     4279set either to a list or array of length $M$ or to a dictionary whose
     4280keys are the attribute names and whose values are lists or arrays of
     4281length $M$. One of the attributes may be specified as the default
     4282attribute, by assigning its name to \code{default_attribute_name}.
     4283If no value is specified, the default attribute is taken to be the
     4284first one.
     4285
     4286Note that the \code{Geospatial_data} object currently reads entire datasets
     4287into memory i.e. no memomry blocking takes place.
     4288For this we refer to the \code{set_quantity()} method which will read PTS and CSV
     4289files into \anuga using memory blocking allowing large files to be used.
    38794290\end{classdesc}
    38804291
    3881 \begin{methoddesc}{import\_points\_file}{delimiter=None, verbose=False}
    3882 
    3883 \end{methoddesc}
    3884 
    3885 \begin{methoddesc}{export\_points\_file}{ofile, absolute=False}
    3886 
    3887 \end{methoddesc}
    3888 
    3889 \begin{methoddesc}{get\_data\_points}{absolute=True, as\_lat\_long=False}
    3890     If \code{as\_lat\_long} is\code{True} the point information
    3891     returned will be in Latitudes and Longitudes.
    3892 \end{methoddesc}
    3893 
    3894 \begin{methoddesc}{set\_attributes}{attributes}
    3895 
    3896 \end{methoddesc}
    3897 
    3898 \begin{methoddesc}{get\_attributes}{attribute_name=None}
    3899 
    3900 \end{methoddesc}
    3901 
    3902 \begin{methoddesc}{get\_all\_attributes}{}
    3903 
    3904 \end{methoddesc}
    3905 
    3906 \begin{methoddesc}{set\_default\_attribute\_name}{default_attribute_name}
    3907 
    3908 \end{methoddesc}
    3909 
    3910 \begin{methoddesc}{set\_geo\_reference}{geo_reference}
    3911 
    3912 \end{methoddesc}
    3913 
    3914 \begin{methoddesc}{add}{}
    3915 
    3916 \end{methoddesc}
    3917 
    3918 \begin{methoddesc}{clip}{}
    3919   Clip geospatial data by a polygon
    3920 
    3921   Inputs are \code{polygon} which is either a list of points, an Nx2 array or
    3922   a Geospatial data object and \code{closed}(optional) which determines
    3923   whether points on boundary should be regarded as belonging to the polygon
    3924   (\code{closed=True}) or not (\code{closed=False}).
    3925   Default is \code{closed=True}.
    3926 
    3927   Returns new Geospatial data object representing points inside specified polygon.
    3928 \end{methoddesc}
    3929 
    3930 \begin{methoddesc}{clip_outside}{}
    3931   Clip geospatial data by a polygon
    3932 
    3933   Inputs are \code{polygon} which is either a list of points, an Nx2 array or
    3934   a Geospatial data object and \code{closed}(optional) which determines
    3935   whether points on boundary should be regarded as belonging to the polygon
    3936   (\code{closed=True}) or not (\code{closed=False}).
    3937   Default is \code{closed=True}.
    3938 
    3939   Returns new Geospatial data object representing points \emph{out}side specified polygon.
    3940 \end{methoddesc}
    3941 
    3942 \begin{methoddesc}{split}{factor=0.5, seed_num=None, verbose=False}
    3943   Returns two geospatial_data object, first is the size of the 'factor'
    3944   smaller the original and the second is the remainder. The two
    3945   new object are disjoin set of each other.
    3946 
    3947   Points of the two new geospatial_data object are selected RANDOMLY.
    3948 
    3949   Input -- the (\code{factor}) which to split the object, if 0.1 then 10% of the
    3950   together object will be returned
    3951 
    3952   Output -- two geospatial_data objects that are disjoint sets of the original
    3953 \end{methoddesc}
    3954 
    3955 \begin{methoddesc}{find_optimal_smoothing_parameter}{data_file, alpha_list=None,
    3956                    mesh_file=None, boundary_poly=None, mesh_resolution=100000,
    3957                    north_boundary=None, south_boundary=None, east_boundary=None,
    3958                    west_boundary=None, plot_name='all_alphas', split_factor=0.1,
    3959                    seed_num=None, cache=False, verbose=False}
    3960   Removes a small random sample of points from 'data_file'. Creates
    3961   models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates
    3962   the predicted value to the previously removed point data. Returns the
    3963   alpha value which has the smallest covariance.
    3964 
    3965   data_file: must not contain points outside the boundaries defined
    3966   and it either a pts, txt or csv file.
    3967 
    3968   alpha_list: the alpha values to test in a single list
    3969 
    3970   mesh_file: name of the created mesh file or if passed in will read it.
    3971   NOTE, if there is a mesh file mesh_resolution, north_boundary, south... etc will be ignored.
    3972 
    3973   mesh_resolution: the maximum area size for a triangle
    3974 
    3975   north_boundary... west_boundary: the value of the boundary
    3976 
    3977   plot_name: the name for the plot contain the results
    3978 
    3979   seed_num: the seed to the random number generator
    3980 
    3981   USAGE:
    3982   convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName,
    3983                                                alpha_list=[0.0001, 0.01, 1],
    3984                                                mesh_file=None,
    3985                                                mesh_resolution=3,
    3986                                                north_boundary=5,
    3987                                                south_boundary=-5,
    3988                                                east_boundary=5,
    3989                                                west_boundary=-5,
    3990                                                plot_name='all_alphas',
    3991                                                seed_num=100000,
    3992                                                verbose=False)
    3993 
    3994   OUTPUT: returns the minumum normalised covalance calculate AND the
    3995   alpha that created it. PLUS writes a plot of the results
    3996 
    3997   NOTE: code will not work if the data_file extent is greater than the
    3998   boundary_polygon or any of the boundaries, eg north_boundary...west_boundary
    3999 \end{methoddesc}
    4000 
    4001 
     4292\begin{methoddesc}{\emph{<Geospatial_data>}.import_points_file}
     4293        {file_name, delimiter=None, verbose=False}
     4294Module: \code{geospatial_data.geospatial_data}
     4295
     4296Import a TXT, CSV or PTS points data file into a code{Geospatial_data} object.
     4297
     4298\code{file_name} is the path to a TXT, CSV or PTS points data file.
     4299
     4300\code{delimiter} is currently unused.
     4301\end{methoddesc}
     4302
     4303\begin{methoddesc}{\emph{<Geospatial_data>}.export_points_file}{file_name, absolute=True,
     4304                                       as_lat_long=False, isSouthHemisphere=True}
     4305Module: \code{geospatial_data.geospatial_data}
     4306
     4307Export a CSV or PTS points data file from a \code{Geospatial_data} object.
     4308
     4309\code{file_name} is the path to the CSV or PTS points file to write.
     4310
     4311\code{absolute} determines if the exported data is absolute or relative to the
     4312\code{Geospatial_data} object geo_reference.  If \code{True} the exported
     4313data is absolute.
     4314
     4315\code{as_lat_long} exports the points data as latitudes and longitudes if \code{True}.
     4316
     4317\code{isSouthHemisphere} has effect only if \code{as_lat_long} is \code{True} and causes
     4318latitude/longitude values to be for the southern (\code{True}) or northern hemispheres
     4319(\code{False}).
     4320\end{methoddesc}
     4321
     4322\begin{methoddesc}{points = \emph{<Geospatial_data>}.get_data_points}
     4323        {absolute=True, geo_reference=None,
     4324         as_lat_long=False, isSouthHemisphere=True}
     4325Module: \code{geospatial_data.geospatial_data}
     4326
     4327Get the coordinates for all the data points as an $N \times 2$ array.
     4328
     4329\code{absolute} determines if the exported data is absolute or relative to the
     4330\code{Geospatial_data} object geo_reference.  If \code{True} the exported
     4331data is absolute.
     4332
     4333\code{geo_reference} is the geo_reference the points are relative to, if supplied.
     4334
     4335\code{as_lat_long} exports the points data as latitudes and longitudes if \code{True}.
     4336
     4337\code{isSouthHemisphere} has effect only if \code{as_lat_long} is \code{True} and causes
     4338latitude/longitude values to be for the southern (\code{True}) or northern hemispheres
     4339(\code{False}).
     4340\end{methoddesc}
     4341
     4342\begin{methoddesc}{\emph{<Geospatial_data>}.set_attributes}{attributes}
     4343Module: \code{geospatial_data.geospatial_data}
     4344
     4345Set the attributes for a \code{Geospatial_data} object.
     4346
     4347\code{attributes} is the new value for the object's attributes.  May be a dictionary or \code{None}.
     4348\end{methoddesc}
     4349
     4350\begin{methoddesc}{atributes = \emph{<Geospatial_data>}.get_attributes}{attribute_name=None}
     4351Module: \code{geospatial_data.geospatial_data}
     4352
     4353Get a named attribute from a \code{Geospatial_data} object.
     4354
     4355\code{attribute_name} is the name of the desired attribute.  If \code{None}, return
     4356the default attribute.
     4357\end{methoddesc}
     4358
     4359\begin{methoddesc}{\emph{<Geospatial_data>}.get_all_attributes}{}
     4360Module: \code{geospatial_data.geospatial_data}
     4361
     4362Get all attributes of a \code{Geospatial_data} object.
     4363
     4364Returns \code{None} or the attributes dictionary (which may be empty).
     4365\end{methoddesc}
     4366
     4367\begin{methoddesc}{\emph{<Geospatial_data>}.set_default_attribute_name}{default_attribute_name}
     4368Module: \code{geospatial_data.geospatial_data}
     4369
     4370Set the default attribute name of a \code{Geospatial_data} object.
     4371
     4372\code{default_attribute_name} is the new default attribute name.
     4373\end{methoddesc}
     4374
     4375\begin{methoddesc}{\emph{<Geospatial_data>}.set_geo_reference}{geo_reference}
     4376Module: \code{geospatial_data.geospatial_data}
     4377
     4378Set the internal geo_reference of a \code{Geospatial_data} object.
     4379
     4380\code{geo_reference} is the new internal geo_reference for the object.
     4381If \code{None} will use the default geo_reference.
     4382
     4383If the \code{Geospatial_data} object already has an internal geo_reference
     4384then the points data will be changed to use the new geo_reference.
     4385\end{methoddesc}
     4386
     4387\begin{methoddesc}{\emph{<Geospatial_data>}.__add__}{other}
     4388Module: \code{geospatial_data.geospatial_data}
     4389
     4390The \code{__add__()} method is defined so it is possible to add two
     4391\code{Geospatial_data} objects.
     4392\end{methoddesc}
     4393
     4394\label{ref:function_clip}
     4395\begin{methoddesc}{geospatial = \emph{<Geospatial_data>}.clip}{polygon, closed=True, verbose=False}
     4396Module: \code{geospatial_data.geospatial_data}
     4397
     4398Clip a \code{Geospatial_data} object with a polygon.
     4399
     4400\code{polygon} is the polygon to clip the \code{Geospatial_data} object with.
     4401This may be a list of points, an $N \times 2$ array or a \code{Geospatial_data}
     4402object.
     4403
     4404\code{closed} determines whether points on the \code{polygon} edge are inside (\code{True})
     4405or outside (\code{False}) the polygon.
     4406
     4407Returns a new \code{Geospatial_data} object representing points inside the
     4408
     4409Compare with \code{clip_outside()}, page \pageref{ref:function_clip_outside}.
     4410specified polygon.
     4411\end{methoddesc}
     4412
     4413\label{ref:function_clip_outside}
     4414\begin{methoddesc}{geospatial = \emph{<Geospatial_data>}.clip_outside}
     4415        {polygon, closed=True, verbose=False}
     4416Module: \code{geospatial_data.geospatial_data}
     4417
     4418Clip a \code{Geospatial_data} object with a polygon.
     4419
     4420\code{polygon} is the polygon to clip the \code{Geospatial_data} object with.
     4421This may be a list of points, an $N \times 2$ array or a \code{Geospatial_data}
     4422object.
     4423
     4424\code{closed} determines whether points on the \code{polygon} edge are inside (\code{True})
     4425or outside (\code{False}) the polygon.
     4426
     4427Returns a new \code{Geospatial_data} object representing points outside the
     4428specified polygon.
     4429
     4430Compare with \code{clip()}, page \pageref{ref:function_clip}.
     4431\end{methoddesc}
     4432
     4433\begin{methoddesc}{(g1, g2) = \emph{<Geospatial_data>}.split}
     4434        {factor=0.5, seed_num=None, verbose=False}
     4435Module: \code{geospatial_data.geospatial_data}
     4436
     4437Split a \code{Geospatial_data} object into two objects of predetermined ratios.
     4438
     4439\code{factor} is the ratio of the size of the first returned object to the
     4440original object.  If '0.5' is supplied, the two resulting objects will be
     4441of equal size.
     4442
     4443\code{seed_num}, if supplied, will be the random number generator seed used for
     4444the split.
     4445
     4446Points of the two new geospatial_data object are selected RANDOMLY.
     4447
     4448Returns two geospatial_data objects that are disjoint sets of the original.
     4449\end{methoddesc}
     4450
     4451\subsection{Miscellaneous Functions}
     4452
     4453The functions here are not \code{Geospatial_data} object methods, but are used with them.
     4454
     4455\begin{methoddesc}{X = find_optimal_smoothing_parameter}
     4456                  {data_file,
     4457                   alpha_list=None,
     4458                   mesh_file=None,
     4459                   boundary_poly=None,
     4460                   mesh_resolution=100000,
     4461                   north_boundary=None,
     4462                   south_boundary=None,
     4463                   east_boundary=None,
     4464                   west_boundary=None,
     4465                   plot_name='all_alphas',
     4466                   split_factor=0.1,
     4467                   seed_num=None,
     4468                   cache=False,
     4469                   verbose=False}
     4470Module: \code{geospatial_data.geospatial_data}
     4471
     4472Calculate the minimum covariance from a set of points in a file.  It does this
     4473by removing a small random sample of points from \code{data_file} and creating
     4474models with different alpha values from \code{alpha_list} and cross validates
     4475the predicted value to the previously removed point data. Returns the
     4476alpha value which has the smallest covariance.
     4477
     4478\code{data_file} is the input data file and must not contain points outside
     4479the boundaries defined and is either a PTS, TXT or CSV file.
     4480
     4481\code{alpha_list} is the list of alpha values to use.
     4482
     4483\code{mesh_file} is the path to a mesh file to create (if supplied).
     4484If \code{None} a mesh file will be created (named \file{temp.msh}).
     4485NOTE: if there is a \code{mesh_resolution} defined or any boundaries are defined,
     4486any input \code{mesh_file} value is ignored.
     4487
     4488\code{mesh_resolution} is the maximum area size for a triangle.
     4489
     4490\code{north_boundary}\\
     4491\code{south_boundary}\\
     4492\code{east_boundary}\\
     4493\code{west_boundary} are the boundary values to use.
     4494
     4495\code{plot_name} is the path name of the plot file to write.
     4496
     4497\code{seed_num} is the random number generator seed to use.
     4498
     4499The function returns a tuple \code{(min_covar, alpha)} where \code{min_covar} is
     4500the minumum normalised covariance and \code{alpha} is the alpha value that
     4501created it.  A plot file is also written.
     4502
     4503This is an example of function usage: \nopagebreak
     4504
     4505\begin{verbatim}
     4506convariance_value, alpha = $\backslash$
     4507        find_optimal_smoothing_parameter(data_file=fileName,
     4508                                         alpha_list=[0.0001, 0.01, 1],
     4509                                         mesh_file=None,
     4510                                         mesh_resolution=3,
     4511                                         north_boundary=5,
     4512                                         south_boundary=-5,
     4513                                         east_boundary=5,
     4514                                         west_boundary=-5,
     4515                                         plot_name='all_alphas',
     4516                                         seed_num=100000,
     4517                                         verbose=False)
     4518\end{verbatim}
     4519
     4520NOTE: The function will not work if the \code{data_file} extent is greater than the
     4521\code{boundary_poly} polygon or any of the boundaries, e.g. \code{north_boundary}, etc.
     4522\end{methoddesc}
     4523
     4524
     4525\pagebreak
    40024526\section{Graphical Mesh Generator GUI}
    4003 The program \code{graphical_mesh_generator.py} in the pmesh module
     4527The program \code{graphical_mesh_generator.py} in the \code{pmesh} module
    40044528allows the user to set up the mesh of the problem interactively.
    40054529It can be used to build the outline of a mesh or to visualise a mesh
     
    40074531
    40084532Graphical Mesh Generator will let the user select various modes. The
    4009 current allowable modes are vertex, segment, hole or region.  The mode
     4533current allowable modes are $vertex$, $segment$, $hole$ or $region$.  The mode
    40104534describes what sort of object is added or selected in response to
    40114535mouse clicks.  When changing modes any prior selected objects become
     
    40174541
    40184542
    4019 \section{alpha\_shape}
     4543\pagebreak
     4544\section{class Alpha_Shape}
    40204545\emph{Alpha shapes} are used to generate close-fitting boundaries
    40214546around sets of points. The alpha shape algorithm produces a shape
     
    40394564with instances of this class.
    40404565
    4041 \begin{classdesc}{Alpha\_Shape}{points, alpha=None}
    4042   Module: \code{alpha\_shape}
    4043 
    4044   To instantiate this class the user supplies the points from which
    4045   the alpha shape is to be created (in the form of a list of 2-tuples
    4046   \code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter
    4047   \code{points}) and, optionally, a value for the parameter
    4048   \code{alpha}. The alpha shape is then computed and the user can then
    4049   retrieve details of the boundary through the attributes defined for
    4050   the class.
     4566\label{class:alpha_shape}
     4567\begin{classdesc}{Alpha_Shape}{points, alpha=None}
     4568Module: \code{alpha_shape}
     4569
     4570Instantiate an instance of the \code{Alpha_Shape} class.
     4571
     4572\code{points} is an $N \times 2$ list of points (\code{[[x1, y1],[x2, y2]}\ldots\code{]}).
     4573
     4574\code{alpha} is the 'fitting' parameter.
    40514575\end{classdesc}
    40524576
    4053 \begin{funcdesc}{alpha\_shape\_via\_files}{point_file, boundary_file, alpha=None}
    4054   Module: \code{alpha\_shape}
    4055 
    4056   This function reads points from the specified point file
    4057   \code{point\_file}, computes the associated alpha shape (either
    4058   using the specified value for \code{alpha} or, if no value is
    4059   specified, automatically setting it to an optimal value) and outputs
    4060   the boundary to a file named \code{boundary\_file}. This output file
    4061   lists the coordinates \code{x, y} of each point in the boundary,
    4062   using one line per point.
     4577\begin{funcdesc}{alpha_shape_via_files}{point_file, boundary_file, alpha= None}
     4578Module: \code{alpha_shape}
     4579
     4580This function reads points from the specified point file
     4581\code{point_file}, computes the associated alpha shape (either
     4582using the specified value for \code{alpha} or, if no value is
     4583specified, automatically setting it to an optimal value) and outputs
     4584the boundary to a file named \code{boundary_file}. This output file
     4585lists the coordinates \code{(x, y)} of each point in the boundary,
     4586using one line per point.
    40634587\end{funcdesc}
    40644588
    4065 \begin{methoddesc}{set\_boundary\_type}{self,raw_boundary=True,
    4066                           remove_holes=False,
    4067                           smooth_indents=False,
    4068                           expand_pinch=False,
    4069                           boundary_points_fraction=0.2}
    4070   Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
    4071 
    4072   This function sets flags that govern the operation of the algorithm
    4073   that computes the boundary, as follows:
    4074 
    4075   \code{raw\_boundary = True} returns raw boundary, i.e. the regular edges of the
    4076                   alpha shape.\\
    4077   \code{remove\_holes = True} removes small holes ('small' is defined by
    4078   \code{boundary\_points\_fraction})\\
    4079   \code{smooth\_indents = True} removes sharp triangular indents in
    4080   boundary\\
    4081   \code{expand\_pinch = True} tests for pinch-off and
    4082   corrects -- preventing a boundary vertex from having more than two edges.
    4083 \end{methoddesc}
    4084 
    4085 \begin{methoddesc}{get\_boundary}{}
    4086   Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
    4087 
    4088   Returns a list of tuples representing the boundary of the alpha
    4089   shape. Each tuple represents a segment in the boundary by providing
    4090   the indices of its two endpoints.
    4091 \end{methoddesc}
    4092 
    4093 \begin{methoddesc}{write\_boundary}{file_name}
    4094   Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
    4095 
    4096   Writes the list of 2-tuples returned by \code{get\_boundary} to the
    4097   file \code{file\_name}, using one line per tuple.
     4589\label{ref:method_set_boundary_type}
     4590\begin{methoddesc}{\emph{<Alpha_shape>}.set_boundary_type}
     4591        {raw_boundary=True,
     4592         remove_holes=False,
     4593         smooth_indents=False,
     4594         expand_pinch=False,
     4595         boundary_points_fraction=0.2}
     4596Module: \code{alpha_shape}
     4597
     4598This function sets internal state that controls how the \code{Alpha_shape}
     4599boundary is presented or exported.
     4600
     4601\code{raw_boundary} sets the type to $raw$ if \code{True},
     4602i.e. the regular edges of the alpha shape.
     4603
     4604\code{remove_holes}, if \code{True} removes small holes ('small' is defined by
     4605\code{boundary_points_fraction}).
     4606
     4607\code{smooth_indents}, if \code{True} removes sharp triangular indents in
     4608the boundary.
     4609
     4610\code{expand_pinch}, if \code{True} tests for pinch-off and
     4611corrects -- preventing a boundary vertex from having more than two edges.
     4612\end{methoddesc}
     4613
     4614\label{ref:method_get_boundary}
     4615\begin{methoddesc}{boundary = \emph{<Alpha_shape>}.get_boundary}{}
     4616Module: \code{alpha_shape}
     4617
     4618Returns a list of tuples representing the boundary of the alpha
     4619shape. Each tuple represents a segment in the boundary by providing
     4620the indices of its two endpoints.
     4621
     4622See \code{set_boundary_type()}, page \pageref{ref:method_set_boundary_type}.
     4623\end{methoddesc}
     4624
     4625\label{ref:method_write_boundary}
     4626\begin{methoddesc}{\emph{<Alpha_shape>}.write_boundary}{file_name}
     4627Module: \code{alpha_shape}
     4628
     4629Writes the list of 2-tuples returned by \code{get_boundary()} to the
     4630file \code{file_name}, using one line per tuple.
     4631
     4632See \code{set_boundary_type()}, page \pageref{ref:method_set_boundary_type}. \\
     4633See \code{get_boundary()}, page \pageref{ref:method_get_boundary}.
    40984634\end{methoddesc}
    40994635
     
    41534689more to come very soon
    41544690
    4155 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    4156 
    4157 \chapter{Modules available in \anuga}
    4158 
    4159 
    4160 \section{\module{abstract\_2d\_finite\_volumes.general\_mesh} }
    4161 \declaremodule[generalmesh]{}{general\_mesh}
    4162 \label{mod:generalmesh}
    4163 
    4164 
    4165 \section{\module{abstract\_2d\_finite\_volumes.neighbour\_mesh} }
    4166 \declaremodule[neighbourmesh]{}{neighbour\_mesh}
    4167 \label{mod:neighbourmesh}
    4168 
    4169 
    4170 \section{\module{abstract\_2d\_finite\_volumes.domain}}
    4171 Generic module for 2D triangular domains for finite-volume computations of conservation laws
    4172 \declaremodule{}{domain}
    4173 \label{mod:domain}
    4174 
    4175 
    4176 \section{\module{abstract\_2d\_finite\_volumes.quantity}}
    4177 \declaremodule{}{quantity}
    4178 \label{mod:quantity}
    4179 
    4180 \begin{verbatim}
    4181 Class Quantity - Implements values at each triangular element
    4182 
    4183 To create:
    4184 
    4185    Quantity(domain, vertex_values)
    4186 
    4187    domain: Associated domain structure. Required.
    4188 
    4189    vertex_values: N x 3 array of values at each vertex for each element.
    4190                   Default None
    4191 
    4192    If vertex_values are None Create array of zeros compatible with domain.
    4193    Otherwise check that it is compatible with dimenions of domain.
    4194    Otherwise raise an exception
    4195 \end{verbatim}
    4196 
    4197 
    4198 \section{\module{shallow\_water}}
    4199 
    4200 2D triangular domains for finite-volume
    4201 computations of the shallow water wave equation.
    4202 This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water
    4203 Wave Equation
    4204 
    4205 \declaremodule[shallowwater]{}{shallow\_water}
    4206 \label{mod:shallowwater}
     4691%?% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     4692%?%
     4693%?% \chapter{Modules available in \anuga}
     4694%?%
     4695%?%
     4696%?% %abstract_2d_finite_volumes
     4697%?%
     4698%?% \section{\module{abstract_2d_finite_volumes.domain}}
     4699%?% Generic module for 2D triangular domains for finite-volume computations of conservation laws
     4700%?% \declaremodule[domain]{}{domain}
     4701%?% \label{mod:domain}
     4702%?%
     4703%?%
     4704%?% \section{\module{abstract_2d_finite_volumes.ermapper_grids}}
     4705%?% \declaremodule[ermappergrids]{}{ermapper_grids}
     4706%?% \label{mod:ermapper_grids}
     4707%?%
     4708%?%
     4709%?% \section{\module{abstract_2d_finite_volumes.general_mesh} }
     4710%?% \declaremodule[generalmesh]{}{general_mesh}
     4711%?% \label{mod:general_mesh}
     4712%?%
     4713%?%
     4714%?% \section{\module{abstract_2d_finite_volumes.generic_boundary_conditions} }
     4715%?% \declaremodule[genericboundaryconditions]{}{generic_boundary_conditions}
     4716%?% \label{mod:generic_boundary_conditions}
     4717%?%
     4718%?%
     4719%?% \section{\module{abstract_2d_finite_volumes.mesh_factory} }
     4720%?% \declaremodule[meshfactory]{}{mesh_factory}
     4721%?% \label{mod:mesh_factory}
     4722%?%
     4723%?%
     4724%?% \section{\module{abstract_2d_finite_volumes.mesh_factory} }
     4725%?% \declaremodule[meshfactory]{}{mesh_factory}
     4726%?% \label{mod:mesh_factory}
     4727%?%
     4728%?%
     4729%?% \section{\module{abstract_2d_finite_volumes.neighbour_mesh} }
     4730%?% \declaremodule[neighbourmesh]{}{neighbour_mesh}
     4731%?% \label{mod:neighbour_mesh}
     4732%?%
     4733%?%
     4734%?% \section{\module{abstract_2d_finite_volumes.pmesh2domain} }
     4735%?% \declaremodule[pmesh2domain]{}{pmesh2domain}
     4736%?% \label{mod:pmesh2domain}
     4737%?%
     4738%?%
     4739%?% \section{\module{abstract_2d_finite_volumes.quantity}}
     4740%?% \declaremodule{}{quantity}
     4741%?% \label{mod:quantity}
     4742%?%
     4743%?% \begin{verbatim}
     4744%?% Class Quantity - Implements values at each triangular element
     4745%?%
     4746%?% To create:
     4747%?%
     4748%?%    Quantity(domain, vertex_values)
     4749%?%
     4750%?%    domain: Associated domain structure. Required.
     4751%?%
     4752%?%    vertex_values: Nx3 array of values at each vertex for each element.
     4753%?%                   Default None
     4754%?%
     4755%?%    If vertex_values are None Create array of zeros compatible with domain.
     4756%?%    Otherwise check that it is compatible with dimenions of domain.
     4757%?%    Otherwise raise an exception
     4758%?% \end{verbatim}
     4759%?%
     4760%?%
     4761%?% \section{\module{abstract_2d_finite_volumes.region} }
     4762%?% \declaremodule[region]{}{region}
     4763%?% \label{mod:region}
     4764%?%
     4765%?%
     4766%?% \section{\module{abstract_2d_finite_volumes.util} }
     4767%?% \declaremodule[util]{}{util}
     4768%?% \label{mod:util}
     4769%?%
     4770%?%
     4771%?% advection
     4772%?% alpha_shape
     4773%?% caching
     4774%?% coordinate_transforms
     4775%?% culvert_flows
     4776%?% damage_modelling
     4777%?% euler
     4778%?% fit_interpolate
     4779%?% geospatial_data
     4780%?% lib
     4781%?% load_mesh
     4782%?% mesh_engine
     4783%?% pmesh
     4784%?% SConstruct
     4785%?% shallow_water
     4786%?% utilities
     4787%?%
     4788%?%
     4789%?% \section{\module{shallow\_water}}
     4790%?%
     4791%?% 2D triangular domains for finite-volume
     4792%?% computations of the shallow water wave equation.
     4793%?% This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water
     4794%?% Wave Equation
     4795%?%
     4796%?% \declaremodule[shallowwater]{}{shallow\_water}
     4797%?% \label{mod:shallowwater}
    42074798
    42084799%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    42094800
    4210 \chapter{ANUGA Full-scale Validations}
     4801\chapter{\anuga Full-scale Validations}
    42114802
    42124803
     
    42324823
    42334824You may download the validation data files by hand and then run the validation.
    4234 Just go to the ANUGA Sourceforge project download page at
     4825Just go to the \anuga Sourceforge project download page at
    42354826\module{http://sourceforge.net/project/showfiles.php?group_id=172848} and select
    42364827the \module{validation_data} package, \module{patong-1.0} release.  You need the
     
    43354926%
    43364927
    4337 %begin{latexonly}
    4338 %\renewcommand{\indexname}{Module Index}
    4339 %end{latexonly}
    4340 \input{mod\jobname.ind}        % Module Index
    4341 %
     4928%?% %begin{latexonly}
     4929%?% %\renewcommand{\indexname}{Module Index}
     4930%?% %end{latexonly}
     4931%?% \input{mod\jobname.ind}        % Module Index
     4932
    43424933%begin{latexonly}
    43434934%\renewcommand{\indexname}{Index}
  • anuga_core/documentation/user_manual/python.sty

    r2363 r7134  
    611611}
    612612\newenvironment{cfuncdesc}[4][\py@badkey]{
     613  \linebreak
     614  \linebreak
    613615  \begin{fulllineitems}
    614616    \cfuncline{#2}{#3}{#4}
     
    616618      \emph{Return value: \textbf{#1}.}\\
    617619    \fi
     620  \linebreak
     621  \linebreak
    618622}{\end{fulllineitems}}
    619623
Note: See TracChangeset for help on using the changeset viewer.