Calculators¶
Package openquake.hazardlib.calc
contains hazard calculator modules
and utilities for them, such as filters
.
Stochastic event set¶
openquake.hazardlib.calc.stochastic
contains
stochastic_event_set()
.

openquake.hazardlib.calc.stochastic.
stochastic_event_set
(sources, sites=None, source_site_filter=<function <lambda>>, rupture_site_filter=<function <lambda>>)[source]¶ Generates a ‘Stochastic Event Set’ (that is a collection of earthquake ruptures) representing a possible realization of the seismicity as described by a source model.
The calculator loops over sources. For each source, it loops over ruptures. For each rupture, the number of occurrence is randomly sampled by calling
openquake.hazardlib.source.rupture.BaseProbabilisticRupture.sample_number_of_occurrences()
Note
This calculator 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
Parameters:  sources – An iterator of seismic sources objects (instances of subclasses
of
BaseSeismicSource
).  sites – A list of sites to consider (or None)
 source_site_filter – The source filter to use (only meaningful is sites is not None)
 source_site_filter – The rupture filter to use (only meaningful is sites is not None)
Returns: Generator of
Rupture
objects that are contained in an event set. Some ruptures can be missing from it, others can appear one or more times in a row. sources – An iterator of seismic sources objects (instances of subclasses
of
Hazard curve¶
openquake.hazardlib.calc.hazard_curve
implements
hazard_curves()
.

openquake.hazardlib.calc.hazard_curve.
agg_curves
(acc, curves)[source]¶ Aggregate hazard curves by composing the probabilities.
Parameters:  acc – an accumulator array
 curves – an array of hazard curves
Returns: a new accumulator

openquake.hazardlib.calc.hazard_curve.
calc_hazard_curves
(sources, sites, imtls, gsim_by_trt, truncation_level=None, source_site_filter=<function <lambda>>, rupture_site_filter=<function <lambda>>, maximum_distance=None)[source]¶ Compute hazard curves on a list of sites, given a set of seismic sources and a set of ground shaking intensity models (one per tectonic region type considered in the seismic sources).
Probability of ground motion exceedance is computed using the following formula
P(X≥xT) = 1  ∏ ∏ Prup_ij(X<xT)
where
P(X≥xT)
is the probability that the ground motion parameterX
is exceeding levelx
one or more times in a time spanT
, andPrup_ij(X<xT)
is the probability that the jth rupture of the ith source is not producing any ground motion exceedance in time spanT
. The first product∏
is done over sources, while the second one is done over ruptures in a source.The above formula computes the probability of having at least one ground motion exceedance in a time span as 1 minus the probability that none of the ruptures in none of the sources is causing a ground motion exceedance in the same time span. The basic assumption is that seismic sources are independent, and ruptures in a seismic source are also independent.
Parameters:  sources – A sequence of seismic sources objects (instances of subclasses
of
BaseSeismicSource
).  sites – Instance of
SiteCollection
object, representing sites of interest.  imtls – Dictionary mapping intensity measure type strings to lists of intensity measure levels.
 gsim_by_trt – Dictionary mapping tectonic region types (members
of
openquake.hazardlib.const.TRT
) toGMPE
orIPE
objects.  truncation_level – Float, number of standard deviations for truncation of the intensity distribution.
 source_site_filter – Optional sourcesite filter function. See
openquake.hazardlib.calc.filters
.  rupture_site_filter – Optional rupturesite filter function. See
openquake.hazardlib.calc.filters
.
Returns: An array of size N, where N is the number of sites, which elements are records with fields given by the intensity measure types; the size of each field is given by the number of levels in
imtls
. sources – A sequence of seismic sources objects (instances of subclasses
of

openquake.hazardlib.calc.hazard_curve.
hazard_curves
(sources, sites, imtls, gsim_by_trt, truncation_level=None, source_site_filter=<function <lambda>>, rupture_site_filter=<function <lambda>>)[source]¶ Deprecated. It does the same job of
openquake.hazardlib.calc.hazard_curve.calc_hazard_curves()
, with the only difference that the intensity measure types in input and output are hazardlib objects instead of simple strings.

openquake.hazardlib.calc.hazard_curve.
hazard_curves_per_trt
(sources, sites, imtls, gsims, truncation_level=None, source_site_filter=<function <lambda>>, rupture_site_filter=<function <lambda>>, maximum_distance=None, bbs=(), monitor=<DummyMonitor>)[source]¶ Compute the hazard curves for a set of sources belonging to the same tectonic region type for all the GSIMs associated to that TRT. The arguments are the same as in
calc_hazard_curves()
, except forgsims
, which is a list of GSIM instances.Returns: A list of G arrays of size N, where N is the number of sites and G the number of gsims. Each array contains records with fields given by the intensity measure types; the size of each field is given by the number of levels in imtls
.
GroundMotion Fields¶
Module gmf
exports
ground_motion_fields()
.

class
openquake.hazardlib.calc.gmf.
GmfComputer
(rupture, sites, imts, gsims, truncation_level=None, correlation_model=None)[source]¶ Given an earthquake rupture, the ground motion field computer computes ground shaking over a set of sites, by randomly sampling a ground shaking intensity model. The usage is:
gmfcomputer = GmfComputer(rupture, r_sites, imts, gsims, truncation_level, correlation_model) gmf1 = gmfcomputer.compute(seed1) gmf2 = gmfcomputer.compute(seed2)
 :param
openquake.hazardlib.source.rupture.Rupture
rupture:  Rupture to calculate ground motion fields radiated from.
 :param
openquake.hazardlib.site.SiteCollection
sites:  Sites of interest to calculate GMFs.
Parameters:  imts – Sorted list of intensity measure type strings
 gsims – Groundshaking intensity models, instances of subclass of either
GMPE
orIPE
, sorted lexicographically.  truncation_level – Float, number of standard deviations for truncation of the intensity
distribution, or
None
.  correlation_model – Instance of correlation model object. See
openquake.hazardlib.correlation
. Can beNone
, in which case noncorrelated ground motion fields are calculated. Correlation model is not used iftruncation_level
is zero.
 :param

openquake.hazardlib.calc.gmf.
ground_motion_fields
(rupture, sites, imts, gsim, truncation_level, realizations, correlation_model=None, rupture_site_filter=<function <lambda>>, seed=None)[source]¶ Given an earthquake rupture, the ground motion field calculator computes ground shaking over a set of sites, by randomly sampling a ground shaking intensity model. A ground motion field represents a possible ‘realization’ of the ground shaking due to an earthquake rupture. If a nontrivial filtering function is passed, the final result is expanded and filled with zeros in the places corresponding to the filtered out sites.
Note
This calculator 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
Parameters:  rupture (openquake.hazardlib.source.rupture.Rupture) – Rupture to calculate ground motion fields radiated from.
 sites (openquake.hazardlib.site.SiteCollection) – Sites of interest to calculate GMFs.
 imts – List of intensity measure type objects (see
openquake.hazardlib.imt
).  gsim – Groundshaking intensity model, instance of subclass of either
GMPE
orIPE
.  truncation_level – Float, number of standard deviations for truncation of the intensity
distribution, or
None
.  realizations – Integer number of GMF realizations to compute.
 correlation_model – Instance of correlation model object. See
openquake.hazardlib.correlation
. Can beNone
, in which case noncorrelated ground motion fields are calculated. Correlation model is not used iftruncation_level
is zero.  rupture_site_filter – Optional rupturesite filter function. See
openquake.hazardlib.calc.filters
.  seed (int) – The seed used in the numpy random number generator
Returns: Dictionary mapping intensity measure type objects (same as in parameter
imts
) to 2d numpy arrays of floats, representing different realizations of ground shaking intensity for all sites in the collection. First dimension represents sites and second one is for realizations.
Correlation models¶
Module openquake.hazardlib.correlation
defines correlation models for
spatiallydistributed groundshaking intensities.

class
openquake.hazardlib.correlation.
BaseCorrelationModel
[source]¶ Base class for correlation models for spatiallydistributed groundshaking intensities.

apply_correlation
(sites, imt, residuals)[source]¶ Apply correlation to randomly sampled residuals.
Parameters:  sites –
SiteCollection
residuals were sampled for.  imt – Intensity measure type object, see
openquake.hazardlib.imt
.  residuals – 2d numpy array of sampled residuals, where first dimension
represents sites (the length as
sites
parameter) and second one represents different realizations (samples).
Returns: Array of the same structure and semantics as
residuals
but with correlations applied. sites –

get_lower_triangle_correlation_matrix
(sites, imt)[source]¶ Get lowertriangle matrix as a result of Choleskydecomposition of correlation matrix.
The resulting matrix should have zeros on values above the main diagonal.
The actual implementations of
BaseCorrelationModel
interface might calculate the matrix considering site collection and IMT (likeJB2009CorrelationModel
does) or might have it preconstructed for a specific site collection and IMT, in which case they will need to make sure that parameters to this function match parameters that were used to precalculate decomposed correlation matrix.Parameters:  sites –
SiteCollection
to create correlation matrix for.  imt – Intensity measure type object, see
openquake.hazardlib.imt
.
 sites –


class
openquake.hazardlib.correlation.
JB2009CorrelationModel
(vs30_clustering)[source]¶ “Correlation model for spatially distributed groundmotion intensities” by Nirmal Jayaram and Jack W. Baker. Published in Earthquake Engineering and Structural Dynamics 2009; 38, pages 16871708.
Parameters: vs30_clustering – Boolean value to indicate whether “Case 1” or “Case 2” from page 1700 should be applied. True
value means that Vs 30 values show or are expected to show clustering (“Case 2”),False
means otherwise.
get_lower_triangle_correlation_matrix
(sites, imt)[source]¶ See
BaseCorrelationModel.get_lower_triangle_correlation_matrix()
.

Disaggregation¶
openquake.hazardlib.calc.disagg
contains
disaggregation()
as well as several aggregation functions for
extracting a specific PMF from the result of disaggregation()
.

openquake.hazardlib.calc.disagg.
disaggregation
(sources, site, imt, iml, gsims, truncation_level, n_epsilons, mag_bin_width, dist_bin_width, coord_bin_width, source_site_filter=<function <lambda>>, rupture_site_filter=<function <lambda>>)[source]¶ Compute “Disaggregation” matrix representing conditional probability of an intensity mesaure type
imt
exceeding, at least once, an intensity measure leveliml
at a geographical locationsite
, given rupture scenarios classified in terms of: rupture magnitude
 JoynerBoore distance from rupture surface to site
 longitude and latitude of the surface projection of a rupture’s point
closest to
site
 epsilon: number of standard deviations by which an intensity measure level deviates from the median value predicted by a GSIM, given the rupture parameters
 rupture tectonic region type
In other words, the disaggregation matrix allows to compute the probability of each scenario with the specified properties (e.g., magnitude, or the magnitude and distance) to cause one or more exceedences of a given hazard level.
For more detailed information about the disaggregation, see for instance “Disaggregation of Seismic Hazard”, Paolo Bazzurro, C. Allin Cornell, Bulletin of the Seismological Society of America, Vol. 89, pp. 501520, April 1999.
Parameters:  sources – Seismic source model, as for
PSHA
calculator it should be an iterator of seismic sources.  site –
Site
of interest to calculate disaggregation matrix for.  imt – Instance of
intensity measure type
class.  iml – Intensity measure level. A float value in units of
imt
.  gsims – Tectonic region type to GSIM objects mapping.
 truncation_level – Float, number of standard deviations for truncation of the intensity distribution.
 n_epsilons – Integer number of epsilon histogram bins in the result matrix.
 mag_bin_width – Magnitude discretization step, width of one magnitude histogram bin.
 dist_bin_width – Distance histogram discretization step, in km.
 coord_bin_width – Longitude and latitude histograms discretization step, in decimal degrees.
 source_site_filter – Optional sourcesite filter function. See
openquake.hazardlib.calc.filters
.  rupture_site_filter – Optional rupturesite filter function. See
openquake.hazardlib.calc.filters
.
Returns: A tuple of two items. First is itself a tuple of bin edges information for (in specified order) magnitude, distance, longitude, latitude, epsilon and tectonic region types.
Second item is 6darray representing the full disaggregation matrix. Dimensions are in the same order as bin edges in the first item of the result tuple. The matrix can be used directly by pmfextractor functions.
PMFExtractors¶

openquake.hazardlib.calc.disagg.
mag_pmf
(matrix)[source]¶ Fold full disaggregation matrix to magnitude PMF.
Returns: 1d array, a histogram representing magnitude PMF.

openquake.hazardlib.calc.disagg.
dist_pmf
(matrix)[source]¶ Fold full disaggregation matrix to distance PMF.
Returns: 1d array, a histogram representing distance PMF.

openquake.hazardlib.calc.disagg.
trt_pmf
(matrix)[source]¶ Fold full disaggregation matrix to tectonic region type PMF.
Returns: 1d array, a histogram representing tectonic region type PMF.

openquake.hazardlib.calc.disagg.
mag_dist_pmf
(matrix)[source]¶ Fold full disaggregation matrix to magnitude / distance PMF.
Returns: 2d array. First dimension represents magnitude histogram bins, second one – distance histogram bins.

openquake.hazardlib.calc.disagg.
mag_dist_eps_pmf
(matrix)[source]¶ Fold full disaggregation matrix to magnitude / distance / epsilon PMF.
Returns: 3d array. First dimension represents magnitude histogram bins, second one – distance histogram bins, third one – epsilon histogram bins.

openquake.hazardlib.calc.disagg.
lon_lat_pmf
(matrix)[source]¶ Fold full disaggregation matrix to longitude / latitude PMF.
Returns: 2d array. First dimension represents longitude histogram bins, second one – latitude histogram bins.
Filters¶
Module filters
contain filter functions for
calculators.
Filters are functions (or other callable objects) that should take generators and return generators. There are two different kinds of filter functions:
 Sourcesite filters. Those functions take a generator of twoitem tuples,
each pair consists of seismic source object (that is, an instance of
a subclass of
BaseSeismicSource
) and a site collection (instance ofSiteCollection
).  Rupturesite filters. Those also take a generator of pairs, but in this
case the first item in the pair is a rupture object (instance of
Rupture
). The second element in generator items is still site collection.
The purpose of both kinds of filters is to limit the amount of calculation
to be done based on some criteria, like the distance between the source
and the site. So common design feature of all the filters is the loop over
pairs of the provided generator, filtering the sites collection, and if
there are no items left in it, skipping the pair and continuing to the next
one. If some sites need to be considered together with that source / rupture,
the pair gets generated out, with a (possibly) limited
site collection.
Consistency of filters’ input and output stream format allows several filters (obviously, of the same kind) to be chained together.
Filter functions should not make assumptions about the ordering of items in the original generator or draw more than one pair at once. Ideally, they should also perform reasonably fast (filtering stage that takes longer than the actual calculation on unfiltered collection only decreases performance).
Module openquake.hazardlib.calc.filters
exports one distancebased
filter function of each kind (see source_site_distance_filter()
and
rupture_site_distance_filter()
) as well as “no operation” filters
(source_site_noop_filter()
and rupture_site_noop_filter()
).

openquake.hazardlib.calc.filters.
filter_sites_by_distance_to_rupture
(rupture, integration_distance, sites)[source]¶ Filter out sites from the collection that are further from the rupture than some arbitrary threshold.
Parameters:  rupture – Instance of
Rupture
that was generated by :meth: openquake.hazardlib.source.base.BaseSeismicSource.iter_ruptures of an instance of this class.  integration_distance – Threshold distance in km.
 sites – Instance of
openquake.hazardlib.site.SiteCollection
to filter.
Returns: Filtered
SiteCollection
.This function is similar to
openquake.hazardlib.source.base.BaseSeismicSource.filter_sites_by_distance_to_source()
. The same notes about filtering criteria apply. Site should not be filtered out if it is not further than the integration distance from the rupture’s surface projection along the great circle arc (this is known as JoynerBoore distance, :meth:` openquake.hazardlib.geo.surface.base.BaseQuadrilateralSurface.get_joyner_boore_distance`). rupture – Instance of

openquake.hazardlib.calc.filters.
rupture_site_distance_filter
(integration_distance)[source]¶ Rupturesite filter based on distance.
Parameters: integration_distance – Threshold distance in km, this value gets passed straight to openquake.hazardlib.calc.filters.filter_sites_by_distance_to_rupture()
which is what is actually used for filtering.

openquake.hazardlib.calc.filters.
rupture_site_noop_filter
(ruptures_sites)¶ Rupturesite “noop” filter, same as
source_site_noop_filter()
.

openquake.hazardlib.calc.filters.
source_site_distance_filter
(integration_distance)[source]¶ Sourcesite filter based on distance.
Parameters: integration_distance – Threshold distance in km, this value gets passed straight to openquake.hazardlib.source.base.BaseSeismicSource.filter_sites_by_distance_to_source()
which is what is actually used for filtering.

openquake.hazardlib.calc.filters.
source_site_noop_filter
(sources_sites)¶ Transparent sourcesite “noop” filter – behaves like a real filter but never filters anything out and doesn’t have any overhead.