Ground_Motion#

class PySeismoSoil.class_ground_motion.Ground_Motion(data: str | numpy.ndarray, *, unit: str, motion_type: Literal['accel', 'veloc', 'displ'] = 'accel', dt: float | None = None, sep: str = '\t', **kwargs_to_genfromtxt: dict[Any, Any])[source]#

Bases: object

Class implementation of an earthquake ground motion.

Parameters:

  • data (str | np.ndarray) –

    If str: the full file name on the hard drive containing the data. If np.ndarray: the numpy array containing the motion data.

    The motion data can be acceleration, velocity, or displacement.

    The data can have one column (which contains the motion) or two columns (1st column: time; 2nd column: motion). If only one column is supplied, another input parameter dt must also be supplied.

  • unit (str) –

    Valid values include:

    [‘m’, ‘cm’, ‘m/s’, ‘cm/s’, ‘m/s/s’, ‘cm/s/s’, ‘gal’, ‘g’]

  • motion_type (Literal['accel', 'veloc', 'displ']) – Specifying what type of motion “data” contains. It needs to be consistent with “unit”. For example, if motion_type is “accel” and unit is “m/s”, an exception will be raised.

  • dt (float | None) – Recording time interval of the ground motion. If data has only one column, this parameter must be supplied. If data has two columns, this parameter is ignored.

  • sep (str) – Delimiter character for reading the text file. If data is supplied as a numpy array, this parameter is ignored.

  • **kwargs_to_genfromtxt (dict[Any, Any]) – Any extra keyword arguments will be passed to numpy.genfromtxt() function for loading the data from the hard drive (if applicable).

dt#

Recording time interval of the motion.

Type:

float

time#

1D numpy array: the time points in seconds.

Type:

np.ndarray

accel#

A numpy array of two columns, whose first column is identical to “time”, and second column is the acceleration in SI unit.

Type:

np.ndarray

veloc#

A numpy array of two columns, whose first column is identical to “time”, and second column is the velocity in SI unit.

Type:

np.ndarray

displ#

A numpy array of two columns, whose first column is identical to “time”, and second column is the displacement in SI unit.

Type:

np.ndarray

pga, pgv, pgd

Peak ground acceleration, velocity, and displacement in SI unit.

Type:

float

pga_in_gal, pga_in_g, pgv_in_cm_s, pgd_in_cm

PGA, PGV, and PGD in other common units.

Type:

<float>

Arias_Intensity#

A numpy array of two columns, whose first column is identical to “time”, and second column is the Arias intensity.

Type:

np.ndarray

Arias_Intensity_normalized#

A numpy array of two columns, whose first column is identical to “time”, and second column is the normalized Arias intensity.

Type:

np.ndarray

peak_Arias_Intensity#

The last element of the second column of Arias_Intensity.

Type:

float

T5_95#

The time interval (in seconds) between 5% of peak Arias intensity to 95% of peak Arias intensity.

Type:

float

rms_accel, rms_veloc, rms_displ

Root-mean-square acceleration, velocity, and displacement of the motion.

Type:

float

_path_name, _file_name

Names of the directory and file of the input data, if a file name.

Type:

str

Raises:

ValueError – When motion_type has invalid values

Methods Summary

amplify(soil_profile[, boundary, show_fig])

Amplify the ground motion via a 1D soil profile, using linear site amplification method.

amplify_by_tf(transfer_function[, taper, ...])

Amplify (or de-amplify) ground motions in the frequency domain.

bandpass(cutoff_freq[, show_fig, ...])

Zero-phase-shift band-pass filtering.

bandstop(cutoff_freq[, show_fig, ...])

Zero-phase-shift band-stop filtering.

baseline_correct([cutoff_freq, show_fig])

Baseline-correct the acceleration (via zero-phase-shift high-pass method).

compare(another_ground_motion[, ...])

Compare with another ground motion: plot comparison figures showing two time histories and the transfer function between them.

deconvolve(soil_profile[, boundary, show_fig])

Deconvolve the ground motion, i.e., propagate the motion downwards to get the borehole motion (rigid boundary) or the "rock outcrop" motion (elastic boundary).

get_Fourier_spectrum([real_val, ...])

Get Fourier spectrum of the ground motion.

get_response_spectra([T_min, T_max, n_pts, ...])

Get elastic response spectra of the ground motion, using the "exact" solution to the equation of motion (Section 5.2, Dynamics of Structures, Second Edition, by Anil K.

highpass(cutoff_freq[, show_fig, ...])

Zero-phase-shift high-pass filtering.

lowpass(cutoff_freq[, show_fig, ...])

Zero-phase-shift low-pass filtering.

plot([show_as_unit, fig, ax, figsize, dpi])

Plot acceleration, velocity, and displacement waveforms together.

save_accel(fname[, sep, t_prec, ...])

Save the acceleration as a text file.

scale_motion([factor, target_PGA_in_g])

Scale ground motion, either by specifying a factor, or specifying a target PGA level.

summary()

Show a brief summary of the ground motion.

truncate(limit[, arias, extend, show_fig])

Truncate ground motion, removing data points in the head and/or tail.

Methods Documentation

amplify(soil_profile: Vs_Profile, boundary: Literal['elastic', 'rigid'] = 'elastic', show_fig: bool = False) → Ground_Motion[source]#

Amplify the ground motion via a 1D soil profile, using linear site amplification method.

Parameters:

  • soil_profile (Vs_Profile) – The soil profile through which to deconvolve the gound motion.

  • boundary (Literal['elastic', 'rigid']) – The type of boundary of the bottom of the soil profile.

  • show_fig (bool) – Whether to show a figure that illustrates the deconvolution process.

Returns:

output_motion – The amplified ground motion.

Return type:

Ground_Motion

Raises:

When the type of soil_profile is not valid –

amplify_by_tf(transfer_function: Frequency_Spectrum, taper: bool = False, extrap_tf: bool = True, deconv: bool = False, show_fig: bool = False, dpi: float = 100, return_fig_obj: bool = False) → tuple[PySeismoSoil.class_ground_motion.Ground_Motion, matplotlib.figure.Figure | None, matplotlib.axes._axes.Axes | None][source]#

Amplify (or de-amplify) ground motions in the frequency domain. The mathematical process behind this function is as follows:

  1. INPUT = fft(input)

  2. OUTPUT = INPUT * TRANS_FUNC

  3. output = ifft(OUTPUT)

Parameters:

  • transfer_function (Frequency_Spectrum) – The transfer function to apply to the ground motion. It only needs to be “single-sided” (see notes below).

  • taper (bool) – Whether to taper the input acceleration (using Tukey taper)

  • extrap_tf (bool) – Whether to extrapolate the transfer function if its frequency range does not reach the frequency range implied by the input motion

  • deconv (bool) – If False, a regular amplification is performed; otherwise, the transfer function is “deducted” from the input motion (“deconvolution”).

  • show_fig (bool) – Whether to show an illustration of how the calculation is carried out.

  • dpi (float) – Desired DPI for the figures; only effective when show_fig is True.

  • return_fig_obj (bool) – Whether to return figure and axis objects to the caller.

Returns:

  • output_motion (Ground_Motion) – The resultant ground motion in time domain

  • fig (Figure | None) – The figure object being created or being passed into this function.

  • ax (Axes | None) – The axes object being created or being passed into this function.

Raises:

TypeError – When the type of transfer_function is not valid

Notes

“Single sided”:

For example, the sampling time interval of input_motion is 0.01 sec, then the Nyquist frequency is 50 Hz. Therefore, the transfer function needs to contain information at least up to the Nyquist frequency, i.e., at least 0-50 Hz, and anything above 50 Hz will not affect the input motion at all.

bandpass(cutoff_freq: tuple[float, float], show_fig: bool = False, filter_order: int = 4, padlen: int = 150) → Ground_Motion[source]#

Zero-phase-shift band-pass filtering.

Parameters:

  • cutoff_freq (tuple[float, float]) – Cut-off frequencies (in Hz), from low to high.

  • show_fig (bool) – Whether to show a figure of “before vs after”

  • filter_order (int) – Filter order.

  • padlen (int) – Pad length (the number of elements by which to extend x at both ends of axis before applying the filter). If None, use the default value (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.filtfilt.html).

Returns:

filtered – Filtered signal

Return type:

Ground_Motion

bandstop(cutoff_freq: tuple[float, float], show_fig: bool = False, filter_order: int = 4, padlen: int = 150) → Ground_Motion[source]#

Zero-phase-shift band-stop filtering.

Parameters:

  • cutoff_freq (tuple[float, float]) – Cut-off frequencies (in Hz), from low to high.

  • show_fig (bool) – Whether to show a figure of “before vs after”

  • filter_order (int) – Filter order.

  • padlen (int) – padlen : int Pad length (the number of elements by which to extend x at both ends of axis before applying the filter). If None, use the default value (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.filtfilt.html).

Returns:

filtered – Filtered signal

Return type:

Ground_Motion

baseline_correct(cutoff_freq: float = 0.2, show_fig: bool = False) → Ground_Motion[source]#

Baseline-correct the acceleration (via zero-phase-shift high-pass method).

Parameters:

  • cutoff_freq (float) – The frequency (unit: Hz) for high passing. Energies below this frequency are filtered out.

  • show_fig (bool) – Whether to show figures comparing before and after.

Returns:

corrected – The baseline-corrected ground motion, with SI units.

Return type:

Ground_Motion

compare(another_ground_motion: Ground_Motion, this_ground_motion_as_input: bool = True, smooth: bool = True, input_accel_label: str = 'Input', output_accel_label: str = 'Output') → tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes][source]#

Compare with another ground motion: plot comparison figures showing two time histories and the transfer function between them.

Parameters:

  • another_ground_motion (Ground_Motion) – Another ground motion object.

  • this_ground_motion_as_input (bool) – If True, this ground motion is treated as the input ground motion. Otherwise, the other ground motion is treated as the input.

  • smooth (bool) – In the comparison plot, whether to also show the smoothed amplification factor.

  • input_accel_label (str) – The text label for the input acceleration in the figure legend.

  • output_accel_label (str) – The text label for the output acceleration in the figure legend.

Returns:

  • fig (Figure) – The figure object created in this function.

  • ax (Axes) – The axes object created in this function.

Raises:

TypeError – When the type of another_ground_motion is not valid

deconvolve(soil_profile: Vs_Profile, boundary: Literal['elastic', 'rigid'] = 'elastic', show_fig: bool = False) → Ground_Motion[source]#

Deconvolve the ground motion, i.e., propagate the motion downwards to get the borehole motion (rigid boundary) or the “rock outcrop” motion (elastic boundary).

Parameters:

  • soil_profile (Vs_Profile) – The soil profile through which to deconvolve the gound motion.

  • boundary (Literal['elastic', 'rigid']) – The type of boundary of the bottom of the soil profile.

  • show_fig (bool) – Whether to show a figure that illustrates the deconvolution process.

Returns:

deconv_motion – The deconvolved motion on the rock outcrop or in a borehole.

Return type:

Ground_Motion

Raises:

TypeError – When the type of soil_profile is not valid

get_Fourier_spectrum(real_val: bool = True, double_sided: bool = False, show_fig: bool = False) → Frequency_Spectrum[source]#

Get Fourier spectrum of the ground motion.

Parameters:

  • real_val (bool) – Whether to return the amplitude (or “magnitude”) of the complex numbers.

  • double_sided (bool) – Whether to return the second half of the spectrum (i.e. beyond the Nyquist frequency).

  • show_fig (bool) – Whether to show figures of the spectrum.

Returns:

fs – A frequency spectrum object.

Return type:

Frequency_Spectrum

get_response_spectra(T_min: float = 0.01, T_max: float = 10, n_pts: int = 60, damping: float = 0.05, show_fig: bool = True, parallel: bool = False, n_cores: int | None = None, subsample_interval: int = 1) → tuple[numpy.ndarray, ...][source]#

Get elastic response spectra of the ground motion, using the “exact” solution to the equation of motion (Section 5.2, Dynamics of Structures, Second Edition, by Anil K. Chopra).

Parameters:

  • T_min (float) – Minimum period value to calculate the response spectra. Unit: sec.

  • T_max (float) – Maximum period value to calculate the response spectra. Unit: sec.

  • n_pts (int) – Number of points you want for the response spectra. A high number increases computation time.

  • damping (float) – Damping of the dash pots. Do not use “percent” as unit. Unit: 1 (i.e., not percent).

  • show_fig (bool) – Whether to show a figure of the response spectra.

  • parallel (bool) – Whether to perform the calculation in parallel.

  • n_cores (int | None) – Number of cores to use in parallel. Not necessary if not parallel.

  • subsample_interval (int) – The interval at which to subsample the input acceleration in the time domain. A higher number reduces computation time, but could lead to less accurate results.

Returns:

(Tn, SA, PSA, SV, PSV, SD, fn) – Periods, spectral acceleration, pseudo spectral acceleration, spectral velocity, pseudo spectral velocity, spectral displacement, and frequencies, respectively. Units: SI.

Return type:

tuple[np.ndarray, …]

highpass(cutoff_freq: float, show_fig: bool = False, filter_order: int = 4, padlen: int = 150) → Ground_Motion[source]#

Zero-phase-shift high-pass filtering.

Parameters:

  • cutoff_freq (float) – Cut-off frequency (unit: Hz).

  • show_fig (bool) – Whether to show a figure of “before vs after”

  • filter_order (int) – Filter order.

  • padlen (int) – Pad length (the number of elements by which to extend x at both ends of axis before applying the filter). If None, use the default value (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.filtfilt.html).

Returns:

filtered – Filtered signal.

Return type:

Ground_Motion

lowpass(cutoff_freq: float, show_fig: bool = False, filter_order: int = 4, padlen: int = 150) → Ground_Motion[source]#

Zero-phase-shift low-pass filtering.

Parameters:

  • cutoff_freq (float) – Cut-off frequency (unit: Hz).

  • show_fig (bool) – Whether to show a figure of “before vs after”

  • filter_order (int) – Filter order.

  • padlen (int) – Pad length (the number of elements by which to extend x at both ends of axis before applying the filter). If None, use the default value (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.filtfilt.html).

Returns:

filtered – Filtered signal.

Return type:

Ground_Motion

plot(show_as_unit: str = 'm', fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes._axes.Axes | None = None, figsize: tuple[float, float] = (5, 6), dpi: float = 100) → tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes][source]#

Plot acceleration, velocity, and displacement waveforms together.

Parameters:

  • show_as_unit (str) – What unit to convert the ground motion into, when plotting.

  • fig (Figure | None) – Figure object. If None, a new figure will be created.

  • ax (Axes | None) – Axes object. If None, a new axes will be created.

  • figsize (tuple[float, float]) – Figure size in inches, as a tuple of two numbers. The figure size of fig (if not None) will override this parameter.

  • dpi (float) – Figure resolution. The dpi of fig (if not None) will override this parameter.

Returns:

  • fig (Figure) – The figure object being created or being passed into this function.

  • ax (Axes) – The axes object being created or being passed into this function.

Raises:

ValueError – When the value of show_as_unit is invalid

save_accel(fname: str, sep: str = '\t', t_prec: str = '%.5g', motion_prec: str = '%.5g', unit: str = 'm/s/s') → None[source]#

Save the acceleration as a text file.

Parameters:

  • fname (str) – File name (including path).

  • sep (str) – Delimiter.

  • t_prec (str) – The precision specifier for the “time” column.

  • motion_prec (str) – The precision specifier for the “motion” column.

  • unit (str) – What unit shall the exported acceleration be in.

scale_motion(factor: float = 1.0, target_PGA_in_g: float | None = None) → Ground_Motion[source]#

Scale ground motion, either by specifying a factor, or specifying a target PGA level.

Parameters:

  • factor (float) – The factor to multiply to the original acceleration (with the unit of m/s/s)

  • target_PGA_in_g (float | None) – The target PGA (in g). If it is not None, it overrides factor.

Returns:

scaled_motion – The scaled motion

Return type:

Ground_Motion

summary() → None[source]#

Show a brief summary of the ground motion.

truncate(limit: tuple[float, float], arias: bool = True, extend: tuple[float, float] = (0, 0), show_fig: bool = False) → tuple[PySeismoSoil.class_ground_motion.Ground_Motion, matplotlib.figure.Figure | None, matplotlib.axes._axes.Axes | None, tuple[int, int]][source]#

Truncate ground motion, removing data points in the head and/or tail.

Parameters:

  • limit (tuple[float, float]) – The lower/upper bounds of time (e.g., [2, 95]) or normalized Arias intensity (e.g., [0.05, 0.95]).

  • arias (bool) – If True, limit means the normalized Arias intensity. Otherwise, limit means the actual time.

  • extend (tuple[float, float]) – How many seconds to extend before and after the original truncated time limits. For example, if extend is [5, 5] sec, and the original time limits are [3, 50] sec, then the actual time limits are [0, 55] sec. (3 - 5 = -2 smaller than 0, so truncated at 0.)

  • show_fig (bool) – Whether to show the waveforms before and after truncation.

Returns:

  • truncated_accel (Ground_Motion) – Truncated ground motion.

  • fig (Figure | None) – The figure object being created or being passed into this function.

  • ax (Axes | None) – The axes object being created or being passed into this function.

  • (n1, n2) (tuple[int, int]) – The indices at which signal is truncated. In other words, truncated_accel = original_accel[n1 : n2].

Raises:

  • TypeError – When the type of limit or extend is invalid

  • ValueError – When the value or dimension of limit or extend is invalid