1 | %\newcommand{\code}[1]{{\small \tt #1}} %For use with one-line code snippets |
---|
2 | |
---|
3 | \documentclass{report} |
---|
4 | |
---|
5 | |
---|
6 | \title{AnuGA User Manual} |
---|
7 | \author{Howard Silcock, Ole Nielsen, Duncan Gray, Jane Sexton} |
---|
8 | |
---|
9 | % Can we get rid of indenting and put a blank line before each para? |
---|
10 | % Find out how to change date format |
---|
11 | % Relabel sections, subsections |
---|
12 | |
---|
13 | \setlength{\parindent}{0mm} %\setlength{\parskip}{3pt} |
---|
14 | \setlength{\oddsidemargin}{0.6in}\setlength{\evensidemargin}{0.6in} |
---|
15 | \addtolength{\textheight}{1in} \addtolength{\textwidth}{0.5in} |
---|
16 | \setlength{\marginparwidth}{0in} |
---|
17 | \setlength{\topmargin}{0mm}\setlength{\headheight}{0in} |
---|
18 | |
---|
19 | \begin{document} |
---|
20 | \maketitle |
---|
21 | |
---|
22 | |
---|
23 | %Subversion keywords: |
---|
24 | % |
---|
25 | %$LastChangedDate: 2006-01-13 16:43:01 +1100 (Fri, 13 Jan 2006) $ |
---|
26 | %$LastChangedRevision: 2206 $ |
---|
27 | %$LastChangedBy: steve $ |
---|
28 | |
---|
29 | \section*{Introduction} |
---|
30 | |
---|
31 | \textbf{AnuGA} is a hydrodynamic modelling tool that |
---|
32 | allows users to model realistic flow problems in complex geometries. Examples include dam breaks or |
---|
33 | the effects of natural hazards such as riverine flooding, storm surges and tsunami. |
---|
34 | |
---|
35 | The user must specify a study area represented by a mesh of triangular |
---|
36 | cells, the topography and bathymetry, frictional resistance, initial |
---|
37 | values for water level (called {\emph{stage} within Anuga), boundary |
---|
38 | conditions and forces such as windstress or pressure gradients if |
---|
39 | applicable. |
---|
40 | |
---|
41 | Anuga tracks the evolution of water depth and horizontal momentum |
---|
42 | within each cell over time by solving the shallow water wave equation |
---|
43 | governing equation using a finite-volume method. |
---|
44 | |
---|
45 | Anuga cannot model details of breaking waves, flow under ceilings such |
---|
46 | as pipes, turbulence and vortices, vertical convection or viscous |
---|
47 | flows. |
---|
48 | |
---|
49 | Anuga also incorporates a mesh generator, called \texttt{pmesh}, that |
---|
50 | allows the user to set up the geometry of the problem interactively as |
---|
51 | well as tools for interpolation and surface fitting, and a number of |
---|
52 | auxiliary tools for visualising and interrogating the model output. |
---|
53 | |
---|
54 | Most AnuGA components are written in the object-oriented programming |
---|
55 | language Python and most users will interact with Anuga by writing |
---|
56 | small Python programs based on the Anuga library |
---|
57 | functions. Computationally intensive components are written for |
---|
58 | efficiency in C routines working directly with the Numerical Python |
---|
59 | structures. |
---|
60 | |
---|
61 | |
---|
62 | |
---|
63 | |
---|
64 | \subsection*{Purpose} |
---|
65 | |
---|
66 | The purpose of this user manual is to introduce the new user to |
---|
67 | the software, describe what it can do and give step-by-step |
---|
68 | instructions for setting up, configuring and running the software. |
---|
69 | |
---|
70 | \subsection*{Scope} |
---|
71 | |
---|
72 | This manual covers only what is needed to operate the software |
---|
73 | after installation. It does not includes instructions for |
---|
74 | installing the software or detailed API documentation, both of |
---|
75 | which will be covered in separate publications. |
---|
76 | |
---|
77 | \subsection*{Audience} |
---|
78 | |
---|
79 | Readers are assumed to be familiar with the operating environment |
---|
80 | and have a general understanding of the problem background, as |
---|
81 | well as enough programming experience to adapt the code to |
---|
82 | different requirements, as described in this manual, and to |
---|
83 | understand the basic terminology of object-oriented programming. |
---|
84 | |
---|
85 | \subsection*{Structure of This Manual} |
---|
86 | |
---|
87 | This manual is structured as follows: |
---|
88 | |
---|
89 | \begin{itemize} |
---|
90 | \item Background (What Anuga does) |
---|
91 | \item A \emph{Getting Started} section |
---|
92 | \item Anuga's overall architecture, components and file formats |
---|
93 | \item Detailed descriptions of the user interface |
---|
94 | \end{itemize} |
---|
95 | |
---|
96 | |
---|
97 | \pagebreak\section*{Getting Started} |
---|
98 | |
---|
99 | This section is designed to assist the reader to get started with |
---|
100 | \textbf{AnuGA} by working through a simple example. What follows |
---|
101 | is a discussion of the structure and operation of the file |
---|
102 | \texttt{bedslope.py}, with just enough detail to allow the reader |
---|
103 | to appreciate what's involved in setting up a scenario like the |
---|
104 | one it depicts. |
---|
105 | |
---|
106 | \subsection*{Overview} |
---|
107 | |
---|
108 | This example carries out the solution of the shallow-water wave |
---|
109 | equation in the simple case of a configuration comprising a flat |
---|
110 | bed, sloping at a fixed angle in one direction and having a |
---|
111 | constant depth across each line in the perpendicular direction. |
---|
112 | |
---|
113 | The example demonstrates many of the basic ideas involved in |
---|
114 | setting up a more complex scenario. In the general case the user |
---|
115 | specifies the geometry (bathymetry and topography), the initial |
---|
116 | water level, boundary conditions such as tide, and any forcing |
---|
117 | terms that may drive the system such as wind stress or atmospheric |
---|
118 | pressure gradients. Frictional resistance from the different |
---|
119 | terrains in the model is represented by predefined forcing |
---|
120 | terms. The boundary is reflective on three sides and a time dependent wave on one side. |
---|
121 | |
---|
122 | The present example, as it represents a simple scenario, does not |
---|
123 | include any forcing term, nor is the data taken from a file as it |
---|
124 | would be in many typical cases. The quantities involved in the |
---|
125 | present problem are: |
---|
126 | \begin{itemize} |
---|
127 | \item elevation |
---|
128 | \item friction |
---|
129 | \item depth |
---|
130 | \item stage |
---|
131 | \end{itemize} |
---|
132 | |
---|
133 | %\emph{[More details of the problem background]} |
---|
134 | |
---|
135 | \subsection*{Outline of the Program} |
---|
136 | |
---|
137 | In outline, \texttt{bedslope.py} performs the following steps: |
---|
138 | |
---|
139 | \begin{enumerate} |
---|
140 | |
---|
141 | \item Sets up a triangular mesh. |
---|
142 | |
---|
143 | \item Sets certain parameters governing the mode of |
---|
144 | operation of the model-specifying, for instance, where to store the model output. |
---|
145 | |
---|
146 | |
---|
147 | \item Inputs various quantities describing physical measurements, such |
---|
148 | as the elevation, to be specified at each mesh point (vertex). |
---|
149 | |
---|
150 | \item Sets up the boundary conditions. |
---|
151 | |
---|
152 | \item Carries out the evolution of the model through a series of time |
---|
153 | steps and outputs the results, providing a results file that can |
---|
154 | be visualised. |
---|
155 | |
---|
156 | \end{enumerate} |
---|
157 | |
---|
158 | \subsection*{The Code} |
---|
159 | |
---|
160 | For reference we include below the complete code listing for |
---|
161 | \texttt{bedslope.py}. Subsequent paragraphs provide a `commentary' |
---|
162 | that describes each step of the program and explains it significance. |
---|
163 | |
---|
164 | |
---|
165 | %\emph{[Can't work out how to prevent \LaTeX (or WinEdt) from |
---|
166 | %wrapping lines, even in \emph{verbatim} mode, without putting} |
---|
167 | %\verb+\\+\emph{s at the ends of lines!]} |
---|
168 | |
---|
169 | {\scriptsize \begin{verbatim} |
---|
170 | from pyvolution.mesh_factory import rectangular |
---|
171 | from pyvolution.shallow_water import Domain, Reflective_boundary, |
---|
172 | Dirichlet_boundary, Time_boundary, Transmissive_boundary |
---|
173 | |
---|
174 | #Create basic mesh |
---|
175 | points, vertices, boundary = rectangular(10,10) |
---|
176 | |
---|
177 | #Create shallow water domain |
---|
178 | domain = Domain(points, vertices,boundary) |
---|
179 | domain.smooth = False domain.visualise = False |
---|
180 | domain.store = True domain.filename = 'bedslope' |
---|
181 | domain.default_order = 2 |
---|
182 | |
---|
183 | ####################### |
---|
184 | # Initial conditions |
---|
185 | def f(x,y): |
---|
186 | return -x/2 |
---|
187 | |
---|
188 | domain.set_quantity('elevation', f) |
---|
189 | domain.set_quantity('friction', 0.1) |
---|
190 | |
---|
191 | h = 0.05 # Constant depth |
---|
192 | domain.set_quantity('stage', expression = 'elevation + %f' %h) |
---|
193 | |
---|
194 | |
---|
195 | # Boundary conditions |
---|
196 | from math import sin, pi |
---|
197 | Br = Reflective_boundary(domain) |
---|
198 | Bt = Transmissive_boundary(domain) |
---|
199 | Bd = Dirichlet_boundary([0.2,0.,0.]) |
---|
200 | |
---|
201 | Bw = Time_boundary(domain=domain, |
---|
202 | f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0]) |
---|
203 | |
---|
204 | |
---|
205 | domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br}) |
---|
206 | |
---|
207 | |
---|
208 | ###################### |
---|
209 | #Evolution |
---|
210 | |
---|
211 | domain.check_integrity() |
---|
212 | |
---|
213 | for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0): |
---|
214 | domain.write_time() |
---|
215 | |
---|
216 | |
---|
217 | \end{verbatim}} |
---|
218 | |
---|
219 | |
---|
220 | \subsection*{Establishing the Mesh} |
---|
221 | |
---|
222 | The first task is to set up the triangular mesh to be used for the |
---|
223 | scenario. This is carried out through the statement: |
---|
224 | |
---|
225 | {\small \begin{verbatim} |
---|
226 | points, vertices, boundary = rectangular(10, 10) |
---|
227 | \end{verbatim}} |
---|
228 | |
---|
229 | The function \texttt{rectangular} is imported from a module |
---|
230 | \texttt{mesh\_factory} defined elsewhere. (\textbf{AnuGA} also |
---|
231 | contains several other schemes that can be used for setting up |
---|
232 | meshes, but we shall not discuss these now.) The above assignment |
---|
233 | sets up a $10 \times 10$ rectangular mesh, triangulated in a |
---|
234 | specific way. In general, the assignment |
---|
235 | |
---|
236 | {\small \begin{verbatim} |
---|
237 | points, vertices, boundary = rectangular(m, n) |
---|
238 | \end{verbatim}} |
---|
239 | |
---|
240 | returns: |
---|
241 | |
---|
242 | \begin{itemize} |
---|
243 | |
---|
244 | \item a list \texttt{points} of length $N$, where $N = (m + 1)(n + 1)$, |
---|
245 | comprising the coordinates $(x, y)$ of each of the $N$ mesh |
---|
246 | points, |
---|
247 | |
---|
248 | \item a list \texttt{vertices} of length $2mn$ (each entry specifies the three |
---|
249 | vertices of one of the triangles used in the triangulation) , and |
---|
250 | |
---|
251 | \item a dictionary \texttt{boundary}, used to tag the triangle edges on |
---|
252 | the boundaries. Each key corresponds to a triangle edge on one of |
---|
253 | the four boundaries and its value is one of \texttt{`left'}, |
---|
254 | \texttt{`right'}, \texttt{`top'} and \texttt{`bottom'}, indicating |
---|
255 | which boundary the edge in question belongs to. |
---|
256 | |
---|
257 | \end{itemize} |
---|
258 | |
---|
259 | |
---|
260 | \subsection*{Initialising the domain} |
---|
261 | |
---|
262 | These variables are then used to set up a data structure |
---|
263 | \texttt{domain}, through the assignment: |
---|
264 | |
---|
265 | {\small \begin{verbatim} |
---|
266 | domain = Domain(points, vertices, boundary) |
---|
267 | \end{verbatim}} |
---|
268 | |
---|
269 | This uses a Python class \texttt{Domain}, imported from |
---|
270 | \texttt{shallow\_water}, which is an extension of a more generic |
---|
271 | class of the same name in the module \texttt{domain}, and inherits |
---|
272 | some methods from the generic class but has others specific to the |
---|
273 | shallow-water scenarios in which it is used. The following lines |
---|
274 | set certain key options governing the domain: \emph{[more details |
---|
275 | of what these do]} |
---|
276 | |
---|
277 | {\scriptsize \begin{verbatim} |
---|
278 | domain.smooth = False |
---|
279 | domain.visualise = False |
---|
280 | domain.store = True |
---|
281 | domain.filename = 'bedslope' |
---|
282 | domain.default_order = 2 |
---|
283 | \end{verbatim}} |
---|
284 | |
---|
285 | |
---|
286 | \subsection*{Specifying the Quantities} |
---|
287 | |
---|
288 | The next task is to specify a number of quantities that we wish to set |
---|
289 | for each mesh point. The class \texttt{Domain} has a method |
---|
290 | \texttt{set\_quantity}, used to specify these quantities. It is a |
---|
291 | particularly flexible method that allows the user to set quantities in |
---|
292 | a variety of ways---using constants, functions, numeric arrays or |
---|
293 | expressions involving other quantities, arbitrary data points with |
---|
294 | associated values, all of which can be passed as arguments. All |
---|
295 | quantities can be initialised using \texttt{set\_quantity}. For |
---|
296 | conserved quantities (\texttt{stage, xmomentum, ymomentum}) this is |
---|
297 | called the \emph{initial condition}, for other quantities that aren't |
---|
298 | updated by the equation, the same interface is used to assign their |
---|
299 | values. The code in the present example demonstrates a number of forms |
---|
300 | in which we can invoke \texttt{set\_quantity}. |
---|
301 | |
---|
302 | |
---|
303 | \subsubsection*{Elevation} |
---|
304 | |
---|
305 | The elevation is set using a function, defined through the |
---|
306 | statements below, which is specific to this example and specifies |
---|
307 | a particularly simple initial configuration for demonstration |
---|
308 | purposes: |
---|
309 | |
---|
310 | {\small \begin{verbatim} |
---|
311 | def f(x,y): |
---|
312 | return -x/2 |
---|
313 | \end{verbatim}} |
---|
314 | |
---|
315 | This simply associates an elevation with each point $(x, y)$ of |
---|
316 | the plane. It specifies that the bed slopes linearly in the $x$ |
---|
317 | direction, with slope $-\frac{1}{2}$, and is constant in the $y$ |
---|
318 | direction.\\ %[screen shot?] |
---|
319 | \\ |
---|
320 | Once the function $f$ is specified, the quantity |
---|
321 | \texttt{elevation} is assigned through the simple statement: |
---|
322 | |
---|
323 | {\small \begin{verbatim} |
---|
324 | \begin{verbatim} |
---|
325 | domain.set_quantity('elevation', f) |
---|
326 | \end{verbatim}} |
---|
327 | |
---|
328 | |
---|
329 | \subsubsection*{Friction} |
---|
330 | |
---|
331 | The assignment of the friction quantity demonstrates another way |
---|
332 | we can use \texttt{set\_quantity} to set quantities---namely, |
---|
333 | assign them to a constant numerical value: |
---|
334 | |
---|
335 | {\small \begin{verbatim} |
---|
336 | domain.set_quantity('friction', 0.1) |
---|
337 | \end{verbatim}} |
---|
338 | |
---|
339 | This just specifies that the Manning friction coefficient is set |
---|
340 | to 0.1 at every mesh point. |
---|
341 | |
---|
342 | \subsubsection*{Depth} |
---|
343 | |
---|
344 | Assigning depth illustrates a more complex way to use |
---|
345 | \texttt{set\_quantity}, introducing an expression involving other |
---|
346 | quantities: |
---|
347 | |
---|
348 | {\small \begin{verbatim} |
---|
349 | h = 0.05 \# Constant depth |
---|
350 | domain.set_quantity('stage', expression = 'elevation + %f' %h) |
---|
351 | \end{verbatim}} |
---|
352 | |
---|
353 | Here the quantity \texttt{stage} is defined by taking the quantity |
---|
354 | elevation already defined and adding a constant value $h = 0.05$ |
---|
355 | to it everywhere. This expresses the fact that the water depth is |
---|
356 | everywhere constant, so the surface is a constant height above the |
---|
357 | elevation of the bed. |
---|
358 | |
---|
359 | \subsubsection*{Boundary Conditions} |
---|
360 | |
---|
361 | The boundary conditions are specified as follows: |
---|
362 | |
---|
363 | {\small \begin{verbatim} |
---|
364 | Br = Reflective_boundary(domain) |
---|
365 | |
---|
366 | Bt = Transmissive_boundary(domain) |
---|
367 | |
---|
368 | Bd = Dirichlet_boundary([0.2,0.,0.]) |
---|
369 | |
---|
370 | Bw = Time_boundary(domain=domain, |
---|
371 | f=lambda t: [(0.1*sin(t*2*pi)), 0.0, 0.0]) |
---|
372 | \end{verbatim}} |
---|
373 | |
---|
374 | The effect of these statements is to set up four alternative |
---|
375 | boundary conditions and store them in variables that can be |
---|
376 | assigned as needed. Each boundary condition specifies the |
---|
377 | behaviour at a boundary in terms of the behaviour in neighbouring |
---|
378 | elements. The boundary conditions may be briefly described as |
---|
379 | follows: |
---|
380 | |
---|
381 | \begin{description} |
---|
382 | \item[Reflective boundary] Returns same \texttt{stage} as |
---|
383 | as present in its neighbour volume but momentum vector reversed 180 degrees (reflected). |
---|
384 | Specific to the shallow water equation as it works with the |
---|
385 | momentum quantities assumed to be the second and third conserved |
---|
386 | quantities. |
---|
387 | \item[Transmissive boundary]Returns same conserved quantities as |
---|
388 | those present in its neighbour volume. |
---|
389 | \item[Dirichlet boundary]Specifies a fixed value at the |
---|
390 | boundary. |
---|
391 | \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time. |
---|
392 | \end{description} |
---|
393 | |
---|
394 | Once the four boundary types have been specified through the |
---|
395 | statements above, they can be applied through a statement of the |
---|
396 | form |
---|
397 | |
---|
398 | {\small \begin{verbatim} |
---|
399 | domain.set_boundary({'left': Bd, 'right': Br, 'top': Br, 'bottom': Br}) |
---|
400 | \end{verbatim}} |
---|
401 | |
---|
402 | This statement stipulates that, in the current example, the left |
---|
403 | boundary is fixed, with an elevation of 0.2, while the other |
---|
404 | boundaries are all reflective. |
---|
405 | |
---|
406 | |
---|
407 | \subsection*{Evolution} |
---|
408 | |
---|
409 | The final statement \nopagebreak[3] |
---|
410 | {\small \begin{verbatim} |
---|
411 | for t in domain.evolve(yieldstep = 0.1, finaltime = 4.0): |
---|
412 | domain.write_time() |
---|
413 | \end{verbatim}} |
---|
414 | |
---|
415 | is the key step that causes the configuration of the domain to |
---|
416 | `evolve' in accordance with the model embodied in the code, over a |
---|
417 | series of steps indicated by the values of \texttt{yieldstep} and |
---|
418 | \texttt{finaltime}, which can be altered as required. |
---|
419 | The yieldstep control the time interval between model output. Behind the scenes more timesteps are generally taken. |
---|
420 | |
---|
421 | |
---|
422 | |
---|
423 | |
---|
424 | \subsection*{Output} |
---|
425 | |
---|
426 | %Give details here of the form of the output and explain how it can |
---|
427 | %be used with swollen. Include screen shots.// |
---|
428 | |
---|
429 | The output is a NetCDF file with the extension \texttt{.sww}. It |
---|
430 | contains stage and momentum information and can be used with the |
---|
431 | \texttt{swollen} visualisation package to generate a visual display. |
---|
432 | |
---|
433 | |
---|
434 | \subsection*{How to Run the Code} |
---|
435 | |
---|
436 | The code can be run in various ways: |
---|
437 | |
---|
438 | \begin{itemize} |
---|
439 | \item{from a Windows command line} as in \texttt{python bedslope.py} |
---|
440 | |
---|
441 | \item{within the Python IDLE environment} |
---|
442 | |
---|
443 | \item{within emacs} |
---|
444 | |
---|
445 | \item{from a Linux command line} as in \texttt{python bedslope.py} |
---|
446 | \end{itemize} |
---|
447 | |
---|
448 | |
---|
449 | |
---|
450 | |
---|
451 | \pagebreak\section*{Glossary} |
---|
452 | |
---|
453 | \begin{description} |
---|
454 | |
---|
455 | \item[AnuGA] |
---|
456 | |
---|
457 | \item[Conserved quantity] |
---|
458 | |
---|
459 | \item[Default order] |
---|
460 | |
---|
461 | \item[Domain] |
---|
462 | |
---|
463 | \item[Dirichlet boundary] |
---|
464 | |
---|
465 | \item[Elevation] |
---|
466 | |
---|
467 | \item[Evolution] |
---|
468 | |
---|
469 | \item[Forcing term] |
---|
470 | |
---|
471 | \item[IDLE] |
---|
472 | |
---|
473 | \item[Manning friction coefficient] |
---|
474 | |
---|
475 | \item[Mesh] |
---|
476 | |
---|
477 | \item[NetCDF] |
---|
478 | |
---|
479 | \item[pmesh] |
---|
480 | |
---|
481 | \item[pyvolution] |
---|
482 | |
---|
483 | \item[Quantity] |
---|
484 | |
---|
485 | \item[Reflective boundary] |
---|
486 | |
---|
487 | \item[Smoothing] |
---|
488 | |
---|
489 | \item[Stage] |
---|
490 | |
---|
491 | \item[Swollen] |
---|
492 | |
---|
493 | \item[Time boundary] |
---|
494 | |
---|
495 | \item[Transmissive boundary] |
---|
496 | |
---|
497 | \item[xmomentum] |
---|
498 | |
---|
499 | \item[ymomentum] |
---|
500 | |
---|
501 | |
---|
502 | \end{description} |
---|
503 | |
---|
504 | \end{document} |
---|