source: documentation/user_manual/anuga_user_manual.tex @ 2434

Last change on this file since 2434 was 2434, checked in by howard, 19 years ago

New material added for Ch 3 and Appendix. A number of other minor changes.

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 35.2 KB
RevLine 
[2329]1% Complete documentation on the extended LaTeX markup used for Python
2% documentation is available in ``Documenting Python'', which is part
3% of the standard documentation for Python.  It may be found online
4% at:
5%
6%     http://www.python.org/doc/current/doc/doc.html
7
8
[2384]9\input{definitions}
10
[2422]11
[2329]12\documentclass{manual}
[2274]13
[2384]14\title{\anuga User Manual}
[2284]15\author{Howard Silcock, Ole Nielsen, Duncan Gray, Jane Sexton}
[2274]16
[2329]17% Please at least include a long-lived email address;
18% the rest is at your discretion.
19\authoraddress{Geoscience Australia \\
20  Email: \email{ole.nielsen@ga.gov.au}
21}
22
[2377]23%Draft date
24\date{\today}                   % update before release!
[2422]25                % Use an explicit date so that reformatting
26                % doesn't cause a new date to be used.  Setting
27                % the date to \today can be used during draft
28                % stages to make it easier to handle versions.
[2329]29
[2422]30\release{1.0}           % release version; this is used to define the
31                % \version macro
[2329]32
[2422]33\makeindex          % tell \index to actually write the .idx file
34%\makemodindex          % If this contains a lot of module sections.
[2329]35
36
37
[2274]38\begin{document}
39\maketitle
40
[2329]41% This makes the contents more accessible from the front page of the HTML.
42\ifhtml
43\chapter*{Front Matter\label{front}}
44\fi
[2285]45
46%Subversion keywords:
47%
[2387]48%$LastChangedDate: 2006-02-22 03:12:54 +0000 (Wed, 22 Feb 2006) $
49%$LastChangedRevision: 2434 $
50%$LastChangedBy: howard $
[2285]51
[2383]52\input{copyright}
[2274]53
[2383]54
[2329]55\begin{abstract}
56
57\noindent
[2384]58\anuga\index{AnuGA} is a hydrodynamic modelling tool that
[2358]59allows users to model realistic flow problems in complex
60geometries. Examples include dam breaks or the effects of natural
61hazards such as riverine flooding, storm surges and tsunami.
[2274]62
[2283]63The user must specify a study area represented by a mesh of triangular
64cells, the topography and bathymetry, frictional resistance, initial
[2422]65values for water level (called \emph{stage}\index{stage} within \anuga),
[2329]66boundary
[2283]67conditions and forces such as windstress or pressure gradients if
68applicable.
69
[2384]70\anuga tracks the evolution of water depth and horizontal momentum
[2283]71within each cell over time by solving the shallow water wave equation
72governing equation using a finite-volume method.
73
[2384]74\anuga cannot model details of breaking waves, flow under ceilings such
[2283]75as pipes, turbulence and vortices, vertical convection or viscous
76flows.
77
[2384]78\anuga also incorporates a mesh generator, called \code{pmesh}, that
[2283]79allows the user to set up the geometry of the problem interactively as
80well as tools for interpolation and surface fitting, and a number of
81auxiliary tools for visualising and interrogating the model output.
82
[2384]83Most \anuga components are written in the object-oriented programming
[2434]84language Python and most users will interact with \anuga by writing
[2384]85small Python programs based on the \anuga library
[2283]86functions. Computationally intensive components are written for
87efficiency in C routines working directly with the Numerical Python
88structures.
89
90
[2329]91\end{abstract}
[2283]92
[2329]93\tableofcontents
[2283]94
[2274]95
[2329]96\chapter{Introduction}
97
98
99\section{Purpose}
100
[2274]101The purpose of this user manual is to introduce the new user to
102the software, describe what it can do and give step-by-step
103instructions for setting up, configuring and running the software.
104
[2329]105\section{Scope}
[2274]106
107This manual covers only what is needed to operate the software
108after installation. It does not includes instructions for
109installing the software or detailed API documentation, both of
110which will be covered in separate publications.
111
[2329]112\section{Audience}
[2274]113
[2283]114Readers are assumed to be familiar with the operating environment
[2274]115and have a general understanding of the problem background, as
116well as enough programming experience to adapt the code to
117different requirements, as described in this manual,  and to
118understand the basic terminology of object-oriented programming.
119
[2329]120\section{Structure of This Manual}
[2274]121
122This manual is structured as follows:
123
124\begin{itemize}
[2384]125  \item Background (What \anuga does)
[2283]126  \item A \emph{Getting Started} section
[2434]127  \item A detailed description of the public interface
128  \item \anuga 's overall architecture, components and file formats
129  \item Assumptions
[2274]130\end{itemize}
131
132
[2329]133\pagebreak
134\chapter{Getting Started}
[2274]135
136This section is designed to assist the reader to get started with
[2434]137\anuga by working through simple examples. Two examples are discussed;
138the first is a simple but artificial example that is useful to illustrate
139many of the ideas, and the second is a real-life example.
140
141\section{First Example: Overview}
142
143What follows
[2274]144is a discussion of the structure and operation of the file
[2358]145\code{bedslope.py}, with just enough detail to allow the reader
[2274]146to appreciate what's involved in setting up a scenario like the
147one it depicts.
148
149This example carries out the solution of the shallow-water wave
150equation in the simple case of a configuration comprising a flat
151bed, sloping at a fixed angle in one direction and having a
[2283]152constant depth across each line in the perpendicular direction.
153
[2274]154The example demonstrates many of the basic ideas involved in
155setting up a more complex scenario. In the general case the user
156specifies the geometry (bathymetry and topography), the initial
157water level, boundary conditions such as tide, and any forcing
158terms that may drive the system such as wind stress or atmospheric
159pressure gradients. Frictional resistance from the different
160terrains in the model is represented by predefined forcing
[2283]161terms. The boundary is reflective on three sides and a time dependent wave on one side.
162
[2274]163The present example, as it represents a simple scenario, does not
164include any forcing term, nor is the data taken from a file as it
165would be in many typical cases. The quantities involved in the
166present problem are:
167\begin{itemize}
[2329]168   \item elevation\index{elevation}
169   \item friction\index{friction}
170   \item depth\index{depth}
171   \item stage\index{stage}
[2274]172\end{itemize}
173
174%\emph{[More details of the problem background]}
175
[2329]176\section{Outline of the Program}
[2274]177
[2358]178In outline, \code{bedslope.py} performs the following steps:
[2274]179
180\begin{enumerate}
181
182   \item Sets up a triangular mesh.
183
184   \item Sets certain parameters governing the mode of
[2283]185operation of the model-specifying, for instance, where to store the model output.
[2274]186
187   \item Inputs various quantities describing physical measurements, such
[2283]188as the elevation, to be specified at each mesh point (vertex).
[2274]189
190   \item Sets up the boundary conditions.
191
192   \item Carries out the evolution of the model through a series of time
193steps and outputs the results, providing a results file that can
194be visualised.
195
196\end{enumerate}
197
[2329]198\section{The Code}
[2274]199
[2422]200%FIXME: we are using the \code function here.
[2434]201%This should be used wherever possible
[2274]202For reference we include below the complete code listing for
[2329]203\code{bedslope.py}. Subsequent paragraphs provide a `commentary'
[2283]204that describes each step of the program and explains it significance.
[2274]205
[2283]206
[2277]207{\scriptsize \begin{verbatim}
208from pyvolution.mesh_factory import rectangular
[2274]209from pyvolution.shallow_water import Domain, Reflective_boundary,
210     Dirichlet_boundary, Time_boundary, Transmissive_boundary
211
212#Create basic mesh
213points, vertices, boundary = rectangular(10,10)
214
[2277]215#Create shallow water domain
216domain = Domain(points, vertices,boundary)
[2289]217domain.set_name('bedslope')
[2274]218
[2289]219
[2274]220#######################
221# Initial conditions
222def f(x,y):
223    return -x/2
224
225domain.set_quantity('elevation', f)
226domain.set_quantity('friction', 0.1)
227
228h = 0.05  # Constant depth
229domain.set_quantity('stage', expression = 'elevation + %f' %h)
230
231
[2277]232# Boundary conditions
233from math import sin, pi
234Br = Reflective_boundary(domain)
[2422]235Bt = Transmissive_boundary(domain)
[2277]236Bd = Dirichlet_boundary([0.2,0.,0.])
[2274]237
238Bw = Time_boundary(domain=domain,
239                   f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0])
240
241
[2277]242domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br})
[2274]243
244
[2277]245######################
[2274]246#Evolution
247
248domain.check_integrity()
249
250for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0):
251    domain.write_time()
252
253
[2277]254\end{verbatim}}
[2274]255
256
[2329]257\section{Establishing the Mesh}
[2274]258
259The first task is to set up the triangular mesh to be used for the
260scenario. This is carried out through the statement:
261
[2277]262{\small \begin{verbatim}
[2422]263    points, vertices, boundary = rectangular(10, 10)
[2277]264\end{verbatim}}
[2274]265
[2358]266The function \code{rectangular} is imported from a module
[2384]267\code{mesh\_factory} defined elsewhere. \anuga also
[2274]268contains several other schemes that can be used for setting up
269meshes, but we shall not discuss these now.) The above assignment
270sets up a $10 \times 10$ rectangular mesh, triangulated in a
271specific way. In general, the assignment
272
[2277]273{\small \begin{verbatim}
[2274]274    points, vertices, boundary = rectangular(m, n)
[2277]275\end{verbatim}}
[2274]276
277returns:
278
279\begin{itemize}
280
[2358]281   \item a list \code{points} of length $N$, where $N = (m + 1)(n + 1)$,
[2274]282comprising the coordinates $(x, y)$ of each of the $N$ mesh
283points,
284
[2358]285   \item a list \code{vertices} of length $2mn$ (each entry specifies the three
[2274]286vertices of one of the triangles used in the triangulation) , and
287
[2358]288   \item a dictionary \code{boundary}, used to tag the triangle edges on
[2274]289the boundaries. Each key corresponds to a triangle edge on one of
[2358]290the four boundaries and its value is one of \code{`left'},
291\code{`right'}, \code{`top'} and \code{`bottom'}, indicating
[2274]292which boundary the edge in question belongs to.
293
294\end{itemize}
295
296
[2434]297\section{Initialising the Domain}
[2274]298
299These variables are then used to set up a data structure
[2358]300\code{domain}, through the assignment:
[2274]301
[2277]302{\small \begin{verbatim}
[2274]303    domain = Domain(points, vertices, boundary)
[2277]304\end{verbatim}}
[2274]305
[2358]306This uses a Python class \code{Domain}, imported from
307\code{shallow\_water}, which is an extension of a more generic
308class of the same name in the module \code{domain}, and inherits
[2274]309some methods from the generic class but has others specific to the
[2422]310shallow-water scenarios in which it is used. Specific options for domain
[2434]311are set at this point. One of them is to set the basename for the output file:
[2274]312
[2277]313{\scriptsize \begin{verbatim}
[2289]314    domain.set_name('bedslope')
[2277]315\end{verbatim}}
[2274]316
317
[2329]318\section{Specifying the Quantities}
[2274]319
[2283]320The next task is to specify a number of quantities that we wish to set
[2358]321for each mesh point. The class \code{Domain} has a method
322\code{set\_quantity}, used to specify these quantities. It is a
[2283]323particularly flexible method that allows the user to set quantities in
324a variety of ways---using constants, functions, numeric arrays or
325expressions involving other quantities, arbitrary data points with
326associated values, all of which can be passed as arguments. All
[2358]327quantities can be initialised using \code{set\_quantity}. For
328conserved quantities (\code{stage, xmomentum, ymomentum}) this is
[2283]329called the \emph{initial condition}, for other quantities that aren't
330updated by the equation, the same interface is used to assign their
331values. The code in the present example demonstrates a number of forms
[2358]332in which we can invoke \code{set\_quantity}.
[2274]333
334
[2329]335\subsection{Elevation}
[2274]336
337The elevation is set using a function, defined through the
338statements below, which is specific to this example and specifies
339a particularly simple initial configuration for demonstration
340purposes:
341
[2277]342{\small \begin{verbatim}
[2274]343    def f(x,y):
344        return -x/2
[2277]345\end{verbatim}}
[2274]346
347This simply associates an elevation with each point $(x, y)$ of
348the plane.  It specifies that the bed slopes linearly in the $x$
349direction, with slope $-\frac{1}{2}$,  and is constant in the $y$
350direction.\\ %[screen shot?]
351\\
352Once the function $f$ is specified, the quantity
[2358]353\code{elevation} is assigned through the simple statement:
[2274]354
[2277]355{\small \begin{verbatim}
[2274]356    domain.set_quantity('elevation', f)
[2277]357\end{verbatim}}
[2274]358
359
[2329]360\subsection{Friction}
[2274]361
362The assignment of the friction quantity demonstrates another way
[2358]363we can use \code{set\_quantity} to set quantities---namely,
[2274]364assign them to a constant numerical value:
365
[2277]366{\small \begin{verbatim}
[2274]367    domain.set_quantity('friction', 0.1)
[2277]368\end{verbatim}}
[2274]369
370This just specifies that the Manning friction coefficient is set
371to 0.1 at every mesh point.
372
[2329]373\subsection{Depth}
[2274]374
375Assigning depth illustrates a more complex way to use
[2358]376\code{set\_quantity}, introducing an expression involving other
[2274]377quantities:
378
[2277]379{\small \begin{verbatim}
[2274]380    h = 0.05 \# Constant depth
381    domain.set_quantity('stage', expression = 'elevation + %f' %h)
[2277]382\end{verbatim}}
[2274]383
[2358]384Here the quantity \code{stage} is defined by taking the quantity
[2274]385elevation already defined and adding a constant value $h = 0.05$
386to it everywhere. This expresses the fact that the water depth is
387everywhere constant, so the surface is a constant height above the
388elevation of the bed.
389
[2329]390\subsection{Boundary Conditions}
[2274]391
392The boundary conditions are specified as follows:
393
[2277]394{\small \begin{verbatim}
[2274]395    Br = Reflective_boundary(domain)
396
397    Bt = Transmissive_boundary(domain)
398
399    Bd = Dirichlet_boundary([0.2,0.,0.])
400
401    Bw = Time_boundary(domain=domain,
402                f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0])
[2277]403\end{verbatim}}
[2274]404
405The effect of these statements is to set up four alternative
406boundary conditions and store them in variables that can be
407assigned as needed. Each boundary condition specifies the
408behaviour at a boundary in terms of the behaviour in neighbouring
409elements. The boundary conditions may be briefly described as
410follows:
411
412\begin{description}
[2358]413    \item[Reflective boundary] Returns same \code{stage} as
[2283]414    as present in its neighbour volume but momentum vector reversed 180 degrees (reflected).
415    Specific to the shallow water equation as it works with the
416    momentum quantities assumed to be the second and third conserved
417    quantities.
[2434]418   
[2274]419    \item[Transmissive boundary]Returns same conserved quantities as
420    those present in its neighbour volume.
[2434]421   
[2274]422    \item[Dirichlet boundary]Specifies a fixed value at the
423boundary.
[2434]424
[2274]425    \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time.
426\end{description}
427
428Once the four boundary types have been specified through the
429statements above, they can be applied through a statement of the
430form
431
[2277]432{\small \begin{verbatim}
433    domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br})
434\end{verbatim}}
[2274]435
436This statement stipulates that, in the current example, the left
437boundary is fixed, with an elevation of 0.2, while the other
438boundaries are all reflective.
439
440
[2329]441\section{Evolution}
[2274]442
443The final statement \nopagebreak[3]
[2277]444{\small \begin{verbatim}
[2274]445    for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0):
446        domain.write_time()
[2277]447\end{verbatim}}
[2274]448
449is the key step that causes the configuration of the domain to
450`evolve' in accordance with the model embodied in the code, over a
[2358]451series of steps indicated by the values of \code{yieldstep} and
452\code{finaltime}, which can be altered as required.
[2434]453The value of \code{yieldstep} controls the time interval between successive model outputs.
454Behind the scenes more time steps are generally taken.
[2274]455
456
[2329]457\section{Output}
[2274]458
459%Give details here of the form of the output and explain how it can
460%be used with swollen. Include screen shots.//
461
[2358]462The output is a NetCDF file with the extension \code{.sww}. It
[2274]463contains stage and momentum information and can be used with the
[2358]464\code{swollen} visualisation package to generate a visual display.
[2274]465
466
[2329]467\section{How to Run the Code}
[2274]468
469The code can be run in various ways:
470
471\begin{itemize}
[2357]472\item{from a Windows command line} as in \code{python bedslope.py}
[2274]473
474\item{within the Python IDLE environment}
475
476\item{within emacs}
477
[2357]478\item{from a Linux command line} as in \code{python bedslope.py}
[2274]479\end{itemize}
480
481
[2434]482\section{An Example with Real Data}
[2274]483
[2358]484The following discussion builds on the \code{bedslope.py} example and
485shows how, using the same basic outline, we can incorporate many more
486complex features.
[2274]487
[2357]488The chief difference is in the method used to create the mesh. Instead of imposing a mesh
[2422]489structure on a rectangular grid, the technique used for this example involves building
490mesh structures inside polygons.
[2357]491
[2358]492In its simplest form, the mesh is created within a single polygon
493whose vertices are at geographical locations specified by the user.  A
494triangular mesh is created using points inside the polygon selected
495through a random process, the user specifying the
496\emph{resolution}---that is, the maximal area of a triangle used for
497triangulation.
[2357]498
[2358]499Figure XXX shows a simple example, in which the triangulation is
500carried out within a pentagon. Instead of using the four tags
501\code{`left'}, \code{`right'}, \code{`bottom'} and
502\code{`top'} to distinguish boundary elements, the user can define
503tags appropriate to the configuration being modelled.
[2357]504
[2358]505While this offers more flexibility than the rectangular grid, it
506doesn't provide a way to adapt to geographic or other features in the
507landscape, for which we may require to vary the resolution. We achieve
508more flexibility by extending this method, allowing the user to
509specify a number of interior polygons which are triangulated
510separately, possibly using different resolutions.  See Figure XXX.
[2357]511
[2358]512
[2434]513\chapter{\anuga Public Interface}
[2358]514
[2434]515This chapter lists the functions and classes available at the public interface.
[2358]516
[2434]517\section{Functions and Classes}
[2358]518
[2434]519\begin{itemize} 
[2358]520
[2434]521  \item \indexedcode{create_mesh_from_region}: Creates a triangular mesh based on a bounding polygon and
522  a number of internal polygons. For each polygon the user specifies a resolution---that is, the maximal area
523  of triangles in the mesh. The bounding polygon also has symbolic \code{tags} associated with it.   
524 
525  \textbf{Arguments:} 
526 
527  \begin{itemize}
528 
529  \item the bounding polygon, %do we need to spell out how a polygon is specified?
530 
531  \item a dictionary of boundary tags, for all segments of the bounding polygon,
532  \emph{[not clear what the keys and values of this dictionary are]}
533 
534  \item the resolution for the bounding polygon,
535 
536  \item (optional) a filename,  \emph{[what is the file for?]}
537 
538  \item a list of 2-tuples \code{(polygon, resolution)}, specifying the interior polygons and their associated
539  resolutions.
540 
541  \end{itemize}
542 
543 
544 
545  \item \indexedcode{pmesh_to_domain_instance}: Converts a generated mesh file to a domain object.
546 
547  \textbf{Arguments:} 
548 
549  \begin{itemize}
550 
551  \item \code{file_name} is the name of the mesh file to convert, including the extension
[2358]552
[2434]553  \item \code{DomainClass} is the Class that will be returned.
554    It must be a subclass of \code{Domain}, with the same interface as domain.
[2364]555
[2434]556  \item \code{use_cache}: \code{True} means that caching is attempted for the computed domain.
557   
558  \end{itemize}
559 
560 
561  \begin{itemize}
562  \item Mesh file name
563 
564  \item Class name, specifying the domain class to be instantiated.
565  \end{itemize}
566 
567  \item \indexedcode{file_function}: %in util.py "High priority"
568  Reads the time history of spatial data from NetCDF file and returns a callable object.
[2422]569
[2434]570  \textbf{Input variables:}
571   
572    \code{filename} - Name of \code{sww} or \code{tms} file
573       
574       \begin{quote}
575       If the file has extension \code{sww} then it is assumed to be spatio-temporal
576       or temporal and the callable object will have the form \code{f(t,x,y)} or \code{f(t)}
577       depending on whether the file contains spatial data.
578
579       If the file has extension \code{tms} then it is assumed to be temporal only
580       and the callable object will have the form \code{f(t)}.
581
582       Either form will return interpolated values based on the input file
583       using the underlying \code{interpolation_function}.
584       \end{quote}
585
586    \code{domain} - Associated domain object   
587       If domain is specified, model time (\code{domain.starttime})
588       will be checked and possibly modified.
589   
590       \begin{quote}
591       All times are assumed to be in UTC.
592       
593       All spatial information is assumed to be in absolute UTM coordinates.
594       \end{quote}
595
596    \code{quantities} - the name of the quantity to be interpolated or a
597                 list of quantity names. The resulting function will return
598                 a tuple of values -- one for each quantity. 
599
600    \code{interpolation_points} - list of absolute UTM coordinates for points at
601    which values are sought
602   
603    \code{use_cache}: \code{True} means that caching of intermediate result of
604               \code{Interpolation_function} is attempted
605
606   
607  %  See Interpolation function for further documentation
608 
609  \item \indexedcode{Interpolation_function} - creates a callable object \code{f(t, id)} or \code{f(t,x,y)}
610    which is interpolated from time series defined at vertices of
611    triangular mesh (such as those stored in \code{sww} files).
612
613    Let $m$ be the number of vertices, $n$ the number of triangles
614    and $p$ the number of time steps.
615
616    \textbf{Mandatory input:}
617   
618        \begin{tabular}{ll}
619        \code{time}: & $p \times 1$ array of monotonously increasing times (Float)\\
620       
621        \code{quantities}: & Dictionary of arrays or one array (Float). The arrays must  \\
622        & have dimensions either $p \times m$ or $m \times 1$. The resulting function \\
623        & will be time dependent in the former case and constant with respect to time \\
624        & in the latter case.\\
625        \end{tabular}
626       
627       
628    \textbf{Optional input:}
629   
630        \begin{tabular}{ll}
631        \code{quantity_names}: & List of keys into the quantities dictionary\\
632       
633        \code{vertex_coordinates}: & $m \times 2$ array of coordinates (Float)\\
634       
635        \code{triangles}: & $n \times 3$ array of indices into \code{vertex_coordinates} (Int)\\
636       
637        \code{interpolation_points}: & $N \times 2$ array of coordinates to be interpolated to \\
638       
639        \code{verbose}: & Level of reporting\\
640        \end{tabular}
641   
642    The quantities returned by the callable object are specified by
643    the list quantities which must contain the names of the
644    quantities to be returned and also reflect the order, e.g. for
645    the shallow water wave equation, one would have
646    \code{quantities = ['stage', 'xmomentum', 'ymomentum']}.
647
648    The parameter \code{interpolation_points} decides at which points interpolated
649    quantities are to be computed whenever the object is called.
650    If \code{None}, returns average value.
651   
652
653  \item \indexedcode{set_region} ``Low priority. Will be merged into set\_quantity''
654   
[2358]655  \item \indexedcode{set_quantity} ``Pretty mature''
[2434]656 
[2358]657  \item \indexedcode{set_boundary} ``Pretty mature''
[2434]658 
[2358]659
[2434]660\end{itemize} 
[2358]661
[2434]662\section{Diagnostics}
[2422]663\begin{itemize}
[2358]664  \item \indexedcode{write_time}
665  \item \indexedcode{write_boundary_statistics}
666
667
[2422]668\end{itemize}
[2358]669
[2422]670
[2434]671\section{Boundary Conditions}
[2358]672
[2434]673\anuga provides a large number of predefined boundary conditions to be used with
[2358]674\code{set_boundary}
675
676What do they do
677How are they used
678
[2422]679\begin{itemize}
[2358]680  \item \indexedcode{Reflective_boundary}
681  function, arguments
[2422]682
[2358]683  \item \indexedcode{Transmissive_boundary}
[2422]684  function, arguments, CAVEATS
685
[2358]686  \item \indexedcode{Dirichlet_boundary}
[2422]687
688  \item \indexedcode{Time_boundary}
689
690  \item \indexedcode{File_boundary}
[2364]691  Based on File\_function
[2422]692
693  \item \indexedcode{}
694
695  \item \indexedcode{}
696
697
[2358]698  \item \indexedcode{User defined boundary conditions.}
[2422]699  How to roll your own
[2358]700
701
702
[2422]703\end{itemize}
[2358]704
[2422]705
706
[2434]707\section{Initial Conditions}
[2358]708
[2434]709\anuga provides a number of predefined initial conditions to be used with
[2358]710\code{set_quantity}.
711
[2422]712\begin{itemize}
[2358]713
714
715  \item \indexedcode{tsunami_slump}
716  function, arguments
[2422]717
[2358]718  \item \indexedcode{}
719
[2422]720\end{itemize}
[2358]721
722
[2434]723\section{Forcing Functions}
[2358]724
[2434]725\anuga provides a number of predefined forcing functions to be used with .....
[2358]726
[2422]727\begin{itemize}
[2358]728
729
730  \item \indexedcode{}
731  function, arguments
[2422]732
[2358]733  \item \indexedcode{}
734
[2422]735\end{itemize}
[2358]736
737
738
[2370]739
[2434]740\chapter{\anuga System Architecture}
[2370]741
[2413]742From pyvolution/documentation
[2370]743
[2434]744\section{File Formats}
[2370]745
[2434]746\chapter{Basic \anuga Assumptions}
[2370]747
[2413]748(From pyvolution/documentation)
[2370]749
[2413]750
751Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
752If one wished to recreate scenarios prior to that date it must be done
753using some relative time (e.g. 0).
754
755
756All spatial data relates to the WGS84 datum (or GDA94) and has been
757projected into UTM with false easting of 500000 and false northing of
7581000000 on the southern hemisphere (0 on the northern).
759
760It is assumed that all computations take place within one UTM zone.
761
762DEMs, meshes and boundary conditions can have different origins within
[2422]763one UTM zone. However, the computation will use that of the mesh for
[2413]764numerical stability.
765
766
767%OLD
768%The dataflow is: (See data_manager.py and from scenarios)
769%
770%
771%Simulation scenarios
772%--------------------%
773%%
774%
775%Sub directories contain scrips and derived files for each simulation.
776%The directory ../source_data contains large source files such as
777%DEMs provided externally as well as MOST tsunami simulations to be used
778%as boundary conditions.
779%
780%Manual steps are:
781%  Creation of DEMs from argcview (.asc + .prj)
782%  Creation of mesh from pmesh (.tsh)
783%  Creation of tsunami simulations from MOST (.nc)
784%%
785%
786%Typical scripted steps are%
787%
788%  prepare_dem.py:  Convert asc and prj files supplied by arcview to
789%                   native dem and pts formats%
790%
791%  prepare_pts.py: Convert netcdf output from MOST to an sww file suitable
792%                  as boundary condition%
793%
794%  prepare_mesh.py: Merge DEM (pts) and mesh (tsh) using least squares
795%                   smoothing. The outputs are tsh files with elevation data.%
796%
797%  run_simulation.py: Use the above together with various parameters to
[2434]798%                     run inundation simulation.
[2413]799
800
801
802
[2329]803\appendix
[2358]804
[2434]805\chapter{Supporting Tools}
[2358]806
807
[2434]808\section{caching}
[2358]809
[2434]810  The \code{cache} function is used to provide supervised caching of function results. A Python
811  function call of the form
[2358]812
[2434]813      {\scriptsize \begin{verbatim}
814      result = func(arg1,...,argn)
815      \end{verbatim}}
[2358]816
[2434]817  can be replaced by
[2358]818
[2434]819      {\scriptsize \begin{verbatim}
820      from caching import cache
821      result = cache(func,(arg1,...,argn))
822      \end{verbatim}}
823 
824  which returns the same output but reuses cached
825  results if the function has been computed previously in the same context.
826  \code{result} and the arguments can be simple types, tuples, list, dictionaries or
827  objects, but not unhashable types such as functions or open file objects.
828  The function \code{func} may be a member function of an object or a module.
[2358]829
[2434]830  This type of caching is particularly useful for computationally intensive
831  functions with few frequently used combinations of input arguments. Note that
832  if the inputs or output are very large caching might not save time because
833  disc access may dominate the execution time.
834
835  If the function definition changes after a result has been cached it will be
836  detected by examining the functions \code{bytecode (co_code, co_consts,
837  func_defualts, co_argcount)} and it will be recomputed.
838 
839  Options are set
840  by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a
841  Python dictionary \code{options} that stores settings such as the name of the directory used, the maximum
842  number of cached files allowed, and so on.
843 
844  The \code{cache} function allows the user also to specify a list of dependent files. If any of these
845  have been changed, the function is recomputed and the results stored again.
846 
847  Other features include support for compression and a capability to \ldots
848
849 
850   \textbf{USAGE:}
851 
852    {\scriptsize \begin{verbatim}
853    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
854                   compression, evaluate, test, return_filename)}
855    \end{verbatim}}
856
857  \textbf{ARGUMENTS:}
858 
859  \begin{tabular}{ll}
860    \code{func} & Function object (Required)\\
861    \code{args} & Arguments to func (Default: ())\\
862    \code{kwargs} & Keyword arguments to func (Default: {}\\ 
863    \code{dependencies} & Filenames that func depends on (Default: \code{None})\\
864    \code{cachedir} & Directory for cache files (Default: \code{options['cachedir']})\\
865    \code{verbose} & Flag verbose output to stdout
866                       (Default: \code{options['verbose']})\\
867    \code{compression} & Flag zlib compression (Default: \code{options['compression']})\\
868    \code{evaluate} & Flag forced evaluation of func (Default: 0)\\
869    \code{test} & Flag test for cached results (Default: 0)\\
870    \code{clear} & Flag delete cached results (Default: 0)\\   
871    \code{return_filename} & Flag return of cache filename (Default: 0)\\   
872  \end{tabular}
873 
874
875  \textbf{LIMITATIONS:}
876 
877  \begin{itemize}
878   \item Caching uses the apply function and will work with anything that can be
879      pickled, so any limitation in apply or pickle extends to caching.
880     
881   \item A function to be cached should not depend on global variables
882      as wrong results may occur if globals are changed after a result has
883      been cached.
884   \end{itemize}
885
886 
887
888
889\section{swollen}
890
891
892The main keys operating the interactive screen are:\\
893
894\begin{tabular}{|ll|}   \hline
895
896\code{w} & toggle wireframe\\
897
898space bar & start/stop\\
899
900up/down arrows & increase/decrease speed\\
901
902left/right arrows & direction in time \emph{(when running)}\\ & step through simulation \emph{(when stopped)}\\
903
904left mouse button & rotate\\
905
906middle mouse button & pan\\
907
908right mouse button & zoom\\  \hline
909
910\end{tabular}
911
912\vfill
913
914The following table describes how to operate swollen from the command line:
915
916Usage: \code{swollen [options] swwfile \ldots}\\  \nopagebreak
917Options:\\  \nopagebreak
918\begin{tabular}{ll}
919  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY_CENTER |}\\
920                                    & \code{HEAD_MOUNTED_DISPLAY}\\
921  \code{--rgba} & Request a RGBA colour buffer visual\\
922  \code{--stencil} & Request a stencil buffer visual\\
923  \code{--stereo} & Use default stereo mode which is \code{ANAGLYPHIC} if not \\
924                                    & overridden by environmental variable\\
925  \code{--stereo <mode>} & \code{ANAGLYPHIC | QUAD_BUFFER | HORIZONTAL_SPLIT |}\\
926                                    & \code{VERTICAL_SPLIT | LEFT_EYE | RIGHT_EYE |}\\
927                                     & \code{ON | OFF} \\
928  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
929  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
930  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
931  \code{-help} & Display this information\\
932  \code{-hmax <float>} & Height above which transparency is set to
933                                     \code{alphamax}\\
934  \code{-hmin <float>} & Height below which transparency is set to
935                                     zero\\
936  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
937                                     up, default is overhead)\\
938  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
939  \code{-movie <dirname>} & Save numbered images to named directory and
940                                     quit\\
941  \code{-nosky} & Omit background sky\\
942  \code{-scale <float>} & Vertical scale factor\\
943  \code{-texture <file>} & Image to use for bedslope topography\\
944  \code{-tps <rate>} & Timesteps per second\\
945  \code{-version} & Revision number and creation (not compile)
946                                     date\\
947\end{tabular}
948
[2358]949\section{utilities/polygons} Could do now.
950
[2422]951\begin{itemize}
952  \item \indexedcode{polygon_function}
953  \item \indexedcode{read_polygon}
954  \item \indexedcode{populate_polygon}
955  \item \indexedcode{point_in_polygon}
956  \item \indexedcode{inside_polygon}
957  \item \indexedcode{outside_polygon}
958  \item \indexedcode{point_on_line}
959  \item \indexedcode{separate_points_by_polygon}
960\end{itemize}
[2358]961
[2373]962
963
964
[2422]965
[2358]966\section{coordinate_transforms}
967
968\section{geo_spatial_data}
969
970\section{pmesh GUI}
971
972\section{alpha_shape}
973
974
[2412]975\section{utilities/numerical_tools} Could do now.
[2358]976
[2422]977\begin{itemize}
[2412]978  \item \indexedcode{ensure_numeric}
979  \item \indexedcode{mean}
[2422]980  \item
981\end{itemize}
[2358]982
[2329]983\chapter{Glossary}
[2274]984
[2358]985\begin{itemize}
[2434]986    \item \indexedbold{\anuga} name of software (joint development between ANU and GA)
[2274]987
[2422]988    \item \indexedbold{Conserved quantity}
989
[2358]990    \item \indexedbold{Default order} is this really needed?
[2274]991
[2358]992    \item \indexedbold{Domain}
[2274]993
[2358]994    \item \indexedbold{Dirichlet boundary}
[2274]995
[2358]996    \item \indexedbold{Elevation} - refers to bathymetry and topography
[2274]997
[2358]998    \item \indexedbold{bathymetry} offshore
[2274]999
[2358]1000    \item \indexedbold{topography} onshore
[2328]1001
[2358]1002    \item \indexedbold{Evolution} integration of the shallow water wave equations over time
[2328]1003
[2358]1004    \item \indexedbold{Forcing term}
[2274]1005
[2358]1006    \item \indexedbold{IDLE} development environment shipped with Python
[2274]1007
[2358]1008    \item \indexedbold{Manning friction coefficient}
[2422]1009
[2358]1010    \item \indexedbold{Mesh}    triangulation of domain
[2274]1011
[2358]1012    \item \indexedbold{Grid} evenly spaced
[2328]1013
[2358]1014    \item \indexedbold{NetCDF}
[2274]1015
[2358]1016    \item \indexedbold{pmesh} does this really need to be here? it's a class/module?
[2274]1017
[2358]1018    \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?
[2274]1019
[2358]1020    \item \indexedbold{Quantity} conserved (state, x and y momentum)
[2274]1021
[2358]1022    \item \indexedbold{Reflective boundary}
[2274]1023
[2358]1024    \item \indexedbold{Smoothing} is this really needed?
[2274]1025
[2358]1026    \item \indexedbold{Stage}
[2274]1027
[2358]1028    \item \indexedbold{Swollen} visualisation tool
[2274]1029
[2358]1030    \item \indexedbold{Time boundary} defined in the manual (flog from there)
[2274]1031
[2358]1032    \item \indexedbold{Transmissive boundary} defined in the manual (flog from there)
[2274]1033
[2358]1034    \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
[2274]1035
[2422]1036    \item \indexedbold{ymomentum}  conserved quantity
1037
[2358]1038    \item \indexedbold{resolution}   refers to the maximal area of each triangular cell in the mesh
[2422]1039
[2434]1040    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created
1041    in this way )
1042    ANUGA represents polygons as either a list of 2-tuples, where the latter are either Python tuples
1043    or Python lists of length 2. The unit square, for example, would be represented by the polygon
1044    [ [0,0], [1,0], [1,1], [0,1] ]. Alternatively, polygons can be represented as $N \times 2$ Numeric
1045    arrays, where $N$ is the number of points.
[2422]1046
[2358]1047    NOTE: More can be read in the module utilities/polygon.py ....
[2274]1048
[2422]1049    \item \indexedbold{easting}
[2328]1050
[2422]1051    \item \indexedbold{northing}
[2328]1052
[2422]1053    \item \indexedbold{latitude}
[2328]1054
[2422]1055    \item \indexedbold{longitude}
[2328]1056
[2422]1057    \item \indexedbold{edge}
[2328]1058
[2422]1059    \item \indexedbold{vertex}
[2328]1060
[2422]1061    \item \indexedbold{finite volume}
[2328]1062
[2422]1063    \item \indexedbold{flux}
[2328]1064
[2422]1065    \item \indexedbold{Digital Elevation Model (DEM)}
[2328]1066
[2422]1067
[2358]1068\end{itemize}
[2274]1069
[2329]1070The \code{\e appendix} markup need not be repeated for additional
1071appendices.
1072
1073
1074%
1075%  The ugly "%begin{latexonly}" pseudo-environments are really just to
1076%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
1077%  not really valuable.
1078%
1079%  If you don't want the Module Index, you can remove all of this up
1080%  until the second \input line.
1081%
1082
1083%begin{latexonly}
1084%\renewcommand{\indexname}{Module Index}
1085%end{latexonly}
[2422]1086%\input{mod\jobname.ind}        % Module Index
[2329]1087
1088%begin{latexonly}
1089\renewcommand{\indexname}{Index}
1090%end{latexonly}
[2422]1091\input{\jobname.ind}            % Index
[2329]1092
1093
1094
[2274]1095\end{document}
Note: See TracBrowser for help on using the repository browser.