# Changeset 5744

Ignore:
Timestamp:
Sep 7, 2008, 11:19:32 AM (14 years ago)
Message:

Had a problem with datetime package in the user manual, caused an error because of conflict with language, so added package babel (found discussion via google search "undefined \ier \ordinaldatefrench")

File:
1 edited

### Legend:

Unmodified
 r5730 \usepackage{graphicx} \usepackage[english]{babel} \usepackage{datetime} % This makes the contents more accessible from the front page of the HTML. \ifhtml \section{Audience} Readers are assumed to be familiar with the Python Programming language and Readers are assumed to be familiar with the Python Programming language and its object oriented approach. Python tutorials include Python tutorials include \url{http://docs.python.org/tut}, \url{http://www.sthurlow.com/python}, and ANUGA is unsuitable for modelling flows in areas larger than one UTM zone (6 degrees wide). \item Fluid is assumed to be inviscid - i.e.\ no kinematic viscosity included. \item Fluid is assumed to be inviscid - i.e.\ no kinematic viscosity included. \item The finite volume is a very robust and flexible numerical technique, but it is not the fastest method around. If the geometry is sufficiently \begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None, \begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None, region_tag=None} Module: \module{pmesh.mesh},  Class: \class{Mesh} Optional argument \code{default\_boundary} can be used to specify another boundary object to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}. The \code{default\_boundary} could be a simple Dirichlet condition or even another \code{File\_boundary} typically using data pertaining to another time interval. The \code{default\_boundary} could be a simple Dirichlet condition or even another \code{File\_boundary} typically using data pertaining to another time interval. \end{classdesc} Module: \module{shallow\_water.shallow\_water\_domain} This method works in the same way as \code{File\_boundary} except that it allows for the value of stage to be offset by a constant specified in the This method works in the same way as \code{File\_boundary} except that it allows for the value of stage to be offset by a constant specified in the keyword argument \code{mean\_stage}. This functionality allows for models to be run for a range of tides using the same boundary information (from .sts, .sww or .tms files). The tidal value for each run would then be specified in the keyword argument \code{mean\_stage}. If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary} behave identically. for each run would then be specified in the keyword argument \code{mean\_stage}. If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary} behave identically. Note that if the optional argument \code{default\_boundary} is specified it's stage value will be adjusted by \code{mean\_stage} just like the values obtained from the file. obtained from the file. See \code{File\_boundary} for further details. \anuga provides a number of predefined forcing functions to be used with simulations. Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list \code{domain.forcing\_terms} and have them affect the model. Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list \code{domain.forcing\_terms} and have them affect the model. Currently, predefined forcing terms are This is a general class to modify any quantity according to a given rate of change. Other specific forcing terms are based on this class but it can be used by itself as well (e.g.\ to modify momentum). The General\_forcing class takes as input: \begin{itemize} \begin{itemize} \item \code{domain}: a reference to the domain being evolved \item \code{quantity\_name}: The name of the quantity that will be affected by this forcing term \item \code{rate}: The rate at which the quantity should change. The parameter \code{rate} can be eithe a constant or a function of time. Positive values indicate increases, function of time. Positive values indicate increases, negative values indicate decreases. The parametr \code{rate} can be \code{None} at initialisation but must be specified Moreover, if the specified polygon or circle does not lie fully within the mesh boundary an Exception will be thrown. \bigskip \bigskip Example: {\scriptsize \begin{verbatim} {\scriptsize \begin{verbatim} P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]] # Square polygon xmom = General_forcing(domain, 'xmomentum', polygon=P) ymom = General_forcing(domain, 'ymomentum', polygon=P) xmom.rate = f ymom.rate = g domain.forcing_terms.append(xmom) domain.forcing_terms.append(ymom) \end{verbatim}} Here, \code{f}, \code{g} are assumed to be defined as functions of time providing a time dependent rate of change for xmomentum and ymomentum respectively. P is assumed to be polygon, specified as a list of points. \end{funcdesc} P is assumed to be polygon, specified as a list of points. \end{funcdesc} This is a general class for inflow and abstraction of water according to a given rate of change. This class will always modify the \code{stage} quantity. Inflow is based on the General_forcing class so the functionality is similar. The Inflow class takes as input: \begin{itemize} \begin{itemize} \item \code{domain}: a reference to the domain being evolved \item \code{rate}: The flow rate in $m^3/s$ at which the stage should change. The parameter \code{rate} can be eithe a constant or a function of time. Positive values indicate inflow, function of time. Positive values indicate inflow, negative values indicate outflow. Note: The specified flow will be divided by the area of the inflow region and then applied to update the stage quantity. stage quantity. \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius. \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon. \end{itemize} \bigskip \bigskip Example: {\scriptsize \begin{verbatim} {\scriptsize \begin{verbatim} hydrograph = Inflow(center=(320, 300), radius=10, rate=file_function('QPMF_Rot_Sub13.tms')) \end{verbatim}} Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for a hydrograph. \end{funcdesc} \end{funcdesc} This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon. This class will always modify the \code{stage} quantity. Rainfall is based on the General_forcing class so the functionality is similar. The Rainfall class takes as input: \begin{itemize} \begin{itemize} \item \code{domain}: a reference to the domain being evolved \item \code{rate}: Total rain rate over the specified domain. \item \code{rate}: Total rain rate over the specified domain. Note: Raingauge Data needs to reflect the time step. For example: if rain gauge is mm read every \code{dt} seconds, then the input This parameter can be either a constant or a function of time. Positive values indicate rain being added (or be used for general infiltration), function of time. Positive values indicate rain being added (or be used for general infiltration), negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction). \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius. \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon. \end{itemize} \bigskip \bigskip Example: {\scriptsize \begin{verbatim} catchmentrainfall = Rainfall(rain=file_function('Q100_2hr_Rain.tms')) {\scriptsize \begin{verbatim} catchmentrainfall = Rainfall(rain=file_function('Q100_2hr_Rain.tms')) domain.forcing_terms.append(catchmentrainfall) \end{verbatim}} Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for the rainfall. \end{funcdesc} \end{funcdesc} This is a general class for implementing flow through a culvert. This class modifies the quantities \code{stage, xmomentum, ymomentum} in areas at both ends of the culvert. The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities. The flow drection is determined on-the-fly so openings are referenced simple as opening0 and opening1 with either being able to take the role as Inflow and Outflow. The Culvert\_flow class takes as input: \begin{itemize} \begin{itemize} \item \code{domain}: a reference to the domain being evolved \item \code{label}: Short text naming the culvert \item \code{description}: Text describing it \item \code{end_point0}: Coordinates of one opening \item \code{end_point0}: Coordinates of one opening \item \code{end_point1}: Coordinates of other opening \item \code{width}: \item \code{width}: \item \code{height}: \item \code{diameter}: The user can specify different culvert routines. Hower ANUGA currently provides only one, namely the \code{boyd\_generalised\_culvert\_model} as used in the example below. \bigskip \bigskip Example: {\scriptsize \begin{verbatim} {\scriptsize \begin{verbatim} from anuga.culvert_flows.culvert_class import Culvert_flow from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model culvert1 = Culvert_flow(domain, label='Culvert No. 1', description='This culvert is a test unit 1.2m Wide by 0.75m High', end_point0=[9.0, 2.5], description='This culvert is a test unit 1.2m Wide by 0.75m High', end_point0=[9.0, 2.5], end_point1=[13.0, 2.5], width=1.20,height=0.75, culvert_routine=boyd_generalised_culvert_model, culvert_routine=boyd_generalised_culvert_model, verbose=True) culvert2 = Culvert_flow(domain, label='Culvert No. 2', description='This culvert is a circular test with d=1.2m', end_point0=[9.0, 1.5], description='This culvert is a circular test with d=1.2m', end_point0=[9.0, 1.5], end_point1=[30.0, 3.5], diameter=1.20, invert_level0=7, culvert_routine=boyd_generalised_culvert_model, culvert_routine=boyd_generalised_culvert_model, verbose=True) domain.forcing_terms.append(culvert1) domain.forcing_terms.append(culvert2) \end{verbatim}} \end{funcdesc} \end{funcdesc} \end{funcdesc} \begin{funcdesc}{set\_values}{location='vertices', indices = None} This method works the same way as \code{set\_quantity} except that it doesn't take a quantity name as the first argument. The reason to use \code{set\_values} is for example to assign values to a new quantity that has been created but which is example to assign values to a new quantity that has been created but which is not part of the domain's predefined quantities. The method \code{set\_values} is always called by \code{set\_quantity} behind the scenes. The method \code{set\_values} is always called by \code{set\_quantity} behind the scenes. \end{funcdesc} \begin{funcdesc}{get\_integral}{} Inputs: \begin{itemize} \begin{itemize} \item filename: Name of sww file containing ANUGA model output. \item polyline: Representation of desired cross section - it may contain multiple sections allowing for complex shapes. Assume absolute UTM coordinates. \end{itemize} \end{itemize} Output: \item time: All stored times in sww file \item Q: Hydrograph of total flow across given segments for all stored times. \end{itemize} \end{itemize} The normal flow is computed for each triangle intersected by the polyline and added up.  Multiple segments at different angles are specified the normal flows may partially cancel each other. Example to find flow through cross section: \begin{verbatim} \begin{verbatim} cross_section = [[x, 0], [x, width]] time, Q = get_flow_through_cross_section(filename, cross_section, verbose=False) \end{verbatim} \end{verbatim} See doc string for general function get_maximum_inundation_data for details. \end{funcdesc} Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or ERS) of a desired grid size \code{cellsize} in metres. The user can select how many the decimal places the output data can be written to using \code{number_of_decimal_places}, ERS) of a desired grid size \code{cellsize} in metres. The user can select how many the decimal places the output data can be written to using \code{number_of_decimal_places}, with the default being 3. The easting and northing values are used if the user wished to determine the output \end{funcdesc} \begin{funcdesc}{urs2sts}{basename_in, basename_out=None, weights=None, verbose=False, origin=None,mean_stage=0.0, \begin{funcdesc}{urs2sts}{basename_in, basename_out=None, weights=None, verbose=False, origin=None,mean_stage=0.0, zscale=1.0, ordering_filename=None} Module: \module{shallow\_water.data\_manager} As demonstrated in our papers, \cite{ZR1999,nielsen2005} these equations and their implementation in \anuga provide a reliable model of general flows associated with inundation such as dam breaks equations and their implementation in \anuga provide a reliable model of general flows associated with inundation such as dam breaks and tsunamis. observed CFL condition: \Delta t = \min_{k,i=[0,1,2]}  \min \left( \frac{r_k}{v_{k,i}}, \frac{r_{n_{k,i}}}{v_{k,i}} \right ) \label{eq:CFL condition} where $r_k$ is the radius of the $k$'th triangle and $v_{k,i}$ is the maximal velocity across edge joining triangle $k$ and it's $i$'th neighbour, triangle $n_{k,i}$, as calculated by the numerical flux function using the central upwind scheme of \cite{KurNP2001}. The symbol $r_{n_{k,i}}$  denotes the radius of the $i$'th neighbour of triangle $k$. The radii are calculated as radii of the inscribed circles where $r_k$ is the radius of the $k$'th triangle and $v_{k,i}$ is the maximal velocity across edge joining triangle $k$ and it's $i$'th neighbour, triangle $n_{k,i}$, as calculated by the numerical flux function using the central upwind scheme of \cite{KurNP2001}. The symbol $r_{n_{k,i}}$  denotes the radius of the $i$'th neighbour of triangle $k$. The radii are calculated as radii of the inscribed circles of each triangle. is either a constant value or a function of coordinates \code{x} and \code{y}, specifying the return value for a point inside \code{P}. The optional parameter \code{default} may be used to specify a value optional parameter \code{default} may be used to specify a value (or a function) for a point not lying inside any of the specified polygons. When a %FIXME (Howard): CAN x, y BE VECTORS? The optional parameter geo\_reference refers to the status of points that are passed into the function. Typically they will be relative to that are passed into the function. Typically they will be relative to some origin. In ANUGA, a typical call will take the form: {\small \begin{verbatim} set_quantity('elevation', set_quantity('elevation', Polygon_function([(P1, v1), (P2, v2)], default=v3, geo_reference=domain.geo_reference)) \end{verbatim}} \end{classdesc} \begin{funcdesc}{plot\_polygons}{polygons, style, figname, verbose = False} Module: \code{utilities.polygon} Plots each polygon contained in input polygon list, e.g. \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]} first one. Note that the Geospatial\_data object currently reads entire datasets into memory i.e.\ no memomry blocking takes place. Note that the Geospatial\_data object currently reads entire datasets into memory i.e.\ no memomry blocking takes place. For this we refer to the set\_quantity method which will read .pts and .csv files into \anuga using memory blocking allowing large files to be used. \end{classdesc} smaller the original and the second is the remainder. The two new object are disjoin set of each other. Points of the two new geospatial_data object are selected RANDOMLY. Points of the two new geospatial_data object are selected RANDOMLY. Input - the (\code{factor}) which to split the object, if 0.1 then 10% of the together object will be returned Output - two geospatial_data objects that are disjoint sets of the original \end{methoddesc} north_boundary=None, south_boundary=None, east_boundary=None, west_boundary=None, plot_name='all_alphas', split_factor=0.1, seed_num=None, cache=False, verbose=False} Removes a small random sample of points from 'data_file'. Creates models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates Removes a small random sample of points from 'data_file'. Creates models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates the predicted value to the previously removed point data. Returns the alpha value which has the smallest covariance. data_file: must not contain points outside the boundaries defined and it either a pts, txt or csv file. and it either a pts, txt or csv file. alpha_list: the alpha values to test in a single list mesh_file: name of the created mesh file or if passed in will read it. mesh_file: name of the created mesh file or if passed in will read it. NOTE, if there is a mesh file mesh_resolution, north_boundary, south... etc will be ignored. mesh_resolution: the maximum area size for a triangle north_boundary... west_boundary: the value of the boundary plot_name: the name for the plot contain the results seed_num: the seed to the random number generator USAGE: convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName, convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName, alpha_list=[0.0001, 0.01, 1], mesh_file=None, seed_num=100000, verbose=False) OUTPUT: returns the minumum normalised covalance calculate AND the OUTPUT: returns the minumum normalised covalance calculate AND the alpha that created it. PLUS writes a plot of the results NOTE: code will not work if the data_file extent is greater than the boundary_polygon or any of the boundaries, eg north_boundary...west_boundary \section{\module{shallow\_water}} 2D triangular domains for finite-volume computations of the shallow water wave equation. computations of the shallow water wave equation. This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water Wave Equation data is often sparse, or non-existent. Note that onshore DEMS can be much finer as the underlying datasets from which they are created often contain several datapoints per m$^2$. It may be necessary to thin out the data so that it can be imported without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?). Note that onshore DEMS can be much finer as the underlying datasets from which they are created often contain several datapoints per m$^2$. It may be necessary to thin out the data so that it can be imported without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?). \subsubsection{How do I extract elevation and other quantities from a SWW file?} The function \code{sww2dem} can extract any quantity, or expression using quantities, from a SWW file as used in The function \code{sww2dem} can extract any quantity, or expression using quantities, from a SWW file as used in the Cairns example described earlier. This function is used in \code{ExportResults.py} in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation can be exported from the input sww file. Note that depth, absolute momentum and speed are expressions and stage and elevation are quantities. In addition to extracting a particular quantity or expression, the user can define a region to extract these values by defining the minimum and maximum of both the easting and northing coordinates. The function also calls for a grid resolution, or cell size, to extract these values at. It is recommended to align this resolution with the mesh resolution in the desired region and to not also calls for a grid resolution, or cell size, to extract these values at. It is recommended to align this resolution with the mesh resolution in the desired region and to not generate a fine grid where the model output cannot support that resolution. \chapter{Glossary}