Changeset 2559
- Timestamp:
- Mar 20, 2006, 8:37:32 AM (17 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
documentation/user_manual/anuga_user_manual.tex
r2542 r2559 171 171 The present example represents a simple scenario and does not 172 172 include any forcing terms, nor is the data taken from a file as it 173 would be in many typical cases. 173 would be in many typical cases. 174 174 175 175 The conserved quantities involved in the 176 176 problem are water depth, $x$-momentum and $y$-momentum. Other quantities 177 involved in the computation are the friction, stage (absolute height of water surface) 177 involved in the computation are the friction, stage (absolute height of water surface) 178 178 and elevation, the last two being related to 179 179 the depth through the equation 180 180 181 181 {\small \begin{verbatim} 182 stage = elevation + depth 182 \code{stage} = \code{elevation} + \code{depth} 183 183 \end{verbatim}} 184 184 … … 335 335 336 336 The stage (the height of the water surface) is related to the 337 elevation and the depth at any time by the equation {\small 338 \begin{verbatim} 339 stage = elevation + depth 340 \end{verbatim}} 337 elevation and the depth at any time by the equation \[\code{stage} = 338 \code{elevation} + \code{depth}\] 341 339 342 340 For this example, we simply assign a constant value to \code{stage}, … … 347 345 \end{verbatim}} 348 346 349 which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units 347 which specifies that the surface level is set to a height of $-0.4$, i.e. 0.4 units 350 348 below the zero level. 351 349 … … 355 353 involving other quantities. Suppose, instead of setting a constant value 356 354 for the stage, we wished 357 to specify a constant value for the \emph{depth}. For such a case we 355 to specify a constant value for the \emph{depth}. For such a case we 358 356 need to specify that \code{stage} is 359 357 everywhere obtained by adding that value to the value already … … 365 363 \end{verbatim}} 366 364 367 That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the 365 That is, the value of \code{stage} is set to $\code{h} = 0.05$ plus the 368 366 value of \code{elevation} already defined. 369 367 370 The reader will probably appreciate that this capability to incorporate 368 The reader will probably appreciate that this capability to incorporate 371 369 expressions into statements using \code{set\_quantity} greatly expands 372 370 its power.) … … 405 403 406 404 \item[Dirichlet boundary]Specifies a fixed value at the 407 boundary and assigns initial values to the $x$-momentum and $y$-momentum. 405 boundary and assigns initial values to the $x$-momentum and $y$-momentum. 408 406 409 407 \item[Time boundary.]A Dirichlet boundary whose behaviour varies with time. … … 423 421 424 422 The reader may wish to experiment by varying the choice of boundary types 425 for one or more of the boundaries. In the case of \code{Bd} and \code{Bw}, 426 the three arguments in each case represent the 423 for one or more of the boundaries. In the case of \code{Bd} and \code{Bw}, 424 the three arguments in each case represent the 427 425 428 426 {\small \begin{verbatim} … … 478 476 479 477 480 \begin{figure}[hbt] 481 482 \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslopestart.eps}}483 484 \caption{Bedslope example viewed with Swollen}485 \label{fig:bedslopestart}486 \end{figure} 487 488 489 \begin{figure}[hbt] 490 491 \centerline{ 492 \includegraphics[width=75mm, height=75mm]{examples/bedslopeduring.eps}493 \includegraphics[width=75mm, height=75mm]{examples/bedslopeend.eps}494 } 495 496 \caption{Bedslope example viewed with Swollen}497 \label{fig:bedslope2}498 \end{figure} 478 %\begin{figure}[hbt] 479 480 % \centerline{ \includegraphics[width=75mm, height=75mm]{examples/bedslope_start.eps}} 481 482 % \caption{Bedslope example viewed with Swollen} 483 % \label{fig:bedslopestart} 484 %\end{figure} 485 486 487 %\begin{figure}[hbt] 488 489 % \centerline{ 490 % \includegraphics[width=75mm, height=75mm]{examples/bedslope_during.eps} 491 % \includegraphics[width=75mm, height=75mm]{examples/bedslope_end.eps} 492 % } 493 494 % \caption{Bedslope example viewed with Swollen} 495 % \label{fig:bedslope2} 496 %\end{figure} 499 497 500 498 … … 513 511 scenario, rather than the artificial illustrative one used in 514 512 \code{bedslopephysical.py}. The domain of interest surrounds the Sydney region, 515 and predominantly covers Sydney Harbour. A hypothetical tsunami wave is 513 and predominantly covers Sydney Harbour. A hypothetical tsunami wave is 516 514 generated by a submarine mass failure situated on the edge of the 517 515 continental shelf. … … 569 567 area of a triangle used for triangulation---and mesh points are 570 568 created inside the polygon through a random process. Figure 571 \ref{fig:pentagon} shows a simple example of this, in which 569 \ref{fig:pentagon} shows a simple example of this, in which 572 570 the triangulation is carried out within a pentagon. 573 571 574 572 575 \begin{figure}[hbt] 576 577 578 579 \caption{Mesh points are created inside the polygon}580 \label{fig:pentagon} 581 \end{figure} 573 %\begin{figure}[hbt] 574 575 576 577 % \caption{Mesh points are created inside the polygon} 578 % \label{fig:pentagon} 579 %\end{figure} 582 580 583 581 Boundary tags are not restricted to \code{`left'}, \code{`right'}, … … 596 594 resolution. See Figure \ref{fig:interior meshes}. 597 595 598 \begin{figure}[hbt] 599 600 601 602 \caption{Interior meshes with individual resolution}603 \label{fig:interior meshes} 604 \end{figure} 596 %\begin{figure}[hbt] 597 598 599 600 % \caption{Interior meshes with individual resolution} 601 % \label{fig:interior meshes} 602 %\end{figure} 605 603 606 604 In its general form, \code{pmesh} takes for its input a bounding … … 633 631 \code{meshname}. 634 632 635 The statements 633 The statements 636 634 637 635 {\small \begin{verbatim} … … 643 641 are used to read in the specific polygons \code{project.harbour\_polygon\_2} and 644 642 \code{botanybay\_polygon\_2} from \code{project.py} and assign a 645 common resolution of 5000 to each. The statement 643 common resolution of 5000 to each. The statement 646 644 647 645 {\small \begin{verbatim} 648 646 create_mesh_from_regions(project.diffpolygonall,% 649 boundary_tags= {'bottom': [0],% 647 boundary_tags= {'bottom': [0],% 650 648 'right1': [1],% 651 649 'right0': [2],% … … 656 654 'left3': [7]},% 657 655 maximum_triangle_area=100000,% 658 filename=meshname,% 656 filename=meshname,% 659 657 interior_regions=interior_regions) 660 658 \end{verbatim}} 661 659 662 660 is then used to create the mesh, taking the bounding polygon to be the polygon 663 \code{diffpolygonall} specified in \code{project.py}. The 664 argument \code{boundary\_tags} assigns a dictionary, whose keys are the 665 names of the boundary tags used for the bounding polygon---\code{`bottom'}, 666 `right0', `right1', `right2', `top', `left1', `left2' and `left3'--- 661 \code{diffpolygonall} specified in \code{project.py}. The 662 argument \code{boundary\_tags} assigns a dictionary, whose keys are the 663 names of the boundary tags used for the bounding polygon---\code{`bottom'}, 664 `right0', `right1', `right2', `top', `left1', `left2' and `left3'--- 667 665 and whose values identify the indices of the segments associated with each of these 668 666 tags. (The value associated with each boundary tag is a one-element list.) … … 697 695 taken from \code{project.py}. 698 696 699 {\small \begin{verbatim} 697 {\small \begin{verbatim} 700 698 domain.set_name(project.basename)% 701 699 domain.set_datadir(project.outputdir)% … … 720 718 \code{slump\_tsunami}. This is similar to how we set elevation in 721 719 \code{bedslopephysical.py} using a function---however, in this case the 722 function is both more complex and more interesting. 723 724 The function returns the water displacement for all \code{x} 725 and \code{y} in the domain. The water displacement is a ?? function that depends 720 function is both more complex and more interesting. 721 722 The function returns the water displacement for all \code{x} 723 and \code{y} in the domain. The water displacement is a ?? function that depends 726 724 on the characteristics of the slump (length, thickness, slope, etc), its 727 location (origin) and the depth at that location. 725 location (origin) and the depth at that location. 728 726 729 727 … … 741 739 The elevation is specified by reading data from a file: 742 740 743 {\small \begin{verbatim} 744 domain.set_quantity('elevation', 745 filename = project.combineddemname + '.pts', 746 use_cache = True, 747 verbose = True) 741 {\small \begin{verbatim}% 742 domain.set_quantity('elevation',% 743 filename = project.combineddemname + '.pts',% 744 use_cache = True,% 745 verbose = True)% 748 746 \end{verbatim}} 749 747 … … 772 770 \subsection{Boundary Conditions} 773 771 774 Setting boundaries follows a similar pattern to the one used for 775 \code{bedslopephysical.py}, except that in this case we need to associate a 772 Setting boundaries follows a similar pattern to the one used for 773 \code{bedslopephysical.py}, except that in this case we need to associate a 776 774 boundary type with each of the 777 boundary tag names introduced when we established the mesh. In place of the four 778 boundary types introduced for \code{bedslopephysical.py}, we use the reflective 775 boundary tag names introduced when we established the mesh. In place of the four 776 boundary types introduced for \code{bedslopephysical.py}, we use the reflective 779 777 boundary for each of the 780 778 eight tagged segments: … … 794 792 {\small \begin{verbatim} 795 793 import time t0 = time.time() 796 794 797 795 for t in domain.evolve(yieldstep = 120, duration = 18000): 798 796 print domain.timestepping_statistics() 799 797 print domain.boundary_statistics(tags = 'bottom') 800 798 801 799 print 'That took %.2f seconds' %(time.time() 802 800 \end{verbatim}} … … 823 821 The listings are intended merely to give the reader an idea of what 824 822 each feature is, where to find it and how it can be used---they do 825 not give full specifications of the features. For these the reader823 not give full specifications. For these the reader 826 824 may consult the code. The code for every function or class contains 827 825 a documentation string, or `docstring', that specifies the precise … … 873 871 874 872 % Translate following into layman's language 875 Creates a triangular mesh based on a bounding polygon and a number 876 of internal polygons. For each polygon the user specifies a 877 resolution---that is, the maximal area of triangles in the mesh. The 878 bounding polygon also has symbolic \code{tags} associated with it. 873 This function is used to create a triangular mesh suitable for use with 874 \anuga, within a specified region. The region is specified as the interior of a polygon 875 (the \emph{bounding polygon}). The user specifies the bounding polygon and the 876 \emph{resolution}---that is, maximal area of any triangle in the mesh. There is 877 also an option to specify a number of internal polygons within each of which a 878 separate mesh is created, generally with a smaller resolution. Additionally, 879 the user specifies a list of boundary tags, one for each edge of the bounding 880 polygon. 879 881 \end{funcdesc} 880 882 … … 885 887 Module: \code{pyvolution.pmesh2domain} 886 888 887 Converts a generated mesh file to a domain object. 889 Once the initial mesh file has been created, this function is applied 890 to convert it to a domain object---that is, to a member of 891 the special Python class Domain (or a subclass of Domain), which provides access to properties and 892 methods that allow quantities to be set and other operations to be carried out. 888 893 889 894 \code{file\_name} is the name of the mesh file to be converted, … … 919 924 \section{Setting Quantities} 920 925 921 \begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None, 922 geospatial_data = None, filename = None, attribute_name = None, 926 \begin{funcdesc}{set\_quantity}{name, numeric = None, quantity = None, function = None, 927 geospatial_data = None, filename = None, attribute_name = None, 923 928 alpha = None, location = 'vertices', indices = None, verbose = False, 924 929 use_cache = False} … … 926 931 \code{pyvolution.quantity.set_values}) 927 932 928 numeric:\\ 929 Compatible list, Numeric array (see below) or constant. If callable 930 it will treated as a function (see below) If instance of another 931 Quantity it will be treated as such. If geo\_spatial object it will 932 be treated as such 933 934 quantity:\\ 935 Another quantity (compatible quantity, e.g. obtained as a linear 936 combination of quantities) 937 938 function:\\ 939 Any callable object that takes two one-dimensional arrays \code{x} and 940 \code{y} 941 each of length $N$ and returns an array also of length $N$. 942 The function will be evaluated at points determined by 943 location and indices in the underlying mesh. 944 945 geospatial_data:\\ 946 Arbitrary geospatial dataset in the form of the class 947 Geospatial_data. Mesh points are populated using least squares 948 fitting 949 950 points:\\ 951 $N \times 2$ array of data points for use with least squares fit 952 If points are present, an $N$ array of attribute 953 values corresponding to 954 each data point must be present. 955 956 values:\\ 957 If points is specified, values is an array of length N containing 958 attribute values for each point. 959 960 data_georef:\\ 961 If points is specified, geo_reference applies to each point. 962 963 filename:\\ 964 Name of a .pts file containing data points and attributes for 965 use with least squares. 966 967 attribute_name:\\ 968 If specified, any array matching that name 969 will be used. from file or geospatial_data. 970 Otherwise a default will be used. 971 972 alpha:\\ 973 Smoothing parameter to be used with least squares fits. 974 See module least_squares for further details about alpha. 975 Alpha will only be used with points, values or filename. 976 Otherwise it will be ignored. 977 978 979 %location: Where values are to be stored. 980 % Permissible options are: vertices, edges, centroids 981 % Default is 'vertices' 982 983 % In case of location == 'centroids' the dimension values must 984 % be a list of a Numerical array of length N, 985 % N being the number of elements. 986 % Otherwise it must be of dimension Nx3 987 988 989 % The values will be stored in elements following their 990 % internal ordering. 991 992 % If location is not 'unique vertices' Indices is the 993 % set of element ids that the operation applies to. 994 % If location is 'unique vertices' Indices is the set 995 % of vertex ids that the operation applies to. 996 997 % If selected location is vertices, values for 998 % centroid and edges will be assigned interpolated 999 % values. In any other case, only values for the 1000 % specified locations will be assigned and the others 1001 % will be left undefined. 1002 1003 %verbose: True means that output to stdout is generated 1004 1005 %use_cache: True means that caching of intermediate results is 1006 % attempted for least squares fit. 933 This function is used to associate quantities with a domain. It is very flexible and can be 934 used with many data types: a statement of the form \code{domain.set\_quantity{name, x}} can 935 be used to define a quantity having the name \code{name}, where the other argument \code{x} can 936 be any of the following: 937 938 \begin{itemize} 939 \item a number 940 \item a list of numbers 941 \item a Numeric array 942 \item a function (e.g. see the samples introduced in Chapter 2) 943 \item an expression composed of other quantities and numbers, arrays, lists (for 944 example, a linear combination of quantities) 945 \item the name of a file from which the data can be read 946 \item a geospatial dataset 947 \end{itemize} 948 1007 949 1008 950 Exactly one of the arguments … … 1044 986 1045 987 \code{quantities} is either the name of a single quantity to be 1046 interpolated or a list of such quantity names. The resulting988 interpolated or a list of such quantity names. In the second case, the resulting 1047 989 function will return a tuple of values---one for each quantity. 1048 990 … … 1067 1009 1068 1010 \code{time} is an array of monotonically increasing times and 1069 \code{quantities} is an array , or dictionary of arrays,of values to1011 \code{quantities} is an array---or dictionary of arrays---of values to 1070 1012 be interpolated. The parameter \code{interpolation_points} may be 1071 1013 used to specify at which points interpolated quantities are to be 1072 1014 computed whenever the object is called. If the default value 1073 \code{None} is used, itreturns an average value.1015 \code{None} is used, the function returns an average value. 1074 1016 \end{classdesc} 1075 1017 … … 1105 1047 within each quantity. 1106 1048 \end{funcdesc} 1107 1108 1109 1049 1110 1050 \begin{funcdesc} {get_boundary_tags}{??} … … 1203 1143 1204 1144 \end{funcdesc} 1205 1206 1207 \begin{funcdesc}{statistics}{???} 1208 1209 print domain.statistics() will provide basic structural statistics about e.g.\ mesh in the form of an area histogram 1210 \end{funcdesc} 1211 1212 1145 1146 1213 1147 \begin{funcdesc}{get_quantity}{???} 1214 Module: \code{pyvolution.domain} 1148 Module: \code{pyvolution.domain} 1215 1149 Allow access to individual quantities and their methods 1216 1217 \end{funcdesc} 1218 1219 1150 1151 \end{funcdesc} 1152 1153 1220 1154 \begin{funcdesc}{get_values}{???} 1221 Module: \code{pyvolution.quantity} 1222 1155 Module: \code{pyvolution.quantity} 1156 1223 1157 Extract values for quantity as an array 1224 1225 \end{funcdesc} 1226 1227 1158 1159 \end{funcdesc} 1160 1161 1228 1162 \begin{funcdesc}{get_integral}{???} 1229 Module: \code{pyvolution.quantity} 1230 1163 Module: \code{pyvolution.quantity} 1164 1231 1165 Return computed integral over entire domain for this quantity 1232 1233 \end{funcdesc} 1234 1235 1236 \section{Other} 1237 1238 \begin{funcdesc}{domain.create_quantity_from_expression}{???} 1239 1240 Handy for creating derived quantities on-the-fly. 1166 1167 \end{funcdesc} 1168 1169 1170 \section{Other} 1171 1172 \begin{funcdesc}{domain.create_quantity_from_expression}{???} 1173 1174 Handy for creating derived quantities on-the-fly. 1241 1175 See \code{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use. 1242 \end{funcdesc} 1176 \end{funcdesc} 1243 1177 1244 1178 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% … … 1335 1269 1336 1270 \begin{funcdesc}{sww2dem}{???} 1337 Module: \code{pyvolution.data\_manager} 1338 1339 1340 \end{funcdesc} 1341 1342 1271 Module: \code{pyvolution.data\_manager} 1272 1273 1274 \end{funcdesc} 1275 1276 1343 1277 \begin{funcdesc}{dem2pts}{???} 1344 Module: \code{pyvolution.data_manager} 1345 1346 1347 \end{funcdesc} 1278 Module: \code{pyvolution.data_manager} 1279 1280 1281 \end{funcdesc} 1348 1282 1349 1283 %\[ … … 1421 1355 \chapter{Supporting Tools} 1422 1356 1357 This section describes a number of supporting tools, supplied with \anuga, that offer a 1358 variety of types of functionality and enhance the basic capabilities of \anuga. 1423 1359 1424 1360 \section{caching} … … 1446 1382 This type of caching is particularly useful for computationally intensive 1447 1383 functions with few frequently used combinations of input arguments. Note that 1448 if the inputs or output are very large caching m ightnot save time because1384 if the inputs or output are very large caching may not save time because 1449 1385 disc access may dominate the execution time. 1450 1386 1451 If the function definition changes after a result has been cached itwill be1387 If the function definition changes after a result has been cached, this will be 1452 1388 detected by examining the functions \code{bytecode (co_code, co_consts, 1453 func_defualts, co_argcount)} and it will be recomputed. 1454 1455 Options are set 1456 by means of the function \code{set_option(key, value)}, where \code{key} is a key associated with a 1457 Python dictionary \code{options} that stores settings such as the name of the directory used, the maximum 1389 func_defualts, co_argcount)} and the function will be recomputed. 1390 1391 Options are set by means of the function \code{set_option(key, value)}, 1392 where \code{key} is a key associated with a 1393 Python dictionary \code{options}. This dictionary stores settings such as the name of 1394 the directory used, the maximum 1458 1395 number of cached files allowed, and so on. 1459 1396 … … 1461 1398 have been changed, the function is recomputed and the results stored again. 1462 1399 1463 Other features include support for compression and a capability to \ldots1400 %Other features include support for compression and a capability to \ldots 1464 1401 1465 1402 … … 1468 1405 {\small \begin{verbatim} 1469 1406 result = cache(func, args, kwargs, dependencies, cachedir, verbose, 1470 compression, evaluate, test, return_filename) }1407 compression, evaluate, test, return_filename) 1471 1408 \end{verbatim}} 1472 1409 1473 \textbf{ARGUMENTS:} 1474 1475 \begin{tabular}{ll} 1476 \code{func} & Function object (Required)\\ 1477 \code{args} & Arguments to func (Default: ())\\ 1478 \code{kwargs} & Keyword arguments to func (Default: {}) \\ 1479 \code{dependencies} & Filenames that func depends on (Default: \code{None})\\ 1480 \code{cachedir} & Directory for cache files (Default: \code{options['cachedir']})\\ 1481 \code{verbose} & Flag verbose output to stdout 1482 (Default: \code{options['verbose']})\\ 1483 \code{compression} & Flag zlib compression (Default: \code{options['compression']})\\ 1484 \code{evaluate} & Flag forced evaluation of func (Default: 0)\\ 1485 \code{test} & Flag test for cached results (Default: 0)\\ 1486 \code{clear} & Flag delete cached results (Default: 0)\\ 1487 \code{return_filename} & Flag return of cache filename (Default: 0)\\ 1488 \end{tabular} 1489 1490 1491 \textbf{LIMITATIONS:} 1492 1493 \begin{itemize} 1494 \item Caching uses the apply function and will work with anything that can be 1495 pickled, so any limitation in apply or pickle extends to caching. 1496 1497 \item A function to be cached should not depend on global variables 1498 as wrong results may occur if globals are changed after a result has 1499 been cached. 1500 \end{itemize} 1501 1502 1503 1504 1410 1505 1411 \section{swollen} 1506 1507 1412 The output generated by \anuga may be viewed by means of the visualisation tool \code{swollen}, 1413 which takes the \code{sww} file output by \anuga and creates a visual representation of the data. 1414 Examples may be seen in Figures XX and YY. To view an \code{sww} file with \code{swollen} in the 1415 Windows environment, you can simply drag the icon representing the file over an icon on the desktop 1416 for the \code{swollen} executable file (or a shortcut to it). Alternatively, you can operate \code{swollen} 1417 from the command line, in both Windows and Linux environments. 1418 1419 On successful operation, you will see an interactive moving-picture display. You can use keys and the mouse 1420 to slow down, speed up or stop the display, change the viewing position or carry out a number of other 1421 simple operations. 1422 1508 1423 The main keys operating the interactive screen are:\\ 1509 1424 … … 1580 1495 \section{geo_spatial_data} 1581 1496 1582 This describes a class that represents arbitrary point data in UTM 1497 This describes a class that represents arbitrary point data in UTM 1583 1498 coordinates along with named attribute values. 1584 1499
Note: See TracChangeset
for help on using the changeset viewer.