Ignore:
Timestamp:
May 22, 2009, 4:40:11 PM (11 years ago)
Author:
rwilson
Message:

Fiddling with layout of user guide.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • anuga_core/documentation/user_manual/anuga_user_manual.tex

    r6887 r7064  
    11% Complete documentation on the extended LaTeX markup used for Python
    2 % documentation is available in ``Documenting Python'', which is part
     2% documentation is available in ''Documenting Python'', which is part
    33% of the standard documentation for Python.  It may be found online
    44% at:
    55%
    66%     http://www.python.org/doc/current/doc/doc.html
    7 
    87
    98%labels
     
    1413
    1514% Is latex failing with;
    16 % `modanuga_user_manual.ind' not found?
     15% 'modanuga_user_manual.ind' not found?
    1716% try this command-line
    1817%   makeindex modanuga_user_manual.idx
    1918% To produce the modanuga_user_manual.ind file.
    20 
    2119
    2220%%%%%%%%%%%%%% TODO %%%%%%%%%%%%%%%%
     
    2624% set_geo_reference
    2725
    28 
    29 
    30 
    3126\documentclass{manual}
    3227
     
    3631
    3732\input{definitions}
     33
     34%%%%%
     35% Set penalties for widows, etc, very high
     36%%%%%
     37
     38\widowpenalty=10000
     39\clubpenalty=10000
     40\raggedbottom
    3841
    3942\title{\anuga User Manual}
     
    5457% stages to make it easier to handle versions.
    5558
    56 
    5759\longdate       % Make date format long using datetime.sty
    5860%\settimeformat{xxivtime} % 24 hour Format
     
    6264
    6365\ifhtml
    64 \date{\today} % latex2html does not know about datetime
     66  \date{\today} % latex2html does not know about datetime
    6567\fi
    66 
    67 
    68 
    6968
    7069\input{version} % Get version info - this file may be modified by
    7170                % update_anuga_user_manual.py - if not a dummy
    72                 % will be used.
    73                
     71                % will be used.
     72
    7473%\release{1.0}   % release version; this is used to define the
    7574%                % \version macro
     
    8180\setcounter{secnumdepth}{3}
    8281
     82% experimental code to get fig/table placement correct.
     83% doesn't have much effect.
     84%% Alter some LaTeX defaults for better treatment of figures:
     85%    % See p.105 of "TeX Unbound" for suggested values.
     86%    % See pp. 199-200 of Lamport's "LaTeX" book for details.
     87%    %   General parameters, for ALL pages:
     88%    \renewcommand{\topfraction}{0.9}   % max fraction of floats at top
     89%    \renewcommand{\bottomfraction}{0.8}        % max fraction of floats at bottom
     90%    %   Parameters for TEXT pages (not float pages):
     91%    \setcounter{topnumber}{2}
     92%    \setcounter{bottomnumber}{2}
     93%    \setcounter{totalnumber}{4}     % 2 may work better
     94%    \setcounter{dbltopnumber}{2}    % for 2-column pages
     95%    \renewcommand{\dbltopfraction}{0.9}        % fit big float above 2-col. text
     96%    \renewcommand{\textfraction}{0.07} % allow minimal text w. figs
     97%    %   Parameters for FLOAT pages (not text pages):
     98%    \renewcommand{\floatpagefraction}{0.7}     % require fuller float pages
     99%       % N.B.: floatpagefraction MUST be less than topfraction !!
     100%    \renewcommand{\dblfloatpagefraction}{0.7}  % require fuller float pages
     101%
     102%    % remember to use [htp] or [htpb] for placement
     103
     104%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    83105
    84106\begin{document}
    85107\maketitle
    86108
    87 
    88 
    89109% This makes the contents more accessible from the front page of the HTML.
    90110\ifhtml
    91 \chapter*{Front Matter\label{front}}
     111  \chapter*{Front Matter\label{front}}
    92112\fi
    93113
     
    100120\input{copyright}
    101121
    102 
    103122\begin{abstract}
    104123\label{def:anuga}
     
    118137governing equation using a finite-volume method.
    119138
    120 \anuga also incorporates a mesh generator %, called \code{graphical
    121                                 %mesh generator},
    122 that
     139\anuga also incorporates a mesh generator that
    123140allows the user to set up the geometry of the problem interactively as
    124141well as tools for interpolation and surface fitting, and a number of
     
    129146small Python programs based on the \anuga library
    130147functions. Computationally intensive components are written for
    131 efficiency in C routines working directly with the Numerical Python
    132 structures.
    133 
     148efficiency in C routines working directly with Python numpy structures.
    134149
    135150\end{abstract}
     
    137152\tableofcontents
    138153
     154%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    139155
    140156\chapter{Introduction}
     
    144160
    145161The purpose of this user manual is to introduce the new user to the
    146 inundation software, describe what it can do and give step-by-step
     162inundation software system, describe what it can do and give step-by-step
    147163instructions for setting up and running hydrodynamic simulations.
    148 The stable release of \anuga and this manual are available on sourceforge at \url{http://sourceforge.net/projects/anuga}. A snapshot of work in progress is available through the \anuga software repository at \url{https://datamining.anu.edu.au/svn/ga/anuga_core} where the more adventurous reader might like to go.
     164The stable release of \anuga and this manual are available on sourceforge ati
     165\url{http://sourceforge.net/projects/anuga}. A snapshot of work in progress is
     166available through the \anuga software repository at
     167\url{https://datamining.anu.edu.au/svn/ga/anuga_core}
     168where the more adventurous reader might like to go.
    149169
    150170
     
    156176which will be covered in separate publications and by documentation
    157177in the source code.
     178
    158179
    159180\section{Audience}
     
    167188\url{http://datamining.anu.edu.au/\~{}ole/work/teaching/ctac2006/exercise1.pdf}.
    168189
    169 
    170190Readers also need to have a general understanding of scientific modelling,
    171 as well as
    172 enough programming experience to adapt the code to different
     191as well as enough programming experience to adapt the code to different
    173192requirements.
    174193
    175 
    176 
    177194\pagebreak
     195
     196%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     197
    178198\chapter{Background}
    179 
    180199
    181200Modelling the effects on the built environment of natural hazards such
     
    197216and around structures such as buildings.  \anuga is also capable
    198217of modelling hydraulic jumps due to the ability of the finite-volume
    199 method to accommodate discontinuities in the solution/footnote{While \anuga works with discontinuities in the conserved quantities stage, xmomentum and ymomentum, it does not allow discontinuities in the bed elevation}.
     218method to accommodate discontinuities in the solution
     219\footnote{While \anuga works with discontinuities in the conserved quantities stage,
     220          xmomentum and ymomentum, it does not allow discontinuities in the bed elevation}.
    200221
    201222To set up a particular scenario the user specifies the geometry
    202223(bathymetry and topography), the initial water level (stage),
    203224boundary conditions such as tide, and any forcing terms that may
    204 drive the system such as rain_fall, abstraction of water, wind stress or atmospheric pressure
     225drive the system such as rainfall, abstraction of water, wind stress or atmospheric pressure
    205226gradients. Gravity and frictional resistance from the different
    206227terrains in the model are represented by predefined forcing terms.
    207 See section \ref{sec:forcing terms} for details on forcing terms available in ANUGA.
     228See section \ref{sec:forcing terms} for details on forcing terms available in \anuga.
    208229
    209230The built-in mesh generator, called \code{graphical\_mesh\_generator},
     
    218239and can be readily adapted to changing requirements throughout its
    219240lifetime.  Computationally intensive components are written for
    220 efficiency in C routines working directly with the Numerical Python
     241efficiency in C routines working directly with Python numeric
    221242structures.  The animation tool developed for \anuga is based on
    222243OpenSceneGraph, an Open Source Software (OSS) component allowing high
     
    228249
    229250Although a powerful and flexible tool for hydrodynamic modelling, \anuga has a
    230 number of limitations that any potential user need to be aware of. They are
     251number of limitations that any potential user needs to be aware of. They are:
    231252
    232253\begin{itemize}
     
    237258  %flow under ceilings or in pipes
    238259  \item All spatial coordinates are assumed to be UTM (meters). As such,
    239   ANUGA is unsuitable for modelling flows in areas larger than one UTM zone
     260  \anuga is unsuitable for modelling flows in areas larger than one UTM zone
    240261  (6 degrees wide).
    241   \item Fluid is assumed to be inviscid - i.e.\ no kinematic viscosity included.
     262  \item Fluid is assumed to be inviscid -- i.e.\ no kinematic viscosity included.
    242263  \item The finite volume is a very robust and flexible numerical technique,
    243264  but it is not the fastest method around. If the geometry is sufficiently
    244265  simple and if there is no need for wetting or drying, a finite-difference
    245266  method may be able to solve the problem faster than \anuga.
    246   %\item Mesh resolutions near coastlines with steep gradients need to be...
     267%\item Mesh resolutions near coastlines with steep gradients need to be...
    247268  \item Frictional resistance is implemented using Manning's formula, but
    248   \anuga has not yet been fully validated in regard to bottom roughness
    249   %\item ANUGA contains no tsunami-genic functionality relating to
    250   %earthquakes.
     269  \anuga has not yet been fully validated in regard to bottom roughness.
     270%\item ANUGA contains no tsunami-genic functionality relating to earthquakes.
    251271\end{itemize}
    252272
    253 
     273%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    254274
    255275\chapter{Getting Started}
     
    261281the second is a more realistic example.
    262282
     283
    263284\section{A Simple Example}
    264285\label{sec:simpleexample}
     
    278299(bathymetry and topography), the initial water level, boundary
    279300conditions such as tide, and any forcing terms that may drive the
    280 system such as rain_fall, abstraction of water, wind stress or atmospheric pressure gradients.
     301system such as rainfall, abstraction of water, wind stress or atmospheric pressure gradients.
    281302Frictional resistance from the different terrains in the model is
    282303represented by predefined forcing terms. In this example, the
     
    293314involved in the computation are the friction and elevation.
    294315
    295 Water depth can be obtained through the equation
    296 
    297 \begin{tabular}{rcrcl}
    298   \code{depth} &=& \code{stage} &$-$& \code{elevation}
    299 \end{tabular}
    300 
     316Water depth can be obtained through the equation:
     317
     318\begin{verbatim}
     319depth = stage - elevation
     320\end{verbatim}
    301321
    302322\subsection{Outline of the Program}
    303323
    304324In outline, \file{runup.py} performs the following steps:
    305 
    306325\begin{enumerate}
    307 
    308326   \item Sets up a triangular mesh.
    309 
    310327   \item Sets certain parameters governing the mode of
    311 operation of the model-specifying, for instance, where to store the model output.
    312 
     328         operation of the model, specifying, for instance,
     329         where to store the model output.
    313330   \item Inputs various quantities describing physical measurements, such
    314 as the elevation, to be specified at each mesh point (vertex).
    315 
     331         as the elevation, to be specified at each mesh point (vertex).
    316332   \item Sets up the boundary conditions.
    317 
    318333   \item Carries out the evolution of the model through a series of time
    319 steps and outputs the results, providing a results file that can
    320 be visualised.
    321 
     334         steps and outputs the results, providing a results file that can
     335         be viewed.
    322336\end{enumerate}
    323337
     
    328342For reference we include below the complete code listing for
    329343\file{runup.py}. Subsequent paragraphs provide a
    330 `commentary' that describes each step of the program and explains it
     344'commentary' that describes each step of the program and explains it
    331345significance.
    332346
     
    338352scenario. This is carried out through the statement:
    339353
    340 {\small \begin{verbatim}
    341     points, vertices, boundary = rectangular_cross(10, 10)
    342 \end{verbatim}}
     354\begin{verbatim}
     355points, vertices, boundary = rectangular_cross(10, 10)
     356\end{verbatim}
    343357
    344358The function \function{rectangular_cross} is imported from a module
     
    346360several other schemes that can be used for setting up meshes, but we
    347361shall not discuss these.) The above assignment sets up a $10 \times
    348 10$ rectangular mesh, triangulated in a regular way. The assignment
    349 
    350 {\small \begin{verbatim}
    351     points, vertices, boundary = rectangular_cross(m, n)
    352 \end{verbatim}}
     36210$ rectangular mesh, triangulated in a regular way. The assignment:
     363
     364\begin{verbatim}
     365points, vertices, boundary = rectangular_cross(m, n)
     366\end{verbatim}
    353367
    354368returns:
    355369
    356370\begin{itemize}
    357 
    358371   \item a list \code{points} giving the coordinates of each mesh point,
    359 
    360372   \item a list \code{vertices} specifying the three vertices of each triangle, and
    361 
    362373   \item a dictionary \code{boundary} that stores the edges on
    363    the boundary and associates each with one of the symbolic tags \code{`left'}, \code{`right'},
    364    \code{`top'} or \code{`bottom'}.
    365 
     374         the boundary and associates each with one of the symbolic tags \code{'left'}, \code{'right'},
     375         \code{'top'} or \code{'bottom'}.
    366376\end{itemize}
    367377
     
    373383given in Section \ref{sec:meshexample}.
    374384
    375 
    376 
    377 
    378385\subsection{Initialising the Domain}
    379386
     
    381388\code{domain}, through the assignment:
    382389
    383 {\small \begin{verbatim}
    384     domain = Domain(points, vertices, boundary)
    385 \end{verbatim}}
     390\begin{verbatim}
     391domain = Domain(points, vertices, boundary)
     392\end{verbatim}
    386393
    387394This creates an instance of the \class{Domain} class, which
     
    390397directory to be used for data:
    391398
    392 {\small \begin{verbatim}
    393     domain.set_name('runup')
    394 \end{verbatim}}
    395 
    396 {\small \begin{verbatim}
    397     domain.set_datadir('.')
    398 \end{verbatim}}
     399\begin{verbatim}
     400domain.set_name('runup')
     401domain.set_datadir('.')
     402\end{verbatim}
    399403
    400404In addition, the following statement now specifies that the
     
    402406to be stored:
    403407
    404 {\small \begin{verbatim}
    405     domain.set_quantities_to_be_stored(['stage', 'xmomentum',
    406     'ymomentum'])
    407 \end{verbatim}}
    408 
     408\begin{verbatim}
     409domain.set_quantities_to_be_stored(['stage', 'xmomentum', 'ymomentum'])
     410\end{verbatim}
    409411
    410412\subsection{Initial Conditions}
     
    414416\method{set\_quantity}, used to specify these quantities. It is a
    415417flexible method that allows the user to set quantities in a variety
    416 of ways---using constants, functions, numeric arrays, expressions
     418of ways -- using constants, functions, numeric arrays, expressions
    417419involving other quantities, or arbitrary data points with associated
    418420values, all of which can be passed as arguments. All quantities can
     
    424426forms in which we can invoke \method{set\_quantity}.
    425427
    426 
    427428\subsubsection{Elevation}
    428429
    429 The elevation, or height of the bed, is set using a function,
     430The elevation, or height of the bed, is set using a function
    430431defined through the statements below, which is specific to this
    431432example and specifies a particularly simple initial configuration
    432433for demonstration purposes:
    433434
    434 {\small \begin{verbatim}
    435     def f(x,y):
    436         return -x/2
    437 \end{verbatim}}
     435\begin{verbatim}
     436def f(x,y):
     437    return -x/2
     438\end{verbatim}
    438439
    439440This simply associates an elevation with each point \code{(x, y)} of
     
    445446\code{elevation} is assigned through the simple statement:
    446447
    447 {\small \begin{verbatim}
    448     domain.set_quantity('elevation', f)
    449 \end{verbatim}}
     448\begin{verbatim}
     449domain.set_quantity('elevation', f)
     450\end{verbatim}
    450451
    451452NOTE: If using function to set \code{elevation} it must be vector
     
    456457The assignment of the friction quantity (a forcing term)
    457458demonstrates another way we can use \method{set\_quantity} to set
    458 quantities---namely, assign them to a constant numerical value:
    459 
    460 {\small \begin{verbatim}
    461     domain.set_quantity('friction', 0.1)
    462 \end{verbatim}}
     459quantities -- namely, assign them to a constant numerical value:
     460
     461\begin{verbatim}
     462domain.set_quantity('friction', 0.1)
     463\end{verbatim}
    463464
    464465This specifies that the Manning friction coefficient is set to 0.1
     
    468469
    469470The stage (the height of the water surface) is related to the
    470 elevation and the depth at any time by the equation
    471 
    472 {\small \begin{verbatim}
    473     stage = elevation + depth
    474 \end{verbatim}}
    475 
     471elevation and the depth at any time by the equation:
     472
     473\begin{verbatim}
     474stage = elevation + depth
     475\end{verbatim}
    476476
    477477For this example, we simply assign a constant value to \code{stage},
    478 using the statement
    479 
    480 {\small \begin{verbatim}
    481     domain.set_quantity('stage', -.4)
    482 \end{verbatim}}
     478using the statement:
     479
     480\begin{verbatim}
     481domain.set_quantity('stage', -0.4)
     482\end{verbatim}
    483483
    484484which specifies that the surface level is set to a height of $-0.4$,
     
    487487Although it is not necessary for this example, it may be useful to
    488488digress here and mention a variant to this requirement, which allows
    489 us to illustrate another way to use \method{set\_quantity}---namely,
     489us to illustrate another way to use \method{set\_quantity} -- namely,
    490490incorporating an expression involving other quantities. Suppose,
    491491instead of setting a constant value for the stage, we wished to
     
    495495would do this by means of the statements:
    496496
    497 {\small \begin{verbatim}
    498     h = 0.05 # Constant depth
    499     domain.set_quantity('stage', expression = 'elevation + %f' %h)
    500 \end{verbatim}}
     497\begin{verbatim}
     498h = 0.05    # Constant depth
     499domain.set_quantity('stage', expression='elevation + %f' % h)
     500\end{verbatim}
    501501
    502502That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus
     
    505505The reader will probably appreciate that this capability to
    506506incorporate expressions into statements using \method{set\_quantity}
    507 greatly expands its power.) See Section \ref{sec:initial conditions} for more
     507greatly expands its power. See Section \ref{sec:initial conditions} for more
    508508details.
    509509
     
    512512The boundary conditions are specified as follows:
    513513
    514 {\small \begin{verbatim}
    515     Br = Reflective_boundary(domain)
    516 
    517     Bt = Transmissive_boundary(domain)
    518 
    519     Bd = Dirichlet_boundary([0.2,0.,0.])
    520 
    521     Bw = Time_boundary(domain=domain,
    522                 f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
    523 \end{verbatim}}
     514\begin{verbatim}
     515Br = Reflective_boundary(domain)
     516
     517Bt = Transmissive_boundary(domain)
     518
     519Bd = Dirichlet_boundary([0.2, 0.0, 0.0])
     520
     521Bw = Time_boundary(domain=domain, f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
     522\end{verbatim}
    524523
    525524The effect of these statements is to set up a selection of different
     
    529528elements. The boundary conditions introduced here may be briefly described as
    530529follows:
    531 
    532530\begin{itemize}
    533531    \item \textbf{Reflective boundary}\label{def:reflective boundary} Returns same \code{stage} as
    534       as present in its neighbour volume but momentum vector
    535       reversed 180 degrees (reflected).
    536       Specific to the shallow water equation as it works with the
    537       momentum quantities assumed to be the second and third conserved
    538       quantities. A reflective boundary condition models a solid wall.
     532          as present in its neighbour volume but momentum vector
     533          reversed 180 degrees (reflected).
     534          Specific to the shallow water equation as it works with the
     535          momentum quantities assumed to be the second and third conserved
     536          quantities. A reflective boundary condition models a solid wall.
    539537    \item \textbf{Transmissive boundary}\label{def:transmissive boundary}
    540       Returns same conserved quantities as
    541       those present in its neighbour volume. This is one way of modelling
    542       outflow from a domain, but it should be used with caution if flow is
    543       not steady state as replication of momentum at the boundary
    544       may cause numerical instabilities propagating into the domain and
    545       eventually causing ANUGA to crash. If this occurs,
    546       consider using e.g. a Dirichlet boundary condition with a stage value
    547       less than the elevation at the boundary.
     538          Returns same conserved quantities as
     539          those present in its neighbour volume. This is one way of modelling
     540          outflow from a domain, but it should be used with caution if flow is
     541          not steady state as replication of momentum at the boundary
     542          may cause numerical instabilities propagating into the domain and
     543          eventually causing ANUGA to crash. If this occurs,
     544          consider using e.g. a Dirichlet boundary condition with a stage value
     545          less than the elevation at the boundary.
    548546    \item \textbf{Dirichlet boundary}\label{def:dirichlet boundary} Specifies
    549       constant values for stage, $x$-momentum and $y$-momentum at the boundary.
     547          constant values for stage, $x$-momentum and $y$-momentum at the boundary.
    550548    \item \textbf{Time boundary}\label{def:time boundary} Like a Dirichlet
    551       boundary but with behaviour varying with time.
     549          boundary but with behaviour varying with time.
    552550\end{itemize}
    553551
     
    556554three variables \code{points}, \code{vertices} and \code{boundary}.
    557555In the code we are discussing, these three variables are returned by
    558 the function \code{rectangular}; however, the example given in
     556the function \code{rectangular}. The example given in
    559557Section \ref{sec:realdataexample} illustrates another way of
    560558assigning the values, by means of the function
    561 \code{create\_mesh\_from\_regions}.
     559\code{create_mesh_from_regions}.
    562560
    563561These variables store the data determining the mesh as follows. (You
     
    565563helps to clarify the following discussion, even though that example
    566564is a \emph{non-rectangular} mesh.)
    567 
    568565\begin{itemize}
    569 \item The variable \code{points} stores a list of 2-tuples giving the
    570 coordinates of the mesh points.
    571 
    572 \item The variable \code{vertices} stores a list of 3-tuples of
    573 numbers, representing vertices of triangles in the mesh. In this
    574 list, the triangle whose vertices are \code{points[i]},
    575 \code{points[j]}, \code{points[k]} is represented by the 3-tuple
    576 \code{(i, j, k)}.
    577 
    578 \item The variable \code{boundary} is a Python dictionary that
    579 not only stores the edges that make up the boundary but also assigns
    580 symbolic tags to these edges to distinguish different parts of the
    581 boundary. An edge with endpoints \code{points[i]} and
    582 \code{points[j]} is represented by the 2-tuple \code{(i, j)}. The
    583 keys for the dictionary are the 2-tuples \code{(i, j)} corresponding
    584 to boundary edges in the mesh, and the values are the tags are used
    585 to label them. In the present example, the value \code{boundary[(i,
    586 j)]} assigned to \code{(i, j)]} is one of the four tags
    587 \code{`left'}, \code{`right'}, \code{`top'} or \code{`bottom'},
    588 depending on whether the boundary edge represented by \code{(i, j)}
    589 occurs at the left, right, top or bottom of the rectangle bounding
    590 the mesh. The function \code{rectangular} automatically assigns
    591 these tags to the boundary edges when it generates the mesh.
     566    \item The variable \code{points} stores a list of 2-tuples giving the
     567          coordinates of the mesh points.
     568    \item The variable \code{vertices} stores a list of 3-tuples of
     569          numbers, representing vertices of triangles in the mesh. In this
     570          list, the triangle whose vertices are \code{points[i]},
     571          \code{points[j]}, \code{points[k]} is represented by the 3-tuple
     572          \code{(i, j, k)}.
     573    \item The variable \code{boundary} is a Python dictionary that
     574          not only stores the edges that make up the boundary but also assigns
     575          symbolic tags to these edges to distinguish different parts of the
     576          boundary. An edge with endpoints \code{points[i]} and
     577          \code{points[j]} is represented by the 2-tuple \code{(i, j)}. The
     578          keys for the dictionary are the 2-tuples \code{(i, j)} corresponding
     579          to boundary edges in the mesh, and the values are the tags are used
     580          to label them. In the present example, the value \code{boundary[(i, j)]}
     581          assigned to \code{(i, j)]} is one of the four tags
     582          \code{'left'}, \code{'right'}, \code{'top'} or \code{'bottom'},
     583          depending on whether the boundary edge represented by \code{(i, j)}
     584          occurs at the left, right, top or bottom of the rectangle bounding
     585          the mesh. The function \code{rectangular} automatically assigns
     586          these tags to the boundary edges when it generates the mesh.
    592587\end{itemize}
    593588
     
    595590to an edge depending on which part of the boundary it belongs to.
    596591(In Section \ref{sec:realdataexample} we describe an example that
    597 uses different boundary tags --- in general, the possible tags are entirely selectable by the user when generating the mesh and not
    598 limited to `left', `right', `top' and `bottom' as in this example.)
     592uses different boundary tags -- in general, the possible tags are entirely selectable by the user when generating the mesh and not
     593limited to 'left', 'right', 'top' and 'bottom' as in this example.)
    599594All segments in bounding polygon must be tagged. If a tag is not supplied, the default tag name 'exterior' will be assigned by ANUGA.
    600595
    601 
    602596Using the boundary objects described above, we assign a boundary
    603 condition to each part of the boundary by means of a statement like
    604 
    605 {\small \begin{verbatim}
    606     domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
    607 \end{verbatim}}
    608 
    609 It is critical that all tags are assoctiated with a boundary conditing in this statement. If not the program will halt with a statement like
     597condition to each part of the boundary by means of a statement like:
    610598
    611599\begin{verbatim}
    612 
     600domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
     601\end{verbatim}
     602
     603It is critical that all tags are associated with a boundary condition in this statement.
     604If not the program will halt with a statement like:
     605
     606\begin{verbatim}
    613607Traceback (most recent call last):
    614608  File "mesh_test.py", line 114, in ?
     
    621615\end{verbatim}
    622616
    623 
    624 The command \code{set\_boundary} stipulates that, in the current example, the right
     617The command \code{set_boundary} stipulates that, in the current example, the right
    625618boundary varies with time, as defined by the lambda function, while the other
    626619boundaries are all reflective.
     
    631624\code{stage}, $x$-momentum and $y$-momentum, respectively.)
    632625
    633 {\small \begin{verbatim}
    634     Bw = Time_boundary(domain=domain,
    635                        f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
    636 \end{verbatim}}
    637 
    638 
     626\begin{verbatim}
     627Bw = Time_boundary(domain=domain, f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
     628\end{verbatim}
    639629
    640630\subsection{Evolution}\index{evolution}
    641631
    642 The final statement \nopagebreak[3]
    643 {\small \begin{verbatim}
    644     for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
    645         print domain.timestepping_statistics()
    646 \end{verbatim}}
    647 
    648 causes the configuration of the domain to `evolve', over a series of
     632The final statement:
     633
     634\begin{verbatim}
     635for t in domain.evolve(yieldstep=0.1, duration=4.0):
     636    print domain.timestepping_statistics()
     637\end{verbatim}
     638
     639causes the configuration of the domain to 'evolve', over a series of
    649640steps indicated by the values of \code{yieldstep} and
    650641\code{duration}, which can be altered as required.  The value of
     
    652643outputs.  Behind the scenes more time steps are generally taken.
    653644
    654 
    655645\subsection{Output}
    656646
    657647The output is a NetCDF file with the extension \code{.sww}. It
    658648contains stage and momentum information and can be used with the
    659 ANUGA viewer \code{animate} (see Section \ref{sec:animate})
    660 visualisation package
    661 to generate a visual display. See Section \ref{sec:file formats}
     649ANUGA viewer \code{animate} visualisation package to generate a visual
     650display (see Section \ref{sec:animate}). See Section \ref{sec:file formats}
    662651(page \pageref{sec:file formats}) for more on NetCDF and other file
    663652formats.
     
    672661
    673662The code can be run in various ways:
    674 
    675663\begin{itemize}
    676664  \item{from a Windows or Unix command line} as in\ \code{python runup.py}
     
    689677Figure \ref{fig:runup2} shows later snapshots for $t=2.3$ and
    690678$t=4$ where the system has been evolved and the wave is encroaching
    691 on the previously dry bed.  All figures are screenshots from an
    692 interactive animation tool called animate which is part of \anuga and
    693 distributed as in the package anuga\_viewer.
    694 Animate is described in more detail is Section \ref{sec:animate}.
    695 
    696 \begin{figure}[hbt]
    697 
     679on the previously dry bed.
     680
     681All figures are screenshots from an interactive animation tool called \code{animate}
     682which is part of \anuga and distributed as in the package anuga\_viewer.
     683\code{animate} is described in more detail is Section \ref{sec:animate}.
     684
     685\begin{figure}[htp]
    698686  \centerline{\includegraphics[width=75mm, height=75mm]
    699687    {graphics/bedslopestart.jpg}}
    700 
    701688  \caption{Runup example viewed with the ANUGA viewer}
    702689  \label{fig:runupstart}
    703690\end{figure}
    704691
    705 
    706 \begin{figure}[hbt]
    707 
     692\begin{figure}[htp]
    708693  \centerline{
    709    \includegraphics[width=75mm, height=75mm]{graphics/bedslopeduring.jpg}
     694    \includegraphics[width=75mm, height=75mm]{graphics/bedslopeduring.jpg}
    710695    \includegraphics[width=75mm, height=75mm]{graphics/bedslopeend.jpg}
    711696   }
    712 
    713697  \caption{Runup example viewed with ANGUA viewer}
    714698  \label{fig:runup2}
    715699\end{figure}
    716700
    717 
    718 
    719701\clearpage
    720702
    721 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    722703
    723704\section{A slightly more complex example}
     
    727708
    728709The next example is about waterflow in a channel with varying boundary conditions and
    729 more complex topograhies. These examples build on the
     710more complex topographies. These examples build on the
    730711concepts introduced through the \file{runup.py} in Section \ref{sec:simpleexample}.
    731712The example will be built up through three progressively more complex scripts.
    732713
    733714\subsection{Overview}
     715
    734716As in the case of \file{runup.py}, the actions carried
    735717out by the program can be organised according to this outline:
    736 
    737718\begin{enumerate}
    738 
    739719   \item Set up a triangular mesh.
    740 
    741720   \item Set certain parameters governing the mode of
    742 operation of the model---specifying, for instance, where to store the
    743 model output.
    744 
     721         operation of the model -- specifying, for instance, where to store the
     722         model output.
    745723   \item Set up initial conditions for various quantities such as the elevation, to be specified at each mesh point (vertex).
    746 
    747724   \item Set up the boundary conditions.
    748 
    749725   \item Carry out the evolution of the model through a series of time
    750 steps and output the results, providing a results file that can be
    751 visualised.
    752 
     726         steps and output the results, providing a results file that can be
     727         viewed.
    753728\end{enumerate}
    754729
    755 
    756730\subsection{The Code}
    757731
    758732Here is the code for the first version of the channel flow \file{channel1.py}:
    759 
    760733\verbatiminput{demos/channel1.py}
    761 
    762734In discussing the details of this example, we follow the outline
    763735given above, discussing each major step of the code in turn.
     
    765737\subsection{Establishing the Mesh}\index{mesh, establishing}
    766738
    767 In this example we use a similar simple structured triangular mesh as in \code{runup.py}
     739In this example we use a similar simple structured triangular mesh as in \file{runup.py}
    768740for simplicity, but this time we will use a symmetric one and also
    769 change the physical extent of the domain. The assignment
    770 
    771 {\small \begin{verbatim}
    772     points, vertices, boundary = rectangular_cross(m, n,
    773                                                    len1=length, len2=width)
    774 \end{verbatim}}
    775 returns a m x n mesh similar to the one used in the previous example, except that now the
     741change the physical extent of the domain. The assignment:
     742
     743\begin{verbatim}
     744points, vertices, boundary = rectangular_cross(m, n, len1=length, len2=width)
     745\end{verbatim}
     746
     747returns an \code{m x n} mesh similar to the one used in the previous example, except that now the
    776748extent in the x and y directions are given by the value of \code{length} and \code{width}
    777749respectively.
    778750
    779 Defining m and n in terms of the extent as in this example provides a convenient way of
    780 controlling the resolution: By defining dx and dy to be the desired size of each hypothenuse in the mesh we can write the mesh generation as follows:
    781 
    782 {\small \begin{verbatim}
    783 length = 10.
    784 width = 5.
     751Defining \code{m} and \code{n} in terms of the extent as in this example provides a convenient way of
     752controlling the resolution: By defining \code{dx} and \code{dy} to be the desired size of each
     753hypothenuse in the mesh we can write the mesh generation as follows:
     754
     755\begin{verbatim}
     756length = 10.0
     757width = 5.0
    785758dx = dy = 1           # Resolution: Length of subdivisions on both axes
    786759
    787760points, vertices, boundary = rectangular_cross(int(length/dx), int(width/dy),
    788761                                               len1=length, len2=width)
    789 \end{verbatim}}
    790 which yields a mesh of length=10m, width=5m with 1m spacings. To increase the resolution, as we will later in this example, one merely decrease the values of dx and dy.
     762\end{verbatim}
     763
     764which yields a mesh of length=10m, width=5m with 1m spacings. To increase the resolution,
     765as we will later in this example, one merely decreases the values of \code{dx} and \code{dy}.
    791766
    792767The rest of this script is as in the previous example.
    793 % except for an application of the 'expression' form of \code{set\_quantity} where we use the value of \code{elevation} to define the (dry) initial condition for \code{stage}:
    794 %{\small \begin{verbatim}
     768% except for an application of the 'expression' form of \code{set\_quantity} where we use
     769% the value of \code{elevation} to define the (dry) initial condition for \code{stage}:
     770%\begin{verbatim}
    795771%  domain.set_quantity('stage', expression='elevation')
    796 %\end{verbatim}}
     772%\end{verbatim}
     773
    797774
    798775\section{Model Output}
     
    800777The following figure is a screenshot from the \anuga visualisation
    801778tool \code{animate} of output from this example.
    802 \begin{figure}[hbt]
     779
     780\begin{figure}[htp]
    803781  \centerline{\includegraphics[height=75mm]
    804782    {graphics/channel1.png}}%
    805 
    806783  \caption{Simple channel example viewed with the ANUGA viewer.}
    807784  \label{fig:channel1}
    808785\end{figure}
    809786
    810 
    811787\subsection{Changing boundary conditions on the fly}
    812788\label{sec:change boundary}
    813789
    814790Here is the code for the second version of the channel flow \file{channel2.py}:
     791
    815792\verbatiminput{demos/channel2.py}
     793
    816794This example differs from the first version in that a constant outflow boundary condition has
    817 been defined
    818 {\small \begin{verbatim}
    819     Bo = Dirichlet_boundary([-5, 0, 0]) # Outflow
    820 \end{verbatim}}
     795been defined:
     796
     797\begin{verbatim}
     798Bo = Dirichlet_boundary([-5, 0, 0])    # Outflow
     799\end{verbatim}
     800
    821801and that it is applied to the right hand side boundary when the water level there exceeds 0m.
    822 {\small \begin{verbatim}
     802
     803\begin{verbatim}
    823804for t in domain.evolve(yieldstep = 0.2, finaltime = 40.0):
    824805    domain.write_time()
     
    827808        print 'Stage > 0: Changing to outflow boundary'
    828809        domain.set_boundary({'right': Bo})
    829 \end{verbatim}}
     810\end{verbatim}
     811
    830812\label{sec:change boundary code}
    831 
    832 The if statement in the timestepping loop (evolve) gets the quantity
    833 \code{stage} and obtain the interpolated value at the point (10m,
     813The \code{if} statement in the timestepping loop (evolve) gets the quantity
     814\code{stage} and obtains the interpolated value at the point (10m,
    8348152.5m) which is on the right boundary. If the stage exceeds 0m a
    835816message is printed and the old boundary condition at tag 'right' is
    836 replaced by the outflow boundary using the method
    837 {\small \begin{verbatim}
    838     domain.set_boundary({'right': Bo})
    839 \end{verbatim}}
     817replaced by the outflow boundary using the method:
     818
     819\begin{verbatim}
     820domain.set_boundary({'right': Bo})
     821\end{verbatim}
     822
    840823This type of dynamically varying boundary could for example be
    841 used to model the
    842 breakdown of a sluice door when water exceeds a certain level.
     824used to model the breakdown of a sluice door when water exceeds a certain level.
    843825
    844826\subsection{Output}
    845827
    846 The text output from this example looks like this
    847 {\small \begin{verbatim}
     828The text output from this example looks like this:
     829
     830\begin{verbatim}
    848831...
    849832Time = 15.4000, delta t in [0.03789902, 0.03789916], steps=6 (6)
     
    854837Time = 16.2000, delta t in [0.03789892, 0.03789904], steps=6 (6)
    855838...
    856 \end{verbatim}}
    857 
     839\end{verbatim}
    858840
    859841\subsection{Flow through more complex topograhies}
    860842
    861843Here is the code for the third version of the channel flow \file{channel3.py}:
     844
    862845\verbatiminput{demos/channel3.py}
    863846
     
    865848contains obstacles.
    866849
    867 This is accomplished here by defining the function \code{topography} as follows
    868 {\small \begin{verbatim}
     850This is accomplished here by defining the function \code{topography} as follows:
     851
     852\begin{verbatim}
    869853def topography(x,y):
    870     """Complex topography defined by a function of vectors x and y
    871     """
     854    """Complex topography defined by a function of vectors x and y."""
    872855
    873856    z = -x/10
     
    875858    N = len(x)
    876859    for i in range(N):
    877 
    878860        # Step
    879861        if 10 < x[i] < 12:
     
    889871
    890872    return z
    891 \end{verbatim}}
    892 
    893 In addition, changing the resolution to dx=dy=0.1 creates a finer mesh resolving the new featurse better.
    894 
    895 A screenshot of this model at time == 15s is
    896 \begin{figure}[hbt]
    897 
     873\end{verbatim}
     874
     875In addition, changing the resolution to \code{dx = dy = 0.1} creates a finer mesh resolving the new features better.
     876
     877A screenshot of this model at time 15s is:
     878\begin{figure}[htp]
    898879  \centerline{\includegraphics[height=75mm]
    899880    {graphics/channel3.png}}
    900 
    901881  \caption{More complex flow in a channel}
    902882  \label{fig:channel3}
     
    904884
    905885
    906 
    907 
    908 \clearpage
    909 
    910 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    911 
    912886\section{An Example with Real Data}
     887
    913888\label{sec:realdataexample} The following discussion builds on the
    914889concepts introduced through the \file{runup.py} example and
     
    931906As in the case of \file{runup.py}, the actions carried
    932907out by the program can be organised according to this outline:
    933 
    934908\begin{enumerate}
    935 
    936909   \item Set up a triangular mesh.
    937910
    938911   \item Set certain parameters governing the mode of
    939 operation of the model---specifying, for instance, where to store the
    940 model output.
     912         operation of the model -- specifying, for instance, where to store the
     913         model output.
    941914
    942915   \item Input various quantities describing physical measurements, such
    943 as the elevation, to be specified at each mesh point (vertex).
     916         as the elevation, to be specified at each mesh point (vertex).
    944917
    945918   \item Set up the boundary conditions.
    946919
    947920   \item Carry out the evolution of the model through a series of time
    948 steps and output the results, providing a results file that can be
    949 visualised.
    950 
     921         steps and output the results, providing a results file that can be
     922         visualised.
    951923\end{enumerate}
    952 
    953 
    954924
    955925\subsection{The Code}
     
    973943In its simplest form, the mesh-generator creates the mesh within a single
    974944polygon whose vertices are at geographical locations specified by
    975 the user. The user specifies the \emph{resolution}---that is, the
    976 maximal area of a triangle used for triangulation---and a triangular
     945the user. The user specifies the \emph{resolution} -- that is, the
     946maximal area of a triangle used for triangulationR -- and a triangular
    977947mesh is created inside the polygon using a mesh generation engine.
    978948On any given platform, the same mesh will be returned.
     
    981951%triangulation is carried out within a pentagon.
    982952
    983 
    984 %\begin{figure}[hbt]
    985 
     953%\begin{figure}[htp]
    986954%  \caption{Mesh points are created inside the polygon}
    987955  %\label{fig:pentagon}
    988956%\end{figure}
    989957
    990 Boundary tags are not restricted to \code{`left'}, \code{`bottom'},
    991 \code{`right'} and \code{`top'}, as in the case of
     958Boundary tags are not restricted to \code{'left'}, \code{'bottom'},
     959\code{'right'} and \code{'top'}, as in the case of
    992960\file{runup.py}. Instead the user specifies a list of
    993961tags appropriate to the configuration being modelled.
     
    998966a number of \emph{interior polygons}, each with a specified
    999967resolution. It is also
    1000 possible to specify one or more `holes'---that is, areas bounded by
     968possible to specify one or more 'holes' -- that is, areas bounded by
    1001969polygons in which no triangulation is required.
    1002970
    1003 %\begin{figure}[hbt]
     971%\begin{figure}[htp]
    1004972%  \caption{Interior meshes with individual resolution}
    1005973%  \label{fig:interior meshes}
     
    1025993extension \code{.tsh}. In the present case, the binary file format
    1026994\code{.msh} is used. See Section \ref{sec:file formats} (page
    1027 \pageref{sec:file formats}) for more on file formats.)
     995\pageref{sec:file formats}) for more on file formats.
    1028996
    1029997In practice, the details of the polygons used are read from a
     
    10431011would decrease to the order of tens of metres.
    10441012
    1045 \begin{figure}[hbt]
    1046 \centerline{\includegraphics[scale=0.5]{graphics/cairns3.jpg}}
    1047 \caption{Landscape of the Cairns scenario.}
    1048 \label{fig:cairns3d}
    1049 
     1013\clearpage
     1014
     1015\begin{figure}[htp]
     1016  \centerline{\includegraphics[scale=0.5]{graphics/cairns3.jpg}}
     1017  \caption{Landscape of the Cairns scenario.}
     1018  \label{fig:cairns3d}
    10501019\end{figure}
     1020
    10511021The following statements are used to read in the specific polygons
    10521022from \code{project.cairns} and assign a defined resolution to
    10531023each polygon.
    10541024
    1055 {\small \begin{verbatim}
    1056     islands_res = 100000
    1057     cairns_res = 100000
    1058     shallow_res = 500000
    1059     interior_regions = [[project.poly_cairns, cairns_res],
    1060                         [project.poly_island0, islands_res],
    1061                         [project.poly_island1, islands_res],
    1062                         [project.poly_island2, islands_res],
    1063                         [project.poly_island3, islands_res],
    1064                         [project.poly_shallow, shallow_res]]
    1065 \end{verbatim}}
     1025\begin{verbatim}
     1026islands_res = 100000
     1027cairns_res = 100000
     1028shallow_res = 500000
     1029interior_regions = [[project.poly_cairns, cairns_res],
     1030                    [project.poly_island0, islands_res],
     1031                    [project.poly_island1, islands_res],
     1032                    [project.poly_island2, islands_res],
     1033                    [project.poly_island3, islands_res],
     1034                    [project.poly_shallow, shallow_res]]
     1035\end{verbatim}
    10661036
    10671037Figure \ref{fig:cairnspolys}
    10681038illustrates the polygons used for the Cairns scenario.
    10691039
    1070 \begin{figure}[hbt]
    1071 
     1040\clearpage
     1041
     1042\begin{figure}[htp]
    10721043  \centerline{\includegraphics[scale=0.5]
    10731044      {graphics/cairnsmodel.jpg}}
     
    10761047\end{figure}
    10771048
    1078 The statement
    1079 
    1080 
    1081 {\small \begin{verbatim}
     1049The statement:
     1050
     1051\begin{verbatim}
    10821052remainder_res = 10000000
    10831053create_mesh_from_regions(project.bounding_polygon,
     
    10911061                         use_cache=True,
    10921062                         verbose=True)
    1093 \end{verbatim}}
     1063\end{verbatim}
     1064
    10941065is then used to create the mesh, taking the bounding polygon to be
    10951066the polygon \code{bounding\_polygon} specified in \file{project.py}.
    10961067The argument \code{boundary\_tags} assigns a dictionary, whose keys
    10971068are the names of the boundary tags used for the bounding
    1098 polygon---\code{`top'}, \code{`ocean\_east'}, \code{`bottom'}, and
    1099 \code{`onshore'}--- and whose values identify the indices of the
     1069polygon -- \code{'top'}, \code{'ocean\_east'}, \code{'bottom'}, and
     1070\code{'onshore'} -- and whose values identify the indices of the
    11001071segments associated with each of these tags.
    11011072The polygon may be arranged either clock-wise or counter clock-wise and the
     
    11031074(Here, the values associated with each boundary tag are one-element lists, but they can have as many indices as there are edges)
    11041075If polygons intersect, or edges coincide (or are even very close) the resolution may be undefined in some regions.
    1105 Use the underlying mesh interface for such cases. See Section
    1106 \ref{sec:mesh interface}.
     1076Use the underlying mesh interface for such cases.
     1077See Section \ref{sec:mesh interface}.
    11071078If a segment is omitted in the tags definition an Exception is raised.
    11081079
     
    11111082areas to be generated irrespective of the requested resolution.
    11121083Make sure points on polygons are spaced to be no closer than the smallest resolution requested.
    1113 
    11141084
    11151085\subsection{Initialising the Domain}
     
    11221092\code{meshname}, as follows:
    11231093
    1124 
    1125 {\small \begin{verbatim}
    1126     domain = Domain(meshname, use_cache=True, verbose=True)
    1127 \end{verbatim}}
     1094\begin{verbatim}
     1095domain = Domain(meshname, use_cache=True, verbose=True)
     1096\end{verbatim}
    11281097
    11291098Providing a filename instead of the lists used in \file{runup.py}
     
    11441113taken from \file{project.py}.
    11451114
    1146 {\small \begin{verbatim}
    1147     domain.set_name(project.basename)
    1148     domain.set_datadir(project.outputdir)
    1149     domain.set_quantities_to_be_stored(['stage', 'xmomentum',
    1150         'ymomentum'])
    1151 \end{verbatim}}
    1152 
     1115\begin{verbatim}
     1116domain.set_name(project.basename)
     1117domain.set_datadir(project.outputdir)
     1118domain.set_quantities_to_be_stored(['stage', 'xmomentum', 'ymomentum'])
     1119\end{verbatim}
    11531120
    11541121\subsection{Initial Conditions}
     1122
    11551123Quantities for \file{runcairns.py} are set
    11561124using similar methods to those in \file{runup.py}. However,
     
    11591127ancillary points file.
    11601128
    1161 
    1162 
    11631129\subsubsection{Stage}
    11641130
     
    11661132object \code{tsunami\_source}, assigned by means of a function
    11671133\function{slide\_tsunami}. This is similar to how we set elevation in
    1168 \file{runup.py} using a function---however, in this case the
     1134\file{runup.py} using a function -- however, in this case the
    11691135function is both more complex and more interesting.
    11701136
     
    11821148We assign the friction exactly as we did for \file{runup.py}:
    11831149
    1184 {\small \begin{verbatim}
    1185     domain.set_quantity('friction', 0.0)
    1186 \end{verbatim}}
    1187 
     1150\begin{verbatim}
     1151domain.set_quantity('friction', 0.0)
     1152\end{verbatim}
    11881153
    11891154\subsubsection{Elevation}
     
    11911156The elevation is specified by reading data from a file:
    11921157
    1193 {\small \begin{verbatim}
    1194     domain.set_quantity('elevation',
    1195                         filename = project.dem_name + '.pts',
    1196                         use_cache = True,
    1197                         verbose = True)
    1198 \end{verbatim}}
     1158\begin{verbatim}
     1159domain.set_quantity('elevation',
     1160                    filename=project.dem_name+'.pts',
     1161                    use_cache=True,
     1162                    verbose=True)
     1163\end{verbatim}
    11991164
    12001165%However, before this step can be executed, some preliminary steps
    12011166%are needed to prepare the file from which the data is taken. Two
    1202 %source files are used for this data---their names are specified in
     1167%source files are used for this data -- their names are specified in
    12031168%the file \file{project.py}, in the variables \code{coarsedemname}
    1204 %and \code{finedemname}. They contain `coarse' and `fine' data,
    1205 %respectively---that is, data sampled at widely spaced points over a
     1169%and \code{finedemname}. They contain 'coarse' and 'fine' data,
     1170%respectively -- that is, data sampled at widely spaced points over a
    12061171%large region and data sampled at closely spaced points over a
    12071172%smaller subregion. The data in these files is combined through the
    12081173%statement
    12091174
    1210 %{\small \begin{verbatim}
     1175%\begin{verbatim}
    12111176%combine_rectangular_points_files(project.finedemname + '.pts',
    12121177%                                 project.coarsedemname + '.pts',
    12131178%                                 project.combineddemname + '.pts')
    1214 %\end{verbatim}}
     1179%\end{verbatim}
     1180%
    12151181%The effect of this is simply to combine the datasets by eliminating
    12161182%any coarse data associated with points inside the smaller region
     
    12261192boundary tag names introduced when we established the mesh. In place of the four
    12271193boundary types introduced for \file{runup.py}, we use the reflective
    1228 boundary for each of the
    1229 eight tagged segments defined by \code{create_mesh_from_regions}:
    1230 
    1231 {\small \begin{verbatim}
     1194boundary for each of the eight tagged segments defined by \code{create_mesh_from_regions}:
     1195
     1196\begin{verbatim}
    12321197Bd = Dirichlet_boundary([0.0,0.0,0.0])
    1233 domain.set_boundary( {'ocean_east': Bd, 'bottom': Bd, 'onshore': Bd,
    1234                           'top': Bd} )
    1235 \end{verbatim}}
     1198domain.set_boundary({'ocean_east': Bd, 'bottom': Bd, 'onshore': Bd, 'top': Bd})
     1199\end{verbatim}
    12361200
    12371201\subsection{Evolution}
    12381202
    1239 With the basics established, the running of the `evolve' step is
     1203With the basics established, the running of the 'evolve' step is
    12401204very similar to the corresponding step in \file{runup.py}. For the slide
    1241 scenario,
    1242 the simulation is run for 5000 seconds with the output stored every ten seconds.
    1243 For this example, we choose to apply the slide at 60 seconds into the simulation.
    1244 
    1245 {\small \begin{verbatim}
    1246     import time t0 = time.time()
    1247 
    1248 
    1249     for t in domain.evolve(yieldstep = 10, finaltime = 60):
    1250             domain.write_time()
    1251             domain.write_boundary_statistics(tags = 'ocean_east')
    1252 
    1253         # add slide
    1254         thisstagestep = domain.get_quantity('stage')
    1255         if allclose(t, 60):
    1256             slide = Quantity(domain)
    1257             slide.set_values(tsunami_source)
    1258             domain.set_quantity('stage', slide + thisstagestep)
    1259 
    1260         for t in domain.evolve(yieldstep = 10, finaltime = 5000,
    1261                                skip_initial_step = True):
    1262             domain.write_time()
     1205scenario, the simulation is run for 5000 seconds with the output stored every ten seconds.
     1206For this example, we choose to apply the slide at 60 seconds into the simulation:
     1207
     1208\begin{verbatim}
     1209import time
     1210
     1211t0 = time.time()
     1212
     1213for t in domain.evolve(yieldstep=10, finaltime=60):
     1214        domain.write_time()
    12631215        domain.write_boundary_statistics(tags = 'ocean_east')
    1264 \end{verbatim}}
     1216
     1217    # add slide
     1218    thisstagestep = domain.get_quantity('stage')
     1219    if allclose(t, 60):
     1220        slide = Quantity(domain)
     1221        slide.set_values(tsunami_source)
     1222        domain.set_quantity('stage', slide + thisstagestep)
     1223
     1224    for t in domain.evolve(yieldstep=10, finaltime=5000,
     1225                           skip_initial_ste=True):
     1226        domain.write_time()
     1227
     1228    domain.write_boundary_statistics(tags = 'ocean_east')
     1229\end{verbatim}
    12651230
    12661231For the fixed wave scenario, the simulation is run to 10000 seconds,
     
    12701235parts of the simulation to be viewed at higher time resolution.
    12711236
    1272 
    1273 {\small \begin{verbatim}
    1274 
     1237\begin{verbatim}
    12751238# save every two mins leading up to wave approaching land
    1276     for t in domain.evolve(yieldstep = 120, finaltime = 5000):
    1277         domain.write_time()
    1278         domain.write_boundary_statistics(tags = 'ocean_east')
    1279 
    1280     # save every 30 secs as wave starts inundating ashore
    1281     for t in domain.evolve(yieldstep = 10, finaltime = 10000,
    1282                            skip_initial_step = True):
    1283         domain.write_time()
    1284         domain.write_boundary_statistics(tags = 'ocean_east')
    1285 
    1286 \end{verbatim}}
     1239for t in domain.evolve(yieldstep=120, finaltime=5000):
     1240    domain.write_time()
     1241    domain.write_boundary_statistics(tags='ocean_east')
     1242
     1243# save every 30 secs as wave starts inundating ashore
     1244for t in domain.evolve(yieldstep=10, finaltime=10000, skip_initial_step=True):
     1245    domain.write_time()
     1246    domain.write_boundary_statistics(tags='ocean_east')
     1247\end{verbatim}
     1248
    12871249
    12881250\section{Exploring the Model Output}
    12891251
    12901252Now that the scenario has been run, the user can view the output in a number of ways.
    1291 As described earlier, the user may run animate to view a three-dimensional representation
     1253As described earlier, the user may run \code{animate} to view a three-dimensional representation
    12921254of the simulation.
    12931255
    12941256The user may also be interested in a maximum inundation map. This simply shows the
    1295 maximum water depth over the domain and is achieved with the function sww2dem (described in
    1296 Section \ref{sec:basicfileconversions}).
     1257maximum water depth over the domain and is achieved with the function \code{sww2dem}
     1258described in Section \ref{sec:basicfileconversions}).
    12971259\file{ExportResults.py} demonstrates how this function can be used:
    12981260
    12991261\verbatiminput{demos/cairns/ExportResults.py}
    13001262
    1301 The script generates an maximum water depth ASCII grid at a defined
     1263The script generates a maximum water depth ASCII grid at a defined
    13021264resolution (here 100 m$^2$) which can then be viewed in a GIS environment, for
    13031265example. The parameters used in the function are defined in \file{project.py}.
     
    13151277coastline.
    13161278
    1317 \begin{figure}[hbt]
    1318 \centerline{\includegraphics[scale=0.5]{graphics/slidedepth.jpg}}
    1319 \caption{Maximum inundation map for the Cairns slide scenario. \bf Note, this
    1320 inundation map has been based on a purely hypothetical scenario which was
    1321 designed explictiy for demonstration purposes only.}
    1322 \label{fig:maxdepthcairnsslide}
     1279\clearpage
     1280
     1281\begin{figure}[htp]
     1282  \centerline{\includegraphics[scale=0.5]{graphics/slidedepth.jpg}}
     1283  \caption{Maximum inundation map for the Cairns slide scenario. \bf Note, this
     1284           inundation map has been based on a purely hypothetical scenario which was
     1285           designed explictiy for demonstration purposes only.}
     1286  \label{fig:maxdepthcairnsslide}
    13231287\end{figure}
    13241288
    1325 \begin{figure}[hbt]
    1326 \centerline{\includegraphics[scale=0.5]{graphics/fixedwavedepth.jpg}}
    1327 \caption{Maximum inundation map for the Cairns fixed wave scenario.
    1328 \bf Note, this
    1329 inundaiton map has been based on a purely hypothetical scenario which was
    1330 designed explictiy for demonstration purposes only.}
    1331 \label{fig:maxdepthcairnsfixedwave}
     1289\clearpage
     1290
     1291\begin{figure}[htp]
     1292  \centerline{\includegraphics[scale=0.5]{graphics/fixedwavedepth.jpg}}
     1293  \caption{Maximum inundation map for the Cairns fixed wave scenario.
     1294           \bf Note, this inundation map has been based on a purely hypothetical scenario which was
     1295           designed explictiy for demonstration purposes only.}
     1296  \label{fig:maxdepthcairnsfixedwave}
    13321297\end{figure}
     1298
     1299\clearpage
    13331300
    13341301The user may also be interested in interrogating the solution at a particular spatial
     
    13371304identified for the Cairns scenario, as shown in Figure \ref{fig:cairnsgauges}.
    13381305
    1339 \begin{figure}[hbt]
    1340 \centerline{\includegraphics[scale=0.5]{graphics/cairnsgauges.jpg}}
    1341 \caption{Point locations to show time series information for the Cairns scenario.}
    1342 \label{fig:cairnsgauges}
     1306\begin{figure}[htp]
     1307  \centerline{\includegraphics[scale=0.5]{graphics/cairnsgauges.jpg}}
     1308  \caption{Point locations to show time series information for the Cairns scenario.}
     1309  \label{fig:cairnsgauges}
    13431310\end{figure}
    13441311
    13451312These locations
    13461313must be stored in either a .csv or .txt file. The corresponding .csv file for
    1347 the gauges shown in Figure \ref{fig:cairnsgauges} is \file{gauges.csv}
     1314the gauges shown in Figure \ref{fig:cairnsgauges} is \file{gauges.csv}:
    13481315
    13491316\verbatiminput{demos/cairns/gauges.csv}
     
    13521319northings, and each gauge is given a name. The elevation column can be zero here.
    13531320This information is then passed to the function \code{sww2csv_gauges} (shown in
    1354 \file{GetTimeseries.py} which generates the csv files for each point location. The csv files
     1321\file{GetTimeseries.py} which generates the csv files for each point location. The CSV files
    13551322can then be used in \code{csv2timeseries_graphs} to create the timeseries plot for each desired
    13561323quantity. \code{csv2timeseries_graphs} relies on \code{pylab} to be installed which is not part
     
    13711338Airport in Figure \ref{fig:airportboth}.
    13721339
    1373 \begin{figure}[hbt]
    1374 \centerline{\includegraphics[scale=0.5]{graphics/gaugeElfordReefstage.png}}
    1375 \caption{Time series information of the quantity stage for the Elford Reef location for the
    1376 fixed wave and slide scenario.}
    1377 \label{fig:reef}
     1340\begin{figure}[htp]
     1341  \centerline{\includegraphics[scale=0.5]{graphics/gaugeElfordReefstage.png}}
     1342  \caption{Time series information of the quantity stage for the Elford Reef location for the
     1343           fixed wave and slide scenario.}
     1344  \label{fig:reef}
    13781345\end{figure}
    13791346
    1380 \begin{figure}[hbt]
    1381 \centerline{\includegraphics[scale=0.5]{graphics/gaugeCairnsAirportdepth.png}}
    1382 \caption{Time series information of the quantity depth for the Cairns Airport
    1383 location for the slide and fixed wave scenario.}
    1384 \label{fig:airportboth}
     1347\begin{figure}[htp]
     1348  \centerline{\includegraphics[scale=0.5]{graphics/gaugeCairnsAirportdepth.png}}
     1349  \caption{Time series information of the quantity depth for the Cairns Airport
     1350           location for the slide and fixed wave scenario.}
     1351  \label{fig:airportboth}
    13851352\end{figure}
    13861353
    1387 
    1388 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    13891354%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    13901355
     
    13961361following headings, which correspond to the outline of the examples
    13971362described in Chapter \ref{ch:getstarted}:
    1398 
    13991363\begin{itemize}
    14001364    \item Establishing the Mesh: Section \ref{sec:establishing the mesh}
    14011365    \item Initialising the Domain: Section \ref{sec:initialising the domain}
    1402     \item Specifying the Quantities: Section \ref{sec:quantitis}
     1366%    \item Specifying the Quantities: Section \ref{sec:quantities}
    14031367    \item Initial Conditions: Section \ref{sec:initial conditions}
    14041368    \item Boundary Conditions: Section \ref{sec:boundary conditions}
     
    14081372
    14091373The listings are intended merely to give the reader an idea of what
    1410 each feature is, where to find it and how it can be used---they do
     1374each feature is, where to find it and how it can be used -- they do
    14111375not give full specifications; for these the reader
    14121376may consult the code. The code for every function or class contains
    1413 a documentation string, or `docstring', that specifies the precise
     1377a documentation string, or 'docstring', that specifies the precise
    14141378syntax for its use. This appears immediately after the line
    14151379introducing the code, between two sets of triple quotes.
     
    14251389\module{mesh\_interface} in a subfolder of \module{inundation} called
    14261390\code{pmesh}. In Linux or Unix syntax, the pathname of the file
    1427 containing the function, relative to \file{inundation}, would be
    1428 
    1429 \begin{center}
    1430 %    \code{pmesh/mesh\_interface.py}
    1431     \code{pmesh}$\slash$\code{mesh\_interface.py}
    1432 \end{center}
     1391containing the function, relative to \file{inundation}, would be:
     1392
     1393\begin{verbatim}
     1394pmesh/mesh_interface.py
     1395\end{verbatim}
     1396
    14331397\label{sec:mesh interface}
    1434 
    1435 while in Windows syntax it would be
    1436 
    1437 \begin{center}
    1438     \code{pmesh}$\backslash$\code{mesh\_interface.py}
    1439 \end{center}
     1398while in Windows syntax it would be:
     1399
     1400\begin{verbatim}
     1401pmesh\mesh_interface.py
     1402\end{verbatim}
    14401403
    14411404Rather than using either of these forms, in this chapter we specify
    1442 the location simply as \code{pmesh.mesh\_interface}, in keeping with
     1405the location simply as \code{pmesh.mesh_interface}, in keeping with
    14431406the usage in the Python statement for importing the function,
    14441407namely:
    1445 \begin{center}
    1446     \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
    1447 \end{center}
     1408
     1409\begin{verbatim}
     1410from pmesh.mesh_interface import create_mesh_from_regions
     1411\end{verbatim}
    14481412
    14491413Each listing details the full set of parameters for the class or
     
    14551419and are omitted from the descriptions given below:
    14561420
    1457 %\begin{center}
    1458 \begin{tabular}{ll}  %\hline
    1459 %\textbf{Name } & \textbf{Description}\\
    1460 %\hline
    1461 \emph{use\_cache} & Specifies whether caching is to be used for improved performance. See Section \ref{sec:caching} for details on the underlying caching functionality\\
    1462 \emph{verbose} & If \code{True}, provides detailed terminal output
    1463 to the user\\  % \hline
     1421%\begin{tabular}{ll}
     1422\begin{tabular}{p{2.0cm} p{14.0cm}}
     1423  \emph{use\_cache} & Specifies whether caching is to be used for improved performance.
     1424                      See Section \ref{sec:caching} for details on the underlying caching functionality\\
     1425  \emph{verbose} & If \code{True}, provides detailed terminal output to the user\\
    14641426\end{tabular}
    1465 %\end{center}
     1427
    14661428
    14671429\section{Mesh Generation}\index{Mesh!generation}
     
    14741436very simple mesh comprising just 11 points and 10 triangles.
    14751437
    1476 
    1477 \begin{figure}[h]
     1438\begin{figure}[htp]
    14781439  \begin{center}
    14791440    \includegraphics[width=90mm, height=90mm]{triangularmesh.jpg}
    14801441  \end{center}
    1481 
    14821442  \caption{A simple mesh}
    14831443  \label{fig:simplemesh}
    14841444\end{figure}
    14851445
     1446\clearpage
    14861447
    14871448The variables \code{points}, \code{triangles} and \code{boundary}
    14881449represent the data displayed in Figure \ref{fig:simplemesh} as
    14891450follows. The list \code{points} stores the coordinates of the
    1490 points, and may be displayed schematically as in Table
    1491 \ref{tab:points}.
    1492 
    1493 
    1494 \begin{table}
     1451points, and may be displayed schematically as in Table \ref{tab:points}.
     1452
     1453\begin{table}[htp]
    14951454  \begin{center}
    14961455    \begin{tabular}[t]{|c|cc|} \hline
     
    15091468    \end{tabular}
    15101469  \end{center}
    1511 
    1512   \caption{Point coordinates for mesh in
    1513     Figure \protect \ref{fig:simplemesh}}
     1470  \caption{Point coordinates for mesh in Figure \protect \ref{fig:simplemesh}}
    15141471  \label{tab:points}
    15151472\end{table}
     
    15251482and $(3,0,1)$.
    15261483
    1527 
    1528 \begin{table}
     1484\begin{table}[htp]
    15291485  \begin{center}
    1530     \begin{tabular}{|c|ccc|} \hline
    1531       index & \multicolumn{3}{c|}{\code{points}}\\ \hline
     1486    \begin{tabular}{|c|ccc|}
     1487      \hline
     1488      index & \multicolumn{3}{c|}{\code{points}}\\
     1489      \hline
    15321490      0 & 0 & 1 & 3\\
    15331491      1 & 1 & 2 & 4\\
     
    15391497      7 & 7 & 9 & 8\\
    15401498      8 & 1 & 4 & 3\\
    1541       9 & 5 & 10 & 9\\  \hline
     1499      9 & 5 & 10 & 9\\
     1500      \hline
    15421501    \end{tabular}
    15431502  \end{center}
     
    15501509triangles and associates a tag with each.
    15511510
    1552 \refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
    1553 
    1554 \begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
     1511% \refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}
     1512\label{sec:meshgeneration}
     1513
     1514\begin{funcdesc} {create\_mesh\_from\_regions}{bounding_polygon,
    15551515                             boundary_tags,
    15561516                             maximum_triangle_area,
     
    15911551\end{funcdesc}
    15921552
    1593 
    1594 
    15951553\subsection{Advanced mesh generation}
    15961554
     
    16101568to build a mesh outline, such as \code{add\_vertices} and
    16111569\code{add\_region\_from\_polygon}.
    1612 
    16131570\end{classdesc}
    16141571
    1615 
    16161572\subsubsection{Key Methods of Class Mesh}
    16171573
    1618 
    1619 \begin{methoddesc} {add\_hole}{x,y}
     1574\begin{methoddesc} {add\_hole}{self, x, y}
    16201575Module: \module{pmesh.mesh},  Class: \class{Mesh}
    16211576
     
    16231578when the boundary of the hole has already been defined, by selecting a
    16241579point within the boundary.
    1625 
    1626 \end{methoddesc}
    1627 
     1580\end{methoddesc}
    16281581
    16291582\begin{methoddesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None}
    16301583Module: \module{pmesh.mesh},  Class: \class{Mesh}
    16311584
    1632 This method is used to add a `hole' within a region ---that is, to
     1585This method is used to add a 'hole' within a region -- that is, to
    16331586define a interior region where the triangular mesh will not be
    1634 generated---to a \class{Mesh} instance. The region boundary is described by
     1587generated -- to a \class{Mesh} instance. The region boundary is described by
    16351588the polygon passed in.  Additionally, the user specifies a list of
    16361589boundary tags, one for each edge of the bounding polygon.
    16371590\end{methoddesc}
    1638 
    16391591
    16401592\begin{methoddesc}  {add\_points_and_segments}{self, points, segments,
     
    16481600[[0,1],[1,2]]} to make a polyline between points 0, 1 and 2. A tag for
    16491601each segment can optionally be added.
    1650 
    1651 \end{methoddesc}
    1652 
    1653 \begin{methoddesc} {add\_region}{x,y}
     1602\end{methoddesc}
     1603
     1604\begin{methoddesc} {add\_region}{self, x, y}
    16541605Module: \module{pmesh.mesh},  Class: \class{Mesh}
    16551606
     
    16581609a point within the boundary.  A region instance is returned.  This can
    16591610be used to set the resolution.
    1660 
    16611611\end{methoddesc}
    16621612
    16631613\begin{methoddesc}  {add\_region\_from\_polygon}{self, polygon,
    1664 segment_tags=None, region_tag=None
    1665                                 max_triangle_area=None}
     1614                     segment_tags=None, region_tag=None, max_triangle_area=None}
    16661615Module: \module{pmesh.mesh},  Class: \class{Mesh}
    16671616
     
    16731622user specifies a list of segment tags, one for each edge of the
    16741623bounding polygon.  The regional tag is set using  \code{region}.
    1675 
    1676 \end{methoddesc}
    1677 
    1678 
    1679 
    1680 
    1681 
    1682 \begin{methoddesc} {add\_vertices}{point_data}
     1624\end{methoddesc}
     1625
     1626\begin{methoddesc} {add\_vertices}{self, point_data}
    16831627Module: \module{pmesh.mesh},  Class: \class{Mesh}
    16841628
     
    16871631\end{methoddesc}
    16881632
    1689 \begin{methoddesc} {auto\_segment}{raw_boundary=raw_boundary,
     1633\begin{methoddesc} {auto\_segment}{self, raw_boundary=raw_boundary,
    16901634                    remove_holes=remove_holes,
    16911635                    smooth_indents=smooth_indents,
     
    16971641useful since a set of user vertices need to be outlined by segments
    16981642before generate_mesh is called.
    1699 
    1700 \end{methoddesc}
    1701 
    1702 \begin{methoddesc}  {export\_mesh_file}{self,ofile}
     1643\end{methoddesc}
     1644
     1645\begin{methoddesc}  {export\_mesh_file}{self, ofile}
    17031646Module: \module{pmesh.mesh},  Class: \class{Mesh}
    17041647
     
    17211664\end{methoddesc}
    17221665
    1723 
    1724 
    1725 \begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None,
     1666\begin{methoddesc}  {import_ungenerate_file}{self, ofile, tag=None,
    17261667region_tag=None}
    17271668Module: \module{pmesh.mesh},  Class: \class{Mesh}
     
    17411682\end{methoddesc}
    17421683
    1743 %%%%%%
     1684
    17441685\section{Initialising the Domain}\index{Initialising the Domain}
    17451686\label{sec:initialising the domain}
     
    17861727
    17871728    Returns the name assigned to the domain by \code{set\_name}. If no name has been
    1788     assigned, returns \code{`domain'}.
     1729    assigned, returns \code{'domain'}.
    17891730\end{methoddesc}
    17901731
     
    17991740    Since different operating systems use different formats for specifying pathnames,
    18001741    it is necessary to specify path separators using the Python code \code{os.sep}, rather than
    1801     the operating-specific ones such as `$\slash$' or `$\backslash$'.
     1742    the operating-specific ones such as '$\slash$' or '$\backslash$'.
    18021743    For this to work you will need to include the statement \code{import os}
    18031744    in your code, before the first appearance of \code{set\_datadir}.
     
    18071748    the statements:
    18081749
    1809     {\small \begin{verbatim}
    1810         import os
    1811         domain.set_datadir{'project' + os.sep + 'data'}
    1812     \end{verbatim}}
     1750    \begin{verbatim}
     1751import os
     1752domain.set_datadir{'project' + os.sep + 'data'}
     1753    \end{verbatim}
    18131754\end{methoddesc}
    18141755
     
    18221763\end{methoddesc}
    18231764
    1824 
    18251765\begin{methoddesc} {set\_minimum_allowed_height}{}
    18261766    Module: \module{shallow\_water.shallow\_water\_domain}
     
    18341774\end{methoddesc}
    18351775
    1836 
    18371776\begin{methoddesc} {set\_minimum_storable_height}{}
    18381777    Module: \module{shallow\_water.shallow\_water\_domain}
     
    18421781    that seems to be caused by friction creep.
    18431782\end{methoddesc}
    1844 
    18451783
    18461784\begin{methoddesc} {set\_maximum_allowed_speed}{}
     
    18531791\end{methoddesc}
    18541792
    1855 
    18561793\begin{methoddesc} {set\_time}{time=0.0}
    18571794    Module: \module{abstract\_2d\_finite\_volumes.domain}
     
    18661803    to \code{n} will cause an error.)
    18671804\end{methoddesc}
    1868 
    18691805
    18701806\begin{methoddesc} {set\_store\_vertices\_uniquely}{flag}
     
    18961832file and the same data stored in the model domain. This must be borne in mind when comparing
    18971833data from the sww files with that of the model internally.
    1898 
    1899 \end{methoddesc}
    1900 
     1834\end{methoddesc}
    19011835
    19021836% Structural methods
     
    19131847\end{methoddesc}
    19141848
    1915 
    19161849\begin{methoddesc}{get\_vertex\_coordinates}{absolute=False}
    19171850    \label{pg:get vertex coordinates}
     
    19261859    Default is False as many parts of ANUGA expects relative coordinates.
    19271860\end{methoddesc}
    1928 
    19291861
    19301862\begin{methoddesc}{get\_centroid\_coordinates}{absolute=False}
     
    19391871\end{methoddesc}
    19401872
    1941 
    19421873\begin{methoddesc}{get\_triangles}{indices=None}
    19431874
    1944         Return Mx3 integer array where M is the number of triangles.
    1945         Each row corresponds to one triangle and the three entries are
    1946         indices into the mesh nodes which can be obtained using the method
    1947         get\_nodes()
    1948 
    1949         Optional argument, indices is the set of triangle ids of interest.
     1875    Return Mx3 integer array where M is the number of triangles.
     1876    Each row corresponds to one triangle and the three entries are
     1877    indices into the mesh nodes which can be obtained using the method
     1878    get\_nodes()
     1879
     1880    Optional argument, indices is the set of triangle ids of interest.
    19501881\end{methoddesc}
    19511882
    19521883\begin{methoddesc}{get\_disconnected\_triangles}{}
    1953 
    1954 Get mesh based on nodes obtained from get_vertex_coordinates.
    1955 
    1956         Return array Mx3 array of integers where each row corresponds to
    1957         a triangle. A triangle is a triplet of indices into
    1958         point coordinates obtained from get_vertex_coordinates and each
    1959         index appears only once.\\
    1960 
    1961         This provides a mesh where no triangles share nodes
    1962         (hence the name disconnected triangles) and different
    1963         nodes may have the same coordinates.\\
    1964 
    1965         This version of the mesh is useful for storing meshes with
    1966         discontinuities at each node and is e.g. used for storing
    1967         data in sww files.\\
    1968 
    1969         The triangles created will have the format
    1970 
    1971     {\small \begin{verbatim}
    1972         [[0,1,2],
    1973          [3,4,5],
    1974          [6,7,8],
    1975          ...
    1976          [3*M-3 3*M-2 3*M-1]]
    1977      \end{verbatim}}
    1978 \end{methoddesc}
    1979 
    1980 
    1981 
    1982 %%%%%%
     1884    Get mesh based on nodes obtained from get_vertex_coordinates.
     1885
     1886    Return array Mx3 array of integers where each row corresponds to
     1887    a triangle. A triangle is a triplet of indices into
     1888    point coordinates obtained from get_vertex_coordinates and each
     1889    index appears only once.\\
     1890
     1891    This provides a mesh where no triangles share nodes
     1892    (hence the name disconnected triangles) and different
     1893    nodes may have the same coordinates.\\
     1894
     1895    This version of the mesh is useful for storing meshes with
     1896    discontinuities at each node and is e.g. used for storing
     1897    data in sww files.\\
     1898
     1899    The triangles created will have the format:
     1900
     1901    \begin{verbatim}
     1902[[0,1,2],
     1903 [3,4,5],
     1904 [6,7,8],
     1905 ...
     1906 [3*M-3 3*M-2 3*M-1]]
     1907    \end{verbatim}
     1908\end{methoddesc}
     1909
     1910
    19831911\section{Initial Conditions}\index{Initial Conditions}
    19841912\label{sec:initial conditions}
     
    19951923
    19961924\begin{methoddesc}{set\_quantity}{name,
    1997     numeric = None,
    1998     quantity = None,
    1999     function = None,
    2000     geospatial_data = None,
    2001     expression = None,   
    2002     filename = None,
    2003     attribute_name = None,
    2004     alpha = None,
    2005     location = 'vertices',
    2006     indices = None,
    2007     verbose = False,
    2008     use_cache = False}
     1925    numeric=None,
     1926    quantity=None,
     1927    function=None,
     1928    geospatial_data=None,
     1929    expression=None,   
     1930    filename=None,
     1931    attribute_name=None,
     1932    alpha=None,
     1933    location='vertices',
     1934    indices=None,
     1935    verbose=False,
     1936    use_cache=False}
    20091937  Module: \module{abstract\_2d\_finite\_volumes.domain}
    20101938  (see also \module{abstract\_2d\_finite\_volumes.quantity.set\_values})
    20111939
    2012 This function is used to assign values to individual quantities for a
    2013 domain. It is very flexible and can be used with many data types: a
    2014 statement of the form \code{domain.set\_quantity(name, x)} can be used
    2015 to define a quantity having the name \code{name}, where the other
    2016 argument \code{x} can be any of the following:
    2017 
    2018 \begin{itemize}
    2019 \item a number, in which case all vertices in the mesh gets that for
    2020 the quantity in question.
    2021 \item a list of numbers or a Numeric array ordered the same way as the mesh vertices.
    2022 \item a function (e.g.\ see the samples introduced in Chapter 2)
    2023 \item an expression composed of other quantities and numbers, arrays, lists (for
    2024 example, a linear combination of quantities, such as
    2025 \code{domain.set\_quantity('stage','elevation'+x))}
    2026 \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.
    2027 \item a geospatial dataset (See Section \ref{sec:geospatial}).
    2028 Optional argument attribute\_name applies here as with files.
    2029 \end{itemize}
    2030 
    2031 
    2032 Exactly one of the arguments
    2033   numeric, quantity, function, points, filename
    2034 must be present.
    2035 
    2036 
    2037 Set quantity will look at the type of the second argument (\code{numeric}) and
    2038 determine what action to take.
    2039 
    2040 Values can also be set using the appropriate keyword arguments.
    2041 If 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)}
    2042 are all equivalent.
    2043 
    2044 
    2045 Other optional arguments are
    2046 \begin{itemize}
    2047 \item \code{indices} which is a list of ids of triangles to which set\_quantity should apply its assignment of values.
    2048 \item \code{location} determines which part of the triangles to assign
    2049   to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'.
    2050   If 'vertices' are use, edge and centroid values are automatically computed as the appropriate averages. This option ensures continuity of the surface.
    2051   If, on the other hand, 'centroids' is used vertex and edge values will be set to the same value effectively creating a piecewise constant surface with possible discontinuities at the edges.
    2052 \end{itemize}
    2053 
    2054 %%%
    2055 \anuga provides a number of predefined initial conditions to be used
    2056 with \code{set\_quantity}. See for example callable object
    2057 \code{slump\_tsunami} below.
    2058 
    2059 \end{methoddesc}
    2060 
    2061 
    2062 
     1940  This function is used to assign values to individual quantities for a
     1941  domain. It is very flexible and can be used with many data types: a
     1942  statement of the form \code{domain.set\_quantity(name, x)} can be used
     1943  to define a quantity having the name \code{name}, where the other
     1944  argument \code{x} can be any of the following:
     1945
     1946  \begin{itemize}
     1947    \item a number, in which case all vertices in the mesh gets that for
     1948          the quantity in question.
     1949    \item a list of numbers or a numeric array ordered the same way as the mesh vertices.
     1950    \item a function (e.g.\ see the samples introduced in Chapter 2)
     1951    \item an expression composed of other quantities and numbers, arrays, lists (for
     1952          example, a linear combination of quantities, such as
     1953    \code{domain.set\_quantity('stage','elevation'+x))}
     1954    \item the name of a file from which the data can be read. In this case, the optional
     1955          argument attribute\_name will select which attribute to use from the file. If left out,
     1956          set\_quantity will pick one. This is useful in cases where there is only one attribute.
     1957    \item a geospatial dataset (See Section \ref{sec:geospatial}).
     1958          Optional argument attribute\_name applies here as with files.
     1959  \end{itemize}
     1960
     1961  Exactly one of the arguments
     1962    numeric, quantity, function, points, filename
     1963  must be present.
     1964
     1965  \code{set_quantity} will look at the type of the second argument (\code{numeric}) and
     1966  determine what action to take.
     1967
     1968  Values can also be set using the appropriate keyword arguments.
     1969  If x is a function, for example, \code{domain.set\_quantity(name, x)}, \code{domain.set\_quantity(name, numeric=x)},
     1970  and \code{domain.set\_quantity(name, function=x)} are all equivalent.
     1971
     1972  Other optional arguments are
     1973  \begin{itemize}
     1974    \item \code{indices} which is a list of ids of triangles to which set\_quantity should apply its assignment of values.
     1975    \item \code{location} determines which part of the triangles to assign
     1976                          to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'.
     1977                          If 'vertices' are use, edge and centroid values are automatically computed as the
     1978                          appropriate averages. This option ensures continuity of the surface.
     1979                          If, on the other hand, 'centroids' is used vertex and edge values will be set to the
     1980                          same value effectively creating a piecewise constant surface with possible discontinuities at the edges.
     1981  \end{itemize}
     1982
     1983  \anuga provides a number of predefined initial conditions to be used
     1984  with \code{set\_quantity}. See for example callable object \code{slump\_tsunami} below.
     1985\end{methoddesc}
    20631986
    20641987\begin{methoddesc}{add\_quantity}{name,
    2065     numeric = None,
    2066     quantity = None,
    2067     function = None,
    2068     geospatial_data = None,
    2069     expression = None,
    2070     filename = None,
    2071     attribute_name = None,
    2072     alpha = None,
    2073     location = 'vertices',
    2074     indices = None,
    2075     verbose = False,
    2076     use_cache = False}
     1988    numeric=None,
     1989    quantity=None,
     1990    function=None,
     1991    geospatial_data=None,
     1992    expression=None,
     1993    filename=None,
     1994    attribute_name=None,
     1995    alpha=None,
     1996    location='vertices',
     1997    indices=None,
     1998    verbose=False,
     1999    use_cache=False}
    20772000  Module: \module{abstract\_2d\_finite\_volumes.domain}
    20782001  (see also \module{abstract\_2d\_finite\_volumes.domain.set\_quantity})
    20792002
    2080 \label{add quantity}
    2081 This function is used to \emph{add} values to individual quantities for a
    2082 domain. It has the same syntax as \code{domain.set\_quantity(name, x)}.
    2083 
    2084 A typical use of this function is to add structures to an existing elevation model:
    2085 
    2086 {\small
    2087 \begin{verbatim}
    2088     # Create digital elevation model from points file
    2089     domain.set_quantity('elevation',
    2090                         filename = 'elevation_file.pts,
    2091                         verbose = True)
    2092 
    2093     # Add buildings from file
    2094     building_polygons, building_heights = csv2building_polygons(building_file)
    2095 
    2096     B = []
    2097     for key in building_polygons:
    2098         poly = building_polygons[key]
    2099         elev = building_heights[key]
    2100         B.append((poly, elev))
    2101 
    2102     domain.add_quantity('elevation', Polygon_function(B, default=0.0))
    2103 
    2104 \end{verbatim}}
    2105 
    2106 \end{methoddesc}
    2107 
    2108 
    2109 
    2110 
    2111 
     2003  \label{add quantity}
     2004  This function is used to \emph{add} values to individual quantities for a
     2005  domain. It has the same syntax as \code{domain.set\_quantity(name, x)}.
     2006
     2007  A typical use of this function is to add structures to an existing elevation model:
     2008
     2009  \begin{verbatim}
     2010# Create digital elevation model from points file
     2011domain.set_quantity('elevation', filename='elevation_file.pts, verbose=True)
     2012
     2013# Add buildings from file
     2014building_polygons, building_heights = csv2building_polygons(building_file)
     2015
     2016B = []
     2017for key in building_polygons:
     2018    poly = building_polygons[key]
     2019    elev = building_heights[key]
     2020    B.append((poly, elev))
     2021
     2022domain.add_quantity('elevation', Polygon_function(B, default=0.0))
     2023  \end{verbatim}
     2024\end{methoddesc}
    21122025
    21132026\begin{funcdesc}{set_region}{tag, quantity, X, location='vertices'}
     
    21162029  (see also \module{abstract\_2d\_finite\_volumes.quantity.set\_values})
    21172030
    2118 This function is used to assign values to individual quantities given
    2119 a regional tag.   It is similar to \code{set\_quantity}.
    2120 For example, if in the mesh-generator a regional tag of 'ditch' was
    2121 used, set\_region can be used to set elevation of this region to
    2122 -10m. X is the constant or function to be applied to the quantity,
    2123 over the tagged region.  Location describes how the values will be
    2124 applied.  Options are 'vertices' (default), 'edges', 'unique
    2125 vertices', and 'centroids'.
    2126 
    2127 This method can also be called with a list of region objects.  This is
    2128 useful for adding quantities in regions, and having one quantity
    2129 value based on another quantity. See  \module{abstract\_2d\_finite\_volumes.region} for
    2130 more details.
     2031  This function is used to assign values to individual quantities given
     2032  a regional tag.   It is similar to \code{set\_quantity}.
     2033  For example, if in the mesh-generator a regional tag of 'ditch' was
     2034  used, set\_region can be used to set elevation of this region to
     2035  -10m. X is the constant or function to be applied to the quantity,
     2036  over the tagged region.  Location describes how the values will be
     2037  applied.  Options are 'vertices' (default), 'edges', 'unique
     2038  vertices', and 'centroids'.
     2039
     2040  This method can also be called with a list of region objects.  This is
     2041  useful for adding quantities in regions, and having one quantity
     2042  value based on another quantity. See  \module{abstract\_2d\_finite\_volumes.region} for
     2043  more details.
    21312044\end{funcdesc}
    2132 
    2133 
    2134 
    21352045
    21362046\begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None,
     
    21412051                domain=None,
    21422052                verbose=False}
    2143 Module: \module{shallow\_water.smf}
    2144 
    2145 This function returns a callable object representing an initial water
    2146 displacement generated by a submarine sediment failure. These failures can take the form of
    2147 a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead.
    2148 
    2149 The arguments include as a minimum, the slump or slide length, the water depth to the centre of sediment
    2150 mass, and the bathymetric slope. Other slump or slide parameters can be included if they are known.
     2053  Module: \module{shallow\_water.smf}
     2054
     2055  This function returns a callable object representing an initial water
     2056  displacement generated by a submarine sediment failure. These failures can take the form of
     2057  a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead.
     2058
     2059  The arguments include as a minimum, the slump or slide length, the water depth to the centre of sediment
     2060  mass, and the bathymetric slope. Other slump or slide parameters can be included if they are known.
    21512061\end{funcdesc}
    21522062
    2153 
    2154 %%%
    21552063\begin{funcdesc}{file\_function}{filename,
    2156     domain = None,
    2157     quantities = None,
    2158     interpolation_points = None,
    2159     verbose = False,
    2160     use_cache = False}
    2161 Module: \module{abstract\_2d\_finite\_volumes.util}
    2162 
    2163 Reads the time history of spatial data for
    2164 specified interpolation points from a NetCDF file (\code{filename})
    2165 and returns
    2166 a callable object. \code{filename} could be a \code{sww} or \code{sts} file.
    2167 Returns interpolated values based on the input
    2168 file using the underlying \code{interpolation\_function}.
    2169 
    2170 \code{quantities} is either the name of a single quantity to be
    2171 interpolated or a list of such quantity names. In the second case, the resulting
    2172 function will return a tuple of values---one for each quantity.
    2173 
    2174 \code{interpolation\_points} is a list of absolute coordinates or a
    2175 geospatial object
    2176 for points at which values are sought.
    2177 
    2178 \code{boundary_polygon} is a list of coordinates specifying the vertices of the boundary. This must be the same polygon as used when calling \code{create_mesh_from_regions}. This argument can only be used when reading boundary data from the STS format.
    2179 
    2180 The model time stored within the file function can be accessed using
    2181 the method \code{f.get\_time()}
    2182 
    2183 
    2184 The underlying algorithm used is as follows:\\
    2185 Given a time series (i.e.\ a series of values associated with
    2186 different times), whose values are either just numbers, a set of
    2187  numbers defined at the vertices of a triangular mesh (such as those
    2188  stored in SWW files) or a set of
    2189  numbers defined at a number of points on the boundary (such as those
    2190  stored in STS files), \code{Interpolation\_function} is used to
    2191  create a callable object that interpolates a value for an arbitrary
    2192  time \code{t} within the model limits and possibly a point \code{(x,
    2193  y)} within a mesh region.
    2194 
    2195  The actual time series at which data is available is specified by
    2196  means of an array \code{time} of monotonically increasing times. The
    2197  quantities containing the values to be interpolated are specified in
    2198  an array---or dictionary of arrays (used in conjunction with the
    2199  optional argument \code{quantity\_names}) --- called
    2200  \code{quantities}. The optional arguments \code{vertex\_coordinates}
    2201  and \code{triangles} represent the spatial mesh associated with the
    2202  quantity arrays. If omitted the function must be created using an STS file
    2203  or a TMS file.
    2204 
    2205  Since, in practice, values need to be computed at specified points,
    2206  the syntax allows the user to specify, once and for all, a list
    2207  \code{interpolation\_points} of points at which values are required.
    2208  In this case, the function may be called using the form \code{f(t,
    2209  id)}, where \code{id} is an index for the list
    2210  \code{interpolation\_points}.
    2211 
    2212 
     2064    domain=None,
     2065    quantities=None,
     2066    interpolation_points=None,
     2067    verbose=False,
     2068    use_cache=False}
     2069  Module: \module{abstract\_2d\_finite\_volumes.util}
     2070
     2071  Reads the time history of spatial data for
     2072  specified interpolation points from a NetCDF file (\code{filename})
     2073  and returns
     2074  a callable object. \code{filename} could be a \code{sww} or \code{sts} file.
     2075  Returns interpolated values based on the input
     2076  file using the underlying \code{interpolation\_function}.
     2077
     2078  \code{quantities} is either the name of a single quantity to be
     2079  interpolated or a list of such quantity names. In the second case, the resulting
     2080  function will return a tuple of values -- one for each quantity.
     2081
     2082  \code{interpolation\_points} is a list of absolute coordinates or a
     2083  geospatial object
     2084  for points at which values are sought.
     2085
     2086  \code{boundary_polygon} is a list of coordinates specifying the vertices of the boundary.
     2087  This must be the same polygon as used when calling \code{create_mesh_from_regions}.
     2088  This argument can only be used when reading boundary data from the STS format.
     2089
     2090  The model time stored within the file function can be accessed using
     2091  the method \code{f.get\_time()}
     2092
     2093  The underlying algorithm used is as follows:\\
     2094  Given a time series (i.e.\ a series of values associated with
     2095  different times), whose values are either just numbers, a set of
     2096  numbers defined at the vertices of a triangular mesh (such as those
     2097  stored in SWW files) or a set of
     2098  numbers defined at a number of points on the boundary (such as those
     2099  stored in STS files), \code{Interpolation\_function} is used to
     2100  create a callable object that interpolates a value for an arbitrary
     2101  time \code{t} within the model limits and possibly a point \code{(x,
     2102  y)} within a mesh region.
     2103
     2104  The actual time series at which data is available is specified by
     2105  means of an array \code{time} of monotonically increasing times. The
     2106  quantities containing the values to be interpolated are specified in
     2107  an array -- or dictionary of arrays (used in conjunction with the
     2108  optional argument \code{quantity\_names}) -- called
     2109  \code{quantities}. The optional arguments \code{vertex\_coordinates}
     2110  and \code{triangles} represent the spatial mesh associated with the
     2111  quantity arrays. If omitted the function must be created using an STS file
     2112  or a TMS file.
     2113
     2114  Since, in practice, values need to be computed at specified points,
     2115  the syntax allows the user to specify, once and for all, a list
     2116  \code{interpolation\_points} of points at which values are required.
     2117  In this case, the function may be called using the form \code{f(t,
     2118  id)}, where \code{id} is an index for the list
     2119  \code{interpolation\_points}.
    22132120\end{funcdesc}
    22142121
     
    22362143%% means of an array \code{time} of monotonically increasing times. The
    22372144%% quantities containing the values to be interpolated are specified in
    2238 %% an array---or dictionary of arrays (used in conjunction with the
    2239 %% optional argument \code{quantity\_names}) --- called
     2145%% an array -- or dictionary of arrays (used in conjunction with the
     2146%% optional argument \code{quantity\_names}) -- called
    22402147%% \code{quantities}. The optional arguments \code{vertex\_coordinates}
    22412148%% and \code{triangles} represent the spatial mesh associated with the
     
    22602167
    22612168
    2262 
    2263 %%%%%%
    22642169\section{Boundary Conditions}\index{boundary conditions}
    22652170\label{sec:boundary conditions}
     
    22682173represented by objects such as \code{Reflective\_boundary(domain)} and
    22692174\code{Dirichlet\_boundary([0.2, 0.0, 0.0])}, described in the examples
    2270 in Chapter 2. Alternatively, you may prefer to ``roll your own'',
     2175in Chapter 2. Alternatively, you may prefer to ''roll your own'',
    22712176following the method explained in Section \ref{sec:roll your own}.
    22722177
     
    22752180
    22762181\begin{methoddesc}{set\_boundary}{boundary_map}
    2277 Module: \module{abstract\_2d\_finite\_volumes.domain}
    2278 
    2279 This function allows you to assign a boundary object (corresponding to a
    2280 pre-defined or user-specified boundary condition) to every boundary segment that
    2281 has been assigned a particular tag.
    2282 
    2283 This is done by specifying a dictionary \code{boundary\_map}, whose values are the boundary objects
    2284 and whose keys are the symbolic tags.
    2285 
     2182  Module: \module{abstract\_2d\_finite\_volumes.domain}
     2183
     2184  This function allows you to assign a boundary object (corresponding to a
     2185  pre-defined or user-specified boundary condition) to every boundary segment that
     2186  has been assigned a particular tag.
     2187
     2188  This is done by specifying a dictionary \code{boundary\_map}, whose values are the boundary objects
     2189  and whose keys are the symbolic tags.
    22862190\end{methoddesc}
    22872191
    22882192\begin{methoddesc} {get\_boundary\_tags}{}
    2289 Module: \module{abstract\_2d\_finite\_volumes.domain}
    2290 
    2291 Returns a list of the available boundary tags.
    2292 \end{methoddesc}
    2293 
    2294 %%%
     2193  Module: \module{abstract\_2d\_finite\_volumes.domain}
     2194
     2195  Returns a list of the available boundary tags.
     2196\end{methoddesc}
     2197
    22952198\subsection{Predefined boundary conditions}
    22962199
    22972200\begin{classdesc}{Reflective\_boundary}{Boundary}
    2298 Module: \module{shallow\_water}
    2299 
    2300 Reflective boundary returns same conserved quantities as those present in
    2301 the neighbouring volume but reflected.
    2302 
    2303 This class is specific to the shallow water equation as it works with the
    2304 momentum quantities assumed to be the second and third conserved quantities.
     2201  Module: \module{shallow\_water}
     2202
     2203  Reflective boundary returns same conserved quantities as those present in
     2204  the neighbouring volume but reflected.
     2205
     2206  This class is specific to the shallow water equation as it works with the
     2207  momentum quantities assumed to be the second and third conserved quantities.
    23052208\end{classdesc}
    23062209
    2307 %%%
    2308 \begin{classdesc}{Transmissive\_boundary}{domain = None}
    2309 \label{pg: transmissive boundary}
    2310 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2311 
    2312 A transmissive boundary returns the same conserved quantities as
    2313 those present in the neighbouring volume.
    2314 
    2315 The underlying domain must be specified when the boundary is instantiated.
     2210\begin{classdesc}{Transmissive\_boundary}{domain=None}
     2211  \label{pg: transmissive boundary}
     2212  Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
     2213
     2214  A transmissive boundary returns the same conserved quantities as
     2215  those present in the neighbouring volume.
     2216
     2217  The underlying domain must be specified when the boundary is instantiated.
    23162218\end{classdesc}
    23172219
    2318 %%%
    23192220\begin{classdesc}{Dirichlet\_boundary}{conserved_quantities=None}
    2320 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2321 
    2322 A Dirichlet boundary returns constant values for each of conserved
    2323 quantities. In the example of \code{Dirichlet\_boundary([0.2, 0.0, 0.0])},
    2324 the \code{stage} value at the boundary is 0.2 and the \code{xmomentum} and
    2325 \code{ymomentum} at the boundary are set to 0.0. The list must contain
    2326 a value for each conserved quantity.
     2221  Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
     2222
     2223  A Dirichlet boundary returns constant values for each of conserved
     2224  quantities. In the example of \code{Dirichlet\_boundary([0.2, 0.0, 0.0])},
     2225  the \code{stage} value at the boundary is 0.2 and the \code{xmomentum} and
     2226  \code{ymomentum} at the boundary are set to 0.0. The list must contain
     2227  a value for each conserved quantity.
    23272228\end{classdesc}
    23282229
    2329 %%%
    23302230\begin{classdesc}{Time\_boundary}{domain = None, f = None}
    2331 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2332 
    2333 A time-dependent boundary returns values for the conserved
    2334 quantities as a function \code{f(t)} of time. The user must specify
    2335 the domain to get access to the model time.
    2336 
    2337 Optional argument \code{default\_boundary} can be used to specify another boundary object to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}.
    2338 The \code{default\_boundary} could be a simple Dirichlet condition or
    2339 even another \code{Time\_boundary}
    2340 typically using data pertaining to another time interval.
     2231  Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
     2232
     2233  A time-dependent boundary returns values for the conserved
     2234  quantities as a function \code{f(t)} of time. The user must specify
     2235  the domain to get access to the model time.
     2236
     2237  Optional argument \code{default\_boundary} can be used to specify another boundary object
     2238  to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}.
     2239  The \code{default\_boundary} could be a simple Dirichlet condition or
     2240  even another \code{Time\_boundary} typically using data pertaining to another time interval.
    23412241\end{classdesc}
    23422242
    2343 %%%
    23442243\begin{classdesc}{File\_boundary}{Boundary}
    2345 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
    2346 
    2347 This method may be used if the user wishes to apply a SWW file, STS file or
    2348 a time series file (TMS) to a boundary segment or segments.
    2349 The boundary values are obtained from a file and interpolated to the
    2350 appropriate segments for each conserved quantity.
    2351 
    2352 Optional argument \code{default\_boundary} can be used to specify another boundary object to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}.
    2353 The \code{default\_boundary} could be a simple Dirichlet condition or
    2354 even another \code{File\_boundary}
    2355 typically using data pertaining to another time interval.
     2244  Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}
     2245
     2246  This method may be used if the user wishes to apply a SWW file, STS file or
     2247  a time series file (TMS) to a boundary segment or segments.
     2248  The boundary values are obtained from a file and interpolated to the
     2249  appropriate segments for each conserved quantity.
     2250
     2251  Optional argument \code{default\_boundary} can be used to specify another boundary object
     2252  to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}.
     2253  The \code{default\_boundary} could be a simple Dirichlet condition or
     2254  even another \code{File\_boundary} typically using data pertaining to another time interval.
    23562255\end{classdesc}
    23572256
    23582257\begin{classdesc}{Field\_boundary}{Boundary}
    2359 Module: \module{shallow\_water.shallow\_water\_domain}
    2360 
    2361 This method works in the same way as \code{File\_boundary} except that it
    2362 allows for the value of stage to be offset by a constant specified in the
    2363 keyword argument \code{mean\_stage}.
    2364 
    2365 This functionality allows for models to be run for a range of tides using
    2366 the same boundary information (from .sts, .sww or .tms files). The tidal value
    2367 for each run would then be specified in the keyword argument
    2368 \code{mean\_stage}.
    2369 If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary}
    2370 behave identically.
    2371 
    2372 
    2373 Note that if the optional argument \code{default\_boundary} is specified
    2374 it's stage value will be adjusted by \code{mean\_stage} just like the values
    2375 obtained from the file.
    2376 
    2377 See \code{File\_boundary} for further details.
     2258  Module: \module{shallow\_water.shallow\_water\_domain}
     2259
     2260  This method works in the same way as \code{File\_boundary} except that it
     2261  allows for the value of stage to be offset by a constant specified in the
     2262  keyword argument \code{mean\_stage}.
     2263
     2264  This functionality allows for models to be run for a range of tides using
     2265  the same boundary information (from .sts, .sww or .tms files). The tidal value
     2266  for each run would then be specified in the keyword argument
     2267  \code{mean\_stage}.
     2268  If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary}
     2269  behave identically.
     2270
     2271  Note that if the optional argument \code{default\_boundary} is specified
     2272  it's stage value will be adjusted by \code{mean\_stage} just like the values
     2273  obtained from the file.
     2274
     2275  See \code{File\_boundary} for further details.
    23782276\end{classdesc}
    23792277
    2380 %%%
    2381 %\begin{classdesc}{Transmissive\_Momentum\_Set\_Stage\_boundary}{Boundary}
    23822278\begin{classdesc}{Transmissive\_momentum\_set\_stage\_boundary}{Boundary}
    2383 Module: \module{shallow\_water}
    2384 \label{pg: transmissive momentum set stage boundary}
    2385 
    2386 This boundary returns same momentum conserved quantities as
    2387 those present in its neighbour volume but sets stage as in a Time\_boundary.
    2388 The underlying domain must be specified when boundary is instantiated
    2389 
    2390 This type of boundary is useful when stage is known at the boundary as a
    2391 function of time, but momenta (or speeds) aren't.
    2392 
    2393 This class is specific to the shallow water equation as it works with the
    2394 momentum quantities assumed to be the second and third conserved quantities.
    2395 
    2396 In some circumstances, this boundary condition may cause numerical instabilities for similar reasons as what has been observed with the simple fully transmissive boundary condition (see Page \pageref{pg: transmissive boundary}).
    2397 This could for example be the case if a planar wave is reflected out through this boundary.
     2279  Module: \module{shallow\_water}
     2280  \label{pg: transmissive momentum set stage boundary}
     2281
     2282  This boundary returns same momentum conserved quantities as
     2283  those present in its neighbour volume but sets stage as in a Time\_boundary.
     2284  The underlying domain must be specified when boundary is instantiated
     2285
     2286  This type of boundary is useful when stage is known at the boundary as a
     2287  function of time, but momenta (or speeds) aren't.
     2288
     2289  This class is specific to the shallow water equation as it works with the
     2290  momentum quantities assumed to be the second and third conserved quantities.
     2291
     2292  In some circumstances, this boundary condition may cause numerical instabilities for similar
     2293  reasons as what has been observed with the simple fully transmissive boundary condition
     2294  (see Page \pageref{pg: transmissive boundary}).
     2295  This could for example be the case if a planar wave is reflected out through this boundary.
    23982296\end{classdesc}
    23992297
    2400 
    24012298\begin{classdesc}{Transmissive\_stage\_zero\_momentum\_boundary}{Boundary}
    2402 Module: \module{shallow\_water}
    2403 \label{pg: transmissive stage zero momentum boundary}
    2404 
    2405 This boundary returns same stage conserved quantities as
    2406 those present in its neighbour volume but sets momentum to zero.
    2407 The underlying domain must be specified when boundary is instantiated
    2408 
    2409 This type of boundary is useful when stage is known at the boundary as a
    2410 function of time, but momentum should be set to zero. This is for example the case where a boundary is needed in the ocean on the two sides perpendicular to the coast to maintain the wave height of the incoming wave.
    2411 
    2412 This class is specific to the shallow water equation as it works with the
    2413 momentum quantities assumed to be the second and third conserved quantities.
    2414 
    2415 This boundary condition should not cause the numerical instabilities seen with the transmissive momentum
    2416 boundary conditions (see Page \pageref{pg: transmissive boundary} and Page \pageref{pg: transmissive momentum set stage boundary}).
    2417 
     2299  Module: \module{shallow\_water}
     2300  \label{pg: transmissive stage zero momentum boundary}
     2301
     2302  This boundary returns same stage conserved quantities as
     2303  those present in its neighbour volume but sets momentum to zero.
     2304  The underlying domain must be specified when boundary is instantiated
     2305
     2306  This type of boundary is useful when stage is known at the boundary as a
     2307  function of time, but momentum should be set to zero. This is for example
     2308  the case where a boundary is needed in the ocean on the two sides perpendicular
     2309  to the coast to maintain the wave height of the incoming wave.
     2310
     2311  This class is specific to the shallow water equation as it works with the
     2312  momentum quantities assumed to be the second and third conserved quantities.
     2313
     2314  This boundary condition should not cause the numerical instabilities seen with the transmissive momentum
     2315  boundary conditions (see Page \pageref{pg: transmissive boundary} and
     2316  Page \pageref{pg: transmissive momentum set stage boundary}).
    24182317\end{classdesc}
    24192318
    2420 
    24212319\begin{classdesc}{Dirichlet\_discharge\_boundary}{Boundary}
    2422 Module: \module{shallow\_water}
    2423 
    2424 Sets stage (stage0)
    2425 Sets momentum (wh0) in the inward normal direction.
     2320  Module: \module{shallow\_water}
     2321
     2322  Sets stage (stage0)
     2323  Sets momentum (wh0) in the inward normal direction.
    24262324\end{classdesc}
    2427 
    2428 
    24292325
    24302326\subsection{User-defined boundary conditions}
     
    24452341
    24462342
    2447 
    24482343\section{Forcing Terms}\index{Forcing terms}
    24492344\label{sec:forcing terms}
    24502345
    24512346\anuga provides a number of predefined forcing functions to be used with simulations.
    2452 Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list
     2347Gravity and friction are always calculated using the elevation and friction quantities,
     2348but the user may additionally add forcing terms to the list
    24532349\code{domain.forcing\_terms} and have them affect the model.
    24542350
    2455 Currently, predefined forcing terms are
    2456 
     2351Currently, predefined forcing terms are:
    24572352\begin{funcdesc}{General\_forcing}{}
    24582353  Module: \module{shallow\_water.shallow\_water\_domain}
     
    24702365                The parametr \code{rate} can be \code{None} at initialisation but must be specified
    24712366                before forcing term is applied (i.e. simulation has started).
    2472                 The default value is 0.0 - i.e.\ no forcing.
     2367                The default value is 0.0 -- i.e.\ no forcing.
    24732368    \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
    2474     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.             
     2369    \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.
    24752370  \end{itemize}
    24762371  Note specifying both center, radius and polygon will cause an exception to be thrown.
     
    24792374  \bigskip
    24802375  Example:
    2481   {\scriptsize \begin{verbatim}
    2482     P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]] # Square polygon
    2483 
    2484     xmom = General_forcing(domain, 'xmomentum', polygon=P)
    2485     ymom = General_forcing(domain, 'ymomentum', polygon=P)
    2486 
    2487     xmom.rate = f
    2488     ymom.rate = g
    2489 
    2490     domain.forcing_terms.append(xmom)
    2491     domain.forcing_terms.append(ymom)   
    2492   \end{verbatim}}
    2493   Here, \code{f}, \code{g} are assumed to be defined as functions of time providing a time dependent rate of change for xmomentum and ymomentum respectively.
     2376
     2377  \begin{verbatim}
     2378P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]]    # Square polygon
     2379
     2380xmom = General_forcing(domain, 'xmomentum', polygon=P)
     2381ymom = General_forcing(domain, 'ymomentum', polygon=P)
     2382
     2383xmom.rate = f
     2384ymom.rate = g
     2385
     2386domain.forcing_terms.append(xmom)
     2387domain.forcing_terms.append(ymom)
     2388  \end{verbatim}
     2389
     2390  Here, \code{f}, \code{g} are assumed to be defined as functions of time providing
     2391  a time dependent rate of change for xmomentum and ymomentum respectively.
    24942392  P is assumed to be polygon, specified as a list of points.
    2495 
    24962393\end{funcdesc}
    2497 
    24982394
    24992395\begin{funcdesc}{Inflow}{}
     
    25112407                function of time. Positive values indicate inflow,
    25122408                negative values indicate outflow.
    2513                
     2409
    25142410                Note: The specified flow will be divided by the area of
    25152411                the inflow region and then applied to update the
    25162412                stage quantity.
    25172413    \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
    2518     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.             
     2414    \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.
    25192415  \end{itemize}
    25202416
    25212417  \bigskip
    25222418  Example:
    2523   {\scriptsize \begin{verbatim}
    2524     hydrograph = Inflow(center=(320, 300), radius=10,
    2525                         rate=file_function('QPMF_Rot_Sub13.tms'))
    2526 
    2527     domain.forcing_terms.append(hydrograph)
    2528   \end{verbatim}}
     2419
     2420  \begin{verbatim}
     2421hydrograph = Inflow(center=(320, 300), radius=10, rate=file_function('QPMF_Rot_Sub13.tms'))
     2422
     2423domain.forcing_terms.append(hydrograph)
     2424  \end{verbatim}
     2425
    25292426  Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for a hydrograph.
    25302427\end{funcdesc}
    2531 
    25322428
    25332429\begin{funcdesc}{Rainfall}{}
     
    25432439    \item \code{domain}: a reference to the domain being evolved
    25442440    \item \code{rate}: Total rain rate over the specified domain.
    2545                   Note: Raingauge Data needs to reflect the time step.
    2546                   For example: if rain gauge is mm read every \code{dt} seconds, then the input
     2441                  Note: Raingauge Data needs to reflect the time step.
     2442                  For example: if rain gauge is mm read every \code{dt} seconds, then the input
    25472443                  here is as \code{mm/dt} so 10 mm in 5 minutes becomes
    25482444                  10/(5x60) = 0.0333mm/s.
    2549        
     2445
    25502446                  This parameter can be either a constant or a
    25512447                  function of time. Positive values indicate rain being added (or be used for general infiltration),
    25522448                  negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction).
    25532449    \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius.
    2554     \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.             
     2450    \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon.
    25552451  \end{itemize}
    25562452
    25572453  \bigskip
    25582454  Example:
    2559   {\scriptsize \begin{verbatim}
    2560 
    2561     catchmentrainfall = Rainfall(rate=file_function('Q100_2hr_Rain.tms'))
    2562     domain.forcing_terms.append(catchmentrainfall)
    2563 
    2564   \end{verbatim}}
     2455
     2456  \begin{verbatim}
     2457catchmentrainfall = Rainfall(rate=file_function('Q100_2hr_Rain.tms'))
     2458domain.forcing_terms.append(catchmentrainfall)
     2459  \end{verbatim}
     2460
    25652461  Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for the rainfall.
    25662462\end{funcdesc}
    25672463
    2568 
    2569 
    25702464\begin{funcdesc}{Culvert\_flow}{}
    25712465  Module: \module{culver\_flows.culvert\_class}
     
    25742468  This class modifies the quantities \code{stage, xmomentum, ymomentum} in areas at both ends of the culvert.
    25752469
    2576   The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities. The flow drection is determined on-the-fly so
    2577   openings are referenced simple as opening0 and opening1 with either being able to take the role as Inflow and Outflow.
     2470  The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities.
     2471  The flow drection is determined on-the-fly so openings are referenced simple as opening0 and opening1
     2472  with either being able to take the role as Inflow and Outflow.
    25782473
    25792474  The Culvert\_flow class takes as input:
     
    25942489  \end{itemize}
    25952490
    2596   The user can specify different culvert routines. Hower ANUGA currently provides only one, namely the \code{boyd\_generalised\_culvert\_model} as used in the example below.
    2597 
    2598   \bigskip
     2491  The user can specify different culvert routines. Hower ANUGA currently provides only one, namely the
     2492  \code{boyd\_generalised\_culvert\_model} as used in the example below.
     2493
    25992494  Example:
    2600   {\scriptsize \begin{verbatim}
    2601     from anuga.culvert_flows.culvert_class import Culvert_flow
    2602     from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model
    2603 
    2604     culvert1 = Culvert_flow(domain,
    2605                            label='Culvert No. 1',
    2606                            description='This culvert is a test unit 1.2m Wide by 0.75m High',
    2607                            end_point0=[9.0, 2.5],
    2608                            end_point1=[13.0, 2.5],
    2609                            width=1.20,height=0.75,
    2610                            culvert_routine=boyd_generalised_culvert_model,
    2611                            number_of_barrels=1,
    2612                            verbose=True)
    2613 
    2614     culvert2 = Culvert_flow(domain,
    2615                            label='Culvert No. 2',
    2616                            description='This culvert is a circular test with d=1.2m',
    2617                            end_point0=[9.0, 1.5],
    2618                            end_point1=[30.0, 3.5],
    2619                            diameter=1.20,
    2620                            invert_level0=7,
    2621                            culvert_routine=boyd_generalised_culvert_model,
    2622                            number_of_barrels=1,                   
    2623                            verbose=True)
    2624 
    2625     domain.forcing_terms.append(culvert1)
    2626     domain.forcing_terms.append(culvert2)
    2627 
    2628 
    2629   \end{verbatim}}
     2495
     2496  \begin{verbatim}
     2497from anuga.culvert_flows.culvert_class import Culvert_flow
     2498from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model
     2499
     2500culvert1 = Culvert_flow(domain,
     2501                        label='Culvert No. 1',
     2502                        description='This culvert is a test unit 1.2m Wide by 0.75m High',
     2503                        end_point0=[9.0, 2.5],
     2504                        end_point1=[13.0, 2.5],
     2505                        width=1.20,height=0.75,
     2506                        culvert_routine=boyd_generalised_culvert_model,
     2507                        number_of_barrels=1,
     2508                        verbose=True)
     2509
     2510culvert2 = Culvert_flow(domain,
     2511                        label='Culvert No. 2',
     2512                        description='This culvert is a circular test with d=1.2m',
     2513                        end_point0=[9.0, 1.5],
     2514                        end_point1=[30.0, 3.5],
     2515                        diameter=1.20,
     2516                        invert_level0=7,
     2517                        culvert_routine=boyd_generalised_culvert_model,
     2518                        number_of_barrels=1,
     2519                        verbose=True)
     2520
     2521domain.forcing_terms.append(culvert1)
     2522domain.forcing_terms.append(culvert2)
     2523  \end{verbatim}
    26302524\end{funcdesc}
    2631 
    2632 
    2633 
    2634 
    26352525
    26362526
     
    26382528\label{sec:evolution}
    26392529
    2640   \begin{methoddesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
    2641 
     2530\begin{methoddesc}{evolve}{yieldstep=None, finaltime=None, duration=None, skip_initial_step=False}
    26422531  Module: \module{abstract\_2d\_finite\_volumes.domain}
    26432532
     
    26622551  You can include \method{evolve} in a statement of the type:
    26632552
    2664   {\small \begin{verbatim}
    2665       for t in domain.evolve(yieldstep, finaltime):
    2666           <Do something with domain and t>
    2667   \end{verbatim}}
    2668 
    2669   \end{methoddesc}
    2670 
    2671 
     2553  \begin{verbatim}
     2554for t in domain.evolve(yieldstep, finaltime):
     2555    <Do something with domain and t>
     2556  \end{verbatim}
     2557\end{methoddesc}
    26722558
    26732559\subsection{Diagnostics}
    26742560\label{sec:diagnostics}
    26752561
    2676 
    2677   \begin{funcdesc}{statistics}{}
     2562\begin{funcdesc}{statistics}{}
    26782563  Module: \module{abstract\_2d\_finite\_volumes.domain}
    26792564
    2680   \end{funcdesc}
    2681 
    2682   \begin{funcdesc}{timestepping\_statistics}{}
     2565\end{funcdesc}
     2566
     2567\begin{funcdesc}{timestepping\_statistics}{}
    26832568  Module: \module{abstract\_2d\_finite\_volumes.domain}
    26842569
    2685   Returns a string of the following type for each
    2686   timestep:
    2687 
     2570  Returns a string of the following type for each timestep:
    26882571  \code{Time = 0.9000, delta t in [0.00598964, 0.01177388], steps=12
    26892572  (12)}
     
    26972580  this diagnostics may help pinpoint problem areas where excessive speeds
    26982581  are generated.
    2699 
    2700   \end{funcdesc}
    2701 
    2702 
    2703   \begin{funcdesc}{boundary\_statistics}{quantities = None, tags = None}
     2582\end{funcdesc}
     2583
     2584\begin{funcdesc}{boundary\_statistics}{quantities=None, tags=None}
    27042585  Module: \module{abstract\_2d\_finite\_volumes.domain}
    27052586
    2706   Returns a string of the following type when \code{quantities = 'stage'} and \code{tags = ['top', 'bottom']}:
    2707 
    2708   {\small \begin{verbatim}
    2709  Boundary values at time 0.5000:
     2587  Returns a string of the following type when \code{quantities = 'stage'}
     2588  and \code{tags = ['top', 'bottom']}:
     2589
     2590  \begin{verbatim}
     2591Boundary values at time 0.5000:
    27102592    top:
    27112593        stage in [ -0.25821218,  -0.02499998]
    27122594    bottom:
    27132595        stage in [ -0.27098821,  -0.02499974]
    2714   \end{verbatim}}
    2715 
    2716   \end{funcdesc}
    2717 
    2718 
    2719   \begin{funcdesc}{get\_quantity}{name, location='vertices', indices = None}
     2596  \end{verbatim}
     2597\end{funcdesc}
     2598
     2599\begin{funcdesc}{get\_quantity}{name, location='vertices', indices=None}
    27202600  Module: \module{abstract\_2d\_finite\_volumes.domain}
    27212601
    27222602  This function returns a Quantity object Q.
    2723   Access to it's values should be done through Q.get\__values documented on Page \pageref{pg:get values}.
    2724  
    2725   \end{funcdesc}
    2726 
    2727 
    2728   \begin{funcdesc}{set\_quantities\_to\_be\_monitored}{}
     2603  Access to its values should be done through Q.get\__values documented on Page \pageref{pg:get values}.
     2604\end{funcdesc}
     2605
     2606\begin{funcdesc}{set\_quantities\_to\_be\_monitored}{}
    27292607  Module: \module{abstract\_2d\_finite\_volumes.domain}
    27302608
     
    27372615  Optional parameters \code{polygon} and \code{time\_interval} may be specified to restrict the
    27382616  extremum computation.
    2739   \end{funcdesc}
    2740 
    2741   \begin{funcdesc}{quantity\_statistics}{}
     2617\end{funcdesc}
     2618
     2619\begin{funcdesc}{quantity\_statistics}{}
    27422620  Module: \module{abstract\_2d\_finite\_volumes.domain}
    27432621
     
    27482626
    27492627  \begin{verbatim}
    2750   Monitored quantities at time 1.0000:
    2751     stage-elevation:
    2752       values since time = 0.00 in [0.00000000, 0.30000000]
    2753       minimum attained at time = 0.00000000, location = (0.16666667, 0.33333333)
    2754       maximum attained at time = 0.00000000, location = (0.83333333, 0.16666667)
    2755     ymomentum:
    2756       values since time = 0.00 in [0.00000000, 0.06241221]
    2757       minimum attained at time = 0.00000000, location = (0.33333333, 0.16666667)
    2758       maximum attained at time = 0.22472667, location = (0.83333333, 0.66666667)
    2759     xmomentum:
    2760       values since time = 0.00 in [-0.06062178, 0.47886313]
    2761       minimum attained at time = 0.00000000, location = (0.16666667, 0.33333333)
    2762       maximum attained at time = 0.35103646, location = (0.83333333, 0.16666667)
     2628Monitored quantities at time 1.0000:
     2629  stage-elevation:
     2630    values since time = 0.00 in [0.00000000, 0.30000000]
     2631    minimum attained at time = 0.00000000, location = (0.16666667, 0.33333333)
     2632    maximum attained at time = 0.00000000, location = (0.83333333, 0.16666667)
     2633  ymomentum:
     2634    values since time = 0.00 in [0.00000000, 0.06241221]
     2635    minimum attained at time = 0.00000000, location = (0.33333333, 0.16666667)
     2636    maximum attained at time = 0.22472667, location = (0.83333333, 0.66666667)
     2637  xmomentum:
     2638    values since time = 0.00 in [-0.06062178, 0.47886313]
     2639    minimum attained at time = 0.00000000, location = (0.16666667, 0.33333333)
     2640    maximum attained at time = 0.35103646, location = (0.83333333, 0.16666667)
    27632641  \end{verbatim}
    27642642
     
    27712649  at every internal timestep.
    27722650
    2773   These values are also stored in the sww file for post processing.
    2774 
    2775   \end{funcdesc}
    2776 
    2777 
    2778 
    2779   \begin{funcdesc}{get\_values}{location='vertices', indices = None}
     2651  These values are also stored in the SWW file for post processing.
     2652\end{funcdesc}
     2653
     2654\begin{funcdesc}{get\_values}{location='vertices', indices=None}
    27802655  \label{pg:get values}
    27812656  Module: \module{abstract\_2d\_finite\_volumes.quantity}
    27822657
    2783   Extract values for quantity as a Numeric array.
    2784 
    2785   {\small \begin{verbatim}
    2786   Inputs:
    2787           interpolation_points: List of x, y coordinates where value is
    2788                                 sought (using interpolation). If points
    2789                                 are given, values of location and indices
    2790                                 are ignored. Assume either absolute UTM
    2791                                 coordinates or geospatial data object.
    2792        
    2793           location: Where values are to be stored.
    2794                     Permissible options are: vertices, edges, centroids
    2795                     and unique vertices. Default is 'vertices'
    2796   \end{verbatim}}
     2658  Extract values for quantity as a numeric array.
     2659
     2660  \begin{verbatim}
     2661Inputs:
     2662  interpolation_points: List of x, y coordinates where value is
     2663                        sought (using interpolation). If points
     2664                        are given, values of location and indices
     2665                        are ignored. Assume either absolute UTM
     2666                        coordinates or geospatial data object.
     2667   
     2668  location: Where values are to be stored.
     2669            Permissible options are: vertices, edges, centroids
     2670            and unique vertices. Default is 'vertices'
     2671  \end{verbatim}
    27972672
    27982673  The returned values will have the leading dimension equal to length of the indices list or
    27992674  N (all values) if indices is None.
    2800        
     2675
    28012676  In case of location == 'centroids' the dimension of returned
    2802   values will be a list or a Numerical array of length N, N being
     2677  values will be a list or a numeric array of length N, N being
    28032678  the number of elements.
    28042679       
     
    28142689  The values will be stored in elements following their
    28152690  internal ordering.
    2816  
    2817   \end{funcdesc}
    2818 
    2819 
    2820 
    2821   \begin{funcdesc}{set\_values}{location='vertices', indices = None}
     2691\end{funcdesc}
     2692
     2693\begin{funcdesc}{set\_values}{location='vertices', indices=None}
    28222694  Module: \module{abstract\_2d\_finite\_volumes.quantity}
    28232695
     
    28302702  The method \code{set\_values} is always called by \code{set\_quantity}
    28312703  behind the scenes.
    2832 
    2833   \end{funcdesc}
    2834 
    2835 
    2836 
    2837   \begin{funcdesc}{get\_integral}{}
     2704\end{funcdesc}
     2705
     2706\begin{funcdesc}{get\_integral}{}
    28382707  Module: \module{abstract\_2d\_finite\_volumes.quantity}
    28392708
    28402709  Return computed integral over entire domain for this quantity
    2841 
    2842   \end{funcdesc}
    2843 
    2844 
    2845 
    2846 
    2847   \begin{funcdesc}{get\_maximum\_value}{indices = None}
     2710\end{funcdesc}
     2711
     2712\begin{funcdesc}{get\_maximum\_value}{indices=None}
    28482713  Module: \module{abstract\_2d\_finite\_volumes.quantity}
    28492714
     
    28542719
    28552720  We do not seek the maximum at vertices as each vertex can
    2856   have multiple values - one for each triangle sharing it.
    2857   \end{funcdesc}
    2858 
    2859 
    2860 
    2861   \begin{funcdesc}{get\_maximum\_location}{indices = None}
     2721  have multiple values -- one for each triangle sharing it.
     2722\end{funcdesc}
     2723
     2724\begin{funcdesc}{get\_maximum\_location}{indices=None}
    28622725  Module: \module{abstract\_2d\_finite\_volumes.quantity}
    28632726
     
    28682731
    28692732  We do not seek the maximum at vertices as each vertex can
    2870   have multiple values - one for each triangle sharing it.
     2733  have multiple values -- one for each triangle sharing it.
    28712734
    28722735  If there are multiple cells with same maximum value, the
    28732736  first cell encountered in the triangle array is returned.
    2874   \end{funcdesc}
    2875 
    2876 
    2877 
    2878   \begin{funcdesc}{get\_wet\_elements}{indices=None}
     2737\end{funcdesc}
     2738
     2739\begin{funcdesc}{get\_wet\_elements}{indices=None}
    28792740  Module: \module{shallow\_water.shallow\_water\_domain}
    28802741
    28812742  Return indices for elements where h $>$ minimum_allowed_height
    28822743  Optional argument indices is the set of element ids that the operation applies to.
    2883   \end{funcdesc}
    2884 
    2885 
    2886   \begin{funcdesc}{get\_maximum\_inundation\_elevation}{indices=None}
     2744\end{funcdesc}
     2745
     2746\begin{funcdesc}{get\_maximum\_inundation\_elevation}{indices=None}
    28872747  Module: \module{shallow\_water.shallow\_water\_domain}
    28882748
     
    28922752  Example to find maximum runup elevation:\\
    28932753     z = domain.get_maximum_inundation_elevation()
    2894   \end{funcdesc}
    2895 
    2896 
    2897   \begin{funcdesc}{get\_maximum\_inundation\_location}{indices=None}
     2754\end{funcdesc}
     2755
     2756\begin{funcdesc}{get\_maximum\_inundation\_location}{indices=None}
    28982757  Module: \module{shallow\_water.shallow\_water\_domain}
    28992758
     
    29032762  Example to find maximum runup location:\\
    29042763     x, y = domain.get_maximum_inundation_location()
    2905   \end{funcdesc}
     2764\end{funcdesc}
    29062765
    29072766
     
    29092768After a model has been run, it is often useful to extract various information from the sww
    29102769output file (see Section \ref{sec:sww format}). This is typically more convenient than using the
    2911 diagnostics described in Section \ref{sec:diagnostics} which rely on the model running - something
     2770diagnostics described in Section \ref{sec:diagnostics} which rely on the model running -- something
    29122771that can be very time consuming. The sww files are easy and quick to read and offer much information
    29132772about the model results such as runup heights, time histories of selected quantities,
     
    29202779  Return highest elevation where depth is positive ($h > 0$)
    29212780
    2922   Example to find maximum runup elevation:\\
    2923   max_runup = get_maximum_inundation_elevation(filename,
    2924   polygon=None,
    2925   time_interval=None,
    2926   verbose=False)
    2927 
     2781  Example to find maximum runup elevation:
     2782
     2783  \begin{verbatim}
     2784max_runup = get_maximum_inundation_elevation(filename,
     2785                                             polygon=None,
     2786                                             time_interval=None,
     2787                                             verbose=False)
     2788  \end{verbatim}
    29282789
    29292790  filename is a NetCDF sww file containing ANUGA model output.
     
    29372798\end{funcdesc}
    29382799
    2939 
    29402800\begin{funcdesc}{get\_maximum\_inundation\_location}{filename, polygon=None,
    29412801    time_interval=None, verbose=False}
     
    29442804  Return location (x,y) of highest elevation where depth is positive ($h > 0$)
    29452805
    2946   Example to find maximum runup location:\\
    2947   max_runup_location = get_maximum_inundation_location(filename,
    2948   polygon=None,
    2949   time_interval=None,
    2950   verbose=False)
    2951 
    2952 
    2953   filename is a NetCDF sww file containing ANUGA model output.
    2954   Optional arguments polygon and time_interval restricts the maximum runup calculation
     2806  Example to find maximum runup location:
     2807
     2808  \begin{verbatim}
     2809max_runup_location = get_maximum_inundation_location(filename,
     2810                                                     polygon=None,
     2811                                                     time_interval=None,
     2812                                                     verbose=False)
     2813  \end{verbatim}
     2814
     2815  \code{filename} is a NetCDF sww file containing ANUGA model output.
     2816  Optional arguments \code{polygon} and \code{time_interval} restricts the maximum runup calculation
    29552817  to a points that lie within the specified polygon and time interval.
    29562818
     
    29582820  is None signifying "No Runup" or "Everything is dry".
    29592821
    2960   See doc string for general function get_maximum_inundation_data for details.
     2822  See the 'doc' string for general function \code{get_maximum_inundation_data} for details.
    29612823\end{funcdesc}
    29622824
    2963 
    2964 \begin{funcdesc}{sww2timeseries}{swwfiles, gauge_filename, production_dirs, report = None, reportname = None,
    2965 plot_quantity = None, generate_fig = False, surface = None, time_min = None, time_max = None, time_thinning = 1,
    2966 time_unit = None, title_on = None, use_cache = False, verbose = False}
    2967 
     2825\begin{funcdesc}{sww2timeseries}{swwfiles, gauge_filename, production_dirs, report=None, reportname=None,
     2826plot_quantity=None, generate_fig=False, surface=None, time_min=None, time_max=None, time_thinning=1,
     2827time_unit=None, title_on=None, use_cache=False, verbose=False}
    29682828  Module: \module{anuga.abstract\_2d\_finite\_volumes.util}
    29692829
    29702830  Return csv files for the location in the \code{gauge_filename} and can also return plots of them
    29712831
    2972   See doc string for general function sww2timeseries for details.
    2973 
     2832  See the 'doc' string for general function \code{sww2timeseries} for details.
    29742833\end{funcdesc}
    2975 
    29762834
    29772835\begin{funcdesc}{get\_flow\_through\_cross\_section}{filename, cross\_section, verbose=False}
     
    29832841  \begin{itemize}
    29842842        \item filename: Name of sww file containing ANUGA model output.
    2985         \item polyline: Representation of desired cross section - it may contain multiple
    2986           sections allowing for complex shapes. Assume absolute UTM coordinates.
     2843        \item polyline: Representation of desired cross section -- it may contain multiple
     2844                        sections allowing for complex shapes. Assume absolute UTM coordinates.
    29872845  \end{itemize}
    29882846
     
    30002858
    30012859  \begin{verbatim}
    3002   cross_section = [[x, 0], [x, width]]
    3003   time, Q = get_flow_through_cross_section(filename,
    3004                                            cross_section,
    3005                                            verbose=False)
     2860cross_section = [[x, 0], [x, width]]
     2861time, Q = get_flow_through_cross_section(filename,
     2862                                         cross_section,
     2863                                         verbose=False)
    30062864  \end{verbatim}
    30072865
    3008 
    3009   See doc string for general function get\_maximum\_inundation\_data for details.
    3010 
     2866  See the 'doc' string for general function \code{get_maximum_inundation_data} for details.
    30112867\end{funcdesc}
    30122868
    30132869
    3014 
    30152870\section{Other}
    3016 
    3017   \begin{funcdesc}{domain.create\_quantity\_from\_expression}{string}
    3018 
    3019   Handy for creating derived quantities on-the-fly as for example
     2871\begin{funcdesc}{domain.create\_quantity\_from\_expression}{string}
     2872  Handy for creating derived quantities on-the-fly as for example:
     2873
    30202874  \begin{verbatim}
    3021   Depth = domain.create_quantity_from_expression('stage-elevation')
    3022 
    3023   exp = '(xmomentum*xmomentum + ymomentum*ymomentum)**0.5')
    3024   Absolute_momentum = domain.create_quantity_from_expression(exp)
     2875Depth = domain.create_quantity_from_expression('stage-elevation')
     2876
     2877exp = '(xmomentum*xmomentum + ymomentum*ymomentum)**0.5'
     2878Absolute_momentum = domain.create_quantity_from_expression(exp)
    30252879  \end{verbatim}
    30262880
    30272881  %See also \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.
    3028   \end{funcdesc}
    3029 
    3030 
    3031 
    3032 
     2882\end{funcdesc}
    30332883
    30342884%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    3035 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    30362885
    30372886\chapter{\anuga System Architecture}
    3038 
    30392887
    30402888\section{File Formats}
     
    30462894
    30472895\bigskip
    3048 
    30492896\begin{center}
    3050 
    30512897\begin{tabular}{|ll|}  \hline
    3052 
    3053 \textbf{Extension} & \textbf{Description} \\
    3054 \hline\hline
    3055 
    3056 \code{.sww} & NetCDF format for storing model output with mesh information
    3057 \code{f(t,x,y)}\\
    3058 
    3059 \code{.sts} & NetCDF format for storing model ouput \code{f(t,x,y)} without any mesh information\\
    3060 
    3061 \code{.tms} & NetCDF format for storing time series \code{f(t)}\\
    3062 
    3063 \code{.csv/.txt} & ASCII format called points csv for storing
    3064 arbitrary points and associated attributes\\
    3065 
    3066 \code{.pts} & NetCDF format for storing arbitrary points and
    3067 associated attributes\\
    3068 
    3069 \code{.asc} & ASCII format of regular DEMs as output from ArcView\\
    3070 
    3071 \code{.prj} & Associated ArcView file giving more metadata for
    3072 \code{.asc} format\\
    3073 
    3074 \code{.ers} & ERMapper header format of regular DEMs for ArcView\\
    3075 
    3076 \code{.dem} & NetCDF representation of regular DEM data\\
    3077 
    3078 \code{.tsh} & ASCII format for storing meshes and associated
    3079 boundary and region info\\
    3080 
    3081 \code{.msh} & NetCDF format for storing meshes and associated
    3082 boundary and region info\\
    3083 
    3084 \code{.nc} & Native ferret NetCDF format\\
    3085 
    3086 \code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
    3087 %\caption{File formats used by \anuga}
     2898  \textbf{Extension} & \textbf{Description} \\
     2899  \hline\hline
     2900  \code{.sww} & NetCDF format for storing model output with mesh information \code{f(t,x,y)}\\
     2901  \code{.sts} & NetCDF format for storing model ouput \code{f(t,x,y)} without any mesh information\\
     2902  \code{.tms} & NetCDF format for storing time series \code{f(t)}\\
     2903  \code{.csv/.txt} & ASCII format called points csv for storing arbitrary points and associated attributes\\
     2904  \code{.pts} & NetCDF format for storing arbitrary points and associated attributes\\
     2905  \code{.asc} & ASCII format of regular DEMs as output from ArcView\\
     2906  \code{.prj} & Associated ArcView file giving more metadata for \code{.asc} format\\
     2907  \code{.ers} & ERMapper header format of regular DEMs for ArcView\\
     2908  \code{.dem} & NetCDF representation of regular DEM data\\
     2909  \code{.tsh} & ASCII format for storing meshes and associated boundary and region info\\
     2910  \code{.msh} & NetCDF format for storing meshes and associated boundary and region info\\
     2911  \code{.nc} & Native ferret NetCDF format\\
     2912  \code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
     2913  %\caption{File formats used by \anuga}
    30882914\end{tabular}
    3089 
    3090 
    30912915\end{center}
    30922916
    30932917The above table shows the file extensions used to identify the
    30942918formats of files. However, typically, in referring to a format we
    3095 capitalise the extension and omit the initial full stop---thus, we
    3096 refer, for example, to `SWW files' or `PRJ files'.
     2919capitalise the extension and omit the initial full stop -- thus, we
     2920refer, for example, to 'SWW files' or 'PRJ files'.
    30972921
    30982922\bigskip
     
    31102934
    31112935\begin{tabular}{ll}
    3112 ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
    3113 DEMs to native \code{.pts} file\\
    3114 
    3115 NC $\rightarrow$ SWW & Convert MOST boundary files to
    3116 boundary \code{.sww}\\
    3117 
    3118 PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
    3119 
    3120 TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
    3121 \code{animate}\\
    3122 
    3123 TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
    3124 \code{\anuga}\\
    3125 
    3126 Polygonal mesh outline $\rightarrow$ & TSH or MSH
     2936  ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert DEMs to native \code{.pts} file\\
     2937  NC $\rightarrow$ SWW & Convert MOST boundary files to boundary \code{.sww}\\
     2938  PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
     2939  TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using \code{animate}\\
     2940  TSH + Boundary SWW $\rightarrow$ SWW & Simulation using \code{\anuga}\\
     2941  Polygonal mesh outline $\rightarrow$ & TSH or MSH
    31272942\end{tabular}
    3128 
    3129 
    3130 
    31312943
    31322944\bigskip
     
    31342946\subsection{SWW, STS and TMS Formats}
    31352947\label{sec:sww format}
    3136 
    3137 The SWW, STS and TMS formats are all NetCDF formats, and are of key
    3138 importance for \anuga.
     2948The SWW, STS and TMS formats are all NetCDF formats, and are of key importance for \anuga.
    31392949
    31402950An SWW file is used for storing \anuga output and therefore pertains
     
    31442954
    31452955\begin{itemize}
    3146     \item \code{x} and \code{y}: coordinates of the points, represented as Numeric arrays
    3147     \item \code{elevation}, a Numeric array storing bed-elevations
    3148     \item \code{volumes}, a list specifying the points at the vertices of each of the
    3149     triangles
     2956  \item \code{x} and \code{y}: coordinates of the points, represented as numeric arrays
     2957  \item \code{elevation}, a numeric array storing bed-elevations
     2958  \item \code{volumes}, a list specifying the points at the vertices of each of the triangles
    31502959    % Refer here to the example to be provided in describing the simple example
    3151     \item \code{time}, a Numeric array containing times for model
    3152     evaluation
     2960  \item \code{time}, a numeric array containing times for model evaluation
    31532961\end{itemize}
    3154 
    31552962
    31562963The contents of an SWW file may be viewed using the anuga viewer
     
    31782985variables:
    31792986\begin{itemize}
    3180     \item \code{x} and \code{y}: coordinates of the points, represented as Numeric arrays
    3181     \item \code{permutation}: Original indices of the points as specified by
    3182     the optional \code{ordering\_file}
    3183     (see the function \code{urs2sts} in Section \ref{sec:basicfileconversions}).
    3184    
    3185     \item \code{elevation}, a Numeric array storing bed-elevations
     2987  \item \code{x} and \code{y}: coordinates of the points, represented as numeric arrays
     2988  \item \code{permutation}: Original indices of the points as specified by the optional \code{ordering\_file}
     2989                            (see the function \code{urs2sts} in Section \ref{sec:basicfileconversions}).
     2990  \item \code{elevation}: a numeric array storing bed-elevations
    31862991    % Refer here to the example to be provided in describing the simple example
    3187     \item \code{time}, a Numeric array containing times for model
    3188     evaluation
     2992  \item \code{time}: a numeric array containing times for model evaluation
    31892993\end{itemize}
    3190 The only difference between the STS format and the SWW format is the former does not contain a list specifying the points at the vertices of each of the triangles (\code{volumes}). Consequenlty information (arrays) stored within an STS file such as \code{elevation} can be accessed in exactly the same way as it would be extraced from an SWW file.
    3191 
    3192 A TMS file is used to store time series data that is independent of
    3193 position.
    3194 
     2994
     2995The only difference between the STS format and the SWW format is the former does
     2996not contain a list specifying the points at the vertices of each of the triangles
     2997(\code{volumes}). Consequently information (arrays) stored within an STS file such
     2998as \code{elevation} can be accessed in exactly the same way as it would be extracted
     2999from an SWW file.
     3000
     3001A TMS file is used to store time series data that is independent of position.
    31953002
    31963003\subsection{Mesh File Formats}
     
    32013008an MSH file, which is a NetCDF file. A mesh file can be generated
    32023009from the function \function{create\_mesh\_from\_regions} (see
    3203 Section \ref{sec:meshgeneration}) and used to initialise a domain.
    3204 
    3205 A mesh file can define the outline of the mesh---the vertices and
     3010Section \ref{sec:meshgeneration}) and be used to initialise a domain.
     3011
     3012A mesh file can define the outline of the mesh -- the vertices and
    32063013line segments that enclose the region in which the mesh is
    3207 created---and the triangular mesh itself, which is specified by
     3014created -- and the triangular mesh itself, which is specified by
    32083015listing the triangles and their vertices, and the segments, which
    32093016are those sides of the triangles that are associated with boundary
    32103017conditions.
    32113018
    3212 In addition, a mesh file may contain `holes' and/or `regions'. A
     3019In addition, a mesh file may contain 'holes' and/or 'regions'. A
    32133020hole represents an area where no mesh is to be created, while a
    32143021region is a labelled area used for defining properties of a mesh,
     
    32173024
    32183025A mesh file can also contain a georeference, which describes an
    3219 offset to be applied to $x$ and $y$ values --- e.g.\ to the vertices.
    3220 
     3026offset to be applied to $x$ and $y$ values -- e.g.\ to the vertices.
    32213027
    32223028\subsection{Formats for Storing Arbitrary Points and Attributes}
    3223 
    32243029
    32253030A CSV/TXT file is used to store data representing
     
    32273032
    32283033The format for an CSV/TXT file is:\\
    3229 %\begin{verbatim}
    3230 
    3231             first line:   \code{[column names]}\\
    3232             other lines:  \code{[x value], [y value], [attributes]}\\
    3233 
    3234             for example:\\
    3235             \code{x, y, elevation, friction}\\
    3236             \code{0.6, 0.7, 4.9, 0.3}\\
    3237             \code{1.9, 2.8, 5, 0.3}\\
    3238             \code{2.7, 2.4, 5.2, 0.3}
    3239 
    3240         The delimiter is a comma. The first two columns are assumed to
    3241         be x, y coordinates.
    3242        
     3034 \\
     3035first line:   \code{[column names]}\\
     3036other lines:  \code{[x value], [y value], [attributes]}\\
     3037
     3038for example:
     3039
     3040\begin{verbatim}
     3041x, y, elevation, friction}
     30420.6, 0.7, 4.9, 0.3}
     30431.9, 2.8, 5, 0.3}
     30442.7, 2.4, 5.2, 0.3}
     3045\end{verbatim}
     3046
     3047The delimiter is a comma. The first two columns are assumed to
     3048be x, y coordinates.
    32433049
    32443050A PTS file is a NetCDF representation of the data held in an points CSV
    32453051file. If the data is associated with a set of $N$ points, then the
    3246 data is stored using an $N \times 2$ Numeric array of float
    3247 variables for the points and an $N \times 1$ Numeric array for each
     3052data is stored using an $N \times 2$ numeric array of float
     3053variables for the points and an $N \times 1$ numeric array for each
    32483054attribute.
    3249 
    3250 %\end{verbatim}
    32513055
    32523056\subsection{ArcView Formats}
     
    32733077to represent metadata for a DEM.
    32743078
    3275 
    32763079\subsection{DEM Format}
    32773080
    32783081A DEM file in \anuga is a NetCDF representation of regular DEM data.
    32793082
    3280 
    32813083\subsection{Other Formats}
    3282 
    3283 
    3284 
    32853084
    32863085\subsection{Basic File Conversions}
    32873086\label{sec:basicfileconversions}
    32883087
    3289   \begin{funcdesc}{sww2dem}{basename_in, basename_out = None,
    3290             quantity = None,
    3291             timestep = None,
    3292             reduction = None,
    3293             cellsize = 10,
    3294             number_of_decimal_places = None,
    3295             NODATA_value = -9999,
    3296             easting_min = None,
    3297             easting_max = None,
    3298             northing_min = None,
    3299             northing_max = None,
    3300             expand_search = False,
    3301             verbose = False,
    3302             origin = None,
    3303             datum = 'WGS84',
    3304             format = 'ers'}
     3088\begin{funcdesc}{sww2dem}{basename_in, basename_out=None,
     3089            quantity=None,
     3090            timestep=None,
     3091            reduction=None,
     3092            cellsize=10,
     3093            number_of_decimal_places=None,
     3094            NODATA_value=-9999,
     3095            easting_min=None,
     3096            easting_max=None,
     3097            northing_min=None,
     3098            northing_max=None,
     3099            expand_search=False,
     3100            verbose=False,
     3101            origin=None,
     3102            datum='WGS84',
     3103            format='ers'}
    33053104  Module: \module{shallow\_water.data\_manager}
    33063105
     
    33123111  within a specified rectangular area. The \code{reduction} input refers to a function
    33133112  to reduce the quantities over all time step of the SWW file, example, maximum.
    3314   \end{funcdesc}
    3315 
    3316 
    3317   \begin{funcdesc}{dem2pts}{basename_in, basename_out=None,
     3113\end{funcdesc}
     3114
     3115\begin{funcdesc}{dem2pts}{basename_in, basename_out=None,
    33183116            easting_min=None, easting_max=None,
    33193117            northing_min=None, northing_max=None,
     
    33233121  Takes DEM data (a NetCDF file representation of data from a regular Digital
    33243122  Elevation Model) and converts it to PTS format.
    3325   \end{funcdesc}
    3326 
    3327   \begin{funcdesc}{urs2sts}{basename_in, basename_out=None,
     3123\end{funcdesc}
     3124
     3125\begin{funcdesc}{urs2sts}{basename_in, basename_out=None,
    33283126            weights=None, verbose=False,
    33293127            origin=None,mean_stage=0.0,
     
    33313129  Module: \module{shallow\_water.data\_manager}
    33323130
    3333   Takes urs data in (timeseries data in mux2 format) and converts it to STS format. The optional filename \code{ordering\_filename} specifies the permutation of indices of points to select along with their longitudes and latitudes. This permutation will also be
    3334   stored in the STS file. If absent, all points are taken and the permutation will be trivial, i.e. $0, 1, \ldots, N-1$, where $N$ is the total number of points stored. 
    3335   \end{funcdesc}
    3336 
    3337  
    3338  
    3339  
     3131  Takes URS data (timeseries data in mux2 format) and converts it to STS format.
     3132  The optional filename \code{ordering\_filename} specifies the permutation of indices
     3133  of points to select along with their longitudes and latitudes. This permutation will also be
     3134  stored in the STS file. If absent, all points are taken and the permutation will be trivial,
     3135  i.e. $0, 1, \ldots, N-1$, where $N$ is the total number of points stored. 
     3136\end{funcdesc}
     3137
    33403138\begin{funcdesc}{csv2building\_polygons}{file\_name, floor\_height=3}
    3341 
    3342 Module: \module{shallow\_water.data\_manager}
    3343 
    3344 Convert CSV files of the form:
    3345 {\small
    3346 \begin{verbatim}
    3347     easting,northing,id,floors
    3348     422664.22,870785.46,2,0
    3349     422672.48,870780.14,2,0
    3350     422668.17,870772.62,2,0
    3351     422660.35,870777.17,2,0
    3352     422664.22,870785.46,2,0
    3353     422661.30,871215.06,3,1
    3354     422667.50,871215.70,3,1
    3355     422668.30,871204.86,3,1
    3356     422662.21,871204.33,3,1
    3357     422661.30,871215.06,3,1
    3358 \end{verbatim} }
    3359 
    3360 to a dictionary of polygons with id as key.
    3361 The associated number of floors are converted to m above MSL and
    3362 returned as a separate dictionary also keyed by id.
     3139  Module: \module{shallow\_water.data\_manager}
     3140
     3141  Convert CSV files of the form:
     3142
     3143  \begin{verbatim}
     3144easting,northing,id,floors
     3145422664.22,870785.46,2,0
     3146422672.48,870780.14,2,0
     3147422668.17,870772.62,2,0
     3148422660.35,870777.17,2,0
     3149422664.22,870785.46,2,0
     3150422661.30,871215.06,3,1
     3151422667.50,871215.70,3,1
     3152422668.30,871204.86,3,1
     3153422662.21,871204.33,3,1
     3154422661.30,871215.06,3,1
     3155  \end{verbatim}
     3156
     3157  to a dictionary of polygons with \code{id} as key.
     3158  The associated number of \code{floors} are converted to m above MSL and
     3159  returned as a separate dictionary also keyed by \code{id}.
    33633160   
    3364 Optional parameter floor_height is the height of each building story.
    3365 
    3366 These can e.g. be converted to a Polygon\_function for use with add\_quantity
    3367 as shown on page \pageref{add quantity}.
     3161  Optional parameter \code{floor_height} is the height of each building story.
     3162
     3163  These can e.g. be converted to a \code{Polygon_function} for use with \code{add_quantity}
     3164  as shown on page \pageref{add quantity}.
    33683165\end{funcdesc}
    33693166
    3370  
    3371  
    3372 
    3373 
    3374 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    33753167%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    33763168
     
    33783170\label{cd:mathematical background}
    33793171
     3172
    33803173\section{Introduction}
    33813174
    33823175This chapter outlines the mathematics underpinning \anuga.
    3383 
    33843176
    33853177
     
    34363228and tsunamis.
    34373229
     3230
    34383231\section{Finite Volume Method}
    34393232\label{sec:fvm}
     
    34473240particular interest.
    34483241
    3449 \begin{figure}
    3450 \begin{center}
    3451 \includegraphics[width=8.0cm,keepaspectratio=true]{graphics/step-five}
    3452 \caption{Triangular mesh used in our finite volume method. Conserved
    3453 quantities $h$, $uh$ and $vh$ are associated with the centroid of
    3454 each triangular cell.} \label{fig:mesh}
    3455 \end{center}
    3456 \end{figure}
     3242\begin{figure}[htp] \begin{center}
     3243  \includegraphics[width=8.0cm,keepaspectratio=true]{graphics/step-five}
     3244  \caption{Triangular mesh used in our finite volume method. Conserved
     3245           quantities $h$, $uh$ and $vh$ are associated with the centroid of
     3246           each triangular cell.}
     3247  \label{fig:mesh}
     3248\end{center} \end{figure}
    34573249
    34583250The equations constituting the finite-volume method are obtained by
     
    34743266where
    34753267\begin{itemize}
    3476 \item $\UU_i$ the vector of conserved quantities averaged over the $i$th cell,
    3477 \item $\SSS_i$ is the source term associated with the $i$th cell,
    3478 and
    3479 \item $\HH_{ij}$ is the outward normal flux of
    3480 material across the \textit{ij}th edge.
     3268  \item $\UU_i$ the vector of conserved quantities averaged over the $i$th cell,
     3269  \item $\SSS_i$ is the source term associated with the $i$th cell, and
     3270  \item $\HH_{ij}$ is the outward normal flux of material across the \textit{ij}th edge.
    34813271\end{itemize}
    3482 
    34833272
    34843273%\item $l_{ij}$ is the length of the edge between the $i$th and $j$th
     
    35103299We use a second order reconstruction to produce a piece-wise linear
    35113300function construction of the conserved quantities for  all $x \in
    3512 T_i$ for each cell (see Figure~\ref{fig:mesh:reconstruct}. This
     3301T_i$ for each cell (see Figure~\ref{fig:mesh:reconstruct}). This
    35133302function is allowed to be discontinuous across the edges of the
    35143303cells, but the slope of this function is limited to avoid
     
    35213310calculate an approximation of the flux across each edge.
    35223311
    3523 \begin{figure}
    3524 \begin{center}
    3525 \includegraphics[width=8.0cm,keepaspectratio=true]{graphics/step-reconstruct}
    3526 \caption{From the values of the conserved quantities at the centroid
    3527 of the cell and its neighbouring cells, a discontinuous piecewise
    3528 linear reconstruction of the conserved quantities is obtained.}
    3529 \label{fig:mesh:reconstruct}
    3530 \end{center}
    3531 \end{figure}
     3312\begin{figure}[htp] \begin{center}
     3313  \includegraphics[width=8.0cm,keepaspectratio=true]{graphics/step-reconstruct}
     3314  \caption{From the values of the conserved quantities at the centroid
     3315           of the cell and its neighbouring cells, a discontinuous piecewise
     3316           linear reconstruction of the conserved quantities is obtained.}
     3317  \label{fig:mesh:reconstruct}
     3318\end{center} \end{figure}
    35323319
    35333320In the computations presented in this paper we use an explicit Euler
     
    35463333of each triangle.
    35473334
     3335
    35483336\section{Flux limiting}
    35493337
    35503338The shallow water equations are solved numerically using a
    3551 finite volume method on unstructured triangular grid.
     3339finite volume method on an unstructured triangular grid.
    35523340The upwind central scheme due to Kurganov and Petrova is used as an
    35533341approximate Riemann solver for the computation of inviscid flux functions.
     
    35573345small water depths near a wet/dry boundary we employ a new flux limiter that
    35583346ensures that unphysical fluxes are never encounted.
    3559 
    35603347
    35613348Let $u$ and $v$ be the velocity components in the $x$ and $y$ direction,
     
    35993386\]
    36003387
    3601 
    36023388ANUGA has a global parameter $H_0$ that controls the minimal depth which
    36033389is considered in the various equations. This parameter is typically set to
     
    36183404which converges quadratically to the true value with the multiple N.
    36193405
    3620 
    3621 %The developed numerical model has been applied to several test cases as well as to real flows. Numerical tests prove the robustness and accuracy of the model.
    3622 
    3623 
    3624 
     3406%The developed numerical model has been applied to several test cases
     3407%as well as to real flows. numeric tests prove the robustness and accuracy of the model.
    36253408
    36263409
    36273410\section{Slope limiting}
    3628 A multidimensional slope-limiting technique is employed to achieve second-order spatial accuracy and to prevent spurious oscillations. This is using the MinMod limiter and is documented elsewhere.
    3629 
    3630 However close to the bed, the limiter must ensure that no negative depths occur. On the other hand, in deep water, the bed topography should be ignored for the purpose of the limiter.
    3631 
     3411A multidimensional slope-limiting technique is employed to achieve second-order spatial
     3412accuracy and to prevent spurious oscillations. This is using the MinMod limiter and is
     3413documented elsewhere.
     3414
     3415However close to the bed, the limiter must ensure that no negative depths occur.
     3416 On the other hand, in deep water, the bed topography should be ignored for the
     3417purpose of the limiter.
    36323418
    36333419Let $w, z, h$  be the stage, bed elevation and depth at the centroid and
     
    36493435\]
    36503436
    3651 
    36523437Similarly, let $\bar{w_i}$ be the stage obtained from a gradient
    36533438limiter limiting on depth respecting the bed slope.
     
    36563441  \bar{h_i} = \bar{w_i} - z_i
    36573442\]
    3658 
    36593443
    36603444We introduce the concept of a balanced stage $w_i$ which is obtained as
     
    37303514%provides a numerical safety {??)
    37313515
    3732 
    3733 
    3734 
    3735 
    37363516%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    3737 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    37383517
    37393518\chapter{Basic \anuga Assumptions}
    37403519
    3741  \section{Time}
     3520
     3521\section{Time}
     3522
    37423523Physical model time cannot be earlier than 1 Jan 1970 00:00:00.
    37433524If one wished to recreate scenarios prior to that date it must be done
    37443525using some relative time (e.g. 0).
    37453526
    3746 The ANUGA domain has an attribute \code{starttime} which is used in cases where the simulation should be started later than the beginning of some input data such as those obtained from boundaries or forcing functions (hydrographs, file\_boundary etc)
    3747 
    3748 The \code{file\_boundary} may adjust domain.startime in case the input data does not itself start until a later time.
     3527The ANUGA domain has an attribute \code{starttime} which is used in cases where the
     3528simulation should be started later than the beginning of some input data such as those
     3529obtained from boundaries or forcing functions (hydrographs, file\_boundary etc).
     3530
     3531The \code{domain.startime} may be adjusted in \code{file_boundary} in the case the
     3532input data does not itself start until a later time.
    37493533
    37503534 
     
    37523536
    37533537\subsection{Projection}
    3754 All spatial data relates to the WGS84 datum (or GDA94) and assumes a projection into UTM with false easting of 500000 and false northing of
     3538All spatial data relates to the WGS84 datum (or GDA94) and assumes a projection
     3539into UTM with false easting of 500000 and false northing of
    375535401000000 on the southern hemisphere (0 on the northern hemisphere).
    37563541All locations must consequently be specified in Cartesian coordinates
     
    37623547It is important to realise that ANUGA for numerical precision uses coordinates that are relative
    37633548to the lower left node of the rectangle containing the mesh ($x_{\mbox{min}}$, $y_{\mbox{min}}$).
    3764 This origin is referred to internally as xllcorner, yllcorner following the ESRI ascii grid notation. 
    3765 The sww file format also includes xllcorner, yllcorner and any coordinate in the file should be adjusted
     3549This origin is referred to internally as \code{xllcorner}, \code{yllcorner} following the ESRI ASCII grid notation. 
     3550The sww file format also includes \code{xllcorner}, \code{yllcorner} and any coordinate in the file should be adjusted
    37663551by adding this origin. See Section \ref{sec:sww format}.
    37673552
    3768 Throughout the ANUGA interface functions have optional boolean arguments \code{absolute} which control
    3769 whether spatial data received is using the internal representation (absolute=False) or the
    3770 user coordinate set (absolute=True). See e.g. \code{get\_vertex\_coordinates} on \pageref{pg:get vertex coordinates}.
     3553Throughout the ANUGA interface, functions have optional boolean arguments \code{absolute} which controls
     3554whether spatial data received is using the internal representation (\code{absolute=False}) or the
     3555user coordinate set (\code{absolute=True}). See e.g. \code{get_vertex_coordinates} on \pageref{pg:get vertex coordinates}.
    37713556
    37723557DEMs, meshes and boundary conditions can have different origins. However, the internal representation in ANUGA
     
    37753560\subsection{Polygons}
    37763561When generating a mesh it is assumed that polygons do not cross.
    3777 Having polygons tht cross can cause the mesh generation to fail or bad
    3778 meshes being produced.
    3779 
     3562Having polygons that cross can cause bad meshes to be produced or the mesh generation itself may fail.
    37803563
    37813564%OLD
     
    38123595%                     run inundation simulation.
    38133596
    3814 
    38153597%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    3816 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    38173598
    38183599\appendix
     3600
    38193601
    38203602\chapter{Supporting Tools}
     
    38223604
    38233605This section describes a number of supporting tools, supplied with \anuga, that offer a
    3824 variety of types of functionality and enhance the basic capabilities of \anuga.
     3606variety of types of functionality and can enhance the basic capabilities of \anuga.
     3607
    38253608
    38263609\section{caching}
     
    38283611
    38293612The \code{cache} function is used to provide supervised caching of function
    3830 results. A Python function call of the form
    3831 
    3832       {\small \begin{verbatim}
    3833       result = func(arg1,...,argn)
    3834       \end{verbatim}}
    3835 
    3836   can be replaced by
    3837 
    3838       {\small \begin{verbatim}
    3839       from caching import cache
    3840       result = cache(func,(arg1,...,argn))
    3841       \end{verbatim}}
    3842 
    3843   which returns the same output but reuses cached
    3844   results if the function has been computed previously in the same context.
    3845   \code{result} and the arguments can be simple types, tuples, list, dictionaries or
    3846   objects, but not unhashable types such as functions or open file objects.
    3847   The function \code{func} may be a member function of an object or a module.
    3848 
    3849   This type of caching is particularly useful for computationally intensive
    3850   functions with few frequently used combinations of input arguments. Note that
    3851   if the inputs or output are very large caching may not save time because
    3852   disc access may dominate the execution time.
    3853 
    3854   If the function definition changes after a result has been cached, this will be
    3855   detected by examining the functions \code{bytecode (co\_code, co\_consts,
    3856   func\_defaults, co\_argcount)} and the function will be recomputed.
    3857   However, caching will not detect changes in modules used by \code{func}.
    3858   In this case cache must be cleared manually.
    3859 
    3860   Options are set by means of the function \code{set\_option(key, value)},
    3861   where \code{key} is a key associated with a
    3862   Python dictionary \code{options}. This dictionary stores settings such as the name of
    3863   the directory used, the maximum
    3864   number of cached files allowed, and so on.
    3865 
    3866   The \code{cache} function allows the user also to specify a list of dependent files. If any of these
    3867   have been changed, the function is recomputed and the results stored again.
    3868 
    3869   %Other features include support for compression and a capability to \ldots
    3870 
    3871 
    3872    \textbf{USAGE:} \nopagebreak
    3873 
    3874     {\small \begin{verbatim}
    3875     result = cache(func, args, kwargs, dependencies, cachedir, verbose,
    3876                    compression, evaluate, test, return_filename)
    3877     \end{verbatim}}
    3878 
    3879 
    3880 \section{ANUGA viewer - animate}
     3613results. A Python function call of the form:
     3614
     3615\begin{verbatim}
     3616result = func(arg1, ..., argn)
     3617\end{verbatim}
     3618
     3619can be replaced by:
     3620
     3621\begin{verbatim}
     3622from caching import cache
     3623result = cache(func,(arg1, ..., argn))
     3624\end{verbatim}
     3625
     3626which returns the same output but reuses cached
     3627results if the function has been computed previously in the same context.
     3628\code{result} and the arguments can be simple types, tuples, list, dictionaries or
     3629objects, but not unhashable types such as functions or open file objects.
     3630The function \code{func} may be a member function of an object or a module.
     3631
     3632This type of caching is particularly useful for computationally intensive
     3633functions with few frequently used combinations of input arguments. Note that
     3634if the inputs or output are very large caching may not save time because
     3635disc access may dominate the execution time.
     3636
     3637If the function definition changes after a result has been cached, this will be
     3638detected by examining the functions \code{bytecode (co\_code, co\_consts,
     3639func\_defaults, co\_argcount)} and the function will be recomputed.
     3640However, caching will not detect changes in modules used by \code{func}.
     3641In this case cache must be cleared manually.
     3642
     3643Options are set by means of the function \code{set\_option(key, value)},
     3644where \code{key} is a key associated with a
     3645Python dictionary \code{options}. This dictionary stores settings such as the name of
     3646the directory used, the maximum number of cached files allowed, and so on.
     3647
     3648The \code{cache} function allows the user also to specify a list of dependent files. If any of these
     3649have been changed, the function is recomputed and the results stored again.
     3650
     3651%Other features include support for compression and a capability to \ldots
     3652
     3653\textbf{USAGE:} \nopagebreak
     3654
     3655\begin{verbatim}
     3656result = cache(func, args, kwargs, dependencies, cachedir, verbose,
     3657               compression, evaluate, test, return_filename)
     3658\end{verbatim}
     3659
     3660
     3661\section{ANUGA viewer -- animate}
    38813662\label{sec:animate}
    3882  The output generated by \anuga may be viewed by
     3663
     3664The output generated by \anuga may be viewed by
    38833665means of the visualisation tool \code{animate}, which takes the
    3884 \code{SWW} file output by \anuga and creates a visual representation
     3666\code{SWW} file generated by \anuga and creates a visual representation
    38853667of the data. Examples may be seen in Figures \ref{fig:runupstart}
    38863668and \ref{fig:runup2}. To view an \code{SWW} file with
     
    38903672file association to make files with the extension \code{.sww} open
    38913673with \code{animate}. Alternatively, you can operate \code{animate}
    3892 from the command line, in both Windows and Linux environments.
    3893 
    3894 On successful operation, you will see an interactive moving-picture
    3895 display. You can use keys and the mouse to slow down, speed up or
     3674from the command line.
     3675
     3676Upon starting the viewer, you will see an interactive moving-picture
     3677display. You can use the keyboard and the mouse to slow down, speed up or
    38963678stop the display, change the viewing position or carry out a number
    38973679of other simple operations. Help is also displayed when you press
    38983680the \code{h} key.
    38993681
    3900 The main keys operating the interactive screen are:\\
    3901 
     3682The main keys operating the interactive screen are:
    39023683\begin{center}
    39033684\begin{tabular}{|ll|}   \hline
    3904 
    3905 \code{w} & toggle wireframe \\
    3906 
    3907 space bar & start/stop\\
    3908 
    3909 up/down arrows & increase/decrease speed\\
    3910 
    3911 left/right arrows & direction in time \emph{(when running)}\\
    3912 & step through simulation \emph{(when stopped)}\\
    3913 
    3914 left mouse button & rotate\\
    3915 
    3916 middle mouse button & pan\\
    3917 
    3918 right mouse button & zoom\\  \hline
    3919 
     3685  \code{h} & toggle on-screen help display \\
     3686  \code{w} & toggle wireframe \\
     3687  space bar & start/stop\\
     3688  up/down arrows & increase/decrease speed\\
     3689  left/right arrows & direction in time \emph{(when running)}\\
     3690                    & step through simulation \emph{(when stopped)}\\
     3691  left mouse button & rotate\\
     3692  middle mouse button & pan\\
     3693  right mouse button & zoom\\  \hline
    39203694\end{tabular}
    39213695\end{center}
    39223696
    3923 \vfill
    3924 
    3925 The following table describes how to operate animate from the command line:
     3697% \vfill
     3698
     3699The following table describes how to operate \code{animate} from the command line:
    39263700
    39273701Usage: \code{animate [options] swwfile \ldots}\\  \nopagebreak
     
    39493723
    39503724\begin{tabular}{ll}
    3951 
    39523725  \code{-hmin <float>} & Height below which transparency is set to
    39533726                                     zero\\
     
    39613734\begin{tabular}{ll}
    39623735  \code{-loop}  & Repeated (looped) playback of \code{.swm} files\\
    3963 
    39643736\end{tabular}
    39653737
     
    39673739  \code{-movie <dirname>} & Save numbered images to named directory and
    39683740                                     quit\\
    3969 
    39703741  \code{-nosky} & Omit background sky\\
    3971 
    3972 
    39733742  \code{-scale <float>} & Vertical scale factor\\
    39743743  \code{-texture <file>} & Image to use for bedslope topography\\
     
    39783747\end{tabular}
    39793748
     3749
     3750/pagebreak
    39803751\section{utilities/polygons}
    39813752
    3982   \declaremodule{standard}{utilities.polygon}
    3983   \refmodindex{utilities.polygon}
    3984 
    3985   \begin{classdesc}{Polygon\_function}{regions, default=0.0, geo_reference=None}
     3753\declaremodule{standard}{utilities.polygon}
     3754\refmodindex{utilities.polygon}
     3755
     3756\begin{classdesc}{Polygon\_function}{regions, default=0.0, geo_reference=None}
    39863757  Module: \code{utilities.polygon}
    39873758
     
    40023773  that are passed into the function. Typically they will be relative to
    40033774  some origin. In ANUGA, a typical call will take the form:
    4004   {\small \begin{verbatim}
    4005      set_quantity('elevation',
    4006                   Polygon_function([(P1, v1), (P2, v2)],
    4007                                    default=v3,
    4008                                    geo_reference=domain.geo_reference))
    4009   \end{verbatim}}
    4010 
    4011 
    4012   \end{classdesc}
    4013 
    4014   \begin{funcdesc}{read\_polygon}{filename}
     3775
     3776  \begin{verbatim}
     3777set_quantity('elevation',
     3778             Polygon_function([(P1, v1), (P2, v2)],
     3779                              default=v3,
     3780                              geo_reference=domain.geo_reference))
     3781  \end{verbatim}
     3782\end{classdesc}
     3783
     3784\begin{funcdesc}{read\_polygon}{filename}
    40153785  Module: \code{utilities.polygon}
    40163786
     
    40183788  line of the file must contain exactly two numbers, separated by a comma, which are interpreted
    40193789  as coordinates of one vertex of the polygon.
    4020   \end{funcdesc}
    4021 
    4022   \begin{funcdesc}{populate\_polygon}{polygon, number_of_points, seed = None, exclude = None}
     3790\end{funcdesc}
     3791
     3792\begin{funcdesc}{populate\_polygon}{polygon, number_of_points, seed = None, exclude = None}
    40233793  Module: \code{utilities.polygon}
    40243794
    40253795  Populates the interior of the specified polygon with the specified number of points,
    40263796  selected by means of a uniform distribution function.
    4027   \end{funcdesc}
    4028 
    4029   \begin{funcdesc}{point\_in\_polygon}{polygon, delta=1e-8}
     3797\end{funcdesc}
     3798
     3799\begin{funcdesc}{point\_in\_polygon}{polygon, delta=1e-8}
    40303800  Module: \code{utilities.polygon}
    40313801
     
    40333803  the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the
    40343804  second argument \code{delta}, which is taken as $10^{-8}$ by default.
    4035   \end{funcdesc}
    4036 
    4037   \begin{funcdesc}{inside\_polygon}{points, polygon, closed = True, verbose = False}
     3805\end{funcdesc}
     3806
     3807\begin{funcdesc}{inside\_polygon}{points, polygon, closed = True, verbose = False}
    40383808  Module: \code{utilities.polygon}
    40393809
    40403810  Used to test whether the members of a list of points
    4041   are inside the specified polygon. Returns a Numeric
     3811  are inside the specified polygon. Returns a numeric
    40423812  array comprising the indices of the points in the list that lie inside the polygon.
    40433813  (If none of the points are inside, returns \code{zeros((0,), 'l')}.)
    40443814  Points on the edges of the polygon are regarded as inside if
    40453815  \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
    4046   \end{funcdesc}
    4047 
    4048   \begin{funcdesc}{outside\_polygon}{points, polygon, closed = True, verbose = False}
     3816\end{funcdesc}
     3817
     3818\begin{funcdesc}{outside\_polygon}{points, polygon, closed = True, verbose = False}
    40493819  Module: \code{utilities.polygon}
    40503820
    4051   Exactly like \code{inside\_polygon}, but with the words `inside' and `outside' interchanged.
    4052   \end{funcdesc}
    4053 
    4054   \begin{funcdesc}{is\_inside\_polygon}{point, polygon, closed=True, verbose=False}
     3821  Exactly like \code{inside\_polygon}, but with the words 'inside' and 'outside' interchanged.
     3822\end{funcdesc}
     3823
     3824\begin{funcdesc}{is\_inside\_polygon}{point, polygon, closed=True, verbose=False}
    40553825  Module: \code{utilities.polygon}
    40563826
     
    40583828  \code{False} otherwise. Points on the edges of the polygon are regarded as inside if
    40593829  \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside.
    4060   \end{funcdesc}
    4061 
    4062   \begin{funcdesc}{is\_outside\_polygon}{point, polygon, closed=True, verbose=False}
     3830\end{funcdesc}
     3831
     3832\begin{funcdesc}{is\_outside\_polygon}{point, polygon, closed=True, verbose=False}
    40633833  Module: \code{utilities.polygon}
    40643834
    4065   Exactly like \code{is\_outside\_polygon}, but with the words `inside' and `outside' interchanged.
    4066   \end{funcdesc}
    4067 
    4068   \begin{funcdesc}{point\_on\_line}{x, y, x0, y0, x1, y1}
     3835  Exactly like \code{is\_outside\_polygon}, but with the words 'inside' and 'outside' interchanged.
     3836\end{funcdesc}
     3837
     3838\begin{funcdesc}{point\_on\_line}{x, y, x0, y0, x1, y1}
    40693839  Module: \code{utilities.polygon}
    40703840
     
    40723842  \code{x, y} is on the line passing through the points with coordinates \code{x0, y0}
    40733843  and \code{x1, y1} (extended if necessary at either end).
    4074   \end{funcdesc}
    4075 
    4076   \begin{funcdesc}{separate\_points\_by\_polygon}{points, polygon, closed = True, verbose = False}
     3844\end{funcdesc}
     3845
     3846\begin{funcdesc}{separate\_points\_by\_polygon}{points, polygon, closed = True, verbose = False}
    40773847    \indexedcode{separate\_points\_by\_polygon}
    40783848  Module: \code{utilities.polygon}
    40793849
    4080   \end{funcdesc}
    4081 
    4082   \begin{funcdesc}{polygon\_area}{polygon}
     3850\end{funcdesc}
     3851
     3852\begin{funcdesc}{polygon\_area}{polygon}
    40833853  Module: \code{utilities.polygon}
    40843854
    40853855  Returns area of arbitrary polygon (reference http://mathworld.wolfram.com/PolygonArea.html)
    4086   \end{funcdesc}
    4087 
    4088   \begin{funcdesc}{plot\_polygons}{polygons, style, figname, verbose = False}
    4089     Module: \code{utilities.polygon}
    4090 
    4091     Plots each polygon contained in input polygon list, e.g.
    4092    \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]}
    4093    etc.  Each polygon can be closed for plotting purposes by assigning the style type to each
    4094    polygon in the list, e.g. \code{style = ['line','line','line']}. The default will be a line
    4095    type when \code{style = None}.
    4096    The subsequent plot will be saved to \code{figname} or defaulted to \code{test_image.png}.
    4097     The function returns a list containing the minimum and maximum of \code{x} and \code{y},
    4098     i.e. \code{[x_{min}, x_{max}, y_{min}, y_{max}]}.
    4099   \end{funcdesc}
     3856\end{funcdesc}
     3857
     3858\begin{funcdesc}{plot\_polygons}{polygons, style, figname, verbose = False}
     3859  Module: \code{utilities.polygon}
     3860
     3861  Plots each polygon contained in input polygon list, e.g.
     3862  \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]}
     3863  etc.  Each polygon can be closed for plotting purposes by assigning the style type to each
     3864  polygon in the list, e.g. \code{style = ['line','line','line']}. The default will be a line
     3865  type when \code{style = None}.
     3866  The subsequent plot will be saved to \code{figname} or defaulted to \code{test_image.png}.
     3867  The function returns a list containing the minimum and maximum of \code{x} and \code{y},
     3868  i.e. \code{[x_{min}, x_{max}, y_{min}, y_{max}]}.
     3869\end{funcdesc}
     3870
    41003871
    41013872\section{coordinate\_transforms}
     3873
    41023874
    41033875\section{geospatial\_data}
     
    41113883%\refmodindex{geospatial_data}
    41123884
    4113 
    4114 
    41153885\begin{classdesc}{Geospatial\_data}
    4116   {data_points = None,
    4117     attributes = None,
    4118     geo_reference = None,
    4119     default_attribute_name = None,
    4120     file_name = None}
    4121 Module: \code{geospatial\_data}
    4122 
    4123 This class is used to store a set of data points and associated
    4124 attributes, allowing these to be manipulated by methods defined for
    4125 the class.
    4126 
    4127 The data points are specified either by reading them from a NetCDF
    4128 or CSV file, identified through the parameter \code{file\_name}, or
    4129 by providing their \code{x}- and \code{y}-coordinates in metres,
    4130 either as a sequence of 2-tuples of floats or as an $M \times 2$
    4131 Numeric array of floats, where $M$ is the number of points.
    4132 Coordinates are interpreted relative to the origin specified by the
    4133 object \code{geo\_reference}, which contains data indicating the UTM
    4134 zone, easting and northing. If \code{geo\_reference} is not
    4135 specified, a default is used.
    4136 
    4137 Attributes are specified through the parameter \code{attributes},
    4138 set either to a list or array of length $M$ or to a dictionary whose
    4139 keys are the attribute names and whose values are lists or arrays of
    4140 length $M$. One of the attributes may be specified as the default
    4141 attribute, by assigning its name to \code{default\_attribute\_name}.
    4142 If no value is specified, the default attribute is taken to be the
    4143 first one.
    4144 
    4145 Note that the Geospatial\_data object currently reads entire datasets
    4146 into memory i.e.\ no memomry blocking takes place.
    4147 For this we refer to the set\_quantity method which will read .pts and .csv files into \anuga using memory blocking allowing large files to be used.
     3886  {data_points=None,
     3887    attributes=None,
     3888    geo_reference=None,
     3889    default_attribute_name=None,
     3890    file_name=None}
     3891  Module: \code{geospatial\_data}
     3892
     3893  This class is used to store a set of data points and associated
     3894  attributes, allowing these to be manipulated by methods defined for
     3895  the class.
     3896
     3897  The data points are specified either by reading them from a NetCDF
     3898  or CSV file, identified through the parameter \code{file\_name}, or
     3899  by providing their \code{x}- and \code{y}-coordinates in metres,
     3900  either as a sequence of 2-tuples of floats or as an $M \times 2$
     3901  numeric array of floats, where $M$ is the number of points.
     3902  Coordinates are interpreted relative to the origin specified by the
     3903  object \code{geo\_reference}, which contains data indicating the UTM
     3904  zone, easting and northing. If \code{geo\_reference} is not
     3905  specified, a default is used.
     3906
     3907  Attributes are specified through the parameter \code{attributes},
     3908  set either to a list or array of length $M$ or to a dictionary whose
     3909  keys are the attribute names and whose values are lists or arrays of
     3910  length $M$. One of the attributes may be specified as the default
     3911  attribute, by assigning its name to \code{default\_attribute\_name}.
     3912  If no value is specified, the default attribute is taken to be the
     3913  first one.
     3914
     3915  Note that the Geospatial\_data object currently reads entire datasets
     3916  into memory i.e.\ no memomry blocking takes place.
     3917  For this we refer to the set\_quantity method which will read .pts and .csv
     3918  files into \anuga using memory blocking allowing large files to be used.
    41483919\end{classdesc}
    41493920
    4150 
    4151 \begin{methoddesc}{import\_points\_file}{delimiter = None, verbose = False}
    4152 
    4153 \end{methoddesc}
    4154 
     3921\begin{methoddesc}{import\_points\_file}{delimiter=None, verbose=False}
     3922
     3923\end{methoddesc}
    41553924
    41563925\begin{methoddesc}{export\_points\_file}{ofile, absolute=False}
     
    41583927\end{methoddesc}
    41593928
    4160 
    4161 \begin{methoddesc}{get\_data\_points}{absolute = True, as\_lat\_long =
    4162     False}
     3929\begin{methoddesc}{get\_data\_points}{absolute=True, as\_lat\_long=False}
    41633930    If \code{as\_lat\_long} is\code{True} the point information
    41643931    returned will be in Latitudes and Longitudes.
    4165 
    4166 \end{methoddesc}
    4167 
     3932\end{methoddesc}
    41683933
    41693934\begin{methoddesc}{set\_attributes}{attributes}
     
    41713936\end{methoddesc}
    41723937
    4173 
    4174 \begin{methoddesc}{get\_attributes}{attribute_name = None}
    4175 
    4176 \end{methoddesc}
    4177 
     3938\begin{methoddesc}{get\_attributes}{attribute_name=None}
     3939
     3940\end{methoddesc}
    41783941
    41793942\begin{methoddesc}{get\_all\_attributes}{}
     
    41813944\end{methoddesc}
    41823945
    4183 
    41843946\begin{methoddesc}{set\_default\_attribute\_name}{default_attribute_name}
    41853947
    41863948\end{methoddesc}
    41873949
    4188 
    41893950\begin{methoddesc}{set\_geo\_reference}{geo_reference}
    41903951
    41913952\end{methoddesc}
    41923953
    4193 
    41943954\begin{methoddesc}{add}{}
    41953955
    41963956\end{methoddesc}
    41973957
    4198 
    41993958\begin{methoddesc}{clip}{}
    4200 Clip geospatial data by a polygon
    4201 
    4202 Inputs are \code{polygon} which is either a list of points, an Nx2 array or
    4203 a Geospatial data object and \code{closed}(optional) which determines
    4204 whether points on boundary should be regarded as belonging to the polygon
    4205 (\code{closed=True}) or not (\code{closed=False}).
    4206 Default is \code{closed=True}.
    4207 
    4208 Returns new Geospatial data object representing points
    4209 inside specified polygon.
    4210 \end{methoddesc}
    4211 
     3959  Clip geospatial data by a polygon
     3960
     3961  Inputs are \code{polygon} which is either a list of points, an Nx2 array or
     3962  a Geospatial data object and \code{closed}(optional) which determines
     3963  whether points on boundary should be regarded as belonging to the polygon
     3964  (\code{closed=True}) or not (\code{closed=False}).
     3965  Default is \code{closed=True}.
     3966
     3967  Returns new Geospatial data object representing points inside specified polygon.
     3968\end{methoddesc}
    42123969
    42133970\begin{methoddesc}{clip_outside}{}
    4214 Clip geospatial data by a polygon
    4215 
    4216 Inputs are \code{polygon} which is either a list of points, an Nx2 array or
    4217 a Geospatial data object and \code{closed}(optional) which determines
    4218 whether points on boundary should be regarded as belonging to the polygon
    4219 (\code{closed=True}) or not (\code{closed=False}).
    4220 Default is \code{closed=True}.
    4221 
    4222 Returns new Geospatial data object representing points
    4223 \emph{out}side specified polygon.
     3971  Clip geospatial data by a polygon
     3972
     3973  Inputs are \code{polygon} which is either a list of points, an Nx2 array or
     3974  a Geospatial data object and \code{closed}(optional) which determines
     3975  whether points on boundary should be regarded as belonging to the polygon
     3976  (\code{closed=True}) or not (\code{closed=False}).
     3977  Default is \code{closed=True}.
     3978
     3979  Returns new Geospatial data object representing points \emph{out}side specified polygon.
    42243980\end{methoddesc}
    42253981
    42263982\begin{methoddesc}{split}{factor=0.5, seed_num=None, verbose=False}
    4227 Returns two geospatial_data object, first is the size of the 'factor'
    4228 smaller the original and the second is the remainder. The two
    4229 new object are disjoin set of each other.
    4230 
    4231 Points of the two new geospatial_data object are selected RANDOMLY.
    4232 
    4233 Input - the (\code{factor}) which to split the object, if 0.1 then 10% of the
    4234 together object will be returned
    4235 
    4236 Output - two geospatial_data objects that are disjoint sets of the original
    4237 \end{methoddesc}
    4238 
    4239 \begin{methoddesc}{find_optimal_smoothing_parameter}{data_file, alpha_list=None, mesh_file=None, boundary_poly=None, mesh_resolution=100000,
    4240 north_boundary=None, south_boundary=None, east_boundary=None, west_boundary=None, plot_name='all_alphas', split_factor=0.1, seed_num=None, cache=False, verbose=False}
    4241 
    4242 Removes a small random sample of points from 'data_file'. Creates
    4243 models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates
    4244 the predicted value to the previously removed point data. Returns the
    4245 alpha value which has the smallest covariance.
    4246 
    4247 data_file: must not contain points outside the boundaries defined
    4248 and it either a pts, txt or csv file.
    4249 
    4250 alpha_list: the alpha values to test in a single list
    4251 
    4252 mesh_file: name of the created mesh file or if passed in will read it.
    4253 NOTE, if there is a mesh file mesh_resolution, north_boundary, south... etc will be ignored.
    4254 
    4255 mesh_resolution: the maximum area size for a triangle
    4256 
    4257 north_boundary... west_boundary: the value of the boundary
    4258 
    4259 plot_name: the name for the plot contain the results
    4260 
    4261 seed_num: the seed to the random number generator
    4262 
    4263 USAGE:
    4264 convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName,
    4265                                              alpha_list=[0.0001, 0.01, 1],
    4266                                              mesh_file=None,
    4267                                              mesh_resolution=3,
    4268                                              north_boundary=5,
    4269                                              south_boundary=-5,
    4270                                              east_boundary=5,
    4271                                              west_boundary=-5,
    4272                                              plot_name='all_alphas',
    4273                                              seed_num=100000,
    4274                                              verbose=False)
    4275 
    4276 OUTPUT: returns the minumum normalised covalance calculate AND the
    4277 alpha that created it. PLUS writes a plot of the results
    4278 
    4279 NOTE: code will not work if the data_file extent is greater than the
    4280 boundary_polygon or any of the boundaries, eg north_boundary...west_boundary
    4281 \end{methoddesc}
    4282 
     3983  Returns two geospatial_data object, first is the size of the 'factor'
     3984  smaller the original and the second is the remainder. The two
     3985  new object are disjoin set of each other.
     3986
     3987  Points of the two new geospatial_data object are selected RANDOMLY.
     3988
     3989  Input -- the (\code{factor}) which to split the object, if 0.1 then 10% of the
     3990  together object will be returned
     3991
     3992  Output -- two geospatial_data objects that are disjoint sets of the original
     3993\end{methoddesc}
     3994
     3995\begin{methoddesc}{find_optimal_smoothing_parameter}{data_file, alpha_list=None,
     3996                   mesh_file=None, boundary_poly=None, mesh_resolution=100000,
     3997                   north_boundary=None, south_boundary=None, east_boundary=None,
     3998                   west_boundary=None, plot_name='all_alphas', split_factor=0.1,
     3999                   seed_num=None, cache=False, verbose=False}
     4000  Removes a small random sample of points from 'data_file'. Creates
     4001  models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates
     4002  the predicted value to the previously removed point data. Returns the
     4003  alpha value which has the smallest covariance.
     4004
     4005  data_file: must not contain points outside the boundaries defined
     4006  and it either a pts, txt or csv file.
     4007
     4008  alpha_list: the alpha values to test in a single list
     4009
     4010  mesh_file: name of the created mesh file or if passed in will read it.
     4011  NOTE, if there is a mesh file mesh_resolution, north_boundary, south... etc will be ignored.
     4012
     4013  mesh_resolution: the maximum area size for a triangle
     4014
     4015  north_boundary... west_boundary: the value of the boundary
     4016
     4017  plot_name: the name for the plot contain the results
     4018
     4019  seed_num: the seed to the random number generator
     4020
     4021  USAGE:
     4022  convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName,
     4023                                               alpha_list=[0.0001, 0.01, 1],
     4024                                               mesh_file=None,
     4025                                               mesh_resolution=3,
     4026                                               north_boundary=5,
     4027                                               south_boundary=-5,
     4028                                               east_boundary=5,
     4029                                               west_boundary=-5,
     4030                                               plot_name='all_alphas',
     4031                                               seed_num=100000,
     4032                                               verbose=False)
     4033
     4034  OUTPUT: returns the minumum normalised covalance calculate AND the
     4035  alpha that created it. PLUS writes a plot of the results
     4036
     4037  NOTE: code will not work if the data_file extent is greater than the
     4038  boundary_polygon or any of the boundaries, eg north_boundary...west_boundary
     4039\end{methoddesc}
    42834040
    42844041
    42854042\section{Graphical Mesh Generator GUI}
    4286 The program \code{graphical\_mesh\_generator.py} in the pmesh module
     4043The program \code{graphical_mesh_generator.py} in the pmesh module
    42874044allows the user to set up the mesh of the problem interactively.
    42884045It can be used to build the outline of a mesh or to visualise a mesh
     
    42994056by pressing the the middle mouse button (scroll bar).
    43004057
     4058
    43014059\section{alpha\_shape}
    43024060\emph{Alpha shapes} are used to generate close-fitting boundaries
    43034061around sets of points. The alpha shape algorithm produces a shape
    4304 that approximates to the `shape formed by the points'---or the shape
     4062that approximates to the 'shape formed by the points' -- or the shape
    43054063that would be seen by viewing the points from a coarse enough
    43064064resolution. For the simplest types of point sets, the alpha shape
     
    43214079with instances of this class.
    43224080
    4323 \begin{classdesc}{Alpha\_Shape}{points, alpha = None}
    4324 Module: \code{alpha\_shape}
    4325 
    4326 To instantiate this class the user supplies the points from which
    4327 the alpha shape is to be created (in the form of a list of 2-tuples
    4328 \code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter
    4329 \code{points}) and, optionally, a value for the parameter
    4330 \code{alpha}. The alpha shape is then computed and the user can then
    4331 retrieve details of the boundary through the attributes defined for
    4332 the class.
     4081\begin{classdesc}{Alpha\_Shape}{points, alpha=None}
     4082  Module: \code{alpha\_shape}
     4083
     4084  To instantiate this class the user supplies the points from which
     4085  the alpha shape is to be created (in the form of a list of 2-tuples
     4086  \code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter
     4087  \code{points}) and, optionally, a value for the parameter
     4088  \code{alpha}. The alpha shape is then computed and the user can then
     4089  retrieve details of the boundary through the attributes defined for
     4090  the class.
    43334091\end{classdesc}
    43344092
    4335 
    4336 \begin{funcdesc}{alpha\_shape\_via\_files}{point_file, boundary_file, alpha= None}
    4337 Module: \code{alpha\_shape}
    4338 
    4339 This function reads points from the specified point file
    4340 \code{point\_file}, computes the associated alpha shape (either
    4341 using the specified value for \code{alpha} or, if no value is
    4342 specified, automatically setting it to an optimal value) and outputs
    4343 the boundary to a file named \code{boundary\_file}. This output file
    4344 lists the coordinates \code{x, y} of each point in the boundary,
    4345 using one line per point.
     4093\begin{funcdesc}{alpha\_shape\_via\_files}{point_file, boundary_file, alpha=None}
     4094  Module: \code{alpha\_shape}
     4095
     4096  This function reads points from the specified point file
     4097  \code{point\_file}, computes the associated alpha shape (either
     4098  using the specified value for \code{alpha} or, if no value is
     4099  specified, automatically setting it to an optimal value) and outputs
     4100  the boundary to a file named \code{boundary\_file}. This output file
     4101  lists the coordinates \code{x, y} of each point in the boundary,
     4102  using one line per point.
    43464103\end{funcdesc}
    4347 
    43484104
    43494105\begin{methoddesc}{set\_boundary\_type}{self,raw_boundary=True,
     
    43524108                          expand_pinch=False,
    43534109                          boundary_points_fraction=0.2}
    4354 Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
    4355 
    4356 This function sets flags that govern the operation of the algorithm
    4357 that computes the boundary, as follows:
    4358 
    4359 \code{raw\_boundary = True} returns raw boundary, i.e. the regular edges of the
    4360                 alpha shape.\\
    4361 \code{remove\_holes = True} removes small holes (`small' is defined by
    4362 \code{boundary\_points\_fraction})\\
    4363 \code{smooth\_indents = True} removes sharp triangular indents in
    4364 boundary\\
    4365 \code{expand\_pinch = True} tests for pinch-off and
    4366 corrects---preventing a boundary vertex from having more than two edges.
    4367 \end{methoddesc}
    4368 
     4110  Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
     4111
     4112  This function sets flags that govern the operation of the algorithm
     4113  that computes the boundary, as follows:
     4114
     4115  \code{raw\_boundary = True} returns raw boundary, i.e. the regular edges of the
     4116                  alpha shape.\\
     4117  \code{remove\_holes = True} removes small holes ('small' is defined by
     4118  \code{boundary\_points\_fraction})\\
     4119  \code{smooth\_indents = True} removes sharp triangular indents in
     4120  boundary\\
     4121  \code{expand\_pinch = True} tests for pinch-off and
     4122  corrects -- preventing a boundary vertex from having more than two edges.
     4123\end{methoddesc}
    43694124
    43704125\begin{methoddesc}{get\_boundary}{}
    4371 Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
    4372 
    4373 Returns a list of tuples representing the boundary of the alpha
    4374 shape. Each tuple represents a segment in the boundary by providing
    4375 the indices of its two endpoints.
    4376 \end{methoddesc}
    4377 
     4126  Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
     4127
     4128  Returns a list of tuples representing the boundary of the alpha
     4129  shape. Each tuple represents a segment in the boundary by providing
     4130  the indices of its two endpoints.
     4131\end{methoddesc}
    43784132
    43794133\begin{methoddesc}{write\_boundary}{file_name}
    4380 Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
    4381 
    4382 Writes the list of 2-tuples returned by \code{get\_boundary} to the
    4383 file \code{file\_name}, using one line per tuple.
    4384 \end{methoddesc}
    4385 
     4134  Module: \code{alpha\_shape},  Class: \class{Alpha\_Shape}
     4135
     4136  Writes the list of 2-tuples returned by \code{get\_boundary} to the
     4137  file \code{file\_name}, using one line per tuple.
     4138\end{methoddesc}
     4139
     4140
     4141\pagebreak
    43864142\section{Numerical Tools}
    43874143
     
    43894145may be found in the module \module{utilities.numerical\_tools}:
    43904146
    4391 \begin{tabular}{|p{8cm} p{8cm}|}  \hline
    4392 \code{angle(v1, v2=None)} & Angle between two-dimensional vectors
    4393 \code{v1} and \code{v2}, or between \code{v1} and the $x$-axis if
    4394 \code{v2} is \code{None}. Value is in range $0$ to $2\pi$. \\
    4395 
    4396 \code{normal\_vector(v)} & Normal vector to \code{v}.\\
    4397 
    4398 \code{mean(x)} & Mean value of a vector \code{x}.\\
    4399 
    4400 \code{cov(x, y=None)} & Covariance of vectors \code{x} and \code{y}.
    4401 If \code{y} is \code{None}, returns \code{cov(x, x)}.\\
    4402 
    4403 \code{err(x, y=0, n=2, relative=True)} & Relative error of
    4404 $\parallel$\code{x}$-$\code{y}$\parallel$ to
    4405 $\parallel$\code{y}$\parallel$ (2-norm if \code{n} = 2 or Max norm
    4406 if \code{n} = \code{None}). If denominator evaluates to zero or if
    4407 \code{y}
    4408 is omitted or if \code{relative = False}, absolute error is returned.\\
    4409 
    4410 \code{norm(x)} & 2-norm of \code{x}.\\
    4411 
    4412 \code{corr(x, y=None)} & Correlation of \code{x} and \code{y}. If
    4413 \code{y} is \code{None} returns autocorrelation of \code{x}.\\
    4414 
    4415 \code{ensure\_numeric(A, typecode = None)} & Returns a Numeric array
    4416 for any sequence \code{A}. If \code{A} is already a Numeric array it
    4417 will be returned unaltered. Otherwise, an attempt is made to convert
    4418 it to a Numeric array. (Needed because \code{array(A)} can
    4419 cause memory overflow.)\\
    4420 
    4421 \code{histogram(a, bins, relative=False)} & Standard histogram. If
    4422 \code{relative} is \code{True}, values will be normalised against
    4423 the total and thus represent frequencies rather than counts.\\
    4424 
    4425 \code{create\_bins(data, number\_of\_bins = None)} & Safely create
    4426 bins for use with histogram. If \code{data} contains only one point
    4427 or is constant, one bin will be created. If \code{number\_of\_bins}
    4428 is omitted, 10 bins will be created.\\  \hline
     4147\begin{tabular}{|p{7.4cm} p{8.6cm}|}
     4148  \hline
     4149  \code{angle(v1, v2=None)} & Angle between two-dimensional vectors
     4150                              \code{v1} and \code{v2}, or between \code{v1} and the $x$-axis if
     4151                              \code{v2} is \code{None}. Value is in range $0$ to $2\pi$. \\
     4152  & \\
     4153  \code{normal\_vector(v)} & Normal vector to \code{v}.\\
     4154  & \\
     4155  \code{mean(x)} & Mean value of a vector \code{x}.\\
     4156  & \\
     4157  \code{cov(x, y=None)} & Covariance of vectors \code{x} and \code{y}.
     4158                          If \code{y} is \code{None}, returns \code{cov(x, x)}.\\
     4159  & \\
     4160  \code{err(x, y=0, n=2, relative=True)} & Relative error of $\parallel$\code{x}$-$\code{y}$\parallel$
     4161                                           to $\parallel$\code{y}$\parallel$ (2-norm if \code{n} = 2 or
     4162                                           Max norm if \code{n} = \code{None}). If denominator evaluates
     4163                                           to zero or if \code{y} is omitted or if \code{relative=False},
     4164                                           absolute error is returned.\\
     4165  & \\
     4166  \code{norm(x)} & 2-norm of \code{x}.\\
     4167  & \\
     4168  \code{corr(x, y=None)} & Correlation of \code{x} and \code{y}. If
     4169                           \code{y} is \code{None} returns autocorrelation of \code{x}.\\
     4170  & \\
     4171  \code{ensure\_numeric(A, typecode=None)} & Returns a numeric array for any sequence \code{A}. If
     4172                                             \code{A} is already a numeric array it will be returned
     4173                                             unaltered. Otherwise, an attempt is made to convert
     4174                                             it to a numeric array. (Needed because \code{array(A)} can
     4175                                             cause memory overflow.)\\
     4176  & \\
     4177  \code{histogram(a, bins, relative=False)} & Standard histogram. If \code{relative} is \code{True},
     4178                                              values will be normalised against the total and thus
     4179                                              represent frequencies rather than counts.\\
     4180  & \\
     4181  \code{create\_bins(data, number\_of\_bins=None)} & Safely create bins for use with histogram.
     4182                                                     If \code{data} contains only one point
     4183                                                     or is constant, one bin will be created.
     4184                                                     If \code{number\_of\_bins} is omitted,
     4185                                                     10 bins will be created.\\
     4186  \hline
     4187\end{tabular}
     4188
    44294189
    44304190\section{Finding the Optimal Alpha Value}
     
    44334193more to come very soon
    44344194
    4435 \end{tabular}
    4436 
     4195%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    44374196
    44384197\chapter{Modules available in \anuga}
     
    44434202\label{mod:generalmesh}
    44444203
     4204
    44454205\section{\module{abstract\_2d\_finite\_volumes.neighbour\_mesh} }
    44464206\declaremodule[neighbourmesh]{}{neighbour\_mesh}
    44474207\label{mod:neighbourmesh}
     4208
    44484209
    44494210\section{\module{abstract\_2d\_finite\_volumes.domain}}
     
    44724233   Otherwise check that it is compatible with dimenions of domain.
    44734234   Otherwise raise an exception
    4474 
    44754235\end{verbatim}
    44764236
    44774237
    4478 
    4479 
    44804238\section{\module{shallow\_water}}
     4239
    448142402D triangular domains for finite-volume
    44824241computations of the shallow water wave equation.
    44834242This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water
    44844243Wave Equation
     4244
    44854245\declaremodule[shallowwater]{}{shallow\_water}
    44864246\label{mod:shallowwater}
    44874247
    4488 
    4489 
    4490 
    44914248%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    44924249
    44934250\chapter{ANUGA Full-scale Validations}
    44944251
     4252
    44954253\section{Overview}
    4496 There are some long-running validations that are not included in the small-scale validations that run when you execute the \module{validate_all.py}
    4497 script in the \module{anuga_validation/automated_validation_test} directory.  These validations are not run automatically
    4498 since they can take a large amount of time and require an internet connection and user input.
     4254
     4255There are some long-running validations that are not included in the small-scale
     4256validations that run when you execute the \module{validate_all.py}
     4257script in the \module{anuga_validation/automated_validation_test} directory.
     4258These validations are not run automatically since they can take a large amount
     4259of time and require an internet connection and user input.
     4260
    44994261
    45004262\section{Patong Beach}
     4263
    45014264The Patong Beach validation is run from the \module{automated_validation_tests/patong_beach_validation}
    4502 directory.  Just execute the \module{validate_patong.py} script in that directory.  This will run a Patong Beach
    4503 simulation and compare the generated SWW file with a known good copy of that file.
    4504 
    4505 The script attempts to refresh the validation data files from master copies held on the Sourceforge
    4506 project site.  If you don't have an internet connection you may still run the validation, as long as you have
    4507 the required files.
    4508 
    4509 You may download the validation data files by hand and then run the validation.  Just go to the ANUGA Sourceforge
    4510 project download page at \module{http://sourceforge.net/project/showfiles.php?group_id=172848} and select the
    4511 \module{validation_data} package, \module{patong-1.0} release.  You need the \module{data.tgz} file and one or more
    4512 of the \module{patong.sww.\{BASIC|TRIAL|FINAL\}.tgz} files.
    4513 
    4514 The BASIC validation is the quickest and the FINAL validation is the slowest.  The \module{validate.py} script
    4515 will use whatever files you have, BASIC first and FINAL last.
     4265directory.  Just execute the \module{validate_patong.py} script in that directory.
     4266This will run a Patong Beach simulation and compare the generated SWW file with a
     4267known good copy of that file.
     4268
     4269The script attempts to refresh the validation data files from master copies held
     4270on the Sourceforge project site.  If you don't have an internet connection you
     4271may still run the validation, as long as you have the required files.
     4272
     4273You may download the validation data files by hand and then run the validation.
     4274Just go to the ANUGA Sourceforge project download page at
     4275\module{http://sourceforge.net/project/showfiles.php?group_id=172848} and select
     4276the \module{validation_data} package, \module{patong-1.0} release.  You need the
     4277\module{data.tgz} file and one or more of the \module{patong.sww.\{BASIC|TRIAL|FINAL\}.tgz}
     4278files.
     4279
     4280The BASIC validation is the quickest and the FINAL validation is the slowest.
     4281The \module{validate.py} script will use whatever files you have, BASIC first and
     4282FINAL last.
    45164283
    45174284%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     
    45194286\chapter{Frequently Asked Questions}
    45204287
    4521 The Frequently Asked Questions have been move to the online FAQ at:
    4522 
     4288The Frequently Asked Questions have been move to the online FAQ at: \\
    45234289\url{https://datamining.anu.edu.au/anuga/wiki/FrequentlyAskedQuestions}
    45244290
     
    45284294
    45294295\begin{tabular}{|lp{10cm}|c|}  \hline
    4530 %\begin{tabular}{|llll|}  \hline
    4531     \emph{Term} & \emph{Definition} & \emph{Page}\\  \hline
    4532 
    4533     \indexedbold{\anuga} & Name of software (joint development between ANU and
    4534     GA) & \pageref{def:anuga}\\
    4535 
    4536     \indexedbold{bathymetry} & offshore elevation &\\
    4537 
    4538     \indexedbold{conserved quantity} & conserved (stage, x and y
    4539     momentum) & \\
    4540 
    4541 %    \indexedbold{domain} & The domain of a function is the set of all input values to the
    4542 %    function.&\\
    4543 
    4544     \indexedbold{Digital Elevation Model (DEM)} & DEMs are digital files consisting of points of elevations,
    4545 sampled systematically at equally spaced intervals.& \\
    4546 
    4547     \indexedbold{Dirichlet boundary} & A boundary condition imposed on a differential equation
    4548  that specifies the values the solution is to take on the boundary of the
    4549  domain. & \pageref{def:dirichlet boundary}\\
    4550 
    4551     \indexedbold{edge} & A triangular cell within the computational mesh can be depicted
    4552     as a set of vertices joined by lines (the edges). & \\
    4553 
    4554     \indexedbold{elevation} & refers to bathymetry and topography &\\
    4555 
    4556     \indexedbold{evolution} & integration of the shallow water wave equations
    4557     over time &\\
    4558 
    4559     \indexedbold{finite volume method} & The method evaluates the terms in the shallow water
    4560     wave equation as fluxes at the surfaces of each finite volume. Because the
    4561     flux entering a given volume is identical to that leaving the adjacent volume,
    4562     these methods are conservative. Another advantage of the finite volume method is
    4563     that it is easily formulated to allow for unstructured meshes. The method is used
    4564     in many computational fluid dynamics packages. & \\
    4565 
    4566     \indexedbold{forcing term} & &\\
    4567 
    4568     \indexedbold{flux} & the amount of flow through the volume per unit
    4569     time & \\
    4570 
    4571     \indexedbold{grid} & Evenly spaced mesh & \\
    4572 
    4573     \indexedbold{latitude} & The angular distance on a mericlear north and south of the
    4574     equator, expressed in degrees and minutes. & \\
    4575 
    4576     \indexedbold{longitude} & The angular distance east or west, between the meridian
    4577     of a particular place on Earth and that of the Prime Meridian (located in Greenwich,
    4578     England) expressed in degrees or time.& \\
    4579 
    4580     \indexedbold{Manning friction coefficient} & &\\
    4581 
    4582     \indexedbold{mesh} & Triangulation of domain &\\
    4583 
    4584     \indexedbold{mesh file} & A TSH or MSH file & \pageref{def:mesh file}\\
    4585 
    4586     \indexedbold{NetCDF} & &\\
    4587 
    4588     \indexedbold{node} & A point at which edges meet & \\
    4589 
    4590     \indexedbold{northing} & A rectangular (x,y) coordinate measurement of distance
    4591     north from a north-south reference line, usually a meridian used as the axis of
    4592     origin within a map zone or projection. Northing is a UTM (Universal Transverse
    4593     Mercator) coordinate. & \\
    4594 
    4595 
    4596     \indexedbold{points file} & A PTS or CSV file & \\  \hline
    4597 
    4598     \end{tabular}
    4599 
    4600     \begin{tabular}{|lp{10cm}|c|}  \hline
    4601 
    4602     \indexedbold{polygon} & A sequence of points in the plane. \anuga represents a polygon
    4603     either as a list consisting of Python tuples or lists of length 2 or as an $N \times 2$
    4604     Numeric array, where $N$ is the number of points.
    4605 
    4606     The unit square, for example, would be represented either as
    4607     \code{[ [0,0], [1,0], [1,1], [0,1] ]} or as \code{array( [0,0], [1,0], [1,1],
    4608     [0,1] )}.
    4609 
    4610     NOTE: For details refer to the module \module{utilities/polygon.py}. &
    4611     \\     \indexedbold{resolution} &  The maximal area of a triangular cell in a
    4612     mesh & \\
    4613 
    4614 
    4615     \indexedbold{reflective boundary} & Models a solid wall. Returns same conserved
    4616     quantities as those present in the neighbouring volume but reflected. Specific to the
    4617     shallow water equation as it works with the momentum quantities assumed to be the
    4618     second and third conserved quantities. & \pageref{def:reflective boundary}\\
    4619 
    4620     \indexedbold{stage} & &\\
    4621 
    4622 %    \indexedbold{try this}
    4623 
    4624     \indexedbold{animate} & visualisation tool used with \anuga &
    4625     \pageref{sec:animate}\\
    4626 
    4627     \indexedbold{time boundary} & Returns values for the conserved
    4628 quantities as a function of time. The user must specify
    4629 the domain to get access to the model time. & \pageref{def:time boundary}\\
    4630 
    4631     \indexedbold{topography} & onshore elevation &\\
    4632 
    4633     \indexedbold{transmissive boundary} & & \pageref{def:transmissive boundary}\\
    4634 
    4635     \indexedbold{vertex} & A point at which edges meet. & \\
    4636 
    4637     \indexedbold{xmomentum} & conserved quantity (note, two-dimensional SWW equations say
    4638     only \code{x} and \code{y} and NOT \code{z}) &\\
    4639 
    4640     \indexedbold{ymomentum}  & conserved quantity & \\  \hline
    4641 
    4642     \end{tabular}
    4643 
     4296  \emph{Term} & \emph{Definition} & \emph{Page}\\
     4297  \hline
     4298  \indexedbold{\anuga} & Name of software (joint development between ANU and GA) & \pageref{def:anuga}\\
     4299  \indexedbold{bathymetry} & offshore elevation & \\
     4300  \indexedbold{conserved quantity} & conserved (stage, x and y momentum) & \\
     4301%  \indexedbold{domain} & The domain of a function is the set of all input values to the function.& \\
     4302  \indexedbold{Digital Elevation Model (DEM)} & DEMs are digital files consisting of points of elevations,
     4303                                                sampled systematically at equally spaced intervals.& \\
     4304  \indexedbold{Dirichlet boundary} & A boundary condition imposed on a differential equation that specifies
     4305                                     the values the solution is to take on the boundary of the domain.
     4306                                   & \pageref{def:dirichlet boundary}\\
     4307  \indexedbold{edge} & A triangular cell within the computational mesh can be depicted
     4308                       as a set of vertices joined by lines (the edges). & \\
     4309  \indexedbold{elevation} & refers to bathymetry and topography & \\
     4310  \indexedbold{evolution} & integration of the shallow water wave equations over time & \\
     4311  \indexedbold{finite volume method} & The method evaluates the terms in the shallow water wave equation as
     4312                                       fluxes at the surfaces of each finite volume. Because the flux entering
     4313                                       a given volume is identical to that leaving the adjacent volume, these
     4314                                       methods are conservative. Another advantage of the finite volume method is
     4315                                       that it is easily formulated to allow for unstructured meshes. The method
     4316                                       is used in many computational fluid dynamics packages. & \\
     4317  \indexedbold{forcing term} & &\\
     4318  \indexedbold{flux} & the amount of flow through the volume per unit time & \\
     4319  \indexedbold{grid} & Evenly spaced mesh & \\
     4320  \indexedbold{latitude} & The angular distance on a mericlear north and south of the equator, expressed in degrees and minutes. & \\
     4321  \indexedbold{longitude} & The angular distance east or west, between the meridian of a particular place on Earth
     4322                            and that of the Prime Meridian (located in Greenwich, England) expressed in degrees or time.& \\
     4323  \indexedbold{Manning friction coefficient} & &\\
     4324  \indexedbold{mesh} & Triangulation of domain &\\
     4325  \indexedbold{mesh file} & A TSH or MSH file & \pageref{def:mesh file}\\
     4326  \indexedbold{NetCDF} & &\\
     4327  \indexedbold{node} & A point at which edges meet & \\
     4328  \indexedbold{northing} & A rectangular (x,y) coordinate measurement of distance north from a north-south
     4329                           reference line, usually a meridian used as the axis of origin within a map zone
     4330                           or projection. Northing is a UTM (Universal Transverse Mercator) coordinate. & \\
     4331  \indexedbold{points file} & A PTS or CSV file & \\
     4332  \hline
     4333\end{tabular}
     4334
     4335\begin{tabular}{|lp{10cm}|c|}
     4336  \hline
     4337  \indexedbold{polygon} & A sequence of points in the plane. \anuga represents a polygon either as a list
     4338                          consisting of Python tuples or lists of length 2 or as an $N \times 2$ numeric array,
     4339                          where $N$ is the number of points.
     4340
     4341                          The unit square, for example, would be represented either as \code{[ [0,0], [1,0], [1,1], [0,1] ]}
     4342                          or as \code{array( [0,0], [1,0], [1,1], [0,1] )}.
     4343
     4344                          NOTE: For details refer to the module \module{utilities/polygon.py}. & \\
     4345  \indexedbold{resolution} &  The maximal area of a triangular cell in a mesh & \\
     4346  \indexedbold{reflective boundary} & Models a solid wall. Returns same conserved quantities as those present in the
     4347                                      neighbouring volume but reflected. Specific to the shallow water equation as
     4348                                      it works with the momentum quantities assumed to be the second and third
     4349                                      conserved quantities. & \pageref{def:reflective boundary}\\
     4350  \indexedbold{stage} & &\\
     4351%  \indexedbold{try this}
     4352  \indexedbold{animate} & visualisation tool used with \anuga & \pageref{sec:animate}\\
     4353  \indexedbold{time boundary} & Returns values for the conserved quantities as a function of time.
     4354                                The user must specify the domain to get access to the model time.
     4355                              & \pageref{def:time boundary}\\
     4356  \indexedbold{topography} & onshore elevation &\\
     4357  \indexedbold{transmissive boundary} & & \pageref{def:transmissive boundary}\\
     4358  \indexedbold{vertex} & A point at which edges meet. & \\
     4359  \indexedbold{xmomentum} & conserved quantity (note, two-dimensional SWW equations say only
     4360                            \code{x} and \code{y} and NOT \code{z}) &\\
     4361  \indexedbold{ymomentum}  & conserved quantity & \\
     4362  \hline
     4363\end{tabular}
    46444364
    46454365%The \code{\e appendix} markup need not be repeated for additional
    46464366%appendices.
    4647 
    46484367
    46494368%
     
    46674386
    46684387
    4669 
    46704388\begin{thebibliography}{99}
     4389%\begin{thebibliography}
    46714390\bibitem[nielsen2005]{nielsen2005}
    46724391{\it Hydrodynamic modelling of coastal inundation}.
     
    47004419\newblock A.~Kurganov, S.~Noelle, and G.~Petrova.
    47014420\newblock {\em SIAM Journal of Scientific Computing}, 23(3):707--740, 2001.
    4702 \end{thebibliography}{99}
     4421\end{thebibliography}
     4422% \end{thebibliography}{99}
    47034423
    47044424\end{document}
Note: See TracChangeset for help on using the changeset viewer.