openquake.hazardlib.geo.surface package¶
Submodules¶
openquake.hazardlib.geo.surface.base module¶
Module openquake.hazardlib.geo.surface.base
implements
BaseSurface
and BaseSurface
.

class
openquake.hazardlib.geo.surface.base.
BaseSurface
(mesh=None)[source]¶ Bases:
object
Base class for a surface in 3Dspace.

get_azimuth
(mesh)[source]¶ This method computes the azimuth of a set of points in a
openquake.hazardlib.geo.mesh
instance. The reference used for the calculation of azimuth is the middle point and the strike of the rupture. The value of azimuth computed corresponds to the angle measured in a clockwise direction from the strike of the rupture. Parameters
mesh – An instance of
openquake.hazardlib.geo.mesh
 Returns
An instance of numpy.ndarray

get_azimuth_of_closest_point
(mesh)[source]¶ Compute the azimuth between point in mesh and the corresponding closest point on the rupture surface.
 Parameters
mesh – An instance of
openquake.hazardlib.geo.mesh
 Returns
An
numpy.ndarray
instance with the azimuth values.

get_bounding_box
()[source]¶ Compute surface bounding box from surface mesh representation. That is extract longitudes and latitudes of mesh points and calls:
openquake.hazardlib.geo.utils.get_spherical_bounding_box()
 Returns
A tuple of four items. These items represent western, eastern, northern and southern borders of the bounding box respectively. Values are floats in decimal degrees.

get_closest_points
(mesh)[source]¶ For each point from
mesh
find a closest point belonging to surface.

get_hypo_location
(mesh_spacing, hypo_loc=None)[source]¶ The method determines the location of the hypocentre within the rupture
 Parameters
mesh –
Mesh
of pointsmesh_spacing – The desired distance between two adjacent points in source’s ruptures’ mesh, in km. Mainly this parameter allows to balance the tradeoff between time needed to compute the distance between the rupture surface and a site and the precision of that computation.
hypo_loc – Hypocentre location as fraction of rupture plane, as a tuple of (Along Strike, Down Dip), e.g. a hypocentre located in the centroid of the rupture would be input as (0.5, 0.5), whereas a hypocentre located in a position 3/4 along the length, and 1/4 of the way down dip of the rupture plane would be entered as (0.75, 0.25).
 Returns
Hypocentre location as instance of
Point

get_joyner_boore_distance
(mesh)[source]¶ Compute and return JoynerBoore (also known as
Rjb
) distance to each point ofmesh
. Parameters
mesh –
Mesh
of points to calculate JoynerBoore distance to. Returns
Numpy array of closest distances between the projections of surface and each point of the
mesh
to the earth surface.

get_middle_point
()[source]¶ Compute coordinates of surface middle point.
The actual definition of
middle point
depends on the type of surface geometry. Returns
instance of
openquake.hazardlib.geo.point.Point
representing surface middle point.

get_min_distance
(mesh)[source]¶ Compute and return the minimum distance from the surface to each point of
mesh
. This distance is sometimes calledRrup
. Parameters
mesh –
Mesh
of points to calculate minimum distance to. Returns
A numpy array of distances in km.

get_resampled_top_edge
(angle_var=0.1)[source]¶ This methods computes a simplified representation of a fault top edge by removing the points that are not describing a change of direction, provided a certain tolerance angle.
 Parameters
angle_var (float) – Number representing the maximum deviation (in degrees) admitted without the creation of a new segment
 Returns
A
Line
representing the rupture surface’s top edge.

get_rx_distance
(mesh)[source]¶ Compute distance between each point of mesh and surface’s great circle arc.
Distance is measured perpendicular to the rupture strike, from the surface projection of the updip edge of the rupture, with the down dip direction being positive (this distance is usually called
Rx
).In other words, is the horizontal distance to top edge of rupture measured perpendicular to the strike. Values on the hanging wall are positive, values on the footwall are negative.
 Parameters
mesh –
Mesh
of points to calculate Rxdistance to. Returns
Numpy array of distances in km.

get_ry0_distance
(mesh)[source]¶ Compute the minimum distance between each point of a mesh and the great circle arcs perpendicular to the average strike direction of the fault trace and passing through the endpoints of the trace.
 Parameters
mesh –
Mesh
of points to calculate Ry0distance to. Returns
Numpy array of distances in km.


openquake.hazardlib.geo.surface.base.
downsample_mesh
(mesh, tol=1.0)[source]¶ Returns a mesh sampled at a lower resolution  if the difference in azimuth is larger than the specified tolerance a turn is assumed
 Returns
Downsampled mesh as instance of :class: openquake.hazardlib.geo.mesh.RectangularMesh
openquake.hazardlib.geo.surface.complex_fault module¶
Module openquake.hazardlib.geo.surface.complex_fault
defines
ComplexFaultSurface
.

class
openquake.hazardlib.geo.surface.complex_fault.
ComplexFaultSurface
(mesh)[source]¶ Bases:
openquake.hazardlib.geo.surface.base.BaseSurface
Represent a complex fault surface as 3D mesh of points (not necessarily uniformly spaced across the surface area).
 Parameters
mesh – Instance of
RectangularMesh
representing surface geometry.
Another way to construct the surface object is to call
from_fault_data()
.
classmethod
check_aki_richards_convention
(edges)[source]¶ Verify that surface (as defined by corner points) conforms with Aki and Richard convention (i.e. surface dips right of surface strike)
This method doesn’t have to be called by hands before creating the surface object, because it is called from
from_fault_data()
.

classmethod
check_fault_data
(edges, mesh_spacing)[source]¶ Verify the fault data and raise
ValueError
if anything is wrong.This method doesn’t have to be called by hands before creating the surface object, because it is called from
from_fault_data()
.

classmethod
check_surface_validity
(edges)[source]¶ Check validity of the surface.
Project edge points to vertical plane anchored to surface upper left edge and with strike equal to top edge strike. Check that resulting polygon is valid.
This method doesn’t have to be called by hands before creating the surface object, because it is called from
from_fault_data()
.

classmethod
from_fault_data
(edges, mesh_spacing)[source]¶ Create and return a fault surface using fault source data.
 Parameters
edges – A list of at least two horizontal edges of the surface as instances of
openquake.hazardlib.geo.line.Line
. The list should be in toptobottom order (the shallowest edge first).mesh_spacing – Distance between two subsequent points in a mesh, in km.
 Returns
An instance of
ComplexFaultSurface
created using that data. Raises
ValueError – If requested mesh spacing is too big for the surface geometry (doesn’t allow to put a single mesh cell along length and/or width).
Uses
check_fault_data()
for checking parameters.

get_dip
()[source]¶ Return the fault dip as the average dip over the mesh.
The average dip is defined as the weighted mean inclination of all the mesh cells. See
openquake.hazardlib.geo.mesh.RectangularMesh.get_mean_inclination_and_azimuth()
 Returns
The average dip, in decimal degrees.

get_strike
()[source]¶ Return the fault strike as the average strike over the mesh.
The average strike is defined as the weighted mean azimuth of all the mesh cells. See
openquake.hazardlib.geo.mesh.RectangularMesh.get_mean_inclination_and_azimuth()
 Returns
The average strike, in decimal degrees.

get_width
()[source]¶ Return surface’s width (that is surface extension along the dip direction) in km.
The width is computed as the average width along the surface. See
openquake.hazardlib.geo.mesh.RectangularMesh.get_mean_width()

classmethod
surface_projection_from_fault_data
(edges)[source]¶ Get a surface projection of the complex fault surface.
 Parameters
edges – A list of horizontal edges of the surface as instances of
openquake.hazardlib.geo.line.Line
. Returns
Instance of
Polygon
describing the surface projection of the complex fault.
openquake.hazardlib.geo.surface.gridded module¶
Module openquake.hazardlib.geo.surface.gridded
defines
GriddedSurface
.

class
openquake.hazardlib.geo.surface.gridded.
GriddedSurface
(mesh=None)[source]¶ Bases:
openquake.hazardlib.geo.surface.base.BaseSurface
Gridded surface defined by an unstructured cloud of points. This surface type is required for a proper implementation of some subduction interface surfaces included int the Japan 2012 model.
Note that currently we support only one rupturesite typology i.e. since this the only one that can be unambiguosly computed.
 Parameters
mesh – An unstructured mesh of points ideally representing a rupture surface. Must be an instance of
Mesh

classmethod
from_points_list
(points)[source]¶ Create a gridded surface from a list of points.
 Parameters
points – A list of
Point
 Returns
An instance of
GriddedSurface

get_bounding_box
()[source]¶ Compute surface geographical bounding box.
 Returns
A tuple of four items. These items represent western, eastern, northern and southern borders of the bounding box respectively. Values are floats in decimal degrees.

get_dip
()[source]¶ Compute surface’s dip as decimal degrees in a range
(0, 90]
.The actual definition of the dip might depend on surface geometry.
 Returns
numpy.nan, not available for this kind of surface (yet)

get_middle_point
()[source]¶ Compute coordinates of surface middle point.
The actual definition of
middle point
depends on the type of surface geometry. Returns
instance of
openquake.hazardlib.geo.point.Point
representing surface middle point.

get_rx_distance
(mesh)[source]¶ Compute distance between each point of mesh and surface’s great circle arc.
Distance is measured perpendicular to the rupture strike, from the surface projection of the updip edge of the rupture, with the down dip direction being positive (this distance is usually called
Rx
).In other words, is the horizontal distance to top edge of rupture measured perpendicular to the strike. Values on the hanging wall are positive, values on the footwall are negative.
 Parameters
mesh –
Mesh
of points to calculate Rxdistance to. Returns
Numpy array of distances in km.

get_strike
()[source]¶ Compute surface’s strike as decimal degrees in a range
[0, 360)
.The actual definition of the strike might depend on surface geometry.
 Returns
numpy.nan, not available for this kind of surface (yet)

get_surface_boundaries_3d
()[source]¶  Returns
(lons, lats, depths) for the 5 points of the bounding box

get_top_edge_depth
()[source]¶ Compute minimum depth of surface’s top edge.
 Returns
Float value, the vertical distance between the earth surface and the shallowest point in surface’s top edge in km.

get_width
()[source]¶ Compute surface’s width (that is surface extension along the dip direction) in km.
The actual definition depends on the type of surface geometry.
 Returns
Float value, the surface width

property
surface_nodes
¶  Parameters
points – a list of Point objects
 Returns
a Node of kind ‘griddedSurface’
openquake.hazardlib.geo.surface.multi module¶
Module openquake.hazardlib.geo.surface.multi
defines
MultiSurface
.

class
openquake.hazardlib.geo.surface.multi.
MultiSurface
(surfaces, tol=0.1)[source]¶ Bases:
openquake.hazardlib.geo.surface.base.BaseSurface
Represent a surface as a collection of independent surface elements.
 Parameters
surfaces – List of instances of subclasses of
BaseSurface
each representing a surface geometry element.edge_set – Retains list of upper edges from all of the surfaces, with each edge given as a numpy array of [longitude, latitude, depth]
cartesian_edges – For GC2, this holds the list of edge sets in an orthographic projection such that the coordinates are all cartesian.
cartesian_endpoints – For GC2, this hold the list of endpoints of the edges in an orthographic projection
proj – For GC2, instance of :class: ~openquake.hazardlib.geo.utils.OrthographicProjection instantiated with the bounding box limits of the fault
length_set – List of lengths of upper edges of each surface
cum_length_set – List of cumulative lengths of edges along fault
gc2_config – For GC2, dictionary holding fault specific parameters for GC2 configuration
p0 – For GC2, reference origin point of the fault
gc2t – GC2 Tcoordinate
gc2u – GC2 Ucoordinate
tmp_mesh – If fed with the same mesh twice (e.g. calling get_rx_distance and then get_ry0_distance in sequence) does not repeat GC2 calculations, this hold the last mesh it was fed with
gc_length – For GC2, determines the length of the fault (km) in its own GC2 configuration

get_bounding_box
()[source]¶ Compute bounding box for each surface element, and then return the bounding box of all surface elements’ bounding boxes.
 Returns
A tuple of four items. These items represent western, eastern, northern and southern borders of the bounding box respectively. Values are floats in decimal degrees.

get_closest_points
(mesh)[source]¶ For each point in
mesh
find the closest surface element, and return the corresponding closest point.See
superclass method
for spec of input and result values.

get_dip
()[source]¶ Compute dip of each surface element and return areaweighted average value (in range
(0, 90]
).Given that dip values are constrained in the range (0, 90], the simple formula for weighted mean is used.

get_generalised_coordinates
(lons, lats)[source]¶ Transforms the site positions into the generalised coordinate form described by Spudich and Chiou (2015) for the multirupture and/or discordant case
Spudich, Paul and Chiou, Brian (2015) Strikeparallel and strikenormal coordinate system around geometrically complicated rupture traces — Use by NGAWest2 and further improvements: U.S. Geological Survey OpenFile Report 20151028

get_joyner_boore_distance
(mesh)[source]¶ For each point in mesh compute the JoynerBoore distance to all the surface elements and return the smallest value.
See
superclass method
for spec of input and result values.

get_middle_point
()[source]¶ If
MultiSurface
is defined by a single surface, simply returns surface’s middle point, otherwise find surface element closest to the surface’s bounding box centroid and return corresponding middle point.Note that the concept of middle point for a multi surface is ambiguous and alternative definitions may be possible. However, this method is mostly used to define the hypocenter location for ruptures described by a multi surface (see
openquake.hazardlib.source.characteristic.CharacteristicFaultSource.iter_ruptures()
). This is needed because when creating fault based sources, the rupture’s hypocenter locations are not explicitly defined, and therefore an automated way to define them is required.

get_min_distance
(mesh)[source]¶ For each point in
mesh
compute the minimum distance to each surface element and return the smallest value.See
superclass method
for spec of input and result values.

get_rx_distance
(mesh)[source]¶ For each point determine the corresponding rx distance using the GC2 configuration.
See
superclass method
for spec of input and result values.

get_ry0_distance
(mesh)[source]¶ For each point determine the corresponding Ry0 distance using the GC2 configuration.
See
superclass method
for spec of input and result values.

get_strike
()[source]¶ Compute strike of each surface element and return areaweighted average value (in range
[0, 360]
) using formula from: http://en.wikipedia.org/wiki/Mean_of_circular_quantitiesNote that the original formula has been adapted to compute a weighted rather than arithmetic mean.

get_surface_boundaries
()[source]¶ Returns the boundaries in the same format as a multiplanar surface, with two lists of lons and lats

get_top_edge_depth
()[source]¶ Compute top edge depth of each surface element and return areaweighted average value (in km).

get_width
()[source]¶ Compute width of each surface element, and return areaweighted average value (in km).

property
mesh
¶  Returns
mesh corresponding to the whole multi surface

property
surface_nodes
¶  Returns
a list of surface nodes from the underlying single node surfaces
openquake.hazardlib.geo.surface.planar module¶
Module openquake.hazardlib.geo.surface.planar
contains
PlanarSurface
.

class
openquake.hazardlib.geo.surface.planar.
PlanarSurface
(strike, dip, top_left, top_right, bottom_right, bottom_left, check=True)[source]¶ Bases:
openquake.hazardlib.geo.surface.base.BaseSurface
Planar rectangular surface with two sides parallel to the Earth surface.
 Parameters
strike – Strike of the surface is the azimuth from
top_left
totop_right
points.dip – Dip is the angle between the surface itself and the earth surface.
Other parameters are points (instances of
Point
) defining the surface corners in clockwise direction starting from top left corner. Top and bottom edges of the polygon must be parallel to earth surface and to each other.See
NodalPlane
for more detailed definition ofstrike
anddip
. Note that these parameters are supposed to match the factual surface geometry (defined by corner points), but this is not enforced or even checked. Raises
ValueError – If either top or bottom points differ in depth or if top edge is not parallel to the bottom edge, if top edge differs in length from the bottom one, or if mesh spacing is not positive.

IMPERFECT_RECTANGLE_TOLERANCE
= 0.002¶ Maximum difference in surface’s rectangle side lengths, maximum offset of a bottom right corner from a plane that contains other corners, as well as maximum offset of a bottom left corner from a line drawn downdip perpendicular to top edge from top left corner, expressed as a fraction of the surface’s area.

property
bottom_left
¶

property
bottom_right
¶

classmethod
from_array
(array3N)[source]¶  Parameters
array3N – an array of shape (3, N)
 Returns
a
PlanarSurface
instance

classmethod
from_corner_points
(top_left, top_right, bottom_right, bottom_left)[source]¶ Create and return a planar surface from four corner points.
The azimuth of the line connecting the top left and the top right corners define the surface strike, while the angle between the line connecting the top left and bottom left corners and a line parallel to the earth surface defines the surface dip.
 Parameters
top_left (openquake.hazardlib.geo.point.Point) – Upper left corner
top_right (openquake.hazardlib.geo.point.Point) – Upper right corner
bottom_right (openquake.hazardlib.geo.point.Point) – Lower right corner
bottom_left (openquake.hazardlib.geo.point.Point) – Lower left corner
 Returns
An instance of
PlanarSurface
.

get_area
()[source]¶ Return surface’s area value (in squared km) obtained as the product of surface lenght and width.

get_bounding_box
()[source]¶ Compute surface bounding box from plane’s corners coordinates. Calls
openquake.hazardlib.geo.utils.get_spherical_bounding_box()
 Returns
A tuple of four items. These items represent western, eastern, northern and southern borders of the bounding box respectively. Values are floats in decimal degrees.

get_closest_points
(mesh)[source]¶ See
superclass' method
.This is an optimized version specific to planar surface that doesn’t make use of the mesh.

get_joyner_boore_distance
(mesh)[source]¶ See
superclass' method
.This is an optimized version specific to planar surface that doesn’t make use of the mesh.

get_middle_point
()[source]¶ Compute middle point from surface’s corners coordinates. Calls
openquake.hazardlib.geo.utils.get_middle_point()

get_min_distance
(mesh)[source]¶ See
superclass' method
.This is an optimized version specific to planar surface that doesn’t make use of the mesh.

get_rx_distance
(mesh)[source]¶ See
superclass method
for spec of input and result values.This is an optimized version specific to planar surface that doesn’t make use of the mesh.

get_ry0_distance
(mesh)[source]¶  Parameters
mesh –
Mesh
of points to calculate Ry0distance to. Returns
Numpy array of distances in km.
See also
superclass method
for spec of input and result values.This is version specific to the planar surface doesn’t make use of the mesh

get_top_edge_depth
()[source]¶ Overrides
superclass' method
in order to avoid creating a mesh.

get_width
()[source]¶ Return surface’s width value (in km) as computed in the constructor (that is mean value of left and right surface sides).

property
mesh
¶  Returns
a mesh with the 4 corner points tl, tr, bl, br

property
surface_nodes
¶ A single element list containing a planarSurface node

property
top_left
¶

property
top_right
¶

translate
(p1, p2)[source]¶ Translate the surface for a specific distance along a specific azimuth direction.
Parameters are two points (instances of
openquake.hazardlib.geo.point.Point
) representing the direction and an azimuth for translation. The resulting surface corner points will be that far along that azimuth from respective corner points of this surface asp2
is located with respect top1
. Returns
A new
PlanarSurface
object with the same mesh spacing, dip, strike, width, length and depth but with corners longitudes and latitudes translated.
openquake.hazardlib.geo.surface.simple_fault module¶
Module openquake.hazardlib.geo.surface.simple_fault
defines
SimpleFaultSurface
.

class
openquake.hazardlib.geo.surface.simple_fault.
SimpleFaultSurface
(mesh)[source]¶ Bases:
openquake.hazardlib.geo.surface.base.BaseSurface
Represent a fault surface as regular (uniformly spaced) 3D mesh of points.
 Parameters
mesh – Instance of
RectangularMesh
representing surface geometry.
Another way to construct the surface object is to call
from_fault_data()
.
classmethod
check_fault_data
(fault_trace, upper_seismogenic_depth, lower_seismogenic_depth, dip, mesh_spacing)[source]¶ Verify the fault data and raise
ValueError
if anything is wrong.This method doesn’t have to be called by hands before creating the surface object, because it is called from
from_fault_data()
.

classmethod
from_fault_data
(fault_trace, upper_seismogenic_depth, lower_seismogenic_depth, dip, mesh_spacing)[source]¶ Create and return a fault surface using fault source data.
 Parameters
fault_trace (openquake.hazardlib.geo.line.Line) – Geographical line representing the intersection between the fault surface and the earth surface. The line must be horizontal (i.e. all depth values must be equal). If the depths are not given, they are assumed to be zero, meaning the trace intersects the surface at sea level, e.g. fault_trace = Line([Point(1, 1), Point(1, 2)]).
upper_seismo_depth – Minimum depth ruptures can reach, in km (i.e. depth to fault’s top edge).
lower_seismo_depth – Maximum depth ruptures can reach, in km (i.e. depth to fault’s bottom edge).
dip – Dip angle (i.e. angle between fault surface and earth surface), in degrees.
mesh_spacing – Distance between two subsequent points in a mesh, in km.
 Returns
An instance of
SimpleFaultSurface
created using that data.
Uses
check_fault_data()
for checking parameters.

get_dip
()[source]¶ Return the fault dip as the average dip over the fault surface mesh.
The average dip is defined as the weighted mean inclination of top row of mesh cells. See
openquake.hazardlib.geo.mesh.RectangularMesh.get_mean_inclination_and_azimuth()
 Returns
The average dip, in decimal degrees.

classmethod
get_fault_patch_vertices
(rupture_top_edge, upper_seismogenic_depth, lower_seismogenic_depth, dip, index_patch=1)[source]¶ Get surface main vertices. Parameters are the same as for
from_fault_data()
, excluding fault_trace, and mesh spacing. Parameters
rupture_top_edge – A instances of
openquake.hazardlib.geo.line.Line
representing the rupture surface’s top edge.index_patch – Indicate the patch of the fault in order to output the vertices. The fault patch numbering follows the same logic of the righthand rule i.e. patch with index 1 is the first patch along the trace.
 Returns
Four :class:~openquake.hazardlib.geo.point.Point objects representing the four vertices of the target patch.

get_strike
()[source]¶ Return the fault strike as the average strike along the fault trace.
The average strike is defined as the weighted mean azimuth of top row of mesh cells. See
openquake.hazardlib.geo.mesh.RectangularMesh.get_mean_inclination_and_azimuth()
 Returns
The average strike, in decimal degrees.

classmethod
get_surface_vertexes
(fault_trace, upper_seismogenic_depth, lower_seismogenic_depth, dip)[source]¶ Get surface main vertexes.
Parameters are the same as for
from_fault_data()
, excluding mesh spacing. Returns
Instance of
Polygon
describing the surface projection of the simple fault with specified parameters.

get_width
()[source]¶ Return surface’s width (that is surface extension along the dip direction) in km.
The width is computed as the average width along the surface. See
openquake.hazardlib.geo.mesh.RectangularMesh.get_mean_width()

classmethod
hypocentre_patch_index
(hypocentre, rupture_top_edge, upper_seismogenic_depth, lower_seismogenic_depth, dip)[source]¶ This methods finds the index of the fault patch including the hypocentre.
 Parameters
hypocentre –
Point
object representing the location of hypocentre.rupture_top_edge – A instances of
openquake.hazardlib.geo.line.Line
representing the rupture surface’s top edge.upper_seismo_depth – Minimum depth ruptures can reach, in km (i.e. depth to fault’s top edge).
lower_seismo_depth – Maximum depth ruptures can reach, in km (i.e. depth to fault’s bottom edge).
dip – Dip angle (i.e. angle between fault surface and earth surface), in degrees.
 Returns
An integer corresponding to the index of the fault patch which contains the hypocentre.

classmethod
surface_projection_from_fault_data
(fault_trace, upper_seismogenic_depth, lower_seismogenic_depth, dip)[source]¶ Get a surface projection of the simple fault surface.
Parameters are the same as for
from_fault_data()
, excluding mesh spacing. Returns
Instance of
Polygon
describing the surface projection of the simple fault with specified parameters.

openquake.hazardlib.geo.surface.simple_fault.
simple_fault_node
(fault_trace, dip, upper_depth, lower_depth)[source]¶  Parameters
fault_trace – an object with an attribute .points
dip – dip parameter
upper_depth – upper seismogenic depth
lower_depth – lower seismogenic depth
 Returns
a Node of kind simpleFaultGeometry
Module contents¶
Package openquake.hazardlib.geo.surface
contains base and specific
implementations of earthquake rupture surfaces.