Changeset 5956

Timestamp:

Nov 13, 2008, 2:51:12 PM (16 years ago)

Author:

rwilson

Message:

Removed FAQ, left pointer to online FAQ.

File:

• anuga_core/documentation/user_manual/anuga_user_manual.tex (modified) (1 diff)

anuga_core/documentation/user_manual/anuga_user_manual.tex

@@ -4303 +4303 @@
 \chapter{Frequently Asked Questions}
 
-
-\section{General Questions}
-
-\subsubsection{What is \anuga?}
-It is a software package suitable for simulating 2D water flows in
-complex geometries.
-
-\subsubsection{Why is it called \anuga?}
-The software was developed in collaboration between the
-Australian National University (ANU) and Geoscience Australia (GA).
-
-\subsubsection{How do I obtain a copy of \anuga?}
-See \url{https://datamining.anu.edu.au/anuga} for all things ANUGA.
-
-%\subsubsection{What developments are expected for \anuga in the future?}
-%This
-
-\subsubsection{Are there any published articles about \anuga that I can reference?}
-See \url{https://datamining.anu.edu.au/anuga} for links.
-
-
-\subsubsection{How do I find out what version of \anuga I am running?}
-Use the following code snippet
-\begin{verbatim}
-from anuga.utilities.system_tools import get_revision_number
-print get_revision_number()
-\end{verbatim}
-This should work both for installations from SourceForge as well as when working off the repository.
-
-
-
-
-\section{Modelling Questions}
-
-\subsubsection{Which type of problems are \anuga good for?}
-General 2D waterflows in complex geometries such as
-dam breaks, flows amoung structurs, coastal inundation etc.
-
-\subsubsection{Which type of problems are beyond the scope of \anuga?}
-See Chapter \ref{ch:limitations}.
-
-\subsubsection{Can I start the simulation at an arbitrary time?}
-Yes, using \code{domain.set\_time()} you can specify an arbitrary
-starting time. This is for example useful in conjunction with a
-file\_boundary, which may start hours before anything hits the model
-boundary. By assigning a later time for the model to start,
-computational resources aren't wasted.
-
-\subsubsection{Can I change values for any quantity during the simulation?}
-Yes, using \code{domain.set\_quantity()} inside the domain.evolve
-loop you can change values of any quantity. This is for example
-useful if you wish to let the system settle for a while before
-assigning an initial condition. Another example would be changing
-the values for elevation to model e.g. erosion.
-
-\subsubsection{Can I change boundary conditions during the simulation?}
-Yes - see example on page \pageref{sec:change boundary code} in Section
-\ref{sec:change boundary}.
-
-\subsubsection{How do I access model time during the simulation?}
-The variable \code{t} in the evolve for loop is the model time.
-For example to change the boundary at a particular time (instead of basing this on the state of the system as in Section \ref{sec:change boundary})
-one would write something like
-{\small \begin{verbatim}
-    for t in domain.evolve(yieldstep = 0.2, duration = 40.0):
-
-        if Numeric.allclose(t, 15):
-            print 'Changing boundary to outflow'
-            domain.set_boundary({'right': Bo})
-
-\end{verbatim}}
-The model time can also be accessed through the public interface \code{domain.get\_time()}, or changed (at your own peril) through \code{domain.set\_time()}.
-
-
-\subsubsection{Why does a file\_function return a list of numbers when evaluated?}
-Currently, file\_function works by returning values for the conserved
-quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time
-and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the
-triplet returned by file\_function, to access \code{xmomentum} one must specify element 1 of the triplet etc.
-
-\subsubsection{Which diagnostics are available to troubleshoot a simulation?}
-
-\subsubsection{How do I use a DEM in my simulation?}
-You use \code{dem2pts} to convert your DEM to the required .pts format. This .pts file is then called
-when setting the elevation data to the mesh in \code{domain.set_quantity}
-
-\subsubsection{What sort of DEM resolution should I use?}
-Try and work with the \emph{best} you have available. Onshore DEMs
-are typically available in 25m, 100m and 250m grids. Note, offshore
-data is often sparse, or non-existent.
-
-Note that onshore DEMS can be much finer as the underlying datasets from which they
-are created often contain several datapoints per m$^2$.
-It may be necessary to thin out the data so that it can be imported
-without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?).
-
-
-\subsubsection{What sort of mesh resolution should I use?}
-The mesh resolution should be commensurate with your DEM - it does not make sense to put in place a mesh which is finer than your DEM. As an example,
-if your DEM is on a 25m grid, then the cell resolution should be of the order of 315$m^2$ (this represents half the area of the square grid). Ideally,
-you need a fine mesh over regions where the DEM changes rapidly, and other areas of significant interest, such as the coast.
-If meshes are too coarse, discretisation errors in both stage and momentum may lead to unrealistic results. All studies should include sensitivity and convergence studies based on different resolutions.
-
-
-\subsubsection{How do I tag interior polygons?}
-At the moment create_mesh_from_regions does not allow interior
-polygons with symbolic tags. If tags are needed, the interior
-polygons must be created subsequently. For example, given a filename
-of polygons representing solid walls (in Arc Ungenerate format) can
-be tagged as such using the code snippet:
-\begin{verbatim}
-  # Create mesh outline with tags
-  mesh = create_mesh_from_regions(bounding_polygon,
-                                  boundary_tags=boundary_tags)
-  # Add buildings outlines with tags set to 'wall'. This would typically
-  # bind to a Reflective boundary
-  mesh.import_ungenerate_file(buildings_filename, tag='wall')
-
-  # Generate and write mesh to file
-  mesh.generate_mesh(maximum_triangle_area=max_area)
-  mesh.export_mesh_file(mesh_filename)
-\end{verbatim}
-
-Note that a mesh object is returned from \code{create_mesh_from_regions}
-when file name is omitted.
-
-\subsubsection{How often should I store the output?}
-This will depend on what you are trying to answer with your model and how much memory you have available on your machine. If you need
-to look in detail at the evolution, then you will need to balance your storage requirements and the duration of the simulation.
-If the SWW file exceeds 1Gb, another SWW file will be created until the end of the simulation. As an example, to store all the conserved
-quantities on a mesh with approximately 300000 triangles on a 2 min interval for 5 hours will result in approximately 350Mb SWW file
-(as for the \file{run\_sydney\_smf.py} example).
-
-\subsubsection{How can I set the friction in different areas in the domain?}
-The model area will typically be estimating the water height and momentum over varying
-topographies which will have different friction values. One way of assigning
-different friction values is to create polygons (say \code{poly1, poly2 and poly3}) describing each
-area and then set the corresponding friction values in the following way
-
-\code{domain.set_quantity('friction',Polygon_function([(poly1,f1),(poly2,f2),
-(poly3,f3))]))}
-
-The values of \code{f1,f2} and \code{f3} could be constant or functions
-as determined by the user.
-
-\subsubsection{How can I combine data sets?}
-
-A user may have access to a range of different resolution DEMs and raw data points (such
-as beach profiles, spot heights, single or multi-beam data etc) and will need
-to combine them to create an overall elevation data set.
-
-If there are multiple DEMs, say of 10m and 25m resolution, then the technique is similar to
-that defined in the Cairns example described earlier, that is
-
-{\small \begin{verbatim}
-convert_dem_from_ascii2netcdf(10m_dem_name, use_cache=True, verbose=True)
-convert_dem_from_ascii2netcdf(25m_dem_name, use_cache=True, verbose=True)
-\end{verbatim}}
-followed by
-{\small \begin{verbatim}
-dem2pts(10m_dem_name, use_cache=True, verbose=True)
-dem2pts(25m_dem_name, use_cache=True, verbose=True)
-\end{verbatim}}
-These data sets can now be combined by
-{\small \begin{verbatim}
-from anuga.geospatial_data.geospatial_data import *
-G1 = Geospatial_data(file_name = 10m_dem_name + '.pts')
-G2 = Geospatial_data(file_name = 25m_dem_name + '.pts')
-G = G1 + G2
-G.export_points_file(combined_dem_name + ï¿œ.ptsï¿œ)
-\end{verbatim}}
-this is the basic way of combining data sets, however, the user will need to
-assess the boundaries of each data set and whether they overlap. For example, consider
-if the 10m DEM is describing by \code{poly1} and the 25m DEM is described by \code{poly2}
-with \code{poly1} completely enclosed in \code{poly2} as shown in Figure \ref{fig:polydata}
-\begin{figure}[hbt]
-  \centerline{\includegraphics{graphics/polyanddata.jpg}}
-  \caption{Polygons describing the extent of the 10m and 25m DEM.}
-  \label{fig:polydata}
-\end{figure}
-To combine the data sets, the geospatial addition is updated to
-{\small \begin{verbatim}
-G = G1 + G2.clip_outside(Geospatial_data(poly1))
-\end{verbatim}}
-For this example, we assume that \code{poly2} is the domain, otherwise an additional dataset
-would be required for the remainder of the domain.
-
-This technique can be expanded to handle point data sets as well. In the case
-of a bathymetry data set available in text format in an \code{.csv} file, then
-the geospatial addition is updated to
-{\small \begin{verbatim}
-G3 = Geospatial_data(file_name = bathy_data_name + '.csv')
-G = G1 + G2.clip_outside(Geospatial_data(poly1)) + G3
-\end{verbatim}}
-The \code{.csv} file has the data stored as \code{x,y,elevation} with the text \code{elevation}
-on the first line.
-
-The coastline could be included
-as part of the clipping polygon to separate the offshore and onshore datasets if required.
-Assume that \code{poly1} crosses the coastline
-In this case, two new polygons could be created out of \code{poly1} which uses the coastline
-as the divider. As shown in Figure \ref{fig:polycoast}, \code{poly3} describes the
-onshore data and \code{poly4} describes the offshore data.
-\begin{figure}[hbt]
-  \centerline{\includegraphics{graphics/polyanddata2.jpg}}
-  \caption{Inclusion of new polygons separating the 10m DEM area into an
-  onshore (poly3) and offshore (poly4) data set.}
-  \label{fig:polycoast}
-\end{figure}
-Let's include the bathymetry
-data described above, so to combine the datasets in this case,
-{\small \begin{verbatim}
-G = G1.clip(Geospatial_data(poly3)) + G2.clip_outside(Geospatial_data(poly1)) + G3
-\end{verbatim}}
-
-Finally, to fit the elevation data to the mesh, the script is adjusted in this way
-{\small \begin{verbatim}
-    domain.set_quantity('elevation',
-                        filename = combined_dem_name + '.pts',
-                        use_cache = True,
-                        verbose = True)
-\end{verbatim}}
-\subsection{Boundary Conditions}
-
-\subsubsection{How do I create a Dirichlet boundary condition?}
-
-A Dirichlet boundary condition sets a constant value for the
-conserved quantities at the boundaries. A list containing
-the constant values for stage, xmomentum and ymomentum is constructed
-and used in the function call, e.g. \code{Dirichlet_boundary([0.2,0.,0.])}
-
-\subsubsection{How do I know which boundary tags are available?}
-The method \code{domain.get\_boundary\_tags()} will return a list of
-available tags for use with
-\code{domain.set\_boundary\_condition()}.
-
-\subsubsection{What is the difference between file_boundary and field_boundary?}
-The only difference is field_boundary will allow you to change the level of the stage height when you read in the boundary condition.
-This is very useful when running different tide heights in the same area as you need only to convert
-one boundary condition to a SWW file, ideally for tide height of 0 m (saving disk space). Then you can
-use field_boundary to read this SWW file and change the stage height (tide) on the fly depending on the scenario.
-
-
-
-
-\subsection{Analysing Results}
-
-\subsubsection{How do I easily plot "tide gauges" timeseries graphs from a SWW file?}
-
-There is two ways to do this.
-
-1) Create csv files from the sww file using \code{anuga.abstract_2d_finite_volumes.util sww2csv_gauges}
-and then use \code{anuga.abstract_2d_finite_volumes.util csv2timeseries_graphs} to
-create the plots. This code is newer, has unit tests and might be easier to use. Read doc strings for more information and
-review section 4.7 of this manual.
-
-Or
-
-2) Use \code{anuga.abstract_2d_finite_volumes.util sww2timeseries} to do the whole thing
-however this doesn't have a much control on the file name and plots. Plus there is no unit tests yet.
-
-Read the doc string for more information.
-
-\subsubsection{How do I extract elevation and other quantities from a SWW file?}
-
-The function \code{sww2dem} can extract any quantity, or expression using
-quantities, from a SWW file as used in
-the Cairns example described earlier. This function is used in \code{ExportResults.py}
-in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation
-can be exported from the input sww file. Note that depth, absolute momentum and speed
-are expressions and stage and elevation are quantities. In addition to extracting a particular
-quantity or expression, the user can define a region to extract these values by
-defining the minimum and maximum of both the easting and northing coordinates. The function
-also calls for a grid resolution, or cell size, to extract these values at. It is
-recommended to align this resolution with the mesh resolution in the desired region and to not
-generate a fine grid where the model output cannot support that resolution.
-
-
+The Frequently Asked Questions have been move to the online FAQ at:
+
+\url{https://datamining.anu.edu.au/anuga/wiki/FrequentlyAskedQuestions}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \chapter{Glossary}