API Documentation

pyomac Module

fdd

pyomac.fdd(data, fs: float, method: str = 'welch', nperseg: int = 4096, fmax: int = 20)

ssi_cov

pyomac.ssi_cov(data: numpy.ndarray, fs: float, ts: float = 5.0, eps_fn: float = 0.02, eps_zeta: float = 0.05, eps_mac: float = 0.01, f_min: float = 0.5, f_max: float = 20.0, n_order: int = 100, t: float = 0.025, min_count: int = 15, return_poles: bool = False)

ssi-cov algorithm according to E. Cheynet, 2018

see: https://de.mathworks.com/matlabcentral/fileexchange/69030-operational-modal-analysis-with-automated-ssi-cov-algorithm

Parameters

  • data (array_like) – Time series of measurement values

  • fs (float) – Sampling frequency [Hz] of the data time series

  • ts (float, optional) – time lag [s] for covariance calculation. Defaults to 5. s

  • eps_fn (float, optional) – Threshold [%] for frequency stability calculations. Defaults to 0.02

  • eps_zeta (float, optional) – Threshold [%] for damping stability calculations. Defaults to 0.05

  • eps_mac (float, optional) – Threshold [-] for mode shape stability calculations. Defaults to 0.01

  • f_min (float, optional) – Lowest considered frequency. Defaults to 0.5 Hz

  • f_max (float, optional) – Highest considered frequency. Defaults to 20. Hz

  • n_order (int, optional) – Highest considered mode order. Defaults to 100

  • t (float, optional) – Similarity threshold [%] as cut-off for hierachical clustering. Defaults to 0.025

  • min_count (int, optional) – Minimal cluster size. Defaults to 15

  • return_poles (bool, optional) – If True, ndarray containing the poles are returned, e.g. fo plotting a stability diagram. Defaults to False

Returns

  • fn (ndarray) – Identified natural frequencies [Hz]

  • zeta (ndarray) – Identified modal damping [-]

  • phi (ndarray) – Identified mode shapes [-]

  • poles_stab (ndarray, optional) – Stable poles for stability diagram

  • order_stab (ndarray, optional) – Corresponding order of stable poles for stability diagram

  • poles (ndarray, optional) – All identified poles for stability diagram

  • order (ndarray, optional) – Corresponding order of all poles for stability diagram

  • Last changed (ajansen, 2021-06-01)

ssi_cov_poles

pyomac.ssi_cov_poles(data: numpy.ndarray, fs: float, n_block_rows: int, max_model_order: int) → Tuple[List[numpy.ndarray], List[numpy.ndarray], List[numpy.ndarray]]

Calculate all poles via the SSI covariannce method up to a maximum model order.

Parameters

  • data (np.ndarray) – A numpy array of size (n_samples x n_channels)

  • fs (float) – The sampling frequency of the data.

  • n_block_rows (int) – The number of block rows for building the block Toeplitz matrix.

  • max_model_order (int) – The maximum model order as parameter for the SSI, for up to which the poles should be identified.

Returns

  • freq (List[np.ndarray]) – A list of 1-dimensional (model_order x 1) arrays containing the undamped eigenfrequencies of the identified poles.

  • xi (List[np.ndarray]) – A list of 1-dimensional (model_order x 1) arrays containing the damping ratios of the identified poles.

  • Psi (List[np.ndarray]) – A list of 2-dimensional (model_order x n_channels) arrays containing the modeshapes of the identified poles.

ssi_cov_poles_for_model_order

pyomac.ssi_cov_poles_for_model_order(data: numpy.ndarray, fs: float, n_block_rows: int, model_order: int) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Calculate all poles via the SSI covariannce method for a specified model order.

Parameters

  • data (np.ndarray) – A numpy array of size (n_samples x n_channels)

  • fs (float) – The sampling frequency of the data.

  • n_block_rows (int) – The number of block rows for building the block Toeplitz matrix.

  • model_order (int) – The model order as parameter for the SSI, for which the poles should be identified.

Returns

  • freq (np.ndarray) – An 1-dimensional (model_order x 1) array containing the undamped eigenfrequencies of the identified poles.

  • xi (np.ndarray) – An 1-dimensional (model_order x 1) array containing the damping ratios of the identified poles.

  • Psi (np.ndarray) – A 2-dimensional (model_order x n_channels) array containing the modeshapes of the identified poles.

filter_ssi_single_order

pyomac.filter_ssi_single_order(freq: numpy.ndarray, xi: numpy.ndarray, Psi: numpy.ndarray, pairwise_occurence: bool = True, positive_damping: bool = True, max_damping: float = 0.15) → numpy.ndarray

Filter a single ssi model order based on acceptrance criteria.

Parameters

  • freq (np.ndarray) – An 1-dimensional (model_order x 1) array containing the undamped eigenfrequencies of the identified poles.

  • xi (np.ndarray) – An 1-dimensional (model_order x 1) array containing the damping ratios of the identified poles.

  • Psi (np.ndarray) – A 2-dimensional (model_order x n_channels) array containing the modeshapes of the identified poles.

  • pairwise_occurence (bool, optional) – If True, only return the first pole of poles that appear pairwise, by default True

  • positive_damping (bool, optional) – If True, only return poles with positive damping, by default True

  • max_damping (float, optional) – If specified, only return poles with damping below this threshold, by default 0.15

Returns

An 1-dimensional (model_order x 1) array boolean mask with the filtered poles.

Return type

np.ndarray

pyomac.plot Module

ssi_stability_plot

pyomac.plot.ssi_stability_plot(poles: Sequence[numpy.ndarray], fmax: float = 25, model_orders: Optional[Sequence[int]] = None, fig_obj: Optional[Tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes]] = None, label: Optional[str] = None) → Tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes]

Plot the stability diagramm of poles over model order.

Parameters

  • poles (Sequence[np.ndarray]) – Sequence of arrays containing the frequencies of the identified poles.

  • fmax (float, optional) – maximum frequency to be displayed, by default 25

  • model_orders (Optional[Sequence[int]], optional) – If supplied, a Sequence of model orders corresponding to the poles

  • fig_obj (Optional[Tuple[Figure, Axes]], optional) – A tuple containing a matplotlib figure and axes to be drawn upon.

  • label (Optional[str], optional) – The label attached to the scatter path collection.

Returns

A tuple containing the matplotlib figure and axes.

Return type

Tuple[Figure, Axes]

fdd_peak_picking_plot

pyomac.plot.fdd_peak_picking_plot(f, s, fn, n_sv=1, semilogy=False)