pyrvt.motions¶

Random vibration theory (RVT) based motions.

The module attribute DEFAULT_CALC is used to control the default peak factor calculator is one is not provided when a class is initialized.

pyrvt.motions.sort_increasing(*args)[source]

Sort arrays such that they are increasing.

Check if the first array is is increasing, if not reverse the order. Same operation is applied to additional arrays.

Parameters:: *args (array_like) – arrays to be re-ordered.
Returns:: tuple containing sorted numpy.ndarray’s.
Return type:: tuple
Raises:: NotImplementedError – If first array is not monotonic.

pyrvt.motions.log_spaced_values(lower, upper, per_decade=512)[source]

Generate values with constant log-spacing.

Parameters:

lower (float) – lower end of the range.
upper (float) – upper end of the range.
per_decade (int, optional) – number of points per decade. Default is 512 points per decade.

Returns:

values – Log-spaced values.

Return type:

numpy.ndarray

pyrvt.motions.calc_sdof_tf(freqs, osc_freq, osc_damping)[source]

Single-degree-of-freedom transfer function.

When applied on the acceleration Fourier amplitude spectrum, it provides the pseudo-spectral acceleration.

Parameters:

freqs (array_like) – Frequencies at which the transfer function should be calculated (Hz).
osc_freq (float) – Frequency of the oscillator (Hz).
osc_damping (float) – Fractional damping of the oscillator (decimal).

Returns:

Complex valued transfer function.

Return type:

numpy.ndarray

pyrvt.motions.calc_stress_drop(magnitude)[source]

Stress drop using Atkinson & Boore (2011) model.

Parameters:: magnitude (float) – Moment magnitude of the stress drop.
Returns:: stress_drop – Stress drop (bars).
Return type:: float

pyrvt.motions.calc_geometric_spreading(dist, params)[source]

Geometric spreading defined by piece-wise linear model.

Parameters:

dist (float) – Closest distance to the rupture surface (km).
params (List[(float,Optional[float])]) – List of (slope, limit) tuples that define the attenuation. For an infinite distance use None. For example, [(1, None)] would provide for 1/R geometric spreading to an infinite distance.

Returns:

coeff – Geometric spreading coefficient.

Return type:

float

class pyrvt.motions.RvtMotion(freqs=None, fourier_amps=None, duration=None, peak_calculator=None, calc_kwds=None)[source]

Bases: object

Random vibration theory motion.

Parameters:

freqs (array_like, optional) – Frequency array (Hz).
fourier_amps (array_like, optional) – Absolute value of acceleration Fourier amplitudes.
duration (float, optional) – Ground motion duration (sec).
peak_calculator (Calculator, optional) – Peak calculator to use. If None, then the default peak calculator is used. The peak calculator may either be specified by a [pyrvt.peak_calculators.Calculator][] instance, or created by the abbreviation of the calculator using [pyrvt.peak_calculators.get_peak_calculator][].
calc_kwds (dict, optional) – Keywords to be passed during the creation the peak calculator. These keywords are only required for some peak calculators.

__init__(freqs=None, fourier_amps=None, duration=None, peak_calculator=None, calc_kwds=None)[source]

Initialize the class.

Parameters:

freqs (ArrayLike | None)
fourier_amps (ArrayLike | None)
duration (float | None)
peak_calculator (str | Calculator | None)
calc_kwds (dict | None)

Return type:

None

property freqs: ndarray: Frequency values (Hz).

property fourier_amps: ndarray: Acceleration Fourier amplitude values (g-sec).

property duration: float: Duration of the ground motion for RVT analysis.

calc_osc_accels(osc_freqs, osc_damping=0.05, trans_func=None)[source]

Pseudo-acceleration spectral response of an oscillator.

Parameters:

osc_freqs (float) – Frequency of the oscillator (Hz).
osc_damping (float) – Fractional damping of the oscillator (dec). For example, 0.05 for a damping ratio of 5%.
trans_func (array_like, optional) – Transfer function to be applied to motion prior calculation of the oscillator response.

Returns:

spec_accels – Peak pseudo-spectral acceleration of the oscillator

Return type:

numpy.ndarray

property angular_freqs: ndarray: Angular frequency values (rad/sec).

property pgv: float: Peak ground velocity (cm/sec).

property pga: float: Peak ground acceleration (g).

property arias_intensity: float: Arias intensity (m/s).

property cav: float: Cumulative absolute velocity (m/s).

calc_pgv(tf=None)[source]

Compute the peak ground velocity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pgv – Peak ground velocity (cm/sec).
Return type:: float

calc_pga(tf=None)[source]

Compute the peak ground acceleration.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pga – Peak ground acceleration (g).
Return type:: float

calc_arias_intensity(tf=None)[source]

Compute the Arias intensity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: arias_intensity – Arias intensity (m/s).
Return type:: float

calc_cav(tf=None)[source]

Compute the cumulative absolute velocity (CAV).

Uses an empirical regression on Arias intensity and duration based on observed ground motions.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: cav – Cumulative absolute velocity (m/s).
Return type:: float

calc_peak(transfer_func=None, **kwds)[source]

Compute the peak response.

Parameters:: transfer_func (array_like, optional) – Transfer function to apply to the motion. If None, then no transfer function is applied.
Returns:: peak – Calculated peak
Return type:: float

calc_attenuation(min_freq, max_freq=None)[source]

Compute the site attenuation (κ) based on a log-linear fit.

Parameters:

min_freq (float) – minimum frequency of the fit (Hz).
max_freq (float, optional) – maximum frequency of the fit. If None, then the maximum frequency range is used.

Returns:

atten (float) – attenuation parameter.
r_sqr (float) – squared correlation coefficient of the fit (R²). See scipy.stats.linregress.
freqs (array_like) – selected frequencies
fitted (array_like) – fitted values

Return type:

tuple[float, float, ndarray, ndarray]

Notes

This function computes the site attenuation defined by Anderson & Hough (1984) [@anderson84] as:

$$ a(f) = A_0 exp(-pi kappa f) text( for ) f > f_E $$

for a single Fourier amplitude spectrum

class pyrvt.motions.SourceTheoryMotion(magnitude, distance, region, stress_drop=None, depth=8, peak_calculator=None, calc_kwds=None, freqs=None, disable_site_amp=False)[source]

Bases: RvtMotion

Single-corner source theory model.

The single-corner source theory model uses default parameters from Campbell (2003).

Parameters:

magnitude (float)
distance (float)
region (str)
stress_drop (float | None)
depth (float | None)
peak_calculator (str | peak_calculators.Calculator | None)
calc_kwds (dict | None)
freqs (npt.ArrayLike | None)
disable_site_amp (bool)

__init__(magnitude, distance, region, stress_drop=None, depth=8, peak_calculator=None, calc_kwds=None, freqs=None, disable_site_amp=False)[source]

Initialize the motion.

Parameters:

magnitude (float) – Moment magnitude of the event.
distance (float) – Epicentral distance (km).
region (str) – Region for the parameters. Either ‘cena’ for Central and Eastern North America, or ‘wna’ for Western North America.
stress_drop (float, optional) – Stress drop of the event (bars). If None, then the default value is used. For region is ‘cena’, the default value is computed by the model, while for region is ‘wna’ the default value is 100 bars.
depth (float, optional) – Hypocenter depth (km). The depth is combined with the distance to compute the hypocentral distance.
peak_calculator (Calculator, optional) – Peak calculator to use. If None, then the default peak calculator is used. The peak calculator may either be specified by a [pyrvt.peak_calculators.Calculator][] object, or by the initials of the calculator using [pyrvt.peak_calculators.get_peak_calculator][].
calc_kwds (dict, optional) – Keywords to be passed during the creation the peak calculator. These keywords are only required for some peak calculators.
freqs (array_like) – frequencies for which the Fourier amplitude spectrum should be computed. Defaults to np.geomspace(0.05, 200, 512)
disable_site_amp (bool, optional) – if the crustal site amplification should be disable. Defaults to False.

Return type:

None

calc_duration()[source]

Compute the duration by combination of source and path.

Returns:: duration – Computed duration
Return type:: float

calc_fourier_amps(freqs=None)[source]

Compute the acceleration Fourier amplitudes for a frequency range.

Parameters:: freqs (array_like, optional) – Frequency range. If no frequency range is specified then log_spaced_values(0.05, 200.)() is used.
Returns:: fourier_amps – acceleration Fourier amplitudes
Return type:: np.ndarray

property angular_freqs: ndarray: Angular frequency values (rad/sec).

property arias_intensity: float: Arias intensity (m/s).

calc_arias_intensity(tf=None)

Compute the Arias intensity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: arias_intensity – Arias intensity (m/s).
Return type:: float

calc_attenuation(min_freq, max_freq=None)

Compute the site attenuation (κ) based on a log-linear fit.

Parameters:

min_freq (float) – minimum frequency of the fit (Hz).
max_freq (float, optional) – maximum frequency of the fit. If None, then the maximum frequency range is used.

Returns:

atten (float) – attenuation parameter.
r_sqr (float) – squared correlation coefficient of the fit (R²). See scipy.stats.linregress.
freqs (array_like) – selected frequencies
fitted (array_like) – fitted values

Return type:

tuple[float, float, ndarray, ndarray]

Notes

This function computes the site attenuation defined by Anderson & Hough (1984) [@anderson84] as:

$$ a(f) = A_0 exp(-pi kappa f) text( for ) f > f_E $$

for a single Fourier amplitude spectrum

calc_cav(tf=None)

Compute the cumulative absolute velocity (CAV).

Uses an empirical regression on Arias intensity and duration based on observed ground motions.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: cav – Cumulative absolute velocity (m/s).
Return type:: float

calc_osc_accels(osc_freqs, osc_damping=0.05, trans_func=None)

Pseudo-acceleration spectral response of an oscillator.

Parameters:

osc_freqs (float) – Frequency of the oscillator (Hz).
osc_damping (float) – Fractional damping of the oscillator (dec). For example, 0.05 for a damping ratio of 5%.
trans_func (array_like, optional) – Transfer function to be applied to motion prior calculation of the oscillator response.

Returns:

spec_accels – Peak pseudo-spectral acceleration of the oscillator

Return type:

numpy.ndarray

calc_peak(transfer_func=None, **kwds)

Compute the peak response.

Parameters:: transfer_func (array_like, optional) – Transfer function to apply to the motion. If None, then no transfer function is applied.
Returns:: peak – Calculated peak
Return type:: float

calc_pga(tf=None)

Compute the peak ground acceleration.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pga – Peak ground acceleration (g).
Return type:: float

calc_pgv(tf=None)

Compute the peak ground velocity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pgv – Peak ground velocity (cm/sec).
Return type:: float

property cav: float: Cumulative absolute velocity (m/s).

property duration: float: Duration of the ground motion for RVT analysis.

property fourier_amps: ndarray: Acceleration Fourier amplitude values (g-sec).

property freqs: ndarray: Frequency values (Hz).

property pga: float: Peak ground acceleration (g).

property pgv: float: Peak ground velocity (cm/sec).

class pyrvt.motions.StaffordEtAl22Motion(mag, dist_rup=None, dist_jb=None, mechanism='U', method='continuous', delta_ztor=0, freqs=None, disable_site_amp=False)[source]

Bases: RvtMotion

Parameters:

mag (float)
dist_rup (float | None)
dist_jb (float | None)
mechanism (str)
method (str)
delta_ztor (float)
freqs (npt.ArrayLike | None)
disable_site_amp (bool)

__init__(mag, dist_rup=None, dist_jb=None, mechanism='U', method='continuous', delta_ztor=0, freqs=None, disable_site_amp=False)[source]

Point source model developed by Stafford (2021) for a Vs30 of 760 m/s.

Use an RVT framework, and assume the following duration/peak factor models:

Boore & Thompson (2014) for excitation duration
Boore & Thompson (2015) for RMS duration
Vanmarke (1975)/Der Kiureghian (1980) peak factor expression; per Boore & Thompson (2015)

Note that other peak factors models are not permitted to be consistent with the Sea22 model.

Parameters:

mag (float) – moment magnitude of the event.
dist_rup (float, optional) – closest distance to the rupture (km). Either dist_rup or dist_jb must be provided.
dist_jb (float, optional) – Joyner-Boore distance (km). Either dist_rup or dist_jb must be provided.
mechanism (str, optional) – earthquake mechansim. Options are: “U”, “SS”, “NS”, “RS”. Defaults to ‘U’.
method (str, optional) – geometric spreading model. Options are: “continuous” or “trilinear”. Defaults to “continuous”.
delta_ztor (float, optional) – difference in the top of the rutpure (km)
freqs (array_like) – frequencies for which the Fourier amplitude spectrum should be computed. Defaults to np.geomspace(0.05, 200, 512)
disable_site_amp (bool, optional) – if the crustal site amplification should be disable. Defaults to False.

Return type:

None

property angular_freqs: ndarray: Angular frequency values (rad/sec).

property arias_intensity: float: Arias intensity (m/s).

calc_arias_intensity(tf=None)

Compute the Arias intensity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: arias_intensity – Arias intensity (m/s).
Return type:: float

calc_attenuation(min_freq, max_freq=None)

Compute the site attenuation (κ) based on a log-linear fit.

Parameters:

min_freq (float) – minimum frequency of the fit (Hz).
max_freq (float, optional) – maximum frequency of the fit. If None, then the maximum frequency range is used.

Returns:

atten (float) – attenuation parameter.
r_sqr (float) – squared correlation coefficient of the fit (R²). See scipy.stats.linregress.
freqs (array_like) – selected frequencies
fitted (array_like) – fitted values

Return type:

tuple[float, float, ndarray, ndarray]

Notes

This function computes the site attenuation defined by Anderson & Hough (1984) [@anderson84] as:

$$ a(f) = A_0 exp(-pi kappa f) text( for ) f > f_E $$

for a single Fourier amplitude spectrum

calc_cav(tf=None)

Compute the cumulative absolute velocity (CAV).

Uses an empirical regression on Arias intensity and duration based on observed ground motions.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: cav – Cumulative absolute velocity (m/s).
Return type:: float

calc_osc_accels(osc_freqs, osc_damping=0.05, trans_func=None)

Pseudo-acceleration spectral response of an oscillator.

Parameters:

osc_freqs (float) – Frequency of the oscillator (Hz).
osc_damping (float) – Fractional damping of the oscillator (dec). For example, 0.05 for a damping ratio of 5%.
trans_func (array_like, optional) – Transfer function to be applied to motion prior calculation of the oscillator response.

Returns:

spec_accels – Peak pseudo-spectral acceleration of the oscillator

Return type:

numpy.ndarray

calc_peak(transfer_func=None, **kwds)

Compute the peak response.

Parameters:: transfer_func (array_like, optional) – Transfer function to apply to the motion. If None, then no transfer function is applied.
Returns:: peak – Calculated peak
Return type:: float

calc_pga(tf=None)

Compute the peak ground acceleration.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pga – Peak ground acceleration (g).
Return type:: float

calc_pgv(tf=None)

Compute the peak ground velocity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pgv – Peak ground velocity (cm/sec).
Return type:: float

property cav: float: Cumulative absolute velocity (m/s).

property duration: float: Duration of the ground motion for RVT analysis.

property fourier_amps: ndarray: Acceleration Fourier amplitude values (g-sec).

property freqs: ndarray: Frequency values (Hz).

property pga: float: Peak ground acceleration (g).

property pgv: float: Peak ground velocity (cm/sec).

classmethod site_amp(freqs, site_atten)[source]

Parameters:

freqs (ArrayLike)
site_atten (float)

Return type:

ndarray

property dist_ps: float: Equivalent point source distance (km).

static calc_depth_tor(mag, mechanism)[source]

Top of rupture model from Chiou and Youngs (2014)

Parameters:

mag (float) – moment magnitude of the event ($M_w$)
mechanism (str) – fault mechanism. Valid options: “U”, “SS”, “NS”, “RS”.

Returns:

depth_tor – estimated depth to top of rupture (km)

Return type:

float

static calc_duration(corner_freq, dist_ps)[source]

Boore & Thomspson (2014) duration model.

Parameters:

corner_freq (float)
dist_ps (float)

Return type:

float

class pyrvt.motions.CompatibleRvtMotion(osc_freqs, osc_accels_target, duration=None, osc_damping=0.05, event_kwds=None, window_len=None, peak_calculator=None, calc_kwds=None)[source]

Bases: RvtMotion

Response spectrum compatible RVT motion.

A [CompatibleRvtMotion][pyrvt.motions.CompatibleRvtMotion] object is used to compute a Fourier amplitude spectrum that is compatible with a target response spectrum.

Parameters:

osc_freqs (npt.ArrayLike)
osc_accels_target (npt.ArrayLike)
duration (float | None)
osc_damping (float | None)
event_kwds (dict | None)
window_len (int | None)
peak_calculator (str | peak_calculators.Calculator | None)
calc_kwds (dict | None)

property angular_freqs: ndarray: Angular frequency values (rad/sec).

property arias_intensity: float: Arias intensity (m/s).

calc_arias_intensity(tf=None)

Compute the Arias intensity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: arias_intensity – Arias intensity (m/s).
Return type:: float

calc_attenuation(min_freq, max_freq=None)

Compute the site attenuation (κ) based on a log-linear fit.

Parameters:

min_freq (float) – minimum frequency of the fit (Hz).
max_freq (float, optional) – maximum frequency of the fit. If None, then the maximum frequency range is used.

Returns:

atten (float) – attenuation parameter.
r_sqr (float) – squared correlation coefficient of the fit (R²). See scipy.stats.linregress.
freqs (array_like) – selected frequencies
fitted (array_like) – fitted values

Return type:

tuple[float, float, ndarray, ndarray]

Notes

This function computes the site attenuation defined by Anderson & Hough (1984) [@anderson84] as:

$$ a(f) = A_0 exp(-pi kappa f) text( for ) f > f_E $$

for a single Fourier amplitude spectrum

calc_cav(tf=None)

Compute the cumulative absolute velocity (CAV).

Uses an empirical regression on Arias intensity and duration based on observed ground motions.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: cav – Cumulative absolute velocity (m/s).
Return type:: float

calc_osc_accels(osc_freqs, osc_damping=0.05, trans_func=None)

Pseudo-acceleration spectral response of an oscillator.

Parameters:

osc_freqs (float) – Frequency of the oscillator (Hz).
osc_damping (float) – Fractional damping of the oscillator (dec). For example, 0.05 for a damping ratio of 5%.
trans_func (array_like, optional) – Transfer function to be applied to motion prior calculation of the oscillator response.

Returns:

spec_accels – Peak pseudo-spectral acceleration of the oscillator

Return type:

numpy.ndarray

calc_peak(transfer_func=None, **kwds)

Compute the peak response.

Parameters:: transfer_func (array_like, optional) – Transfer function to apply to the motion. If None, then no transfer function is applied.
Returns:: peak – Calculated peak
Return type:: float

calc_pga(tf=None)

Compute the peak ground acceleration.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pga – Peak ground acceleration (g).
Return type:: float

calc_pgv(tf=None)

Compute the peak ground velocity.

Parameters:: tf (array_like, optional) – Transfer function to apply to the motion. If None, no transfer function is applied.
Returns:: pgv – Peak ground velocity (cm/sec).
Return type:: float

property cav: float: Cumulative absolute velocity (m/s).

property duration: float: Duration of the ground motion for RVT analysis.

property fourier_amps: ndarray: Acceleration Fourier amplitude values (g-sec).

property freqs: ndarray: Frequency values (Hz).

property pga: float: Peak ground acceleration (g).

property pgv: float: Peak ground velocity (cm/sec).

__init__(osc_freqs, osc_accels_target, duration=None, osc_damping=0.05, event_kwds=None, window_len=None, peak_calculator=None, calc_kwds=None)[source]

Initialize the motion.

Parameters:

osc_freqs (array_like) – Frequencies of the oscillator response (Hz).
osc_accels_target (array_like) – Spectral acceleration of the oscillator at the specified frequencies (g).
duration (float, optional) – Duration of the ground motion (sec). If None, then the duration is computed using the event_kwds.
osc_damping (float, optional) – Fractional damping of the oscillator (dec). Default value is 0.05 for a damping ratio of 5%.
event_kwds (Dict, optional) – Keywords passed to SourceTheoryMotion and used to compute the duration of the motion. Either duration or event_kwds should be specified.
window_len (int, optional) – Window length used for smoothing the computed Fourier amplitude spectrum. If None, then no smoothing is applied. The smoothing is applied as a moving average with a width of window_len.
peak_calculator (Calculator, optional) – Peak calculator to use. If None, then the default peak calculator is used. The peak calculator may either be specified by a [pyrvt.peak_calculators.Calculator][] object, or by the initials of the calculator using [pyrvt.peak_calculators.get_peak_calculator][].
calc_kwds (dict, optional) – Keywords to be passed during the creation the peak calculator. These keywords are only required for some peak calculators.

Return type:

None