# Changeset 2529

Ignore:
Timestamp:
Mar 12, 2006, 11:16:03 PM (17 years ago)
Message:

Ongoing editing of earlier sections and padding out of Chapter 3

File:
1 edited

### Legend:

Unmodified
 r2524 \setcounter{tocdepth}{3} \setcounter{secnumdepth}{3} \begin{document} \maketitle 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. \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} \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. 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]} \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} %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} 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} \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} 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: \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. 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}} \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} \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... \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} \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} 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: \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. 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 \caption{Mesh points are created inside the polygon.} \caption{Mesh points are created inside the polygon} \label{fig:pentagon} \end{figure} 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. \caption{Interior meshes with individual resolution.} \caption{Interior meshes with individual resolution} \label{fig:interior meshes} \end{figure} \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 {\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}} \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 \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} 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}} \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}} \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}} 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}} 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 \begin{center} \code{pmesh/mesh\_interface.py} \code{pmesh/mesh\_interface.py} \end{center} \begin{center} \code{pmesh}$\backslash$\code{mesh\_interface.py} \code{pmesh}$\backslash$\code{mesh\_interface.py} \end{center} 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} 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 \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}. \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:\\ 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 \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}