Changeset 2467


Ignore:
Timestamp:
Mar 2, 2006, 5:03:22 PM (18 years ago)
Author:
howard
Message:

Updates to Chapters 2 and 3.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • documentation/user_manual/anuga_user_manual.tex

    r2463 r2467  
    4141%\makemodindex          % If this contains a lot of module sections.
    4242
    43 
     43\setcounter{tocdepth}{3}
    4444
    4545\begin{document}
     
    6262\begin{abstract}
    6363
    64 \noindent
    65 \anuga\index{AnuGA} is a hydrodynamic modelling tool that
    66 allows users to model realistic flow problems in complex
    67 geometries. Examples include dam breaks or the effects of natural
    68 hazards such as riverine flooding, storm surges and tsunami.
     64\noindent \anuga\index{\anuga} is a hydrodynamic modelling tool that
     65allows users to model realistic flow problems in complex geometries.
     66Examples include dam breaks or the effects of natural hazards such
     67as riverine flooding, storm surges and tsunami.
    6968
    7069The user must specify a study area represented by a mesh of triangular
     
    514513to geographic or other features in the landscape, whose presence may
    515514require us to vary the resolution in the neighbourhood of the
    516 features. However, this capability is in fact also provided in
    517 \code{pmesh}. It provides for these more general situations by
    518 allowing the user to specify a number of \emph{interior polygons},
    519 which are triangulated separately, each according to a separately
    520 specified resolution. See Figure XXX.
     515features. To cope with this requirement, \code{pmesh} also allows
     516the user to specify a number of \emph{interior polygons}, which are
     517triangulated separately, each according to a separately specified
     518resolution. See Figure XXX.
    521519
    522520In its general form, \code{pmesh} takes for its input a bounding
     
    543541file, with extension \code{.tsh}. In the present case, the binary
    544542file format \code{.msh} is used. See Section \ref{sec:file formats}
    545 for more on file formats.) \code{pmesh} assigns a name to the file
    546 by appending the extension \code{.msh} to the name specified in the
    547 input file \code{project.py}. This name is stored in the variable
     543(p. \pageref{sec:file formats}) for more on file formats.)
     544\code{pmesh} assigns a name to the file by appending the extension
     545\code{.msh} to the name specified in the input file
     546\code{project.py}. This name is stored in the variable
    548547\code{meshname}.
    549548
     
    699698\end{verbatim}}
    700699
     700%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     701%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     702
    701703\chapter{\anuga Public Interface}
    702704
    703 This chapter lists the functions and classes available at the public interface.
     705This chapter describes the features of \anuga that are available to
     706the user at the public interface.
    704707
    705708\section{Functions and Classes}
    706709
    707 \indexedcodeheader{create\_mesh\_from\_region}\label{codehdr:create\_mesh\_from\_region}
     710\indexedcodeheader{create\_mesh\_from\_regions}\label{codehdr:createmeshfromregions}
    708711
    709712  Creates a triangular mesh based on a bounding polygon and
     
    723726  \end{itemize}
    724727
    725 
    726 \indexedcodeheader{pmesh\_to\_domain\_instance}
     728*********************************************************************************************
     729
     730\emph{\textbf{[The following is how the description of
     731\emph{\code{create\_mesh\_from\_regions}} would be presented using
     732the Python documentation system's \emph{\code{funcdesc}} environment
     733for describing a module-level function.]}}
     734
     735\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
     736                             boundary_tags,
     737                             maximum_triangle_area,
     738                             filename=None,
     739                             interior_regions=None,
     740                             poly_geo_reference=None,
     741                             mesh_geo_reference=None,
     742                             minimum_triangle_angle=28.0}
     743Creates a triangular mesh based on a bounding polygon and a number
     744of internal polygons. For each polygon the user specifies a
     745resolution---that is, the maximal area of triangles in the mesh. The
     746bounding polygon also has symbolic \code{tags} associated with it.
     747\end{funcdesc}
     748
     749*********************************************************************************************
     750
     751\indexedcodeheader{pmesh\_to\_domain\_instance}  \nopagebreak
    727752
    728753 Converts a generated mesh file to a domain object.
     
    733758    \item \code{file\_name} is the name of the mesh file to convert, including the extension
    734759    \item \code{DomainClass} is the Class that will be returned.
    735     It must be a subclass of \code{Domain}, with the same interface as domain.
     760    It must be a subclass of \code{Domain}, with the same interface as
     761    domain. In practice, it can usually be set simply to
     762    \code{Domain}.
    736763    \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain.
    737764  \end{itemize}
     
    743770  \end{itemize}
    744771
    745 \indexedcodeheader{file\_function} %in util.py "High priority"
     772*********************************************************************************************
     773
     774\begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
     775Converts a generated mesh file to a domain object.
     776
     777\begin{itemize}
     778    \item \code{file\_name} is the name of the mesh file to convert, including the extension
     779    \item \code{DomainClass} is the Class that will be returned.
     780    It must be a subclass of \code{Domain}, with the same interface as
     781    domain. In practice, it can usually be set simply to
     782    \code{Domain}.
     783    \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain.
     784  \end{itemize}
     785\end{funcdesc}
     786*********************************************************************************************
     787
     788
     789%\indexedcodeheader{file\_function} %in util.py "High priority"
    746790
    747791  Reads the time history of spatial data from NetCDF file and returns a callable object.
     
    784828    \code{use\_cache}: \code{True} means that caching of intermediate result of
    785829               \code{Interpolation\_function} is attempted
     830
     831
     832  \begin{funcdesc}{file_function}{filename,
     833                  domain = None,
     834                  quantities = None,
     835                  interpolation_points = None,
     836                  verbose = False,
     837                  use_cache = False}
     838
     839  Reads the time history of spatial data from NetCDF file and returns a callable object. Returns
     840  interpolated values based on the input file
     841  using the underlying \code{interpolation\_function}.
     842
     843    \code{quantities} -- the name of the quantity to be interpolated or a
     844                 list of quantity names. The resulting function will return
     845                 a tuple of values -- one for each quantity.
     846
     847    \code{interpolation\_points} -- list of absolute UTM coordinates for points at
     848    which values are sought
     849
     850    \code{use\_cache}: \code{True} means that caching of intermediate result of
     851               \code{Interpolation\_function} is attempted
     852  \end{funcdesc}
    786853
    787854
     
    923990\label{sec:file formats}
    924991
    925 This module takes care of reading and writing datafiles such as
    926 topograhies, model output, etc
    927 
    928 
    929 Formats used within AnuGA:
    930 
    931 .sww: Netcdf format for storing model output f(t,x,y) .tms: Netcdf
    932 format for storing time series f(t)
    933 
    934 .xya: ASCII format for storing arbitrary points and associated
    935 attributes .pts: NetCDF format for storing arbitrary points and
    936 associated attributes
    937 
    938 .asc: ASCII format of regular DEMs as output from ArcView .prj:
    939 Associated ArcView file giving more meta data for asc format .ers:
    940 ERMapper header format of regular DEMs for ArcView
    941 
    942 .dem: NetCDF representation of regular DEM data
    943 
    944 .tsh: ASCII format for storing meshes and associated boundary and
    945 region info .msh: NetCDF format for storing meshes and associated
    946 boundary and region info
    947 
    948 .nc: Native ferret NetCDF format .geo: Houdinis ascii geometry
    949 format (?)
    950 
    951 
    952 A typical dataflow can be described as follows
    953 
    954 Manually created files: ASC, PRJ:     Digital elevation models
    955 (gridded) TSH:          Triangular meshes (e.g. created from pmesh)
    956 NC            Model outputs for use as boundary conditions (e.g from
    957 MOST)
    958 
    959 
    960 AUTOMATICALLY CREATED FILES:
    961 
    962 ASC, PRJ  ->  DEM  ->  PTS: Conversion of DEM's to native pts file
    963 
    964 NC -> SWW: Conversion of MOST bundary files to boundary sww
    965 
    966 PTS + TSH -> TSH with elevation: Least squares fit
    967 
    968 TSH -> SWW:  Conversion of TSH to sww viewable using Swollen
    969 
    970 TSH + Boundary SWW -> SWW: Simluation using pyvolution
    971 
     992\anuga makes use of a number of different file formats. The
     993following table lists all these formats, which are described in more
     994detail in the paragraphs below.
     995
     996\begin{tabular}{|ll|}  \hline
     997\code{.sww} & NetCDF format for storing model output
     998\code{f(t,x,y)}\\
     999
     1000\code{.tms} & NetCDF format for storing time series \code{f(t)}\\
     1001
     1002\code{.xya} & ASCII format for storing arbitrary points and
     1003associated attributes\\
     1004
     1005\code{.pts} & NetCDF format for storing arbitrary points and
     1006associated attributes\\
     1007
     1008\code{.asc} & ASCII format of regular DEMs as output from ArcView\\
     1009
     1010\code{.prj} & Associated ArcView file giving more metadata for
     1011\code{.asc} format\\
     1012
     1013\code{.ers} & ERMapper header format of regular DEMs for ArcView\\
     1014
     1015\code{.dem} & NetCDF representation of regular DEM data\\
     1016
     1017\code{.tsh} & ASCII format for storing meshes and associated
     1018boundary and region info\\
     1019
     1020\code{.msh} & NetCDF format for storing meshes and associated
     1021boundary and region info\\
     1022
     1023\code{.nc} & Native ferret NetCDF format\\
     1024
     1025\code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
     1026%\caption{File formats used by \anuga}
     1027\end{tabular}
     1028
     1029
     1030A typical dataflow can be described as follows:
     1031
     1032\subsection{Manually Created Files}
     1033
     1034\begin{tabular}{ll}
     1035ASC, PRJ & Digital elevation models (gridded)\\
     1036TSH & Triangular
     1037meshes (e.g. created from \code{pmesh})\\
     1038NC & Model outputs for use as boundary conditions (e.g. from MOST)
     1039\end{tabular}
     1040
     1041\subsection{Automatically Created Files}
     1042
     1043\begin{tabular}{ll}
     1044ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
     1045DEMs to native \code{.pts} file\\
     1046
     1047NC $\rightarrow$ SWW & Convert MOST boundary files to
     1048boundary \code{.sww}\\
     1049
     1050PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
     1051
     1052TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
     1053Swollen\\
     1054
     1055TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
     1056\code{pyvolution}
     1057\end{tabular}
    9721058
    9731059%\[
     
    12211307\chapter{Glossary}
    12221308
     1309\indexplacer{try it} \indexascode{try it out again}
     1310
    12231311\begin{itemize}
    12241312    \item \indexedbold{\anuga} Name of software (joint development between ANU and GA)
    12251313
    1226     \item \indexedbold{Conserved quantity}
    1227 
    1228     \item \indexedbold{Domain}
     1314    \item \indexedbold{domain}
    12291315
    12301316    \item \indexedbold{Dirichlet boundary}
    12311317
    1232     \item \indexedbold{Elevation} - refers to bathymetry and topography
    1233 
    1234     \item \indexedbold{Bathymetry} offshore
    1235 
    1236     \item \indexedbold{Topography} onshore
    1237 
    1238     \item \indexedbold{Evolution} integration of the shallow water wave equations over time
    1239 
    1240     \item \indexedbold{Forcing term}
     1318    \item \indexedbold{elevation} - refers to bathymetry and topography
     1319
     1320    \item \indexedbold{bathymetry} offshore
     1321
     1322    \item \indexedbold{topography} onshore
     1323
     1324    \item \indexedbold{evolution} integration of the shallow water wave equations over time
     1325
     1326    \item \indexedbold{forcing term}
    12411327
    12421328    \item \indexedbold{IDLE} Development environment shipped with Python
     
    12441330    \item \indexedbold{Manning friction coefficient}
    12451331
    1246     \item \indexedbold{Mesh}    Triangulation of domain
    1247 
    1248     \item \indexedbold{Meshfile}  [generic word for either .tsh or
     1332    \item \indexedbold{mesh}    Triangulation of domain
     1333
     1334    \item \indexedbold{meshfile}  [generic word for either .tsh or
    12491335    .msh file]
    12501336
    1251     \item \indexedbold{Points file}  [generic word for either .pts or
     1337    \item \indexedbold{points file}  [generic word for either .pts or
    12521338    .xya file]
    12531339
    1254     \item \indexedbold{Grid} evenly spaced
     1340    \item \indexedbold{grid} evenly spaced
    12551341
    12561342    \item \indexedbold{NetCDF}
     
    12601346    \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?
    12611347
    1262     \item \indexedbold{Conserved Quantity} conserved (state, x and y momentum)
    1263 
    1264     \item \indexedbold{Reflective boundary}
    1265 
    1266     \item \indexedbold{Smoothing} is this really needed?
    1267 
    1268     \item \indexedbold{Stage}
    1269 
    1270     \item \indexedbold{Swollen} visualisation tool
    1271 
    1272     \item \indexedbold{Time boundary} defined in the manual (flog from there)
    1273 
    1274     \item \indexedbold{Transmissive boundary} defined in the manual (flog from there)
     1348    \item \indexedbold{conserved quantity} conserved (state, x and y momentum)
     1349
     1350    \item \indexedbold{reflective boundary}
     1351
     1352    \item \indexedbold{smoothing} is this really needed?
     1353
     1354    \item \indexedbold{stage}
     1355
     1356%    \item \indexedbold{try this}
     1357
     1358    \item \indexedbold{swollen} visualisation tool
     1359
     1360    \item \indexedbold{time boundary} defined in the manual (flog from there)
     1361
     1362    \item \indexedbold{transmissive boundary} defined in the manual (flog from there)
    12751363
    12761364    \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
     
    12781366    \item \indexedbold{ymomentum}  conserved quantity
    12791367
    1280     \item \indexedbold{Resolution}   The maximal area of a triangular cell in a mesh
    1281 
    1282     \item \indexedbold{Polygon} A sequence of points in the plane. (Arbitrary polygons can be created
     1368    \item \indexedbold{resolution}   The maximal area of a triangular cell in a mesh
     1369
     1370    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created
    12831371    in this way.)
    12841372    \anuga represents a polygon in one of two ways. One way is to represent it as a
     
    12911379    NOTE: More can be read in the module utilities/polygon.py ....
    12921380
    1293     \item \indexedbold{Easting}
    1294 
    1295     \item \indexedbold{Northing}
    1296 
    1297     \item \indexedbold{Latitude}
    1298 
    1299     \item \indexedbold{Longitude}
    1300 
    1301     \item \indexedbold{Edge}
    1302 
    1303     \item \indexedbold{Vertex}
    1304 
    1305     \item \indexedbold{Finite volume}
    1306 
    1307     \item \indexedbold{Flux}
     1381    \item \indexedbold{easting}
     1382
     1383    \item \indexedbold{northing}
     1384
     1385    \item \indexedbold{latitude}
     1386
     1387    \item \indexedbold{longitude}
     1388
     1389    \item \indexedbold{edge}
     1390
     1391    \item \indexedbold{vertex}
     1392
     1393    \item \indexedbold{finite volume}
     1394
     1395    \item \indexedbold{flux}
    13081396
    13091397    \item \indexedbold{Digital Elevation Model (DEM)}
Note: See TracChangeset for help on using the changeset viewer.