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