Changeset 5744
- Timestamp:
- Sep 7, 2008, 11:19:32 AM (17 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
anuga_core/documentation/user_manual/anuga_user_manual.tex
r5730 r5744 32 32 33 33 \usepackage{graphicx} 34 \usepackage[english]{babel} 34 35 \usepackage{datetime} 35 36 … … 85 86 86 87 88 87 89 % This makes the contents more accessible from the front page of the HTML. 88 90 \ifhtml … … 155 157 \section{Audience} 156 158 157 Readers are assumed to be familiar with the Python Programming language and 159 Readers are assumed to be familiar with the Python Programming language and 158 160 its object oriented approach. 159 Python tutorials include 161 Python tutorials include 160 162 \url{http://docs.python.org/tut}, 161 163 \url{http://www.sthurlow.com/python}, and … … 235 237 ANUGA is unsuitable for modelling flows in areas larger than one UTM zone 236 238 (6 degrees wide). 237 \item Fluid is assumed to be inviscid - i.e.\ no kinematic viscosity included. 239 \item Fluid is assumed to be inviscid - i.e.\ no kinematic viscosity included. 238 240 \item The finite volume is a very robust and flexible numerical technique, 239 241 but it is not the fastest method around. If the geometry is sufficiently … … 1715 1717 1716 1718 1717 \begin{methoddesc} {import_ungenerate_file}{self,ofile, tag=None, 1719 \begin{methoddesc} {import_ungenerate_file}{self,ofile, tag=None, 1718 1720 region_tag=None} 1719 1721 Module: \module{pmesh.mesh}, Class: \class{Mesh} … … 2268 2270 2269 2271 Optional argument \code{default\_boundary} can be used to specify another boundary object to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}. 2270 The \code{default\_boundary} could be a simple Dirichlet condition or 2271 even another \code{File\_boundary} 2272 typically using data pertaining to another time interval. 2272 The \code{default\_boundary} could be a simple Dirichlet condition or 2273 even another \code{File\_boundary} 2274 typically using data pertaining to another time interval. 2273 2275 \end{classdesc} 2274 2276 … … 2276 2278 Module: \module{shallow\_water.shallow\_water\_domain} 2277 2279 2278 This method works in the same way as \code{File\_boundary} except that it 2279 allows for the value of stage to be offset by a constant specified in the 2280 This method works in the same way as \code{File\_boundary} except that it 2281 allows for the value of stage to be offset by a constant specified in the 2280 2282 keyword argument \code{mean\_stage}. 2281 2283 2282 2284 This functionality allows for models to be run for a range of tides using 2283 2285 the same boundary information (from .sts, .sww or .tms files). The tidal value 2284 for each run would then be specified in the keyword argument 2285 \code{mean\_stage}. 2286 If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary} 2287 behave identically. 2286 for each run would then be specified in the keyword argument 2287 \code{mean\_stage}. 2288 If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary} 2289 behave identically. 2288 2290 2289 2291 2290 2292 Note that if the optional argument \code{default\_boundary} is specified 2291 2293 it's stage value will be adjusted by \code{mean\_stage} just like the values 2292 obtained from the file. 2294 obtained from the file. 2293 2295 2294 2296 See \code{File\_boundary} for further details. … … 2342 2344 2343 2345 \anuga provides a number of predefined forcing functions to be used with simulations. 2344 Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list 2345 \code{domain.forcing\_terms} and have them affect the model. 2346 2346 Gravity and friction are always calculated using the elevation and friction quantities, but the user may additionally add forcing terms to the list 2347 \code{domain.forcing\_terms} and have them affect the model. 2348 2347 2349 Currently, predefined forcing terms are 2348 2350 … … 2352 2354 This is a general class to modify any quantity according to a given rate of change. 2353 2355 Other specific forcing terms are based on this class but it can be used by itself as well (e.g.\ to modify momentum). 2354 2356 2355 2357 The General\_forcing class takes as input: 2356 \begin{itemize} 2358 \begin{itemize} 2357 2359 \item \code{domain}: a reference to the domain being evolved 2358 2360 \item \code{quantity\_name}: The name of the quantity that will be affected by this forcing term 2359 2361 \item \code{rate}: The rate at which the quantity should change. The parameter \code{rate} can be eithe a constant or a 2360 function of time. Positive values indicate increases, 2362 function of time. Positive values indicate increases, 2361 2363 negative values indicate decreases. 2362 2364 The parametr \code{rate} can be \code{None} at initialisation but must be specified … … 2369 2371 Moreover, if the specified polygon or circle does not lie fully within the mesh boundary an Exception will be thrown. 2370 2372 2371 \bigskip 2373 \bigskip 2372 2374 Example: 2373 {\scriptsize \begin{verbatim} 2375 {\scriptsize \begin{verbatim} 2374 2376 P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]] # Square polygon 2375 2377 2376 2378 xmom = General_forcing(domain, 'xmomentum', polygon=P) 2377 2379 ymom = General_forcing(domain, 'ymomentum', polygon=P) … … 2379 2381 xmom.rate = f 2380 2382 ymom.rate = g 2381 2383 2382 2384 domain.forcing_terms.append(xmom) 2383 2385 domain.forcing_terms.append(ymom) 2384 2386 \end{verbatim}} 2385 2387 Here, \code{f}, \code{g} are assumed to be defined as functions of time providing a time dependent rate of change for xmomentum and ymomentum respectively. 2386 P is assumed to be polygon, specified as a list of points. 2387 2388 \end{funcdesc} 2388 P is assumed to be polygon, specified as a list of points. 2389 2390 \end{funcdesc} 2389 2391 2390 2392 … … 2394 2396 This is a general class for inflow and abstraction of water according to a given rate of change. 2395 2397 This class will always modify the \code{stage} quantity. 2396 2398 2397 2399 Inflow is based on the General_forcing class so the functionality is similar. 2398 2400 2399 2401 The Inflow class takes as input: 2400 \begin{itemize} 2402 \begin{itemize} 2401 2403 \item \code{domain}: a reference to the domain being evolved 2402 2404 \item \code{rate}: The flow rate in $m^3/s$ at which the stage should change. The parameter \code{rate} can be eithe a constant or a 2403 function of time. Positive values indicate inflow, 2405 function of time. Positive values indicate inflow, 2404 2406 negative values indicate outflow. 2405 2407 2406 2408 Note: The specified flow will be divided by the area of 2407 2409 the inflow region and then applied to update the 2408 stage quantity. 2410 stage quantity. 2409 2411 \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius. 2410 2412 \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon. 2411 2413 \end{itemize} 2412 2414 2413 \bigskip 2415 \bigskip 2414 2416 Example: 2415 {\scriptsize \begin{verbatim} 2417 {\scriptsize \begin{verbatim} 2416 2418 hydrograph = Inflow(center=(320, 300), radius=10, 2417 2419 rate=file_function('QPMF_Rot_Sub13.tms')) … … 2420 2422 \end{verbatim}} 2421 2423 Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for a hydrograph. 2422 \end{funcdesc} 2424 \end{funcdesc} 2423 2425 2424 2426 … … 2428 2430 This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon. 2429 2431 This class will always modify the \code{stage} quantity. 2430 2432 2431 2433 Rainfall is based on the General_forcing class so the functionality is similar. 2432 2434 2433 2435 The Rainfall class takes as input: 2434 \begin{itemize} 2436 \begin{itemize} 2435 2437 \item \code{domain}: a reference to the domain being evolved 2436 \item \code{rate}: Total rain rate over the specified domain. 2438 \item \code{rate}: Total rain rate over the specified domain. 2437 2439 Note: Raingauge Data needs to reflect the time step. 2438 2440 For example: if rain gauge is mm read every \code{dt} seconds, then the input … … 2441 2443 2442 2444 This parameter can be either a constant or a 2443 function of time. Positive values indicate rain being added (or be used for general infiltration), 2445 function of time. Positive values indicate rain being added (or be used for general infiltration), 2444 2446 negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction). 2445 2447 \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius. 2446 2448 \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon. 2447 2449 \end{itemize} 2448 2449 \bigskip 2450 2451 \bigskip 2450 2452 Example: 2451 {\scriptsize \begin{verbatim} 2452 2453 catchmentrainfall = Rainfall(rain=file_function('Q100_2hr_Rain.tms')) 2453 {\scriptsize \begin{verbatim} 2454 2455 catchmentrainfall = Rainfall(rain=file_function('Q100_2hr_Rain.tms')) 2454 2456 domain.forcing_terms.append(catchmentrainfall) 2455 2457 2456 2458 \end{verbatim}} 2457 2459 Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for the rainfall. 2458 \end{funcdesc} 2460 \end{funcdesc} 2459 2461 2460 2462 … … 2465 2467 This is a general class for implementing flow through a culvert. 2466 2468 This class modifies the quantities \code{stage, xmomentum, ymomentum} in areas at both ends of the culvert. 2467 2469 2468 2470 The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities. The flow drection is determined on-the-fly so 2469 2471 openings are referenced simple as opening0 and opening1 with either being able to take the role as Inflow and Outflow. 2470 2472 2471 2473 The Culvert\_flow class takes as input: 2472 \begin{itemize} 2474 \begin{itemize} 2473 2475 \item \code{domain}: a reference to the domain being evolved 2474 2476 \item \code{label}: Short text naming the culvert 2475 2477 \item \code{description}: Text describing it 2476 \item \code{end_point0}: Coordinates of one opening 2478 \item \code{end_point0}: Coordinates of one opening 2477 2479 \item \code{end_point1}: Coordinates of other opening 2478 \item \code{width}: 2480 \item \code{width}: 2479 2481 \item \code{height}: 2480 2482 \item \code{diameter}: … … 2486 2488 2487 2489 The user can specify different culvert routines. Hower ANUGA currently provides only one, namely the \code{boyd\_generalised\_culvert\_model} as used in the example below. 2488 2489 \bigskip 2490 2491 \bigskip 2490 2492 Example: 2491 {\scriptsize \begin{verbatim} 2493 {\scriptsize \begin{verbatim} 2492 2494 from anuga.culvert_flows.culvert_class import Culvert_flow 2493 from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model 2495 from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model 2494 2496 2495 2497 culvert1 = Culvert_flow(domain, 2496 2498 label='Culvert No. 1', 2497 description='This culvert is a test unit 1.2m Wide by 0.75m High', 2498 end_point0=[9.0, 2.5], 2499 description='This culvert is a test unit 1.2m Wide by 0.75m High', 2500 end_point0=[9.0, 2.5], 2499 2501 end_point1=[13.0, 2.5], 2500 2502 width=1.20,height=0.75, 2501 culvert_routine=boyd_generalised_culvert_model, 2503 culvert_routine=boyd_generalised_culvert_model, 2502 2504 verbose=True) 2503 2505 2504 2506 culvert2 = Culvert_flow(domain, 2505 2507 label='Culvert No. 2', 2506 description='This culvert is a circular test with d=1.2m', 2507 end_point0=[9.0, 1.5], 2508 description='This culvert is a circular test with d=1.2m', 2509 end_point0=[9.0, 1.5], 2508 2510 end_point1=[30.0, 3.5], 2509 2511 diameter=1.20, 2510 2512 invert_level0=7, 2511 culvert_routine=boyd_generalised_culvert_model, 2513 culvert_routine=boyd_generalised_culvert_model, 2512 2514 verbose=True) 2513 2515 2514 2516 domain.forcing_terms.append(culvert1) 2515 2517 domain.forcing_terms.append(culvert2) 2516 2518 2517 2519 2518 2520 \end{verbatim}} 2519 \end{funcdesc} 2521 \end{funcdesc} 2520 2522 2521 2523 … … 2667 2669 \end{funcdesc} 2668 2670 2669 2671 2670 2672 2671 2673 \begin{funcdesc}{set\_values}{location='vertices', indices = None} … … 2675 2677 This method works the same way as \code{set\_quantity} except that it doesn't take 2676 2678 a quantity name as the first argument. The reason to use \code{set\_values} is for 2677 example to assign values to a new quantity that has been created but which is 2679 example to assign values to a new quantity that has been created but which is 2678 2680 not part of the domain's predefined quantities. 2679 2681 2680 The method \code{set\_values} is always called by \code{set\_quantity} 2681 behind the scenes. 2682 2682 The method \code{set\_values} is always called by \code{set\_quantity} 2683 behind the scenes. 2684 2683 2685 \end{funcdesc} 2684 2685 2686 2687 2686 2688 2687 2689 \begin{funcdesc}{get\_integral}{} … … 2831 2833 2832 2834 Inputs: 2833 \begin{itemize} 2835 \begin{itemize} 2834 2836 \item filename: Name of sww file containing ANUGA model output. 2835 2837 \item polyline: Representation of desired cross section - it may contain multiple 2836 2838 sections allowing for complex shapes. Assume absolute UTM coordinates. 2837 \end{itemize} 2839 \end{itemize} 2838 2840 2839 2841 Output: … … 2841 2843 \item time: All stored times in sww file 2842 2844 \item Q: Hydrograph of total flow across given segments for all stored times. 2843 \end{itemize} 2844 2845 \end{itemize} 2846 2845 2847 The normal flow is computed for each triangle intersected by the polyline and 2846 2848 added up. Multiple segments at different angles are specified the normal flows 2847 2849 may partially cancel each other. 2848 2850 2849 2851 Example to find flow through cross section: 2850 2851 \begin{verbatim} 2852 2853 \begin{verbatim} 2852 2854 cross_section = [[x, 0], [x, width]] 2853 2855 time, Q = get_flow_through_cross_section(filename, 2854 2856 cross_section, 2855 2857 verbose=False) 2856 \end{verbatim} 2858 \end{verbatim} 2857 2859 2858 2860 2859 2861 See doc string for general function get_maximum_inundation_data for details. 2860 2862 2861 2863 \end{funcdesc} 2862 2864 … … 3151 3153 3152 3154 Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or 3153 ERS) of a desired grid size \code{cellsize} in metres. The user can select how 3154 many the decimal places the output data can be written to using \code{number_of_decimal_places}, 3155 ERS) of a desired grid size \code{cellsize} in metres. The user can select how 3156 many the decimal places the output data can be written to using \code{number_of_decimal_places}, 3155 3157 with the default being 3. 3156 3158 The easting and northing values are used if the user wished to determine the output … … 3170 3172 \end{funcdesc} 3171 3173 3172 \begin{funcdesc}{urs2sts}{basename_in, basename_out=None, 3173 weights=None, verbose=False, 3174 origin=None,mean_stage=0.0, 3174 \begin{funcdesc}{urs2sts}{basename_in, basename_out=None, 3175 weights=None, verbose=False, 3176 origin=None,mean_stage=0.0, 3175 3177 zscale=1.0, ordering_filename=None} 3176 3178 Module: \module{shallow\_water.data\_manager} … … 3241 3243 3242 3244 As demonstrated in our papers, \cite{ZR1999,nielsen2005} these 3243 equations and their implementation in \anuga provide a reliable 3244 model of general flows associated with inundation such as dam breaks 3245 equations and their implementation in \anuga provide a reliable 3246 model of general flows associated with inundation such as dam breaks 3245 3247 and tsunamis. 3246 3248 … … 3344 3346 observed CFL condition: 3345 3347 3346 \begin{equation} 3348 \begin{equation} 3347 3349 \Delta t = \min_{k,i=[0,1,2]} \min \left( \frac{r_k}{v_{k,i}}, \frac{r_{n_{k,i}}}{v_{k,i}} \right ) 3348 3350 \label{eq:CFL condition} 3349 \end{equation} 3350 where $r_k$ is the radius of the $k$'th triangle and $v_{k,i}$ is the maximal velocity across 3351 edge joining triangle $k$ and it's $i$'th neighbour, triangle $n_{k,i}$, as calculated by the 3352 numerical flux function 3353 using the central upwind scheme of \cite{KurNP2001}. The symbol $r_{n_{k,i}}$ denotes the radius 3354 of the $i$'th neighbour of triangle $k$. The radii are calculated as radii of the inscribed circles 3351 \end{equation} 3352 where $r_k$ is the radius of the $k$'th triangle and $v_{k,i}$ is the maximal velocity across 3353 edge joining triangle $k$ and it's $i$'th neighbour, triangle $n_{k,i}$, as calculated by the 3354 numerical flux function 3355 using the central upwind scheme of \cite{KurNP2001}. The symbol $r_{n_{k,i}}$ denotes the radius 3356 of the $i$'th neighbour of triangle $k$. The radii are calculated as radii of the inscribed circles 3355 3357 of each triangle. 3356 3358 … … 3784 3786 is either a constant value or a function of coordinates \code{x} 3785 3787 and \code{y}, specifying the return value for a point inside \code{P}. The 3786 optional parameter \code{default} may be used to specify a value 3788 optional parameter \code{default} may be used to specify a value 3787 3789 (or a function) 3788 3790 for a point not lying inside any of the specified polygons. When a … … 3792 3794 %FIXME (Howard): CAN x, y BE VECTORS? 3793 3795 The optional parameter geo\_reference refers to the status of points 3794 that are passed into the function. Typically they will be relative to 3796 that are passed into the function. Typically they will be relative to 3795 3797 some origin. In ANUGA, a typical call will take the form: 3796 3798 {\small \begin{verbatim} 3797 set_quantity('elevation', 3799 set_quantity('elevation', 3798 3800 Polygon_function([(P1, v1), (P2, v2)], 3799 3801 default=v3, 3800 3802 geo_reference=domain.geo_reference)) 3801 3803 \end{verbatim}} 3802 3804 3803 3805 3804 3806 \end{classdesc} … … 3880 3882 \begin{funcdesc}{plot\_polygons}{polygons, style, figname, verbose = False} 3881 3883 Module: \code{utilities.polygon} 3882 3884 3883 3885 Plots each polygon contained in input polygon list, e.g. 3884 3886 \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]} … … 3935 3937 first one. 3936 3938 3937 Note that the Geospatial\_data object currently reads entire datasets 3938 into memory i.e.\ no memomry blocking takes place. 3939 Note that the Geospatial\_data object currently reads entire datasets 3940 into memory i.e.\ no memomry blocking takes place. 3939 3941 For this we refer to the set\_quantity method which will read .pts and .csv files into \anuga using memory blocking allowing large files to be used. 3940 3942 \end{classdesc} … … 4020 4022 smaller the original and the second is the remainder. The two 4021 4023 new object are disjoin set of each other. 4022 4023 Points of the two new geospatial_data object are selected RANDOMLY. 4024 4024 4025 Points of the two new geospatial_data object are selected RANDOMLY. 4026 4025 4027 Input - the (\code{factor}) which to split the object, if 0.1 then 10% of the 4026 4028 together object will be returned 4027 4029 4028 4030 Output - two geospatial_data objects that are disjoint sets of the original 4029 4031 \end{methoddesc} … … 4032 4034 north_boundary=None, south_boundary=None, east_boundary=None, west_boundary=None, plot_name='all_alphas', split_factor=0.1, seed_num=None, cache=False, verbose=False} 4033 4035 4034 Removes a small random sample of points from 'data_file'. Creates 4035 models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates 4036 Removes a small random sample of points from 'data_file'. Creates 4037 models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates 4036 4038 the predicted value to the previously removed point data. Returns the 4037 4039 alpha value which has the smallest covariance. 4038 4040 4039 4041 data_file: must not contain points outside the boundaries defined 4040 and it either a pts, txt or csv file. 4041 4042 and it either a pts, txt or csv file. 4043 4042 4044 alpha_list: the alpha values to test in a single list 4043 4044 mesh_file: name of the created mesh file or if passed in will read it. 4045 4046 mesh_file: name of the created mesh file or if passed in will read it. 4045 4047 NOTE, if there is a mesh file mesh_resolution, north_boundary, south... etc will be ignored. 4046 4048 4047 4049 mesh_resolution: the maximum area size for a triangle 4048 4050 4049 4051 north_boundary... west_boundary: the value of the boundary 4050 4052 4051 4053 plot_name: the name for the plot contain the results 4052 4054 4053 4055 seed_num: the seed to the random number generator 4054 4056 4055 4057 USAGE: 4056 convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName, 4058 convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName, 4057 4059 alpha_list=[0.0001, 0.01, 1], 4058 4060 mesh_file=None, … … 4065 4067 seed_num=100000, 4066 4068 verbose=False) 4067 4068 OUTPUT: returns the minumum normalised covalance calculate AND the 4069 4070 OUTPUT: returns the minumum normalised covalance calculate AND the 4069 4071 alpha that created it. PLUS writes a plot of the results 4070 4072 4071 4073 NOTE: code will not work if the data_file extent is greater than the 4072 4074 boundary_polygon or any of the boundaries, eg north_boundary...west_boundary … … 4272 4274 \section{\module{shallow\_water}} 4273 4275 2D triangular domains for finite-volume 4274 computations of the shallow water wave equation. 4276 computations of the shallow water wave equation. 4275 4277 This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water 4276 4278 Wave Equation … … 4376 4378 data is often sparse, or non-existent. 4377 4379 4378 Note that onshore DEMS can be much finer as the underlying datasets from which they 4379 are created often contain several datapoints per m$^2$. 4380 It may be necessary to thin out the data so that it can be imported 4381 without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?). 4380 Note that onshore DEMS can be much finer as the underlying datasets from which they 4381 are created often contain several datapoints per m$^2$. 4382 It may be necessary to thin out the data so that it can be imported 4383 without exceeding available memory. One tool available on the net is called 'decimate'. %FIXME: (Need reference?). 4382 4384 4383 4385 … … 4550 4552 \subsubsection{How do I extract elevation and other quantities from a SWW file?} 4551 4553 4552 The function \code{sww2dem} can extract any quantity, or expression using 4553 quantities, from a SWW file as used in 4554 The function \code{sww2dem} can extract any quantity, or expression using 4555 quantities, from a SWW file as used in 4554 4556 the Cairns example described earlier. This function is used in \code{ExportResults.py} 4555 in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation 4557 in the Cairns demo folder where stage, absolute momentum, depth, speed and elevation 4556 4558 can be exported from the input sww file. Note that depth, absolute momentum and speed 4557 4559 are expressions and stage and elevation are quantities. In addition to extracting a particular 4558 4560 quantity or expression, the user can define a region to extract these values by 4559 4561 defining the minimum and maximum of both the easting and northing coordinates. The function 4560 also calls for a grid resolution, or cell size, to extract these values at. It is 4561 recommended to align this resolution with the mesh resolution in the desired region and to not 4562 also calls for a grid resolution, or cell size, to extract these values at. It is 4563 recommended to align this resolution with the mesh resolution in the desired region and to not 4562 4564 generate a fine grid where the model output cannot support that resolution. 4563 4565 4564 4566 4565 4567 4566 4568 \chapter{Glossary}
Note: See TracChangeset
for help on using the changeset viewer.
