Ignore:
Timestamp:
Jun 14, 2010, 8:00:01 PM (14 years ago)
Author:
hudson
Message:

Updated user manual to version 1.2 - did spell check.

Location:
trunk/anuga_core/documentation/user_manual
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/anuga_core/documentation/user_manual/anuga_user_manual.tex

    r7804 r7828  
    1 % Complete documentation on the extended LaTeX markup used for Python
     1% Complete documentation on the extended LaTeX markup used for Python
    22% documentation is available in ''Documenting Python'', which is part
    33% of the standard documentation for Python.  It may be found online
    … …  
    4747% the rest is at your discretion.
    4848\authoraddress{Geoscience Australia \\
    49   Email: \email{ole.nielsen@ga.gov.au}
     49  Email: \email{nariman.habili@ga.gov.au}
    5050}
    5151
    … …  
    7171                % update_anuga_user_manual.py - if not a dummy
    7272                % will be used.
    73 
    74 %\release{1.2}   % release version; this is used to define the
    75 %                % \version macro
    7673
    7774\makeindex          % tell \index to actually write the .idx file
    … …  
    147144where the more adventurous reader might like to go.
    148145
    149 This manual describes \anuga version 1.2. To check for later versions of this manual
     146This manual describes \anuga version \version. To check for later versions of this manual
    150147go to \url{https://datamining.anu.edu.au/anuga}.
    151148
    … …  
    153150
    154151This manual covers only what is needed to operate the software after
    155 installation and configuration. It does not includes instructions
     152installation and configuration. It does not include instructions
    156153for installing the software or detailed API documentation, both of
    157154which will be covered in separate publications and by documentation
    … …  
    632629contains stage and momentum information and can be used with the
    633630\anuga viewer \code{anuga\_viewer} to generate a visual
    634 display (see Section \ref{sec:animate}). See Section \ref{sec:file formats}
     631display (see Section \ref{sec:anuga_viewer}). See Section \ref{sec:file formats}
    635632(page \pageref{sec:file formats}) for more on NetCDF and other file
    636633formats.
    … …  
    657654
    658655The following figures are screenshots from the \anuga visualisation
    659 tool \code{animate}. Figure \ref{fig:runupstart} shows the domain
     656tool \code{anuga_viewer}. Figure \ref{fig:runupstart} shows the domain
    660657with water surface as specified by the initial condition, $t=0$.
    661658Figure \ref{fig:runup2} shows later snapshots for $t=2.3$ and
    … …  
    663660on the previously dry bed.
    664661
    665 \code{animate} is described in more detail in Section \ref{sec:animate}.
     662\code{anuga_viewer} is described in more detail in Section \ref{sec:anuga_viewer}.
    666663
    667664\begin{figure}[htp]
    … …  
    689686\subsection{Overview}
    690687
    691 The next example is about waterflow in a channel with varying boundary conditions and
     688The next example is about water-flow in a channel with varying boundary conditions and
    692689more complex topographies. These examples build on the
    693690concepts introduced through the \file{runup.py} in Section \ref{sec:simpleexample}.
    … …  
    735732Defining \code{m} and \code{n} in terms of the extent as in this example provides a convenient way of
    736733controlling the resolution: By defining \code{dx} and \code{dy} to be the desired size of each
    737 hypothenuse in the mesh we can write the mesh generation as follows:
     734hypotenuse in the mesh we can write the mesh generation as follows:
    738735
    739736\begin{verbatim}
    … …  
    760757
    761758The following figure is a screenshot from the \anuga visualisation
    762 tool \code{animate} of output from this example.
     759tool \code{anuga_viewer} of output from this example.
    763760
    764761\begin{figure}[htp]
    … …  
    823820\end{verbatim}
    824821
    825 \subsection{Flow through more complex topograhies}
     822\subsection{Flow through more complex topographies}
    826823
    827824Here is the code for the third version of the channel flow \file{channel3.py}:
    … …  
    12261223
    12271224Now that the scenario has been run, the user can view the output in a number of ways.
    1228 As described earlier, the user may run \code{animate} to view a three-dimensional representation
     1225As described earlier, the user may run \code{anuga_viewer} to view a three-dimensional representation
    12291226of the simulation.
    12301227
    … …  
    13091306Elford Reef location for each scenario (the elevation at this location is negative,
    13101307therefore stage is the more appropriate quantity to plot). Note the large negative stage value when the slide was
    1311 introduced. This is due to the double gaussian form of the initial surface
     1308introduced. This is due to the double Gaussian form of the initial surface
    13121309displacement of the slide. By contrast, the time series for depth is shown for the onshore location of the Cairns
    13131310Airport in Figure \ref{fig:airportboth}.
    … …  
    13461343\end{itemize}
    13471344
    1348 The listings are intended merely to give the reader an idea of what
    1349 each feature is, where to find it and how it can be used -- they do
     1345\section{Documentation}\index{Documentation}
     1346
     1347The listings here are intended merely to give the reader an idea of what
     1348each feature is and how it can be used -- they do
    13501349not give full specifications; for these the reader
    1351 may consult the code. The code for every function or class contains
     1350may consult the programmer's guide. The code for every function or class contains
    13521351a documentation string, or 'docstring', that specifies the precise
    13531352syntax for its use. This appears immediately after the line
    13541353introducing the code, between two sets of triple quotes.
    13551354
    1356 Each listing also describes the location of the module in which
    1357 the code for the feature being described can be found. All modules
    1358 are in the folder \file{inundation} or one of its subfolders, and the
     1355Python has a handy tool that lets you easily navigate this documentation,
     1356called \code{pydoc}. In Linux, it runs as a server, which serves the
     1357documentation up to your web browser:
     1358
     13591. Open a terminal at your \code{anuga_source/anuga} folder
     13602. Start the python documentation server with \code{pydoc -p 6767}
     13613. Open a browser and type in \code{http://localhost:6767/}
     1362
     1363Now you have a real-time programmers' guide for \anuga, and an easy way to find
     1364the functions you are interested in. Pydoctor and other Python doc generators
     1365look nicer and have graphs, etc, but pydoc works straight out of the box.
     1366
     1367\section{Public vs Private Interface}\index{public vs private interface}
     1368
     1369To simplify the process of writing scripts, \anuga has a public API which packages
     1370up all the commonly-used functionality of \anuga in the one place. To use it, simply
     1371import the anuga module like so:
     1372
     1373\begin{verbatim}
     1374import anuga
     1375\end{verbatim}
     1376
     1377You can now use the public API like so. Note the \code{anuga.} prefix:
     1378
     1379\begin{verbatim}
     1380anuga.sww2dem('in.sww', 'out.asc')
     1381\end{verbatim}
     1382
     1383If you wish to delve "under the hood" and modify the way \anuga runs at a more
     1384advanced level, you need to specify the full location of the module like so:
     1385
     1386\begin{verbatim}
     1387from anuga.fit_interpolate.interpolate import Interpolation_interface
     1388\end{verbatim}
     1389
     1390All modules are in the folder \file{inundation} or one of its subfolders, and the
    13591391location of each module is described relative to \file{inundation}. Rather
    13601392than using pathnames, whose syntax depends on the operating system,
    … …  
    13781410
    13791411Rather than using either of these forms, in this chapter we specify
    1380 the location simply as \code{pmesh.mesh_interface}, in keeping with
     1412the location simply as \code{anuga.pmesh.mesh_interface}, in keeping with
    13811413the usage in the Python statement for importing the function,
    13821414namely:
    13831415
    13841416\begin{verbatim}
    1385 from pmesh.mesh_interface import create_mesh_from_regions
    1386 \end{verbatim}
    1387 
    1388 Each listing details the full set of parameters for the class or
    1389 function; however, the description is generally limited to the most
    1390 important parameters and the reader is again referred to the code
    1391 for more details.
     1417from anuga.pmesh.mesh_interface import create_mesh_from_regions
     1418\end{verbatim}
     1419
    13921420
    13931421The following parameters are common to many functions and classes
    … …  
    14881516
    14891517\begin{funcdesc}{create_mesh_from_regions}{bounding_polygon,
    1490                                            boundary_tags,
    1491                                            maximum_triangle_area=None,
    1492                                            filename=None,
    1493                                            interior_regions=None,
    1494                                            interior_holes=None,
    1495                                            poly_geo_reference=None,
    1496                                            mesh_geo_reference=None,
    1497                                            minimum_triangle_angle=28.0,
    1498                                            fail_if_polygons_outside=True,
    1499                                            use_cache=False,
    1500                                            verbose=True}
     1518                                             boundary_tags,
     1519                                             maximum_triangle_area=None,
     1520                                             filename=None,
     1521                                             interior_regions=None,
     1522                                             interior_holes=None,
     1523                                             hole_tags=None,
     1524                                             poly_geo_reference=None,
     1525                                             mesh_geo_reference=None,
     1526                                             minimum_triangle_angle=28.0,
     1527                                             fail_if_polygons_outside=True,
     1528                                             breaklines=None,
     1529                                             use_cache=False,
     1530                                             verbose=True}
    15011531Module: \module{pmesh.mesh\_interface}
    15021532
    … …  
    15101540interior polygon and its resolution.  Additionally, the user specifies
    15111541a list of boundary tags, one for each edge of the bounding polygon.
     1542
     1543\code{breaklines} lets you force a split along a boundary within the mesh. For
     1544example, a kerb or the edge of a dyke could be specified here. (new in 1.2)
     1545
     1546\code{interior_holes} lets you specify polygons as empty holes in the mesh.
     1547This can be used  to represent buildings, pylons and other immovable
     1548structures. These polygons do not need to be closed, but their points must be
     1549specified in a counter-clockwise order.(new in 1.2)
    15121550
    15131551\textbf{WARNING}. Note that the dictionary structure used for the
    … …  
    15231561
    15241562\textbf{WARNING}. Do not have polygon lines cross or be on-top of each
    1525     other. This can result in regions of unspecified resolutions. Do
     1563    other. This can result in regions of unspecified resolutions, and \anuga
     1564    will give you an error. Do
    15261565    not have polygon close to each other. This can result in the area
    15271566    between the polygons having small triangles.  For more control
    … …  
    15591598\code{maximum_triangle_area} is the maximal area per triangle
    15601599for the bounding polygon, excluding the interior regions.
     1600
     1601\code{interior_holes} lets you specify polygons as empty holes in the mesh.
     1602This can be used  to represent buildings, pylons and other immovable
     1603structures. These polygons do not need to be closed, but their points must be
     1604specified in a counter-clockwise order.(new in 1.2)
    15611605
    15621606\code{mesh_filename} is the name of the file to contain the generated
    … …  
    21632207
    21642208# Add buildings from file
    2165 building_polygons, building_heights = csv2building_polygons(building_file)
     2209building_polygons, building_heights = anuga.load_csv_as_building_polygons(building_file)
    21662210
    21672211B = []
    … …  
    22242268                                time_limit=None,
    22252269                                verbose=False,
     2270                                output_centroids=False,
    22262271                                use_cache=False,
    22272272                                boundary_polygon=None}
    … …  
    22492294This must be the same polygon as used when calling \code{create_mesh_from_regions()}.
    22502295This argument can only be used when reading boundary data from an STS format file.
     2296
     2297\code{output_centroids} set to true to sample at the centre of the triangle containing the point.
     2298This may be useful for debugging. (new in 1.2)
    22512299
    22522300The model time stored within the file function can be accessed using
    … …  
    27012749\end{itemize}
    27022750
    2703 The user can specify different culvert routines. Hower \anuga currently provides only one, namely the
     2751The user can specify different culvert routines. However, \anuga currently provides only one, namely the
    27042752\code{boyd_generalised_culvert_model} as used in the example below:
    27052753
    … …  
    31123160                                 time_min=None,
    31133161                                 time_max=None,
     3162                                 output_centroids=False,
    31143163                                 time_thinning=1,
    31153164                                 time_unit=None,
    … …  
    31353184
    31363185\code{filename} is the path to the SWW file.
     3186
     3187\code{output_centroids} set to true to sample at the centre of the triangle containing the point.
     3188This may be useful for debugging. (new in 1.2)
    31373189
    31383190\code{polyline} is the representation of the desired cross section -- it may contain
    … …  
    32353287  NC $\rightarrow$ SWW & Convert MOST boundary files to boundary \code{.sww}\\
    32363288  PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
    3237   TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using \code{animate}\\
     3289  TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using \code{anuga_viewer}\\
    32383290  TSH + Boundary SWW $\rightarrow$ SWW & Simulation using \code{\anuga}\\
    32393291  Polygonal mesh outline $\rightarrow$ & TSH or MSH
    … …  
    32593311\end{itemize}
    32603312
    3261 The contents of an SWW file may be viewed using the anuga viewer \code{animate},
    3262 which creates an on-screen visialisation.  See section \ref{sec:animate}
    3263 (page \pageref{sec:animate}) in Appendix \ref{ch:supportingtools} for more on \code{animate}.
     3313The contents of an SWW file may be viewed using the anuga viewer \code{anuga_viewer},
     3314which creates an on-screen visualisation.  See section \ref{sec:anuga_viewer}
     3315(page \pageref{sec:anuga_viewer}) in Appendix \ref{ch:supportingtools} for more on \code{anuga_viewer}.
    32643316
    32653317Alternatively, there are tools, such as \code{ncdump}, that allow
    … …  
    36173669
    36183670In the computations presented in this paper we use an explicit Euler
    3619 time stepping method with variable timestepping adapted to the
     3671timestepping method with variable timestepping adapted to the
    36203672observed CFL condition:
    36213673
    … …  
    36423694To alleviate the problems associated with numerical instabilities due to
    36433695small water depths near a wet/dry boundary we employ a new flux limiter that
    3644 ensures that unphysical fluxes are never encounted.
     3696ensures that unphysical fluxes are never encountered.
    36453697
    36463698Let $u$ and $v$ be the velocity components in the $x$ and $y$ direction,
    … …  
    36903742  h_0 = H_0^2
    36913743\]
    3692 provides a reasonable balance between accurracy and stability. In fact,
     3744provides a reasonable balance between accuracy and stability. In fact,
    36933745setting $h=H_0$ will scale the predicted speed by a factor of $0.5$:
    36943746\[
    … …  
    38763928%%
    38773929%
    3878 %Sub directories contain scrips and derived files for each simulation.
     3930%Sub directories contain scripts and derived files for each simulation.
    38793931%The directory ../source_data contains large source files such as
    38803932%DEMs provided externally as well as MOST tsunami simulations to be used
    … …  
    38823934%
    38833935%Manual steps are:
    3884 %  Creation of DEMs from argcview (.asc + .prj)
     3936%  Creation of DEMs from arcview (.asc + .prj)
    38853937%  Creation of mesh from pmesh (.tsh)
    38863938%  Creation of tsunami simulations from MOST (.nc)
    … …  
    39674019\pagebreak
    39684020\section{anuga\_viewer}
    3969 \label{sec:animate}
     4021\label{sec:anuga_viewer}
    39704022
    39714023The output generated by \anuga may be viewed by
    … …  
    39894041%\code{anuga\_viewer} executable file (or a shortcut to it), or set up a
    39904042%file association to make files with the extension \code{.sww} open
    3991 %with \code{animate}. Alternatively, you can operate \code{animate}
     4043%with \code{anuga_viewer}. Alternatively, you can operate \code{anuga_viewer}
    39924044%from the command line.
    39934045
    … …  
    39964048
    39974049%% \pagebreak
    3998 %% \section{\anuga viewer -- animate}
    3999 %% \label{sec:animate}
     4050%% \section{\anuga viewer -- anuga_viewer}
     4051%% \label{sec:anuga_viewer}
    40004052
    40014053%% The output generated by \anuga may be viewed by
    4002 %% means of the visualisation tool \code{animate}, which takes an
     4054%% means of the visualisation tool \code{anuga_viewer}, which takes an
    40034055%% SWW file generated by \anuga and creates a visual representation
    40044056%% of the data. Examples may be seen in Figures \ref{fig:runupstart}
    40054057%% and \ref{fig:runup2}. To view an SWW file with
    4006 %% \code{animate} in the Windows environment, you can simply drag the
     4058%% \code{anuga_viewer} in the Windows environment, you can simply drag the
    40074059%% icon representing the file over an icon on the desktop for the
    4008 %% \code{animate} executable file (or a shortcut to it), or set up a
     4060%% \code{anuga_viewer} executable file (or a shortcut to it), or set up a
    40094061%% file association to make files with the extension \code{.sww} open
    4010 %% with \code{animate}. Alternatively, you can operate \code{animate}
     4062%% with \code{anuga_viewer}. Alternatively, you can operate \code{anuga_viewer}
    40114063%% from the command line.
    40124064
    … …  
    40344086%% % \vfill
    40354087
    4036 %% The following describes how to operate \code{animate} from the command line:
    4037 
    4038 %% Usage: \code{animate [options] swwfile \ldots}\\ \nopagebreak
     4088%% The following describes how to operate \code{anuga_viewer} from the command line:
     4089
     4090%% Usage: \code{anuga_viewer [options] swwfile \ldots}\\ \nopagebreak
    40394091%% where: \\ \nopagebreak
    40404092%% \begin{tabular}{ll}
    … …  
    49745026  \indexedbold{stage} & &\\
    49755027%  \indexedbold{try this}
    4976   \indexedbold{animate} & visualisation tool used with \anuga & \pageref{sec:animate}\\
     5028  \indexedbold{anuga_viewer} & visualisation tool used with \anuga & \pageref{sec:anuga_viewer}\\
    49775029  \indexedbold{time boundary} & Returns values for the conserved quantities as a function of time.
    49785030                                The user must specify the domain to get access to the model time.

  • trunk/anuga_core/documentation/user_manual/copyright.tex

    r7809 r7828  
    1919\vspace*{0.5in}
    2020
    21 Copyright \copyright 2004, 2005, 2006 Australian National University and Geoscience Australia. All rights reserved.
     21Copyright \copyright 2004, 2005, 2006, 2010 Australian National University and Geoscience Australia. All rights reserved.
    2222
    2323Permission to use, copy, modify, and distribute this software for any
    … …  
    134134\pagebreak
    135135\item Pmw is a toolkit for building high-level compound widgets in
    136 Python using the Tkinter module. Parts of Pmw have been encorpoated
     136Python using the Tkinter module. Parts of Pmw have been incorpoated
    137137into the graphical mesh generator. The license for Pmw reads
    138138
Note: See TracChangeset for help on using the changeset viewer.