Index: /anuga_core/documentation/user_manual/anuga_user_manual.tex
===================================================================
--- /anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 5743)
+++ /anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 5744)
@@ -32,4 +32,5 @@
 
 \usepackage{graphicx}
+\usepackage[english]{babel}
 \usepackage{datetime}
 
@@ -85,4 +86,5 @@
 
 
+
 % This makes the contents more accessible from the front page of the HTML.
 \ifhtml
@@ -155,7 +157,7 @@
 \section{Audience}
 
-Readers are assumed to be familiar with the Python Programming language and 
+Readers are assumed to be familiar with the Python Programming language and
 its object oriented approach.
-Python tutorials include 
+Python tutorials include
 \url{http://docs.python.org/tut},
 \url{http://www.sthurlow.com/python}, and
@@ -235,5 +237,5 @@
   ANUGA is unsuitable for modelling flows in areas larger than one UTM zone
   (6 degrees wide).
-  \item Fluid is assumed to be inviscid - i.e.\ no kinematic viscosity included. 
+  \item Fluid is assumed to be inviscid - i.e.\ no kinematic viscosity included.
   \item The finite volume is a very robust and flexible numerical technique,
   but it is not the fastest method around. If the geometry is sufficiently
@@ -1715,5 +1717,5 @@
 
 
-\begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None, 
+\begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None,
 region_tag=None}
 Module: \module{pmesh.mesh},  Class: \class{Mesh}
@@ -2268,7 +2270,7 @@
 
 Optional argument \code{default\_boundary} can be used to specify another boundary object to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}.
-The \code{default\_boundary} could be a simple Dirichlet condition or 
-even another \code{File\_boundary} 
-typically using data pertaining to another time interval.  
+The \code{default\_boundary} could be a simple Dirichlet condition or
+even another \code{File\_boundary}
+typically using data pertaining to another time interval.
 \end{classdesc}
 
@@ -2276,19 +2278,19 @@
 Module: \module{shallow\_water.shallow\_water\_domain}
 
-This method works in the same way as \code{File\_boundary} except that it 
-allows for the value of stage to be offset by a constant specified in the 
+This method works in the same way as \code{File\_boundary} except that it
+allows for the value of stage to be offset by a constant specified in the
 keyword argument \code{mean\_stage}.
 
 This functionality allows for models to be run for a range of tides using
 the same boundary information (from .sts, .sww or .tms files). The tidal value
-for each run would then be specified in the keyword argument 
-\code{mean\_stage}. 
-If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary} 
-behave identically. 
+for each run would then be specified in the keyword argument
+\code{mean\_stage}.
+If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary}
+behave identically.
 
 
 Note that if the optional argument \code{default\_boundary} is specified
 it's stage value will be adjusted by \code{mean\_stage} just like the values
-obtained from the file. 
+obtained from the file.
 
 See \code{File\_boundary} for further details.
@@ -2342,7 +2344,7 @@
 
 \anuga provides a number of predefined forcing functions to be used with simulations.
-Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list 
-\code{domain.forcing\_terms} and have them affect the model. 
- 
+Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list
+\code{domain.forcing\_terms} and have them affect the model.
+
 Currently, predefined forcing terms are
 
@@ -2352,11 +2354,11 @@
   This is a general class to modify any quantity according to a given rate of change.
   Other specific forcing terms are based on this class but it can be used by itself as well (e.g.\ to modify momentum).
-  
+
   The General\_forcing class takes as input:
-  \begin{itemize} 
+  \begin{itemize}
     \item \code{domain}: a reference to the domain being evolved
     \item \code{quantity\_name}: The name of the quantity that will be affected by this forcing term
     \item \code{rate}: The rate at which the quantity should change. The parameter \code{rate} can be eithe a constant or a
-                function of time. Positive values indicate increases, 
+                function of time. Positive values indicate increases,
                 negative values indicate decreases.
                 The parametr \code{rate} can be \code{None} at initialisation but must be specified
@@ -2369,9 +2371,9 @@
   Moreover, if the specified polygon or circle does not lie fully within the mesh boundary an Exception will be thrown.
 
-  \bigskip  
+  \bigskip
   Example:
-  {\scriptsize \begin{verbatim} 
+  {\scriptsize \begin{verbatim}
     P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]] # Square polygon
-  
+
     xmom = General_forcing(domain, 'xmomentum', polygon=P)
     ymom = General_forcing(domain, 'ymomentum', polygon=P)
@@ -2379,12 +2381,12 @@
     xmom.rate = f
     ymom.rate = g
-  
+
     domain.forcing_terms.append(xmom)
     domain.forcing_terms.append(ymom)	
   \end{verbatim}}
   Here, \code{f}, \code{g} are assumed to be defined as functions of time providing a time dependent rate of change for xmomentum and ymomentum respectively.
-  P is assumed to be polygon, specified as a list of points. 
-  
-\end{funcdesc} 
+  P is assumed to be polygon, specified as a list of points.
+
+\end{funcdesc}
 
 
@@ -2394,24 +2396,24 @@
   This is a general class for inflow and abstraction of water according to a given rate of change.
   This class will always modify the \code{stage} quantity.
-  
+
   Inflow is based on the General_forcing class so the functionality is similar.
-  
+
   The Inflow class takes as input:
-  \begin{itemize} 
+  \begin{itemize}
     \item \code{domain}: a reference to the domain being evolved
     \item \code{rate}: The flow rate in $m^3/s$ at which the stage should change. The parameter \code{rate} can be eithe a constant or a
-                function of time. Positive values indicate inflow, 
+                function of time. Positive values indicate inflow,
                 negative values indicate outflow.
 		
                 Note: The specified flow will be divided by the area of
                 the inflow region and then applied to update the
-                stage quantity.     
+                stage quantity.
     \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.		
   \end{itemize}
 
-  \bigskip      
+  \bigskip
   Example:
-  {\scriptsize \begin{verbatim} 
+  {\scriptsize \begin{verbatim}
     hydrograph = Inflow(center=(320, 300), radius=10,
                         rate=file_function('QPMF_Rot_Sub13.tms'))
@@ -2420,5 +2422,5 @@
   \end{verbatim}}
   Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for a hydrograph.
-\end{funcdesc} 
+\end{funcdesc}
 
 
@@ -2428,11 +2430,11 @@
   This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon.
   This class will always modify the \code{stage} quantity.
-  
+
   Rainfall is based on the General_forcing class so the functionality is similar.
-  
+
   The Rainfall class takes as input:
-  \begin{itemize} 
+  \begin{itemize}
     \item \code{domain}: a reference to the domain being evolved
-    \item \code{rate}: Total rain rate over the specified domain.  
+    \item \code{rate}: Total rain rate over the specified domain.
 	          Note: Raingauge Data needs to reflect the time step.
 		  For example: if rain gauge is mm read every \code{dt} seconds, then the input
@@ -2441,20 +2443,20 @@
 	
                   This parameter can be either a constant or a
-                  function of time. Positive values indicate rain being added (or be used for general infiltration), 
+                  function of time. Positive values indicate rain being added (or be used for general infiltration),
                   negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction).
     \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.		
   \end{itemize}
-  
-  \bigskip    
+
+  \bigskip
   Example:
-  {\scriptsize \begin{verbatim} 
-  
-    catchmentrainfall = Rainfall(rain=file_function('Q100_2hr_Rain.tms'))  
+  {\scriptsize \begin{verbatim}
+
+    catchmentrainfall = Rainfall(rain=file_function('Q100_2hr_Rain.tms'))
     domain.forcing_terms.append(catchmentrainfall)
 
   \end{verbatim}}
   Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for the rainfall.
-\end{funcdesc} 
+\end{funcdesc}
 
 
@@ -2465,16 +2467,16 @@
   This is a general class for implementing flow through a culvert.
   This class modifies the quantities \code{stage, xmomentum, ymomentum} in areas at both ends of the culvert.
-  
+
   The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities. The flow drection is determined on-the-fly so
   openings are referenced simple as opening0 and opening1 with either being able to take the role as Inflow and Outflow.
-  
+
   The Culvert\_flow class takes as input:
-  \begin{itemize} 
+  \begin{itemize}
     \item \code{domain}: a reference to the domain being evolved
     \item \code{label}: Short text naming the culvert
     \item \code{description}: Text describing it
-    \item \code{end_point0}: Coordinates of one opening 
+    \item \code{end_point0}: Coordinates of one opening
     \item \code{end_point1}: Coordinates of other opening
-    \item \code{width}: 
+    \item \code{width}:
     \item \code{height}:
     \item \code{diameter}:
@@ -2486,36 +2488,36 @@
 
   The user can specify different culvert routines. Hower ANUGA currently provides only one, namely the \code{boyd\_generalised\_culvert\_model} as used in the example below.
-      
-  \bigskip        
+
+  \bigskip
   Example:
-  {\scriptsize \begin{verbatim} 
+  {\scriptsize \begin{verbatim}
     from anuga.culvert_flows.culvert_class import Culvert_flow
-    from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model  
+    from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model
 
     culvert1 = Culvert_flow(domain,
                            label='Culvert No. 1',
-                           description='This culvert is a test unit 1.2m Wide by 0.75m High',   
-                           end_point0=[9.0, 2.5], 
+                           description='This culvert is a test unit 1.2m Wide by 0.75m High',
+                           end_point0=[9.0, 2.5],
                            end_point1=[13.0, 2.5],
                            width=1.20,height=0.75,
-                           culvert_routine=boyd_generalised_culvert_model,        
+                           culvert_routine=boyd_generalised_culvert_model,
                            verbose=True)
 
     culvert2 = Culvert_flow(domain,
                            label='Culvert No. 2',
-                           description='This culvert is a circular test with d=1.2m',   
-                           end_point0=[9.0, 1.5], 
+                           description='This culvert is a circular test with d=1.2m',
+                           end_point0=[9.0, 1.5],
                            end_point1=[30.0, 3.5],
                            diameter=1.20,
                            invert_level0=7,
-                           culvert_routine=boyd_generalised_culvert_model,        
+                           culvert_routine=boyd_generalised_culvert_model,
                            verbose=True)
-                           
+
     domain.forcing_terms.append(culvert1)
     domain.forcing_terms.append(culvert2)
 
-    
+
   \end{verbatim}}
-\end{funcdesc} 
+\end{funcdesc}
 
 
@@ -2667,5 +2669,5 @@
   \end{funcdesc}
 
-  
+
 
   \begin{funcdesc}{set\_values}{location='vertices', indices = None}
@@ -2675,13 +2677,13 @@
   This method works the same way as \code{set\_quantity} except that it doesn't take
   a quantity name as the first argument. The reason to use \code{set\_values} is for
-  example to assign values to a new quantity that has been created but which is 
+  example to assign values to a new quantity that has been created but which is
   not part of the domain's predefined quantities.
 
-  The method \code{set\_values} is always called by \code{set\_quantity} 
-  behind the scenes. 
-  
+  The method \code{set\_values} is always called by \code{set\_quantity}
+  behind the scenes.
+
   \end{funcdesc}
-  
-  
+
+
 
   \begin{funcdesc}{get\_integral}{}
@@ -2831,9 +2833,9 @@
 
   Inputs:
-  \begin{itemize} 
+  \begin{itemize}
         \item filename: Name of sww file containing ANUGA model output.
         \item polyline: Representation of desired cross section - it may contain multiple
           sections allowing for complex shapes. Assume absolute UTM coordinates.
-  \end{itemize} 
+  \end{itemize}
 
   Output:
@@ -2841,22 +2843,22 @@
     \item time: All stored times in sww file
     \item Q: Hydrograph of total flow across given segments for all stored times.
-  \end{itemize} 
-  
+  \end{itemize}
+
   The normal flow is computed for each triangle intersected by the polyline and
   added up.  Multiple segments at different angles are specified the normal flows
   may partially cancel each other.
-  
+
   Example to find flow through cross section:
-  
-  \begin{verbatim}  
+
+  \begin{verbatim}
   cross_section = [[x, 0], [x, width]]
   time, Q = get_flow_through_cross_section(filename,
                                            cross_section,
                                            verbose=False)
-  \end{verbatim} 
+  \end{verbatim}
 
 
   See doc string for general function get_maximum_inundation_data for details.
-  
+
 \end{funcdesc}
 
@@ -3151,6 +3153,6 @@
 
   Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or
-  ERS) of a desired grid size \code{cellsize} in metres. The user can select how 
-  many the decimal places the output data can be written to using \code{number_of_decimal_places}, 
+  ERS) of a desired grid size \code{cellsize} in metres. The user can select how
+  many the decimal places the output data can be written to using \code{number_of_decimal_places},
   with the default being 3.
   The easting and northing values are used if the user wished to determine the output
@@ -3170,7 +3172,7 @@
   \end{funcdesc}
 
-  \begin{funcdesc}{urs2sts}{basename_in, basename_out=None, 
-            weights=None, verbose=False, 
-            origin=None,mean_stage=0.0, 
+  \begin{funcdesc}{urs2sts}{basename_in, basename_out=None,
+            weights=None, verbose=False,
+            origin=None,mean_stage=0.0,
             zscale=1.0, ordering_filename=None}
   Module: \module{shallow\_water.data\_manager}
@@ -3241,6 +3243,6 @@
 
 As demonstrated in our papers, \cite{ZR1999,nielsen2005} these
-equations and their implementation in \anuga provide a reliable 
-model of general flows associated with inundation such as dam breaks 
+equations and their implementation in \anuga provide a reliable
+model of general flows associated with inundation such as dam breaks
 and tsunamis.
 
@@ -3344,13 +3346,13 @@
 observed CFL condition:
 
-\begin{equation} 
+\begin{equation}
   \Delta t = \min_{k,i=[0,1,2]}  \min \left( \frac{r_k}{v_{k,i}}, \frac{r_{n_{k,i}}}{v_{k,i}} \right )
   \label{eq:CFL condition}
-\end{equation} 
-where $r_k$ is the radius of the $k$'th triangle and $v_{k,i}$ is the maximal velocity across 
-edge joining triangle $k$ and it's $i$'th neighbour, triangle $n_{k,i}$, as calculated by the 
-numerical flux function 
-using the central upwind scheme of \cite{KurNP2001}. The symbol $r_{n_{k,i}}$  denotes the radius 
-of the $i$'th neighbour of triangle $k$. The radii are calculated as radii of the inscribed circles 
+\end{equation}
+where $r_k$ is the radius of the $k$'th triangle and $v_{k,i}$ is the maximal velocity across
+edge joining triangle $k$ and it's $i$'th neighbour, triangle $n_{k,i}$, as calculated by the
+numerical flux function
+using the central upwind scheme of \cite{KurNP2001}. The symbol $r_{n_{k,i}}$  denotes the radius
+of the $i$'th neighbour of triangle $k$. The radii are calculated as radii of the inscribed circles
 of each triangle.
 
@@ -3784,5 +3786,5 @@
   is either a constant value or a function of coordinates \code{x}
   and \code{y}, specifying the return value for a point inside \code{P}. The
-  optional parameter \code{default} may be used to specify a value 
+  optional parameter \code{default} may be used to specify a value
   (or a function)
   for a point not lying inside any of the specified polygons. When a
@@ -3792,13 +3794,13 @@
   %FIXME (Howard): CAN x, y BE VECTORS?
   The optional parameter geo\_reference refers to the status of points
-  that are passed into the function. Typically they will be relative to 
+  that are passed into the function. Typically they will be relative to
   some origin. In ANUGA, a typical call will take the form:
   {\small \begin{verbatim}
-     set_quantity('elevation', 
+     set_quantity('elevation',
                   Polygon_function([(P1, v1), (P2, v2)],
                                    default=v3,
                                    geo_reference=domain.geo_reference))
   \end{verbatim}}
-  
+
 
   \end{classdesc}
@@ -3880,5 +3882,5 @@
   \begin{funcdesc}{plot\_polygons}{polygons, style, figname, verbose = False}
     Module: \code{utilities.polygon}
-  
+
     Plots each polygon contained in input polygon list, e.g.
    \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]}
@@ -3935,6 +3937,6 @@
 first one.
 
-Note that the Geospatial\_data object currently reads entire datasets 
-into memory i.e.\ no memomry blocking takes place.  
+Note that the Geospatial\_data object currently reads entire datasets
+into memory i.e.\ no memomry blocking takes place.
 For this we refer to the set\_quantity method which will read .pts and .csv files into \anuga using memory blocking allowing large files to be used.
 \end{classdesc}
@@ -4020,10 +4022,10 @@
 smaller the original and the second is the remainder. The two
 new object are disjoin set of each other.
-        
-Points of the two new geospatial_data object are selected RANDOMLY. 
-        
+
+Points of the two new geospatial_data object are selected RANDOMLY.
+
 Input - the (\code{factor}) which to split the object, if 0.1 then 10% of the
 together object will be returned
-        
+
 Output - two geospatial_data objects that are disjoint sets of the original
 \end{methoddesc}
@@ -4032,27 +4034,27 @@
 north_boundary=None, south_boundary=None, east_boundary=None, west_boundary=None, plot_name='all_alphas', split_factor=0.1, seed_num=None, cache=False, verbose=False}
 
-Removes a small random sample of points from 'data_file'. Creates 
-models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates 
+Removes a small random sample of points from 'data_file'. Creates
+models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates
 the predicted value to the previously removed point data. Returns the
 alpha value which has the smallest covariance.
 
 data_file: must not contain points outside the boundaries defined
-and it either a pts, txt or csv file. 
-    
+and it either a pts, txt or csv file.
+
 alpha_list: the alpha values to test in a single list
-    
-mesh_file: name of the created mesh file or if passed in will read it. 
+
+mesh_file: name of the created mesh file or if passed in will read it.
 NOTE, if there is a mesh file mesh_resolution, north_boundary, south... etc will be ignored.
-    
+
 mesh_resolution: the maximum area size for a triangle
-    
+
 north_boundary... west_boundary: the value of the boundary
-    
+
 plot_name: the name for the plot contain the results
-    
+
 seed_num: the seed to the random number generator
-    
+
 USAGE:
-convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName, 
+convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName,
                                              alpha_list=[0.0001, 0.01, 1],
                                              mesh_file=None,
@@ -4065,8 +4067,8 @@
                                              seed_num=100000,
                                              verbose=False)
-    
-OUTPUT: returns the minumum normalised covalance calculate AND the 
+
+OUTPUT: returns the minumum normalised covalance calculate AND the
 alpha that created it. PLUS writes a plot of the results
-           
+
 NOTE: code will not work if the data_file extent is greater than the
 boundary_polygon or any of the boundaries, eg north_boundary...west_boundary
@@ -4272,5 +4274,5 @@
 \section{\module{shallow\_water}}
 2D triangular domains for finite-volume
-computations of the shallow water wave equation. 
+computations of the shallow water wave equation.
 This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water
 Wave Equation
@@ -4376,8 +4378,8 @@
 data is often sparse, or non-existent.
 
-Note that onshore DEMS can be much finer as the underlying datasets from which they 
-are created often contain several datapoints per m$^2$. 
-It may be necessary to thin out the data so that it can be imported 
-without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?).  
+Note that onshore DEMS can be much finer as the underlying datasets from which they
+are created often contain several datapoints per m$^2$.
+It may be necessary to thin out the data so that it can be imported
+without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?).
 
 
@@ -4550,17 +4552,17 @@
 \subsubsection{How do I extract elevation and other quantities from a SWW file?}
 
-The function \code{sww2dem} can extract any quantity, or expression using 
-quantities, from a SWW file as used in 
+The function \code{sww2dem} can extract any quantity, or expression using
+quantities, from a SWW file as used in
 the Cairns example described earlier. This function is used in \code{ExportResults.py}
-in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation 
+in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation
 can be exported from the input sww file. Note that depth, absolute momentum and speed
 are expressions and stage and elevation are quantities. In addition to extracting a particular
 quantity or expression, the user can define a region to extract these values by
 defining the minimum and maximum of both the easting and northing coordinates. The function
-also calls for a grid resolution, or cell size, to extract these values at. It is 
-recommended to align this resolution with the mesh resolution in the desired region and to not 
+also calls for a grid resolution, or cell size, to extract these values at. It is
+recommended to align this resolution with the mesh resolution in the desired region and to not
 generate a fine grid where the model output cannot support that resolution.
 
- 
+
 
 \chapter{Glossary}
