# Changeset 2485

Ignore:
Timestamp:
Mar 3, 2006, 4:46:24 PM (18 years ago)
Message:

Reorganised Chap 3 and provided intro material

File:
1 edited

### Legend:

Unmodified
 r2482 \end{verbatim}} This simply associates an elevation with each point $(x, y)$ of the plane.  It specifies that the bed slopes linearly in the $x$ direction, with slope $-\frac{1}{2}$,  and is constant in the $y$ direction.\\ %[screen shot?] \\ Once the function $f$ is specified, the quantity This simply associates an elevation with each point \code{(x, y)} of the plane.  It specifies that the bed slopes linearly in the \code{x} direction, with slope $-\frac{1}{2}$,  and is constant in the \code{y} direction. %[screen shot?] Once the function \code{f} is specified, the quantity \code{elevation} is assigned through the simple statement: \begin{itemize} \item Functions and Classes \item Establishing the Mesh \item Initialising the Domain \item Specifying the Quantities \item Initial Conditions \item Boundary Conditions \item Forcing Functions \item Diagnostics \item Boundary Conditions \item Initial Conditions \item Forcing Functions. \end{itemize} The listings do not give full specifications of the features, for which the reader may consult the docstrings provided in the code. They are intended merely to give the reader an idea of what each feature is and how it can be used. \section{Functions and Classes} %\indexedcodeheader{create\_mesh\_from\_regions}\label{codehdr:createmeshfromregions} %  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. %  \textbf{Arguments:} %  \begin{itemize} %    \item the bounding polygon, %do we need to spell out how a polygon is specified? %    \item a dictionary of boundary tags, for all segments of the bounding polygon, %    \emph{[not clear what the keys and values of this dictionary are]} %    \item the resolution for the bounding polygon, %    \item (optional) a filename,  \emph{[what is the file for?]} %    \item a list of 2-tuples \code{(polygon, resolution)}, specifying the interior polygons and %    their associated resolutions. %  \end{itemize} %********************************************************************************************* %\emph{\textbf{[The following is how the description of %\emph{\code{create\_mesh\_from\_regions}} would be presented using %the Python documentation system's \emph{\code{funcdesc}} environment %for describing a module-level function.]}} 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 may consult the code. The code for every function or class contains a documentation string, or `docstring', that specifies the precise syntax for its use. This appears immediately after the line introducing the code, between two sets of triple quotes. Each paragraph 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 than using pathnames, whose syntax depends on the operating system, we use the format adopted for importing the function or class for use in Python code. For example, suppose we wish to specify that the function \code{create\_mesh\_from\_regions} is in a module called \code{mesh\_interface} in a subfolder of \code{inundation} called \code{pmesh}. In Linux or Unix syntax, the pathname of the file containing the function, relative to \code{inundation}, would be \begin{center} \code{pmesh/mesh\_interface.py} \end{center} while in Windows syntax it would be \begin{center} \code{pmesh}$\backslash$\code{mesh\_interface.py} \end{center} Rather than using either of these forms, in this chapter we specify the location simply as \code{pmesh.mesh_interface}, in keeping with the usage in the Python statement for importing the function, namely: \begin{center} \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions} \end{center} \section{Mesh Generation} \begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon, mesh_geo_reference=None, minimum_triangle_angle=28.0} Module: \code{pmesh.mesh\_interface} Creates a triangular mesh based on a bounding polygon and a number of internal polygons. For each polygon the user specifies a \end{funcdesc} %********************************************************************************************* %\indexedcodeheader{pmesh\_to\_domain\_instance}  \nopagebreak % Converts a generated mesh file to a domain object. % \textbf{Arguments:} %  \begin{itemize} %    \item \code{file\_name} is the name of the mesh file to convert, including the extension %    \item \code{DomainClass} is the Class that will be returned. %    It must be a subclass of \code{Domain}, with the same interface as %    domain. In practice, it can usually be set simply to %    \code{Domain}. %    \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain. %  \end{itemize} %  \begin{itemize} %    \item Mesh file name %    \item Class name, specifying the domain class to be instantiated. %  \end{itemize} % %********************************************************************************************* %%%%%% \section{Initialising Domain} \begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False} Module: \code{pyvolution.pmesh2domain} Converts a generated mesh file to a domain object. \code{file\_name} is the name of the mesh file to convert, including the extension. \code{DomainClass} is the class to be returned, which must be a subclass of \code{Domain}, with the same interface as \code{Domain}---in practice, it can usually be set simply to \code{Domain}. \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 interface as \code{Domain}---in practice, it can usually be set simply to \code{Domain}. \end{funcdesc} %********************************************************************************************* %\indexedcodeheader{file\_function} %in util.py "High priority" %  Reads the time history of spatial data from NetCDF file and returns a callable object. %  \textbf{Arguments:} %    \code{filename} -- Name of \code{sww} or \code{tms} file (see %    Section \ref{sec:file formats} on page \pageref{sec:file formats} %    for details about file formats). %       \begin{quote} %       If the file has extension \code{sww} then it is assumed to be spatio-temporal %       or temporal and the callable object will have the form \code{f(t,x,y)} or \code{f(t)} %       depending on whether the file contains spatial data. %       If the file has extension \code{tms} then it is assumed to be temporal only %       and the callable object will have the form \code{f(t)}. %       Either form will return interpolated values based on the input file %       using the underlying \code{interpolation\_function}. %       \end{quote} %    \code{domain} -- Associated domain object %       If domain is specified, model time (\code{domain.starttime}) %       will be checked and possibly modified. %      \begin{quote} %       All times are assumed to be in UTC. %       All spatial information is assumed to be in absolute UTM coordinates. %       \end{quote} %    \code{quantities} -- the name of the quantity to be interpolated or a %                 list of quantity names. The resulting function will return %                 a tuple of values -- one for each quantity. %    \code{interpolation\_points} -- list of absolute UTM coordinates for points at %    which values are sought %    \code{use\_cache}: \code{True} means that caching of intermediate result of %               \code{Interpolation\_function} is attempted \begin{funcdesc}{file_function}{filename, %%%%%% \section{Setting Quantities} \begin{funcdesc}{set\_quantity}{name, *args, **kwargs} Module: \code{pyvolution.domain} -- see also \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. Exactly one of the arguments numeric, quantity, function, points, filename must be present. \end{funcdesc} %%% \anuga provides a number of predefined initial conditions to be used with \code{set_quantity}. \begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None, \ x0=0.0, y0=0.0, alpha=0.0, \ gravity=9.8, gamma=1.85, \ massco=1, dragco=1, frictionco=0, psi=0, \ dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, \ domain=None, verbose=False} This function returns a callable object representing an initial water displacement generated by a submarine sediment slide. The arguments include the downslope slide length, the water depth to the slide centre of mass, and the bathymetric slope. \end{funcdesc} %%% \begin{funcdesc}{file_function}{filename, domain = None, quantities = None, verbose = False, use_cache = False} Reads the time history of spatial data from NetCDF file and returns a callable object. Returns interpolated values based on the input file using the underlying \code{interpolation\_function}. \code{quantities} is either the name of a single quantity to be interpolated or a list of such quantity names. The resulting function will return a tuple of values---one for each quantity. \code{interpolation\_points} is a list of absolute UTM coordinates for points at which values are sought. \end{funcdesc} %  See Interpolation function for further documentation %\indexedcodeheader{Interpolation\_function} % Creates a callable object \code{f(t, id)} or \code{f(t,x,y)} %    interpolated from a time series defined at the vertices of %    a triangular mesh (such as those stored in \code{sww} files). %    Let $m$ be the number of vertices, $n$ the number of triangles %   and $p$ the number of time steps. %   \textbf{Mandatory Arguments:} %       \begin{tabular}{ll} %       \code{time}: & $p \times 1$ array of monotonously increasing times (Float)\\ %       \code{quantities}: & Dictionary of arrays or one array (Float). The arrays must  \\ %       & have dimensions either $p \times m$ or $m \times 1$. The resulting function \\ %        & will be time dependent in the former case and constant with respect to time \\ %        & in the latter case.\\ %       \end{tabular} %   \textbf{Optional Arguments:} %       \begin{tabular}{ll} %      \code{quantity\_names}: & List of keys into the quantities dictionary\\ %       \code{vertex\_coordinates}: & $m \times 2$ array of coordinates (Float)\\ %        \code{triangles}: & $n \times 3$ array of indices into \code{vertex\_coordinates} (Int)\\ %        \code{interpolation\_points}: & $N \times 2$ array of coordinates to be interpolated to \\ %        \code{verbose}: & Level of reporting\\ %        \end{tabular} %    The quantities returned by the callable object are specified by %    the list \code{quantities} which must contain the names of the %    quantities to be returned and also reflect the order, e.g. for %    the shallow water wave equation, one would have %    \code{quantities = ['stage', 'xmomentum', 'ymomentum']}. %    The parameter \code{interpolation_points} decides at which points interpolated %    quantities are to be computed whenever the object is called. %    If \code{None}, returns average value. Module: \code{pyvolution.util} Reads the time history of spatial data from NetCDF file and returns a callable object. Returns interpolated values based on the input file using the underlying \code{interpolation\_function}. \code{quantities} is either the name of a single quantity to be interpolated or a list of such quantity names. The resulting function will return a tuple of values---one for each quantity. \code{interpolation\_points} is a list of absolute UTM coordinates for points at which values are sought. \end{funcdesc} %%% \begin{classdesc}{Interpolation_function}{self, time, interpolation_points = None, verbose = False} Module: \code{pyvolution.least\_squares} Creates a callable object \code{f(t, id)} or \code{f(t,x,y)} interpolated from a time series defined at the vertices of a \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, returns average value. 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. \end{classdesc} \begin{funcdesc}{set\_region}{???} %%% \begin{funcdesc}{set\_region}{functions} [Low priority. Will be merged into set\_quantity] Module:\code{pyvolution.domain} \end{funcdesc} \begin{funcdesc}{set\_quantity}{???} [Pretty mature] \end{funcdesc} \begin{funcdesc}{set\_boundary}{???} [Pretty mature] \end{funcdesc} \section{Diagnostics} \begin{funcdesc}{write\_time}{???} \end{funcdesc} \begin{funcdesc}{write\_boundary\_statistics}{???} \end{funcdesc} %%%%%% \section{Boundary Conditions} be used with \code{set\_boundary}. \subsection{Predefined boundary conditions} \begin{classdesc}{Reflective_boundary}{Boundary} Reflective boundary returns same conserved quantities as those present in the neighbouring volume but reflected. This class is specific to the shallow water equation as it works with the momentum quantities assumed to be the second and third conserved quantities. \end{classdesc} \begin{classdesc}{Transmissive_boundary}{domain = None} A transmissive boundary returns the same conserved quantities as those present in the neighbouring volume. The underlying domain must be specified when the boundary is instantiated. \end{classdesc} \begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None} A Dirichlet boundary returns constant values for the conserved quantities. \end{classdesc} \begin{classdesc}{Time_boundary}{domain = None, f = None} A time-dependent boundary returns values for the conserved quantities as a function \code{f(t)} of time. The user must specify the domain to get access to the model time. \end{classdesc} \begin{classdesc}{File_boundary}{Boundary} The boundary values are obtained from a file and interpolated. The file is assumed to contain a time series and possibly also spatial information. The conserved quantities are given as a function of time. \end{classdesc} \subsection{User-defined boundary conditions} [How to roll your own] \section{Initial Conditions} \anuga provides a number of predefined initial conditions to be used with \code{set_quantity}. \begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None, \ x0=0.0, y0=0.0, alpha=0.0, \ gravity=9.8, gamma=1.85, \ massco=1, dragco=1, frictionco=0, psi=0, \ dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, \ domain=None, verbose=False} This function returns a callable object representing an initial water displacement generated by a submarine sediment slide. The arguments include the downslope slide length, the water depth to the slide centre of mass, and the bathymetric slope. \end{funcdesc} \begin{funcdesc}{set\_boundary}{boundary_map} Module: \code{pyvolution.domain} \end{funcdesc} %%% \subsection{Predefined boundary conditions} \begin{classdesc}{Reflective_boundary}{Boundary} Module: \code{pyvolution.shallow\_water} Reflective boundary returns same conserved quantities as those present in the neighbouring volume but reflected. This class is specific to the shallow water equation as it works with the momentum quantities assumed to be the second and third conserved quantities. \end{classdesc} %%% \begin{classdesc}{Transmissive_boundary}{domain = None} Module: \code{pyvolution.generic\_boundary\_conditions} A transmissive boundary returns the same conserved quantities as those present in the neighbouring volume. The underlying domain must be specified when the boundary is instantiated. \end{classdesc} %%% \begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None} Module: \code{pyvolution.generic\_boundary\_conditions} A Dirichlet boundary returns constant values for the conserved quantities. \end{classdesc} %%% \begin{classdesc}{Time_boundary}{domain = None, f = None} Module: \code{pyvolution.generic\_boundary\_conditions} A time-dependent boundary returns values for the conserved quantities as a function \code{f(t)} of time. The user must specify the domain to get access to the model time. \end{classdesc} %%% \begin{classdesc}{File_boundary}{Boundary} Module: \code{pyvolution.generic\_boundary\_conditions} The boundary values are obtained from a file and interpolated. The file is assumed to contain a time series and possibly also spatial information. The conserved quantities are given as a function of time. \end{classdesc} \subsection{User-defined boundary conditions} [How to roll your own] \section{Forcing Functions} %\end{itemize} \section{Diagnostics} \begin{funcdesc}{write\_time}{???} \end{funcdesc} \begin{funcdesc}{write\_boundary\_statistics}{???} \end{funcdesc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \bigskip \begin{center} \begin{center} \begin{tabular}{|ll|}  \hline \end{center} \end{center} \bigskip