Changeset 3111

Timestamp:

Jun 8, 2006, 10:59:32 AM (19 years ago)

Author:

howard

Message:

Added a description of symbolic tags to the example in 3.1, and incorporated other changes from feedback received.

File:

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

documentation/user_manual/anuga_user_manual.tex ¶

@@ -143 +143 @@
 
 Readers are assumed to be familiar with the operating environment
-and have a general understanding of the problem background, as well
-as enough programming experience to adapt the code to different
-requirements, as described in this manual, and to understand the
-basic terminology of object-oriented programming.
+and have a general understanding of the subject matter, as well as
+enough programming experience to adapt the code to different
+requirements and to understand the basic terminology of
+object-oriented programming.
 
 \pagebreak
@@ -173 +173 @@
 
 To set up a particular scenario the user specifies the geometry
-(bathymetry and topography), the initial water level, boundary
-conditions such as tide, and any forcing terms that may drive the
-system such as wind stress or atmospheric pressure gradients.
-Gravity and frictional resistance from the different terrains in the model are
-represented by predefined forcing terms.
+(bathymetry and topography), the initial water level (stage)
+,
+boundary conditions such as tide, and any forcing terms that may
+drive the system such as wind stress or atmospheric pressure
+gradients. Gravity and frictional resistance from the different
+terrains in the model are represented by predefined forcing terms.
 
 A mesh generator, called pmesh, allows the user to set up the geometry
@@ -303 +304 @@
 \begin{itemize}
 
-   \item a list \code{points} of length $N$, where $N = (m + 1)(n + 1)$,
-comprising the coordinates \code{(x, y)} of each of the $N$ mesh
-points,
-
-   \item a list \code{vertices} of length $2mn$ (each entry specifies the three
-vertices of one of the triangles used in the triangulation) , and
-
-   \item a dictionary \code{boundary}, used to tag the triangle edges on
-the boundaries. Each key corresponds to a triangle edge on one of
-the four boundaries and its value is one of \code{`left'},
-\code{`right'}, \code{`top'} and \code{`bottom'}, indicating
-which boundary the edge in question belongs to.
+   \item a list \code{points} giving the coordinates of each mesh point,
+
+   \item a list \code{vertices} specifying the three vertices of each triangle, and
+
+   \item a dictionary \code{boundary} that stores the edges on
+   the boundary and associates each with one of the symbolic tags \code{`left'}, \code{`right'},
+   \code{`top'} or \code{`bottom'}.
 
 \end{itemize}
 
-An example of a general unstructured mesh and the
-associated data structures \code{points}, \code{vertices} and \code{boundary}
-is given in Section \ref{xxxx}.
-
-
-
+An example of a general unstructured mesh and the associated data
+structures \code{points}, \code{vertices} and \code{boundary} is
+given in Section \ref{sec:meshexample}.
 
 
@@ -338 +331 @@
 
 This creates an instance of the \class{Domain} class, which
-represents the domain of the simulation. Specific options for domain
-are set at this point, including setting the basename for the output
-file and the directory to be used for data:
+represents the domain of the simulation. Specific options are set at
+this point, including the basename for the output file and the
+directory to be used for data:
 
 {\small \begin{verbatim}
@@ -366 +359 @@
 \method{set\_quantity}, used to specify these quantities. It is a
 flexible method that allows the user to set quantities in a variety
-of ways---using constants, functions, numeric arrays or expressions
-involving other quantities, arbitrary data points with associated
+of ways---using constants, functions, numeric arrays, expressions
+involving other quantities, or arbitrary data points with associated
 values, all of which can be passed as arguments. All quantities can
 be initialised using \method{set\_quantity}. For a conserved
@@ -392 +385 @@
 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?]
+the \code{y} direction.
 
 Once the function \function{f} is specified, the quantity
@@ -412 +405 @@
 \end{verbatim}}
 
-This just specifies that the Manning friction coefficient is set
-to 0.1 at every mesh point.
+This specifies that the Manning friction coefficient is set to 0.1
+at every mesh point.
 
 \subsubsection{Stage}
@@ -436 +429 @@
 i.e. 0.4 units (m) below the zero level.
 
+%FIXME (Howard): Can we put this para somewhere else?
 Although it is not necessary for this example, it may be useful to
 digress here and mention a variant to this requirement, which allows
@@ -501 +495 @@
 
 Before describing how these boundary conditions are assigned, we
-recall that the variable \code{boundary} returned by
-\code{rectangular} not only stores the edges of the mesh that
-constitute the boundary but also assigns to each a symbolic `tag',
-which indicates whether that edge forms part of the `top' boundary,
-the `left' boundary, the `bottom' boundary or the `right' boundary.
-These tags provide the means to assign different boundary conditions
+recall that the definition of a mesh uses a variable \code{boundary}
+to store the edges of the mesh that lie on the boundary. (In the
+code we are discussing, \code{boundary} was one of the three
+variables returned by the function \code{rectangular}.)
+
+This variable \code{boundary} is a Python dictionary and it serves
+not only to hold the edges that make up the boundary but also to
+assign symbolic tags to these edges to distinguish different parts
+of the boundary. In this example, the tags  used are \code{`left',
+\code{`right'}, \code{`top'} and \code{`bottom'}, corresponding to
+the left, right, top and bottom of the rectangle bounding the mesh,
+and the function \code{rectangular} automatically assigns these tags
+to the boundary edges when it generates the mesh. The tags are used
+as keys for the dictionary, so that, for example,
+\code{boundary[`left']} is a list of the mesh edges that lie along
+the left part of the boundary.
+
+The tags provide the means to assign different boundary conditions
 to an edge depending on which part of the boundary it belongs to.
-(Later we shall describe examples in which the boundary is divided
-differently---we are not limited to the tags `left', `right', `top'
-and `bottom'.)
-
-With boundary objects assigned to variables as described above, we
-can apply one to each part of the boundary by means of a statement
-like
+(Later we shall describe an example that uses different boundary
+tags---we are not limited to using `left', `right', `top' and
+`bottom'.)
+
+Using the boundary objects described above, we assign a boundary
+condition to each part of the boundary by means of a statement like
 
 {\small \begin{verbatim}
@@ -756 +761 @@
 \end{verbatim}}
 
-is then used to create the mesh, taking the bounding polygon to be the polygon
-\code{diffpolygonall} specified in \file{project.py}. The
-argument \code{boundary\_tags} assigns a dictionary, whose keys are the
-names of the boundary tags used for the bounding polygon---\code{`bottom'},
-`right0', `right1', `right2', `top', `left1', `left2' and `left3'---
-and whose values identify the indices of the segments associated with each of these
-tags. (The value associated with each boundary tag is a one-element list.)
+is then used to create the mesh, taking the bounding polygon to be
+the polygon \code{diffpolygonall} specified in \file{project.py}.
+The argument \code{boundary\_tags} assigns a dictionary, whose keys
+are the names of the boundary tags used for the bounding
+polygon---\code{`bottom'}, \code{`right0'}, \code{`right1'},
+\code{`right2'}, \code{`top'}, \code{`left1'}, \code{`left2'} and
+\code{`left3'}--- and whose values identify the indices of the
+segments associated with each of these tags. (The value associated
+with each boundary tag is a one-element list.)
 
 
@@ -988 +995 @@
 mesh and use it to describe how mesh data is stored.
 
-Figure \ref{fig:simplemesh} represents a very simple mesh comprising
-just 11 points and 10 triangles.
+\label{sec:meshexample} Figure \ref{fig:simplemesh} represents a
+very simple mesh comprising just 11 points and 10 triangles.
 
 
@@ -1880 +1887 @@
         Use the same delimiter for the attribute names and the data.
 
-        An XYA file can optionally end with lines of this type:
+        An XYA file can optionally end with a description of the georeference:
 
             \code{\#geo reference}\\
@@ -2098 +2105 @@
  The output generated by \anuga may be viewed by
 means of the visualisation tool \code{swollen}, which takes the
-\code{sww} file output by \anuga and creates a visual representation
+\code{SWW} file output by \anuga and creates a visual representation
 of the data. Examples may be seen in Figures \ref{fig:runupstart}
-and \ref{fig:bedslope2}. To view an \code{sww} file with
+and \ref{fig:bedslope2}. To view an \code{SWW} file with
 \code{swollen} in the Windows environment, you can simply drag the
 icon representing the file over an icon on the desktop for the
-\code{swollen} executable file (or a shortcut to it). Alternatively,
-you can operate \code{swollen} from the command line, in both
-Windows and Linux environments.
-
-On successful operation, you will see an interactive moving-picture display. You can use keys and the mouse
-to slow down, speed up or stop the display, change the viewing position or carry out a number of other
-simple operations.
+\code{swollen} executable file (or a shortcut to it), or set up a
+file association to make files with the extension \code{.sww} open
+with \code{swollen}. Alternatively, you can operate \code{swollen}
+from the command line, in both Windows and Linux environments.
+
+On successful operation, you will see an interactive moving-picture
+display. You can use keys and the mouse to slow down, speed up or
+stop the display, change the viewing position or carry out a number
+of other simple operations. Help is also displayed when you press
+the \code{h} key.
 
 The main keys operating the interactive screen are:\\