Engineering Parameters and Signal Response Functions¶

This module provides functions to compute classic engineering parameters from seismic records, such as Arias intensity, peak amplitude, CAV, and the response of single-degree-of-freedom (SDOF) systems. It is designed to support strong motion analysis and structural engineering tasks, operating directly on ShakeLab Record objects.

Hilbert Transform¶

Compute the complex analytic signal using the Hilbert transform.

Inputs: - record (Record): the input signal object to process : a ShakeLab Record instance

Output: - complex-valued NumPy array of same length

Usage Example:

Python

from shakelab.signals.engpar import hilbert_transform
analytic = hilbert_transform(record)

Amplitude Envelope¶

Compute the amplitude envelope using the Hilbert transform or RMS.

Inputs: - record (Record): the input signal object to process : a Record object - method (str): computation mode, e.g. ‘hilbert’ or ‘rms’ : ‘hilbert’ or ‘rms’ - window (float): duration in seconds for RMS averaging : RMS window in seconds (used if method=’rms’)

Output: - real-valued NumPy array of same length

Usage Example:

Python

env = amplitude_envelope(record, method='rms', window=0.5)

Instantaneous Phase¶

Compute the unwrapped phase from the analytic signal.

Output: - array of phase values in radians

Usage Example:

Python

phi = instantaneous_phase(record)

Instantaneous Frequency¶

Compute the instantaneous frequency by differentiating the phase.

instantaneous_frequency(record, pad=False, method='diff')

Inputs: - pad (bool): if True, extends result to match signal length : if True, pads the output to length N - method (str): computation mode, e.g. ‘hilbert’ or ‘rms’ : ‘diff’ or ‘gradient’

Output: - array of frequency in Hz

Usage Example:

Python

freq = instantaneous_frequency(record, pad=True, method='gradient')

Peak Amplitude¶

Compute the absolute peak value of the signal.

Output: - float (or tuple with time if return_time=True)

Usage Example:

Python

peak, t = peak_amplitude(record, return_time=True)

Arias Intensity¶

Compute the Arias intensity or its normalized form.

Output: - float or normalized cumulative array

Usage Example:

Python

ia = arias_intensity(record)
norm = arias_intensity(record, normalize=True)

Cumulative Absolute Velocity (CAV)¶

Compute the CAV metric or its normalized cumulative form.

cumulative_absolute_velocity(record, normalize=False)

Output: - float or normalized cumulative array

Usage Example:

Python

cav = cumulative_absolute_velocity(record)

Bracketed Duration¶

Compute time between first and last exceedance of a threshold.

``bracketed_duration(record, threshold=0.05,: relative=False, return_times=False)``

Output: - float or (duration, t0, t1)

Usage Example:

Python

dur, t0, t1 = bracketed_duration(record, relative=True,
                                 return_times=True)

Significant Duration¶

Compute duration between two normalized energy percentiles.

``significant_duration(record, threshold=(0.05, 0.95),: return_times=False)``

Output: - float or (duration, t0, t1)

Usage Example:

Python

d = significant_duration(record, return_times=True)

Root Mean Square (RMS)¶

Compute the RMS over the whole record or a sliding window.

Output: - float (if global) or ndarray (if window is set)

Usage Example:

Python

rms_series = root_mean_square(record, window=2.0)

SDOF Peak Response Spectrum¶

Compute peak response values (SA, SV, SD, PSA, PSV) over multiple periods.

sdof_peak_response_spectrum(record, periods, zeta=0.05)

Output: - dictionary of NumPy arrays

Usage Example:

Python

periods = [0.1, 0.2, 1.0]
spectrum = sdof_peak_response_spectrum(record, periods)

SDOF Time History Response¶

Compute the full time history of a linear SDOF oscillator.

sdof_time_response(record, period, zeta=0.05)

Output: - dictionary with keys ‘d’, ‘v’, ‘a’

Usage Example:

Python

response = sdof_time_response(record, period=1.0)

SDOF Interstory Drift¶

Compute the interstory drift for an equivalent 2DOF structure.

sdof_interstory_drift(record, period, zeta=0.05)

Output: - NumPy array with relative displacement time series

Usage Example:

Python

drift = sdof_interstory_drift(record, period=0.8)

1D Soil Response (Stub)¶

Placeholder for future implementation of layered soil models.

compute_soil1d_response(record, model1d, component='sh', angle=0.0)

Output: - NotImplementedError

Usage Example:

Python

compute_soil1d_response(record, model1d)