Changeset 2358


Ignore:
Timestamp:
Feb 8, 2006, 4:43:35 PM (18 years ago)
Author:
ole
Message:

Ideas for Howard

File:
1 edited

Legend:

Unmodified
Added
Removed
  • documentation/AnuGA_user_manual.tex

    r2357 r2358  
    77
    88
    9 %\newcommand{\code}[1]{{\small \tt #1}} %For use with one-line code snippets
     9\newcommand{\indexedcode}[1]{\code{#1}\index{#1}}
     10\newcommand{\indexedbold}[1]{\textbf{#1}\index{#1}}
    1011       
    1112\documentclass{manual}
     
    5354\noindent
    5455\textbf{AnuGA}\index{AnuGA} is a hydrodynamic modelling tool that
    55 allows users to model realistic flow problems in complex geometries. Examples include dam breaks or   
    56 the effects of natural hazards such as riverine flooding, storm surges and tsunami.
     56allows users to model realistic flow problems in complex
     57geometries. Examples include dam breaks or the effects of natural
     58hazards such as riverine flooding, storm surges and tsunami.
    5759
    5860The user must specify a study area represented by a mesh of triangular
     
    7173flows.
    7274
    73 Anuga also incorporates a mesh generator, called \texttt{pmesh}, that
     75Anuga also incorporates a mesh generator, called \code{pmesh}, that
    7476allows the user to set up the geometry of the problem interactively as
    7577well as tools for interpolation and surface fitting, and a number of
     
    131133\textbf{AnuGA} by working through a simple example. What follows
    132134is a discussion of the structure and operation of the file
    133 \texttt{bedslope.py}, with just enough detail to allow the reader
     135\code{bedslope.py}, with just enough detail to allow the reader
    134136to appreciate what's involved in setting up a scenario like the
    135137one it depicts.
     
    166168\section{Outline of the Program}
    167169
    168 In outline, \texttt{bedslope.py} performs the following steps:
     170In outline, \code{bedslope.py} performs the following steps:
    169171
    170172\begin{enumerate}
     
    189191\section{The Code}
    190192
    191 %FIXME: we are using the \code function here. This should be used whereever possible
     193%FIXME: we are using the \code function here.
     194%This should be used whereever possible
    192195For reference we include below the complete code listing for
    193196\code{bedslope.py}. Subsequent paragraphs provide a `commentary'
     
    254257\end{verbatim}}
    255258
    256 The function \texttt{rectangular} is imported from a module
    257 \texttt{mesh\_factory} defined elsewhere. (\textbf{AnuGA} also
     259The function \code{rectangular} is imported from a module
     260\code{mesh\_factory} defined elsewhere. (\textbf{AnuGA} also
    258261contains several other schemes that can be used for setting up
    259262meshes, but we shall not discuss these now.) The above assignment
     
    269272\begin{itemize}
    270273
    271    \item a list \texttt{points} of length $N$, where $N = (m + 1)(n + 1)$,
     274   \item a list \code{points} of length $N$, where $N = (m + 1)(n + 1)$,
    272275comprising the coordinates $(x, y)$ of each of the $N$ mesh
    273276points,
    274277
    275    \item a list \texttt{vertices} of length $2mn$ (each entry specifies the three
     278   \item a list \code{vertices} of length $2mn$ (each entry specifies the three
    276279vertices of one of the triangles used in the triangulation) , and
    277280
    278    \item a dictionary \texttt{boundary}, used to tag the triangle edges on
     281   \item a dictionary \code{boundary}, used to tag the triangle edges on
    279282the boundaries. Each key corresponds to a triangle edge on one of
    280 the four boundaries and its value is one of \texttt{`left'},
    281 \texttt{`right'}, \texttt{`top'} and \texttt{`bottom'}, indicating
     283the four boundaries and its value is one of \code{`left'},
     284\code{`right'}, \code{`top'} and \code{`bottom'}, indicating
    282285which boundary the edge in question belongs to.
    283286
     
    288291
    289292These variables are then used to set up a data structure
    290 \texttt{domain}, through the assignment:
     293\code{domain}, through the assignment:
    291294
    292295{\small \begin{verbatim}
     
    294297\end{verbatim}}
    295298
    296 This uses a Python class \texttt{Domain}, imported from
    297 \texttt{shallow\_water}, which is an extension of a more generic
    298 class of the same name in the module \texttt{domain}, and inherits
     299This uses a Python class \code{Domain}, imported from
     300\code{shallow\_water}, which is an extension of a more generic
     301class of the same name in the module \code{domain}, and inherits
    299302some methods from the generic class but has others specific to the
    300303shallow-water scenarios in which it is used. Specific options for domain
     
    309312
    310313The next task is to specify a number of quantities that we wish to set
    311 for each mesh point. The class \texttt{Domain} has a method
    312 \texttt{set\_quantity}, used to specify these quantities. It is a
     314for each mesh point. The class \code{Domain} has a method
     315\code{set\_quantity}, used to specify these quantities. It is a
    313316particularly flexible method that allows the user to set quantities in
    314317a variety of ways---using constants, functions, numeric arrays or
    315318expressions involving other quantities, arbitrary data points with
    316319associated values, all of which can be passed as arguments. All
    317 quantities can be initialised using \texttt{set\_quantity}. For
    318 conserved quantities (\texttt{stage, xmomentum, ymomentum}) this is
     320quantities can be initialised using \code{set\_quantity}. For
     321conserved quantities (\code{stage, xmomentum, ymomentum}) this is
    319322called the \emph{initial condition}, for other quantities that aren't
    320323updated by the equation, the same interface is used to assign their
    321324values. The code in the present example demonstrates a number of forms
    322 in which we can invoke \texttt{set\_quantity}.
     325in which we can invoke \code{set\_quantity}.
    323326
    324327
     
    341344\\
    342345Once the function $f$ is specified, the quantity
    343 \texttt{elevation} is assigned through the simple statement:
     346\code{elevation} is assigned through the simple statement:
    344347
    345348{\small \begin{verbatim}
     
    352355
    353356The assignment of the friction quantity demonstrates another way
    354 we can use \texttt{set\_quantity} to set quantities---namely,
     357we can use \code{set\_quantity} to set quantities---namely,
    355358assign them to a constant numerical value:
    356359
     
    365368
    366369Assigning depth illustrates a more complex way to use
    367 \texttt{set\_quantity}, introducing an expression involving other
     370\code{set\_quantity}, introducing an expression involving other
    368371quantities:
    369372
     
    373376\end{verbatim}}
    374377
    375 Here the quantity \texttt{stage} is defined by taking the quantity
     378Here the quantity \code{stage} is defined by taking the quantity
    376379elevation already defined and adding a constant value $h = 0.05$
    377380to it everywhere. This expresses the fact that the water depth is
     
    402405
    403406\begin{description}
    404     \item[Reflective boundary] Returns same \texttt{stage} as
     407    \item[Reflective boundary] Returns same \code{stage} as
    405408    as present in its neighbour volume but momentum vector reversed 180 degrees (reflected).
    406409    Specific to the shallow water equation as it works with the
     
    437440is the key step that causes the configuration of the domain to
    438441`evolve' in accordance with the model embodied in the code, over a
    439 series of steps indicated by the values of \texttt{yieldstep} and
    440 \texttt{finaltime}, which can be altered as required.
     442series of steps indicated by the values of \code{yieldstep} and
     443\code{finaltime}, which can be altered as required.
    441444The yieldstep control the time interval between model output. Behind the scenes more timesteps are generally taken.
    442445
     
    449452%be used with swollen. Include screen shots.//
    450453
    451 The output is a NetCDF file with the extension \texttt{.sww}. It
     454The output is a NetCDF file with the extension \code{.sww}. It
    452455contains stage and momentum information and can be used with the
    453 \texttt{swollen} visualisation package to generate a visual display.
     456\code{swollen} visualisation package to generate a visual display.
    454457
    455458
     
    471474\section{Example with real data}
    472475
    473 The following discussion builds on the \code{bedslope.py} example and shows
    474 how, using the same basic outline, we can incorporate many more complex features.
     476The following discussion builds on the \code{bedslope.py} example and
     477shows how, using the same basic outline, we can incorporate many more
     478complex features.
    475479
    476480The chief difference is in the method used to create the mesh. Instead of imposing a mesh
     
    478482mesh structures inside polygons.
    479483
    480 In its simplest form, the mesh is created within a
    481 single polygon whose vertices are at geographical locations specified by the user.
    482 A triangular mesh is created using points inside the polygon selected
    483 through a random process, the
    484 user specifying the \emph{resolution}---that is, the maximal area of a triangle used for triangulation.
    485 
    486 Figure XXX shows a simple example, in which the triangulation is carried out within a
    487 pentagon. Instead of using the four tags \texttt{`left'}, \texttt{`right'}, \texttt{`bottom'} and
    488 \texttt{`top'} to distinguish
    489 boundary elements, the user can define tags appropriate to the configuration being modelled.
    490 
    491 While this offers more flexibility than the rectangular grid, it doesn't provide a way to
    492 adapt to geographic
    493 or other features in the landscape, for which we may require to vary the resolution. We achieve
    494 more flexibility by extending this method, allowing the user to specify a number of
    495 interior polygons which are triangulated separately, possibly using different resolutions.
    496 See Figure XXX.
     484In its simplest form, the mesh is created within a single polygon
     485whose vertices are at geographical locations specified by the user.  A
     486triangular mesh is created using points inside the polygon selected
     487through a random process, the user specifying the
     488\emph{resolution}---that is, the maximal area of a triangle used for
     489triangulation.
     490
     491Figure XXX shows a simple example, in which the triangulation is
     492carried out within a pentagon. Instead of using the four tags
     493\code{`left'}, \code{`right'}, \code{`bottom'} and
     494\code{`top'} to distinguish boundary elements, the user can define
     495tags appropriate to the configuration being modelled.
     496
     497While this offers more flexibility than the rectangular grid, it
     498doesn't provide a way to adapt to geographic or other features in the
     499landscape, for which we may require to vary the resolution. We achieve
     500more flexibility by extending this method, allowing the user to
     501specify a number of interior polygons which are triangulated
     502separately, possibly using different resolutions.  See Figure XXX.
     503
     504
     505\chapter{ANUGA Public Interface}
     506
     507thoaedut
     508
     509
     510
     511\begin{itemize}
     512
     513  \item \indexedcode{create_mesh_from_region}: Create mesh based on a bounding polygon and a number of internal polygons. Each polygon has a maximal area of triangles associated with it - the resolution. The bounding polygon also has symbolic \code{tags} associated with it.   
     514  Arguments are:
     515  \item \indexedcode{pmesh_to_domain_instance}: Convert generated mesh file to domain object. Arguments are: Mesh file name and class specifying which domain class to instantiate. (Simpler)
     516 
     517 
     518  \item \indexedcode{set_region} ``Low priority. Will be merged into set_quantity'' 
     519  \item \indexedcode{set_quantity} ``Pretty mature''
     520  \item \indexedcode{set_boundary} ``Pretty mature''
     521 
     522
     523\end{itemize}
     524
     525
     526Diagnostics
     527\begin{itemize}
     528  \item \indexedcode{write_time}
     529  \item \indexedcode{write_boundary_statistics}
     530 
     531
     532\end{itemize}
     533
     534
     535\subsection{Boundary conditions}
     536
     537ANUGA provides a large number of predefined boundary conditions to be used with
     538\code{set_boundary}
     539
     540What do they do
     541How are they used
     542
     543\begin{itemize}
     544  \item \indexedcode{Reflective_boundary}
     545  function, arguments
     546 
     547  \item \indexedcode{Transmissive_boundary}
     548  function, arguments, CAVEATS 
     549 
     550  \item \indexedcode{Dirichlet_boundary}
     551 
     552  \item \indexedcode{Time_boundary} 
     553 
     554  \item \indexedcode{File_boundary}   
     555 
     556  \item \indexedcode{}     
     557 
     558  \item \indexedcode{}       
     559 
     560 
     561  \item \indexedcode{User defined boundary conditions.}
     562  How to roll your own     
     563 
     564 
     565
     566\end{itemize}
     567
     568
     569
     570\subsection{Initial conditions}
     571
     572ANUGA provides a number of predefined initial conditions to be used with
     573\code{set_quantity}.
     574
     575\begin{itemize}
     576
     577
     578  \item \indexedcode{tsunami_slump}
     579  function, arguments
     580 
     581  \item \indexedcode{}
     582
     583\end{itemize}
     584
     585
     586\subsection{Initial conditions}
     587
     588ANUGA provides a number of predefined forcing functions to be used with .....
     589
     590\begin{itemize}
     591
     592
     593  \item \indexedcode{}
     594  function, arguments
     595 
     596  \item \indexedcode{}
     597
     598\end{itemize}
     599
     600
    497601
    498602\appendix
     603
     604\chapter{Supporting tools}
     605
     606
     607\section{caching} Could do now.
     608
     609
     610
     611\section{swollen} Could do now.
     612
     613
     614\section{utilities/polygons} Could do now.
     615
     616
     617\section{coordinate_transforms}
     618
     619\section{geo_spatial_data}
     620
     621\section{pmesh GUI}
     622
     623\section{alpha_shape}
     624
     625
     626
     627
     628
    499629\chapter{Glossary}
    500630
    501 \begin{description}
    502 
    503     \item[AnuGA] name of software (joint development between ANU and GA)
     631\begin{itemize}
     632    \item \indexedbold{ANUGA} name of software (joint development between ANU and GA)
    504633   
    505     \item[Conserved quantity]   
    506 
    507     \item[Default order] is this really needed?
    508 
    509     \item[Domain]
    510 
    511     \item[Dirichlet boundary]
    512 
    513     \item[Elevation] - refers to bathymetry and topography
    514 
    515     \item[bathymetry] offshore
    516 
    517     \item[topography] onshore
    518 
    519     \item[Evolution] integration of the shallow water wave equations over time
    520 
    521     \item[Forcing term]
    522 
    523     \item[IDLE] development environment shipped with Python
    524 
    525     \item[Manning friction coefficient]
     634    \item \indexedbold{Conserved quantity}   
     635
     636    \item \indexedbold{Default order} is this really needed?
     637
     638    \item \indexedbold{Domain}
     639
     640    \item \indexedbold{Dirichlet boundary}
     641
     642    \item \indexedbold{Elevation} - refers to bathymetry and topography
     643
     644    \item \indexedbold{bathymetry} offshore
     645
     646    \item \indexedbold{topography} onshore
     647
     648    \item \indexedbold{Evolution} integration of the shallow water wave equations over time
     649
     650    \item \indexedbold{Forcing term}
     651
     652    \item \indexedbold{IDLE} development environment shipped with Python
     653
     654    \item \indexedbold{Manning friction coefficient}
    526655   
    527     \item[Mesh]    triangulation of domain
    528 
    529     \item[Grid] evenly spaced
    530 
    531     \item[NetCDF]
    532 
    533     \item[pmesh] does this really need to be here? it's a class/module?
    534 
    535     \item[pyvolution] does this really need to be here? it's a class/module?
    536 
    537     \item[Quantity] conserved (state, x and y momentum)
    538 
    539     \item[Reflective boundary]
    540 
    541     \item[Smoothing] is this really needed?
    542 
    543     \item[Stage]
    544 
    545     \item[Swollen] visualisation tool
    546 
    547     \item[Time boundary] defined in the manual (flog from there)
    548 
    549     \item[Transmissive boundary] defined in the manual (flog from there)
    550 
    551     \item[xmomentum] conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
     656    \item \indexedbold{Mesh}    triangulation of domain
     657
     658    \item \indexedbold{Grid} evenly spaced
     659
     660    \item \indexedbold{NetCDF}
     661
     662    \item \indexedbold{pmesh} does this really need to be here? it's a class/module?
     663
     664    \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?
     665
     666    \item \indexedbold{Quantity} conserved (state, x and y momentum)
     667
     668    \item \indexedbold{Reflective boundary}
     669
     670    \item \indexedbold{Smoothing} is this really needed?
     671
     672    \item \indexedbold{Stage}
     673
     674    \item \indexedbold{Swollen} visualisation tool
     675
     676    \item \indexedbold{Time boundary} defined in the manual (flog from there)
     677
     678    \item \indexedbold{Transmissive boundary} defined in the manual (flog from there)
     679
     680    \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
    552681   
    553     \item[ymomentum]  conserved quantity
    554 
    555     \item[resolution]   refers to the maximal area of each triangular cell in the mesh
    556 
    557     \item[easting]   
    558 
    559     \item[northing]   
    560 
    561     \item[latitude]   
    562 
    563     \item[longitude]   
    564 
    565     \item[edge]   
    566 
    567     \item[vertex] 
     682    \item \indexedbold{ymomentum}  conserved quantity
     683
     684    \item \indexedbold{resolution}   refers to the maximal area of each triangular cell in the mesh
     685   
     686    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created in this way )
     687    ANUGA represents polygons as either a list of 2-tuples, where the latter are either Python tuples or Python lists of length 2. The unit square, for example, would be represented by the polygon [ [0,0], [1,0], [1,1], [0,1] ]. Alternatively, polygons can be represented as $N \times 2$ Numeric arrays, where $N$ is the number of points.       
     688   
     689    NOTE: More can be read in the module utilities/polygon.py ....
     690
     691    \item \indexedbold{easting}   
     692
     693    \item \indexedbold{northing}   
     694
     695    \item \indexedbold{latitude}   
     696
     697    \item \indexedbold{longitude}   
     698
     699    \item \indexedbold{edge}   
     700
     701    \item \indexedbold{vertex} 
    568702 
    569     \item[finite volume] 
    570 
    571     \item[flux] 
    572 
    573     \item[Digital Elevation Model (DEM)]   
    574 
    575 
    576 \end{description}
     703    \item \indexedbold{finite volume} 
     704
     705    \item \indexedbold{flux} 
     706
     707    \item \indexedbold{Digital Elevation Model (DEM)}   
     708
     709
     710\end{itemize}
    577711
    578712The \code{\e appendix} markup need not be repeated for additional
Note: See TracChangeset for help on using the changeset viewer.