# Changeset 7828 for trunk/anuga_core/documentation/user_manual/anuga_user_manual.tex

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

Updated user manual to version 1.2 - did spell check.

File:
1 edited

### Legend:

Unmodified
 r7804 % Complete documentation on the extended LaTeX markup used for Python ﻿% Complete documentation on the extended LaTeX markup used for Python % documentation is available in ''Documenting Python'', which is part % of the standard documentation for Python.  It may be found online % the rest is at your discretion. \authoraddress{Geoscience Australia \\ Email: \email{ole.nielsen@ga.gov.au} Email: \email{nariman.habili@ga.gov.au} } % update_anuga_user_manual.py - if not a dummy % will be used. %\release{1.2}   % release version; this is used to define the %                % \version macro \makeindex          % tell \index to actually write the .idx file where the more adventurous reader might like to go. This manual describes \anuga version 1.2. To check for later versions of this manual This manual describes \anuga version \version. To check for later versions of this manual go to \url{https://datamining.anu.edu.au/anuga}. This manual covers only what is needed to operate the software after installation and configuration. It does not includes instructions installation and configuration. It does not include instructions for installing the software or detailed API documentation, both of which will be covered in separate publications and by documentation contains stage and momentum information and can be used with the \anuga viewer \code{anuga\_viewer} to generate a visual display (see Section \ref{sec:animate}). See Section \ref{sec:file formats} display (see Section \ref{sec:anuga_viewer}). See Section \ref{sec:file formats} (page \pageref{sec:file formats}) for more on NetCDF and other file formats. The following figures are screenshots from the \anuga visualisation tool \code{animate}. Figure \ref{fig:runupstart} shows the domain tool \code{anuga_viewer}. Figure \ref{fig:runupstart} shows the domain with water surface as specified by the initial condition, $t=0$. Figure \ref{fig:runup2} shows later snapshots for $t=2.3$ and on the previously dry bed. \code{animate} is described in more detail in Section \ref{sec:animate}. \code{anuga_viewer} is described in more detail in Section \ref{sec:anuga_viewer}. \begin{figure}[htp] \subsection{Overview} The next example is about waterflow in a channel with varying boundary conditions and The next example is about water-flow in a channel with varying boundary conditions and more complex topographies. These examples build on the concepts introduced through the \file{runup.py} in Section \ref{sec:simpleexample}. Defining \code{m} and \code{n} in terms of the extent as in this example provides a convenient way of controlling the resolution: By defining \code{dx} and \code{dy} to be the desired size of each hypothenuse in the mesh we can write the mesh generation as follows: hypotenuse in the mesh we can write the mesh generation as follows: \begin{verbatim} The following figure is a screenshot from the \anuga visualisation tool \code{animate} of output from this example. tool \code{anuga_viewer} of output from this example. \begin{figure}[htp] \end{verbatim} \subsection{Flow through more complex topograhies} \subsection{Flow through more complex topographies} Here is the code for the third version of the channel flow \file{channel3.py}: Now that the scenario has been run, the user can view the output in a number of ways. As described earlier, the user may run \code{animate} to view a three-dimensional representation As described earlier, the user may run \code{anuga_viewer} to view a three-dimensional representation of the simulation. Elford Reef location for each scenario (the elevation at this location is negative, therefore stage is the more appropriate quantity to plot). Note the large negative stage value when the slide was introduced. This is due to the double gaussian form of the initial surface introduced. This is due to the double Gaussian form of the initial surface displacement of the slide. By contrast, the time series for depth is shown for the onshore location of the Cairns Airport in Figure \ref{fig:airportboth}. \end{itemize} The listings are intended merely to give the reader an idea of what each feature is, where to find it and how it can be used -- they do \section{Documentation}\index{Documentation} The listings here are intended merely to give the reader an idea of what each feature is and how it can be used -- they do not give full specifications; for these the reader may consult the code. The code for every function or class contains may consult the programmer's guide. The code for every function or class contains a documentation string, or 'docstring', that specifies the precise syntax for its use. This appears immediately after the line introducing the code, between two sets of triple quotes. Each listing also describes the location of the module in which the code for the feature being described can be found. All modules are in the folder \file{inundation} or one of its subfolders, and the Python has a handy tool that lets you easily navigate this documentation, called \code{pydoc}. In Linux, it runs as a server, which serves the documentation up to your web browser: 1. Open a terminal at your \code{anuga_source/anuga} folder 2. Start the python documentation server with \code{pydoc -p 6767} 3. Open a browser and type in \code{http://localhost:6767/} Now you have a real-time programmers' guide for \anuga, and an easy way to find the functions you are interested in. Pydoctor and other Python doc generators look nicer and have graphs, etc, but pydoc works straight out of the box. \section{Public vs Private Interface}\index{public vs private interface} To simplify the process of writing scripts, \anuga has a public API which packages up all the commonly-used functionality of \anuga in the one place. To use it, simply import the anuga module like so: \begin{verbatim} import anuga \end{verbatim} You can now use the public API like so. Note the \code{anuga.} prefix: \begin{verbatim} anuga.sww2dem('in.sww', 'out.asc') \end{verbatim} If you wish to delve "under the hood" and modify the way \anuga runs at a more advanced level, you need to specify the full location of the module like so: \begin{verbatim} from anuga.fit_interpolate.interpolate import Interpolation_interface \end{verbatim} All modules are in the folder \file{inundation} or one of its subfolders, and the location of each module is described relative to \file{inundation}. Rather than using pathnames, whose syntax depends on the operating system, Rather than using either of these forms, in this chapter we specify the location simply as \code{pmesh.mesh_interface}, in keeping with the location simply as \code{anuga.pmesh.mesh_interface}, in keeping with the usage in the Python statement for importing the function, namely: \begin{verbatim} from pmesh.mesh_interface import create_mesh_from_regions \end{verbatim} Each listing details the full set of parameters for the class or function; however, the description is generally limited to the most important parameters and the reader is again referred to the code for more details. from anuga.pmesh.mesh_interface import create_mesh_from_regions \end{verbatim} The following parameters are common to many functions and classes \begin{funcdesc}{create_mesh_from_regions}{bounding_polygon, boundary_tags, maximum_triangle_area=None, filename=None, interior_regions=None, interior_holes=None, poly_geo_reference=None, mesh_geo_reference=None, minimum_triangle_angle=28.0, fail_if_polygons_outside=True, use_cache=False, verbose=True} boundary_tags, maximum_triangle_area=None, filename=None, interior_regions=None, interior_holes=None, hole_tags=None, poly_geo_reference=None, mesh_geo_reference=None, minimum_triangle_angle=28.0, fail_if_polygons_outside=True, breaklines=None, use_cache=False, verbose=True} Module: \module{pmesh.mesh\_interface} interior polygon and its resolution.  Additionally, the user specifies a list of boundary tags, one for each edge of the bounding polygon. \code{breaklines} lets you force a split along a boundary within the mesh. For example, a kerb or the edge of a dyke could be specified here. (new in 1.2) \code{interior_holes} lets you specify polygons as empty holes in the mesh. This can be used  to represent buildings, pylons and other immovable structures. These polygons do not need to be closed, but their points must be specified in a counter-clockwise order.(new in 1.2) \textbf{WARNING}. Note that the dictionary structure used for the \textbf{WARNING}. Do not have polygon lines cross or be on-top of each other. This can result in regions of unspecified resolutions. Do other. This can result in regions of unspecified resolutions, and \anuga will give you an error. Do not have polygon close to each other. This can result in the area between the polygons having small triangles.  For more control \code{maximum_triangle_area} is the maximal area per triangle for the bounding polygon, excluding the interior regions. \code{interior_holes} lets you specify polygons as empty holes in the mesh. This can be used  to represent buildings, pylons and other immovable structures. These polygons do not need to be closed, but their points must be specified in a counter-clockwise order.(new in 1.2) \code{mesh_filename} is the name of the file to contain the generated # Add buildings from file building_polygons, building_heights = csv2building_polygons(building_file) building_polygons, building_heights = anuga.load_csv_as_building_polygons(building_file) B = [] time_limit=None, verbose=False, output_centroids=False, use_cache=False, boundary_polygon=None} This must be the same polygon as used when calling \code{create_mesh_from_regions()}. This argument can only be used when reading boundary data from an STS format file. \code{output_centroids} set to true to sample at the centre of the triangle containing the point. This may be useful for debugging. (new in 1.2) The model time stored within the file function can be accessed using \end{itemize} The user can specify different culvert routines. Hower \anuga currently provides only one, namely the The user can specify different culvert routines. However, \anuga currently provides only one, namely the \code{boyd_generalised_culvert_model} as used in the example below: time_min=None, time_max=None, output_centroids=False, time_thinning=1, time_unit=None, \code{filename} is the path to the SWW file. \code{output_centroids} set to true to sample at the centre of the triangle containing the point. This may be useful for debugging. (new in 1.2) \code{polyline} is the representation of the desired cross section -- it may contain NC $\rightarrow$ SWW & Convert MOST boundary files to boundary \code{.sww}\\ PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\ TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using \code{animate}\\ TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using \code{anuga_viewer}\\ TSH + Boundary SWW $\rightarrow$ SWW & Simulation using \code{\anuga}\\ Polygonal mesh outline $\rightarrow$ & TSH or MSH \end{itemize} The contents of an SWW file may be viewed using the anuga viewer \code{animate}, which creates an on-screen visialisation.  See section \ref{sec:animate} (page \pageref{sec:animate}) in Appendix \ref{ch:supportingtools} for more on \code{animate}. The contents of an SWW file may be viewed using the anuga viewer \code{anuga_viewer}, which creates an on-screen visualisation.  See section \ref{sec:anuga_viewer} (page \pageref{sec:anuga_viewer}) in Appendix \ref{ch:supportingtools} for more on \code{anuga_viewer}. Alternatively, there are tools, such as \code{ncdump}, that allow In the computations presented in this paper we use an explicit Euler time stepping method with variable timestepping adapted to the timestepping method with variable timestepping adapted to the observed CFL condition: To alleviate the problems associated with numerical instabilities due to small water depths near a wet/dry boundary we employ a new flux limiter that ensures that unphysical fluxes are never encounted. ensures that unphysical fluxes are never encountered. Let $u$ and $v$ be the velocity components in the $x$ and $y$ direction, h_0 = H_0^2 \] provides a reasonable balance between accurracy and stability. In fact, provides a reasonable balance between accuracy and stability. In fact, setting $h=H_0$ will scale the predicted speed by a factor of $0.5$: \[ %% % %Sub directories contain scrips and derived files for each simulation. %Sub directories contain scripts and derived files for each simulation. %The directory ../source_data contains large source files such as %DEMs provided externally as well as MOST tsunami simulations to be used % %Manual steps are: %  Creation of DEMs from argcview (.asc + .prj) %  Creation of DEMs from arcview (.asc + .prj) %  Creation of mesh from pmesh (.tsh) %  Creation of tsunami simulations from MOST (.nc) \pagebreak \section{anuga\_viewer} \label{sec:animate} \label{sec:anuga_viewer} The output generated by \anuga may be viewed by %\code{anuga\_viewer} executable file (or a shortcut to it), or set up a %file association to make files with the extension \code{.sww} open %with \code{animate}. Alternatively, you can operate \code{animate} %with \code{anuga_viewer}. Alternatively, you can operate \code{anuga_viewer} %from the command line. %% \pagebreak %% \section{\anuga viewer -- animate} %% \label{sec:animate} %% \section{\anuga viewer -- anuga_viewer} %% \label{sec:anuga_viewer} %% The output generated by \anuga may be viewed by %% means of the visualisation tool \code{animate}, which takes an %% means of the visualisation tool \code{anuga_viewer}, which takes an %% SWW file generated by \anuga and creates a visual representation %% of the data. Examples may be seen in Figures \ref{fig:runupstart} %% and \ref{fig:runup2}. To view an SWW file with %% \code{animate} in the Windows environment, you can simply drag the %% \code{anuga_viewer} in the Windows environment, you can simply drag the %% icon representing the file over an icon on the desktop for the %% \code{animate} executable file (or a shortcut to it), or set up a %% \code{anuga_viewer} executable file (or a shortcut to it), or set up a %% file association to make files with the extension \code{.sww} open %% with \code{animate}. Alternatively, you can operate \code{animate} %% with \code{anuga_viewer}. Alternatively, you can operate \code{anuga_viewer} %% from the command line. %% % \vfill %% The following describes how to operate \code{animate} from the command line: %% Usage: \code{animate [options] swwfile \ldots}\\ \nopagebreak %% The following describes how to operate \code{anuga_viewer} from the command line: %% Usage: \code{anuga_viewer [options] swwfile \ldots}\\ \nopagebreak %% where: \\ \nopagebreak %% \begin{tabular}{ll} \indexedbold{stage} & &\\ %  \indexedbold{try this} \indexedbold{animate} & visualisation tool used with \anuga & \pageref{sec:animate}\\ \indexedbold{anuga_viewer} & visualisation tool used with \anuga & \pageref{sec:anuga_viewer}\\ \indexedbold{time boundary} & Returns values for the conserved quantities as a function of time. The user must specify the domain to get access to the model time.