Index: /documentation/AnuGA_user_manual.tex
===================================================================
--- /documentation/AnuGA_user_manual.tex	(revision 2282)
+++ /documentation/AnuGA_user_manual.tex	(revision 2283)
@@ -22,10 +22,36 @@
 \section*{Introduction}
 
-\textbf{AnuGA} is a hydrodynamic inundation modelling tool that
-allows users to model the effects of natural hazards such as
-riverine flooding, storm surges and tsunami. It incorporates a
-mesh generator, called \texttt{pmesh}, that allows the user to set
-up
-the geometry of the problem interactively.\\
+\textbf{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} 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 \texttt{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.
+
+
+
 
 \subsection*{Purpose}
@@ -44,5 +70,5 @@
 \subsection*{Audience}
 
-Readers aare assumed to be familiar with the operating environment
+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
@@ -55,9 +81,8 @@
 
 \begin{itemize}
-
-    \item{A \emph{Getting Started} section}
-
-    \item{Detailed descriptions of the various components}
-
+  \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}
 
@@ -77,6 +102,6 @@
 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.\\
-\\
+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
@@ -86,6 +111,6 @@
 pressure gradients. Frictional resistance from the different
 terrains in the model is represented by predefined forcing
-terms.\\
-\\
+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
@@ -110,9 +135,9 @@
 
    \item Sets certain parameters governing the mode of
-operation of the model-specifying, for instance, whether the
-output is to be `smoothed'.
+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.
+as the elevation, to be specified at each mesh point (vertex).
 
    \item Sets up the boundary conditions.
@@ -128,9 +153,10 @@
 For reference we include below the complete code listing for
 \texttt{bedslope.py}. Subsequent paragraphs provide a `commentary'
-that describes each step of the program and explains it significance.\\
-\\
-\emph{[Can't work out how to prevent \LaTeX (or WinEdt) from
-wrapping lines, even in \emph{verbatim} mode, without putting}
-\verb+\\+\emph{s at the ends of lines!]}
+that describes each step of the program and explains it significance.
+
+
+%\emph{[Can't work out how to prevent \LaTeX (or WinEdt) from
+%wrapping lines, even in \emph{verbatim} mode, without putting}
+%\verb+\\+\emph{s at the ends of lines!]}
 
 {\scriptsize \begin{verbatim}
@@ -191,5 +217,5 @@
 
 {\small \begin{verbatim}
-    points, vertices, boundary = rectangular(10, 10) .
+    points, vertices, boundary = rectangular(10, 10) 
 \end{verbatim}}
 
@@ -253,13 +279,17 @@
 \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 \texttt{Domain} has a method
+The next task is to specify a number of quantities that we wish to set
+for each mesh point. The class \texttt{Domain} has a method
 \texttt{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, all of
-which can be passed as arguments. The code in the present example
-demonstrates a number of forms in which we can invoke
-\texttt{set\_quantity}.
+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 \texttt{set\_quantity}. For
+conserved quantities (\texttt{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 \texttt{set\_quantity}.
 
 
@@ -272,5 +302,4 @@
 
 {\small \begin{verbatim}
-    \# Initial conditions
     def f(x,y):
         return -x/2
@@ -344,9 +373,9 @@
 
 \begin{description}
-    \item[Reflective boundary]Returns same conserved
-quantities as those present in its neighbour volume but reflected.
-Specific to the shallow water equation as it works with the
-momentum quantities assumed to be the second and third conserved
-quantities.
+    \item[Reflective boundary] Returns same \texttt{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.
@@ -381,4 +410,7 @@
 series of steps indicated by the values of \texttt{yieldstep} and
 \texttt{finaltime}, which can be altered as required.
+The yieldstep control the time interval between model output. Behind the scenes more timesteps are generally taken.
+
+
 
 
@@ -390,5 +422,5 @@
 The output is a NetCDF file with the extension \texttt{.sww}. It
 contains stage and momentum information and can be used with the
-\texttt{swollen} package to generate a visual display.
+\texttt{swollen} visualisation package to generate a visual display.
 
 
@@ -398,5 +430,5 @@
 
 \begin{itemize}
-\item{from a Windows command line}
+\item{from a Windows command line} as in \texttt{python bedslope.py}
 
 \item{within the Python IDLE environment}
@@ -404,5 +436,5 @@
 \item{within emacs}
 
-\item{from a Linux command line}
+\item{from a Linux command line} as in \texttt{python bedslope.py}
 \end{itemize}
 
@@ -415,4 +447,6 @@
 
     \item[AnuGA]
+    
+    \item[Conserved quantity]    
 
     \item[Default order]
@@ -426,9 +460,11 @@
     \item[Evolution]
 
-    \item[Forcing]
+    \item[Forcing term]
 
     \item[IDLE]
 
     \item[Manning friction coefficient]
+    
+    \item[Mesh]    
 
     \item[NetCDF]
@@ -452,4 +488,7 @@
     \item[Transmissive boundary]
 
+    \item[xmomentum]
+    
+    \item[ymomentum]    
 
 
