source: documentation/user_manual/anuga_user_manual.tex @ 2542

Last change on this file since 2542 was 2542, checked in by steve, 18 years ago

Small typos

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