openquake.hazardlib.mfd package#

Magnitude-frequency distributions#

arbitrary_mfd#

Module openquake.hazardlib.mfd.evenly_discretized defines an evenly discretized MFD.

class openquake.hazardlib.mfd.arbitrary_mfd.ArbitraryMFD(magnitudes, occurrence_rates)[source]#

Bases: BaseMFD

An arbitrary MFD is defined as a list of tuples of magnitude values and their corresponding rates

Parameters:

magnitudes – List of magnitudes
occurrence_rates – The list of non-negative float values representing the actual annual occurrence rates. The resulting histogram has as many bins as this list length.

MODIFICATIONS = {'set_mfd'}#: 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]#

Checks the following constraints:

Magnitude list and occurrence rate lists are the same length
Occurrence rates list is not empty.
Each number in occurrence rates list is non-negative.
Minimum magnitude is positive.

get_annual_occurrence_rates()[source]#: Returns the predefined annual occurrence rates.

get_min_max_mag()[source]#: Returns the minumun and maximum magnitudes

modify_set_mfd(magnitudes, occurrence_rates)[source]#

Applies absolute modification of the MFD from the magnitudes, occurrence_rates modification.

Parameters:

magnitudes – List of magnitudes
occurrence_rates – The list of non-negative float values representing the actual annual occurrence rates. The resulting histogram has as many bins as this list length.

base#

Module openquake.hazardlib.mfd.base defines base class for MFD – BaseMFD.

class openquake.hazardlib.mfd.base.BaseMFD[source]#

Bases: object

Abstract base class for Magnitude-Frequency Distribution function.

abstract property 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.

abstract check_constraints()[source]#

Check MFD-specific constraints and raise ValueError in case of violation.

This method must be implemented by subclasses.

abstract 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 with magnitude 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.

abstract 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 also MODIFICATIONS.

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 from MODIFICATIONS.

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]#

Bases: BaseMFD

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 non-negative float values representing the actual annual occurrence rates. The resulting histogram has as many bins as this list length.

MODIFICATIONS = {'set_mfd'}#: 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]#

Checks the following constraints:

Bin width is positive.
Occurrence rates list is not empty.
Each number in occurrence rates list is non-negative.
Minimum magnitude is positive.

get_annual_occurrence_rates()[source]#: Returns the predefined annual occurrence rates.

get_min_max_mag()[source]#: Returns the minumun and maximum magnitudes

modify_set_mfd(min_mag, bin_width, occurrence_rates)[source]#

Applies absolute modification of the MFD from the min_mag, bin_width and occurrence_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 non-negative float values representing the actual annual occurrence rates. The resulting histogram has as many bins as this list length.

truncated_gr#

Module openquake.hazardlib.mfd.truncated_gr defines a Truncated Gutenberg-Richter MFD.

class openquake.hazardlib.mfd.truncated_gr.TruncatedGRMFD(min_mag, max_mag, bin_width, a_val, b_val)[source]#

Bases: BaseMFD

Truncated Gutenberg-Richter 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 cumulative a value (10 ** a is the number of earthquakes per year with magnitude greater than or equal to 0),
b_val is Gutenberg-Richter b value – the decay rate of exponential distribution. It describes the relative size distribution of earthquakes: a higher b value indicates a relatively larger proportion of small events and vice versa.
mag_lo and mag_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 to max_mag - bin_width / 2.
bin_width – A positive float value – the width of a single histogram bin.

Values for min_mag and max_mag don’t have to be aligned with respect to bin_width. They get rounded accordingly anyway so that both are divisible by bin_width just before converting a function to a histogram. See _get_min_mag_and_num_bins().

MODIFICATIONS = {'increment_b', 'increment_max_mag', 'increment_max_mag_no_mo_balance', 'set_ab', 'set_bGR', 'set_max_mag'}#: 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]#

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.

classmethod from_moment(min_mag, max_mag, bin_width, b_val, moment_rate, d_val=9.1)[source]#

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 to max_mag - bin_width / 2.
bin_width – A positive float value – the width of a single histogram bin.
b_val – The slope of the GR relationship
moment_rate – The value of scalar seismic moment per year released by this MFD. Unit of measure is N ・m
d_val – The constant term of the equation used to compute moment from magnitude. Set to 9.1 for backcompatibility.

classmethod from_slip_rate(min_mag, max_mag, bin_width, b_val, slip_rate, rigidity, area, constant_term=9.1)[source]#

Calls .from_moment with moment = slip_rate * rigidity * area

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 to max_mag - bin_width / 2.
bin_width – A positive float value – the width of a single histogram bin.
b_val – The slope of the GR relationship
slip_rate – A float defining the slip rate [mm/yr]
rigidity – A float defining the rigidity [GPa]
area – A float defining the area of the fault surface [km^2]
constant_term – A float defining the constant term of the equation used to compute the log M0 from magnitude.

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.

get_min_max_mag()[source]#: Return the minum magnitude

modify_increment_b(value)[source]#

Apply relative b-value modification.

Parameters:: value – A float value to add to b_val.

After changing b_val the a_val is recalculated the same way as for modify_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 Gutenberg-Richter a value is recalculated with respect to old total moment rate.

modify_increment_max_mag_no_mo_balance(value)[source]#

Apply relative maximum magnitude modification.

Parameters:: value – A float value to add to max_mag.

modify_set_ab(a_val, b_val)[source]#

Apply absolute a and b values modification.

Parameters:

a_val – A float value to use as a new a_val.
b_val – A float value to use as a new b_val.

No recalculation of other Gutenberg-Richter parameters is done.

modify_set_bGR(b_val: float)[source]#

Updates the b_value of the GR relationship.

Parameters:: b_val – The value of the new maximum magnitude

modify_set_max_mag(value)[source]#

Apply absolute maximum magnitude modification.

Parameters:: value – A float value to assign to max_mag.

No specific recalculation of other Gutenberg-Richter parameters is done after assigning a new value to max_mag.

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, b_val, char_mag, char_rate, bin_width, total_moment_rate=None)[source]#

Bases: BaseMFD

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 939-964, 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 Gutenberg-Richeter part of the distribution) is equal to the absolute maximum magnitude minus Δ_mc (that is there is no gap between the Gutenberg-Richter 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 Gutenberg-Richter a value – the intercept of the loglinear cumulative G-R relationship.
b_val – The Gutenberg-Richter b value – the gradient of the loglinear G-R 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 to bin_width. They get rounded accordingly anyway so that both are divisible by bin_width just before converting a function to a histogram. See _get_min_mag_and_num_bins().

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]#

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 G-R 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 formula
```
a_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 as

a_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 Gutenberg-Richter b value – the gradient of the loglinear G-R 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 to bin_width. They get rounded accordingly anyway so that both are divisible by bin_width just before converting a function to a histogram. See _get_min_mag_and_num_bins().

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 equation

10 ** (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 Gutenberg-Richter b value – the gradient of the loglinear G-R 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 to bin_width. They get rounded accordingly anyway so that both are divisible by bin_width just before converting a function to a histogram. See _get_min_mag_and_num_bins().

get_annual_occurrence_rates()[source]#

Calculate and return the annual occurrence rates histogram.

Returns:: See :meth: openquake.hazardlib.mfd.base.BaseMFD.get_annual_occurrence_rates.

get_min_max_mag()[source]#: Return the minimum and maximum magnitudes

Module contents#

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.

openquake.hazardlib.mfd.from_toml(string, bin_width)[source]#: Convert a TOML string into an MFD instance