Changeset 2485
 Timestamp:
 Mar 3, 2006, 4:46:24 PM (18 years ago)
 File:

 1 edited
Legend:
 Unmodified
 Added
 Removed

documentation/user_manual/anuga_user_manual.tex
r2482 r2485 303 303 \end{verbatim}} 304 304 305 This simply associates an elevation with each point $(x, y)$of306 the plane. It specifies that the bed slopes linearly in the $x$307 direction, with slope $\frac{1}{2}$, and is constant in the $y$ 308 direction.\\%[screen shot?]309 \\ 310 Once the function $f$is specified, the quantity305 This simply associates an elevation with each point \code{(x, y)} of 306 the plane. It specifies that the bed slopes linearly in the 307 \code{x} direction, with slope $\frac{1}{2}$, and is constant in 308 the \code{y} direction. %[screen shot?] 309 310 Once the function \code{f} is specified, the quantity 311 311 \code{elevation} is assigned through the simple statement: 312 312 … … 709 709 710 710 \begin{itemize} 711 \item Functions and Classes 711 \item Establishing the Mesh 712 \item Initialising the Domain 713 \item Specifying the Quantities 714 \item Initial Conditions 715 \item Boundary Conditions 716 \item Forcing Functions 712 717 \item Diagnostics 713 \item Boundary Conditions714 \item Initial Conditions715 \item Forcing Functions.716 718 \end{itemize} 717 719 718 The listings do not give full specifications of the features, for 719 which the reader may consult the docstrings provided in the code. 720 They are intended merely to give the reader an idea of what each 721 feature is and how it can be used. 722 723 \section{Functions and Classes} 724 725 %\indexedcodeheader{create\_mesh\_from\_regions}\label{codehdr:createmeshfromregions} 726 727 % Creates a triangular mesh based on a bounding polygon and 728 % a number of internal polygons. For each polygon the user specifies a resolutionthat is, the maximal area 729 % of triangles in the mesh. The bounding polygon also has symbolic \code{tags} associated with it. 730 731 % \textbf{Arguments:} 732 733 % \begin{itemize} 734 % \item the bounding polygon, %do we need to spell out how a polygon is specified? 735 % \item a dictionary of boundary tags, for all segments of the bounding polygon, 736 % \emph{[not clear what the keys and values of this dictionary are]} 737 % \item the resolution for the bounding polygon, 738 % \item (optional) a filename, \emph{[what is the file for?]} 739 % \item a list of 2tuples \code{(polygon, resolution)}, specifying the interior polygons and 740 % their associated resolutions. 741 % \end{itemize} 742 743 %********************************************************************************************* 744 745 %\emph{\textbf{[The following is how the description of 746 %\emph{\code{create\_mesh\_from\_regions}} would be presented using 747 %the Python documentation system's \emph{\code{funcdesc}} environment 748 %for describing a modulelevel function.]}} 720 The listings are intended merely to give the reader an idea of what 721 each feature is, where to find it and how it can be usedthey do 722 not give full specifications of the features. For these the reader 723 may consult the code. The code for every function or class contains 724 a documentation string, or `docstring', that specifies the precise 725 syntax for its use. This appears immediately after the line 726 introducing the code, between two sets of triple quotes. 727 728 Each paragraph also describes the location of the module in which 729 the code for the feature being described can be found. All modules 730 are in the folder \code{inundation} or its subfolders, and the 731 location of each module is described relative to this folder. Rather 732 than using pathnames, whose syntax depends on the operating system, 733 we use the format adopted for importing the function or class for 734 use in Python code. For example, suppose we wish to specify that the 735 function \code{create\_mesh\_from\_regions} is in a module called 736 \code{mesh\_interface} in a subfolder of \code{inundation} called 737 \code{pmesh}. In Linux or Unix syntax, the pathname of the file 738 containing the function, relative to \code{inundation}, would be 739 740 \begin{center} 741 \code{pmesh/mesh\_interface.py} 742 \end{center} 743 744 while in Windows syntax it would be 745 746 \begin{center} 747 \code{pmesh}$\backslash$\code{mesh\_interface.py} 748 \end{center} 749 750 Rather than using either of these forms, in this chapter we specify 751 the location simply as \code{pmesh.mesh_interface}, in keeping with 752 the usage in the Python statement for importing the function, 753 namely: 754 \begin{center} 755 \code{from pmesh.mesh\_interface import create\_mesh\_from\_regions} 756 \end{center} 757 758 759 \section{Mesh Generation} 749 760 750 761 \begin{funcdesc} {create\_mesh\_from\_regions}{bounding_polygon, … … 756 767 mesh_geo_reference=None, 757 768 minimum_triangle_angle=28.0} 769 Module: \code{pmesh.mesh\_interface} 770 758 771 Creates a triangular mesh based on a bounding polygon and a number 759 772 of internal polygons. For each polygon the user specifies a … … 762 775 \end{funcdesc} 763 776 764 %********************************************************************************************* 765 766 %\indexedcodeheader{pmesh\_to\_domain\_instance} \nopagebreak 767 768 % Converts a generated mesh file to a domain object. 769 770 % \textbf{Arguments:} 771 772 % \begin{itemize} 773 % \item \code{file\_name} is the name of the mesh file to convert, including the extension 774 % \item \code{DomainClass} is the Class that will be returned. 775 % It must be a subclass of \code{Domain}, with the same interface as 776 % domain. In practice, it can usually be set simply to 777 % \code{Domain}. 778 % \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain. 779 % \end{itemize} 780 781 782 % \begin{itemize} 783 % \item Mesh file name 784 % \item Class name, specifying the domain class to be instantiated. 785 % \end{itemize} 786 % 787 %********************************************************************************************* 777 %%%%%% 778 \section{Initialising Domain} 788 779 789 780 \begin{funcdesc} {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False} 781 Module: \code{pyvolution.pmesh2domain} 782 790 783 Converts a generated mesh file to a domain object. 791 784 792 \code{file\_name} is the name of the mesh file to convert, including 793 the extension. \code{DomainClass} is the class to be returned, which 794 must be a subclass of \code{Domain}, with the same interface as 795 \code{Domain}in practice, it can usually be set simply to 796 \code{Domain}. 797 785 \code{file\_name} is the name of the mesh file to be converted, 786 including the extension. \code{DomainClass} is the class to be 787 returned, which must be a subclass of \code{Domain}, with the same 788 interface as \code{Domain}in practice, it can usually be set 789 simply to \code{Domain}. 798 790 \end{funcdesc} 799 %********************************************************************************************* 800 801 802 %\indexedcodeheader{file\_function} %in util.py "High priority" 803 804 % Reads the time history of spatial data from NetCDF file and returns a callable object. 805 806 % \textbf{Arguments:} 807 808 % \code{filename}  Name of \code{sww} or \code{tms} file (see 809 % Section \ref{sec:file formats} on page \pageref{sec:file formats} 810 % for details about file formats). 811 812 % \begin{quote} 813 % If the file has extension \code{sww} then it is assumed to be spatiotemporal 814 % or temporal and the callable object will have the form \code{f(t,x,y)} or \code{f(t)} 815 % depending on whether the file contains spatial data. 816 817 % If the file has extension \code{tms} then it is assumed to be temporal only 818 % and the callable object will have the form \code{f(t)}. 819 820 % Either form will return interpolated values based on the input file 821 % using the underlying \code{interpolation\_function}. 822 % \end{quote} 823 824 % \code{domain}  Associated domain object 825 % If domain is specified, model time (\code{domain.starttime}) 826 % will be checked and possibly modified. 827 828 % \begin{quote} 829 % All times are assumed to be in UTC. 830 831 % All spatial information is assumed to be in absolute UTM coordinates. 832 % \end{quote} 833 834 % \code{quantities}  the name of the quantity to be interpolated or a 835 % list of quantity names. The resulting function will return 836 % a tuple of values  one for each quantity. 837 838 % \code{interpolation\_points}  list of absolute UTM coordinates for points at 839 % which values are sought 840 841 % \code{use\_cache}: \code{True} means that caching of intermediate result of 842 % \code{Interpolation\_function} is attempted 843 844 845 \begin{funcdesc}{file_function}{filename, 791 792 %%%%%% 793 \section{Setting Quantities} 794 795 \begin{funcdesc}{set\_quantity}{name, *args, **kwargs} 796 Module: \code{pyvolution.domain}  see also 797 \code{pyvolution.quantity.set_values} 798 799 numeric:\\ 800 Compatible list, Numeric array (see below) or constant. If callable 801 it will treated as a function (see below) If instance of another 802 Quantity it will be treated as such. If geo_spatial object it will 803 be treated as such 804 805 quantity:\\ 806 Another quantity (compatible quantity, e.g. obtained as a linear 807 combination of quantities) 808 809 function:\\ 810 Any callable object that takes two onedimensional arrays \code{x} and 811 \code{y} 812 each of length $N$ and returns an array also of length $N$. 813 The function will be evaluated at points determined by 814 location and indices in the underlying mesh. 815 816 geospatial_data:\\ 817 Arbitrary geospatial dataset in the form of the class 818 Geospatial_data. Mesh points are populated using least squares 819 fitting 820 821 points:\\ 822 $N \times 2$ array of data points for use with least squares fit 823 If points are present, an $N$ array of attribute 824 values corresponding to 825 each data point must be present. 826 827 values:\\ 828 If points is specified, values is an array of length N containing 829 attribute values for each point. 830 831 data_georef:\\ 832 If points is specified, geo_reference applies to each point. 833 834 filename:\\ 835 Name of a .pts file containing data points and attributes for 836 use with least squares. 837 838 attribute_name:\\ 839 If specified, any array matching that name 840 will be used. from file or geospatial_data. 841 Otherwise a default will be used. 842 843 alpha:\\ 844 Smoothing parameter to be used with least squares fits. 845 See module least_squares for further details about alpha. 846 Alpha will only be used with points, values or filename. 847 Otherwise it will be ignored. 848 849 850 location: Where values are to be stored. 851 Permissible options are: vertices, edges, centroids 852 Default is 'vertices' 853 854 In case of location == 'centroids' the dimension values must 855 be a list of a Numerical array of length N, 856 N being the number of elements. 857 Otherwise it must be of dimension Nx3 858 859 860 The values will be stored in elements following their 861 internal ordering. 862 863 If location is not 'unique vertices' Indices is the 864 set of element ids that the operation applies to. 865 If location is 'unique vertices' Indices is the set 866 of vertex ids that the operation applies to. 867 868 If selected location is vertices, values for 869 centroid and edges will be assigned interpolated 870 values. In any other case, only values for the 871 specified locations will be assigned and the others 872 will be left undefined. 873 874 verbose: True means that output to stdout is generated 875 876 use_cache: True means that caching of intermediate results is 877 attempted for least squares fit. 878 879 Exactly one of the arguments 880 numeric, quantity, function, points, filename 881 must be present. 882 \end{funcdesc} 883 884 %%% 885 \anuga provides a number of predefined initial conditions to be used 886 with \code{set_quantity}. 887 888 \begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None, \ 889 x0=0.0, y0=0.0, alpha=0.0, \ 890 gravity=9.8, gamma=1.85, \ 891 massco=1, dragco=1, frictionco=0, psi=0, \ 892 dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, \ 893 domain=None, 894 verbose=False} 895 This function returns a callable object representing an initial water 896 displacement generated by a submarine sediment slide. 897 898 The arguments include the downslope slide length, the water depth to the slide centre of mass, 899 and the bathymetric slope. 900 \end{funcdesc} 901 902 903 %%% 904 \begin{funcdesc}{file_function}{filename, 846 905 domain = None, 847 906 quantities = None, … … 849 908 verbose = False, 850 909 use_cache = False} 851 852 Reads the time history of spatial data from NetCDF file and returns a callable object. Returns 853 interpolated values based on the input file 854 using the underlying \code{interpolation\_function}. 855 856 \code{quantities} is either the name of a single quantity to be interpolated or a 857 list of such quantity names. The resulting function will return 858 a tuple of valuesone for each quantity. 859 860 \code{interpolation\_points} is a list of absolute UTM coordinates for points at 861 which values are sought. 862 863 \end{funcdesc} 864 865 866 % See Interpolation function for further documentation 867 %\indexedcodeheader{Interpolation\_function} 868 % Creates a callable object \code{f(t, id)} or \code{f(t,x,y)} 869 % interpolated from a time series defined at the vertices of 870 % a triangular mesh (such as those stored in \code{sww} files). 871 872 % Let $m$ be the number of vertices, $n$ the number of triangles 873 % and $p$ the number of time steps. 874 875 % \textbf{Mandatory Arguments:} 876 877 % \begin{tabular}{ll} 878 % \code{time}: & $p \times 1$ array of monotonously increasing times (Float)\\ 879 880 881 % \code{quantities}: & Dictionary of arrays or one array (Float). The arrays must \\ 882 % & have dimensions either $p \times m$ or $m \times 1$. The resulting function \\ 883 % & will be time dependent in the former case and constant with respect to time \\ 884 % & in the latter case.\\ 885 % \end{tabular} 886 887 888 % \textbf{Optional Arguments:} 889 890 % \begin{tabular}{ll} 891 % \code{quantity\_names}: & List of keys into the quantities dictionary\\ 892 893 % \code{vertex\_coordinates}: & $m \times 2$ array of coordinates (Float)\\ 894 895 % \code{triangles}: & $n \times 3$ array of indices into \code{vertex\_coordinates} (Int)\\ 896 897 % \code{interpolation\_points}: & $N \times 2$ array of coordinates to be interpolated to \\ 898 899 % \code{verbose}: & Level of reporting\\ 900 % \end{tabular} 901 902 % The quantities returned by the callable object are specified by 903 % the list \code{quantities} which must contain the names of the 904 % quantities to be returned and also reflect the order, e.g. for 905 % the shallow water wave equation, one would have 906 % \code{quantities = ['stage', 'xmomentum', 'ymomentum']}. 907 908 % The parameter \code{interpolation_points} decides at which points interpolated 909 % quantities are to be computed whenever the object is called. 910 % If \code{None}, returns average value. 911 910 Module: \code{pyvolution.util} 911 912 Reads the time history of spatial data from NetCDF file and returns 913 a callable object. Returns interpolated values based on the input 914 file using the underlying \code{interpolation\_function}. 915 916 \code{quantities} is either the name of a single quantity to be 917 interpolated or a list of such quantity names. The resulting 918 function will return a tuple of valuesone for each quantity. 919 920 \code{interpolation\_points} is a list of absolute UTM coordinates 921 for points at which values are sought. 922 \end{funcdesc} 923 924 %%% 912 925 \begin{classdesc}{Interpolation_function}{self, 913 926 time, … … 918 931 interpolation_points = None, 919 932 verbose = False} 933 Module: \code{pyvolution.least\_squares} 934 920 935 Creates a callable object \code{f(t, id)} or \code{f(t,x,y)} 921 936 interpolated from a time series defined at the vertices of a … … 925 940 \code{quantities} is an array, or dictionary of arrays, of values to 926 941 be interpolated. The parameter \code{interpolation_points} may be 927 used to specify at which points interpolated 928 quantities are to be computed whenever the object is called. 929 If the default value \code{None} is used, returnsaverage value.942 used to specify at which points interpolated quantities are to be 943 computed whenever the object is called. If the default value 944 \code{None} is used, it returns an average value. 930 945 \end{classdesc} 931 946 932 933 \begin{funcdesc}{set\_region}{ ???}947 %%% 948 \begin{funcdesc}{set\_region}{functions} 934 949 [Low priority. Will be merged into set\_quantity] 950 951 Module:\code{pyvolution.domain} 935 952 \end{funcdesc} 936 953 937 \begin{funcdesc}{set\_quantity}{???} 938 [Pretty mature] 939 \end{funcdesc} 940 941 \begin{funcdesc}{set\_boundary}{???} 942 [Pretty mature] 943 \end{funcdesc} 944 945 946 947 \section{Diagnostics} 948 949 \begin{funcdesc}{write\_time}{???} 950 951 \end{funcdesc} 952 953 954 \begin{funcdesc}{write\_boundary\_statistics}{???} 955 956 \end{funcdesc} 957 958 959 954 955 956 %%%%%% 960 957 \section{Boundary Conditions} 961 958 … … 963 960 be used with \code{set\_boundary}. 964 961 965 \subsection{Predefined boundary conditions}966 967 \begin{classdesc}{Reflective_boundary}{Boundary}968 Reflective boundary returns same conserved quantities as those present in 969 the neighbouring volume but reflected. 970 971 This class is specific to the shallow water equation as it works with the 972 momentum quantities assumed to be the second and third conserved quantities. 973 \end{classdesc}974 975 976 \begin{classdesc}{Transmissive_boundary}{domain = None} 977 A transmissive boundary returns the same conserved quantities as 978 those present in the neighbouring volume. 979 980 The underlying domain must be specified when the boundary is instantiated.981 982 983 984 \begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None}985 A Dirichlet boundary returns constant values for the conserved 986 quantities. 987 \end{classdesc} 988 989 990 \begin{classdesc}{Time_boundary}{domain = None, f = None} 991 A timedependent boundary returns values for the conserved quantities as a 992 function \code{f(t)} of time. The user must specify the domain to get access to the model 993 time. 994 \end{classdesc}995 996 997 \begin{classdesc}{File_boundary}{Boundary} 998 The boundary values are obtained from a file and interpolated. The file is 999 assumed to contain a time series and possibly also spatial information. 1000 The conserved quantities are given as a function of time. 1001 \end{classdesc} 1002 1003 1004 \subsection{Userdefined boundary conditions} 1005 [How to roll your own] 1006 1007 1008 1009 \section{Initial Conditions} 1010 1011 \ anuga provides a number of predefined initial conditions to be used with1012 \code{set_quantity}. 1013 1014 \begin{funcdesc}{tsunami_slump}{length, depth, slope, width=None, thickness=None, \ 1015 x0=0.0, y0=0.0, alpha=0.0, \ 1016 gravity=9.8, gamma=1.85, \ 1017 massco=1, dragco=1, frictionco=0, psi=0, \ 1018 dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, \ 1019 domain=None, 1020 verbose=False} 1021 This function returns a callable object representing an initial water 1022 displacement generated by a submarine sediment slide. 1023 1024 The arguments include the downslope slide length, the water depth to the slide centre of mass, 1025 and the bathymetric slope. 1026 \end{funcdesc} 962 \begin{funcdesc}{set\_boundary}{boundary_map} 963 Module: \code{pyvolution.domain} 964 \end{funcdesc} 965 966 967 %%% 968 \subsection{Predefined boundary conditions} 969 970 \begin{classdesc}{Reflective_boundary}{Boundary} 971 Module: \code{pyvolution.shallow\_water} 972 973 Reflective boundary returns same conserved quantities as those present in 974 the neighbouring volume but reflected. 975 976 This class is specific to the shallow water equation as it works with the 977 momentum quantities assumed to be the second and third conserved quantities. 978 \end{classdesc} 979 980 %%% 981 \begin{classdesc}{Transmissive_boundary}{domain = None} 982 Module: \code{pyvolution.generic\_boundary\_conditions} 983 984 A transmissive boundary returns the same conserved quantities as 985 those present in the neighbouring volume. 986 987 The underlying domain must be specified when the boundary is instantiated. 988 \end{classdesc} 989 990 %%% 991 \begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None} 992 Module: \code{pyvolution.generic\_boundary\_conditions} 993 994 A Dirichlet boundary returns constant values for the conserved 995 quantities. 996 \end{classdesc} 997 998 %%% 999 \begin{classdesc}{Time_boundary}{domain = None, f = None} 1000 Module: \code{pyvolution.generic\_boundary\_conditions} 1001 1002 A timedependent boundary returns values for the conserved 1003 quantities as a function \code{f(t)} of time. The user must specify 1004 the domain to get access to the model time. 1005 \end{classdesc} 1006 1007 %%% 1008 \begin{classdesc}{File_boundary}{Boundary} 1009 Module: \code{pyvolution.generic\_boundary\_conditions} 1010 1011 The boundary values are obtained from a file and interpolated. The 1012 file is assumed to contain a time series and possibly also spatial 1013 information. The conserved quantities are given as a function of 1014 time. 1015 \end{classdesc} 1016 1017 1018 \subsection{Userdefined boundary conditions} 1019 [How to roll your own] 1020 1021 1022 1023 1027 1024 1028 1025 \section{Forcing Functions} … … 1040 1037 %\end{itemize} 1041 1038 1039 1040 1041 \section{Diagnostics} 1042 1043 \begin{funcdesc}{write\_time}{???} 1044 1045 \end{funcdesc} 1046 1047 1048 \begin{funcdesc}{write\_boundary\_statistics}{???} 1049 1050 \end{funcdesc} 1042 1051 1043 1052 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% … … 1057 1066 \bigskip 1058 1067 1059 \begin{center} 1068 \begin{center} 1060 1069 1061 1070 \begin{tabular}{ll} \hline … … 1097 1106 1098 1107 1099 \end{center} 1108 \end{center} 1100 1109 1101 1110 \bigskip
Note: See TracChangeset
for help on using the changeset viewer.