Additional Modules

Spectral tools, Arias intensity, response spectra and small utilities used by the core pydysp.channel.Channel and pydysp.test.Test classes.

Spectral Tools

class pydysp.spectra.FourierSpectrum(f, s)[source]

Bases: object

Single-sided Fourier amplitude spectrum.

This dataclass stores the frequency axis and corresponding single-sided amplitude spectrum (magnitude of the FFT) for a real-valued time series.

Parameters:

  • f (np.ndarray) – One-dimensional array of frequencies in Hz.

  • s (np.ndarray) – One-dimensional array of amplitude values corresponding to f.

f: ndarray
s: ndarray
peak()[source]

Return the frequency and amplitude at the maximum spectral peak.

Returns:

  • f_peak (float) – Frequency at which the amplitude spectrum is maximum.

  • s_peak (float) – Maximum amplitude value.

Raises:

ValueError – If the spectrum array s is empty.

Return type:

tuple[float, float]

plot(ax=None, fmax=50.0, **plot_kwargs)[source]

Plot the Fourier amplitude spectrum.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure and axes are created.

  • fmax (float or None, optional) – Upper x-limit for the frequency axis in Hz. If None, the full frequency range is shown. Default is 50.0.

  • **plot_kwargs – Additional keyword arguments forwarded to matplotlib.axes.Axes.plot() (for example color, linewidth).

Returns:

Axes instance with the plotted spectrum.

Return type:

matplotlib.axes.Axes

class pydysp.spectra.WelchSpectrum(f, p)[source]

Bases: object

Power spectral density (PSD) result from Welch’s method.

This dataclass stores the frequency axis and corresponding power spectral density values obtained using Welch’s method.

Parameters:

  • f (np.ndarray) – One-dimensional array of frequencies in Hz.

  • p (np.ndarray) – One-dimensional array of PSD values corresponding to f.

f: ndarray
p: ndarray
peak()[source]

Return the frequency and PSD value at the maximum spectral peak.

Returns:

  • f_peak (float) – Frequency at which the PSD is maximum.

  • p_peak (float) – Maximum PSD value.

Raises:

ValueError – If the PSD array p is empty.

Return type:

tuple[float, float]

plot(ax=None, fmax=50.0, **plot_kwargs)[source]

Plot the Welch power spectral density.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure and axes are created.

  • fmax (float or None, optional) – Upper x-limit for the frequency axis in Hz. If None, the full frequency range is shown. Default is 50.0.

  • **plot_kwargs – Additional keyword arguments forwarded to matplotlib.axes.Axes.plot().

Returns:

Axes instance with the plotted PSD.

Return type:

matplotlib.axes.Axes

Arias Intensity

class pydysp.arias.AriasResult(t, Ia, t_start, t_end)[source]

Bases: object

Container for Arias intensity time history and significant-duration window.

This dataclass stores the Husid-style cumulative Arias intensity and the corresponding significant-duration window, typically defined between two Arias intensity percentiles (e.g. 5–95%).

Parameters:

  • t (np.ndarray) – One-dimensional array of time values (in seconds) corresponding to the input acceleration record.

  • Ia (np.ndarray) – One-dimensional array of cumulative Arias intensity values evaluated at times t.

  • t_start (float) – Start time of the significant-duration window (e.g. the time at which a given lower percentile of Arias intensity is reached).

  • t_end (float) – End time of the significant-duration window (e.g. the time at which a given upper percentile of Arias intensity is reached).

Notes

The AriasResult class is typically created by higher-level routines that compute Arias intensity from acceleration time series. It is mainly used to: * Visualise the cumulative Arias intensity (Husid plot). * Provide a convenient representation of the significant-duration window

for trimming and further analysis.

t: ndarray
Ia: ndarray
t_start: float
t_end: float
plot(ax=None, show_window=True, **plot_kwargs)[source]

Plot the Arias intensity time history.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axes object to plot on. If None, a new figure and axes are created with plt.subplots().

  • show_window (bool, optional) – If True, vertical dashed lines are drawn at t_start and t_end to indicate the significant-duration window. The default is True.

  • **plot_kwargs – Additional keyword arguments passed directly to ax.plot (for example color, linewidth, etc.).

Returns:

The axes instance containing the Arias intensity plot.

Return type:

matplotlib.axes.Axes

Notes

The x-axis is labelled as time in seconds, and the y-axis as Arias intensity in consistent units with the underlying acceleration record. A grid is enabled by default to facilitate reading the Husid plot.

Response Spectra

class pydysp.response.ResponseSpectrum(T, Sd, Sv, Sa, ksi)[source]

Bases: object

Elastic response spectrum for a family of SDOF oscillators.

This dataclass stores spectral displacement, velocity and acceleration for a set of single-degree-of-freedom (SDOF) oscillators with the same damping ratio, evaluated over a grid of natural periods.

Parameters:

  • T (np.ndarray) – One-dimensional array of natural periods in seconds.

  • Sd (np.ndarray) – Spectral displacement values in metres (same shape as T).

  • Sv (np.ndarray) – Spectral velocity values in metres per second (same shape as T).

  • Sa (np.ndarray) – Spectral pseudo-acceleration values in g (same shape as T).

  • ksi (float) – Damping ratio used to compute the spectrum (e.g. 0.05 for 5%).

T: ndarray
Sd: ndarray
Sv: ndarray
Sa: ndarray
ksi: float
peak()[source]

Return the dominant period and peak spectral acceleration.

Returns:

  • T_peak (float) – Period at which Sa attains its maximum value.

  • Sa_peak (float) – Maximum spectral acceleration value in g.

Raises:

ValueError – If the spectral acceleration array Sa is empty.

Return type:

tuple[float, float]

plot(ax=None, y='Sa', logx=False, logy=False, **plot_kwargs)[source]

Plot one of the response spectra (Sa, Sv or Sd).

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure and axes are created.

  • y ({"Sa", "Sv", "Sd"}, optional) – Which spectrum to plot: spectral acceleration "Sa" (default), velocity "Sv", or displacement "Sd".

  • logx (bool, optional) – If True, use a logarithmic scale on the x-axis. Default is False.

  • logy (bool, optional) – If True, use a logarithmic scale on the y-axis. Default is False.

  • **plot_kwargs – Additional keyword arguments forwarded to matplotlib.axes.Axes.plot() (for example color, linewidth, etc.).

Returns:

Axes instance containing the plotted spectrum.

Return type:

matplotlib.axes.Axes

Raises:

ValueError – If y is not one of "Sa", "Sv", or "Sd".

pydysp.response.sdof_newmark_response(acc, dt, omega, ksi)[source]

Newmark-beta (average-acceleration) SDOF response to base acceleration.

This function integrates the response of a linear single-degree-of-freedom (SDOF) oscillator subjected to ground acceleration using the Newmark-beta average-acceleration scheme, and returns peak relative displacement, relative velocity and absolute acceleration.

Parameters:

  • acc (np.ndarray) – Ground acceleration time history \(a_g(t)\) in m/s².

  • dt (float) – Time step in seconds.

  • omega (float) – Circular frequency of the oscillator in rad/s.

  • ksi (float) – Damping ratio (e.g. 0.05 for 5% damping).

Returns:

  • Sd (float) – Peak relative displacement in metres (maximum absolute value of relative displacement time history).

  • Sv (float) – Peak relative velocity in metres per second.

  • Sa (float) – Peak absolute acceleration in m/s² (sum of relative and ground acceleration).

Return type:

tuple[float, float, float]

Notes

  • A unit mass \(m = 1\) is assumed, with stiffness k = m * omega**2 and viscous damping c = 2 * ksi * omega * m.

  • If the input acceleration array is empty, all returned values are 0.0.

Utilities

pydysp.downsample.downsample(file_in, file_out, factor=20)[source]

Downsample array-like variables in a MATLAB .mat file.

This function loads a .mat file, downsamples any array-like variables (NumPy arrays, MATLAB arrays, or objects exposing a shape attribute with ndim >= 1), and writes the result to a new .mat file. Non-array containers such as Python list or tuple are left unchanged.

Parameters:

  • file_in (str) – Path to the input MATLAB .mat file.

  • file_out (str) – Path to the output MATLAB .mat file where the downsampled variables will be saved.

  • factor (int, optional) – Downsampling factor applied along the first dimension. Must be a positive integer. Default is 20.

Raises:

  • FileNotFoundError – If the input file cannot be found or opened.

  • ValueError – If factor is not a positive integer.

Return type:

None

Notes

  • Only objects exposing shape and having at least one dimension are downsampled. The operation is performed using slicing val[::factor].

  • Keys such as __header__, __version__ and __globals__ are preserved and written unchanged.

  • SciPy warnings related to MATLAB struct fields beginning with an underscore are suppressed during saving.