# Changeset 2559

Ignore:
Timestamp:
Mar 20, 2006, 8:37:32 AM (17 years ago)
Message:

Updated material on swollen. Reworded text in a number of places to improve readability.

File:
1 edited

### Legend:

Unmodified
 r2542 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. 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) 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} stage = elevation + depth \code{stage} = \code{elevation} + \code{depth} \end{verbatim}} The stage (the height of the water surface) is related to the elevation and the depth at any time by the equation {\small \begin{verbatim} stage = elevation + depth \end{verbatim}} elevation and the depth at any time by the equation $\code{stage} = \code{elevation} + \code{depth}$ For this example, we simply assign a constant value to \code{stage}, \end{verbatim}} which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units below the zero level. 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 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 \end{verbatim}} That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the 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 The reader will probably appreciate that this capability to incorporate expressions into statements using \code{set\_quantity} greatly expands its power.) \item[Dirichlet boundary]Specifies a fixed value at the boundary and assigns initial values to the $x$-momentum and $y$-momentum. boundary and assigns initial values to the $x$-momentum and $y$-momentum. \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time. 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 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} \begin{figure}[hbt] \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}} \caption{Bedslope example viewed with Swollen} \label{fig:bedslopestart} \end{figure} \begin{figure}[hbt] \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps} \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps} } \caption{Bedslope example viewed with Swollen} \label{fig:bedslope2} \end{figure} %\begin{figure}[hbt] %  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslope_start.eps}} %  \caption{Bedslope example viewed with Swollen} %  \label{fig:bedslopestart} %\end{figure} %\begin{figure}[hbt] %  \centerline{ %    \includegraphics[width=75mm, height=75mm]{examples/bedslope_during.eps} %    \includegraphics[width=75mm, height=75mm]{examples/bedslope_end.eps} %   } %  \caption{Bedslope example viewed with Swollen} %  \label{fig:bedslope2} %\end{figure} scenario, rather than the artificial illustrative one used in \code{bedslopephysical.py}. The domain of interest surrounds the Sydney region, and predominantly covers Sydney Harbour. A hypothetical tsunami wave is and predominantly covers Sydney Harbour. A hypothetical tsunami wave is generated by a submarine mass failure situated on the edge of the continental shelf. area of a triangle used for triangulation---and mesh points are created inside the polygon through a random process. Figure \ref{fig:pentagon} shows a simple example of this, in which \ref{fig:pentagon} shows a simple example of this, in which the triangulation is carried out within a pentagon. \begin{figure}[hbt] \caption{Mesh points are created inside the polygon} \label{fig:pentagon} \end{figure} %\begin{figure}[hbt] %  \caption{Mesh points are created inside the polygon} %  \label{fig:pentagon} %\end{figure} Boundary tags are not restricted to \code{left'}, \code{right'}, resolution. See Figure \ref{fig:interior meshes}. \begin{figure}[hbt] \caption{Interior meshes with individual resolution} \label{fig:interior meshes} \end{figure} %\begin{figure}[hbt] %  \caption{Interior meshes with individual resolution} %  \label{fig:interior meshes} %\end{figure} In its general form, \code{pmesh} takes for its input a bounding \code{meshname}. The statements The statements {\small \begin{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 common resolution of 5000 to each. The statement {\small \begin{verbatim} create_mesh_from_regions(project.diffpolygonall,% boundary_tags= {'bottom': [0],% boundary_tags= {'bottom': [0],% 'right1': [1],% 'right0': [2],% 'left3': [7]},% maximum_triangle_area=100000,% filename=meshname,% 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'--- \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.) taken from \code{project.py}. {\small \begin{verbatim} {\small \begin{verbatim} domain.set_name(project.basename)% domain.set_datadir(project.outputdir)% \code{slump\_tsunami}. This is similar to how we set elevation in \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 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. location (origin) and the depth at that location. 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) {\small \begin{verbatim}% domain.set_quantity('elevation',% filename = project.combineddemname + '.pts',% use_cache = True,% verbose = True)% \end{verbatim}} \subsection{Boundary Conditions} Setting boundaries follows a similar pattern to the one used for \code{bedslopephysical.py}, except that in this case we need to associate a 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 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} 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}} The listings are intended merely to give the reader an idea of what each feature is, where to find it and how it can be used---they do not give full specifications of the features. For these the reader not give full specifications. For these the reader may consult the code. The code for every function or class contains a documentation string, or `docstring', that specifies the precise % 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 resolution---that is, the maximal area of triangles in the mesh. The bounding polygon also has symbolic \code{tags} associated with it. This function is used to create a triangular mesh suitable for use with \anuga, within a specified region. The region is specified as the interior of a polygon (the \emph{bounding polygon}). The user specifies the bounding polygon and the \emph{resolution}---that is, maximal area of any triangle in the mesh. There is also an option to specify a number of internal polygons within each of which a separate mesh is created, generally with a smaller resolution. Additionally, the user specifies a list of boundary tags, one for each edge of the bounding polygon. \end{funcdesc} Module: \code{pyvolution.pmesh2domain} Converts a generated mesh file to a domain object. Once the initial mesh file has been created, this function is applied to convert it to a domain object---that is, to a member of the special Python class Domain (or a subclass of Domain), which provides access to properties and methods that allow quantities to be set and other operations to be carried out. \code{file\_name} is the name of the mesh file to be converted, \section{Setting Quantities} \begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None, geospatial_data = None, filename = None, attribute_name = None, \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} \code{pyvolution.quantity.set_values}) numeric:\\ Compatible list, Numeric array (see below) or constant. If callable it will treated as a function (see below) If instance of another Quantity it will be treated as such. If geo\_spatial object it will be treated as such quantity:\\ Another quantity (compatible quantity, e.g. obtained as a linear combination of quantities) function:\\ Any callable object that takes two one-dimensional arrays \code{x} and \code{y} each of length $N$ and returns an array also of length $N$. The function will be evaluated at points determined by location and indices in the underlying mesh. geospatial_data:\\ Arbitrary geospatial dataset in the form of the class Geospatial_data. Mesh points are populated using least squares fitting points:\\ $N \times 2$ array of data points for use with least squares fit If points are present, an $N$ array of attribute values corresponding to each data point must be present. values:\\ If points is specified, values is an array of length N containing attribute values for each point. data_georef:\\ If points is specified, geo_reference applies to each point. filename:\\ Name of a .pts file containing data points and attributes for use with least squares. attribute_name:\\ If specified, any array matching that name will be used. from file or geospatial_data. Otherwise a default will be used. alpha:\\ Smoothing parameter to be used with least squares fits. See module least_squares for further details about alpha. Alpha will only be used with points, values or filename. Otherwise it will be ignored. %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. This function is used to associate quantities with a domain. It is very flexible and can be used with many data types: a statement of the form \code{domain.set\_quantity{name, x}} can be used to define a quantity having the name \code{name}, where the other argument \code{x} can be any of the following: \begin{itemize} \item a number \item a list of numbers \item a Numeric array \item a function (e.g. see the samples introduced in Chapter 2) \item an expression composed of other quantities and numbers, arrays, lists (for example, a linear combination of quantities) \item the name of a file from which the data can be read \item a geospatial dataset \end{itemize} Exactly one of the arguments \code{quantities} is either the name of a single quantity to be interpolated or a list of such quantity names. The resulting interpolated or a list of such quantity names. In the second case, the resulting function will return a tuple of values---one for each quantity. \code{time} is an array of monotonically increasing times and \code{quantities} is an array, or dictionary of arrays, of values to \code{quantities} is an array---or dictionary of arrays---of values to be interpolated. The parameter \code{interpolation_points} may be used to specify at which points interpolated quantities are to be computed whenever the object is called. If the default value \code{None} is used, it returns an average value. \code{None} is used, the function returns an average value. \end{classdesc} within each quantity. \end{funcdesc} \begin{funcdesc} {get_boundary_tags}{??} \end{funcdesc} \begin{funcdesc}{statistics}{???} print domain.statistics() will provide basic structural statistics about e.g.\ mesh in the form of an area histogram \end{funcdesc} \begin{funcdesc}{get_quantity}{???} Module: \code{pyvolution.domain} Module: \code{pyvolution.domain} Allow access to individual quantities and their methods \end{funcdesc} \end{funcdesc} \begin{funcdesc}{get_values}{???} Module: \code{pyvolution.quantity} Module: \code{pyvolution.quantity} Extract values for quantity as an array \end{funcdesc} \end{funcdesc} \begin{funcdesc}{get_integral}{???} Module: \code{pyvolution.quantity} Module: \code{pyvolution.quantity} Return computed integral over entire domain for this quantity \end{funcdesc} \section{Other} \begin{funcdesc}{domain.create_quantity_from_expression}{???} Handy for creating derived quantities on-the-fly. \end{funcdesc} \section{Other} \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} \end{funcdesc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{funcdesc}{sww2dem}{???} Module: \code{pyvolution.data\_manager} \end{funcdesc} Module: \code{pyvolution.data\_manager} \end{funcdesc} \begin{funcdesc}{dem2pts}{???} Module: \code{pyvolution.data_manager} \end{funcdesc} Module: \code{pyvolution.data_manager} \end{funcdesc} %\[ \chapter{Supporting Tools} This section describes a number of supporting tools, supplied with \anuga, that offer a variety of types of functionality and enhance the basic capabilities of \anuga. \section{caching} This type of caching is particularly useful for computationally intensive functions with few frequently used combinations of input arguments. Note that if the inputs or output are very large caching might not save time because if the inputs or output are very large caching may not save time because disc access may dominate the execution time. If the function definition changes after a result has been cached it will be If the function definition changes after a result has been cached, this will be detected by examining the functions \code{bytecode (co_code, co_consts, func_defualts, co_argcount)} and it will be recomputed. Options are set by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a Python dictionary \code{options} that stores settings such as the name of the directory used, the maximum func_defualts, co_argcount)} and the function will be recomputed. Options are set by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a Python dictionary \code{options}. This dictionary stores settings such as the name of the directory used, the maximum number of cached files allowed, and so on. have been changed, the function is recomputed and the results stored again. Other features include support for compression and a capability to \ldots %Other features include support for compression and a capability to \ldots {\small \begin{verbatim} result = cache(func, args, kwargs, dependencies, cachedir, verbose, compression, evaluate, test, return_filename)} compression, evaluate, test, return_filename) \end{verbatim}} \textbf{ARGUMENTS:} \begin{tabular}{ll} \code{func} & Function object (Required)\\ \code{args} & Arguments to func (Default: ())\\ \code{kwargs} & Keyword arguments to func (Default: {})  \\ \code{dependencies} & Filenames that func depends on (Default: \code{None})\\ \code{cachedir} & Directory for cache files (Default: \code{options['cachedir']})\\ \code{verbose} & Flag verbose output to stdout (Default: \code{options['verbose']})\\ \code{compression} & Flag zlib compression (Default: \code{options['compression']})\\ \code{evaluate} & Flag forced evaluation of func (Default: 0)\\ \code{test} & Flag test for cached results (Default: 0)\\ \code{clear} & Flag delete cached results (Default: 0)\\ \code{return_filename} & Flag return of cache filename (Default: 0)\\ \end{tabular} \textbf{LIMITATIONS:} \begin{itemize} \item Caching uses the apply function and will work with anything that can be pickled, so any limitation in apply or pickle extends to caching. \item A function to be cached should not depend on global variables as wrong results may occur if globals are changed after a result has been cached. \end{itemize} \section{swollen} The output generated by \anuga may be viewed by means of the visualisation tool \code{swollen}, which takes the \code{sww} file output by \anuga and creates a visual representation of the data. Examples may be seen in Figures XX and YY. To view an \code{sww} file with \code{swollen} in the Windows environment, you can simply drag the icon representing the file over an icon on the desktop for the \code{swollen} executable file (or a shortcut to it). Alternatively, you can operate \code{swollen} from the command line, in both Windows and Linux environments. On successful operation, you will see an interactive moving-picture display. You can use keys and the mouse to slow down, speed up or stop the display, change the viewing position or carry out a number of other simple operations. The main keys operating the interactive screen are:\\ \section{geo_spatial_data} This describes a class that represents arbitrary point data in UTM This describes a class that represents arbitrary point data in UTM coordinates along with named attribute values.