Changeset 3091

Timestamp:

Jun 6, 2006, 10:01:40 AM (19 years ago)

Author:

sexton

Message:

updates

Location:

documentation/user_manual

Files:

• anuga_user_manual.tex (modified) (23 diffs)
• examples/runup.py (modified) (1 diff)

documentation/user_manual/anuga_user_manual.tex

@@ -734 +734 @@
 user. The user specifies the \emph{resolution}---that is, the maximal
 area of a triangle used for triangulation---and mesh points are
-created inside the polygon through a random process. Figure
+created inside the polygon using a mesh generation engine. On any
+given platform, the same mesh will be returned. Figure
 \ref{fig:pentagon} shows a simple example of this, in which
 the triangulation is carried out within a pentagon.
@@ -760 +761 @@
 the user to specify a number of \emph{interior polygons}, which are
 triangulated separately, each according to a separately specified
-resolution. See Figure \ref{fig:interior meshes}. It is also
+resolution, see Figure \ref{fig:interior meshes}. It is also
 possible to specify one or more `holes'---that is, areas bounded by
 polygons in which no triangulation is required.
@@ -905 +906 @@
 
 {\small \begin{verbatim}
-    domain.set_quantity('friction', 0.03)
+    domain.set_quantity('friction', 0.0)
 \end{verbatim}}
 
@@ -962 +963 @@
 
 With the basics established, the running of the `evolve' step is
-very similar to the corresponding step in \file{runup.py}:
+very similar to the corresponding step in \file{runup.py}. Here,
+the simulation is run for five hours (18000 seconds) with
+the output stored every two minutes (120 seconds).
 
 {\small \begin{verbatim}
@@ -982 +985 @@
 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:
+following headings and follows the outline of the examples described
+earlier:
 
 \begin{itemize}
@@ -996 +1000 @@
 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. For these the reader
+not give full specifications; 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
@@ -1080 +1084 @@
 
 This function allows a user to initiate the automatic creation of a
-mesh inside a specified polygon. Among the parameters that can be
+mesh inside a specified polygon (input \code{bounding_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.
+\code{interior_regions} is a paired list containing the interior
+polygon and its resolution.
 Additionally, the user specifies a list of boundary tags, one for
 each edge of the bounding polygon.
@@ -1105 +1112 @@
 % Translate following into layman's language
 This method is used to add a region to a \class{Mesh} instance.  The
-region is described by the polygon passed in.  Additionally, the
+region is described by the input \code{polygon}.  Additionally, the
 user specifies a list of boundary tags, one for each edge of the
 bounding polygon.
@@ -1117 +1124 @@
 
 % Translate following into layman's language
-This method is used to add a `hole'---that is, a region where the
+This method is used to add a `hole' wihtin a region ---that is, to define a
+interior 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
@@ -1289 +1297 @@
 \item a function (e.g.\ see the samples introduced in Chapter 2)
 \item an expression composed of other quantities and numbers, arrays, lists (for
-example, a linear combination of quantities)
+example, a linear combination of quantities, such as 
+\code{domain.set\_quantity('stage','elevation'+x))}
 \item the name of a file from which the data can be read. In this case, the optional argument attribute_name will select which attribute to use from the file. If left out, set_quantity will pick one. This is useful in cases where there is only one attribute.
 \item a geospatial dataset (See ?????). Optional argument attribute_name applies here as with files.
@@ -1327 +1336 @@
 with \code{set_quantity}.
 
-\begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None,
+\begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None,
                 x0=0.0, y0=0.0, alpha=0.0,
                 gravity=9.8, gamma=1.85,
@@ -1334 +1343 @@
                 domain=None,
                 verbose=False}
+Module: \module{pyvolution.smf}
+
 This function returns a callable object representing an initial water
 displacement generated by a submarine sediment failure. These failures can take the form of
-a submarine slump or slide.
+a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead.
 
 The arguments include as a minimum, the slump or slide length, the water depth to the centre of sediment
@@ -1352 +1363 @@
 Module: \module{pyvolution.util}
 
-Reads the time history of spatial data from NetCDF file and returns
-a callable object. Returns interpolated values based on the input
+Reads the time history of spatial data for
+specified interpolation points from a NetCDF file (\code{filename})
+and returns
+a callable object. \code{filename} could be a \code{sww} file.
+Returns interpolated values based on the input
 file using the underlying \code{interpolation_function}.
 
@@ -1363 +1377 @@
 for points at which values are sought.
 
-To get access to the model time stored within the file function use
+The model time stored within the file function can be accessed using
 the method \code{f.get_time()}
 \end{funcdesc}
@@ -1471 +1485 @@
 
 A Dirichlet boundary returns constant values for the conserved
-quantities.
+quantities. In the example of \code{Dirichlet\_boundary([0.2, 0.0, 0.0])}, 
+the \code{stage} value at the boundary is 0.2 and the \code{xmomentum} and 
+\code{ymomentum} at the boundary are set to 0.0. The list must contain
+a value for each conserved quantity.
 \end{classdesc}
 
@@ -1529 +1546 @@
   outputting statistics whenever a user-specified period
   \code{yieldstep} is completed (generally during this period the
-  model will evolve through several steps internally). The user
+  model will evolve through several steps internally
+  as the method forces the water speed to be calculated
+  on successive new cells). The user
   specifies the total time period over which the evolution is to take
   place, by specifying values (in seconds) for either \code{duration}
@@ -1806 +1825 @@
             \code{8644444.0}
 
-        Here the first number specifies the zone (in this case zone 56)  and other numbers specify the
+        Here the first number specifies the UTM zone (in this case zone 56)  and other numbers specify the
+        easting and northing
         coordinates (in this case (466600.0, 8644444.0)) of the lower left corner.
 
@@ -1823 +1843 @@
 
 An ASC file is an ASCII representation of DEM output from ArcView.
-It has the following format...
+It contains a header with the following format:
+
+\begin{tabular}{l l}
+\code{ncols}      &   \code{753}
+\code{nrows}      &   \code{766}
+\code{xllcorner}  &   \code{314036.58727982}
+\code{yllcorner}  &   \code{6224951.2960092}
+\code{cellsize}   &   \code{100}
+\code{NODATA_value} & \code{-9999}
+\end{tabular}
+
+The remainder of the file contains the elevation data for each grid point
+in the grid defined by the above information.
 
 A PRJ file is an ArcView file used in conjunction with an ASC file
@@ -1858 +1890 @@
   Module: \module{pyvolution.data\_manager}
 
-  Takes data from an SWW file and converts it to DEM format (ASC or
-  ERS)
+  Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or
+  ERS) of a desired grid size \code{cellsize} in metres. 
+  The easting and northing values are used if the user wished to clip the output 
+  file to a specified rectangular area. The \code{reduction} input refers to a function
+  to reduce the quantities over all time step of the SWW file, example, maximum.
   \end{funcdesc}
 
@@ -2017 +2052 @@
 \begin{tabular}{|ll|}   \hline
 
-\code{w} & toggle wireframe\\
+\code{w} & toggle wireframe \\
 
 space bar & start/stop\\
@@ -2171 +2206 @@
   Module: \code{utilities.polygon}
 
-  Plots each polygon contained in input polygon list, e.g. [poly1, poly2, poly3].
- Each polygon is closed for plotting purposes and subsequent plot saved to figname.
-  Returns list containing the minimum and maximum of $x$ and $y$,
-  i.e. [$x_{min}, x_{max}, y_{min}, y_{max}$].
+  Plots each polygon contained in input polygon list, e.g. 
+ \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]}
+ etc.  Each polygon is closed for plotting purposes and subsequent plot saved to \code{figname}.
+  Returns list containing the minimum and maximum of \code{x} and \code{y},
+  i.e. \code{[x_{min}, x_{max}, y_{min}, y_{max}]}.
   \end{funcdesc}
 
@@ -2451 +2487 @@
 
 \subsubsection{How do I use a DEM in my simulation?}
-You use \code{dem2pts} to convert your DEM to the required .pts format. This .pts file is then called When setting the elevation data to the mesh
-in \code{domain.set_quantity}
+You use \code{dem2pts} to convert your DEM to the required .pts format. This .pts file is then called 
+when setting the elevation data to the mesh in \code{domain.set_quantity}
 
 \subsubsection{What sort of DEM resolution should I use?}
-Try and work with the "best" you have available. Onshore DEMs are typically available in 25m, 100m and 250m grids. Note, offshore data is often sparse,
+Try and work with the \emph{best} you have available. Onshore DEMs are typically available in 25m, 100m and 250m grids. Note, offshore data is often sparse,
 or non-existant.
 
@@ -2465 +2501 @@
 \subsubsection{How often should I store the output?}
 This will depend on what you are trying to answer with your model and how much memory you have available on your machine. If you need
-to look in detail at the evolution, then you will need to balance against your storage requirements and the duration of the simulation.
-If the sww file exceeds 1Gb, another sww file will be created until the end of the simulation. As an example, to store all the conserved
-quantities on a mesh with approximately 300000 triangles on a 2 min interval for 5 hours will result in approximately 350Mb sww file.
+to look in detail at the evolution, then you will need to balance your storage requirements and the duration of the simulation.
+If the SWW file exceeds 1Gb, another SWW file will be created until the end of the simulation. As an example, to store all the conserved
+quantities on a mesh with approximately 300000 triangles on a 2 min interval for 5 hours will result in approximately 350Mb SWW file
+(as for the \file{run\_sydney\_smf.py} example).
 
 \subsection{Boundary Conditions}
 
 \subsubsection{How do I create a Dirichlet boundary condition?}
+
+A Dirichlet boundary condition sets a constant value for the
+conserved quantities at the boundaries. A list containing
+the constant values for stage, xmomentum and ymomentum is constructed
+and used in the function call, e.g. \code{Dirichlet_boundary([0.2,0.,0.])}
 
 \subsubsection{How do I know which boundary tags are available?}

documentation/user_manual/examples/runup.py

@@ -27 +27 @@
 domain.set_name('bedslope')                 # Output to bedslope.sww
 domain.set_datadir('.')                     # Use current directory for output
-domain.set_quantities_to_be_stored(['stage',
+domain.set_quantities_to_be_stored(['stage',# Store all conserved quantities
                                     'xmomentum',
                                     'ymomentum'])