The ssi module

This module provides a collection of utility functions to support the implementation of Stochastic Subspace Identification (SSI) algorithms [BPDG99], [MiDo11], [DOME13]. It includes functions for building Hankel matrices with various methods, converting state-space representations to modal parameters,performing system identification using SSI, and extracting modal parameters from identified systems.

Functions:

  • build_hank(): Constructs a Hankel matrix from time series data.

  • SSI(): Performs system identification using the SSI method.

  • SSI_fast(): Efficient implementation of the SSI system identification.

  • SSI_poles(): Computes modal parameters from identified state-space models.

  • SSI_multi_setup(): SSI for multiple setup measurements.

  • SSI_mpe(): Extracts modal parameters for selected frequencies.

  • synt_spctr(): Computes synthetic output power spectral density using a state-space model.

Stochastic Subspace Identification (SSI) Utility Functions module. Part of the pyOMA2 package. Authors: Dag Pasca Angelo Aloisio

pyoma2.functions.ssi.SSI(H: ndarray, br: int, ordmax: int, step: int = 1) → Tuple[ndarray, List[ndarray], List[ndarray]][source]

Perform System Identification using the Stochastic Subspace Identification (SSI) method.

The SSI algorithm estimates system matrices and output influence matrices for increasing model orders, based on a provided Hankel matrix.

Parameters:

  • H (np.ndarray) – The Hankel matrix of the system.

  • br (int) – Number of block rows in the Hankel matrix.

  • ordmax (int) – Maximum system order to consider for identification.

  • step (int, optional) – Step size for increasing system order. Default is 1.

Returns:

  • Obs (np.ndarray) – The observability matrix for the system.

  • A (list of np.ndarray) – Estimated system matrices for various system orders.

  • C (list of np.ndarray) – Estimated output influence matrices for various system orders.

Notes

This is a classical implementation of SSI using the shift structure of the observability matrix. For faster implementations, consider using SSI_fast.

pyoma2.functions.ssi.SSI_fast(H: ndarray, br: int, ordmax: int, step: int = 1) → Tuple[List[ndarray], List[ndarray], List[ndarray], List[ndarray]][source]

Perform a fast implementation of Stochastic Subspace Identification (SSI).

This optimized SSI method uses QR decomposition to accelerate the extraction of system and output matrices for varying model orders.

Parameters:

  • H (np.ndarray) – The Hankel matrix.

  • br (int) – Number of block rows in the Hankel matrix.

  • ordmax (int) – Maximum system order for identification.

  • step (int, optional) – Step size for increasing system order. Default is 1.

Returns:

  • Obs (np.ndarray) – The global observability matrix of the system.

  • A (list of np.ndarray) – List of estimated system matrices for each model order.

  • C (list of np.ndarray) – List of estimated output influence matrices for each model order.

  • G (list of np.ndarray) – List of estimated next state-output covariance matrices

Notes

This method is computationally more efficient than the classical SSI approach, leveraging QR decomposition for rapid estimation, see [DOME13].

pyoma2.functions.ssi.SSI_mpe(freq_ref: list, Fn_pol: ndarray, Xi_pol: ndarray, Phi_pol: ndarray, order: int | list | str, step: int, Lab: ndarray | None = None, rtol: float = 0.05, Fn_std: ndarray = None, Xi_std: ndarray = None, Phi_std: ndarray = None) → Tuple[ndarray, ndarray, ndarray, ndarray | int, ndarray | None, ndarray | None, ndarray | None][source]

Extract modal parameters using the Stochastic Subspace Identification (SSI) method for selected frequencies.

Parameters:

  • freq_ref (list) – List of selected frequencies for modal parameter extraction.

  • Fn_pol (numpy.ndarray) – Array of natural frequencies obtained from SSI for each model order.

  • Xi_pol (numpy.ndarray) – Array of damping ratios obtained from SSI for each model order.

  • Phi_pol (numpy.ndarray) – 3D array of mode shapes obtained from SSI for each model order.

  • order (int, list of int, or str) – Specifies the model order(s) for which the modal parameters are to be extracted. If ‘find_min’, the function attempts to find the minimum model order that provides stable poles for each mode of interest.

  • Lab (numpy.ndarray, optional) – Array of labels identifying stable poles. Required if order is ‘find_min’.

  • rtol (float, optional) – Relative tolerance for comparing frequencies, by default 5e-2.

  • Fn_std (numpy.ndarray, optional) – Covariance array of natural frequencies, by default None.

  • Xi_std (numpy.ndarray, optional) – Covariance array of damping ratios, by default None.

  • Phi_std (numpy.ndarray, optional) – Covariance array of mode shapes, by default None.

Returns:

A tuple containing: - Fn (numpy.ndarray): Extracted natural frequencies. - Xi (numpy.ndarray): Extracted damping ratios. - Phi (numpy.ndarray): Extracted mode shapes. - order_out (numpy.ndarray or int): Output model order used for extraction for each frequency. - Fn_std (numpy.ndarray, optional): Covariance of extracted natural frequencies. - Xi_std (numpy.ndarray, optional): Covariance of extracted damping ratios. - Phi_std (numpy.ndarray, optional): Covariance of extracted mode shapes.

Return type:

tuple

Raises:

AttributeError – If ‘order’ is not an int, list of int, or ‘find_min’, or if ‘order’ is ‘find_min’ but ‘Lab’ is not provided.

pyoma2.functions.ssi.SSI_multi_setup(Y: list, fs: float, br: int, ordmax: int, method_hank: str, step: int = 1) → Tuple[ndarray, List[ndarray], List[ndarray]][source]

Perform Subspace System Identification SSI for multiple setup measurements.

Parameters:

  • Y (list of dictionaries) – List of dictionaries, each representing data from a different setup. Each dictionary must have keys ‘ref’ (reference sensor data) and ‘mov’ (moving sensor data), with corresponding numpy arrays.

  • fs (float) – Sampling frequency of the data.

  • br (int) – Number of block rows in the Hankel matrix.

  • ordmax (int) – Maximum order for the system identification process.

  • methodHank (str) – Method for Hankel matrix construction. Can be ‘cov’, ‘cov_R’, ‘dat’.

  • step (int, optional) – Step size for increasing the order in the identification process. Default is 1.

Returns:

Obs_all : numpy array of the global observability matrix. A : list of numpy arrays

System matrices for each model order.

Clist of numpy arrays

Output influence matrices for each model order.

Return type:

tuple

pyoma2.functions.ssi.SSI_poles(Obs: ndarray, AA: List[ndarray], CC: List[ndarray], ordmax: int, dt: float, step: int = 1, HC: bool = True, xi_max: float = 0.1, calc_unc: bool = False, H: ndarray = None, T: ndarray = None) → Tuple[ndarray, ndarray, ndarray, ndarray, ndarray | None, ndarray | None, ndarray | None, ndarray | None][source]

Calculate modal parameters using the Stochastic Subspace Identification (SSI) method.

The function computes natural frequencies, damping ratios, and mode shapes for a range of system orders. Optional uncertainty propagation can be performed.

Parameters:

  • Obs (np.ndarray) – The global observability matrix.

  • AA (list of np.ndarray) – List of estimated system matrices for each model order.

  • CC (list of np.ndarray) – List of output matrices for each model order.

  • ordmax (int) – The maximum model order.

  • dt (float) – Sampling time step.

  • step (int, optional) – Step size for increasing model order. Default is 1.

  • HC (bool, optional) – Whether to apply Hard Criteria to remove unstable poles. Default is True.

  • xi_max (float, optional) – Maximum allowed damping ratio. Default is 0.1.

  • calc_unc (bool, optional) – Whether to calculate uncertainties for modal parameters. Default is False.

  • H (np.ndarray, optional) – The Hankel matrix, required for uncertainty propagation. Default is None.

  • T (np.ndarray, optional) – Auxiliary uncertainty matrix cov(H) used in uncertainty propagation.

Returns:

  • Fn (np.ndarray) – Array of natural frequencies for each system order.

  • Xi (np.ndarray) – Array of damping ratios for each system order.

  • Phi (np.ndarray) – Normalised (to unity) mode shapes for each system order.

  • Lambdas (np.ndarray) – Continuous-time eigenvalues for each system order.

  • Fn_std (np.ndarray, optional) – Standard deviations of natural frequencies, returned if calc_unc is True.

  • Xi_std (np.ndarray, optional) – Standard deviations of damping ratios, returned if calc_unc is True.

  • Phi_std (np.ndarray, optional) – Standard deviations of mode shapes, returned if calc_unc is True.

pyoma2.functions.ssi.build_hank(Y: ndarray, Yref: ndarray, br: int, method: Literal['cov', 'cov_R', 'dat', 'IOcov'], calc_unc: bool = False, nb: int = 50, U: ndarray = None) → Tuple[ndarray, ndarray | None][source]

Construct a Hankel matrix using specified method with optional uncertainty estimation.

Depending on the selected method, this function assembles a Hankel matrix using covariance-based, data-driven, or input-output approaches, with an option to estimate uncertainty.

Parameters:

  • Y (np.ndarray) – Output data matrix with shape (number of output channels, number of data points).

  • Yref (np.ndarray) – Reference output data matrix with shape (number of reference channels, number of data points).

  • br (int) – Number of block rows in the Hankel matrix.

  • method ({'cov', 'cov_R', 'dat', 'IOcov'}) – Method used for Hankel matrix construction: - ‘cov’: Covariance-based using future and past output data. - ‘cov_R’: Covariance-based using correlation matrices. - ‘dat’: Data-driven using QR decomposition. - ‘IOcov’: Input-output covariance-based method (requires U).

  • calc_unc (bool, optional) – If True, compute an uncertainty matrix using data segmentation. Default is False.

  • nb (int, optional) – Number of segments for uncertainty estimation. Default is 50.

  • U (np.ndarray, optional) – Input data matrix with shape (number of input channels, number of data points). Required if method is ‘IOcov’.

Returns:

  • Hank (np.ndarray) – Assembled Hankel matrix according to the selected method.

  • T (np.ndarray or None) – Matrix containing uncertainty estimates, returned only if calc_unc is True; otherwise, None.

Raises:

  • AttributeError – If an unsupported method is specified or if input requirements are not met (e.g., U is not provided for ‘IOcov’).

  • AttributeError – If the number of data points per block is insufficient for uncertainty estimation.

Notes

Uncertainty calculations follow the approach detailed in [DOME13].

pyoma2.functions.ssi.synt_spctr(A: ndarray, C: ndarray, G: ndarray, R0: ndarray, omega: ndarray, dt: float) → ndarray[source]

Compute the synthetic output power spectral density matrix.

This function evaluates the power spectral density (PSD) of system outputs using a state-space model over a range of angular frequencies.

Parameters:

  • A (np.ndarray) – State matrix of shape (n, n).

  • C (np.ndarray) – Output matrix of shape (p, n).

  • G (np.ndarray) – Input influence matrix of shape (n, p).

  • R0 (np.ndarray) – Output noise covariance matrix of shape (p, p).

  • omega (np.ndarray) – Array of angular frequencies at which the PSD is computed.

  • dt (float) – Sampling time interval.

Returns:

S_YY – Power spectral density matrix of shape (p, p, N), where N is the number of frequency points.

Return type:

np.ndarray