source: documentation/user_manual/anuga_user_manual.tex @ 2574

Last change on this file since 2574 was 2574, checked in by ole, 18 years ago

From meeting with Howard

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