source: documentation/user_manual/anuga_user_manual.tex @ 3049

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

Minor corrections and additions in the first 4 chapters

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