Groundshaking intensity models¶
Package openquake.hazardlib.gsim
contains base and specific
implementations of ground shaking intensity models. See
openquake.hazardlib.gsim.base
.
Builtin GSIMs¶
 Abrahamson and Silva 1997
 Abrahamson and Silva 2008
 Akkar et al. 2013
 Akkar et al. 2014
 Akkar and Bommer 2010
 Akkar and Cagnan 2010
 Allen 2012
 Atkinson and Boore 1995
 Atkinson and Boore 2003
 Atkinson and Boore 2006
 BergeThierry et al. 2003
 Bindi et al. 2011
 Boore, Joyner and Fumal 1993
 Boore, Joyner and Fumal 1997
 Boore, Stewart, Seyhan & Atkinson 2014
 Boore and Atkinson 2008
 Boore and Atkinson 2011
 Bradley 2013
 Campbell 2003
 Campbell and Bozorgnia 2003
 Campbell and Bozorgnia 2008
 Campbell & Bozorgnia 2014
 Cauzzi and Faccioli 2008
 Cauzzi and Faccioli 2008  Switzerland
 Chiou and Youngs 2008
 Chiou and Youngs 2008  Switzerland
 Chiou and Youngs 2014
 Climent et al. 1994
 Convertito et al. 2012
 Douglas et al., 2013
 Edwards and Fah 2013 Alpine
 Edwards and Fah 2013 Foreland
 Faccioli et al. 2010
 Frankel et al. 1996
 Fukushima and Tanaka 1990
 Garcia et al. 2005
 Geomatrix 1993
 Lin and Lee 2008
 Lin 2009
 McVerry et al. 2006
 Megawati & Pan 2010
 Pezeshk et al. 2011
 Sadigh et. al. 1997
 Silva et al. 2002
 Si and Midorikawa 1999
 Somerville et al. 2001
 Somerville et al. 2009
 Tavakoli and Pezeshk 2005
 Toro et al. 1997
 Toro et al. 2003
 Youngs et al. 1997
 Zhao et al. 2006
 Zhao et al. 2006  Switzerland
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
orIPE
.Subclasses of both must implement
get_mean_and_stddevs()
and all the class attributes with names starting fromDEFINED_FOR
andREQUIRES
.
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 moduleopenquake.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 theSitesContext
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 fromn_epsilons
distribution bins.If
truncation_level = 3
,n_epsilons = 3
, bin edges are3 .. 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 thatiml
is only one single intensity level andtruncation_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 withn_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). sites – Instance of

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
anddctx
) must conform to each other. The easiest way to get them is to callmake_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
andmean + 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 nonnegative float number, and ifimts
dictionary contain wrong or unsupported IMTs (seeDEFINED_FOR_INTENSITY_MEASURE_TYPES
). sctx – An instance of

make_contexts
(site_collection, rupture)[source]¶ Create context objects for given site collection and rupture.
Parameters:  site_collection – Instance of
openquake.hazardlib.site.SiteCollection
.  rupture – Instance of
Rupture
(or subclass ofBaseProbabilisticRupture
).
Returns: Tuple of three items: sites context, rupture context and distances context, that is, instances of
SitesContext
,RuptureContext
andDistancesContext
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.
 site_collection – Instance of

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
andIPE
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 toto_distribution_values()
.This method is implemented by both
GMPE
andIPE
so there is no need to override it in actual GSIM implementations.


class
openquake.hazardlib.gsim.base.
GMPE
[source]¶ GroundMotion Prediction Equation is a subclass of generic
GroundShakingIntensityModel
with a distinct feature that the intensity values are lognormally distributed.Method
get_mean_and_stddevs()
of actual GMPE implementations is supposed to return the mean value as a natural logarithm of intensity.

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, forMMI
.
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 spaceseparated 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 whatsites 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 whatrupture 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 whatdistance measures
does it need. Only those required values are calculated and made available in a result context object.