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>>)

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.

Hazard curve

openquake.hazardlib.calc.hazard_curve implements calc_hazard_curves().

openquake.hazardlib.calc.hazard_curve.agg_curves(acc, curves)

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.array_of_curves(pmap, nsites, imtls, gsim_idx=0)

Convert a probability map into an array of length nsites and dtype imt_dt.

Parameters:

• pmap – a dictionary sid -> ProbabilityCurve
• nsites – the number of sites in the full site collection
• imtls – intensity measure types and levels
• gsims_idx – extract the data corresponding to a specific GSIM

openquake.hazardlib.calc.hazard_curve.calc_hazard_curves(sources, sites, imtls, gsim_by_trt, truncation_level=None, source_site_filter=<function <lambda>>, maximum_distance=None)

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≥x|T) = 1 - ∏ ∏ Prup_ij(X<x|T)

where P(X≥x|T) is the probability that the ground motion parameter X is exceeding level x one or more times in a time span T, and Prup_ij(X<x|T) is the probability that the j-th rupture of the i-th source is not producing any ground motion exceedance in time span T. 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) to GMPE or IPE objects.
• truncation_level – Float, number of standard deviations for truncation of the intensity distribution.
• source_site_filter – Optional source-site 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.

openquake.hazardlib.calc.hazard_curve.get_probability_no_exceedance(rupture, sctx, rctx, dctx, imtls, gsims, trunclevel)

Parameters:

• rupture – a Rupture instance
• sctx – the corresponding SiteContext instance
• rctx – the corresponding RuptureContext instance
• dctx – the corresponding DistanceContext instance
• imtls – a dictionary-like object providing the intensity levels
• gsims – the list of GSIMs to use
• trunclevel – the truncation level

Returns:

an array of shape (num_sites, num_levels, num_gsims)

openquake.hazardlib.calc.hazard_curve.hazard_curves_per_trt(sources, sites, imtls, gsims, truncation_level=None, source_site_filter=<function <lambda>>, maximum_distance=None, bbs=(), monitor=<Monitor dummy>)

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 for gsims, which is a list of GSIM instances.

Returns:a ProbabilityMap instance

openquake.hazardlib.calc.hazard_curve.poe_map(src, s_sites, imtls, cmaker, trunclevel, bbs, ctx_mon, pne_mon, disagg_mon)

Compute the ProbabilityMap generated by the given source. Also, store some information in the monitors and optionally in the bounding boxes.

openquake.hazardlib.calc.hazard_curve.zero_curves(num_sites, imtls)

Parameters:

• num_sites – the number of sites
• imtls – the intensity measure levels dictionary

Returns:

an array of zero curves with length num_sites

openquake.hazardlib.calc.hazard_curve.zero_maps(num_sites, imts, poes=())

Parameters:

• num_sites – the number of sites
• imts – the intensity measure types

Returns:

an array of zero curves with length num_sites

Ground-Motion Fields

Module gmf exports ground_motion_fields().

class openquake.hazardlib.calc.gmf.GmfComputer(rupture, sites, imts, gsims, truncation_level=None, correlation_model=None, samples=0)

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.

: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 – a sorted list of Intensity Measure Type strings
• 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 be None, in which case non-correlated ground motion fields are calculated. Correlation model is not used if truncation_level is zero.

calcgmfs(seed, events, rlzs_by_gsim, min_iml=None)

Yield the ground motion field for each seismic event.

Parameters:

• seed – seed for the numpy random number generator
• events – composite array of seismic events (eid, ses, occ, samples)
• rlzs_by_gsim – a dictionary {gsim instance: realizations}

Yields:

tuples (eid, imti, rlz, gmf_sids)

compute(seed, gsim, num_events)

Parameters:

• seed – a random seed
• gsim – a GSIM instance
• num_events – the number of seismic events

Returns:

a 32 bit array of shape (num_imts, num_sites, num_events)

openquake.hazardlib.calc.gmf.ground_motion_fields(rupture, sites, imts, gsim, truncation_level, realizations, correlation_model=None, rupture_site_filter=<function <lambda>>, seed=None)

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 non-trivial 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 – Ground-shaking intensity model, instance of subclass of either GMPE or IPE.
• 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 be None, in which case non-correlated ground motion fields are calculated. Correlation model is not used if truncation_level is zero.
• rupture_site_filter – Optional rupture-site 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 spatially-distributed ground-shaking intensities.

class openquake.hazardlib.correlation.BaseCorrelationModel

Base class for correlation models for spatially-distributed ground-shaking intensities.

apply_correlation(sites, imt, residuals)

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.

get_lower_triangle_correlation_matrix(sites, imt)

Get lower-triangle matrix as a result of Cholesky-decomposition 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 (like JB2009CorrelationModel does) or might have it pre-constructed 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 pre-calculate decomposed correlation matrix.

Parameters:

• sites – SiteCollection to create correlation matrix for.
• imt – Intensity measure type object, see openquake.hazardlib.imt.

class openquake.hazardlib.correlation.JB2009CorrelationModel(vs30_clustering)

“Correlation model for spatially distributed ground-motion intensities” by Nirmal Jayaram and Jack W. Baker. Published in Earthquake Engineering and Structural Dynamics 2009; 38, pages 1687-1708.

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)

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>>)

Compute “Disaggregation” matrix representing conditional probability of an intensity mesaure type imt exceeding, at least once, an intensity measure level iml at a geographical location site, given rupture scenarios classified in terms of:

• rupture magnitude
• Joyner-Boore 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. 501-520, 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 source-site filter function. See openquake.hazardlib.calc.filters.
• rupture_site_filter – Optional rupture-site 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 6d-array 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 pmf-extractor functions.

PMF-Extractors

openquake.hazardlib.calc.disagg.mag_pmf(matrix)

Fold full disaggregation matrix to magnitude PMF.

Returns:1d array, a histogram representing magnitude PMF.

openquake.hazardlib.calc.disagg.dist_pmf(matrix)

Fold full disaggregation matrix to distance PMF.

Returns:1d array, a histogram representing distance PMF.

openquake.hazardlib.calc.disagg.trt_pmf(matrix)

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)

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)

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)

Fold full disaggregation matrix to longitude / latitude PMF.

Returns:2d array. First dimension represents longitude histogram bins, second one – latitude histogram bins.

openquake.hazardlib.calc.disagg.mag_lon_lat_pmf(matrix)

Fold full disaggregation matrix to magnitude / longitude / latitude PMF.

Returns:3d array. First dimension represents magnitude histogram bins, second one – longitude histogram bins, third one – latitude histogram bins.

openquake.hazardlib.calc.disagg.lon_lat_trt_pmf(matrix)

Fold full disaggregation matrix to longitude / latitude / tectonic region type PMF.

Returns:3d array. Dimension represent longitude, latitude and tectonic region type histogram bins respectively.

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:

1. Source-site filters. Those functions take a generator of two-item tuples, each pair consists of seismic source object (that is, an instance of a subclass of BaseSeismicSource) and a site collection (instance of SiteCollection).
2. Rupture-site 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 distance-based 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)

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 Joyner-Boore distance, :meth:` openquake.hazardlib.geo.surface.base.BaseQuadrilateralSurface.get_joyner_boore_distance`).

openquake.hazardlib.calc.filters.rupture_site_distance_filter(integration_distance)

Rupture-site 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)

Rupture-site “no-op” filter, same as source_site_noop_filter().

openquake.hazardlib.calc.filters.source_site_distance_filter(integration_distance)

Source-site 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 source-site “no-op” filter – behaves like a real filter but never filters anything out and doesn’t have any overhead.