Context Navigation

← Previous Changeset
Next Changeset →

Changeset 2559

Timestamp:

Mar 20, 2006, 8:37:32 AM (17 years ago)

Author:

howard

Message:

Updated material on swollen. Reworded text in a number of places to improve readability.

File:

: 1 edited

documentation/user_manual/anuga_user_manual.tex (modified) (34 diffs)

Legend:

: Unmodified
: Added
: Removed

documentation/user_manual/anuga_user_manual.tex

-                      r2542
+                      r2559
 The present example represents a simple scenario and does not
 include any forcing terms, nor is the data taken from a file as it
 would be in many typical cases.
+would be in many typical cases.
 The conserved quantities involved in the
 problem are water depth, $x$-momentum and $y$-momentum. Other quantities
 involved in the computation are the friction, stage (absolute height of water surface)
+involved in the computation are the friction, stage (absolute height of water surface)
 and elevation, the last two being related to
 the depth through the equation
 {\small \begin{verbatim}
+stage = elevation + depth
+\code{stage} = \code{elevation} + \code{depth}
 \end{verbatim}}
 …
 The stage (the height of the water surface) is related to the
+elevation and the depth at any time by the equation {\small
+\begin{verbatim}
+    stage = elevation + depth
+\end{verbatim}}
+elevation and the depth at any time by the equation \[\code{stage} =
+\code{elevation} + \code{depth}\]
 For this example, we simply assign a constant value to \code{stage},
 …
 \end{verbatim}}
 which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units
+which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units
 below the zero level.
 …
 involving other quantities. Suppose, instead of setting a constant value
 for the stage, we wished
 to specify a constant value for the \emph{depth}. For such a case we
+to specify a constant value for the \emph{depth}. For such a case we
 need to specify that \code{stage} is
 everywhere obtained by adding that value to the value already
 …
 \end{verbatim}}
 That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the
+That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the
 value of \code{elevation} already defined.
 The reader will probably appreciate that this capability to incorporate
+The reader will probably appreciate that this capability to incorporate
 expressions into statements using \code{set\_quantity} greatly expands
 its power.)
 …
     \item[Dirichlet boundary]Specifies a fixed value at the
 boundary and assigns initial values to the $x$-momentum and $y$-momentum.
+boundary and assigns initial values to the $x$-momentum and $y$-momentum.
     \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time.
 …
 The reader may wish to experiment by varying the choice of boundary types
 for one or more of the boundaries. In the case of \code{Bd} and \code{Bw},
 the three arguments in each case represent the
+for one or more of the boundaries. In the case of \code{Bd} and \code{Bw},
+the three arguments in each case represent the
 {\small \begin{verbatim}
 …
+\begin{figure}[hbt]
   \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}}
   \caption{Bedslope example viewed with Swollen}
   \label{fig:bedslopestart}
+\end{figure}
+\begin{figure}[hbt]
+  \centerline{
     \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps}
     \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps}
+   }
   \caption{Bedslope example viewed with Swollen}
   \label{fig:bedslope2}
+\end{figure}
+%\begin{figure}[hbt]
+%  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslope_start.eps}}
+%  \caption{Bedslope example viewed with Swollen}
+%  \label{fig:bedslopestart}
+%\end{figure}
+%\begin{figure}[hbt]
+%  \centerline{
+%    \includegraphics[width=75mm, height=75mm]{examples/bedslope_during.eps}
+%    \includegraphics[width=75mm, height=75mm]{examples/bedslope_end.eps}
+%   }
+%  \caption{Bedslope example viewed with Swollen}
+%  \label{fig:bedslope2}
+%\end{figure}
 …
 scenario, rather than the artificial illustrative one used in
 \code{bedslopephysical.py}. The domain of interest surrounds the Sydney region,
 and predominantly covers Sydney Harbour. A hypothetical tsunami wave is
+and predominantly covers Sydney Harbour. A hypothetical tsunami wave is
 generated by a submarine mass failure situated on the edge of the
 continental shelf.
 …
 area of a triangle used for triangulation---and mesh points are
 created inside the polygon through a random process. Figure
 \ref{fig:pentagon} shows a simple example of this, in which
+\ref{fig:pentagon} shows a simple example of this, in which
 the triangulation is carried out within a pentagon.
+\begin{figure}[hbt]
   \caption{Mesh points are created inside the polygon}
+  \label{fig:pentagon}
+\end{figure}
+%\begin{figure}[hbt]
+%  \caption{Mesh points are created inside the polygon}
+%  \label{fig:pentagon}
+%\end{figure}
 Boundary tags are not restricted to \code{`left'}, \code{`right'},
 …
 resolution. See Figure \ref{fig:interior meshes}.
+\begin{figure}[hbt]
   \caption{Interior meshes with individual resolution}
+  \label{fig:interior meshes}
+\end{figure}
+%\begin{figure}[hbt]
+%  \caption{Interior meshes with individual resolution}
+%  \label{fig:interior meshes}
+%\end{figure}
 In its general form, \code{pmesh} takes for its input a bounding
 …
 \code{meshname}.
 The statements
+The statements
 {\small \begin{verbatim}
 …
 are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
 \code{botanybay\_polygon\_2} from \code{project.py} and assign a
 common resolution of 5000 to each. The statement
+common resolution of 5000 to each. The statement
 {\small \begin{verbatim}
     create_mesh_from_regions(project.diffpolygonall,%
                          boundary_tags= {'bottom': [0],%
+                         boundary_tags= {'bottom': [0],%
                                          'right1': [1],%
                                          'right0': [2],%
 …
                                          'left3': [7]},%
                          maximum_triangle_area=100000,%
                          filename=meshname,%
+                         filename=meshname,%
                          interior_regions=interior_regions)
 \end{verbatim}}
 is then used to create the mesh, taking the bounding polygon to be the polygon
 \code{diffpolygonall} specified in \code{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'---
+\code{diffpolygonall} specified in \code{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.)
 …
 taken from \code{project.py}.
 {\small \begin{verbatim}
+{\small \begin{verbatim}
     domain.set_name(project.basename)%
     domain.set_datadir(project.outputdir)%
 …
 \code{slump\_tsunami}. This is similar to how we set elevation in
 \code{bedslopephysical.py} using a function---however, in this case the
 function is both more complex and more interesting.
 The function returns the water displacement for all \code{x}
 and \code{y} in the domain. The water displacement is a ?? function that depends
+function is both more complex and more interesting.
+The function returns the water displacement for all \code{x}
+and \code{y} in the domain. The water displacement is a ?? function that depends
 on the characteristics of the slump (length, thickness, slope, etc), its
 location (origin) and the depth at that location.
+location (origin) and the depth at that location.
 …
 The elevation is specified by reading data from a file:
 {\small \begin{verbatim}
     domain.set_quantity('elevation',
                     filename = project.combineddemname + '.pts',
                     use_cache = True,
                     verbose = True)
+{\small \begin{verbatim}%
+    domain.set_quantity('elevation',%
+                    filename = project.combineddemname + '.pts',%
+                    use_cache = True,%
+                    verbose = True)%
 \end{verbatim}}
 …
 \subsection{Boundary Conditions}
 Setting boundaries follows a similar pattern to the one used for
 \code{bedslopephysical.py}, except that in this case we need to associate a
+Setting boundaries follows a similar pattern to the one used for
+\code{bedslopephysical.py}, except that in this case we need to associate a
 boundary type with each of the
 boundary tag names introduced when we established the mesh. In place of the four
 boundary types introduced for \code{bedslopephysical.py}, we use the reflective
+boundary tag names introduced when we established the mesh. In place of the four
+boundary types introduced for \code{bedslopephysical.py}, we use the reflective
 boundary for each of the
 eight tagged segments:
 …
 {\small \begin{verbatim}
     import time t0 = time.time()
     for t in domain.evolve(yieldstep = 120, duration = 18000):
         print domain.timestepping_statistics()
         print domain.boundary_statistics(tags = 'bottom')
     print 'That took %.2f seconds' %(time.time()
 \end{verbatim}}
 …
 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
+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
 …
 % Translate following into layman's language
+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.
+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}
 …
 Module: \code{pyvolution.pmesh2domain}
+Converts a generated mesh file to a domain object.
+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.
 \code{file\_name} is the name of the mesh file to be converted,
 …
 \section{Setting Quantities}
 \begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None,
                    geospatial_data = None, filename = None, attribute_name = None,
+\begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None,
+                   geospatial_data = None, filename = None, attribute_name = None,
                    alpha = None, location = 'vertices', indices = None, verbose = False,
                    use_cache = False}
 …
 \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.
+This function is used to associate quantities with a domain. It is very flexible and can be
+used with many data types: a statement of the form \code{domain.set\_quantity{name, x}} can
+be used to define a quantity having the name \code{name}, where the other argument \code{x} can
+be any of the following:
+\begin{itemize}
+\item a number
+\item a list of numbers
+\item a Numeric array
+\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)
+\item the name of a file from which the data can be read
+\item a geospatial dataset
+\end{itemize}
 Exactly one of the arguments
 …
 \code{quantities} is either the name of a single quantity to be
 interpolated or a list of such quantity names. The resulting
+interpolated or a list of such quantity names. In the second case, the resulting
 function will return a tuple of values---one for each quantity.
 …
 \code{time} is an array of monotonically increasing times and
 \code{quantities} is an array, or dictionary of arrays, of values to
+\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, it returns an average value.
+\code{None} is used, the function returns an average value.
 \end{classdesc}
 …
 within each quantity.
 \end{funcdesc}
 \begin{funcdesc} {get_boundary_tags}{??}
 …
   \end{funcdesc}
+  \begin{funcdesc}{statistics}{???}
+    print domain.statistics() will provide basic structural statistics about e.g.\ mesh in the form of an area histogram
+  \end{funcdesc}
   \begin{funcdesc}{get_quantity}{???}
   Module: \code{pyvolution.domain}
+  Module: \code{pyvolution.domain}
   Allow access to individual quantities and their methods
   \end{funcdesc}
+  \end{funcdesc}
   \begin{funcdesc}{get_values}{???}
   Module: \code{pyvolution.quantity}
+  Module: \code{pyvolution.quantity}
   Extract values for quantity as an array
   \end{funcdesc}
+  \end{funcdesc}
   \begin{funcdesc}{get_integral}{???}
   Module: \code{pyvolution.quantity}
+  Module: \code{pyvolution.quantity}
   Return computed integral over entire domain for this quantity
   \end{funcdesc}
 \section{Other}
   \begin{funcdesc}{domain.create_quantity_from_expression}{???}
   Handy for creating derived quantities on-the-fly.
+  \end{funcdesc}
+\section{Other}
+  \begin{funcdesc}{domain.create_quantity_from_expression}{???}
+  Handy for creating derived quantities on-the-fly.
   See \code{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
   \end{funcdesc}
+  \end{funcdesc}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 …
   \begin{funcdesc}{sww2dem}{???}
   Module: \code{pyvolution.data\_manager}
   \end{funcdesc}
+  Module: \code{pyvolution.data\_manager}
+  \end{funcdesc}
   \begin{funcdesc}{dem2pts}{???}
   Module: \code{pyvolution.data_manager}
   \end{funcdesc}
+  Module: \code{pyvolution.data_manager}
+  \end{funcdesc}
 %\[
 …
 \chapter{Supporting Tools}
+This section describes a number of supporting tools, supplied with \anuga, that offer a
+variety of types of functionality and enhance the basic capabilities of \anuga.
 \section{caching}
 …
   This type of caching is particularly useful for computationally intensive
   functions with few frequently used combinations of input arguments. Note that
   if the inputs or output are very large caching might not save time because
+  if the inputs or output are very large caching may not save time because
   disc access may dominate the execution time.
   If the function definition changes after a result has been cached it will be
+  If the function definition changes after a result has been cached, this will be
   detected by examining the functions \code{bytecode (co_code, co_consts,
+  func_defualts, co_argcount)} and it will be recomputed.
+  Options are set
+  by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a
+  Python dictionary \code{options} that stores settings such as the name of the directory used, the maximum
+  func_defualts, co_argcount)} and the function will be recomputed.
+  Options are set by means of the function \code{set_option(key, value)},
+  where \code{key} is a key associated with a
+  Python dictionary \code{options}. This dictionary stores settings such as the name of
+  the directory used, the maximum
   number of cached files allowed, and so on.
 …
   have been changed, the function is recomputed and the results stored again.
   Other features include support for compression and a capability to \ldots
+  %Other features include support for compression and a capability to \ldots
 …
     {\small \begin{verbatim}
     result = cache(func, args, kwargs, dependencies, cachedir, verbose,
                    compression, evaluate, test, return_filename)}
+                   compression, evaluate, test, return_filename)
     \end{verbatim}}
+  \textbf{ARGUMENTS:}
+  \begin{tabular}{ll}
+    \code{func} & Function object (Required)\\
+    \code{args} & Arguments to func (Default: ())\\
+    \code{kwargs} & Keyword arguments to func (Default: {})  \\
+    \code{dependencies} & Filenames that func depends on (Default: \code{None})\\
+    \code{cachedir} & Directory for cache files (Default: \code{options['cachedir']})\\
+    \code{verbose} & Flag verbose output to stdout
+                       (Default: \code{options['verbose']})\\
+    \code{compression} & Flag zlib compression (Default: \code{options['compression']})\\
+    \code{evaluate} & Flag forced evaluation of func (Default: 0)\\
+    \code{test} & Flag test for cached results (Default: 0)\\
+    \code{clear} & Flag delete cached results (Default: 0)\\
+    \code{return_filename} & Flag return of cache filename (Default: 0)\\
+  \end{tabular}
+  \textbf{LIMITATIONS:}
+  \begin{itemize}
+   \item Caching uses the apply function and will work with anything that can be
+      pickled, so any limitation in apply or pickle extends to caching.
+   \item A function to be cached should not depend on global variables
+      as wrong results may occur if globals are changed after a result has
+      been cached.
+   \end{itemize}
 \section{swollen}
+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 of the data.
+Examples may be seen in Figures XX and YY. 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.
 The main keys operating the interactive screen are:\\
 …
 \section{geo_spatial_data}
 This describes a class that represents arbitrary point data in UTM
+This describes a class that represents arbitrary point data in UTM
 coordinates along with named attribute values.

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 2559

Legend:

documentation/user_manual/anuga_user_manual.tex

Download in other formats: