Changeset 5956

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

Removed FAQ, left pointer to online FAQ.

1 edited


  • anuga_core/documentation/user_manual/anuga_user_manual.tex

    r5955 r5956  
    43034303\chapter{Frequently Asked Questions}
    4306 \section{General Questions}
    4308 \subsubsection{What is \anuga?}
    4309 It is a software package suitable for simulating 2D water flows in
    4310 complex geometries.
    4312 \subsubsection{Why is it called \anuga?}
    4313 The software was developed in collaboration between the
    4314 Australian National University (ANU) and Geoscience Australia (GA).
    4316 \subsubsection{How do I obtain a copy of \anuga?}
    4317 See \url{} for all things ANUGA.
    4319 %\subsubsection{What developments are expected for \anuga in the future?}
    4320 %This
    4322 \subsubsection{Are there any published articles about \anuga that I can reference?}
    4323 See \url{} for links.
    4326 \subsubsection{How do I find out what version of \anuga I am running?}
    4327 Use the following code snippet
    4328 \begin{verbatim}
    4329 from anuga.utilities.system_tools import get_revision_number
    4330 print get_revision_number()
    4331 \end{verbatim}
    4332 This should work both for installations from SourceForge as well as when working off the repository.
    4337 \section{Modelling Questions}
    4339 \subsubsection{Which type of problems are \anuga good for?}
    4340 General 2D waterflows in complex geometries such as
    4341 dam breaks, flows amoung structurs, coastal inundation etc.
    4343 \subsubsection{Which type of problems are beyond the scope of \anuga?}
    4344 See Chapter \ref{ch:limitations}.
    4346 \subsubsection{Can I start the simulation at an arbitrary time?}
    4347 Yes, using \code{domain.set\_time()} you can specify an arbitrary
    4348 starting time. This is for example useful in conjunction with a
    4349 file\_boundary, which may start hours before anything hits the model
    4350 boundary. By assigning a later time for the model to start,
    4351 computational resources aren't wasted.
    4353 \subsubsection{Can I change values for any quantity during the simulation?}
    4354 Yes, using \code{domain.set\_quantity()} inside the domain.evolve
    4355 loop you can change values of any quantity. This is for example
    4356 useful if you wish to let the system settle for a while before
    4357 assigning an initial condition. Another example would be changing
    4358 the values for elevation to model e.g. erosion.
    4360 \subsubsection{Can I change boundary conditions during the simulation?}
    4361 Yes - see example on page \pageref{sec:change boundary code} in Section
    4362 \ref{sec:change boundary}.
    4364 \subsubsection{How do I access model time during the simulation?}
    4365 The variable \code{t} in the evolve for loop is the model time.
    4366 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})
    4367 one would write something like
    4368 {\small \begin{verbatim}
    4369     for t in domain.evolve(yieldstep = 0.2, duration = 40.0):
    4371         if Numeric.allclose(t, 15):
    4372             print 'Changing boundary to outflow'
    4373             domain.set_boundary({'right': Bo})
    4375 \end{verbatim}}
    4376 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()}.
    4379 \subsubsection{Why does a file\_function return a list of numbers when evaluated?}
    4380 Currently, file\_function works by returning values for the conserved
    4381 quantities \code{stage}, \code{xmomentum} and \code{ymomentum} at a given point in time
    4382 and space as a triplet. To access e.g.\ \code{stage} one must specify element 0 of the
    4383 triplet returned by file\_function, to access \code{xmomentum} one must specify element 1 of the triplet etc.
    4385 \subsubsection{Which diagnostics are available to troubleshoot a simulation?}
    4387 \subsubsection{How do I use a DEM in my simulation?}
    4388 You use \code{dem2pts} to convert your DEM to the required .pts format. This .pts file is then called
    4389 when setting the elevation data to the mesh in \code{domain.set_quantity}
    4391 \subsubsection{What sort of DEM resolution should I use?}
    4392 Try and work with the \emph{best} you have available. Onshore DEMs
    4393 are typically available in 25m, 100m and 250m grids. Note, offshore
    4394 data is often sparse, or non-existent.
    4396 Note that onshore DEMS can be much finer as the underlying datasets from which they
    4397 are created often contain several datapoints per m$^2$.
    4398 It may be necessary to thin out the data so that it can be imported
    4399 without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?).
    4402 \subsubsection{What sort of mesh resolution should I use?}
    4403 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,
    4404 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,
    4405 you need a fine mesh over regions where the DEM changes rapidly, and other areas of significant interest, such as the coast.
    4406 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.
    4409 \subsubsection{How do I tag interior polygons?}
    4410 At the moment create_mesh_from_regions does not allow interior
    4411 polygons with symbolic tags. If tags are needed, the interior
    4412 polygons must be created subsequently. For example, given a filename
    4413 of polygons representing solid walls (in Arc Ungenerate format) can
    4414 be tagged as such using the code snippet:
    4415 \begin{verbatim}
    4416   # Create mesh outline with tags
    4417   mesh = create_mesh_from_regions(bounding_polygon,
    4418                                   boundary_tags=boundary_tags)
    4419   # Add buildings outlines with tags set to 'wall'. This would typically
    4420   # bind to a Reflective boundary
    4421   mesh.import_ungenerate_file(buildings_filename, tag='wall')
    4423   # Generate and write mesh to file
    4424   mesh.generate_mesh(maximum_triangle_area=max_area)
    4425   mesh.export_mesh_file(mesh_filename)
    4426 \end{verbatim}
    4428 Note that a mesh object is returned from \code{create_mesh_from_regions}
    4429 when file name is omitted.
    4431 \subsubsection{How often should I store the output?}
    4432 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
    4433 to look in detail at the evolution, then you will need to balance your storage requirements and the duration of the simulation.
    4434 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
    4435 quantities on a mesh with approximately 300000 triangles on a 2 min interval for 5 hours will result in approximately 350Mb SWW file
    4436 (as for the \file{run\_sydney\} example).
    4438 \subsubsection{How can I set the friction in different areas in the domain?}
    4439 The model area will typically be estimating the water height and momentum over varying
    4440 topographies which will have different friction values. One way of assigning
    4441 different friction values is to create polygons (say \code{poly1, poly2 and poly3}) describing each
    4442 area and then set the corresponding friction values in the following way
    4444 \code{domain.set_quantity('friction',Polygon_function([(poly1,f1),(poly2,f2),
    4445 (poly3,f3))]))}
    4447 The values of \code{f1,f2} and \code{f3} could be constant or functions
    4448 as determined by the user.
    4450 \subsubsection{How can I combine data sets?}
    4452 A user may have access to a range of different resolution DEMs and raw data points (such
    4453 as beach profiles, spot heights, single or multi-beam data etc) and will need
    4454 to combine them to create an overall elevation data set.
    4456 If there are multiple DEMs, say of 10m and 25m resolution, then the technique is similar to
    4457 that defined in the Cairns example described earlier, that is
    4459 {\small \begin{verbatim}
    4460 convert_dem_from_ascii2netcdf(10m_dem_name, use_cache=True, verbose=True)
    4461 convert_dem_from_ascii2netcdf(25m_dem_name, use_cache=True, verbose=True)
    4462 \end{verbatim}}
    4463 followed by
    4464 {\small \begin{verbatim}
    4465 dem2pts(10m_dem_name, use_cache=True, verbose=True)
    4466 dem2pts(25m_dem_name, use_cache=True, verbose=True)
    4467 \end{verbatim}}
    4468 These data sets can now be combined by
    4469 {\small \begin{verbatim}
    4470 from anuga.geospatial_data.geospatial_data import *
    4471 G1 = Geospatial_data(file_name = 10m_dem_name + '.pts')
    4472 G2 = Geospatial_data(file_name = 25m_dem_name + '.pts')
    4473 G = G1 + G2
    4474 G.export_points_file(combined_dem_name + ï¿œ.ptsï¿œ)
    4475 \end{verbatim}}
    4476 this is the basic way of combining data sets, however, the user will need to
    4477 assess the boundaries of each data set and whether they overlap. For example, consider
    4478 if the 10m DEM is describing by \code{poly1} and the 25m DEM is described by \code{poly2}
    4479 with \code{poly1} completely enclosed in \code{poly2} as shown in Figure \ref{fig:polydata}
    4480 \begin{figure}[hbt]
    4481   \centerline{\includegraphics{graphics/polyanddata.jpg}}
    4482   \caption{Polygons describing the extent of the 10m and 25m DEM.}
    4483   \label{fig:polydata}
    4484 \end{figure}
    4485 To combine the data sets, the geospatial addition is updated to
    4486 {\small \begin{verbatim}
    4487 G = G1 + G2.clip_outside(Geospatial_data(poly1))
    4488 \end{verbatim}}
    4489 For this example, we assume that \code{poly2} is the domain, otherwise an additional dataset
    4490 would be required for the remainder of the domain.
    4492 This technique can be expanded to handle point data sets as well. In the case
    4493 of a bathymetry data set available in text format in an \code{.csv} file, then
    4494 the geospatial addition is updated to
    4495 {\small \begin{verbatim}
    4496 G3 = Geospatial_data(file_name = bathy_data_name + '.csv')
    4497 G = G1 + G2.clip_outside(Geospatial_data(poly1)) + G3
    4498 \end{verbatim}}
    4499 The \code{.csv} file has the data stored as \code{x,y,elevation} with the text \code{elevation}
    4500 on the first line.
    4502 The coastline could be included
    4503 as part of the clipping polygon to separate the offshore and onshore datasets if required.
    4504 Assume that \code{poly1} crosses the coastline
    4505 In this case, two new polygons could be created out of \code{poly1} which uses the coastline
    4506 as the divider. As shown in Figure \ref{fig:polycoast}, \code{poly3} describes the
    4507 onshore data and \code{poly4} describes the offshore data.
    4508 \begin{figure}[hbt]
    4509   \centerline{\includegraphics{graphics/polyanddata2.jpg}}
    4510   \caption{Inclusion of new polygons separating the 10m DEM area into an
    4511   onshore (poly3) and offshore (poly4) data set.}
    4512   \label{fig:polycoast}
    4513 \end{figure}
    4514 Let's include the bathymetry
    4515 data described above, so to combine the datasets in this case,
    4516 {\small \begin{verbatim}
    4517 G = G1.clip(Geospatial_data(poly3)) + G2.clip_outside(Geospatial_data(poly1)) + G3
    4518 \end{verbatim}}
    4520 Finally, to fit the elevation data to the mesh, the script is adjusted in this way
    4521 {\small \begin{verbatim}
    4522     domain.set_quantity('elevation',
    4523                         filename = combined_dem_name + '.pts',
    4524                         use_cache = True,
    4525                         verbose = True)
    4526 \end{verbatim}}
    4527 \subsection{Boundary Conditions}
    4529 \subsubsection{How do I create a Dirichlet boundary condition?}
    4531 A Dirichlet boundary condition sets a constant value for the
    4532 conserved quantities at the boundaries. A list containing
    4533 the constant values for stage, xmomentum and ymomentum is constructed
    4534 and used in the function call, e.g. \code{Dirichlet_boundary([0.2,0.,0.])}
    4536 \subsubsection{How do I know which boundary tags are available?}
    4537 The method \code{domain.get\_boundary\_tags()} will return a list of
    4538 available tags for use with
    4539 \code{domain.set\_boundary\_condition()}.
    4541 \subsubsection{What is the difference between file_boundary and field_boundary?}
    4542 The only difference is field_boundary will allow you to change the level of the stage height when you read in the boundary condition.
    4543 This is very useful when running different tide heights in the same area as you need only to convert
    4544 one boundary condition to a SWW file, ideally for tide height of 0 m (saving disk space). Then you can
    4545 use field_boundary to read this SWW file and change the stage height (tide) on the fly depending on the scenario.
    4550 \subsection{Analysing Results}
    4552 \subsubsection{How do I easily plot "tide gauges" timeseries graphs from a SWW file?}
    4554 There is two ways to do this.
    4556 1) Create csv files from the sww file using \code{anuga.abstract_2d_finite_volumes.util sww2csv_gauges}
    4557 and then use \code{anuga.abstract_2d_finite_volumes.util csv2timeseries_graphs} to
    4558 create the plots. This code is newer, has unit tests and might be easier to use. Read doc strings for more information and
    4559 review section 4.7 of this manual.
    4561 Or
    4563 2) Use \code{anuga.abstract_2d_finite_volumes.util sww2timeseries} to do the whole thing
    4564 however this doesn't have a much control on the file name and plots. Plus there is no unit tests yet.
    4566 Read the doc string for more information.
    4568 \subsubsection{How do I extract elevation and other quantities from a SWW file?}
    4570 The function \code{sww2dem} can extract any quantity, or expression using
    4571 quantities, from a SWW file as used in
    4572 the Cairns example described earlier. This function is used in \code{}
    4573 in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation
    4574 can be exported from the input sww file. Note that depth, absolute momentum and speed
    4575 are expressions and stage and elevation are quantities. In addition to extracting a particular
    4576 quantity or expression, the user can define a region to extract these values by
    4577 defining the minimum and maximum of both the easting and northing coordinates. The function
    4578 also calls for a grid resolution, or cell size, to extract these values at. It is
    4579 recommended to align this resolution with the mesh resolution in the desired region and to not
    4580 generate a fine grid where the model output cannot support that resolution.
     4305The Frequently Asked Questions have been move to the online FAQ at:
Note: See TracChangeset for help on using the changeset viewer.