Changeset 3109


Ignore:
Timestamp:
Jun 7, 2006, 4:58:26 PM (18 years ago)
Author:
howard
Message:

Changes from feedback in group have been implemented

File:
1 edited

Legend:

Unmodified
Added
Removed
  • documentation/user_manual/anuga_user_manual.tex

    r3104 r3109  
    128128\section{Purpose}
    129129
    130 The purpose of this user manual is to introduce the new user to
    131 the software, describe what it can do and give step-by-step
     130The purpose of this user manual is to introduce the new user to the
     131inundation software, describe what it can do and give step-by-step
    132132instructions for setting up and running hydrodynamic simulations.
    133133
     
    201201
    202202This section is designed to assist the reader to get started with
    203 \anuga by working through simple examples. Two examples are discussed;
    204 the first is a simple but artificial example that is useful to illustrate
    205 many of the ideas, and the second is a more realistic example.
     203\anuga by working through some examples. Two examples are discussed;
     204the first is a simple example to illustrate many of the ideas, and
     205the second is a more realistic example.
    206206
    207207\section{A Simple Example}
     
    210210\subsection{Overview}
    211211
    212 What follows is a discussion of the structure and operation of a script which we will call \file{runup.py},
    213 with just enough detail to allow
    214 the reader to appreciate what's involved in setting up a scenario
    215 like the one it depicts.
     212What follows is a discussion of the structure and operation of a
     213script called \file{runup.py}.
    216214
    217215This example carries out the solution of the shallow-water wave
     
    220218constant depth across each line in the perpendicular direction.
    221219
    222 The example demonstrates many of the basic ideas involved in
    223 setting up a more complex scenario. In the general case the user
    224 specifies the geometry (bathymetry and topography), the initial
    225 water level, boundary conditions such as tide, and any forcing
    226 terms that may drive the system such as wind stress or atmospheric
    227 pressure gradients. Frictional resistance from the different
    228 terrains in the model is represented by predefined forcing
    229 terms. The boundary is reflective on three sides and a time dependent wave on one side.
     220The example demonstrates the basic ideas involved in setting up a
     221complex scenario. In general the user specifies the geometry
     222(bathymetry and topography), the initial water level, boundary
     223conditions such as tide, and any forcing terms that may drive the
     224system such as wind stress or atmospheric pressure gradients.
     225Frictional resistance from the different terrains in the model is
     226represented by predefined forcing terms. In this example, the
     227boundary is reflective on three sides and a time dependent wave on
     228one side.
    230229
    231230The present example represents a simple scenario and does not
    232231include any forcing terms, nor is the data taken from a file as it
    233 would be in many typical cases.
     232would typically be.
    234233
    235234The conserved quantities involved in the
     
    319318\end{itemize}
    320319
    321 An example of a general unstructured mesh and the 
     320An example of a general unstructured mesh and the
    322321associated data structures \code{points}, \code{vertices} and \code{boundary}
    323322is given in Section \ref{xxxx}.
    324323
    325324
    326 Since these three variables encapsulate the information needed to
    327 specify the grid, it may be helpful to consider how they look in a
    328 very simple case, not directly related to the example at hand.
     325
     326
     327
     328
     329
     330\subsection{Initialising the Domain}
     331
     332These variables are then used to set up a data structure
     333\code{domain}, through the assignment:
     334
     335{\small \begin{verbatim}
     336    domain = Domain(points, vertices, boundary)
     337\end{verbatim}}
     338
     339This creates an instance of the \class{Domain} class, which
     340represents the domain of the simulation. Specific options for domain
     341are set at this point, including setting the basename for the output
     342file and the directory to be used for data:
     343
     344{\small \begin{verbatim}
     345    domain.set_name('bedslope')
     346\end{verbatim}}
     347
     348{\small \begin{verbatim}
     349    domain.set_datadir('.')
     350\end{verbatim}}
     351
     352In addition, the following statement now specifies that the
     353quantities \code{stage}, \code{xmomentum} and \code{ymomentum} are
     354to be stored:
     355
     356{\small \begin{verbatim}
     357    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
     358    'ymomentum'])
     359\end{verbatim}}
     360
     361
     362\subsection{Initial Conditions}
     363
     364The next task is to specify a number of quantities that we wish to
     365set for each mesh point. The class \class{Domain} has a method
     366\method{set\_quantity}, used to specify these quantities. It is a
     367flexible method that allows the user to set quantities in a variety
     368of ways---using constants, functions, numeric arrays or expressions
     369involving other quantities, arbitrary data points with associated
     370values, all of which can be passed as arguments. All quantities can
     371be initialised using \method{set\_quantity}. For a conserved
     372quantity (such as \code{stage, xmomentum, ymomentum}) this is called
     373an \emph{initial condition}. However, other quantities that aren't
     374updated by the equation are also assigned values using the same
     375interface. The code in the present example demonstrates a number of
     376forms in which we can invoke \method{set\_quantity}.
     377
     378
     379\subsubsection{Elevation}
     380
     381The elevation, or height of the bed, is set using a function,
     382defined through the statements below, which is specific to this
     383example and specifies a particularly simple initial configuration
     384for demonstration purposes:
     385
     386{\small \begin{verbatim}
     387    def f(x,y):
     388        return -x/2
     389\end{verbatim}}
     390
     391This simply associates an elevation with each point \code{(x, y)} of
     392the plane.  It specifies that the bed slopes linearly in the
     393\code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
     394the \code{y} direction.  %[screen shot?]
     395
     396Once the function \function{f} is specified, the quantity
     397\code{elevation} is assigned through the simple statement:
     398
     399{\small \begin{verbatim}
     400    domain.set_quantity('elevation', f)
     401\end{verbatim}}
     402
     403
     404\subsubsection{Friction}
     405
     406The assignment of the friction quantity (a forcing term) demonstrates another way we
     407can use \method{set\_quantity} to set quantities---namely, assign
     408them to a constant numerical value:
     409
     410{\small \begin{verbatim}
     411    domain.set_quantity('friction', 0.1)
     412\end{verbatim}}
     413
     414This just specifies that the Manning friction coefficient is set
     415to 0.1 at every mesh point.
     416
     417\subsubsection{Stage}
     418
     419The stage (the height of the water surface) is related to the
     420elevation and the depth at any time by the equation
     421
     422
     423{\small \begin{verbatim}
     424    stage = elevation + depth
     425\end{verbatim}}
     426
     427
     428For this example, we simply assign a constant value to \code{stage},
     429using the statement
     430
     431{\small \begin{verbatim}
     432    domain.set_quantity('stage', -.4)
     433\end{verbatim}}
     434
     435which specifies that the surface level is set to a height of $-0.4$,
     436i.e. 0.4 units (m) below the zero level.
     437
     438Although it is not necessary for this example, it may be useful to
     439digress here and mention a variant to this requirement, which allows
     440us to illustrate another way to use \method{set\_quantity}---namely,
     441incorporating an expression involving other quantities. Suppose,
     442instead of setting a constant value for the stage, we wished to
     443specify a constant value for the \emph{depth}. For such a case we
     444need to specify that \code{stage} is everywhere obtained by adding
     445that value to the value already specified for \code{elevation}. We
     446would do this by means of the statements:
     447
     448{\small \begin{verbatim}
     449    h = 0.05 # Constant depth
     450    domain.set_quantity('stage', expression = 'elevation + %f' %h)
     451\end{verbatim}}
     452
     453That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus
     454the value of \code{elevation} already defined.
     455
     456The reader will probably appreciate that this capability to
     457incorporate expressions into statements using \method{set\_quantity}
     458greatly expands its power.) See Section \ref{sec:Initial Conditions} for more
     459details.
     460
     461\subsection{Boundary Conditions}
     462
     463The boundary conditions are specified as follows:
     464
     465{\small \begin{verbatim}
     466    Br = Reflective_boundary(domain)
     467
     468    Bt = Transmissive_boundary(domain)
     469
     470    Bd = Dirichlet_boundary([0.2,0.,0.])
     471
     472    Bw = Time_boundary(domain=domain,
     473                f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
     474\end{verbatim}}
     475
     476The effect of these statements is to set up a selection of different
     477alternative boundary conditions and store them in variables that can be
     478assigned as needed. Each boundary condition specifies the
     479behaviour at a boundary in terms of the behaviour in neighbouring
     480elements. The boundary conditions introduced here may be briefly described as
     481follows:
     482
     483\begin{itemize}
     484    \item \textbf{Reflective boundary}\label{def:reflective boundary} Returns same \code{stage} as
     485      as present in its neighbour volume but momentum vector
     486      reversed 180 degrees (reflected).
     487      Specific to the shallow water equation as it works with the
     488      momentum quantities assumed to be the second and third conserved
     489      quantities. A reflective boundary condition models a solid wall.
     490    \item \textbf{Transmissive boundary}\label{def:transmissive boundary} Returns same conserved quantities as
     491      those present in its neighbour volume. This is one way of modelling
     492      outflow from a domain, but it should be used with caution if flow is
     493      not steady state as replication of momentum at the boundary
     494      may cause occasional spurious effects. If this occurs,
     495      consider using e.g. a Dirichlet boundary condition.
     496    \item \textbf{Dirichlet boundary}\label{def:dirichlet boundary} Specifies
     497      constant values for stage, $x$-momentum and $y$-momentum at the boundary.
     498    \item \textbf{Time boundary}\label{def:time boundary} Like a Dirichlet
     499      boundary but with behaviour varying with time.
     500\end{itemize}
     501
     502Before describing how these boundary conditions are assigned, we
     503recall that the variable \code{boundary} returned by
     504\code{rectangular} not only stores the edges of the mesh that
     505constitute the boundary but also assigns to each a symbolic `tag',
     506which indicates whether that edge forms part of the `top' boundary,
     507the `left' boundary, the `bottom' boundary or the `right' boundary.
     508These tags provide the means to assign different boundary conditions
     509to an edge depending on which part of the boundary it belongs to.
     510(Later we shall describe examples in which the boundary is divided
     511differently---we are not limited to the tags `left', `right', `top'
     512and `bottom'.)
     513
     514With boundary objects assigned to variables as described above, we
     515can apply one to each part of the boundary by means of a statement
     516like
     517
     518{\small \begin{verbatim}
     519    domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
     520\end{verbatim}}
     521
     522This statement stipulates that, in the current example, the right
     523boundary varies with time, as defined by the lambda function, while the other
     524boundaries are all reflective.
     525
     526The reader may wish to experiment by varying the choice of boundary
     527types for one or more of the boundaries. (In the case of \code{Bd}
     528and \code{Bw}, the three arguments in each case represent the
     529\code{stage}, $x$-momentum and $y$-momentum, respectively.)
     530
     531{\small \begin{verbatim}
     532    Bw = Time_boundary(domain=domain,
     533                       f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
     534\end{verbatim}}
     535
     536
     537
     538\subsection{Evolution}
     539
     540The final statement \nopagebreak[3]
     541{\small \begin{verbatim}
     542    for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
     543        print domain.timestepping_statistics()
     544\end{verbatim}}
     545
     546causes the configuration of the domain to `evolve', over a series of
     547steps indicated by the values of \code{yieldstep} and
     548\code{duration}, which can be altered as required.  The value of
     549\code{yieldstep} controls the time interval between successive model
     550outputs.  Behind the scenes more time steps are generally taken.
     551
     552
     553\subsection{Output}
     554
     555The output is a NetCDF file with the extension \code{.sww}. It
     556contains stage and momentum information and can be used with the
     557\code{swollen} (see Section \ref{sec:swollen})
     558visualisation package to generate a visual display.
     559See Section \ref{sec:file formats} (page \pageref{sec:file formats})
     560for more on NetCDF and other file formats.
     561
     562
     563\section{How to Run the Code}
     564
     565The code can be run in various ways:
     566
     567\begin{itemize}
     568  \item{from a Windows or Unix command line} as in\ \code{python runup.py}
     569  \item{within the Python IDLE environment}
     570  \item{within emacs}
     571  \item{within Windows, by double-clicking the \code{runup.py}
     572  file.}
     573\end{itemize}
     574
     575
     576\section{Exploring the Model Output}
     577
     578The following figures are screenshots from the \anuga visualisation
     579tool \code{swollen}. Figure \ref{fig:runupstart} shows the domain
     580with water surface as specified by the initial condition, $t=0$.
     581Figure \ref{fig:bedslope2} shows later snapshots for $t=2.3$ and
     582$t=4$ where the system has been evolved and the wave is encroaching
     583on the previously dry bed.  All figures are screenshots from an
     584interactive animation tool called Swollen which is part of \anuga.
     585Swollen is described in more detail is Section \ref{sec:swollen}.
     586
     587\begin{figure}[hbt]
     588
     589  \centerline{\includegraphics[width=75mm, height=75mm]
     590    {examples/runupstart.eps}}
     591
     592  \caption{Bedslope example viewed with Swollen}
     593  \label{fig:runupstart}
     594\end{figure}
     595
     596
     597\begin{figure}[hbt]
     598
     599  \centerline{
     600    \includegraphics[width=75mm, height=75mm]{examples/runupduring.eps}
     601    \includegraphics[width=75mm, height=75mm]{examples/runupend.eps}
     602   }
     603
     604  \caption{Bedslope example viewed with Swollen}
     605  \label{fig:bedslope2}
     606\end{figure}
     607
     608
     609
     610
     611\clearpage
     612
     613%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     614
     615\section{An Example with Real Data}
     616\label{sec:realdataexample} The following discussion builds on the
     617concepts introduced through the \file{runup.py} example and
     618introduces a second example, \file{run\_sydney.py}.  This refers to
     619a real-life scenario, in which the domain of interest surrounds the
     620Sydney region, and predominantly covers Sydney Harbour. A
     621hypothetical tsunami wave is generated by a submarine mass failure
     622situated on the edge of the continental shelf.
     623
     624\subsection{Overview}
     625As in the case of \file{runup.py}, the actions carried
     626out by the program can be organised according to this outline:
     627
     628\begin{enumerate}
     629
     630   \item Set up a triangular mesh.
     631
     632   \item Set certain parameters governing the mode of
     633operation of the model---specifying, for instance, where to store the
     634model output.
     635
     636   \item Input various quantities describing physical measurements, such
     637as the elevation, to be specified at each mesh point (vertex).
     638
     639   \item Set up the boundary conditions.
     640
     641   \item Carry out the evolution of the model through a series of time
     642steps and output the results, providing a results file that can be
     643visualised.
     644
     645\end{enumerate}
     646
     647
     648
     649\subsection{The Code}
     650
     651Here is the code for \file{run\_sydney\_smf.py}:
     652
     653\verbatiminput{examples/runsydney.py}
     654
     655In discussing the details of this example, we follow the outline
     656given above, discussing each major step of the code in turn.
     657
     658\subsection{Establishing the Mesh}
     659
     660One obvious way that the present example differs from
     661\file{runup.py} is in the use of a more complex method to
     662create the mesh. Instead of imposing a mesh structure on a
     663rectangular grid, the technique used for this example involves
     664building mesh structures inside polygons specified by the user,
     665using a mesh-generator referred to as \code{pmesh}.
     666
     667In its simplest form, \code{pmesh} creates the mesh within a single
     668polygon whose vertices are at geographical locations specified by
     669the user. The user specifies the \emph{resolution}---that is, the
     670maximal area of a triangle used for triangulation---and a triangular
     671mesh is created inside the polygon using a mesh generation engine.
     672On any given platform, the same mesh will be returned. Figure
     673\ref{fig:pentagon} shows a simple example of this, in which the
     674triangulation is carried out within a pentagon.
     675
     676
     677\begin{figure}[hbt]
     678
     679  \caption{Mesh points are created inside the polygon}
     680  \label{fig:pentagon}
     681\end{figure}
     682
     683Boundary tags are not restricted to \code{`left'}, \code{`right'},
     684\code{`bottom'} and \code{`top'}, as in the case of
     685\file{runup.py}. Instead the user specifies a list of
     686tags appropriate to the configuration being modelled.
     687
     688In addition, \code{pmesh} provides a way to adapt to geographic or
     689other features in the landscape, whose presence may require an
     690increase in resolution. This is done by allowing the user to specify
     691a number of \emph{interior polygons}, each with a specified
     692resolution, see Figure \ref{fig:interior meshes}. It is also
     693possible to specify one or more `holes'---that is, areas bounded by
     694polygons in which no triangulation is required.
     695
     696\begin{figure}[hbt]
     697
     698
     699
     700  \caption{Interior meshes with individual resolution}
     701  \label{fig:interior meshes}
     702\end{figure}
     703
     704In its general form, \code{pmesh} takes for its input a bounding
     705polygon and (optionally) a list of interior polygons. The user
     706specifies resolutions, both for the bounding polygon and for each of
     707the interior polygons. Given this data, \code{pmesh} first creates a
     708triangular mesh with varying resolution.
     709
     710The function used to implement this process is
     711\function{create\_mesh\_from\_regions}. Its arguments include the
     712bounding polygon and its resolution, a list of boundary tags, and a
     713list of pairs \code{[polygon, resolution]}, specifying the interior
     714polygons and their resolutions.
     715
     716In practice, the details of the polygons used are read from a
     717separate file \file{project.py}. Here is a complete listing of
     718\file{project.py}:
     719
     720\verbatiminput{examples/project.py}
     721
     722The resulting mesh is output to a \emph{mesh file}\index{mesh
     723file}\label{def:mesh file}. This term is used to describe a file of
     724a specific format used to store the data specifying a mesh. (There
     725are in fact two possible formats for such a file: it can either be a
     726binary file, with extension \code{.msh}, or an ASCII file, with
     727extension \code{.tsh}. In the present case, the binary file format
     728\code{.msh} is used. See Section \ref{sec:file formats} (page
     729\pageref{sec:file formats}) for more on file formats.)
     730
     731The statements
     732
     733{\small \begin{verbatim}
     734    interior_res = 5000%
     735    interior_regions = [[project.harbour_polygon_2, interior_res],
     736                    [project.botanybay_polygon_2, interior_res]]
     737\end{verbatim}}
     738
     739are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
     740\code{botanybay\_polygon\_2} from \file{project.py} and assign a
     741common resolution of 5000 to each. The statement
     742
     743{\small \begin{verbatim}
     744    create_mesh_from_regions(project.diffpolygonall,
     745                         boundary_tags= {'bottom': [0],
     746                                         'right1': [1],
     747                                         'right0': [2],
     748                                         'right2': [3],
     749                                         'top': [4],
     750                                         'left1': [5],
     751                                         'left2': [6],
     752                                         'left3': [7]},
     753                         maximum_triangle_area=100000,
     754                         filename=meshname,
     755                         interior_regions=interior_regions)
     756\end{verbatim}}
     757
     758is then used to create the mesh, taking the bounding polygon to be the polygon
     759\code{diffpolygonall} specified in \file{project.py}. The
     760argument \code{boundary\_tags} assigns a dictionary, whose keys are the
     761names of the boundary tags used for the bounding polygon---\code{`bottom'},
     762`right0', `right1', `right2', `top', `left1', `left2' and `left3'---
     763and whose values identify the indices of the segments associated with each of these
     764tags. (The value associated with each boundary tag is a one-element list.)
     765
     766
     767\subsection{Initialising the Domain}
     768
     769As with \file{runup.py}, once we have created the mesh, the next
     770step is to create the data structure \code{domain}. We did this for
     771\file{runup.py} by inputting lists of points and triangles and
     772specifying the boundary tags directly. However, in the present case,
     773we use a method that works directly with the mesh file
     774\code{meshname}, as follows:
     775
     776
     777{\small \begin{verbatim}
     778    domain = Domain(meshname, use_cache=True, verbose=True)
     779\end{verbatim}}
     780
     781Providing a filename instead of the lists used in \file{runup.py}
     782above causes \code{Domain} to convert a mesh file \code{meshname}
     783into an instance of \code{Domain}, allowing us to use methods like
     784\method{set\_quantity} to set quantities and to apply other
     785operations.
     786
     787%(In principle, the
     788%second argument of \function{pmesh\_to\_domain\_instance} can be any
     789%subclass of \class{Domain}, but for applications involving the
     790%shallow-water wave equation, the second argument of
     791%\function{pmesh\_to\_domain\_instance} can always be set simply to
     792%\class{Domain}.)
     793
     794The following statements specify a basename and data directory, and
     795identify quantities to be stored. For the first two, values are
     796taken from \file{project.py}.
     797
     798{\small \begin{verbatim}
     799    domain.set_name(project.basename)
     800    domain.set_datadir(project.outputdir)
     801    domain.set_quantities_to_be_stored(['stage', 'xmomentum',
     802        'ymomentum'])
     803\end{verbatim}}
     804
     805
     806\subsection{Initial Conditions}
     807Quantities for \file{runsydney.py} are set
     808using similar methods to those in \file{runup.py}. However,
     809in this case, many of the values are read from the auxiliary file
     810\file{project.py} or, in the case of \code{elevation}, from an
     811ancillary points file.
     812
     813
     814
     815\subsubsection{Stage}
     816
     817For the scenario we are modelling in this case, we use a callable
     818object \code{tsunami\_source}, assigned by means of a function
     819\function{slump\_tsunami}. This is similar to how we set elevation in
     820\file{runup.py} using a function---however, in this case the
     821function is both more complex and more interesting.
     822
     823The function returns the water displacement for all \code{x} and
     824\code{y} in the domain. The water displacement is a double Gaussian
     825function that depends on the characteristics of the slump (length,
     826thickness, slope, etc), its location (origin) and the depth at that
     827location.
     828
     829
     830\subsubsection{Friction}
     831
     832We assign the friction exactly as we did for \file{runup.py}:
     833
     834{\small \begin{verbatim}
     835    domain.set_quantity('friction', 0.0)
     836\end{verbatim}}
     837
     838
     839\subsubsection{Elevation}
     840
     841The elevation is specified by reading data from a file:
     842
     843{\small \begin{verbatim}
     844    domain.set_quantity('elevation',
     845                        filename = project.combineddemname + '.pts',
     846                        use_cache = True,
     847                        verbose = True)
     848\end{verbatim}}
     849
     850However, before this step can be executed, some preliminary steps
     851are needed to prepare the file from which the data is taken. Two
     852source files are used for this data---their names are specified in
     853the file \file{project.py}, in the variables \code{coarsedemname}
     854and \code{finedemname}. They contain `coarse' and `fine' data,
     855respectively---that is, data sampled at widely spaced points over a
     856large region and data sampled at closely spaced points over a
     857smaller subregion. The data in these files is combined through the
     858statement
     859
     860{\small \begin{verbatim}
     861combine_rectangular_points_files(project.finedemname + '.pts',
     862                                 project.coarsedemname + '.pts',
     863                                 project.combineddemname + '.pts')
     864\end{verbatim}}
     865
     866The effect of this is simply to combine the datasets by eliminating
     867any coarse data associated with points inside the smaller region
     868common to both datasets. The name to be assigned to the resulting
     869dataset is also derived from the name stored in the variable
     870\code{combinedname} in the file \file{project.py}.
     871
     872\subsection{Boundary Conditions}
     873
     874Setting boundaries follows a similar pattern to the one used for
     875\file{runup.py}, except that in this case we need to associate a
     876boundary type with each of the
     877boundary tag names introduced when we established the mesh. In place of the four
     878boundary types introduced for \file{runup.py}, we use the reflective
     879boundary for each of the
     880eight tagged segments defined by \code{create_mesh_from_regions}:
     881
     882{\small \begin{verbatim}
     883    Br = Reflective_boundary(domain)
     884    domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
     885                          'right2': Br, 'top': Br, 'left1': Br,
     886                          'left2': Br, 'left3': Br} )
     887\end{verbatim}}
     888
     889\subsection{Evolution}
     890
     891With the basics established, the running of the `evolve' step is
     892very similar to the corresponding step in \file{runup.py}. Here,
     893the simulation is run for five hours (18000 seconds) with
     894the output stored every two minutes (120 seconds).
     895
     896{\small \begin{verbatim}
     897    import time t0 = time.time()
     898
     899    for t in domain.evolve(yieldstep = 120, duration = 18000):
     900        print domain.timestepping_statistics()
     901        print domain.boundary_statistics(tags = 'bottom')
     902
     903    print 'That took %.2f seconds' %(time.time()
     904\end{verbatim}}
     905
     906%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     907%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     908
     909\chapter{\anuga Public Interface}
     910\label{ch:interface}
     911
     912This chapter gives an overview of the features of \anuga available
     913to the user at the public interface. These are grouped under the
     914following headings, which correspond to the outline of the examples
     915described in Chapter \ref{ch:getstarted}:
     916
     917\begin{itemize}
     918    \item Establishing the Mesh
     919    \item Initialising the Domain
     920    \item Specifying the Quantities
     921    \item Initial Conditions
     922    \item Boundary Conditions
     923    \item Forcing Functions
     924    \item Evolution
     925\end{itemize}
     926
     927The listings are intended merely to give the reader an idea of what
     928each feature is, where to find it and how it can be used---they do
     929not give full specifications; for these the reader
     930may consult the code. The code for every function or class contains
     931a documentation string, or `docstring', that specifies the precise
     932syntax for its use. This appears immediately after the line
     933introducing the code, between two sets of triple quotes.
     934
     935Each listing also describes the location of the module in which
     936the code for the feature being described can be found. All modules
     937are in the folder \file{inundation} or one of its subfolders, and the
     938location of each module is described relative to \file{inundation}. Rather
     939than using pathnames, whose syntax depends on the operating system,
     940we use the format adopted for importing the function or class for
     941use in Python code. For example, suppose we wish to specify that the
     942function \function{create\_mesh\_from\_regions} is in a module called
     943\module{mesh\_interface} in a subfolder of \module{inundation} called
     944\code{pmesh}. In Linux or Unix syntax, the pathname of the file
     945containing the function, relative to \file{inundation}, would be
     946
     947\begin{center}
     948%    \code{pmesh/mesh\_interface.py}
     949    \code{pmesh}$\slash$\code{mesh\_interface.py}
     950\end{center}
     951
     952while in Windows syntax it would be
     953
     954\begin{center}
     955    \code{pmesh}$\backslash$\code{mesh\_interface.py}
     956\end{center}
     957
     958Rather than using either of these forms, in this chapter we specify
     959the location simply as \code{pmesh.mesh\_interface}, in keeping with
     960the usage in the Python statement for importing the function,
     961namely:
     962\begin{center}
     963    \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
     964\end{center}
     965
     966Each listing details the full set of parameters for the class or
     967function; however, the description is generally limited to the most
     968important parameters and the reader is again referred to the code
     969for more details.
     970
     971The following parameters are common to many functions and classes
     972and are omitted from the descriptions given below:
     973
     974%\begin{center}
     975\begin{tabular}{ll}  %\hline
     976%\textbf{Name } & \textbf{Description}\\
     977%\hline
     978\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\\
     979\emph{verbose} & If \code{True}, provides detailed terminal output
     980to the user\\  % \hline
     981\end{tabular}
     982%\end{center}
     983
     984\section{Mesh Generation}
     985
     986Before discussing the part of the interface relating to mesh
     987generation, we begin with a description of a simple example of a
     988mesh and use it to describe how mesh data is stored.
     989
    329990Figure \ref{fig:simplemesh} represents a very simple mesh comprising
    330 just 11 points and three triangles. (To avoid confusion, we should
    331 emphasise that this particular mesh is \emph{not} generated by
    332 \code{rectangular}---it is not even rectangular in nature. )
     991just 11 points and 10 triangles.
    333992
    334993
     
    3461005represent the data displayed in Figure \ref{fig:simplemesh} as
    3471006follows. The list \code{points} stores the coordinates of the
    348 points, and may be displayed schematically as in Table \ref{tab:points}.
     1007points, and may be displayed schematically as in Table
     1008\ref{tab:points}.
    3491009
    3501010
     
    3781038around the triangle. Thus, in the example shown in Figure
    3791039\ref{fig:simplemesh}, the variable \code{vertices} contains the
    380 entries shown in Table \ref{tab:vertices}. The starting point is arbitrary so triangle $(0,1,3)$ is considered the same as $(1,3,0)$ and $(3,0,1)$.
     1040entries shown in Table \ref{tab:vertices}. The starting point is
     1041arbitrary so triangle $(0,1,3)$ is considered the same as $(1,3,0)$
     1042and $(3,0,1)$.
    3811043
    3821044
     
    3981060  \end{center}
    3991061
    400   \caption{Vertices for mesh in
    401     Figure \protect \ref{fig:simplemesh}}
     1062  \caption{Vertices for mesh in Figure \protect \ref{fig:simplemesh}}
    4021063  \label{tab:vertices}
    4031064\end{table}
     
    4061067triangles and associates a tag with each.
    4071068
    408 
    409 
    410 
    411 \subsection{Initialising the Domain}
    412 
    413 These variables are then used to set up a data structure
    414 \code{domain}, through the assignment:
    415 
    416 {\small \begin{verbatim}
    417     domain = Domain(points, vertices, boundary)
    418 \end{verbatim}}
    419 
    420 This uses a Python class \class{Domain}, imported from
    421 \module{shallow\_water}, which is an extension of a more generic
    422 class of the same name in the module \refmodule{pyvolution.domain}
    423 (page \pageref{mod:pyvolution.domain}),
    424 and inherits
    425 some methods from the generic class but has others specific to the
    426 shallow-water scenarios in which it is used. Specific options for
    427 domain are set at this point. One of them is to set the basename for
    428 the output file:
    429 
    430 {\small \begin{verbatim}
    431     domain.set_name('bedslope')
    432 \end{verbatim}}
    433 
    434 
    435 \subsection{Initial Conditions}
    436 
    437 The next task is to specify a number of quantities that we wish to
    438 set for each mesh point. The class \class{Domain} has a method
    439 \method{set\_quantity}, used to specify these quantities. It is a
    440 particularly flexible method that allows the user to set quantities
    441 in a variety of ways---using constants, functions, numeric arrays or
    442 expressions involving other quantities, arbitrary data points with
    443 associated values, all of which can be passed as arguments. All
    444 quantities can be initialised using \method{set\_quantity}. For a
    445 conserved quantity (such as \code{stage, xmomentum, ymomentum}) this
    446 is called an \emph{initial condition}. However, other quantities
    447 that aren't updated by the equation are also assigned values using
    448 the same interface. The code in the present example demonstrates a
    449 number of forms in which we can invoke \method{set\_quantity}.
    450 
    451 
    452 \subsubsection{Elevation}
    453 
    454 The elevation, or height of the bed, is set using a function,
    455 defined through the statements below, which is specific to this
    456 example and specifies a particularly simple initial configuration
    457 for demonstration purposes:
    458 
    459 {\small \begin{verbatim}
    460     def f(x,y):
    461         return -x/2
    462 \end{verbatim}}
    463 
    464 This simply associates an elevation with each point \code{(x, y)} of
    465 the plane.  It specifies that the bed slopes linearly in the
    466 \code{x} direction, with slope $-\frac{1}{2}$,  and is constant in
    467 the \code{y} direction.  %[screen shot?]
    468 
    469 Once the function \function{f} is specified, the quantity
    470 \code{elevation} is assigned through the simple statement:
    471 
    472 {\small \begin{verbatim}
    473     domain.set_quantity('elevation', f)
    474 \end{verbatim}}
    475 
    476 
    477 \subsubsection{Friction}
    478 
    479 The assignment of the friction quantity (a forcing term) demonstrates another way we
    480 can use \method{set\_quantity} to set quantities---namely, assign
    481 them to a constant numerical value:
    482 
    483 {\small \begin{verbatim}
    484     domain.set_quantity('friction', 0.1)
    485 \end{verbatim}}
    486 
    487 This just specifies that the Manning friction coefficient is set
    488 to 0.1 at every mesh point.
    489 
    490 \subsubsection{Stage}
    491 
    492 The stage (the height of the water surface) is related to the
    493 elevation and the depth at any time by the equation
    494 
    495 
    496 {\small \begin{verbatim}
    497     stage = elevation + depth
    498 \end{verbatim}}
    499 
    500 
    501 For this example, we simply assign a constant value to \code{stage},
    502 using the statement
    503 
    504 {\small \begin{verbatim}
    505     domain.set_quantity('stage', -.4)
    506 \end{verbatim}}
    507 
    508 which specifies that the surface level is set to a height of $-0.4$,
    509 i.e. 0.4 units (m) below the zero level.
    510 
    511 Although it is not necessary for this example, it may be useful to
    512 digress here and mention a variant to this requirement, which allows
    513 us to illustrate another way to use \method{set\_quantity}---namely,
    514 incorporating an expression involving other quantities. Suppose,
    515 instead of setting a constant value for the stage, we wished to
    516 specify a constant value for the \emph{depth}. For such a case we
    517 need to specify that \code{stage} is everywhere obtained by adding
    518 that value to the value already specified for \code{elevation}. We
    519 would do this by means of the statements:
    520 
    521 {\small \begin{verbatim}
    522     h = 0.05 # Constant depth
    523     domain.set_quantity('stage', expression = 'elevation + %f' %h)
    524 \end{verbatim}}
    525 
    526 That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus
    527 the value of \code{elevation} already defined.
    528 
    529 The reader will probably appreciate that this capability to
    530 incorporate expressions into statements using \method{set\_quantity}
    531 greatly expands its power.) See Section \ref{sec:Initial Conditions} for more
    532 details.
    533 
    534 \subsection{Boundary Conditions}
    535 
    536 The boundary conditions are specified as follows:
    537 
    538 {\small \begin{verbatim}
    539     Br = Reflective_boundary(domain)
    540 
    541     Bt = Transmissive_boundary(domain)
    542 
    543     Bd = Dirichlet_boundary([0.2,0.,0.])
    544 
    545     Bw = Time_boundary(domain=domain,
    546                 f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
    547 \end{verbatim}}
    548 
    549 The effect of these statements is to set up a selection of different
    550 alternative boundary conditions and store them in variables that can be
    551 assigned as needed. Each boundary condition specifies the
    552 behaviour at a boundary in terms of the behaviour in neighbouring
    553 elements. The boundary conditions introduced here may be briefly described as
    554 follows:
    555 
    556 \begin{itemize}
    557     \item \textbf{Reflective boundary}\label{def:reflective boundary} Returns same \code{stage} as
    558       as present in its neighbour volume but momentum vector
    559       reversed 180 degrees (reflected).
    560       Specific to the shallow water equation as it works with the
    561       momentum quantities assumed to be the second and third conserved
    562       quantities. A reflective boundary condition models a solid wall.
    563     \item \textbf{Transmissive boundary}\label{def:transmissive boundary} Returns same conserved quantities as
    564       those present in its neighbour volume. This is one way of modelling
    565       outflow from a domain, but it should be used with caution if flow is
    566       not steady state as replication of momentum at the boundary
    567       may cause occasional spurious effects. If this occurs,
    568       consider using e.g. a Dirichlet boundary condition.
    569     \item \textbf{[Dirichlet boundary}\label{def:dirichlet boundary} Specifies
    570       constant values for stage, $x$-momentum and $y$-momentum at the boundary.
    571     \item \textbf{Time boundary}\label{def:time boundary} Like a Dirichlet
    572       boundary but with behaviour varying with time.
    573 \end{itemize}
    574 
    575 Once the boundary objects have been specified through the
    576 statements above, they can be applied through a statement of the
    577 form
    578 
    579 {\small \begin{verbatim}
    580     domain.set_boundary({'left': Br, 'right': Bw, 'top': Br, 'bottom': Br})
    581 \end{verbatim}}
    582 
    583 This statement stipulates that, in the current example, the right
    584 boundary varies with time, as defined by the lambda function, while the other
    585 boundaries are all reflective.
    586 
    587 The reader may wish to experiment by varying the choice of boundary
    588 types for one or more of the boundaries. In the case of \code{Bd}
    589 and \code{Bw}, the three arguments in each case represent the
    590 \code{stage}, $x$-momentum and $y$-momentum, respectively.
    591 
    592 {\small \begin{verbatim}
    593     Bw = Time_boundary(domain=domain,
    594                        f=lambda t: [(0.1*sin(t*2*pi)-0.3), 0.0, 0.0])
    595 \end{verbatim}}
    596 
    597 
    598 
    599 \subsection{Evolution}
    600 
    601 The final statement \nopagebreak[3]
    602 {\small \begin{verbatim}
    603     for t in domain.evolve(yieldstep = 0.1, duration = 4.0):
    604         print domain.timestepping_statistics()
    605 \end{verbatim}}
    606 
    607 is the key step that causes the configuration of the domain to
    608 `evolve' in accordance with the model embodied in the code, over a
    609 series of steps indicated by the values of \code{yieldstep} and
    610 \code{duration}, which can be altered as required.  The value of
    611 \code{yieldstep} controls the time interval between successive model
    612 outputs.  Behind the scenes more time steps are generally taken.
    613 
    614 
    615 \subsection{Output}
    616 
    617 %Give details here of the form of the output and explain how it can
    618 %be used with swollen. Include screen shots.//
    619 
    620 The output is a NetCDF file with the extension \code{.sww}. It
    621 contains stage and momentum information and can be used with the
    622 \code{swollen} (see Section \ref{sec:swollen})
    623 visualisation package to generate a visual display.
    624 See Section \ref{sec:file formats} (page \pageref{sec:file formats})
    625 for more on NetCDF and other file formats.
    626 
    627 
    628 \section{How to Run the Code}
    629 
    630 The code can be run in various ways:
    631 
    632 \begin{itemize}
    633   \item{from a Windows or Unix command line} as in\ \code{python runup.py}
    634   \item{within the Python IDLE environment}
    635   \item{within emacs}
    636 \end{itemize}
    637 
    638 
    639 \section{Exploring the Model Output}
    640 
    641 Figure \ref{fig:runupstart} shows the domain with water surface as
    642 specified by the initial condition, $t=0$. Figure
    643 \ref{fig:bedslope2} shows later snapshots for $t=2.3$ and $t=4$
    644 where the system has been evolved and the wave is encroaching on the
    645 previously dry bed.  All figures are screenshots from an interactive
    646 animation tool called Swollen which is part of \anuga. Swollen is
    647 described in more detail is Section \ref{sec:swollen}.
    648 
    649 
    650 
    651 \begin{figure}[hbt]
    652 
    653   \centerline{\includegraphics[width=75mm, height=75mm]
    654     {examples/runupstart.eps}}
    655 
    656   \caption{Bedslope example viewed with Swollen}
    657   \label{fig:runupstart}
    658 \end{figure}
    659 
    660 
    661 \begin{figure}[hbt]
    662 
    663   \centerline{
    664     \includegraphics[width=75mm, height=75mm]{examples/runupduring.eps}
    665     \includegraphics[width=75mm, height=75mm]{examples/runupend.eps}
    666    }
    667 
    668   \caption{Bedslope example viewed with Swollen}
    669   \label{fig:bedslope2}
    670 \end{figure}
    671 
    672 
    673 
    674 
    675 \clearpage
    676 
    677 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    678 
    679 \section{An Example with Real Data}
    680 \label{sec:realdataexample}
    681 The following discussion builds on the concepts introduced through
    682 the \file{runup.py} example and introduces a second
    683 example, \file{run\_sydney.py}, that follows the same basic
    684 outline, but incorporates more complex features and refers to a
    685 real-life scenario, rather than the artificial illustrative one used
    686 in \file{runup.py}. The domain of interest surrounds the
    687 Sydney region, and predominantly covers Sydney Harbour. A
    688 hypothetical tsunami wave is generated by a submarine mass failure
    689 situated on the edge of the continental shelf.
    690 
    691 \subsection{Overview}
    692 As in the case of \file{runup.py}, the actions carried
    693 out by the program can be organised according to this outline:
    694 
    695 \begin{enumerate}
    696 
    697    \item Set up a triangular mesh.
    698 
    699    \item Set certain parameters governing the mode of
    700 operation of the model---specifying, for instance, where to store the
    701 model output.
    702 
    703    \item Input various quantities describing physical measurements, such
    704 as the elevation, to be specified at each mesh point (vertex).
    705 
    706    \item Set up the boundary conditions.
    707 
    708    \item Carry out the evolution of the model through a series of time
    709 steps and outputs the results, providing a results file that can be
    710 visualised.
    711 
    712 \end{enumerate}
    713 
    714 
    715 
    716 \subsection{The Code}
    717 
    718 Here is the code for \file{run\_sydney\_smf.py}:
    719 
    720 %\verbatiminput{"runsydneysmf.py"}
    721 \verbatiminput{examples/runsydney.py}
    722 
    723 In discussing the details of this example, we follow the outline
    724 given above, discussing each major step of the code in turn.
    725 
    726 \subsection{Establishing the Mesh}
    727 
    728 One obvious way that the present example differs from
    729 \file{runup.py} is in the use of a more complex method to
    730 create the mesh. Instead of imposing a mesh structure on a
    731 rectangular grid, the technique used for this example involves
    732 building mesh structures inside polygons specified by the user,
    733 using a mesh-generator referred to as \code{pmesh}.
    734 
    735 The following remarks may help the reader understand how
    736 \code{pmesh} is used.
    737 
    738 In its simplest form, \code{pmesh} creates the mesh within a single
    739 polygon whose vertices are at geographical locations specified by the
    740 user. The user specifies the \emph{resolution}---that is, the maximal
    741 area of a triangle used for triangulation---and mesh points are
    742 created inside the polygon using a mesh generation engine. On any
    743 given platform, the same mesh will be returned. Figure
    744 \ref{fig:pentagon} shows a simple example of this, in which
    745 the triangulation is carried out within a pentagon.
    746 
    747 
    748 \begin{figure}[hbt]
    749 
    750 
    751 
    752   \caption{Mesh points are created inside the polygon}
    753   \label{fig:pentagon}
    754 \end{figure}
    755 
    756 Boundary tags are not restricted to \code{`left'}, \code{`right'},
    757 \code{`bottom'} and \code{`top'}, as in the case of
    758 \file{runup.py}. Instead the user specifies a list of
    759 tags appropriate to the configuration being modelled.
    760 
    761 While a mesh created inside a polygon offers more flexibility than
    762 one based on a rectangular grid, using \code{pmesh} in the limited
    763 form we have described so far still doesn't provide a way to adapt
    764 to geographic or other features in the landscape, whose presence may
    765 require us to vary the resolution in the neighbourhood of the
    766 features. To cope with this requirement, \code{pmesh} also allows
    767 the user to specify a number of \emph{interior polygons}, which are
    768 triangulated separately, each according to a separately specified
    769 resolution, see Figure \ref{fig:interior meshes}. It is also
    770 possible to specify one or more `holes'---that is, areas bounded by
    771 polygons in which no triangulation is required.
    772 
    773 \begin{figure}[hbt]
    774 
    775 
    776 
    777   \caption{Interior meshes with individual resolution}
    778   \label{fig:interior meshes}
    779 \end{figure}
    780 
    781 In its general form, \code{pmesh} takes for its input a bounding
    782 polygon and (optionally) a list of interior polygons. The user
    783 specifies resolutions, both for the bounding polygon and for each of
    784 the interior polygons. Given this data, \code{pmesh} first creates a
    785 triangular mesh inside the bounding polygon, using the specified
    786 resolution, and then creates a separate triangulation inside each of
    787 the interior polygons, using the resolution specified for that
    788 polygon.
    789 
    790 The function used to implement this process is
    791 \function{create\_mesh\_from\_regions}. Its arguments include the
    792 bounding polygon and its resolution, a list of boundary tags, and a
    793 list of pairs \code{[polygon, resolution]}, specifying the interior
    794 polygons and their resolutions.
    795 
    796 In practice, the details of the polygons used are read from a
    797 separate file \file{project.py}. The resulting mesh is output to a
    798 \emph{meshfile}\index{meshfile}\label{def:meshfile}. This term is
    799 used to describe a file of a specific format used to store the data
    800 specifying a mesh. (There are in fact two possible formats for such
    801 a file: it can either be a binary file, with extension \code{.msh},
    802 or an ASCII file, with extension \code{.tsh}. In the present case,
    803 the binary file format \code{.msh} is used. See Section
    804 \ref{sec:file formats} (page \pageref{sec:file formats}) for more on
    805 file formats.) \code{pmesh} assigns a name to the file by appending
    806 the extension \code{.msh} to the name specified in the input file
    807 \file{project.py}. This name is stored in the variable
    808 \code{meshname}.
    809 
    810 The statements
    811 
    812 {\small \begin{verbatim}
    813     interior_res = 5000%
    814     interior_regions = [[project.harbour_polygon_2, interior_res],
    815                     [project.botanybay_polygon_2, interior_res]]
    816 \end{verbatim}}
    817 
    818 are used to read in the specific polygons \code{project.harbour\_polygon\_2} and
    819 \code{botanybay\_polygon\_2} from \file{project.py} and assign a
    820 common resolution of 5000 to each. The statement
    821 
    822 {\small \begin{verbatim}
    823     create_mesh_from_regions(project.diffpolygonall,
    824                          boundary_tags= {'bottom': [0],
    825                                          'right1': [1],
    826                                          'right0': [2],
    827                                          'right2': [3],
    828                                          'top': [4],
    829                                          'left1': [5],
    830                                          'left2': [6],
    831                                          'left3': [7]},
    832                          maximum_triangle_area=100000,
    833                          filename=meshname,
    834                          interior_regions=interior_regions)
    835 \end{verbatim}}
    836 
    837 is then used to create the mesh, taking the bounding polygon to be the polygon
    838 \code{diffpolygonall} specified in \file{project.py}. The
    839 argument \code{boundary\_tags} assigns a dictionary, whose keys are the
    840 names of the boundary tags used for the bounding polygon---\code{`bottom'},
    841 `right0', `right1', `right2', `top', `left1', `left2' and `left3'---
    842 and whose values identify the indices of the segments associated with each of these
    843 tags. (The value associated with each boundary tag is a one-element list.)
    844 
    845 
    846 \subsection{Initialising the Domain}
    847 
    848 As with \file{runup.py}, once we have created the mesh, the next
    849 step is to create the data structure \code{domain}. We did this for
    850 \file{runup.py} by inputting lists of points and triangles and
    851 specifying the boundary tags directly. However, in the present case,
    852 we use a method that works directly with the meshfile
    853 \code{meshname}, as follows:
    854 
    855 
    856 {\small \begin{verbatim}
    857     domain = Domain(meshname, use_cache=True, verbose=True)
    858 \end{verbatim}}
    859 
    860 Providing a filename instead of the lists used in \file{runup.py}
    861 above causes \code{Domain} to convert a meshfile \code{meshname}
    862 into an instance of the data structure \code{domain}, allowing us to
    863 use methods like \method{set\_quantity} to set quantities and to
    864 apply other operations.
    865 
    866 %(In principle, the
    867 %second argument of \function{pmesh\_to\_domain\_instance} can be any
    868 %subclass of \class{Domain}, but for applications involving the
    869 %shallow-water wave equation, the second argument of
    870 %\function{pmesh\_to\_domain\_instance} can always be set simply to
    871 %\class{Domain}.)
    872 
    873 The following statements specify a basename and data directory, and
    874 identify quantities to be stored. For the first two, values are
    875 taken from \file{project.py}.
    876 
    877 {\small \begin{verbatim}
    878     domain.set_name(project.basename)
    879     domain.set_datadir(project.outputdir)
    880     domain.set_quantities_to_be_stored(['stage', 'xmomentum',
    881         'ymomentum'])
    882 \end{verbatim}}
    883 
    884 
    885 \subsection{Initial Conditions}
    886 Quantities for \file{runsydney.py} are set
    887 using similar methods to those in \file{runup.py}. However,
    888 in this case, many of the values are read from the auxiliary file
    889 \file{project.py} or, in the case of \code{elevation}, from an
    890 ancillary points file.
    891 
    892 
    893 
    894 \subsubsection{Stage}
    895 
    896 For the scenario we are modelling in this case, we use a callable
    897 object \code{tsunami\_source}, assigned by means of a function
    898 \function{slump\_tsunami}. This is similar to how we set elevation in
    899 \file{runup.py} using a function---however, in this case the
    900 function is both more complex and more interesting.
    901 
    902 The function returns the water displacement for all \code{x} and
    903 \code{y} in the domain. The water displacement is a double Gaussian
    904 function that depends on the characteristics of the slump (length,
    905 thickness, slope, etc), its location (origin) and the depth at that
    906 location.
    907 
    908 
    909 \subsubsection{Friction}
    910 
    911 We assign the friction exactly as we did for \file{runup.py}:
    912 
    913 {\small \begin{verbatim}
    914     domain.set_quantity('friction', 0.0)
    915 \end{verbatim}}
    916 
    917 
    918 \subsubsection{Elevation}
    919 
    920 The elevation is specified by reading data from a file:
    921 
    922 {\small \begin{verbatim}
    923     domain.set_quantity('elevation',
    924                         filename = project.combineddemname + '.pts',
    925                         use_cache = True,
    926                         verbose = True)
    927 \end{verbatim}}
    928 
    929 However, before this step can be executed, some preliminary steps
    930 are needed to prepare the file from which the data is taken. Two
    931 source files are used for this data---their names are specified in
    932 the file \file{project.py}, in the variables \code{coarsedemname}
    933 and \code{finedemname}. They contain `coarse' and `fine' data,
    934 respectively---that is, data sampled at widely spaced points over a
    935 large region and data sampled at closely spaced points over a
    936 smaller subregion. The data in these files is combined through the
    937 statement
    938 
    939 {\small \begin{verbatim}
    940 combine_rectangular_points_files(project.finedemname + '.pts',
    941                                  project.coarsedemname + '.pts',
    942                                  project.combineddemname + '.pts')
    943 \end{verbatim}}
    944 
    945 The effect of this is simply to combine the datasets by eliminating
    946 any coarse data associated with points inside the smaller region
    947 common to both datasets. The name to be assigned to the resulting
    948 dataset is also derived from the name stored in the variable
    949 \code{combinedname} in the file \file{project.py}.
    950 
    951 \subsection{Boundary Conditions}
    952 
    953 Setting boundaries follows a similar pattern to the one used for
    954 \file{runup.py}, except that in this case we need to associate a
    955 boundary type with each of the
    956 boundary tag names introduced when we established the mesh. In place of the four
    957 boundary types introduced for \file{runup.py}, we use the reflective
    958 boundary for each of the
    959 eight tagged segments defined by \code{create_mesh_from_regions}:
    960 
    961 {\small \begin{verbatim}
    962     Br = Reflective_boundary(domain)
    963     domain.set_boundary( {'bottom': Br, 'right1': Br, 'right0': Br,
    964                           'right2': Br, 'top': Br, 'left1': Br,
    965                           'left2': Br, 'left3': Br} )
    966 \end{verbatim}}
    967 
    968 \subsection{Evolution}
    969 
    970 With the basics established, the running of the `evolve' step is
    971 very similar to the corresponding step in \file{runup.py}. Here,
    972 the simulation is run for five hours (18000 seconds) with
    973 the output stored every two minutes (120 seconds).
    974 
    975 {\small \begin{verbatim}
    976     import time t0 = time.time()
    977 
    978     for t in domain.evolve(yieldstep = 120, duration = 18000):
    979         print domain.timestepping_statistics()
    980         print domain.boundary_statistics(tags = 'bottom')
    981 
    982     print 'That took %.2f seconds' %(time.time()
    983 \end{verbatim}}
    984 
    985 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    986 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    987 
    988 \chapter{\anuga Public Interface}
    989 \label{ch:interface}
    990 
    991 This chapter gives an overview of the features of \anuga available
    992 to the user at the public interface. These are grouped under the
    993 following headings and follows the outline of the examples described
    994 earlier:
    995 
    996 \begin{itemize}
    997     \item Establishing the Mesh
    998     \item Initialising the Domain
    999     \item Specifying the Quantities
    1000     \item Initial Conditions
    1001     \item Boundary Conditions
    1002     \item Forcing Functions
    1003     \item Evolution
    1004 \end{itemize}
    1005 
    1006 The listings are intended merely to give the reader an idea of what
    1007 each feature is, where to find it and how it can be used---they do
    1008 not give full specifications; for these the reader
    1009 may consult the code. The code for every function or class contains
    1010 a documentation string, or `docstring', that specifies the precise
    1011 syntax for its use. This appears immediately after the line
    1012 introducing the code, between two sets of triple quotes.
    1013 
    1014 Each listing also describes the location of the module in which
    1015 the code for the feature being described can be found. All modules
    1016 are in the folder \file{inundation} or one of its subfolders, and the
    1017 location of each module is described relative to \file{inundation}. Rather
    1018 than using pathnames, whose syntax depends on the operating system,
    1019 we use the format adopted for importing the function or class for
    1020 use in Python code. For example, suppose we wish to specify that the
    1021 function \function{create\_mesh\_from\_regions} is in a module called
    1022 \module{mesh\_interface} in a subfolder of \module{inundation} called
    1023 \code{pmesh}. In Linux or Unix syntax, the pathname of the file
    1024 containing the function, relative to \file{inundation}, would be
    1025 
    1026 \begin{center}
    1027 %    \code{pmesh/mesh\_interface.py}
    1028     \code{pmesh}$\slash$\code{mesh\_interface.py}
    1029 \end{center}
    1030 
    1031 while in Windows syntax it would be
    1032 
    1033 \begin{center}
    1034     \code{pmesh}$\backslash$\code{mesh\_interface.py}
    1035 \end{center}
    1036 
    1037 Rather than using either of these forms, in this chapter we specify
    1038 the location simply as \code{pmesh.mesh\_interface}, in keeping with
    1039 the usage in the Python statement for importing the function,
    1040 namely:
    1041 \begin{center}
    1042     \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions}
    1043 \end{center}
    1044 
    1045 Each listing details the full set of parameters for the class or
    1046 function; however, the description is generally limited to the most
    1047 important parameters and the reader is again referred to the code
    1048 for more details.
    1049 
    1050 The following parameters are common to many functions and classes
    1051 and are omitted from the descriptions given below:
    1052 
    1053 %\begin{center}
    1054 \begin{tabular}{ll}  %\hline
    1055 %\textbf{Name } & \textbf{Description}\\
    1056 %\hline
    1057 \emph{use\_cache} & Specifies whether caching is to be used for improved performance. See Section \ref{sec:caching} for details on the underlying caching functionality\\
    1058 \emph{verbose} & If \code{True}, provides detailed terminal output
    1059 to the user\\  % \hline
    1060 \end{tabular}
    1061 %\end{center}
    1062 
    1063 \section{Mesh Generation}
    10641069\refmodindex[pmesh.meshinterface]{pmesh.mesh\_interface}\label{sec:meshgeneration}
    1065 
    1066 \begin{classdesc}  {Mesh}{userSegments=None,
    1067                  userVertices=None,
    1068                  holes=None,
    1069                  regions=None,
    1070                  geo_reference=None}
    1071 Module: \module{pmesh.mesh}
    1072 
    1073 A class used to store a representation of a two-dimensional
    1074 triangular mesh. The user may initialise the class by specifying
    1075 lists of segments and/or vertices, using the parameters
    1076 \code{userSegments} and \code{userVertices}, and may also specify
    1077 lists of regions and/or holes, using the parameters \code{regions}
    1078 and \code{holes}.
    1079 \end{classdesc}
    10801070
    10811071\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
     
    10911081This function allows a user to initiate the automatic creation of a
    10921082mesh inside a specified polygon (input \code{bounding_polygon}).
    1093 Among the parameters that can be
    1094 set are the \emph{resolution} (maximal area for any triangle in the
    1095 mesh) and the minimal angle allowable in any triangle. The user can
    1096 specify a number of internal polygons within each of which a
    1097 separate mesh is to be created, generally with a smaller resolution.
    1098 \code{interior_regions} is a paired list containing the interior
    1099 polygon and its resolution.
     1083Among the parameters that can be set are the \emph{resolution}
     1084(maximal area for any triangle in the mesh) and the minimal angle
     1085allowable in any triangle. The user can specify a number of internal
     1086polygons within each of which a separate mesh is to be created,
     1087generally with a smaller resolution. \code{interior_regions} is a
     1088paired list containing the interior polygon and its resolution.
    11001089Additionally, the user specifies a list of boundary tags, one for
    11011090each edge of the bounding polygon.
     
    11031092
    11041093
    1105 \begin{funcdesc} {add\_region}{}
    1106 
    1107 \end{funcdesc}
    1108 
    1109 \begin{funcdesc} {add\_hole}{}
    1110 
    1111 \end{funcdesc}
    1112 
    1113 
    1114 \begin{funcdesc}  {add\_region\_from\_polygon}{self, polygon, tags=None,
     1094
     1095
     1096\begin{classdesc}  {Mesh}{userSegments=None,
     1097                 userVertices=None,
     1098                 holes=None,
     1099                 regions=None,
     1100                 geo_reference=None}
     1101Module: \module{pmesh.mesh}
     1102
     1103A class used to store a representation of a two-dimensional
     1104triangular mesh. The user may initialise the class by specifying
     1105lists of segments and/or vertices, using the parameters
     1106\code{userSegments} and \code{userVertices}, and may also specify
     1107lists of regions and/or holes, using the parameters \code{regions}
     1108and \code{holes}.
     1109\end{classdesc}
     1110
     1111
     1112\subsection{Key Methods of Class Mesh}
     1113
     1114\begin{methoddesc} {add\_region}{}
     1115
     1116\end{methoddesc}
     1117
     1118\begin{methoddesc} {add\_hole}{}
     1119
     1120\end{methoddesc}
     1121
     1122
     1123\begin{methoddesc}  {add\_region\_from\_polygon}{self, polygon, tags=None,
    11151124                                max_triangle_area=None, geo_reference=None}
    11161125Module: \module{pmesh.mesh}  Class: \class{Mesh}
    11171126
    1118 % Translate following into layman's language
    11191127This method is used to add a region to a \class{Mesh} instance.  The
    11201128region is described by the input \code{polygon}.  Additionally, the
     
    11221130bounding polygon.
    11231131
    1124 
    1125 \end{funcdesc}
    1126 
    1127 \begin{funcdesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None,
     1132\end{methoddesc}
     1133
     1134
     1135\begin{methoddesc}  {add\_hole\_from\_polygon}{self, polygon, tags=None,
    11281136    geo_reference=None}
    1129 Module: \module{pmesh.mesh.Mesh}
     1137Module: \module{pmesh.mesh}  Class: \class{Mesh}
    11301138
    11311139% Translate following into layman's language
    1132 This method is used to add a `hole' wihtin a region ---that is, to define a
    1133 interior region where the
    1134 triangular mesh will not be generated---to a \class{Mesh} instance.
    1135 The region is described by the polygon passed in.  Additionally, the
    1136 user specifies a list of boundary tags, one for each edge of the
    1137 bounding polygon.
    1138 \end{funcdesc}
    1139 
    1140 \begin{funcdesc}  {generate\_mesh}{self,
     1140This method is used to add a `hole' within a region ---that is, to
     1141define a interior region where the triangular mesh will not be
     1142generated---to a \class{Mesh} instance. The region is described by
     1143the polygon passed in.  Additionally, the user specifies a list of
     1144boundary tags, one for each edge of the bounding polygon.
     1145\end{methoddesc}
     1146
     1147\begin{methoddesc}  {generate\_mesh}{self,
    11411148                      maximum_triangle_area=None,
    11421149                      minimum_triangle_angle=28.0,
    11431150                      verbose=False}
    1144 Module: \module{pmesh.mesh.Mesh}
     1151Module: \module{pmesh.mesh}  Class: \class{Mesh}
    11451152
    11461153% Translate following into layman's language
     
    11481155area of any triangle in the mesh can be specified, along with the
    11491156minimum angle in any triangle.
    1150 \end{funcdesc}
    1151 
    1152 
    1153 \begin{funcdesc}  {export\_mesh_file}{self,ofile}
    1154 Module: \module{pmesh.mesh.Mesh}
     1157\end{methoddesc}
     1158
     1159
     1160\begin{methoddesc}  {export\_mesh_file}{self,ofile}
     1161Module: \module{pmesh.mesh}  Class: \class{Mesh}
    11551162
    11561163% Translate following into layman's language
     
    11591166the extension \code{.msh} for the file to be in NetCDF format and
    11601167\code{.tsh} for the file to be ASCII format.
    1161 \end{funcdesc}
    1162 
    1163 
    1164 \begin{funcdesc}  {import_ungenerate_file}{self,ofile, tag=None}
    1165 Module: \module{pmesh.mesh.Mesh}
     1168\end{methoddesc}
     1169
     1170
     1171\begin{methoddesc}  {import_ungenerate_file}{self,ofile, tag=None}
     1172Module: \module{pmesh.mesh}  Class: \class{Mesh}
    11661173
    11671174% Translate following into layman's language
    1168 This method is used to import a polygon file in the ungenerate format,
    1169 which is used by arcGIS. The polygons are converted to vertices and segments.\code{ofile} is the
    1170 name of the polygon file.  \code{tag} is the tag given to all
    1171 the polygons segments.
     1175This method is used to import a polygon file in the ungenerate
     1176format, which is used by arcGIS. The polygons are converted to
     1177vertices and segments. \code{ofile} is the name of the polygon file.
     1178\code{tag} is the tag given to all the polygon's segments.
    11721179
    11731180This function can be used to import building footprints.
    1174 \end{funcdesc}
     1181\end{methoddesc}
    11751182
    11761183%%%%%%
     
    12011208This class is used to create an instance of a data structure used to
    12021209store and manipulate data associated with a mesh. The mesh is
    1203 specified either by assigning the name of a meshfile to
     1210specified either by assigning the name of a mesh file to
    12041211\code{source} or by
    12051212\end{classdesc}
     
    12271234\subsection{Key Methods of Domain}
    12281235
    1229 \begin{funcdesc} {set\_name}{name}
     1236\begin{methoddesc} {set\_name}{name}
    12301237    Module: \refmodule{pyvolution.domain}, page \pageref{mod:pyvolution.domain}  %\code{pyvolution.domain}
    12311238
    12321239    Assigns the name \code{name} to the domain.
    1233 \end{funcdesc}
    1234 
    1235 \begin{funcdesc} {get\_name}{}
     1240\end{methoddesc}
     1241
     1242\begin{methoddesc} {get\_name}{}
    12361243    Module: \module{pyvolution.domain}
    12371244
    12381245    Returns the name assigned to the domain by \code{set\_name}. If no name has been
    12391246    assigned, returns \code{`domain'}.
    1240 \end{funcdesc}
    1241 
    1242 \begin{funcdesc} {set\_datadir}{name}
     1247\end{methoddesc}
     1248
     1249\begin{methoddesc} {set\_datadir}{name}
    12431250    Module: \module{pyvolution.domain}
    12441251
     
    12611268        domain.set_datadir{'project' + os.sep + 'data'}
    12621269    \end{verbatim}}
    1263 \end{funcdesc}
    1264 
    1265 \begin{funcdesc} {get\_datadir}{}
     1270\end{methoddesc}
     1271
     1272\begin{methoddesc} {get\_datadir}{}
    12661273    Module: \module{pyvolution.domain}
    12671274
     
    12701277    been run, returns the value \code{default\_datadir} specified in
    12711278    \code{config.py}.
    1272 \end{funcdesc}
    1273 
    1274 \begin{funcdesc} {set\_time}{time=0.0}
     1279\end{methoddesc}
     1280
     1281\begin{methoddesc} {set\_time}{time=0.0}
    12751282    Module: \module{pyvolution.domain}
    12761283
    12771284    Sets the initial time, in seconds, for the simulation. The
    12781285    default is 0.0.
    1279 \end{funcdesc}
    1280 
    1281 \begin{funcdesc} {set\_default\_order}{n}
     1286\end{methoddesc}
     1287
     1288\begin{methoddesc} {set\_default\_order}{n}
    12821289    Sets the default (spatial) order to the value specified by
    12831290    \code{n}, which must be either 1 or 2. (Assigning any other value
    12841291    to \code{n} will cause an error.)
    1285 \end{funcdesc}
     1292\end{methoddesc}
    12861293
    12871294
     
    13001307condition setting; it can be used at any time throughout the simulation.
    13011308
    1302 \begin{funcdesc}{set\_quantity}{name,
     1309\begin{methoddesc}{set\_quantity}{name,
    13031310    numeric = None,
    13041311    quantity = None,
     
    13541361
    13551362
    1356 \end{funcdesc}
     1363\end{methoddesc}
    13571364
    13581365
     
    14691476to assign boundary conditions according to the tags used to label boundary segments.
    14701477
    1471 \begin{funcdesc}{set\_boundary}{boundary_map}
     1478\begin{methoddesc}{set\_boundary}{boundary_map}
    14721479Module: \module{pyvolution.domain}
    14731480
     
    14791486and whose keys are the symbolic tags.
    14801487
    1481 \end{funcdesc}
    1482 
    1483 \begin{funcdesc} {get\_boundary\_tags}{}
     1488\end{methoddesc}
     1489
     1490\begin{methoddesc} {get\_boundary\_tags}{}
    14841491Module: \module{pyvolution.mesh}
    14851492
    14861493Returns a list of the available boundary tags.
    1487 \end{funcdesc}
     1494\end{methoddesc}
    14881495
    14891496%%%
     
    15501557The underlying domain must be specified when boundary is instantiated
    15511558
    1552 This type of boundary is useful when stage is known at the boundary as a 
     1559This type of boundary is useful when stage is known at the boundary as a
    15531560function of time, but momenta (or speeds) aren't.
    15541561
     
    15851592\section{Evolution}
    15861593
    1587   \begin{funcdesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
     1594  \begin{methoddesc}{evolve}{yieldstep = None, finaltime = None, duration = None, skip_initial_step = False}
    15881595
    15891596  Module: \module{pyvolution.domain}
     
    16091616  \end{verbatim}}
    16101617
    1611   \end{funcdesc}
     1618  \end{methoddesc}
    16121619
    16131620
     
    16181625  \begin{funcdesc}{statistics}{}
    16191626  Module: \module{pyvolution.domain}
    1620  
     1627
    16211628  \end{funcdesc}
    1622    
     1629
    16231630  \begin{funcdesc}{timestepping\_statistics}{}
    16241631  Module: \module{pyvolution.domain}
     
    18271834
    18281835
    1829 \subsection{Meshfile Formats}
    1830 
    1831 A meshfile is a file that has a specific format suited to specifying
    1832 mesh data for \anuga. A meshfile can have one of two formats: it can
    1833 be either a TSH file, which is an ASCII file, or an MSH file, which
    1834 is a NetCDF file. A meshfile can be generated from the function
    1835 \function{create\_mesh\_from\_regions} (see Section
     1836\subsection{Mesh File Formats}
     1837
     1838A mesh file is a file that has a specific format suited to
     1839specifying mesh data for \anuga. A mesh file can have one of two
     1840formats: it can be either a TSH file, which is an ASCII file, or an
     1841MSH file, which is a NetCDF file. A mesh file can be generated from
     1842the function \function{create\_mesh\_from\_regions} (see Section
    18361843\ref{sec:meshgeneration}) and used to initialise a domain.
    18371844
    1838 A meshfile describes the outline of the mesh---the vertices and line
    1839 segments that enclose the region in which the mesh is created---and
    1840 the triangular mesh itself, which is specified by listing the
    1841 triangles and their vertices, and the segments, which are those
    1842 sides of the triangles that are associated with boundary conditions.
    1843 
    1844 In addition, a meshfile may contain `holes' and/or `regions'. A hole
    1845 or region is defined by specifying a point and a number of segments
    1846 that enclose that point. A hole represents an area where no mesh is
    1847 to be created, while a region is a labelled area used for defining
    1848 properties of a mesh, such as friction values.
    1849 
    1850 A meshfile can also contain a georeference, which describes an
     1845A mesh file describes the outline of the mesh---the vertices and
     1846line segments that enclose the region in which the mesh is
     1847created---and the triangular mesh itself, which is specified by
     1848listing the triangles and their vertices, and the segments, which
     1849are those sides of the triangles that are associated with boundary
     1850conditions.
     1851
     1852In addition, a mesh file may contain `holes' and/or `regions'. A
     1853hole or region is defined by specifying a point and a number of
     1854segments that enclose that point. A hole represents an area where no
     1855mesh is to be created, while a region is a labelled area used for
     1856defining properties of a mesh, such as friction values.
     1857
     1858A mesh file can also contain a georeference, which describes an
    18511859offset to be applied to $x$ and $y$ values---eg to the vertices.
    18521860
     
    20632071  detected by examining the functions \code{bytecode (co\_code, co\_consts,
    20642072  func\_defaults, co\_argcount)} and the function will be recomputed.
    2065   However, caching will not detect changes in modules used by \code{func}. 
     2073  However, caching will not detect changes in modules used by \code{func}.
    20662074  In this case cache must be cleared manually.
    20672075
     
    23352343
    23362344
    2337 \begin{funcdesc}{import\_points\_file}{delimiter = None, verbose = False}
    2338 
    2339 \end{funcdesc}
    2340 
    2341 
    2342 \begin{funcdesc}{export\_points\_file}{ofile, absolute=False}
    2343 
    2344 \end{funcdesc}
    2345 
    2346 
    2347 \begin{funcdesc}{get\_data\_points}{absolute = True}
    2348 
    2349 \end{funcdesc}
    2350 
    2351 
    2352 \begin{funcdesc}{set\_attributes}{attributes}
    2353 
    2354 \end{funcdesc}
    2355 
    2356 
    2357 \begin{funcdesc}{get\_attributes}{attribute_name = None}
    2358 
    2359 \end{funcdesc}
    2360 
    2361 
    2362 \begin{funcdesc}{get\_all\_attributes}{}
    2363 
    2364 \end{funcdesc}
    2365 
    2366 
    2367 \begin{funcdesc}{set\_default\_attribute\_name}{default_attribute_name}
    2368 
    2369 \end{funcdesc}
    2370 
    2371 
    2372 \begin{funcdesc}{set\_geo\_reference}{geo_reference}
    2373 
    2374 \end{funcdesc}
    2375 
    2376 
    2377 \begin{funcdesc}{add}{}
    2378 
    2379 \end{funcdesc}
     2345\begin{methoddesc}{import\_points\_file}{delimiter = None, verbose = False}
     2346
     2347\end{methoddesc}
     2348
     2349
     2350\begin{methoddesc}{export\_points\_file}{ofile, absolute=False}
     2351
     2352\end{methoddesc}
     2353
     2354
     2355\begin{methoddesc}{get\_data\_points}{absolute = True}
     2356
     2357\end{methoddesc}
     2358
     2359
     2360\begin{methoddesc}{set\_attributes}{attributes}
     2361
     2362\end{methoddesc}
     2363
     2364
     2365\begin{methoddesc}{get\_attributes}{attribute_name = None}
     2366
     2367\end{methoddesc}
     2368
     2369
     2370\begin{methoddesc}{get\_all\_attributes}{}
     2371
     2372\end{methoddesc}
     2373
     2374
     2375\begin{methoddesc}{set\_default\_attribute\_name}{default_attribute_name}
     2376
     2377\end{methoddesc}
     2378
     2379
     2380\begin{methoddesc}{set\_geo\_reference}{geo_reference}
     2381
     2382\end{methoddesc}
     2383
     2384
     2385\begin{methoddesc}{add}{}
     2386
     2387\end{methoddesc}
    23802388
    23812389
     
    23832391
    23842392\section{alpha\_shape}
    2385 An \emph{alpha shape} is a shape created from a set of points in the
    2386 plane, according to an algorithm. This shape is intended to capture
    2387 the intuitive notion of the `shape formed by the points'. For a
    2388 sufficiently simple set, the alpha shape reduces to the more precise
    2389 notion of the convex hull, but in general an alpha shape can be much
    2390 much more complex and may be far from convex.
    2391 
    2392 In the context of \anuga, an alpha shape is used to fit a polygonal
    2393 boundary around a set of points when fitting a mesh to a region. The
    2394 algorithm uses a parameter $\alpha$ that can be adjusted to make the
    2395 resultant shape resemble the shape suggested by intuition more
    2396 closely.
     2393\emph{Alpha shapes} are used to generate close-fitting boundaries
     2394around sets of points. The alpha shape algorithm produces a shape
     2395that approximates to the `shape formed by the points'---or the shape
     2396that would be seen by viewing the points from a coarse enough
     2397resolution. For the simplest types of point sets, the alpha shape
     2398reduces to the more precise notion of the convex hull. However, for
     2399many sets of points the convex hull does not provide a close fit and
     2400the alpha shape usually fits more closely to the original point set,
     2401offering a better approximation to the shape being sought.
     2402
     2403In \anuga, an alpha shape is used to generate a polygonal boundary
     2404around a set of points before mesh generation. The algorithm uses a
     2405parameter $\alpha$ that can be adjusted to make the resultant shape
     2406resemble the shape suggested by intuition more closely. An alpha
     2407shape can serve as an initial boundary approximation that the user
     2408can adjust as needed.
    23972409
    23982410The following paragraphs describe the class used to model an alpha
    2399 shape and some of the more important methods and attributes
    2400 associated with instances of this class.
     2411shape and some of the important methods and attributes associated
     2412with instances of this class.
    24012413
    24022414\begin{classdesc}{Alpha\_Shape}{points, alpha = None}
     
    24072419\code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter
    24082420\code{points}) and, optionally, a value for the parameter
    2409 \code{alpha}. The alpha shape is then computed and details of the
    2410 required boundary may be retrieved as attributes of the class
    2411 instance.
     2421\code{alpha}. The alpha shape is then computed and the user can then
     2422retrieve details of the boundary through the attributes defined for
     2423the class.
    24122424\end{classdesc}
    24132425
     
    24162428Module: \code{alpha\_shape}
    24172429
    2418 This function reads points from the specified file
     2430This function reads points from the specified point file
    24192431\code{point\_file}, computes the associated alpha shape (either
    24202432using the specified value for \code{alpha} or, if no value is
    2421 specified, automatically setting it to a value judged to be optimal)
    2422 and outputs the boundary to a file named \code{boundary\_file}. This
    2423 output file lists the coordinates \code{x, y} of each point in the
    2424 boundary, using one line per point.
     2433specified, automatically setting it to an optimal value) and outputs
     2434the boundary to a file named \code{boundary\_file}. This output file
     2435lists the coordinates \code{x, y} of each point in the boundary,
     2436using one line per point.
    24252437\end{funcdesc}
    24262438
    24272439
    2428 \begin{funcdesc}{set\_boundary\_type}{self,raw_boundary=True,
     2440\begin{methoddesc}{set\_boundary\_type}{self,raw_boundary=True,
    24292441                          remove_holes=False,
    24302442                          smooth_indents=False,
    24312443                          expand_pinch=False,
    24322444                          boundary_points_fraction=0.2}
    2433 Module: \code{alpha\_shape}
     2445Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
    24342446
    24352447This function sets flags that govern the operation of the algorithm
    24362448that computes the boundary, as follows:
    24372449
    2438         Set \code{raw\_boundary = True} to return raw boundary, i.e. the regular edges of the
    2439                         alpha shape.\\
    2440         Set \code{remove\_holes = True} to remove small holes
    2441                         (`small' is defined by
    2442                         \code{boundary\_points\_fraction})\\
    2443         Set \code{smooth\_indents = True} to remove sharp triangular indents in
    2444         boundary\\
    2445         Set \code{expand\_pinch = True} to test for pinch-off and
    2446         correct, i.e. to prevent a boundary vertex having more than two edges.
    2447 \end{funcdesc}
     2450\code{raw\_boundary = True} returns raw boundary, i.e. the regular edges of the
     2451                alpha shape.\\
     2452\code{remove\_holes = True} removes small holes (`small' is defined by
     2453\code{boundary\_points\_fraction})\\
     2454\code{smooth\_indents = True} removes sharp triangular indents in
     2455boundary\\
     2456\code{expand\_pinch = True} tests for pinch-off and
     2457corrects---preventing a boundary vertex from having more than two edges.
     2458\end{methoddesc}
     2459
     2460
     2461\begin{methoddesc}{get\_boundary}{}
     2462Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
     2463
     2464Returns a list of tuples representing the boundary of the alpha
     2465shape. Each tuple represents a segment in the boundary by providing
     2466the indices of its two endpoints.
     2467\end{methoddesc}
     2468
     2469
     2470\begin{methoddesc}{write\_boundary}{file_name}
     2471Module: \code{alpha\_shape}  Class: \class{Alpha\_Shape}
     2472
     2473Writes the list of 2-tuples returned by \code{get\_boundary} to the
     2474file \code{file\_name}, using one line per tuple.
     2475\end{methoddesc}
    24482476
    24492477\section{Numerical Tools}
     
    25322560
    25332561
    2534 \section{\module{pyvolution.shallow\_water} --- 2D triangular domains for finite-volume computations of the shallow water wave equation. This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water Wave Equation
     2562\section{\module{pyvolution.shallow\_water} --- 2D triangular domains for finite-volume
     2563computations of the shallow water wave equation. This module contains a specialisation
     2564of class Domain from module domain.py consisting of methods specific to the Shallow Water
     2565Wave Equation
    25352566}
    25362567\declaremodule[pyvolution.shallowwater]{}{pyvolution.shallow\_water}
     
    25822613\subsubsection{Why does a file\_function return a list of numbers when evaluated?}
    25832614Currently, file\_function works by returning values for the conserved
    2584 quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the triplet returned by file\_function.
     2615quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time
     2616and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the
     2617triplet returned by file\_function.
    25852618
    25862619\subsubsection{Which diagnostics are available to troubleshoot a simulation?}
     
    26822715    \indexedbold{mesh} & Triangulation of domain &\\
    26832716
    2684     \indexedbold{meshfile} & A TSH or MSH file & \pageref{def:meshfile}\\
     2717    \indexedbold{mesh file} & A TSH or MSH file & \pageref{def:mesh file}\\
    26852718
    26862719    \indexedbold{NetCDF} & &\\
Note: See TracChangeset for help on using the changeset viewer.