Ground-shaking intensity models

Package openquake.hazardlib.gsim contains base and specific implementations of ground shaking intensity models. See openquake.hazardlib.gsim.base.

Base GSIM classes and functionality

Module openquake.hazardlib.gsim.base defines base classes for different kinds of ground shaking intensity models.

Intensity models

class openquake.hazardlib.gsim.base.GroundShakingIntensityModel[source]

Base class for all the ground shaking intensity models.

A Ground Shaking Intensity Model (GSIM) defines a set of equations for computing mean and standard deviation of a Normal distribution representing the variability of an intensity measure (or of its logarithm) at a site given an earthquake rupture.

This class is not intended to be subclassed directly, instead the actual GSIMs should subclass either GMPE or IPE.

Subclasses of both must implement get_mean_and_stddevs() and all the class attributes with names starting from DEFINED_FOR and REQUIRES.

DEFINED_FOR_INTENSITY_MEASURE_COMPONENT

Reference to a intensity measure component type this GSIM can calculate mean and standard deviation for.

DEFINED_FOR_INTENSITY_MEASURE_TYPES

Set of intensity measure types calculate. A set should contain classes from module openquake.hazardlib.imt.

DEFINED_FOR_STANDARD_DEVIATION_TYPES

Set of standard deviation types this GSIM can calculate.

DEFINED_FOR_TECTONIC_REGION_TYPE

Reference to a tectonic region type this GSIM is defined for. One GSIM can implement only one tectonic region type.

REQUIRES_DISTANCES

Set of types of distance measures between rupture and sites. Possible values are:

rrup
Closest distance to rupture surface. See get_min_distance().
rjb
Distance to rupture’s surface projection. See get_joyner_boore_distance().
rx
Perpendicular distance to rupture top edge projection. See get_rx_distance().

All the distances are available from the DistancesContext object attributes with same names. Values are in kilometers.

REQUIRES_RUPTURE_PARAMETERS

Set of rupture parameters (excluding distance information) required by GSIM. Supported parameters are:

mag
Magnitude of the rupture.
dip
Rupture’s surface dip angle in decimal degrees.
rake
Angle describing the slip propagation on the rupture surface, in decimal degrees. See nodalplane for more detailed description of dip and rake.
ztor
Depth of rupture’s top edge in km. See get_top_edge_depth().

These parameters are available from the RuptureContext object attributes with same names.

REQUIRES_SITES_PARAMETERS

Set of site parameters names this GSIM needs. The set should include strings that match names of the attributes of a site object. Those attributes are then available in the SitesContext object with the same names.

disaggregate_poe(sctx, rctx, dctx, imt, iml, truncation_level, n_epsilons)[source]

Disaggregate (separate) PoE of iml in different contributions each coming from n_epsilons distribution bins.

If truncation_level = 3, n_epsilons = 3, bin edges are -3 .. -1, -1 .. +1 and +1 .. +3.

Parameters:n_epsilons – Integer number of bins to split truncated Gaussian distribution to.

Other parameters are the same as for get_poes(), with differences that iml is only one single intensity level and truncation_level is required to be positive.

Returns:Contribution to probability of exceedance of iml coming from different sigma bands in a form of 1d numpy array with n_epsilons floats between 0 and 1.
get_mean_and_stddevs(sites, rup, dists, imt, stddev_types)[source]

Calculate and return mean value of intensity distribution and it’s standard deviation.

Method must be implemented by subclasses.

Parameters:
  • sites – Instance of SitesContext with parameters of sites collection assigned to respective values as numpy arrays. Only those attributes that are listed in class’ REQUIRES_SITES_PARAMETERS set are available.
  • rup – Instance of RuptureContext with parameters of a rupture assigned to respective values. Only those attributes that are listed in class’ REQUIRES_RUPTURE_PARAMETERS set are available.
  • dists – Instance of DistancesContext with values of distance measures between the rupture and each site of the collection assigned to respective values as numpy arrays. Only those attributes that are listed in class’ REQUIRES_DISTANCES set are available.
  • imt – An instance (not a class) of intensity measure type. See openquake.hazardlib.imt.
  • stddev_types – List of standard deviation types, constants from openquake.hazardlib.const.StdDev. Method result value should include standard deviation values for each of types in this list.
Returns:

Method should return a tuple of two items. First item should be a numpy array of floats – mean values of respective component of a chosen intensity measure type, and the second should be a list of numpy arrays of standard deviation values for the same single component of the same single intensity measure type, one array for each type in stddev_types parameter, preserving the order.

Combining interface to mean and standard deviation values in a single method allows to avoid redoing the same intermediate calculations if there are some shared between stddev and mean formulae without resorting to keeping any sort of internal state (and effectively making GSIM not reenterable).

However it is advised to split calculation of mean and stddev values and make get_mean_and_stddevs() just combine both (and possibly compute interim steps).

get_poes(sctx, rctx, dctx, imt, imls, truncation_level)[source]

Calculate and return probabilities of exceedance (PoEs) of one or more intensity measure levels (IMLs) of one intensity measure type (IMT) for one or more pairs “site – rupture”.

Parameters:
  • sctx – An instance of SitesContext with sites information to calculate PoEs on.
  • rctx – An instance of RuptureContext with a single rupture information.
  • dctx –

    An instance of DistancesContext with information about the distances between sites and a rupture.

    All three contexts (sctx, rctx and dctx) must conform to each other. The easiest way to get them is to call make_contexts().

  • imt – An intensity measure type object (that is, an instance of one of classes from openquake.hazardlib.imt).
  • imls – List of interested intensity measure levels (of type imt).
  • truncation_level –

    Can be None, which means that the distribution of intensity is treated as Gaussian distribution with possible values ranging from minus infinity to plus infinity.

    When set to zero, the mean intensity is treated as an exact value (standard deviation is not even computed for that case) and resulting array contains 0 in places where IMT is strictly lower than the mean value of intensity and 1.0 where IMT is equal or greater.

    When truncation level is positive number, the intensity distribution is processed as symmetric truncated Gaussian with range borders being mean - truncation_level * stddev and mean + truncation_level * stddev. That is, the truncation level expresses how far the range borders are from the mean value and is defined in units of sigmas. The resulting PoEs for that mode are values of complementary cumulative distribution function of that truncated Gaussian applied to IMLs.
Returns:

A dictionary of the same structure as parameter imts (see above). Instead of lists of IMLs values of the dictionaries have 2d numpy arrays of corresponding PoEs, first dimension represents sites and the second represents IMLs.
Raises:

ValueError – If truncation level is not None and neither non-negative float number, and if imts dictionary contain wrong or unsupported IMTs (see DEFINED_FOR_INTENSITY_MEASURE_TYPES).
make_contexts(site_collection, rupture)[source]

Create context objects for given site collection and rupture.

Parameters:
Returns:

Tuple of three items: sites context, rupture context and distances context, that is, instances of SitesContext, RuptureContext and DistancesContext in a specified order. Only those values that are required by GSIM are filled in in contexts.
Raises:

ValueError – If any of declared required parameters (that includes site, rupture and distance parameters) is unknown.
to_distribution_values(values)[source]

Convert a list or array of values in units of IMT to a numpy array of values of intensity measure distribution (like taking the natural logarithm for GMPE).

This method is implemented by both GMPE and IPE so there is no need to override it in actual GSIM implementations.

to_imt_unit_values(values)[source]

Convert a list or array of values of intensity measure distribution (like ones returned from get_mean_and_stddevs()) to values in units of IMT. This is the opposite operation to to_distribution_values().

This method is implemented by both GMPE and IPE so there is no need to override it in actual GSIM implementations.

class openquake.hazardlib.gsim.base.GMPE[source]

Ground-Motion Prediction Equation is a subclass of generic GroundShakingIntensityModel with a distinct feature that the intensity values are log-normally distributed.

Method get_mean_and_stddevs() of actual GMPE implementations is supposed to return the mean value as a natural logarithm of intensity.

to_distribution_values(values)[source]

Returns numpy array of natural logarithms of values.

to_imt_unit_values(values)[source]

Returns numpy array of exponents of values.

class openquake.hazardlib.gsim.base.IPE[source]

Intensity Prediction Equation is a subclass of generic GroundShakingIntensityModel which is suitable for intensity measures that are normally distributed. In particular, for MMI.

to_distribution_values(values)[source]

Returns numpy array of values without any conversion.

to_imt_unit_values(values)[source]

Returns numpy array of values without any conversion.

Helper for coefficients tables

class openquake.hazardlib.gsim.base.CoeffsTable(**kwargs)[source]

Instances of CoeffsTable encapsulate tables of coefficients corresponding to different IMTs.

Tables are defined in a space-separated tabular form in a simple string literal (heading and trailing whitespace does not matter). The first column in the table must be named “IMT” (or “imt”) and thus should represent IMTs:

>>> CoeffsTable(table='''imf z
...                      pga 1''')
Traceback (most recent call last):
    ...
ValueError: first column in a table must be IMT

Names of other columns are used as coefficients dicts keys. The values in the first column should correspond to real intensity measure types, see openquake.hazardlib.imt:

>>> CoeffsTable(table='''imt  z
...                      pgx  2''')
Traceback (most recent call last):
    ...
ValueError: unknown IMT 'PGX'

Note that CoeffsTable only accepts keyword argumets:

>>> CoeffsTable()
Traceback (most recent call last):
    ...
TypeError: CoeffsTable requires "table" kwarg
>>> CoeffsTable(table='', foo=1)
Traceback (most recent call last):
    ...
TypeError: CoeffsTable got unexpected kwargs: {'foo': 1}

If there are SA IMTs in the table, they are not referenced by name, because they require parametrization:

>>> CoeffsTable(table='''imt  x
...                      sa   15''')
Traceback (most recent call last):
    ...
ValueError: specify period as float value to declare SA IMT
>>> CoeffsTable(table='''imt  x
...                      0.1  20''')
Traceback (most recent call last):
    ...
TypeError: attribute "sa_damping" is required for tables defining SA

So proper table defining SA looks like this:

>>> ct = CoeffsTable(sa_damping=5, table='''
...     imt   a    b     c   d
...     pga   1    2.4  -5   0.01
...     pgd  7.6  12     0  44.1
...     0.1  10   20    30  40
...     1.0   1    2     3   4
...     10    2    4     6   8
... ''')

Table objects could be indexed by IMT objects (this returns a dictionary of coefficients):

>>> from openquake.hazardlib import imt
>>> ct[imt.PGA()] == dict(a=1, b=2.4, c=-5, d=0.01)
True
>>> ct[imt.PGD()] == dict(a=7.6, b=12, c=0, d=44.1)
True
>>> ct[imt.SA(damping=5, period=0.1)] == dict(a=10, b=20, c=30, d=40)
True
>>> ct[imt.PGV()]
Traceback (most recent call last):
    ...
KeyError: PGV()
>>> ct[imt.SA(1.0, 4)]
Traceback (most recent call last):
    ...
KeyError: SA(period=1.0, damping=4)

Table of coefficients for spectral acceleration could be indexed by instances of openquake.hazardlib.imt.SA with period value that is not specified in the table. The coefficients then get interpolated between the ones for closest higher and closest lower period. That scaling of coefficients works in a logarithmic scale of periods and only within the same damping:

>>> '%.5f' % ct[imt.SA(period=0.2, damping=5)]['a']
'7.29073'
>>> '%.5f' % ct[imt.SA(period=0.9, damping=5)]['c']
'4.23545'
>>> '%.5f' % ct[imt.SA(period=5, damping=5)]['c']
'5.09691'
>>> ct[imt.SA(period=0.9, damping=15)]
Traceback (most recent call last):
    ...
KeyError: SA(period=0.9, damping=15)

Extrapolation is not possible:

>>> ct[imt.SA(period=0.01, damping=5)]
Traceback (most recent call last):
    ...
KeyError: SA(period=0.01, damping=5)

Calculation context

class openquake.hazardlib.gsim.base.SitesContext[source]

Sites calculation context for ground shaking intensity models.

Instances of this class are passed into GroundShakingIntensityModel.get_mean_and_stddevs(). They are intended to represent relevant features of the sites collection. Every GSIM class is required to declare what sites parameters does it need. Only those required parameters are made available in a result context object.

class openquake.hazardlib.gsim.base.RuptureContext[source]

Rupture calculation context for ground shaking intensity models.

Instances of this class are passed into GroundShakingIntensityModel.get_mean_and_stddevs(). They are intended to represent relevant features of a single rupture. Every GSIM class is required to declare what rupture parameters does it need. Only those required parameters are made available in a result context object.

class openquake.hazardlib.gsim.base.DistancesContext[source]

Distances context for ground shaking intensity models.

Instances of this class are passed into GroundShakingIntensityModel.get_mean_and_stddevs(). They are intended to represent relevant distances between sites from the collection and the rupture. Every GSIM class is required to declare what distance measures does it need. Only those required values are calculated and made available in a result context object.