source: documentation/user_manual/anuga_user_manual.tex @ 2600

Last change on this file since 2600 was 2600, checked in by howard, 18 years ago

Added material on evolve, plus a few other minor changes

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 58.8 KB
Line 
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
9%labels
10%Sections and subsections \label{sec: }
11%Chapters \label{ch: }
12%Equations \label{eq: }
13%Figures \label{fig: }
14
15
16
17\documentclass{manual}
18
19\usepackage{graphicx}
20\input{definitions}
21
22\title{\anuga User Manual}
23\author{Howard Silcock, Ole Nielsen, Duncan Gray, Jane Sexton}
24
25% Please at least include a long-lived email address;
26% the rest is at your discretion.
27\authoraddress{Geoscience Australia \\
28  Email: \email{ole.nielsen@ga.gov.au}
29}
30
31%Draft date
32\date{\today}   % update before release!
33                % Use an explicit date so that reformatting
34                % doesn't cause a new date to be used.  Setting
35                % the date to \today can be used during draft
36                % stages to make it easier to handle versions.
37
38\release{1.0}   % release version; this is used to define the
39                % \version macro
40
41\makeindex          % tell \index to actually write the .idx file
42%\makemodindex          % If this contains a lot of module sections.
43
44\setcounter{tocdepth}{3}
45\setcounter{secnumdepth}{3}
46\begin{document}
47\maketitle
48
49% This makes the contents more accessible from the front page of the HTML.
50\ifhtml
51\chapter*{Front Matter\label{front}}
52\fi
53
54%Subversion keywords:
55%
56%$LastChangedDate: 2006-03-26 19:55:32 +0000 (Sun, 26 Mar 2006) $
57%$LastChangedRevision: 2600 $
58%$LastChangedBy: howard $
59
60\input{copyright}
61
62
63\begin{abstract}
64
65\noindent \anuga\index{\anuga} is a hydrodynamic modelling tool that
66allows users to model realistic flow problems in complex geometries.
67Examples include dam breaks or the effects of natural hazards such
68as riverine flooding, storm surges and tsunami.
69
70The user must specify a study area represented by a mesh of triangular
71cells, the topography and bathymetry, frictional resistance, initial
72values for water level (called \emph{stage}\index{stage} within \anuga),
73boundary
74conditions and forces such as windstress or pressure gradients if
75applicable.
76
77\anuga tracks the evolution of water depth and horizontal momentum
78within each cell over time by solving the shallow water wave equation
79governing equation using a finite-volume method.
80
81\anuga cannot model details of breaking waves, flow under ceilings such
82as pipes, turbulence and vortices, vertical convection or viscous
83flows.
84
85\anuga also incorporates a mesh generator, called \code{pmesh}, that
86allows the user to set up the geometry of the problem interactively as
87well as tools for interpolation and surface fitting, and a number of
88auxiliary tools for visualising and interrogating the model output.
89
90Most \anuga components are written in the object-oriented programming
91language Python and most users will interact with \anuga by writing
92small Python programs based on the \anuga library
93functions. Computationally intensive components are written for
94efficiency in C routines working directly with the Numerical Python
95structures.
96
97
98\end{abstract}
99
100\tableofcontents
101
102
103\chapter{Introduction}
104
105
106\section{Purpose}
107
108The purpose of this user manual is to introduce the new user to
109the software, describe what it can do and give step-by-step
110instructions for setting up and running hydrodynamic simulations.
111
112\section{Scope}
113
114This manual covers only what is needed to operate the software
115after installation and configuration. It does not includes instructions for
116installing the software or detailed API documentation, both of
117which will be covered in separate publications.
118
119\section{Audience}
120
121Readers are assumed to be familiar with the operating environment
122and have a general understanding of the problem background, as
123well as enough programming experience to adapt the code to
124different requirements, as described in this manual,  and to
125understand the basic terminology of object-oriented programming.
126
127\section{Structure of This Manual}
128
129This manual is structured as follows:
130
131\begin{itemize}
132  \item Background (What \anuga does)
133  \item A \emph{Getting Started} section
134  \item A detailed description of the public interface
135  \item \anuga 's overall architecture, components and file formats
136  \item Assumptions
137\end{itemize}
138
139
140\pagebreak
141\chapter{Getting Started}
142
143This section is designed to assist the reader to get started with
144\anuga by working through simple examples. Two examples are discussed;
145the first is a simple but artificial example that is useful to illustrate
146many of the ideas, and the second is a more realistic example.
147
148\section{A Simple Example}
149
150\subsection{Overview}
151
152What follows is a discussion of the structure and operation of the file
153\code{bedslopephysical.py}, with just enough detail to allow the reader
154to appreciate what's involved in setting up a scenario like the
155one it depicts.
156
157This example carries out the solution of the shallow-water wave
158equation in the simple case of a configuration comprising a flat
159bed, sloping at a fixed angle in one direction and having a
160constant depth across each line in the perpendicular direction.
161
162The example demonstrates many of the basic ideas involved in
163setting up a more complex scenario. In the general case the user
164specifies the geometry (bathymetry and topography), the initial
165water level, boundary conditions such as tide, and any forcing
166terms that may drive the system such as wind stress or atmospheric
167pressure gradients. Frictional resistance from the different
168terrains in the model is represented by predefined forcing
169terms. The boundary is reflective on three sides and a time dependent wave on one side.
170
171The present example represents a simple scenario and does not
172include any forcing terms, nor is the data taken from a file as it
173would be in many typical cases.
174
175The conserved quantities involved in the
176problem are water depth, $x$-momentum and $y$-momentum. Other quantities
177involved in the computation are the friction, stage (absolute height of water surface)
178and elevation, the last two being related to
179the depth through the equation
180
181\begin{tabular}{rcrcl} 
182  \code{stage} &=& \code{elevation} &+& \code{depth}
183\end{tabular} 
184
185
186%\emph{[More details of the problem background]}
187
188\subsection{Outline of the Program}
189
190In outline, \code{bedslopephysical.py} performs the following steps:
191
192\begin{enumerate}
193
194   \item Sets up a triangular mesh.
195
196   \item Sets certain parameters governing the mode of
197operation of the model-specifying, for instance, where to store the model output.
198
199   \item Inputs various quantities describing physical measurements, such
200as the elevation, to be specified at each mesh point (vertex).
201
202   \item Sets up the boundary conditions.
203
204   \item Carries out the evolution of the model through a series of time
205steps and outputs the results, providing a results file that can
206be visualised.
207
208\end{enumerate}
209
210\subsection{The Code}
211
212%FIXME: we are using the \code function here.
213%This should be used wherever possible
214For reference we include below the complete code listing for
215\code{bedslopephysical.py}. Subsequent paragraphs provide a `commentary'
216that describes each step of the program and explains it significance.
217
218%\verbatiminput{examples/bedslopephysical.py}
219\verbatiminput{examples/bedslope.py}
220
221\subsection{Establishing the Mesh}
222
223The first task is to set up the triangular mesh to be used for the
224scenario. This is carried out through the statement:
225
226{\small \begin{verbatim}
227    points, vertices, boundary = rectangular(10, 10)
228\end{verbatim}}
229
230The function \code{rectangular} is imported from a module
231\code{mesh\_factory} defined elsewhere. (\anuga also contains
232several other schemes that can be used for setting up meshes, but we
233shall not discuss these now.) The above assignment sets up a $10
234\times 10$ rectangular mesh, triangulated in a specific way. In
235general, the assignment
236
237{\small \begin{verbatim}
238    points, vertices, boundary = rectangular(m, n)
239\end{verbatim}}
240
241returns:
242
243\begin{itemize}
244
245   \item a list \code{points} of length $N$, where $N = (m + 1)(n + 1)$,
246comprising the coordinates $(x, y)$ of each of the $N$ mesh points,
247
248   \item a list \code{vertices} of length $2mn$ (each entry specifies the three
249vertices of one of the triangles used in the triangulation) , and
250
251   \item a dictionary \code{boundary}, used to tag the triangle edges on
252the boundaries. Each key corresponds to a triangle edge on one of
253the four boundaries and its value is one of \code{`left'},
254\code{`right'}, \code{`top'} and \code{`bottom'}, indicating
255which boundary the edge in question belongs to.
256
257\end{itemize}
258
259
260\subsection{Initialising the Domain}
261
262These variables are then used to set up a data structure
263\code{domain}, through the assignment:
264
265{\small \begin{verbatim}
266    domain = Domain(points, vertices, boundary)
267\end{verbatim}}
268
269This uses a Python class \code{Domain}, imported from
270\code{shallow\_water}, which is an extension of a more generic
271class of the same name in the module \code{domain}, and inherits
272some methods from the generic class but has others specific to the
273shallow-water scenarios in which it is used. Specific options for domain
274are set at this point. One of them is to set the basename for the output file:
275
276{\small \begin{verbatim}
277    domain.set_name('bedslope')
278\end{verbatim}}
279
280
281\subsection{Specifying the Quantities}
282
283The next task is to specify a number of quantities that we wish to set
284for each mesh point. The class \code{Domain} has a method
285\code{set\_quantity}, used to specify these quantities. It is a
286particularly flexible method that allows the user to set quantities in
287a variety of ways---using constants, functions, numeric arrays or
288expressions involving other quantities, arbitrary data points with
289associated values, all of which can be passed as arguments. All
290quantities can be initialised using \code{set\_quantity}. For
291conserved quantities (\code{stage, xmomentum, ymomentum}) this is
292called the \emph{initial condition}, for other quantities that aren't
293updated by the equation, the same interface is used to assign their
294values. The code in the present example demonstrates a number of forms
295in which we can invoke \code{set\_quantity}.
296
297
298\subsubsection{Elevation}
299
300The elevation, or height of the bed, is set using a function,
301defined through the statements below, which is specific to this
302example and specifies a particularly simple initial configuration
303for demonstration purposes:
304
305{\small \begin{verbatim}
306    def f(x,y):
307        return -x/2
308\end{verbatim}}
309
310This simply associates an elevation with each point \code{(x, y)} of
311the plane.  It specifies that the bed slopes linearly in the
312\code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
313the \code{y} direction.  %[screen shot?]
314
315Once the function \code{f} is specified, the quantity
316\code{elevation} is assigned through the simple statement:
317
318{\small \begin{verbatim}
319    domain.set_quantity('elevation', f)
320\end{verbatim}}
321
322
323\subsubsection{Friction}
324
325The assignment of the friction quantity demonstrates another way
326we can use \code{set\_quantity} to set quantities---namely,
327assign them to a constant numerical value:
328
329{\small \begin{verbatim}
330    domain.set_quantity('friction', 0.1)
331\end{verbatim}}
332
333This just specifies that the Manning friction coefficient is set
334to 0.1 at every mesh point.
335
336\subsubsection{Stage}
337
338The stage (the height of the water surface) is related to the
339elevation and the depth at any time by the equation
340
341
342{\small \begin{verbatim}
343    stage = elevation + depth
344\end{verbatim}} 
345 
346
347For this example, we simply assign a constant value to \code{stage},
348using the statement
349
350{\small \begin{verbatim}
351    domain.set_quantity('stage', -.4)
352\end{verbatim}}
353
354which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units
355below the zero level.
356
357(Although it is not necessary for this example, it may be useful to digress here
358and mention a variant to this requirement, which allows us to illustrate
359another way to use \code{set\_quantity}---namely, incorporating an expression
360involving other quantities. Suppose, instead of setting a constant value
361for the stage, we wished
362to specify a constant value for the \emph{depth}. For such a case we 
363need to specify that \code{stage} is
364everywhere obtained by adding that value to the value already
365specified for \code{elevation}. We would do this by means of the statements:
366
367{\small \begin{verbatim}
368    h = 0.05 \# Constant depth
369    domain.set_quantity('stage', expression = 'elevation + %f' %h)
370\end{verbatim}}
371
372That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the
373value of \code{elevation} already defined.
374
375The reader will probably appreciate that this capability to incorporate
376expressions into statements using \code{set\_quantity} greatly expands
377its power.)
378
379\subsubsection{Boundary Conditions}
380
381The boundary conditions are specified as follows:
382
383{\small \begin{verbatim}
384    Br = Reflective_boundary(domain)
385
386    Bt = Transmissive_boundary(domain)
387
388    Bd = Dirichlet_boundary([0.2,0.,0.])
389
390    Bw = Time_boundary(domain=domain,
391                f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0])
392\end{verbatim}}
393
394The effect of these statements is to set up four alternative
395boundary conditions and store them in variables that can be
396assigned as needed. Each boundary condition specifies the
397behaviour at a boundary in terms of the behaviour in neighbouring
398elements. The boundary conditions introduced here may be briefly described as
399follows:
400
401\begin{description}
402    \item[Reflective boundary] Returns same \code{stage} as
403    as present in its neighbour volume but momentum vector reversed 180 degrees (reflected).
404    Specific to the shallow water equation as it works with the
405    momentum quantities assumed to be the second and third conserved
406    quantities.
407
408    \item[Transmissive boundary]Returns same conserved quantities as
409    those present in its neighbour volume.
410
411    \item[Dirichlet boundary]Specifies a fixed value at the
412boundary and assigns initial values to the $x$-momentum and $y$-momentum. 
413
414    \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time.
415\end{description}
416
417Once the four boundary types have been specified through the
418statements above, they can be applied through a statement of the
419form
420
421{\small \begin{verbatim}
422    domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br})
423\end{verbatim}}
424
425This statement stipulates that, in the current example, the left
426boundary is fixed, with an elevation of 0.2, while the other
427boundaries are all reflective.
428
429The reader may wish to experiment by varying the choice of boundary types
430for one or more of the boundaries. In the case of \code{Bd} and \code{Bw},
431the three arguments in each case represent the
432
433{\small \begin{verbatim}
434    Bw = Time_boundary(domain=domain,
435                f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0])
436\end{verbatim}}
437
438
439
440\subsection{Evolution}
441
442The final statement \nopagebreak[3]
443{\small \begin{verbatim}
444    for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
445        print domain.timestepping_statistics()
446\end{verbatim}}
447
448is the key step that causes the configuration of the domain to
449`evolve' in accordance with the model embodied in the code, over a
450series of steps indicated by the values of \code{yieldstep} and
451\code{duration}, which can be altered as required.
452The value of \code{yieldstep} controls the time interval between successive model outputs.
453Behind the scenes more time steps are generally taken.
454
455
456\subsection{Output}
457
458%Give details here of the form of the output and explain how it can
459%be used with swollen. Include screen shots.//
460
461The output is a NetCDF file with the extension \code{.sww}. It
462contains stage and momentum information and can be used with the
463\code{swollen} visualisation package to generate a visual display.
464
465
466\section{How to Run the Code}
467
468The code can be run in various ways:
469
470\begin{itemize}
471  \item{from a Windows command line} as in \code{python bedslopephysical.py}
472  \item{within the Python IDLE environment}
473  \item{within emacs}
474  \item{from a Linux command line} as in \code{python bedslopephysical.py}
475\end{itemize}
476
477
478\section{Exploring the model output}
479
480Figure \ref{fig:bedslopestart} shows the \\
481Figure \ref{fig:bedslope2} shows later snapshots...
482
483
484
485\begin{figure}[hbt]
486
487%  \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}}
488 
489  \caption{Bedslope example viewed with Swollen}
490  \label{fig:bedslopestart}
491\end{figure} 
492
493
494\begin{figure}[hbt]
495
496  \centerline{ 
497%    \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps}
498%    \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps}
499   }   
500 
501  \caption{Bedslope example viewed with Swollen}
502  \label{fig:bedslope2}
503\end{figure} 
504
505
506
507
508\clearpage
509
510%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
511
512\section{An Example with Real Data}
513
514The following discussion builds on the concepts introduced through
515the \code{bedslopephysical.py} example and introduces a second example,
516\code{run\_sydney\_smf.py}, that follows the same basic outline, but
517incorporates more complex features and refers to a real-life
518scenario, rather than the artificial illustrative one used in
519\code{bedslopephysical.py}. The domain of interest surrounds the Sydney region,
520and predominantly covers Sydney Harbour. A hypothetical tsunami wave is
521generated by a submarine mass failure situated on the edge of the
522continental shelf.
523
524\subsection{Overview}
525As in the case of \code{bedslopephysical.py}, the actions carried out by the
526program can be organised according to this outline:
527
528\begin{enumerate}
529
530   \item Set up a triangular mesh.
531
532   \item Set certain parameters governing the mode of
533operation of the model---specifying, for instance, where to store the
534model output.
535
536   \item Input various quantities describing physical measurements, such
537as the elevation, to be specified at each mesh point (vertex).
538
539   \item Set up the boundary conditions.
540
541   \item Carry out the evolution of the model through a series of time
542steps and outputs the results, providing a results file that can be
543visualised.
544
545\end{enumerate}
546
547
548
549\subsection{The Code}
550
551Here is the code for \code{run\_sydney\_smf.py}:
552
553%\verbatiminput{"runsydneysmf.py"}
554\verbatiminput{examples/runsydney.py}
555
556In discussing the details of this example, we follow the outline
557given above, discussing each major step of the code in turn.
558
559\subsection{Establishing the Mesh}
560
561One obvious way that the present example differs from
562\code{bedslopephysical.py} is in the use of a more complex method to create
563the mesh. Instead of imposing a mesh structure on a rectangular
564grid, the technique used for this example involves building mesh
565structures inside polygons specified by the user, using a
566mesh-generator referred to as \code{pmesh}.
567
568The following remarks may help the reader understand how
569\code{pmesh} is used.
570
571In its simplest form, \code{pmesh} creates the mesh within a single
572polygon whose vertices are at geographical locations specified by the
573user. The user specifies the \emph{resolution}---that is, the maximal
574area of a triangle used for triangulation---and mesh points are
575created inside the polygon through a random process. Figure
576\ref{fig:pentagon} shows a simple example of this, in which
577the triangulation is carried out within a pentagon.
578
579
580\begin{figure}[hbt]
581
582
583 
584  \caption{Mesh points are created inside the polygon}
585  \label{fig:pentagon} 
586\end{figure} 
587
588Boundary tags are not restricted to \code{`left'}, \code{`right'},
589\code{`bottom'} and \code{`top'}, as in the case of
590\code{bedslopephysical.py}. Instead the user specifies a list of tags
591appropriate to the configuration being modelled.
592
593While a mesh created inside a polygon offers more flexibility than
594one based on a rectangular grid, using \code{pmesh} in the limited
595form we have described so far still doesn't provide a way to adapt
596to geographic or other features in the landscape, whose presence may
597require us to vary the resolution in the neighbourhood of the
598features. To cope with this requirement, \code{pmesh} also allows
599the user to specify a number of \emph{interior polygons}, which are
600triangulated separately, each according to a separately specified
601resolution. See Figure \ref{fig:interior meshes}.
602
603\begin{figure}[hbt]
604
605
606 
607  \caption{Interior meshes with individual resolution}
608  \label{fig:interior meshes} 
609\end{figure} 
610
611In its general form, \code{pmesh} takes for its input a bounding
612polygon and (optionally) a list of interior polygons. The user
613specifies resolutions, both for the bounding polygon and for each of
614the interior polygons. Given this data, \code{pmesh} first creates a
615triangular mesh inside the bounding polygon, using the specified
616resolution, and then creates a separate triangulation inside each of
617the interior polygons, using the resolution specified for that
618polygon.
619
620The function used to implement this process is
621\code{create\_mesh\_from\_regions}. Its arguments include the
622bounding polygon and its resolution, a list of boundary tags, and a
623list of pairs \code{[polygon, resolution]}, specifying the interior
624polygons and their resolutions.
625
626In practice, the details of the polygons used are read from a
627separate file \code{project.py}. The resulting mesh is output to a
628\emph{meshfile}\index{meshfile}. This term is used to describe a
629file of a specific format used to store the data specifying a mesh.
630(There are in fact two possible formats for such a file: it can
631either be a binary file, with extension \code{.msh}, or an ASCII
632file, with extension \code{.tsh}. In the present case, the binary
633file format \code{.msh} is used. See Section \ref{sec:file formats}
634(p. \pageref{sec:file formats}) for more on file formats.)
635\code{pmesh} assigns a name to the file by appending the extension
636\code{.msh} to the name specified in the input file
637\code{project.py}. This name is stored in the variable
638\code{meshname}.
639
640The statements
641
642{\small \begin{verbatim}
643    interior_res = 5000%
644    interior_regions = [[project.harbour_polygon_2, interior_res],
645                    [project.botanybay_polygon_2, interior_res]]
646\end{verbatim}}
647
648are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
649\code{botanybay\_polygon\_2} from \code{project.py} and assign a
650common resolution of 5000 to each. The statement
651
652{\small \begin{verbatim}
653    create_mesh_from_regions(project.diffpolygonall,%
654                         boundary_tags= {'bottom': [0],%
655                                         'right1': [1],%
656                                         'right0': [2],%
657                                         'right2': [3],%
658                                         'top': [4],%
659                                         'left1': [5],%
660                                         'left2': [6],%
661                                         'left3': [7]},%
662                         maximum_triangle_area=100000,%
663                         filename=meshname,%           
664                         interior_regions=interior_regions)
665\end{verbatim}}
666
667is then used to create the mesh, taking the bounding polygon to be the polygon
668\code{diffpolygonall} specified in \code{project.py}. The
669argument \code{boundary\_tags} assigns a dictionary, whose keys are the
670names of the boundary tags used for the bounding polygon---\code{`bottom'},
671`right0', `right1', `right2', `top', `left1', `left2' and `left3'---
672and whose values identify the indices of the segments associated with each of these
673tags. (The value associated with each boundary tag is a one-element list.)
674
675
676\subsection{Initialising the Domain}
677
678As with \code{bedslopephysical.py}, once we have created the mesh, the next
679step is to create the data structure \code{domain}. We did this for
680\code{bedslopephysical.py} by inputting lists of points and triangles and
681specifying the boundary tags directly. However, in the present case,
682we use a method that works directly with the meshfile
683\code{meshname}, as follows:
684
685{\small \begin{verbatim}
686    domain = pmesh_to_domain_instance(meshname,
687    Domain, use_cache = True, verbose = True)
688\end{verbatim}}
689
690The function \code{pmesh\_to\_domain\_instance} converts a meshfile
691\code{meshname} into an instance of the data structure
692\code{domain}, allowing us to use methods like \code{set\_quantity}
693to set quantities and to apply other operations. (In principle, the
694second argument of \code{pmesh\_to\_domain\_instance} can be any
695subclass of \code{Domain}, but for applications involving the
696shallow-water wave equation, the second argument of
697\code{pmesh\_to\_domain\_instance} can always be set simply to
698\code{Domain}.)
699
700The following statements specify a basename and data directory, and
701identify quantities to be stored. For the first two, values are
702taken from \code{project.py}.
703
704{\small \begin{verbatim} 
705    domain.set_name(project.basename)%
706    domain.set_datadir(project.outputdir)%
707    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
708        'ymomentum'])
709\end{verbatim}}
710
711
712\subsection{Specifying the Quantities}
713Quantities for \code{run\_sydney\_smf.py} are set
714using similar methods to those in \code{bedslopephysical.py}. However,
715in this case, many of the values are read from the auxiliary file
716\code{project.py} or, in the case of \code{elevation}, from an
717ancillary points file.
718
719
720
721\subsubsection{Stage}
722
723For the scenario we are modelling in this case, we use a callable
724object \code{tsunami\_source}, assigned by means of a function
725\code{slump\_tsunami}. This is similar to how we set elevation in
726\code{bedslopephysical.py} using a function---however, in this case the
727function is both more complex and more interesting.
728
729The function returns the water displacement for all \code{x} 
730and \code{y} in the domain. The water displacement is a ?? function that depends
731on the characteristics of the slump (length, thickness, slope, etc), its
732location (origin) and the depth at that location.
733
734
735\subsubsection{Friction}
736
737We assign the friction exactly as we did for \code{bedslopephysical.py}:
738
739{\small \begin{verbatim}
740    domain.set_quantity('friction', 0.03)
741\end{verbatim}}
742
743
744\subsubsection{Elevation}
745
746The elevation is specified by reading data from a file:
747
748{\small \begin{verbatim}%
749    domain.set_quantity('elevation',%
750                    filename = project.combineddemname + '.pts',%
751                    use_cache = True,%
752                    verbose = True)%
753\end{verbatim}}
754
755However, before this step can be executed, some preliminary steps
756are needed to prepare the file from which the data is taken. Two
757source files are used for this data---their names are specified in
758the file \code{project.py}, in the variables \code{coarsedemname}
759and \code{finedemname}. They contain `coarse' and `fine' data,
760respectively---that is, data sampled at widely spaced points over a
761large region and data sampled at closely spaced points over a
762smaller subregion. The data in these files is combined through the
763statement
764
765{\small \begin{verbatim}
766combine_rectangular_points_files(project.finedemname + '.pts',
767                                 project.coarsedemname + '.pts',
768                                 project.combineddemname + '.pts')
769\end{verbatim}}
770
771The effect of this is simply to combine the datasets by eliminating
772any coarse data associated with points inside the smaller region
773common to both datasets. The name to be assigned to the resulting
774dataset is also derived from the name stored in the variable
775\code{combinedname} in the file \code{project.py}.
776
777\subsection{Boundary Conditions}
778
779Setting boundaries follows a similar pattern to the one used for
780\code{bedslopephysical.py}, except that in this case we need to associate a
781boundary type with each of the
782boundary tag names introduced when we established the mesh. In place of the four
783boundary types introduced for \code{bedslopephysical.py}, we use the reflective
784boundary for each of the
785eight tagged segments:
786
787{\small \begin{verbatim}
788    Br = Reflective_boundary(domain)
789    domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
790                          'right2': Br, 'top': Br, 'left1': Br,
791                          'left2': Br, 'left3': Br} )
792\end{verbatim}}
793
794\subsection{Evolution}
795
796With the basics established, the running of the `evolve' step is
797very similar to the corresponding step in \code{bedslopephysical.py}:
798
799{\small \begin{verbatim}
800    import time t0 = time.time()
801   
802    for t in domain.evolve(yieldstep = 120, duration = 18000):
803        print domain.timestepping_statistics()
804        print domain.boundary_statistics(tags = 'bottom')
805   
806    print 'That took %.2f seconds' %(time.time()
807\end{verbatim}}
808
809%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
810%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
811
812\chapter{\anuga Public Interface}
813
814This chapter gives an overview of the features of \anuga available
815to the user at the public interface. These are grouped under the
816following headings:
817
818\begin{itemize}
819    \item Establishing the Mesh
820    \item Initialising the Domain
821    \item Specifying the Quantities
822    \item Initial Conditions
823    \item Boundary Conditions
824    \item Forcing Functions
825    \item Evolution
826\end{itemize}
827
828The listings are intended merely to give the reader an idea of what
829each feature is, where to find it and how it can be used---they do
830not give full specifications. For these the reader
831may consult the code. The code for every function or class contains
832a documentation string, or `docstring', that specifies the precise
833syntax for its use. This appears immediately after the line
834introducing the code, between two sets of triple quotes.
835
836Each listing also describes the location of the module in which
837the code for the feature being described can be found. All modules
838are in the folder \code{inundation} or one of its subfolders, and the
839location of each module is described relative to \code{inundation}. Rather
840than using pathnames, whose syntax depends on the operating system,
841we use the format adopted for importing the function or class for
842use in Python code. For example, suppose we wish to specify that the
843function \code{create\_mesh\_from\_regions} is in a module called
844\code{mesh\_interface} in a subfolder of \code{inundation} called
845\code{pmesh}. In Linux or Unix syntax, the pathname of the file
846containing the function, relative to \code{inundation}, would be
847
848\begin{center}
849    \code{pmesh/mesh\_interface.py}
850\end{center}
851
852while in Windows syntax it would be
853
854\begin{center}
855    \code{pmesh}$\backslash$\code{mesh\_interface.py}
856\end{center}
857
858Rather than using either of these forms, in this chapter we specify
859the location simply as \code{pmesh.mesh_interface}, in keeping with
860the usage in the Python statement for importing the function,
861namely:
862\begin{center}
863    \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
864\end{center}
865
866
867\section{Mesh Generation}
868
869\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
870                             boundary_tags,
871                             maximum_triangle_area,
872                             filename=None,
873                             interior_regions=None,
874                             poly_geo_reference=None,
875                             mesh_geo_reference=None,
876                             minimum_triangle_angle=28.0}
877Module: \code{pmesh.mesh\_interface}
878
879% Translate following into layman's language
880This function is used to create a triangular mesh suitable for use with
881\anuga, within a specified region. The region is specified as the interior of a polygon
882(the \emph{bounding polygon}). The user specifies the bounding polygon and the
883\emph{resolution}---that is, maximal area of any triangle in the mesh. There is
884also an option to specify a number of internal polygons within each of which a
885separate mesh is created, generally with a smaller resolution. Additionally,
886the user specifies a list of boundary tags, one for each edge of the bounding
887polygon.
888\end{funcdesc}
889
890%%%%%%
891\section{Initialising Domain}
892
893\begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
894Module: \code{pyvolution.pmesh2domain}
895
896Once the initial mesh file has been created, this function is applied
897to convert it to a domain object---that is, to a member of
898the special Python class Domain (or a subclass of Domain), which provides access to properties and
899methods that allow quantities to be set and other operations to be carried out.
900
901\code{file\_name} is the name of the mesh file to be converted,
902including the extension. \code{DomainClass} is the class to be
903returned, which must be a subclass of \code{Domain} having the same
904interface as \code{Domain}---in practice, it can usually be set
905simply to \code{Domain}.
906\end{funcdesc}
907
908
909\subsection{Setters and getters of class Domain}
910
911\begin{funcdesc} {set_name}{??}
912\end{funcdesc}
913
914\begin{funcdesc} {get_name}{??}
915\end{funcdesc}
916
917\begin{funcdesc} {set_datadir}{??}
918\end{funcdesc}
919
920\begin{funcdesc} {get_datadir}{??}
921\end{funcdesc}
922
923\begin{funcdesc} {set_time}{??}
924\end{funcdesc}
925
926\begin{funcdesc} {set_default_order}{??}
927\end{funcdesc}
928
929
930%%%%%%
931\section{Setting Quantities}
932
933\begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None,
934                   geospatial_data = None, filename = None, attribute_name = None,
935                   alpha = None, location = 'vertices', indices = None, verbose = False,
936                   use_cache = False}
937Module: \code{pyvolution.domain}  (see also
938\code{pyvolution.quantity.set_values})
939
940This function is used to assign values to individual quantities for a domain. It is very flexible and can be
941used with many data types: a statement of the form \code{domain.set\_quantity{name, x}} can
942be used to define a quantity having the name \code{name}, where the other argument \code{x} can
943be any of the following:
944
945\begin{itemize}
946\item a number in which case all vertices in the mesh gets that for the quantity in question.
947\item a list of numbers or a Numeric array ordered the same way as the mesh vertices.
948\item a function (e.g.\ see the samples introduced in Chapter 2)
949\item an expression composed of other quantities and numbers, arrays, lists (for
950example, a linear combination of quantities)
951\item the name of a file from which the data can be read
952\item a geospatial dataset (See ?????)
953\end{itemize}
954
955
956Exactly one of the arguments
957  numeric, quantity, function, points, filename
958must be present.
959\end{funcdesc}
960
961%%%
962\anuga provides a number of predefined initial conditions to be used
963with \code{set_quantity}.
964
965\begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None, \
966                x0=0.0, y0=0.0, alpha=0.0, \
967                gravity=9.8, gamma=1.85, \
968                massco=1, dragco=1, frictionco=0, psi=0, \
969                dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, \
970                domain=None,
971                verbose=False}
972This function returns a callable object representing an initial water
973displacement generated by a submarine sediment slide.
974
975The arguments include the downslope slide length, the water depth to the slide centre of mass,
976and the bathymetric slope.
977\end{funcdesc}
978
979
980%%%
981\begin{funcdesc}{file_function}{filename,
982                  domain = None,
983                  quantities = None,
984                  interpolation_points = None,
985                  verbose = False,
986                  use_cache = False}
987Module: \code{pyvolution.util}
988
989Reads the time history of spatial data from NetCDF file and returns
990a callable object. Returns interpolated values based on the input
991file using the underlying \code{interpolation\_function}.
992
993\code{quantities} is either the name of a single quantity to be
994interpolated or a list of such quantity names. In the second case, the resulting
995function will return a tuple of values---one for each quantity.
996
997\code{interpolation\_points} is a list of absolute UTM coordinates
998for points at which values are sought.
999\end{funcdesc}
1000
1001%%%
1002\begin{classdesc}{Interpolation_function}{self,
1003                 time,
1004                 quantities,
1005                 quantity_names = None,
1006                 vertex_coordinates = None,
1007                 triangles = None,
1008                 interpolation_points = None,
1009                 verbose = False}
1010Module: \code{pyvolution.least\_squares}
1011
1012Creates a callable object \code{f(t, id)} or \code{f(t,x,y)}
1013interpolated from a time series defined at the vertices of a
1014triangular mesh (such as those stored in \code{sww} files).
1015
1016\code{time} is an array of monotonically increasing times and
1017\code{quantities} is an array---or dictionary of arrays---of values to
1018be interpolated. The parameter \code{interpolation_points} may be
1019used to specify at which points interpolated quantities are to be
1020computed whenever the object is called. If the default value
1021\code{None} is used, the function returns an average value.
1022\end{classdesc}
1023
1024%%%
1025\begin{funcdesc}{set\_region}{functions}
1026[Low priority. Will be merged into set\_quantity]
1027
1028Module:\code{pyvolution.domain}
1029\end{funcdesc}
1030
1031
1032
1033%%%%%%
1034\section{Boundary Conditions}
1035
1036\anuga provides a large number of predefined boundary conditions to
1037be used with \code{set\_boundary}.
1038
1039\begin{funcdesc}{set\_boundary}{boundary_map}
1040Module: \code{pyvolution.domain}
1041
1042Associate boundary objects with tagged boundary segments.
1043
1044The input \code{boundary\_map} is a dictionary of boundary objects
1045keyed by symbolic tags.
1046
1047As result one pointer to a boundary object is stored for each vertex
1048in the list self.boundary_objects.
1049More entries may point to the same boundary object
1050
1051Schematically the mapping is from two dictionaries to one list where
1052the index is used as pointer to the \code{boundary\_values} arrays
1053within each quantity.
1054\end{funcdesc}
1055
1056\begin{funcdesc} {get_boundary_tags}{??}
1057\end{funcdesc}
1058
1059%%%
1060\subsection{Predefined boundary conditions}
1061
1062\begin{classdesc}{Reflective_boundary}{Boundary}
1063Module: \code{pyvolution.shallow\_water}
1064
1065Reflective boundary returns same conserved quantities as those present in
1066the neighbouring volume but reflected.
1067
1068This class is specific to the shallow water equation as it works with the
1069momentum quantities assumed to be the second and third conserved quantities.
1070\end{classdesc}
1071
1072%%%
1073\begin{classdesc}{Transmissive_boundary}{domain = None}
1074Module: \code{pyvolution.generic\_boundary\_conditions}
1075
1076A transmissive boundary returns the same conserved quantities as
1077those present in the neighbouring volume.
1078
1079The underlying domain must be specified when the boundary is instantiated.
1080\end{classdesc}
1081
1082%%%
1083\begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None}
1084Module: \code{pyvolution.generic\_boundary\_conditions}
1085
1086A Dirichlet boundary returns constant values for the conserved
1087quantities.
1088\end{classdesc}
1089
1090%%%
1091\begin{classdesc}{Time_boundary}{domain = None, f = None}
1092Module: \code{pyvolution.generic\_boundary\_conditions}
1093
1094A time-dependent boundary returns values for the conserved
1095quantities as a function \code{f(t)} of time. The user must specify
1096the domain to get access to the model time.
1097\end{classdesc}
1098
1099%%%
1100\begin{classdesc}{File_boundary}{Boundary}
1101Module: \code{pyvolution.generic\_boundary\_conditions}
1102
1103The boundary values are obtained from a file and interpolated. The
1104file is assumed to contain a time series and possibly also spatial
1105information. The conserved quantities are given as a function of
1106time.
1107\end{classdesc}
1108
1109
1110\subsection{User-defined boundary conditions}
1111[How to roll your own]
1112
1113
1114
1115
1116
1117\section{Forcing Functions}
1118
1119\anuga provides a number of predefined forcing functions to be used with .....
1120
1121%\begin{itemize}
1122
1123
1124%  \item \indexedcode{}
1125%  [function, arguments]
1126
1127%  \item \indexedcode{}
1128
1129%\end{itemize}
1130
1131
1132
1133\section{Evolution}
1134
1135  \begin{funcdesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
1136 
1137  Module: pyvolution.domain
1138 
1139  This function (a method of \code{domain}) is invoked once all the preliminary steps have been
1140  taken, and causes the model to progress through a successive steps in its evolution, during
1141  which quantities are progressively recalculated and the domain may be modified. The user specifies
1142  the time period over which the evolution is to take place, by specifying values (in seconds) for either
1143  \code{duration} or \code{finaltime}, as well as the interval in seconds after which results are to be
1144  stored and statistics output. 
1145 
1146  You can include \code{evolve} in a statement of the type:
1147 
1148  {\small \begin{verbatim}
1149      for t in domain.evolve(yieldstep, finaltime):
1150          <Do something with domain and t>
1151  \end{verbatim}}
1152
1153  \end{funcdesc}
1154
1155
1156
1157\subsection{Diagnostics}
1158
1159  \begin{funcdesc}{timestepping_statistics}{???}
1160
1161  \end{funcdesc}
1162
1163
1164  \begin{funcdesc}{boundary\_statistics}{???}
1165
1166  \end{funcdesc}
1167 
1168 
1169  \begin{funcdesc}{get_quantity}{???}
1170  Module: \code{pyvolution.domain} 
1171  Allow access to individual quantities and their methods
1172 
1173  \end{funcdesc} 
1174 
1175 
1176  \begin{funcdesc}{get_values}{???}
1177  Module: \code{pyvolution.quantity}   
1178 
1179  Extract values for quantity as an array
1180 
1181  \end{funcdesc}   
1182 
1183 
1184  \begin{funcdesc}{get_integral}{???}
1185  Module: \code{pyvolution.quantity}   
1186 
1187  Return computed integral over entire domain for this quantity
1188 
1189  \end{funcdesc}     
1190 
1191 
1192\section{Other} 
1193
1194  \begin{funcdesc}{domain.create_quantity_from_expression}{???} 
1195 
1196  Handy for creating derived quantities on-the-fly. 
1197  See \code{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
1198  \end{funcdesc}       
1199
1200%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1201%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1202
1203\chapter{\anuga System Architecture}
1204
1205From pyvolution/documentation
1206
1207\section{File Formats}
1208\label{sec:file formats}
1209
1210\anuga makes use of a number of different file formats. The
1211following table lists all these formats, which are described in more
1212detail in the paragraphs below.
1213
1214\bigskip
1215
1216\begin{center}
1217
1218\begin{tabular}{|ll|}  \hline
1219
1220\textbf{Extension} & \textbf{Description} \\
1221\hline\hline
1222
1223\code{.sww} & NetCDF format for storing model output
1224\code{f(t,x,y)}\\
1225
1226\code{.tms} & NetCDF format for storing time series \code{f(t)}\\
1227
1228\code{.xya} & ASCII format for storing arbitrary points and
1229associated attributes\\
1230
1231\code{.pts} & NetCDF format for storing arbitrary points and
1232associated attributes\\
1233
1234\code{.asc} & ASCII format of regular DEMs as output from ArcView\\
1235
1236\code{.prj} & Associated ArcView file giving more metadata for
1237\code{.asc} format\\
1238
1239\code{.ers} & ERMapper header format of regular DEMs for ArcView\\
1240
1241\code{.dem} & NetCDF representation of regular DEM data\\
1242
1243\code{.tsh} & ASCII format for storing meshes and associated
1244boundary and region info\\
1245
1246\code{.msh} & NetCDF format for storing meshes and associated
1247boundary and region info\\
1248
1249\code{.nc} & Native ferret NetCDF format\\
1250
1251\code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
1252%\caption{File formats used by \anuga}
1253\end{tabular}
1254
1255
1256\end{center}
1257
1258\bigskip
1259
1260A typical dataflow can be described as follows:
1261
1262\subsection{Manually Created Files}
1263
1264\begin{tabular}{ll}
1265ASC, PRJ & Digital elevation models (gridded)\\
1266TSH & Triangular
1267meshes (e.g. created from \code{pmesh})\\
1268NC & Model outputs for use as boundary conditions (e.g. from MOST)
1269\end{tabular}
1270
1271\subsection{Automatically Created Files}
1272
1273\begin{tabular}{ll}
1274ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
1275DEMs to native \code{.pts} file\\
1276
1277NC $\rightarrow$ SWW & Convert MOST boundary files to
1278boundary \code{.sww}\\
1279
1280PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
1281
1282TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
1283Swollen\\
1284
1285TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
1286\code{pyvolution}
1287\end{tabular}
1288
1289
1290\subsection{Basic file conversions}
1291
1292  \begin{funcdesc}{sww2dem}{???}
1293  Module: \code{pyvolution.data\_manager}   
1294 
1295 
1296  \end{funcdesc}     
1297
1298 
1299  \begin{funcdesc}{dem2pts}{???}
1300  Module: \code{pyvolution.data_manager}   
1301 
1302 
1303  \end{funcdesc}       
1304
1305%\[
1306%  \left[
1307%  \begin{array}{ccr}
1308%  2 & 4 & 4\\
1309%  1 & 1 & 1
1310%  \end{array}
1311%  \right]
1312%\]
1313
1314%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1315%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1316
1317\chapter{Basic \anuga Assumptions}
1318
1319(From pyvolution/documentation)
1320
1321
1322Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
1323If one wished to recreate scenarios prior to that date it must be done
1324using some relative time (e.g. 0).
1325
1326
1327All spatial data relates to the WGS84 datum (or GDA94) and has been
1328projected into UTM with false easting of 500000 and false northing of
13291000000 on the southern hemisphere (0 on the northern).
1330
1331It is assumed that all computations take place within one UTM zone.
1332
1333DEMs, meshes and boundary conditions can have different origins within
1334one UTM zone. However, the computation will use that of the mesh for
1335numerical stability.
1336
1337
1338%OLD
1339%The dataflow is: (See data_manager.py and from scenarios)
1340%
1341%
1342%Simulation scenarios
1343%--------------------%
1344%%
1345%
1346%Sub directories contain scrips and derived files for each simulation.
1347%The directory ../source_data contains large source files such as
1348%DEMs provided externally as well as MOST tsunami simulations to be used
1349%as boundary conditions.
1350%
1351%Manual steps are:
1352%  Creation of DEMs from argcview (.asc + .prj)
1353%  Creation of mesh from pmesh (.tsh)
1354%  Creation of tsunami simulations from MOST (.nc)
1355%%
1356%
1357%Typical scripted steps are%
1358%
1359%  prepare_dem.py:  Convert asc and prj files supplied by arcview to
1360%                   native dem and pts formats%
1361%
1362%  prepare_pts.py: Convert netcdf output from MOST to an sww file suitable
1363%                  as boundary condition%
1364%
1365%  prepare_mesh.py: Merge DEM (pts) and mesh (tsh) using least squares
1366%                   smoothing. The outputs are tsh files with elevation data.%
1367%
1368%  run_simulation.py: Use the above together with various parameters to
1369%                     run inundation simulation.
1370
1371
1372%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1373%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1374
1375\appendix
1376
1377\chapter{Supporting Tools}
1378
1379This section describes a number of supporting tools, supplied with \anuga, that offer a
1380variety of types of functionality and enhance the basic capabilities of \anuga.
1381
1382\section{caching}
1383
1384  The \code{cache} function is used to provide supervised caching of function results. A Python
1385  function call of the form
1386
1387      {\small \begin{verbatim}
1388      result = func(arg1,...,argn)
1389      \end{verbatim}}
1390
1391  can be replaced by
1392
1393      {\small \begin{verbatim}
1394      from caching import cache
1395      result = cache(func,(arg1,...,argn))
1396      \end{verbatim}}
1397
1398  which returns the same output but reuses cached
1399  results if the function has been computed previously in the same context.
1400  \code{result} and the arguments can be simple types, tuples, list, dictionaries or
1401  objects, but not unhashable types such as functions or open file objects.
1402  The function \code{func} may be a member function of an object or a module.
1403
1404  This type of caching is particularly useful for computationally intensive
1405  functions with few frequently used combinations of input arguments. Note that
1406  if the inputs or output are very large caching may not save time because
1407  disc access may dominate the execution time.
1408
1409  If the function definition changes after a result has been cached, this will be
1410  detected by examining the functions \code{bytecode (co_code, co_consts,
1411  func_defualts, co_argcount)} and the function will be recomputed.
1412
1413  Options are set by means of the function \code{set_option(key, value)},
1414  where \code{key} is a key associated with a
1415  Python dictionary \code{options}. This dictionary stores settings such as the name of
1416  the directory used, the maximum
1417  number of cached files allowed, and so on.
1418
1419  The \code{cache} function allows the user also to specify a list of dependent files. If any of these
1420  have been changed, the function is recomputed and the results stored again.
1421
1422  %Other features include support for compression and a capability to \ldots
1423
1424
1425   \textbf{USAGE:}
1426
1427    {\small \begin{verbatim}
1428    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
1429                   compression, evaluate, test, return_filename)
1430    \end{verbatim}}
1431
1432 
1433\section{swollen}
1434The output generated by \anuga may be viewed by means of the visualisation tool \code{swollen},
1435which takes the \code{sww} file output by \anuga and creates a visual representation of the data.
1436Examples may be seen in Figures \ref{fig:bedslopestart} and \ref{fig:bedslope2}.
1437To view an \code{sww} file with \code{swollen} in the
1438Windows environment, you can simply drag the icon representing the file over an icon on the desktop
1439for the \code{swollen} executable file (or a shortcut to it). Alternatively, you can operate \code{swollen}
1440from the command line, in both Windows and Linux environments.
1441
1442On successful operation, you will see an interactive moving-picture display. You can use keys and the mouse
1443to slow down, speed up or stop the display, change the viewing position or carry out a number of other
1444simple operations.
1445 
1446The main keys operating the interactive screen are:\\
1447
1448\begin{tabular}{|ll|}   \hline
1449
1450\code{w} & toggle wireframe\\
1451
1452space bar & start/stop\\
1453
1454up/down arrows & increase/decrease speed\\
1455
1456left/right arrows & direction in time \emph{(when running)}\\ & step through simulation \emph{(when stopped)}\\
1457
1458left mouse button & rotate\\
1459
1460middle mouse button & pan\\
1461
1462right mouse button & zoom\\  \hline
1463
1464\end{tabular}
1465
1466\vfill
1467
1468The following table describes how to operate swollen from the command line:
1469
1470Usage: \code{swollen [options] swwfile \ldots}\\  \nopagebreak
1471Options:\\  \nopagebreak
1472\begin{tabular}{ll}
1473  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY_CENTER |}\\
1474                                    & \code{HEAD_MOUNTED_DISPLAY}\\
1475  \code{--rgba} & Request a RGBA colour buffer visual\\
1476  \code{--stencil} & Request a stencil buffer visual\\
1477  \code{--stereo} & Use default stereo mode which is \code{ANAGLYPHIC} if not \\
1478                                    & overridden by environmental variable\\
1479  \code{--stereo <mode>} & \code{ANAGLYPHIC | QUAD_BUFFER | HORIZONTAL_SPLIT |}\\
1480                                    & \code{VERTICAL_SPLIT | LEFT_EYE | RIGHT_EYE |}\\
1481                                     & \code{ON | OFF} \\
1482  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
1483  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
1484  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
1485  \code{-help} & Display this information\\
1486  \code{-hmax <float>} & Height above which transparency is set to
1487                                     \code{alphamax}\\
1488  \code{-hmin <float>} & Height below which transparency is set to
1489                                     zero\\
1490  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
1491                                     up, default is overhead)\\
1492  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
1493  \code{-movie <dirname>} & Save numbered images to named directory and
1494                                     quit\\
1495  \code{-nosky} & Omit background sky\\
1496  \code{-scale <float>} & Vertical scale factor\\
1497  \code{-texture <file>} & Image to use for bedslope topography\\
1498  \code{-tps <rate>} & Timesteps per second\\
1499  \code{-version} & Revision number and creation (not compile)
1500                                     date\\
1501\end{tabular}
1502
1503\section{utilities/polygons}
1504
1505  \begin{classdesc}{Polygon_function}{regions, default = 0.0, geo_reference = None}
1506  Module: \code{utilities.polygon} 
1507 
1508 
1509  \end{classdesc}
1510 
1511  \begin{funcdesc}{read_polygon}{filename}
1512  Module: \code{utilities.polygon} 
1513 
1514  Reads the specified file and returns a polygon. Each
1515  line of the file must contain exactly two numbers, separated by a comma, which are interpreted
1516  as coordinates of one vertex of the polygon.
1517  \end{funcdesc}
1518 
1519  \begin{funcdesc}{populate_polygon}{polygon, number_of_points, seed = None, exclude = None}
1520  Module: \code{utilities.polygon} 
1521 
1522  Populates the interior of the specified polygon with the specified number of points,
1523  selected by means of a uniform distribution function.
1524  \end{funcdesc}
1525 
1526  \begin{funcdesc}{point_in_polygon}{polygon, delta=1e-8}
1527  Module: \code{utilities.polygon} 
1528 
1529  Returns a point inside the specified polygon and close to the edge. The distance between
1530  the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the
1531  second argument \code{delta}, which is taken as $10^{-8}$ by default.
1532  \end{funcdesc}
1533 
1534  \begin{funcdesc}{inside_polygon}{points, polygon, closed = True, verbose = False}
1535  Module: \code{utilities.polygon} 
1536 
1537  Used to test whether a single point---or the members of a list of points---
1538  are inside the specified polygon. If the first argument is a single point,
1539  returns \code{True} if the point is inside the polygon, or \code{False}
1540  otherwise. If the first argument is a list of points, returns a Numeric
1541  array comprising the indices of the points in the list that lie inside the polygon.
1542  (If none of the points are inside, returns \code{zeros((0,), 'l')}.)
1543  Points on the edges of the polygon are regarded as inside if
1544  \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
1545  \end{funcdesc}
1546 
1547  \begin{funcdesc}{outside_polygon}{points, polygon, closed = True, verbose = False}
1548  Module: \code{utilities.polygon} 
1549 
1550  Exactly like \code{inside_polygon}, but with the words `inside' and `outside' interchanged.
1551  \end{funcdesc}
1552 
1553  \begin{funcdesc}{point_on_line}{x, y, x0, y0, x1, y1}
1554  Module: \code{utilities.polygon}
1555 
1556  Returns \code{True} or \code{False}, depending on whether the point with coordinates
1557  \code{x, y} is on the line passing through the points with coordinates \code{x0, y0} 
1558  and \code{x1, y1} (extended if necessary at either end).
1559  \end{funcdesc}
1560 
1561  \begin{funcdesc}{separate_points_by_polygon}{points, polygon,
1562                               closed = True, verbose = False}\indexedcode{separate_points_by_polygon}
1563  Module: \code{utilities.polygon} 
1564 
1565  \end{funcdesc}
1566   
1567
1568
1569\section{coordinate_transforms}
1570
1571\section{geo_spatial_data}
1572
1573This describes a class that represents arbitrary point data in UTM
1574coordinates along with named attribute values.
1575
1576TBA
1577
1578\section{pmesh GUI}
1579
1580\section{alpha_shape}
1581
1582
1583\section{utilities/numerical_tools} Do now.
1584
1585\begin{itemize}
1586  \item \indexedcode{ensure_numeric}
1587  \item \indexedcode{mean}
1588  \item
1589\end{itemize}
1590
1591%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1592
1593\chapter{Glossary}
1594
1595\begin{itemize}
1596    \item \indexedbold{\anuga} Name of software (joint development between ANU and GA)
1597
1598    \item \indexedbold{domain}
1599
1600    \item \indexedbold{Dirichlet boundary}
1601
1602    \item \indexedbold{elevation} - refers to bathymetry and topography
1603
1604    \item \indexedbold{bathymetry} offshore
1605
1606    \item \indexedbold{topography} onshore
1607
1608    \item \indexedbold{evolution} integration of the shallow water wave equations over time
1609
1610    \item \indexedbold{forcing term}
1611
1612    \item \indexedbold{IDLE} Development environment shipped with Python
1613
1614    \item \indexedbold{Manning friction coefficient}
1615
1616    \item \indexedbold{mesh}    Triangulation of domain
1617
1618    \item \indexedbold{meshfile}  [generic word for either .tsh or
1619    .msh file]
1620
1621    \item \indexedbold{points file}  [generic word for either .pts or
1622    .xya file]
1623
1624    \item \indexedbold{grid} evenly spaced
1625
1626    \item \indexedbold{NetCDF}
1627
1628    \item \indexedbold{pmesh} does this really need to be here? it's a class/module?
1629
1630    \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?
1631
1632    \item \indexedbold{conserved quantity} conserved (state, x and y momentum)
1633
1634    \item \indexedbold{reflective boundary}
1635
1636    \item \indexedbold{smoothing} is this really needed?
1637
1638    \item \indexedbold{stage}
1639
1640%    \item \indexedbold{try this}
1641
1642    \item \indexedbold{swollen} visualisation tool
1643
1644    \item \indexedbold{time boundary} defined in the manual (flog from there)
1645
1646    \item \indexedbold{transmissive boundary} defined in the manual (flog from there)
1647
1648    \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
1649
1650    \item \indexedbold{ymomentum}  conserved quantity
1651
1652    \item \indexedbold{resolution}   The maximal area of a triangular cell in a mesh
1653
1654    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created
1655    in this way.)
1656    \anuga represents a polygon in one of two ways. One way is to represent it as a
1657    list whose members are either Python tuples
1658    or Python lists of length 2. The unit square, for example, would be represented by the
1659    list
1660    [ [0,0], [1,0], [1,1], [0,1] ]. The alternative is to represent it as an
1661    $N \times 2$ Numeric array, where $N$ is the number of points.
1662
1663    NOTE: More can be read in the module utilities/polygon.py ....
1664
1665    \item \indexedbold{easting}
1666
1667    \item \indexedbold{northing}
1668
1669    \item \indexedbold{latitude}
1670
1671    \item \indexedbold{longitude}
1672
1673    \item \indexedbold{edge}
1674
1675    \item \indexedbold{vertex}
1676
1677    \item \indexedbold{finite volume}
1678
1679    \item \indexedbold{flux}
1680
1681    \item \indexedbold{Digital Elevation Model (DEM)}
1682
1683
1684\end{itemize}
1685
1686The \code{\e appendix} markup need not be repeated for additional
1687appendices.
1688
1689
1690%
1691%  The ugly "%begin{latexonly}" pseudo-environments are really just to
1692%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
1693%  not really valuable.
1694%
1695%  If you don't want the Module Index, you can remove all of this up
1696%  until the second \input line.
1697%
1698
1699%begin{latexonly}
1700%\renewcommand{\indexname}{Module Index}
1701%end{latexonly}
1702%\input{mod\jobname.ind}        % Module Index
1703
1704%begin{latexonly}
1705\renewcommand{\indexname}{Index}
1706%end{latexonly}
1707\input{\jobname.ind}            % Index
1708
1709
1710
1711\end{document}
Note: See TracBrowser for help on using the repository browser.