source: documentation/user_manual/anuga_user_manual.tex @ 2409

% 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


\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.



\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-02-13 06:03:53 +0000 (Mon, 13 Feb 2006) $
%$LastChangedRevision: 2387 $
%$LastChangedBy: ole $

\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 Anuga's overall architecture, components and file formats
  \item Detailed descriptions of the user interface
\end{itemize}


\pagebreak
\chapter{Getting Started}

This section is designed to assist the reader to get started with
\anuga by working through a simple example. 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.

\section{Overview}

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]}

\section{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}

\section{The Code}

%FIXME: we are using the \code function here. 
%This should be used whereever 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.


{\scriptsize \begin{verbatim}
from pyvolution.mesh_factory import rectangular
from pyvolution.shallow_water import Domain, Reflective_boundary,
     Dirichlet_boundary, Time_boundary, Transmissive_boundary

#Create basic mesh
points, vertices, boundary = rectangular(10,10)

#Create shallow water domain
domain = Domain(points, vertices,boundary)
domain.set_name('bedslope')


#######################
# Initial conditions
def f(x,y):
    return -x/2

domain.set_quantity('elevation', f)
domain.set_quantity('friction', 0.1)

h = 0.05  # Constant depth
domain.set_quantity('stage', expression = 'elevation + %f' %h)


# Boundary conditions
from math import sin, pi
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])


domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br})


######################
#Evolution

domain.check_integrity()

for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0):
    domain.write_time()


\end{verbatim}}


\section{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}


\section{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 are to set the basename for the output file

{\scriptsize \begin{verbatim}
    domain.set_name('bedslope')
\end{verbatim}}


\section{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}.


\subsection{Elevation}

The elevation 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}
\begin{verbatim}
    domain.set_quantity('elevation', f)
\end{verbatim}}


\subsection{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.

\subsection{Depth}

Assigning depth illustrates a more complex 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 the quantity \code{stage} is defined by taking the quantity
elevation already defined and adding a constant value $h = 0.05$
to it everywhere. This expresses the fact that the water depth is
everywhere constant, so the surface is a constant height above the
elevation of the bed.

\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.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.


\section{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 yieldstep control the time interval between model output. Behind the scenes more timesteps are generally taken.




\section{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{Example with real data}

The following discussion builds on the \code{bedslope.py} example and
shows how, using the same basic outline, we can incorporate many more
complex features.

The chief difference is in the method used 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. 

In its simplest form, the mesh is created within a single polygon
whose vertices are at geographical locations specified by the user.  A
triangular mesh is created using points inside the polygon selected
through a random process, the user specifying the
\emph{resolution}---that is, the maximal area of a triangle used for
triangulation.

Figure XXX shows a simple example, in which the triangulation is
carried out within a pentagon. Instead of using the four tags
\code{`left'}, \code{`right'}, \code{`bottom'} and
\code{`top'} to distinguish boundary elements, the user can define
tags appropriate to the configuration being modelled.

While this offers more flexibility than the rectangular grid, it
doesn't provide a way to adapt to geographic or other features in the
landscape, for which we may require to vary the resolution. We achieve
more flexibility by extending this method, allowing the user to
specify a number of interior polygons which are triangulated
separately, possibly using different resolutions.  See Figure XXX.


\chapter{ANUGA Public Interface}

thoaedut



\begin{itemize} 

  \item \indexedcode{create_mesh_from_region}: Create mesh based on a bounding polygon and a number of internal polygons. Each polygon has a maximal area of triangles associated with it - the resolution. The bounding polygon also has symbolic \code{tags} associated with it.   
  Arguments are: 
  \item \indexedcode{pmesh_to_domain_instance}: Convert generated mesh file to domain object. Arguments are: Mesh file name and class specifying which domain class to instantiate. (Simpler)
  
  \item \indexedcode{file_function} %in util.py "High priority"  
  \item \indexedcode{Interpolation_function} %In least_squares.py ("High priority")  

  \item \indexedcode{set_region} ``Low priority. Will be merged into set\_quantity''  
  \item \indexedcode{set_quantity} ``Pretty mature''
  \item \indexedcode{set_boundary} ``Pretty mature''
  
\end{itemize} 


Diagnostics
\begin{itemize} 
  \item \indexedcode{write_time}
  \item \indexedcode{write_boundary_statistics}
  

\end{itemize} 


\subsection{Boundary conditions}

ANUGA provides a large number of predefined boundary conditions to be used with 
\code{set_boundary}

What do they do
How are they used

\begin{itemize} 
  \item \indexedcode{Reflective_boundary}
  function, arguments
  
  \item \indexedcode{Transmissive_boundary}
  function, arguments, CAVEATS  
  
  \item \indexedcode{Dirichlet_boundary}
  
  \item \indexedcode{Time_boundary}  
  
  \item \indexedcode{File_boundary}    
  Based on File\_function
  
  \item \indexedcode{}      
  
  \item \indexedcode{}        
  
  
  \item \indexedcode{User defined boundary conditions.}
  How to roll your own      
  
  

\end{itemize} 



\subsection{Initial conditions}

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

\begin{itemize} 


  \item \indexedcode{tsunami_slump}
  function, arguments
  
  \item \indexedcode{}

\end{itemize} 


\subsection{Initial conditions}

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}

Take some stuff from pyvolution/documentation and update it.





\appendix

\chapter{Supporting tools}


\section{caching} Could do now.



\section{swollen} Could do now.


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





\chapter{Glossary}

\begin{itemize}
    \item \indexedbold{ANUGA} name of software (joint development between ANU and GA)
    
    \item \indexedbold{Conserved quantity}    

    \item \indexedbold{Default order} is this really needed?

    \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{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{Quantity} conserved (state, x and y momentum)

    \item \indexedbold{Reflective boundary}

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

    \item \indexedbold{Stage}

    \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}   refers to the maximal area of each triangular cell in the mesh
    
    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created in this way )
    ANUGA represents polygons as either a list of 2-tuples, where the latter are either Python tuples or Python lists of length 2. The unit square, for example, would be represented by the polygon [ [0,0], [1,0], [1,1], [0,1] ]. Alternatively, polygons can be represented as $N \times 2$ Numeric arrays, 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}