Changeset 7134
- Timestamp:
- May 29, 2009, 3:45:23 PM (16 years ago)
- Location:
- anuga_core/documentation/user_manual
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
anuga_core/documentation/user_manual/anuga_user_manual.tex
r7124 r7134 216 216 regions using symbolic tags. These tags may then be used to set the 217 217 actual boundary conditions and attributes for different regions 218 (e.g. \the Manning friction coefficient) for each simulation.218 (e.g. the Manning friction coefficient) for each simulation. 219 219 220 220 Most \anuga components are written in the object-oriented programming … … 237 237 \item The mathematical model is the 2D shallow water wave equation. 238 238 As such it cannot resolve vertical convection and consequently not breaking 239 waves or 3D turbulence (e.g. \vorticity).239 waves or 3D turbulence (e.g. vorticity). 240 240 %\item The surface is assumed to be open, e.g. \anuga cannot model 241 241 %flow under ceilings or in pipes … … 251 251 \item Frictional resistance is implemented using Manning's formula, but 252 252 \anuga has not yet been fully validated in regard to bottom roughness. 253 %\item ANUGAcontains no tsunami-genic functionality relating to earthquakes.253 %\item \anuga contains no tsunami-genic functionality relating to earthquakes. 254 254 \end{itemize} 255 255 … … 523 523 not steady state as replication of momentum at the boundary 524 524 may cause numerical instabilities propagating into the domain and 525 eventually causing ANUGAto crash. If this occurs,525 eventually causing \anuga to crash. If this occurs, 526 526 consider using e.g. a Dirichlet boundary condition with a stage value 527 527 less than the elevation at the boundary. … … 574 574 uses different boundary tags -- in general, the possible tags are entirely selectable by the user when generating the mesh and not 575 575 limited to 'left', 'right', 'top' and 'bottom' as in this example.) 576 All segments in bounding polygon must be tagged. If a tag is not supplied, the default tag name 'exterior' will be assigned by ANUGA.576 All segments in bounding polygon must be tagged. If a tag is not supplied, the default tag name 'exterior' will be assigned by \anuga. 577 577 578 578 Using the boundary objects described above, we assign a boundary … … 629 629 The output is a NetCDF file with the extension \code{.sww}. It 630 630 contains stage and momentum information and can be used with the 631 ANUGAviewer \code{animate} to generate a visual631 \anuga viewer \code{animate} to generate a visual 632 632 display (see Section \ref{sec:animate}). See Section \ref{sec:file formats} 633 633 (page \pageref{sec:file formats}) for more on NetCDF and other file … … 666 666 \centerline{\includegraphics[width=75mm, height=75mm] 667 667 {graphics/bedslopestart.jpg}} 668 \caption{Runup example viewed with the ANUGAviewer}668 \caption{Runup example viewed with the \anuga viewer} 669 669 \label{fig:runupstart} 670 670 \end{figure} … … 727 727 \end{verbatim} 728 728 729 returns an \code{m xn} mesh similar to the one used in the previous example, except that now the729 returns an \code{mxn} mesh similar to the one used in the previous example, except that now the 730 730 extent in the x and y directions are given by the value of \code{length} and \code{width} 731 731 respectively. … … 763 763 \centerline{\includegraphics[height=75mm] 764 764 {graphics/channel1.png}}% 765 \caption{Simple channel example viewed with the ANUGAviewer.}765 \caption{Simple channel example viewed with the \anuga viewer.} 766 766 \label{fig:channel1} 767 767 \end{figure} … … 928 928 maximal area of a triangle used for triangulation -- and a triangular 929 929 mesh is created inside the polygon using a mesh generation engine. 930 On any given platform, the same mesh will be returned. 930 On any given platform, the same mesh will be returned each time the 931 script is run. 931 932 932 933 Boundary tags are not restricted to \code{'left'}, \code{'bottom'}, … … 1056 1057 1057 1058 Since we used \code{create_domain_from_regions} to create the mesh file, we do not need to 1058 create the domain explicitly, as the above function also does that.1059 create the domain explicitly, as the above function does both mesh and domain creation. 1059 1060 1060 1061 The following statements specify a basename and data directory, and 1061 sets a minimum storable height, which helps with visualisation. 1062 1063 \begin{verbatim} 1064 domain.set_name('cairns_' + project.scenario) # Name of sww file 1065 domain.set_datadir('.') # Store sww output here 1062 sets a minimum storable height, which helps with visualisation and post-processing 1063 if one wants to remove water less than 1cm deep (for instance). 1064 1065 \begin{verbatim} 1066 domain.set_name('cairns_' + project.scenario) # Name of SWW file 1067 domain.set_datadir('.') # Store SWW output here 1066 1068 domain.set_minimum_storable_height(0.01) # Store only depth > 1cm 1067 1069 \end{verbatim} … … 1073 1075 in this case, many of the values are read from the auxiliary file 1074 1076 \file{project.py} or, in the case of \code{elevation}, from an 1075 a ncillary points file.1077 auxiliary points file. 1076 1078 1077 1079 \subsubsection{Stage} 1078 1080 1079 The stage is initially set to 0.0 by the following statements:1081 The stage is initially set to 0.0 (i.e. Mean Sea Level) by the following statements: 1080 1082 1081 1083 \begin{verbatim} … … 1083 1085 domain.set_quantity('stage', tide) 1084 1086 \end{verbatim} 1087 1088 It could also take the value of the highest astronomical tide. 1085 1089 1086 1090 %For the scenario we are modelling in this case, we use a callable … … 1109 1113 \subsubsection{Elevation} 1110 1114 1111 The elevation is specified by reading data from a file: 1115 The elevation is specified by reading data from a file with a name derived from 1116 \code{project.demname} with the \code{.pts} extension: 1112 1117 1113 1118 \begin{verbatim} … … 1118 1123 alpha=0.1) 1119 1124 \end{verbatim} 1125 1126 The \code{alpha} parameter controls how smooth the elevation surface 1127 should be. See section \ref{class:alpha_shape}, page \pageref{class:alpha_shape}. 1128 1129 Setting \code{cache=True} allows \anuga to save the result in order 1130 to make subsequent runs faster. 1131 1132 Using \code{verbose=True} tells the function to write diagnostics to 1133 the screen. 1120 1134 1121 1135 \subsection{Boundary Conditions}\index{boundary conditions} … … 1165 1179 \begin{verbatim} 1166 1180 if project.scenario == 'slide': 1181 # Initial run without any event 1167 1182 for t in domain.evolve(yieldstep=10, finaltime=60): 1168 1183 print domain.timestepping_statistics() 1169 1184 print domain.boundary_statistics(tags='ocean_east') 1170 1185 1171 # Add slide 1172 thisstagestep = domain.get_quantity('stage') 1186 # Add slide to water surface 1173 1187 if allclose(t, 60): 1174 slide = Quantity(domain) 1175 slide.set_values(tsunami_source) 1176 domain.set_quantity('stage', slide + thisstagestep) 1177 1188 domain.add_quantity('stage', tsunami_source) 1189 1190 # Continue propagating wave 1178 1191 for t in domain.evolve(yieldstep=10, finaltime=5000, 1179 1192 skip_initial_step=True): … … 1464 1477 \label{sec:meshgeneration} 1465 1478 1466 \begin{funcdesc} {create\_mesh\_from\_regions}{bounding_polygon, 1467 boundary_tags, 1468 maximum_triangle_area, 1469 filename=None, 1470 interior_regions=None, 1471 poly_geo_reference=None, 1472 mesh_geo_reference=None, 1473 minimum_triangle_angle=28.0} 1479 \begin{funcdesc}{create_mesh_from_regions}{bounding_polygon, 1480 boundary_tags, 1481 maximum_triangle_area=None, 1482 filename=None, 1483 interior_regions=None, 1484 interior_holes=None, 1485 poly_geo_reference=None, 1486 mesh_geo_reference=None, 1487 minimum_triangle_angle=28.0, 1488 fail_if_polygons_outside=True, 1489 use_cache=False, 1490 verbose=True} 1474 1491 Module: \module{pmesh.mesh\_interface} 1475 1492 … … 1503 1520 \end{funcdesc} 1504 1521 1522 \begin{funcdesc}{create_domain_from_regions}{bounding_polygon, 1523 boundary_tags, 1524 maximum_triangle_area=None, 1525 mesh_filename=None, 1526 interior_regions=None, 1527 interior_holes=None, 1528 poly_geo_reference=None, 1529 mesh_geo_reference=None, 1530 minimum_triangle_angle=28.0, 1531 fail_if_polygons_outside=True, 1532 use_cache=False, 1533 verbose=True} 1534 1535 Module: \module{interface.py} 1536 1537 This higher-level function allows a user to create a domain (and associated mesh) 1538 inside a specified polygon. 1539 1540 \code{bounding_polygon} is a list of points in Eastings and Northings, 1541 relative to the zone stated in \code{poly_geo_reference} if specified. 1542 Otherwise points are just x, y coordinates with no particular 1543 association to any location. 1544 1545 \code{boundary_tags} is a dictionary of symbolic tags. For every tag there 1546 is a list of indices referring to segments associated with that tag. 1547 If a segment is omitted it will be assigned the default tag ''. 1548 1549 \code{maximum_triangle_area} is the maximal area per triangle 1550 for the bounding polygon, excluding the interior regions. 1551 1552 \code{mesh_filename} is the name of the file to contain the generated 1553 mesh data. 1554 1555 \code{interior_regions} is a list of tuples consisting of (polygon, 1556 resolution) for each region to be separately refined. Do not have 1557 polygon lines cross or be on-top of each other. Also do not have 1558 polygons close to each other. 1559 1560 \code{poly_geo_reference} is the geo_reference of the bounding polygon and 1561 the interior polygons. 1562 If none, assume absolute. Please pass one though, since absolute 1563 references have a zone. 1564 1565 \code{mesh_geo_reference} is the geo_reference of the mesh to be created. 1566 If none is given one will be automatically generated. It will use 1567 the lower left hand corner of bounding_polygon (absolute) 1568 as the x and y values for the geo_ref. 1569 1570 \code{minimum_triangle_angle} is the minimum angle allowed for each generated triangle. 1571 This controls the \emph{slimness} allowed for a triangle. 1572 1573 \code{fail_if_polygons_outside} -- if True (the default) an Exception in thrown 1574 if interior polygons fall outside the bounding polygon. If False, these 1575 will be ignored and execution continues. 1576 1577 \textbf{WARNING}. Note that the dictionary structure used for the 1578 parameter \code{boundary_tags} is different from that used for the 1579 variable \code{boundary} that occurs in the specification of a mesh. 1580 In the case of \code{boundary}, the tags are the \emph{values} of 1581 the dictionary, whereas in the case of \code{boundary_tags}, the 1582 tags are the \emph{keys} and the \emph{value} corresponding to a 1583 particular tag is a list of numbers identifying boundary edges 1584 labelled with that tag. Because of this, it is theoretically 1585 possible to assign the same edge to more than one tag. However, an 1586 attempt to do this will cause an error. 1587 1588 \textbf{WARNING}. Do not have polygon lines cross or be on-top of each 1589 other. This can result in regions of unspecified resolutions. Do 1590 not have polygon close to each other. This can result in the area 1591 between the polygons having small triangles. For more control 1592 over the mesh outline use the methods described below. 1593 1594 \end{funcdesc} 1595 1505 1596 \subsection{Advanced mesh generation} 1506 1597 … … 1508 1599 methods of the class \class{Mesh}. 1509 1600 1510 1511 \begin{classdesc} {Mesh}{userSegments=None,1512 userVertices=None,1513 holes=None,1514 regions=None}1601 \begin{classdesc}{Mesh}{userSegments=None, 1602 userVertices=None, 1603 holes=None, 1604 regions=None, 1605 geo_reference=None} 1515 1606 Module: \module{pmesh.mesh} 1516 1607 1517 1608 A class used to build a mesh outline and generate a two-dimensional 1518 1609 triangular mesh. The mesh outline is used to describe features on the 1519 mesh, such as the mesh boundary. Many of this classes methods are used 1520 to build a mesh outline, such as \code{add\_vertices} and 1521 \code{add\_region\_from\_polygon}. 1610 mesh, such as the mesh boundary. Many of this class's methods are used 1611 to build a mesh outline, such as \code{add_vertices()} and 1612 \code{add_region_from_polygon()}. 1613 1614 \code{userSegments} and \code{userVertices} define the outline enclosing the mesh. 1615 1616 \code{holes} describes any regions inside the mesh that are not to be included in the mesh. 1617 1618 \code{geo_reference} defines the geo_reference to which all point information is relative. 1619 If \code{geo_reference} is \code{None} then the default geo_reference is used. 1522 1620 \end{classdesc} 1523 1621 1524 1622 \subsubsection{Key Methods of Class Mesh} 1525 1623 1526 \begin{methoddesc} {add\_hole}{self, x, y} 1527 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1528 1529 This method is used to build the mesh outline. It defines a hole, 1530 when the boundary of the hole has already been defined, by selecting a 1531 point within the boundary. 1532 \end{methoddesc} 1533 1534 \begin{methoddesc} {add\_hole\_from\_polygon}{self, polygon, tags=None} 1535 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1624 \begin{methoddesc}{\emph{<mesh>}.add_hole}{x, y, geo_reference=None} 1625 Module: \module{pmesh.mesh} 1626 1627 This method adds a hole to the mesh outline. 1628 1629 \code{x} and \code{y} define a point on the already defined hole boundary. 1630 1631 If \code{geo_reference} is not supplied the points are assumed to be absolute. 1632 \end{methoddesc} 1633 1634 \begin{methoddesc}{\emph{<mesh>}.add_hole_from_polygon}{polygon, 1635 segment_tags=None, 1636 geo_reference=None} 1637 Module: \module{pmesh.mesh} 1536 1638 1537 1639 This method is used to add a 'hole' within a region -- that is, to … … 1540 1642 the polygon passed in. Additionally, the user specifies a list of 1541 1643 boundary tags, one for each edge of the bounding polygon. 1542 \end{methoddesc} 1543 1544 \begin{methoddesc} {add\_points_and_segments}{self, points, segments, 1545 segment\_tags=None} 1546 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1547 1548 This method is used to build the mesh outline. It adds points and 1549 segments connecting the points. Points is a list of points. Segments 1550 is a list of segments. Each segment is defined by the start and end 1551 of the line by it's point index, e.g. use \code{segments = 1552 [[0,1],[1,2]]} to make a polyline between points 0, 1 and 2. A tag for 1553 each segment can optionally be added. 1554 \end{methoddesc} 1555 1556 \begin{methoddesc} {add\_region}{self, x, y} 1557 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1558 1559 This method is used to build the mesh outline. It defines a region, 1560 when the boundary of the region has already been defined, by selecting 1561 a point within the boundary. A region instance is returned. This can 1562 be used to set the resolution. 1563 \end{methoddesc} 1564 1565 \begin{methoddesc} {add\_region\_from\_polygon}{self, polygon, 1566 segment_tags=None, region_tag=None, max_triangle_area=None} 1567 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1568 1569 This method is used to build the mesh outline. It adds a region to a 1644 1645 \code{polygon} is the polygon that defines the hole to be added to the \code{<mesh>}. 1646 1647 \code{segment_tags} -- ?? 1648 1649 If \code{geo_reference} is \code{None} then the default \code{geo_reference} is used. 1650 \end{methoddesc} 1651 1652 \begin{methoddesc}{\emph{<mesh>}.add_points_and_segments}{points, 1653 segments=None, 1654 segment_tags=None} 1655 Module: \module{pmesh.mesh} 1656 1657 This adds points and segments connecting the points to a mesh. 1658 1659 \code{points} is a list of points. 1660 1661 \code{segments} is a list of segments. Each segment is defined by the start and end 1662 of the line by its point index, e.g. use \code{segments = [[0,1],[1,2]]} to make a 1663 polyline between points 0, 1 and 2. 1664 1665 \code{segment_tags} may be used to optionally define a tag for each segment. 1666 \end{methoddesc} 1667 1668 \begin{methoddesc}{\emph{<mesh>}.add_region}{x,y, geo_reference=None, tag=None} 1669 Module: \module{pmesh.mesh} 1670 1671 This method adds a region to a mesh outline. 1672 1673 \code{x} and \code{y} define a point on the already-defined region that is to 1674 be added to the mesh. 1675 1676 If \code{geo_reference} is not supplied the points data is assumed to be absolute. 1677 1678 \code{tag} -- ?? 1679 1680 A region instance is returned. This can be used to set the resolution of the added region. 1681 \end{methoddesc} 1682 1683 \begin{methoddesc}{\emph{<mesh>}.add_region_from_polygon}{polygon, 1684 segment_tags=None, 1685 max_triangle_area=None, 1686 geo_reference=None, 1687 region_tag=None} 1688 Module: \module{pmesh.mesh} 1689 1690 This method adds a region to a 1570 1691 \class{Mesh} instance. Regions are commonly used to describe an area 1571 with an increased density of triangles, by setting 1572 \code{max_triangle_area}. The 1573 region boundary is described by the input \code{polygon}. Additionally, the 1574 user specifies a list of segment tags, one for each edge of the 1575 bounding polygon. The regional tag is set using \code{region}. 1576 \end{methoddesc} 1577 1578 \begin{methoddesc} {add\_vertices}{self, point_data} 1579 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1580 1581 Add user vertices. The point_data can be a list of (x,y) values, a numeric 1582 array or a geospatial_data instance. 1583 \end{methoddesc} 1584 1585 \begin{methoddesc} {auto\_segment}{self, raw_boundary=raw_boundary, 1586 remove_holes=remove_holes, 1587 smooth_indents=smooth_indents, 1588 expand_pinch=expand_pinch} 1589 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1692 with an increased density of triangles by setting \code{max_triangle_area}. 1693 1694 \code{polygon} describes the region boundary to add to the \code{<mesh>}. 1695 1696 \code{segment_tags} specifies a list of segment tags, one for each edge of the 1697 bounding polygon. 1698 1699 If \code{geo_reference} is not supplied the points data is assumed to be absolute. 1700 1701 \code{region_tag} sets the region tag. 1702 \end{methoddesc} 1703 1704 \begin{methoddesc}{\emph{<mesh>}.add_vertices}{point_data} 1705 Module: \module{pmesh.mesh} 1706 1707 Add user vertices to a mesh. 1708 1709 \code{point_data} is the list of point data, and can be a list of (x,y) values, 1710 a numeric array or a geospatial_data instance. 1711 \end{methoddesc} 1712 1713 \begin{methoddesc}{\emph{<mesh>}.auto_segment}{alpha=None, 1714 raw_boundary=True, 1715 remove_holes=False, 1716 smooth_indents=False, 1717 expand_pinch=False} 1718 Module: \module{pmesh.mesh} 1590 1719 1591 1720 Add segments between some of the user vertices to give the vertices an … … 1593 1722 useful since a set of user vertices need to be outlined by segments 1594 1723 before generate_mesh is called. 1595 \end{methoddesc} 1596 1597 \begin{methoddesc} {export\_mesh_file}{self, ofile} 1598 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1599 1600 This method is used to save the mesh to a file. \code{ofile} is the 1601 name of the mesh file to be written, including the extension. Use 1602 the extension \code{.msh} for the file to be in NetCDF format and 1724 1725 \code{alpha} determines the $smoothness$ of the alpha shape. 1726 1727 \code{raw_boundary}, if \code{True} instructs the function to return the raw 1728 boundary, i.e. the regular edges of the alpha shape. 1729 1730 \code{remove_holes}, if \code{True} enables a filter to remove small holes 1731 (small is defined by boundary_points_fraction). 1732 1733 \code{smooth_indents}, if \code{True} removes sharp triangular indents 1734 in the boundary. 1735 1736 \code{expand_pinch}, if \code{True} tests for pinch-off and corrects 1737 (i.e. a boundary vertex with more than two edges). 1738 \end{methoddesc} 1739 1740 \begin{methoddesc}{\emph{<mesh>}.export_mesh_file}{ofile} 1741 Module: \module{pmesh.mesh} 1742 1743 This method is used to save a mesh to a file. 1744 1745 \code{ofile} is the name of the mesh file to be written, including the extension. 1746 Use the extension \code{.msh} for the file to be in NetCDF format and 1603 1747 \code{.tsh} for the file to be ASCII format. 1604 1748 \end{methoddesc} 1605 1749 1606 \begin{methoddesc} {generate\_mesh}{self, 1607 maximum_triangle_area=None, 1608 minimum_triangle_angle=28.0, 1609 verbose=False} 1610 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1611 1612 This method is used to generate the triangular mesh. The maximal 1613 area of any triangle in the mesh can be specified, which is used to 1614 control the triangle density, along with the 1615 minimum angle in any triangle. 1616 \end{methoddesc} 1617 1618 \begin{methoddesc} {import_ungenerate_file}{self, ofile, tag=None, 1619 region_tag=None} 1620 Module: \module{pmesh.mesh}, Class: \class{Mesh} 1750 \begin{methoddesc}{\emph{<mesh>}.generate_mesh}{maximum_triangle_area="", 1751 minimum_triangle_angle=28.0, 1752 verbose=True} 1753 Module: \module{pmesh.mesh} 1754 1755 This method is used to generate the triangular mesh. 1756 1757 \code{maximum_triangle_area} sets the maximum area of any triangle in the mesh. 1758 1759 \code{minimum_triangle_angle} sets the minimum area of any triangle in the mesh. 1760 1761 These two parameters can be used to control the triangle density. 1762 \end{methoddesc} 1763 1764 \begin{methoddesc}{\emph{<mesh>}.import_ungenerate_file}{ofile, 1765 tag=None, 1766 region_tag=None} 1767 Module: \module{pmesh.mesh} 1621 1768 1622 1769 This method is used to import a polygon file in the ungenerate format, 1623 1770 which is used by arcGIS. The polygons from the file are converted to 1624 vertices and segments. \code{ofile} is the name of the polygon file. 1771 vertices and segments. 1772 1773 \code{ofile} is the name of the polygon file. 1774 1625 1775 \code{tag} is the tag given to all the polygon's segments. 1776 If \code{tag} is not supplied then the segment will not effect the water 1777 flow, it will only effect the mesh generation. 1778 1626 1779 \code{region_tag} is the tag given to all the polygon's segments. If 1627 it is a string the one valuewill be assigned to all regions. If it1780 it is a string the tag will be assigned to all regions. If it 1628 1781 is a list the first value in the list will be applied to the first 1629 polygon etc. If \code{tag} is not given a value it defaults to None, 1630 which means the segement will not effect the water flow, it will only 1631 effect the mesh generation. 1782 polygon etc. 1632 1783 1633 1784 This function can be used to import building footprints. … … 1638 1789 \label{sec:initialising the domain} 1639 1790 1640 %Include description of the class Domain and the module domain. 1641 1642 %FIXME (Ole): This is also defined in a later chapter 1643 %\declaremodule{standard}{...domain} 1644 1645 \begin{classdesc} {Domain} {source=None, 1646 triangles=None, 1647 boundary=None, 1648 conserved_quantities=None, 1649 other_quantities=None, 1650 tagged_elements=None, 1651 use_inscribed_circle=False, 1652 mesh_filename=None, 1653 use_cache=False, 1654 verbose=False, 1655 full_send_dict=None, 1656 ghost_recv_dict=None, 1657 processor=0, 1658 numproc=1} 1791 \begin{classdesc}{Domain}{source=None, 1792 triangles=None, 1793 boundary=None, 1794 conserved_quantities=None, 1795 other_quantities=None, 1796 tagged_elements=None, 1797 geo_reference=None, 1798 use_inscribed_circle=False, 1799 mesh_filename=None, 1800 use_cache=False, 1801 verbose=False, 1802 full_send_dict=None, 1803 ghost_recv_dict=None, 1804 processor=0, 1805 numproc=1, 1806 number_of_full_nodes=None, 1807 number_of_full_triangles=None} 1659 1808 Module: \refmodule{abstract_2d_finite_volumes.domain} 1660 1809 1661 This class is used to create an instance of a datastructure used to1810 This class is used to create an instance of a structure used to 1662 1811 store and manipulate data associated with a mesh. The mesh is 1663 1812 specified either by assigning the name of a mesh file to … … 1668 1817 \subsection{Key Methods of Domain} 1669 1818 1670 \begin{methoddesc} {set\_name}{name} 1671 Module: \refmodule{abstract\_2d\_finite\_volumes.domain}, 1672 page \pageref{mod:domain} 1673 1674 Assigns the name \code{name} to the domain. 1675 \end{methoddesc} 1676 1677 \begin{methoddesc} {get\_name}{} 1678 Module: \module{abstract\_2d\_finite\_volumes.domain} 1679 1680 Returns the name assigned to the domain by \code{set\_name}. If no name has been 1681 assigned, returns \code{'domain'}. 1682 \end{methoddesc} 1683 1684 \begin{methoddesc} {set\_datadir}{name} 1685 Module: \module{abstract\_2d\_finite\_volumes.domain} 1686 1687 Specifies the directory used for SWW files, assigning it to the 1688 pathname \code{name}. The default value, before 1689 \code{set\_datadir} has been run, is the value \code{default\_datadir} 1690 specified in \code{config.py}. 1691 1692 Since different operating systems use different formats for specifying pathnames, 1693 it is necessary to specify path separators using the Python code \code{os.sep}, rather than 1694 the operating-specific ones such as '$\slash$' or '$\backslash$'. 1695 For this to work you will need to include the statement \code{import os} 1696 in your code, before the first appearance of \code{set\_datadir}. 1697 1698 For example, to set the data directory to a subdirectory 1699 \code{data} of the directory \code{project}, you could use 1700 the statements: 1701 1702 \begin{verbatim} 1819 \begin{methoddesc}{\emph{<domain>}.set_name}{name} 1820 Module: \refmodule{abstract_2d_finite_volumes.domain}, 1821 page \pageref{mod:domain} 1822 1823 \code{name} is used to name the domain. The \code{name} is also used to identify the output SWW file. 1824 If no name is assigned to a domain, the assumed name is \code{'domain'}. 1825 \end{methoddesc} 1826 1827 \begin{methoddesc}{\emph{<domain>}.get_name}{} 1828 Module: \module{abstract_2d_finite_volumes.domain} 1829 1830 Returns the name assigned to the domain by \code{set_name()}. If no name has been 1831 assigned, returns \code{'domain'}. 1832 \end{methoddesc} 1833 1834 \begin{methoddesc}{\emph{<domain>}.set_datadir}{path} 1835 Module: \module{abstract_2d_finite_volumes.domain} 1836 1837 \code{path} specifies the path to the directory used to store SWW files. 1838 1839 Before this method is used to set the SWW directory path, the assumed directory 1840 path is \code{default_datadir} specified in \code{config.py}. 1841 1842 Since different operating systems use different formats for specifying pathnames 1843 it is necessary to specify path separators using the Python code \code{os.sep} rather than 1844 the operating-specific ones such as '$\slash$' or '$\backslash$'. 1845 For this to work you will need to include the statement \code{import os} 1846 in your code, before the first use of \code{set_datadir()}. 1847 1848 For example, to set the data directory to a subdirectory 1849 \code{data} of the directory \code{project}, you could use 1850 the statements: 1851 1852 \begin{verbatim} 1703 1853 import os 1704 1854 domain.set_datadir{'project' + os.sep + 'data'} 1705 \end{verbatim} 1706 \end{methoddesc} 1707 1708 \begin{methoddesc} {get\_datadir}{} 1709 Module: \module{abstract\_2d\_finite\_volumes.domain} 1710 1711 Returns the data directory set by \code{set\_datadir} or, 1712 if \code{set\_datadir} has not 1713 been run, returns the value \code{default\_datadir} specified in 1714 \code{config.py}. 1715 \end{methoddesc} 1716 1717 \begin{methoddesc} {set\_minimum_allowed_height}{} 1718 Module: \module{shallow\_water.shallow\_water\_domain} 1719 1720 Set the minimum depth (in meters) that will be recognised in 1721 the numerical scheme (including limiters and flux computations) 1722 1723 Default value is $10^{-3}$ m, but by setting this to a greater value, 1724 e.g.\ for large scale simulations, the computation time can be 1725 significantly reduced. 1726 \end{methoddesc} 1727 1728 \begin{methoddesc} {set\_minimum_storable_height}{} 1729 Module: \module{shallow\_water.shallow\_water\_domain} 1730 1731 Sets the minimum depth that will be recognised when writing 1732 to an sww file. This is useful for removing thin water layers 1733 that seems to be caused by friction creep. 1734 \end{methoddesc} 1735 1736 \begin{methoddesc} {set\_maximum_allowed_speed}{} 1737 Module: \module{shallow\_water.shallow\_water\_domain} 1738 1739 Set the maximum particle speed that is allowed in water 1740 shallower than minimum_allowed_height. This is useful for 1741 controlling speeds in very thin layers of water and at the same time 1742 allow some movement avoiding pooling of water. 1743 \end{methoddesc} 1744 1745 \begin{methoddesc} {set\_time}{time=0.0} 1746 Module: \module{abstract\_2d\_finite\_volumes.domain} 1747 1748 Sets the initial time, in seconds, for the simulation. The 1749 default is 0.0. 1750 \end{methoddesc} 1751 1752 \begin{methoddesc} {set\_default\_order}{n} 1753 Sets the default (spatial) order to the value specified by 1754 \code{n}, which must be either 1 or 2. (Assigning any other value 1755 to \code{n} will cause an error.) 1756 \end{methoddesc} 1757 1758 \begin{methoddesc} {set\_store\_vertices\_uniquely}{flag} 1855 \end{verbatim} 1856 \end{methoddesc} 1857 1858 \begin{methoddesc}{\emph{<domain>}.get_datadir}{} 1859 Module: \module{abstract_2d_finite_volumes.domain} 1860 1861 Returns the path to the directory where SWW files will be stored. 1862 1863 If the path has not previously been set with \code{set_datadir()} this method 1864 will return the value \code{default_datadir} specified in \code{config.py}. 1865 \end{methoddesc} 1866 1867 \begin{methoddesc}{\emph{<domain>}.set_minimum_allowed_height}{minimum_allowed_height} 1868 Module: \module{shallow_water.shallow_water_domain} 1869 1870 Set the minimum depth (in metres) that will be recognised in 1871 the numerical scheme (including limiters and flux computations) 1872 1873 \code{minimum_allowed_height} is the new minimum allowed height value. 1874 1875 Default value is $10^{-3}$ metre, but by setting this to a greater value, 1876 e.g. for large scale simulations, the computation time can be 1877 significantly reduced. 1878 \end{methoddesc} 1879 1880 \begin{methoddesc}{\emph{<domain>}.set_minimum_storable_height}{minimum_storable_height} 1881 Module: \module{shallow_water.shallow_water_domain} 1882 1883 Sets the minimum depth that will be recognised when writing 1884 to an SWW file. This is useful for removing thin water layers 1885 that seems to be caused by friction creep. 1886 1887 \code{minimum_storable_height} is the new minimum storable height value. 1888 \end{methoddesc} 1889 1890 \begin{methoddesc}{\emph{<domain>}.set_maximum_allowed_speed}{maximum_allowed_speed} 1891 Module: \module{shallow_water.shallow_water_domain} 1892 1893 Set the maximum particle speed that is allowed in water 1894 shallower than \code{minimum_allowed_height}. This is useful for 1895 controlling speeds in very thin layers of water and at the same time 1896 allow some movement avoiding pooling of water. 1897 1898 \code{maximum_allowed_speed} sets the maximum allowed speed value. 1899 \end{methoddesc} 1900 1901 \begin{methoddesc}{\emph{<domain>}.set_time}{time=0.0} 1902 Module: \module{abstract_2d_finite_volumes.domain} 1903 1904 \code{time} sets the initial time, in seconds, for the simulation. The 1905 default is 0.0. 1906 \end{methoddesc} 1907 1908 \begin{methoddesc}{\emph{<domain>}.set_default_order}{n} 1909 Module: \module{abstract_2d_finite_volumes.domain} 1910 1911 Sets the default (spatial) order to the value specified by 1912 \code{n}, which must be either 1 or 2. (Assigning any other value 1913 to \code{n} will cause an error.) 1914 \end{methoddesc} 1915 1916 \begin{methoddesc}{\emph{<domain>}.set_store_vertices_uniquely}{flag, reduction=None} 1917 Module: \module{shallow_water.shallow_water_domain} 1918 1759 1919 Decide whether vertex values should be stored uniquely as 1760 1920 computed in the model or whether they should be reduced to one 1761 1921 value per vertex using averaging. 1762 1922 1763 Triangles stored in the sww file can be discontinuous reflecting 1923 \code{flag} may be \code{True} (meaning do not smooth vertex values) or \code{False}. 1924 1925 \code{reduction} defines the smoothing operation if \code{flag} is \code{True}. If not 1926 supplied, \code{reduction} is assumed to be \code{mean}. 1927 1928 Triangles stored in the SWW file can be discontinuous reflecting 1764 1929 the internal representation of the finite-volume scheme 1765 (this is a feature allowing for arbitrary steepness of the water surface gradient as well as the momentum gradients). 1766 However, for visual purposes and also for use with \code{Field\_boundary} 1767 (and \code{File\_boundary}) it is often desirable to store triangles 1930 (this is a feature allowing for arbitrary steepness of the water surface gradient 1931 as well as the momentum gradients). 1932 However, for visual purposes and also for use with \code{Field_boundary} 1933 (and \code{File_boundary}), it is often desirable to store triangles 1768 1934 with values at each vertex point as the average of the potentially 1769 1935 discontinuous numbers found at vertices of different triangles sharing the 1770 1936 same vertex location. 1771 1937 1772 Storing one way or the other is controlled in ANUGAthrough the method1773 \code{ domain.store\_vertices\_uniquely}. Options are1938 Storing one way or the other is controlled in \anuga through the method 1939 \code{<domain>.store_vertices_uniquely()}. Options are: 1774 1940 \begin{itemize} 1775 \item \code{ domain.store\_vertices\_uniquely(True)}: Allow discontinuities in the swwfile1776 \item \code{ domain.store\_vertices\_uniquely(False)}: (Default).1941 \item \code{<domain>.store_vertices_uniquely(True)}: Allow discontinuities in the SWW file 1942 \item \code{<domain>.store_vertices_uniquely(False)}: (Default). 1777 1943 Average values 1778 to ensure continuity in swwfile. The latter also makes for smaller1779 swwfiles.1944 to ensure continuity in SWW file. The latter also makes for smaller 1945 SWW files. 1780 1946 \end{itemize} 1781 1947 1782 Note that when model data in the swwfile are averaged (i.e. not stored uniquely),1783 then there will most likely be a small discrepancy between values extracted from the sww1948 Note that when model data in the SWW file are averaged (i.e. not stored uniquely), 1949 then there will most likely be a small discrepancy between values extracted from the SWW 1784 1950 file and the same data stored in the model domain. This must be borne in mind when comparing 1785 data from the swwfiles with that of the model internally.1951 data from the SWW files with that of the model internally. 1786 1952 \end{methoddesc} 1787 1953 1788 1954 % Structural methods 1789 \begin{methoddesc}{get\_nodes}{absolute=False} 1790 Return x,y coordinates of all nodes in mesh. 1791 1792 The nodes are ordered in an Nx2 array where N is the number of nodes. 1793 This is the same format they were provided in the constructor 1794 i.e. without any duplication. 1795 1796 Boolean keyword argument absolute determines whether coordinates 1797 are to be made absolute by taking georeference into account 1798 Default is False as many parts of ANUGA expects relative coordinates. 1799 \end{methoddesc} 1800 1801 \begin{methoddesc}{get\_vertex\_coordinates}{absolute=False} 1802 \label{pg:get vertex coordinates} 1803 Return vertex coordinates for all triangles. 1804 1805 Return all vertex coordinates for all triangles as a 3*M x 2 array 1806 where the jth vertex of the ith triangle is located in row 3*i+j and 1807 M the number of triangles in the mesh. 1808 1809 Boolean keyword argument absolute determines whether coordinates 1810 are to be made absolute by taking georeference into account 1811 Default is False as many parts of ANUGA expects relative coordinates. 1812 \end{methoddesc} 1813 1814 \begin{methoddesc}{get\_centroid\_coordinates}{absolute=False} 1815 1816 Return centroid coordinates for all triangles. 1817 1818 Return all centroid coordinates for all triangles as a M x 2 array 1955 \begin{methoddesc}{\emph{<domain>}.get_nodes}{absolute=False} 1956 Module: \module{abstract_2d_finite_volumes.domain} 1957 1958 Return x,y coordinates of all nodes in the domain mesh. The nodes are ordered 1959 in an \code{Nx2} array where N is the number of nodes. This is the same format 1960 they were provided in the constructor i.e. without any duplication. 1961 1962 \code{absolute} is a boolean which determines whether coordinates 1963 are to be made absolute by taking georeference into account. 1964 Default is \code{False} as many parts of \anuga expect relative coordinates. 1965 \end{methoddesc} 1966 1967 \begin{methoddesc}{\emph{<domain>}.get_vertex_coordinates}{absolute=False} 1968 Module: \module{abstract_2d_finite_volumes.domain} 1969 1970 \label{pg:get vertex coordinates} 1971 Return vertex coordinates for all triangles as a \code{3*Mx2} array 1972 where the jth vertex of the ith triangle is located in row 3*i+j and 1973 M is the number of triangles in the mesh. 1974 1975 \code{absolute} is a boolean which determines whether coordinates 1976 are to be made absolute by taking georeference into account. 1977 Default is \code{False} as many parts of \anuga expect relative coordinates. 1978 \end{methoddesc} 1979 1980 \begin{methoddesc}{\emph{<domain>}.get_centroid_coordinates}{absolute=False} 1981 Module: \module{abstract_2d_finite_volumes.domain} 1982 1983 Return centroid coordinates for all triangles as an \code{Mx2} array. 1819 1984 1820 Boolean keyword argument absolute determines whether coordinates 1821 are to be made absolute by taking georeference into account 1822 Default is False as many parts of ANUGA expects relative coordinates. 1823 \end{methoddesc} 1824 1825 \begin{methoddesc}{get\_triangles}{indices=None} 1826 1827 Return Mx3 integer array where M is the number of triangles. 1828 Each row corresponds to one triangle and the three entries are 1829 indices into the mesh nodes which can be obtained using the method 1830 get\_nodes() 1831 1832 Optional argument, indices is the set of triangle ids of interest. 1833 \end{methoddesc} 1834 1835 \begin{methoddesc}{get\_disconnected\_triangles}{} 1836 Get mesh based on nodes obtained from get_vertex_coordinates. 1837 1838 Return array Mx3 array of integers where each row corresponds to 1839 a triangle. A triangle is a triplet of indices into 1840 point coordinates obtained from get_vertex_coordinates and each 1841 index appears only once.\\ 1842 1843 This provides a mesh where no triangles share nodes 1844 (hence the name disconnected triangles) and different 1845 nodes may have the same coordinates.\\ 1846 1847 This version of the mesh is useful for storing meshes with 1848 discontinuities at each node and is e.g. used for storing 1849 data in sww files.\\ 1850 1851 The triangles created will have the format: 1852 1853 \begin{verbatim} 1985 \code{absolute} is a boolean which determines whether coordinates 1986 are to be made absolute by taking georeference into account. 1987 Default is \code{False} as many parts of \anuga expect relative coordinates. 1988 \end{methoddesc} 1989 1990 \begin{methoddesc}{\emph{<domain>}.get_triangles}{indices=None} 1991 Module: \module{abstract_2d_finite_volumes.domain} 1992 1993 Return an \code{Mx3} integer array where M is the number of triangles. 1994 Each row corresponds to one triangle and the three entries are 1995 indices into the mesh nodes which can be obtained using the method 1996 \code{get_nodes()}. 1997 1998 \code{indices}, if specified, is the set of triangle \code{id}s of interest. 1999 \end{methoddesc} 2000 2001 \begin{methoddesc}{\emph{<domain>}.get_disconnected_triangles}{} 2002 Module: \module{abstract_2d_finite_volumes.domain} 2003 2004 Get the domain mesh based on nodes obtained from \code{get_vertex_coordinates()}. 2005 2006 Returns an \code{Mx3} array of integers where each row corresponds to 2007 a triangle. A triangle is a triplet of indices into 2008 point coordinates obtained from \code{get_vertex_coordinates()} and each 2009 index appears only once. 2010 2011 This provides a mesh where no triangles share nodes 2012 (hence the name disconnected triangles) and different 2013 nodes may have the same coordinates. 2014 2015 This version of the mesh is useful for storing meshes with 2016 discontinuities at each node and is e.g. used for storing 2017 data in SWW files. 2018 2019 The triangles created will have the format: 2020 2021 \begin{verbatim} 1854 2022 [[0,1,2], 1855 2023 [3,4,5], … … 1857 2025 ... 1858 2026 [3*M-3 3*M-2 3*M-1]] 1859 2027 \end{verbatim} 1860 2028 \end{methoddesc} 1861 2029 … … 1871 2039 of initial conditions to refer to initial values for variables which need 1872 2040 prescription to solve the shallow water wave equation. Further, it must be noted 1873 that \code{set_quantity } does not necessarily have to be used in the initial2041 that \code{set_quantity()} does not necessarily have to be used in the initial 1874 2042 condition setting; it can be used at any time throughout the simulation. 1875 2043 1876 \begin{methoddesc}{set\_quantity}{name, 1877 numeric=None, 1878 quantity=None, 1879 function=None, 1880 geospatial_data=None, 1881 expression=None, 1882 filename=None, 1883 attribute_name=None, 1884 alpha=None, 1885 location='vertices', 1886 indices=None, 1887 verbose=False, 1888 use_cache=False} 1889 Module: \module{abstract\_2d\_finite\_volumes.domain} 1890 (see also \module{abstract\_2d\_finite\_volumes.quantity.set\_values}) 1891 1892 This function is used to assign values to individual quantities for a 1893 domain. It is very flexible and can be used with many data types: a 1894 statement of the form \code{domain.set\_quantity(name, x)} can be used 1895 to define a quantity having the name \code{name}, where the other 1896 argument \code{x} can be any of the following: 1897 1898 \begin{itemize} 1899 \item a number, in which case all vertices in the mesh gets that for 1900 the quantity in question. 1901 \item a list of numbers or a numeric array ordered the same way as the mesh vertices. 1902 \item a function (e.g.\ see the samples introduced in Chapter 2) 1903 \item an expression composed of other quantities and numbers, arrays, lists (for 1904 example, a linear combination of quantities, such as 1905 \code{domain.set\_quantity('stage','elevation'+x))} 1906 \item the name of a file from which the data can be read. In this case, the optional 1907 argument attribute\_name will select which attribute to use from the file. If left out, 1908 set\_quantity will pick one. This is useful in cases where there is only one attribute. 1909 \item a geospatial dataset (See Section \ref{sec:geospatial}). 1910 Optional argument attribute\_name applies here as with files. 1911 \end{itemize} 1912 1913 Exactly one of the arguments 1914 numeric, quantity, function, points, filename 1915 must be present. 1916 1917 \code{set_quantity} will look at the type of the second argument (\code{numeric}) and 1918 determine what action to take. 1919 1920 Values can also be set using the appropriate keyword arguments. 1921 If x is a function, for example, \code{domain.set\_quantity(name, x)}, \code{domain.set\_quantity(name, numeric=x)}, 1922 and \code{domain.set\_quantity(name, function=x)} are all equivalent. 1923 1924 Other optional arguments are 1925 \begin{itemize} 1926 \item \code{indices} which is a list of ids of triangles to which set\_quantity should apply its assignment of values. 1927 \item \code{location} determines which part of the triangles to assign 1928 to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'. 1929 If 'vertices' are use, edge and centroid values are automatically computed as the 1930 appropriate averages. This option ensures continuity of the surface. 1931 If, on the other hand, 'centroids' is used vertex and edge values will be set to the 1932 same value effectively creating a piecewise constant surface with possible discontinuities at the edges. 1933 \end{itemize} 1934 1935 \anuga provides a number of predefined initial conditions to be used 1936 with \code{set\_quantity}. See for example callable object \code{slump\_tsunami} below. 1937 \end{methoddesc} 1938 1939 \begin{methoddesc}{add\_quantity}{name, 1940 numeric=None, 1941 quantity=None, 1942 function=None, 1943 geospatial_data=None, 1944 expression=None, 1945 filename=None, 1946 attribute_name=None, 1947 alpha=None, 1948 location='vertices', 1949 indices=None, 1950 verbose=False, 1951 use_cache=False} 1952 Module: \module{abstract\_2d\_finite\_volumes.domain} 1953 (see also \module{abstract\_2d\_finite\_volumes.domain.set\_quantity}) 1954 1955 \label{add quantity} 1956 This function is used to \emph{add} values to individual quantities for a 1957 domain. It has the same syntax as \code{domain.set\_quantity(name, x)}. 1958 1959 A typical use of this function is to add structures to an existing elevation model: 1960 1961 \begin{verbatim} 2044 \begin{methoddesc}{\emph{<domain>}.set_quantity}{numeric=None, 2045 quantity=None, 2046 function=None, 2047 geospatial_data=None, 2048 filename=None, 2049 attribute_name=None, 2050 alpha=None, 2051 location='vertices', 2052 polygon=None, 2053 indices=None, 2054 smooth=False, 2055 verbose=False, 2056 use_cache=False} 2057 Module: \module{abstract_2d_finite_volumes.domain} \\ 2058 (This method passes off to \module{abstract_2d_finite_volumes.quantity.set_values()}) 2059 2060 This function is used to assign values to individual quantities for a 2061 domain. It is very flexible and can be used with many data types: a 2062 statement of the form \code{\emph{<domain>}.set_quantity(name, x)} can be used 2063 to define a quantity having the name \code{name}, where the other 2064 argument \code{x} can be any of the following: 2065 2066 \begin{itemize} 2067 \item a number, in which case all vertices in the mesh gets that for 2068 the quantity in question 2069 \item a list of numbers or a numeric array ordered the same way as the mesh vertices 2070 \item a function (e.g. see the samples introduced in Chapter 2) 2071 \item an expression composed of other quantities and numbers, arrays, lists (for 2072 example, a linear combination of quantities, such as 2073 \code{\emph{<domain>}.set_quantity('stage','elevation'+x))} 2074 \item the name of a file from which the data can be read. In this case, the optional 2075 argument \code{attribute_name} will select which attribute to use from the file. If left out, 2076 \code{set_quantity()} will pick one. This is useful in cases where there is only one attribute 2077 \item a geospatial dataset (See Section \ref{sec:geospatial}). 2078 Optional argument \code{attribute_name} applies here as with files 2079 \end{itemize} 2080 2081 Exactly one of the arguments \code{numeric}, \code{quantity}, \code{function}, 2082 \code{geospatial_data} and \code{filename} must be present. 2083 2084 \code{set_quantity()} will look at the type of the \code{numeric} and 2085 determine what action to take. 2086 2087 Values can also be set using the appropriate keyword arguments. 2088 If \code{x} is a function, for example, \code{domain.set_quantity(name, x)}, \code{domain.set_quantity(name, numeric=x)}, 2089 and \code{domain.set_quantity(name, function=x)} are all equivalent. 2090 2091 Other optional arguments are: 2092 \begin{itemize} 2093 \item \code{indices} which is a list of ids of triangles to which \code{set_quantity()} 2094 should apply its assignment of values. 2095 \item \code{location} determines which part of the triangles to assign to. 2096 Options are 'vertices' (the default), 'edges', 'unique vertices', and 'centroids'. 2097 If 'vertices' is used, edge and centroid values are automatically computed as the 2098 appropriate averages. This option ensures continuity of the surface. 2099 If, on the other hand, 'centroids' is used, vertex and edge values will be set to the 2100 same value effectively creating a piecewise constant surface with possible 2101 discontinuities at the edges. 2102 \end{itemize} 2103 2104 \anuga provides a number of predefined initial conditions to be used 2105 with \code{set_quantity()}. See for example callable object \code{slump_tsunami} below. 2106 \end{methoddesc} 2107 2108 \begin{methoddesc}{\emph{<domain>}.add_quantity}{numeric=None, 2109 quantity=None, 2110 function=None, 2111 geospatial_data=None, 2112 filename=None, 2113 attribute_name=None, 2114 alpha=None, 2115 location='vertices', 2116 polygon=None, 2117 indices=None, 2118 smooth=False, 2119 verbose=False, 2120 use_cache=False} 2121 Module: \module{abstract_2d_finite_volumes.domain} \\ 2122 (passes off to \module{abstract_2d_finite_volumes.domain.set_quantity()}) 2123 2124 \label{add quantity} 2125 This function is used to \emph{add} values to individual quantities for a 2126 domain. It has the same syntax as \code{\emph{<domain>}.set_quantity(name, x)}. 2127 2128 A typical use of this function is to add structures to an existing elevation model: 2129 2130 \begin{verbatim} 1962 2131 # Create digital elevation model from points file 1963 2132 domain.set_quantity('elevation', filename='elevation_file.pts, verbose=True) … … 1973 2142 1974 2143 domain.add_quantity('elevation', Polygon_function(B, default=0.0)) 1975 \end{verbatim} 1976 \end{methoddesc} 1977 1978 \begin{funcdesc}{set_region}{tag, quantity, X, location='vertices'} 1979 Module: \module{abstract\_2d\_finite\_volumes.domain} 1980 1981 (see also \module{abstract\_2d\_finite\_volumes.quantity.set\_values}) 1982 1983 This function is used to assign values to individual quantities given 1984 a regional tag. It is similar to \code{set\_quantity}. 1985 For example, if in the mesh-generator a regional tag of 'ditch' was 1986 used, set\_region can be used to set elevation of this region to 1987 -10m. X is the constant or function to be applied to the quantity, 1988 over the tagged region. Location describes how the values will be 1989 applied. Options are 'vertices' (default), 'edges', 'unique 1990 vertices', and 'centroids'. 1991 1992 This method can also be called with a list of region objects. This is 1993 useful for adding quantities in regions, and having one quantity 1994 value based on another quantity. See \module{abstract\_2d\_finite\_volumes.region} for 1995 more details. 2144 \end{verbatim} 2145 \end{methoddesc} 2146 2147 \begin{methoddesc}{\emph{<domain>}.set_region}{tag, quantity, X, location='vertices'} 2148 Module: \module{abstract_2d_finite_volumes.domain} \\ 2149 (see also \module{abstract_2d_finite_volumes.quantity.set_values}) 2150 2151 This function is used to assign values to individual quantities given 2152 a regional tag. It is similar to \code{set_quantity()}. 2153 2154 For example, if in the mesh-generator a regional tag of 'ditch' was 2155 used, \code{set_region()} can be used to set elevation of this region to 2156 -10m. \code{X} is the constant or function to be applied to the \code{quantity}, 2157 over the tagged region. \code{location} describes how the values will be 2158 applied. Options are 'vertices' (the default), 'edges', 'unique 2159 vertices', and 'centroids'. 2160 2161 This method can also be called with a list of region objects. This is 2162 useful for adding quantities in regions, and having one quantity 2163 value based on another quantity. See \module{abstract_2d_finite_volumes.region} for 2164 more details. 2165 \end{methoddesc} 2166 2167 \begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None, 2168 radius=None, dphi=0.48, x0=0.0, y0=0.0, alpha=0.0, 2169 gravity=9.8, gamma=1.85, 2170 massco=1, dragco=1, frictionco=0, 2171 dx=None, kappa=3.0, kappad=1.0, zsmall=0.01, scale=None, 2172 domain=None, 2173 verbose=False} 2174 Module: \module{shallow\_water.smf} 2175 2176 This function returns a callable object representing an initial water 2177 displacement generated by a submarine sediment failure. These failures can take the form of 2178 a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead. 2179 2180 \code{length} is the length of the slide or slump. 2181 2182 \code{depth} is the water depth to the centre of the sediment mass. 2183 2184 \code{slope} is the bathymetric slope. 2185 2186 Other slump or slide parameters can be included if they are known. 1996 2187 \end{funcdesc} 1997 2188 1998 \begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None, 1999 x0=0.0, y0=0.0, alpha=0.0, 2000 gravity=9.8, gamma=1.85, 2001 massco=1, dragco=1, frictionco=0, psi=0, 2002 dx=None, kappa=3.0, kappad=0.8, zsmall=0.01, 2003 domain=None, 2004 verbose=False} 2005 Module: \module{shallow\_water.smf} 2006 2007 This function returns a callable object representing an initial water 2008 displacement generated by a submarine sediment failure. These failures can take the form of 2009 a submarine slump or slide. In the case of a slide, use \code{slide_tsunami} instead. 2010 2011 The arguments include as a minimum, the slump or slide length, the water depth to the centre of sediment 2012 mass, and the bathymetric slope. Other slump or slide parameters can be included if they are known. 2189 \begin{funcdesc}{\emph{<callable_object>} = file_function}{filename, 2190 domain=None, 2191 quantities=None, 2192 interpolation_points=None, 2193 time_thinning=1, 2194 time_limit=None, 2195 verbose=False, 2196 use_cache=False, 2197 boundary_polygon=None} 2198 Module: \module{abstract_2d_finite_volumes.util} 2199 2200 Reads the time history of spatial data for specified interpolation points from 2201 a NetCDF file and returns a callable object. Values returned from the \code{\emph{<callable_object>}} 2202 are interpolated values based on the input file using the underlying \code{interpolation_function}. 2203 2204 \code{filename} is the name of the input file. Could be an SWW or STS file. 2205 2206 \code{quantities} is either the name of a single quantity to be 2207 interpolated or a list of such quantity names. In the second case, the resulting 2208 function will return a tuple of values -- one for each quantity. 2209 2210 \code{interpolation_points} is a list of absolute coordinates or a 2211 geospatial object for points at which values are sought. 2212 2213 \code{boundary_polygon} is a list of coordinates specifying the vertices of the boundary. 2214 This must be the same polygon as used when calling \code{create_mesh_from_regions()}. 2215 This argument can only be used when reading boundary data from an STS format file. 2216 2217 The model time stored within the file function can be accessed using 2218 the method \code{\emph{<callable_object>}.get_time()} 2219 2220 The underlying algorithm used is as follows:\\ 2221 Given a time series (i.e. a series of values associated with 2222 different times), whose values are either just numbers, a set of 2223 numbers defined at the vertices of a triangular mesh (such as those 2224 stored in SWW files) or a set of 2225 numbers defined at a number of points on the boundary (such as those 2226 stored in STS files), \code{Interpolation_function()} is used to 2227 create a callable object that interpolates a value for an arbitrary 2228 time \code{t} within the model limits and possibly a point \code{(x, y)} 2229 within a mesh region. 2230 2231 The actual time series at which data is available is specified by 2232 means of an array \code{time} of monotonically increasing times. The 2233 quantities containing the values to be interpolated are specified in 2234 an array -- or dictionary of arrays (used in conjunction with the 2235 optional argument \code{quantity_names}) -- called 2236 \code{quantities}. The optional arguments \code{vertex_coordinates} 2237 and \code{triangles} represent the spatial mesh associated with the 2238 quantity arrays. If omitted the function must be created using an STS file 2239 or a TMS file. 2240 2241 Since, in practice, values need to be computed at specified points, 2242 the syntax allows the user to specify, once and for all, a list 2243 \code{interpolation_points} of points at which values are required. 2244 In this case, the function may be called using the form \code{\emph{<callable_object>}(t, id)}, 2245 where \code{id} is an index for the list \code{interpolation_points}. 2013 2246 \end{funcdesc} 2014 2247 2015 \begin{funcdesc}{file\_function}{filename, 2016 domain=None, 2017 quantities=None, 2018 interpolation_points=None, 2019 verbose=False, 2020 use_cache=False} 2021 Module: \module{abstract\_2d\_finite\_volumes.util} 2022 2023 Reads the time history of spatial data for 2024 specified interpolation points from a NetCDF file (\code{filename}) 2025 and returns 2026 a callable object. \code{filename} could be a \code{sww} or \code{sts} file. 2027 Returns interpolated values based on the input 2028 file using the underlying \code{interpolation\_function}. 2029 2030 \code{quantities} is either the name of a single quantity to be 2031 interpolated or a list of such quantity names. In the second case, the resulting 2032 function will return a tuple of values -- one for each quantity. 2033 2034 \code{interpolation\_points} is a list of absolute coordinates or a 2035 geospatial object 2036 for points at which values are sought. 2037 2038 \code{boundary_polygon} is a list of coordinates specifying the vertices of the boundary. 2039 This must be the same polygon as used when calling \code{create_mesh_from_regions}. 2040 This argument can only be used when reading boundary data from the STS format. 2041 2042 The model time stored within the file function can be accessed using 2043 the method \code{f.get\_time()} 2044 2045 The underlying algorithm used is as follows:\\ 2046 Given a time series (i.e.\ a series of values associated with 2047 different times), whose values are either just numbers, a set of 2048 numbers defined at the vertices of a triangular mesh (such as those 2049 stored in SWW files) or a set of 2050 numbers defined at a number of points on the boundary (such as those 2051 stored in STS files), \code{Interpolation\_function} is used to 2052 create a callable object that interpolates a value for an arbitrary 2053 time \code{t} within the model limits and possibly a point \code{(x, 2054 y)} within a mesh region. 2055 2056 The actual time series at which data is available is specified by 2057 means of an array \code{time} of monotonically increasing times. The 2058 quantities containing the values to be interpolated are specified in 2059 an array -- or dictionary of arrays (used in conjunction with the 2060 optional argument \code{quantity\_names}) -- called 2061 \code{quantities}. The optional arguments \code{vertex\_coordinates} 2062 and \code{triangles} represent the spatial mesh associated with the 2063 quantity arrays. If omitted the function must be created using an STS file 2064 or a TMS file. 2065 2066 Since, in practice, values need to be computed at specified points, 2067 the syntax allows the user to specify, once and for all, a list 2068 \code{interpolation\_points} of points at which values are required. 2069 In this case, the function may be called using the form \code{f(t, 2070 id)}, where \code{id} is an index for the list 2071 \code{interpolation\_points}. 2072 \end{funcdesc} 2073 2074 % FIXME (OLE): Why has this been commented out? 2075 %%% 2076 %% \begin{classdesc}{Interpolation\_function}{self, 2077 %% time, 2078 %% quantities, 2079 %% quantity_names = None, 2080 %% vertex_coordinates = None, 2081 %% triangles = None, 2082 %% interpolation_points = None, 2083 %% verbose = False} 2084 %% Module: \module{abstract\_2d\_finite\_volumes.least\_squares} 2085 2086 %% Given a time series (i.e.\ a series of values associated with 2087 %% different times), whose values are either just numbers or a set of 2088 %% numbers defined at the vertices of a triangular mesh (such as those 2089 %% stored in SWW files), \code{Interpolation\_function} is used to 2090 %% create a callable object that interpolates a value for an arbitrary 2091 %% time \code{t} within the model limits and possibly a point \code{(x, 2092 %% y)} within a mesh region. 2093 2094 %% The actual time series at which data is available is specified by 2095 %% means of an array \code{time} of monotonically increasing times. The 2096 %% quantities containing the values to be interpolated are specified in 2097 %% an array -- or dictionary of arrays (used in conjunction with the 2098 %% optional argument \code{quantity\_names}) -- called 2099 %% \code{quantities}. The optional arguments \code{vertex\_coordinates} 2100 %% and \code{triangles} represent the spatial mesh associated with the 2101 %% quantity arrays. If omitted the function created by 2102 %% \code{Interpolation\_function} will be a function of \code{t} only. 2103 2104 %% Since, in practice, values need to be computed at specified points, 2105 %% the syntax allows the user to specify, once and for all, a list 2106 %% \code{interpolation\_points} of points at which values are required. 2107 %% In this case, the function may be called using the form \code{f(t, 2108 %% id)}, where \code{id} is an index for the list 2109 %% \code{interpolation\_points}. 2110 2111 %% \end{classdesc} 2112 2113 %%% 2114 %\begin{funcdesc}{set\_region}{functions} 2115 %[Low priority. Will be merged into set\_quantity] 2116 2117 %Module:\module{abstract\_2d\_finite\_volumes.domain} 2118 %\end{funcdesc} 2248 \begin{classdesc}{\emph{<callable_object>} = Interpolation_function}{time, 2249 quantities, 2250 quantity_names=None, 2251 vertex_coordinates=None, 2252 triangles=None, 2253 interpolation_points=None, 2254 time_thinning=1, 2255 verbose=False, 2256 gauge_neighbour_id=None} 2257 Module: \module{fit_interpolate.interpolate} 2258 2259 Given a time series (i.e. a series of values associated with 2260 different times) whose values are either just numbers or a set of 2261 numbers defined at the vertices of a triangular mesh (such as those 2262 stored in SWW files), \code{Interpolation_function} is used to 2263 create a callable object that interpolates a value for an arbitrary 2264 time \code{t} within the model limits and possibly a point \code{(x, y)} 2265 within a mesh region. 2266 2267 The actual time series at which data is available is specified by 2268 means of an array \code{time} of monotonically increasing times. The 2269 quantities containing the values to be interpolated are specified in 2270 an array -- or dictionary of arrays (used in conjunction with the 2271 optional argument \code{quantity\_names}) -- called 2272 \code{quantities}. The optional arguments \code{vertex_coordinates} 2273 and \code{triangles} represent the spatial mesh associated with the 2274 quantity arrays. If omitted the function created by 2275 \code{Interpolation_function} will be a function of \code{t} only. 2276 2277 Since, in practice, values need to be computed at specified points, 2278 the syntax allows the user to specify, once and for all, a list 2279 \code{interpolation_points} of points at which values are required. 2280 In this case, the function may be called using the form \code{f(t, id)}, 2281 where \code{id} is an index for the list \code{interpolation_points}. 2282 \end{classdesc} 2119 2283 2120 2284 … … 2123 2287 2124 2288 \anuga provides a large number of predefined boundary conditions, 2125 represented by objects such as \code{Reflective \_boundary(domain)} and2126 \code{Dirichlet \_boundary([0.2, 0.0, 0.0])}, described in the examples2289 represented by objects such as \code{Reflective_boundary(domain)} and 2290 \code{Dirichlet_boundary([0.2, 0.0, 0.0])}, described in the examples 2127 2291 in Chapter 2. Alternatively, you may prefer to ''roll your own'', 2128 2292 following the method explained in Section \ref{sec:roll your own}. 2129 2293 2130 These boundary objects may be used with the function \code{set \_boundary} described below2294 These boundary objects may be used with the function \code{set_boundary} described below 2131 2295 to assign boundary conditions according to the tags used to label boundary segments. 2132 2296 2133 \begin{methoddesc}{set\_boundary}{boundary_map} 2134 Module: \module{abstract\_2d\_finite\_volumes.domain} 2135 2136 This function allows you to assign a boundary object (corresponding to a 2137 pre-defined or user-specified boundary condition) to every boundary segment that 2138 has been assigned a particular tag. 2139 2140 This is done by specifying a dictionary \code{boundary\_map}, whose values are the boundary objects 2141 and whose keys are the symbolic tags. 2142 \end{methoddesc} 2143 2144 \begin{methoddesc} {get\_boundary\_tags}{} 2145 Module: \module{abstract\_2d\_finite\_volumes.domain} 2146 2147 Returns a list of the available boundary tags. 2297 \begin{methoddesc}{\emph{<domain>}.set_boundary}{boundary_map} 2298 Module: \module{abstract_2d_finite_volumes.domain} 2299 2300 This function allows you to assign a boundary object (corresponding to a 2301 pre-defined or user-specified boundary condition) to every boundary segment that 2302 has been assigned a particular tag. 2303 2304 \code{boundary_map} is a dictionary of boundary objects keyed by symbolic tags. 2305 \end{methoddesc} 2306 2307 \begin{methoddesc} {\emph{<domain>}.get_boundary_tags}{} 2308 Module: \module{abstract\_2d\_finite\_volumes.domain} 2309 2310 Returns a list of the available boundary tags. 2148 2311 \end{methoddesc} 2149 2312 2150 2313 \subsection{Predefined boundary conditions} 2151 2314 2152 \begin{classdesc}{Reflective \_boundary}{Boundary}2153 Module: \module{shallow\_water}2154 2155 2156 2157 2158 2159 2315 \begin{classdesc}{Reflective_boundary}{domain=None} 2316 Module: \module{shallow_water} 2317 2318 Reflective boundary returns same conserved quantities as those present in 2319 the neighbouring volume but reflected. 2320 2321 This class is specific to the shallow water equation as it works with the 2322 momentum quantities assumed to be the second and third conserved quantities. 2160 2323 \end{classdesc} 2161 2324 2162 \begin{classdesc}{Transmissive \_boundary}{domain=None}2325 \begin{classdesc}{Transmissive_boundary}{domain=None} 2163 2326 \label{pg: transmissive boundary} 2164 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}2165 2166 2167 2168 2169 2327 Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions} 2328 2329 A transmissive boundary returns the same conserved quantities as 2330 those present in the neighbouring volume. 2331 2332 The underlying domain must be specified when the boundary is instantiated. 2170 2333 \end{classdesc} 2171 2334 2172 \begin{classdesc}{Dirichlet \_boundary}{conserved_quantities=None}2173 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions}2174 2175 2176 quantities. In the example of \code{Dirichlet\_boundary([0.2, 0.0, 0.0])},2177 2178 2179 2335 \begin{classdesc}{Dirichlet_boundary}{conserved_quantities=None} 2336 Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions} 2337 2338 A Dirichlet boundary returns constant values for each of conserved 2339 quantities. In the example of \code{Dirichlet_boundary([0.2, 0.0, 0.0])}, 2340 the \code{stage} value at the boundary is 0.2 and the \code{xmomentum} and 2341 \code{ymomentum} at the boundary are set to 0.0. The list must contain 2342 a value for each conserved quantity. 2180 2343 \end{classdesc} 2181 2344 2182 \begin{classdesc}{Time\_boundary}{domain = None, f = None} 2183 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions} 2184 2185 A time-dependent boundary returns values for the conserved 2186 quantities as a function \code{f(t)} of time. The user must specify 2187 the domain to get access to the model time. 2188 2189 Optional argument \code{default\_boundary} can be used to specify another boundary object 2190 to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}. 2191 The \code{default\_boundary} could be a simple Dirichlet condition or 2192 even another \code{Time\_boundary} typically using data pertaining to another time interval. 2345 \begin{classdesc}{Time_boundary}{domain=None, 2346 function=None, 2347 default_boundary=None, 2348 verbose=False} 2349 Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions} 2350 2351 A time-dependent boundary returns values for the conserved 2352 quantities as a function of time \code{function(t)}. The user must specify 2353 the domain to get access to the model time. 2354 2355 Optional argument \code{default_boundary} can be used to specify another boundary object 2356 to be used in case model time exceeds the time available in the file used by \code{File_boundary}. 2357 The \code{default_boundary} could be a simple Dirichlet condition or 2358 even another \code{Time_boundary} typically using data pertaining to another time interval. 2193 2359 \end{classdesc} 2194 2360 2195 \begin{classdesc}{File\_boundary}{Boundary} 2196 Module: \module{abstract\_2d\_finite\_volumes.generic\_boundary\_conditions} 2197 2198 This method may be used if the user wishes to apply a SWW file, STS file or 2199 a time series file (TMS) to a boundary segment or segments. 2200 The boundary values are obtained from a file and interpolated to the 2201 appropriate segments for each conserved quantity. 2202 2203 Optional argument \code{default\_boundary} can be used to specify another boundary object 2204 to be used in case model time exceeds the time availabel in the file used by \code{File\_boundary}. 2205 The \code{default\_boundary} could be a simple Dirichlet condition or 2206 even another \code{File\_boundary} typically using data pertaining to another time interval. 2361 \begin{classdesc}{File_boundary}{filename, 2362 domain, 2363 time_thinning=1, 2364 time_limit=None, 2365 boundary_polygon=None, 2366 default_boundary=None, 2367 use_cache=False, 2368 verbose=False} 2369 Module: \module{abstract_2d_finite_volumes.generic_boundary_conditions} 2370 2371 This method may be used if the user wishes to apply a SWW file, STS file or 2372 a time series file (TMS) to a boundary segment or segments. 2373 The boundary values are obtained from a file and interpolated to the 2374 appropriate segments for each conserved quantity. 2375 2376 Optional argument \code{default_boundary} can be used to specify another boundary object 2377 to be used in case model time exceeds the time available in the file used by \code{File_boundary}. 2378 The \code{default_boundary} could be a simple Dirichlet condition or 2379 even another \code{File_boundary} typically using data pertaining to another time interval. 2207 2380 \end{classdesc} 2208 2381 2209 \begin{classdesc}{Field\_boundary}{Boundary} 2210 Module: \module{shallow\_water.shallow\_water\_domain} 2211 2212 This method works in the same way as \code{File\_boundary} except that it 2213 allows for the value of stage to be offset by a constant specified in the 2214 keyword argument \code{mean\_stage}. 2215 2216 This functionality allows for models to be run for a range of tides using 2217 the same boundary information (from .sts, .sww or .tms files). The tidal value 2218 for each run would then be specified in the keyword argument 2219 \code{mean\_stage}. 2220 If \code{mean\_stage} = 0.0, \code{Field\_boundary} and \code{File\_boundary} 2221 behave identically. 2222 2223 Note that if the optional argument \code{default\_boundary} is specified 2224 it's stage value will be adjusted by \code{mean\_stage} just like the values 2225 obtained from the file. 2226 2227 See \code{File\_boundary} for further details. 2382 \begin{classdesc}{Field_boundary}{filename, 2383 domain, 2384 mean_stage=0.0, 2385 time_thinning=1, 2386 time_limit=None, 2387 boundary_polygon=None, 2388 default_boundary=None, 2389 use_cache=False, 2390 verbose=False} 2391 Module: \module{shallow_water.shallow_water_domain} 2392 2393 This method works in the same way as \code{File_boundary} except that it 2394 allows for the value of stage to be offset by a constant specified in the 2395 keyword argument \code{mean_stage}. 2396 2397 This functionality allows for models to be run for a range of tides using 2398 the same boundary information (from STS, SWW or TMS files). The tidal value 2399 for each run would then be specified in the keyword argument \code{mean_stage}. 2400 If \code{mean_stage} = 0.0, \code{Field_boundary} and \code{File_boundary} 2401 behave identically. 2402 2403 Note that if the optional argument \code{default_boundary} is specified 2404 its stage value will be adjusted by \code{mean_stage} just like the values 2405 obtained from the file. 2406 2407 See \code{File_boundary} for further details. 2228 2408 \end{classdesc} 2229 2409 2230 \begin{classdesc}{Transmissive\_momentum\_set\_stage\_boundary}{Boundary} 2231 Module: \module{shallow\_water} 2232 \label{pg: transmissive momentum set stage boundary} 2233 2234 This boundary returns same momentum conserved quantities as 2235 those present in its neighbour volume but sets stage as in a Time\_boundary. 2236 The underlying domain must be specified when boundary is instantiated 2237 2238 This type of boundary is useful when stage is known at the boundary as a 2239 function of time, but momenta (or speeds) aren't. 2240 2241 This class is specific to the shallow water equation as it works with the 2242 momentum quantities assumed to be the second and third conserved quantities. 2243 2244 In some circumstances, this boundary condition may cause numerical instabilities for similar 2245 reasons as what has been observed with the simple fully transmissive boundary condition 2246 (see Page \pageref{pg: transmissive boundary}). 2247 This could for example be the case if a planar wave is reflected out through this boundary. 2410 \begin{classdesc}{Transmissive_momentum_set_stage_boundary}{domain=None, 2411 function=None} 2412 Module: \module{shallow_water.shallow_water_domain} 2413 \label{pg: transmissive momentum set stage boundary} 2414 2415 This boundary returns the same momentum conserved quantities as 2416 those present in its neighbour volume but sets stage as in a \code{Time_boundary}. 2417 The underlying domain must be specified when boundary is instantiated. 2418 2419 This type of boundary is useful when stage is known at the boundary as a 2420 function of time, but momenta (or speeds) aren't. 2421 2422 This class is specific to the shallow water equation as it works with the 2423 momentum quantities assumed to be the second and third conserved quantities. 2424 2425 In some circumstances, this boundary condition may cause numerical instabilities for similar 2426 reasons as what has been observed with the simple fully transmissive boundary condition 2427 (see Page \pageref{pg: transmissive boundary}). 2428 This could for example be the case if a planar wave is reflected out through this boundary. 2248 2429 \end{classdesc} 2249 2430 2250 \begin{classdesc}{Transmissive \_stage\_zero\_momentum\_boundary}{Boundary}2251 Module: \module{shallow\_water}2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2431 \begin{classdesc}{Transmissive_stage_zero_momentum_boundary}{domain=None} 2432 Module: \module{shallow_water} 2433 \label{pg: transmissive stage zero momentum boundary} 2434 2435 This boundary returns same stage conserved quantities as 2436 those present in its neighbour volume but sets momentum to zero. 2437 The underlying domain must be specified when boundary is instantiated 2438 2439 This type of boundary is useful when stage is known at the boundary as a 2440 function of time, but momentum should be set to zero. This is for example 2441 the case where a boundary is needed in the ocean on the two sides perpendicular 2442 to the coast to maintain the wave height of the incoming wave. 2443 2444 This class is specific to the shallow water equation as it works with the 2445 momentum quantities assumed to be the second and third conserved quantities. 2446 2447 This boundary condition should not cause the numerical instabilities seen with the transmissive momentum 2448 boundary conditions (see Page \pageref{pg: transmissive boundary} and 2449 Page \pageref{pg: transmissive momentum set stage boundary}). 2269 2450 \end{classdesc} 2270 2451 2271 \begin{classdesc}{Dirichlet\_discharge\_boundary}{Boundary} 2272 Module: \module{shallow\_water} 2273 2274 Sets stage (stage0) 2275 Sets momentum (wh0) in the inward normal direction. 2452 \begin{classdesc}{Dirichlet_discharge_boundary}{domain=None, stage0=None, wh0=None} 2453 Module: \module{shallow_water.shallow_water_domain} 2454 2455 \code{stage0} sets the stage. 2456 2457 \code{wh0} sets momentum in the inward normal direction. 2276 2458 \end{classdesc} 2277 2459 … … 2280 2462 2281 2463 All boundary classes must inherit from the generic boundary class 2282 \code{Boundary} and have a method called \code{evaluate } which must2283 take as inputs \code{self , vol\_id, edge\_id} where selfrefers to the2284 object itself and vol\_id and edge\_idare integers referring to2464 \code{Boundary} and have a method called \code{evaluate()} which must 2465 take as inputs \code{self}, \code{vol_id} and \code{edge_id} where \code{self} refers to the 2466 object itself and \code{vol_id} and \code{edge_id} are integers referring to 2285 2467 particular edges. The method must return a list of three floating point 2286 2468 numbers representing values for \code{stage}, … … 2288 2470 2289 2471 The constructor of a particular boundary class may be used to specify 2290 particular values or flags to be used by the \code{evaluate } method.2472 particular values or flags to be used by the \code{evaluate()} method. 2291 2473 Please refer to the source code for the existing boundary conditions 2292 2474 for examples of how to implement boundary conditions. … … 2299 2481 Gravity and friction are always calculated using the elevation and friction quantities, 2300 2482 but the user may additionally add forcing terms to the list 2301 \code{domain.forcing\_terms} and have them affect the model. 2302 2303 Currently, predefined forcing terms are: 2304 \begin{funcdesc}{General\_forcing}{} 2305 Module: \module{shallow\_water.shallow\_water\_domain} 2306 2307 This is a general class to modify any quantity according to a given rate of change. 2308 Other specific forcing terms are based on this class but it can be used by itself as well (e.g.\ to modify momentum). 2309 2310 The General\_forcing class takes as input: 2311 \begin{itemize} 2312 \item \code{domain}: a reference to the domain being evolved 2313 \item \code{quantity\_name}: The name of the quantity that will be affected by this forcing term 2314 \item \code{rate}: The rate at which the quantity should change. The parameter \code{rate} can be eithe a constant or a 2315 function of time. Positive values indicate increases, 2316 negative values indicate decreases. 2317 The parametr \code{rate} can be \code{None} at initialisation but must be specified 2318 before forcing term is applied (i.e. simulation has started). 2319 The default value is 0.0 -- i.e.\ no forcing. 2320 \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius. 2321 \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon. 2322 \end{itemize} 2323 Note specifying both center, radius and polygon will cause an exception to be thrown. 2324 Moreover, if the specified polygon or circle does not lie fully within the mesh boundary an Exception will be thrown. 2325 2326 \bigskip 2327 Example: 2328 2329 \begin{verbatim} 2483 \code{domain.forcing_terms} and have them affect the model. 2484 2485 Currently, predefined forcing terms are: \\ 2486 \begin{classdesc}{General_forcing}{domain, 2487 quantity_name, 2488 rate=0.0, 2489 center=None, 2490 radius=None, 2491 polygon=None, 2492 default_rate=None, 2493 verbose=False} 2494 Module: \module{shallow_water.shallow_water_domain} 2495 2496 This is a general class to modify any quantity according to a given rate of change. 2497 Other specific forcing terms are based on this class but it can be used by itself as well (e.g. to modify momentum). 2498 2499 \code{domain} is the domain being evolved. 2500 2501 \code{quantity_name} is the name of the quantity that will be affected by this forcing term. 2502 2503 \code{rate} is the rate at which the quantity should change. This can be either a constant or a 2504 function of time. Positive values indicate increases, negative values indicate decreases. 2505 The parameter \code{rate} can be \code{None} at initialisation but must be specified 2506 before a forcing term is applied (i.e. simulation has started). 2507 The default value is 0.0 -- i.e. no forcing. 2508 2509 \code{center} and \code{ radius} optionally restrict forcing to a circle with given center and radius. 2510 2511 \code{polygon} optionally restricts forcing to an area enclosed by the given polygon. 2512 2513 Note: specifying \code{center}, \code{radius} and \code{polygon} will cause an exception to be thrown. 2514 Moreover, if the specified polygon or circle does not lie fully within the mesh boundary an Exception will be thrown. 2515 2516 Example: 2517 2518 \begin{verbatim} 2330 2519 P = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]] # Square polygon 2331 2520 … … 2338 2527 domain.forcing_terms.append(xmom) 2339 2528 domain.forcing_terms.append(ymom) 2340 \end{verbatim} 2341 2342 Here, \code{f}, \code{g} are assumed to be defined as functions of time providing 2343 a time dependent rate of change for xmomentum and ymomentum respectively. 2344 P is assumed to be polygon, specified as a list of points. 2345 \end{funcdesc} 2346 2347 \begin{funcdesc}{Inflow}{} 2348 Module: \module{shallow\_water.shallow\_water\_domain} 2349 2350 This is a general class for inflow and abstraction of water according to a given rate of change. 2351 This class will always modify the \code{stage} quantity. 2352 2353 Inflow is based on the General_forcing class so the functionality is similar. 2354 2355 The Inflow class takes as input: 2356 \begin{itemize} 2357 \item \code{domain}: a reference to the domain being evolved 2358 \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 2359 function of time. Positive values indicate inflow, 2360 negative values indicate outflow. 2361 2362 Note: The specified flow will be divided by the area of 2363 the inflow region and then applied to update the 2364 stage quantity. 2365 \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius. 2366 \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon. 2367 \end{itemize} 2368 2369 \bigskip 2370 Example: 2371 2372 \begin{verbatim} 2373 hydrograph = Inflow(center=(320, 300), radius=10, rate=file_function('QPMF_Rot_Sub13.tms')) 2529 \end{verbatim} 2530 2531 Here, \code{f} and \code{g} are assumed to be defined as functions of time providing 2532 a time dependent rate of change for xmomentum and ymomentum respectively. 2533 \code{P} is assumed to be the polygon, specified as a list of points. 2534 \end{classdesc} 2535 2536 \begin{classdesc}{Inflow}{domain, 2537 rate=0.0, 2538 center=None, radius=None, 2539 polygon=None, 2540 default_rate=None, 2541 verbose=False} 2542 Module: \module{shallow_water.shallow_water_domain} 2543 2544 This is a general class for inflow and abstraction of water according to a given rate of change. 2545 This class will always modify the \code{stage} quantity. 2546 2547 Inflow is based on the \code{General_forcing} class so the functionality is similar. 2548 2549 \code{domain} is the domain being evolved. 2550 2551 \code{rate} is the flow rate ($m^3/s$) at which the quantity should change. This can be either a constant or a 2552 function of time. Positive values indicate inflow, negative values indicate outflow. 2553 Note: The specified flow will be divided by the area of the inflow region and then applied to update the 2554 stage quantity. 2555 2556 \code{center} and \code{ radius} optionally restrict forcing to a circle with given center and radius. 2557 2558 \code{polygon} optionally restricts forcing to an area enclosed by the given polygon. 2559 2560 Example: 2561 2562 \begin{verbatim} 2563 hydrograph = Inflow(center=(320, 300), radius=10, 2564 rate=file_function('QPMF_Rot_Sub13.tms')) 2374 2565 2375 2566 domain.forcing_terms.append(hydrograph) 2376 \end{verbatim} 2377 2378 Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for a hydrograph. 2379 \end{funcdesc} 2380 2381 \begin{funcdesc}{Rainfall}{} 2382 Module: \module{shallow\_water.shallow\_water\_domain} 2383 2384 This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon. 2385 This class will always modify the \code{stage} quantity. 2386 2387 Rainfall is based on the General_forcing class so the functionality is similar. 2388 2389 The Rainfall class takes as input: 2390 \begin{itemize} 2391 \item \code{domain}: a reference to the domain being evolved 2392 \item \code{rate}: Total rain rate over the specified domain. 2393 Note: Raingauge Data needs to reflect the time step. 2394 For example: if rain gauge is mm read every \code{dt} seconds, then the input 2395 here is as \code{mm/dt} so 10 mm in 5 minutes becomes 2396 10/(5x60) = 0.0333mm/s. 2397 2398 This parameter can be either a constant or a 2399 function of time. Positive values indicate rain being added (or be used for general infiltration), 2400 negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction). 2401 \item \code{center, radius}: Optionally restrict forcing to a circle with given center and radius. 2402 \item \code{polygon}: Optionally restrict forcing to an area enclosed by given polygon. 2403 \end{itemize} 2404 2405 \bigskip 2406 Example: 2407 2408 \begin{verbatim} 2567 \end{verbatim} 2568 2569 Here, \code{'QPMF_Rot_Sub13.tms'} is assumed to be a NetCDF file in the TMS format defining a timeseries for a hydrograph. 2570 \end{classdesc} 2571 2572 \begin{classdesc}{Rainfall}{domain, 2573 rate=0.0, 2574 center=None, 2575 radius=None, 2576 polygon=None, 2577 default_rate=None, 2578 verbose=False} 2579 Module: \module{shallow_water.shallow_water_domain} 2580 2581 This is a general class for implementing rainfall over the domain, possibly restricted to a given circle or polygon. 2582 This class will always modify the \code{stage} quantity. 2583 2584 Rainfall is based on the \code{General_forcing} class so the functionality is similar. 2585 2586 \code{domain} is the domain being evolved. 2587 2588 \code{rate} is the total rain rate over the specified domain. 2589 Note: Raingauge Data needs to reflect the time step. 2590 For example, if rain gauge is \code{mm} read every \code{dt} seconds, then the input 2591 here is as \code{mm/dt} so 10 mm in 5 minutes becomes 2592 10/(5x60) = 0.0333mm/s. This parameter can be either a constant or a 2593 function of time. Positive values indicate rain being added (or be used for general infiltration), 2594 negative values indicate outflow at the specified rate (presumably this could model evaporation or abstraction). 2595 2596 \code{center} and \code{ radius} optionally restrict forcing to a circle with given center and radius. 2597 2598 \code{polygon} optionally restricts forcing to an area enclosed by the given polygon. 2599 2600 Example: 2601 2602 \begin{verbatim} 2409 2603 catchmentrainfall = Rainfall(rate=file_function('Q100_2hr_Rain.tms')) 2410 2604 domain.forcing_terms.append(catchmentrainfall) 2411 \end{verbatim} 2412 2413 Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the format \code{tms} defining a timeseries for the rainfall. 2414 \end{funcdesc} 2415 2416 \begin{funcdesc}{Culvert\_flow}{} 2417 Module: \module{culver\_flows.culvert\_class} 2418 2419 This is a general class for implementing flow through a culvert. 2420 This class modifies the quantities \code{stage, xmomentum, ymomentum} in areas at both ends of the culvert. 2421 2422 The Culvert\_flow forcing term uses \code{Inflow} and {General\_forcing} to update the quantities. 2423 The flow drection is determined on-the-fly so openings are referenced simple as opening0 and opening1 2424 with either being able to take the role as Inflow and Outflow. 2425 2426 The Culvert\_flow class takes as input: 2427 \begin{itemize} 2428 \item \code{domain}: a reference to the domain being evolved 2429 \item \code{label}: Short text naming the culvert 2430 \item \code{description}: Text describing it 2431 \item \code{end_point0}: Coordinates of one opening 2432 \item \code{end_point1}: Coordinates of other opening 2433 \item \code{width}: 2434 \item \code{height}: 2435 \item \code{diameter}: 2436 \item \code{manning}: Mannings Roughness for Culvert 2437 \item \code{invert_level0}: Invert level if not the same as the Elevation on the Domain 2438 \item \code{invert_level1}: Invert level if not the same as the Elevation on the Domain 2439 \item \code{culvert_routine}: Function specifying the calculation of flow based on energy difference between the two openings (see below) 2440 \item \code{number_of_barrels}: Number of identical pipes in the culvert. Default == 1. 2441 \end{itemize} 2442 2443 The user can specify different culvert routines. Hower ANUGA currently provides only one, namely the 2444 \code{boyd\_generalised\_culvert\_model} as used in the example below. 2445 2446 Example: 2447 2448 \begin{verbatim} 2605 \end{verbatim} 2606 2607 Here, \code{'Q100_2hr_Rain.tms'} is assumed to be a NetCDF file in the TMS format defining a timeseries for the rainfall. 2608 \end{classdesc} 2609 2610 \begin{classdesc}{Culvert_flow}{domain, 2611 culvert_description_filename=None, 2612 culvert_routine=None, 2613 end_point0=None, 2614 end_point1=None, 2615 enquiry_point0=None, 2616 enquiry_point1=None, 2617 type='box', 2618 width=None, 2619 height=None, 2620 length=None, 2621 number_of_barrels=1, 2622 trigger_depth=0.01, 2623 manning=None, 2624 sum_loss=None, 2625 use_velocity_head=False, 2626 use_momentum_jet=False, 2627 label=None, 2628 description=None, 2629 update_interval=None, 2630 log_file=False, 2631 discharge_hydrograph=False, 2632 verbose=False} 2633 Module: \module{culvert_flows.culvert_class} 2634 2635 This is a general class for implementing flow through a culvert. 2636 This class modifies the quantities \code{stage}, \code{xmomentum} and \code{ymomentum} in areas at both ends of the culvert. 2637 2638 The \code{Culvert_flow} forcing term uses \code{Inflow} and \code{General_forcing} to update the quantities. 2639 The flow direction is determined on-the-fly so openings are referenced simple as opening0 and opening1 2640 with either being able to take the role as Inflow or Outflow. 2641 2642 The Culvert_flow class takes as input: 2643 \begin{itemize} 2644 \item \code{domain}: a reference to the domain being evolved 2645 \item \code{culvert_description_filename}: 2646 \item \code{culvert_routine}: 2647 \item \code{end_point0}: Coordinates of one opening 2648 \item \code{end_point1}: Coordinates of other opening 2649 \item \code{enquiry_point0}: 2650 \item \code{enquiry_point1}: 2651 \item \code{type}: (default is 'box') 2652 \item \code{width}: 2653 \item \code{height}: 2654 \item \code{length}: 2655 \item \code{number_of_barrels}: Number of identical pipes in the culvert (default is 1) 2656 \item \code{trigger_depth}: (default is 0.01) 2657 \item \code{manning}: Mannings Roughness for Culvert 2658 \item \code{sum_loss}: 2659 \item \code{use_velocity_head}: 2660 \item \code{use_momentum_jet}: 2661 \item \code{label}: Short text naming the culvert 2662 \item \code{description}: Text describing the culvert 2663 \item \code{update_interval}: 2664 \item \code{log_file}: 2665 \item \code{discharge_hydrograph}: 2666 \end{itemize} 2667 2668 The user can specify different culvert routines. Hower \anuga currently provides only one, namely the 2669 \code{boyd_generalised_culvert_model} as used in the example below: 2670 2671 \begin{verbatim} 2449 2672 from anuga.culvert_flows.culvert_class import Culvert_flow 2450 2673 from anuga.culvert_flows.culvert_routines import boyd_generalised_culvert_model … … 2455 2678 end_point0=[9.0, 2.5], 2456 2679 end_point1=[13.0, 2.5], 2457 width=1.20,height=0.75, 2680 width=1.20, 2681 height=0.75, 2458 2682 culvert_routine=boyd_generalised_culvert_model, 2459 2683 number_of_barrels=1, … … 2473 2697 domain.forcing_terms.append(culvert1) 2474 2698 domain.forcing_terms.append(culvert2) 2475 2476 \end{ funcdesc}2699 \end{verbatim} 2700 \end{classdesc} 2477 2701 2478 2702 … … 2480 2704 \label{sec:evolution} 2481 2705 2482 \begin{methoddesc}{evolve}{yieldstep=None, finaltime=None, duration=None, skip_initial_step=False} 2483 Module: \module{abstract\_2d\_finite\_volumes.domain} 2484 2485 This function (a method of \class{domain}) is invoked once all the 2486 preliminaries have been completed, and causes the model to progress 2487 through successive steps in its evolution, storing results and 2488 outputting statistics whenever a user-specified period 2489 \code{yieldstep} is completed (generally during this period the 2490 model will evolve through several steps internally 2491 as the method forces the water speed to be calculated 2492 on successive new cells). 2493 2494 The code specified by the user in the block following the evolve statement is only executed once every \code{yieldstep} even though 2495 ANUGA typically will take many more internal steps behind the scenes. 2496 2497 The user 2498 specifies the total time period over which the evolution is to take 2499 place, by specifying values (in seconds) for either \code{duration} 2500 or \code{finaltime}, as well as the interval in seconds after which 2501 results are to be stored and statistics output. 2502 2503 You can include \method{evolve} in a statement of the type: 2504 2505 \begin{verbatim} 2706 \begin{methoddesc}{\emph{<domain>}.evolve}{yieldstep=None, 2707 finaltime=None, 2708 duration=None, 2709 skip_initial_step=False} 2710 Module: \module{abstract_2d_finite_volumes.domain} 2711 2712 This method is invoked once all the 2713 preliminaries have been completed, and causes the model to progress 2714 through successive steps in its evolution, storing results and 2715 outputting statistics whenever a user-specified period 2716 \code{yieldstep} is completed. Generally during this period the 2717 model will evolve through several steps internally 2718 as the method forces the water speed to be calculated 2719 on successive new cells. 2720 2721 \code{yieldstep} is the interval in seconds between yields where results are 2722 stored, statistics written and the domain is inspected or possibly modified. 2723 If omitted an internal predefined \code{yieldstep} is used. Internally, smaller 2724 timesteps may be taken. 2725 2726 \code{duration} is the duration of the simulation in seconds. 2727 2728 \code{finaltime} is the time in seconds where simulation should end. This is currently 2729 relative time, so it's the same as \code{duration}. If both \code{duration} and 2730 \code{finaltime} are given an exception is thrown. 2731 2732 \code{skip_initial_step} is a boolean flag that decides whether the first 2733 yield step is skipped or not. This is useful for example to avoid 2734 duplicate steps when multiple evolve processes are dove tailed. 2735 2736 The code specified by the user in the block following the evolve statement is 2737 only executed once every \code{yieldstep} even though 2738 \anuga typically will take many more internal steps behind the scenes. 2739 2740 You can include \method{evolve} in a statement of the type: 2741 2742 \begin{verbatim} 2506 2743 for t in domain.evolve(yieldstep, finaltime): 2507 2744 <Do something with domain and t> 2508 2745 \end{verbatim} 2509 2746 \end{methoddesc} 2510 2747 … … 2512 2749 \label{sec:diagnostics} 2513 2750 2514 \begin{funcdesc}{statistics}{} 2515 Module: \module{abstract\_2d\_finite\_volumes.domain} 2516 2517 \end{funcdesc} 2518 2519 \begin{funcdesc}{timestepping\_statistics}{} 2520 Module: \module{abstract\_2d\_finite\_volumes.domain} 2521 2522 Returns a string of the following type for each timestep: 2523 \code{Time = 0.9000, delta t in [0.00598964, 0.01177388], steps=12 2524 (12)} 2525 2526 Here the numbers in \code{steps=12 (12)} indicate the number of steps taken and 2527 the number of first-order steps, respectively.\\ 2528 2529 The optional keyword argument \code{track_speeds=True} will 2530 generate a histogram of speeds generated by each triangle. The 2531 speeds relate to the size of the timesteps used by ANUGA and 2532 this diagnostics may help pinpoint problem areas where excessive speeds 2533 are generated. 2534 \end{funcdesc} 2535 2536 \begin{funcdesc}{boundary\_statistics}{quantities=None, tags=None} 2537 Module: \module{abstract\_2d\_finite\_volumes.domain} 2538 2539 Returns a string of the following type when \code{quantities = 'stage'} 2540 and \code{tags = ['top', 'bottom']}: 2541 2542 \begin{verbatim} 2751 \begin{methoddesc}{\emph{<domain>}.statistics}{} 2752 Module: \module{abstract\_2d\_finite\_volumes.domain} 2753 2754 Outputs statistics about the mesh within the \code{Domain}. 2755 \end{methoddesc} 2756 2757 \begin{methoddesc}{\emph{<domain>}.timestepping_statistics}{track_speeds=False, triangle_id=None} 2758 Module: \module{abstract_2d_finite_volumes.domain} 2759 2760 Returns a string of the following type for each timestep:\\ 2761 \code{Time = 0.9000, delta t in [0.00598964, 0.01177388], steps=12 (12)} 2762 2763 Here the numbers in \code{steps=12 (12)} indicate the number of steps taken and 2764 the number of first-order steps, respectively. 2765 2766 The optional keyword argument \code{track_speeds} will 2767 generate a histogram of speeds generated by each triangle if set to \code{True}. The 2768 speeds relate to the size of the timesteps used by \anuga and 2769 this diagnostics may help pinpoint problem areas where excessive speeds 2770 are generated. 2771 2772 The optional keyword argument \code{triangle_id} can be used to specify a particular 2773 triangle rather than the one with the largest speed. 2774 \end{methoddesc} 2775 2776 \begin{methoddesc}{\emph{<domain>}.boundary_statistics}{quantities=None, 2777 tags=None} 2778 Module: \module{abstract_2d_finite_volumes.domain} 2779 2780 Generates output about boundary forcing at each timestep. 2781 2782 \code{quantities} names the quantities to be reported -- may be \code{None}, 2783 a string or a list of strings. 2784 2785 \code{tags} names the tags to be reported -- may be either None, a string or a list of strings. 2786 2787 When \code{quantities = 'stage'} and \code{tags = ['top', 'bottom']} 2788 will return a string like: 2789 2790 \begin{verbatim} 2543 2791 Boundary values at time 0.5000: 2544 2792 top: … … 2546 2794 bottom: 2547 2795 stage in [ -0.27098821, -0.02499974] 2548 \end{verbatim} 2549 \end{funcdesc} 2550 2551 \begin{funcdesc}{get\_quantity}{name, location='vertices', indices=None} 2552 Module: \module{abstract\_2d\_finite\_volumes.domain} 2553 2554 This function returns a Quantity object Q. 2555 Access to its values should be done through Q.get\__values documented on Page \pageref{pg:get values}. 2556 \end{funcdesc} 2557 2558 \begin{funcdesc}{set\_quantities\_to\_be\_monitored}{} 2559 Module: \module{abstract\_2d\_finite\_volumes.domain} 2560 2561 Selects quantities and derived quantities for which extrema attained at internal timesteps 2562 will be collected. 2563 2564 Information can be tracked in the evolve loop by printing \code{quantity\_statistics} and 2565 collected data will be stored in the sww file. 2566 2567 Optional parameters \code{polygon} and \code{time\_interval} may be specified to restrict the 2568 extremum computation. 2569 \end{funcdesc} 2570 2571 \begin{funcdesc}{quantity\_statistics}{} 2572 Module: \module{abstract\_2d\_finite\_volumes.domain} 2573 2574 Reports on extrema attained by selected quantities. 2575 2576 Returns a string of the following type for each 2577 timestep: 2578 2579 \begin{verbatim} 2796 \end{verbatim} 2797 \end{methoddesc} 2798 2799 \begin{methoddesc}{Q = \emph{<domain>}.get_quantity}{name, 2800 location='vertices', 2801 indices=None} 2802 Module: \module{abstract_2d_finite_volumes.domain} 2803 2804 This function returns a Quantity object Q. 2805 Access to its values should be done through \code{Q.get_values()} documented on Page \pageref{pg:get values}. 2806 2807 \code{name} is the name of the quantity to retrieve. 2808 2809 \code{location} is 2810 2811 \code{indices} is 2812 \end{methoddesc} 2813 2814 \begin{methoddesc}{\emph{<domain>}.set_quantities_to_be_monitored}{quantity, 2815 polygon=None, 2816 time_interval=None} 2817 Module: \module{abstract\_2d\_finite\_volumes.domain} 2818 2819 Selects quantities and derived quantities for which extrema attained at internal timesteps 2820 will be collected. 2821 2822 \code{quantity} specifies the quantity or quantities to be monitored and must be either: 2823 \begin{itemize} 2824 \item the name of a quantity or derived quantity such as 'stage-elevation', 2825 \item a list of quantity names, or 2826 \item \code{None}. 2827 \end{itemize} 2828 2829 \code{polygon} can be used to monitor only triangles inside the polygon. Otherwise 2830 all triangles will be included. 2831 2832 \code{time_interval} will restrict monitoring to time steps in the interval. Otherwise 2833 all timesteps will be included. 2834 2835 Information can be tracked in the evolve loop by printing \code{quantity_statistics} and 2836 collected data will be stored in the SWW file. 2837 \end{methoddesc} 2838 2839 \begin{methoddesc}{\emph{<domain>}.quantity_statistics}{precision='\%.4f'} 2840 Module: \module{abstract_2d_finite_volumes.domain} 2841 2842 Reports on extrema attained by selected quantities. 2843 2844 Returns a string of the following type for each timestep: 2845 2846 \begin{verbatim} 2580 2847 Monitored quantities at time 1.0000: 2581 2848 stage-elevation: … … 2591 2858 minimum attained at time = 0.00000000, location = (0.16666667, 0.33333333) 2592 2859 maximum attained at time = 0.35103646, location = (0.83333333, 0.16666667) 2593 \end{verbatim} 2594 2595 The quantities (and derived quantities) listed here must be selected at model 2596 initialisation using the method \code{domain.set_quantities_to_be_monitored}.\\ 2597 2598 The optional keyword argument \code{precision='\%.4f'} will 2599 determine the precision used for floating point values in the output. 2600 This diagnostics helps track extrema attained by the selected quantities 2601 at every internal timestep. 2602 2603 These values are also stored in the SWW file for post processing. 2604 \end{funcdesc} 2605 2606 \begin{funcdesc}{get\_values}{location='vertices', indices=None} 2607 \label{pg:get values} 2608 Module: \module{abstract\_2d\_finite\_volumes.quantity} 2609 2610 Extract values for quantity as a numeric array. 2611 2612 \begin{verbatim} 2613 Inputs: 2614 interpolation_points: List of x, y coordinates where value is 2615 sought (using interpolation). If points 2616 are given, values of location and indices 2617 are ignored. Assume either absolute UTM 2618 coordinates or geospatial data object. 2860 \end{verbatim} 2861 2862 The quantities (and derived quantities) listed here must be selected at model 2863 initialisation time using the method \code{domain.set_quantities_to_be_monitored()}. 2864 2865 The optional keyword argument \code{precision='\%.4f'} will 2866 determine the precision used for floating point values in the output. 2867 This diagnostics helps track extrema attained by the selected quantities 2868 at every internal timestep. 2869 2870 These values are also stored in the SWW file for post-processing. 2871 \end{methoddesc} 2872 2873 \begin{methoddesc}{\emph{<quantity>}.get_values}{interpolation_points=None, 2874 location='vertices', 2875 indices=None, 2876 use_cache=False, 2877 verbose=False} 2878 \label{pg:get values} 2879 Module: \module{abstract_2d_finite_volumes.quantity} 2880 2881 Extract values for quantity as a numeric array. 2882 2883 \code{interpolation_points} is a list of (x, y) coordinates where the value is 2884 sought (using interpolation). If \code{interpolation_points} is given, values 2885 for \code{location} and \code{indices} are ignored. 2886 Assume either an absolute UTM coordinates or geospatial data object. 2619 2887 2620 location: Where values are to be stored. 2621 Permissible options are: vertices, edges, centroids 2622 and unique vertices. Default is 'vertices' 2623 \end{verbatim} 2624 2625 The returned values will have the leading dimension equal to length of the indices list or 2626 N (all values) if indices is None. 2627 2628 In case of location == 'centroids' the dimension of returned 2629 values will be a list or a numeric array of length N, N being 2630 the number of elements. 2631 2632 In case of location == 'vertices' or 'edges' the dimension of 2633 returned values will be of dimension Nx3 2634 2635 In case of location == 'unique vertices' the average value at 2636 each vertex will be returned and the dimension of returned values 2637 will be a 1d array of length "number of vertices" 2638 2639 Indices is the set of element ids that the operation applies to. 2640 2641 The values will be stored in elements following their 2642 internal ordering. 2643 \end{funcdesc} 2644 2645 \begin{funcdesc}{set\_values}{location='vertices', indices=None} 2646 Module: \module{abstract\_2d\_finite\_volumes.quantity} 2647 2648 Assign values to a quantity object. 2649 This method works the same way as \code{set\_quantity} except that it doesn't take 2650 a quantity name as the first argument. The reason to use \code{set\_values} is for 2651 example to assign values to a new quantity that has been created but which is 2652 not part of the domain's predefined quantities. 2653 2654 The method \code{set\_values} is always called by \code{set\_quantity} 2655 behind the scenes. 2656 \end{funcdesc} 2657 2658 \begin{funcdesc}{get\_integral}{} 2659 Module: \module{abstract\_2d\_finite\_volumes.quantity} 2660 2661 Return computed integral over entire domain for this quantity 2662 \end{funcdesc} 2663 2664 \begin{funcdesc}{get\_maximum\_value}{indices=None} 2665 Module: \module{abstract\_2d\_finite\_volumes.quantity} 2666 2667 Return maximum value of quantity (on centroids) 2668 2669 Optional argument indices is the set of element ids that 2670 the operation applies to. If omitted all elements are considered. 2671 2672 We do not seek the maximum at vertices as each vertex can 2673 have multiple values -- one for each triangle sharing it. 2674 \end{funcdesc} 2675 2676 \begin{funcdesc}{get\_maximum\_location}{indices=None} 2677 Module: \module{abstract\_2d\_finite\_volumes.quantity} 2678 2679 Return location of maximum value of quantity (on centroids) 2680 2681 Optional argument indices is the set of element ids that 2682 the operation applies to. 2683 2684 We do not seek the maximum at vertices as each vertex can 2685 have multiple values -- one for each triangle sharing it. 2686 2687 If there are multiple cells with same maximum value, the 2688 first cell encountered in the triangle array is returned. 2689 \end{funcdesc} 2690 2691 \begin{funcdesc}{get\_wet\_elements}{indices=None} 2692 Module: \module{shallow\_water.shallow\_water\_domain} 2693 2694 Return indices for elements where h $>$ minimum_allowed_height 2695 Optional argument indices is the set of element ids that the operation applies to. 2696 \end{funcdesc} 2697 2698 \begin{funcdesc}{get\_maximum\_inundation\_elevation}{indices=None} 2699 Module: \module{shallow\_water.shallow\_water\_domain} 2700 2701 Return highest elevation where h $>$ 0.\\ 2702 Optional argument indices is the set of element ids that the operation applies to.\\ 2703 2704 Example to find maximum runup elevation:\\ 2705 z = domain.get_maximum_inundation_elevation() 2706 \end{funcdesc} 2707 2708 \begin{funcdesc}{get\_maximum\_inundation\_location}{indices=None} 2709 Module: \module{shallow\_water.shallow\_water\_domain} 2710 2711 Return location (x,y) of highest elevation where h $>$ 0.\\ 2712 Optional argument indices is the set of element ids that the operation applies to.\\ 2713 2714 Example to find maximum runup location:\\ 2715 x, y = domain.get_maximum_inundation_location() 2716 \end{funcdesc} 2888 \code{location} specifies where values are to be stored. 2889 Permissible options are 'vertices', 'edges', 'centroids' or 'unique vertices'. 2890 2891 The returned values will have the leading dimension equal to length of the \code{indices} list or 2892 N (all values) if \code{indices} is \code{None}. 2893 2894 If \code{location} is 'centroids' the dimension of returned 2895 values will be a list or a numeric array of length N, N being 2896 the number of elements. 2897 2898 If \code{location} is 'vertices' or 'edges' the dimension of 2899 returned values will be of dimension \code{Nx3}. 2900 2901 If \code{location} is 'unique vertices' the average value at 2902 each vertex will be returned and the dimension of returned values 2903 will be a 1d array of length "number of vertices" 2904 2905 \code{indices} is the set of element ids that the operation applies to. 2906 2907 The values will be stored in elements following their internal ordering. 2908 \end{methoddesc} 2909 2910 \begin{methoddesc}{\emph{<quantity>}.set_values}{numeric=None, 2911 quantity=None, 2912 function=None, 2913 geospatial_data=None, 2914 filename=None, 2915 attribute_name=None, 2916 alpha=None, 2917 location='vertices', 2918 polygon=None, 2919 indices=None, 2920 smooth=False, 2921 verbose=False, 2922 use_cache=False} 2923 Module: \module{abstract_2d_finite_volumes.quantity} 2924 2925 Assign values to a quantity object. 2926 2927 This method works the same way as \code{set_quantity()} except that it doesn't take 2928 a quantity name as the first argument since it is applied directly to the quantity. 2929 Use \code{set_values} is used to assign 2930 values to a new quantity that has been created but which is 2931 not part of the domain's predefined quantities. 2932 2933 \code{location} is ?? 2934 2935 \code{indices} is ?? 2936 2937 The method \code{set_values()} is always called by \code{set_quantity()} 2938 behind the scenes. 2939 \end{methoddesc} 2940 2941 \begin{methoddesc}{\emph{<quantity>}.get_integral}{} 2942 Module: \module{abstract_2d_finite_volumes.quantity} 2943 2944 Return the computed integral over the entire domain for the quantity. 2945 \end{methoddesc} 2946 2947 \begin{methoddesc}{\emph{<quantity>}.get_maximum_value}{indices=None} 2948 Module: \module{abstract_2d_finite_volumes.quantity} 2949 2950 Return the maximum value of a quantity (on centroids). 2951 2952 \code{indices} is the optional set of element \code{id}s that 2953 the operation applies to. 2954 2955 We do not seek the maximum at vertices as each vertex can 2956 have multiple values -- one for each triangle sharing it. 2957 \end{methoddesc} 2958 2959 \begin{methoddesc}{\emph{<quantity>}.get_maximum_location}{indices=None} 2960 Module: \module{abstract_2d_finite_volumes.quantity} 2961 2962 Return the location of the maximum value of a quantity (on centroids). 2963 2964 \code{indices} is the optional set of element \code{id}s that 2965 the operation applies to. 2966 2967 We do not seek the maximum at vertices as each vertex can 2968 have multiple values -- one for each triangle sharing it. 2969 2970 If there are multiple cells with the same maximum value, the 2971 first cell encountered in the triangle array is returned. 2972 \end{methoddesc} 2973 2974 \begin{methoddesc}{\emph{<domain>}.get_wet_elements}{indices=None} 2975 Module: \module{shallow_water.shallow_water_domain} 2976 2977 Returns the indices for elements where h $>$ minimum_allowed_height 2978 2979 \code{indices} is the optional set of element \code{id}s that 2980 the operation applies to. 2981 \end{methoddesc} 2982 2983 \begin{methoddesc}{\emph{<domain>}.get_maximum_inundation_elevation}{indices=None} 2984 Module: \module{shallow_water.shallow_water_domain} 2985 2986 Return highest elevation where h $>$ 0. 2987 2988 \code{indices} is the optional set of element \code{id}s that 2989 the operation applies to. 2990 2991 Example to find maximum runup elevation: 2992 \begin{verbatim} 2993 z = domain.get_maximum_inundation_elevation() 2994 \end{verbatim} 2995 \end{methoddesc} 2996 2997 \begin{methoddesc}{\emph{<domain>}.get_maximum_inundation_location}{indices=None} 2998 Module: \module{shallow_water.shallow_water_domain} 2999 3000 Return location (x,y) of highest elevation where h $>$ 0. 3001 3002 \code{indices} is the optional set of element \code{id}s that 3003 the operation applies to. 3004 3005 Example to find maximum runup location: 3006 \begin{verbatim} 3007 x, y = domain.get_maximum_inundation_location() 3008 \end{verbatim} 3009 \end{methoddesc} 2717 3010 2718 3011 2719 3012 \section{Queries of SWW model output files} 2720 After a model has been run, it is often useful to extract various information from the sww3013 After a model has been run, it is often useful to extract various information from the SWW 2721 3014 output file (see Section \ref{sec:sww format}). This is typically more convenient than using the 2722 3015 diagnostics described in Section \ref{sec:diagnostics} which rely on the model running -- something 2723 that can be very time consuming. The sww files are easy and quick to read and offer muchinformation3016 that can be very time consuming. The SWW files are easy and quick to read and offer information 2724 3017 about the model results such as runup heights, time histories of selected quantities, 2725 3018 flow through cross sections and much more. 2726 3019 2727 \begin{funcdesc}{get\_maximum\_inundation\_elevation}{filename, polygon=None, 2728 time_interval=None, verbose=False} 2729 Module: \module{shallow\_water.data\_manager} 2730 2731 Return highest elevation where depth is positive ($h > 0$) 2732 2733 Example to find maximum runup elevation: 2734 2735 \begin{verbatim} 2736 max_runup = get_maximum_inundation_elevation(filename, 2737 polygon=None, 2738 time_interval=None, 2739 verbose=False) 2740 \end{verbatim} 2741 2742 filename is a NetCDF sww file containing ANUGA model output. 2743 Optional arguments polygon and time_interval restricts the maximum runup calculation 2744 to a points that lie within the specified polygon and time interval. 2745 2746 If no inundation is found within polygon and time_interval the return value 2747 is None signifying "No Runup" or "Everything is dry". 2748 2749 See doc string for general function get_maximum_inundation_data for details. 3020 \begin{funcdesc}{elevation = get_maximum_inundation_elevation}{filename, 3021 polygon=None, 3022 time_interval=None, 3023 verbose=False} 3024 Module: \module{shallow_water.data_manager} 3025 3026 Return the highest elevation where depth is positive ($h > 0$). 3027 3028 \code{filename} is the path to a NetCDF SWW file containing \anuga model output. 3029 3030 \code{polygon} restricts the query to the points that lie within the polygon. 3031 3032 \code {time_interval} restricts the query to within the time interval. 3033 3034 Example to find maximum runup elevation: 3035 3036 \begin{verbatim} 3037 max_runup = get_maximum_inundation_elevation(filename) 3038 \end{verbatim} 3039 3040 If no inundation is found (within the \code{polygon} and \code{time_interval}, if specified) 3041 the return value is \code{None}. This indicates "No Runup" or "Everything is dry". 2750 3042 \end{funcdesc} 2751 3043 2752 \begin{funcdesc}{ get\_maximum\_inundation\_location}{filename, polygon=None,2753 time_interval=None, verbose=False}2754 Module: \module{shallow\_water.data\_manager}2755 2756 Return location (x,y) of highest elevation where depth is positive ($h > 0$) 2757 2758 Example to find maximum runup location: 2759 2760 \begin{verbatim} 2761 max_runup_location = get_maximum_inundation_location(filename, 2762 polygon=None, 2763 time_interval=None, 2764 verbose=False) 2765 \end{verbatim} 2766 2767 \code{filename} is a NetCDF sww file containing ANUGA model output. 2768 Optional arguments \code{polygon} and \code{time_interval} restricts the maximum runup calculation 2769 to a points that lie within the specified polygon and time interval. 2770 2771 If no inundation is found within polygon and time_interval the return value 2772 is None signifying "No Runup" or "Everything is dry". 2773 2774 See the 'doc' string for general function \code{get_maximum_inundation_data} for details.3044 \begin{funcdesc}{(x, y) = get_maximum_inundation_location}{filename, 3045 polygon=None, 3046 time_interval=None, 3047 verbose=False} 3048 Module: \module{shallow_water.data_manager} 3049 3050 Return location (x,y) of the highest elevation where depth is positive ($h > 0$). 3051 3052 \code{filename} is the path to a NetCDF SWW file containing \anuga model output. 3053 3054 \code{polygon} restricts the query to the points that lie within the polygon. 3055 3056 \code {time_interval} restricts the query to within the time interval. 3057 3058 Example to find maximum runup location: 3059 3060 \begin{verbatim} 3061 max_runup_location = get_maximum_inundation_location(filename) 3062 \end{verbatim} 3063 3064 If no inundation is found (within the \code{polygon} and \code{time_interval}, if specified) 3065 the return value is \code{None}. This indicates "No Runup" or "Everything is dry". 3066 is \code{None}. This indicates "No Runup" or "Everything is dry". 2775 3067 \end{funcdesc} 2776 3068 2777 \begin{funcdesc}{sww2timeseries}{swwfiles, gauge_filename, production_dirs, report=None, reportname=None, 2778 plot_quantity=None, generate_fig=False, surface=None, time_min=None, time_max=None, time_thinning=1, 2779 time_unit=None, title_on=None, use_cache=False, verbose=False} 2780 Module: \module{anuga.abstract\_2d\_finite\_volumes.util} 2781 2782 Return csv files for the location in the \code{gauge_filename} and can also return plots of them 2783 2784 See the 'doc' string for general function \code{sww2timeseries} for details. 3069 \begin{funcdesc}{sww2timeseries}{swwfiles, 3070 gauge_filename, 3071 production_dirs, 3072 report=None, 3073 reportname=None, 3074 plot_quantity=None, 3075 generate_fig=False, 3076 surface=None, 3077 time_min=None, 3078 time_max=None, 3079 time_thinning=1, 3080 time_unit=None, 3081 title_on=None, 3082 use_cache=False, 3083 verbose=False} 3084 Module: \module{abstract_2d_finite_volumes.util} 3085 3086 Read a set of SWW files and plot the time series for the prescribed quantities 3087 at defined gauge locations and prescribed time range. 3088 3089 \code{swwfiles} is a dictionary of SWW files with keys of \code{label_id}. 3090 3091 \code{gauge_filename} is the path to a file containing gauge data. 3092 3093 THIS NEEDS MORE WORK. WORK ON FUNCTION __DOC__ STRING, IF NOTHING ELSE! 2785 3094 \end{funcdesc} 2786 3095 2787 \begin{funcdesc}{get\_flow\_through\_cross\_section}{filename, cross\_section, verbose=False} 2788 Module: \module{shallow\_water.data\_manager} 2789 2790 Obtain flow $[m^3/s]$ perpendicular to specified cross section. 2791 2792 Inputs: 2793 \begin{itemize} 2794 \item filename: Name of sww file containing ANUGA model output. 2795 \item polyline: Representation of desired cross section -- it may contain multiple 2796 sections allowing for complex shapes. Assume absolute UTM coordinates. 2797 \end{itemize} 2798 2799 Output: 2800 \begin{itemize} 2801 \item time: All stored times in sww file 2802 \item Q: Hydrograph of total flow across given segments for all stored times. 2803 \end{itemize} 2804 2805 The normal flow is computed for each triangle intersected by the polyline and 2806 added up. Multiple segments at different angles are specified the normal flows 2807 may partially cancel each other. 2808 2809 Example to find flow through cross section: 2810 2811 \begin{verbatim} 3096 \begin{funcdesc}{(time, Q) = get_flow_through_cross_section}{filename, polyline, verbose=False} 3097 Module: \module{shallow_water.data_manager} 3098 3099 Obtain flow ($m^3/s$) perpendicular to specified cross section. 3100 3101 \code{filename} is the path to the SWW file. 3102 3103 \code{polyline} is the representation of the desired cross section -- it may contain 3104 multiple sections allowing for complex shapes. Assumes absolute UTM coordinates. 3105 3106 Returns a tuple \code{time, Q} where: 3107 3108 \code{time} is all the stored times in the SWW file. 3109 3110 \code{Q} is a hydrograph of total flow across the given segments for all stored times. 3111 3112 The normal flow is computed for each triangle intersected by the \code{polyline} and 3113 added up. If multiple segments at different angles are specified the normal flows 3114 may partially cancel each other. 3115 3116 Example to find flow through cross section: 3117 3118 \begin{verbatim} 2812 3119 cross_section = [[x, 0], [x, width]] 2813 time, Q = get_flow_through_cross_section(filename, 2814 cross_section, 2815 verbose=False) 2816 \end{verbatim} 2817 2818 See the 'doc' string for general function \code{get_maximum_inundation_data} for details. 3120 time, Q = get_flow_through_cross_section(filename, cross_section) 3121 \end{verbatim} 2819 3122 \end{funcdesc} 2820 3123 2821 3124 2822 3125 \section{Other} 2823 \begin{funcdesc}{domain.create\_quantity\_from\_expression}{string} 2824 Handy for creating derived quantities on-the-fly as for example: 2825 2826 \begin{verbatim} 3126 \begin{methoddesc}{quantity = \emph{<domain>}.create_quantity_from_expression}{string} 3127 Module: \module{abstract_2d_finite_volumes.domain} 3128 3129 Create a new quantity from other quantities in the domain using an arbitrary expression. 3130 3131 \code{string} is a string containing an arbitrary quantity expression. 3132 3133 Returns the new \code{Quantity} object. 3134 3135 Handy for creating derived quantities on-the-fly: 3136 3137 \begin{verbatim} 2827 3138 Depth = domain.create_quantity_from_expression('stage-elevation') 2828 3139 2829 3140 exp = '(xmomentum*xmomentum + ymomentum*ymomentum)**0.5' 2830 3141 Absolute_momentum = domain.create_quantity_from_expression(exp) 2831 2832 2833 %See also \file{Analytical\_solution\_circular\_hydraulic\_jump.py} for an example of use.2834 \end{ funcdesc}3142 \end{verbatim} 3143 3144 %See also \file{Analytical_solution_circular_hydraulic_jump.py} for an example. 3145 \end{methoddesc} 2835 3146 2836 3147 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% … … 2845 3156 detail in the paragraphs below. 2846 3157 2847 \bigskip2848 3158 \begin{center} 2849 3159 \begin{tabular}{|ll|} \hline … … 2851 3161 \hline\hline 2852 3162 \code{.sww} & NetCDF format for storing model output with mesh information \code{f(t,x,y)}\\ 2853 \code{.sts} & NetCDF format for storing model ouput \code{f(t,x,y)} without anymesh information\\3163 \code{.sts} & NetCDF format for storing model ouput \code{f(t,x,y)} without mesh information\\ 2854 3164 \code{.tms} & NetCDF format for storing time series \code{f(t)}\\ 2855 \code{.csv/.txt} & ASCII format called points csvfor storing arbitrary points and associated attributes\\3165 \code{.csv/.txt} & ASCII format for storing arbitrary points and associated attributes\\ 2856 3166 \code{.pts} & NetCDF format for storing arbitrary points and associated attributes\\ 2857 3167 \code{.asc} & ASCII format of regular DEMs as output from ArcView\\ … … 2863 3173 \code{.nc} & Native ferret NetCDF format\\ 2864 3174 \code{.geo} & Houdinis ASCII geometry format (?) \\ \par \hline 2865 %\caption{File formats used by \anuga}2866 3175 \end{tabular} 2867 3176 \end{center} … … 2870 3179 formats of files. However, typically, in referring to a format we 2871 3180 capitalise the extension and omit the initial full stop -- thus, we 2872 refer , for example, to 'SWW files' or 'PRJfiles'.3181 refer to 'SWW files' or 'PRJ files', not 'sww files' or '.prj files'. 2873 3182 2874 3183 \bigskip 2875 3184 2876 3185 A typical dataflow can be described as follows: 3186 3187 SOMETHING MISSING HERE!? 2877 3188 2878 3189 \subsection{Manually Created Files} … … 2898 3209 \subsection{SWW, STS and TMS Formats} 2899 3210 \label{sec:sww format} 2900 The SWW, STS and TMS formats are all NetCDF formats ,and are of key importance for \anuga.3211 The SWW, STS and TMS formats are all NetCDF formats and are of key importance for \anuga. 2901 3212 2902 3213 An SWW file is used for storing \anuga output and therefore pertains … … 2907 3218 \begin{itemize} 2908 3219 \item \code{x} and \code{y}: coordinates of the points, represented as numeric arrays 2909 \item \code{elevation} ,a numeric array storing bed-elevations2910 \item \code{volumes} ,a list specifying the points at the vertices of each of the triangles3220 \item \code{elevation}: a numeric array storing bed-elevations 3221 \item \code{volumes}: a list specifying the points at the vertices of each of the triangles 2911 3222 % Refer here to the example to be provided in describing the simple example 2912 \item \code{time} ,a numeric array containing times for model evaluation3223 \item \code{time}: a numeric array containing times for model evaluation 2913 3224 \end{itemize} 2914 3225 2915 The contents of an SWW file may be viewed using the anuga viewer 2916 \code{animate}, which creates an on-screen geometric 2917 representation. See section \ref{sec:animate} (page 2918 \pageref{sec:animate}) in Appendix \ref{ch:supportingtools} for more 2919 on \code{animate}. 3226 The contents of an SWW file may be viewed using the anuga viewer \code{animate}, 3227 which creates an on-screen visialisation. See section \ref{sec:animate} 3228 (page \pageref{sec:animate}) in Appendix \ref{ch:supportingtools} for more on \code{animate}. 2920 3229 2921 3230 Alternatively, there are tools, such as \code{ncdump}, that allow 2922 you to convert a nNetCDF file into a readable format such as the3231 you to convert a NetCDF file into a readable format such as the 2923 3232 Class Definition Language (CDL). The following is an excerpt from a 2924 3233 CDL representation of the output file \file{runup.sww} generated 2925 from running the simple example \file{runup.py} of 2926 Chapter \ref{ch:getstarted}: 3234 from running the simple example \file{runup.py} of Chapter \ref{ch:getstarted}: 2927 3235 2928 3236 %FIXME (Ole): Should put in example with nonzero xllcorner, yllcorner … … 2933 3241 \function{file\_function}, described in Chapter \ref{ch:interface}. 2934 3242 2935 An STS file is used for storing a set of points and a nd associated set oftimes.3243 An STS file is used for storing a set of points and associated times. 2936 3244 It contains, in addition to dimension information, the following 2937 3245 variables: 2938 3246 \begin{itemize} 2939 3247 \item \code{x} and \code{y}: coordinates of the points, represented as numeric arrays 2940 \item \code{permutation}: Original indices of the points as specified by the optional \code{ordering \_file}2941 (see the function \code{urs2sts } in Section \ref{sec:basicfileconversions}).3248 \item \code{permutation}: Original indices of the points as specified by the optional \code{ordering_file} 3249 (see the function \code{urs2sts()} in Section \ref{sec:basicfileconversions}) 2942 3250 \item \code{elevation}: a numeric array storing bed-elevations 2943 3251 % Refer here to the example to be provided in describing the simple example … … 2959 3267 two formats: it can be either a TSH file, which is an ASCII file, or 2960 3268 an MSH file, which is a NetCDF file. A mesh file can be generated 2961 from the function \function{create \_mesh\_from\_regions} (see3269 from the function \function{create_mesh_from_regions()} (see 2962 3270 Section \ref{sec:meshgeneration}) and be used to initialise a domain. 2963 3271 … … 2976 3284 2977 3285 A mesh file can also contain a georeference, which describes an 2978 offset to be applied to $x$ and $y$ values -- e.g. \to the vertices.3286 offset to be applied to $x$ and $y$ values -- e.g. to the vertices. 2979 3287 2980 3288 \subsection{Formats for Storing Arbitrary Points and Attributes} … … 2991 3299 2992 3300 \begin{verbatim} 2993 x, y, elevation, friction }2994 0.6, 0.7, 4.9, 0.3 }2995 1.9, 2.8, 5 , 0.3}2996 2.7, 2.4, 5.2, 0.3 }3301 x, y, elevation, friction 3302 0.6, 0.7, 4.9, 0.3 3303 1.9, 2.8, 5.0, 0.3 3304 2.7, 2.4, 5.2, 0.3 2997 3305 \end{verbatim} 2998 3306 2999 3307 The delimiter is a comma. The first two columns are assumed to 3000 be x, ycoordinates.3308 be $x$ and $y$ coordinates. 3001 3309 3002 3310 A PTS file is a NetCDF representation of the data held in an points CSV … … 3038 3346 \label{sec:basicfileconversions} 3039 3347 3040 \begin{funcdesc}{sww2dem}{basename_in, basename_out=None, 3348 \begin{funcdesc}{sww2dem}{(basename_in, 3349 basename_out=None, 3041 3350 quantity=None, 3042 3351 timestep=None, … … 3049 3358 northing_min=None, 3050 3359 northing_max=None, 3051 expand_search=False,3052 3360 verbose=False, 3053 3361 origin=None, 3054 3362 datum='WGS84', 3055 format='ers'} 3056 Module: \module{shallow\_water.data\_manager} 3057 3058 Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or 3059 ERS) of a desired grid size \code{cellsize} in metres. The user can select how 3060 many the decimal places the output data can be written to using \code{number_of_decimal_places}, 3061 with the default being 3. 3062 The easting and northing values are used if the user wished to determine the output 3063 within a specified rectangular area. The \code{reduction} input refers to a function 3064 to reduce the quantities over all time step of the SWW file, example, maximum. 3363 format='ers', 3364 block_size=None} 3365 Module: \module{shallow_water.data_manager} 3366 3367 Takes data from an SWW file \code{basename_in} and converts it to DEM format (ASC or 3368 ERS) of a desired grid size \code{cellsize} in metres. The user can select how 3369 many decimal places the output data is represented with by using \code{number_of_decimal_places}, 3370 with the default being 3. 3371 3372 The $easting$ and $northing$ values are used if the user wishes to determine the output 3373 within a specified rectangular area. The \code{reduction} input refers to a function 3374 to reduce the quantities over all time step of the SWW file, e.g. maximum. 3065 3375 \end{funcdesc} 3066 3376 … … 3302 3612 $z$ the bed elevation. The latter are assumed to be relative to the 3303 3613 same height datum. 3304 The conserved quantities tracked by ANUGAare momentum in the3614 The conserved quantities tracked by \anuga are momentum in the 3305 3615 $x$-direction ($\mu = uh$), momentum in the $y$-direction ($\nu = vh$) 3306 3616 and depth ($h = w-z$). … … 3338 3648 \] 3339 3649 3340 ANUGAhas a global parameter $H_0$ that controls the minimal depth which3650 \anuga has a global parameter $H_0$ that controls the minimal depth which 3341 3651 is considered in the various equations. This parameter is typically set to 3342 3652 $10^{-3}$. Setting … … 3352 3662 \] 3353 3663 In general, for multiples of the minimal depth $N H_0$ one obtains 3354 \ begin{equation}3664 \[ 3355 3665 \left[ \frac{\mu}{h + h_0/h} \right]_{h = N H_0} = 3356 \frac{\mu}{N H_0 + H_0/N} = 3357 \frac{\mu}{h (1 + 1/N^2)} 3358 \label{eq:flux limit multiple} 3359 \end{equation} 3666 \frac{\mu}{H_0 (1 + 1/N^2)} 3667 \] 3360 3668 which converges quadratically to the true value with the multiple N. 3361 3362 Although this equation can be used for any depth, we have restricted its use to depths less than $10 * H_0$ (or 1 cm) to computational resources.3363 According to Equation \ref{eq:flux limit multiple} this cutoff3364 affects the calculated velocity by less than 1 \%.3365 3669 3366 3670 %The developed numerical model has been applied to several test cases … … 3485 3789 using some relative time (e.g. 0). 3486 3790 3487 The ANUGAdomain has an attribute \code{starttime} which is used in cases where the3791 The \anuga domain has an attribute \code{starttime} which is used in cases where the 3488 3792 simulation should be started later than the beginning of some input data such as those 3489 obtained from boundaries or forcing functions (hydrographs, file \_boundary etc).3793 obtained from boundaries or forcing functions (hydrographs, file_boundary etc). 3490 3794 3491 3795 The \code{domain.startime} may be adjusted in \code{file_boundary} in the case the … … 3501 3805 All locations must consequently be specified in Cartesian coordinates 3502 3806 (eastings, northings) or (x,y) where the unit is metres. 3503 Alternative projections can be assumed, but ANUGAdoes have the concept of a UTM zone3807 Alternative projections can be used, but \anuga does have the concept of a UTM zone 3504 3808 that must be the same for all coordinates in the model. 3505 3809 3506 3810 \subsection{Internal coordinates} 3507 It is important to realise that ANUGA for numerical precisionuses coordinates that are relative3811 It is important to realise that for numerical precision \anuga uses coordinates that are relative 3508 3812 to the lower left node of the rectangle containing the mesh ($x_{\mbox{min}}$, $y_{\mbox{min}}$). 3509 3813 This origin is referred to internally as \code{xllcorner}, \code{yllcorner} following the ESRI ASCII grid notation. 3510 The swwfile format also includes \code{xllcorner}, \code{yllcorner} and any coordinate in the file should be adjusted3814 The SWW file format also includes \code{xllcorner}, \code{yllcorner} and any coordinate in the file should be adjusted 3511 3815 by adding this origin. See Section \ref{sec:sww format}. 3512 3816 3513 Throughout the ANUGAinterface, functions have optional boolean arguments \code{absolute} which controls3817 Throughout the \anuga interface, functions have optional boolean arguments \code{absolute} which controls 3514 3818 whether spatial data received is using the internal representation (\code{absolute=False}) or the 3515 user coordinate set (\code{absolute=True}). See e.g. \code{get_vertex_coordinates } on \pageref{pg:get vertex coordinates}.3516 3517 DEMs, meshes and boundary conditions can have different origins. However, the internal representation in ANUGA3819 user coordinate set (\code{absolute=True}). See e.g. \code{get_vertex_coordinates()} on \pageref{pg:get vertex coordinates}. 3820 3821 DEMs, meshes and boundary conditions can have different origins. However, the internal representation in \anuga 3518 3822 will use the origin of the mesh. 3519 3823 … … 3546 3850 % native dem and pts formats% 3547 3851 % 3548 % prepare_pts.py: Convert netcdf output from MOST to an swwfile suitable3852 % prepare_pts.py: Convert netcdf output from MOST to an SWW file suitable 3549 3853 % as boundary condition% 3550 3854 % … … 3596 3900 3597 3901 If the function definition changes after a result has been cached, this will be 3598 detected by examining the functions \code{bytecode (co\_code, co\_consts, 3599 func\_defaults, co\_argcount)} and the function will be recomputed. 3902 detected by examining the functions bytecode and the function will be recomputed. 3600 3903 However, caching will not detect changes in modules used by \code{func}. 3601 In this case cache must be cleared manually.3602 3603 Options are set by means of the function \code{set \_option(key, value)},3904 In this case the cache must be cleared manually. 3905 3906 Options are set by means of the function \code{set_option(key, value)}, 3604 3907 where \code{key} is a key associated with a 3605 3908 Python dictionary \code{options}. This dictionary stores settings such as the name of … … 3611 3914 %Other features include support for compression and a capability to \ldots 3612 3915 3613 \textbf{USAGE:}\nopagebreak3916 USAGE: \nopagebreak 3614 3917 3615 3918 \begin{verbatim} … … 3619 3922 3620 3923 3621 \section{ANUGA viewer -- animate} 3924 \pagebreak 3925 \section{\anuga viewer -- animate} 3622 3926 \label{sec:animate} 3623 3927 3624 3928 The output generated by \anuga may be viewed by 3625 means of the visualisation tool \code{animate}, which takes the3626 \code{SWW}file generated by \anuga and creates a visual representation3929 means of the visualisation tool \code{animate}, which takes an 3930 SWW file generated by \anuga and creates a visual representation 3627 3931 of the data. Examples may be seen in Figures \ref{fig:runupstart} 3628 and \ref{fig:runup2}. To view an \code{SWW}file with3932 and \ref{fig:runup2}. To view an SWW file with 3629 3933 \code{animate} in the Windows environment, you can simply drag the 3630 3934 icon representing the file over an icon on the desktop for the … … 3635 3939 3636 3940 Upon starting the viewer, you will see an interactive moving-picture 3637 display. You can use the keyboard and themouse to slow down, speed up or3941 display. You can use the keyboard and mouse to slow down, speed up or 3638 3942 stop the display, change the viewing position or carry out a number 3639 3943 of other simple operations. Help is also displayed when you press … … 3657 3961 % \vfill 3658 3962 3659 The following tabledescribes how to operate \code{animate} from the command line:3660 3661 Usage: \code{animate [options] swwfile \ldots}\\ 3662 Options:\\\nopagebreak3963 The following describes how to operate \code{animate} from the command line: 3964 3965 Usage: \code{animate [options] swwfile \ldots}\\ \nopagebreak 3966 where: \\ \nopagebreak 3663 3967 \begin{tabular}{ll} 3664 3968 \code{--display <type>} & \code{MONITOR | POWERWALL | REALITY\_CENTER |}\\ … … 3673 3977 \code{-alphamax <float 0-1>} & Maximum transparency clamp value\\ 3674 3978 \code{-alphamin <float 0-1>} & Transparency value at \code{hmin}\\ 3675 \end{tabular}3676 3677 \begin{tabular}{ll}3678 3979 \code{-cullangle <float angle 0-90>} & Cull triangles steeper than this value\\ 3679 3980 \code{-help} & Display this information\\ 3680 3981 \code{-hmax <float>} & Height above which transparency is set to 3681 3982 \code{alphamax}\\ 3682 \end{tabular}3683 3684 \begin{tabular}{ll}3685 3983 \code{-hmin <float>} & Height below which transparency is set to 3686 3984 zero\\ 3687 \end{tabular}3688 3689 \begin{tabular}{ll}3690 3985 \code{-lightpos <float>,<float>,<float>} & $x,y,z$ of bedslope directional light ($z$ is 3691 3986 up, default is overhead)\\ 3692 \end{tabular}3693 3694 \begin{tabular}{ll}3695 3987 \code{-loop} & Repeated (looped) playback of \code{.swm} files\\ 3696 \end{tabular}3697 3698 \begin{tabular}{ll}3699 3988 \code{-movie <dirname>} & Save numbered images to named directory and 3700 3989 quit\\ … … 3714 4003 \refmodindex{utilities.polygon} 3715 4004 3716 \begin{classdesc}{Polygon\_function}{regions, default=0.0, geo_reference=None} 3717 Module: \code{utilities.polygon} 3718 3719 Creates a callable object that returns one of a specified list of values when 3720 evaluated at a point \code{x, y}, depending on which polygon, from a specified list of polygons, the 3721 point belongs to. The parameter \code{regions} is a list of pairs 3722 \code{(P, v)}, where each \code{P} is a polygon and each \code{v} 3723 is either a constant value or a function of coordinates \code{x} 3724 and \code{y}, specifying the return value for a point inside \code{P}. The 3725 optional parameter \code{default} may be used to specify a value 3726 (or a function) 3727 for a point not lying inside any of the specified polygons. When a 3728 point lies in more than one polygon, the return value is taken to 3729 be the value for whichever of these polygon appears later in the 3730 list. 3731 %FIXME (Howard): CAN x, y BE VECTORS? 3732 The optional parameter geo\_reference refers to the status of points 3733 that are passed into the function. Typically they will be relative to 3734 some origin. In ANUGA, a typical call will take the form: 3735 3736 \begin{verbatim} 4005 \begin{classdesc}{<callable> = Polygon_function}{regions, 4006 default=0.0, 4007 geo_reference=None} 4008 Module: \code{utilities.polygon} 4009 4010 Creates a callable object that returns one of a specified list of values when 4011 evaluated at a point \code{(x, y)}, depending on which polygon, from a specified list of polygons, the 4012 point belongs to. 4013 4014 \code{regions} is a list of pairs 4015 \code{(P, v)}, where each \code{P} is a polygon and each \code{v} 4016 is either a constant value or a function of coordinates \code{x} 4017 and \code{y}, specifying the return value for a point inside \code{P}. 4018 4019 \code{default} may be used to specify a value (or a function) 4020 for a point not lying inside any of the specified polygons. 4021 4022 When a point lies in more than one polygon, the return value is taken to 4023 be the value for whichever of these polygon appears later in the list. 4024 4025 %FIXME (Howard): CAN x, y BE VECTORS? 4026 4027 \code{geo_reference} refers to the status of points 4028 that are passed into the function. Typically they will be relative to 4029 some origin. 4030 4031 Typical usage may take the form: 4032 4033 \begin{verbatim} 3737 4034 set_quantity('elevation', 3738 4035 Polygon_function([(P1, v1), (P2, v2)], 3739 4036 default=v3, 3740 4037 geo_reference=domain.geo_reference)) 3741 4038 \end{verbatim} 3742 4039 \end{classdesc} 3743 4040 3744 \begin{funcdesc}{read\_polygon}{filename} 3745 Module: \code{utilities.polygon} 3746 3747 Reads the specified file and returns a polygon. Each 3748 line of the file must contain exactly two numbers, separated by a comma, which are interpreted 3749 as coordinates of one vertex of the polygon. 4041 \begin{funcdesc}{<polygon> = read_polygon}{filename, split=','} 4042 Module: \code{utilities.polygon} 4043 4044 Reads the specified file and returns a polygon. 4045 Each line of the file must contain exactly two numbers, separated by a delimiter, which are interpreted 4046 as coordinates of one vertex of the polygon. 4047 4048 \code{filename} is the path to the file to read. 4049 4050 \code{split} sets the delimiter character between the numbers on one line of 4051 the file. If not specified, the delimiter is the ',' character. 3750 4052 \end{funcdesc} 3751 4053 3752 \begin{funcdesc}{populate\_polygon}{polygon, number_of_points, seed = None, exclude = None} 3753 Module: \code{utilities.polygon} 3754 3755 Populates the interior of the specified polygon with the specified number of points, 3756 selected by means of a uniform distribution function. 4054 \label{ref:function_populate_polygon} 4055 \begin{funcdesc}{populate_polygon}{polygon, number_of_points, seed=None, exclude=None} 4056 Module: \code{utilities.polygon} 4057 4058 Populates the interior of the specified polygon with the specified number of points, 4059 selected by means of a uniform distribution function. 4060 4061 \code{polygon} is the polygon to populate. 4062 4063 \code{number_of_points} is the (optional) number of points. 4064 4065 \code{seed}is the optional seed for random number generator. 4066 4067 \code{exclude} is a list of polygons (inside main polygon) from where points should be excluded. 3757 4068 \end{funcdesc} 3758 4069 3759 \begin{funcdesc}{point\_in\_polygon}{polygon, delta=1e-8} 3760 Module: \code{utilities.polygon} 3761 3762 Returns a point inside the specified polygon and close to the edge. The distance between 3763 the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the 3764 second argument \code{delta}, which is taken as $10^{-8}$ by default. 4070 \label{ref:function_point_in_polygon} 4071 \begin{funcdesc}{<point> = point_in_polygon}{polygon, delta=1e-8} 4072 Module: \code{utilities.polygon} 4073 4074 Returns a point inside the specified polygon and close to the edge. The distance between 4075 the returned point and the nearest point of the polygon is less than $\sqrt{2}$ times the 4076 second argument \code{delta}, which is taken as $10^{-8}$ by default. 3765 4077 \end{funcdesc} 3766 4078 3767 \begin{funcdesc}{inside\_polygon}{points, polygon, closed = True, verbose = False} 3768 Module: \code{utilities.polygon} 3769 3770 Used to test whether the members of a list of points 3771 are inside the specified polygon. Returns a numeric 3772 array comprising the indices of the points in the list that lie inside the polygon. 3773 (If none of the points are inside, returns \code{zeros((0,), 'l')}.) 3774 Points on the edges of the polygon are regarded as inside if 3775 \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside. 4079 \label{ref:function_inside_polygon} 4080 \begin{funcdesc}{<array> = inside_polygon}{points, polygon, closed=True, verbose=False} 4081 Module: \code{utilities.polygon} 4082 4083 Get a set of points that lie inside a given polygon. 4084 4085 \code{points} is the list of points to test. 4086 4087 \code{polygon} is the polygon to test the points against. 4088 4089 \code{closed} specifies if points on the polygon edge are considered to be inside 4090 or outside the polygon -- \code{True} means they are inside. 4091 4092 Returns a numeric array comprising the indices of the points in the list 4093 that lie inside the polygon. If none of the points are inside, returns 4094 \code{zeros((0,), 'l') (ie, an empty numeric array)}. 4095 4096 Compare with \code{outside_polygon()}, page \pageref{ref:function_outside_polygon}. 3776 4097 \end{funcdesc} 3777 4098 3778 \begin{funcdesc}{outside\_polygon}{points, polygon, closed = True, verbose = False} 3779 Module: \code{utilities.polygon} 3780 3781 Exactly like \code{inside\_polygon}, but with the words 'inside' and 'outside' interchanged. 4099 \label{ref:function_outside_polygon} 4100 \begin{funcdesc}{<array> = outside_polygon}{points, polygon, closed=True, verbose=False} 4101 Module: \code{utilities.polygon} 4102 4103 Get a set of points that lie outside a given polygon. 4104 4105 \code{points} is the list of points to test. 4106 4107 \code{polygon} is the polygon to test the points against. 4108 4109 \code{closed} specifies if points on the polygon edge are considered to be outside 4110 or inside the polygon -- \code{True} means they are outside. 4111 4112 Returns a numeric array comprising the indices of the points in the list 4113 that lie outside the polygon. If none of the points are outside, returns 4114 \code{zeros((0,), 'l')} (ie, an empty numeric array). 4115 4116 Compare with \code{inside_polygon()}, page \pageref{ref:function_inside_polygon}. 3782 4117 \end{funcdesc} 3783 4118 3784 \begin{funcdesc}{is\_inside\_polygon}{point, polygon, closed=True, verbose=False} 3785 Module: \code{utilities.polygon} 3786 3787 Returns \code{True} if \code{point} is inside \code{polygon} or 3788 \code{False} otherwise. Points on the edges of the polygon are regarded as inside if 3789 \code{closed} is set to \code{True} or omitted; otherwise they are regarded as outside. 4119 \label{ref:function_is_inside_polygon} 4120 \begin{funcdesc}{<boolean> = is_inside_polygon}{point, polygon, closed=True, verbose=False} 4121 Module: \code{utilities.polygon} 4122 4123 Determines if a single point is inside a polygon. 4124 4125 \code{point} is the point to test. 4126 4127 \code{polygon} is the polygon to test \code{point} against. 4128 4129 \code{closed} is a flag that forces the function to consider a point on the polygon 4130 edge to be inside or outside -- if \code{True} a point on the edge is considered inside the 4131 polygon. 4132 4133 Returns \code{True} if \code{point} is inside \code{polygon}. 4134 4135 Compare with \code{inside_polygon()}, page \pageref{ref:function_inside_polygon}. 3790 4136 \end{funcdesc} 3791 4137 3792 \begin{funcdesc}{is\_outside\_polygon}{point, polygon, closed=True, verbose=False} 3793 Module: \code{utilities.polygon} 3794 3795 Exactly like \code{is\_outside\_polygon}, but with the words 'inside' and 'outside' interchanged. 4138 \label{ref:function_is_outside_polygon} 4139 \begin{funcdesc}{<boolean> = is_outside_polygon}{point, polygon, closed=True, verbose=False, 4140 % points_geo_ref=None, polygon_geo_ref=None 4141 } 4142 Module: \code{utilities.polygon} 4143 4144 Determines if a single point is outside a polygon. 4145 4146 \code{point} is the point to test. 4147 4148 \code{polygon} is the polygon to test \code{point} against. 4149 4150 \code{closed} is a flag that forces the function to consider a point on the polygon 4151 edge to be outside or inside -- if \code{True} a point on the edge is considered inside the 4152 polygon. 4153 4154 %\code{points_geo_ref} is ?? 4155 % 4156 %\code{polygon_geo_ref} is ?? 4157 4158 Compare with \code{outside_polygon()}, page \pageref{ref:function_outside_polygon}. 3796 4159 \end{funcdesc} 3797 4160 3798 \begin{funcdesc}{point\_on\_line}{x, y, x0, y0, x1, y1} 3799 Module: \code{utilities.polygon} 3800 3801 Returns \code{True} or \code{False}, depending on whether the point with coordinates 3802 \code{x, y} is on the line passing through the points with coordinates \code{x0, y0} 3803 and \code{x1, y1} (extended if necessary at either end). 4161 \label{ref:function_point_on_line} 4162 \begin{funcdesc}{<boolean> = point_on_line}{point, line, rtol=1.0e-5, atol=1.0e-8} 4163 Module: \code{utilities.polygon} 4164 4165 Determine if a point is on a line to some tolerance. The line is considered to 4166 extend past its end-points. 4167 4168 \code{point} is the point to test ([$x$, $y$]). 4169 4170 \code{line} is the line to test \code{point} against ([[$x1$,$y1$], [$x2$,$y2$]]). 4171 4172 \code{rtol} is the relative tolerance to use when testing for coincidence. 4173 4174 \code{atol} is the absolute tolerance to use when testing for coincidence. 4175 4176 Returns \code{True} if the point is on the line, else \code{False}. 3804 4177 \end{funcdesc} 3805 4178 3806 \begin{funcdesc}{separate\_points\_by\_polygon}{points, polygon, closed = True, verbose = False} 3807 \indexedcode{separate\_points\_by\_polygon} 3808 Module: \code{utilities.polygon} 3809 4179 \label{ref:function_separate_points_by_polygon} 4180 \begin{funcdesc}{(indices, count) = separate_points_by_polygon}{points, polygon, 4181 closed=True, 4182 check_input=True, 4183 verbose=False} 4184 \indexedcode{separate_points_by_polygon} 4185 Module: \code{utilities.polygon} 4186 4187 Separate a set of points into points that are inside and outside a polygon. 4188 4189 \code{points} is a list of points to separate. 4190 4191 \code{polygon} is the polygon used to separate the points. 4192 4193 \code{closed} determines whether points on the polygon edge should be 4194 regarded as inside or outside the polygon. \code{True} means they are inside. 4195 4196 \code{check_input} specifies whether the input parameters are checked -- \code{True} 4197 means check the input parameters. 4198 4199 The function returns a tuple \code{(indices, count)} where \code{indices} is a list of 4200 point $indices$ from the input \code{points} list, with the indices of points inside the 4201 polygon at the left and indices of points outside the polygon listed at the right. The 4202 \code{count} value is the count (from the left) of the indices of the points $inside$ the 4203 polygon. 3810 4204 \end{funcdesc} 3811 4205 3812 \begin{funcdesc}{ polygon\_area}{polygon}3813 3814 3815 Returns area of arbitrary polygon (reference http://mathworld.wolfram.com/PolygonArea.html) 4206 \begin{funcdesc}{<area> = polygon_area}{polygon} 4207 Module: \code{utilities.polygon} 4208 4209 Returns area of an arbitrary polygon (reference http://mathworld.wolfram.com/PolygonArea.html). 3816 4210 \end{funcdesc} 3817 4211 3818 \begin{funcdesc}{plot\_polygons}{polygons, style, figname, verbose = False} 3819 Module: \code{utilities.polygon} 3820 3821 Plots each polygon contained in input polygon list, e.g. 3822 \code{polygons = [poly1, poly2, poly3]} where \code{poly1 = [[x11,y11],[x12,y12],[x13,y13]]} 3823 etc. Each polygon can be closed for plotting purposes by assigning the style type to each 3824 polygon in the list, e.g. \code{style = ['line','line','line']}. The default will be a line 3825 type when \code{style = None}. 3826 The subsequent plot will be saved to \code{figname} or defaulted to \code{test_image.png}. 3827 The function returns a list containing the minimum and maximum of \code{x} and \code{y}, 3828 i.e. \code{[x_{min}, x_{max}, y_{min}, y_{max}]}. 4212 \begin{funcdesc}{[$x_{min}$, $x_{max}$, $y_{min}$, $y_{max}$] = plot_polygons} 4213 {polygons_points, style=None, 4214 figname=None, label=None, verbose=False} 4215 Module: \code{utilities.polygon} 4216 4217 Plot a list of polygons to a file. 4218 4219 \code{polygons_points} is a list of polygons to plot. 4220 4221 \code{style} is a list of style strings to be applied to the corresponding polygon 4222 in \code{polygons_points}. A polygon can be closed for plotting purposes by assigning 4223 the style string 'line' to it in the appropriate place in the \code{style} list. 4224 The default style is 'line'. 4225 4226 \code{figname} is the path to the file to save the plot in. If not specified, use 4227 \file{test_image.png}. 4228 4229 The function returns a list containing the minimum and maximum of the points in all the 4230 input polygons, i.e. \code{[$x_{min}$, $x_{max}$, $y_{min}$, $y_{max}$]}. 3829 4231 \end{funcdesc} 3830 4232 3831 4233 3832 \section{coordinate\_transforms} 3833 3834 3835 \section{geospatial\_data} 4234 \pagebreak 4235 \section{coordinate_transforms} 4236 4237 4238 \pagebreak 4239 \section{geospatial_data} 3836 4240 \label{sec:geospatial} 3837 4241 … … 3843 4247 %\refmodindex{geospatial_data} 3844 4248 3845 \begin{classdesc}{Geospatial\_data} 3846 {data_points=None, 3847 attributes=None, 3848 geo_reference=None, 3849 default_attribute_name=None, 3850 file_name=None} 3851 Module: \code{geospatial\_data} 3852 3853 This class is used to store a set of data points and associated 3854 attributes, allowing these to be manipulated by methods defined for 3855 the class. 3856 3857 The data points are specified either by reading them from a NetCDF 3858 or CSV file, identified through the parameter \code{file\_name}, or 3859 by providing their \code{x}- and \code{y}-coordinates in metres, 3860 either as a sequence of 2-tuples of floats or as an $M \times 2$ 3861 numeric array of floats, where $M$ is the number of points. 3862 Coordinates are interpreted relative to the origin specified by the 3863 object \code{geo\_reference}, which contains data indicating the UTM 3864 zone, easting and northing. If \code{geo\_reference} is not 3865 specified, a default is used. 3866 3867 Attributes are specified through the parameter \code{attributes}, 3868 set either to a list or array of length $M$ or to a dictionary whose 3869 keys are the attribute names and whose values are lists or arrays of 3870 length $M$. One of the attributes may be specified as the default 3871 attribute, by assigning its name to \code{default\_attribute\_name}. 3872 If no value is specified, the default attribute is taken to be the 3873 first one. 3874 3875 Note that the Geospatial\_data object currently reads entire datasets 3876 into memory i.e.\ no memomry blocking takes place. 3877 For this we refer to the set\_quantity method which will read .pts and .csv 3878 files into \anuga using memory blocking allowing large files to be used. 4249 \begin{classdesc}{Geospatial_data} 4250 {data_points=None, 4251 attributes=None, 4252 geo_reference=None, 4253 default_attribute_name=None, 4254 file_name=None, 4255 latitudes=None, 4256 longitudes=None, 4257 points_are_lats_longs=False, 4258 max_read_lines=None, 4259 load_file_now=True, 4260 verbose=False} 4261 Module: \code{geospatial_data.geospatial_data} 4262 4263 This class is used to store a set of data points and associated 4264 attributes, allowing these to be manipulated by methods defined for 4265 the class. 4266 4267 The data points are specified either by reading them from a NetCDF 4268 or CSV file, identified through the parameter \code{file_name}, or 4269 by providing their \code{x}- and \code{y}-coordinates in metres, 4270 either as a sequence of 2-tuples of floats or as an $M \times 2$ 4271 numeric array of floats, where $M$ is the number of points. 4272 4273 Coordinates are interpreted relative to the origin specified by the 4274 object \code{geo_reference}, which contains data indicating the UTM 4275 zone, easting and northing. If \code{geo_reference} is not 4276 specified, a default is used. 4277 4278 Attributes are specified through the parameter \code{attributes}, 4279 set either to a list or array of length $M$ or to a dictionary whose 4280 keys are the attribute names and whose values are lists or arrays of 4281 length $M$. One of the attributes may be specified as the default 4282 attribute, by assigning its name to \code{default_attribute_name}. 4283 If no value is specified, the default attribute is taken to be the 4284 first one. 4285 4286 Note that the \code{Geospatial_data} object currently reads entire datasets 4287 into memory i.e. no memomry blocking takes place. 4288 For this we refer to the \code{set_quantity()} method which will read PTS and CSV 4289 files into \anuga using memory blocking allowing large files to be used. 3879 4290 \end{classdesc} 3880 4291 3881 \begin{methoddesc}{import\_points\_file}{delimiter=None, verbose=False} 3882 3883 \end{methoddesc} 3884 3885 \begin{methoddesc}{export\_points\_file}{ofile, absolute=False} 3886 3887 \end{methoddesc} 3888 3889 \begin{methoddesc}{get\_data\_points}{absolute=True, as\_lat\_long=False} 3890 If \code{as\_lat\_long} is\code{True} the point information 3891 returned will be in Latitudes and Longitudes. 3892 \end{methoddesc} 3893 3894 \begin{methoddesc}{set\_attributes}{attributes} 3895 3896 \end{methoddesc} 3897 3898 \begin{methoddesc}{get\_attributes}{attribute_name=None} 3899 3900 \end{methoddesc} 3901 3902 \begin{methoddesc}{get\_all\_attributes}{} 3903 3904 \end{methoddesc} 3905 3906 \begin{methoddesc}{set\_default\_attribute\_name}{default_attribute_name} 3907 3908 \end{methoddesc} 3909 3910 \begin{methoddesc}{set\_geo\_reference}{geo_reference} 3911 3912 \end{methoddesc} 3913 3914 \begin{methoddesc}{add}{} 3915 3916 \end{methoddesc} 3917 3918 \begin{methoddesc}{clip}{} 3919 Clip geospatial data by a polygon 3920 3921 Inputs are \code{polygon} which is either a list of points, an Nx2 array or 3922 a Geospatial data object and \code{closed}(optional) which determines 3923 whether points on boundary should be regarded as belonging to the polygon 3924 (\code{closed=True}) or not (\code{closed=False}). 3925 Default is \code{closed=True}. 3926 3927 Returns new Geospatial data object representing points inside specified polygon. 3928 \end{methoddesc} 3929 3930 \begin{methoddesc}{clip_outside}{} 3931 Clip geospatial data by a polygon 3932 3933 Inputs are \code{polygon} which is either a list of points, an Nx2 array or 3934 a Geospatial data object and \code{closed}(optional) which determines 3935 whether points on boundary should be regarded as belonging to the polygon 3936 (\code{closed=True}) or not (\code{closed=False}). 3937 Default is \code{closed=True}. 3938 3939 Returns new Geospatial data object representing points \emph{out}side specified polygon. 3940 \end{methoddesc} 3941 3942 \begin{methoddesc}{split}{factor=0.5, seed_num=None, verbose=False} 3943 Returns two geospatial_data object, first is the size of the 'factor' 3944 smaller the original and the second is the remainder. The two 3945 new object are disjoin set of each other. 3946 3947 Points of the two new geospatial_data object are selected RANDOMLY. 3948 3949 Input -- the (\code{factor}) which to split the object, if 0.1 then 10% of the 3950 together object will be returned 3951 3952 Output -- two geospatial_data objects that are disjoint sets of the original 3953 \end{methoddesc} 3954 3955 \begin{methoddesc}{find_optimal_smoothing_parameter}{data_file, alpha_list=None, 3956 mesh_file=None, boundary_poly=None, mesh_resolution=100000, 3957 north_boundary=None, south_boundary=None, east_boundary=None, 3958 west_boundary=None, plot_name='all_alphas', split_factor=0.1, 3959 seed_num=None, cache=False, verbose=False} 3960 Removes a small random sample of points from 'data_file'. Creates 3961 models from resulting points in 'data_file' with different alpha values from 'alpha_list' and cross validates 3962 the predicted value to the previously removed point data. Returns the 3963 alpha value which has the smallest covariance. 3964 3965 data_file: must not contain points outside the boundaries defined 3966 and it either a pts, txt or csv file. 3967 3968 alpha_list: the alpha values to test in a single list 3969 3970 mesh_file: name of the created mesh file or if passed in will read it. 3971 NOTE, if there is a mesh file mesh_resolution, north_boundary, south... etc will be ignored. 3972 3973 mesh_resolution: the maximum area size for a triangle 3974 3975 north_boundary... west_boundary: the value of the boundary 3976 3977 plot_name: the name for the plot contain the results 3978 3979 seed_num: the seed to the random number generator 3980 3981 USAGE: 3982 convariance_value, alpha = find_optimal_smoothing_parameter(data_file=fileName, 3983 alpha_list=[0.0001, 0.01, 1], 3984 mesh_file=None, 3985 mesh_resolution=3, 3986 north_boundary=5, 3987 south_boundary=-5, 3988 east_boundary=5, 3989 west_boundary=-5, 3990 plot_name='all_alphas', 3991 seed_num=100000, 3992 verbose=False) 3993 3994 OUTPUT: returns the minumum normalised covalance calculate AND the 3995 alpha that created it. PLUS writes a plot of the results 3996 3997 NOTE: code will not work if the data_file extent is greater than the 3998 boundary_polygon or any of the boundaries, eg north_boundary...west_boundary 3999 \end{methoddesc} 4000 4001 4292 \begin{methoddesc}{\emph{<Geospatial_data>}.import_points_file} 4293 {file_name, delimiter=None, verbose=False} 4294 Module: \code{geospatial_data.geospatial_data} 4295 4296 Import a TXT, CSV or PTS points data file into a code{Geospatial_data} object. 4297 4298 \code{file_name} is the path to a TXT, CSV or PTS points data file. 4299 4300 \code{delimiter} is currently unused. 4301 \end{methoddesc} 4302 4303 \begin{methoddesc}{\emph{<Geospatial_data>}.export_points_file}{file_name, absolute=True, 4304 as_lat_long=False, isSouthHemisphere=True} 4305 Module: \code{geospatial_data.geospatial_data} 4306 4307 Export a CSV or PTS points data file from a \code{Geospatial_data} object. 4308 4309 \code{file_name} is the path to the CSV or PTS points file to write. 4310 4311 \code{absolute} determines if the exported data is absolute or relative to the 4312 \code{Geospatial_data} object geo_reference. If \code{True} the exported 4313 data is absolute. 4314 4315 \code{as_lat_long} exports the points data as latitudes and longitudes if \code{True}. 4316 4317 \code{isSouthHemisphere} has effect only if \code{as_lat_long} is \code{True} and causes 4318 latitude/longitude values to be for the southern (\code{True}) or northern hemispheres 4319 (\code{False}). 4320 \end{methoddesc} 4321 4322 \begin{methoddesc}{points = \emph{<Geospatial_data>}.get_data_points} 4323 {absolute=True, geo_reference=None, 4324 as_lat_long=False, isSouthHemisphere=True} 4325 Module: \code{geospatial_data.geospatial_data} 4326 4327 Get the coordinates for all the data points as an $N \times 2$ array. 4328 4329 \code{absolute} determines if the exported data is absolute or relative to the 4330 \code{Geospatial_data} object geo_reference. If \code{True} the exported 4331 data is absolute. 4332 4333 \code{geo_reference} is the geo_reference the points are relative to, if supplied. 4334 4335 \code{as_lat_long} exports the points data as latitudes and longitudes if \code{True}. 4336 4337 \code{isSouthHemisphere} has effect only if \code{as_lat_long} is \code{True} and causes 4338 latitude/longitude values to be for the southern (\code{True}) or northern hemispheres 4339 (\code{False}). 4340 \end{methoddesc} 4341 4342 \begin{methoddesc}{\emph{<Geospatial_data>}.set_attributes}{attributes} 4343 Module: \code{geospatial_data.geospatial_data} 4344 4345 Set the attributes for a \code{Geospatial_data} object. 4346 4347 \code{attributes} is the new value for the object's attributes. May be a dictionary or \code{None}. 4348 \end{methoddesc} 4349 4350 \begin{methoddesc}{atributes = \emph{<Geospatial_data>}.get_attributes}{attribute_name=None} 4351 Module: \code{geospatial_data.geospatial_data} 4352 4353 Get a named attribute from a \code{Geospatial_data} object. 4354 4355 \code{attribute_name} is the name of the desired attribute. If \code{None}, return 4356 the default attribute. 4357 \end{methoddesc} 4358 4359 \begin{methoddesc}{\emph{<Geospatial_data>}.get_all_attributes}{} 4360 Module: \code{geospatial_data.geospatial_data} 4361 4362 Get all attributes of a \code{Geospatial_data} object. 4363 4364 Returns \code{None} or the attributes dictionary (which may be empty). 4365 \end{methoddesc} 4366 4367 \begin{methoddesc}{\emph{<Geospatial_data>}.set_default_attribute_name}{default_attribute_name} 4368 Module: \code{geospatial_data.geospatial_data} 4369 4370 Set the default attribute name of a \code{Geospatial_data} object. 4371 4372 \code{default_attribute_name} is the new default attribute name. 4373 \end{methoddesc} 4374 4375 \begin{methoddesc}{\emph{<Geospatial_data>}.set_geo_reference}{geo_reference} 4376 Module: \code{geospatial_data.geospatial_data} 4377 4378 Set the internal geo_reference of a \code{Geospatial_data} object. 4379 4380 \code{geo_reference} is the new internal geo_reference for the object. 4381 If \code{None} will use the default geo_reference. 4382 4383 If the \code{Geospatial_data} object already has an internal geo_reference 4384 then the points data will be changed to use the new geo_reference. 4385 \end{methoddesc} 4386 4387 \begin{methoddesc}{\emph{<Geospatial_data>}.__add__}{other} 4388 Module: \code{geospatial_data.geospatial_data} 4389 4390 The \code{__add__()} method is defined so it is possible to add two 4391 \code{Geospatial_data} objects. 4392 \end{methoddesc} 4393 4394 \label{ref:function_clip} 4395 \begin{methoddesc}{geospatial = \emph{<Geospatial_data>}.clip}{polygon, closed=True, verbose=False} 4396 Module: \code{geospatial_data.geospatial_data} 4397 4398 Clip a \code{Geospatial_data} object with a polygon. 4399 4400 \code{polygon} is the polygon to clip the \code{Geospatial_data} object with. 4401 This may be a list of points, an $N \times 2$ array or a \code{Geospatial_data} 4402 object. 4403 4404 \code{closed} determines whether points on the \code{polygon} edge are inside (\code{True}) 4405 or outside (\code{False}) the polygon. 4406 4407 Returns a new \code{Geospatial_data} object representing points inside the 4408 4409 Compare with \code{clip_outside()}, page \pageref{ref:function_clip_outside}. 4410 specified polygon. 4411 \end{methoddesc} 4412 4413 \label{ref:function_clip_outside} 4414 \begin{methoddesc}{geospatial = \emph{<Geospatial_data>}.clip_outside} 4415 {polygon, closed=True, verbose=False} 4416 Module: \code{geospatial_data.geospatial_data} 4417 4418 Clip a \code{Geospatial_data} object with a polygon. 4419 4420 \code{polygon} is the polygon to clip the \code{Geospatial_data} object with. 4421 This may be a list of points, an $N \times 2$ array or a \code{Geospatial_data} 4422 object. 4423 4424 \code{closed} determines whether points on the \code{polygon} edge are inside (\code{True}) 4425 or outside (\code{False}) the polygon. 4426 4427 Returns a new \code{Geospatial_data} object representing points outside the 4428 specified polygon. 4429 4430 Compare with \code{clip()}, page \pageref{ref:function_clip}. 4431 \end{methoddesc} 4432 4433 \begin{methoddesc}{(g1, g2) = \emph{<Geospatial_data>}.split} 4434 {factor=0.5, seed_num=None, verbose=False} 4435 Module: \code{geospatial_data.geospatial_data} 4436 4437 Split a \code{Geospatial_data} object into two objects of predetermined ratios. 4438 4439 \code{factor} is the ratio of the size of the first returned object to the 4440 original object. If '0.5' is supplied, the two resulting objects will be 4441 of equal size. 4442 4443 \code{seed_num}, if supplied, will be the random number generator seed used for 4444 the split. 4445 4446 Points of the two new geospatial_data object are selected RANDOMLY. 4447 4448 Returns two geospatial_data objects that are disjoint sets of the original. 4449 \end{methoddesc} 4450 4451 \subsection{Miscellaneous Functions} 4452 4453 The functions here are not \code{Geospatial_data} object methods, but are used with them. 4454 4455 \begin{methoddesc}{X = find_optimal_smoothing_parameter} 4456 {data_file, 4457 alpha_list=None, 4458 mesh_file=None, 4459 boundary_poly=None, 4460 mesh_resolution=100000, 4461 north_boundary=None, 4462 south_boundary=None, 4463 east_boundary=None, 4464 west_boundary=None, 4465 plot_name='all_alphas', 4466 split_factor=0.1, 4467 seed_num=None, 4468 cache=False, 4469 verbose=False} 4470 Module: \code{geospatial_data.geospatial_data} 4471 4472 Calculate the minimum covariance from a set of points in a file. It does this 4473 by removing a small random sample of points from \code{data_file} and creating 4474 models with different alpha values from \code{alpha_list} and cross validates 4475 the predicted value to the previously removed point data. Returns the 4476 alpha value which has the smallest covariance. 4477 4478 \code{data_file} is the input data file and must not contain points outside 4479 the boundaries defined and is either a PTS, TXT or CSV file. 4480 4481 \code{alpha_list} is the list of alpha values to use. 4482 4483 \code{mesh_file} is the path to a mesh file to create (if supplied). 4484 If \code{None} a mesh file will be created (named \file{temp.msh}). 4485 NOTE: if there is a \code{mesh_resolution} defined or any boundaries are defined, 4486 any input \code{mesh_file} value is ignored. 4487 4488 \code{mesh_resolution} is the maximum area size for a triangle. 4489 4490 \code{north_boundary}\\ 4491 \code{south_boundary}\\ 4492 \code{east_boundary}\\ 4493 \code{west_boundary} are the boundary values to use. 4494 4495 \code{plot_name} is the path name of the plot file to write. 4496 4497 \code{seed_num} is the random number generator seed to use. 4498 4499 The function returns a tuple \code{(min_covar, alpha)} where \code{min_covar} is 4500 the minumum normalised covariance and \code{alpha} is the alpha value that 4501 created it. A plot file is also written. 4502 4503 This is an example of function usage: \nopagebreak 4504 4505 \begin{verbatim} 4506 convariance_value, alpha = $\backslash$ 4507 find_optimal_smoothing_parameter(data_file=fileName, 4508 alpha_list=[0.0001, 0.01, 1], 4509 mesh_file=None, 4510 mesh_resolution=3, 4511 north_boundary=5, 4512 south_boundary=-5, 4513 east_boundary=5, 4514 west_boundary=-5, 4515 plot_name='all_alphas', 4516 seed_num=100000, 4517 verbose=False) 4518 \end{verbatim} 4519 4520 NOTE: The function will not work if the \code{data_file} extent is greater than the 4521 \code{boundary_poly} polygon or any of the boundaries, e.g. \code{north_boundary}, etc. 4522 \end{methoddesc} 4523 4524 4525 \pagebreak 4002 4526 \section{Graphical Mesh Generator GUI} 4003 The program \code{graphical_mesh_generator.py} in the pmeshmodule4527 The program \code{graphical_mesh_generator.py} in the \code{pmesh} module 4004 4528 allows the user to set up the mesh of the problem interactively. 4005 4529 It can be used to build the outline of a mesh or to visualise a mesh … … 4007 4531 4008 4532 Graphical Mesh Generator will let the user select various modes. The 4009 current allowable modes are vertex, segment, hole or region. The mode4533 current allowable modes are $vertex$, $segment$, $hole$ or $region$. The mode 4010 4534 describes what sort of object is added or selected in response to 4011 4535 mouse clicks. When changing modes any prior selected objects become … … 4017 4541 4018 4542 4019 \section{alpha\_shape} 4543 \pagebreak 4544 \section{class Alpha_Shape} 4020 4545 \emph{Alpha shapes} are used to generate close-fitting boundaries 4021 4546 around sets of points. The alpha shape algorithm produces a shape … … 4039 4564 with instances of this class. 4040 4565 4041 \begin{classdesc}{Alpha\_Shape}{points, alpha=None} 4042 Module: \code{alpha\_shape} 4043 4044 To instantiate this class the user supplies the points from which 4045 the alpha shape is to be created (in the form of a list of 2-tuples 4046 \code{[[x1, y1],[x2, y2]}\ldots\code{]}, assigned to the parameter 4047 \code{points}) and, optionally, a value for the parameter 4048 \code{alpha}. The alpha shape is then computed and the user can then 4049 retrieve details of the boundary through the attributes defined for 4050 the class. 4566 \label{class:alpha_shape} 4567 \begin{classdesc}{Alpha_Shape}{points, alpha=None} 4568 Module: \code{alpha_shape} 4569 4570 Instantiate an instance of the \code{Alpha_Shape} class. 4571 4572 \code{points} is an $N \times 2$ list of points (\code{[[x1, y1],[x2, y2]}\ldots\code{]}). 4573 4574 \code{alpha} is the 'fitting' parameter. 4051 4575 \end{classdesc} 4052 4576 4053 \begin{funcdesc}{alpha \_shape\_via\_files}{point_file, boundary_file, alpha=None}4054 Module: \code{alpha\_shape}4055 4056 4057 \code{point\_file}, computes the associated alpha shape (either4058 4059 4060 the boundary to a file named \code{boundary\_file}. This output file4061 lists the coordinates \code{x, y} of each point in the boundary,4062 4577 \begin{funcdesc}{alpha_shape_via_files}{point_file, boundary_file, alpha= None} 4578 Module: \code{alpha_shape} 4579 4580 This function reads points from the specified point file 4581 \code{point_file}, computes the associated alpha shape (either 4582 using the specified value for \code{alpha} or, if no value is 4583 specified, automatically setting it to an optimal value) and outputs 4584 the boundary to a file named \code{boundary_file}. This output file 4585 lists the coordinates \code{(x, y)} of each point in the boundary, 4586 using one line per point. 4063 4587 \end{funcdesc} 4064 4588 4065 \begin{methoddesc}{set\_boundary\_type}{self,raw_boundary=True, 4066 remove_holes=False, 4067 smooth_indents=False, 4068 expand_pinch=False, 4069 boundary_points_fraction=0.2} 4070 Module: \code{alpha\_shape}, Class: \class{Alpha\_Shape} 4071 4072 This function sets flags that govern the operation of the algorithm 4073 that computes the boundary, as follows: 4074 4075 \code{raw\_boundary = True} returns raw boundary, i.e. the regular edges of the 4076 alpha shape.\\ 4077 \code{remove\_holes = True} removes small holes ('small' is defined by 4078 \code{boundary\_points\_fraction})\\ 4079 \code{smooth\_indents = True} removes sharp triangular indents in 4080 boundary\\ 4081 \code{expand\_pinch = True} tests for pinch-off and 4082 corrects -- preventing a boundary vertex from having more than two edges. 4083 \end{methoddesc} 4084 4085 \begin{methoddesc}{get\_boundary}{} 4086 Module: \code{alpha\_shape}, Class: \class{Alpha\_Shape} 4087 4088 Returns a list of tuples representing the boundary of the alpha 4089 shape. Each tuple represents a segment in the boundary by providing 4090 the indices of its two endpoints. 4091 \end{methoddesc} 4092 4093 \begin{methoddesc}{write\_boundary}{file_name} 4094 Module: \code{alpha\_shape}, Class: \class{Alpha\_Shape} 4095 4096 Writes the list of 2-tuples returned by \code{get\_boundary} to the 4097 file \code{file\_name}, using one line per tuple. 4589 \label{ref:method_set_boundary_type} 4590 \begin{methoddesc}{\emph{<Alpha_shape>}.set_boundary_type} 4591 {raw_boundary=True, 4592 remove_holes=False, 4593 smooth_indents=False, 4594 expand_pinch=False, 4595 boundary_points_fraction=0.2} 4596 Module: \code{alpha_shape} 4597 4598 This function sets internal state that controls how the \code{Alpha_shape} 4599 boundary is presented or exported. 4600 4601 \code{raw_boundary} sets the type to $raw$ if \code{True}, 4602 i.e. the regular edges of the alpha shape. 4603 4604 \code{remove_holes}, if \code{True} removes small holes ('small' is defined by 4605 \code{boundary_points_fraction}). 4606 4607 \code{smooth_indents}, if \code{True} removes sharp triangular indents in 4608 the boundary. 4609 4610 \code{expand_pinch}, if \code{True} tests for pinch-off and 4611 corrects -- preventing a boundary vertex from having more than two edges. 4612 \end{methoddesc} 4613 4614 \label{ref:method_get_boundary} 4615 \begin{methoddesc}{boundary = \emph{<Alpha_shape>}.get_boundary}{} 4616 Module: \code{alpha_shape} 4617 4618 Returns a list of tuples representing the boundary of the alpha 4619 shape. Each tuple represents a segment in the boundary by providing 4620 the indices of its two endpoints. 4621 4622 See \code{set_boundary_type()}, page \pageref{ref:method_set_boundary_type}. 4623 \end{methoddesc} 4624 4625 \label{ref:method_write_boundary} 4626 \begin{methoddesc}{\emph{<Alpha_shape>}.write_boundary}{file_name} 4627 Module: \code{alpha_shape} 4628 4629 Writes the list of 2-tuples returned by \code{get_boundary()} to the 4630 file \code{file_name}, using one line per tuple. 4631 4632 See \code{set_boundary_type()}, page \pageref{ref:method_set_boundary_type}. \\ 4633 See \code{get_boundary()}, page \pageref{ref:method_get_boundary}. 4098 4634 \end{methoddesc} 4099 4635 … … 4153 4689 more to come very soon 4154 4690 4155 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 4156 4157 \chapter{Modules available in \anuga} 4158 4159 4160 \section{\module{abstract\_2d\_finite\_volumes.general\_mesh} } 4161 \declaremodule[generalmesh]{}{general\_mesh} 4162 \label{mod:generalmesh} 4163 4164 4165 \section{\module{abstract\_2d\_finite\_volumes.neighbour\_mesh} } 4166 \declaremodule[neighbourmesh]{}{neighbour\_mesh} 4167 \label{mod:neighbourmesh} 4168 4169 4170 \section{\module{abstract\_2d\_finite\_volumes.domain}} 4171 Generic module for 2D triangular domains for finite-volume computations of conservation laws 4172 \declaremodule{}{domain} 4173 \label{mod:domain} 4174 4175 4176 \section{\module{abstract\_2d\_finite\_volumes.quantity}} 4177 \declaremodule{}{quantity} 4178 \label{mod:quantity} 4179 4180 \begin{verbatim} 4181 Class Quantity - Implements values at each triangular element 4182 4183 To create: 4184 4185 Quantity(domain, vertex_values) 4186 4187 domain: Associated domain structure. Required. 4188 4189 vertex_values: N x 3 array of values at each vertex for each element. 4190 Default None 4191 4192 If vertex_values are None Create array of zeros compatible with domain. 4193 Otherwise check that it is compatible with dimenions of domain. 4194 Otherwise raise an exception 4195 \end{verbatim} 4196 4197 4198 \section{\module{shallow\_water}} 4199 4200 2D triangular domains for finite-volume 4201 computations of the shallow water wave equation. 4202 This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water 4203 Wave Equation 4204 4205 \declaremodule[shallowwater]{}{shallow\_water} 4206 \label{mod:shallowwater} 4691 %?% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 4692 %?% 4693 %?% \chapter{Modules available in \anuga} 4694 %?% 4695 %?% 4696 %?% %abstract_2d_finite_volumes 4697 %?% 4698 %?% \section{\module{abstract_2d_finite_volumes.domain}} 4699 %?% Generic module for 2D triangular domains for finite-volume computations of conservation laws 4700 %?% \declaremodule[domain]{}{domain} 4701 %?% \label{mod:domain} 4702 %?% 4703 %?% 4704 %?% \section{\module{abstract_2d_finite_volumes.ermapper_grids}} 4705 %?% \declaremodule[ermappergrids]{}{ermapper_grids} 4706 %?% \label{mod:ermapper_grids} 4707 %?% 4708 %?% 4709 %?% \section{\module{abstract_2d_finite_volumes.general_mesh} } 4710 %?% \declaremodule[generalmesh]{}{general_mesh} 4711 %?% \label{mod:general_mesh} 4712 %?% 4713 %?% 4714 %?% \section{\module{abstract_2d_finite_volumes.generic_boundary_conditions} } 4715 %?% \declaremodule[genericboundaryconditions]{}{generic_boundary_conditions} 4716 %?% \label{mod:generic_boundary_conditions} 4717 %?% 4718 %?% 4719 %?% \section{\module{abstract_2d_finite_volumes.mesh_factory} } 4720 %?% \declaremodule[meshfactory]{}{mesh_factory} 4721 %?% \label{mod:mesh_factory} 4722 %?% 4723 %?% 4724 %?% \section{\module{abstract_2d_finite_volumes.mesh_factory} } 4725 %?% \declaremodule[meshfactory]{}{mesh_factory} 4726 %?% \label{mod:mesh_factory} 4727 %?% 4728 %?% 4729 %?% \section{\module{abstract_2d_finite_volumes.neighbour_mesh} } 4730 %?% \declaremodule[neighbourmesh]{}{neighbour_mesh} 4731 %?% \label{mod:neighbour_mesh} 4732 %?% 4733 %?% 4734 %?% \section{\module{abstract_2d_finite_volumes.pmesh2domain} } 4735 %?% \declaremodule[pmesh2domain]{}{pmesh2domain} 4736 %?% \label{mod:pmesh2domain} 4737 %?% 4738 %?% 4739 %?% \section{\module{abstract_2d_finite_volumes.quantity}} 4740 %?% \declaremodule{}{quantity} 4741 %?% \label{mod:quantity} 4742 %?% 4743 %?% \begin{verbatim} 4744 %?% Class Quantity - Implements values at each triangular element 4745 %?% 4746 %?% To create: 4747 %?% 4748 %?% Quantity(domain, vertex_values) 4749 %?% 4750 %?% domain: Associated domain structure. Required. 4751 %?% 4752 %?% vertex_values: Nx3 array of values at each vertex for each element. 4753 %?% Default None 4754 %?% 4755 %?% If vertex_values are None Create array of zeros compatible with domain. 4756 %?% Otherwise check that it is compatible with dimenions of domain. 4757 %?% Otherwise raise an exception 4758 %?% \end{verbatim} 4759 %?% 4760 %?% 4761 %?% \section{\module{abstract_2d_finite_volumes.region} } 4762 %?% \declaremodule[region]{}{region} 4763 %?% \label{mod:region} 4764 %?% 4765 %?% 4766 %?% \section{\module{abstract_2d_finite_volumes.util} } 4767 %?% \declaremodule[util]{}{util} 4768 %?% \label{mod:util} 4769 %?% 4770 %?% 4771 %?% advection 4772 %?% alpha_shape 4773 %?% caching 4774 %?% coordinate_transforms 4775 %?% culvert_flows 4776 %?% damage_modelling 4777 %?% euler 4778 %?% fit_interpolate 4779 %?% geospatial_data 4780 %?% lib 4781 %?% load_mesh 4782 %?% mesh_engine 4783 %?% pmesh 4784 %?% SConstruct 4785 %?% shallow_water 4786 %?% utilities 4787 %?% 4788 %?% 4789 %?% \section{\module{shallow\_water}} 4790 %?% 4791 %?% 2D triangular domains for finite-volume 4792 %?% computations of the shallow water wave equation. 4793 %?% This module contains a specialisation of class Domain from module domain.py consisting of methods specific to the Shallow Water 4794 %?% Wave Equation 4795 %?% 4796 %?% \declaremodule[shallowwater]{}{shallow\_water} 4797 %?% \label{mod:shallowwater} 4207 4798 4208 4799 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 4209 4800 4210 \chapter{ ANUGAFull-scale Validations}4801 \chapter{\anuga Full-scale Validations} 4211 4802 4212 4803 … … 4232 4823 4233 4824 You may download the validation data files by hand and then run the validation. 4234 Just go to the ANUGASourceforge project download page at4825 Just go to the \anuga Sourceforge project download page at 4235 4826 \module{http://sourceforge.net/project/showfiles.php?group_id=172848} and select 4236 4827 the \module{validation_data} package, \module{patong-1.0} release. You need the … … 4335 4926 % 4336 4927 4337 % begin{latexonly}4338 % \renewcommand{\indexname}{Module Index}4339 % end{latexonly}4340 \input{mod\jobname.ind} % Module Index4341 % 4928 %?% %begin{latexonly} 4929 %?% %\renewcommand{\indexname}{Module Index} 4930 %?% %end{latexonly} 4931 %?% \input{mod\jobname.ind} % Module Index 4932 4342 4933 %begin{latexonly} 4343 4934 %\renewcommand{\indexname}{Index} -
anuga_core/documentation/user_manual/python.sty
r2363 r7134 611 611 } 612 612 \newenvironment{cfuncdesc}[4][\py@badkey]{ 613 \linebreak 614 \linebreak 613 615 \begin{fulllineitems} 614 616 \cfuncline{#2}{#3}{#4} … … 616 618 \emph{Return value: \textbf{#1}.}\\ 617 619 \fi 620 \linebreak 621 \linebreak 618 622 }{\end{fulllineitems}} 619 623
Note: See TracChangeset
for help on using the changeset viewer.