Changeset 5976

Timestamp:

Nov 19, 2008, 3:21:51 PM (16 years ago)

Author:

ole

Message:

Documentation update (get values, georef, etc)

Location:

anuga_core

Files:

• documentation/user_manual/anuga_user_manual.tex (modified) (11 diffs)
• source/anuga/abstract_2d_finite_volumes/quantity.py (modified) (2 diffs)

anuga_core/documentation/user_manual/anuga_user_manual.tex

@@ -1100 +1100 @@
 indices refer to edges in the order they appear: Edge 0 connects vertex 0 and vertex 1, edge 1 connects vertex 1 and 2; and so forth.
 (Here, the values associated with each boundary tag are one-element lists, but they can have as many indices as there are edges)
-If polygons intersect, or edges coincide the resolution may be undefined in some regions.
+If polygons intersect, or edges coincide (or are even very close) the resolution may be undefined in some regions.
 Use the underlying mesh interface for such cases. See Section
 \ref{sec:mesh interface}.
@@ -1906 +1906 @@
 
 
-\begin{methoddesc}{get\_vertex_coordinates}{absolute=False}
-
+\begin{methoddesc}{get\_vertex\_coordinates}{absolute=False}
+    \label{pg:get vertex coordinates}
     Return vertex coordinates for all triangles.
 
@@ -1914 +1914 @@
     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\_centroid\_coordinates}{absolute=False}
+
+    Return centroid coordinates for all triangles.
+
+    Return all centroid coordinates for all triangles as a M x 2 array
+    
     Boolean keyword argument absolute determines whether coordinates
     are to be made absolute by taking georeference into account
@@ -2027 +2039 @@
 \item \code{location} determines which part of the triangles to assign
   to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'.
+  If 'vertices' are use, edge and centroid values are automatically computed as the appropriate averages. This option ensures continuity of the surface.
+  If, on the other hand, 'centroids' is used vertex and edge values will be set to the same value effectively creating a piecewise constant surface with possible discontinuities at the edges.
 \end{itemize}
 
@@ -2551 +2565 @@
   model will evolve through several steps internally
   as the method forces the water speed to be calculated
-  on successive new cells). The user
+  on successive new cells). 
+  
+  The code specified by the user in the block following the evolve statement is only executed once every \code{yieldstep} even though 
+  ANUGA typically will take many more internal steps behind the scenes.
+  
+  The user
   specifies the total time period over which the evolution is to take
   place, by specifying values (in seconds) for either \code{duration}
@@ -2617 +2636 @@
   Module: \module{abstract\_2d\_finite\_volumes.domain}
 
-  Allow access to individual quantities and their methods
-
+  This function returns a Quantity object Q.
+  Access to it's values should be done through Q.get\__values documented on Page \pageref{pg:get values}.
+  
   \end{funcdesc}
 
@@ -2674 +2694 @@
 
   \begin{funcdesc}{get\_values}{location='vertices', indices = None}
+  \label{pg:get values}
   Module: \module{abstract\_2d\_finite\_volumes.quantity}
 
-  Extract values for quantity as an array
-
+  Extract values for quantity as a Numeric array.
+
+  {\small \begin{verbatim}
+  Inputs:
+          interpolation_points: List of x, y coordinates where value is
+                                sought (using interpolation). If points 
+                                are given, values of location and indices 
+                                are ignored. Assume either absolute UTM
+                                coordinates or geospatial data object.
+        
+          location: Where values are to be stored.
+                    Permissible options are: vertices, edges, centroids
+                    and unique vertices. Default is 'vertices'
+
+
+  The returned values will have the leading dimension equal to length of the indices list or
+  N (all values) if indices is None.
+        
+  In case of location == 'centroids' the dimension of returned
+  values will be a list or a Numerical array of length N, N being
+  the number of elements.
+        
+  In case of location == 'vertices' or 'edges' the dimension of
+  returned values will be of dimension Nx3
+
+  In case of location == 'unique vertices' the average value at
+  each vertex will be returned and the dimension of returned values
+  will be a 1d array of length "number of vertices" 
+        
+  Indices is the set of element ids that the operation applies to.
+
+  The values will be stored in elements following their
+  internal ordering.
+  
   \end{funcdesc}
 
@@ -3030 +3083 @@
 Chapter \ref{ch:getstarted}:
 
+%FIXME (Ole): Should put in example with nonzero xllcorner, yllcorner
 \verbatiminput{examples/bedslopeexcerpt.cdl}
 
@@ -3079 +3133 @@
 
 A mesh file can also contain a georeference, which describes an
-offset to be applied to $x$ and $y$ values---eg to the vertices.
+offset to be applied to $x$ and $y$ values --- e.g.\ to the vertices.
 
 
@@ -3091 +3145 @@
 %\begin{verbatim}
 
-            first line:     \code{[column names]}\\
+            first line:   \code{[column names]}\\
             other lines:  \code{[x value], [y value], [attributes]}\\
 
@@ -3566 +3620 @@
 \chapter{Basic \anuga Assumptions}
 
-
+ \section{Time}
 Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
 If one wished to recreate scenarios prior to that date it must be done
 using some relative time (e.g. 0).
 
-
-All spatial data relates to the WGS84 datum (or GDA94) and has been
-projected into UTM with false easting of 500000 and false northing of
-1000000 on the southern hemisphere (0 on the northern).
-
-It is assumed that all computations take place within one UTM zone and
-all locations must consequently be specified in Cartesian coordinates
+The ANUGA domain has an attribute \code{starttime} which is used in cases where the simulation should be started later than the beginning of some input data such as those obtained from boundaries or forcing functions (hydrographs, file\_boundary etc)
+
+The \code{file\_boundary} may adjust domain.startime in case the input data does not itself start until a later time. 
+
+ 
+\section{Spatial data}
+
+\subsection{Projection}
+All spatial data relates to the WGS84 datum (or GDA94) and assumes a projection into UTM with false easting of 500000 and false northing of
+1000000 on the southern hemisphere (0 on the northern hemisphere). 
+All locations must consequently be specified in Cartesian coordinates
 (eastings, northings) or (x,y) where the unit is metres.
-
-DEMs, meshes and boundary conditions can have different origins within
-one UTM zone. However, the computation will use that of the mesh for
-numerical stability.
-
+Alternative projections can be assumed, but ANUGA does have the concept of a UTM zone 
+that must be the same for all coordinates in the model.
+
+\subsection{Internal coordinates}
+It is important to realise that ANUGA for numerical precision uses coordinates that are relative 
+to the lower left node of the rectangle containing the mesh ($x_$min, $y_$min). 
+This origin is referred to internally as xllcorner, yllcorner following the ESRI ascii grid notation.  
+The sww file format also includes xllcorner, yllcorner and any coordinate in the file should be adjusted 
+by adding this origin. See Section \ref{sec:sww format}.
+
+Throughout the ANUGA interface functions have optional boolean arguments \code{absolute} which control 
+whether spatial data received is using the internal representation (absolute=False) or the 
+user coordinate set (absolute=True). See e.g. \code{get\_vertex\_coordinates} on \pageref{pg:get vertex coordinates}.
+
+DEMs, meshes and boundary conditions can have different origins. However, the internal representation in ANUGA 
+will use the origin of the mesh.
+
+\subsection{Polygons}
 When generating a mesh it is assumed that polygons do not cross.
 Having polygons tht cross can cause the mesh generation to fail or bad

anuga_core/source/anuga/abstract_2d_finite_volumes/quantity.py

@@ -1084 +1084 @@
         """get values for quantity
 
-        return X, Compatible list, Numeric array (see below)
+        Extract values for quantity as a Numeric array.        
         
         Inputs:
@@ -1098 +1098 @@
 
 
-        The returned values with be a list the length of indices
-        (N if indices = None).
+        The returned values will have the leading dimension equal to length of the indices list or
+        N (all values) if indices is None.
 
         In case of location == 'centroids' the dimension of returned