Changeset 2529 for documentation

Timestamp:

Mar 12, 2006, 11:16:03 PM (19 years ago)

Author:

howard

Message:

Ongoing editing of earlier sections and padding out of Chapter 3

File:

• documentation/user_manual/anuga_user_manual.tex (modified) (39 diffs)

documentation/user_manual/anuga_user_manual.tex

@@ -43 +43 @@
 
 \setcounter{tocdepth}{3}
-
+\setcounter{secnumdepth}{3}
 \begin{document}
 \maketitle
@@ -108 +108 @@
 The purpose of this user manual is to introduce the new user to
 the software, describe what it can do and give step-by-step
-instructions for setting up, configuring and running the software.
+instructions for setting up and running hydrodynamic simulations.
 
 \section{Scope}
 
 This manual covers only what is needed to operate the software
-after installation. It does not includes instructions for
+after installation and configuration. It does not includes instructions for
 installing the software or detailed API documentation, both of
 which will be covered in separate publications.
@@ -144 +144 @@
 \anuga by working through simple examples. Two examples are discussed;
 the first is a simple but artificial example that is useful to illustrate
-many of the ideas, and the second is a real-life example.
+many of the ideas, and the second is a more realistic example.
 
 \section{A Simple Example}
@@ -150 +150 @@
 \subsection{Overview}
 
-What follows
-is a discussion of the structure and operation of the file
-\code{bedslope.py}, with just enough detail to allow the reader
+What follows is a discussion of the structure and operation of the file
+\code{bedslopephysical.py}, with just enough detail to allow the reader
 to appreciate what's involved in setting up a scenario like the
 one it depicts.
@@ -170 +169 @@
 terms. The boundary is reflective on three sides and a time dependent wave on one side.
 
-The present example, as it represents a simple scenario, does not
-include any forcing term, nor is the data taken from a file as it
-would be in many typical cases. The quantities involved in the
-present problem are:
-\begin{itemize}
-   \item elevation\index{elevation}
-   \item friction\index{friction}
-   \item depth\index{depth}
-   \item stage\index{stage}
-\end{itemize}
+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. 
+
+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) 
+and elevation, the last two being related to
+the depth through the equation
+
+{\small \begin{verbatim}
+\code{stage} = \code{elevation} + \code{depth}
+\end{verbatim}}
 
 %\emph{[More details of the problem background]}
@@ -185 +187 @@
 \subsection{Outline of the Program}
 
-In outline, \code{bedslope.py} performs the following steps:
+In outline, \code{bedslopephysical.py} performs the following steps:
 
 \begin{enumerate}
@@ -210 +212 @@
 %This should be used wherever possible
 For reference we include below the complete code listing for
-\code{bedslope.py}. Subsequent paragraphs provide a `commentary'
+\code{bedslopephysical.py}. Subsequent paragraphs provide a `commentary'
 that describes each step of the program and explains it significance.
 
-\verbatiminput{examples/bedslope_physical.py}
+\verbatiminput{examples/bedslopephysical.py}
 
 \subsection{Establishing the Mesh}
@@ -334 +336 @@
 The stage (the height of the water surface) is related to the
 elevation and the depth at any time by the equation \[\code{stage} =
-\code{elevation} + \code{depth}\] To specify a constant depth of a
-particular value, therefore, we need to specify that \code{stage} is
-everywhere obtained by adding that constant value to the already
-specified \code{elevation}. Doing this allows us to illustrate
-another way to use \code{set\_quantity}, introducing an expression
-involving other quantities:
+\code{elevation} + \code{depth}\] 
+
+For this example, we simply assign a constant value to \code{stage},
+using the statement
+
+{\small \begin{verbatim}
+    domain.set_quantity('stage', -.4)
+\end{verbatim}}
+
+which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units 
+below the zero level.
+
+(Although it is not necessary for this example, it may be useful to digress here
+and mention a variant to this requirement, which allows us to illustrate
+another way to use \code{set\_quantity}---namely, incorporating an expression
+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  
+need to specify that \code{stage} is
+everywhere obtained by adding that value to the value already
+specified for \code{elevation}. We would do this by means of the statements:
 
 {\small \begin{verbatim}
@@ -346 +363 @@
 \end{verbatim}}
 
-Here we are stipulating that the quantity \code{stage} is defined by
-taking the quantity elevation already defined and adding a constant
-value $h = 0.05$ to it everywhere.
+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 
+expressions into statements using \code{set\_quantity} greatly expands
+its power.)
 
 \subsubsection{Boundary Conditions}
@@ -369 +389 @@
 assigned as needed. Each boundary condition specifies the
 behaviour at a boundary in terms of the behaviour in neighbouring
-elements. The boundary conditions may be briefly described as
+elements. The boundary conditions introduced here may be briefly described as
 follows:
 
@@ -383 +403 @@
 
     \item[Dirichlet boundary]Specifies a fixed value at the
-boundary.
+boundary and assigns initial values to the $x$-momentum and $y$-momentum.  
 
     \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time.
@@ -399 +419 @@
 boundary is fixed, with an elevation of 0.2, while the other
 boundaries are all reflective.
+
+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 
+
+{\small \begin{verbatim}
+    Bw = Time_boundary(domain=domain,
+                f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0])
+\end{verbatim}}
+
 
 
@@ -432 +462 @@
 
 \begin{itemize}
-  \item{from a Windows command line} as in \code{python bedslope.py}
+  \item{from a Windows command line} as in \code{python bedslopephysical.py}
   \item{within the Python IDLE environment}
   \item{within emacs}
-  \item{from a Linux command line} as in \code{python bedslope.py}
+  \item{from a Linux command line} as in \code{python bedslopephysical.py}
 \end{itemize}
 
@@ -441 +471 @@
 \section{Exploring the model output}
 
-blablabal Figure \ref{fig:bedslope start} shows the 
+Figure \ref{fig:bedslopestart} shows the \\
 Figure \ref{fig:bedslope2} shows later snapshots...
 
@@ -448 +478 @@
 \begin{figure}[hbt] 
 
-  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}}
-  
-  \caption{Bedslope example viewed with Swollen.}
-  \label{fig:bedslope start}
+  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslope_start.eps}}
+  
+  \caption{Bedslope example viewed with Swollen}
+  \label{fig:bedslopestart}
 \end{figure} 
 
@@ -458 +488 @@
 
   \centerline{ 
-    \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps}
-    \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps}
+    \includegraphics[width=75mm, height=75mm]{examples/bedslope_during.eps}
+    \includegraphics[width=75mm, height=75mm]{examples/bedslope_end.eps}
    }    
   
-  \caption{Bedslope example viewed with Swollen.}
+  \caption{Bedslope example viewed with Swollen}
   \label{fig:bedslope2}
 \end{figure} 
@@ -476 +506 @@
 
 The following discussion builds on the concepts introduced through
-the \code{bedslope.py} example and introduces a second example,
+the \code{bedslopephysical.py} example and introduces a second example,
 \code{run\_sydney\_smf.py}, that follows the same basic outline, but
 incorporates more complex features and refers to a real-life
 scenario, rather than the artificial illustrative one used in
-\code{bedslope.py}. [Include details of the scenario to which it
-refers??]
+\code{bedslopephysical.py}. The domain of interest surrounds the Sydney region,
+and predominantly covers Sydney Harbour. A hypothetical tsunami wave is 
+generated by a submarine mass failure situated on the edge of the
+continental shelf.
 
 \subsection{Overview}
-As in the case of \code{bedslope.py}, the actions carried out by the
+As in the case of \code{bedslopephysical.py}, the actions carried out by the
 program can be organised according to this outline:
 
@@ -492 +524 @@
 
    \item Set certain parameters governing the mode of
-operation of the model-specifying, for instance, where to store the
+operation of the model---specifying, for instance, where to store the
 model output.
 
@@ -521 +553 @@
 
 One obvious way that the present example differs from
-\code{bedslope.py} is in the use of a more complex method to create
+\code{bedslopephysical.py} is in the use of a more complex method to create
 the mesh. Instead of imposing a mesh structure on a rectangular
 grid, the technique used for this example involves building mesh
@@ -543 +575 @@
 
   
-  \caption{Mesh points are created inside the polygon.}
+  \caption{Mesh points are created inside the polygon}
   \label{fig:pentagon}  
 \end{figure} 
@@ -549 +581 @@
 Boundary tags are not restricted to \code{`left'}, \code{`right'},
 \code{`bottom'} and \code{`top'}, as in the case of
-\code{bedslope.py}. Instead the user specifies a list of tags
+\code{bedslopephysical.py}. Instead the user specifies a list of tags
 appropriate to the configuration being modelled.
 
@@ -566 +598 @@
 
  
-  \caption{Interior meshes with individual resolution.}
+  \caption{Interior meshes with individual resolution}
   \label{fig:interior meshes}  
 \end{figure} 
@@ -599 +631 @@
 \code{meshname}.
 
+The statements 
+
+{\small \begin{verbatim}
+    interior_res = 5000%
+    interior_regions = [[project.harbour_polygon_2, interior_res],
+                    [project.botanybay_polygon_2, interior_res]]
+\end{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 
+
+{\small \begin{verbatim}
+    create_mesh_from_regions(project.diffpolygonall,%
+                         boundary_tags= {'bottom': [0],% 
+                                         'right1': [1],%
+                                         'right0': [2],%
+                                         'right2': [3],%
+                                         'top': [4],%
+                                         'left1': [5],%
+                                         'left2': [6],%
+                                         'left3': [7]},%
+                         maximum_triangle_area=100000,%
+                         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'--- 
+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.)
+
 
 \subsection{Initialising the Domain}
 
-As with \code{bedslope.py}, once we have created the mesh, the next
+As with \code{bedslopephysical.py}, once we have created the mesh, the next
 step is to create the data structure \code{domain}. We did this for
-\code{bedslope.py} by inputting lists of points and triangles and
+\code{bedslopephysical.py} by inputting lists of points and triangles and
 specifying the boundary tags directly. However, in the present case,
 we use a method that works directly with the meshfile
@@ -610 +677 @@
 
 {\small \begin{verbatim}
-domain = pmesh_to_domain_instance(meshname,
-Domain, use_cache = True, verbose = True)
+    domain = pmesh_to_domain_instance(meshname,
+    Domain, use_cache = True, verbose = True)
 \end{verbatim}}
 
@@ -624 +691 @@
 \code{Domain}.)
 
+The following statements specify a basename and data directory, and
+identify quantities to be stored. For the first two, values are
+taken from \code{project.py}.
+
+{\small \begin{verbatim} 
+    domain.set_name(project.basename)%
+    domain.set_datadir(project.outputdir)%
+    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
+        'ymomentum'])
+\end{verbatim}}
+
+
 \subsection{Specifying the Quantities}
-Setting quantities for \code{run\_sydney\_smf.py} is accomplished
-using similar methods to those used in \code{bedslope.py}. However,
+Quantities for \code{run\_sydney\_smf.py} are set
+using similar methods to those in \code{bedslopephysical.py}. However,
 in this case, many of the values are read from the auxiliary file
 \code{project.py} or, in the case of \code{elevation}, from an
@@ -632 +711 @@
 
 
-\subsubsection{Fundamental Quantities}
-
-The following statements specify a basename and data directory, and
-identify quantities to be stored. For the first two, values are
-taken from \code{project.py}.
-
-{\small \begin{verbatim} domain.set_name(project.basename)
-domain.set_datadir(project.outputdir)
-domain.set_quantities_to_be_stored(['stage', 'xmomentum',
-'ymomentum'])
-\end{verbatim}}
 
 \subsubsection{Stage}
@@ -649 +717 @@
 object \code{tsunami\_source}, assigned by means of a function
 \code{slump\_tsunami}. This is similar to how we set elevation in
-\code{bedslope.py} using a function---however, in this case the
-function is both more complex and more interesting.
-
-{\small \begin{verbatim}
-#-------------------------------------------------------------------------------
-# Set up scenario (tsunami_source is a callable object used with
-set_quantity)
-#-------------------------------------------------------------------------------
-
-tsunami_source = slump_tsunami(length=30000.0,
-                               depth=400.0,
-                               slope=6.0,
-                               thickness=176.0,
-                               radius=3330,
-                               dphi=0.23,
-                               x0=project.slump_origin[0],
-                               y0=project.slump_origin[1],
-                               alpha=0.0,
-                               domain=domain)
-
-
-#-------------------------------------------------------------------------------
-# Set up initial conditions
-#-------------------------------------------------------------------------------
-
-domain.set_quantity('stage', tsunami_source)
-\end{verbatim}}
+\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 
+on the characteristics of the slump (length, thickness, slope, etc), its
+location (origin) and the depth at that location. 
+
 
 \subsubsection{Friction}
 
-Assigning the friction is exactly parallel to what we did for
-\code{bedslope.py}:
-
-{\small \begin{verbatim}
-domain.set_quantity('friction', 0.03)
-#supplied by Benfield
+We assign the friction exactly as we did for \code{bedslopephysical.py}:
+
+{\small \begin{verbatim}
+    domain.set_quantity('friction', 0.03)
 \end{verbatim}}
 
@@ -690 +737 @@
 \subsubsection{Elevation}
 
-In this example, 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)
+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)%
 \end{verbatim}}
 
@@ -724 +770 @@
 \subsection{Boundary Conditions}
 
-Setting boundaries in \code{run\_sydney\_smf.py} is very similar to
-what we did in \code{bedslope.py}, except that we now have a larger
-number of boundary tags:
-
-{\small \begin{verbatim}
-Br = Reflective_boundary(domain)
-domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
-                      'right2': Br, 'top': Br, 'left1': Br,
-                      'left2': Br, 'left3': Br} )
+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 for each of the
+eight tagged segments:
+
+{\small \begin{verbatim}
+    Br = Reflective_boundary(domain)
+    domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
+                          'right2': Br, 'top': Br, 'left1': Br,
+                          'left2': Br, 'left3': Br} )
 \end{verbatim}}
 
@@ -738 +788 @@
 
 With the basics established, the running of the `evolve' step is
-very similar to the corresponding step in \code{bedslope.py}:
-
-{\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()-t0)
+very similar to the corresponding step in \code{bedslopephysical.py}:
+
+{\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}}
 
@@ -777 +827 @@
 introducing the code, between two sets of triple quotes.
 
-Each paragraph also describes the location of the module in which
+Each listing also describes the location of the module in which
 the code for the feature being described can be found. All modules
-are in the folder \code{inundation} or its subfolders, and the
-location of each module is described relative to this folder. Rather
+are in the folder \code{inundation} or one of its subfolders, and the
+location of each module is described relative to \code{inundation}. Rather
 than using pathnames, whose syntax depends on the operating system,
 we use the format adopted for importing the function or class for
@@ -790 +840 @@
 
 \begin{center}
-\code{pmesh/mesh\_interface.py}
+    \code{pmesh/mesh\_interface.py}
 \end{center}
 
@@ -796 +846 @@
 
 \begin{center}
-\code{pmesh}$\backslash$\code{mesh\_interface.py}
+    \code{pmesh}$\backslash$\code{mesh\_interface.py}
 \end{center}
 
@@ -804 +854 @@
 namely:
 \begin{center}
-\code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
+    \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
 \end{center}
 
@@ -820 +870 @@
 Module: \code{pmesh.mesh\_interface}
 
+% 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
@@ -836 +887 @@
 \code{file\_name} is the name of the mesh file to be converted,
 including the extension. \code{DomainClass} is the class to be
-returned, which must be a subclass of \code{Domain}, with the same
+returned, which must be a subclass of \code{Domain} having the same
 interface as \code{Domain}---in practice, it can usually be set
 simply to \code{Domain}.
@@ -866 +917 @@
 \section{Setting Quantities}
 
-\begin{funcdesc}{set\_quantity}{name, *args, **kwargs}
-Module: \code{pyvolution.domain} -- see also
-\code{pyvolution.quantity.set_values}
+\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}
+Module: \code{pyvolution.domain}  (see also
+\code{pyvolution.quantity.set_values})
 
 numeric:\\
@@ -921 +975 @@
 
 
-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.
+%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.
 
 Exactly one of the arguments
@@ -1174 +1228 @@
 \section{Other}  
 
-  \begin{funcdesc}{domain.create_quantity_from_expression}{}  
-  
-  Handy for creating derived quantities on-the-fly 
-  See Analytical\_solution_\circular\_hydraulic\_jump.py for an example of use.
+  \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}