Changeset 2809

Timestamp:

May 5, 2006, 5:03:01 PM (19 years ago)

Author:

howard

Message:

New material on file formats and some other minor changes

File:

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

documentation/user_manual/anuga_user_manual.tex

@@ -279 +279 @@
 \code{`right'}, \code{`top'} and \code{`bottom'}, indicating
 which boundary the edge in question belongs to.
+
+# TO DO: Clarify the description of vertices to make it clear the
+entries are *indices* to points. Also good to have an example
 
 \end{itemize}
@@ -847 +850 @@
 
 \chapter{\anuga Public Interface}
+\label{ch:interface}
 
 This chapter gives an overview of the features of \anuga available
@@ -909 +913 @@
 and are omitted from the descriptions given below:
 
-\begin{tabular}{|l|l|}  \hline
-\textbf{Name } & \textbf{Description}\\
-\hline
-\code{usecache} & Specifies whether caching is to be used\\
-\code{verbose} & If \code{True}, provides detailed terminal output
-to the user\\   \hline
+%\begin{center}
+\begin{tabular}{ll}  %\hline
+%\textbf{Name } & \textbf{Description}\\
+%\hline
+\emph{usecache} & Specifies whether caching is to be used\\
+\emph{verbose} & If \code{True}, provides detailed terminal output
+to the user\\  % \hline
 \end{tabular}
-
+%\end{center}
 
 \section{Mesh Generation}
@@ -930 +935 @@
 Module: \module{pmesh.mesh\_interface}
 
+This function allows a user to initiate the automatic creation of a
+mesh inside a specified polygon. Among the parameters that can be
+set are the \emph{resolution} (maximal area for any triangle in the
+mesh) and the minimal angle allowable in any triangle. The user can
+specify a number of internal polygons within each of which a
+separate mesh is to be created, generally with a smaller resolution.
+Additionally, the user specifies a list of boundary tags, one for
+each edge of the bounding polygon.
+\end{funcdesc}
+
+
+\begin{funcdesc}  {Mesh}{userSegments=None,
+                 userVertices=None,
+                 holes=None,
+                 regions=None,
+                 geo_reference=None}
+Module: \module{pmesh.mesh}
 
 % Translate following into layman's language
-This function is used to create a triangular mesh suitable for use with
-\anuga, within a specified region. The region is specified as the interior of a polygon
-(the \emph{bounding polygon}). The user specifies the bounding polygon and the
-\emph{resolution}---that is, maximal area of any triangle in the mesh. There is
-also an option to specify a number of internal polygons within each of which a
-separate mesh is created, generally with a smaller resolution. Additionally,
-the user specifies a list of boundary tags, one for each edge of the bounding
-polygon.
-\end{funcdesc}
-
-
-\begin{funcdesc}  {Mesh}{}
-Module: \module{pmesh.mesh}
-
-% Translate following into layman's language
-This function is used to create a Mesh instance.  This can then be
-used to build the outline of the mesh and then generate the
+An instance of the class \class{Mesh} is used to store .  This can
+then be used to build the outline of the mesh and then generate the
 mesh.
 \end{funcdesc}
@@ -958 +965 @@
 
 % Translate following into layman's language
-This method is used to add a region to a Mesh instance.  The region is
-described by the polygon passed in.  Additionally,
-the user specifies a list of boundary tags, one for each edge of the bounding
-polygon.
+This method is used to add a region to a \class{Mesh} instance.  The
+region is described by the polygon passed in.  Additionally, the
+user specifies a list of boundary tags, one for each edge of the
+bounding polygon.
+
+
 \end{funcdesc}
 
@@ -969 +978 @@
 
 % Translate following into layman's language
-This method is used to add a region where the triangular mesh will not
-be generated to a Mesh instance.  The region is
-described by the polygon passed in.  Additionally,
-the user specifies a list of boundary tags, one for each edge of the bounding
-polygon.
+This method is used to add a `hole'---that is, a region where the
+triangular mesh will not be generated---to a \class{Mesh} instance.
+The region is described by the polygon passed in.  Additionally, the
+user specifies a list of boundary tags, one for each edge of the
+bounding polygon.
 \end{funcdesc}
 
@@ -1004 +1013 @@
 Module: \module{pyvolution.pmesh2domain}
 
-Once the initial mesh file has been created, this function is applied
-to convert it to a domain object---that is, to a member of
-the special Python class Domain (or a subclass of Domain), which provides access to properties and
-methods that allow quantities to be set and other operations to be carried out.
+Once the initial mesh file has been created, this function is
+applied to convert it to a domain object---that is, to a member of
+the special Python class \class{Domain} (or a subclass of
+\class{Domain}), which provides access to properties and methods
+that allow quantities to be set and other operations to be carried
+out.
 
 \code{file\_name} is the name of the mesh file to be converted,
@@ -1031 +1042 @@
 
     Returns the name assigned to the domain by \code{set_name}. If no name has been
-    assigned, returns `domain'.
+    assigned, returns \code{`domain'}.
 \end{funcdesc}
 
@@ -1047 +1058 @@
     in your code, before the first appearance of \code{set\_datadir}.
 
-    For example, if you wished to set the data directory to a subdirectory
-    \code{data} of the directory \code{project}, you might use
-    statements of the following type:
+    For example, to set the data directory to a subdirectory
+    \code{data} of the directory \code{project}, you could use
+    the statements:
 
     {\small \begin{verbatim}
@@ -1535 +1546 @@
     \item \code{volumes}, a list specifying the points at the vertices of each of the
     triangles
+    % Refer here to the example to be provided in describing the simple example
     \item \code{time}, a Numeric array containing times for model
     evaluation
@@ -1551 +1563 @@
 CDL representation of the output file \file{bedslope.sww} generated
 from running the simple example \file{bedslopephysical.py} of
-Chapter \ref{ch:getstarted}.
+Chapter \ref{ch:getstarted}:
 
 \verbatiminput{examples/bedslopeexcerpt.cdl}
 
-A TMS file is used to store time series...
+The SWW format is used not only for output but also serves as input
+for functions such as \function{file_boundary} and
+\function{file_function}, described in Chapter \ref{ch:interface}.
+
+A TMS file is used to store time series data that is independent of
+position.
 
 
@@ -1563 +1580 @@
 mesh data for \anuga. A meshfile 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.
+is a NetCDF file. A meshfile can be generated from the function
+\function{create_mesh_from_regions} (see ) and used to initialise a
+domain.
 
 A meshfile describes the outline of the mesh---the vertices and line
@@ -1586 +1605 @@
 attributes associated with a set of points.
 
-The format for a .xya file is:
-\begin{verbatim}
-            1st line:     [attribute names]
-            other lines:  x y [attributes]
-
-            for example:
-            elevation, friction
-            0.6, 0.7, 4.9, 0.3
-            1.9, 2.8, 5, 0.3
-            2.7, 2.4, 5.2, 0.3
-
-        The first two columns are always implicitly assumed to be x, y coordinates.
-        Use the same delimiter for the attribute names and the data
-
-        An xya file can optionally end with
-            #geo reference
-            56
-            466600.0
-            8644444.0
-
-        When the 1st # is the zone,
-        2nd # the xllcorner and
-        3rd # the yllcorner
-\end{verbatim}
+The format for an XYA file is:
+%\begin{verbatim}
+
+            first line:     \code{[attribute names]}\\
+            other lines:  \code{x y [attributes]}\\
+
+            for example:\\
+            \code{elevation, friction}\\
+            \code{0.6, 0.7, 4.9, 0.3}\\
+            \code{1.9, 2.8, 5, 0.3}\\
+            \code{2.7, 2.4, 5.2, 0.3}
+
+        The first two columns are always implicitly assumed to be $x$, $y$ coordinates.
+        Use the same delimiter for the attribute names and the data.
+
+        An XYA file can optionally end with lines having the format exemplified here:
+
+            \code{\#geo reference}\\
+            \code{56}\\
+            \code{466600.0}\\
+            \code{8644444.0}
+
+        where the first number specifies the zone (here 56)  and other numbers are the
+        coordinates of the lower left corner (466600.0, 8644444.0).
+
+A PTS file is a NetCDF representation of the data held in an XYA
+file. If the data is associated with a set of $N$ points, then the
+data is stored using an $N \times 2$ Numeric array of float
+variables for the points and an $N \times 1$ Numeric array for each
+attribute.
+
+%\end{verbatim}
 
 \subsection{ArcView Formats}
 
+Files of the three formats ASC, PRJ and ERS are all associated with
+data from ArcView.
+
+An ASC file is an ASCII representation of DEM output from ArcView.
+It has the following format...
+
+A PRJ file is an ArcView file used in conjunction with an ASC file
+to represent metadata for a DEM.
+
+
+\subsection{DEM Format}
+
+A DEM file is a NetCDF representation of regular DEM data.
+
 
 \subsection{Other Formats}
+
+
+
 
 \subsection{Basic File Conversions}