Skip to content

API Reference

gmspy.SeismoGM class

gmspy.SeismoGM 

SeismoGM(dt: float, acc: Union[list, tuple, ndarray], unit: str = 'g')

A class for computing various intensity measures (IMs) of ground motions, as well as elastic response spectra, constant ductility response spectra, and spectrum-related intensity measures.

See the following references for details on IMs:

  • [1] Hariri-Ardebili M A, Saouma V E. Probabilistic seismic demand model and optimal intensity measure for concrete dams[J]. Structural Safety, 2016, 59: 67-85. .. DOI: https://doi.org/10.1016/j.strusafe.2015.12.001 <https://doi.org/10.1016/j.strusafe.2015.12.001>_
  • [2] Yan Y, Xia Y, Yang J, et al. Optimal selection of scalar and vector-valued seismic intensity measures based on Gaussian Process Regression[J]. Soil Dynamics and Earthquake Engineering, 2022, 152: 106961. .. DOI: https://doi.org/10.1016/j.soildyn.2021.106961 <https://doi.org/10.1016/j.soildyn.2021.106961>_

Parameters:

Name Type Description Default
dt float

The size of the time step of the input acceleration time history.

 required
acc Union[list, tuple, ndarray]

The acceleration time history.

 required
unit str

Unit of input acceleration time-history, by default “g”, ignoring time unit “/s2”.

 'g'

get_acc 

get_acc()

return acceleration time-history.

get_avdsi 

get_avdsi(damp_ratio: float = 0.05)

Acceleration (ASI)，Velocity (VSI) and Displacement(DSI) Spectrum Intensity.

Parameters:

Name Type Description Default
damp_ratio float

Damping ratio, by default 0.05.

 0.05

Returns:

Name Type Description
AVD_SI 1D ArrayLike

Each element is in the order of acceleration, velocity and displacement.

get_avgsavd 

get_avgsavd(Tavg: Union[list, tuple, ndarray], damp_ratio: float = 0.05, n_jobs: int = 0)

Average Spectral Acceleration, Velocity and Displacement. They are computed as the geometric mean.

Parameters:

Name Type Description Default
Tavg 1D ArrayLike

Period series used to calculate Average Spectral Acceleration.

 required
damp_ratio float

Damping ratio, by default 0.05.

 0.05
n_jobs int, optional, by default 0

If 0, do not use parallelism. If an integer greater than 0, call joblib for parallel computing, and the number of cpu cores used is n_jobs. If -1, use all cpu cores.

 0

Returns:

Name Type Description
Savd_avg 1D ArrayLike

Average Spectral Acceleration. Each element is in the order of acceleration, velocity and displacement.

get_brac_td 

get_brac_td()

Bracketed duration. The total time elapsed between the first and the last excursions of a specified level of acceleration (default is 5% of PGA).

get_cavdi 

get_cavdi(acc_cutoff_level: float = None)

Cumulative Absolute Velocity (CAV) ，Displacement (CAD) and Impetus(CAI). See Campbell, Kenneth W and Yousef Bozorgnia. “Use of Cumulative Absolute Velocity ( CAV ) in Damage Assessment.” (2012).

Parameters:

Name Type Description Default
acc_cutoff_level float

The acceleration cutoff level, only data with abs(acc)>=a will be used. Unit must be m/s2. See get_cavdi5().

 None

get_cavdi5 

get_cavdi5(acc_cutoff_level: float = 0.05)

Bracketed Cumulative Absolute Velocity (CAV5) ，Displacement (CAD5) and Impetus(CAI5). The cumulative absolute velocity estimated for ground motion time series with an acceleration cutoff of 5 cm/s^2, well known as CAV5. This intensity measure is very useful in geotechnical problems involving seismic actions, and several references used this IM.

See Kramer SL, Mitchell RA. Ground Motion Intensity Measures for Liquefaction Hazard Evaluation. Earthquake Spectra. 2006;22(2):413-438. doi:10.1193/1.2194970

Parameters:

Name Type Description Default
acc_cutoff_level float

The acceleration cutoff level, only data with abs(acc)>=a will be used. Unit must be m/s2.

 0.05 m/s2

get_cavstd 

get_cavstd(acc_cutoff_level: float = None)

Standardized Cumulative Absolute Velocity (CAVSTD) [Campbell and Bozorgnia 2011]. See Campbell, Kenneth W and Yousef Bozorgnia. “Use of Cumulative Absolute Velocity ( CAV ) in Damage Assessment.” (2012).

Parameters:

Name Type Description Default
acc_cutoff_level float

The acceleration cutoff level, only data with abs(acc)>=a will be used. Unit must be m/s2. See get_cavdi5().

 None

get_cavstd5 

get_cavstd5(acc_cutoff_level: float = 0.05)

Bracketed Standardized Cumulative Absolute Velocity (CAVstd5). The cumulative Standardized absolute velocity estimated for ground motion time series with an acceleration cutoff of 5 cm/s^2, well known as CAVstd5. This intensity measure is very useful in geotechnical problems involving seismic actions, and several references used this IM.

See Kramer SL, Mitchell RA. Ground Motion Intensity Measures for Liquefaction Hazard Evaluation. Earthquake Spectra. 2006;22(2):413-438. doi:10.1193/1.2194970

Parameters:

Name Type Description Default
acc_cutoff_level float

The acceleration cutoff level, only data with abs(acc)>=a will be used. Unit must be m/s2.

 0.05 m/s2

get_const_duct_spec 

get_const_duct_spec(Ts: Union[float, list, ndarray], harden_ratio: float = 0.02, damp_ratio: float = 0.05, analy_dt: float = None, mu: float = 5, niter: int = 100, tol: float = 0.01, n_jobs: int = 0, plot: int = False) -> np.ndarray

Constant-ductility inelastic spectra. See

  • section 7.5 in Anil K. Chopra (DYNAMICS OF STRUCTURES, Fifth Edition, 2020) and
  • the notes "Inelastic Response Spectra" (CEE 541. Structural Dynamics) by Henri P. Gavin.
  • Papazafeiropoulos, George, and Vagelis Plevris."OpenSeismoMatlab: A new open-source software for strong ground motion data processing."Heliyon 4.9 (2018): e00784.

Parameters:

Name Type Description Default
Ts ArrayLike

Eigen-periods for which the response spectra are requested.

 required
harden_ratio float

Stiffness-hardening ratio, by default 0.02

 0.02
damp_ratio float

Damping ratio, by default 0.05.

 0.05
analy_dt float

Time step for bilinear SDOF response analysis, if None, default=dt.

 = None
mu float

Target ductility ratio, by default 5

 5
niter int

Maximum number of iterations, by default 100

 100
tol float

Controls the tolerance of ductility ratio convergence, by default 0.01

 0.01
n_jobs int, optional, by default 0
  • If 0, do not use parallelism.
  • If an integer greater than 0, call joblib for parallel computing,
  • and the number of cpu cores used is n_jobs.
  • If -1, use all cpu cores.
 0
plot int

If True, plot spectra.

 False

Returns:

Type Description
Size (len(Ts), 6) numpy array

Each column corresponds to acceleration Sa, velocity Sv, displacement Sd spectra, yield displacement Dy, strength reduction factor Ry, and yield strength factor Cy (1/Ry).

get_d_v 

get_d_v()

Peak displacement and velocity ratio (PGD/PGV).

get_disp 

get_disp()

return displacement time-history.

get_eda 

get_eda(freq=9)

EDA: Effective design acceleration, defined as the peak acceleration value found after lowpass filtering the input time history with a cut-off frequency of 9 Hz [Benjamin and Associates, 1988].

Parameters:

Name Type Description Default
freq

Frequency threshold.

 9

get_elas_spec 

get_elas_spec(Ts: Union[float, list, ndarray], damp_ratio: float = 0.05, method: str = 'nigam_jennings', n_jobs: int = 0, plot: bool = False)

Computing the Elastic Response Spectrum.

Parameters:

Name Type Description Default
Ts Union[float, ArrayLike]

Eigenperiods for which the response spectra are requested.

 required
damp_ratio float

Damping ratio, by default 0.05.

 0.05
method str

Linear Dynamic Time-History Analysis method, optional, one of ("FFT", "Nigam_Jennings", "Newmark0", "Newmark1"):

  • "FFT"---Fast Fourier Transform;
  • "Nigam_Jennings"---exact solution by interpolating the excitation over each time interval;
  • "Newmark0"---const acceleration Newmark-beta method, gamma=0.5, beta=0.25;
  • "Newmark1"---linear acceleration Newmark-beta method, gamma=0.5, beta=1/6.

.. note:: It is recommended to use the “Nigam_Jennings” method as this is exact for linear systems and will be accelerated using numba.jit <https://numba.readthedocs.io/en/stable/user/jit.html>_ so speed of computation should not be an issue.

 'nigam_jennings'
n_jobs int, optional, by default 0
  • If 0, do not use parallelism.
  • If an integer greater than 0, call joblib for parallel computing,
  • and the number of cpu cores used is n_jobs.
  • If -1, use all cpu cores.
 0
plot bool

If True, plot spectra.

 False

Returns:

Name Type Description
output (len(Ts), 5) ArrayLike.

Each column is the pseudo-acceleration spectrum, pseudo-velocity spectrum, acceleration spectrum, velocity spectrum and displacement spectrum in turn.

get_epavd 

get_epavd(damp_ratio: float = 0.05)

Effective peak acceleration (EPA), velocity (EPV) and displacement (EPD).

Parameters:

Name Type Description Default
damp_ratio float

Damping ratio, by default 0.05.

 0.05

Returns:

Name Type Description
EPAVD 1D ArrayLike

Each element is in the order of acceleration, velocity and displacement.

get_fou_pow_spec 

get_fou_pow_spec(plot: bool = False)

The Fourier Amplitude Spectrum and the Power Spectrum (or Power Spectral Density Function) are computed by means of Fast Fourier Transformation (FFT) of the input time-history. The Fourier amplitude spectrum shows how the amplitude of the ground motion is distributed with respect to frequency (or period), effectively meaning that the frequency content of the given accelerogram can be fully determined. The power spectral density function, on the other hand, may be used to estimate the statistical properties of the input ground motion and to compute stochastic response using random vibration techniques.

  • Fourier Amplitude is computed as the square root of the sum of the squares of the real and imaginary parts of the Fourier transform: SQRT (Re^2+Im^2);
  • Fourier Phase is computed as the angle given by the real and imaginary parts of the Fourier transform: ATAN (Re/Im);
  • Power Spectral Amplitude is computed as FourierAmpl^2/(PidurationRmsAcc^2), where duration is the time length of the record, RmsAcc is the acceleration RMS and Pi is 3.14159.

Parameters:

Name Type Description Default
plot bool

If True, plot time histories.

 False

Returns:

Name Type Description
freq 1D ArrayLike

Frequency.
amp 1D ArrayLike

Fourier Amplitude.
phase 1D ArrayLike

Fourier Phase.
pow_amp 1D ArrayLike

Power Spectral Amplitude.

get_hsi 

get_hsi(damp_ratio: float = 0.05)

Housner Spectra Intensity (HSI).

Parameters:

Name Type Description Default
damp_ratio float

Damping ratio, by default 0.05.

 0.05

Returns:

Name Type Description
HSI float

Housner Spectra Intensity (HSI)

get_ia 

get_ia()

return Arias intensity IA. The Arias intensity (IA) is a measure of the strength of a ground motion. It determines the intensity of shaking by measuring the acceleration of transient seismic waves. It has been found to be a fairly reliable parameter to describe earthquake shaking necessary to trigger landslides. It was proposed by Chilean engineer Arturo Arias in 1970.

It is defined as the time-integral of the square of the ground acceleration:

.. math::

I_{A}={rac{\pi}{2g}}\int_{0}^{T_{d}}a(t)^{2}dt} (m/s)

where g is the acceleration due to gravity and Td is the duration of signal above threshold. The Arias Intensity could also alternatively be defined as the sum of all the squared acceleration values from seismic strong motion records.

get_ic 

get_ic()

Characteristic Intensity (Ic).

get_icm 

get_icm()

Cosenza–Manfredi Intensity.

get_if 

get_if()

Fajfar index.

get_ima 

get_ima()

Return modified Arias intensity Ima [Araya and Saragoni(1980)]. Ia/(nZero.^2), nZero is the number of zero points in the acceleration time-history per unit time.

get_ims 

get_ims(display_results: bool = False)

return various IMs independent of response spectra.

display_results: bool If True, display the results.

Returns:

Type Description
A dict of IMs.
* PGA: peak ground acceleration;
* PGV: peak ground velocity;
* PGD: peak ground displacement;
* V_A: PGV/PGA;
* D_V: PGD/PGV;
* EDA: effective design acceleration;
* Ia: Arias intensity;
* Ima: Modified Arias intensity;
* MIV: Maximum Incremental Velocity;
* Arms, Vrms, Drms: Root-mean-square of acceleration, velocity, and displacement;
* Pa, Pv, Pd: Housner earthquake power index of acceleration, velocity, and displacement;
* Ra, Rv, Rd: Riddell index of acceleration, velocity, and displacement;
* SED: Specific Energy Density;
* If: Fajfar index;
* Ic: Park-Ang Index, i.e., characteristic intensity.
* Icm: Cosenza–Manfredi Intensity;
* CAV, CAD, CAI: Cumulative Absolute Velocity, Displacement and Impetus;
* CAV5, CAD5, CAI5: Cumulative Absolute Velocity, Displacement and Impetus estimated for ground motion time series with an acceleration cutoff of 5 cm/s^2;
* CAVstd: Standardized Cumulative Absolute Velocity;
* CAVstd5: Standardized Cumulative Absolute Velocity estimated for ground motion time series with an acceleration cutoff of 5 cm/s^2;
* Ip: Impulsivity Index;
* Tsig_5_95: 5%-95% Arias intensity duration;
* Tsig_5_75: 5%-75% Arias intensity duration;
* Tbd: Bracketed duration;
* Tud: Uniform duration.

get_ip 

get_ip()

Impulsivity Index (IP) [Panella et al., 2017]. An indicator of the impulsive character of the ground motion and is calculated as the developed length of velocity of the velocity time-series divided by the Peak Ground Velocity.

get_miv 

get_miv()

Maximum Incremental Velocity (MIV), defined as the maximum value of the time integral of the acceleration between all two zero points.

get_pavd 

get_pavd()

Housner earthquake power index, Pa, Pv, Pd

get_pga 

get_pga()

return peak ground values of acceleration (PGA).

get_pgd 

get_pgd()

return peak ground values of displacement (PGD).

get_pgv 

get_pgv()

return peak ground values of velocity (PGV).

get_ravd 

get_ravd()

Riddell index，Ra, Rv, Rd

get_rms 

get_rms()

Root-mean-square (RMS) of acceleration, velocity and displacement.

get_sac 

get_sac(T1: Union[float, list, ndarray], damp_ratio: float = 0.05, alpha: float = 0.5, beta: float = 0.5)

Cordova Intensity.

Parameters:

Name Type Description Default
T1 Union[float, ArrayLike]

The 1st order natural period of the structure.

 required
damp_ratio float

Damping ratio, by default 0.05.

 0.05
alpha float

coefficient.

 0.5
beta float

coefficient.

 0.5

Returns:

Name Type Description
Sac Union[float, ArrayLike]

Cordova Intensity.

get_samp 

get_samp(T1: Union[float, list, ndarray], T2: Union[float, list, ndarray], m1: Union[float, list, ndarray], m2: Union[float, list, ndarray], damp_ratio: float = 0.05)

Multiple-Period Intensities.

Parameters:

Name Type Description Default
T1 Union[float, ArrayLike]

The 1st order natural period of the structure.

 required
T2 Union[float, ArrayLike]

The 2nd order natural period of the structure.

 required
m1 Union[float, ArrayLike]

The 1st order modal participation factor.

 required
m2 Union[float, ArrayLike]

The 2nd order modal participation factor.

 required
damp_ratio float

Damping ratio, by default 0.05.

 0.05

Returns:

Name Type Description
Sa_mp Union[float, ArrayLike]

Multiple-Period Intensity.

get_savam 

get_savam(T1: Union[float, list, ndarray], T2: Union[float, list, ndarray], T3: Union[float, list, ndarray] = None, damp_ratio: float = 0.05, alpha: float = 1 / 3, beta: float = 1 / 3, gamma: float = 1 / 3)

Vamvatsikos Intensity.

Parameters:

Name Type Description Default
T1 Union[float, ArrayLike]

The 1st order natural period of the structure.

 required
T2 Union[float, ArrayLike]

The 2nd order natural period of the structure.

 required
T3 Union[float, ArrayLike], optional, by default None

If None, default is 2 * T1

 None
damp_ratio float

Damping ratio, by default 0.05.

 0.05
alpha float

coefficient.

 1 / 3
beta float

coefficient.

 1 / 3
gamma float

coefficient.

 1 / 3

Returns:

Name Type Description
Sa_vam Union[float, ArrayLike]

Vamvatsikos Intensity.

get_savdp 

get_savdp(damp_ratio: float = 0.05)

The peak of the response spectra.

Parameters:

Name Type Description Default
damp_ratio float

Damping ratio, by default 0.05.

 0.05

Returns:

Name Type Description
Savd_p 1D ArrayLike

Each element is in the order of acceleration, velocity and displacement.

get_sed 

get_sed()

Specific Energy Density (SED).

get_time 

get_time()

return time array.

get_time_hists 

get_time_hists()

return acceleration, velocity, and displacement time history.

Returns:

Type Description
A length 3 tuple of acceleration, velocity, and displacement time histories.

get_truncate_hists 

get_truncate_hists(lower: float = 0.05, upper: float = 0.95, return_idx: bool = False)

Returns the truncated time-histories for lower-upper Arias intensity.

Parameters:

Name Type Description Default
lower float

Lower limit of truncation.

 0.05
upper float

Upper limit of truncation.

 0.95
return_idx bool

Whether return index.

 False

Returns:

Name Type Description
if return_idx is True:

Return the index.
else

Return (acc, vel, disp): 1D Array like.

get_unif_td 

get_unif_td()

Uniform duration. The total time during which the acceleration is larger than a given threshold value (default is 5% of PGA).

get_v_a 

get_v_a()

Peak velocity and acceleration ratio (PGV/PGA).

get_vel 

get_vel()

return velocity time-history.

plot_hist 

plot_hist()

Plot the time-histories.

set_units 

set_units(acc: str = 'g', vel: str = 'cm', disp: str = 'cm', verbose: bool = True)

Specify the unit of input acceleration time-history and the units of output velocity and displacement.

Parameters:

Name Type Description Default
acc str, optional, one of ('g', 'm', 'cm', 'mm', 'in', 'ft')

Unit of input acceleration time-history, by default “g”, ignoring time unit /s2.

 'g'
vel str, optional, one of ('m', 'cm', 'mm', 'in', 'ft')

Unit of output velocity, by default “cm”, ignoring time unit /s.

 'cm'
disp str, optional, one of ('m', 'cm', 'mm', 'in', 'ft')

Unit of output displacement, by default “cm”.

 'cm'
verbose bool

Print info.

 True

Ohther gmspy module contents

gmspy.loadPEER 

loadPEER(filename: Union[str, Path, None] = None, plot: bool = False) -> NamedTuple

This function is used to read ground motion data from PEER database.

Parameters:

Name Type Description Default
filename Optional[str]

Path of the PEER ground motion file. If None, tkinter will be used.

 None
plot bool

If True, plot the time-history, by default False

 False

Returns:

Name Type Description
GMdata namedtuple(GM, [tsg, times, dt, npts, RSN, file_name, unit])
Each field is:
* "tsg" -- Time-history data.
* "times" -- Times data.
* "dt" -- Time step size.
* "npts" -- Number of points.
* "RSN" -- RSN tag.
* "file_name" -- File name.
* "unit" -- data unit.
You can call the output like this, ``tsg = GMdata.tsg``.
See .. _collections.namedtuple: https://docs.python.org/3/library/collections.html#collections.namedtuple.

gmspy.loadPEERbatch 

loadPEERbatch(file_path: str, vertical_factor: float = 0.65, print_info: bool = True, return_vel: bool = False, return_disp: bool = False)

Read PEER ground motion data under a certain path in batches. The requirement is that the data has been decompressed into *.AT2, *.VT2, *.DT2 files.

Parameters:

Name Type Description Default
file_path str or ``pathlib.Path``

The path to the data file.

 required
vertical_factor float

The scaling factor used when the vertical component is missing. Multiply it by the horizontal component with the largest peak value to get the vertical component.

 0.65
print_info bool

Print information when reading data.

 True
return_vel bool

Read and return the velocity data identified by *.VT2 if True.

 False
return_disp bool

Read and return the displacement data identified by *.DT2 if True.

 False

Returns:

Type Description
* If return_vel is ``False`` and return_disp is ``False``:

return accel_data: dict
* If return_vel is ``True`` and return_disp is ``True``:

return (accel_data: dict, vel_data: dict, disp_data: dict)
* If return_vel is ``True`` and return_disp is ``False``:

return (accel_data: dict, vel_data: dict)
* If return_vel is ``False`` and return_disp is ``True``:

return (accel_data: dict, disp_data: dict)
``accel_data``, ``vel_data`` or ``disp_data`` is a ``dict`` obj with unique ``RSN`` tags as keys,
and each value is a ``namedtuple``:
``namedtuple("GM", ["tsgH1", "tsgH2", "tsgV3", "times", "dt", "npts", "filenames"])``
* tsgH1: 1D numpy array, horizontal component with largest peak.
* tsgH2: 1D numpy array, the second horizontal component.
* tsgV3: 1D numpy array, vertical component.
* times: 1D numpy array, the times corresponding to the components.
* dt: float, Sampling time step.
* npts: int, the number of points along the components.
* filenames: list, the file names of the components.
You can call the output like this, ``tsg = accel_data[RSNtag].tsgH1``.
See .. _collections.namedtuple: https://docs.python.org/3/library/collections.html#collections.namedtuple.

Examples:

>>> import matplotlib.pyplot as plt
>>> accel = loadPEERbatch(file_path)
>>> tag = 666  # A specific RSN tag in accel.keys()
>>> print(
>>>     np.max(np.abs(accel[tag].tsgH1)),
>>>     np.max(np.abs(accel[tag].tsgH2)),
>>>     np.max(np.abs(accel[tag].tsgV3))
>>> )
>>> plt.plot(accel[tag].times, accel[tag].tsgH1, c='b', label='H1')
>>> plt.plot(accel[tag].times, accel[tag].tsgH2, c='r', label='H2')
>>> plt.plot(accel[tag].times, accel[tag].tsgV3, c='g', label='V3')
>>> plt.legend()
>>> plt.show()

gmspy.load_gm_examples 

load_gm_examples(name: str = 'Kobe', plot: bool = False)

load built-in ground motions examples.

Parameters:

Name Type Description Default
name str

Record name, by default "Kobe". One of ("ChiChi", "Friuli", "Hollister", "Imperial_Valley", "Kobe", "Kocaeli", "Landers", "Loma_Prieta", "Northridge", "Trinidad")

 'Kobe'
plot bool

If True, plot ground motion, by default False.

 False

Returns:

Name Type Description
ts 1D array_like

Time.
acc 1D array_like

Acceleration Time-History.

gmspy.baselinecorr 

baselinecorr(ts: list, acc: list, poly_degree: int = 1, plot: bool = False)

Baseline Correction through regression analysis, consists in (1) determining, through regression analysis (least-squares-fit method), the polynomial curve that best fits the time-acceleration pairs of values and then (2) subtracting from the actual acceleration values their corresponding counterparts as obtained with the regression-derived equation.

Parameters:

Name Type Description Default
ts (array_like, shape(M))

The time vector of the input acceleration time history acc.

 required
acc (array_like, shape(M))

Vector of the acceleration history of the excitation imposed at the base.

 required
poly_degree int

Polynomial degree to adopt. 0-constant, 1-linear, 2-quadratic and 3-cubic, and so on.

 1
plot bool

If True, plot time histories.

 False

Returns:

Name Type Description
cor_acc (array_like, shape(M))

Time-history of acceleration.
cor_vel (array_like, shape(M))

Time-history of velocity.
cor_disp (array_like, shape(M))

Time-history of displacement.

gmspy.resample 

resample(dt: float, acc: Union[list, tuple, ndarray], dti: float)

Resampling the signal.

Parameters:

Name Type Description Default
dt float

The size of the time step of the input acceleration time history.

 required
acc Union[list, tuple, ndarray]

The acceleration time history.

 required
dti float

New time step size for resampling of the input acceleration time history.

 required

Returns:

Name Type Description
time 1D ArrayLike

New time.
acc 1D ArrayLike

Resamped acceleration time history.

gmspy.freq_filt 

freq_filt(dt: float, acc: Union[list, tuple, ndarray], ftype: str = 'Butterworth', btype: str = 'bandpass', order: int = 4, freq1: float = 0.1, freq2: float = 24.99, rp: float = 3, plot: bool = False)

Filtering employed to remove unwanted frequency components from a given acceleration signal.

.. note:: freq2 cannot be higher than 1/2 of the record's time-step frequency.

Parameters:

Name Type Description Default
dt float

Time step size.

 required
acc 1D ArrayLike

Acceleration time-history.

 required
ftype (str, optional, {Butterworth, Chebyshev, Bessel})

The type of IIR filter to design, by default "Butterworth"

 'Butterworth'
btype (str, optional, {lowpass, highpass, bandpass, bandstop})

The type of filter. Default is 'bandpass'.

 'bandpass'
order int, optional, recommended range [1, 8]

The order of the filter, by default 4

 4
freq1 float

Cut-off frequency (Hz) for lowpass and highpass filtering.

  • lowpass filtering suppresses frequencies that are higher than freq1.
  • highpass filtering allows frequencies that are higher than freq1 to pass through.
 = 0.1
freq2 float

Cut-off frequency (Hz) required for bandpass and bandstop filtering.

  • bandpass filtering allows signals within a given frequency range (freq1 to freq2) bandwidth to pass through.
  • bandstop filtering suppresses signals within the given frequency range (freq1 to freq2)
 = 24.99
rp float

Required when btype= 'Chebyshev', the maximum ripple allowed below unity gain in the passband. Specified in decibels (db), as a positive number.

 3
plot bool

If True, plot time histories.

 False

Returns:

Name Type Description
acc_filt 1D ArrayLike

Filtered acceleration time-history.

gmspy.lida 

lida(dt: float, acc: list, omega: float, damp_ratio: float = 0.05, method: str = 'nigam_jennings', plot: bool = False)

Linear Dynamic Time-History Analysis of Single Degree of Freedom (SDOF) System.

Parameters:

Name Type Description Default
dt float

Time step.

 required
acc 1D ArrayLike

Acceleration time series.

 required
omega float

Natural circular frequency of an SDOF system.

 required
damp_ratio float

Damping ratio, by default 0.05

 0.05
plot bool

If True, plot time histories.

 False
method str

Linear Dynamic Time-History Analysis method, optional, one of ("FFT", "Nigam_Jennings", "Newmark0", "Newmark1"):

  • "FFT"---Fast Fourier Transform;
  • "Nigam_Jennings"---exact solution by interpolating the excitation over each time interval;
  • "Newmark0"---const acceleration Newmark-beta method, gamma=0.5, beta=0.25;
  • "Newmark1"---linear acceleration Newmark-beta method, gamma=0.5, beta=1/6.

.. note:: It is recommended to use the “Nigam_Jennings” method as this is exact for linear systems and will be accelerated using numba.jit <https://numba.readthedocs.io/en/stable/user/jit.html>_ so speed of computation should not be an issue.

 'nigam_jennings'

Returns:

Type Description
3-element tuple (u: 1D ArrayLike, v: 1D ArrayLike, a: 1D ArrayLike)

Displacement, Velocity, Acceleration Time History.

gmspy.elas_resp_spec 

elas_resp_spec(dt: float, acc: Union[list, tuple, ndarray], Ts: Union[list, tuple, ndarray], damp_ratio: float = 0.05, method: str = 'nigam_jennings', n_jobs: int = 0) -> np.ndarray

Computing the Elastic Response Spectrum.

Parameters:

Name Type Description Default
dt float

Time step.

 required
acc 1D ArrayLike

Acceleration time series.

 required
Ts ArrayLike

Eigenperiods for which the response spectra are requested.

 required
damp_ratio float

Damping ratio, by default 0.05.

 0.05
method str

Linear Dynamic Time-History Analysis method, optional, one of ("FFT", "Nigam_Jennings", "Newmark0", "Newmark1"):

  • "FFT"---Fast Fourier Transform;
  • "Nigam_Jennings"---exact solution by interpolating the excitation over each time interval;
  • "Newmark0"---const acceleration Newmark-beta method, gamma=0.5, beta=0.25;
  • "Newmark1"---linear acceleration Newmark-beta method, gamma=0.5, beta=1/6.

.. note:: It is recommended to use the “Nigam_Jennings” method as this is exact for linear systems and will be accelerated using numba.jit <https://numba.readthedocs.io/en/stable/user/jit.html>_ so speed of computation should not be an issue.

 'nigam_jennings'
n_jobs int, optional, by default 0
  • If 0, do not use parallelism.
  • If an integer greater than 0, call joblib for parallel computing,
  • and the number of cpu cores used is n_jobs.
  • If -1, use all cpu cores.
 0

Returns:

Name Type Description
output (len(Ts), 5) ArrayLike.

Each column is the pseudo-acceleration spectrum, pseudo-velocity spectrum, acceleration spectrum, velocity spectrum and displacement spectrum in turn.

gmspy.const_duct_spec 

const_duct_spec(dt: float, acc: Union[list, tuple, ndarray], Ts: Union[list, tuple, ndarray], harden_ratio: float = 0.02, damp_ratio: float = 0.05, analy_dt: float = None, mu: float = 5, niter: int = 100, tol: float = 0.01, n_jobs: int = 0)

Constant-ductility inelastic spectra. See

  • section 7.5 in Anil K. Chopra (DYNAMICS OF STRUCTURES, Fifth Edition, 2020) and
  • the notes "Inelastic Response Spectra" (CEE 541. Structural Dynamics) by Henri P. Gavin.
  • Papazafeiropoulos, George, and Vagelis Plevris. "OpenSeismoMatlab: A new open-source software for strong ground motion data processing." Heliyon 4.9 (2018): e00784.

Parameters:

Name Type Description Default
dt float

Time step.

 required
acc 1D ArrayLike

Acceleration time series.

 required
Ts ArrayLike

Eigen-periods for which the response spectra are requested.

 required
harden_ratio float

Stiffness-hardening ratio, by default 0.02

 0.02
damp_ratio float

Damping ratio, by default 0.05.

 0.05
analy_dt float

Time step for bilinear SDOF response analysis, if None, default=dt.

 = None
mu float

Target ductility ratio, by default 5

 5
niter int

Maximum number of iterations, by default 100

 100
tol float

Controls the tolerance of ductility ratio convergence, by default 0.01

 0.01
n_jobs int, optional, by default 0

If 0, do not use parallelism. If an integer greater than 0, call joblib for parallel computing, and the number of cpu cores used is n_jobs. If -1, use all cpu cores.

 0

Returns:

Type Description
Size (len(Ts), 6) numpy array

Each column corresponds to acceleration Sa, velocity Sv, displacement Sd spectra, yield displacement Dy, strength reduction factor Ry, and yield strength factor Cy (1/Ry).

gmspy.fou_pow_spec 

fou_pow_spec(ts: Union[list, tuple, ndarray], acc: Union[list, tuple, ndarray], plot: bool = False)

The Fourier Amplitude Spectrum and the Power Spectrum (or Power Spectral Density Function) are computed by means of Fast Fourier Transformation (FFT) of the input time-history.

  • Fourier Amplitude is computed as the square root of the sum of the squares of the real and imaginary parts of the Fourier transform: SQRT (Re^2+Im^2);
  • Fourier Phase is computed as the angle given by the real and imaginary parts of the Fourier transform: ATAN (Re/Im);
  • Power Spectral Amplitude is computed as FourierAmpl^2/(PidurationRmsAcc^2), where duration is the time length of the record, RmsAcc is the acceleration RMS and Pi is 3.14159.

Parameters:

Name Type Description Default
ts 1D ArrayLike

Time.

 required
acc 1D ArrayLike

Acceleration time series.

 required
plot bool

If True, plot time histories.

 False

Returns:

Name Type Description
freq 1D ArrayLike

Frequency.
amp 1D ArrayLike

Fourier Amplitude.
phase 1D ArrayLike

Fourier Phase.
pow_amp 1D ArrayLike

Power Spectral Amplitude.