Changeset 2474

Timestamp:

Mar 3, 2006, 10:57:05 AM (18 years ago)

Author:

howard

Message:

Further updates to Chapter 3

File:

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

documentation/user_manual/anuga_user_manual.tex

@@ -703 +703 @@
 \chapter{\anuga Public Interface}
 
-This chapter describes the features of \anuga that are available to
-the user at the public interface.
+This chapter gives an overview of the features of \anuga available
+to the user at the public interface. These are grouped under the
+following headings:
+
+\begin{itemize}
+    \item Functions and Classes
+    \item Diagnostics
+    \item Boundary Conditions
+    \item Initial Conditions
+    \item Forcing Functions.
+\end{itemize}
+
+The listings do not give full specifications of the features, for
+which the reader may consult the docstrings provided in the code.
+They are intended merely to give the reader an idea of what each
+feature is and how it can be used.
 
 \section{Functions and Classes}
 
-\indexedcodeheader{create\_mesh\_from\_regions}\label{codehdr:createmeshfromregions}
-
-  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}
-
-*********************************************************************************************
-
-\emph{\textbf{[The following is how the description of
-\emph{\code{create\_mesh\_from\_regions}} would be presented using
-the Python documentation system's \emph{\code{funcdesc}} environment
-for describing a module-level function.]}}
+%\indexedcodeheader{create\_mesh\_from\_regions}\label{codehdr:createmeshfromregions}
+
+%  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}
+
+%*********************************************************************************************
+
+%\emph{\textbf{[The following is how the description of
+%\emph{\code{create\_mesh\_from\_regions}} would be presented using
+%the Python documentation system's \emph{\code{funcdesc}} environment
+%for describing a module-level function.]}}
 
 \begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
@@ -747 +761 @@
 \end{funcdesc}
 
-*********************************************************************************************
-
-\indexedcodeheader{pmesh\_to\_domain\_instance}  \nopagebreak
-
- 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. In practice, it can usually be set simply to
-    \code{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}
-
-*********************************************************************************************
+%*********************************************************************************************
+
+%\indexedcodeheader{pmesh\_to\_domain\_instance}  \nopagebreak
+
+% 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. In practice, it can usually be set simply to
+%    \code{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}
+%
+%*********************************************************************************************
 
 \begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
 Converts a generated mesh file to a domain object.
 
-\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. In practice, it can usually be set simply to
-    \code{Domain}.
-    \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain.
-  \end{itemize}
+\code{file\_name} is the name of the mesh file to convert, including
+the extension. \code{DomainClass} is the class to be returned, which
+must be a subclass of \code{Domain}, with the same interface as
+\code{Domain}---in practice, it can usually be set simply to
+\code{Domain}.
+
 \end{funcdesc}
-*********************************************************************************************
+%*********************************************************************************************
 
 
 %\indexedcodeheader{file\_function} %in util.py "High priority"
 
-  Reads the time history of spatial data from NetCDF file and returns a callable object.
-
-  \textbf{Arguments:}
-
-    \code{filename} -- Name of \code{sww} or \code{tms} file (see
-    Section \ref{sec:file formats} on page \pageref{sec:file formats}
-    for details about file formats).
-
-       \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
+%  Reads the time history of spatial data from NetCDF file and returns a callable object.
+
+%  \textbf{Arguments:}
+
+%    \code{filename} -- Name of \code{sww} or \code{tms} file (see
+%    Section \ref{sec:file formats} on page \pageref{sec:file formats}
+%    for details about file formats).
+
+%       \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
 
 
@@ -839 +851 @@
   Reads the time history of spatial data from NetCDF file and returns a callable object. Returns
   interpolated values based on the input file
-  using the underlying \code{interpolation\_function}. 
-
-    \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
+  using the underlying \code{interpolation\_function}.
+
+  \code{quantities} is either the name of a single quantity to be interpolated or a
+                 list of such quantity names. The resulting function will return
+                 a tuple of values---one for each quantity.
+
+  \code{interpolation\_points} is a list of absolute UTM coordinates for points at
+    which values are sought.
+
   \end{funcdesc}
 
 
   %  See Interpolation function for further documentation
-\indexedcodeheader{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 Arguments:}
-
-        \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 Arguments:}
-
-        \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
+%\indexedcodeheader{Interpolation\_function}
+% Creates a callable object \code{f(t, id)} or \code{f(t,x,y)}
+%    interpolated from a time series defined at the vertices of
+%    a 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 Arguments:}
+
+ %       \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 Arguments:}
+
+ %       \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 \code{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.
+
+\begin{classdesc}{Interpolation_function}{self,
+                 time,
+                 quantities,
+                 quantity_names = None,
+                 vertex_coordinates = None,
+                 triangles = None,
+                 interpolation_points = None,
+                 verbose = False}
+Creates a callable object \code{f(t, id)} or \code{f(t,x,y)}
+interpolated from a time series defined at the vertices of a
+triangular mesh (such as those stored in \code{sww} files).
+
+\code{time} is an array of monotonically increasing times and
+\code{quantities} is an array, or dictionary of arrays, of values to
+be interpolated. The parameter \code{interpolation_points} may be
+used to specify at which points interpolated
     quantities are to be computed whenever the object is called.
-    If \code{None}, returns average value.
-
-
-\indexedcodeheader{set\_region} ``Low priority. Will be merged into
-set\_quantity''
-
-\indexedcodeheader{set\_quantity} ``Pretty mature''
-
-\indexedcodeheader{set\_boundary} ``Pretty mature''
-
+    If the default value \code{None} is used, returns average value.
+\end{classdesc}
+
+
+\begin{funcdesc}{set\_region}{???}
+[Low priority. Will be merged into set\_quantity]
+\end{funcdesc}
+
+\begin{funcdesc}{set\_quantity}{???}
+[Pretty mature]
+\end{funcdesc}
+
+\begin{funcdesc}{set\_boundary}{???}
+[Pretty mature]
+\end{funcdesc}
 
 
 
 \section{Diagnostics}
-\begin{itemize}
-  \item \indexedcode{write\_time}
-  \item \indexedcode{write\_boundary\_statistics}
-
-
-\end{itemize}
+
+  \begin{funcdesc}{write\_time}{???}
+
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{write\_boundary\_statistics}{???}
+
+  \end{funcdesc}
+
 
 
@@ -921 +960 @@
 
 \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}
-  Based on File\_function
-
-  \item \indexedcode{}
-
-  \item \indexedcode{}
-
-  \item \indexedcode{User defined boundary conditions.}
-  How to roll your own
-\end{itemize}
+be used with \code{set\_boundary}.
+
+ \subsection{Predefined boundary conditions}
+
+  \begin{classdesc}{Reflective_boundary}{Boundary}
+  Reflective boundary returns same conserved quantities as those present in
+  the neighbouring volume but reflected.
+
+  This class is specific to the shallow water equation as it works with the
+  momentum quantities assumed to be the second and third conserved quantities.
+  \end{classdesc}
+
+
+  \begin{classdesc}{Transmissive_boundary}{domain = None}
+  A transmissive boundary returns the same conserved quantities as
+  those present in the neighbouring volume.
+
+  The underlying domain must be specified when the boundary is instantiated.
+  \end{classdesc}
+
+
+  \begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None}
+  A Dirichlet boundary returns constant values for the conserved
+  quantities.
+  \end{classdesc}
+
+
+  \begin{classdesc}{Time_boundary}{domain = None, f = None}
+  A time-dependent boundary returns values for the conserved quantities as a
+  function \code{f(t)} of time. The user must specify the domain to get access to the model
+  time.
+  \end{classdesc}
+
+
+  \begin{classdesc}{File_boundary}{Boundary}
+  The boundary values are obtained from a file and interpolated. The file is
+  assumed to contain a time series and possibly also spatial information.
+  The conserved quantities are given as a function of time.
+  \end{classdesc}
+
+
+  \subsection{User-defined boundary conditions}
+  [How to roll your own]
 
 
@@ -955 +1011 @@
 \code{set_quantity}.
 
-\begin{itemize}
-
-
-  \item \indexedcode{tsunami_slump}
-  function, arguments
-
-  \item \indexedcode{}
-
-\end{itemize}
-
+  \begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None, \
+                  x0=0.0, y0=0.0, alpha=0.0, \
+                  gravity=9.8, gamma=1.85, \
+                  massco=1, dragco=1, frictionco=0, psi=0, \
+                  dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, \
+                  domain=None,
+                  verbose=False}
+  This function returns a callable object representing an initial water
+  displacement generated by a submarine sediment slide.
+
+  The arguments include the downslope slide length, the water depth to the slide centre of mass,
+  and the bathymetric slope.
+  \end{funcdesc}
 
 \section{Forcing Functions}
@@ -970 +1029 @@
 \anuga provides a number of predefined forcing functions to be used with .....
 
-\begin{itemize}
-
-
-  \item \indexedcode{}
-  function, arguments
-
-  \item \indexedcode{}
-
-\end{itemize}
-
-
-
+%\begin{itemize}
+
+
+%  \item \indexedcode{}
+%  [function, arguments]
+
+%  \item \indexedcode{}
+
+%\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \chapter{\anuga System Architecture}
@@ -1307 +1367 @@
 \chapter{Glossary}
 
-\indexplacer{try it} \indexascode{try it out again}
-
 \begin{itemize}
     \item \indexedbold{\anuga} Name of software (joint development between ANU and GA)