Changeset 2434

Timestamp:

Feb 22, 2006, 2:12:54 PM (19 years ago)

Author:

howard

Message:

New material added for Ch 3 and Appendix. A number of other minor changes.

File:

• documentation/user_manual/anuga_user_manual.tex (modified) (19 diffs)

documentation/user_manual/anuga_user_manual.tex

@@ -82 +82 @@
 
 Most \anuga components are written in the object-oriented programming
-language Python and most users will interact with Anuga by writing
+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
@@ -125 +125 @@
   \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
+  \item A detailed description of the public interface
+  \item \anuga 's overall architecture, components and file formats
+  \item Assumptions
 \end{itemize}
 
@@ -134 +135 @@
 
 This section is designed to assist the reader to get started with
-\anuga by working through a simple example. What follows
+\anuga by working through simple examples. Two examples are discussed;
+the first is a simple but artificial example that is useful to illustrate
+many of the ideas, and the second is a real-life example.
+
+\section{First Example: Overview}
+
+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
@@ -180 +185 @@
 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).
@@ -195 +199 @@
 
 %FIXME: we are using the \code function here.
-%This should be used whereever possible
+%This should be used wherever possible
 For reference we include below the complete code listing for
 \code{bedslope.py}. Subsequent paragraphs provide a `commentary'
@@ -291 +295 @@
 
 
-\section{Initialising the domain}
+\section{Initialising the Domain}
 
 These variables are then used to set up a data structure
@@ -305 +309 @@
 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
+are set at this point. One of them is to set the basename for the output file:
 
 {\scriptsize \begin{verbatim}
@@ -412 +416 @@
     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}
@@ -444 +451 @@
 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.
-
-
+The value of \code{yieldstep} controls the time interval between successive model outputs. 
+Behind the scenes more time steps are generally taken.
 
 
@@ -474 +480 @@
 
 
-\section{Example with real data}
+\section{An Example with Real Data}
 
 The following discussion builds on the \code{bedslope.py} example and
@@ -505 +511 @@
 
 
-\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''
+\chapter{\anuga Public Interface}
+
+This chapter lists the functions and classes available at the public interface. 
+
+\section{Functions and Classes}
+
+\begin{itemize} 
+
+  \item \indexedcode{create_mesh_from_region}: Creates a triangular mesh based on a bounding polygon and 
+  a number of internal polygons. For each polygon the user specifies a resolution---that is, the maximal area 
+  of triangles in the mesh. The bounding polygon also has symbolic \code{tags} associated with it.   
+  
+  \textbf{Arguments:} 
+  
+  \begin{itemize}
+  
+  \item the bounding polygon, %do we need to spell out how a polygon is specified?
+  
+  \item a dictionary of boundary tags, for all segments of the bounding polygon, 
+  \emph{[not clear what the keys and values of this dictionary are]}
+  
+  \item the resolution for the bounding polygon,
+  
+  \item (optional) a filename,  \emph{[what is the file for?]}
+  
+  \item a list of 2-tuples \code{(polygon, resolution)}, specifying the interior polygons and their associated 
+  resolutions.
+  
+  \end{itemize}
+  
+  
+  
+  \item \indexedcode{pmesh_to_domain_instance}: Converts a generated mesh file to a domain object. 
+  
+  \textbf{Arguments:} 
+  
+  \begin{itemize}
+  
+  \item \code{file_name} is the name of the mesh file to convert, including the extension
+
+  \item \code{DomainClass} is the Class that will be returned.
+    It must be a subclass of \code{Domain}, with the same interface as domain.
+
+  \item \code{use_cache}: \code{True} means that caching is attempted for the computed domain.
+    
+  \end{itemize}
+  
+  
+  \begin{itemize}
+  \item Mesh file name
+  
+  \item Class name, specifying the domain class to be instantiated. 
+  \end{itemize}
+  
+  \item \indexedcode{file_function}: %in util.py "High priority" 
+  Reads the time history of spatial data from NetCDF file and returns a callable object.
+
+  \textbf{Input variables:}
+    
+    \code{filename} - Name of \code{sww} or \code{tms} file
+       
+       \begin{quote}
+       If the file has extension \code{sww} then it is assumed to be spatio-temporal
+       or temporal and the callable object will have the form \code{f(t,x,y)} or \code{f(t)}
+       depending on whether the file contains spatial data.
+
+       If the file has extension \code{tms} then it is assumed to be temporal only
+       and the callable object will have the form \code{f(t)}.
+
+       Either form will return interpolated values based on the input file
+       using the underlying \code{interpolation_function}.
+       \end{quote}
+
+    \code{domain} - Associated domain object   
+       If domain is specified, model time (\code{domain.starttime})
+       will be checked and possibly modified.
+    
+       \begin{quote}
+       All times are assumed to be in UTC.
+       
+       All spatial information is assumed to be in absolute UTM coordinates.
+       \end{quote}
+
+    \code{quantities} - the name of the quantity to be interpolated or a
+                 list of quantity names. The resulting function will return
+                 a tuple of values -- one for each quantity.  
+
+    \code{interpolation_points} - list of absolute UTM coordinates for points at
+    which values are sought
+    
+    \code{use_cache}: \code{True} means that caching of intermediate result of
+               \code{Interpolation_function} is attempted
+
+    
+  %  See Interpolation function for further documentation 
+  
+  \item \indexedcode{Interpolation_function} - creates a callable object \code{f(t, id)} or \code{f(t,x,y)}
+    which is interpolated from time series defined at vertices of
+    triangular mesh (such as those stored in \code{sww} files).
+
+    Let $m$ be the number of vertices, $n$ the number of triangles
+    and $p$ the number of time steps. 
+
+    \textbf{Mandatory input:}
+    
+        \begin{tabular}{ll}
+        \code{time}: & $p \times 1$ array of monotonously increasing times (Float)\\
+        
+        \code{quantities}: & Dictionary of arrays or one array (Float). The arrays must  \\
+        & have dimensions either $p \times m$ or $m \times 1$. The resulting function \\
+        & will be time dependent in the former case and constant with respect to time \\
+        & in the latter case.\\
+        \end{tabular}
+        
+        
+    \textbf{Optional input:}
+    
+        \begin{tabular}{ll}
+        \code{quantity_names}: & List of keys into the quantities dictionary\\
+        
+        \code{vertex_coordinates}: & $m \times 2$ array of coordinates (Float)\\
+        
+        \code{triangles}: & $n \times 3$ array of indices into \code{vertex_coordinates} (Int)\\
+        
+        \code{interpolation_points}: & $N \times 2$ array of coordinates to be interpolated to \\
+        
+        \code{verbose}: & Level of reporting\\
+        \end{tabular}
+    
+    The quantities returned by the callable object are specified by
+    the list quantities which must contain the names of the
+    quantities to be returned and also reflect the order, e.g. for
+    the shallow water wave equation, one would have
+    \code{quantities = ['stage', 'xmomentum', 'ymomentum']}.
+
+    The parameter \code{interpolation_points} decides at which points interpolated
+    quantities are to be computed whenever the object is called.
+    If \code{None}, returns average value.
+   
+
+  \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
+  
+
+\end{itemize} 
+
+\section{Diagnostics}
 \begin{itemize}
   \item \indexedcode{write_time}
@@ -536 +669 @@
 
 
-\subsection{Boundary conditions}
-
-ANUGA provides a large number of predefined boundary conditions to be used with
+\section{Boundary Conditions}
+
+\anuga provides a large number of predefined boundary conditions to be used with
 \code{set_boundary}
 
@@ -572 +705 @@
 
 
-\subsection{Initial conditions}
-
-ANUGA provides a number of predefined initial conditions to be used with
+\section{Initial Conditions}
+
+\anuga provides a number of predefined initial conditions to be used with
 \code{set_quantity}.
 
@@ -588 +721 @@
 
 
-\subsection{Initial conditions}
-
-ANUGA provides a number of predefined forcing functions to be used with .....
+\section{Forcing Functions}
+
+\anuga provides a number of predefined forcing functions to be used with .....
 
 \begin{itemize}
@@ -605 +738 @@
 
 
-\chapter{ANUGA system architecture}
+\chapter{\anuga System Architecture}
 
 From pyvolution/documentation
 
-
-
-\chapter{Basic ANUGA assumptions}
+\section{File Formats}
+
+\chapter{Basic \anuga Assumptions}
 
 (From pyvolution/documentation)
@@ -663 +796 @@
 %
 %  run_simulation.py: Use the above together with various parameters to
-%                     run inundation simluation.
+%                     run inundation simulation.
 
 
@@ -670 +803 @@
 \appendix
 
-\chapter{Supporting tools}
-
-
-\section{caching} Could do now.
-
-
-
-\section{swollen} Could do now.
-
+\chapter{Supporting Tools}
+
+
+\section{caching}
+
+  The \code{cache} function is used to provide supervised caching of function results. A Python 
+  function call of the form
+
+      {\scriptsize \begin{verbatim}
+      result = func(arg1,...,argn)
+      \end{verbatim}}
+
+  can be replaced by
+
+      {\scriptsize \begin{verbatim}
+      from caching import cache
+      result = cache(func,(arg1,...,argn))
+      \end{verbatim}}
+  
+  which returns the same output but reuses cached
+  results if the function has been computed previously in the same context.
+  \code{result} and the arguments can be simple types, tuples, list, dictionaries or
+  objects, but not unhashable types such as functions or open file objects. 
+  The function \code{func} may be a member function of an object or a module.
+
+  This type of caching is particularly useful for computationally intensive
+  functions with few frequently used combinations of input arguments. Note that
+  if the inputs or output are very large caching might not save time because
+  disc access may dominate the execution time.
+
+  If the function definition changes after a result has been cached it will be
+  detected by examining the functions \code{bytecode (co_code, co_consts,
+  func_defualts, co_argcount)} and it will be recomputed. 
+  
+  Options are set 
+  by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a 
+  Python dictionary \code{options} that stores settings such as the name of the directory used, the maximum 
+  number of cached files allowed, and so on.
+  
+  The \code{cache} function allows the user also to specify a list of dependent files. If any of these
+  have been changed, the function is recomputed and the results stored again.
+  
+  Other features include support for compression and a capability to \ldots
+
+  
+   \textbf{USAGE:}
+  
+    {\scriptsize \begin{verbatim}
+    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
+                   compression, evaluate, test, return_filename)}
+    \end{verbatim}}
+
+  \textbf{ARGUMENTS:}
+  
+  \begin{tabular}{ll}
+    \code{func} & Function object (Required)\\
+    \code{args} & Arguments to func (Default: ())\\
+    \code{kwargs} & Keyword arguments to func (Default: {})  \\  
+    \code{dependencies} & Filenames that func depends on (Default: \code{None})\\
+    \code{cachedir} & Directory for cache files (Default: \code{options['cachedir']})\\
+    \code{verbose} & Flag verbose output to stdout
+                       (Default: \code{options['verbose']})\\
+    \code{compression} & Flag zlib compression (Default: \code{options['compression']})\\
+    \code{evaluate} & Flag forced evaluation of func (Default: 0)\\
+    \code{test} & Flag test for cached results (Default: 0)\\
+    \code{clear} & Flag delete cached results (Default: 0)\\    
+    \code{return_filename} & Flag return of cache filename (Default: 0)\\    
+  \end{tabular}
+ 
+
+  \textbf{LIMITATIONS:}
+  
+  \begin{itemize}
+   \item Caching uses the apply function and will work with anything that can be
+      pickled, so any limitation in apply or pickle extends to caching. 
+      
+   \item A function to be cached should not depend on global variables
+      as wrong results may occur if globals are changed after a result has
+      been cached.
+   \end{itemize}
+
+ 
+
+
+\section{swollen}
+
+
+The main keys operating the interactive screen are:\\
+
+\begin{tabular}{|ll|}   \hline
+
+\code{w} & toggle wireframe\\
+
+space bar & start/stop\\
+
+up/down arrows & increase/decrease speed\\
+
+left/right arrows & direction in time \emph{(when running)}\\ & step through simulation \emph{(when stopped)}\\
+
+left mouse button & rotate\\
+
+middle mouse button & pan\\
+
+right mouse button & zoom\\  \hline
+
+\end{tabular}
+
+\vfill
+
+The following table describes how to operate swollen from the command line:
+
+Usage: \code{swollen [options] swwfile \ldots}\\  \nopagebreak
+Options:\\  \nopagebreak
+\begin{tabular}{ll}
+  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY_CENTER |}\\
+                                    & \code{HEAD_MOUNTED_DISPLAY}\\
+  \code{--rgba} & Request a RGBA colour buffer visual\\
+  \code{--stencil} & Request a stencil buffer visual\\
+  \code{--stereo} & Use default stereo mode which is \code{ANAGLYPHIC} if not \\
+                                    & overridden by environmental variable\\
+  \code{--stereo <mode>} & \code{ANAGLYPHIC | QUAD_BUFFER | HORIZONTAL_SPLIT |}\\
+                                    & \code{VERTICAL_SPLIT | LEFT_EYE | RIGHT_EYE |}\\
+                                     & \code{ON | OFF} \\
+  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
+  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
+  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
+  \code{-help} & Display this information\\
+  \code{-hmax <float>} & Height above which transparency is set to
+                                     \code{alphamax}\\
+  \code{-hmin <float>} & Height below which transparency is set to
+                                     zero\\
+  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
+                                     up, default is overhead)\\
+  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
+  \code{-movie <dirname>} & Save numbered images to named directory and
+                                     quit\\
+  \code{-nosky} & Omit background sky\\
+  \code{-scale <float>} & Vertical scale factor\\
+  \code{-texture <file>} & Image to use for bedslope topography\\
+  \code{-tps <rate>} & Timesteps per second\\
+  \code{-version} & Revision number and creation (not compile)
+                                     date\\
+\end{tabular}
 
 \section{utilities/polygons} Could do now.
@@ -717 +984 @@
 
 \begin{itemize}
-    \item \indexedbold{ANUGA} name of software (joint development between ANU and GA)
+    \item \indexedbold{\anuga} name of software (joint development between ANU and GA)
 
     \item \indexedbold{Conserved quantity}
@@ -771 +1038 @@
     \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.
+    \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 ....