Changeset 2559


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

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • documentation/user_manual/anuga_user_manual.tex

    r2542 r2559  
    171171The present example represents a simple scenario and does not
    172172include any forcing terms, nor is the data taken from a file as it
    173 would be in many typical cases.
     173would be in many typical cases. 
    174174
    175175The conserved quantities involved in the
    176176problem are water depth, $x$-momentum and $y$-momentum. Other quantities
    177 involved in the computation are the friction, stage (absolute height of water surface)
     177involved in the computation are the friction, stage (absolute height of water surface) 
    178178and elevation, the last two being related to
    179179the depth through the equation
    180180
    181181{\small \begin{verbatim}
    182 stage = elevation + depth
     182\code{stage} = \code{elevation} + \code{depth}
    183183\end{verbatim}}
    184184
     
    335335
    336336The stage (the height of the water surface) is related to the
    337 elevation and the depth at any time by the equation {\small
    338 \begin{verbatim}
    339     stage = elevation + depth
    340 \end{verbatim}}
     337elevation and the depth at any time by the equation \[\code{stage} =
     338\code{elevation} + \code{depth}\]
    341339
    342340For this example, we simply assign a constant value to \code{stage},
     
    347345\end{verbatim}}
    348346
    349 which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units
     347which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units 
    350348below the zero level.
    351349
     
    355353involving other quantities. Suppose, instead of setting a constant value
    356354for the stage, we wished
    357 to specify a constant value for the \emph{depth}. For such a case we
     355to specify a constant value for the \emph{depth}. For such a case we 
    358356need to specify that \code{stage} is
    359357everywhere obtained by adding that value to the value already
     
    365363\end{verbatim}}
    366364
    367 That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the
     365That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the 
    368366value of \code{elevation} already defined.
    369367
    370 The reader will probably appreciate that this capability to incorporate
     368The reader will probably appreciate that this capability to incorporate 
    371369expressions into statements using \code{set\_quantity} greatly expands
    372370its power.)
     
    405403
    406404    \item[Dirichlet boundary]Specifies a fixed value at the
    407 boundary and assigns initial values to the $x$-momentum and $y$-momentum.
     405boundary and assigns initial values to the $x$-momentum and $y$-momentum. 
    408406
    409407    \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time.
     
    423421
    424422The reader may wish to experiment by varying the choice of boundary types
    425 for one or more of the boundaries. In the case of \code{Bd} and \code{Bw},
    426 the three arguments in each case represent the
     423for one or more of the boundaries. In the case of \code{Bd} and \code{Bw}, 
     424the three arguments in each case represent the 
    427425
    428426{\small \begin{verbatim}
     
    478476
    479477
    480 \begin{figure}[hbt]
    481 
    482   \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}}
    483 
    484   \caption{Bedslope example viewed with Swollen}
    485   \label{fig:bedslopestart}
    486 \end{figure}
    487 
    488 
    489 \begin{figure}[hbt]
    490 
    491   \centerline{
    492     \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps}
    493     \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps}
    494    }
    495 
    496   \caption{Bedslope example viewed with Swollen}
    497   \label{fig:bedslope2}
    498 \end{figure}
     478%\begin{figure}[hbt]
     479
     480%  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslope_start.eps}}
     481 
     482%  \caption{Bedslope example viewed with Swollen}
     483%  \label{fig:bedslopestart}
     484%\end{figure}
     485
     486
     487%\begin{figure}[hbt]
     488
     489%  \centerline{
     490%    \includegraphics[width=75mm, height=75mm]{examples/bedslope_during.eps}
     491%    \includegraphics[width=75mm, height=75mm]{examples/bedslope_end.eps}
     492%   }   
     493 
     494%  \caption{Bedslope example viewed with Swollen}
     495%  \label{fig:bedslope2}
     496%\end{figure}
    499497
    500498
     
    513511scenario, rather than the artificial illustrative one used in
    514512\code{bedslopephysical.py}. The domain of interest surrounds the Sydney region,
    515 and predominantly covers Sydney Harbour. A hypothetical tsunami wave is
     513and predominantly covers Sydney Harbour. A hypothetical tsunami wave is 
    516514generated by a submarine mass failure situated on the edge of the
    517515continental shelf.
     
    569567area of a triangle used for triangulation---and mesh points are
    570568created inside the polygon through a random process. Figure
    571 \ref{fig:pentagon} shows a simple example of this, in which
     569\ref{fig:pentagon} shows a simple example of this, in which 
    572570the triangulation is carried out within a pentagon.
    573571
    574572
    575 \begin{figure}[hbt]
    576 
    577 
    578 
    579   \caption{Mesh points are created inside the polygon}
    580   \label{fig:pentagon}
    581 \end{figure}
     573%\begin{figure}[hbt]
     574
     575
     576 
     577%  \caption{Mesh points are created inside the polygon}
     578%  \label{fig:pentagon} 
     579%\end{figure}
    582580
    583581Boundary tags are not restricted to \code{`left'}, \code{`right'},
     
    596594resolution. See Figure \ref{fig:interior meshes}.
    597595
    598 \begin{figure}[hbt]
    599 
    600 
    601 
    602   \caption{Interior meshes with individual resolution}
    603   \label{fig:interior meshes}
    604 \end{figure}
     596%\begin{figure}[hbt]
     597
     598
     599 
     600%  \caption{Interior meshes with individual resolution}
     601%  \label{fig:interior meshes} 
     602%\end{figure}
    605603
    606604In its general form, \code{pmesh} takes for its input a bounding
     
    633631\code{meshname}.
    634632
    635 The statements
     633The statements 
    636634
    637635{\small \begin{verbatim}
     
    643641are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
    644642\code{botanybay\_polygon\_2} from \code{project.py} and assign a
    645 common resolution of 5000 to each. The statement
     643common resolution of 5000 to each. The statement 
    646644
    647645{\small \begin{verbatim}
    648646    create_mesh_from_regions(project.diffpolygonall,%
    649                          boundary_tags= {'bottom': [0],%
     647                         boundary_tags= {'bottom': [0],% 
    650648                                         'right1': [1],%
    651649                                         'right0': [2],%
     
    656654                                         'left3': [7]},%
    657655                         maximum_triangle_area=100000,%
    658                          filename=meshname,%
     656                         filename=meshname,%           
    659657                         interior_regions=interior_regions)
    660658\end{verbatim}}
    661659
    662660is then used to create the mesh, taking the bounding polygon to be the polygon
    663 \code{diffpolygonall} specified in \code{project.py}. The
    664 argument \code{boundary\_tags} assigns a dictionary, whose keys are the
    665 names of the boundary tags used for the bounding polygon---\code{`bottom'},
    666 `right0', `right1', `right2', `top', `left1', `left2' and `left3'---
     661\code{diffpolygonall} specified in \code{project.py}. The 
     662argument \code{boundary\_tags} assigns a dictionary, whose keys are the 
     663names of the boundary tags used for the bounding polygon---\code{`bottom'}, 
     664`right0', `right1', `right2', `top', `left1', `left2' and `left3'--- 
    667665and whose values identify the indices of the segments associated with each of these
    668666tags. (The value associated with each boundary tag is a one-element list.)
     
    697695taken from \code{project.py}.
    698696
    699 {\small \begin{verbatim}
     697{\small \begin{verbatim} 
    700698    domain.set_name(project.basename)%
    701699    domain.set_datadir(project.outputdir)%
     
    720718\code{slump\_tsunami}. This is similar to how we set elevation in
    721719\code{bedslopephysical.py} using a function---however, in this case the
    722 function is both more complex and more interesting.
    723 
    724 The function returns the water displacement for all \code{x}
    725 and \code{y} in the domain. The water displacement is a ?? function that depends
     720function is both more complex and more interesting. 
     721
     722The function returns the water displacement for all \code{x} 
     723and \code{y} in the domain. The water displacement is a ?? function that depends 
    726724on the characteristics of the slump (length, thickness, slope, etc), its
    727 location (origin) and the depth at that location.
     725location (origin) and the depth at that location. 
    728726
    729727
     
    741739The elevation is specified by reading data from a file:
    742740
    743 {\small \begin{verbatim}
    744     domain.set_quantity('elevation',
    745                     filename = project.combineddemname + '.pts',
    746                     use_cache = True,
    747                     verbose = True)
     741{\small \begin{verbatim}%
     742    domain.set_quantity('elevation',%
     743                    filename = project.combineddemname + '.pts',%
     744                    use_cache = True,%
     745                    verbose = True)%
    748746\end{verbatim}}
    749747
     
    772770\subsection{Boundary Conditions}
    773771
    774 Setting boundaries follows a similar pattern to the one used for
    775 \code{bedslopephysical.py}, except that in this case we need to associate a
     772Setting boundaries follows a similar pattern to the one used for 
     773\code{bedslopephysical.py}, except that in this case we need to associate a 
    776774boundary type with each of the
    777 boundary tag names introduced when we established the mesh. In place of the four
    778 boundary types introduced for \code{bedslopephysical.py}, we use the reflective
     775boundary tag names introduced when we established the mesh. In place of the four 
     776boundary types introduced for \code{bedslopephysical.py}, we use the reflective 
    779777boundary for each of the
    780778eight tagged segments:
     
    794792{\small \begin{verbatim}
    795793    import time t0 = time.time()
    796 
     794   
    797795    for t in domain.evolve(yieldstep = 120, duration = 18000):
    798796        print domain.timestepping_statistics()
    799797        print domain.boundary_statistics(tags = 'bottom')
    800 
     798   
    801799    print 'That took %.2f seconds' %(time.time()
    802800\end{verbatim}}
     
    823821The listings are intended merely to give the reader an idea of what
    824822each feature is, where to find it and how it can be used---they do
    825 not give full specifications of the features. For these the reader
     823not give full specifications. For these the reader
    826824may consult the code. The code for every function or class contains
    827825a documentation string, or `docstring', that specifies the precise
     
    873871
    874872% Translate following into layman's language
    875 Creates a triangular mesh based on a bounding polygon and a number
    876 of internal polygons. For each polygon the user specifies a
    877 resolution---that is, the maximal area of triangles in the mesh. The
    878 bounding polygon also has symbolic \code{tags} associated with it.
     873This function is used to create a triangular mesh suitable for use with
     874\anuga, within a specified region. The region is specified as the interior of a polygon
     875(the \emph{bounding polygon}). The user specifies the bounding polygon and the
     876\emph{resolution}---that is, maximal area of any triangle in the mesh. There is
     877also an option to specify a number of internal polygons within each of which a
     878separate mesh is created, generally with a smaller resolution. Additionally,
     879the user specifies a list of boundary tags, one for each edge of the bounding
     880polygon.
    879881\end{funcdesc}
    880882
     
    885887Module: \code{pyvolution.pmesh2domain}
    886888
    887 Converts a generated mesh file to a domain object.
     889Once the initial mesh file has been created, this function is applied
     890to convert it to a domain object---that is, to a member of
     891the special Python class Domain (or a subclass of Domain), which provides access to properties and
     892methods that allow quantities to be set and other operations to be carried out.
    888893
    889894\code{file\_name} is the name of the mesh file to be converted,
     
    919924\section{Setting Quantities}
    920925
    921 \begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None,
    922                    geospatial_data = None, filename = None, attribute_name = None,
     926\begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None, 
     927                   geospatial_data = None, filename = None, attribute_name = None, 
    923928                   alpha = None, location = 'vertices', indices = None, verbose = False,
    924929                   use_cache = False}
     
    926931\code{pyvolution.quantity.set_values})
    927932
    928 numeric:\\
    929 Compatible list, Numeric array (see below) or constant. If callable
    930 it will treated as a function (see below) If instance of another
    931 Quantity it will be treated as such. If geo\_spatial object it will
    932 be treated as such
    933 
    934 quantity:\\
    935 Another quantity (compatible quantity, e.g. obtained as a linear
    936 combination of quantities)
    937 
    938 function:\\
    939   Any callable object that takes two one-dimensional arrays \code{x} and
    940   \code{y}
    941   each of length $N$ and returns an array also of length $N$.
    942   The function will be evaluated at points determined by
    943   location and indices in the underlying mesh.
    944 
    945 geospatial_data:\\
    946   Arbitrary geospatial dataset in the form of the class
    947   Geospatial_data. Mesh points are populated using least squares
    948   fitting
    949 
    950 points:\\
    951   $N \times 2$ array of data points for use with least squares fit
    952   If points are present, an $N$ array of attribute
    953   values corresponding to
    954   each data point must be present.
    955 
    956 values:\\
    957   If points is specified, values is an array of length N containing
    958   attribute values for each point.
    959 
    960 data_georef:\\
    961   If points is specified, geo_reference applies to each point.
    962 
    963 filename:\\
    964   Name of a .pts file containing data points and attributes for
    965   use with least squares.
    966 
    967 attribute_name:\\
    968   If specified, any array matching that name
    969   will be used. from file or geospatial_data.
    970   Otherwise a default will be used.
    971 
    972 alpha:\\
    973   Smoothing parameter to be used with least squares fits.
    974   See module least_squares for further details about alpha.
    975   Alpha will only be used with points, values or filename.
    976   Otherwise it will be ignored.
    977 
    978 
    979 %location: Where values are to be stored.
    980 %  Permissible options are: vertices, edges, centroids
    981 %  Default is 'vertices'
    982 
    983 %  In case of location == 'centroids' the dimension values must
    984 %  be a list of a Numerical array of length N,
    985 %  N being the number of elements.
    986 %  Otherwise it must be of dimension Nx3
    987 
    988 
    989 %  The values will be stored in elements following their
    990 %  internal ordering.
    991 
    992 %  If location is not 'unique vertices' Indices is the
    993 %  set of element ids that the operation applies to.
    994 %  If location is 'unique vertices' Indices is the set
    995 %  of vertex ids that the operation applies to.
    996 
    997 %  If selected location is vertices, values for
    998 %  centroid and edges will be assigned interpolated
    999 %  values.  In any other case, only values for the
    1000 %  specified locations will be assigned and the others
    1001 %  will be left undefined.
    1002 
    1003 %verbose: True means that output to stdout is generated
    1004 
    1005 %use_cache: True means that caching of intermediate results is
    1006 %           attempted for least squares fit.
     933This function is used to associate quantities with a domain. It is very flexible and can be
     934used with many data types: a statement of the form \code{domain.set\_quantity{name, x}} can
     935be used to define a quantity having the name \code{name}, where the other argument \code{x} can
     936be any of the following:
     937
     938\begin{itemize}
     939\item a number
     940\item a list of numbers
     941\item a Numeric array
     942\item a function (e.g. see the samples introduced in Chapter 2)
     943\item an expression composed of other quantities and numbers, arrays, lists (for
     944example, a linear combination of quantities)
     945\item the name of a file from which the data can be read
     946\item a geospatial dataset
     947\end{itemize}
     948
    1007949
    1008950Exactly one of the arguments
     
    1044986
    1045987\code{quantities} is either the name of a single quantity to be
    1046 interpolated or a list of such quantity names. The resulting
     988interpolated or a list of such quantity names. In the second case, the resulting
    1047989function will return a tuple of values---one for each quantity.
    1048990
     
    10671009
    10681010\code{time} is an array of monotonically increasing times and
    1069 \code{quantities} is an array, or dictionary of arrays, of values to
     1011\code{quantities} is an array---or dictionary of arrays---of values to
    10701012be interpolated. The parameter \code{interpolation_points} may be
    10711013used to specify at which points interpolated quantities are to be
    10721014computed whenever the object is called. If the default value
    1073 \code{None} is used, it returns an average value.
     1015\code{None} is used, the function returns an average value.
    10741016\end{classdesc}
    10751017
     
    11051047within each quantity.
    11061048\end{funcdesc}
    1107 
    1108 
    11091049
    11101050\begin{funcdesc} {get_boundary_tags}{??}
     
    12031143
    12041144  \end{funcdesc}
    1205 
    1206 
    1207   \begin{funcdesc}{statistics}{???}
    1208 
    1209     print domain.statistics() will provide basic structural statistics about e.g.\ mesh in the form of an area histogram
    1210   \end{funcdesc}
    1211 
    1212 
     1145 
     1146 
    12131147  \begin{funcdesc}{get_quantity}{???}
    1214   Module: \code{pyvolution.domain}
     1148  Module: \code{pyvolution.domain} 
    12151149  Allow access to individual quantities and their methods
    1216 
    1217   \end{funcdesc}
    1218 
    1219 
     1150 
     1151  \end{funcdesc} 
     1152 
     1153 
    12201154  \begin{funcdesc}{get_values}{???}
    1221   Module: \code{pyvolution.quantity}
    1222 
     1155  Module: \code{pyvolution.quantity}   
     1156 
    12231157  Extract values for quantity as an array
    1224 
    1225   \end{funcdesc}
    1226 
    1227 
     1158 
     1159  \end{funcdesc}   
     1160 
     1161 
    12281162  \begin{funcdesc}{get_integral}{???}
    1229   Module: \code{pyvolution.quantity}
    1230 
     1163  Module: \code{pyvolution.quantity}   
     1164 
    12311165  Return computed integral over entire domain for this quantity
    1232 
    1233   \end{funcdesc}
    1234 
    1235 
    1236 \section{Other}
    1237 
    1238   \begin{funcdesc}{domain.create_quantity_from_expression}{???}
    1239 
    1240   Handy for creating derived quantities on-the-fly.
     1166 
     1167  \end{funcdesc}     
     1168 
     1169 
     1170\section{Other} 
     1171
     1172  \begin{funcdesc}{domain.create_quantity_from_expression}{???} 
     1173 
     1174  Handy for creating derived quantities on-the-fly. 
    12411175  See \code{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
    1242   \end{funcdesc}
     1176  \end{funcdesc}       
    12431177
    12441178%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     
    13351269
    13361270  \begin{funcdesc}{sww2dem}{???}
    1337   Module: \code{pyvolution.data\_manager}
    1338 
    1339 
    1340   \end{funcdesc}
    1341 
    1342 
     1271  Module: \code{pyvolution.data\_manager}   
     1272 
     1273 
     1274  \end{funcdesc}     
     1275
     1276 
    13431277  \begin{funcdesc}{dem2pts}{???}
    1344   Module: \code{pyvolution.data_manager}
    1345 
    1346 
    1347   \end{funcdesc}
     1278  Module: \code{pyvolution.data_manager}   
     1279 
     1280 
     1281  \end{funcdesc}       
    13481282
    13491283%\[
     
    14211355\chapter{Supporting Tools}
    14221356
     1357This section describes a number of supporting tools, supplied with \anuga, that offer a
     1358variety of types of functionality and enhance the basic capabilities of \anuga.
    14231359
    14241360\section{caching}
     
    14461382  This type of caching is particularly useful for computationally intensive
    14471383  functions with few frequently used combinations of input arguments. Note that
    1448   if the inputs or output are very large caching might not save time because
     1384  if the inputs or output are very large caching may not save time because
    14491385  disc access may dominate the execution time.
    14501386
    1451   If the function definition changes after a result has been cached it will be
     1387  If the function definition changes after a result has been cached, this will be
    14521388  detected by examining the functions \code{bytecode (co_code, co_consts,
    1453   func_defualts, co_argcount)} and it will be recomputed.
    1454 
    1455   Options are set
    1456   by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a
    1457   Python dictionary \code{options} that stores settings such as the name of the directory used, the maximum
     1389  func_defualts, co_argcount)} and the function will be recomputed.
     1390
     1391  Options are set by means of the function \code{set_option(key, value)},
     1392  where \code{key} is a key associated with a
     1393  Python dictionary \code{options}. This dictionary stores settings such as the name of
     1394  the directory used, the maximum
    14581395  number of cached files allowed, and so on.
    14591396
     
    14611398  have been changed, the function is recomputed and the results stored again.
    14621399
    1463   Other features include support for compression and a capability to \ldots
     1400  %Other features include support for compression and a capability to \ldots
    14641401
    14651402
     
    14681405    {\small \begin{verbatim}
    14691406    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
    1470                    compression, evaluate, test, return_filename)}
     1407                   compression, evaluate, test, return_filename)
    14711408    \end{verbatim}}
    14721409
    1473   \textbf{ARGUMENTS:}
    1474 
    1475   \begin{tabular}{ll}
    1476     \code{func} & Function object (Required)\\
    1477     \code{args} & Arguments to func (Default: ())\\
    1478     \code{kwargs} & Keyword arguments to func (Default: {})  \\
    1479     \code{dependencies} & Filenames that func depends on (Default: \code{None})\\
    1480     \code{cachedir} & Directory for cache files (Default: \code{options['cachedir']})\\
    1481     \code{verbose} & Flag verbose output to stdout
    1482                        (Default: \code{options['verbose']})\\
    1483     \code{compression} & Flag zlib compression (Default: \code{options['compression']})\\
    1484     \code{evaluate} & Flag forced evaluation of func (Default: 0)\\
    1485     \code{test} & Flag test for cached results (Default: 0)\\
    1486     \code{clear} & Flag delete cached results (Default: 0)\\
    1487     \code{return_filename} & Flag return of cache filename (Default: 0)\\
    1488   \end{tabular}
    1489 
    1490 
    1491   \textbf{LIMITATIONS:}
    1492 
    1493   \begin{itemize}
    1494    \item Caching uses the apply function and will work with anything that can be
    1495       pickled, so any limitation in apply or pickle extends to caching.
    1496 
    1497    \item A function to be cached should not depend on global variables
    1498       as wrong results may occur if globals are changed after a result has
    1499       been cached.
    1500    \end{itemize}
    1501 
    1502 
    1503 
    1504 
     1410 
    15051411\section{swollen}
    1506 
    1507 
     1412The output generated by \anuga may be viewed by means of the visualisation tool \code{swollen},
     1413which takes the \code{sww} file output by \anuga and creates a visual representation of the data.
     1414Examples may be seen in Figures XX and YY. To view an \code{sww} file with \code{swollen} in the
     1415Windows environment, you can simply drag the icon representing the file over an icon on the desktop
     1416for the \code{swollen} executable file (or a shortcut to it). Alternatively, you can operate \code{swollen}
     1417from the command line, in both Windows and Linux environments.
     1418
     1419On successful operation, you will see an interactive moving-picture display. You can use keys and the mouse
     1420to slow down, speed up or stop the display, change the viewing position or carry out a number of other
     1421simple operations.
     1422 
    15081423The main keys operating the interactive screen are:\\
    15091424
     
    15801495\section{geo_spatial_data}
    15811496
    1582 This describes a class that represents arbitrary point data in UTM
     1497This describes a class that represents arbitrary point data in UTM 
    15831498coordinates along with named attribute values.
    15841499
Note: See TracChangeset for help on using the changeset viewer.