source: documentation/user_manual/anuga_user_manual.tex @ 2637

Last change on this file since 2637 was 2637, checked in by steve, 18 years ago
  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 61.5 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-30 09:20:39 +0000 (Thu, 30 Mar 2006) $
57%$LastChangedRevision: 2637 $
58%$LastChangedBy: steve $
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}{name}
912    Module: \code{pyvolution.domain}
913
914    Assigns the name \code{name} to the domain
915\end{funcdesc}
916
917\begin{funcdesc} {get\_name}{}
918    Module: \code{pyvolution.domain}
919
920    Returns the name assigned to the domain by \code{set_name}. If no name has been
921    assigned, returns `domain'.
922\end{funcdesc}
923
924\begin{funcdesc} {set\_datadir}{name}
925    Module: \code{pyvolution.domain}
926
927    Sets the directory used for data to the value \code{name}. The default value, before
928    \code{set\_datadir} is run, is the value \code{default_datadir}
929    specified in \code{config.py}.
930\end{funcdesc}
931
932\begin{funcdesc} {get_datadir}{}
933    Module: \code{pyvolution.domain}
934
935    Returns the data directory set by \code{set\_datadir} or, if \code{set\_datadir} has not
936    been run, returns the value \code{default_datadir} specified in
937    \code{config.py}.
938\end{funcdesc}
939
940\begin{funcdesc} {set_time}{??}
941\end{funcdesc}
942
943\begin{funcdesc} {set_default_order}{??}
944\end{funcdesc}
945
946
947%%%%%%
948\section{Setting Quantities}
949
950\begin{funcdesc}{set\_quantity}{name,
951    numeric = None,
952    quantity = None,
953    function = None,
954    geospatial_data = None,
955    filename = None,
956    attribute_name = None,
957    alpha = None,
958    location = 'vertices',
959    indices = None,
960    verbose = False,
961    use_cache = False}
962  Module: \code{pyvolution.domain}
963  (see also \code{pyvolution.quantity.set_values})
964
965This function is used to assign values to individual quantities for a
966domain. It is very flexible and can be used with many data types: a
967statement of the form \code{domain.set\_quantity(name, x)} can be used
968to define a quantity having the name \code{name}, where the other
969argument \code{x} can be any of the following:
970
971\begin{itemize}
972\item a number, in which case all vertices in the mesh gets that for
973the quantity in question.
974\item a list of numbers or a Numeric array ordered the same way as the mesh vertices.
975\item a function (e.g.\ see the samples introduced in Chapter 2)
976\item an expression composed of other quantities and numbers, arrays, lists (for
977example, a linear combination of quantities)
978\item the name of a file from which the data can be read. In this case, the optional argument attribute_name will select which attribute to use from the file. If left out, set_quantity will pick one. This is useful in cases where there is only one attribute.
979\item a geospatial dataset (See ?????). Optional argument attribute_name applies here as with files.
980\end{itemize}
981
982
983Exactly one of the arguments
984  numeric, quantity, function, points, filename
985must be present.
986
987
988Set quantity will look at the type of the second argument (\code{numeric}) and
989determine what action to take.
990
991Values can also be set using the appropriate keyword arguments.
992If x is a function, for example, \code{domain.set\_quantity(name, x)}, \code{domain.set\_quantity(name, numeric=x)}, and \code{domain.set\_quantity(name, function=x)}
993are all equivalent.
994
995
996Other optional arguments are
997\begin{itemize}
998\item \code{indices} which is a list of ids of triangles to which set_quantity should apply its assignment of values.
999\item \code{location} determines which part of the triangles to assign to. Options are 'vertices' (default), 'edges', and 'centroids'.
1000\end{itemize}
1001
1002
1003a number, in which case all vertices in the mesh gets that for
1004the quantity in question.
1005\item a list of numbers or a Numeric array ordered the same way as the mesh vertices.
1006
1007
1008\end{funcdesc}
1009
1010
1011
1012
1013
1014
1015
1016%%%
1017\anuga provides a number of predefined initial conditions to be used
1018with \code{set_quantity}.
1019
1020\begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None,
1021                x0=0.0, y0=0.0, alpha=0.0,
1022                gravity=9.8, gamma=1.85,
1023                massco=1, dragco=1, frictionco=0, psi=0,
1024                dx=None, kappa=3.0, kappad=0.8, zsmall=0.01,
1025                domain=None,
1026                verbose=False}
1027This function returns a callable object representing an initial water
1028displacement generated by a submarine sediment slide.
1029
1030The arguments include the downslope slide length, the water depth to the slide centre of mass,
1031and the bathymetric slope.
1032\end{funcdesc}
1033
1034
1035%%%
1036\begin{funcdesc}{file_function}{filename,
1037                  domain = None,
1038                  quantities = None,
1039                  interpolation_points = None,
1040                  verbose = False,
1041                  use_cache = False}
1042Module: \code{pyvolution.util}
1043
1044Reads the time history of spatial data from NetCDF file and returns
1045a callable object. Returns interpolated values based on the input
1046file using the underlying \code{interpolation\_function}.
1047
1048\code{quantities} is either the name of a single quantity to be
1049interpolated or a list of such quantity names. In the second case, the resulting
1050function will return a tuple of values---one for each quantity.
1051
1052\code{interpolation\_points} is a list of absolute UTM coordinates
1053for points at which values are sought.
1054\end{funcdesc}
1055
1056%%%
1057\begin{classdesc}{Interpolation\_function}{self,
1058                 time,
1059                 quantities,
1060                 quantity_names = None,
1061                 vertex_coordinates = None,
1062                 triangles = None,
1063                 interpolation_points = None,
1064                 verbose = False}
1065Module: \code{pyvolution.least\_squares}
1066
1067Given a time series, either as a sequence of numbers or
1068defined at the vertices of a triangular mesh (such
1069as those stored in \code{sww} files), \code{Interpolation\_function}
1070is used to create a callable object that interpolates a value for
1071an arbitrary time \code{t} within the model limits and possibly a
1072point \code{(x, y)} within a mesh region.
1073
1074The actual time series at which data is available is specified by means
1075of an array \code{time} of monotonically increasing times.
1076The quantities containing the values to be interpolated are specified in
1077an array---or dictionary of arrays (used in conjunction with the optional argument
1078\code{quantitity\_names}) --- called \code{quantities}.
1079The optional arguments \code{vertex_coordinates} and \code{triangles} represent
1080the spatial mesh associated with the quantity arrays. If omitted the function created
1081by \code{Interpolation\_function} will be a function of \code{t} only.
1082
1083
1084Since, in practice, values need to be computed at specified
1085points, the syntax allows the user to specify, once and for all, a list
1086\code{interpolation\_points} of points at which values are required. In this case,
1087the function may be called using the form \code{f(t, id)}, where \code{id} is an
1088index identifying a member of \code{interpolation\_points}.
1089
1090
1091
1092
1093
1094\end{classdesc}
1095
1096%%%
1097\begin{funcdesc}{set\_region}{functions}
1098[Low priority. Will be merged into set\_quantity]
1099
1100Module:\code{pyvolution.domain}
1101\end{funcdesc}
1102
1103
1104
1105%%%%%%
1106\section{Boundary Conditions}
1107
1108\anuga provides a large number of predefined boundary conditions,
1109represented by objects such as \code{Reflective\_boundary(domain)} and
1110\code{Dirichlet\_boundary([0.2, 0.0, 0.0])}, described in the examples
1111in Chapter 2. Alternatively, you may prefer to ``roll your own'',
1112following the method explained in Section \ref{sec:roll your own}.
1113
1114These boundary objects may be used with the function \code{set\_boundary} described below
1115to assign boundary conditions according to the tags used to label boundary segments.
1116
1117\begin{funcdesc}{set\_boundary}{boundary_map}
1118Module: \code{pyvolution.domain}
1119
1120This function allows you to assign a boundary object (corresponding to a
1121pre-defined or user-specified boundary condition) to every boundary segment that
1122has been assigned a particular tag.
1123
1124This is done by specifying a dictionary \code{boundary\_map}, whose values are the boundary objects
1125and whose keys are the symbolic tags.
1126
1127\end{funcdesc}
1128
1129\begin{funcdesc} {get_boundary_tags}{}
1130Module: \code{pyvolution.mesh}
1131\end{funcdesc}
1132
1133%%%
1134\subsection{Predefined boundary conditions}
1135
1136\begin{classdesc}{Reflective_boundary}{Boundary}
1137Module: \code{pyvolution.shallow\_water}
1138
1139Reflective boundary returns same conserved quantities as those present in
1140the neighbouring volume but reflected.
1141
1142This class is specific to the shallow water equation as it works with the
1143momentum quantities assumed to be the second and third conserved quantities.
1144\end{classdesc}
1145
1146%%%
1147\begin{classdesc}{Transmissive_boundary}{domain = None}
1148Module: \code{pyvolution.generic\_boundary\_conditions}
1149
1150A transmissive boundary returns the same conserved quantities as
1151those present in the neighbouring volume.
1152
1153The underlying domain must be specified when the boundary is instantiated.
1154\end{classdesc}
1155
1156%%%
1157\begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None}
1158Module: \code{pyvolution.generic\_boundary\_conditions}
1159
1160A Dirichlet boundary returns constant values for the conserved
1161quantities.
1162\end{classdesc}
1163
1164%%%
1165\begin{classdesc}{Time_boundary}{domain = None, f = None}
1166Module: \code{pyvolution.generic\_boundary\_conditions}
1167
1168A time-dependent boundary returns values for the conserved
1169quantities as a function \code{f(t)} of time. The user must specify
1170the domain to get access to the model time.
1171\end{classdesc}
1172
1173%%%
1174\begin{classdesc}{File_boundary}{Boundary}
1175Module: \code{pyvolution.generic\_boundary\_conditions}
1176
1177The boundary values are obtained from a file and interpolated. The
1178file is assumed to contain a time series and possibly also spatial
1179information. The conserved quantities are given as a function of
1180time.
1181\end{classdesc}
1182
1183
1184\subsection{User-defined boundary conditions}
1185\label{sec:roll your own}
1186[How to roll your own]
1187
1188
1189
1190
1191
1192\section{Forcing Functions}
1193
1194\anuga provides a number of predefined forcing functions to be used with .....
1195
1196%\begin{itemize}
1197
1198
1199%  \item \indexedcode{}
1200%  [function, arguments]
1201
1202%  \item \indexedcode{}
1203
1204%\end{itemize}
1205
1206
1207
1208\section{Evolution}
1209
1210  \begin{funcdesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
1211
1212  Module: pyvolution.domain
1213
1214  This function (a method of \code{domain}) is invoked once all the preliminaries have been
1215  completed, and causes the model to progress through successive steps in its evolution, storing results and
1216  outputting statistics whenever a user-specified period \code{yieldstep} is completed (generally
1217  during this period the model will evolve through several steps internally). The user specifies
1218  the total time period over which the evolution is to take place, by specifying values (in seconds) for either
1219  \code{duration} or \code{finaltime}, as well as the interval in seconds after which results are to be
1220  stored and statistics output.
1221
1222  You can include \code{evolve} in a statement of the type:
1223
1224  {\small \begin{verbatim}
1225      for t in domain.evolve(yieldstep, finaltime):
1226          <Do something with domain and t>
1227  \end{verbatim}}
1228
1229  \end{funcdesc}
1230
1231
1232
1233\subsection{Diagnostics}
1234
1235  \begin{funcdesc}{timestepping_statistics}{???}
1236
1237  \end{funcdesc}
1238
1239
1240  \begin{funcdesc}{boundary\_statistics}{???}
1241
1242  \end{funcdesc}
1243
1244
1245  \begin{funcdesc}{get_quantity}{???}
1246  Module: \code{pyvolution.domain}
1247  Allow access to individual quantities and their methods
1248
1249  \end{funcdesc}
1250
1251
1252  \begin{funcdesc}{get_values}{???}
1253  Module: \code{pyvolution.quantity}
1254
1255  Extract values for quantity as an array
1256
1257  \end{funcdesc}
1258
1259
1260  \begin{funcdesc}{get_integral}{???}
1261  Module: \code{pyvolution.quantity}
1262
1263  Return computed integral over entire domain for this quantity
1264
1265  \end{funcdesc}
1266
1267
1268\section{Other}
1269
1270  \begin{funcdesc}{domain.create_quantity_from_expression}{???}
1271
1272  Handy for creating derived quantities on-the-fly.
1273  See \code{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
1274  \end{funcdesc}
1275
1276%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1277%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1278
1279\chapter{\anuga System Architecture}
1280
1281From pyvolution/documentation
1282
1283\section{File Formats}
1284\label{sec:file formats}
1285
1286\anuga makes use of a number of different file formats. The
1287following table lists all these formats, which are described in more
1288detail in the paragraphs below.
1289
1290\bigskip
1291
1292\begin{center}
1293
1294\begin{tabular}{|ll|}  \hline
1295
1296\textbf{Extension} & \textbf{Description} \\
1297\hline\hline
1298
1299\code{.sww} & NetCDF format for storing model output
1300\code{f(t,x,y)}\\
1301
1302\code{.tms} & NetCDF format for storing time series \code{f(t)}\\
1303
1304\code{.xya} & ASCII format for storing arbitrary points and
1305associated attributes\\
1306
1307\code{.pts} & NetCDF format for storing arbitrary points and
1308associated attributes\\
1309
1310\code{.asc} & ASCII format of regular DEMs as output from ArcView\\
1311
1312\code{.prj} & Associated ArcView file giving more metadata for
1313\code{.asc} format\\
1314
1315\code{.ers} & ERMapper header format of regular DEMs for ArcView\\
1316
1317\code{.dem} & NetCDF representation of regular DEM data\\
1318
1319\code{.tsh} & ASCII format for storing meshes and associated
1320boundary and region info\\
1321
1322\code{.msh} & NetCDF format for storing meshes and associated
1323boundary and region info\\
1324
1325\code{.nc} & Native ferret NetCDF format\\
1326
1327\code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
1328%\caption{File formats used by \anuga}
1329\end{tabular}
1330
1331
1332\end{center}
1333
1334\bigskip
1335
1336A typical dataflow can be described as follows:
1337
1338\subsection{Manually Created Files}
1339
1340\begin{tabular}{ll}
1341ASC, PRJ & Digital elevation models (gridded)\\
1342TSH & Triangular
1343meshes (e.g. created from \code{pmesh})\\
1344NC & Model outputs for use as boundary conditions (e.g. from MOST)
1345\end{tabular}
1346
1347\subsection{Automatically Created Files}
1348
1349\begin{tabular}{ll}
1350ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
1351DEMs to native \code{.pts} file\\
1352
1353NC $\rightarrow$ SWW & Convert MOST boundary files to
1354boundary \code{.sww}\\
1355
1356PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
1357
1358TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
1359Swollen\\
1360
1361TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
1362\code{pyvolution}
1363\end{tabular}
1364
1365
1366\subsection{Basic file conversions}
1367
1368  \begin{funcdesc}{sww2dem}{???}
1369  Module: \code{pyvolution.data\_manager}
1370
1371
1372  \end{funcdesc}
1373
1374
1375  \begin{funcdesc}{dem2pts}{???}
1376  Module: \code{pyvolution.data_manager}
1377
1378
1379  \end{funcdesc}
1380
1381%\[
1382%  \left[
1383%  \begin{array}{ccr}
1384%  2 & 4 & 4\\
1385%  1 & 1 & 1
1386%  \end{array}
1387%  \right]
1388%\]
1389
1390%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1391%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1392
1393\chapter{Basic \anuga Assumptions}
1394
1395(From pyvolution/documentation)
1396
1397
1398Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
1399If one wished to recreate scenarios prior to that date it must be done
1400using some relative time (e.g. 0).
1401
1402
1403All spatial data relates to the WGS84 datum (or GDA94) and has been
1404projected into UTM with false easting of 500000 and false northing of
14051000000 on the southern hemisphere (0 on the northern).
1406
1407It is assumed that all computations take place within one UTM zone.
1408
1409DEMs, meshes and boundary conditions can have different origins within
1410one UTM zone. However, the computation will use that of the mesh for
1411numerical stability.
1412
1413
1414%OLD
1415%The dataflow is: (See data_manager.py and from scenarios)
1416%
1417%
1418%Simulation scenarios
1419%--------------------%
1420%%
1421%
1422%Sub directories contain scrips and derived files for each simulation.
1423%The directory ../source_data contains large source files such as
1424%DEMs provided externally as well as MOST tsunami simulations to be used
1425%as boundary conditions.
1426%
1427%Manual steps are:
1428%  Creation of DEMs from argcview (.asc + .prj)
1429%  Creation of mesh from pmesh (.tsh)
1430%  Creation of tsunami simulations from MOST (.nc)
1431%%
1432%
1433%Typical scripted steps are%
1434%
1435%  prepare_dem.py:  Convert asc and prj files supplied by arcview to
1436%                   native dem and pts formats%
1437%
1438%  prepare_pts.py: Convert netcdf output from MOST to an sww file suitable
1439%                  as boundary condition%
1440%
1441%  prepare_mesh.py: Merge DEM (pts) and mesh (tsh) using least squares
1442%                   smoothing. The outputs are tsh files with elevation data.%
1443%
1444%  run_simulation.py: Use the above together with various parameters to
1445%                     run inundation simulation.
1446
1447
1448%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1449%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1450
1451\appendix
1452
1453\chapter{Supporting Tools}
1454
1455This section describes a number of supporting tools, supplied with \anuga, that offer a
1456variety of types of functionality and enhance the basic capabilities of \anuga.
1457
1458\section{caching}
1459
1460  The \code{cache} function is used to provide supervised caching of function results. A Python
1461  function call of the form
1462
1463      {\small \begin{verbatim}
1464      result = func(arg1,...,argn)
1465      \end{verbatim}}
1466
1467  can be replaced by
1468
1469      {\small \begin{verbatim}
1470      from caching import cache
1471      result = cache(func,(arg1,...,argn))
1472      \end{verbatim}}
1473
1474  which returns the same output but reuses cached
1475  results if the function has been computed previously in the same context.
1476  \code{result} and the arguments can be simple types, tuples, list, dictionaries or
1477  objects, but not unhashable types such as functions or open file objects.
1478  The function \code{func} may be a member function of an object or a module.
1479
1480  This type of caching is particularly useful for computationally intensive
1481  functions with few frequently used combinations of input arguments. Note that
1482  if the inputs or output are very large caching may not save time because
1483  disc access may dominate the execution time.
1484
1485  If the function definition changes after a result has been cached, this will be
1486  detected by examining the functions \code{bytecode (co_code, co_consts,
1487  func_defualts, co_argcount)} and the function will be recomputed.
1488
1489  Options are set by means of the function \code{set_option(key, value)},
1490  where \code{key} is a key associated with a
1491  Python dictionary \code{options}. This dictionary stores settings such as the name of
1492  the directory used, the maximum
1493  number of cached files allowed, and so on.
1494
1495  The \code{cache} function allows the user also to specify a list of dependent files. If any of these
1496  have been changed, the function is recomputed and the results stored again.
1497
1498  %Other features include support for compression and a capability to \ldots
1499
1500
1501   \textbf{USAGE:}
1502
1503    {\small \begin{verbatim}
1504    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
1505                   compression, evaluate, test, return_filename)
1506    \end{verbatim}}
1507
1508
1509\section{swollen}
1510The output generated by \anuga may be viewed by means of the visualisation tool \code{swollen},
1511which takes the \code{sww} file output by \anuga and creates a visual representation of the data.
1512Examples may be seen in Figures \ref{fig:bedslopestart} and \ref{fig:bedslope2}.
1513To view an \code{sww} file with \code{swollen} in the
1514Windows environment, you can simply drag the icon representing the file over an icon on the desktop
1515for the \code{swollen} executable file (or a shortcut to it). Alternatively, you can operate \code{swollen}
1516from the command line, in both Windows and Linux environments.
1517
1518On successful operation, you will see an interactive moving-picture display. You can use keys and the mouse
1519to slow down, speed up or stop the display, change the viewing position or carry out a number of other
1520simple operations.
1521
1522The main keys operating the interactive screen are:\\
1523
1524\begin{tabular}{|ll|}   \hline
1525
1526\code{w} & toggle wireframe\\
1527
1528space bar & start/stop\\
1529
1530up/down arrows & increase/decrease speed\\
1531
1532left/right arrows & direction in time \emph{(when running)}\\ & step through simulation \emph{(when stopped)}\\
1533
1534left mouse button & rotate\\
1535
1536middle mouse button & pan\\
1537
1538right mouse button & zoom\\  \hline
1539
1540\end{tabular}
1541
1542\vfill
1543
1544The following table describes how to operate swollen from the command line:
1545
1546Usage: \code{swollen [options] swwfile \ldots}\\  \nopagebreak
1547Options:\\  \nopagebreak
1548\begin{tabular}{ll}
1549  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY_CENTER |}\\
1550                                    & \code{HEAD_MOUNTED_DISPLAY}\\
1551  \code{--rgba} & Request a RGBA colour buffer visual\\
1552  \code{--stencil} & Request a stencil buffer visual\\
1553  \code{--stereo} & Use default stereo mode which is \code{ANAGLYPHIC} if not \\
1554                                    & overridden by environmental variable\\
1555  \code{--stereo <mode>} & \code{ANAGLYPHIC | QUAD_BUFFER | HORIZONTAL_SPLIT |}\\
1556                                    & \code{VERTICAL_SPLIT | LEFT_EYE | RIGHT_EYE |}\\
1557                                     & \code{ON | OFF} \\
1558  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
1559  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
1560  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
1561  \code{-help} & Display this information\\
1562  \code{-hmax <float>} & Height above which transparency is set to
1563                                     \code{alphamax}\\
1564  \code{-hmin <float>} & Height below which transparency is set to
1565                                     zero\\
1566  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
1567                                     up, default is overhead)\\
1568  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
1569  \code{-movie <dirname>} & Save numbered images to named directory and
1570                                     quit\\
1571  \code{-nosky} & Omit background sky\\
1572  \code{-scale <float>} & Vertical scale factor\\
1573  \code{-texture <file>} & Image to use for bedslope topography\\
1574  \code{-tps <rate>} & Timesteps per second\\
1575  \code{-version} & Revision number and creation (not compile)
1576                                     date\\
1577\end{tabular}
1578
1579\section{utilities/polygons}
1580
1581  \begin{classdesc}{Polygon_function}{regions, default = 0.0, geo_reference = None}
1582  Module: \code{utilities.polygon}
1583
1584
1585  \end{classdesc}
1586
1587  \begin{funcdesc}{read_polygon}{filename}
1588  Module: \code{utilities.polygon}
1589
1590  Reads the specified file and returns a polygon. Each
1591  line of the file must contain exactly two numbers, separated by a comma, which are interpreted
1592  as coordinates of one vertex of the polygon.
1593  \end{funcdesc}
1594
1595  \begin{funcdesc}{populate_polygon}{polygon, number_of_points, seed = None, exclude = None}
1596  Module: \code{utilities.polygon}
1597
1598  Populates the interior of the specified polygon with the specified number of points,
1599  selected by means of a uniform distribution function.
1600  \end{funcdesc}
1601
1602  \begin{funcdesc}{point_in_polygon}{polygon, delta=1e-8}
1603  Module: \code{utilities.polygon}
1604
1605  Returns a point inside the specified polygon and close to the edge. The distance between
1606  the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the
1607  second argument \code{delta}, which is taken as $10^{-8}$ by default.
1608  \end{funcdesc}
1609
1610  \begin{funcdesc}{inside_polygon}{points, polygon, closed = True, verbose = False}
1611  Module: \code{utilities.polygon}
1612
1613  Used to test whether a single point---or the members of a list of points---
1614  are inside the specified polygon. If the first argument is a single point,
1615  returns \code{True} if the point is inside the polygon, or \code{False}
1616  otherwise. If the first argument is a list of points, returns a Numeric
1617  array comprising the indices of the points in the list that lie inside the polygon.
1618  (If none of the points are inside, returns \code{zeros((0,), 'l')}.)
1619  Points on the edges of the polygon are regarded as inside if
1620  \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
1621  \end{funcdesc}
1622
1623  \begin{funcdesc}{outside_polygon}{points, polygon, closed = True, verbose = False}
1624  Module: \code{utilities.polygon}
1625
1626  Exactly like \code{inside_polygon}, but with the words `inside' and `outside' interchanged.
1627  \end{funcdesc}
1628
1629  \begin{funcdesc}{point_on_line}{x, y, x0, y0, x1, y1}
1630  Module: \code{utilities.polygon}
1631
1632  Returns \code{True} or \code{False}, depending on whether the point with coordinates
1633  \code{x, y} is on the line passing through the points with coordinates \code{x0, y0}
1634  and \code{x1, y1} (extended if necessary at either end).
1635  \end{funcdesc}
1636
1637  \begin{funcdesc}{separate_points_by_polygon}{points, polygon,
1638                               closed = True, verbose = False}\indexedcode{separate_points_by_polygon}
1639  Module: \code{utilities.polygon}
1640
1641  \end{funcdesc}
1642
1643
1644
1645\section{coordinate_transforms}
1646
1647\section{geo_spatial_data}
1648
1649This describes a class that represents arbitrary point data in UTM
1650coordinates along with named attribute values.
1651
1652TBA
1653
1654\section{pmesh GUI}
1655
1656\section{alpha_shape}
1657
1658
1659\section{utilities/numerical_tools} Do now.
1660
1661\begin{itemize}
1662  \item \indexedcode{ensure_numeric}
1663  \item \indexedcode{mean}
1664  \item
1665\end{itemize}
1666
1667%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1668
1669\chapter{Glossary}
1670
1671\begin{itemize}
1672    \item \indexedbold{\anuga} Name of software (joint development between ANU and GA)
1673
1674    \item \indexedbold{domain}
1675
1676    \item \indexedbold{Dirichlet boundary}
1677
1678    \item \indexedbold{elevation} - refers to bathymetry and topography
1679
1680    \item \indexedbold{bathymetry} offshore
1681
1682    \item \indexedbold{topography} onshore
1683
1684    \item \indexedbold{evolution} integration of the shallow water wave equations over time
1685
1686    \item \indexedbold{forcing term}
1687
1688    \item \indexedbold{IDLE} Development environment shipped with Python
1689
1690    \item \indexedbold{Manning friction coefficient}
1691
1692    \item \indexedbold{mesh}    Triangulation of domain
1693
1694    \item \indexedbold{meshfile}  [generic word for either .tsh or
1695    .msh file]
1696
1697    \item \indexedbold{points file}  [generic word for either .pts or
1698    .xya file]
1699
1700    \item \indexedbold{grid} evenly spaced
1701
1702    \item \indexedbold{NetCDF}
1703
1704    \item \indexedbold{pmesh} does this really need to be here? it's a class/module?
1705
1706    \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?
1707
1708    \item \indexedbold{conserved quantity} conserved (state, x and y momentum)
1709
1710    \item \indexedbold{reflective boundary}
1711
1712    \item \indexedbold{smoothing} is this really needed?
1713
1714    \item \indexedbold{stage}
1715
1716%    \item \indexedbold{try this}
1717
1718    \item \indexedbold{swollen} visualisation tool
1719
1720    \item \indexedbold{time boundary} defined in the manual (flog from there)
1721
1722    \item \indexedbold{transmissive boundary} defined in the manual (flog from there)
1723
1724    \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
1725
1726    \item \indexedbold{ymomentum}  conserved quantity
1727
1728    \item \indexedbold{resolution}   The maximal area of a triangular cell in a mesh
1729
1730    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created
1731    in this way.)
1732    \anuga represents a polygon in one of two ways. One way is to represent it as a
1733    list whose members are either Python tuples
1734    or Python lists of length 2. The unit square, for example, would be represented by the
1735    list
1736    [ [0,0], [1,0], [1,1], [0,1] ]. The alternative is to represent it as an
1737    $N \times 2$ Numeric array, where $N$ is the number of points.
1738
1739    NOTE: More can be read in the module utilities/polygon.py ....
1740
1741    \item \indexedbold{easting}
1742
1743    \item \indexedbold{northing}
1744
1745    \item \indexedbold{latitude}
1746
1747    \item \indexedbold{longitude}
1748
1749    \item \indexedbold{edge}
1750
1751    \item \indexedbold{vertex}
1752
1753    \item \indexedbold{finite volume}
1754
1755    \item \indexedbold{flux}
1756
1757    \item \indexedbold{Digital Elevation Model (DEM)}
1758
1759
1760\end{itemize}
1761
1762The \code{\e appendix} markup need not be repeated for additional
1763appendices.
1764
1765
1766%
1767%  The ugly "%begin{latexonly}" pseudo-environments are really just to
1768%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
1769%  not really valuable.
1770%
1771%  If you don't want the Module Index, you can remove all of this up
1772%  until the second \input line.
1773%
1774
1775%begin{latexonly}
1776%\renewcommand{\indexname}{Module Index}
1777%end{latexonly}
1778%\input{mod\jobname.ind}        % Module Index
1779
1780%begin{latexonly}
1781\renewcommand{\indexname}{Index}
1782%end{latexonly}
1783\input{\jobname.ind}            % Index
1784
1785
1786
1787\end{document}
Note: See TracBrowser for help on using the repository browser.