Changeset 3121

Timestamp:

Jun 8, 2006, 4:49:08 PM (19 years ago)

Author:

howard

Message:

Added entries for index and made numerous other minor changes

File:

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

documentation/user_manual/anuga_user_manual.tex

@@ -281 +281 @@
 %\verbatiminput{examples/bedslope.py}
 
-\subsection{Establishing the Mesh}
+\subsection{Establishing the Mesh}\index{mesh, establishing}
 
 The first task is to set up the triangular mesh to be used for the
@@ -454 +454 @@
 details.
 
-\subsection{Boundary Conditions}
+\subsection{Boundary Conditions}\index{boundary conditions}
 
 The boundary conditions are specified as follows:
@@ -524 +524 @@
 boundary. An edge with endpoints \code{points[i]} and
 \code{points[j]} is represented by the 2-tuple \code{(i, j)}. The
-keys for the dictionary are the 2-tuples \code{[i, j]} corresponding
+keys for the dictionary are the 2-tuples \code{(i, j)} corresponding
 to boundary edges in the mesh, and the values are the tags are used
-to label them. In the present example, the value \code{boundary[i,
-j]} assigned to \code{[i, j]} is one of the four tags \code{`left'},
-\code{`right'}, \code{`top'} or \code{`bottom'}, depending on
-whether the boundary edge represented by \code{(i, j)} occurs at the
-left, right, top or bottom of the rectangle bounding the mesh. The
-function \code{rectangular} automatically assigns these tags to the
-boundary edges when it generates the mesh.
+to label them. In the present example, the value \code{boundary[(i,
+j)]} assigned to \code{(i, j)]} is one of the four tags
+\code{`left'}, \code{`right'}, \code{`top'} or \code{`bottom'},
+depending on whether the boundary edge represented by \code{(i, j)}
+occurs at the left, right, top or bottom of the rectangle bounding
+the mesh. The function \code{rectangular} automatically assigns
+these tags to the boundary edges when it generates the mesh.
 \end{itemize}
 
@@ -539 +539 @@
 (In Section \ref{sec:realdataexample} we describe an example that
 uses different boundary tags---in general, the possible tags are not
-limited to `left', `right', `top' and `bottom', but can be selected
+limited to `left', `right', `top' and `bottom', but can be specified
 by the user.)
 
@@ -565 +565 @@
 
 
-\subsection{Evolution}
+\subsection{Evolution}\index{evolution}
 
 The final statement \nopagebreak[3]
@@ -690 +690 @@
 given above, discussing each major step of the code in turn.
 
-\subsection{Establishing the Mesh}
+\subsection{Establishing the Mesh}\index{mesh, establishing}
 
 One obvious way that the present example differs from
@@ -906 +906 @@
 \code{combinedname} in the file \file{project.py}.
 
-\subsection{Boundary Conditions}
+\subsection{Boundary Conditions}\index{boundary conditions}
 
 Setting boundaries follows a similar pattern to the one used for
@@ -1125 +1125 @@
 Additionally, the user specifies a list of boundary tags, one for
 each edge of the bounding polygon.
+
+\textbf{WARNING}. Note that the dictionary structure used for the
+parameter \code{boundary\_tags} is different from that used for the
+variable \code{boundary} that occurs in the specification of a mesh.
+In the case of \code{boundary}, the tags are the \emph{values} of
+the dictionary, whereas in the case of \code{boundary_tags}, the
+tags are the \emph{keys} and the \emph{value} corresponding to a
+particular tag is a list of numbers identifying boundary edges
+labelled with that tag. Because of this, it is theoretically
+possible to assign the same edge to more than one tag. However, an
+attempt to do this will cause an error.
 \end{funcdesc}
 
@@ -1159 +1170 @@
 \begin{methoddesc}  {add\_region\_from\_polygon}{self, polygon, tags=None,
                                 max_triangle_area=None, geo_reference=None}
-Module: \module{pmesh.mesh}  Class: \class{Mesh}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
 
 This method is used to add a region to a \class{Mesh} instance.  The
@@ -1171 +1182 @@
 \begin{methoddesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None,
     geo_reference=None}
-Module: \module{pmesh.mesh}  Class: \class{Mesh}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
 
 % Translate following into layman's language
@@ -1185 +1196 @@
                       minimum_triangle_angle=28.0,
                       verbose=False}
-Module: \module{pmesh.mesh}  Class: \class{Mesh}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
 
 % Translate following into layman's language
@@ -1195 +1206 @@
 
 \begin{methoddesc}  {export\_mesh_file}{self,ofile}
-Module: \module{pmesh.mesh}  Class: \class{Mesh}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
 
 % Translate following into layman's language
@@ -1206 +1217 @@
 
 \begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None}
-Module: \module{pmesh.mesh}  Class: \class{Mesh}
+Module: \module{pmesh.mesh},  Class: \class{Mesh}
 
 % Translate following into layman's language
@@ -1286 +1297 @@
     Module: \module{pyvolution.domain}
 
-    Specifies the directory used for data, assigning it to the pathname \code{name}. The default value, before
+    Specifies the directory used for SWW files, assigning it to the pathname \code{name}. The default value, before
     \code{set\_datadir} has been run, is the value \code{default\_datadir}
     specified in \code{config.py}.
@@ -1465 +1476 @@
 Module: \module{pyvolution.least\_squares}
 
-Given a time series, either as a sequence of numbers or defined at
-the vertices of a triangular mesh (such as those stored in SWW
-files), \code{Interpolation\_function} is used to create a callable
-object that interpolates a value for an arbitrary time \code{t}
-within the model limits and possibly a point \code{(x, y)} within a
-mesh region.
+Given a time series (i.e. a series of values associated with
+different times), whose values are either just numbers or a set of
+numbers defined at the vertices of a triangular mesh (such as those
+stored in SWW files), \code{Interpolation\_function} is used to
+create a callable object that interpolates a value for an arbitrary
+time \code{t} within the model limits and possibly a point \code{(x,
+y)} within a mesh region.
 
 The actual time series at which data is available is specified by
@@ -1501 +1513 @@
 
 %%%%%%
-\section{Boundary Conditions}
+\section{Boundary Conditions}\index{boundary conditions}
 
 \anuga provides a large number of predefined boundary conditions,
@@ -1626 +1638 @@
 
 
-\section{Evolution}
+\section{Evolution}\index{evolution}
 
   \begin{methoddesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
@@ -1667 +1679 @@
   Module: \module{pyvolution.domain}
 
-
+  Returns a string of the following type for each
+  timestep:
+
+  \code{Time = 0.9000, delta t in [0.00598964, 0.01177388], steps=12
+  (12)}
+
+  Here the numbers in \code{steps=12 (12)} indicate the number of steps taken and
+  the number of first-order steps, respectively.
   \end{funcdesc}
 
@@ -1674 +1693 @@
   Module: \module{pyvolution.domain}
 
+  Returns a string of the following type when \code{quantities = 'stage'} and \code{tags = ['top', 'bottom']}:
+
+  {\small \begin{verbatim}
+ Boundary values at time 0.5000:
+    top:
+        stage in [ -0.25821218,  -0.02499998]
+    bottom:
+        stage in [ -0.27098821,  -0.02499974]
+  \end{verbatim}}
 
   \end{funcdesc}
@@ -1708 +1736 @@
   See \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
   \end{funcdesc}
-
-
-  \begin{classdesc}{Geospatial\_data}{data_points = None,
-                 attributes = None,
-                 geo_reference = None,
-                 default_attribute_name = None,
-                 file_name = None}
-    Module: \module{geospatial\_data.geo\_spatial\_data}
-    Creates a georeferenced geospatial data object from either arrays or
-    a file (pts or xya).
-
-    Objects of this class can be used with \method{set\_quantity}.
-
-    FIXME (Ole): Describe methods such as get\_attributes() etc
-  \end{classdesc}
 
 
@@ -1799 +1812 @@
 \begin{tabular}{ll}
 ASC, PRJ & Digital elevation models (gridded)\\
-TSH & Triangular meshes (e.g. created from \code{pmesh})\\
 NC & Model outputs for use as boundary conditions (e.g. from MOST)
 \end{tabular}
@@ -1818 +1830 @@
 
 TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
-\code{pyvolution}
+\code{pyvolution}\\
+
+Polygonal mesh outline $\rightarrow$ & TSH or MSH
 \end{tabular}
 
@@ -1873 +1887 @@
 
 A mesh file is a file that has a specific format suited to
-specifying mesh data for \anuga. A mesh file can have one of two
-formats: it can be either a TSH file, which is an ASCII file, or an
-MSH file, which is a NetCDF file. A mesh file can be generated from
-the function \function{create\_mesh\_from\_regions} (see Section
-\ref{sec:meshgeneration}) and used to initialise a domain.
-
-A mesh file describes the outline of the mesh---the vertices and
+triangular meshes and their outlines. A mesh file can have one of
+two formats: it can be either a TSH file, which is an ASCII file, or
+an MSH file, which is a NetCDF file. A mesh file can be generated
+from the function \function{create\_mesh\_from\_regions} (see
+Section \ref{sec:meshgeneration}) and used to initialise a domain.
+
+A mesh file can define the outline of the mesh---the vertices and
 line segments that enclose the region in which the mesh is
 created---and the triangular mesh itself, which is specified by
@@ -1887 +1901 @@
 
 In addition, a mesh file may contain `holes' and/or `regions'. A
-hole or region is defined by specifying a point and a number of
-segments that enclose that point. A hole represents an area where no
-mesh is to be created, while a region is a labelled area used for
-defining properties of a mesh, such as friction values.
+hole represents an area where no mesh is to be created, while a
+region is a labelled area used for defining properties of a mesh,
+such as friction values.  A hole or region is specified by a point
+and bounded by a number of segments that enclose that point.
 
 A mesh file can also contain a georeference, which describes an
@@ -2482 +2496 @@
                           expand_pinch=False,
                           boundary_points_fraction=0.2}
-Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
+Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
 
 This function sets flags that govern the operation of the algorithm
@@ -2499 +2513 @@
 
 \begin{methoddesc}{get\_boundary}{}
-Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
+Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
 
 Returns a list of tuples representing the boundary of the alpha
@@ -2508 +2522 @@
 
 \begin{methoddesc}{write\_boundary}{file_name}
-Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
+Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
 
 Writes the list of 2-tuples returned by \code{get\_boundary} to the
@@ -2536 +2550 @@
 if \code{n} = \code{None}). If denominator evaluates to zero or if
 \code{y}
-is omitted, absolute error is returned.\\
+is omitted or if \code{relative = False}, absolute error is returned.\\
 
 \code{norm(x)} & 2-norm of \code{x}.\\
@@ -2543 +2557 @@
 \code{y} is \code{None} returns autocorrelation of \code{x}.\\
 
-\code{ensure\_numeric(A, typecode = None)} & Ensure that sequence is
-a Numeric array. If \code{A} is already a Numeric array it will be
-returned unaltered. Otherwise, an attempt is made to convert it to a
-Numeric array. (Needed because \code{array(A)} can
+\code{ensure\_numeric(A, typecode = None)} & Returns a Numeric array
+for any sequence \code{A}. If \code{A} is already a Numeric array it
+will be returned unaltered. Otherwise, an attempt is made to convert
+it to a Numeric array. (Needed because \code{array(A)} can
 cause memory overflow.)\\