source: documentation/user_manual/anuga_user_manual.tex @ 2474

% Complete documentation on the extended LaTeX markup used for Python
% documentation is available in ``Documenting Python'', which is part
% of the standard documentation for Python.  It may be found online
% at:
%
%     http://www.python.org/doc/current/doc/doc.html


%labels
%Sections and subsections \label{sec: }
%Chapters \label{ch: }
%Equations \label{eq: }
%Figures \label{fig: }


\input{definitions}


\documentclass{manual}

\title{\anuga User Manual}
\author{Howard Silcock, Ole Nielsen, Duncan Gray, Jane Sexton}

% Please at least include a long-lived email address;
% the rest is at your discretion.
\authoraddress{Geoscience Australia \\
  Email: \email{ole.nielsen@ga.gov.au}
}

%Draft date
\date{\today}                   % update before release!
                % Use an explicit date so that reformatting
                % doesn't cause a new date to be used.  Setting
                % the date to \today can be used during draft
                % stages to make it easier to handle versions.

\release{1.0}           % release version; this is used to define the
                % \version macro

\makeindex          % tell \index to actually write the .idx file
%\makemodindex          % If this contains a lot of module sections.

\setcounter{tocdepth}{3}

\begin{document}
\maketitle

% This makes the contents more accessible from the front page of the HTML.
\ifhtml
\chapter*{Front Matter\label{front}}
\fi

%Subversion keywords:
%
%$LastChangedDate: 2006-03-02 23:57:05 +0000 (Thu, 02 Mar 2006) $
%$LastChangedRevision: 2474 $
%$LastChangedBy: howard $

\input{copyright}


\begin{abstract}

\noindent \anuga\index{\anuga} is a hydrodynamic modelling tool that
allows users to model realistic flow problems in complex geometries.
Examples include dam breaks or the effects of natural hazards such
as riverine flooding, storm surges and tsunami.

The user must specify a study area represented by a mesh of triangular
cells, the topography and bathymetry, frictional resistance, initial
values for water level (called \emph{stage}\index{stage} within \anuga),
boundary
conditions and forces such as windstress or pressure gradients if
applicable.

\anuga tracks the evolution of water depth and horizontal momentum
within each cell over time by solving the shallow water wave equation
governing equation using a finite-volume method.

\anuga cannot model details of breaking waves, flow under ceilings such
as pipes, turbulence and vortices, vertical convection or viscous
flows.

\anuga also incorporates a mesh generator, called \code{pmesh}, that
allows the user to set up the geometry of the problem interactively as
well as tools for interpolation and surface fitting, and a number of
auxiliary tools for visualising and interrogating the model output.

Most \anuga components are written in the object-oriented programming
language Python and most users will interact with \anuga by writing
small Python programs based on the \anuga library
functions. Computationally intensive components are written for
efficiency in C routines working directly with the Numerical Python
structures.


\end{abstract}

\tableofcontents


\chapter{Introduction}


\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
instructions for setting up, configuring and running the software.

\section{Scope}

This manual covers only what is needed to operate the software
after installation. It does not includes instructions for
installing the software or detailed API documentation, both of
which will be covered in separate publications.

\section{Audience}

Readers are assumed to be familiar with the operating environment
and have a general understanding of the problem background, as
well as enough programming experience to adapt the code to
different requirements, as described in this manual,  and to
understand the basic terminology of object-oriented programming.

\section{Structure of This Manual}

This manual is structured as follows:

\begin{itemize}
  \item Background (What \anuga does)
  \item A \emph{Getting Started} section
  \item A detailed description of the public interface
  \item \anuga 's overall architecture, components and file formats
  \item Assumptions
\end{itemize}


\pagebreak
\chapter{Getting Started}

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 real-life example.

\section{A Simple Example}

\subsection{Overview}

What follows
is a discussion of the structure and operation of the file
\code{bedslope.py}, with just enough detail to allow the reader
to appreciate what's involved in setting up a scenario like the
one it depicts.

This example carries out the solution of the shallow-water wave
equation in the simple case of a configuration comprising a flat
bed, sloping at a fixed angle in one direction and having a
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 present example, as it represents a simple scenario, does not
include any forcing term, nor is the data taken from a file as it
would be in many typical cases. The quantities involved in the
present problem are:
\begin{itemize}
   \item elevation\index{elevation}
   \item friction\index{friction}
   \item depth\index{depth}
   \item stage\index{stage}
\end{itemize}

%\emph{[More details of the problem background]}

\subsection{Outline of the Program}

In outline, \code{bedslope.py} performs the following steps:

\begin{enumerate}

   \item Sets up a triangular mesh.

   \item Sets certain parameters governing the mode of
operation of the model-specifying, for instance, where to store the model output.

   \item Inputs various quantities describing physical measurements, such
as the elevation, to be specified at each mesh point (vertex).

   \item Sets up the boundary conditions.

   \item Carries 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}

%FIXME: we are using the \code function here.
%This should be used wherever possible
For reference we include below the complete code listing for
\code{bedslope.py}. Subsequent paragraphs provide a `commentary'
that describes each step of the program and explains it significance.

\verbatiminput{../../inundation/examples/bedslope.py}

\subsection{Establishing the Mesh}

The first task is to set up the triangular mesh to be used for the
scenario. This is carried out through the statement:

{\small \begin{verbatim}
    points, vertices, boundary = rectangular(10, 10)
\end{verbatim}}

The function \code{rectangular} is imported from a module
\code{mesh\_factory} defined elsewhere. (\anuga also contains
several other schemes that can be used for setting up meshes, but we
shall not discuss these now.) The above assignment sets up a $10
\times 10$ rectangular mesh, triangulated in a specific way. In
general, the assignment

{\small \begin{verbatim}
    points, vertices, boundary = rectangular(m, n)
\end{verbatim}}

returns:

\begin{itemize}

   \item a list \code{points} of length $N$, where $N = (m + 1)(n + 1)$,
comprising the coordinates $(x, y)$ of each of the $N$ mesh points,

   \item a list \code{vertices} of length $2mn$ (each entry specifies the three
vertices of one of the triangles used in the triangulation) , and

   \item a dictionary \code{boundary}, used to tag the triangle edges on
the boundaries. Each key corresponds to a triangle edge on one of
the four boundaries and its value is one of \code{`left'},
\code{`right'}, \code{`top'} and \code{`bottom'}, indicating
which boundary the edge in question belongs to.

\end{itemize}


\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 \code{Domain}, imported from
\code{shallow\_water}, which is an extension of a more generic
class of the same name in the module \code{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{Specifying the Quantities}

The next task is to specify a number of quantities that we wish to set
for each mesh point. The class \code{Domain} has a method
\code{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 \code{set\_quantity}. For
conserved quantities (\code{stage, xmomentum, ymomentum}) this is
called the \emph{initial condition}, for other quantities that aren't
updated by the equation, the same interface is used to assign their
values. The code in the present example demonstrates a number of forms
in which we can invoke \code{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 $(x, y)$ of
the plane.  It specifies that the bed slopes linearly in the $x$
direction, with slope $-\frac{1}{2}$,  and is constant in the $y$
direction.\\ %[screen shot?]
\\
Once the 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 demonstrates another way
we can use \code{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 \[\code{stage} =
\code{elevation} + \code{depth}\] To specify a constant depth of a
particular value, therefore, we need to specify that \code{stage} is
everywhere obtained by adding that constant value to the already
specified \code{elevation}. Doing this allows us to illustrate
another way to use \code{set\_quantity}, introducing an expression
involving other quantities:

{\small \begin{verbatim}
    h = 0.05 \# Constant depth
    domain.set_quantity('stage', expression = 'elevation + %f' %h)
\end{verbatim}}

Here we are stipulating that the quantity \code{stage} is defined by
taking the quantity elevation already defined and adding a constant
value $h = 0.05$ to it everywhere.

\subsubsection{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.0, 0.0])
\end{verbatim}}

The effect of these statements is to set up four 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 may be briefly described as
follows:

\begin{description}
    \item[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.

    \item[Transmissive boundary]Returns same conserved quantities as
    those present in its neighbour volume.

    \item[Dirichlet boundary]Specifies a fixed value at the
boundary.

    \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time.
\end{description}

Once the four boundary types have been specified through the
statements above, they can be applied through a statement of the
form

{\small \begin{verbatim}
    domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br})
\end{verbatim}}

This statement stipulates that, in the current example, the left
boundary is fixed, with an elevation of 0.2, while the other
boundaries are all reflective.


\subsection{Evolution}

The final statement \nopagebreak[3]
{\small \begin{verbatim}
    for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0):
        domain.write_time()
\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{finaltime}, 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} visualisation package to generate a visual display.


\section{How to Run the Code}

The code can be run in various ways:

\begin{itemize}
  \item{from a Windows command line} as in \code{python bedslope.py}
  \item{within the Python IDLE environment}
  \item{within emacs}
  \item{from a Linux command line} as in \code{python bedslope.py}
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{An Example with Real Data}

The following discussion builds on the concepts introduced through
the \code{bedslope.py} example and introduces a second example,
\code{run\_sydney\_smf.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
\code{bedslope.py}. [Include details of the scenario to which it
refers??]

\subsection{Overview}
As in the case of \code{bedslope.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 \code{run\_sydney\_smf.py}:

\verbatiminput{"runsydneysmf.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
\code{bedslope.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 through a random process. Figure XXX
shows a simple example of this, in which the triangulation is
carried out within a pentagon.

Boundary tags are not restricted to \code{`left'}, \code{`right'},
\code{`bottom'} and \code{`top'}, as in the case of
\code{bedslope.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 XXX.

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
\code{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 \code{project.py}. The resulting mesh is output to a
\emph{meshfile}\index{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}
(p. \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
\code{project.py}. This name is stored in the variable
\code{meshname}.


\subsection{Initialising the Domain}

As with \code{bedslope.py}, once we have created the mesh, the next
step is to create the data structure \code{domain}. We did this for
\code{bedslope.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 = pmesh_to_domain_instance(meshname,
Domain, use_cache = True, verbose = True)
\end{verbatim}}

The function \code{pmesh\_to\_domain\_instance} converts a meshfile
\code{meshname} into an instance of the data structure
\code{domain}, allowing us to use methods like \code{set\_quantity}
to set quantities and to apply other operations. (In principle, the
second argument of \code{pmesh\_to\_domain\_instance} can be any
subclass of \code{Domain}, but for applications involving the
shallow-water wave equation, the second argument of
\code{pmesh\_to\_domain\_instance} can always be set simply to
\code{Domain}.)

\subsection{Specifying the Quantities}
Setting quantities for \code{run\_sydney\_smf.py} is accomplished
using similar methods to those used in \code{bedslope.py}. However,
in this case, many of the values are read from the auxiliary file
\code{project.py} or, in the case of \code{elevation}, from an
ancillary points file.


\subsubsection{Fundamental Quantities}

The following statements specify a basename and data directory, and
identify quantities to be stored. For the first two, values are
taken from \code{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}}

\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
\code{slump\_tsunami}. This is similar to how we set elevation in
\code{bedslope.py} using a function---however, in this case the
function is both more complex and more interesting.

{\small \begin{verbatim}
#-------------------------------------------------------------------------------
# Set up scenario (tsunami_source is a callable object used with
set_quantity)
#-------------------------------------------------------------------------------

tsunami_source = slump_tsunami(length=30000.0,
                               depth=400.0,
                               slope=6.0,
                               thickness=176.0,
                               radius=3330,
                               dphi=0.23,
                               x0=project.slump_origin[0],
                               y0=project.slump_origin[1],
                               alpha=0.0,
                               domain=domain)


#-------------------------------------------------------------------------------
# Set up initial conditions
#-------------------------------------------------------------------------------

domain.set_quantity('stage', tsunami_source)
\end{verbatim}}

\subsubsection{Friction}

Assigning the friction is exactly parallel to what we did for
\code{bedslope.py}:

{\small \begin{verbatim}
domain.set_quantity('friction', 0.03)
#supplied by Benfield
\end{verbatim}}


\subsubsection{Elevation}

In this example, 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 \code{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 \code{project.py}.

\subsection{Boundary Conditions}

Setting boundaries in \code{run\_sydney\_smf.py} is very similar to
what we did in \code{bedslope.py}, except that we now have a larger
number of boundary tags:

{\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 \code{bedslope.py}:

{\small \begin{verbatim}
import time t0 = time.time()

for t in domain.evolve(yieldstep = 120, finaltime = 18000):
    domain.write_time()
    domain.write_boundary_statistics(tags = 'bottom')

print 'That took %.2f seconds' %(time.time()-t0)
\end{verbatim}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{\anuga Public 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:

\begin{itemize}
    \item Functions and Classes
    \item Diagnostics
    \item Boundary Conditions
    \item Initial Conditions
    \item Forcing Functions.
\end{itemize}

The listings do not give full specifications of the features, for
which the reader may consult the docstrings provided in the code.
They are intended merely to give the reader an idea of what each
feature is and how it can be used.

\section{Functions and Classes}

%\indexedcodeheader{create\_mesh\_from\_regions}\label{codehdr:createmeshfromregions}

%  Creates a triangular mesh based on a bounding polygon and
%  a number of internal polygons. For each polygon the user specifies a resolution---that is, the maximal area
%  of triangles in the mesh. The bounding polygon also has symbolic \code{tags} associated with it.

%  \textbf{Arguments:}

%  \begin{itemize}
%    \item the bounding polygon, %do we need to spell out how a polygon is specified?
%    \item a dictionary of boundary tags, for all segments of the bounding polygon,
%    \emph{[not clear what the keys and values of this dictionary are]}
%    \item the resolution for the bounding polygon,
%    \item (optional) a filename,  \emph{[what is the file for?]}
%    \item a list of 2-tuples \code{(polygon, resolution)}, specifying the interior polygons and
%    their associated resolutions.
%  \end{itemize}

%*********************************************************************************************

%\emph{\textbf{[The following is how the description of
%\emph{\code{create\_mesh\_from\_regions}} would be presented using
%the Python documentation system's \emph{\code{funcdesc}} environment
%for describing a module-level function.]}}

\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
                             boundary_tags,
                             maximum_triangle_area,
                             filename=None,
                             interior_regions=None,
                             poly_geo_reference=None,
                             mesh_geo_reference=None,
                             minimum_triangle_angle=28.0}
Creates a triangular mesh based on a bounding polygon and a number
of internal polygons. For each polygon the user specifies a
resolution---that is, the maximal area of triangles in the mesh. The
bounding polygon also has symbolic \code{tags} associated with it.
\end{funcdesc}

%*********************************************************************************************

%\indexedcodeheader{pmesh\_to\_domain\_instance}  \nopagebreak

% Converts a generated mesh file to a domain object.

 % \textbf{Arguments:}

%  \begin{itemize}
%    \item \code{file\_name} is the name of the mesh file to convert, including the extension
%    \item \code{DomainClass} is the Class that will be returned.
%    It must be a subclass of \code{Domain}, with the same interface as
%    domain. In practice, it can usually be set simply to
%    \code{Domain}.
%    \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain.
%  \end{itemize}


%  \begin{itemize}
%    \item Mesh file name
%    \item Class name, specifying the domain class to be instantiated.
%  \end{itemize}
%
%*********************************************************************************************

\begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
Converts a generated mesh file to a domain object.

\code{file\_name} is the name of the mesh file to convert, including
the extension. \code{DomainClass} is the class to be returned, which
must be a subclass of \code{Domain}, with the same interface as
\code{Domain}---in practice, it can usually be set simply to
\code{Domain}.

\end{funcdesc}
%*********************************************************************************************


%\indexedcodeheader{file\_function} %in util.py "High priority"

%  Reads the time history of spatial data from NetCDF file and returns a callable object.

%  \textbf{Arguments:}

%    \code{filename} -- Name of \code{sww} or \code{tms} file (see
%    Section \ref{sec:file formats} on page \pageref{sec:file formats}
%    for details about file formats).

%       \begin{quote}
%       If the file has extension \code{sww} then it is assumed to be spatio-temporal
%       or temporal and the callable object will have the form \code{f(t,x,y)} or \code{f(t)}
%       depending on whether the file contains spatial data.

%       If the file has extension \code{tms} then it is assumed to be temporal only
%       and the callable object will have the form \code{f(t)}.

%       Either form will return interpolated values based on the input file
%       using the underlying \code{interpolation\_function}.
%       \end{quote}

%    \code{domain} -- Associated domain object
%       If domain is specified, model time (\code{domain.starttime})
%       will be checked and possibly modified.

 %      \begin{quote}
%       All times are assumed to be in UTC.

%       All spatial information is assumed to be in absolute UTM coordinates.
%       \end{quote}

%    \code{quantities} -- the name of the quantity to be interpolated or a
%                 list of quantity names. The resulting function will return
%                 a tuple of values -- one for each quantity.

%    \code{interpolation\_points} -- list of absolute UTM coordinates for points at
%    which values are sought

%    \code{use\_cache}: \code{True} means that caching of intermediate result of
%               \code{Interpolation\_function} is attempted


  \begin{funcdesc}{file_function}{filename,
                  domain = None,
                  quantities = None,
                  interpolation_points = None,
                  verbose = False,
                  use_cache = False}

  Reads the time history of spatial data from NetCDF file and returns a callable object. Returns
  interpolated values based on the input file
  using the underlying \code{interpolation\_function}.

  \code{quantities} is either the name of a single quantity to be interpolated or a
                 list of such quantity names. The resulting function will return
                 a tuple of values---one for each quantity.

  \code{interpolation\_points} is a list of absolute UTM coordinates for points at
    which values are sought.

  \end{funcdesc}


  %  See Interpolation function for further documentation
%\indexedcodeheader{Interpolation\_function}
% Creates a callable object \code{f(t, id)} or \code{f(t,x,y)}
%    interpolated from a time series defined at the vertices of
%    a triangular mesh (such as those stored in \code{sww} files).

%    Let $m$ be the number of vertices, $n$ the number of triangles
 %   and $p$ the number of time steps.

 %   \textbf{Mandatory Arguments:}

 %       \begin{tabular}{ll}
 %       \code{time}: & $p \times 1$ array of monotonously increasing times (Float)\\


 %       \code{quantities}: & Dictionary of arrays or one array (Float). The arrays must  \\
 %       & have dimensions either $p \times m$ or $m \times 1$. The resulting function \\
%        & will be time dependent in the former case and constant with respect to time \\
%        & in the latter case.\\
 %       \end{tabular}


 %   \textbf{Optional Arguments:}

 %       \begin{tabular}{ll}
  %      \code{quantity\_names}: & List of keys into the quantities dictionary\\

 %       \code{vertex\_coordinates}: & $m \times 2$ array of coordinates (Float)\\

%        \code{triangles}: & $n \times 3$ array of indices into \code{vertex\_coordinates} (Int)\\

%        \code{interpolation\_points}: & $N \times 2$ array of coordinates to be interpolated to \\

%        \code{verbose}: & Level of reporting\\
%        \end{tabular}

%    The quantities returned by the callable object are specified by
%    the list \code{quantities} which must contain the names of the
%    quantities to be returned and also reflect the order, e.g. for
%    the shallow water wave equation, one would have
%    \code{quantities = ['stage', 'xmomentum', 'ymomentum']}.

%    The parameter \code{interpolation_points} decides at which points interpolated
%    quantities are to be computed whenever the object is called.
%    If \code{None}, returns average value.

\begin{classdesc}{Interpolation_function}{self,
                 time,
                 quantities,
                 quantity_names = None,
                 vertex_coordinates = None,
                 triangles = None,
                 interpolation_points = None,
                 verbose = False}
Creates a callable object \code{f(t, id)} or \code{f(t,x,y)}
interpolated from a time series defined at the vertices of a
triangular mesh (such as those stored in \code{sww} files).

\code{time} is an array of monotonically increasing times and
\code{quantities} is an array, or dictionary of arrays, of values to
be interpolated. The parameter \code{interpolation_points} may be
used to specify at which points interpolated
    quantities are to be computed whenever the object is called.
    If the default value \code{None} is used, returns average value.
\end{classdesc}


\begin{funcdesc}{set\_region}{???}
[Low priority. Will be merged into set\_quantity]
\end{funcdesc}

\begin{funcdesc}{set\_quantity}{???}
[Pretty mature]
\end{funcdesc}

\begin{funcdesc}{set\_boundary}{???}
[Pretty mature]
\end{funcdesc}



\section{Diagnostics}

  \begin{funcdesc}{write\_time}{???}

  \end{funcdesc}


  \begin{funcdesc}{write\_boundary\_statistics}{???}

  \end{funcdesc}



\section{Boundary Conditions}

\anuga provides a large number of predefined boundary conditions to
be used with \code{set\_boundary}.

 \subsection{Predefined boundary conditions}

  \begin{classdesc}{Reflective_boundary}{Boundary}
  Reflective boundary returns same conserved quantities as those present in
  the neighbouring volume but reflected.

  This class is specific to the shallow water equation as it works with the
  momentum quantities assumed to be the second and third conserved quantities.
  \end{classdesc}


  \begin{classdesc}{Transmissive_boundary}{domain = None}
  A transmissive boundary returns the same conserved quantities as
  those present in the neighbouring volume.

  The underlying domain must be specified when the boundary is instantiated.
  \end{classdesc}


  \begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None}
  A Dirichlet boundary returns constant values for the conserved
  quantities.
  \end{classdesc}


  \begin{classdesc}{Time_boundary}{domain = None, f = None}
  A time-dependent boundary returns values for the conserved quantities as a
  function \code{f(t)} of time. The user must specify the domain to get access to the model
  time.
  \end{classdesc}


  \begin{classdesc}{File_boundary}{Boundary}
  The boundary values are obtained from a file and interpolated. The file is
  assumed to contain a time series and possibly also spatial information.
  The conserved quantities are given as a function of time.
  \end{classdesc}


  \subsection{User-defined boundary conditions}
  [How to roll your own]



\section{Initial Conditions}

\anuga provides a number of predefined initial conditions to be used with
\code{set_quantity}.

  \begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None, \
                  x0=0.0, y0=0.0, alpha=0.0, \
                  gravity=9.8, gamma=1.85, \
                  massco=1, dragco=1, frictionco=0, psi=0, \
                  dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, \
                  domain=None,
                  verbose=False}
  This function returns a callable object representing an initial water
  displacement generated by a submarine sediment slide.

  The arguments include the downslope slide length, the water depth to the slide centre of mass,
  and the bathymetric slope.
  \end{funcdesc}

\section{Forcing Functions}

\anuga provides a number of predefined forcing functions to be used with .....

%\begin{itemize}


%  \item \indexedcode{}
%  [function, arguments]

%  \item \indexedcode{}

%\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{\anuga System Architecture}

From pyvolution/documentation

\section{File Formats}
\label{sec:file formats}

\anuga makes use of a number of different file formats. The
following table lists all these formats, which are described in more
detail in the paragraphs below.

\begin{tabular}{|ll|}  \hline
\code{.sww} & NetCDF format for storing model output
\code{f(t,x,y)}\\

\code{.tms} & NetCDF format for storing time series \code{f(t)}\\

\code{.xya} & ASCII format for storing arbitrary points and
associated attributes\\

\code{.pts} & NetCDF format for storing arbitrary points and
associated attributes\\

\code{.asc} & ASCII format of regular DEMs as output from ArcView\\

\code{.prj} & Associated ArcView file giving more metadata for
\code{.asc} format\\

\code{.ers} & ERMapper header format of regular DEMs for ArcView\\

\code{.dem} & NetCDF representation of regular DEM data\\

\code{.tsh} & ASCII format for storing meshes and associated
boundary and region info\\

\code{.msh} & NetCDF format for storing meshes and associated
boundary and region info\\

\code{.nc} & Native ferret NetCDF format\\

\code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
%\caption{File formats used by \anuga}
\end{tabular}


A typical dataflow can be described as follows:

\subsection{Manually Created Files}

\begin{tabular}{ll}
ASC, PRJ & Digital elevation models (gridded)\\
TSH & Triangular
meshes (e.g. created from \code{pmesh})\\
NC & Model outputs for use as boundary conditions (e.g. from MOST)
\end{tabular}

\subsection{Automatically Created Files}

\begin{tabular}{ll}
ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
DEMs to native \code{.pts} file\\

NC $\rightarrow$ SWW & Convert MOST boundary files to
boundary \code{.sww}\\

PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\

TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
Swollen\\

TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
\code{pyvolution}
\end{tabular}

%\[
%  \left[
%  \begin{array}{ccr}
%  2 & 4 & 4\\
%  1 & 1 & 1
%  \end{array}
%  \right]
%\]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Basic \anuga Assumptions}

(From pyvolution/documentation)


Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
If one wished to recreate scenarios prior to that date it must be done
using some relative time (e.g. 0).


All spatial data relates to the WGS84 datum (or GDA94) and has been
projected into UTM with false easting of 500000 and false northing of
1000000 on the southern hemisphere (0 on the northern).

It is assumed that all computations take place within one UTM zone.

DEMs, meshes and boundary conditions can have different origins within
one UTM zone. However, the computation will use that of the mesh for
numerical stability.


%OLD
%The dataflow is: (See data_manager.py and from scenarios)
%
%
%Simulation scenarios
%--------------------%
%%
%
%Sub directories contain scrips and derived files for each simulation.
%The directory ../source_data contains large source files such as
%DEMs provided externally as well as MOST tsunami simulations to be used
%as boundary conditions.
%
%Manual steps are:
%  Creation of DEMs from argcview (.asc + .prj)
%  Creation of mesh from pmesh (.tsh)
%  Creation of tsunami simulations from MOST (.nc)
%%
%
%Typical scripted steps are%
%
%  prepare_dem.py:  Convert asc and prj files supplied by arcview to
%                   native dem and pts formats%
%
%  prepare_pts.py: Convert netcdf output from MOST to an sww file suitable
%                  as boundary condition%
%
%  prepare_mesh.py: Merge DEM (pts) and mesh (tsh) using least squares
%                   smoothing. The outputs are tsh files with elevation data.%
%
%  run_simulation.py: Use the above together with various parameters to
%                     run inundation simulation.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\appendix

\chapter{Supporting Tools}


\section{caching}

  The \code{cache} function is used to provide supervised caching of function results. A Python
  function call of the form

      {\small \begin{verbatim}
      result = func(arg1,...,argn)
      \end{verbatim}}

  can be replaced by

      {\small \begin{verbatim}
      from caching import cache
      result = cache(func,(arg1,...,argn))
      \end{verbatim}}

  which returns the same output but reuses cached
  results if the function has been computed previously in the same context.
  \code{result} and the arguments can be simple types, tuples, list, dictionaries or
  objects, but not unhashable types such as functions or open file objects.
  The function \code{func} may be a member function of an object or a module.

  This type of caching is particularly useful for computationally intensive
  functions with few frequently used combinations of input arguments. Note that
  if the inputs or output are very large caching might not save time because
  disc access may dominate the execution time.

  If the function definition changes after a result has been cached it will be
  detected by examining the functions \code{bytecode (co_code, co_consts,
  func_defualts, co_argcount)} and it will be recomputed.

  Options are set
  by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a
  Python dictionary \code{options} that stores settings such as the name of the directory used, the maximum
  number of cached files allowed, and so on.

  The \code{cache} function allows the user also to specify a list of dependent files. If any of these
  have been changed, the function is recomputed and the results stored again.

  Other features include support for compression and a capability to \ldots


   \textbf{USAGE:}

    {\small \begin{verbatim}
    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
                   compression, evaluate, test, return_filename)}
    \end{verbatim}}

  \textbf{ARGUMENTS:}

  \begin{tabular}{ll}
    \code{func} & Function object (Required)\\
    \code{args} & Arguments to func (Default: ())\\
    \code{kwargs} & Keyword arguments to func (Default: {})  \\
    \code{dependencies} & Filenames that func depends on (Default: \code{None})\\
    \code{cachedir} & Directory for cache files (Default: \code{options['cachedir']})\\
    \code{verbose} & Flag verbose output to stdout
                       (Default: \code{options['verbose']})\\
    \code{compression} & Flag zlib compression (Default: \code{options['compression']})\\
    \code{evaluate} & Flag forced evaluation of func (Default: 0)\\
    \code{test} & Flag test for cached results (Default: 0)\\
    \code{clear} & Flag delete cached results (Default: 0)\\
    \code{return_filename} & Flag return of cache filename (Default: 0)\\
  \end{tabular}


  \textbf{LIMITATIONS:}

  \begin{itemize}
   \item Caching uses the apply function and will work with anything that can be
      pickled, so any limitation in apply or pickle extends to caching.

   \item A function to be cached should not depend on global variables
      as wrong results may occur if globals are changed after a result has
      been cached.
   \end{itemize}




\section{swollen}


The main keys operating the interactive screen are:\\

\begin{tabular}{|ll|}   \hline

\code{w} & toggle wireframe\\

space bar & start/stop\\

up/down arrows & increase/decrease speed\\

left/right arrows & direction in time \emph{(when running)}\\ & step through simulation \emph{(when stopped)}\\

left mouse button & rotate\\

middle mouse button & pan\\

right mouse button & zoom\\  \hline

\end{tabular}

\vfill

The following table describes how to operate swollen from the command line:

Usage: \code{swollen [options] swwfile \ldots}\\  \nopagebreak
Options:\\  \nopagebreak
\begin{tabular}{ll}
  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY_CENTER |}\\
                                    & \code{HEAD_MOUNTED_DISPLAY}\\
  \code{--rgba} & Request a RGBA colour buffer visual\\
  \code{--stencil} & Request a stencil buffer visual\\
  \code{--stereo} & Use default stereo mode which is \code{ANAGLYPHIC} if not \\
                                    & overridden by environmental variable\\
  \code{--stereo <mode>} & \code{ANAGLYPHIC | QUAD_BUFFER | HORIZONTAL_SPLIT |}\\
                                    & \code{VERTICAL_SPLIT | LEFT_EYE | RIGHT_EYE |}\\
                                     & \code{ON | OFF} \\
  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
  \code{-help} & Display this information\\
  \code{-hmax <float>} & Height above which transparency is set to
                                     \code{alphamax}\\
  \code{-hmin <float>} & Height below which transparency is set to
                                     zero\\
  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
                                     up, default is overhead)\\
  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
  \code{-movie <dirname>} & Save numbered images to named directory and
                                     quit\\
  \code{-nosky} & Omit background sky\\
  \code{-scale <float>} & Vertical scale factor\\
  \code{-texture <file>} & Image to use for bedslope topography\\
  \code{-tps <rate>} & Timesteps per second\\
  \code{-version} & Revision number and creation (not compile)
                                     date\\
\end{tabular}

\section{utilities/polygons} Could do now.

\begin{itemize}
  \item \indexedcode{polygon_function}
  \item \indexedcode{read_polygon}
  \item \indexedcode{populate_polygon}
  \item \indexedcode{point_in_polygon}
  \item \indexedcode{inside_polygon}
  \item \indexedcode{outside_polygon}
  \item \indexedcode{point_on_line}
  \item \indexedcode{separate_points_by_polygon}
\end{itemize}

\section{coordinate_transforms}

\section{geo_spatial_data}

\section{pmesh GUI}

\section{alpha_shape}


\section{utilities/numerical_tools} Could do now.

\begin{itemize}
  \item \indexedcode{ensure_numeric}
  \item \indexedcode{mean}
  \item
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Glossary}

\begin{itemize}
    \item \indexedbold{\anuga} Name of software (joint development between ANU and GA)

    \item \indexedbold{domain}

    \item \indexedbold{Dirichlet boundary}

    \item \indexedbold{elevation} - refers to bathymetry and topography

    \item \indexedbold{bathymetry} offshore

    \item \indexedbold{topography} onshore

    \item \indexedbold{evolution} integration of the shallow water wave equations over time

    \item \indexedbold{forcing term}

    \item \indexedbold{IDLE} Development environment shipped with Python

    \item \indexedbold{Manning friction coefficient}

    \item \indexedbold{mesh}    Triangulation of domain

    \item \indexedbold{meshfile}  [generic word for either .tsh or
    .msh file]

    \item \indexedbold{points file}  [generic word for either .pts or
    .xya file]

    \item \indexedbold{grid} evenly spaced

    \item \indexedbold{NetCDF}

    \item \indexedbold{pmesh} does this really need to be here? it's a class/module?

    \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?

    \item \indexedbold{conserved quantity} conserved (state, x and y momentum)

    \item \indexedbold{reflective boundary}

    \item \indexedbold{smoothing} is this really needed?

    \item \indexedbold{stage}

%    \item \indexedbold{try this}

    \item \indexedbold{swollen} visualisation tool

    \item \indexedbold{time boundary} defined in the manual (flog from there)

    \item \indexedbold{transmissive boundary} defined in the manual (flog from there)

    \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)

    \item \indexedbold{ymomentum}  conserved quantity

    \item \indexedbold{resolution}   The maximal area of a triangular cell in a mesh

    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created
    in this way.)
    \anuga represents a polygon in one of two ways. One way is to represent it as a
    list whose members are either Python tuples
    or Python lists of length 2. The unit square, for example, would be represented by the
    list
    [ [0,0], [1,0], [1,1], [0,1] ]. The alternative is to represent it as an
    $N \times 2$ Numeric array, where $N$ is the number of points.

    NOTE: More can be read in the module utilities/polygon.py ....

    \item \indexedbold{easting}

    \item \indexedbold{northing}

    \item \indexedbold{latitude}

    \item \indexedbold{longitude}

    \item \indexedbold{edge}

    \item \indexedbold{vertex}

    \item \indexedbold{finite volume}

    \item \indexedbold{flux}

    \item \indexedbold{Digital Elevation Model (DEM)}


\end{itemize}

The \code{\e appendix} markup need not be repeated for additional
appendices.


%
%  The ugly "%begin{latexonly}" pseudo-environments are really just to
%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
%  not really valuable.
%
%  If you don't want the Module Index, you can remove all of this up
%  until the second \input line.
%

%begin{latexonly}
%\renewcommand{\indexname}{Module Index}
%end{latexonly}
%\input{mod\jobname.ind}        % Module Index

%begin{latexonly}
\renewcommand{\indexname}{Index}
%end{latexonly}
\input{\jobname.ind}            % Index



\end{document}