Changeset 2455

Timestamp:

Feb 27, 2006, 4:52:42 PM (19 years ago)

Author:

howard

Message:

Further work on second example. Also reorganised section and subsection levels to give a more consistent logical structure.

File:

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

documentation/user_manual/anuga_user_manual.tex

@@ -146 +146 @@
 many of the ideas, and the second is a real-life example.
 
-\section{First Example: Overview}
+\section{A Simple Example}
+
+\subsection{Overview}
 
 What follows
@@ -181 +183 @@
 %\emph{[More details of the problem background]}
 
-\section{Outline of the Program}
+\subsection{Outline of the Program}
 
 In outline, \code{bedslope.py} performs the following steps:
@@ -203 +205 @@
 \end{enumerate}
 
-\section{The Code}
+\subsection{The Code}
 
 %FIXME: we are using the \code function here.
@@ -257 +259 @@
 for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0):
     domain.write_time()
-
-
-\end{verbatim}}
-
-
-\section{Establishing the Mesh}
+\end{verbatim}}
+
+
+\subsection{Establishing the Mesh}
 
 The first task is to set up the triangular mesh to be used for the
@@ -302 +302 @@
 
 
-\section{Initialising the Domain}
+\subsection{Initialising the Domain}
 
 These variables are then used to set up a data structure
@@ -323 +323 @@
 
 
-\section{Specifying the Quantities}
+\subsection{Specifying the Quantities}
 
 The next task is to specify a number of quantities that we wish to set
@@ -340 +340 @@
 
 
-\subsection{Elevation}
+\subsubsection{Elevation}
 
 The elevation is set using a function, defined through the
@@ -365 +365 @@
 
 
-\subsection{Friction}
+\subsubsection{Friction}
 
 The assignment of the friction quantity demonstrates another way
@@ -378 +378 @@
 to 0.1 at every mesh point.
 
-\subsection{Depth}
+\subsubsection{Depth}
 
 Assigning depth illustrates a more complex way to use
@@ -395 +395 @@
 elevation of the bed.
 
-\subsection{Boundary Conditions}
+\subsubsection{Boundary Conditions}
 
 The boundary conditions are specified as follows:
@@ -446 +446 @@
 
 
-\section{Evolution}
+\subsection{Evolution}
 
 The final statement \nopagebreak[3]
@@ -462 +462 @@
 
 
-\section{Output}
+\subsection{Output}
 
 %Give details here of the form of the output and explain how it can
@@ -493 +493 @@
 \code{run_sydney_smf.py}, that follows the same basic outline, but
 incorporates many more complex features.
+
+\subsection{Overview}
+As in the case of \code{bedslope.py}, the actions carried out by the
+program can be organised according to this outline:
+
+\begin{enumerate}
+
+   \item Set up a triangular mesh.
+
+   \item Set certain parameters governing the mode of
+operation of the model-specifying, for instance, where to store the
+model output.
+
+   \item Input various quantities describing physical measurements, such
+as the elevation, to be specified at each mesh point (vertex).
+
+   \item Set up the boundary conditions.
+
+   \item Carry out the evolution of the model through a series of time
+steps and outputs the results, providing a results file that can be
+visualised.
+
+\end{enumerate}
+
+
+
+\subsection{The Code}
 
 Here is the code for \code{run_sydney_smf.py}:
@@ -535 +562 @@
 from smf import slump_tsunami
 # Function for submarine mudslide
-
-
-#-------------------------------------------------------------------------------
-# Preparation of topographic data #
-# Convert ASC 2 DEM 2 PTS using
-source data and store result in source data
-# Do for coarse and fine
+\end{verbatim}}
+
+
+{\scriptsize \begin{verbatim}
+#-------------------------------------------------------------------------------
+# Preparation of topographic data # # Convert ASC 2 DEM 2 PTS using
+source data and store result in source data # Do for coarse and fine
 data
 
@@ -590 +617 @@
 
 from pmesh.create_mesh import create_mesh_from_regions
-
-num_polygons = 1 filelist = [] fileext = '.csv' filename =
-project.polygonptsfile interior_res = 50000
+\end{verbatim}}
+
+
+{\scriptsize \begin{verbatim}
+ num_polygons = 1 filelist = [] fileext
+= '.csv' filename = project.polygonptsfile interior_res = 50000
 
 for p in range(1, num_polygons+1):
@@ -599 +629 @@
     interior_regions.append([interior_polygon, interior_res])
 
-# test #interior_regions = [[project.poly1, interior_res], #
-[project.poly2, interior_res]] # original #interior_regions =
-[[project.harbour_polygon_2, interior_res], #
+# test
+#interior_regions = [[project.poly1, interior_res],
+#
+[project.poly2, interior_res]]
+# original
+#interior_regions =
+[[project.harbour_polygon_2, interior_res],
+#
 [project.botanybay_polygon_2, interior_res]]
 
 #FIXME: Fix caching of this one once the mesh_interface is ready
-from caching import cache _ = cache(create_mesh_from_regions,
+from caching import cache
+_ = cache(create_mesh_from_regions,
           project.diffpolygonall,
           {'boundary_tags': {'bottom': [0],
@@ -620 +656 @@
 
 #-------------------------------------------------------------------------------
-# Setup computational domain
+# Set up computational domain
 #-------------------------------------------------------------------------------
 
@@ -694 +730 @@
 high-level perspective of the various tasks it undertakes.
 
-If we compare this example with \code{bedslope.py}, the most
-noticeable difference is that data is taken from a file. This is to
-be expected, since the example now represents an actual physical
-scenario rather than an illustrative example.
-
-However, another important difference is that this example uses a
-different method to create the mesh---one more suited to use for a
-physical scenario. Instead of imposing a mesh structure on a
+\subsection{Establishing the Mesh}
+
+Comparing the present example with \code{bedslope.py}, we note that
+one important difference is 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 structures inside polygons specified by the user.
 
-In its simplest form, this technique creates the mesh within a
-single polygon whose vertices are at geographical locations
-specified by the user. A triangular mesh is created using points
-inside the polygon selected through a random process, the user
-specifying the \emph{resolution}---that is, the maximal area of a
-triangle used for triangulation.
-
-Figure XXX shows a simple example, in which the triangulation is
-carried out within a pentagon. Instead of using the four tags
-\code{`left'}, \code{`right'}, \code{`bottom'} and
-\code{`top'} to distinguish boundary elements, the user can define
-tags appropriate to the configuration being modelled.
-
-While this offers more flexibility than the rectangular grid, it
-doesn't provide a way to adapt to geographic or other features in the
-landscape, for which we may require to vary the resolution. We achieve
-more flexibility by extending this method, allowing the user to
-specify a number of interior polygons which are triangulated
-separately, possibly using different resolutions.  See Figure XXX.
-
-As before, we start by including
-
-
-
-
-
-
+The following remarks may help the reader understand the basic ideas
+behind the mesh-creation technique used in this program.
+
+In its simplest form, the technique creates the mesh within a single
+polygon whose vertices are at geographical locations specified by
+the user. A triangular mesh is created using points inside the
+polygon selected through a random process, the user specifying the
+\emph{resolution}---that is, the maximal area of a triangle used for
+triangulation.
+
+Figure XXX shows a simple example of this, in which the
+triangulation is carried out within a pentagon. Instead of using the
+four tags \code{`left'}, \code{`right'}, \code{`bottom'} and
+\code{`top'} that we used in the case of \code{bedslope.py} to
+distinguish boundary elements, the user can define tags appropriate
+to the configuration being modelled.
+
+While this simple version of the technique offers more flexibility
+than the rectangular grid, it doesn't provide a way to adapt to
+geographic or other features in the landscape, whose presence may
+require us to vary the resolution in the neighbourhood of the
+features. To achieve more flexibility we therefore extend the
+technique, allowing the user to specify a number of interior
+polygons to be triangulated separately, possibly using different
+resolutions. See Figure XXX.
+
+The upshot is a general method that takes for its input a bounding
+polygon and (optionally) a list of interior polygons. It creates a
+triangular mesh inside the bounding polygon, using a specified
+resolution, but initially leaves the regions inside the interior
+polygons alone. It then triangulates each of these regions
+separately, using a separately specified resolution.
+
+The function used to implement this process is the function
+\code{create_mesh_from_regions}. Its arguments include the bounding
+polygon and its resolution, a list of boundary tags, and a list of
+pairs \code{[polygon, resolution]}, specifying the interior polygons
+and their resolutions.
+
+In practice, the details of the polygons used are read from a
+separate file \code{project.py}.
+
+
+\subsection{Initialising the Domain}
+
+As with \code{bedslope.py}, once we have created the mesh, the next
+step is to create the data structure \code{domain}.
+
+{\scriptsize \begin{verbatim}
+domain =
+pmesh_to_domain_instance(meshname, Domain,
+                                  use_cache = True,
+                                  verbose = True)
+\end{verbatim}}
+
+\subsection{Specifying the Quantities}
+
+{\scriptsize \begin{verbatim}
+domain.set_name(project.basename)
+domain.set_datadir(project.outputdir)
+domain.set_quantities_to_be_stored(['stage', 'xmomentum',
+'ymomentum'])
+
+
+#-------------------------------------------------------------------------------
+# 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)
+
+
+#-------------------------------------------------------------------------------
+# Setup initial conditions
+#-------------------------------------------------------------------------------
+
+domain.set_quantity('stage', tsunami_source)
+domain.set_quantity('friction', 0.03) # supplied by Benfield
+domain.set_quantity('elevation',
+                    filename = project.combineddemname + '.pts',
+                    use_cache = True,
+                    verbose = True)
+\end{verbatim}}
+
+\subsection{Boundary Conditions}
+
+{\scriptsize \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}}
 
 \chapter{\anuga Public Interface}