source: documentation/user_manual/anuga_user_manual.tex @ 2708

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

Added reference to geospatial data

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