sdynpy.doc.RandomVibTest

• Defined as: sdynpy.doc.sdynpy_vibration_test.RandomVibTest

• Module: sdynpy.doc.sdynpy_vibration_test

• Source: GitHub

Signature¶

class sdynpy.doc.RandomVibTest(source_data: sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeRandomEnvironmentData = None, geometry: str | sdynpy.core.sdynpy_geometry.Geometry = None, coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, control_coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, response_coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, excitation_coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, time_data: list[sdynpy.core.sdynpy_data.TimeHistoryArray] = None, cpsd: list[sdynpy.core.sdynpy_data.PowerSpectralDensityArray] = None, specification_cpsd: sdynpy.core.sdynpy_data.PowerSpectralDensityArray = None, specification_warning_psd: sdynpy.core.sdynpy_data.PowerSpectralDensityArray = None, specification_abort_psd: sdynpy.core.sdynpy_data.PowerSpectralDensityArray = None, averages: int = None, overlap: float = None, fft_lines: int = None, window: str = None, samples_per_frame: int = None, start_time: float = None, units: numpy.ndarray = None, frf: list[sdynpy.core.sdynpy_data.TransferFunctionArray] = None, oct_order: int = None)

Container for a random vibration test data set with automated plotting.

Holds time history data, cross-power spectral densities, specifications, and data for a random vibration test environment. Provides methods to compute CPSDs/FRFs and produce a standard suite of diagnostic plots.

Parameters¶

• source_data : RattlesnakeRandomEnvironmentData, optional Parsed Rattlesnake environment data for the test environment.

• geometry : str or Geometry, optional Path to a geometry file or a Geometry object for 3-D visualization.

• coordinate : CoordinateArray, optional Full channel coordinate array (all channels).

• control_coordinate : CoordinateArray, optional Subset of coordinates for control/reference channels.

• response_coordinate : CoordinateArray, optional Subset of coordinates for response channels.

• excitation_coordinate : CoordinateArray, optional Subset of coordinates for excitation (drive) channels.

• time_data : list of TimeHistoryArray, optional List of time history arrays, one per data set.

• cpsd : list of PowerSpectralDensityArray or None, optional Pre-computed cross-power spectral densities. Pass None (default) to have them computed on demand.

• specification_cpsd : PowerSpectralDensityArray, optional Target PSD specification.

• specification_warning_psd : PowerSpectralDensityArray, optional Warning-level tolerance bands around the specification.

• specification_abort_psd : PowerSpectralDensityArray, optional Abort-level tolerance bands around the specification.

• averages : int, optional Number of spectral averages used when computing CPSDs.

• overlap : float, optional Fractional overlap between frames (0 to 1).

• fft_lines : int, optional Number of FFT lines.

• window : str, optional Name of the windowing function (e.g. 'hann').

• samples_per_frame : int, optional Number of samples per FFT frame.

• start_time : float or None, optional Start time (seconds) for the analysis window within each data set. None triggers automatic selection via optimal_subset.

• units : np.ndarray, optional String array of engineering-unit labels, one per channel.

• frf : list of TransferFunctionArray or None, optional Pre-computed frequency response functions.

• oct_order : int, optional Octave band order for octave-averaged results.

Attributes¶

geometry¶

Geometry object for 3-D visualisation.

Returns¶

• Geometry or None

• The loaded geometry object, or None if none has been set.

start_time¶

List of analysis-window start times in seconds, one per data set.

A value of None for any element triggers automatic selection via :func:optimal_subset when the truncated data is first requested.

Returns¶

• list of float or None

time_data¶

List of full-length TimeHistoryArray objects, one per data set.

Returns¶

• list of TimeHistoryArray or None

time_data_truncated¶

Time data windowed to the analysis subset used for CPSD computation.

Lazily computed on first access and cached. Each element is extracted from the corresponding full TimeHistoryArray beginning at start_time and covering exactly samples_per_frame * averages - overlap_samples * (averages - 1) samples. When start_time is None for a data set, the optimal start index is found via :func:optimal_subset and the corresponding start_time entry is updated in-place.

Returns¶

• list of TimeHistoryArray

• One truncated TimeHistoryArray per data set.

Methods¶

__init__¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.__init__(self, source_data: sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeRandomEnvironmentData = None, geometry: str | sdynpy.core.sdynpy_geometry.Geometry = None, coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, control_coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, response_coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, excitation_coordinate: sdynpy.core.sdynpy_coordinate.CoordinateArray = None, time_data: list[sdynpy.core.sdynpy_data.TimeHistoryArray] = None, cpsd: list[sdynpy.core.sdynpy_data.PowerSpectralDensityArray] = None, specification_cpsd: sdynpy.core.sdynpy_data.PowerSpectralDensityArray = None, specification_warning_psd: sdynpy.core.sdynpy_data.PowerSpectralDensityArray = None, specification_abort_psd: sdynpy.core.sdynpy_data.PowerSpectralDensityArray = None, averages: int = None, overlap: float = None, fft_lines: int = None, window: str = None, samples_per_frame: int = None, start_time: float = None, units: numpy.ndarray = None, frf: list[sdynpy.core.sdynpy_data.TransferFunctionArray] = None, oct_order: int = None)

Store all test data attributes.

Every named parameter is assigned directly to self. See the class docstring for parameter descriptions. cpsd and frf default to empty lists when None is passed, and the specification CPSD is sanitised so that zero values are replaced with NaN.

compute_cpsd¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.compute_cpsd(self)

Compute cross-power spectral densities for each time data set.

Computes ASDs for each truncated time data segment and appends them to self.cpsd. Already-computed entries (PowerSpectralDensityArray instances) are left unchanged; only None or non-array entries are recomputed.

compute_frf¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.compute_frf(self)

Compute FRFs for each time data set and append them to self.frf.

For each truncated time data segment, computes H1 frequency response functions between the excitation (reference) channels and all response channels using the same windowing parameters as CPSD computation. Each resulting TransferFunctionArray is appended to self.frf.

Excitation channels are identified by a non-empty feedback_channel entry in the source channel table, matching the logic used in RattlesnakeData.excitation_coordinate.

convert_to_octave¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.convert_to_octave(self, oct_order=6)

Convert all stored PSDs to octave-band averages.

Restricts the analysis to the specification bandwidth, computes nominal octave-band centres for the given oct_order, then replaces the stored CPSDs, specification CPSD, warning PSD, and abort PSD with their octave-band equivalents using bandwidth_average. Sets self.oct_order so that subsequent RMS computations use octave integration.

Parameters¶

• oct_order : int, optional Octave-band order (e.g. 3 for third-octave, 6 for sixth-octave). Default is 6.

create_all_plots¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.create_all_plots(self, figure_root_path='Figures')

Generate and save all standard diagnostic plots to disk.

Computes CPSDs if they have not already been computed, saves a time- subset plot, then iterates over all standard plot methods, saving each figure to a labelled subdirectory under figure_root_path. All matplotlib figures are closed after each method to free memory.

The plot methods called (and their subfolder names) are:

• plot_control_vs_spec -> Control vs Specification PSD Plot

• plot_response -> Response PSD Plot

• plot_percent_lines_out -> Percent Lines Out Plot

• plot_rms_level -> RMS Plot

• plot_rms_error -> RMS Error Plot

• plot_kurtosis -> Kurtosis Plot

• plot_time_histories -> Time Histories Plot

• plot_multiple_coherence -> Multiple Coherence Plot

• plot_signal_to_noise -> Signal to Noise Plot

Parameters¶

• figure_root_path : str, optional Root directory under which all figure subdirectories are created. Default is 'Figures'.

load_rattlesnake_streaming_data¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.load_rattlesnake_streaming_data(cls, file: os.PathLike | sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData, environment_name: str = None, geometry: os.PathLike | sdynpy.core.sdynpy_geometry.Geometry = None)

Construct a RandomVibTest from a Rattlesnake streaming nc4 file.

Reads (or reuses) a RattlesnakeData object, selects the requested environment, and populates a new RandomVibTest with all time data, coordinate arrays, specification PSDs, and spectral processing parameters drawn from the file.

Parameters¶

• file : os.PathLike or RattlesnakeData Path to a Rattlesnake nc4 file, or an already-parsed RattlesnakeData object.

• environment_name : str, optional Name of the environment group to load. When None (default) the first environment in the file is used. A warning is emitted when the file contains more than one environment and none is specified.

• geometry : os.PathLike or Geometry, optional Path to a geometry file or a Geometry object for 3-D visualisation. Default is None.

Returns¶

• RandomVibTest

• Fully initialised RandomVibTest instance ready for CPSD

• computation and plotting.

Warns¶

• UserWarning

• If the file contains multiple environments and environment_name

• is not specified.

plot_control_vs_spec¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_control_vs_spec(self, save_path: None | str = None)

Plot measured control PSD against the specification for each control channel.

For each data set, creates a grid of subplots — one per control channel — showing the abort-limit band (filled grey), warning-limit band (light grey), specification (dashed black), and measured response (blue). Out-of-limit regions are shaded and a percentage-out-of-limit annotation is added to each subplot. The in-band RMS level is shown as a text annotation.

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The figure index and (when multiple data sets exist) data set index are appended to the stem. Default is None (figures are not saved).

Returns¶

• figures : list of list of matplotlib.figure.Figure figures[i] is the list of figures for data set i.

• axes : list of list of list of matplotlib.axes.Axes axes[i] is the list of per-figure axes groups for data set i. axes[i][j] is the list of Axes objects on figure j.

plot_cpsd_time_subset¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_cpsd_time_subset(self, save_path=None)

Plot the selected time subset used for CPSD computation.

Parameters¶

• save_path : str or None, optional If provided, the figure is saved to this path. If there are multiple time data sets the data set number is appended to the filename stem. Default is None (figure is not saved).

plot_kurtosis¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_kurtosis(self, save_path: None | str = None)

Plot the kurtosis of each response channel time history.

Kurtosis is computed on the truncated (analysis-window) portion of each data set using Fisher’s definition disabled (Pearson kurtosis, where Gaussian has kurtosis = 3). Bars that fall outside the range [3 - 1, 3 + 1] are coloured red.

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The data set index is appended to the stem when multiple data sets exist. Default is None (figures are not saved).

Returns¶

• figures : list of matplotlib.figure.Figure One figure per data set.

• axes : list of list of matplotlib.axes.Axes One list of axes per data set.

plot_multiple_coherence¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_multiple_coherence(self, save_path: None | str = None)

Plot multiple coherence for each response channel within the analysis bandwidth.

For each data set, computes the multiple coherence between every response channel and all excitation channels (using the same windowing parameters as CPSD computation), truncates to the specification bandwidth, then produces a grid of subplots with one panel per response channel. The y-axis is fixed to [0, 1].

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The figure index and (when multiple data sets exist) data set index are appended to the stem. Default is None (figures are not saved).

Returns¶

• figures : list of list of matplotlib.figure.Figure figures[i] is the list of figures for data set i.

• axes : list of list of list of matplotlib.axes.Axes axes[i] is the nested list of axis groups for data set i.

plot_percent_lines_out¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_percent_lines_out(self, save_path: None | str = None)

Plot the percentage of spectral lines out of tolerance for each control channel.

For each data set, computes the fraction of frequency lines within the analysis bandwidth where the measured response falls outside the abort tolerance limits, then displays the result as a horizontal bar chart. Bars exceeding a 10 % threshold are coloured red. The fraction of channels that exceed the threshold is shown in the figure title.

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The data set index is appended to the stem when multiple data sets exist. Default is None (figures are not saved).

Returns¶

• figures : list of matplotlib.figure.Figure One figure per data set.

• axes : list of list of matplotlib.axes.Axes One list of axes per data set.

plot_response¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_response(self, save_path: None | str = None, one_figure=False)

Plot the measured response PSD for each response channel.

For each data set, creates a grid of subplots — one per response channel — showing the measured ASD (blue) on a log scale. The in-band RMS level is annotated on each subplot.

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The figure index and (when multiple data sets exist) data set index are appended to the stem. Default is None (figures are not saved).

• one_figure : bool, optional Whether successive datasets should be overlayed on the same grid of figures, or new grids should be made for each dataset Default is False

Returns¶

• figures : list of list of matplotlib.figure.Figure figures[i] is the list of figures for data set i.

• axes : list of list of list of matplotlib.axes.Axes axes[i] is the nested list of axis groups for data set i.

plot_rms_error¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_rms_error(self, save_path: None | str = None)

Plot the broadband RMS error between response and specification for each control channel.

The RMS error is computed as the difference between the measured RMS level and the specification RMS level, both restricted to the analysis bandwidth. Results are displayed as a horizontal bar chart.

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The data set index is appended to the stem when multiple data sets exist. Default is None (figures are not saved).

Returns¶

• figures : list of matplotlib.figure.Figure One figure per data set.

• axes : list of list of matplotlib.axes.Axes One list of axes per data set.

plot_rms_level¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_rms_level(self, save_path: None | str = None)

Plot the broadband RMS level for each response channel.

RMS values are computed from the CPSD restricted to the analysis bandwidth defined by the specification, warning, and abort PSDs. Results are displayed as a horizontal bar chart.

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The data set index is appended to the stem when multiple data sets exist. Default is None (figures are not saved).

Returns¶

• figures : list of matplotlib.figure.Figure One figure per data set.

• axes : list of list of matplotlib.axes.Axes One list of axes per data set.

plot_signal_to_noise¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_signal_to_noise(self, save_path: None | str = None)

Plot the signal-to-noise ratio for a two-dataset (noise + signal) test.

Requires exactly two data sets: the first is treated as the noise measurement and the second as the signal measurement. SNR is computed as 10 * log10(signal_power / noise_power) where power is the integral of the ASD over the full frequency range. Bars with SNR below 10 dB are coloured red.

Parameters¶

• save_path : str or None, optional File path for saving the figure. Default is None (figure is not saved).

Returns¶

• fig : matplotlib.figure.Figure or None The figure, or None if time_data does not contain exactly two data sets.

• axis : list of matplotlib.axes.Axes or None The axes list, or None as above.

plot_time_histories¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.plot_time_histories(self, save_path: None | str = None)

Plot the truncated time history for each channel.

For each data set, creates a grid of subplots — one per channel in the truncated TimeHistoryArray — showing the time-domain signal. Path simplification is enabled for performance on large records.

Parameters¶

• save_path : str or None, optional Base file path for saving figures. The figure index and (when multiple data sets exist) data set index are appended to the stem. Default is None (figures are not saved).

Returns¶

• figures : list of list of matplotlib.figure.Figure figures[i] is the list of figures for data set i.

• axes : list of list of list of matplotlib.axes.Axes axes[i] is the nested list of axis groups for data set i.

set_tolerance_limit_psd¶

• Source: GitHub

def sdynpy.doc.RandomVibTest.set_tolerance_limit_psd(self, dB=6)

Set the abort-tolerance PSD from the specification using a dB tolerance.

Computes lower and upper bounds as specification_asd / 10^(dB/10) and specification_asd * 10^(dB/10) respectively, then stores them as self.specification_abort_psd. Only the abort band is updated; specification_warning_psd is not modified.

Parameters¶

• dB : float, optional Tolerance in decibels above and below the specification. Default is 6 dB.

Raises¶

• TypeError

• If specification_cpsd is not a PowerSpectralDensityArray.