Changeset 2485

Timestamp:

Mar 3, 2006, 4:46:24 PM (18 years ago)

Author:

howard

Message:

Reorganised Chap 3 and provided intro material

File:

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

documentation/user_manual/anuga_user_manual.tex

@@ -303 +303 @@
 \end{verbatim}}
 
-This simply associates an elevation with each point $(x, y)$ of
-the plane.  It specifies that the bed slopes linearly in the $x$
-direction, with slope $-\frac{1}{2}$,  and is constant in the $y$
-direction.\\ %[screen shot?]
-\\
-Once the function $f$ is specified, the quantity
+This simply associates an elevation with each point \code{(x, y)} of
+the plane.  It specifies that the bed slopes linearly in the
+\code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
+the \code{y} direction.  %[screen shot?]
+
+Once the function \code{f} is specified, the quantity
 \code{elevation} is assigned through the simple statement:
 
@@ -709 +709 @@
 
 \begin{itemize}
-    \item Functions and Classes
+    \item Establishing the Mesh
+    \item Initialising the Domain
+    \item Specifying the Quantities
+    \item Initial Conditions
+    \item Boundary Conditions
+    \item Forcing Functions
     \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.]}}
+The listings are intended merely to give the reader an idea of what
+each feature is, where to find it and how it can be used---they do
+not give full specifications of the features. For these the reader
+may consult the code. The code for every function or class contains
+a documentation string, or `docstring', that specifies the precise
+syntax for its use. This appears immediately after the line
+introducing the code, between two sets of triple quotes.
+
+Each paragraph also describes the location of the module in which
+the code for the feature being described can be found. All modules
+are in the folder \code{inundation} or its subfolders, and the
+location of each module is described relative to this folder. Rather
+than using pathnames, whose syntax depends on the operating system,
+we use the format adopted for importing the function or class for
+use in Python code. For example, suppose we wish to specify that the
+function \code{create\_mesh\_from\_regions} is in a module called
+\code{mesh\_interface} in a subfolder of \code{inundation} called
+\code{pmesh}. In Linux or Unix syntax, the pathname of the file
+containing the function, relative to \code{inundation}, would be
+
+\begin{center}
+\code{pmesh/mesh\_interface.py}
+\end{center}
+
+while in Windows syntax it would be
+
+\begin{center}
+\code{pmesh}$\backslash$\code{mesh\_interface.py}
+\end{center}
+
+Rather than using either of these forms, in this chapter we specify
+the location simply as \code{pmesh.mesh_interface}, in keeping with
+the usage in the Python statement for importing the function,
+namely:
+\begin{center}
+\code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
+\end{center}
+
+
+\section{Mesh Generation}
 
 \begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
@@ -756 +767 @@
                              mesh_geo_reference=None,
                              minimum_triangle_angle=28.0}
+Module: \code{pmesh.mesh\_interface}
+
 Creates a triangular mesh based on a bounding polygon and a number
 of internal polygons. For each polygon the user specifies a
@@ -762 +775 @@
 \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}
-%
-%*********************************************************************************************
+%%%%%%
+\section{Initialising Domain}
 
 \begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
+Module: \code{pyvolution.pmesh2domain}
+
 Converts a generated mesh file to a domain object.
 
-\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}.
-
+\code{file\_name} is the name of the mesh file to be converted,
+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
-
-
-  \begin{funcdesc}{file_function}{filename,
+
+%%%%%%
+\section{Setting Quantities}
+
+\begin{funcdesc}{set\_quantity}{name, *args, **kwargs}
+Module: \code{pyvolution.domain} -- see also
+\code{pyvolution.quantity.set_values}
+
+numeric:\\
+Compatible list, Numeric array (see below) or constant. If callable
+it will treated as a function (see below) If instance of another
+Quantity it will be treated as such. If geo_spatial object it will
+be treated as such
+
+quantity:\\
+Another quantity (compatible quantity, e.g. obtained as a linear
+combination of quantities)
+
+function:\\
+  Any callable object that takes two one-dimensional arrays \code{x} and
+  \code{y}
+  each of length $N$ and returns an array also of length $N$.
+  The function will be evaluated at points determined by
+  location and indices in the underlying mesh.
+
+geospatial_data:\\
+  Arbitrary geospatial dataset in the form of the class
+  Geospatial_data. Mesh points are populated using least squares
+  fitting
+
+points:\\
+  $N \times 2$ array of data points for use with least squares fit
+  If points are present, an $N$ array of attribute
+  values corresponding to
+  each data point must be present.
+
+values:\\
+  If points is specified, values is an array of length N containing
+  attribute values for each point.
+
+data_georef:\\
+  If points is specified, geo_reference applies to each point.
+
+filename:\\
+  Name of a .pts file containing data points and attributes for
+  use with least squares.
+
+attribute_name:\\
+  If specified, any array matching that name
+  will be used. from file or geospatial_data.
+  Otherwise a default will be used.
+
+alpha:\\
+  Smoothing parameter to be used with least squares fits.
+  See module least_squares for further details about alpha.
+  Alpha will only be used with points, values or filename.
+  Otherwise it will be ignored.
+
+
+location: Where values are to be stored.
+  Permissible options are: vertices, edges, centroids
+  Default is 'vertices'
+
+  In case of location == 'centroids' the dimension values must
+  be a list of a Numerical array of length N,
+  N being the number of elements.
+  Otherwise it must be of dimension Nx3
+
+
+  The values will be stored in elements following their
+  internal ordering.
+
+  If location is not 'unique vertices' Indices is the
+  set of element ids that the operation applies to.
+  If location is 'unique vertices' Indices is the set
+  of vertex ids that the operation applies to.
+
+  If selected location is vertices, values for
+  centroid and edges will be assigned interpolated
+  values.  In any other case, only values for the
+  specified locations will be assigned and the others
+  will be left undefined.
+
+verbose: True means that output to stdout is generated
+
+use_cache: True means that caching of intermediate results is
+           attempted for least squares fit.
+
+Exactly one of the arguments
+  numeric, quantity, function, points, filename
+must be present.
+\end{funcdesc}
+
+%%%
+\anuga provides a number of predefined initial conditions to be used
+with \code{set_quantity}.
+
+\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}
+
+
+%%%
+\begin{funcdesc}{file_function}{filename,
                   domain = None,
                   quantities = None,
@@ -849 +908 @@
                   verbose = False,
                   use_cache = False}
-
-  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} 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)}
-%    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.
-
+Module: \code{pyvolution.util}
+
+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} 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}
+
+%%%
 \begin{classdesc}{Interpolation_function}{self,
                  time,
@@ -918 +931 @@
                  interpolation_points = None,
                  verbose = False}
+Module: \code{pyvolution.least\_squares}
+
 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
@@ -925 +940 @@
 \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 the default value \code{None} is used, returns average value.
+used to specify at which points interpolated quantities are to be
+computed whenever the object is called. If the default value
+\code{None} is used, it returns an average value.
 \end{classdesc}
 
-
-\begin{funcdesc}{set\_region}{???}
+%%%
+\begin{funcdesc}{set\_region}{functions}
 [Low priority. Will be merged into set\_quantity]
+
+Module:\code{pyvolution.domain}
 \end{funcdesc}
 
-\begin{funcdesc}{set\_quantity}{???}
-[Pretty mature]
-\end{funcdesc}
-
-\begin{funcdesc}{set\_boundary}{???}
-[Pretty mature]
-\end{funcdesc}
-
-
-
-\section{Diagnostics}
-
-  \begin{funcdesc}{write\_time}{???}
-
-  \end{funcdesc}
-
-
-  \begin{funcdesc}{write\_boundary\_statistics}{???}
-
-  \end{funcdesc}
-
-
-
+
+
+%%%%%%
 \section{Boundary Conditions}
 
@@ -963 +960 @@
 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]
-
-
-
-\section{Initial Conditions}
-
-\anuga provides a number of predefined initial conditions to be used with
-\code{set_quantity}.
-
-  \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}
+\begin{funcdesc}{set\_boundary}{boundary_map}
+Module: \code{pyvolution.domain}
+\end{funcdesc}
+
+
+%%%
+\subsection{Predefined boundary conditions}
+
+\begin{classdesc}{Reflective_boundary}{Boundary}
+Module: \code{pyvolution.shallow\_water}
+
+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}
+Module: \code{pyvolution.generic\_boundary\_conditions}
+
+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}
+Module: \code{pyvolution.generic\_boundary\_conditions}
+
+A Dirichlet boundary returns constant values for the conserved
+quantities.
+\end{classdesc}
+
+%%%
+\begin{classdesc}{Time_boundary}{domain = None, f = None}
+Module: \code{pyvolution.generic\_boundary\_conditions}
+
+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}
+Module: \code{pyvolution.generic\_boundary\_conditions}
+
+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]
+
+
+
+
 
 \section{Forcing Functions}
@@ -1040 +1037 @@
 %\end{itemize}
 
+
+
+\section{Diagnostics}
+
+  \begin{funcdesc}{write\_time}{???}
+
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{write\_boundary\_statistics}{???}
+
+  \end{funcdesc}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1057 +1066 @@
 \bigskip
 
-\begin{center} 
+\begin{center}
 
 \begin{tabular}{|ll|}  \hline
@@ -1097 +1106 @@
 
 
-\end{center} 
+\end{center}
 
 \bigskip