Index: /anuga_core/documentation/user_manual/anuga_user_manual.tex
===================================================================
--- /anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 4122)
+++ /anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 4123)
@@ -106,5 +106,6 @@
 governing equation using a finite-volume method.
 
-\anuga also incorporates a mesh generator, called \code{pmesh}, that
+\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
@@ -180,9 +181,10 @@
 terrains in the model are represented by predefined forcing terms.
 
-A mesh generator, called pmesh, allows the user to set up the geometry
+The built-in mesh generator %, called pmesh, 
+allows the user to set up the geometry
 of the problem interactively and to identify boundary segments and
 regions using symbolic tags.  These tags may then be used to set the
 actual boundary conditions and attributes for different regions
-(e.g. the Manning friction coefficient) for each simulation.
+(e.g.\ the Manning friction coefficient) for each simulation.
 
 Most \anuga components are written in the object-oriented programming
Index: /anuga_work/publications/linuxconf_2006/database1.bib
===================================================================
--- /anuga_work/publications/linuxconf_2006/database1.bib	(revision 4122)
+++ /anuga_work/publications/linuxconf_2006/database1.bib	(revision 4123)
@@ -72,4 +72,18 @@
   pages =        {839--855},
 }
+
+
+@ARTICLE{Nielsen2006,
+  author = {Ole Nielsen, Jane Sexton, Duncan Gray and Nick Bartzis},
+  year = 2006,
+  title = {Modelling answers tsunami questions},
+  journal = {AusGeo News}, 
+  month = {September},
+  year = {2006},
+  number = 83,
+  note = {\url{http://www.ga.gov.au/ausgeonews/ausgeonews200609/modelling.jsp}
+  }
+
+
 @ARTICLE{Rob99l,
   author = {C. Zoppou and S. Roberts},
Index: /anuga_work/publications/linuxconf_2006/paper_ole_nielsen.tex
===================================================================
--- /anuga_work/publications/linuxconf_2006/paper_ole_nielsen.tex	(revision 4122)
+++ /anuga_work/publications/linuxconf_2006/paper_ole_nielsen.tex	(revision 4123)
@@ -32,5 +32,5 @@
 \and
 S.~G.~Roberts\thanks{Dept. of Maths, Australian National University,
-Canberra, \textsc{Australia}. \protect\url{mailto:stephen.roberts}}}
+Canberra, \textsc{Australia}. \protect\url{mailto:stephen.roberts@anu.edu.au}}}
 
 \date{30 December 2006}
@@ -73,7 +73,6 @@
 for solving the conservative form of the Shallow Water Wave equation.
 In this paper we describe the model, the architecture and some applications.
-ANUGA has recently been released as Open Source available at 
-\url{http://sourceforge.net/projects/anuga}. This strategy will enable
-free access to the software and allow the risk research community to
+ANUGA has recently been released as Open Source. This strategy will enable
+free access to the software and allow the scientific community to
 use, validate and contribute to the software in the future.
 
@@ -108,51 +107,36 @@
 \label{sec:intro}
 
-%Floods are the single greatest cause of death due to natural hazards
-%in Australia, causing almost 40{\%} of the fatalities recorded
-%between 1788 and 2003~\cite{Blong-2005}. Analysis of buildings
-%damaged between 1900 and 2003 suggests that 93.6{\%} of damage is
-%the result of meteorological hazards, of which almost 25{\%} is
-%directly attributable to flooding~\cite{Blong-2005}.
-
-Flooding of coastal communities may result from surges of near-shore
-waters caused by severe storms. The extent of inundation is
-critically linked to tidal conditions, bathymetry and topography; as
-recently exemplified in the United States by Hurricane Katrina.
-While the scale of the impact from such events is not common, the
+The Indian Ocean tsunami on 26 December 2004 demonstrated the
+potentially catastrophic consequences of natural hazards.  While the
+scale of the impact from such events is not common, smaller-scale
+tsunami regularly threaten coastal communities
+around the world. Earthquakes which occur in the Java Trench near
+Indonesia (e.g.~\cite{TsuMIS1995} or \cite{Baldwin-2006}) and along
+the Puysegur Ridge to the south of New Zealand (e.g.~\cite{LebKC1998})
+have potential to generate tsunami that may threaten Australia's
+northwestern and southeastern coastlines. In addition, the
 preferential development of Australian coastal corridors means that
-storm-surge inundation of even a few hundred metres beyond the
-shoreline has increased potential to cause significant disruption
-and loss.
-
-Coastal communities also face the small but real risk of tsunami.
-Fortunately, catastrophic tsunami of the scale of the 26 December
-2004 event are exceedingly rare. However, smaller-scale tsunami are
-more common and regularly threaten coastal communities around the
-world. Earthquakes which occur in the Java Trench near Indonesia
-(e.g.~\cite{TsuMIS1995} or \cite{Baldwin-2006}) 
-and along the Puysegur Ridge to the south
-of New Zealand (e.g.~\cite{LebKC1998}) have potential to generate
-tsunami that may threaten Australia's northwestern and southeastern
-coastlines.
-
-Hydrodynamic modelling allows flooding, storm-surge and tsunami
-hazards to be better understood, their impacts to be anticipated
-and, with appropriate planning, their effects to be mitigated.
-Geoscience Australia in collaboration with the Mathematical Sciences
-Institute, Australian National University, is developing a software
-application called \AnuGA{} to model the hydrodynamics of floods,
-storm surges and tsunami. These hazards are modelled using the
-conservative shallow water equations which are described in
-section~\ref{sec:model}. In \AnuGA{} these equations are solved
-using a finite volume method as described in section~\ref{sec:fvm}.
-A more complete discussion of the method can be found in
-\cite{modsim2005} where the model and solution technique is
-validated on a standard tsunami benchmark data set.
-
-In this paper we will provide a description of the parallelisation
-of the code using a domain decomposition strategy and provide the
-preliminary timing results which verify the scalability of the
-parallel code.
-
+inundation from hydrological disasters such as tsunami or storm-surge
+of even a few hundred metres beyond the shoreline has increased
+potential to cause significant disruption and loss. The extent of
+inundation is critically linked to the event, tidal conditions,
+bathymetry and topography and it not feasible to make impact
+predictions using heuristics alone.
+
+Hydrodynamic modelling allows impacts from flooding, storm-surge and
+tsunami to be better understood, their impacts to be anticipated and,
+with appropriate planning, their effects to be mitigated.  Geoscience
+Australia in collaboration with the Mathematical Sciences Institute,
+Australian National University, is developing a software application
+called \AnuGA{} to model the hydrodynamics of floods, storm surges and
+tsunami. These hazards are modelled using the conservative shallow
+water equations which are described in section~\ref{sec:model}. In
+\AnuGA{} these equations are solved using a finite volume method as
+described in section~\ref{sec:fvm}.  A more complete discussion of the
+method can be found in \cite{modsim2005} where the model and solution
+technique is validated on a standard tsunami benchmark data set.
+Section~\ref{sec:software} describes the software implementation and
+the API while section~\ref{sec:validation} presents testing and
+validation results.
 
 
@@ -302,20 +286,43 @@
 \end{figure}
 
-
-
-
-
 In the computations presented in this paper we use an explicit Euler
 time stepping method with variable timestepping adapted to the
 observed CFL condition.
 
+
 \section{Software Implementation}
 
-To set up a scenario the user specifies the geometry (derived from bathymetric and topographic data), the initial water level, boundary conditions (e.g. tide), outputs from other models (e.g. a deep water tsunami model), and forcing terms (e.g. frictional resistance, wind stress, atmospheric pressure gradients etc.).  The geometry could for example be a digital elevation model of an estuary and a boundary could be a collection of time series derived from tide gauges.
-
-To help with these tasks, a tool called pmesh has been developed which allows the user to set up the geometry of the problem interactively.  Pmesh produces a triangular mesh of the study area in which the user can specify the locations and types of boundary conditions that apply as well as identifying regions for either mesh refinement or for assignment of values at run time.  Figure \ref{fig:anuga mesh} shows an example of 
-a geometry generated by pmesh.
-
-
+\AnuGA{} is mostly written in the object-oriented programming 
+language \Python{} with computationally intensive parts implemented 
+as highly optimised shared objects written in C. 
+
+\Python{} is known for its clarity, elegance, efficiency and
+reliability. Complex software can be built in \Python{} without undue
+distractions arising from idiosyncrasies of the underlying software
+language syntax. In addition, \Python{}'s automatic memory management,
+dynamic typing, object model and vast number of libraries means that
+software can be produced quickly and can be readily adapted to
+changing requirements throughout its lifetime.
+
+The fundamental object in \AnuGA{} is the \code{Domain} which 
+inherits functionality from a hierarchy of increasingly specialised 
+classes starting with a basic structural Mesh to classes implementing 
+the finite-volume scheme described in section \ref{sec:fvm}. Other classes 
+are \code{Quantity} which represents values of one variable across the mesh 
+along with their associated operations, \code{Geospatial_data} which 
+represents georeferenced elevation data and a collection of \code{Boundary} 
+classes which allows for a 'pluggable' way of driving the model. 
+The conserved quantities updated automatically by the numerical scheme 
+are \code{stage} (water level) $w$, \code{xmomentum} $uh$ and \code{ymomentum} 
+$vh$. The quanitites \code{elevation} $z$ and \code{friction} $\eta$ are 
+quantities that are not updated automaticall but can be changed explicitly
+if the user wishes to.  
+
+To set up a scenario the user specifies the study area along with any internal 
+regions where increased mesh resolution is required. External edges may 
+be labelled using symbolic tags which are subsequently used to bind 
+boundary condition objects to tagged segments of the boundary.  
+
+Figure \ref{fig:anuga mesh} shows an example of a mesh generated by \AnuGA{}.
 
 \begin{figure}
@@ -323,43 +330,90 @@
 \includegraphics[width=5.0cm,keepaspectratio=true]{tsunami-fig-1}
 \caption{Triangular mesh used in our finite volume method. Conserved
-quantities $h$, $uh$ and $vh$ are associated with the centroid of
-each triangular cell.} \label{fig:anuga mesh}
+quantities $h$, $uh$ and $vh$ are associated with each triangular cell.} 
+\label{fig:anuga mesh}
 \end{center}
 \end{figure}
 
- 
-%Figure 1 Mesh generated by pmesh for a reservoir simulation.
-
-When the model is run, the mesh is converted into a domain object which represents the study area, the mesh, quantities, boundaries and forcing terms together with methods for time stepping, flux calculations, and all other numerical operations pertinent to the model.
-
-
-The (conserved) quantities updated by the numerical scheme are stage (water level) and horizontal momentum while bed elevation and friction are quantities that are not updated.  Setting initial values for quantities is done through the method
-domain.set_quantity(name, X, location, region)
-where name is the name of the quantity (e.g. 'stage', 'xmomentum', 'ymomentum', 'elevation' or 'friction').  The variable X represents the source data for populating the quantity and may take one of the following forms:
+The mesh is then generated using \AnuGA{}'s built-in mesh generator and 
+converted into the \code{Domain} object which provides all methods used to 
+setup and run the flow simulation.
+
+Next step is to setup initial conditions for each Quantity object. For
+the elevation $z$ this is typically obtained from bathymetric and
+topographic data sets. Setting initial values for quantities is done
+through the method \code{domain.set_quantity(name, X, location,
+region)} where name is the name of the quantity (e.g.\ 'stage',
+'xmomentum', 'ymomentum', 'elevation' or 'friction').  The variable X
+represents the source data for populating the quantity and may take
+one of the following forms:
 
 \begin{itemize} 
-
-\item A constant value as in domain.set_quantity('stage', 1) which will set the initial water level to 1 m everywhere.
-\item Another quantity or a linear combination of quantities.  If q1 and q2 are two arbitrary quantities defined within the same domain, the expression set_quantity('stage', q1*(3*q2 + 5)) will set the stage quantity accordingly.  One common application of this would be to assign the stage as a constant depth above the bed elevation.
-\item An arbitrary function (or a callable object), f(x, y), where x and y are assumed to be vectors.  The quantity will take values for f at each location within the mesh.
-\item An arbitrary set of points and associated values (wrapped into a point_set object).  The points need not coincide with triangle vertices or centroids and a penalised least squares technique is employed to populate the quantity in a smooth and stable way.
+\item A constant value as in domain.set_quantity('stage', 1) which
+will set the initial water level to 1 m everywhere.
+\item Another quantity or a linear combination of quantities.  If q1
+and q2 are two arbitrary quantities defined within the same domain,
+the expression set_quantity('stage', q1*(3*q2 + 5)) will set the stage
+quantity accordingly.  One common application of this would be to
+assign the stage as a constant depth above the bed elevation.
+\item An arbitrary function (or a callable object), f(x, y), where x
+and y are assumed to be vectors. The quantity will be assigned values by 
+evaluating f at each location within the mesh.
+\item An arbitrary set of points and associated values (wrapped into a
+Geospatial_data object). The points need not coincide with triangle
+vertices or centroids and a penalised least squares technique is
+employed to populate the quantity in a smooth and stable way.
 \item A filename containing points and attributes.
-\item A Numerical Python array (or a list of numbers) ordered according to the internal data structure.
+\item A Numerical Python array (or a list of numbers) ordered
+according to the internal data structure.
 \end{itemize} 
 
 
-The parameter location determines whether the values should be assigned to triangle edge midpoints or vertices and region allows the operation to be restricted to a region specified by a symbolic tag or a set of indices.
-
-Since the least squares technique can be time consuming for large problems, set_quantity employs a caching technique which automatically decides whether to perform the computations or retrieve them from a cache.  This will typically speed up the build by several orders of magnitude after each computation has been performed once.
-
-Boundary conditions are bound to symbolic tags through the method domain.set_boundary which takes as input a lookup table (implemented as a Python dictionary) of the form {tag: boundary_object}.  The boundary objects are all assumed to be callable functions of vectors x and y.  Several predefined standard boundary objects are available and it is relatively straightforward to define problem-specific custom boundaries if needed.  The predefined boundary conditions include Dirichlet, Reflective, Transmissive, Temporal, and Spatio-Temporal boundaries.
-
-Forcing terms can be written according to a fixed protocol and added to the model using the idiom domain.forcing_terms.append(F) where F is assumed to be a user-defined callable object.
-
-When the simulation is running, the length of each time step is determined from the maximal speeds encountered and the sizes of triangles in order not to violate the CFL condition which specifies that no information should skip any triangles in one time step.  With large speeds and small triangles, time steps can become very small.  In order to access the state of the simulation at regular time intervals, AnuGA uses the method evolve:
-For t in domain.evolve(yieldstep, duration):
-   <do whatever>
-
-The parameter duration specifies the time period over which evolve operates, and control is passed to the body of the for-loop at each fixed yieldstep.  The internal time stepping is thus decoupled from the overall time stepping so that outputs may be stored, displayed or interrogated.  The evolve method has been implemented using a Python generator.
+The parameter location determines whether the values should be
+assigned to triangle edge midpoints or vertices and region allows the
+operation to be restricted to a region specified by a symbolic tag or
+a set of indices.
+
+Since the least squares technique can be time consuming for large
+problems, \code{set_quantity} employs a caching technique which automatically
+decides whether to perform the computations or retrieve them from a
+cache.  This will typically speed up the build by several orders of
+magnitude after each computation has been performed once.
+
+Boundary conditions are bound to symbolic tags through the method
+\code{domain.set_boundary} which takes as input a lookup table (implemented
+as a Python dictionary) of the form \code{\{tag: boundary_object\}}.  
+The boundary objects are all assumed to be callable functions of vectors x
+and y.  Several predefined standard boundary objects are available and
+it is relatively straightforward to define problem-specific custom
+boundaries if needed.  The predefined boundary conditions include
+Dirichlet, Reflective, Transmissive, Temporal, and Spatio-Temporal
+boundaries.
+
+Forcing terms can be written according to a fixed protocol and added 
+to the model using the idiom \code{domain.forcing_terms.append(F)} where F is 
+assumed to be a user-defined callable object.
+
+When the simulation is running, the length of each time step is
+determined from the maximal speeds encountered and the sizes of
+triangles in order not to violate the CFL condition which specifies
+that no information should skip any triangles in one time step.  With
+large speeds and small triangles, time steps can become very small.
+In order to access the state of the simulation at regular time
+intervals, \AnuGA{} uses the method evolve: 
+
+\begin{verbatim} 
+For t in domain.evolve(yieldstep, duration): 
+    <do whatever>
+\end{verbatim}     
+
+The parameter \code{duration} specifies the time period over which
+evolve operates, and control is passed to the body of the for-loop at
+each fixed time step called \code{yieldstep}.  The internal workings
+of the numerical scheme and its variable time stepping are thus
+decoupled from the fixed time stepping of the evolve loop.  This means
+that the user of the API may access the model at fixed timesteps to
+e.g.\ store model outputs, interrogate quantities or change the model
+itself at runtime. The evolve method has been implemented using a
+Python generator hence the reference to 'yield' in the parameter.
 
 Figure \ref{fig:beach runup} shows a simulation of water flowing onto a 
@@ -375,15 +429,4 @@
 \end{center}
 \end{figure}
-
- 
-%Figure 2  Simulation of a levee breach.
-
-Most of the components of AnuGA are written in Python, an object-oriented programming language known for its clarity, elegance, efficiency and reliability.  It is often said that "Python lets you focus on the problem at hand".  This means that it is possible to develop complex pieces of software without undue distractions in dealing with idiosyncrasies of the software language syntax.  Consequently, software written in Python can be produced quickly and can be readily adapted to changing requirements throughout its lifetime.
-
-
-
-
-
-
 
 
@@ -446,76 +489,7 @@
 
 
-
-\section{Parallel Implementation}\label{sec:parallel}
-
-To parallelize our algorithm we use a simple domain decomposition
-strategy. We suppose we have a global mesh which defines the domain
-of our problem. We must first subdivide the global mesh into a set
-of non-overlapping submeshes. This partitioning is done using the
-\Metis{} partitioning library. We will demonstrate the efficiency of
-this library in the following subsections. Once this partitioning
-has been done, and the proper communication patterns set, we can
-start to evolve our solution. Each timestep consists of
-independently and then communicate the appropriate ``ghost'' cell
-information once each timestep.
-
-%\begin{figure}[hbtp]
-%  \centerline{ \includegraphics[scale = 0.6]{domain.eps}}
-%  \caption{The first step of the parallel algorithm is to divide
-%  the mesh over the processors.}
-%  \label{fig:subpart}
-%\end{figure}
-
-
-
-\begin{figure}[h!]
-  \centerline{ \includegraphics[width=6.5cm]{mermesh.eps}}
-  \caption{The global Merimbula mesh}
- \label{fig:mergrid}
-\end{figure}
-
-\begin{figure}[h!]
-  \centerline{ \includegraphics[width=6.5cm]{mermesh4c.eps}
-  \includegraphics[width=6.5cm]{mermesh4a.eps}}
-
-  \centerline{ \includegraphics[width=6.5cm]{mermesh4d.eps}
-  \includegraphics[width=6.5cm]{mermesh4b.eps}}
-  \caption{The global Merimbula mesh partitioned into 4 submeshes using \Metis.}
- \label{fig:mergrid4}
-\end{figure}
-
-
-
-
-\begin{table}[h!]
-\caption{4-way and 8-way partition tests of Merimbula mesh showing
-the percentage distribution of cells between the
-submeshes.}\label{tbl:mer}
-\begin{center}
-\begin{tabular}{|c|c c c c|}
-\hline
-CPU & 0 & 1 & 2 & 3\\
-\hline
-Cells & 2757 & 2713 & 2761 & 2554\\
-\% & 25.6\% & 25.2\% & 25.6\% & 23.7\%\ \\
-\hline
-\end{tabular}
-
-\medskip
-
-\begin{tabular}{|c|c c c c c c c c|}
-\hline
-CPU & 0 & 1 & 2 & 3 & 4 & 5 & 6 & 7\\
-\hline
-Cells & 1229 & 1293 & 1352 & 1341 & 1349 & 1401 & 1413 & 1407\\
-\% & 11.4\% & 12.0\% & 12.5\% & 12.4\% & 12.5\% & 13.0\% & 13.1\% & 13.1\%\\
-\hline
-\end{tabular}
-\end{center}
-\end{table}
-
-
 \section{Conclusions}
-\label{sec:6} \AnuGA{} is a flexible and robust modelling system
+\label{sec:6} 
+\AnuGA{} is a flexible and robust modelling system
 that simulates hydrodynamics by solving the shallow water wave
 equation in a triangular mesh. It can model the process of wetting
@@ -525,6 +499,7 @@
 
 \AnuGA{} can take as input bathymetric and topographic datasets and
-simulate the behaviour of riverine flooding, storm surge and
-tsunami. Initial validation using wave tank data supports AnuGA's
+simulate the behaviour of riverine flooding, storm surge,
+tsunami or even dam breaks. 
+Initial validation using wave tank data supports \AnuGA{}'s
 ability to model complex scenarios. Further validation will be
 pursued as additional datasets become available.
@@ -534,19 +509,9 @@
 Geoscience Australia's ongoing research effort to model and
 understand the potential impact from natural hazards in order to
-reduce their impact on Australian communities.
-
-
-%\paragraph{Acknowledgements:}
-%The authors are grateful to Belinda Barnes, National Centre for
-%Epidemiology and Population Health, Australian National University,
-%and Matt Hayne and Augusto Sanabria, Risk Research Group, Geoscience
-%Australia, for helpful reviews of a previous version of this paper.
-%Author Nielsen publish with the permission of the CEO, Geoscience
-%Australia.
-
-% Preferably provide your bibliography as a separate .bbl file.
-% Include URLs, DOIs, Math Review numbers or Zentralblatt numbers in your bibliography
-% so we help connect the web of science and ensure maximum visibility
-% for your article.
+reduce their impact on Australian communities (see \cite{Nielsen2006}).
+
+The \AnuGA{} source code is available 
+at \url{http://sourceforge.net/projects/anuga}.
+
 \bibliographystyle{plain}
 \bibliography{database1}
