[2329] | 1 | % Complete documentation on the extended LaTeX markup used for Python |
---|
| 2 | % documentation is available in ``Documenting Python'', which is part |
---|
| 3 | % of the standard documentation for Python. It may be found online |
---|
| 4 | % at: |
---|
| 5 | % |
---|
| 6 | % http://www.python.org/doc/current/doc/doc.html |
---|
| 7 | |
---|
| 8 | |
---|
[2384] | 9 | \input{definitions} |
---|
| 10 | |
---|
[2422] | 11 | |
---|
[2329] | 12 | \documentclass{manual} |
---|
[2274] | 13 | |
---|
[2384] | 14 | \title{\anuga User Manual} |
---|
[2284] | 15 | \author{Howard Silcock, Ole Nielsen, Duncan Gray, Jane Sexton} |
---|
[2274] | 16 | |
---|
[2329] | 17 | % Please at least include a long-lived email address; |
---|
| 18 | % the rest is at your discretion. |
---|
| 19 | \authoraddress{Geoscience Australia \\ |
---|
| 20 | Email: \email{ole.nielsen@ga.gov.au} |
---|
| 21 | } |
---|
| 22 | |
---|
[2377] | 23 | %Draft date |
---|
| 24 | \date{\today} % update before release! |
---|
[2422] | 25 | % Use an explicit date so that reformatting |
---|
| 26 | % doesn't cause a new date to be used. Setting |
---|
| 27 | % the date to \today can be used during draft |
---|
| 28 | % stages to make it easier to handle versions. |
---|
[2329] | 29 | |
---|
[2422] | 30 | \release{1.0} % release version; this is used to define the |
---|
| 31 | % \version macro |
---|
[2329] | 32 | |
---|
[2422] | 33 | \makeindex % tell \index to actually write the .idx file |
---|
| 34 | %\makemodindex % If this contains a lot of module sections. |
---|
[2329] | 35 | |
---|
| 36 | |
---|
| 37 | |
---|
[2274] | 38 | \begin{document} |
---|
| 39 | \maketitle |
---|
| 40 | |
---|
[2329] | 41 | % This makes the contents more accessible from the front page of the HTML. |
---|
| 42 | \ifhtml |
---|
| 43 | \chapter*{Front Matter\label{front}} |
---|
| 44 | \fi |
---|
[2285] | 45 | |
---|
| 46 | %Subversion keywords: |
---|
| 47 | % |
---|
[2387] | 48 | %$LastChangedDate: 2006-02-16 09:29:56 +0000 (Thu, 16 Feb 2006) $ |
---|
| 49 | %$LastChangedRevision: 2422 $ |
---|
| 50 | %$LastChangedBy: steve $ |
---|
[2285] | 51 | |
---|
[2383] | 52 | \input{copyright} |
---|
[2274] | 53 | |
---|
[2383] | 54 | |
---|
[2329] | 55 | \begin{abstract} |
---|
| 56 | |
---|
| 57 | \noindent |
---|
[2384] | 58 | \anuga\index{AnuGA} is a hydrodynamic modelling tool that |
---|
[2358] | 59 | allows users to model realistic flow problems in complex |
---|
| 60 | geometries. Examples include dam breaks or the effects of natural |
---|
| 61 | hazards such as riverine flooding, storm surges and tsunami. |
---|
[2274] | 62 | |
---|
[2283] | 63 | The user must specify a study area represented by a mesh of triangular |
---|
| 64 | cells, the topography and bathymetry, frictional resistance, initial |
---|
[2422] | 65 | values for water level (called \emph{stage}\index{stage} within \anuga), |
---|
[2329] | 66 | boundary |
---|
[2283] | 67 | conditions and forces such as windstress or pressure gradients if |
---|
| 68 | applicable. |
---|
| 69 | |
---|
[2384] | 70 | \anuga tracks the evolution of water depth and horizontal momentum |
---|
[2283] | 71 | within each cell over time by solving the shallow water wave equation |
---|
| 72 | governing equation using a finite-volume method. |
---|
| 73 | |
---|
[2384] | 74 | \anuga cannot model details of breaking waves, flow under ceilings such |
---|
[2283] | 75 | as pipes, turbulence and vortices, vertical convection or viscous |
---|
| 76 | flows. |
---|
| 77 | |
---|
[2384] | 78 | \anuga also incorporates a mesh generator, called \code{pmesh}, that |
---|
[2283] | 79 | allows the user to set up the geometry of the problem interactively as |
---|
| 80 | well as tools for interpolation and surface fitting, and a number of |
---|
| 81 | auxiliary tools for visualising and interrogating the model output. |
---|
| 82 | |
---|
[2384] | 83 | Most \anuga components are written in the object-oriented programming |
---|
[2283] | 84 | language Python and most users will interact with Anuga by writing |
---|
[2384] | 85 | small Python programs based on the \anuga library |
---|
[2283] | 86 | functions. Computationally intensive components are written for |
---|
| 87 | efficiency in C routines working directly with the Numerical Python |
---|
| 88 | structures. |
---|
| 89 | |
---|
| 90 | |
---|
[2329] | 91 | \end{abstract} |
---|
[2283] | 92 | |
---|
[2329] | 93 | \tableofcontents |
---|
[2283] | 94 | |
---|
[2274] | 95 | |
---|
[2329] | 96 | \chapter{Introduction} |
---|
| 97 | |
---|
| 98 | |
---|
| 99 | \section{Purpose} |
---|
| 100 | |
---|
[2274] | 101 | The purpose of this user manual is to introduce the new user to |
---|
| 102 | the software, describe what it can do and give step-by-step |
---|
| 103 | instructions for setting up, configuring and running the software. |
---|
| 104 | |
---|
[2329] | 105 | \section{Scope} |
---|
[2274] | 106 | |
---|
| 107 | This manual covers only what is needed to operate the software |
---|
| 108 | after installation. It does not includes instructions for |
---|
| 109 | installing the software or detailed API documentation, both of |
---|
| 110 | which will be covered in separate publications. |
---|
| 111 | |
---|
[2329] | 112 | \section{Audience} |
---|
[2274] | 113 | |
---|
[2283] | 114 | Readers are assumed to be familiar with the operating environment |
---|
[2274] | 115 | and have a general understanding of the problem background, as |
---|
| 116 | well as enough programming experience to adapt the code to |
---|
| 117 | different requirements, as described in this manual, and to |
---|
| 118 | understand the basic terminology of object-oriented programming. |
---|
| 119 | |
---|
[2329] | 120 | \section{Structure of This Manual} |
---|
[2274] | 121 | |
---|
| 122 | This manual is structured as follows: |
---|
| 123 | |
---|
| 124 | \begin{itemize} |
---|
[2384] | 125 | \item Background (What \anuga does) |
---|
[2283] | 126 | \item A \emph{Getting Started} section |
---|
| 127 | \item Anuga's overall architecture, components and file formats |
---|
[2284] | 128 | \item Detailed descriptions of the user interface |
---|
[2274] | 129 | \end{itemize} |
---|
| 130 | |
---|
| 131 | |
---|
[2329] | 132 | \pagebreak |
---|
| 133 | \chapter{Getting Started} |
---|
[2274] | 134 | |
---|
| 135 | This section is designed to assist the reader to get started with |
---|
[2384] | 136 | \anuga by working through a simple example. What follows |
---|
[2274] | 137 | is a discussion of the structure and operation of the file |
---|
[2358] | 138 | \code{bedslope.py}, with just enough detail to allow the reader |
---|
[2274] | 139 | to appreciate what's involved in setting up a scenario like the |
---|
| 140 | one it depicts. |
---|
| 141 | |
---|
[2329] | 142 | \section{Overview} |
---|
[2274] | 143 | |
---|
| 144 | This example carries out the solution of the shallow-water wave |
---|
| 145 | equation in the simple case of a configuration comprising a flat |
---|
| 146 | bed, sloping at a fixed angle in one direction and having a |
---|
[2283] | 147 | constant depth across each line in the perpendicular direction. |
---|
| 148 | |
---|
[2274] | 149 | The example demonstrates many of the basic ideas involved in |
---|
| 150 | setting up a more complex scenario. In the general case the user |
---|
| 151 | specifies the geometry (bathymetry and topography), the initial |
---|
| 152 | water level, boundary conditions such as tide, and any forcing |
---|
| 153 | terms that may drive the system such as wind stress or atmospheric |
---|
| 154 | pressure gradients. Frictional resistance from the different |
---|
| 155 | terrains in the model is represented by predefined forcing |
---|
[2283] | 156 | terms. The boundary is reflective on three sides and a time dependent wave on one side. |
---|
| 157 | |
---|
[2274] | 158 | The present example, as it represents a simple scenario, does not |
---|
| 159 | include any forcing term, nor is the data taken from a file as it |
---|
| 160 | would be in many typical cases. The quantities involved in the |
---|
| 161 | present problem are: |
---|
| 162 | \begin{itemize} |
---|
[2329] | 163 | \item elevation\index{elevation} |
---|
| 164 | \item friction\index{friction} |
---|
| 165 | \item depth\index{depth} |
---|
| 166 | \item stage\index{stage} |
---|
[2274] | 167 | \end{itemize} |
---|
| 168 | |
---|
| 169 | %\emph{[More details of the problem background]} |
---|
| 170 | |
---|
[2329] | 171 | \section{Outline of the Program} |
---|
[2274] | 172 | |
---|
[2358] | 173 | In outline, \code{bedslope.py} performs the following steps: |
---|
[2274] | 174 | |
---|
| 175 | \begin{enumerate} |
---|
| 176 | |
---|
| 177 | \item Sets up a triangular mesh. |
---|
| 178 | |
---|
| 179 | \item Sets certain parameters governing the mode of |
---|
[2283] | 180 | operation of the model-specifying, for instance, where to store the model output. |
---|
[2274] | 181 | |
---|
[2283] | 182 | |
---|
[2274] | 183 | \item Inputs various quantities describing physical measurements, such |
---|
[2283] | 184 | as the elevation, to be specified at each mesh point (vertex). |
---|
[2274] | 185 | |
---|
| 186 | \item Sets up the boundary conditions. |
---|
| 187 | |
---|
| 188 | \item Carries out the evolution of the model through a series of time |
---|
| 189 | steps and outputs the results, providing a results file that can |
---|
| 190 | be visualised. |
---|
| 191 | |
---|
| 192 | \end{enumerate} |
---|
| 193 | |
---|
[2329] | 194 | \section{The Code} |
---|
[2274] | 195 | |
---|
[2422] | 196 | %FIXME: we are using the \code function here. |
---|
[2358] | 197 | %This should be used whereever possible |
---|
[2274] | 198 | For reference we include below the complete code listing for |
---|
[2329] | 199 | \code{bedslope.py}. Subsequent paragraphs provide a `commentary' |
---|
[2283] | 200 | that describes each step of the program and explains it significance. |
---|
[2274] | 201 | |
---|
[2283] | 202 | |
---|
[2277] | 203 | {\scriptsize \begin{verbatim} |
---|
| 204 | from pyvolution.mesh_factory import rectangular |
---|
[2274] | 205 | from pyvolution.shallow_water import Domain, Reflective_boundary, |
---|
| 206 | Dirichlet_boundary, Time_boundary, Transmissive_boundary |
---|
| 207 | |
---|
| 208 | #Create basic mesh |
---|
| 209 | points, vertices, boundary = rectangular(10,10) |
---|
| 210 | |
---|
[2277] | 211 | #Create shallow water domain |
---|
| 212 | domain = Domain(points, vertices,boundary) |
---|
[2289] | 213 | domain.set_name('bedslope') |
---|
[2274] | 214 | |
---|
[2289] | 215 | |
---|
[2274] | 216 | ####################### |
---|
| 217 | # Initial conditions |
---|
| 218 | def f(x,y): |
---|
| 219 | return -x/2 |
---|
| 220 | |
---|
| 221 | domain.set_quantity('elevation', f) |
---|
| 222 | domain.set_quantity('friction', 0.1) |
---|
| 223 | |
---|
| 224 | h = 0.05 # Constant depth |
---|
| 225 | domain.set_quantity('stage', expression = 'elevation + %f' %h) |
---|
| 226 | |
---|
| 227 | |
---|
[2277] | 228 | # Boundary conditions |
---|
| 229 | from math import sin, pi |
---|
| 230 | Br = Reflective_boundary(domain) |
---|
[2422] | 231 | Bt = Transmissive_boundary(domain) |
---|
[2277] | 232 | Bd = Dirichlet_boundary([0.2,0.,0.]) |
---|
[2274] | 233 | |
---|
| 234 | Bw = Time_boundary(domain=domain, |
---|
| 235 | f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0]) |
---|
| 236 | |
---|
| 237 | |
---|
[2277] | 238 | domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br}) |
---|
[2274] | 239 | |
---|
| 240 | |
---|
[2277] | 241 | ###################### |
---|
[2274] | 242 | #Evolution |
---|
| 243 | |
---|
| 244 | domain.check_integrity() |
---|
| 245 | |
---|
| 246 | for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0): |
---|
| 247 | domain.write_time() |
---|
| 248 | |
---|
| 249 | |
---|
[2277] | 250 | \end{verbatim}} |
---|
[2274] | 251 | |
---|
| 252 | |
---|
[2329] | 253 | \section{Establishing the Mesh} |
---|
[2274] | 254 | |
---|
| 255 | The first task is to set up the triangular mesh to be used for the |
---|
| 256 | scenario. This is carried out through the statement: |
---|
| 257 | |
---|
[2277] | 258 | {\small \begin{verbatim} |
---|
[2422] | 259 | points, vertices, boundary = rectangular(10, 10) |
---|
[2277] | 260 | \end{verbatim}} |
---|
[2274] | 261 | |
---|
[2358] | 262 | The function \code{rectangular} is imported from a module |
---|
[2384] | 263 | \code{mesh\_factory} defined elsewhere. \anuga also |
---|
[2274] | 264 | contains several other schemes that can be used for setting up |
---|
| 265 | meshes, but we shall not discuss these now.) The above assignment |
---|
| 266 | sets up a $10 \times 10$ rectangular mesh, triangulated in a |
---|
| 267 | specific way. In general, the assignment |
---|
| 268 | |
---|
[2277] | 269 | {\small \begin{verbatim} |
---|
[2274] | 270 | points, vertices, boundary = rectangular(m, n) |
---|
[2277] | 271 | \end{verbatim}} |
---|
[2274] | 272 | |
---|
| 273 | returns: |
---|
| 274 | |
---|
| 275 | \begin{itemize} |
---|
| 276 | |
---|
[2358] | 277 | \item a list \code{points} of length $N$, where $N = (m + 1)(n + 1)$, |
---|
[2274] | 278 | comprising the coordinates $(x, y)$ of each of the $N$ mesh |
---|
| 279 | points, |
---|
| 280 | |
---|
[2358] | 281 | \item a list \code{vertices} of length $2mn$ (each entry specifies the three |
---|
[2274] | 282 | vertices of one of the triangles used in the triangulation) , and |
---|
| 283 | |
---|
[2358] | 284 | \item a dictionary \code{boundary}, used to tag the triangle edges on |
---|
[2274] | 285 | the boundaries. Each key corresponds to a triangle edge on one of |
---|
[2358] | 286 | the four boundaries and its value is one of \code{`left'}, |
---|
| 287 | \code{`right'}, \code{`top'} and \code{`bottom'}, indicating |
---|
[2274] | 288 | which boundary the edge in question belongs to. |
---|
| 289 | |
---|
| 290 | \end{itemize} |
---|
| 291 | |
---|
| 292 | |
---|
[2329] | 293 | \section{Initialising the domain} |
---|
[2274] | 294 | |
---|
| 295 | These variables are then used to set up a data structure |
---|
[2358] | 296 | \code{domain}, through the assignment: |
---|
[2274] | 297 | |
---|
[2277] | 298 | {\small \begin{verbatim} |
---|
[2274] | 299 | domain = Domain(points, vertices, boundary) |
---|
[2277] | 300 | \end{verbatim}} |
---|
[2274] | 301 | |
---|
[2358] | 302 | This uses a Python class \code{Domain}, imported from |
---|
| 303 | \code{shallow\_water}, which is an extension of a more generic |
---|
| 304 | class of the same name in the module \code{domain}, and inherits |
---|
[2274] | 305 | some methods from the generic class but has others specific to the |
---|
[2422] | 306 | shallow-water scenarios in which it is used. Specific options for domain |
---|
[2289] | 307 | are set at this point. One of them are to set the basename for the output file |
---|
[2274] | 308 | |
---|
[2277] | 309 | {\scriptsize \begin{verbatim} |
---|
[2289] | 310 | domain.set_name('bedslope') |
---|
[2277] | 311 | \end{verbatim}} |
---|
[2274] | 312 | |
---|
| 313 | |
---|
[2329] | 314 | \section{Specifying the Quantities} |
---|
[2274] | 315 | |
---|
[2283] | 316 | The next task is to specify a number of quantities that we wish to set |
---|
[2358] | 317 | for each mesh point. The class \code{Domain} has a method |
---|
| 318 | \code{set\_quantity}, used to specify these quantities. It is a |
---|
[2283] | 319 | particularly flexible method that allows the user to set quantities in |
---|
| 320 | a variety of ways---using constants, functions, numeric arrays or |
---|
| 321 | expressions involving other quantities, arbitrary data points with |
---|
| 322 | associated values, all of which can be passed as arguments. All |
---|
[2358] | 323 | quantities can be initialised using \code{set\_quantity}. For |
---|
| 324 | conserved quantities (\code{stage, xmomentum, ymomentum}) this is |
---|
[2283] | 325 | called the \emph{initial condition}, for other quantities that aren't |
---|
| 326 | updated by the equation, the same interface is used to assign their |
---|
| 327 | values. The code in the present example demonstrates a number of forms |
---|
[2358] | 328 | in which we can invoke \code{set\_quantity}. |
---|
[2274] | 329 | |
---|
| 330 | |
---|
[2329] | 331 | \subsection{Elevation} |
---|
[2274] | 332 | |
---|
| 333 | The elevation is set using a function, defined through the |
---|
| 334 | statements below, which is specific to this example and specifies |
---|
| 335 | a particularly simple initial configuration for demonstration |
---|
| 336 | purposes: |
---|
| 337 | |
---|
[2277] | 338 | {\small \begin{verbatim} |
---|
[2274] | 339 | def f(x,y): |
---|
| 340 | return -x/2 |
---|
[2277] | 341 | \end{verbatim}} |
---|
[2274] | 342 | |
---|
| 343 | This simply associates an elevation with each point $(x, y)$ of |
---|
| 344 | the plane. It specifies that the bed slopes linearly in the $x$ |
---|
| 345 | direction, with slope $-\frac{1}{2}$, and is constant in the $y$ |
---|
| 346 | direction.\\ %[screen shot?] |
---|
| 347 | \\ |
---|
| 348 | Once the function $f$ is specified, the quantity |
---|
[2358] | 349 | \code{elevation} is assigned through the simple statement: |
---|
[2274] | 350 | |
---|
[2277] | 351 | {\small \begin{verbatim} |
---|
[2274] | 352 | domain.set_quantity('elevation', f) |
---|
[2277] | 353 | \end{verbatim}} |
---|
[2274] | 354 | |
---|
| 355 | |
---|
[2329] | 356 | \subsection{Friction} |
---|
[2274] | 357 | |
---|
| 358 | The assignment of the friction quantity demonstrates another way |
---|
[2358] | 359 | we can use \code{set\_quantity} to set quantities---namely, |
---|
[2274] | 360 | assign them to a constant numerical value: |
---|
| 361 | |
---|
[2277] | 362 | {\small \begin{verbatim} |
---|
[2274] | 363 | domain.set_quantity('friction', 0.1) |
---|
[2277] | 364 | \end{verbatim}} |
---|
[2274] | 365 | |
---|
| 366 | This just specifies that the Manning friction coefficient is set |
---|
| 367 | to 0.1 at every mesh point. |
---|
| 368 | |
---|
[2329] | 369 | \subsection{Depth} |
---|
[2274] | 370 | |
---|
| 371 | Assigning depth illustrates a more complex way to use |
---|
[2358] | 372 | \code{set\_quantity}, introducing an expression involving other |
---|
[2274] | 373 | quantities: |
---|
| 374 | |
---|
[2277] | 375 | {\small \begin{verbatim} |
---|
[2274] | 376 | h = 0.05 \# Constant depth |
---|
| 377 | domain.set_quantity('stage', expression = 'elevation + %f' %h) |
---|
[2277] | 378 | \end{verbatim}} |
---|
[2274] | 379 | |
---|
[2358] | 380 | Here the quantity \code{stage} is defined by taking the quantity |
---|
[2274] | 381 | elevation already defined and adding a constant value $h = 0.05$ |
---|
| 382 | to it everywhere. This expresses the fact that the water depth is |
---|
| 383 | everywhere constant, so the surface is a constant height above the |
---|
| 384 | elevation of the bed. |
---|
| 385 | |
---|
[2329] | 386 | \subsection{Boundary Conditions} |
---|
[2274] | 387 | |
---|
| 388 | The boundary conditions are specified as follows: |
---|
| 389 | |
---|
[2277] | 390 | {\small \begin{verbatim} |
---|
[2274] | 391 | Br = Reflective_boundary(domain) |
---|
| 392 | |
---|
| 393 | Bt = Transmissive_boundary(domain) |
---|
| 394 | |
---|
| 395 | Bd = Dirichlet_boundary([0.2,0.,0.]) |
---|
| 396 | |
---|
| 397 | Bw = Time_boundary(domain=domain, |
---|
| 398 | f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0]) |
---|
[2277] | 399 | \end{verbatim}} |
---|
[2274] | 400 | |
---|
| 401 | The effect of these statements is to set up four alternative |
---|
| 402 | boundary conditions and store them in variables that can be |
---|
| 403 | assigned as needed. Each boundary condition specifies the |
---|
| 404 | behaviour at a boundary in terms of the behaviour in neighbouring |
---|
| 405 | elements. The boundary conditions may be briefly described as |
---|
| 406 | follows: |
---|
| 407 | |
---|
| 408 | \begin{description} |
---|
[2358] | 409 | \item[Reflective boundary] Returns same \code{stage} as |
---|
[2283] | 410 | as present in its neighbour volume but momentum vector reversed 180 degrees (reflected). |
---|
| 411 | Specific to the shallow water equation as it works with the |
---|
| 412 | momentum quantities assumed to be the second and third conserved |
---|
| 413 | quantities. |
---|
[2274] | 414 | \item[Transmissive boundary]Returns same conserved quantities as |
---|
| 415 | those present in its neighbour volume. |
---|
| 416 | \item[Dirichlet boundary]Specifies a fixed value at the |
---|
| 417 | boundary. |
---|
| 418 | \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time. |
---|
| 419 | \end{description} |
---|
| 420 | |
---|
| 421 | Once the four boundary types have been specified through the |
---|
| 422 | statements above, they can be applied through a statement of the |
---|
| 423 | form |
---|
| 424 | |
---|
[2277] | 425 | {\small \begin{verbatim} |
---|
| 426 | domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br}) |
---|
| 427 | \end{verbatim}} |
---|
[2274] | 428 | |
---|
| 429 | This statement stipulates that, in the current example, the left |
---|
| 430 | boundary is fixed, with an elevation of 0.2, while the other |
---|
| 431 | boundaries are all reflective. |
---|
| 432 | |
---|
| 433 | |
---|
[2329] | 434 | \section{Evolution} |
---|
[2274] | 435 | |
---|
| 436 | The final statement \nopagebreak[3] |
---|
[2277] | 437 | {\small \begin{verbatim} |
---|
[2274] | 438 | for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0): |
---|
| 439 | domain.write_time() |
---|
[2277] | 440 | \end{verbatim}} |
---|
[2274] | 441 | |
---|
| 442 | is the key step that causes the configuration of the domain to |
---|
| 443 | `evolve' in accordance with the model embodied in the code, over a |
---|
[2358] | 444 | series of steps indicated by the values of \code{yieldstep} and |
---|
| 445 | \code{finaltime}, which can be altered as required. |
---|
[2283] | 446 | The yieldstep control the time interval between model output. Behind the scenes more timesteps are generally taken. |
---|
[2274] | 447 | |
---|
| 448 | |
---|
[2283] | 449 | |
---|
| 450 | |
---|
[2329] | 451 | \section{Output} |
---|
[2274] | 452 | |
---|
| 453 | %Give details here of the form of the output and explain how it can |
---|
| 454 | %be used with swollen. Include screen shots.// |
---|
| 455 | |
---|
[2358] | 456 | The output is a NetCDF file with the extension \code{.sww}. It |
---|
[2274] | 457 | contains stage and momentum information and can be used with the |
---|
[2358] | 458 | \code{swollen} visualisation package to generate a visual display. |
---|
[2274] | 459 | |
---|
| 460 | |
---|
[2329] | 461 | \section{How to Run the Code} |
---|
[2274] | 462 | |
---|
| 463 | The code can be run in various ways: |
---|
| 464 | |
---|
| 465 | \begin{itemize} |
---|
[2357] | 466 | \item{from a Windows command line} as in \code{python bedslope.py} |
---|
[2274] | 467 | |
---|
| 468 | \item{within the Python IDLE environment} |
---|
| 469 | |
---|
| 470 | \item{within emacs} |
---|
| 471 | |
---|
[2357] | 472 | \item{from a Linux command line} as in \code{python bedslope.py} |
---|
[2274] | 473 | \end{itemize} |
---|
| 474 | |
---|
| 475 | |
---|
[2357] | 476 | \section{Example with real data} |
---|
[2274] | 477 | |
---|
[2358] | 478 | The following discussion builds on the \code{bedslope.py} example and |
---|
| 479 | shows how, using the same basic outline, we can incorporate many more |
---|
| 480 | complex features. |
---|
[2274] | 481 | |
---|
[2357] | 482 | The chief difference is in the method used to create the mesh. Instead of imposing a mesh |
---|
[2422] | 483 | structure on a rectangular grid, the technique used for this example involves building |
---|
| 484 | mesh structures inside polygons. |
---|
[2357] | 485 | |
---|
[2358] | 486 | In its simplest form, the mesh is created within a single polygon |
---|
| 487 | whose vertices are at geographical locations specified by the user. A |
---|
| 488 | triangular mesh is created using points inside the polygon selected |
---|
| 489 | through a random process, the user specifying the |
---|
| 490 | \emph{resolution}---that is, the maximal area of a triangle used for |
---|
| 491 | triangulation. |
---|
[2357] | 492 | |
---|
[2358] | 493 | Figure XXX shows a simple example, in which the triangulation is |
---|
| 494 | carried out within a pentagon. Instead of using the four tags |
---|
| 495 | \code{`left'}, \code{`right'}, \code{`bottom'} and |
---|
| 496 | \code{`top'} to distinguish boundary elements, the user can define |
---|
| 497 | tags appropriate to the configuration being modelled. |
---|
[2357] | 498 | |
---|
[2358] | 499 | While this offers more flexibility than the rectangular grid, it |
---|
| 500 | doesn't provide a way to adapt to geographic or other features in the |
---|
| 501 | landscape, for which we may require to vary the resolution. We achieve |
---|
| 502 | more flexibility by extending this method, allowing the user to |
---|
| 503 | specify a number of interior polygons which are triangulated |
---|
| 504 | separately, possibly using different resolutions. See Figure XXX. |
---|
[2357] | 505 | |
---|
[2358] | 506 | |
---|
| 507 | \chapter{ANUGA Public Interface} |
---|
| 508 | |
---|
| 509 | thoaedut |
---|
| 510 | |
---|
| 511 | |
---|
| 512 | |
---|
[2422] | 513 | \begin{itemize} |
---|
[2358] | 514 | |
---|
[2422] | 515 | \item \indexedcode{create_mesh_from_region}: Create mesh based on a bounding polygon and a number of internal polygons. Each polygon has a maximal area of triangles associated with it - the resolution. The bounding polygon also has symbolic \code{tags} associated with it. |
---|
| 516 | Arguments are: |
---|
[2358] | 517 | \item \indexedcode{pmesh_to_domain_instance}: Convert generated mesh file to domain object. Arguments are: Mesh file name and class specifying which domain class to instantiate. (Simpler) |
---|
[2364] | 518 | |
---|
[2422] | 519 | \item \indexedcode{file_function} %in util.py "High priority" |
---|
| 520 | \item \indexedcode{Interpolation_function} %In least_squares.py ("High priority") |
---|
| 521 | |
---|
| 522 | \item \indexedcode{set_region} ``Low priority. Will be merged into set\_quantity'' |
---|
[2358] | 523 | \item \indexedcode{set_quantity} ``Pretty mature'' |
---|
| 524 | \item \indexedcode{set_boundary} ``Pretty mature'' |
---|
| 525 | |
---|
[2422] | 526 | \end{itemize} |
---|
[2358] | 527 | |
---|
[2422] | 528 | |
---|
[2358] | 529 | Diagnostics |
---|
[2422] | 530 | \begin{itemize} |
---|
[2358] | 531 | \item \indexedcode{write_time} |
---|
| 532 | \item \indexedcode{write_boundary_statistics} |
---|
| 533 | |
---|
| 534 | |
---|
[2422] | 535 | \end{itemize} |
---|
[2358] | 536 | |
---|
[2422] | 537 | |
---|
[2358] | 538 | \subsection{Boundary conditions} |
---|
| 539 | |
---|
[2422] | 540 | ANUGA provides a large number of predefined boundary conditions to be used with |
---|
[2358] | 541 | \code{set_boundary} |
---|
| 542 | |
---|
| 543 | What do they do |
---|
| 544 | How are they used |
---|
| 545 | |
---|
[2422] | 546 | \begin{itemize} |
---|
[2358] | 547 | \item \indexedcode{Reflective_boundary} |
---|
| 548 | function, arguments |
---|
[2422] | 549 | |
---|
[2358] | 550 | \item \indexedcode{Transmissive_boundary} |
---|
[2422] | 551 | function, arguments, CAVEATS |
---|
| 552 | |
---|
[2358] | 553 | \item \indexedcode{Dirichlet_boundary} |
---|
[2422] | 554 | |
---|
| 555 | \item \indexedcode{Time_boundary} |
---|
| 556 | |
---|
| 557 | \item \indexedcode{File_boundary} |
---|
[2364] | 558 | Based on File\_function |
---|
[2422] | 559 | |
---|
| 560 | \item \indexedcode{} |
---|
| 561 | |
---|
| 562 | \item \indexedcode{} |
---|
| 563 | |
---|
| 564 | |
---|
[2358] | 565 | \item \indexedcode{User defined boundary conditions.} |
---|
[2422] | 566 | How to roll your own |
---|
[2358] | 567 | |
---|
| 568 | |
---|
| 569 | |
---|
[2422] | 570 | \end{itemize} |
---|
[2358] | 571 | |
---|
[2422] | 572 | |
---|
| 573 | |
---|
[2358] | 574 | \subsection{Initial conditions} |
---|
| 575 | |
---|
[2422] | 576 | ANUGA provides a number of predefined initial conditions to be used with |
---|
[2358] | 577 | \code{set_quantity}. |
---|
| 578 | |
---|
[2422] | 579 | \begin{itemize} |
---|
[2358] | 580 | |
---|
| 581 | |
---|
| 582 | \item \indexedcode{tsunami_slump} |
---|
| 583 | function, arguments |
---|
[2422] | 584 | |
---|
[2358] | 585 | \item \indexedcode{} |
---|
| 586 | |
---|
[2422] | 587 | \end{itemize} |
---|
[2358] | 588 | |
---|
| 589 | |
---|
| 590 | \subsection{Initial conditions} |
---|
| 591 | |
---|
| 592 | ANUGA provides a number of predefined forcing functions to be used with ..... |
---|
| 593 | |
---|
[2422] | 594 | \begin{itemize} |
---|
[2358] | 595 | |
---|
| 596 | |
---|
| 597 | \item \indexedcode{} |
---|
| 598 | function, arguments |
---|
[2422] | 599 | |
---|
[2358] | 600 | \item \indexedcode{} |
---|
| 601 | |
---|
[2422] | 602 | \end{itemize} |
---|
[2358] | 603 | |
---|
| 604 | |
---|
| 605 | |
---|
[2370] | 606 | |
---|
| 607 | \chapter{ANUGA system architecture} |
---|
| 608 | |
---|
[2413] | 609 | From pyvolution/documentation |
---|
[2370] | 610 | |
---|
| 611 | |
---|
| 612 | |
---|
[2413] | 613 | \chapter{Basic ANUGA assumptions} |
---|
[2370] | 614 | |
---|
[2413] | 615 | (From pyvolution/documentation) |
---|
[2370] | 616 | |
---|
[2413] | 617 | |
---|
| 618 | Physical model time cannot be earlier than 1 Jan 1970 00:00:00. |
---|
| 619 | If one wished to recreate scenarios prior to that date it must be done |
---|
| 620 | using some relative time (e.g. 0). |
---|
| 621 | |
---|
| 622 | |
---|
| 623 | All spatial data relates to the WGS84 datum (or GDA94) and has been |
---|
| 624 | projected into UTM with false easting of 500000 and false northing of |
---|
| 625 | 1000000 on the southern hemisphere (0 on the northern). |
---|
| 626 | |
---|
| 627 | It is assumed that all computations take place within one UTM zone. |
---|
| 628 | |
---|
| 629 | DEMs, meshes and boundary conditions can have different origins within |
---|
[2422] | 630 | one UTM zone. However, the computation will use that of the mesh for |
---|
[2413] | 631 | numerical stability. |
---|
| 632 | |
---|
| 633 | |
---|
| 634 | %OLD |
---|
| 635 | %The dataflow is: (See data_manager.py and from scenarios) |
---|
| 636 | % |
---|
| 637 | % |
---|
| 638 | %Simulation scenarios |
---|
| 639 | %--------------------% |
---|
| 640 | %% |
---|
| 641 | % |
---|
| 642 | %Sub directories contain scrips and derived files for each simulation. |
---|
| 643 | %The directory ../source_data contains large source files such as |
---|
| 644 | %DEMs provided externally as well as MOST tsunami simulations to be used |
---|
| 645 | %as boundary conditions. |
---|
| 646 | % |
---|
| 647 | %Manual steps are: |
---|
| 648 | % Creation of DEMs from argcview (.asc + .prj) |
---|
| 649 | % Creation of mesh from pmesh (.tsh) |
---|
| 650 | % Creation of tsunami simulations from MOST (.nc) |
---|
| 651 | %% |
---|
| 652 | % |
---|
| 653 | %Typical scripted steps are% |
---|
| 654 | % |
---|
| 655 | % prepare_dem.py: Convert asc and prj files supplied by arcview to |
---|
| 656 | % native dem and pts formats% |
---|
| 657 | % |
---|
| 658 | % prepare_pts.py: Convert netcdf output from MOST to an sww file suitable |
---|
| 659 | % as boundary condition% |
---|
| 660 | % |
---|
| 661 | % prepare_mesh.py: Merge DEM (pts) and mesh (tsh) using least squares |
---|
| 662 | % smoothing. The outputs are tsh files with elevation data.% |
---|
| 663 | % |
---|
| 664 | % run_simulation.py: Use the above together with various parameters to |
---|
| 665 | % run inundation simluation. |
---|
| 666 | |
---|
| 667 | |
---|
| 668 | |
---|
| 669 | |
---|
[2329] | 670 | \appendix |
---|
[2358] | 671 | |
---|
| 672 | \chapter{Supporting tools} |
---|
| 673 | |
---|
| 674 | |
---|
| 675 | \section{caching} Could do now. |
---|
| 676 | |
---|
| 677 | |
---|
| 678 | |
---|
| 679 | \section{swollen} Could do now. |
---|
| 680 | |
---|
| 681 | |
---|
| 682 | \section{utilities/polygons} Could do now. |
---|
| 683 | |
---|
[2422] | 684 | \begin{itemize} |
---|
| 685 | \item \indexedcode{polygon_function} |
---|
| 686 | \item \indexedcode{read_polygon} |
---|
| 687 | \item \indexedcode{populate_polygon} |
---|
| 688 | \item \indexedcode{point_in_polygon} |
---|
| 689 | \item \indexedcode{inside_polygon} |
---|
| 690 | \item \indexedcode{outside_polygon} |
---|
| 691 | \item \indexedcode{point_on_line} |
---|
| 692 | \item \indexedcode{separate_points_by_polygon} |
---|
| 693 | \end{itemize} |
---|
[2358] | 694 | |
---|
[2373] | 695 | |
---|
| 696 | |
---|
| 697 | |
---|
[2422] | 698 | |
---|
[2358] | 699 | \section{coordinate_transforms} |
---|
| 700 | |
---|
| 701 | \section{geo_spatial_data} |
---|
| 702 | |
---|
| 703 | \section{pmesh GUI} |
---|
| 704 | |
---|
| 705 | \section{alpha_shape} |
---|
| 706 | |
---|
| 707 | |
---|
[2412] | 708 | \section{utilities/numerical_tools} Could do now. |
---|
[2358] | 709 | |
---|
[2422] | 710 | \begin{itemize} |
---|
[2412] | 711 | \item \indexedcode{ensure_numeric} |
---|
| 712 | \item \indexedcode{mean} |
---|
[2422] | 713 | \item |
---|
| 714 | \end{itemize} |
---|
[2358] | 715 | |
---|
[2329] | 716 | \chapter{Glossary} |
---|
[2274] | 717 | |
---|
[2358] | 718 | \begin{itemize} |
---|
| 719 | \item \indexedbold{ANUGA} name of software (joint development between ANU and GA) |
---|
[2274] | 720 | |
---|
[2422] | 721 | \item \indexedbold{Conserved quantity} |
---|
| 722 | |
---|
[2358] | 723 | \item \indexedbold{Default order} is this really needed? |
---|
[2274] | 724 | |
---|
[2358] | 725 | \item \indexedbold{Domain} |
---|
[2274] | 726 | |
---|
[2358] | 727 | \item \indexedbold{Dirichlet boundary} |
---|
[2274] | 728 | |
---|
[2358] | 729 | \item \indexedbold{Elevation} - refers to bathymetry and topography |
---|
[2274] | 730 | |
---|
[2358] | 731 | \item \indexedbold{bathymetry} offshore |
---|
[2274] | 732 | |
---|
[2358] | 733 | \item \indexedbold{topography} onshore |
---|
[2328] | 734 | |
---|
[2358] | 735 | \item \indexedbold{Evolution} integration of the shallow water wave equations over time |
---|
[2328] | 736 | |
---|
[2358] | 737 | \item \indexedbold{Forcing term} |
---|
[2274] | 738 | |
---|
[2358] | 739 | \item \indexedbold{IDLE} development environment shipped with Python |
---|
[2274] | 740 | |
---|
[2358] | 741 | \item \indexedbold{Manning friction coefficient} |
---|
[2422] | 742 | |
---|
[2358] | 743 | \item \indexedbold{Mesh} triangulation of domain |
---|
[2274] | 744 | |
---|
[2358] | 745 | \item \indexedbold{Grid} evenly spaced |
---|
[2328] | 746 | |
---|
[2358] | 747 | \item \indexedbold{NetCDF} |
---|
[2274] | 748 | |
---|
[2358] | 749 | \item \indexedbold{pmesh} does this really need to be here? it's a class/module? |
---|
[2274] | 750 | |
---|
[2358] | 751 | \item \indexedbold{pyvolution} does this really need to be here? it's a class/module? |
---|
[2274] | 752 | |
---|
[2358] | 753 | \item \indexedbold{Quantity} conserved (state, x and y momentum) |
---|
[2274] | 754 | |
---|
[2358] | 755 | \item \indexedbold{Reflective boundary} |
---|
[2274] | 756 | |
---|
[2358] | 757 | \item \indexedbold{Smoothing} is this really needed? |
---|
[2274] | 758 | |
---|
[2358] | 759 | \item \indexedbold{Stage} |
---|
[2274] | 760 | |
---|
[2358] | 761 | \item \indexedbold{Swollen} visualisation tool |
---|
[2274] | 762 | |
---|
[2358] | 763 | \item \indexedbold{Time boundary} defined in the manual (flog from there) |
---|
[2274] | 764 | |
---|
[2358] | 765 | \item \indexedbold{Transmissive boundary} defined in the manual (flog from there) |
---|
[2274] | 766 | |
---|
[2358] | 767 | \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z) |
---|
[2274] | 768 | |
---|
[2422] | 769 | \item \indexedbold{ymomentum} conserved quantity |
---|
| 770 | |
---|
[2358] | 771 | \item \indexedbold{resolution} refers to the maximal area of each triangular cell in the mesh |
---|
[2422] | 772 | |
---|
[2358] | 773 | \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created in this way ) |
---|
[2422] | 774 | ANUGA represents polygons as either a list of 2-tuples, where the latter are either Python tuples or Python lists of length 2. The unit square, for example, would be represented by the polygon [ [0,0], [1,0], [1,1], [0,1] ]. Alternatively, polygons can be represented as $N \times 2$ Numeric arrays, where $N$ is the number of points. |
---|
| 775 | |
---|
[2358] | 776 | NOTE: More can be read in the module utilities/polygon.py .... |
---|
[2274] | 777 | |
---|
[2422] | 778 | \item \indexedbold{easting} |
---|
[2328] | 779 | |
---|
[2422] | 780 | \item \indexedbold{northing} |
---|
[2328] | 781 | |
---|
[2422] | 782 | \item \indexedbold{latitude} |
---|
[2328] | 783 | |
---|
[2422] | 784 | \item \indexedbold{longitude} |
---|
[2328] | 785 | |
---|
[2422] | 786 | \item \indexedbold{edge} |
---|
[2328] | 787 | |
---|
[2422] | 788 | \item \indexedbold{vertex} |
---|
[2328] | 789 | |
---|
[2422] | 790 | \item \indexedbold{finite volume} |
---|
[2328] | 791 | |
---|
[2422] | 792 | \item \indexedbold{flux} |
---|
[2328] | 793 | |
---|
[2422] | 794 | \item \indexedbold{Digital Elevation Model (DEM)} |
---|
[2328] | 795 | |
---|
[2422] | 796 | |
---|
[2358] | 797 | \end{itemize} |
---|
[2274] | 798 | |
---|
[2329] | 799 | The \code{\e appendix} markup need not be repeated for additional |
---|
| 800 | appendices. |
---|
| 801 | |
---|
| 802 | |
---|
| 803 | % |
---|
| 804 | % The ugly "%begin{latexonly}" pseudo-environments are really just to |
---|
| 805 | % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're |
---|
| 806 | % not really valuable. |
---|
| 807 | % |
---|
| 808 | % If you don't want the Module Index, you can remove all of this up |
---|
| 809 | % until the second \input line. |
---|
| 810 | % |
---|
| 811 | |
---|
| 812 | %begin{latexonly} |
---|
| 813 | %\renewcommand{\indexname}{Module Index} |
---|
| 814 | %end{latexonly} |
---|
[2422] | 815 | %\input{mod\jobname.ind} % Module Index |
---|
[2329] | 816 | |
---|
| 817 | %begin{latexonly} |
---|
| 818 | \renewcommand{\indexname}{Index} |
---|
| 819 | %end{latexonly} |
---|
[2422] | 820 | \input{\jobname.ind} % Index |
---|
[2329] | 821 | |
---|
| 822 | |
---|
| 823 | |
---|
[2274] | 824 | \end{document} |
---|