Changeset 4017


Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed
  • anuga_core/documentation/user_manual/anuga_user_manual.tex

    r4016 r4017  
    197197
    198198\chapter{Restrictions and limitations on \anuga}
     199\label{ch:limitations}
    199200
    200201Although a powerful and flexible tool for hydrodynamic modelling, \anuga has a
     
    217218  %\item Mesh resolutions near coastlines with steep gradients need to be...   
    218219  \item Frictional resistance is implemented using Manning's formula, but
    219   \anuga has not yet been validated in regard to bottom roughness
     220  \anuga has not yet been fully validated in regard to bottom roughness
     221  \item ANUGA contains no tsunami-genic functionality relating to
     222  earthquakes.
    220223\end{itemize}
    221224
     
    976979supporting data is found in the ASCII grid, \code{cairns.asc}, which
    977980has been sourced from the publically available Australian Bathymetry
    978 and Topography Grid 2005, \cite{grid250:grid250}.
     981and Topography Grid 2005, \cite{grid250}.
    979982
    980983\begin{figure}[hbt]
     
    13351338triangles and associates a tag with each.
    13361339
    1337 %\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
     1340\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
    13381341
    13391342\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
     
    15381541\code{source} or by specifying the points, triangle and boundary of the
    15391542mesh.
    1540 
     1543\end{classdesc}
    15411544
    15421545\subsection{Key Methods of Domain}
     
    15891592\end{methoddesc}
    15901593
    1591 \begin{methoddesc} {set\_minimum_storable_height}{time=0.0}
     1594\begin{methoddesc} {set\_minimum_storable_height}{}
    15921595    Module: \module{shallow\_water.shallow\_water\_domain}
    15931596
     
    15961599    that seems to be caused by friction creep.
    15971600\end{methoddesc}
     1601
     1602
     1603\begin{methoddesc} {set\_maximum_allowed_speed}{}
     1604    Module: \module{shallow\_water.shallow\_water\_domain}
     1605
     1606    Set the maximum particle speed that is allowed in water
     1607    shallower than minimum_allowed_height. This is useful for
     1608    controlling speeds in very thin layers of water and at the same time
     1609    allow some movement avoiding pooling of water.
     1610\end{methoddesc}
     1611
    15981612
    15991613\begin{methoddesc} {set\_time}{time=0.0}
     
    16091623    to \code{n} will cause an error.)
    16101624\end{methoddesc}
     1625
     1626
     1627\begin{methoddesc} {set\_store\_vertices\_uniquely}{flag, reduction=None}
     1628Decide whether vertex values should be stored uniquely as
     1629computed in the model or whether they should be reduced to one
     1630value per vertex using self.reduction.
     1631\end{methoddesc}
     1632
     1633
     1634% Structural methods
     1635\begin{methoddesc}{get\_nodes}{absolute=False}
     1636    Return x,y coordinates of all nodes in mesh.
     1637
     1638    The nodes are ordered in an Nx2 array where N is the number of nodes.
     1639    This is the same format they were provided in the constructor
     1640    i.e. without any duplication.
     1641
     1642    Boolean keyword argument absolute determines whether coordinates
     1643    are to be made absolute by taking georeference into account
     1644    Default is False as many parts of ANUGA expects relative coordinates.
     1645\end{methoddesc}
     1646
     1647
     1648\begin{methoddesc}{get\_vertex_coordinates}{absolute=False}
     1649       
     1650    Return vertex coordinates for all triangles.
     1651       
     1652    Return all vertex coordinates for all triangles as a 3*M x 2 array
     1653    where the jth vertex of the ith triangle is located in row 3*i+j and
     1654    M the number of triangles in the mesh.
     1655
     1656    Boolean keyword argument absolute determines whether coordinates
     1657    are to be made absolute by taking georeference into account
     1658    Default is False as many parts of ANUGA expects relative coordinates.
     1659\end{methoddesc}
     1660       
     1661       
     1662\begin{methoddesc}{get\_triangles}{indices=None}
     1663
     1664        Return Mx3 integer array where M is the number of triangles.
     1665        Each row corresponds to one triangle and the three entries are
     1666        indices into the mesh nodes which can be obtained using the method
     1667        get\_nodes()
     1668
     1669        Optional argument, indices is the set of triangle ids of interest.
     1670\end{methoddesc}
     1671   
     1672\begin{methoddesc}{get\_disconnected\_triangles}{}
     1673
     1674Get mesh based on nodes obtained from get_vertex_coordinates.
     1675
     1676        Return array Mx3 array of integers where each row corresponds to
     1677        a triangle. A triangle is a triplet of indices into
     1678        point coordinates obtained from get_vertex_coordinates and each
     1679        index appears only once.\\
     1680
     1681        This provides a mesh where no triangles share nodes
     1682        (hence the name disconnected triangles) and different
     1683        nodes may have the same coordinates.\\
     1684
     1685        This version of the mesh is useful for storing meshes with
     1686        discontinuities at each node and is e.g. used for storing
     1687        data in sww files.\\
     1688
     1689        The triangles created will have the format
     1690
     1691        {\small \begin{verbatim}
     1692        [[0,1,2],
     1693         [3,4,5],
     1694         [6,7,8],
     1695         ...
     1696         [3*M-3 3*M-2 3*M-1]]   
     1697         \end{verbatim}}       
     1698\end{methoddesc}
     1699
    16111700
    16121701
     
    16551744\code{domain.set\_quantity('stage','elevation'+x))}
    16561745\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.
    1657 \item a geospatial dataset (See ?????). Optional argument attribute\_name applies here as with files.
     1746\item a geospatial dataset (See Section \ref{sec:geospatial}).
     1747Optional argument attribute\_name applies here as with files.
    16581748\end{itemize}
    16591749
     
    16811771%%%
    16821772\anuga provides a number of predefined initial conditions to be used
    1683 with \code{set\_quantity}.
     1773with \code{set\_quantity}. See for example callable object
     1774\code{slump\_tsunami} below.
    16841775
    16851776\end{methoddesc}
     
    17551846The model time stored within the file function can be accessed using
    17561847the method \code{f.get\_time()}
     1848
     1849
     1850The underlying algorithm used is as follows:\\
     1851Given a time series (i.e.\ a series of values associated with
     1852different times), whose values are either just numbers or a set of
     1853 numbers defined at the vertices of a triangular mesh (such as those
     1854 stored in SWW files), \code{Interpolation\_function} is used to
     1855 create a callable object that interpolates a value for an arbitrary
     1856 time \code{t} within the model limits and possibly a point \code{(x,
     1857 y)} within a mesh region.
     1858
     1859 The actual time series at which data is available is specified by
     1860 means of an array \code{time} of monotonically increasing times. The
     1861 quantities containing the values to be interpolated are specified in
     1862 an array---or dictionary of arrays (used in conjunction with the
     1863 optional argument \code{quantity\_names}) --- called
     1864 \code{quantities}. The optional arguments \code{vertex\_coordinates}
     1865 and \code{triangles} represent the spatial mesh associated with the
     1866 quantity arrays. If omitted the function created by
     1867 \code{Interpolation\_function} will be a function of \code{t} only.
     1868
     1869 Since, in practice, values need to be computed at specified points,
     1870 the syntax allows the user to specify, once and for all, a list
     1871 \code{interpolation\_points} of points at which values are required.
     1872 In this case, the function may be called using the form \code{f(t,
     1873 id)}, where \code{id} is an index for the list
     1874 \code{interpolation\_points}.
     1875
     1876
    17571877\end{funcdesc}
    17581878
    17591879%%%
    1760 \begin{classdesc}{Interpolation\_function}{self,
    1761     time,
    1762     quantities,
    1763     quantity_names = None,
    1764     vertex_coordinates = None,
    1765     triangles = None,
    1766     interpolation_points = None,
    1767     verbose = False}
    1768 Module: \module{abstract\_2d\_finite\_volumes.least\_squares}
    1769 
    1770 Given a time series (i.e. a series of values associated with
    1771 different times), whose values are either just numbers or a set of
    1772 numbers defined at the vertices of a triangular mesh (such as those
    1773 stored in SWW files), \code{Interpolation\_function} is used to
    1774 create a callable object that interpolates a value for an arbitrary
    1775 time \code{t} within the model limits and possibly a point \code{(x,
    1776 y)} within a mesh region.
    1777 
    1778 The actual time series at which data is available is specified by
    1779 means of an array \code{time} of monotonically increasing times. The
    1780 quantities containing the values to be interpolated are specified in
    1781 an array---or dictionary of arrays (used in conjunction with the
    1782 optional argument \code{quantity\_names}) --- called
    1783 \code{quantities}. The optional arguments \code{vertex\_coordinates}
    1784 and \code{triangles} represent the spatial mesh associated with the
    1785 quantity arrays. If omitted the function created by
    1786 \code{Interpolation\_function} will be a function of \code{t} only.
    1787 
    1788 Since, in practice, values need to be computed at specified points,
    1789 the syntax allows the user to specify, once and for all, a list
    1790 \code{interpolation\_points} of points at which values are required.
    1791 In this case, the function may be called using the form \code{f(t,
    1792 id)}, where \code{id} is an index for the list
    1793 \code{interpolation\_points}.
    1794 
    1795 \end{classdesc}
     1880%% \begin{classdesc}{Interpolation\_function}{self,
     1881%%     time,
     1882%%     quantities,
     1883%%     quantity_names = None,
     1884%%     vertex_coordinates = None,
     1885%%     triangles = None,
     1886%%     interpolation_points = None,
     1887%%     verbose = False}
     1888%% Module: \module{abstract\_2d\_finite\_volumes.least\_squares}
     1889
     1890%% Given a time series (i.e.\ a series of values associated with
     1891%% different times), whose values are either just numbers or a set of
     1892%% numbers defined at the vertices of a triangular mesh (such as those
     1893%% stored in SWW files), \code{Interpolation\_function} is used to
     1894%% create a callable object that interpolates a value for an arbitrary
     1895%% time \code{t} within the model limits and possibly a point \code{(x,
     1896%% y)} within a mesh region.
     1897
     1898%% The actual time series at which data is available is specified by
     1899%% means of an array \code{time} of monotonically increasing times. The
     1900%% quantities containing the values to be interpolated are specified in
     1901%% an array---or dictionary of arrays (used in conjunction with the
     1902%% optional argument \code{quantity\_names}) --- called
     1903%% \code{quantities}. The optional arguments \code{vertex\_coordinates}
     1904%% and \code{triangles} represent the spatial mesh associated with the
     1905%% quantity arrays. If omitted the function created by
     1906%% \code{Interpolation\_function} will be a function of \code{t} only.
     1907
     1908%% Since, in practice, values need to be computed at specified points,
     1909%% the syntax allows the user to specify, once and for all, a list
     1910%% \code{interpolation\_points} of points at which values are required.
     1911%% In this case, the function may be called using the form \code{f(t,
     1912%% id)}, where \code{id} is an index for the list
     1913%% \code{interpolation\_points}.
     1914
     1915%% \end{classdesc}
    17961916
    17971917%%%
     
    19052025
    19062026
     2027\begin{classdesc}{Dirichlet\_Discharge\_boundary}{Boundary}
     2028Module: \module{shallow\_water}
     2029
     2030Sets stage (stage0)
     2031Sets momentum (wh0) in the inward normal direction.
     2032\end{classdesc}
     2033
     2034
    19072035
    19082036\subsection{User-defined boundary conditions}
    19092037\label{sec:roll your own}
    1910 [How to roll your own] TBA
    1911 
    1912 
    1913 
    1914 
    1915 
    1916 \section{Forcing Functions}
    1917 
    1918 \anuga provides a number of predefined forcing functions to be used with .....
    1919 
    1920 %\begin{itemize}
    1921 
    1922 
    1923 %  \item \indexedcode{}
    1924 %  [function, arguments]
    1925 
    1926 %  \item \indexedcode{}
    1927 
    1928 %\end{itemize}
     2038
     2039All boundary classes must inherit from the generic boundary class
     2040\code{Boundary} and have a method called \code{evaluate} which must
     2041take as inputs \code{self, vol\_id, edge\_id} where self refers to the
     2042object itself and vol\_id and edge\_id are integers referring to
     2043particular edges. The method must return a list of three floating point
     2044numbers representing values for \code{stage},
     2045\code{xmomentum} and \code{ymomentum}, respectively.
     2046
     2047The constructor of a particular boundary class may be used to specify
     2048particular values or flags to be used by the \code{evaluate} method.
     2049Please refer to the source code for the existing boundary conditions
     2050for examples of how to implement boundary conditions.
     2051
     2052
     2053
     2054%\section{Forcing Functions}
     2055%
     2056%\anuga provides a number of predefined forcing functions to be used with .....
     2057
    19292058
    19302059
     
    20132142  \end{funcdesc}
    20142143 
     2144
     2145  \begin{funcdesc}{get\_integral}{}
     2146  Module: \module{abstract\_2d\_finite\_volumes.quantity}
     2147
     2148  Return computed integral over entire domain for this quantity
     2149
     2150  \end{funcdesc}
     2151
     2152 
    20152153 
    20162154
     
    20232161  the operation applies to. If omitted all elements are considered.
    20242162
    2025   Note, we do not seek the maximum at vertices as each vertex can
     2163  We do not seek the maximum at vertices as each vertex can
    20262164  have multiple values - one for each triangle sharing it.           
    20272165  \end{funcdesc}
     
    20342172  Return location of maximum value of quantity (on centroids)
    20352173
    2036         Optional argument indices is the set of element ids that the operation applies to.
    2037 
    2038         Usage:
    2039             x, y = get_maximum_location()
    2040 
    2041 
    2042         Notes:
    2043             We do not seek the maximum at vertices as each vertex can
    2044             have multiple values - one for each triangle sharing it.
    2045 
    2046             If there are multiple cells with same maximum value, the
    2047             first cell encountered in the triangle array is returned.       
    2048         """
    2049 
    2050         i = self.get_maximum_index(indices)
    2051         x, y = self.domain.get_centroid_coordinates()[i]
    2052 
    2053         return x, y
    2054 
    2055 
     2174  Optional argument indices is the set of element ids that
     2175  the operation applies to.
     2176
     2177  We do not seek the maximum at vertices as each vertex can
     2178  have multiple values - one for each triangle sharing it.
     2179
     2180  If there are multiple cells with same maximum value, the
     2181  first cell encountered in the triangle array is returned.       
     2182  \end{funcdesc}
     2183
     2184
     2185 
     2186  \begin{funcdesc}{get\_wet\_elements}{indices=None}
     2187  Module: \module{shallow\_water.shallow\_water\_domain} 
     2188
     2189  Return indices for elements where h > minimum_allowed_height
     2190  Optional argument indices is the set of element ids that the operation applies to.
     2191  \end{funcdesc}
     2192
     2193
     2194  \begin{funcdesc}{get\_maximum\_inundation\_elevation}{indices=None}
     2195  Module: \module{shallow\_water.shallow\_water\_domain} 
     2196
     2197  Return highest elevation where h > 0.\\
     2198  Optional argument indices is the set of element ids that the operation applies to.\\
     2199 
     2200  Example to find maximum runup elevation:\\ 
     2201     z = domain.get_maximum_inundation_elevation() 
     2202  \end{funcdesc}
     2203
     2204
     2205  \begin{funcdesc}{get\_maximum\_inundation\_location}{indices=None}
     2206  Module: \module{shallow\_water.shallow\_water\_domain} 
     2207 
     2208  Return location (x,y) of highest elevation where h > 0.\\
     2209  Optional argument indices is the set of element ids that the operation applies to.\\
     2210
     2211  Example to find maximum runup location:\\
     2212     x, y = domain.get_maximum_inundation_location() 
     2213  \end{funcdesc}
     2214
     2215 
     2216 
     2217\section{Other}
     2218
     2219  \begin{funcdesc}{domain.create\_quantity\_from\_expression}{???}
     2220
     2221  Handy for creating derived quantities on-the-fly as for example
     2222  \begin{verbatim}
     2223  Depth = domain.create_quantity_from_expression('stage-elevation')
     2224
     2225  exp = '(xmomentum*xmomentum + ymomentum*ymomentum)**0.5')       
     2226  Absolute_momentum = domain.create_quantity_from_expression(exp)
     2227  \end{verbatim}
    20562228 
    20572229 
    20582230 
    2059  
    2060  
    2061  
    2062  
    2063 
    2064   \begin{funcdesc}{get\_integral}{}
    2065   Module: \module{abstract\_2d\_finite\_volumes.quantity}
    2066 
    2067   Return computed integral over entire domain for this quantity
    2068 
    2069   \end{funcdesc}
    2070 
    2071   %FIXME (Ole): Document these new funcs in shallow_water_domain and the also the ones they use in quantity.py
    2072   %  w = domain.get_maximum_inundation_elevation()
    2073   %  x, y = domain.get_maximum_inundation_location() 
    2074 
    2075 \section{Other}
    2076 
    2077   \begin{funcdesc}{domain.create\_quantity\_from\_expression}{???}
    2078 
    2079   Handy for creating derived quantities on-the-fly.
    2080   See \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
     2231  See also \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
    20812232  \end{funcdesc}
    20822233
     
    27002851
    27012852\section{geospatial\_data}
     2853\label{sec:geospatial}
    27022854
    27032855This describes a class that represents arbitrary point data in UTM
     
    29683120\label{mod:quantity}
    29693121
    2970 
     3122\begin{verbatim}
    29713123Class Quantity - Implements values at each triangular element
    29723124
     
    29843136   Otherwise raise an exception
    29853137
    2986 
     3138\end{verbatim}
    29873139   
    29883140   
     
    30083160
    30093161\subsubsection{What is \anuga?}
     3162It is a software package suitable for simulating 2D water flows in
     3163complex geometries.
    30103164
    30113165\subsubsection{Why is it called \anuga?}
     3166The software was developed in collaboration between the
     3167Australian National University (ANU) and Geoscience Australia (GA).
    30123168
    30133169\subsubsection{How do I obtain a copy of \anuga?}
    3014 
    3015 \subsubsection{What developments are expected for \anuga in the future?}
     3170See url{https://datamining.anu.edu.au/anuga} for all things ANUGA.
     3171
     3172%\subsubsection{What developments are expected for \anuga in the future?}
     3173%This
    30163174
    30173175\subsubsection{Are there any published articles about \anuga that I can reference?}
     3176See url{https://datamining.anu.edu.au/anuga} for links.
     3177
    30183178
    30193179\section{Modelling Questions}
    30203180
    30213181\subsubsection{Which type of problems are \anuga good for?}
     3182General 2D waterflows in complex geometries such as
     3183dam breaks, flows amoung structurs, coastal inundation etc.
    30223184
    30233185\subsubsection{Which type of problems are beyond the scope of \anuga?}
     3186See Chapter \ref{ch:limitations}.
    30243187
    30253188\subsubsection{Can I start the simulation at an arbitrary time?}
     
    30613224if 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,
    30623225you need a fine mesh over regions where the DEM changes rapidly, and other areas of significant interest, such as the coast.
     3226If 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.
    30633227
    30643228
Note: See TracChangeset for help on using the changeset viewer.