Changeset 5956
- Timestamp:
- Nov 13, 2008, 2:51:12 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
anuga_core/documentation/user_manual/anuga_user_manual.tex
r5955 r5956 4303 4303 \chapter{Frequently Asked Questions} 4304 4304 4305 4306 \section{General Questions} 4307 4308 \subsubsection{What is \anuga?} 4309 It is a software package suitable for simulating 2D water flows in 4310 complex geometries. 4311 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). 4315 4316 \subsubsection{How do I obtain a copy of \anuga?} 4317 See \url{https://datamining.anu.edu.au/anuga} for all things ANUGA. 4318 4319 %\subsubsection{What developments are expected for \anuga in the future?} 4320 %This 4321 4322 \subsubsection{Are there any published articles about \anuga that I can reference?} 4323 See \url{https://datamining.anu.edu.au/anuga} for links. 4324 4325 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. 4333 4334 4335 4336 4337 \section{Modelling Questions} 4338 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. 4342 4343 \subsubsection{Which type of problems are beyond the scope of \anuga?} 4344 See Chapter \ref{ch:limitations}. 4345 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. 4352 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. 4359 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}. 4363 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): 4370 4371 if Numeric.allclose(t, 15): 4372 print 'Changing boundary to outflow' 4373 domain.set_boundary({'right': Bo}) 4374 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()}. 4377 4378 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. 4384 4385 \subsubsection{Which diagnostics are available to troubleshoot a simulation?} 4386 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} 4390 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. 4395 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?). 4400 4401 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. 4407 4408 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') 4422 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} 4427 4428 Note that a mesh object is returned from \code{create_mesh_from_regions} 4429 when file name is omitted. 4430 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\_smf.py} example). 4437 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 4443 4444 \code{domain.set_quantity('friction',Polygon_function([(poly1,f1),(poly2,f2), 4445 (poly3,f3))]))} 4446 4447 The values of \code{f1,f2} and \code{f3} could be constant or functions 4448 as determined by the user. 4449 4450 \subsubsection{How can I combine data sets?} 4451 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. 4455 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 4458 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. 4491 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. 4501 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}} 4519 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} 4528 4529 \subsubsection{How do I create a Dirichlet boundary condition?} 4530 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.])} 4535 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()}. 4540 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. 4546 4547 4548 4549 4550 \subsection{Analysing Results} 4551 4552 \subsubsection{How do I easily plot "tide gauges" timeseries graphs from a SWW file?} 4553 4554 There is two ways to do this. 4555 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. 4560 4561 Or 4562 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. 4565 4566 Read the doc string for more information. 4567 4568 \subsubsection{How do I extract elevation and other quantities from a SWW file?} 4569 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{ExportResults.py} 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. 4581 4582 4305 The Frequently Asked Questions have been move to the online FAQ at: 4306 4307 \url{https://datamining.anu.edu.au/anuga/wiki/FrequentlyAskedQuestions} 4308 4309 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 4583 4310 4584 4311 \chapter{Glossary}
Note: See TracChangeset
for help on using the changeset viewer.