Seismic sources and ruptures

Package openquake.hazardlib.source deals with various types of seismic sources.

Earthquake rupture

Module openquake.hazardlib.source.rupture defines classes Rupture, BaseProbabilisticRupture and its subclasses NonParametricProbabilisticRupture and ParametricProbabilisticRupture

class openquake.hazardlib.source.rupture.BaseProbabilisticRupture(mag, rake, tectonic_region_type, hypocenter, surface, source_typology)

Base class for a probabilistic rupture, that is a Rupture associated with a temporal occurrence model defining probability of rupture occurrence in a certain time span.

get_probability_no_exceedance(poes)

Compute and return the probability that in the time span for which the rupture is defined, the rupture itself never generates a ground motion value higher than a given level at a given site.

Such calculation is performed starting from the conditional probability that an occurrence of the current rupture is producing a ground motion value higher than the level of interest at the site of interest.

The actual formula used for such calculation depends on the temporal occurrence model the rupture is associated with.

The calculation can be performed for multiple intensity measure levels and multiple sites in a vectorized fashion.

Parameters:poes – 2D numpy array containing conditional probabilities the the a rupture occurrence causes a ground shaking value exceeding a ground motion level at a site. First dimension represent sites, second dimension intensity measure levels. poes can be obtained calling the method.

sample_number_of_occurrences()

Randomly sample number of occurrences from temporal occurrence model probability distribution.

Note

This method is using random numbers. In order to reproduce the same results numpy random numbers generator needs to be seeded, see http://docs.scipy.org/doc/numpy/reference/generated/numpy.random.seed.html

Returns:int, Number of rupture occurrences

class openquake.hazardlib.source.rupture.NonParametricProbabilisticRupture(mag, rake, tectonic_region_type, hypocenter, surface, source_typology, pmf)

Probabilistic rupture for which the probability distribution for rupture occurrence is described through a generic probability mass function.

Parameters:pmf –

Instance of openquake.hazardlib.pmf.PMF. Values in the abscissae represent number of rupture occurrences (in increasing order, staring from 0) and values in the ordinates represent associated probabilities. Example: if, for a given time span, a rupture has probability 0.8 to not occurr, 0.15 to occur once, and 0.05 to occur twice, the pmf can be defined as

pmf = PMF([(Decimal('0.8'), 0), (Decimal('0.15'), 1),
            Decimal('0.05', 2)])

Raises:ValueError – If number of ruptures in pmf do not start from 0, are not defined in increasing order, and if they are not defined with unit step

get_probability_no_exceedance(poes)

See superclass method for spec of input and result values.

Uses the formula

∑ p(k|T) * p(X<x|rup)^k

where p(k|T) is the probability that the rupture occurs k times in the time span T, p(X<x|rup) is the probability that a rupture occurrence does not cause a ground motion exceedance, and the summation ∑ is done over the number of occurrences k.

p(k|T) is given by the constructor’s parameter pmf, and p(X<x|rup) is computed as 1 - poes.

sample_number_of_occurrences()

See superclass method for spec of input and result values.

Uses ‘Inverse Transform Sampling’ method.

class openquake.hazardlib.source.rupture.ParametricProbabilisticRupture(mag, rake, tectonic_region_type, hypocenter, surface, source_typology, occurrence_rate, temporal_occurrence_model)

Rupture associated with an occurrence rate and a temporal occurrence model.

Parameters:

• occurrence_rate – Number of times rupture happens per year.
• temporal_occurrence_model – Temporal occurrence model assigned for this rupture. Should be an instance of openquake.hazardlib.tom.PoissonTOM.

Raises:

ValueError – If occurrence rate is not positive.

get_probability_no_exceedance(poes)

See superclass method for spec of input and result values.

Uses get_probability_no_exceedance()

get_probability_one_occurrence()

Return the probability of this rupture to occur exactly one time.

Uses :meth: ~openquake.hazardlib.tom.PoissonTOM.get_probability_one_occurrence of an assigned temporal occurrence model.

get_probability_one_or_more_occurrences()

Return the probability of this rupture to occur one or more times.

Uses get_probability_one_or_more_occurrences() of an assigned temporal occurrence model.

sample_number_of_occurrences()

Draw a random sample from the distribution and return a number of events to occur.

Uses :meth: ~openquake.hazardlib.tom.PoissonTOM.sample_number_of_occurrences of an assigned temporal occurrence model.

class openquake.hazardlib.source.rupture.Rupture(mag, rake, tectonic_region_type, hypocenter, surface, source_typology)

Rupture object represents a single earthquake rupture.

Parameters:

• mag – Magnitude of the rupture.
• rake – Rake value of the rupture. See NodalPlane.
• tectonic_region_type – Rupture’s tectonic regime. One of constants in openquake.hazardlib.const.TRT.
• hypocenter – A Point, rupture’s hypocenter.
• surface – An instance of subclass of BaseSurface. Object representing the rupture surface geometry.
• source_typology – Subclass of BaseSeismicSource (class object, not an instance) referencing the typology of the source that produced this rupture.

Raises:

ValueError – If magnitude value is not positive, hypocenter is above the earth surface or tectonic region type is unknown.

Point source

Module openquake.hazardlib.source.point defines PointSource.

class openquake.hazardlib.source.point.PointSource(source_id, name, tectonic_region_type, mfd, rupture_mesh_spacing, magnitude_scaling_relationship, rupture_aspect_ratio, temporal_occurrence_model, upper_seismogenic_depth, lower_seismogenic_depth, location, nodal_plane_distribution, hypocenter_distribution)

Point source typology represents seismicity on a single geographical location.

Parameters:

• upper_seismogenic_depth – Minimum depth an earthquake rupture can reach, in km.
• lower_seismogenic_depth – Maximum depth an earthquake rupture can reach, in km.
• location – Point object representing the location of the seismic source. The depth value of that point is ignored.
• nodal_plane_distribution – PMF object with values that are instances of openquake.hazardlib.geo.nodalplane.NodalPlane. Shows the distribution of probability for rupture to have the certain nodal plane.
• hypocenter_distribution – PMF with values being float numbers in km representing the depth of the hypocenter. Latitude and longitude of the hypocenter is always set to ones of location.

See also openquake.hazardlib.source.base.ParametricSeismicSource for description of other parameters.

Raises:ValueError – If upper seismogenic depth is negative or below lower seismogenic depth, if one or more of hypocenter depth values is shallower than upper seismogenic depth or deeper than lower seismogenic depth.

_get_max_rupture_projection_radius()

Find a maximum radius of a circle on Earth surface enveloping a rupture produced by this source.

Returns:Half of maximum rupture’s diagonal surface projection.

_get_rupture_dimensions(mag, nodal_plane)

Calculate and return the rupture length and width for given magnitude mag and nodal plane.

Parameters:nodal_plane – Instance of openquake.hazardlib.geo.nodalplane.NodalPlane. Returns:Tuple of two items: rupture length in width in km.

The rupture area is calculated using method get_median_area() of source’s magnitude-scaling relationship. In any case the returned dimensions multiplication is equal to that value. Than the area is decomposed to length and width with respect to source’s rupture aspect ratio.

If calculated rupture width being inclined by nodal plane’s dip angle would not fit in between upper and lower seismogenic depth, the rupture width is shrunken to a maximum possible and rupture length is extended to preserve the same area.

_get_rupture_surface(mag, nodal_plane, hypocenter)

Create and return rupture surface object with given properties.

Parameters:

• mag – Magnitude value, used to calculate rupture dimensions, see _get_rupture_dimensions().
• nodal_plane – Instance of openquake.hazardlib.geo.nodalplane.NodalPlane describing the rupture orientation.
• hypocenter – Point representing rupture’s hypocenter.

Returns:

Instance of PlanarSurface.

_iter_ruptures_at_location(temporal_occurrence_model, location, rate_scaling_factor=1)

The common part of :meth: openquake.hazardlib.source.point.Point.iter_ruptures shared between point source and AreaSource.

Parameters:

• temporal_occurrence_model – The same object as given to :meth: openquake.hazardlib.source.base.BaseSeismicSource.iter_ruptures.
• location – A Point object representing the hypocenter location. In case of PointSource it is the one provided to constructor, and for area source the location points are taken from polygon discretization.
• rate_scaling_factor – Positive float number to multiply occurrence rates by. It is used by area source to scale the occurrence rates with respect to number of locations. Point sources use no scaling (rate_scaling_factor = 1).

count_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.count_ruptures.

filter_sites_by_distance_to_source(integration_distance, sites)

Filter sites that are closer than maximum rupture projection radius plus integration distance along the great circle arc from source’s epicenter location. Overrides base class' method in order to avoid using polygon.

get_rupture_enclosing_polygon(dilation=0)

Returns a circle-shaped polygon with radius equal to dilation plus _get_max_rupture_projection_radius().

See superclass method for parameter and return value definition.

iter_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.iter_ruptures.

Generate one rupture for each combination of magnitude, nodal plane and hypocenter depth.

Area source

Module openquake.hazardlib.source.area defines AreaSource.

class openquake.hazardlib.source.area.AreaSource(source_id, name, tectonic_region_type, mfd, rupture_mesh_spacing, magnitude_scaling_relationship, rupture_aspect_ratio, temporal_occurrence_model, upper_seismogenic_depth, lower_seismogenic_depth, nodal_plane_distribution, hypocenter_distribution, polygon, area_discretization)

Area source represents uniform seismicity occurring over a geographical region.

Parameters:

• polygon – An instance of openquake.hazardlib.geo.polygon.Polygon that defines source’s area.
• area_discretization – Float number, polygon area discretization spacing in kilometers. See openquake.hazardlib.source.area.AreaSource.iter_ruptures().

Other parameters (except location) are the same as for PointSource.

count_ruptures()

See openquake.hazardlib.source.base.BaseSeismicSource.count_ruptures() for description of parameters and return value.

filter_sites_by_distance_to_source(integration_distance, sites)

Overrides implementation of the point source class just to call the base class one.

get_rupture_enclosing_polygon(dilation=0)

Extends the area source polygon by dilation plus _get_max_rupture_projection_radius().

See superclass method for parameter and return value definition.

iter_ruptures()

See openquake.hazardlib.source.base.BaseSeismicSource.iter_ruptures() for description of parameters and return value.

Area sources are treated as a collection of point sources (see openquake.hazardlib.source.point) with uniform parameters. Ruptures of area source are just a union of ruptures of those point sources. The actual positions of the implied point sources form a uniformly spaced mesh on the polygon. Polygon’s method :meth: ~openquake.hazardlib.geo.polygon.Polygon.discretize is used for creating a mesh of points on the source’s area. Constructor’s parameter area_discretization is used as polygon’s discretization spacing (not to be confused with rupture surface’s mesh spacing which is as well provided to the constructor).

The ruptures’ occurrence rates are rescaled with respect to number of points the polygon discretizes to.

Simple fault

Module openquake.hazardlib.source.simple_fault defines SimpleFaultSource.

class openquake.hazardlib.source.simple_fault.SimpleFaultSource(source_id, name, tectonic_region_type, mfd, rupture_mesh_spacing, magnitude_scaling_relationship, rupture_aspect_ratio, temporal_occurrence_model, upper_seismogenic_depth, lower_seismogenic_depth, fault_trace, dip, rake)

Simple fault source typology represents seismicity occurring on a fault surface with simple geometry.

Parameters:

• upper_seismogenic_depth – Minimum depth an earthquake rupture can reach, in km.
• lower_seismogenic_depth – Maximum depth an earthquake rupture can reach, in km.
• fault_trace – A Line representing the line of intersection between the fault plane and the Earth’s surface.
• dip – Angle between earth surface and fault plane in decimal degrees.
• rake – Angle describing rupture propagation direction in decimal degrees.

See also openquake.hazardlib.source.base.ParametricSeismicSource for description of other parameters.

Raises:ValueError – If check_fault_data() fails, if rake value is invalid and if rupture mesh spacing is too high for the lowest magnitude value.

count_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.count_ruptures.

get_rupture_enclosing_polygon(dilation=0)

Uses openquake.hazardlib.geo.surface.simple_fault.SimpleFaultSurface.surface_projection_from_fault_data() for getting the fault’s surface projection and then calls its dilate() method passing in dilation parameter.

See superclass method for parameter and return value definition.

iter_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.iter_ruptures.

Generates a ruptures using the “floating” algorithm: for all the magnitude values of assigned MFD calculates the rupture size with respect to MSR and aspect ratio and then places ruptures of that size on the surface of the whole fault source. The occurrence rate of each of those ruptures is the magnitude occurrence rate divided by the number of ruptures that can be placed in a fault.

Complex fault

Module openquake.hazardlib.source.complex_fault defines ComplexFaultSource.

class openquake.hazardlib.source.complex_fault.ComplexFaultSource(source_id, name, tectonic_region_type, mfd, rupture_mesh_spacing, magnitude_scaling_relationship, rupture_aspect_ratio, temporal_occurrence_model, edges, rake)

Complex fault source typology represents seismicity occurring on a fault surface with an arbitrarily complex geometry.

Parameters:

• edges – A list of Line objects, representing fault source geometry. See openquake.hazardlib.geo.surface.complex_fault.ComplexFaultSurface.from_fault_data().
• rake – Angle describing rupture propagation direction in decimal degrees.

See also openquake.hazardlib.source.base.ParametricSeismicSource for description of other parameters.

Raises:ValueError – If check_fault_data() fails or if rake value is invalid.

count_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.count_ruptures.

get_rupture_enclosing_polygon(dilation=0)

Uses openquake.hazardlib.geo.surface.complex_fault.ComplexFaultSurface.surface_projection_from_fault_data() for getting the fault’s surface projection and then calls its dilate() method passing in dilation parameter.

See superclass method for parameter and return value definition.

iter_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.iter_ruptures.

Uses _float_ruptures() for finding possible rupture locations on the whole fault surface.

openquake.hazardlib.source.complex_fault._float_ruptures(rupture_area, rupture_length, cell_area, cell_length)

Get all possible unique rupture placements on the fault surface.

Parameters:

• rupture_area – The area of the rupture to float on the fault surface, in squared km.
• rupture_length – The target length (spatial extension along fault trace) of the rupture, in km.
• cell_area – 2d numpy array representing area of mesh cells in squared km.
• cell_length – 2d numpy array of the shape as cell_area representing cells’ length in km.

Returns:

A list of slice objects. Number of items in the list is equal to number of possible locations of the requested rupture on the fault surface. Each slice can be used to get a portion of the whole fault surface mesh that would represent the location of the rupture.

Characteristic source

Module openquake.hazardlib.source.characteristic defines CharacteristicFaultSource.

class openquake.hazardlib.source.characteristic.CharacteristicFaultSource(source_id, name, tectonic_region_type, mfd, temporal_occurrence_model, surface, rake)

Characteristic source typology represents seismicity occuring on a generic fault surface with seismic events rupturing the entire fault surface independently of their magnitude values.

Characteristic source typology can be used to model individual faults or fault segments that tend to produce essentialy same size earthquakes (see for instance: Schwartz, D. P., K. J. Coppersmith, Fault behavior and characteristic earthquakes: Examples from the Wasatch and San Andreas fault zones, J. Geophys. Res., 89, 5681-5698, 1984)

Parameters:

• surface – Fault surface, see openquake.hazardlib.geo.surface.
• rake – Angle describing rupture propagation direction in decimal degrees.

See also openquake.hazardlib.source.base.ParametricSeismicSource for description of other parameters.

Note that a CharacteristicFaultSource does not need any mesh spacing, magnitude scaling relationship, and aspect ratio, therefore the constructor set these parameters to None.

count_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.count_ruptures.

get_rupture_enclosing_polygon(dilation=0)

Uses :meth: openquake.hazardlib.geo.surface.base.BaseSurface.get_bounding_box() and from bounding box coordinates create openquake.hazardlib.geo.mesh.RectangularMesh and then calls openquake.hazardlib.geo.mesh.Mesh.get_convex_hull() to get a polygon representation of the bounding box. Note that this is needed to cope with the situation of a vertical rupture for which the bounding box collapses to a line. In this case the method get_convex_hull() returns a valid polygon obtained by expanding the line by a small distance. Finally, a polygon is returned by calling dilate() passing in the dilation parameter.

See superclass method for parameter and return value definition.

iter_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.iter_ruptures.

For each magnitude value in the given MFD, return an earthquake rupture with a surface always equal to the given surface.

Non Parametric source

Module openquake.hazardlib.source.non_parametric defines NonParametricSeismicSource

class openquake.hazardlib.source.non_parametric.NonParametricSeismicSource(source_id, name, tectonic_region_type, data)

Non Parametric Seismic Source explicitly defines earthquake ruptures in the constructor. That is earthquake ruptures are not generated algorithmically from a set of source parameters.

Ruptures’ rectonic region types are overwritten by source tectonic region type.

Parameters:data – List of tuples. Each tuple must contain two items. The first item must be an instance of openquake.hazardlib.source.rupture.Rupture. The second item must be an instance of openquake.hazardlib.pmf.PMF describing the probability of the rupture to occur N times (the PMF must be defined from a minimum number of occurrences equal to 0)

count_ruptures()

See :meth: openquake.hazardlib.source.base.BaseSeismicSource.count_ruptures.

get_min_max_mag()

Return the minimum and maximum magnitudes of the ruptures generated by the source

get_rupture_enclosing_polygon(dilation=0)

Create instance of openquake.hazardlib.geo.surface.multi.MultiSurface from all ruptures’ surfaces and compute its bounding box. Calculate convex hull of bounding box, and return it dilated by dilation.

Parameters:dilation – A buffer distance in km to extend the polygon borders to. Returns:Instance of openquake.hazardlib.geo.polygon.Polygon.

iter_ruptures()

Get a generator object that yields probabilistic ruptures the source consists of.

Returns:Generator of instances of :class: ~openquake.hazardlib.source.rupture.NonParametricProbabilisticRupture.

Abstract base seismic source

Module openquake.hazardlib.source.base defines a base class for seismic sources.

class openquake.hazardlib.source.base.BaseSeismicSource(source_id, name, tectonic_region_type)

Base class representing a seismic source, that is a structure generating earthquake ruptures.

Parameters:

• source_id – Some (numeric or literal) source identifier. Supposed to be unique within the source model.
• name – String, a human-readable name of the source.
• tectonic_region_type – Source’s tectonic regime. See openquake.hazardlib.const.TRT.

count_ruptures()

Return the number of ruptures that will be generated by the source.

filter_sites_by_distance_to_source(integration_distance, sites)

Filter out sites from the collection that are further from the source than some arbitrary threshold.

Parameters:

• integration_distance – Distance in km representing a threshold: sites that are further than that distance from the closest rupture produced by the source should be excluded.
• sites – Instance of openquake.hazardlib.site.SiteCollection to filter.

Returns:

Filtered SiteCollection.

Method can be overridden by subclasses in order to achieve higher performance for a specific typology. Base class method calls get_rupture_enclosing_polygon() with integration_distance as a dilation value and then filters site collection by checking :meth: containment <openquake.hazardlib.geo.polygon.Polygon.intersects> of site locations.

The main criteria for this method to decide whether a site should be filtered out or not is the minimum distance between the site and all the ruptures produced by the source. If at least one rupture is closer (in terms of great circle distance between surface projections) than integration distance to a site, it should not be filtered out. However, it is important not to make this method too computationally intensive. If short-circuits are taken, false positives are generally better than false negatives (it’s better not to filter a site out if there is some uncertainty about its distance).

get_min_max_mag()

Return minimum and maximum magnitudes of the ruptures generated by the source.

get_rupture_enclosing_polygon(dilation=0)

Get a polygon which encloses all the ruptures generated by the source.

The rupture enclosing polygon is meant to be used in all hazard calculators to filter out sources whose ruptures the user wants to be neglected because they are too far from the locations of interest.

For performance reasons, the get_rupture_enclosing_polygon() should compute the polygon, without creating all the ruptures. The rupture enclosing polygon may not be necessarily the minimum enclosing polygon, but must guarantee that all ruptures are within the polygon.

This method must be implemented by subclasses.

Parameters:dilation – A buffer distance in km to extend the polygon borders to. Returns:Instance of openquake.hazardlib.geo.polygon.Polygon.

iter_ruptures()

Get a generator object that yields probabilistic ruptures the source consists of.

Returns:Generator of instances of sublclass of :class: ~openquake.hazardlib.source.rupture.BaseProbabilisticRupture.

class openquake.hazardlib.source.base.ParametricSeismicSource(source_id, name, tectonic_region_type, mfd, rupture_mesh_spacing, magnitude_scaling_relationship, rupture_aspect_ratio, temporal_occurrence_model)

Parametric Seismic Source generates earthquake ruptures from source parameters, and associated probabilities of occurrence are defined through a magnitude frequency distribution and a temporal occurrence model.

Parameters:

• mfd – Magnitude-Frequency distribution for the source. See openquake.hazardlib.mfd.
• rupture_mesh_spacing – The desired distance between two adjacent points in source’s ruptures’ mesh, in km. Mainly this parameter allows to balance the trade-off between time needed to compute the distance between the rupture surface and a site and the precision of that computation.
• magnitude_scaling_relationship – Instance of subclass of openquake.hazardlib.scalerel.base.BaseMSR to describe how does the area of the rupture depend on magnitude and rake.
• rupture_aspect_ratio – Float number representing how much source’s ruptures are more wide than tall. Aspect ratio of 1 means ruptures have square shape, value below 1 means ruptures stretch vertically more than horizontally and vice versa.
• temporal_occurrence_model – Instance of openquake.hazardlib.tom.PoissonTOM defining temporal occurrence model for calculating rupture occurrence probabilities

Raises:

ValueError – If either rupture aspect ratio or rupture mesh spacing is not positive (if not None).

get_annual_occurrence_rates(min_rate=0)

Get a list of pairs “magnitude – annual occurrence rate”.

The list is taken from assigned MFD object (see openquake.hazardlib.mfd.base.BaseMFD.get_annual_occurrence_rates()) with simple filtering by rate applied.

Parameters:min_rate – A non-negative value to filter magnitudes by minimum annual occurrence rate. Only magnitudes with rates greater than that are included in the result list. Returns:A list of two-item tuples – magnitudes and occurrence rates.

get_min_max_mag()

Get the minimum and maximum magnitudes of the ruptures generated by the source from the underlying MFD.