source: documentation/user_manual/anuga_user_manual.tex @ 2921

Last change on this file since 2921 was 2921, checked in by sexton, 18 years ago

including references to new polygon things

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 85.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\usepackage{datetime}
21
22\input{definitions}
23
24\title{\anuga User Manual}
25\author{Geoscience Australia and the Australian National University}
26
27% Please at least include a long-lived email address;
28% the rest is at your discretion.
29\authoraddress{Geoscience Australia \\
30  Email: \email{ole.nielsen@ga.gov.au}
31}
32
33%Draft date
34
35% update before release!
36% Use an explicit date so that reformatting
37% doesn't cause a new date to be used.  Setting
38% the date to \today can be used during draft
39% stages to make it easier to handle versions.
40
41
42\longdate       % Make date format long using datetime.sty
43%\settimeformat{xxivtime} % 24 hour Format
44\settimeformat{oclock} % Verbose
45\date{\today, \ \currenttime}
46
47\ifhtml
48\date{\today} % latex2html does not know about datetime
49\fi
50
51
52
53
54
55\release{1.0}   % release version; this is used to define the
56                % \version macro
57
58\makeindex          % tell \index to actually write the .idx file
59\makemodindex       % If this contains a lot of module sections.
60
61\setcounter{tocdepth}{3}
62\setcounter{secnumdepth}{3}
63
64
65\begin{document}
66\maketitle
67
68
69% This makes the contents more accessible from the front page of the HTML.
70\ifhtml
71\chapter*{Front Matter\label{front}}
72\fi
73
74%Subversion keywords:
75%
76%$LastChangedDate: 2006-05-19 01:12:27 +0000 (Fri, 19 May 2006) $
77%$LastChangedRevision: 2921 $
78%$LastChangedBy: sexton $
79
80\input{copyright}
81
82
83\begin{abstract}
84
85\noindent \anuga\index{\anuga} is a hydrodynamic modelling tool that
86allows users to model realistic flow problems in complex geometries.
87Examples include dam breaks or the effects of natural hazards such
88as riverine flooding, storm surges and tsunami.
89
90The user must specify a study area represented by a mesh of triangular
91cells, the topography and bathymetry, frictional resistance, initial
92values for water level (called \emph{stage}\index{stage} within \anuga),
93boundary
94conditions and forces such as windstress or pressure gradients if
95applicable.
96
97\anuga tracks the evolution of water depth and horizontal momentum
98within each cell over time by solving the shallow water wave equation
99governing equation using a finite-volume method.
100
101\anuga cannot model details of breaking waves, flow under ceilings such
102as pipes, turbulence and vortices, vertical convection or viscous
103flows.
104
105\anuga also incorporates a mesh generator, called \code{pmesh}, that
106allows the user to set up the geometry of the problem interactively as
107well as tools for interpolation and surface fitting, and a number of
108auxiliary tools for visualising and interrogating the model output.
109
110Most \anuga components are written in the object-oriented programming
111language Python and most users will interact with \anuga by writing
112small Python programs based on the \anuga library
113functions. Computationally intensive components are written for
114efficiency in C routines working directly with the Numerical Python
115structures.
116
117
118\end{abstract}
119
120\tableofcontents
121
122
123\chapter{Introduction}
124
125
126\section{Purpose}
127
128The purpose of this user manual is to introduce the new user to
129the software, describe what it can do and give step-by-step
130instructions for setting up and running hydrodynamic simulations.
131
132\section{Scope}
133
134This manual covers only what is needed to operate the software
135after installation and configuration. It does not includes instructions for
136installing the software or detailed API documentation, both of
137which will be covered in separate publications and by  documentation in the
138source code.
139
140\section{Audience}
141
142Readers are assumed to be familiar with the operating environment
143and have a general understanding of the problem background, as
144well as enough programming experience to adapt the code to
145different requirements, as described in this manual,  and to
146understand the basic terminology of object-oriented programming.
147
148\section{Structure of This Manual}
149
150FIXME (Ole): Isn't this superseded by the contents section?
151
152This manual is structured as follows:
153
154\begin{itemize}
155  \item Background (What \anuga does)
156  \item A \emph{Getting Started} section
157  \item A detailed description of the public interface
158  \item \anuga 's overall architecture, components and file formats
159  \item Assumptions
160\end{itemize}
161
162
163\pagebreak
164\chapter{Background}
165
166
167Modelling the effects on the built environment of natural hazards such
168as riverine flooding, storm surges and tsunami is critical for
169understanding their economic and social impact on our urban
170communities.  Geoscience Australia and the Australian National
171University are developing a hydrodynamic inundation modelling tool
172called \anuga to help simulate the impact of these hazards.
173
174The core of \anuga is the fluid dynamics module, called pyvolution,
175which is based on a finite-volume method for solving the shallow water
176wave equation.  The study area is represented by a mesh of triangular
177cells.  By solving the governing equation within each cell, water
178depth and horizontal momentum are tracked over time.
179
180A major capability of pyvolution is that it can model the process of
181wetting and drying as water enters and leaves an area.  This means
182that it is suitable for simulating water flow onto a beach or dry land
183and around structures such as buildings.  Pyvolution is also capable
184of modelling hydraulic jumps due to the ability of the finite-volume
185method to accommodate discontinuities in the solution.
186
187To set up a particular scenario the user specifies the geometry
188(bathymetry and topography), the initial water level, boundary
189conditions such as tide, and any forcing terms that may drive the
190system such as wind stress or atmospheric pressure gradients.
191Frictional resistance from the different terrains in the model is
192represented by predefined forcing terms.
193
194A mesh generator, called pmesh, allows the user to set up the geometry
195of the problem interactively and to identify boundary segments and
196regions using symbolic tags.  These tags may then be used to set the
197actual boundary conditions and attributes for different regions
198(e.g. the Manning friction coefficient) for each simulation.
199
200Most \anuga components are written in the object-oriented programming
201language Python.  Software written in Python can be produced quickly
202and can be readily adapted to changing requirements throughout its
203lifetime.  Computationally intensive components are written for
204efficiency in C routines working directly with the Numerical Python
205structures.  The animation tool developed for \anuga is based on
206OpenSceneGraph, an Open Source Software (OSS) component allowing high
207level interaction with sophisticated graphics primitives.
208
209See \cite{nielsen2005} and \cite{roberts1999} for more background on \anuga.
210%FIXME (Ole): Add bibliography
211
212\chapter{Getting Started}
213\label{ch:getstarted}
214
215This section is designed to assist the reader to get started with
216\anuga by working through simple examples. Two examples are discussed;
217the first is a simple but artificial example that is useful to illustrate
218many of the ideas, and the second is a more realistic example.
219
220\section{A Simple Example}
221
222\subsection{Overview}
223
224What follows is a discussion of the structure and operation of a script which we will call \file{runup.py}, with just enough detail to allow
225the reader to appreciate what's involved in setting up a scenario
226like the one it depicts.
227
228This example carries out the solution of the shallow-water wave
229equation in the simple case of a configuration comprising a flat
230bed, sloping at a fixed angle in one direction and having a
231constant depth across each line in the perpendicular direction.
232
233The example demonstrates many of the basic ideas involved in
234setting up a more complex scenario. In the general case the user
235specifies the geometry (bathymetry and topography), the initial
236water level, boundary conditions such as tide, and any forcing
237terms that may drive the system such as wind stress or atmospheric
238pressure gradients. Frictional resistance from the different
239terrains in the model is represented by predefined forcing
240terms. The boundary is reflective on three sides and a time dependent wave on one side.
241
242The present example represents a simple scenario and does not
243include any forcing terms, nor is the data taken from a file as it
244would be in many typical cases.
245
246The conserved quantities involved in the
247problem are stage (absolute height of water surface),
248$x$-momentum and $y$-momentum. Other quantities
249involved in the computation are the friction and elevation.
250
251Water depth can be obtained through the equation
252
253\begin{tabular}{rcrcl}
254  \code{depth} &=& \code{stage} &-& \code{elevation}
255\end{tabular}
256
257
258%\emph{[More details of the problem background]}
259
260\subsection{Outline of the Program}
261
262In outline, \file{runup.py} performs the following steps:
263
264\begin{enumerate}
265
266   \item Sets up a triangular mesh.
267
268   \item Sets certain parameters governing the mode of
269operation of the model-specifying, for instance, where to store the model output.
270
271   \item Inputs various quantities describing physical measurements, such
272as the elevation, to be specified at each mesh point (vertex).
273
274   \item Sets up the boundary conditions.
275
276   \item Carries out the evolution of the model through a series of time
277steps and outputs the results, providing a results file that can
278be visualised.
279
280\end{enumerate}
281
282\subsection{The Code}
283
284%FIXME: we are using the \code function here.
285%This should be used wherever possible
286For reference we include below the complete code listing for
287\file{runup.py}. Subsequent paragraphs provide a
288`commentary' that describes each step of the program and explains it
289significance.
290
291\verbatiminput{examples/runup.py}
292%\verbatiminput{examples/bedslope.py}
293
294\subsection{Establishing the Mesh}
295
296The first task is to set up the triangular mesh to be used for the
297scenario. This is carried out through the statement:
298
299{\small \begin{verbatim}
300    points, vertices, boundary = rectangular(10, 10)
301\end{verbatim}}
302
303The function \function{rectangular} is imported from a module
304\module{mesh\_factory} defined elsewhere. (\anuga also contains
305several other schemes that can be used for setting up meshes, but we
306shall not discuss these now.) The above assignment sets up a $10
307\times 10$ rectangular mesh, triangulated in a specific way. In
308general, the assignment
309
310{\small \begin{verbatim}
311    points, vertices, boundary = rectangular(m, n)
312\end{verbatim}}
313
314returns:
315
316\begin{itemize}
317
318   \item a list \code{points} of length $N$, where $N = (m + 1)(n + 1)$,
319comprising the coordinates \code{(x, y)} of each of the $N$ mesh
320points,
321
322   \item a list \code{vertices} of length $2mn$ (each entry specifies the three
323vertices of one of the triangles used in the triangulation) , and
324
325   \item a dictionary \code{boundary}, used to tag the triangle edges on
326the boundaries. Each key corresponds to a triangle edge on one of
327the four boundaries and its value is one of \code{`left'},
328\code{`right'}, \code{`top'} and \code{`bottom'}, indicating
329which boundary the edge in question belongs to.
330
331\end{itemize}
332
333Since these three variables encapsulate the information needed to
334specify the grid, it may be helpful to consider how they look in a
335very simple case, not directly related to the example at hand.
336Figure \ref{fig:simplemesh} represents a very simple mesh comprising
337just 11 points and three triangles. (To avoid confusion, we should
338emphasise that this particular mesh is \emph{not} generated by
339\code{rectangular}---and is not even rectangular in nature. )
340
341
342\begin{figure}[h]
343  \begin{center}
344    \includegraphics[width=90mm, height=90mm]{triangularmesh.eps}
345  \end{center}
346 
347  \caption{A simple mesh}
348  \label{fig:simplemesh}
349\end{figure}
350
351
352The variables \code{points}, \code{vertices} and \code{boundary}
353represent the data displayed in Figure \ref{fig:simplemesh} as
354follows. The list \code{points} stores the coordinates of the
355points, and may be displayed schematically as in Table \ref{tab:points}.
356
357
358\begin{table}
359  \begin{center}
360    \begin{tabular}[t]{|c|cc|} \hline
361      index & \code{x} & \code{y}\\  \hline
362      0 & 1 & 1\\
363      1 & 4 & 2\\
364      2 & 8 & 1\\
365      3 & 1 & 3\\
366      4 & 5 & 5\\
367      5 & 8 & 6\\
368      6 & 11 & 5\\
369      7 & 3 & 6\\
370      8 & 1 & 8\\
371      9 & 4 & 9\\
372      10 & 10 & 7\\  \hline
373    \end{tabular}
374  \end{center}
375 
376  \caption{Point coordinates for mesh in
377    Figure \protect \ref{fig:simplemesh}}
378  \label{tab:points} 
379\end{table} 
380
381The list \code{vertices} specifies the triangles that make up the
382mesh. It does this by specifying, for each triangle, the indices
383(the numbers shown in the first column above) that correspond to the
384three points at its vertices, taken in an anti-clockwise order
385around the triangle. Thus, in the example shown in Figure
386\ref{fig:simplemesh}, the variable \code{vertices} contains the
387entries shown in Table \ref{tab:vertices}. The starting point is arbitrary so triangle $(0,1,3)$ is considered the same as $(1,3,0)$ and $(3,0,1)$.
388
389
390\begin{table}
391  \begin{center}
392    \begin{tabular}{|c|ccc|} \hline
393      index & \multicolumn{3}{c|}{\code{vertices}}\\ \hline
394      0 & 0 & 1 & 3\\
395      1 & 1 & 2 & 4\\
396      2 & 2 & 5 & 4\\
397      3 & 2 & 6 & 5\\
398      4 & 4 & 5 & 9\\
399      5 & 4 & 9 & 7\\
400      6 & 3 & 4 & 7\\
401      7 & 7 & 9 & 8\\
402      8 & 1 & 4 & 3\\
403      9 & 5 & 10 & 9\\  \hline
404    \end{tabular}
405  \end{center}
406 
407  \caption{Vertices for mesh in
408    Figure \protect \ref{fig:simplemesh}}
409  \label{tab:vertices}   
410\end{table}   
411
412Finally, the variable \code{boundary} identifies the boundary
413triangles and associates a tag with each.
414
415
416
417
418\subsection{Initialising the Domain}
419
420These variables are then used to set up a data structure
421\code{domain}, through the assignment:
422
423{\small \begin{verbatim}
424    domain = Domain(points, vertices, boundary)
425\end{verbatim}}
426
427This uses a Python class \class{Domain}, imported from
428\module{shallow\_water}, which is an extension of a more generic
429class of the same name in the module \refmodule{pyvolution.domain}
430(page \pageref{mod:pyvolution.domain}),
431and inherits
432some methods from the generic class but has others specific to the
433shallow-water scenarios in which it is used. Specific options for
434domain are set at this point. One of them is to set the basename for
435the output file:
436
437{\small \begin{verbatim}
438    domain.set_name('bedslope')
439\end{verbatim}}
440
441
442\subsection{Initial Conditions}
443
444The next task is to specify a number of quantities that we wish to
445set for each mesh point. The class \class{Domain} has a method
446\method{set\_quantity}, used to specify these quantities. It is a
447particularly flexible method that allows the user to set quantities
448in a variety of ways---using constants, functions, numeric arrays or
449expressions involving other quantities, arbitrary data points with
450associated values, all of which can be passed as arguments. All
451quantities can be initialised using \method{set\_quantity}. For
452conserved quantities (\code{stage, xmomentum, ymomentum}) this is
453called the \emph{initial condition}, for other quantities that
454aren't updated by the equation, the same interface is used to assign
455their values. The code in the present example demonstrates a number
456of forms in which we can invoke \method{set\_quantity}.
457
458
459\subsubsection{Elevation}
460
461The elevation, or height of the bed, is set using a function,
462defined through the statements below, which is specific to this
463example and specifies a particularly simple initial configuration
464for demonstration purposes:
465
466{\small \begin{verbatim}
467    def f(x,y):
468        return -x/2
469\end{verbatim}}
470
471This simply associates an elevation with each point \code{(x, y)} of
472the plane.  It specifies that the bed slopes linearly in the
473\code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
474the \code{y} direction.  %[screen shot?]
475
476Once the function \function{f} is specified, the quantity
477\code{elevation} is assigned through the simple statement:
478
479{\small \begin{verbatim}
480    domain.set_quantity('elevation', f)
481\end{verbatim}}
482
483
484\subsubsection{Friction}
485
486The assignment of the friction quantity demonstrates another way we
487can use \method{set\_quantity} to set quantities---namely, assign
488them to a constant numerical value:
489
490{\small \begin{verbatim}
491    domain.set_quantity('friction', 0.1)
492\end{verbatim}}
493
494This just specifies that the Manning friction coefficient is set
495to 0.1 at every mesh point.
496
497\subsubsection{Stage}
498
499The stage (the height of the water surface) is related to the
500elevation and the depth at any time by the equation
501
502
503{\small \begin{verbatim}
504    stage = elevation + depth
505\end{verbatim}}
506
507
508For this example, we simply assign a constant value to \code{stage},
509using the statement
510
511{\small \begin{verbatim}
512    domain.set_quantity('stage', -.4)
513\end{verbatim}}
514
515which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units
516below the zero level.
517
518(Although it is not necessary for this example, it may be useful to
519digress here and mention a variant to this requirement, which allows
520us to illustrate another way to use \method{set\_quantity}---namely,
521incorporating an expression involving other quantities. Suppose,
522instead of setting a constant value for the stage, we wished to
523specify a constant value for the \emph{depth}. For such a case we
524need to specify that \code{stage} is everywhere obtained by adding
525that value to the value already specified for \code{elevation}. We
526would do this by means of the statements:
527
528{\small \begin{verbatim}
529    h = 0.05 # Constant depth
530    domain.set_quantity('stage', expression = 'elevation + %f' %h)
531\end{verbatim}}
532
533That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus
534the value of \code{elevation} already defined.
535
536The reader will probably appreciate that this capability to
537incorporate expressions into statements using \method{set\_quantity}
538greatly expands its power.)
539
540\subsection{Boundary Conditions}
541
542The boundary conditions are specified as follows:
543
544{\small \begin{verbatim}
545    Br = Reflective_boundary(domain)
546
547    Bt = Transmissive_boundary(domain)
548
549    Bd = Dirichlet_boundary([0.2,0.,0.])
550
551    Bw = Time_boundary(domain=domain,
552                f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
553\end{verbatim}}
554
555The effect of these statements is to set up a selection of different
556alternative boundary conditions and store them in variables that can be
557assigned as needed. Each boundary condition specifies the
558behaviour at a boundary in terms of the behaviour in neighbouring
559elements. The boundary conditions introduced here may be briefly described as
560follows:
561
562\begin{itemize} 
563    \item \textbf{Reflective boundary} Returns same \code{stage} as
564      as present in its neighbour volume but momentum vector
565      reversed 180 degrees (reflected).
566      Specific to the shallow water equation as it works with the
567      momentum quantities assumed to be the second and third conserved
568      quantities. A reflective boundary condition models a solid wall.
569    \item \textbf{Transmissive boundary} Returns same conserved quantities as
570      those present in its neighbour volume. This is one way of modelling
571      outflow from a domain, but it should be used with caution if flow is
572      not steady state as replication of momentum at the boundary
573      may cause occasional spurious effects. If this occurs,
574      consider using e.g. a Dirichlet boundary condition.
575    \item \textbf{[Dirichlet boundary} Specifies a fixed value at the
576      boundary and assigns initial values to the $x$-momentum and $y$-momentum.
577    \item \textbf {Time boundary} Like a Dirichlet boundary but with behaviour
578      varying with time.
579\end{itemize}
580
581Once the boundary objects have been specified through the
582statements above, they can be applied through a statement of the
583form
584
585{\small \begin{verbatim}
586    domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
587\end{verbatim}}
588
589This statement stipulates that, in the current example, the right
590boundary varies with time, as defined by the lambda function, while the other
591boundaries are all reflective.
592
593The reader may wish to experiment by varying the choice of boundary
594types for one or more of the boundaries. In the case of \code{Bd}
595and \code{Bw}, the three arguments in each case represent the
596\code{stage}, $x$-momentum and $y$-momentum, respectively.
597
598{\small \begin{verbatim}
599    Bw = Time_boundary(domain=domain,
600                       f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
601\end{verbatim}}
602
603
604
605\subsection{Evolution}
606
607The final statement \nopagebreak[3]
608{\small \begin{verbatim}
609    for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
610        print domain.timestepping_statistics()
611\end{verbatim}}
612
613is the key step that causes the configuration of the domain to
614`evolve' in accordance with the model embodied in the code, over a
615series of steps indicated by the values of \code{yieldstep} and
616\code{duration}, which can be altered as required.  The value of
617\code{yieldstep} controls the time interval between successive model
618outputs.  Behind the scenes more time steps are generally taken.
619
620
621\subsection{Output}
622
623%Give details here of the form of the output and explain how it can
624%be used with swollen. Include screen shots.//
625
626The output is a NetCDF file with the extension \code{.sww}. It
627contains stage and momentum information and can be used with the
628\code{swollen} visualisation package to generate a visual display.
629See Section \ref{sec:file formats} (page \pageref{sec:file formats})
630for more on NetCDF and other file formats.
631
632
633\section{How to Run the Code}
634
635The code can be run in various ways:
636
637\begin{itemize}
638  \item{from a Windows command line} as in \code{python runup.py}
639  \item{within the Python IDLE environment}
640  \item{within emacs}
641  \item{from a Linux command line} as in \code{python runup.py}
642\end{itemize}
643
644
645\section{Exploring the model output}
646
647Figure \ref{fig:runupstart} shows the domain with water surface as
648specified by the initial condition, $t=0$. Figure \ref{fig:bedslope2}
649shows later snapshots for $t=2.3$ and $t=4$ where the system has been
650evolved and the wave encroaching on the previously dry bed.  All
651figures are screenshots from an interactive animation tool called
652Swollen which is part of ANUGA. Swollen is described in more detail is
653Section \ref{sec:swollen}.
654 
655
656
657\begin{figure}[hbt]
658
659  \centerline{\includegraphics[width=75mm, height=75mm]
660    {examples/runupstart.eps}}
661
662  \caption{Bedslope example viewed with Swollen}
663  \label{fig:runupstart}
664\end{figure}
665
666
667\begin{figure}[hbt]
668
669  \centerline{
670    \includegraphics[width=75mm, height=75mm]{examples/runupduring.eps}
671    \includegraphics[width=75mm, height=75mm]{examples/runupend.eps}
672   }
673
674  \caption{Bedslope example viewed with Swollen}
675  \label{fig:bedslope2}
676\end{figure}
677
678
679
680
681\clearpage
682
683%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
684
685\section{An Example with Real Data}
686
687The following discussion builds on the concepts introduced through
688the \file{runup.py} example and introduces a second
689example, \file{run\_sydney\_smf.py}, that follows the same basic
690outline, but incorporates more complex features and refers to a
691real-life scenario, rather than the artificial illustrative one used
692in \file{runup.py}. The domain of interest surrounds the
693Sydney region, and predominantly covers Sydney Harbour. A
694hypothetical tsunami wave is generated by a submarine mass failure
695situated on the edge of the continental shelf.
696
697\subsection{Overview}
698As in the case of \file{runup.py}, the actions carried
699out by the program can be organised according to this outline:
700
701\begin{enumerate}
702
703   \item Set up a triangular mesh.
704
705   \item Set certain parameters governing the mode of
706operation of the model---specifying, for instance, where to store the
707model output.
708
709   \item Input various quantities describing physical measurements, such
710as the elevation, to be specified at each mesh point (vertex).
711
712   \item Set up the boundary conditions.
713
714   \item Carry out the evolution of the model through a series of time
715steps and outputs the results, providing a results file that can be
716visualised.
717
718\end{enumerate}
719
720
721
722\subsection{The Code}
723
724Here is the code for \file{run\_sydney\_smf.py}:
725
726%\verbatiminput{"runsydneysmf.py"}
727\verbatiminput{examples/runsydney.py}
728
729In discussing the details of this example, we follow the outline
730given above, discussing each major step of the code in turn.
731
732\subsection{Establishing the Mesh}
733
734One obvious way that the present example differs from
735\file{runup.py} is in the use of a more complex method to
736create the mesh. Instead of imposing a mesh structure on a
737rectangular grid, the technique used for this example involves
738building mesh structures inside polygons specified by the user,
739using a mesh-generator referred to as \code{pmesh}.
740
741The following remarks may help the reader understand how
742\code{pmesh} is used.
743
744In its simplest form, \code{pmesh} creates the mesh within a single
745polygon whose vertices are at geographical locations specified by the
746user. The user specifies the \emph{resolution}---that is, the maximal
747area of a triangle used for triangulation---and mesh points are
748created inside the polygon through a random process. Figure
749\ref{fig:pentagon} shows a simple example of this, in which
750the triangulation is carried out within a pentagon.
751
752
753\begin{figure}[hbt]
754
755
756
757  \caption{Mesh points are created inside the polygon}
758  \label{fig:pentagon}
759\end{figure}
760
761Boundary tags are not restricted to \code{`left'}, \code{`right'},
762\code{`bottom'} and \code{`top'}, as in the case of
763\file{runup.py}. Instead the user specifies a list of
764tags appropriate to the configuration being modelled.
765
766While a mesh created inside a polygon offers more flexibility than
767one based on a rectangular grid, using \code{pmesh} in the limited
768form we have described so far still doesn't provide a way to adapt
769to geographic or other features in the landscape, whose presence may
770require us to vary the resolution in the neighbourhood of the
771features. To cope with this requirement, \code{pmesh} also allows
772the user to specify a number of \emph{interior polygons}, which are
773triangulated separately, each according to a separately specified
774resolution. See Figure \ref{fig:interior meshes}.
775
776\begin{figure}[hbt]
777
778
779
780  \caption{Interior meshes with individual resolution}
781  \label{fig:interior meshes}
782\end{figure}
783
784In its general form, \code{pmesh} takes for its input a bounding
785polygon and (optionally) a list of interior polygons. The user
786specifies resolutions, both for the bounding polygon and for each of
787the interior polygons. Given this data, \code{pmesh} first creates a
788triangular mesh inside the bounding polygon, using the specified
789resolution, and then creates a separate triangulation inside each of
790the interior polygons, using the resolution specified for that
791polygon.
792
793The function used to implement this process is
794\function{create\_mesh\_from\_regions}. Its arguments include the
795bounding polygon and its resolution, a list of boundary tags, and a
796list of pairs \code{[polygon, resolution]}, specifying the interior
797polygons and their resolutions.
798
799In practice, the details of the polygons used are read from a
800separate file \file{project.py}. The resulting mesh is output to a
801\emph{meshfile}\index{meshfile}. This term is used to describe a
802file of a specific format used to store the data specifying a mesh.
803(There are in fact two possible formats for such a file: it can
804either be a binary file, with extension \code{.msh}, or an ASCII
805file, with extension \code{.tsh}. In the present case, the binary
806file format \code{.msh} is used. See Section \ref{sec:file formats}
807(page \pageref{sec:file formats}) for more on file formats.)
808\code{pmesh} assigns a name to the file by appending the extension
809\code{.msh} to the name specified in the input file
810\file{project.py}. This name is stored in the variable
811\code{meshname}.
812
813The statements
814
815{\small \begin{verbatim}
816    interior_res = 5000%
817    interior_regions = [[project.harbour_polygon_2, interior_res],
818                    [project.botanybay_polygon_2, interior_res]]
819\end{verbatim}}
820
821are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
822\code{botanybay\_polygon\_2} from \file{project.py} and assign a
823common resolution of 5000 to each. The statement
824
825{\small \begin{verbatim}
826    create_mesh_from_regions(project.diffpolygonall,%
827                         boundary_tags= {'bottom': [0],%
828                                         'right1': [1],%
829                                         'right0': [2],%
830                                         'right2': [3],%
831                                         'top': [4],%
832                                         'left1': [5],%
833                                         'left2': [6],%
834                                         'left3': [7]},%
835                         maximum_triangle_area=100000,%
836                         filename=meshname,%
837                         interior_regions=interior_regions)
838\end{verbatim}}
839
840is then used to create the mesh, taking the bounding polygon to be the polygon
841\code{diffpolygonall} specified in \file{project.py}. The
842argument \code{boundary\_tags} assigns a dictionary, whose keys are the
843names of the boundary tags used for the bounding polygon---\code{`bottom'},
844`right0', `right1', `right2', `top', `left1', `left2' and `left3'---
845and whose values identify the indices of the segments associated with each of these
846tags. (The value associated with each boundary tag is a one-element list.)
847
848
849\subsection{Initialising the Domain}
850
851As with \file{runup.py}, once we have created the mesh, the next
852step is to create the data structure \code{domain}. We did this for
853\file{runup.py} by inputting lists of points and triangles and
854specifying the boundary tags directly. However, in the present case,
855we use a method that works directly with the meshfile
856\code{meshname}, as follows:
857
858
859{\small \begin{verbatim}
860    domain = Domain(meshname, use_cache=True, verbose=True)
861\end{verbatim}}
862
863Providing a filename instead of the lists used in bedslopephysical
864above causes Domain to convert a meshfile
865\code{meshname} into an instance of the data structure
866\code{domain}, allowing us to use methods like \method{set\_quantity}
867to set quantities and to apply other operations.
868
869%(In principle, the
870%second argument of \function{pmesh\_to\_domain\_instance} can be any
871%subclass of \class{Domain}, but for applications involving the
872%shallow-water wave equation, the second argument of
873%\function{pmesh\_to\_domain\_instance} can always be set simply to
874%\class{Domain}.)
875
876The following statements specify a basename and data directory, and
877identify quantities to be stored. For the first two, values are
878taken from \file{project.py}.
879
880{\small \begin{verbatim}
881    domain.set_name(project.basename)%
882    domain.set_datadir(project.outputdir)%
883    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
884        'ymomentum'])
885\end{verbatim}}
886
887
888\subsection{Initial Conditions}
889Quantities for \file{runsydney.py} are set
890using similar methods to those in \file{runup.py}. However,
891in this case, many of the values are read from the auxiliary file
892\file{project.py} or, in the case of \code{elevation}, from an
893ancillary points file.
894
895
896
897\subsubsection{Stage}
898
899For the scenario we are modelling in this case, we use a callable
900object \code{tsunami\_source}, assigned by means of a function
901\function{slump\_tsunami}. This is similar to how we set elevation in
902\file{runup.py} using a function---however, in this case the
903function is both more complex and more interesting.
904
905The function returns the water displacement for all \code{x} and
906\code{y} in the domain. The water displacement is a double Gaussian
907function that depends on the characteristics of the slump (length,
908thickness, slope, etc), its location (origin) and the depth at that
909location.
910
911
912\subsubsection{Friction}
913
914We assign the friction exactly as we did for \file{runup.py}:
915
916{\small \begin{verbatim}
917    domain.set_quantity('friction', 0.03)
918\end{verbatim}}
919
920
921\subsubsection{Elevation}
922
923The elevation is specified by reading data from a file:
924
925{\small \begin{verbatim}
926    domain.set_quantity('elevation',
927                        filename = project.combineddemname + '.pts',
928                        use_cache = True,
929                        verbose = True)
930\end{verbatim}}
931
932However, before this step can be executed, some preliminary steps
933are needed to prepare the file from which the data is taken. Two
934source files are used for this data---their names are specified in
935the file \file{project.py}, in the variables \code{coarsedemname}
936and \code{finedemname}. They contain `coarse' and `fine' data,
937respectively---that is, data sampled at widely spaced points over a
938large region and data sampled at closely spaced points over a
939smaller subregion. The data in these files is combined through the
940statement
941
942{\small \begin{verbatim}
943combine_rectangular_points_files(project.finedemname + '.pts',
944                                 project.coarsedemname + '.pts',
945                                 project.combineddemname + '.pts')
946\end{verbatim}}
947
948The effect of this is simply to combine the datasets by eliminating
949any coarse data associated with points inside the smaller region
950common to both datasets. The name to be assigned to the resulting
951dataset is also derived from the name stored in the variable
952\code{combinedname} in the file \file{project.py}.
953
954\subsection{Boundary Conditions}
955
956Setting boundaries follows a similar pattern to the one used for
957\file{runup.py}, except that in this case we need to associate a
958boundary type with each of the
959boundary tag names introduced when we established the mesh. In place of the four
960boundary types introduced for \file{runup.py}, we use the reflective
961boundary for each of the
962eight tagged segments:
963
964{\small \begin{verbatim}
965    Br = Reflective_boundary(domain)
966    domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
967                          'right2': Br, 'top': Br, 'left1': Br,
968                          'left2': Br, 'left3': Br} )
969\end{verbatim}}
970
971\subsection{Evolution}
972
973With the basics established, the running of the `evolve' step is
974very similar to the corresponding step in \file{runup.py}:
975
976{\small \begin{verbatim}
977    import time t0 = time.time()
978
979    for t in domain.evolve(yieldstep = 120, duration = 18000):
980        print domain.timestepping_statistics()
981        print domain.boundary_statistics(tags = 'bottom')
982
983    print 'That took %.2f seconds' %(time.time()
984\end{verbatim}}
985
986%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
987%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
988
989\chapter{\anuga Public Interface}
990\label{ch:interface}
991
992This chapter gives an overview of the features of \anuga available
993to the user at the public interface. These are grouped under the
994following headings:
995
996\begin{itemize}
997    \item Establishing the Mesh
998    \item Initialising the Domain
999    \item Specifying the Quantities
1000    \item Initial Conditions
1001    \item Boundary Conditions
1002    \item Forcing Functions
1003    \item Evolution
1004\end{itemize}
1005
1006The listings are intended merely to give the reader an idea of what
1007each feature is, where to find it and how it can be used---they do
1008not give full specifications. For these the reader
1009may consult the code. The code for every function or class contains
1010a documentation string, or `docstring', that specifies the precise
1011syntax for its use. This appears immediately after the line
1012introducing the code, between two sets of triple quotes.
1013
1014Each listing also describes the location of the module in which
1015the code for the feature being described can be found. All modules
1016are in the folder \file{inundation} or one of its subfolders, and the
1017location of each module is described relative to \file{inundation}. Rather
1018than using pathnames, whose syntax depends on the operating system,
1019we use the format adopted for importing the function or class for
1020use in Python code. For example, suppose we wish to specify that the
1021function \function{create\_mesh\_from\_regions} is in a module called
1022\module{mesh\_interface} in a subfolder of \module{inundation} called
1023\code{pmesh}. In Linux or Unix syntax, the pathname of the file
1024containing the function, relative to \file{inundation}, would be
1025
1026\begin{center}
1027%    \code{pmesh/mesh\_interface.py}
1028    \code{pmesh}$\slash$\code{mesh\_interface.py}
1029\end{center}
1030
1031while in Windows syntax it would be
1032
1033\begin{center}
1034    \code{pmesh}$\backslash$\code{mesh\_interface.py}
1035\end{center}
1036
1037Rather than using either of these forms, in this chapter we specify
1038the location simply as \code{pmesh.mesh_interface}, in keeping with
1039the usage in the Python statement for importing the function,
1040namely:
1041\begin{center}
1042    \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
1043\end{center}
1044
1045Each listing details the full set of parameters for the class or
1046function; however, the description is generally limited to the most
1047important parameters and the reader is again referred to the code
1048for more details.
1049
1050The following parameters are common to many functions and classes
1051and are omitted from the descriptions given below:
1052
1053%\begin{center}
1054\begin{tabular}{ll}  %\hline
1055%\textbf{Name } & \textbf{Description}\\
1056%\hline
1057\emph{usecache} & Specifies whether caching is to be used\\
1058\emph{verbose} & If \code{True}, provides detailed terminal output
1059to the user\\  % \hline
1060\end{tabular}
1061%\end{center}
1062
1063\section{Mesh Generation}
1064\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}
1065\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
1066                             boundary_tags,
1067                             maximum_triangle_area,
1068                             filename=None,
1069                             interior_regions=None,
1070                             poly_geo_reference=None,
1071                             mesh_geo_reference=None,
1072                             minimum_triangle_angle=28.0}
1073Module: \module{pmesh.mesh\_interface}
1074
1075This function allows a user to initiate the automatic creation of a
1076mesh inside a specified polygon. Among the parameters that can be
1077set are the \emph{resolution} (maximal area for any triangle in the
1078mesh) and the minimal angle allowable in any triangle. The user can
1079specify a number of internal polygons within each of which a
1080separate mesh is to be created, generally with a smaller resolution.
1081Additionally, the user specifies a list of boundary tags, one for
1082each edge of the bounding polygon.
1083\end{funcdesc}
1084
1085
1086\begin{funcdesc}  {Mesh}{userSegments=None,
1087                 userVertices=None,
1088                 holes=None,
1089                 regions=None,
1090                 geo_reference=None}
1091Module: \module{pmesh.mesh}
1092
1093% Translate following into layman's language
1094An instance of the class \class{Mesh} is used to store .  This can
1095then be used to build the outline of the mesh and then generate the
1096mesh.
1097\end{funcdesc}
1098
1099
1100\begin{funcdesc}  {add_region_from_polygon}{self, polygon, tags=None,
1101                                max_triangle_area=None, geo_reference=None}
1102Module: \module{pmesh.mesh.Mesh}
1103
1104% Translate following into layman's language
1105This method is used to add a region to a \class{Mesh} instance.  The
1106region is described by the polygon passed in.  Additionally, the
1107user specifies a list of boundary tags, one for each edge of the
1108bounding polygon.
1109
1110
1111\end{funcdesc}
1112
1113\begin{funcdesc}  {add_hole_from_polygon}{self, polygon, tags=None,
1114    geo_reference=None}
1115Module: \module{pmesh.mesh.Mesh}
1116
1117% Translate following into layman's language
1118This method is used to add a `hole'---that is, a region where the
1119triangular mesh will not be generated---to a \class{Mesh} instance.
1120The region is described by the polygon passed in.  Additionally, the
1121user specifies a list of boundary tags, one for each edge of the
1122bounding polygon.
1123\end{funcdesc}
1124
1125\begin{funcdesc}  {generate_mesh}{self,
1126                      maximum_triangle_area=None,
1127                      minimum_triangle_angle=28.0,
1128                      verbose=False}
1129Module: \module{pmesh.mesh.Mesh}
1130
1131% Translate following into layman's language
1132This method is used to generate the triangular mesh.  The  maximal area
1133of any triangle in the mesh can be specified, along with the minimum
1134angle of all triangles.
1135\end{funcdesc}
1136
1137
1138\begin{funcdesc}  {export_mesh_file}{self,ofile}
1139Module: \module{pmesh.mesh.Mesh}
1140
1141% Translate following into layman's language
1142This method is used to save the mesh to a file. \code{ofile} is the name of the mesh file to be writen,
1143including the extension.  Use the extension \code{.msh} for the file to
1144be in NetCDF format and \code{.tsh} for the file to be ASCII format.
1145\end{funcdesc}
1146
1147%%%%%%
1148\section{Initialising Domain}
1149
1150\begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
1151Module: \module{pyvolution.pmesh2domain}
1152
1153Once the initial mesh file has been created, this function is
1154applied to convert it to a domain object---that is, to a member of
1155the special Python class \class{Domain} (or a subclass of
1156\class{Domain}), which provides access to properties and methods
1157that allow quantities to be set and other operations to be carried
1158out.
1159
1160\code{file\_name} is the name of the mesh file to be converted,
1161including the extension. \code{DomainClass} is the class to be
1162returned, which must be a subclass of \class{Domain} having the same
1163interface as \class{Domain}---in practice, it can usually be set
1164simply to \class{Domain}.
1165
1166This is now superseded by Domain(mesh_filename).
1167\end{funcdesc}
1168
1169
1170\subsection{Key Methods of Domain}
1171
1172\begin{funcdesc} {set\_name}{name}
1173    Module: \refmodule{pyvolution.domain}, page \pageref{mod:pyvolution.domain}  %\code{pyvolution.domain}
1174
1175    Assigns the name \code{name} to the domain.
1176\end{funcdesc}
1177
1178\begin{funcdesc} {get\_name}{}
1179    Module: \module{pyvolution.domain}
1180
1181    Returns the name assigned to the domain by \code{set_name}. If no name has been
1182    assigned, returns \code{`domain'}.
1183\end{funcdesc}
1184
1185\begin{funcdesc} {set\_datadir}{name}
1186    Module: \module{pyvolution.domain}
1187
1188    Specifies the directory used for data, assigning it to the pathname \code{name}. The default value, before
1189    \code{set\_datadir} has been run, is the value \code{default_datadir}
1190    specified in \code{config.py}.
1191
1192    Since different operating systems use different formats for specifying pathnames,
1193    it is necessary to specify path separators using the Python code \code{os.sep}, rather than
1194    the operating-specific ones such as `$\slash$' or `$\backslash$'.
1195    For this to work you will need to include the statement \code{import os}
1196    in your code, before the first appearance of \code{set\_datadir}.
1197
1198    For example, to set the data directory to a subdirectory
1199    \code{data} of the directory \code{project}, you could use
1200    the statements:
1201
1202    {\small \begin{verbatim}
1203        import os
1204        domain.set_datadir{'project' + os.sep + 'data'}
1205    \end{verbatim}}
1206\end{funcdesc}
1207
1208\begin{funcdesc} {get_datadir}{}
1209    Module: \module{pyvolution.domain}
1210
1211    Returns the data directory set by \code{set\_datadir} or, if \code{set\_datadir} has not
1212    been run, returns the value \code{default_datadir} specified in
1213    \code{config.py}.
1214\end{funcdesc}
1215
1216\begin{funcdesc} {set_time}{time=0.0}
1217    Module: \module{pyvolution.domain}
1218
1219    Sets the initial time, in seconds, for the simulation. The
1220    default is 0.0.
1221\end{funcdesc}
1222
1223\begin{funcdesc} {set_default_order}{??}
1224\end{funcdesc}
1225
1226
1227%%%%%%
1228\section{Initial Conditions}
1229
1230\begin{funcdesc}{set\_quantity}{name,
1231    numeric = None,
1232    quantity = None,
1233    function = None,
1234    geospatial_data = None,
1235    filename = None,
1236    attribute_name = None,
1237    alpha = None,
1238    location = 'vertices',
1239    indices = None,
1240    verbose = False,
1241    use_cache = False}
1242  Module: \module{pyvolution.domain}
1243  (see also \module{pyvolution.quantity.set_values})
1244
1245This function is used to assign values to individual quantities for a
1246domain. It is very flexible and can be used with many data types: a
1247statement of the form \code{domain.set\_quantity(name, x)} can be used
1248to define a quantity having the name \code{name}, where the other
1249argument \code{x} can be any of the following:
1250
1251\begin{itemize}
1252\item a number, in which case all vertices in the mesh gets that for
1253the quantity in question.
1254\item a list of numbers or a Numeric array ordered the same way as the mesh vertices.
1255\item a function (e.g.\ see the samples introduced in Chapter 2)
1256\item an expression composed of other quantities and numbers, arrays, lists (for
1257example, a linear combination of quantities)
1258\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.
1259\item a geospatial dataset (See ?????). Optional argument attribute_name applies here as with files.
1260\end{itemize}
1261
1262
1263Exactly one of the arguments
1264  numeric, quantity, function, points, filename
1265must be present.
1266
1267
1268Set quantity will look at the type of the second argument (\code{numeric}) and
1269determine what action to take.
1270
1271Values can also be set using the appropriate keyword arguments.
1272If 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)}
1273are all equivalent.
1274
1275
1276Other optional arguments are
1277\begin{itemize}
1278\item \code{indices} which is a list of ids of triangles to which set_quantity should apply its assignment of values.
1279\item \code{location} determines which part of the triangles to assign to. Options are 'vertices' (default), 'edges', and 'centroids'.
1280\end{itemize}
1281
1282
1283a number, in which case all vertices in the mesh gets that for
1284the quantity in question.
1285\item a list of numbers or a Numeric array ordered the same way as the mesh vertices.
1286
1287
1288\end{funcdesc}
1289
1290
1291
1292
1293
1294
1295
1296%%%
1297\anuga provides a number of predefined initial conditions to be used
1298with \code{set_quantity}.
1299
1300\begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None,
1301                x0=0.0, y0=0.0, alpha=0.0,
1302                gravity=9.8, gamma=1.85,
1303                massco=1, dragco=1, frictionco=0, psi=0,
1304                dx=None, kappa=3.0, kappad=0.8, zsmall=0.01,
1305                domain=None,
1306                verbose=False}
1307This function returns a callable object representing an initial water
1308displacement generated by a submarine sediment failure. These failures can take the form of
1309a submarine slump or slide.
1310
1311The arguments include as a minimum, the slump or slide length, the water depth to the centre of sediment
1312mass, and the bathymetric slope. Other slump or slide parameters can be included if they are known.
1313\end{funcdesc}
1314
1315
1316%%%
1317\begin{funcdesc}{file_function}{filename,
1318                  domain = None,
1319                  quantities = None,
1320                  interpolation_points = None,
1321                  verbose = False,
1322                  use_cache = False}
1323Module: \module{pyvolution.util}
1324
1325Reads the time history of spatial data from NetCDF file and returns
1326a callable object. Returns interpolated values based on the input
1327file using the underlying \code{interpolation_function}.
1328
1329\code{quantities} is either the name of a single quantity to be
1330interpolated or a list of such quantity names. In the second case, the resulting
1331function will return a tuple of values---one for each quantity.
1332
1333\code{interpolation_points} is a list of absolute UTM coordinates
1334for points at which values are sought.
1335
1336To get access to the model time stored within the file funcion use the method \code{f.get_time()}
1337\end{funcdesc}
1338
1339%%%
1340\begin{classdesc}{Interpolation\_function}{self,
1341                 time,
1342                 quantities,
1343                 quantity_names = None,
1344                 vertex_coordinates = None,
1345                 triangles = None,
1346                 interpolation_points = None,
1347                 verbose = False}
1348Module: \module{pyvolution.least\_squares}
1349
1350Given a time series, either as a sequence of numbers or
1351defined at the vertices of a triangular mesh (such
1352as those stored in \code{sww} files), \code{Interpolation\_function}
1353is used to create a callable object that interpolates a value for
1354an arbitrary time \code{t} within the model limits and possibly a
1355point \code{(x, y)} within a mesh region.
1356
1357The actual time series at which data is available is specified by
1358means of an array \code{time} of monotonically increasing times. The
1359quantities containing the values to be interpolated are specified in
1360an array---or dictionary of arrays (used in conjunction with the
1361optional argument \code{quantity\_names}) --- called
1362\code{quantities}. The optional arguments \code{vertex_coordinates}
1363and \code{triangles} represent the spatial mesh associated with the
1364quantity arrays. If omitted the function created by
1365\code{Interpolation\_function} will be a function of \code{t} only.
1366
1367Since, in practice, values need to be computed at specified points,
1368the syntax allows the user to specify, once and for all, a list
1369\code{interpolation\_points} of points at which values are required.
1370In this case, the function may be called using the form \code{f(t,
1371id)}, where \code{id} is an index for the list
1372\code{interpolation\_points}.
1373
1374\end{classdesc}
1375
1376%%%
1377\begin{funcdesc}{set\_region}{functions}
1378[Low priority. Will be merged into set\_quantity]
1379
1380Module:\module{pyvolution.domain}
1381\end{funcdesc}
1382
1383
1384
1385%%%%%%
1386\section{Boundary Conditions}
1387
1388\anuga provides a large number of predefined boundary conditions,
1389represented by objects such as \code{Reflective\_boundary(domain)} and
1390\code{Dirichlet\_boundary([0.2, 0.0, 0.0])}, described in the examples
1391in Chapter 2. Alternatively, you may prefer to ``roll your own'',
1392following the method explained in Section \ref{sec:roll your own}.
1393
1394These boundary objects may be used with the function \code{set\_boundary} described below
1395to assign boundary conditions according to the tags used to label boundary segments.
1396
1397\begin{funcdesc}{set\_boundary}{boundary_map}
1398Module: \module{pyvolution.domain}
1399
1400This function allows you to assign a boundary object (corresponding to a
1401pre-defined or user-specified boundary condition) to every boundary segment that
1402has been assigned a particular tag.
1403
1404This is done by specifying a dictionary \code{boundary\_map}, whose values are the boundary objects
1405and whose keys are the symbolic tags.
1406
1407\end{funcdesc}
1408
1409\begin{funcdesc} {get_boundary_tags}{}
1410Module: \module{pyvolution.mesh}
1411\end{funcdesc}
1412
1413%%%
1414\subsection{Predefined boundary conditions}
1415
1416\begin{classdesc}{Reflective_boundary}{Boundary}
1417Module: \module{pyvolution.shallow\_water}
1418
1419Reflective boundary returns same conserved quantities as those present in
1420the neighbouring volume but reflected.
1421
1422This class is specific to the shallow water equation as it works with the
1423momentum quantities assumed to be the second and third conserved quantities.
1424\end{classdesc}
1425
1426%%%
1427\begin{classdesc}{Transmissive_boundary}{domain = None}
1428Module: \module{pyvolution.generic\_boundary\_conditions}
1429
1430A transmissive boundary returns the same conserved quantities as
1431those present in the neighbouring volume.
1432
1433The underlying domain must be specified when the boundary is instantiated.
1434\end{classdesc}
1435
1436%%%
1437\begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None}
1438Module: \module{pyvolution.generic\_boundary\_conditions}
1439
1440A Dirichlet boundary returns constant values for the conserved
1441quantities.
1442\end{classdesc}
1443
1444%%%
1445\begin{classdesc}{Time_boundary}{domain = None, f = None}
1446Module: \module{pyvolution.generic\_boundary\_conditions}
1447
1448A time-dependent boundary returns values for the conserved
1449quantities as a function \code{f(t)} of time. The user must specify
1450the domain to get access to the model time.
1451\end{classdesc}
1452
1453%%%
1454\begin{classdesc}{File_boundary}{Boundary}
1455Module: \module{pyvolution.generic\_boundary\_conditions}
1456
1457The boundary values are obtained from a file and interpolated. The
1458file is assumed to contain a time series and possibly also spatial
1459information. The conserved quantities are given as a function of
1460time.
1461\end{classdesc}
1462
1463
1464\subsection{User-defined boundary conditions}
1465\label{sec:roll your own}
1466[How to roll your own]
1467
1468
1469
1470
1471
1472\section{Forcing Functions}
1473
1474\anuga provides a number of predefined forcing functions to be used with .....
1475
1476%\begin{itemize}
1477
1478
1479%  \item \indexedcode{}
1480%  [function, arguments]
1481
1482%  \item \indexedcode{}
1483
1484%\end{itemize}
1485
1486
1487
1488\section{Evolution}
1489
1490  \begin{funcdesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
1491
1492  Module: \module{pyvolution.domain}
1493
1494  This function (a method of \class{domain}) is invoked once all the
1495  preliminaries have been completed, and causes the model to progress
1496  through successive steps in its evolution, storing results and
1497  outputting statistics whenever a user-specified period
1498  \code{yieldstep} is completed (generally during this period the
1499  model will evolve through several steps internally). The user
1500  specifies the total time period over which the evolution is to take
1501  place, by specifying values (in seconds) for either \code{duration}
1502  or \code{finaltime}, as well as the interval in seconds after which
1503  results are to be stored and statistics output.
1504
1505  You can include \method{evolve} in a statement of the type:
1506
1507  {\small \begin{verbatim}
1508      for t in domain.evolve(yieldstep, finaltime):
1509          <Do something with domain and t>
1510  \end{verbatim}}
1511
1512  \end{funcdesc}
1513
1514
1515
1516\subsection{Diagnostics}
1517
1518  \begin{funcdesc}{timestepping_statistics}{}
1519  Module: \module{pyvolution.domain}
1520
1521
1522  \end{funcdesc}
1523
1524
1525  \begin{funcdesc}{boundary\_statistics}{quantities = None, tags = None}
1526  Module: \module{pyvolution.domain}
1527
1528
1529  \end{funcdesc}
1530
1531
1532  \begin{funcdesc}{get_quantity}{name, location='vertices', indices = None}
1533  Module: \module{pyvolution.domain}
1534  Allow access to individual quantities and their methods
1535
1536  \end{funcdesc}
1537
1538
1539  \begin{funcdesc}{get_values}{location='vertices', indices = None}
1540  Module: \module{pyvolution.quantity}
1541
1542  Extract values for quantity as an array
1543
1544  \end{funcdesc}
1545
1546
1547  \begin{funcdesc}{get_integral}{}
1548  Module: \module{pyvolution.quantity}
1549
1550  Return computed integral over entire domain for this quantity
1551
1552  \end{funcdesc}
1553
1554
1555\section{Other}
1556
1557  \begin{funcdesc}{domain.create_quantity_from_expression}{???}
1558
1559  Handy for creating derived quantities on-the-fly.
1560  See \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
1561  \end{funcdesc}
1562
1563
1564  \begin{classdesc}{Geospatial_data}{???}
1565    Module: \module{geospatial_data.geo_spatial_data}
1566    Creates a georeferenced geospatial data object from either arrays or
1567    a file (pts or xya).
1568
1569    Objects of this class can be used with \method{set\_quantity}.
1570   
1571    FIXME (Ole): Describe methods such as get_attributes() etc
1572  \end{classdesc}
1573
1574
1575
1576
1577
1578%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1579%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1580
1581\chapter{\anuga System Architecture}
1582
1583From pyvolution/documentation
1584
1585\section{File Formats}
1586\label{sec:file formats}
1587
1588\anuga makes use of a number of different file formats. The
1589following table lists all these formats, which are described in more
1590detail in the paragraphs below.
1591
1592\bigskip
1593
1594\begin{center}
1595
1596\begin{tabular}{|ll|}  \hline
1597
1598\textbf{Extension} & \textbf{Description} \\
1599\hline\hline
1600
1601\code{.sww} & NetCDF format for storing model output
1602\code{f(t,x,y)}\\
1603
1604\code{.tms} & NetCDF format for storing time series \code{f(t)}\\
1605
1606\code{.xya} & ASCII format for storing arbitrary points and
1607associated attributes\\
1608
1609\code{.pts} & NetCDF format for storing arbitrary points and
1610associated attributes\\
1611
1612\code{.asc} & ASCII format of regular DEMs as output from ArcView\\
1613
1614\code{.prj} & Associated ArcView file giving more metadata for
1615\code{.asc} format\\
1616
1617\code{.ers} & ERMapper header format of regular DEMs for ArcView\\
1618
1619\code{.dem} & NetCDF representation of regular DEM data\\
1620
1621\code{.tsh} & ASCII format for storing meshes and associated
1622boundary and region info\\
1623
1624\code{.msh} & NetCDF format for storing meshes and associated
1625boundary and region info\\
1626
1627\code{.nc} & Native ferret NetCDF format\\
1628
1629\code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
1630%\caption{File formats used by \anuga}
1631\end{tabular}
1632
1633
1634\end{center}
1635
1636The above table shows the file extensions used to identify the
1637formats of files. However, typically, in referring to a format we
1638capitalise the extension and omit the initial full stop---thus, we
1639refer, for example, to `SWW files' or `PRJ files'.
1640
1641\bigskip
1642
1643A typical dataflow can be described as follows:
1644
1645\subsection{Manually Created Files}
1646
1647\begin{tabular}{ll}
1648ASC, PRJ & Digital elevation models (gridded)\\
1649TSH & Triangular meshes (e.g. created from \code{pmesh})\\
1650NC & Model outputs for use as boundary conditions (e.g. from MOST)
1651\end{tabular}
1652
1653\subsection{Automatically Created Files}
1654
1655\begin{tabular}{ll}
1656ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
1657DEMs to native \code{.pts} file\\
1658
1659NC $\rightarrow$ SWW & Convert MOST boundary files to
1660boundary \code{.sww}\\
1661
1662PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
1663
1664TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
1665Swollen\\
1666
1667TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
1668\code{pyvolution}
1669\end{tabular}
1670
1671
1672
1673
1674\bigskip
1675
1676\subsection{SWW and TMS Formats}
1677
1678The SWW and TMS formats are both NetCDF formats, and are of key
1679importance for \anuga.
1680
1681An SWW file is used for storing \anuga output and therefore pertains
1682to a set of points and a set of times at which a model is evaluated.
1683It contains, in addition to dimension information, the following
1684variables:
1685
1686\begin{itemize}
1687    \item \code{x} and \code{y}: coordinates of the points, represented as Numeric arrays
1688    \item \code{elevation}, a Numeric array storing bed-elevations
1689    \item \code{volumes}, a list specifying the points at the vertices of each of the
1690    triangles
1691    % Refer here to the example to be provided in describing the simple example
1692    \item \code{time}, a Numeric array containing times for model
1693    evaluation
1694\end{itemize}
1695
1696
1697The contents of an SWW file may be viewed using the visualisation
1698tool \code{swollen}, which creates an on-screen geometric
1699representation. See section \ref{sec:swollen} (page
1700\pageref{sec:swollen}) in Appendix \ref{ch:supportingtools} for more
1701on \code{swollen}.
1702
1703Alternatively, there are tools, such as \code{ncdump}, that allow
1704you to convert an NetCDF file into a readable format such as the
1705Class Definition Language (CDL). The following is an excerpt from a
1706CDL representation of the output file \file{bedslope.sww} generated
1707from running the simple example \file{runup.py} of
1708Chapter \ref{ch:getstarted}:
1709
1710\verbatiminput{examples/bedslopeexcerpt.cdl}
1711
1712The SWW format is used not only for output but also serves as input
1713for functions such as \function{file_boundary} and
1714\function{file_function}, described in Chapter \ref{ch:interface}.
1715
1716A TMS file is used to store time series data that is independent of
1717position.
1718
1719
1720\subsection{Meshfile Formats}
1721
1722A meshfile is a file that has a specific format suited to specifying
1723mesh data for \anuga. A meshfile can have one of two formats: it can
1724be either a TSH file, which is an ASCII file, or an MSH file, which
1725is a NetCDF file. A meshfile can be generated from the function
1726\function{create_mesh_from_regions} (see ) and used to initialise a
1727domain.
1728
1729A meshfile describes the outline of the mesh---the vertices and line
1730segments that enclose the region in which the mesh is created---and
1731the triangular mesh itself, which is specified by listing the
1732triangles and their vertices, and the segments, which are those
1733sides of the triangles that are associated with boundary conditions.
1734
1735In addition, a meshfile may contain `holes' and/or `regions'. A hole
1736or region is defined by specifying a point and a number of segments
1737that enclose that point. A hole represents an area where no mesh is
1738to be created, while a region is a labelled area used for defining
1739properties of a mesh, such as friction values.
1740
1741A meshfile can also contain a georeference, which describes an
1742offset to be applied to $x$ and $y$ values---eg to the vertices.
1743
1744
1745\subsection{Formats for Storing Arbitrary Points and Attributes}
1746
1747An XYA file is used to store data representing arbitrary numerical
1748attributes associated with a set of points.
1749
1750The format for an XYA file is:
1751%\begin{verbatim}
1752
1753            first line:     \code{[attribute names]}\\
1754            other lines:  \code{x y [attributes]}\\
1755
1756            for example:\\
1757            \code{elevation, friction}\\
1758            \code{0.6, 0.7, 4.9, 0.3}\\
1759            \code{1.9, 2.8, 5, 0.3}\\
1760            \code{2.7, 2.4, 5.2, 0.3}
1761
1762        The first two columns are always implicitly assumed to be $x$, $y$ coordinates.
1763        Use the same delimiter for the attribute names and the data.
1764
1765        An XYA file can optionally end with lines of this type:
1766
1767            \code{\#geo reference}\\
1768            \code{56}\\
1769            \code{466600.0}\\
1770            \code{8644444.0}
1771
1772        Here the first number specifies the zone (in this case zone 56)  and other numbers specify the
1773        coordinates (in this case (466600.0, 8644444.0)) of the lower left corner.
1774
1775A PTS file is a NetCDF representation of the data held in an XYA
1776file. If the data is associated with a set of $N$ points, then the
1777data is stored using an $N \times 2$ Numeric array of float
1778variables for the points and an $N \times 1$ Numeric array for each
1779attribute.
1780
1781%\end{verbatim}
1782
1783\subsection{ArcView Formats}
1784
1785Files of the three formats ASC, PRJ and ERS are all associated with
1786data from ArcView.
1787
1788An ASC file is an ASCII representation of DEM output from ArcView.
1789It has the following format...
1790
1791A PRJ file is an ArcView file used in conjunction with an ASC file
1792to represent metadata for a DEM.
1793
1794
1795\subsection{DEM Format}
1796
1797A DEM file is a NetCDF representation of regular DEM data.
1798
1799
1800\subsection{Other Formats}
1801
1802
1803
1804
1805\subsection{Basic File Conversions}
1806
1807  \begin{funcdesc}{sww2dem}{basename_in, basename_out = None,
1808            quantity = None,
1809            timestep = None,
1810            reduction = None,
1811            cellsize = 10,
1812            NODATA_value = -9999,
1813            easting_min = None,
1814            easting_max = None,
1815            northing_min = None,
1816            northing_max = None,
1817            expand_search = False,
1818            verbose = False,
1819            origin = None,
1820            datum = 'WGS84',
1821            format = 'ers'}
1822  Module: \module{pyvolution.data\_manager}
1823
1824  Takes data from an SWW file and converts it to DEM format (ASC or
1825  ERS)
1826  \end{funcdesc}
1827
1828
1829  \begin{funcdesc}{dem2pts}{basename_in, basename_out=None,
1830            easting_min=None, easting_max=None,
1831            northing_min=None, northing_max=None,
1832            use_cache=False, verbose=False}
1833  Module: \module{pyvolution.data\_manager}
1834
1835  Takes DEM data (a NetCDF file representation of data from a regular Digital
1836  Elevation Model) and converts it to PTS format.
1837  \end{funcdesc}
1838
1839
1840
1841%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1842%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1843
1844\chapter{Basic \anuga Assumptions}
1845
1846(From pyvolution/documentation)
1847
1848
1849Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
1850If one wished to recreate scenarios prior to that date it must be done
1851using some relative time (e.g. 0).
1852
1853
1854All spatial data relates to the WGS84 datum (or GDA94) and has been
1855projected into UTM with false easting of 500000 and false northing of
18561000000 on the southern hemisphere (0 on the northern).
1857
1858It is assumed that all computations take place within one UTM zone.
1859
1860DEMs, meshes and boundary conditions can have different origins within
1861one UTM zone. However, the computation will use that of the mesh for
1862numerical stability.
1863
1864
1865%OLD
1866%The dataflow is: (See data_manager.py and from scenarios)
1867%
1868%
1869%Simulation scenarios
1870%--------------------%
1871%%
1872%
1873%Sub directories contain scrips and derived files for each simulation.
1874%The directory ../source_data contains large source files such as
1875%DEMs provided externally as well as MOST tsunami simulations to be used
1876%as boundary conditions.
1877%
1878%Manual steps are:
1879%  Creation of DEMs from argcview (.asc + .prj)
1880%  Creation of mesh from pmesh (.tsh)
1881%  Creation of tsunami simulations from MOST (.nc)
1882%%
1883%
1884%Typical scripted steps are%
1885%
1886%  prepare_dem.py:  Convert asc and prj files supplied by arcview to
1887%                   native dem and pts formats%
1888%
1889%  prepare_pts.py: Convert netcdf output from MOST to an sww file suitable
1890%                  as boundary condition%
1891%
1892%  prepare_mesh.py: Merge DEM (pts) and mesh (tsh) using least squares
1893%                   smoothing. The outputs are tsh files with elevation data.%
1894%
1895%  run_simulation.py: Use the above together with various parameters to
1896%                     run inundation simulation.
1897
1898
1899%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1900%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1901
1902\appendix
1903
1904\chapter{Supporting Tools}
1905\label{ch:supportingtools}
1906
1907This section describes a number of supporting tools, supplied with \anuga, that offer a
1908variety of types of functionality and enhance the basic capabilities of \anuga.
1909
1910\section{caching}
1911
1912  The \code{cache} function is used to provide supervised caching of function results. A Python
1913  function call of the form
1914
1915      {\small \begin{verbatim}
1916      result = func(arg1,...,argn)
1917      \end{verbatim}}
1918
1919  can be replaced by
1920
1921      {\small \begin{verbatim}
1922      from caching import cache
1923      result = cache(func,(arg1,...,argn))
1924      \end{verbatim}}
1925
1926  which returns the same output but reuses cached
1927  results if the function has been computed previously in the same context.
1928  \code{result} and the arguments can be simple types, tuples, list, dictionaries or
1929  objects, but not unhashable types such as functions or open file objects.
1930  The function \code{func} may be a member function of an object or a module.
1931
1932  This type of caching is particularly useful for computationally intensive
1933  functions with few frequently used combinations of input arguments. Note that
1934  if the inputs or output are very large caching may not save time because
1935  disc access may dominate the execution time.
1936
1937  If the function definition changes after a result has been cached, this will be
1938  detected by examining the functions \code{bytecode (co_code, co_consts,
1939  func_defualts, co_argcount)} and the function will be recomputed.
1940
1941  Options are set by means of the function \code{set_option(key, value)},
1942  where \code{key} is a key associated with a
1943  Python dictionary \code{options}. This dictionary stores settings such as the name of
1944  the directory used, the maximum
1945  number of cached files allowed, and so on.
1946
1947  The \code{cache} function allows the user also to specify a list of dependent files. If any of these
1948  have been changed, the function is recomputed and the results stored again.
1949
1950  %Other features include support for compression and a capability to \ldots
1951
1952
1953   \textbf{USAGE:}
1954
1955    {\small \begin{verbatim}
1956    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
1957                   compression, evaluate, test, return_filename)
1958    \end{verbatim}}
1959
1960
1961\section{swollen}
1962\label{sec:swollen}
1963 The output generated by \anuga may be viewed by
1964means of the visualisation tool \code{swollen}, which takes the
1965\code{sww} file output by \anuga and creates a visual representation
1966of the data. Examples may be seen in Figures \ref{fig:runupstart}
1967and \ref{fig:bedslope2}. To view an \code{sww} file with
1968\code{swollen} in the Windows environment, you can simply drag the
1969icon representing the file over an icon on the desktop for the
1970\code{swollen} executable file (or a shortcut to it). Alternatively,
1971you can operate \code{swollen} from the command line, in both
1972Windows and Linux environments.
1973
1974On successful operation, you will see an interactive moving-picture display. You can use keys and the mouse
1975to slow down, speed up or stop the display, change the viewing position or carry out a number of other
1976simple operations.
1977
1978The main keys operating the interactive screen are:\\
1979
1980\begin{center}
1981\begin{tabular}{|ll|}   \hline
1982
1983\code{w} & toggle wireframe\\
1984
1985space bar & start/stop\\
1986
1987up/down arrows & increase/decrease speed\\
1988
1989left/right arrows & direction in time \emph{(when running)}\\ & step through simulation \emph{(when stopped)}\\
1990
1991left mouse button & rotate\\
1992
1993middle mouse button & pan\\
1994
1995right mouse button & zoom\\  \hline
1996
1997\end{tabular}
1998\end{center}
1999
2000\vfill
2001
2002The following table describes how to operate swollen from the command line:
2003
2004Usage: \code{swollen [options] swwfile \ldots}\\  \nopagebreak
2005Options:\\  \nopagebreak
2006\begin{tabular}{ll}
2007  \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY_CENTER |}\\
2008                                    & \code{HEAD_MOUNTED_DISPLAY}\\
2009  \code{--rgba} & Request a RGBA colour buffer visual\\
2010  \code{--stencil} & Request a stencil buffer visual\\
2011  \code{--stereo} & Use default stereo mode which is \code{ANAGLYPHIC} if not \\
2012                                    & overridden by environmental variable\\
2013  \code{--stereo <mode>} & \code{ANAGLYPHIC | QUAD_BUFFER | HORIZONTAL_SPLIT |}\\
2014                                    & \code{VERTICAL_SPLIT | LEFT_EYE | RIGHT_EYE |}\\
2015                                     & \code{ON | OFF} \\
2016  \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\
2017  \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\
2018  \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\
2019  \code{-help} & Display this information\\
2020  \code{-hmax <float>} & Height above which transparency is set to
2021                                     \code{alphamax}\\
2022  \code{-hmin <float>} & Height below which transparency is set to
2023                                     zero\\
2024  \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is
2025                                     up, default is overhead)\\
2026  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
2027  \code{-movie <dirname>} & Save numbered images to named directory and
2028                                     quit\\
2029  \code{-nosky} & Omit background sky\\
2030  \code{-scale <float>} & Vertical scale factor\\
2031  \code{-texture <file>} & Image to use for bedslope topography\\
2032  \code{-tps <rate>} & Timesteps per second\\
2033  \code{-version} & Revision number and creation (not compile)
2034                                     date\\
2035\end{tabular}
2036
2037\section{utilities/polygons}
2038
2039  \begin{classdesc}{Polygon_function}{regions, default = 0.0, geo_reference = None}
2040  Module: \code{utilities.polygon}
2041
2042
2043  \end{classdesc}
2044
2045  \begin{funcdesc}{read_polygon}{filename}
2046  Module: \code{utilities.polygon}
2047
2048  Reads the specified file and returns a polygon. Each
2049  line of the file must contain exactly two numbers, separated by a comma, which are interpreted
2050  as coordinates of one vertex of the polygon.
2051  \end{funcdesc}
2052
2053  \begin{funcdesc}{populate_polygon}{polygon, number_of_points, seed = None, exclude = None}
2054  Module: \code{utilities.polygon}
2055
2056  Populates the interior of the specified polygon with the specified number of points,
2057  selected by means of a uniform distribution function.
2058  \end{funcdesc}
2059
2060  \begin{funcdesc}{point_in_polygon}{polygon, delta=1e-8}
2061  Module: \code{utilities.polygon}
2062
2063  Returns a point inside the specified polygon and close to the edge. The distance between
2064  the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the
2065  second argument \code{delta}, which is taken as $10^{-8}$ by default.
2066  \end{funcdesc}
2067
2068  \begin{funcdesc}{inside_polygon}{points, polygon, closed = True, verbose = False}
2069  Module: \code{utilities.polygon}
2070
2071  Used to test whether a single point---or the members of a list of points---
2072  are inside the specified polygon. If the first argument is a single point,
2073  returns \code{True} if the point is inside the polygon, or \code{False}
2074  otherwise. If the first argument is a list of points, returns a Numeric
2075  array comprising the indices of the points in the list that lie inside the polygon.
2076  (If none of the points are inside, returns \code{zeros((0,), 'l')}.)
2077  Points on the edges of the polygon are regarded as inside if
2078  \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
2079  \end{funcdesc}
2080
2081  \begin{funcdesc}{outside_polygon}{points, polygon, closed = True, verbose = False}
2082  Module: \code{utilities.polygon}
2083
2084  Exactly like \code{inside_polygon}, but with the words `inside' and `outside' interchanged.
2085  \end{funcdesc}
2086
2087  \begin{funcdesc}{point_on_line}{x, y, x0, y0, x1, y1}
2088  Module: \code{utilities.polygon}
2089
2090  Returns \code{True} or \code{False}, depending on whether the point with coordinates
2091  \code{x, y} is on the line passing through the points with coordinates \code{x0, y0}
2092  and \code{x1, y1} (extended if necessary at either end).
2093  \end{funcdesc}
2094
2095  \begin{funcdesc}{separate_points_by_polygon}{points, polygon,
2096                               closed = True, verbose = False}\indexedcode{separate_points_by_polygon}
2097  Module: \code{utilities.polygon}
2098
2099  \begin{funcdesc}{polygon_area}{polygon}
2100  Module: \code{utilities.polygon}
2101
2102  Returns area of arbitrary polygon (reference http://mathworld.wolfram.com/PolygonArea.html)
2103  \end{funcdesc}
2104
2105  \begin{funcdesc}{plot_polygons}{polygons, figname, verbose = False}
2106  Module: \code{utilities.polygon}
2107
2108  Plots each polygon contained in input polygon list, e.g. [poly1, poly2, poly3].
2109 Each polygon is closed for plotting purposes and subsequent plot saved to figname.
2110  Returns list containing the minimum and maximum of $x$ and $y$,
2111  i.e. [$x_{min}, x_{max}, y_{min}, y_{max}$].
2112  \end{funcdesc}
2113
2114\section{coordinate_transforms}
2115
2116\section{geo_spatial_data}
2117
2118This describes a class that represents arbitrary point data in UTM
2119coordinates along with named attribute values.
2120
2121TBA
2122
2123\section{pmesh GUI}
2124
2125\section{alpha_shape}
2126
2127
2128\section{utilities/numerical_tools} Do now.
2129
2130\begin{itemize}
2131  \item \indexedcode{ensure_numeric}
2132  \item \indexedcode{mean}
2133  \item
2134\end{itemize}
2135
2136
2137\chapter{Modules available in \anuga}
2138
2139
2140\section{\module{pyvolution.general\_mesh} }
2141\declaremodule[pyvolution.generalmesh]{}{pyvolution.general\_mesh}
2142\label{mod:pyvolution.generalmesh}
2143
2144\section{\module{pyvolution.mesh} }
2145\declaremodule{}{pyvolution.mesh}
2146\label{mod:pyvolution.mesh}
2147
2148\section{\module{pyvolution.domain} --- Generic module for 2D triangular domains for finite-volume computations of conservation laws}
2149\declaremodule{}{pyvolution.domain}
2150\label{mod:pyvolution.domain}
2151
2152
2153\section{\module{pyvolution.quantity}}
2154\declaremodule{}{pyvolution.quantity}
2155\label{mod:pyvolution.quantity}
2156
2157
2158\section{\module{pyvolution.shallow\_water} --- 2D triangular domains for finite-volume computations of the shallow water wave equation. This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water Wave Equation
2159}
2160\declaremodule[pyvolution.shallowwater]{}{pyvolution.shallow\_water}
2161\label{mod:pyvolution.shallowwater}
2162
2163
2164
2165
2166%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2167
2168\chapter{Frequently Asked Questions}
2169
2170
2171\section{General Questions}
2172
2173\subsubsection{What is \anuga?}
2174
2175\subsubsection{Why is it called \anuga?}
2176
2177\subsubsection{How do I obtain a copy of \anuga?}
2178
2179\subsubsection{What developments are expected for \anuga in the future?}
2180
2181\subsubsection{Are there any published articles about \anuga that I can reference?}
2182
2183\section{Modelling Questions}
2184
2185\subsubsection{Which type of problems are \anuga good for?}
2186
2187\subsubsection{Which type of problems are beyond the scope of \anuga?}
2188
2189\subsubsection{Can I start the simulation at an arbitrary time?}
2190Yes, using \code{domain.set_time()} you can specify an arbitrary starting time.
2191This is for example useful in conjunction with a file_boundary, which may start hours before anything hits the model boundary. By assigning a later time for the model to start, computational resources aren't wasted.
2192
2193\subsubsection{Can I change values for any quantity during the simulation?}
2194Yes, using \code{domain.set_quantity()} inside the domain.evolve loop you
2195can change values of any quantity. This is for example useful if you wish to
2196let the system settle for a while before assigning an initial condition. Another example would be changing the values for elevation to model e.g. erosion.
2197
2198\subsubsection{Can I change boundary conditions during the simulation?}
2199Not sure, but it would be nice :-)
2200
2201\subsubsection{Why does a file\_function return a list of numbers when evaluated?}
2202Currently, file\_function works by returning values for the conserved
2203quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the triplet returned by file\_function.
2204
2205\subsubsection{Which diagnostics are available to troubleshoot a simulation?}
2206
2207\subsubsection{How do I use a DEM in my simulation?}
2208You use \code{dem2pts} to convert your DEM to the required .pts format. This .pts file is then called When setting the elevation data to the mesh
2209in \code{domain.set_quantity}
2210
2211\subsubsection{What sort of DEM resolution should I use?}
2212Try and work with the "best" you have available. Onshore DEMs are typically available in 25m, 100m and 250m grids. Note, offshore data is often sparse,
2213or non-existant.
2214
2215\subsubsection{What sort of mesh resolution should I use?}
2216The mesh resolution should be commensurate with your DEM - it does not make sense to put in place a mesh which is finer than your DEM. As an example,
2217if your DEM is on a 25m grid, then the cell resolution should be of the order of 315$m^2$ (this represents half the area of the square grid). Ideally,
2218you need a fine mesh over regions where the DEM changes rapidly, and other areas of significant interest, such as the coast.
2219
2220\subsubsection{How often should I store the output?}
2221This will depend on what you are trying to answer with your model and how much memory you have available on your machine. If you need
2222to look in detail at the evolution, then you will need to balance against your storage requirements and the duration of the simulation.
2223If the sww file exceeds 1Gb, another sww file will be created until the end of the simulation. As an example, to store all the conserved
2224quantities on a mesh with approximately 300000 triangles on a 2 min interval for 5 hours will result in approximately 350Mb sww file.
2225
2226\subsection{Boundary Conditions}
2227
2228\subsubsection{How do I create a Dirichlet boundary condition?}
2229
2230\subsubsection{How do I know which boundary tags are available?}
2231The method \code{domain.get_boundary_tags()} will return a list of
2232available tags for use with \code{domain.set_boundary_condition()}.
2233
2234
2235
2236
2237
2238\chapter{Glossary}
2239
2240\begin{itemize}
2241    \item \indexedbold{\anuga} Name of software (joint development between ANU and GA)
2242
2243    \item \indexedbold{domain} The domain of a function is the set of all input values to the function.
2244
2245    \item \indexedbold{Dirichlet boundary} - A Dirichlet boundary condition imposed on a differential equation
2246 which specifies the values the solution is to take on the boundary of the domain.
2247
2248    \item \indexedbold{elevation} - refers to bathymetry and topography
2249
2250    \item \indexedbold{bathymetry} - offshore elevation
2251
2252    \item \indexedbold{topography} - onshore elevation
2253
2254    \item \indexedbold{evolution} - integration of the shallow water wave equations over time
2255
2256    \item \indexedbold{forcing term}
2257
2258    \item \indexedbold{IDLE} - Development environment shipped with Python
2259
2260    \item \indexedbold{Manning friction coefficient}
2261
2262    \item \indexedbold{mesh}    - Triangulation of domain
2263
2264    \item \indexedbold{meshfile}  [generic word for either .tsh or
2265    .msh file]
2266
2267    \item \indexedbold{points file}  [generic word for either .pts or
2268    .xya file]
2269
2270    \item \indexedbold{grid} - evenly spaced mesh
2271
2272    \item \indexedbold{NetCDF}
2273
2274    \item \indexedbold{pmesh} does this really need to be here? it's a class/module?
2275
2276    \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?
2277
2278    \item \indexedbold{conserved quantity} conserved (stage, x and y momentum)
2279
2280    \item \indexedbold{reflective boundary}
2281
2282    \item \indexedbold{smoothing} is this really needed?
2283
2284    \item \indexedbold{stage}
2285
2286%    \item \indexedbold{try this}
2287
2288    \item \indexedbold{swollen} - visualisation tool
2289
2290    \item \indexedbold{time boundary} - defined in the manual (flog from there)
2291
2292    \item \indexedbold{transmissive boundary} - defined in the manual (flog from there)
2293
2294    \item \indexedbold{xmomentum} - conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
2295
2296    \item \indexedbold{ymomentum}  - conserved quantity
2297
2298    \item \indexedbold{resolution} -  The maximal area of a triangular cell in a mesh
2299
2300    \item \indexedbold{polygon} - A sequence of points in the plane. (Arbitrary polygons can be created
2301    in this way.)
2302    \anuga represents a polygon in one of two ways. One way is to represent it as a
2303    list whose members are either Python tuples
2304    or Python lists of length 2. The unit square, for example, would be represented by the
2305    list
2306    [ [0,0], [1,0], [1,1], [0,1] ]. The alternative is to represent it as an
2307    $N \times 2$ Numeric array, where $N$ is the number of points.
2308
2309    NOTE: More can be read in the module utilities/polygon.py ....
2310
2311    \item \indexedbold{easting} - A rectangular (x,y) coordinate measurement of distance east from a north-south reference line,
2312usually a meridian used as the axis of origin within a map zone or projection. Easting is a UTM (Universal Transverse Mercator) Coordinate.
2313
2314    \item \indexedbold{northing} - A rectangular (x,y) coordinate measurement of distance north from a north-south reference line,
2315usually a meridian used as the axis of origin within a map zone or projection. Northing is a UTM (Universal Transverse Mercator) Coordinate.
2316
2317
2318    \item \indexedbold{latitude} - The angular distance on a mericlear north and south of the equator, expressed in degrees and minutes.
2319
2320    \item \indexedbold{longitude} - The angular distance east or west, between the meridian of a particular place on Earth and that of the
2321Prime Meridian (located in Greenwich, England) expressed in degrees or time.
2322
2323    \item \indexedbold{edge} - A triangulare cell within the computational mesh can be depicted as a set of vertices joined by lines (the edges).
2324
2325    \item \indexedbold{vertex} - A point at which edges meet.
2326
2327    \item \indexedbold{finite volume} - The method evaluates the terms in the shallow water wave equationas fluxes at the surfaces of each
2328finite volume. Because the flux entering a given volume is identical to that leaving the adjacent volume, these methods are conservative.
2329Another advantage of the finite volume method is that it is easily formulated to allow for unstructured meshes.
2330The method is used in many computational fluid dynamics packages.
2331
2332
2333    \item \indexedbold{flux} - the amount of flow through the volume per unit time
2334
2335    \item \indexedbold{Digital Elevation Model (DEM)} - DEMs are digital files consisting of points of elevations,
2336sampled systematically at equally spaced intervals.
2337
2338
2339\end{itemize}
2340
2341The \code{\e appendix} markup need not be repeated for additional
2342appendices.
2343
2344
2345%
2346%  The ugly "%begin{latexonly}" pseudo-environments are really just to
2347%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
2348%  not really valuable.
2349%
2350%  If you don't want the Module Index, you can remove all of this up
2351%  until the second \input line.
2352%
2353
2354%begin{latexonly}
2355%\renewcommand{\indexname}{Module Index}
2356%end{latexonly}
2357\input{mod\jobname.ind}        % Module Index
2358%
2359%begin{latexonly}
2360%\renewcommand{\indexname}{Index}
2361%end{latexonly}
2362\input{\jobname.ind}            % Index
2363
2364
2365
2366\end{document}
Note: See TracBrowser for help on using the repository browser.