source: trunk/anuga_core/source/anuga/__init__.py @ 7791

Last change on this file since 7791 was 7791, checked in by steve, 12 years ago

Added some documentation

File size: 10.2 KB
Line 
1""" ANUGA models the effect of tsunamis and flooding upon a terrain mesh.
2    In typical usage, a Domain class is created for a particular piece of
3    terrain. Boundary conditions are specified for the domain, such as inflow
4    and outflow, and then the simulation is run.
5
6    This is the public API to ANUGA. It provides a toolkit of often-used
7    modules, which can be used directly by including the following line in
8    the user's code:
9
10    import anuga
11       
12    This usage pattern abstracts away the internal heirarchy of the ANUGA
13    system, allowing the user to concentrate on writing simulations without
14    searching through the ANUGA source tree for the functions that they need.
15   
16    Also, it isolates the user from "under-the-hood" refactorings.
17"""
18
19pass
20
21#Add path of package to PYTHONPATH to allow C-extensions to be loaded
22import sys
23sys.path += __path__
24
25#-----------------------------------------------------
26# Make selected classes available directly
27#-----------------------------------------------------
28
29from anuga.shallow_water.shallow_water_domain import Domain
30
31from anuga.abstract_2d_finite_volumes.util import file_function
32
33from anuga.abstract_2d_finite_volumes.mesh_factory import rectangular_cross
34
35from anuga.file.csv_file import load_csv_as_building_polygons,  \
36                                load_csv_as_polygons
37
38from anuga.file.sts import create_sts_boundary
39
40from anuga.geometry.polygon import read_polygon, plot_polygons, polygon_area
41from anuga.geometry.polygon import Polygon_function
42
43from anuga.abstract_2d_finite_volumes.pmesh2domain import \
44                                            pmesh_to_domain_instance
45
46
47#-----------------------------
48# Standard Boundaries
49#-----------------------------
50from anuga.shallow_water.boundaries import File_boundary
51from anuga.shallow_water.boundaries import Reflective_boundary
52from anuga.shallow_water.boundaries import Field_boundary
53from anuga.shallow_water.boundaries import \
54                    Transmissive_stage_zero_momentum_boundary
55from anuga.shallow_water.boundaries import \
56                    Transmissive_momentum_set_stage_boundary
57from anuga.shallow_water.boundaries import \
58                    Transmissive_n_momentum_zero_t_momentum_set_stage_boundary
59
60
61#-----------------------------
62# SWW-specific Boundaries
63#-----------------------------
64from anuga.abstract_2d_finite_volumes.generic_boundary_conditions \
65                            import Dirichlet_boundary
66from anuga.abstract_2d_finite_volumes.generic_boundary_conditions \
67                            import Time_boundary
68from anuga.abstract_2d_finite_volumes.generic_boundary_conditions \
69                            import Time_space_boundary
70from anuga.abstract_2d_finite_volumes.generic_boundary_conditions \
71                            import Transmissive_boundary
72
73
74
75#-----------------------------
76# Forcing
77#-----------------------------
78from anuga.shallow_water.forcing import Inflow
79
80#-----------------------------
81# File conversion utilities
82#-----------------------------
83from anuga.file_conversion.file_conversion import sww2obj, dat2obj, \
84                    timefile2netcdf, tsh2sww, urs2sww
85from anuga.file_conversion.urs2nc import urs2nc
86from anuga.file_conversion.dem2pts import dem2pts                   
87from anuga.file_conversion.esri2sww import esri2sww   
88from anuga.file_conversion.sww2dem import sww2dem, sww2dem_batch
89from anuga.file_conversion.asc2dem import asc2dem     
90from anuga.file_conversion.ferret2sww import ferret2sww     
91from anuga.file_conversion.dem2dem import dem2dem
92
93#-----------------------------
94# SWW file access
95#-----------------------------
96from anuga.shallow_water.sww_interrogate import get_flow_through_cross_section
97
98#-----------------------------
99# rectangular domains
100#-----------------------------
101def rectangular_cross_domain(*args, **kwargs):
102    """
103    Create a rectangular domain with triangulation made
104    up of m+1 by n+1 uniform rectangular cells divided
105    into 4 triangles in a cross pattern
106
107    Arguments
108    m:      number of cells in x direction
109    n:      number of cells in y direction
110    len1:   length of domain in x direction (left to right)
111            (default 1.0)
112    len2:   length of domain in y direction (bottom to top)
113            (default 1.0)
114    origin: tuple (x,y) specifying location of lower left corner
115            of domain (default (0,0))
116    """
117    points, vertices, boundary = rectangular_cross(*args, **kwargs)
118    return Domain(points, vertices, boundary)
119
120#----------------------------
121# Create domain from file
122#----------------------------
123def create_domain_from_file(file):
124    """
125    Create a domain from a file
126    """
127    return pmesh_to_domain_instance(file,Domain)
128
129#---------------------------
130# Create domain from regions
131#---------------------------
132
133def create_domain_from_regions(bounding_polygon,
134                               boundary_tags,
135                               maximum_triangle_area=None,
136                               mesh_filename=None,
137                               interior_regions=None,
138                               interior_holes=None,
139                               poly_geo_reference=None,
140                               mesh_geo_reference=None,
141                               minimum_triangle_angle=28.0,
142                               fail_if_polygons_outside=True,
143                               use_cache=False,
144                               verbose=True):
145    """Create domain from bounding polygons and resolutions.
146
147    bounding_polygon is a list of points in Eastings and Northings,
148    relative to the zone stated in poly_geo_reference if specified.
149    Otherwise points are just x, y coordinates with no particular
150    association to any location.
151
152    boundary_tags is a dictionary of symbolic tags. For every tag there
153    is a list of indices referring to segments associated with that tag.
154    If a segment is omitted it will be assigned the default tag ''.
155
156    maximum_triangle_area is the maximal area per triangle
157    for the bounding polygon, excluding the  interior regions.
158
159    Interior_regions is a list of tuples consisting of (polygon,
160    resolution) for each region to be separately refined. Do not have
161    polygon lines cross or be on-top of each other.  Also do not have
162    polygon close to each other.
163   
164    NOTE: If a interior_region is outside the bounding_polygon it should
165    throw an error
166   
167    Interior_holes is a list of ploygons for each hole.
168
169    This function does not allow segments to share points - use underlying
170    pmesh functionality for that
171
172    poly_geo_reference is the geo_reference of the bounding polygon and
173    the interior polygons.
174    If none, assume absolute.  Please pass one though, since absolute
175    references have a zone.
176   
177    mesh_geo_reference is the geo_reference of the mesh to be created.
178    If none is given one will be automatically generated.  It was use
179    the lower left hand corner of  bounding_polygon (absolute)
180    as the x and y values for the geo_ref.
181   
182    Returns the shallow water domain instance
183
184    Note, interior regions should be fully nested, as overlaps may cause
185    unintended resolutions.
186
187    fail_if_polygons_outside: If True (the default) Exception in thrown
188    where interior polygons fall outside bounding polygon. If False, these
189    will be ignored and execution continued.
190       
191   
192    """
193
194
195    # Build arguments and keyword arguments for use with caching or apply.
196    args = (bounding_polygon,
197            boundary_tags)
198   
199    kwargs = {'maximum_triangle_area': maximum_triangle_area,
200              'mesh_filename': mesh_filename,
201              'interior_regions': interior_regions,
202              'interior_holes': interior_holes,
203              'poly_geo_reference': poly_geo_reference,
204              'mesh_geo_reference': mesh_geo_reference,
205              'minimum_triangle_angle': minimum_triangle_angle,
206              'fail_if_polygons_outside': fail_if_polygons_outside,
207              'verbose': verbose} #FIXME (Ole): See ticket:14
208
209    # Call underlying engine with or without caching
210    if use_cache is True:
211        try:
212            from anuga.caching import cache
213        except:
214            msg = 'Caching was requested, but caching module'+\
215                  'could not be imported'
216            raise msg
217
218
219        domain = cache(_create_domain_from_regions,
220                       args, kwargs,
221                       verbose=verbose,
222                       compression=False)
223    else:
224        domain = apply(_create_domain_from_regions,
225                       args, kwargs)
226
227    return domain
228
229       
230def _create_domain_from_regions(bounding_polygon,
231                                boundary_tags,
232                                maximum_triangle_area=None,
233                                mesh_filename=None,                           
234                                interior_regions=None,
235                                interior_holes=None,
236                                poly_geo_reference=None,
237                                mesh_geo_reference=None,
238                                minimum_triangle_angle=28.0,
239                                fail_if_polygons_outside=True,
240                                verbose=True):
241    """_create_domain_from_regions - internal function.
242
243    See create_domain_from_regions for documentation.
244    """
245
246    from anuga.shallow_water.shallow_water_domain import Domain
247    from anuga.pmesh.mesh_interface import create_mesh_from_regions
248   
249    create_mesh_from_regions(bounding_polygon,
250                             boundary_tags,
251                             maximum_triangle_area=maximum_triangle_area,
252                             interior_regions=interior_regions,
253                             filename=mesh_filename,
254                             interior_holes=interior_holes,
255                             poly_geo_reference=poly_geo_reference,
256                             mesh_geo_reference=mesh_geo_reference,
257                             minimum_triangle_angle=minimum_triangle_angle,
258                             fail_if_polygons_outside=fail_if_polygons_outside,
259                             use_cache=False,
260                             verbose=verbose)
261    domain = Domain(mesh_filename, use_cache=False, verbose=verbose)
262
263
264    return domain
265   
266
267
268
269
270
Note: See TracBrowser for help on using the repository browser.