Changeset 2358

Timestamp:

Feb 8, 2006, 4:43:35 PM (19 years ago)

Author:

ole

Message:

Ideas for Howard

File:

• documentation/AnuGA_user_manual.tex (modified) (20 diffs)

documentation/AnuGA_user_manual.tex

@@ -7 +7 @@
 
 
-%\newcommand{\code}[1]{{\small \tt #1}} %For use with one-line code snippets
+\newcommand{\indexedcode}[1]{\code{#1}\index{#1}}
+\newcommand{\indexedbold}[1]{\textbf{#1}\index{#1}}
         
 \documentclass{manual}
@@ -53 +54 @@
 \noindent
 \textbf{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. 
+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
@@ -71 +73 @@
 flows.
 
-Anuga also incorporates a mesh generator, called \texttt{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
@@ -131 +133 @@
 \textbf{AnuGA} by working through a simple example. What follows
 is a discussion of the structure and operation of the file
-\texttt{bedslope.py}, with just enough detail to allow the reader
+\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.
@@ -166 +168 @@
 \section{Outline of the Program}
 
-In outline, \texttt{bedslope.py} performs the following steps:
+In outline, \code{bedslope.py} performs the following steps:
 
 \begin{enumerate}
@@ -189 +191 @@
 \section{The Code}
 
-%FIXME: we are using the \code function here. This should be used whereever possible
+%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'
@@ -254 +257 @@
 \end{verbatim}}
 
-The function \texttt{rectangular} is imported from a module
-\texttt{mesh\_factory} defined elsewhere. (\textbf{AnuGA} also
+The function \code{rectangular} is imported from a module
+\code{mesh\_factory} defined elsewhere. (\textbf{AnuGA} also
 contains several other schemes that can be used for setting up
 meshes, but we shall not discuss these now.) The above assignment
@@ -269 +272 @@
 \begin{itemize}
 
-   \item a list \texttt{points} of length $N$, where $N = (m + 1)(n + 1)$,
+   \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 \texttt{vertices} of length $2mn$ (each entry specifies the three
+   \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 \texttt{boundary}, used to tag the triangle edges on
+   \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 \texttt{`left'},
-\texttt{`right'}, \texttt{`top'} and \texttt{`bottom'}, indicating
+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.
 
@@ -288 +291 @@
 
 These variables are then used to set up a data structure
-\texttt{domain}, through the assignment:
+\code{domain}, through the assignment:
 
 {\small \begin{verbatim}
@@ -294 +297 @@
 \end{verbatim}}
 
-This uses a Python class \texttt{Domain}, imported from
-\texttt{shallow\_water}, which is an extension of a more generic
-class of the same name in the module \texttt{domain}, and inherits
+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 
@@ -309 +312 @@
 
 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
+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 \texttt{set\_quantity}. For
-conserved quantities (\texttt{stage, xmomentum, ymomentum}) this is
+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 \texttt{set\_quantity}.
+in which we can invoke \code{set\_quantity}.
 
 
@@ -341 +344 @@
 \\
 Once the function $f$ is specified, the quantity
-\texttt{elevation} is assigned through the simple statement:
+\code{elevation} is assigned through the simple statement:
 
 {\small \begin{verbatim}
@@ -352 +355 @@
 
 The assignment of the friction quantity demonstrates another way
-we can use \texttt{set\_quantity} to set quantities---namely,
+we can use \code{set\_quantity} to set quantities---namely,
 assign them to a constant numerical value:
 
@@ -365 +368 @@
 
 Assigning depth illustrates a more complex way to use
-\texttt{set\_quantity}, introducing an expression involving other
+\code{set\_quantity}, introducing an expression involving other
 quantities:
 
@@ -373 +376 @@
 \end{verbatim}}
 
-Here the quantity \texttt{stage} is defined by taking the quantity
+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
@@ -402 +405 @@
 
 \begin{description}
-    \item[Reflective boundary] Returns same \texttt{stage} as
+    \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
@@ -437 +440 @@
 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 \texttt{yieldstep} and
-\texttt{finaltime}, which can be altered as required.
+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.
 
@@ -449 +452 @@
 %be used with swollen. Include screen shots.//
 
-The output is a NetCDF file with the extension \texttt{.sww}. It
+The output is a NetCDF file with the extension \code{.sww}. It
 contains stage and momentum information and can be used with the
-\texttt{swollen} visualisation package to generate a visual display.
+\code{swollen} visualisation package to generate a visual display.
 
 
@@ -471 +474 @@
 \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 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
@@ -478 +482 @@
 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 \texttt{`left'}, \texttt{`right'}, \texttt{`bottom'} and 
-\texttt{`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. 
+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{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}    
+  
+  \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} 
+
+
 
 \appendix
+
+\chapter{Supporting tools}
+
+
+\section{caching} Could do now.
+
+
+
+\section{swollen} Could do now.
+
+
+\section{utilities/polygons} Could do now.
+
+
+\section{coordinate_transforms}
+
+\section{geo_spatial_data}
+
+\section{pmesh GUI}
+
+\section{alpha_shape}
+
+
+
+
+
 \chapter{Glossary}
 
-\begin{description}
-
-    \item[AnuGA] name of software (joint development between ANU and GA)
+\begin{itemize}
+    \item \indexedbold{ANUGA} name of software (joint development between ANU and GA)
     
-    \item[Conserved quantity]    
-
-    \item[Default order] is this really needed?
-
-    \item[Domain]
-
-    \item[Dirichlet boundary]
-
-    \item[Elevation] - refers to bathymetry and topography
-
-    \item[bathymetry] offshore
-
-    \item[topography] onshore
-
-    \item[Evolution] integration of the shallow water wave equations over time
-
-    \item[Forcing term]
-
-    \item[IDLE] development environment shipped with Python
-
-    \item[Manning friction coefficient]
+    \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[Mesh]    triangulation of domain
-
-    \item[Grid] evenly spaced
-
-    \item[NetCDF]
-
-    \item[pmesh] does this really need to be here? it's a class/module?
-
-    \item[pyvolution] does this really need to be here? it's a class/module?
-
-    \item[Quantity] conserved (state, x and y momentum)
-
-    \item[Reflective boundary]
-
-    \item[Smoothing] is this really needed?
-
-    \item[Stage]
-
-    \item[Swollen] visualisation tool
-
-    \item[Time boundary] defined in the manual (flog from there)
-
-    \item[Transmissive boundary] defined in the manual (flog from there)
-
-    \item[xmomentum] conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
+    \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[ymomentum]  conserved quantity 
-
-    \item[resolution]   refers to the maximal area of each triangular cell in the mesh
-
-    \item[easting]   
-
-    \item[northing]   
-
-    \item[latitude]   
-
-    \item[longitude]   
-
-    \item[edge]   
-
-    \item[vertex]  
+    \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[finite volume]  
-
-    \item[flux]  
-
-    \item[Digital Elevation Model (DEM)]   
-
-
-\end{description}
+    \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