Magnitudefrequency distributions¶
A Magnitude Frequency Distribution (MFD) is a function that describes the rate (per year) of earthquakes across all magnitudes.
Package mfd contains the basic class for MFD –
openquake.hazardlib.mfd.base.BaseMFD
, and three actual
implementations:
openquake.hazardlib.mfd.evenly_discretized.EvenlyDiscretizedMFD
openquake.hazardlib.mfd.truncated_gr.TruncatedGRMFD
and
openquake.hazardlib.mfd.youngs_coppersmith_1985.YoungsCoppersmith1985MFD
.
Evenly discretized¶
Module openquake.hazardlib.mfd.evenly_discretized
defines an evenly
discretized MFD.

class
openquake.hazardlib.mfd.evenly_discretized.
EvenlyDiscretizedMFD
(min_mag, bin_width, occurrence_rates)[source]¶ Evenly discretized MFD is defined as a precalculated histogram.
Parameters:  min_mag – Positive float value representing the middle point of the first bin in the histogram.
 bin_width – A positive float value – the width of a single histogram bin.
 occurrence_rates – The list of nonnegative float values representing the actual annual occurrence rates. The resulting histogram has as many bins as this list length.

check_constraints
()[source]¶ Checks the following constraints:
 Bin width is positive.
 Occurrence rates list is not empty.
 Each number in occurrence rates list is nonnegative.
 Minimum magnitude is positive.

modify_set_mfd
(min_mag, bin_width, occurrence_rates)[source]¶ Applies absolute modification of the MFD from the
min_mag
,bin_width
andoccurrence_rates
modification.Parameters:  min_mag – Positive float value representing the middle point of the first bin in the histogram.
 bin_width – A positive float value – the width of a single histogram bin.
 occurrence_rates – The list of nonnegative float values representing the actual annual occurrence rates. The resulting histogram has as many bins as this list length.
Truncated GutenbergRichter¶
Module openquake.hazardlib.mfd.truncated_gr
defines a Truncated
GutenbergRichter MFD.

class
openquake.hazardlib.mfd.truncated_gr.
TruncatedGRMFD
(min_mag, max_mag, bin_width, a_val, b_val)[source]¶ Truncated GutenbergRichter MFD is defined in a functional form.
The annual occurrence rate for a specific bin (magnitude band) is defined as
rate = 10 ** (a_val  b_val * mag_lo)  10 ** (a_val  b_val * mag_hi)
where
a_val
is the cumulativea
value (10 ** a
is the number of earthquakes per year with magnitude greater than or equal to 0),b_val
is GutenbergRichterb
value – the decay rate of exponential distribution. It describes the relative size distribution of earthquakes: a higherb
value indicates a relatively larger proportion of small events and vice versa.mag_lo
andmag_hi
are lower and upper magnitudes of a specific bin respectively.
Parameters:  min_mag – The lowest possible magnitude for this MFD. The first bin in the
result histogram
will be aligned to make its left border match this value.  max_mag – The highest possible magnitude. The same as for
min_mag
: the last bin in the histogram will correspond to the magnitude value equal tomax_mag  bin_width / 2
.  bin_width – A positive float value – the width of a single histogram bin.
Values for
min_mag
andmax_mag
don’t have to be aligned with respect tobin_width
. They get rounded accordingly anyway so that both are divisible bybin_width
just before converting a function to a histogram. See_get_min_mag_and_num_bins()
.
_get_min_mag_and_num_bins
()[source]¶ Estimate the number of bins in the histogram and return it along with the first bin center abscissa (magnitude) value.
Rounds
min_mag
andmax_mag
with respect tobin_width
to make the distance between them include integer number of bins.Returns: A tuple of two items: first bin center and total number of bins.

_get_rate
(mag)[source]¶ Calculate and return an annual occurrence rate for a specific bin.
Parameters: mag – Magnitude value corresponding to the center of the bin of interest. Returns: Float number, the annual occurrence rate calculated using formula described in TruncatedGRMFD
.

_get_total_moment_rate
()[source]¶ Calculate total moment rate (total energy released per unit time)
TMR = ((10**ai) / bi) * (10 ** (bi*max_mag)  10 ** (bi*min_mag))
where
ai = a + log10(b) + 9.05
andbi = 1.5  b
. In case ofbi == 0
the following formula is applied:TMR = (10 ** ai) * (max_mag  min_mag)
Returns: Float, calculated TMR value in N * m / year
(Newtonmeter per year).

_set_a
(tmr)[source]¶ Recalculate an
a
value preserving a total moment ratetmr
a = (log10((tmr * bi) / (10 ** (bi*max_mag)  10 ** (bi*min_mag)))  9.05  log10(b))
where
bi = 1.5  b
. Ifbi == 0
the following formula is used:a = log10(tmr / (max_mag  min_mag))  9.05  log10(b)

check_constraints
()[source]¶ Checks the following constraints:
 Bin width is greater than 0.
 Minimum magnitude is positive.
 Maximum magnitude is greater than minimum magnitude by at least one bin width (or equal to that value).
b
value is positive.

get_annual_occurrence_rates
()[source]¶ Calculate and return the annual occurrence rates histogram.
The result histogram has only one bin if minimum and maximum magnitude values appear equal after rounding.
Returns: See :meth: openquake.hazardlib.mfd.base.BaseMFD.get_annual_occurrence_rates.

modify_increment_b
(value)[source]¶ Apply relative
b
value modification.Parameters: value – A float value to add to b_val
.After changing
b_val
thea_val
is recalculated the same way as formodify_increment_max_mag()
(with respect to TMR).

modify_increment_max_mag
(value)[source]¶ Apply relative maximum magnitude modification.
Parameters: value – A float value to add to max_mag
.The GutenbergRichter
a
value isrecalculated
with respect to oldtotal moment rate
.
Youngs Coppersmith 1985¶
Module openquake.hazardlib.mfd.youngs_coppersmith_1985
defines the
Youngs and Coppersmith 1985 MFD.

class
openquake.hazardlib.mfd.youngs_coppersmith_1985.
YoungsCoppersmith1985MFD
(min_mag, a_val, b_val, char_mag, char_rate, bin_width)[source]¶ Class implementing the MFD for the ‘Characteristic Earthquake Model’ as described in: “Implications of fault slip rates and earthquake recurrence models to probabilistic seismic hazard estimates”, by Robert R. Youngs and Kevin J. Coppersmith and published in Bulletin of the Seismological Society of America, Vol. 75, No. 4, pages 939964, 1985. The class implements the MFD under the following assumptions as reported at page 954:
 Δ_mc (width of the boxcar distribution representing characteristic rate) is equal to 0.5 magnitude unit
 m’ (maximum magnitude value for the GutenbergRicheter part of the distribution) is equal to the absolute maximum magnitude minus Δ_mc (that is there is no gap between the GutenbergRichter distribution and the boxcar distribution)
 the rate of events at the characteristic magnitude is equal to the rate of events for magnitude equal to m’  1
Parameters:  min_mag – The lowest possible magnitude for the MFD. The first bin in the
result histogram
is aligned to make its left border match this value.  a_val – The GutenbergRichter
a
value – the intercept of the loglinear cumulative GR relationship.  b_val – The GutenbergRichter
b
value – the gradient of the loglinear GR relationship.  char_mag – The characteristic magnitude defining the middle point of the characteristic distribution. That is the boxcar function representing the characteristic distribution is defined in the range [char_mag  0.25, char_mag + 0.25].
 char_rate – The characteristic rate associated to the characteristic magnitude, to be distributed over the domain of the boxcar function representing the characteristic distribution (that is λ_char = char_rate / 0.5)
 bin_width – A positive float value – the width of a single histogram bin.
Values for
min_mag
and the maximum magnitude (char_mag + 0.25) don’t have to be aligned with respect tobin_width
. They get rounded accordingly anyway so that both are divisible bybin_width
just before converting a function to a histogram. See_get_min_mag_and_num_bins()
.
_get_min_mag_and_num_bins
()[source]¶ Estimate the number of bins in the histogram and return it along with the first bin center value.
Rounds
min_mag
andmax_mag
with respect tobin_width
to make the distance between them include integer number of bins.Returns: A tuple of 2 items: first bin center, and total number of bins.

_get_rate
(mag)[source]¶ Calculate and return the annual occurrence rate for a specific bin.
Parameters: mag – Magnitude value corresponding to the center of the bin of interest. Returns: Float number, the annual occurrence rate for the :param mag value.

check_constraints
()[source]¶ Checks the following constraints:
minimum magnitude is positive.
b
value is positive.characteristic magnitude is positive
characteristic rate is positive
bin width is in the range (0, 0.5] to allow for at least one bin representing the characteristic distribution
characteristic magnitude minus 0.25 (that is the maximum magnitude of the GR distribution) is greater than the minimum magnitude by at least one magnitude bin.
rate of events at the characteristic magnitude is equal to the rate of events for magnitude equal to m_prime  1. This is done by asserting the equality (up to 7 digit precision)
10 ** (a_incr  b * (m'  1)) == char_rate / 0.5
where
a_incr
is the incremental a value obtained from the cumulative a value using the following formulaa_incr = a_val + log10(b_val * ln(10))
and
m'  1 = char_mag  1.25

classmethod
from_characteristic_rate
(min_mag, b_val, char_mag, char_rate, bin_width)[source]¶ Define Youngs and Coppersmith 1985 MFD by constraing cumulative a value from characteristic rate. The cumulative a value is obtained by making use of the property that the rate of events at m’  1 must be equal to the rate at the characteristic magnitude, and therefore by first computing the incremental a value, using the following equation:
10 ** (a_incr  b_val * (m_prime  1)) == char_rate / 0.5
where
m'  1 = char_mag  1.25
. The cumulative a value is then obtained asa_val = a_incr  log10(b_val * ln(10))
Parameters:  min_mag – The lowest magnitude for the MFD. The first bin in the
result histogram
is aligned to make its left border match this value.  b_val – The GutenbergRichter
b
value – the gradient of the loglinear GR relationship.  char_mag – The characteristic magnitude defining the middle point of characteristic distribution. That is the boxcar function representing the characteristic distribution is defined in the range [char_mag  0.25, char_mag + 0.25].
 char_rate – The characteristic rate associated to the characteristic magnitude, to be distributed over the domain of the boxcar function representing the characteristic distribution (that is λ_char = char_rate / 0.5)
 bin_width – A positive float value – the width of a single histogram bin.
Returns: An instance of
YoungsCoppersmith1985MFD
.Values for
min_mag
and the maximum magnitude (char_mag + 0.25) don’t have to be aligned with respect tobin_width
. They get rounded accordingly anyway so that both are divisible bybin_width
just before converting a function to a histogram. See_get_min_mag_and_num_bins()
. min_mag – The lowest magnitude for the MFD. The first bin in the

classmethod
from_total_moment_rate
(min_mag, b_val, char_mag, total_moment_rate, bin_width)[source]¶ Define Youngs and Coppersmith 1985 MFD by constraing cumulative a value and characteristic rate from total moment rate. The cumulative a value and characteristic rate are obtained by solving equations (16) and (17), page 954, for the cumulative rate of events with magnitude greater than the minimum magnitude  N(min_mag)  and the cumulative rate of characteristic earthquakes  N(char_mag). The difference
N(min_mag)  N(char_mag)
represents the rate of noncharacteristic, exponentially distributed earthquakes and is used to derive the cumulative a value by solving the following equation10 ** (a_val  b_val * min_mag)  10 ** (a_val  b_val * (char_mag  0.25)) = N(min_mag)  N(char_mag)
which can be written as
a_val = log10(N(min_mag)  N(char_mag)) / (10 ** ( b_val * min_mag)  10 ** ( b_val * (char_mag  0.25))
In the calculation of N(min_mag) and N(char_mag), the Hanks and Kanamori (1979) formula
M0 = 10 ** (1.5 * Mw + 9.05)
is used to convert moment magnitude (Mw) to seismic moment (M0, Newton × m)
Parameters:  min_mag – The lowest magnitude for the MFD. The first bin in the
result histogram
is aligned to make its left border match this value.  b_val – The GutenbergRichter
b
value – the gradient of the loglinear GR relationship.  char_mag – The characteristic magnitude defining the middle point of characteristic distribution. That is the boxcar function representing the characteristic distribution is defined in the range [char_mag  0.25, char_mag + 0.25].
 total_moment_rate – Total moment rate in N * m / year.
 bin_width – A positive float value – the width of a single histogram bin.
Returns: An instance of
YoungsCoppersmith1985MFD
.Values for
min_mag
and the maximum magnitude (char_mag + 0.25) don’t have to be aligned with respect tobin_width
. They get rounded accordingly anyway so that both are divisible bybin_width
just before converting a function to a histogram. See_get_min_mag_and_num_bins()
. min_mag – The lowest magnitude for the MFD. The first bin in the
Abstract base distribution¶
Module openquake.hazardlib.mfd.base
defines base class for MFD –
BaseMFD
.

class
openquake.hazardlib.mfd.base.
BaseMFD
[source]¶ Abstract base class for MagnitudeFrequency Distribution function.

MODIFICATIONS
¶ The set of modification type names that are supported by an MFD. Each modification should have a corresponding method named
modify_modificationname()
where the actual modification logic resides.

check_constraints
()[source]¶ Check MFDspecific constraints and raise
ValueError
in case of violation.This method must be implemented by subclasses.

get_annual_occurrence_rates
()[source]¶ Return an MFD annual occurrence rates histogram.
This method must be implemented by subclasses.
Returns: The list of tuples, each tuple containing a pair (magnitude, occurrence_rate)
. Each pair represents a single bin of the histogram withmagnitude
being the center of the bin. Magnitude values are monotonically increasing by value of bin width.occurence_rate
represents the number of events per year with magnitude that falls in between bin’s boundaries.

get_min_max_mag
()[source]¶ Return the minimum and maximum magnitudes this MFD is defined for.
This method must be implemented by subclasses.
Returns: Magnitude value, float number.

modify
(modification, parameters)[source]¶ Apply a single modification to an MFD parameters.
Reflects the modification method and calls it passing
parameters
as keyword arguments. See alsoMODIFICATIONS
.Modifications can be applied one on top of another. The logic of stacking modifications is up to a specific MFD implementation.
Parameters:  modification – String name representing the type of modification.
 parameters – Dictionary of parameters needed for modification.
Raises: ValueError – If
modification
is missing fromMODIFICATIONS
.
