Changeset 4017

Timestamp:

Nov 21, 2006, 1:19:25 PM (18 years ago)

Author:

ole

Message:

More public interface material, fixed undefined references and a missing end{classdesc}

File:

• anuga_core/documentation/user_manual/anuga_user_manual.tex (modified) (20 diffs)

anuga_core/documentation/user_manual/anuga_user_manual.tex

@@ -197 +197 @@
 
 \chapter{Restrictions and limitations on \anuga}
+\label{ch:limitations}
 
 Although a powerful and flexible tool for hydrodynamic modelling, \anuga has a
@@ -217 +218 @@
   %\item Mesh resolutions near coastlines with steep gradients need to be...   
   \item Frictional resistance is implemented using Manning's formula, but 
-  \anuga has not yet been validated in regard to bottom roughness
+  \anuga has not yet been fully validated in regard to bottom roughness
+  \item ANUGA contains no tsunami-genic functionality relating to
+  earthquakes.
 \end{itemize}
 
@@ -976 +979 @@
 supporting data is found in the ASCII grid, \code{cairns.asc}, which
 has been sourced from the publically available Australian Bathymetry
-and Topography Grid 2005, \cite{grid250:grid250}.
+and Topography Grid 2005, \cite{grid250}.
 
 \begin{figure}[hbt]
@@ -1335 +1338 @@
 triangles and associates a tag with each.
 
-%\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
+\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
 
 \begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
@@ -1538 +1541 @@
 \code{source} or by specifying the points, triangle and boundary of the
 mesh.
-
+\end{classdesc}
 
 \subsection{Key Methods of Domain}
@@ -1589 +1592 @@
 \end{methoddesc}
 
-\begin{methoddesc} {set\_minimum_storable_height}{time=0.0}
+\begin{methoddesc} {set\_minimum_storable_height}{}
     Module: \module{shallow\_water.shallow\_water\_domain}
 
@@ -1596 +1599 @@
     that seems to be caused by friction creep.
 \end{methoddesc}
+
+
+\begin{methoddesc} {set\_maximum_allowed_speed}{}
+    Module: \module{shallow\_water.shallow\_water\_domain}
+
+    Set the maximum particle speed that is allowed in water
+    shallower than minimum_allowed_height. This is useful for
+    controlling speeds in very thin layers of water and at the same time
+    allow some movement avoiding pooling of water.
+\end{methoddesc}
+
 
 \begin{methoddesc} {set\_time}{time=0.0}
@@ -1609 +1623 @@
     to \code{n} will cause an error.)
 \end{methoddesc}
+
+
+\begin{methoddesc} {set\_store\_vertices\_uniquely}{flag, reduction=None}
+Decide whether vertex values should be stored uniquely as
+computed in the model or whether they should be reduced to one
+value per vertex using self.reduction.
+\end{methoddesc}
+
+
+% Structural methods
+\begin{methoddesc}{get\_nodes}{absolute=False}
+    Return x,y coordinates of all nodes in mesh.
+
+    The nodes are ordered in an Nx2 array where N is the number of nodes.
+    This is the same format they were provided in the constructor
+    i.e. without any duplication.
+
+    Boolean keyword argument absolute determines whether coordinates
+    are to be made absolute by taking georeference into account
+    Default is False as many parts of ANUGA expects relative coordinates.
+\end{methoddesc}
+
+
+\begin{methoddesc}{get\_vertex_coordinates}{absolute=False}
+        
+    Return vertex coordinates for all triangles. 
+        
+    Return all vertex coordinates for all triangles as a 3*M x 2 array
+    where the jth vertex of the ith triangle is located in row 3*i+j and
+    M the number of triangles in the mesh.
+
+    Boolean keyword argument absolute determines whether coordinates
+    are to be made absolute by taking georeference into account
+    Default is False as many parts of ANUGA expects relative coordinates.
+\end{methoddesc}
+        
+        
+\begin{methoddesc}{get\_triangles}{indices=None}
+
+        Return Mx3 integer array where M is the number of triangles.
+        Each row corresponds to one triangle and the three entries are
+        indices into the mesh nodes which can be obtained using the method
+        get\_nodes()
+
+        Optional argument, indices is the set of triangle ids of interest.
+\end{methoddesc}
+    
+\begin{methoddesc}{get\_disconnected\_triangles}{}
+
+Get mesh based on nodes obtained from get_vertex_coordinates.
+
+        Return array Mx3 array of integers where each row corresponds to
+        a triangle. A triangle is a triplet of indices into
+        point coordinates obtained from get_vertex_coordinates and each
+        index appears only once.\\
+
+        This provides a mesh where no triangles share nodes
+        (hence the name disconnected triangles) and different
+        nodes may have the same coordinates.\\
+
+        This version of the mesh is useful for storing meshes with
+        discontinuities at each node and is e.g. used for storing
+        data in sww files.\\
+
+        The triangles created will have the format
+
+        {\small \begin{verbatim}
+        [[0,1,2],
+         [3,4,5],
+         [6,7,8],
+         ...
+         [3*M-3 3*M-2 3*M-1]]   
+         \end{verbatim}}       
+\end{methoddesc}
+
 
 
@@ -1655 +1744 @@
 \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.
+\item a geospatial dataset (See Section \ref{sec:geospatial}). 
+Optional argument attribute\_name applies here as with files.
 \end{itemize}
 
@@ -1681 +1771 @@
 %%%
 \anuga provides a number of predefined initial conditions to be used
-with \code{set\_quantity}.
+with \code{set\_quantity}. See for example callable object 
+\code{slump\_tsunami} below.
 
 \end{methoddesc}
@@ -1755 +1846 @@
 The model time stored within the file function can be accessed using
 the method \code{f.get\_time()}
+
+
+The underlying algorithm used is as follows:\\
+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
+ means of an array \code{time} of monotonically increasing times. The
+ quantities containing the values to be interpolated are specified in
+ an array---or dictionary of arrays (used in conjunction with the
+ optional argument \code{quantity\_names}) --- called
+ \code{quantities}. The optional arguments \code{vertex\_coordinates}
+ and \code{triangles} represent the spatial mesh associated with the
+ quantity arrays. If omitted the function created by
+ \code{Interpolation\_function} will be a function of \code{t} only.
+
+ Since, in practice, values need to be computed at specified points,
+ the syntax allows the user to specify, once and for all, a list
+ \code{interpolation\_points} of points at which values are required.
+ In this case, the function may be called using the form \code{f(t,
+ id)}, where \code{id} is an index for the list
+ \code{interpolation\_points}.
+
+
 \end{funcdesc}
 
 %%%
-\begin{classdesc}{Interpolation\_function}{self,
-    time,
-    quantities,
-    quantity_names = None,
-    vertex_coordinates = None,
-    triangles = None,
-    interpolation_points = None,
-    verbose = False}
-Module: \module{abstract\_2d\_finite\_volumes.least\_squares}
-
-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
-means of an array \code{time} of monotonically increasing times. The
-quantities containing the values to be interpolated are specified in
-an array---or dictionary of arrays (used in conjunction with the
-optional argument \code{quantity\_names}) --- called
-\code{quantities}. The optional arguments \code{vertex\_coordinates}
-and \code{triangles} represent the spatial mesh associated with the
-quantity arrays. If omitted the function created by
-\code{Interpolation\_function} will be a function of \code{t} only.
-
-Since, in practice, values need to be computed at specified points,
-the syntax allows the user to specify, once and for all, a list
-\code{interpolation\_points} of points at which values are required.
-In this case, the function may be called using the form \code{f(t,
-id)}, where \code{id} is an index for the list
-\code{interpolation\_points}.
-
-\end{classdesc}
+%% \begin{classdesc}{Interpolation\_function}{self,
+%%     time,
+%%     quantities,
+%%     quantity_names = None,
+%%     vertex_coordinates = None,
+%%     triangles = None,
+%%     interpolation_points = None,
+%%     verbose = False}
+%% Module: \module{abstract\_2d\_finite\_volumes.least\_squares}
+
+%% 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
+%% means of an array \code{time} of monotonically increasing times. The
+%% quantities containing the values to be interpolated are specified in
+%% an array---or dictionary of arrays (used in conjunction with the
+%% optional argument \code{quantity\_names}) --- called
+%% \code{quantities}. The optional arguments \code{vertex\_coordinates}
+%% and \code{triangles} represent the spatial mesh associated with the
+%% quantity arrays. If omitted the function created by
+%% \code{Interpolation\_function} will be a function of \code{t} only.
+
+%% Since, in practice, values need to be computed at specified points,
+%% the syntax allows the user to specify, once and for all, a list
+%% \code{interpolation\_points} of points at which values are required.
+%% In this case, the function may be called using the form \code{f(t,
+%% id)}, where \code{id} is an index for the list
+%% \code{interpolation\_points}.
+
+%% \end{classdesc}
 
 %%%
@@ -1905 +2025 @@
 
 
+\begin{classdesc}{Dirichlet\_Discharge\_boundary}{Boundary}
+Module: \module{shallow\_water}
+
+Sets stage (stage0)
+Sets momentum (wh0) in the inward normal direction.
+\end{classdesc}
+
+
 
 \subsection{User-defined boundary conditions}
 \label{sec:roll your own}
-[How to roll your own] TBA
-
-
-
-
-
-\section{Forcing Functions}
-
-\anuga provides a number of predefined forcing functions to be used with .....
-
-%\begin{itemize}
-
-
-%  \item \indexedcode{}
-%  [function, arguments]
-
-%  \item \indexedcode{}
-
-%\end{itemize}
+
+All boundary classes must inherit from the generic boundary class
+\code{Boundary} and have a method called \code{evaluate} which must 
+take as inputs \code{self, vol\_id, edge\_id} where self refers to the
+object itself and vol\_id and edge\_id are integers referring to
+particular edges. The method must return a list of three floating point 
+numbers representing values for \code{stage}, 
+\code{xmomentum} and \code{ymomentum}, respectively.
+
+The constructor of a particular boundary class may be used to specify 
+particular values or flags to be used by the \code{evaluate} method.
+Please refer to the source code for the existing boundary conditions 
+for examples of how to implement boundary conditions.
+
+
+
+%\section{Forcing Functions}
+%
+%\anuga provides a number of predefined forcing functions to be used with .....
+
 
 
@@ -2013 +2142 @@
   \end{funcdesc}
   
+
+  \begin{funcdesc}{get\_integral}{}
+  Module: \module{abstract\_2d\_finite\_volumes.quantity}
+
+  Return computed integral over entire domain for this quantity
+
+  \end{funcdesc}
+
+  
   
 
@@ -2023 +2161 @@
   the operation applies to. If omitted all elements are considered.
 
-  Note, we do not seek the maximum at vertices as each vertex can
+  We do not seek the maximum at vertices as each vertex can
   have multiple values - one for each triangle sharing it.            
   \end{funcdesc}
@@ -2034 +2172 @@
   Return location of maximum value of quantity (on centroids)
 
-        Optional argument indices is the set of element ids that the operation applies to.
-
-        Usage:
-            x, y = get_maximum_location()
-
-
-        Notes:
-            We do not seek the maximum at vertices as each vertex can
-            have multiple values - one for each triangle sharing it.
-
-            If there are multiple cells with same maximum value, the
-            first cell encountered in the triangle array is returned.       
-        """
-
-        i = self.get_maximum_index(indices)
-        x, y = self.domain.get_centroid_coordinates()[i]
-
-        return x, y
-
-
+  Optional argument indices is the set of element ids that 
+  the operation applies to.
+
+  We do not seek the maximum at vertices as each vertex can
+  have multiple values - one for each triangle sharing it.
+
+  If there are multiple cells with same maximum value, the
+  first cell encountered in the triangle array is returned.       
+  \end{funcdesc}
+
+
+  
+  \begin{funcdesc}{get\_wet\_elements}{indices=None}
+  Module: \module{shallow\_water.shallow\_water\_domain}  
+
+  Return indices for elements where h > minimum_allowed_height
+  Optional argument indices is the set of element ids that the operation applies to.
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{get\_maximum\_inundation\_elevation}{indices=None}
+  Module: \module{shallow\_water.shallow\_water\_domain}  
+
+  Return highest elevation where h > 0.\\
+  Optional argument indices is the set of element ids that the operation applies to.\\
+  
+  Example to find maximum runup elevation:\\  
+     z = domain.get_maximum_inundation_elevation()  
+  \end{funcdesc}
+
+
+  \begin{funcdesc}{get\_maximum\_inundation\_location}{indices=None}
+  Module: \module{shallow\_water.shallow\_water\_domain}  
+  
+  Return location (x,y) of highest elevation where h > 0.\\
+  Optional argument indices is the set of element ids that the operation applies to.\\
+
+  Example to find maximum runup location:\\
+     x, y = domain.get_maximum_inundation_location()  
+  \end{funcdesc}
+
+  
+  
+\section{Other}
+
+  \begin{funcdesc}{domain.create\_quantity\_from\_expression}{???}
+
+  Handy for creating derived quantities on-the-fly as for example
+  \begin{verbatim} 
+  Depth = domain.create_quantity_from_expression('stage-elevation')
+
+  exp = '(xmomentum*xmomentum + ymomentum*ymomentum)**0.5')        
+  Absolute_momentum = domain.create_quantity_from_expression(exp)
+  \end{verbatim} 
   
   
   
-  
-  
-  
-  
-
-  \begin{funcdesc}{get\_integral}{}
-  Module: \module{abstract\_2d\_finite\_volumes.quantity}
-
-  Return computed integral over entire domain for this quantity
-
-  \end{funcdesc}
-
-  %FIXME (Ole): Document these new funcs in shallow_water_domain and the also the ones they use in quantity.py
-  %  w = domain.get_maximum_inundation_elevation()
-  %  x, y = domain.get_maximum_inundation_location()  
-
-\section{Other}
-
-  \begin{funcdesc}{domain.create\_quantity\_from\_expression}{???}
-
-  Handy for creating derived quantities on-the-fly.
-  See \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
+  See also \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
   \end{funcdesc}
 
@@ -2700 +2851 @@
 
 \section{geospatial\_data}
+\label{sec:geospatial}
 
 This describes a class that represents arbitrary point data in UTM
@@ -2968 +3120 @@
 \label{mod:quantity}
 
-
+\begin{verbatim} 
 Class Quantity - Implements values at each triangular element
 
@@ -2984 +3136 @@
    Otherwise raise an exception
 
-
+\end{verbatim} 
    
    
@@ -3008 +3160 @@
 
 \subsubsection{What is \anuga?}
+It is a software package suitable for simulating 2D water flows in 
+complex geometries.
 
 \subsubsection{Why is it called \anuga?}
+The software was developed in collaboration between the 
+Australian National University (ANU) and Geoscience Australia (GA).
 
 \subsubsection{How do I obtain a copy of \anuga?}
-
-\subsubsection{What developments are expected for \anuga in the future?}
+See url{https://datamining.anu.edu.au/anuga} for all things ANUGA.
+
+%\subsubsection{What developments are expected for \anuga in the future?}
+%This 
 
 \subsubsection{Are there any published articles about \anuga that I can reference?}
+See url{https://datamining.anu.edu.au/anuga} for links.
+
 
 \section{Modelling Questions}
 
 \subsubsection{Which type of problems are \anuga good for?}
+General 2D waterflows in complex geometries such as 
+dam breaks, flows amoung structurs, coastal inundation etc.
 
 \subsubsection{Which type of problems are beyond the scope of \anuga?}
+See Chapter \ref{ch:limitations}.
 
 \subsubsection{Can I start the simulation at an arbitrary time?}
@@ -3061 +3224 @@
 if your DEM is on a 25m grid, then the cell resolution should be of the order of 315$m^2$ (this represents half the area of the square grid). Ideally,
 you need a fine mesh over regions where the DEM changes rapidly, and other areas of significant interest, such as the coast.
+If meshes are too coarse, discretisation errors in both stage and momentum may lead to unphysical results. All studies should include sensitivity and convergence studies based on different resolutions.