Changeset 3109

Timestamp:

Jun 7, 2006, 4:58:26 PM (19 years ago)

Author:

howard

Message:

Changes from feedback in group have been implemented

File:

• documentation/user_manual/anuga_user_manual.tex (modified) (35 diffs)

documentation/user_manual/anuga_user_manual.tex

@@ -128 +128 @@
 \section{Purpose}
 
-The purpose of this user manual is to introduce the new user to
-the software, describe what it can do and give step-by-step
+The purpose of this user manual is to introduce the new user to the
+inundation software, describe what it can do and give step-by-step
 instructions for setting up and running hydrodynamic simulations.
 
@@ -201 +201 @@
 
 This section is designed to assist the reader to get started with
-\anuga by working through simple examples. Two examples are discussed;
-the first is a simple but artificial example that is useful to illustrate
-many of the ideas, and the second is a more realistic example.
+\anuga by working through some examples. Two examples are discussed;
+the first is a simple example to illustrate many of the ideas, and
+the second is a more realistic example.
 
 \section{A Simple Example}
@@ -210 +210 @@
 \subsection{Overview}
 
-What follows is a discussion of the structure and operation of a script which we will call \file{runup.py},
-with just enough detail to allow
-the reader to appreciate what's involved in setting up a scenario
-like the one it depicts.
+What follows is a discussion of the structure and operation of a
+script called \file{runup.py}.
 
 This example carries out the solution of the shallow-water wave
@@ -220 +218 @@
 constant depth across each line in the perpendicular direction.
 
-The example demonstrates many of the basic ideas involved in
-setting up a more complex scenario. In the general case the user
-specifies the geometry (bathymetry and topography), the initial
-water level, boundary conditions such as tide, and any forcing
-terms that may drive the system such as wind stress or atmospheric
-pressure gradients. Frictional resistance from the different
-terrains in the model is represented by predefined forcing
-terms. The boundary is reflective on three sides and a time dependent wave on one side.
+The example demonstrates the basic ideas involved in setting up a
+complex scenario. In general the user specifies the geometry
+(bathymetry and topography), the initial water level, boundary
+conditions such as tide, and any forcing terms that may drive the
+system such as wind stress or atmospheric pressure gradients.
+Frictional resistance from the different terrains in the model is
+represented by predefined forcing terms. In this example, the
+boundary is reflective on three sides and a time dependent wave on
+one side.
 
 The present example represents a simple scenario and does not
 include any forcing terms, nor is the data taken from a file as it
-would be in many typical cases.
+would typically be.
 
 The conserved quantities involved in the
@@ -319 +318 @@
 \end{itemize}
 
-An example of a general unstructured mesh and the 
+An example of a general unstructured mesh and the
 associated data structures \code{points}, \code{vertices} and \code{boundary}
 is given in Section \ref{xxxx}.
 
 
-Since these three variables encapsulate the information needed to
-specify the grid, it may be helpful to consider how they look in a
-very simple case, not directly related to the example at hand.
+
+
+
+
+
+\subsection{Initialising the Domain}
+
+These variables are then used to set up a data structure
+\code{domain}, through the assignment:
+
+{\small \begin{verbatim}
+    domain = Domain(points, vertices, boundary)
+\end{verbatim}}
+
+This creates an instance of the \class{Domain} class, which
+represents the domain of the simulation. Specific options for domain
+are set at this point, including setting the basename for the output
+file and the directory to be used for data:
+
+{\small \begin{verbatim}
+    domain.set_name('bedslope')
+\end{verbatim}}
+
+{\small \begin{verbatim}
+    domain.set_datadir('.')
+\end{verbatim}}
+
+In addition, the following statement now specifies that the
+quantities \code{stage}, \code{xmomentum} and \code{ymomentum} are
+to be stored:
+
+{\small \begin{verbatim}
+    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
+    'ymomentum'])
+\end{verbatim}}
+
+
+\subsection{Initial Conditions}
+
+The next task is to specify a number of quantities that we wish to
+set for each mesh point. The class \class{Domain} has a method
+\method{set\_quantity}, used to specify these quantities. It is a
+flexible method that allows the user to set quantities in a variety
+of ways---using constants, functions, numeric arrays or expressions
+involving other quantities, arbitrary data points with associated
+values, all of which can be passed as arguments. All quantities can
+be initialised using \method{set\_quantity}. For a conserved
+quantity (such as \code{stage, xmomentum, ymomentum}) this is called
+an \emph{initial condition}. However, other quantities that aren't
+updated by the equation are also assigned values using the same
+interface. The code in the present example demonstrates a number of
+forms in which we can invoke \method{set\_quantity}.
+
+
+\subsubsection{Elevation}
+
+The elevation, or height of the bed, is set using a function,
+defined through the statements below, which is specific to this
+example and specifies a particularly simple initial configuration
+for demonstration purposes:
+
+{\small \begin{verbatim}
+    def f(x,y):
+        return -x/2
+\end{verbatim}}
+
+This simply associates an elevation with each point \code{(x, y)} of
+the plane.  It specifies that the bed slopes linearly in the
+\code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
+the \code{y} direction.  %[screen shot?]
+
+Once the function \function{f} is specified, the quantity
+\code{elevation} is assigned through the simple statement:
+
+{\small \begin{verbatim}
+    domain.set_quantity('elevation', f)
+\end{verbatim}}
+
+
+\subsubsection{Friction}
+
+The assignment of the friction quantity (a forcing term) demonstrates another way we
+can use \method{set\_quantity} to set quantities---namely, assign
+them to a constant numerical value:
+
+{\small \begin{verbatim}
+    domain.set_quantity('friction', 0.1)
+\end{verbatim}}
+
+This just specifies that the Manning friction coefficient is set
+to 0.1 at every mesh point.
+
+\subsubsection{Stage}
+
+The stage (the height of the water surface) is related to the
+elevation and the depth at any time by the equation
+
+
+{\small \begin{verbatim}
+    stage = elevation + depth
+\end{verbatim}}
+
+
+For this example, we simply assign a constant value to \code{stage},
+using the statement
+
+{\small \begin{verbatim}
+    domain.set_quantity('stage', -.4)
+\end{verbatim}}
+
+which specifies that the surface level is set to a height of $-0.4$,
+i.e. 0.4 units (m) below the zero level.
+
+Although it is not necessary for this example, it may be useful to
+digress here and mention a variant to this requirement, which allows
+us to illustrate another way to use \method{set\_quantity}---namely,
+incorporating an expression involving other quantities. Suppose,
+instead of setting a constant value for the stage, we wished to
+specify a constant value for the \emph{depth}. For such a case we
+need to specify that \code{stage} is everywhere obtained by adding
+that value to the value already specified for \code{elevation}. We
+would do this by means of the statements:
+
+{\small \begin{verbatim}
+    h = 0.05 # Constant depth
+    domain.set_quantity('stage', expression = 'elevation + %f' %h)
+\end{verbatim}}
+
+That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus
+the value of \code{elevation} already defined.
+
+The reader will probably appreciate that this capability to
+incorporate expressions into statements using \method{set\_quantity}
+greatly expands its power.) See Section \ref{sec:Initial Conditions} for more
+details.
+
+\subsection{Boundary Conditions}
+
+The boundary conditions are specified as follows:
+
+{\small \begin{verbatim}
+    Br = Reflective_boundary(domain)
+
+    Bt = Transmissive_boundary(domain)
+
+    Bd = Dirichlet_boundary([0.2,0.,0.])
+
+    Bw = Time_boundary(domain=domain,
+                f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
+\end{verbatim}}
+
+The effect of these statements is to set up a selection of different
+alternative boundary conditions and store them in variables that can be
+assigned as needed. Each boundary condition specifies the
+behaviour at a boundary in terms of the behaviour in neighbouring
+elements. The boundary conditions introduced here may be briefly described as
+follows:
+
+\begin{itemize}
+    \item \textbf{Reflective boundary}\label{def:reflective boundary} Returns same \code{stage} as
+      as present in its neighbour volume but momentum vector
+      reversed 180 degrees (reflected).
+      Specific to the shallow water equation as it works with the
+      momentum quantities assumed to be the second and third conserved
+      quantities. A reflective boundary condition models a solid wall.
+    \item \textbf{Transmissive boundary}\label{def:transmissive boundary} Returns same conserved quantities as
+      those present in its neighbour volume. This is one way of modelling
+      outflow from a domain, but it should be used with caution if flow is
+      not steady state as replication of momentum at the boundary
+      may cause occasional spurious effects. If this occurs,
+      consider using e.g. a Dirichlet boundary condition.
+    \item \textbf{Dirichlet boundary}\label{def:dirichlet boundary} Specifies
+      constant values for stage, $x$-momentum and $y$-momentum at the boundary.
+    \item \textbf{Time boundary}\label{def:time boundary} Like a Dirichlet
+      boundary but with behaviour varying with time.
+\end{itemize}
+
+Before describing how these boundary conditions are assigned, we
+recall that the variable \code{boundary} returned by
+\code{rectangular} not only stores the edges of the mesh that
+constitute the boundary but also assigns to each a symbolic `tag',
+which indicates whether that edge forms part of the `top' boundary,
+the `left' boundary, the `bottom' boundary or the `right' boundary.
+These tags provide the means to assign different boundary conditions
+to an edge depending on which part of the boundary it belongs to.
+(Later we shall describe examples in which the boundary is divided
+differently---we are not limited to the tags `left', `right', `top'
+and `bottom'.)
+
+With boundary objects assigned to variables as described above, we
+can apply one to each part of the boundary by means of a statement
+like
+
+{\small \begin{verbatim}
+    domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
+\end{verbatim}}
+
+This statement stipulates that, in the current example, the right
+boundary varies with time, as defined by the lambda function, while the other
+boundaries are all reflective.
+
+The reader may wish to experiment by varying the choice of boundary
+types for one or more of the boundaries. (In the case of \code{Bd}
+and \code{Bw}, the three arguments in each case represent the
+\code{stage}, $x$-momentum and $y$-momentum, respectively.)
+
+{\small \begin{verbatim}
+    Bw = Time_boundary(domain=domain,
+                       f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
+\end{verbatim}}
+
+
+
+\subsection{Evolution}
+
+The final statement \nopagebreak[3]
+{\small \begin{verbatim}
+    for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
+        print domain.timestepping_statistics()
+\end{verbatim}}
+
+causes the configuration of the domain to `evolve', over a series of
+steps indicated by the values of \code{yieldstep} and
+\code{duration}, which can be altered as required.  The value of
+\code{yieldstep} controls the time interval between successive model
+outputs.  Behind the scenes more time steps are generally taken.
+
+
+\subsection{Output}
+
+The output is a NetCDF file with the extension \code{.sww}. It
+contains stage and momentum information and can be used with the
+\code{swollen} (see Section \ref{sec:swollen})
+visualisation package to generate a visual display.
+See Section \ref{sec:file formats} (page \pageref{sec:file formats})
+for more on NetCDF and other file formats.
+
+
+\section{How to Run the Code}
+
+The code can be run in various ways:
+
+\begin{itemize}
+  \item{from a Windows or Unix command line} as in\ \code{python runup.py}
+  \item{within the Python IDLE environment}
+  \item{within emacs}
+  \item{within Windows, by double-clicking the \code{runup.py}
+  file.}
+\end{itemize}
+
+
+\section{Exploring the Model Output}
+
+The following figures are screenshots from the \anuga visualisation
+tool \code{swollen}. Figure \ref{fig:runupstart} shows the domain
+with water surface as specified by the initial condition, $t=0$.
+Figure \ref{fig:bedslope2} shows later snapshots for $t=2.3$ and
+$t=4$ where the system has been evolved and the wave is encroaching
+on the previously dry bed.  All figures are screenshots from an
+interactive animation tool called Swollen which is part of \anuga.
+Swollen is described in more detail is Section \ref{sec:swollen}.
+
+\begin{figure}[hbt]
+
+  \centerline{\includegraphics[width=75mm, height=75mm]
+    {examples/runupstart.eps}}
+
+  \caption{Bedslope example viewed with Swollen}
+  \label{fig:runupstart}
+\end{figure}
+
+
+\begin{figure}[hbt]
+
+  \centerline{
+    \includegraphics[width=75mm, height=75mm]{examples/runupduring.eps}
+    \includegraphics[width=75mm, height=75mm]{examples/runupend.eps}
+   }
+
+  \caption{Bedslope example viewed with Swollen}
+  \label{fig:bedslope2}
+\end{figure}
+
+
+
+
+\clearpage
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{An Example with Real Data}
+\label{sec:realdataexample} The following discussion builds on the
+concepts introduced through the \file{runup.py} example and
+introduces a second example, \file{run\_sydney.py}.  This refers to
+a real-life scenario, in which the domain of interest surrounds the
+Sydney region, and predominantly covers Sydney Harbour. A
+hypothetical tsunami wave is generated by a submarine mass failure
+situated on the edge of the continental shelf.
+
+\subsection{Overview}
+As in the case of \file{runup.py}, the actions carried
+out by the program can be organised according to this outline:
+
+\begin{enumerate}
+
+   \item Set up a triangular mesh.
+
+   \item Set certain parameters governing the mode of
+operation of the model---specifying, for instance, where to store the
+model output.
+
+   \item Input various quantities describing physical measurements, such
+as the elevation, to be specified at each mesh point (vertex).
+
+   \item Set up the boundary conditions.
+
+   \item Carry out the evolution of the model through a series of time
+steps and output the results, providing a results file that can be
+visualised.
+
+\end{enumerate}
+
+
+
+\subsection{The Code}
+
+Here is the code for \file{run\_sydney\_smf.py}:
+
+\verbatiminput{examples/runsydney.py}
+
+In discussing the details of this example, we follow the outline
+given above, discussing each major step of the code in turn.
+
+\subsection{Establishing the Mesh}
+
+One obvious way that the present example differs from
+\file{runup.py} is in the use of a more complex method to
+create the mesh. Instead of imposing a mesh structure on a
+rectangular grid, the technique used for this example involves
+building mesh structures inside polygons specified by the user,
+using a mesh-generator referred to as \code{pmesh}.
+
+In its simplest form, \code{pmesh} creates the mesh within a single
+polygon whose vertices are at geographical locations specified by
+the user. The user specifies the \emph{resolution}---that is, the
+maximal area of a triangle used for triangulation---and a triangular
+mesh is created inside the polygon using a mesh generation engine.
+On any given platform, the same mesh will be returned. Figure
+\ref{fig:pentagon} shows a simple example of this, in which the
+triangulation is carried out within a pentagon.
+
+
+\begin{figure}[hbt]
+
+  \caption{Mesh points are created inside the polygon}
+  \label{fig:pentagon}
+\end{figure}
+
+Boundary tags are not restricted to \code{`left'}, \code{`right'},
+\code{`bottom'} and \code{`top'}, as in the case of
+\file{runup.py}. Instead the user specifies a list of
+tags appropriate to the configuration being modelled.
+
+In addition, \code{pmesh} provides a way to adapt to geographic or
+other features in the landscape, whose presence may require an
+increase in resolution. This is done by allowing the user to specify
+a number of \emph{interior polygons}, each with a specified
+resolution, see Figure \ref{fig:interior meshes}. It is also
+possible to specify one or more `holes'---that is, areas bounded by
+polygons in which no triangulation is required.
+
+\begin{figure}[hbt]
+
+
+
+  \caption{Interior meshes with individual resolution}
+  \label{fig:interior meshes}
+\end{figure}
+
+In its general form, \code{pmesh} takes for its input a bounding
+polygon and (optionally) a list of interior polygons. The user
+specifies resolutions, both for the bounding polygon and for each of
+the interior polygons. Given this data, \code{pmesh} first creates a
+triangular mesh with varying resolution.
+
+The function used to implement this process is
+\function{create\_mesh\_from\_regions}. Its arguments include the
+bounding polygon and its resolution, a list of boundary tags, and a
+list of pairs \code{[polygon, resolution]}, specifying the interior
+polygons and their resolutions.
+
+In practice, the details of the polygons used are read from a
+separate file \file{project.py}. Here is a complete listing of
+\file{project.py}:
+
+\verbatiminput{examples/project.py}
+
+The resulting mesh is output to a \emph{mesh file}\index{mesh
+file}\label{def:mesh file}. This term is used to describe a file of
+a specific format used to store the data specifying a mesh. (There
+are in fact two possible formats for such a file: it can either be a
+binary file, with extension \code{.msh}, or an ASCII file, with
+extension \code{.tsh}. In the present case, the binary file format
+\code{.msh} is used. See Section \ref{sec:file formats} (page
+\pageref{sec:file formats}) for more on file formats.)
+
+The statements
+
+{\small \begin{verbatim}
+    interior_res = 5000%
+    interior_regions = [[project.harbour_polygon_2, interior_res],
+                    [project.botanybay_polygon_2, interior_res]]
+\end{verbatim}}
+
+are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
+\code{botanybay\_polygon\_2} from \file{project.py} and assign a
+common resolution of 5000 to each. The statement
+
+{\small \begin{verbatim}
+    create_mesh_from_regions(project.diffpolygonall,
+                         boundary_tags= {'bottom': [0],
+                                         'right1': [1],
+                                         'right0': [2],
+                                         'right2': [3],
+                                         'top': [4],
+                                         'left1': [5],
+                                         'left2': [6],
+                                         'left3': [7]},
+                         maximum_triangle_area=100000,
+                         filename=meshname,
+                         interior_regions=interior_regions)
+\end{verbatim}}
+
+is then used to create the mesh, taking the bounding polygon to be the polygon
+\code{diffpolygonall} specified in \file{project.py}. The
+argument \code{boundary\_tags} assigns a dictionary, whose keys are the
+names of the boundary tags used for the bounding polygon---\code{`bottom'},
+`right0', `right1', `right2', `top', `left1', `left2' and `left3'---
+and whose values identify the indices of the segments associated with each of these
+tags. (The value associated with each boundary tag is a one-element list.)
+
+
+\subsection{Initialising the Domain}
+
+As with \file{runup.py}, once we have created the mesh, the next
+step is to create the data structure \code{domain}. We did this for
+\file{runup.py} by inputting lists of points and triangles and
+specifying the boundary tags directly. However, in the present case,
+we use a method that works directly with the mesh file
+\code{meshname}, as follows:
+
+
+{\small \begin{verbatim}
+    domain = Domain(meshname, use_cache=True, verbose=True)
+\end{verbatim}}
+
+Providing a filename instead of the lists used in \file{runup.py}
+above causes \code{Domain} to convert a mesh file \code{meshname}
+into an instance of \code{Domain}, allowing us to use methods like
+\method{set\_quantity} to set quantities and to apply other
+operations.
+
+%(In principle, the
+%second argument of \function{pmesh\_to\_domain\_instance} can be any
+%subclass of \class{Domain}, but for applications involving the
+%shallow-water wave equation, the second argument of
+%\function{pmesh\_to\_domain\_instance} can always be set simply to
+%\class{Domain}.)
+
+The following statements specify a basename and data directory, and
+identify quantities to be stored. For the first two, values are
+taken from \file{project.py}.
+
+{\small \begin{verbatim}
+    domain.set_name(project.basename)
+    domain.set_datadir(project.outputdir)
+    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
+        'ymomentum'])
+\end{verbatim}}
+
+
+\subsection{Initial Conditions}
+Quantities for \file{runsydney.py} are set
+using similar methods to those in \file{runup.py}. However,
+in this case, many of the values are read from the auxiliary file
+\file{project.py} or, in the case of \code{elevation}, from an
+ancillary points file.
+
+
+
+\subsubsection{Stage}
+
+For the scenario we are modelling in this case, we use a callable
+object \code{tsunami\_source}, assigned by means of a function
+\function{slump\_tsunami}. This is similar to how we set elevation in
+\file{runup.py} using a function---however, in this case the
+function is both more complex and more interesting.
+
+The function returns the water displacement for all \code{x} and
+\code{y} in the domain. The water displacement is a double Gaussian
+function that depends on the characteristics of the slump (length,
+thickness, slope, etc), its location (origin) and the depth at that
+location.
+
+
+\subsubsection{Friction}
+
+We assign the friction exactly as we did for \file{runup.py}:
+
+{\small \begin{verbatim}
+    domain.set_quantity('friction', 0.0)
+\end{verbatim}}
+
+
+\subsubsection{Elevation}
+
+The elevation is specified by reading data from a file:
+
+{\small \begin{verbatim}
+    domain.set_quantity('elevation',
+                        filename = project.combineddemname + '.pts',
+                        use_cache = True,
+                        verbose = True)
+\end{verbatim}}
+
+However, before this step can be executed, some preliminary steps
+are needed to prepare the file from which the data is taken. Two
+source files are used for this data---their names are specified in
+the file \file{project.py}, in the variables \code{coarsedemname}
+and \code{finedemname}. They contain `coarse' and `fine' data,
+respectively---that is, data sampled at widely spaced points over a
+large region and data sampled at closely spaced points over a
+smaller subregion. The data in these files is combined through the
+statement
+
+{\small \begin{verbatim}
+combine_rectangular_points_files(project.finedemname + '.pts',
+                                 project.coarsedemname + '.pts',
+                                 project.combineddemname + '.pts')
+\end{verbatim}}
+
+The effect of this is simply to combine the datasets by eliminating
+any coarse data associated with points inside the smaller region
+common to both datasets. The name to be assigned to the resulting
+dataset is also derived from the name stored in the variable
+\code{combinedname} in the file \file{project.py}.
+
+\subsection{Boundary Conditions}
+
+Setting boundaries follows a similar pattern to the one used for
+\file{runup.py}, except that in this case we need to associate a
+boundary type with each of the
+boundary tag names introduced when we established the mesh. In place of the four
+boundary types introduced for \file{runup.py}, we use the reflective
+boundary for each of the
+eight tagged segments defined by \code{create_mesh_from_regions}:
+
+{\small \begin{verbatim}
+    Br = Reflective_boundary(domain)
+    domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
+                          'right2': Br, 'top': Br, 'left1': Br,
+                          'left2': Br, 'left3': Br} )
+\end{verbatim}}
+
+\subsection{Evolution}
+
+With the basics established, the running of the `evolve' step is
+very similar to the corresponding step in \file{runup.py}. Here,
+the simulation is run for five hours (18000 seconds) with
+the output stored every two minutes (120 seconds).
+
+{\small \begin{verbatim}
+    import time t0 = time.time()
+
+    for t in domain.evolve(yieldstep = 120, duration = 18000):
+        print domain.timestepping_statistics()
+        print domain.boundary_statistics(tags = 'bottom')
+
+    print 'That took %.2f seconds' %(time.time()
+\end{verbatim}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{\anuga Public Interface}
+\label{ch:interface}
+
+This chapter gives an overview of the features of \anuga available
+to the user at the public interface. These are grouped under the
+following headings, which correspond to the outline of the examples
+described in Chapter \ref{ch:getstarted}:
+
+\begin{itemize}
+    \item Establishing the Mesh
+    \item Initialising the Domain
+    \item Specifying the Quantities
+    \item Initial Conditions
+    \item Boundary Conditions
+    \item Forcing Functions
+    \item Evolution
+\end{itemize}
+
+The listings are intended merely to give the reader an idea of what
+each feature is, where to find it and how it can be used---they do
+not give full specifications; for these the reader
+may consult the code. The code for every function or class contains
+a documentation string, or `docstring', that specifies the precise
+syntax for its use. This appears immediately after the line
+introducing the code, between two sets of triple quotes.
+
+Each listing also describes the location of the module in which
+the code for the feature being described can be found. All modules
+are in the folder \file{inundation} or one of its subfolders, and the
+location of each module is described relative to \file{inundation}. Rather
+than using pathnames, whose syntax depends on the operating system,
+we use the format adopted for importing the function or class for
+use in Python code. For example, suppose we wish to specify that the
+function \function{create\_mesh\_from\_regions} is in a module called
+\module{mesh\_interface} in a subfolder of \module{inundation} called
+\code{pmesh}. In Linux or Unix syntax, the pathname of the file
+containing the function, relative to \file{inundation}, would be
+
+\begin{center}
+%    \code{pmesh/mesh\_interface.py}
+    \code{pmesh}$\slash$\code{mesh\_interface.py}
+\end{center}
+
+while in Windows syntax it would be
+
+\begin{center}
+    \code{pmesh}$\backslash$\code{mesh\_interface.py}
+\end{center}
+
+Rather than using either of these forms, in this chapter we specify
+the location simply as \code{pmesh.mesh\_interface}, in keeping with
+the usage in the Python statement for importing the function,
+namely:
+\begin{center}
+    \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
+\end{center}
+
+Each listing details the full set of parameters for the class or
+function; however, the description is generally limited to the most
+important parameters and the reader is again referred to the code
+for more details.
+
+The following parameters are common to many functions and classes
+and are omitted from the descriptions given below:
+
+%\begin{center}
+\begin{tabular}{ll}  %\hline
+%\textbf{Name } & \textbf{Description}\\
+%\hline
+\emph{use\_cache} & Specifies whether caching is to be used for improved performance. See Section \ref{sec:caching} for details on the underlying caching functionality\\
+\emph{verbose} & If \code{True}, provides detailed terminal output
+to the user\\  % \hline
+\end{tabular}
+%\end{center}
+
+\section{Mesh Generation}
+
+Before discussing the part of the interface relating to mesh
+generation, we begin with a description of a simple example of a
+mesh and use it to describe how mesh data is stored.
+
 Figure \ref{fig:simplemesh} represents a very simple mesh comprising
-just 11 points and three triangles. (To avoid confusion, we should
-emphasise that this particular mesh is \emph{not} generated by
-\code{rectangular}---it is not even rectangular in nature. )
+just 11 points and 10 triangles.
 
 
@@ -346 +1005 @@
 represent the data displayed in Figure \ref{fig:simplemesh} as
 follows. The list \code{points} stores the coordinates of the
-points, and may be displayed schematically as in Table \ref{tab:points}.
+points, and may be displayed schematically as in Table
+\ref{tab:points}.
 
 
@@ -378 +1038 @@
 around the triangle. Thus, in the example shown in Figure
 \ref{fig:simplemesh}, the variable \code{vertices} contains the
-entries shown in Table \ref{tab:vertices}. The starting point is arbitrary so triangle $(0,1,3)$ is considered the same as $(1,3,0)$ and $(3,0,1)$.
+entries shown in Table \ref{tab:vertices}. The starting point is
+arbitrary so triangle $(0,1,3)$ is considered the same as $(1,3,0)$
+and $(3,0,1)$.
 
 
@@ -398 +1060 @@
   \end{center}
 
-  \caption{Vertices for mesh in
-    Figure \protect \ref{fig:simplemesh}}
+  \caption{Vertices for mesh in Figure \protect \ref{fig:simplemesh}}
   \label{tab:vertices}
 \end{table}
@@ -406 +1067 @@
 triangles and associates a tag with each.
 
-
-
-
-\subsection{Initialising the Domain}
-
-These variables are then used to set up a data structure
-\code{domain}, through the assignment:
-
-{\small \begin{verbatim}
-    domain = Domain(points, vertices, boundary)
-\end{verbatim}}
-
-This uses a Python class \class{Domain}, imported from
-\module{shallow\_water}, which is an extension of a more generic
-class of the same name in the module \refmodule{pyvolution.domain}
-(page \pageref{mod:pyvolution.domain}),
-and inherits
-some methods from the generic class but has others specific to the
-shallow-water scenarios in which it is used. Specific options for
-domain are set at this point. One of them is to set the basename for
-the output file:
-
-{\small \begin{verbatim}
-    domain.set_name('bedslope')
-\end{verbatim}}
-
-
-\subsection{Initial Conditions}
-
-The next task is to specify a number of quantities that we wish to
-set for each mesh point. The class \class{Domain} has a method
-\method{set\_quantity}, used to specify these quantities. It is a
-particularly flexible method that allows the user to set quantities
-in a variety of ways---using constants, functions, numeric arrays or
-expressions involving other quantities, arbitrary data points with
-associated values, all of which can be passed as arguments. All
-quantities can be initialised using \method{set\_quantity}. For a
-conserved quantity (such as \code{stage, xmomentum, ymomentum}) this
-is called an \emph{initial condition}. However, other quantities
-that aren't updated by the equation are also assigned values using
-the same interface. The code in the present example demonstrates a
-number of forms in which we can invoke \method{set\_quantity}.
-
-
-\subsubsection{Elevation}
-
-The elevation, or height of the bed, is set using a function,
-defined through the statements below, which is specific to this
-example and specifies a particularly simple initial configuration
-for demonstration purposes:
-
-{\small \begin{verbatim}
-    def f(x,y):
-        return -x/2
-\end{verbatim}}
-
-This simply associates an elevation with each point \code{(x, y)} of
-the plane.  It specifies that the bed slopes linearly in the
-\code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
-the \code{y} direction.  %[screen shot?]
-
-Once the function \function{f} is specified, the quantity
-\code{elevation} is assigned through the simple statement:
-
-{\small \begin{verbatim}
-    domain.set_quantity('elevation', f)
-\end{verbatim}}
-
-
-\subsubsection{Friction}
-
-The assignment of the friction quantity (a forcing term) demonstrates another way we
-can use \method{set\_quantity} to set quantities---namely, assign
-them to a constant numerical value:
-
-{\small \begin{verbatim}
-    domain.set_quantity('friction', 0.1)
-\end{verbatim}}
-
-This just specifies that the Manning friction coefficient is set
-to 0.1 at every mesh point.
-
-\subsubsection{Stage}
-
-The stage (the height of the water surface) is related to the
-elevation and the depth at any time by the equation
-
-
-{\small \begin{verbatim}
-    stage = elevation + depth
-\end{verbatim}}
-
-
-For this example, we simply assign a constant value to \code{stage},
-using the statement
-
-{\small \begin{verbatim}
-    domain.set_quantity('stage', -.4)
-\end{verbatim}}
-
-which specifies that the surface level is set to a height of $-0.4$, 
-i.e. 0.4 units (m) below the zero level.
-
-Although it is not necessary for this example, it may be useful to
-digress here and mention a variant to this requirement, which allows
-us to illustrate another way to use \method{set\_quantity}---namely,
-incorporating an expression involving other quantities. Suppose,
-instead of setting a constant value for the stage, we wished to
-specify a constant value for the \emph{depth}. For such a case we
-need to specify that \code{stage} is everywhere obtained by adding
-that value to the value already specified for \code{elevation}. We
-would do this by means of the statements:
-
-{\small \begin{verbatim}
-    h = 0.05 # Constant depth
-    domain.set_quantity('stage', expression = 'elevation + %f' %h)
-\end{verbatim}}
-
-That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus
-the value of \code{elevation} already defined.
-
-The reader will probably appreciate that this capability to
-incorporate expressions into statements using \method{set\_quantity}
-greatly expands its power.) See Section \ref{sec:Initial Conditions} for more 
-details.
-
-\subsection{Boundary Conditions}
-
-The boundary conditions are specified as follows:
-
-{\small \begin{verbatim}
-    Br = Reflective_boundary(domain)
-
-    Bt = Transmissive_boundary(domain)
-
-    Bd = Dirichlet_boundary([0.2,0.,0.])
-
-    Bw = Time_boundary(domain=domain,
-                f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
-\end{verbatim}}
-
-The effect of these statements is to set up a selection of different
-alternative boundary conditions and store them in variables that can be
-assigned as needed. Each boundary condition specifies the
-behaviour at a boundary in terms of the behaviour in neighbouring
-elements. The boundary conditions introduced here may be briefly described as
-follows:
-
-\begin{itemize}
-    \item \textbf{Reflective boundary}\label{def:reflective boundary} Returns same \code{stage} as
-      as present in its neighbour volume but momentum vector
-      reversed 180 degrees (reflected).
-      Specific to the shallow water equation as it works with the
-      momentum quantities assumed to be the second and third conserved
-      quantities. A reflective boundary condition models a solid wall.
-    \item \textbf{Transmissive boundary}\label{def:transmissive boundary} Returns same conserved quantities as
-      those present in its neighbour volume. This is one way of modelling
-      outflow from a domain, but it should be used with caution if flow is
-      not steady state as replication of momentum at the boundary
-      may cause occasional spurious effects. If this occurs,
-      consider using e.g. a Dirichlet boundary condition.
-    \item \textbf{[Dirichlet boundary}\label{def:dirichlet boundary} Specifies 
-      constant values for stage, $x$-momentum and $y$-momentum at the boundary. 
-    \item \textbf{Time boundary}\label{def:time boundary} Like a Dirichlet 
-      boundary but with behaviour varying with time.
-\end{itemize}
-
-Once the boundary objects have been specified through the
-statements above, they can be applied through a statement of the
-form
-
-{\small \begin{verbatim}
-    domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
-\end{verbatim}}
-
-This statement stipulates that, in the current example, the right
-boundary varies with time, as defined by the lambda function, while the other
-boundaries are all reflective.
-
-The reader may wish to experiment by varying the choice of boundary
-types for one or more of the boundaries. In the case of \code{Bd}
-and \code{Bw}, the three arguments in each case represent the
-\code{stage}, $x$-momentum and $y$-momentum, respectively.
-
-{\small \begin{verbatim}
-    Bw = Time_boundary(domain=domain,
-                       f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
-\end{verbatim}}
-
-
-
-\subsection{Evolution}
-
-The final statement \nopagebreak[3]
-{\small \begin{verbatim}
-    for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
-        print domain.timestepping_statistics()
-\end{verbatim}}
-
-is the key step that causes the configuration of the domain to
-`evolve' in accordance with the model embodied in the code, over a
-series of steps indicated by the values of \code{yieldstep} and
-\code{duration}, which can be altered as required.  The value of
-\code{yieldstep} controls the time interval between successive model
-outputs.  Behind the scenes more time steps are generally taken.
-
-
-\subsection{Output}
-
-%Give details here of the form of the output and explain how it can
-%be used with swollen. Include screen shots.//
-
-The output is a NetCDF file with the extension \code{.sww}. It
-contains stage and momentum information and can be used with the
-\code{swollen} (see Section \ref{sec:swollen}) 
-visualisation package to generate a visual display.
-See Section \ref{sec:file formats} (page \pageref{sec:file formats})
-for more on NetCDF and other file formats.
-
-
-\section{How to Run the Code}
-
-The code can be run in various ways:
-
-\begin{itemize}
-  \item{from a Windows or Unix command line} as in\ \code{python runup.py}
-  \item{within the Python IDLE environment}
-  \item{within emacs}
-\end{itemize}
-
-
-\section{Exploring the Model Output}
-
-Figure \ref{fig:runupstart} shows the domain with water surface as
-specified by the initial condition, $t=0$. Figure
-\ref{fig:bedslope2} shows later snapshots for $t=2.3$ and $t=4$
-where the system has been evolved and the wave is encroaching on the
-previously dry bed.  All figures are screenshots from an interactive
-animation tool called Swollen which is part of \anuga. Swollen is
-described in more detail is Section \ref{sec:swollen}.
-
-
-
-\begin{figure}[hbt]
-
-  \centerline{\includegraphics[width=75mm, height=75mm]
-    {examples/runupstart.eps}}
-
-  \caption{Bedslope example viewed with Swollen}
-  \label{fig:runupstart}
-\end{figure}
-
-
-\begin{figure}[hbt]
-
-  \centerline{
-    \includegraphics[width=75mm, height=75mm]{examples/runupduring.eps}
-    \includegraphics[width=75mm, height=75mm]{examples/runupend.eps}
-   }
-
-  \caption{Bedslope example viewed with Swollen}
-  \label{fig:bedslope2}
-\end{figure}
-
-
-
-
-\clearpage
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\section{An Example with Real Data}
-\label{sec:realdataexample}
-The following discussion builds on the concepts introduced through
-the \file{runup.py} example and introduces a second
-example, \file{run\_sydney.py}, that follows the same basic
-outline, but incorporates more complex features and refers to a
-real-life scenario, rather than the artificial illustrative one used
-in \file{runup.py}. The domain of interest surrounds the
-Sydney region, and predominantly covers Sydney Harbour. A
-hypothetical tsunami wave is generated by a submarine mass failure
-situated on the edge of the continental shelf.
-
-\subsection{Overview}
-As in the case of \file{runup.py}, the actions carried
-out by the program can be organised according to this outline:
-
-\begin{enumerate}
-
-   \item Set up a triangular mesh.
-
-   \item Set certain parameters governing the mode of
-operation of the model---specifying, for instance, where to store the
-model output.
-
-   \item Input various quantities describing physical measurements, such
-as the elevation, to be specified at each mesh point (vertex).
-
-   \item Set up the boundary conditions.
-
-   \item Carry out the evolution of the model through a series of time
-steps and outputs the results, providing a results file that can be
-visualised.
-
-\end{enumerate}
-
-
-
-\subsection{The Code}
-
-Here is the code for \file{run\_sydney\_smf.py}:
-
-%\verbatiminput{"runsydneysmf.py"}
-\verbatiminput{examples/runsydney.py}
-
-In discussing the details of this example, we follow the outline
-given above, discussing each major step of the code in turn.
-
-\subsection{Establishing the Mesh}
-
-One obvious way that the present example differs from
-\file{runup.py} is in the use of a more complex method to
-create the mesh. Instead of imposing a mesh structure on a
-rectangular grid, the technique used for this example involves
-building mesh structures inside polygons specified by the user,
-using a mesh-generator referred to as \code{pmesh}.
-
-The following remarks may help the reader understand how
-\code{pmesh} is used.
-
-In its simplest form, \code{pmesh} creates the mesh within a single
-polygon whose vertices are at geographical locations specified by the
-user. The user specifies the \emph{resolution}---that is, the maximal
-area of a triangle used for triangulation---and mesh points are
-created inside the polygon using a mesh generation engine. On any
-given platform, the same mesh will be returned. Figure
-\ref{fig:pentagon} shows a simple example of this, in which
-the triangulation is carried out within a pentagon.
-
-
-\begin{figure}[hbt]
-
-
-
-  \caption{Mesh points are created inside the polygon}
-  \label{fig:pentagon}
-\end{figure}
-
-Boundary tags are not restricted to \code{`left'}, \code{`right'},
-\code{`bottom'} and \code{`top'}, as in the case of
-\file{runup.py}. Instead the user specifies a list of
-tags appropriate to the configuration being modelled.
-
-While a mesh created inside a polygon offers more flexibility than
-one based on a rectangular grid, using \code{pmesh} in the limited
-form we have described so far still doesn't provide a way to adapt
-to geographic or other features in the landscape, whose presence may
-require us to vary the resolution in the neighbourhood of the
-features. To cope with this requirement, \code{pmesh} also allows
-the user to specify a number of \emph{interior polygons}, which are
-triangulated separately, each according to a separately specified
-resolution, see Figure \ref{fig:interior meshes}. It is also
-possible to specify one or more `holes'---that is, areas bounded by
-polygons in which no triangulation is required.
-
-\begin{figure}[hbt]
-
-
-
-  \caption{Interior meshes with individual resolution}
-  \label{fig:interior meshes}
-\end{figure}
-
-In its general form, \code{pmesh} takes for its input a bounding
-polygon and (optionally) a list of interior polygons. The user
-specifies resolutions, both for the bounding polygon and for each of
-the interior polygons. Given this data, \code{pmesh} first creates a
-triangular mesh inside the bounding polygon, using the specified
-resolution, and then creates a separate triangulation inside each of
-the interior polygons, using the resolution specified for that
-polygon.
-
-The function used to implement this process is
-\function{create\_mesh\_from\_regions}. Its arguments include the
-bounding polygon and its resolution, a list of boundary tags, and a
-list of pairs \code{[polygon, resolution]}, specifying the interior
-polygons and their resolutions.
-
-In practice, the details of the polygons used are read from a
-separate file \file{project.py}. The resulting mesh is output to a
-\emph{meshfile}\index{meshfile}\label{def:meshfile}. This term is
-used to describe a file of a specific format used to store the data
-specifying a mesh. (There are in fact two possible formats for such
-a file: it can either be a binary file, with extension \code{.msh},
-or an ASCII file, with extension \code{.tsh}. In the present case,
-the binary file format \code{.msh} is used. See Section
-\ref{sec:file formats} (page \pageref{sec:file formats}) for more on
-file formats.) \code{pmesh} assigns a name to the file by appending
-the extension \code{.msh} to the name specified in the input file
-\file{project.py}. This name is stored in the variable
-\code{meshname}.
-
-The statements
-
-{\small \begin{verbatim}
-    interior_res = 5000%
-    interior_regions = [[project.harbour_polygon_2, interior_res],
-                    [project.botanybay_polygon_2, interior_res]]
-\end{verbatim}}
-
-are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
-\code{botanybay\_polygon\_2} from \file{project.py} and assign a
-common resolution of 5000 to each. The statement
-
-{\small \begin{verbatim}
-    create_mesh_from_regions(project.diffpolygonall,
-                         boundary_tags= {'bottom': [0],
-                                         'right1': [1],
-                                         'right0': [2],
-                                         'right2': [3],
-                                         'top': [4],
-                                         'left1': [5],
-                                         'left2': [6],
-                                         'left3': [7]},
-                         maximum_triangle_area=100000,
-                         filename=meshname,
-                         interior_regions=interior_regions)
-\end{verbatim}}
-
-is then used to create the mesh, taking the bounding polygon to be the polygon
-\code{diffpolygonall} specified in \file{project.py}. The
-argument \code{boundary\_tags} assigns a dictionary, whose keys are the
-names of the boundary tags used for the bounding polygon---\code{`bottom'},
-`right0', `right1', `right2', `top', `left1', `left2' and `left3'---
-and whose values identify the indices of the segments associated with each of these
-tags. (The value associated with each boundary tag is a one-element list.)
-
-
-\subsection{Initialising the Domain}
-
-As with \file{runup.py}, once we have created the mesh, the next
-step is to create the data structure \code{domain}. We did this for
-\file{runup.py} by inputting lists of points and triangles and
-specifying the boundary tags directly. However, in the present case,
-we use a method that works directly with the meshfile
-\code{meshname}, as follows:
-
-
-{\small \begin{verbatim}
-    domain = Domain(meshname, use_cache=True, verbose=True)
-\end{verbatim}}
-
-Providing a filename instead of the lists used in \file{runup.py}
-above causes \code{Domain} to convert a meshfile \code{meshname}
-into an instance of the data structure \code{domain}, allowing us to
-use methods like \method{set\_quantity} to set quantities and to
-apply other operations.
-
-%(In principle, the
-%second argument of \function{pmesh\_to\_domain\_instance} can be any
-%subclass of \class{Domain}, but for applications involving the
-%shallow-water wave equation, the second argument of
-%\function{pmesh\_to\_domain\_instance} can always be set simply to
-%\class{Domain}.)
-
-The following statements specify a basename and data directory, and
-identify quantities to be stored. For the first two, values are
-taken from \file{project.py}.
-
-{\small \begin{verbatim}
-    domain.set_name(project.basename)
-    domain.set_datadir(project.outputdir)
-    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
-        'ymomentum'])
-\end{verbatim}}
-
-
-\subsection{Initial Conditions}
-Quantities for \file{runsydney.py} are set
-using similar methods to those in \file{runup.py}. However,
-in this case, many of the values are read from the auxiliary file
-\file{project.py} or, in the case of \code{elevation}, from an
-ancillary points file.
-
-
-
-\subsubsection{Stage}
-
-For the scenario we are modelling in this case, we use a callable
-object \code{tsunami\_source}, assigned by means of a function
-\function{slump\_tsunami}. This is similar to how we set elevation in
-\file{runup.py} using a function---however, in this case the
-function is both more complex and more interesting.
-
-The function returns the water displacement for all \code{x} and
-\code{y} in the domain. The water displacement is a double Gaussian
-function that depends on the characteristics of the slump (length,
-thickness, slope, etc), its location (origin) and the depth at that
-location.
-
-
-\subsubsection{Friction}
-
-We assign the friction exactly as we did for \file{runup.py}:
-
-{\small \begin{verbatim}
-    domain.set_quantity('friction', 0.0)
-\end{verbatim}}
-
-
-\subsubsection{Elevation}
-
-The elevation is specified by reading data from a file:
-
-{\small \begin{verbatim}
-    domain.set_quantity('elevation',
-                        filename = project.combineddemname + '.pts',
-                        use_cache = True,
-                        verbose = True)
-\end{verbatim}}
-
-However, before this step can be executed, some preliminary steps
-are needed to prepare the file from which the data is taken. Two
-source files are used for this data---their names are specified in
-the file \file{project.py}, in the variables \code{coarsedemname}
-and \code{finedemname}. They contain `coarse' and `fine' data,
-respectively---that is, data sampled at widely spaced points over a
-large region and data sampled at closely spaced points over a
-smaller subregion. The data in these files is combined through the
-statement
-
-{\small \begin{verbatim}
-combine_rectangular_points_files(project.finedemname + '.pts',
-                                 project.coarsedemname + '.pts',
-                                 project.combineddemname + '.pts')
-\end{verbatim}}
-
-The effect of this is simply to combine the datasets by eliminating
-any coarse data associated with points inside the smaller region
-common to both datasets. The name to be assigned to the resulting
-dataset is also derived from the name stored in the variable
-\code{combinedname} in the file \file{project.py}.
-
-\subsection{Boundary Conditions}
-
-Setting boundaries follows a similar pattern to the one used for
-\file{runup.py}, except that in this case we need to associate a
-boundary type with each of the
-boundary tag names introduced when we established the mesh. In place of the four
-boundary types introduced for \file{runup.py}, we use the reflective
-boundary for each of the
-eight tagged segments defined by \code{create_mesh_from_regions}:
-
-{\small \begin{verbatim}
-    Br = Reflective_boundary(domain)
-    domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
-                          'right2': Br, 'top': Br, 'left1': Br,
-                          'left2': Br, 'left3': Br} )
-\end{verbatim}}
-
-\subsection{Evolution}
-
-With the basics established, the running of the `evolve' step is
-very similar to the corresponding step in \file{runup.py}. Here,
-the simulation is run for five hours (18000 seconds) with
-the output stored every two minutes (120 seconds).
-
-{\small \begin{verbatim}
-    import time t0 = time.time()
-
-    for t in domain.evolve(yieldstep = 120, duration = 18000):
-        print domain.timestepping_statistics()
-        print domain.boundary_statistics(tags = 'bottom')
-
-    print 'That took %.2f seconds' %(time.time()
-\end{verbatim}}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\chapter{\anuga Public Interface}
-\label{ch:interface}
-
-This chapter gives an overview of the features of \anuga available
-to the user at the public interface. These are grouped under the
-following headings and follows the outline of the examples described
-earlier:
-
-\begin{itemize}
-    \item Establishing the Mesh
-    \item Initialising the Domain
-    \item Specifying the Quantities
-    \item Initial Conditions
-    \item Boundary Conditions
-    \item Forcing Functions
-    \item Evolution
-\end{itemize}
-
-The listings are intended merely to give the reader an idea of what
-each feature is, where to find it and how it can be used---they do
-not give full specifications; for these the reader
-may consult the code. The code for every function or class contains
-a documentation string, or `docstring', that specifies the precise
-syntax for its use. This appears immediately after the line
-introducing the code, between two sets of triple quotes.
-
-Each listing also describes the location of the module in which
-the code for the feature being described can be found. All modules
-are in the folder \file{inundation} or one of its subfolders, and the
-location of each module is described relative to \file{inundation}. Rather
-than using pathnames, whose syntax depends on the operating system,
-we use the format adopted for importing the function or class for
-use in Python code. For example, suppose we wish to specify that the
-function \function{create\_mesh\_from\_regions} is in a module called
-\module{mesh\_interface} in a subfolder of \module{inundation} called
-\code{pmesh}. In Linux or Unix syntax, the pathname of the file
-containing the function, relative to \file{inundation}, would be
-
-\begin{center}
-%    \code{pmesh/mesh\_interface.py}
-    \code{pmesh}$\slash$\code{mesh\_interface.py}
-\end{center}
-
-while in Windows syntax it would be
-
-\begin{center}
-    \code{pmesh}$\backslash$\code{mesh\_interface.py}
-\end{center}
-
-Rather than using either of these forms, in this chapter we specify
-the location simply as \code{pmesh.mesh\_interface}, in keeping with
-the usage in the Python statement for importing the function,
-namely:
-\begin{center}
-    \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
-\end{center}
-
-Each listing details the full set of parameters for the class or
-function; however, the description is generally limited to the most
-important parameters and the reader is again referred to the code
-for more details.
-
-The following parameters are common to many functions and classes
-and are omitted from the descriptions given below:
-
-%\begin{center}
-\begin{tabular}{ll}  %\hline
-%\textbf{Name } & \textbf{Description}\\
-%\hline
-\emph{use\_cache} & Specifies whether caching is to be used for improved performance. See Section \ref{sec:caching} for details on the underlying caching functionality\\
-\emph{verbose} & If \code{True}, provides detailed terminal output
-to the user\\  % \hline
-\end{tabular}
-%\end{center}
-
-\section{Mesh Generation}
 \refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
-
-\begin{classdesc}  {Mesh}{userSegments=None,
-                 userVertices=None,
-                 holes=None,
-                 regions=None,
-                 geo_reference=None}
-Module: \module{pmesh.mesh}
-
-A class used to store a representation of a two-dimensional
-triangular mesh. The user may initialise the class by specifying
-lists of segments and/or vertices, using the parameters
-\code{userSegments} and \code{userVertices}, and may also specify
-lists of regions and/or holes, using the parameters \code{regions}
-and \code{holes}.
-\end{classdesc}
 
 \begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
@@ -1091 +1081 @@
 This function allows a user to initiate the automatic creation of a
 mesh inside a specified polygon (input \code{bounding_polygon}).
-Among the parameters that can be
-set are the \emph{resolution} (maximal area for any triangle in the
-mesh) and the minimal angle allowable in any triangle. The user can
-specify a number of internal polygons within each of which a
-separate mesh is to be created, generally with a smaller resolution.
-\code{interior_regions} is a paired list containing the interior
-polygon and its resolution.
+Among the parameters that can be set are the \emph{resolution}
+(maximal area for any triangle in the mesh) and the minimal angle
+allowable in any triangle. The user can specify a number of internal
+polygons within each of which a separate mesh is to be created,
+generally with a smaller resolution. \code{interior_regions} is a
+paired list containing the interior polygon and its resolution.
 Additionally, the user specifies a list of boundary tags, one for
 each edge of the bounding polygon.
@@ -1103 +1092 @@
 
 
-\begin{funcdesc} {add\_region}{}
-
-\end{funcdesc}
-
-\begin{funcdesc} {add\_hole}{}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}  {add\_region\_from\_polygon}{self, polygon, tags=None,
+
+
+\begin{classdesc}  {Mesh}{userSegments=None,
+                 userVertices=None,
+                 holes=None,
+                 regions=None,
+                 geo_reference=None}
+Module: \module{pmesh.mesh}
+
+A class used to store a representation of a two-dimensional
+triangular mesh. The user may initialise the class by specifying
+lists of segments and/or vertices, using the parameters
+\code{userSegments} and \code{userVertices}, and may also specify
+lists of regions and/or holes, using the parameters \code{regions}
+and \code{holes}.
+\end{classdesc}
+
+
+\subsection{Key Methods of Class Mesh}
+
+\begin{methoddesc} {add\_region}{}
+
+\end{methoddesc}
+
+\begin{methoddesc} {add\_hole}{}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}  {add\_region\_from\_polygon}{self, polygon, tags=None,
                                 max_triangle_area=None, geo_reference=None}
 Module: \module{pmesh.mesh}  Class: \class{Mesh}
 
-% Translate following into layman's language
 This method is used to add a region to a \class{Mesh} instance.  The
 region is described by the input \code{polygon}.  Additionally, the
@@ -1122 +1130 @@
 bounding polygon.
 
-
-\end{funcdesc}
-
-\begin{funcdesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None,
+\end{methoddesc}
+
+
+\begin{methoddesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None,
     geo_reference=None}
-Module: \module{pmesh.mesh.Mesh}
+Module: \module{pmesh.mesh}  Class: \class{Mesh}
 
 % Translate following into layman's language
-This method is used to add a `hole' wihtin a region ---that is, to define a
-interior region where the
-triangular mesh will not be generated---to a \class{Mesh} instance.
-The region is described by the polygon passed in.  Additionally, the
-user specifies a list of boundary tags, one for each edge of the
-bounding polygon.
-\end{funcdesc}
-
-\begin{funcdesc}  {generate\_mesh}{self,
+This method is used to add a `hole' within a region ---that is, to
+define a interior region where the triangular mesh will not be
+generated---to a \class{Mesh} instance. The region is described by
+the polygon passed in.  Additionally, the user specifies a list of
+boundary tags, one for each edge of the bounding polygon.
+\end{methoddesc}
+
+\begin{methoddesc}  {generate\_mesh}{self,
                       maximum_triangle_area=None,
                       minimum_triangle_angle=28.0,
                       verbose=False}
-Module: \module{pmesh.mesh.Mesh}
+Module: \module{pmesh.mesh}  Class: \class{Mesh}
 
 % Translate following into layman's language
@@ -1148 +1155 @@
 area of any triangle in the mesh can be specified, along with the
 minimum angle in any triangle.
-\end{funcdesc}
-
-
-\begin{funcdesc}  {export\_mesh_file}{self,ofile}
-Module: \module{pmesh.mesh.Mesh}
+\end{methoddesc}
+
+
+\begin{methoddesc}  {export\_mesh_file}{self,ofile}
+Module: \module{pmesh.mesh}  Class: \class{Mesh}
 
 % Translate following into layman's language
@@ -1159 +1166 @@
 the extension \code{.msh} for the file to be in NetCDF format and
 \code{.tsh} for the file to be ASCII format.
-\end{funcdesc}
-
-
-\begin{funcdesc}  {import_ungenerate_file}{self,ofile, tag=None}
-Module: \module{pmesh.mesh.Mesh}
+\end{methoddesc}
+
+
+\begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None}
+Module: \module{pmesh.mesh}  Class: \class{Mesh}
 
 % Translate following into layman's language
-This method is used to import a polygon file in the ungenerate format,
-which is used by arcGIS. The polygons are converted to vertices and segments.\code{ofile} is the
-name of the polygon file.  \code{tag} is the tag given to all
-the polygons segments.
+This method is used to import a polygon file in the ungenerate
+format, which is used by arcGIS. The polygons are converted to
+vertices and segments. \code{ofile} is the name of the polygon file.
+\code{tag} is the tag given to all the polygon's segments.
 
 This function can be used to import building footprints.
-\end{funcdesc}
+\end{methoddesc}
 
 %%%%%%
@@ -1201 +1208 @@
 This class is used to create an instance of a data structure used to
 store and manipulate data associated with a mesh. The mesh is
-specified either by assigning the name of a meshfile to
+specified either by assigning the name of a mesh file to
 \code{source} or by
 \end{classdesc}
@@ -1227 +1234 @@
 \subsection{Key Methods of Domain}
 
-\begin{funcdesc} {set\_name}{name}
+\begin{methoddesc} {set\_name}{name}
     Module: \refmodule{pyvolution.domain}, page \pageref{mod:pyvolution.domain}  %\code{pyvolution.domain}
 
     Assigns the name \code{name} to the domain.
-\end{funcdesc}
-
-\begin{funcdesc} {get\_name}{}
+\end{methoddesc}
+
+\begin{methoddesc} {get\_name}{}
     Module: \module{pyvolution.domain}
 
     Returns the name assigned to the domain by \code{set\_name}. If no name has been
     assigned, returns \code{`domain'}.
-\end{funcdesc}
-
-\begin{funcdesc} {set\_datadir}{name}
+\end{methoddesc}
+
+\begin{methoddesc} {set\_datadir}{name}
     Module: \module{pyvolution.domain}
 
@@ -1261 +1268 @@
         domain.set_datadir{'project' + os.sep + 'data'}
     \end{verbatim}}
-\end{funcdesc}
-
-\begin{funcdesc} {get\_datadir}{}
+\end{methoddesc}
+
+\begin{methoddesc} {get\_datadir}{}
     Module: \module{pyvolution.domain}
 
@@ -1270 +1277 @@
     been run, returns the value \code{default\_datadir} specified in
     \code{config.py}.
-\end{funcdesc}
-
-\begin{funcdesc} {set\_time}{time=0.0}
+\end{methoddesc}
+
+\begin{methoddesc} {set\_time}{time=0.0}
     Module: \module{pyvolution.domain}
 
     Sets the initial time, in seconds, for the simulation. The
     default is 0.0.
-\end{funcdesc}
-
-\begin{funcdesc} {set\_default\_order}{n}
+\end{methoddesc}
+
+\begin{methoddesc} {set\_default\_order}{n}
     Sets the default (spatial) order to the value specified by
     \code{n}, which must be either 1 or 2. (Assigning any other value
     to \code{n} will cause an error.)
-\end{funcdesc}
+\end{methoddesc}
 
 
@@ -1300 +1307 @@
 condition setting; it can be used at any time throughout the simulation.
 
-\begin{funcdesc}{set\_quantity}{name,
+\begin{methoddesc}{set\_quantity}{name,
     numeric = None,
     quantity = None,
@@ -1354 +1361 @@
 
 
-\end{funcdesc}
+\end{methoddesc}
 
 
@@ -1469 +1476 @@
 to assign boundary conditions according to the tags used to label boundary segments.
 
-\begin{funcdesc}{set\_boundary}{boundary_map}
+\begin{methoddesc}{set\_boundary}{boundary_map}
 Module: \module{pyvolution.domain}
 
@@ -1479 +1486 @@
 and whose keys are the symbolic tags.
 
-\end{funcdesc}
-
-\begin{funcdesc} {get\_boundary\_tags}{}
+\end{methoddesc}
+
+\begin{methoddesc} {get\_boundary\_tags}{}
 Module: \module{pyvolution.mesh}
 
 Returns a list of the available boundary tags.
-\end{funcdesc}
+\end{methoddesc}
 
 %%%
@@ -1550 +1557 @@
 The underlying domain must be specified when boundary is instantiated
 
-This type of boundary is useful when stage is known at the boundary as a 
+This type of boundary is useful when stage is known at the boundary as a
 function of time, but momenta (or speeds) aren't.
 
@@ -1585 +1592 @@
 \section{Evolution}
 
-  \begin{funcdesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
+  \begin{methoddesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
 
   Module: \module{pyvolution.domain}
@@ -1609 +1616 @@
   \end{verbatim}}
 
-  \end{funcdesc}
+  \end{methoddesc}
 
 
@@ -1618 +1625 @@
   \begin{funcdesc}{statistics}{}
   Module: \module{pyvolution.domain}
-  
+
   \end{funcdesc}
-    
+
   \begin{funcdesc}{timestepping\_statistics}{}
   Module: \module{pyvolution.domain}
@@ -1827 +1834 @@
 
 
-\subsection{Meshfile Formats}
-
-A meshfile is a file that has a specific format suited to specifying
-mesh data for \anuga. A meshfile can have one of two formats: it can
-be either a TSH file, which is an ASCII file, or an MSH file, which
-is a NetCDF file. A meshfile can be generated from the function
-\function{create\_mesh\_from\_regions} (see Section
+\subsection{Mesh File Formats}
+
+A mesh file is a file that has a specific format suited to
+specifying mesh data for \anuga. A mesh file can have one of two
+formats: it can be either a TSH file, which is an ASCII file, or an
+MSH file, which is a NetCDF file. A mesh file can be generated from
+the function \function{create\_mesh\_from\_regions} (see Section
 \ref{sec:meshgeneration}) and used to initialise a domain.
 
-A meshfile describes the outline of the mesh---the vertices and line
-segments that enclose the region in which the mesh is created---and
-the triangular mesh itself, which is specified by listing the
-triangles and their vertices, and the segments, which are those
-sides of the triangles that are associated with boundary conditions.
-
-In addition, a meshfile may contain `holes' and/or `regions'. A hole
-or region is defined by specifying a point and a number of segments
-that enclose that point. A hole represents an area where no mesh is
-to be created, while a region is a labelled area used for defining
-properties of a mesh, such as friction values.
-
-A meshfile can also contain a georeference, which describes an
+A mesh file describes the outline of the mesh---the vertices and
+line segments that enclose the region in which the mesh is
+created---and the triangular mesh itself, which is specified by
+listing the triangles and their vertices, and the segments, which
+are those sides of the triangles that are associated with boundary
+conditions.
+
+In addition, a mesh file may contain `holes' and/or `regions'. A
+hole or region is defined by specifying a point and a number of
+segments that enclose that point. A hole represents an area where no
+mesh is to be created, while a region is a labelled area used for
+defining properties of a mesh, such as friction values.
+
+A mesh file can also contain a georeference, which describes an
 offset to be applied to $x$ and $y$ values---eg to the vertices.
 
@@ -2063 +2071 @@
   detected by examining the functions \code{bytecode (co\_code, co\_consts,
   func\_defaults, co\_argcount)} and the function will be recomputed.
-  However, caching will not detect changes in modules used by \code{func}. 
+  However, caching will not detect changes in modules used by \code{func}.
   In this case cache must be cleared manually.
 
@@ -2335 +2343 @@
 
 
-\begin{funcdesc}{import\_points\_file}{delimiter = None, verbose = False}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{export\_points\_file}{ofile, absolute=False}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{get\_data\_points}{absolute = True}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{set\_attributes}{attributes}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{get\_attributes}{attribute_name = None}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{get\_all\_attributes}{}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{set\_default\_attribute\_name}{default_attribute_name}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{set\_geo\_reference}{geo_reference}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{add}{}
-
-\end{funcdesc}
+\begin{methoddesc}{import\_points\_file}{delimiter = None, verbose = False}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{export\_points\_file}{ofile, absolute=False}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_data\_points}{absolute = True}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{set\_attributes}{attributes}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_attributes}{attribute_name = None}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_all\_attributes}{}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{set\_default\_attribute\_name}{default_attribute_name}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{set\_geo\_reference}{geo_reference}
+
+\end{methoddesc}
+
+
+\begin{methoddesc}{add}{}
+
+\end{methoddesc}
 
 
@@ -2383 +2391 @@
 
 \section{alpha\_shape}
-An \emph{alpha shape} is a shape created from a set of points in the
-plane, according to an algorithm. This shape is intended to capture
-the intuitive notion of the `shape formed by the points'. For a
-sufficiently simple set, the alpha shape reduces to the more precise
-notion of the convex hull, but in general an alpha shape can be much
-much more complex and may be far from convex.
-
-In the context of \anuga, an alpha shape is used to fit a polygonal
-boundary around a set of points when fitting a mesh to a region. The
-algorithm uses a parameter $\alpha$ that can be adjusted to make the
-resultant shape resemble the shape suggested by intuition more
-closely.
+\emph{Alpha shapes} are used to generate close-fitting boundaries
+around sets of points. The alpha shape algorithm produces a shape
+that approximates to the `shape formed by the points'---or the shape
+that would be seen by viewing the points from a coarse enough
+resolution. For the simplest types of point sets, the alpha shape
+reduces to the more precise notion of the convex hull. However, for
+many sets of points the convex hull does not provide a close fit and
+the alpha shape usually fits more closely to the original point set,
+offering a better approximation to the shape being sought.
+
+In \anuga, an alpha shape is used to generate a polygonal boundary
+around a set of points before mesh generation. The algorithm uses a
+parameter $\alpha$ that can be adjusted to make the resultant shape
+resemble the shape suggested by intuition more closely. An alpha
+shape can serve as an initial boundary approximation that the user
+can adjust as needed.
 
 The following paragraphs describe the class used to model an alpha
-shape and some of the more important methods and attributes
-associated with instances of this class.
+shape and some of the important methods and attributes associated
+with instances of this class.
 
 \begin{classdesc}{Alpha\_Shape}{points, alpha = None}
@@ -2407 +2419 @@
 \code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter
 \code{points}) and, optionally, a value for the parameter
-\code{alpha}. The alpha shape is then computed and details of the
-required boundary may be retrieved as attributes of the class
-instance.
+\code{alpha}. The alpha shape is then computed and the user can then
+retrieve details of the boundary through the attributes defined for
+the class.
 \end{classdesc}
 
@@ -2416 +2428 @@
 Module: \code{alpha\_shape}
 
-This function reads points from the specified file
+This function reads points from the specified point file
 \code{point\_file}, computes the associated alpha shape (either
 using the specified value for \code{alpha} or, if no value is
-specified, automatically setting it to a value judged to be optimal)
-and outputs the boundary to a file named \code{boundary\_file}. This
-output file lists the coordinates \code{x, y} of each point in the
-boundary, using one line per point.
+specified, automatically setting it to an optimal value) and outputs
+the boundary to a file named \code{boundary\_file}. This output file
+lists the coordinates \code{x, y} of each point in the boundary,
+using one line per point.
 \end{funcdesc}
 
 
-\begin{funcdesc}{set\_boundary\_type}{self,raw_boundary=True,
+\begin{methoddesc}{set\_boundary\_type}{self,raw_boundary=True,
                           remove_holes=False,
                           smooth_indents=False,
                           expand_pinch=False,
                           boundary_points_fraction=0.2}
-Module: \code{alpha\_shape}
+Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
 
 This function sets flags that govern the operation of the algorithm
 that computes the boundary, as follows:
 
-        Set \code{raw\_boundary = True} to return raw boundary, i.e. the regular edges of the
-                        alpha shape.\\
-        Set \code{remove\_holes = True} to remove small holes
-                        (`small' is defined by
-                        \code{boundary\_points\_fraction})\\
-        Set \code{smooth\_indents = True} to remove sharp triangular indents in
-        boundary\\
-        Set \code{expand\_pinch = True} to test for pinch-off and
-        correct, i.e. to prevent a boundary vertex having more than two edges.
-\end{funcdesc}
+\code{raw\_boundary = True} returns raw boundary, i.e. the regular edges of the
+                alpha shape.\\
+\code{remove\_holes = True} removes small holes (`small' is defined by
+\code{boundary\_points\_fraction})\\
+\code{smooth\_indents = True} removes sharp triangular indents in
+boundary\\
+\code{expand\_pinch = True} tests for pinch-off and
+corrects---preventing a boundary vertex from having more than two edges.
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_boundary}{}
+Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
+
+Returns a list of tuples representing the boundary of the alpha
+shape. Each tuple represents a segment in the boundary by providing
+the indices of its two endpoints.
+\end{methoddesc}
+
+
+\begin{methoddesc}{write\_boundary}{file_name}
+Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
+
+Writes the list of 2-tuples returned by \code{get\_boundary} to the
+file \code{file\_name}, using one line per tuple.
+\end{methoddesc}
 
 \section{Numerical Tools}
@@ -2532 +2560 @@
 
 
-\section{\module{pyvolution.shallow\_water} --- 2D triangular domains for finite-volume computations of the shallow water wave equation. This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water Wave Equation
+\section{\module{pyvolution.shallow\_water} --- 2D triangular domains for finite-volume
+computations of the shallow water wave equation. This module contains a specialisation
+of class Domain from module domain.py consisting of methods specific to the Shallow Water
+Wave Equation
 }
 \declaremodule[pyvolution.shallowwater]{}{pyvolution.shallow\_water}
@@ -2582 +2613 @@
 \subsubsection{Why does a file\_function return a list of numbers when evaluated?}
 Currently, file\_function works by returning values for the conserved
-quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the triplet returned by file\_function.
+quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time
+and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the
+triplet returned by file\_function.
 
 \subsubsection{Which diagnostics are available to troubleshoot a simulation?}
@@ -2682 +2715 @@
     \indexedbold{mesh} & Triangulation of domain &\\
 
-    \indexedbold{meshfile} & A TSH or MSH file & \pageref{def:meshfile}\\
+    \indexedbold{mesh file} & A TSH or MSH file & \pageref{def:mesh file}\\
 
     \indexedbold{NetCDF} & &\\