The ssi algorithm module

This module implements the Stochastic Subspace Identification (SSI) [BPDG99], [MiDo11] algorithm in various forms, tailored for both single and multiple experimental setup scenarios [MiDo11], [DOME13]. It includes classes and methods for conducting data-driven and covariance-driven SSI analyses, with optional uncertainty bounds estimation.

Classes:
SSIdat

Implements the Data-Driven SSI algorithm for single setup.

SSIcov

Implements the Covariance-Driven SSI algorithm for single setup.

SSIdat_MS

Extends SSIdat for multi-setup experiments.

SSIcov_MS

Extends SSIdat_MS for covariance-based analysis in multi-setup experiments.

Important

Each class contains methods for executing the SSI algorithm, extracting modal parameters, plotting results, and additional utilities relevant to the specific SSI approach.

Note

Users should be familiar with the concepts of modal analysis and system identification to effectively use this module.

The SSIdat class

class pyoma2.algorithms.ssi.SSIdat(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)[source]

Bases: BaseAlgorithm

Data-Driven Stochastic Subspace Identification (SSI) algorithm for single setup analysis.

This class processes measurement data from a single setup experiment to identify and extract modal parameters using the SSIdat-ref method.

RunParamCls

The class of parameters specific to this algorithm’s run.

Type:

Type[SSIRunParams]

ResultCls

The class of results produced by this algorithm.

Type:

Type[SSIResult]

method

The method used in this SSI algorithm, set to ‘dat’ by default.

Type:

str

ResultCls

alias of SSIResult

RunParamCls

alias of SSIRunParams

__init__(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)

Initialize the algorithm with optional run parameters and a name.

Parameters:

  • run_params (Optional[T_RunParams], optional) – The parameters required to run the algorithm. If not provided, can be set later.

  • name (Optional[str], optional) – The name of the algorithm. If not provided, defaults to the class name.

  • *args (tuple) – Additional positional arguments.

  • **kwargs (dict) – Additional keyword arguments used to instantiate run parameters if run_params is not provided.

mpe(sel_freq: List[float], order_in: int | str = 'find_min', rtol: float = 0.05) → Any[source]

Extracts the modal parameters at the selected frequencies.

Parameters:

  • sel_freq (list of float) – Selected frequencies for modal parameter extraction.

  • order (int or str, optional) – Model order for extraction, or ‘find_min’ to auto-determine the minimum stable order. Default is ‘find_min’.

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

Returns:

The extracted modal parameters. The format and content depend on the algorithm’s implementation.

Return type:

Any

mpe_from_plot(freqlim: tuple[float, float] | None = None, rtol: float = 0.01) → Any[source]

Interactive method for extracting modal parameters by selecting frequencies from a plot.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • rtol (float, optional) – Relative tolerance for comparing frequencies. Default is 1e-2.

Returns:

The extracted modal parameters after interactive selection. Format depends on algorithm’s implementation.

Return type:

Any

plot_freqvsdamp(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any[source]

Plot the frequency-damping cluster diagram for the identified modal parameters.

The cluster diagram visualizes the relationship between frequencies and damping ratios for the identified poles, helping to identify clusters of physical modes.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True. If True, hide individual pole markers in the scatter. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the cluster diagram plot.

Return type:

Any

plot_stab(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any[source]

Plot the Stability Diagram for the SSI algorithms.

The Stability Diagram helps visualize the stability of identified poles across different model orders, making it easier to separate physical poles from spurious ones.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the Stability Diagram plot.

Return type:

Any

plot_svalH(iter_n: int | None = None) → Any[source]

Plot the singular values of the Hankel matrix for the SSI algorithm.

This plot is useful for checking the influence of the number of block-rows, br, on the Singular Values of the Hankel matrix.

Parameters:

iter_n (int, optional) – The iteration number for which to plot the singular values. If None, the last iteration is used. Default is None.

Returns:

A tuple containing the matplotlib figure and axes of the singular value plot.

Return type:

Any

Raises:

ValueError – If the algorithm has not been run before plotting.

run() → SSIResult[source]

Executes the SSIdat algorithm and returns the results.

Processes the input data using the Data-Driven Stochastic Subspace Identification method. Computes state space matrices, modal parameters, and other relevant results.

Returns:

An object containing the computed matrices and modal parameters.

Return type:

SSIResult

set_run_params(run_params: T_RunParams) → BaseAlgorithm

Set the run parameters for the algorithm.

Parameters:

run_params (T_RunParams) – The run parameters for the algorithm.

Returns:

Returns the instance with updated run parameters.

Return type:

BaseAlgorithm

Note

This method allows dynamically setting or updating the run parameters for the algorithm after its initialization.

The SSIcov class

class pyoma2.algorithms.ssi.SSIcov(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)[source]

Bases: SSIdat

Implements the Covariance-driven Stochastic Subspace Identification (SSI) algorithm for single setup experiments.

This class is an extension of the SSIdat class, adapted for covariance-driven analysis. It processes measurement data from a single setup to identify system dynamics and extract modal parameters using the SSIcov-ref method.

Inherits all attributes and methods from SSIdat.

method

The method used in this SSI algorithm, overridden to ‘cov’ or ‘cov_R’ for covariance-based analysis.

Type:

str

Inherits all methods from SSIdat with covariance-specific implementations.
ResultCls

alias of SSIResult

RunParamCls

alias of SSIRunParams

__init__(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)

Initialize the algorithm with optional run parameters and a name.

Parameters:

  • run_params (Optional[T_RunParams], optional) – The parameters required to run the algorithm. If not provided, can be set later.

  • name (Optional[str], optional) – The name of the algorithm. If not provided, defaults to the class name.

  • *args (tuple) – Additional positional arguments.

  • **kwargs (dict) – Additional keyword arguments used to instantiate run parameters if run_params is not provided.

mpe(sel_freq: List[float], order_in: int | str = 'find_min', rtol: float = 0.05) → Any

Extracts the modal parameters at the selected frequencies.

Parameters:

  • sel_freq (list of float) – Selected frequencies for modal parameter extraction.

  • order (int or str, optional) – Model order for extraction, or ‘find_min’ to auto-determine the minimum stable order. Default is ‘find_min’.

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

Returns:

The extracted modal parameters. The format and content depend on the algorithm’s implementation.

Return type:

Any

mpe_from_plot(freqlim: tuple[float, float] | None = None, rtol: float = 0.01) → Any

Interactive method for extracting modal parameters by selecting frequencies from a plot.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • rtol (float, optional) – Relative tolerance for comparing frequencies. Default is 1e-2.

Returns:

The extracted modal parameters after interactive selection. Format depends on algorithm’s implementation.

Return type:

Any

plot_freqvsdamp(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any

Plot the frequency-damping cluster diagram for the identified modal parameters.

The cluster diagram visualizes the relationship between frequencies and damping ratios for the identified poles, helping to identify clusters of physical modes.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True. If True, hide individual pole markers in the scatter. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the cluster diagram plot.

Return type:

Any

plot_stab(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any

Plot the Stability Diagram for the SSI algorithms.

The Stability Diagram helps visualize the stability of identified poles across different model orders, making it easier to separate physical poles from spurious ones.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the Stability Diagram plot.

Return type:

Any

plot_svalH(iter_n: int | None = None) → Any

Plot the singular values of the Hankel matrix for the SSI algorithm.

This plot is useful for checking the influence of the number of block-rows, br, on the Singular Values of the Hankel matrix.

Parameters:

iter_n (int, optional) – The iteration number for which to plot the singular values. If None, the last iteration is used. Default is None.

Returns:

A tuple containing the matplotlib figure and axes of the singular value plot.

Return type:

Any

Raises:

ValueError – If the algorithm has not been run before plotting.

run() → SSIResult

Executes the SSIdat algorithm and returns the results.

Processes the input data using the Data-Driven Stochastic Subspace Identification method. Computes state space matrices, modal parameters, and other relevant results.

Returns:

An object containing the computed matrices and modal parameters.

Return type:

SSIResult

set_run_params(run_params: T_RunParams) → BaseAlgorithm

Set the run parameters for the algorithm.

Parameters:

run_params (T_RunParams) – The run parameters for the algorithm.

Returns:

Returns the instance with updated run parameters.

Return type:

BaseAlgorithm

Note

This method allows dynamically setting or updating the run parameters for the algorithm after its initialization.

The SSIdat_MS class

class pyoma2.algorithms.ssi.SSIdat_MS(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)[source]

Bases: SSIdat

Implements the Data-Driven Stochastic Subspace Identification (SSI) algorithm for multi-setup experiments.

This class extends the SSIdat class to handle data from multiple experimental setups, with moving and reference sensors.

Inherits all attributes and methods from SSIdat, with focus on multi-setup data handling.

Inherits all attributes from SSIdat.
Inherits other methods from SSIdat, applicable to multi-setup scenarios.
ResultCls

alias of SSIResult

RunParamCls

alias of SSIRunParams

__init__(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)

Initialize the algorithm with optional run parameters and a name.

Parameters:

  • run_params (Optional[T_RunParams], optional) – The parameters required to run the algorithm. If not provided, can be set later.

  • name (Optional[str], optional) – The name of the algorithm. If not provided, defaults to the class name.

  • *args (tuple) – Additional positional arguments.

  • **kwargs (dict) – Additional keyword arguments used to instantiate run parameters if run_params is not provided.

mpe(sel_freq: List[float], order_in: int | str = 'find_min', rtol: float = 0.05) → Any

Extracts the modal parameters at the selected frequencies.

Parameters:

  • sel_freq (list of float) – Selected frequencies for modal parameter extraction.

  • order (int or str, optional) – Model order for extraction, or ‘find_min’ to auto-determine the minimum stable order. Default is ‘find_min’.

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

Returns:

The extracted modal parameters. The format and content depend on the algorithm’s implementation.

Return type:

Any

mpe_from_plot(freqlim: tuple[float, float] | None = None, rtol: float = 0.01) → Any

Interactive method for extracting modal parameters by selecting frequencies from a plot.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • rtol (float, optional) – Relative tolerance for comparing frequencies. Default is 1e-2.

Returns:

The extracted modal parameters after interactive selection. Format depends on algorithm’s implementation.

Return type:

Any

plot_freqvsdamp(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any

Plot the frequency-damping cluster diagram for the identified modal parameters.

The cluster diagram visualizes the relationship between frequencies and damping ratios for the identified poles, helping to identify clusters of physical modes.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True. If True, hide individual pole markers in the scatter. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the cluster diagram plot.

Return type:

Any

plot_stab(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any

Plot the Stability Diagram for the SSI algorithms.

The Stability Diagram helps visualize the stability of identified poles across different model orders, making it easier to separate physical poles from spurious ones.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the Stability Diagram plot.

Return type:

Any

plot_svalH(iter_n: int | None = None) → Any

Plot the singular values of the Hankel matrix for the SSI algorithm.

This plot is useful for checking the influence of the number of block-rows, br, on the Singular Values of the Hankel matrix.

Parameters:

iter_n (int, optional) – The iteration number for which to plot the singular values. If None, the last iteration is used. Default is None.

Returns:

A tuple containing the matplotlib figure and axes of the singular value plot.

Return type:

Any

Raises:

ValueError – If the algorithm has not been run before plotting.

run() → SSIResult[source]

Executes the SSI algorithm for multiple setups and returns the results.

Processes the input data from multiple setups using the Data-Driven Stochastic Subspace Identification method. It builds Hankel matrices for each setup and computes the state and output matrices, along with frequency poles.

Returns:

An object containing the system matrices, poles, damping ratios, and mode shapes across multiple setups.

Return type:

SSIResult

set_run_params(run_params: T_RunParams) → BaseAlgorithm

Set the run parameters for the algorithm.

Parameters:

run_params (T_RunParams) – The run parameters for the algorithm.

Returns:

Returns the instance with updated run parameters.

Return type:

BaseAlgorithm

Note

This method allows dynamically setting or updating the run parameters for the algorithm after its initialization.

The SSIcov_MS class

class pyoma2.algorithms.ssi.SSIcov_MS(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)[source]

Bases: SSIdat_MS

Implements the Covariance-Driven Stochastic Subspace Identification (SSI) algorithm for multi-setup experiments.

This class extends SSIdat_MS, focusing on the covariance-driven approach to SSI for multiple experimental setups.

Inherits all attributes and methods from SSIdat_MS, adapted for covariance-driven analysis methods.

Inherits all attributes from SSIdat_MS.
Inherits all methods from SSIdat_MS, adapted for covariance-based analysis.
ResultCls

alias of SSIResult

RunParamCls

alias of SSIRunParams

__init__(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)

Initialize the algorithm with optional run parameters and a name.

Parameters:

  • run_params (Optional[T_RunParams], optional) – The parameters required to run the algorithm. If not provided, can be set later.

  • name (Optional[str], optional) – The name of the algorithm. If not provided, defaults to the class name.

  • *args (tuple) – Additional positional arguments.

  • **kwargs (dict) – Additional keyword arguments used to instantiate run parameters if run_params is not provided.

mpe(sel_freq: List[float], order_in: int | str = 'find_min', rtol: float = 0.05) → Any

Extracts the modal parameters at the selected frequencies.

Parameters:

  • sel_freq (list of float) – Selected frequencies for modal parameter extraction.

  • order (int or str, optional) – Model order for extraction, or ‘find_min’ to auto-determine the minimum stable order. Default is ‘find_min’.

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

Returns:

The extracted modal parameters. The format and content depend on the algorithm’s implementation.

Return type:

Any

mpe_from_plot(freqlim: tuple[float, float] | None = None, rtol: float = 0.01) → Any

Interactive method for extracting modal parameters by selecting frequencies from a plot.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • rtol (float, optional) – Relative tolerance for comparing frequencies. Default is 1e-2.

Returns:

The extracted modal parameters after interactive selection. Format depends on algorithm’s implementation.

Return type:

Any

plot_freqvsdamp(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any

Plot the frequency-damping cluster diagram for the identified modal parameters.

The cluster diagram visualizes the relationship between frequencies and damping ratios for the identified poles, helping to identify clusters of physical modes.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True. If True, hide individual pole markers in the scatter. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the cluster diagram plot.

Return type:

Any

plot_stab(freqlim: tuple[float, float] | None = None, hide_poles: bool | None = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Any

Plot the Stability Diagram for the SSI algorithms.

The Stability Diagram helps visualize the stability of identified poles across different model orders, making it easier to separate physical poles from spurious ones.

Parameters:

  • freqlim (tuple of float, optional) – Frequency limits for the plot. If None, limits are determined automatically. Default is None.

  • hide_poles (bool, optional) – Option to hide poles in the plot for clarity. Default is True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’.

Returns:

A tuple containing the matplotlib figure and axes of the Stability Diagram plot.

Return type:

Any

plot_svalH(iter_n: int | None = None) → Any

Plot the singular values of the Hankel matrix for the SSI algorithm.

This plot is useful for checking the influence of the number of block-rows, br, on the Singular Values of the Hankel matrix.

Parameters:

iter_n (int, optional) – The iteration number for which to plot the singular values. If None, the last iteration is used. Default is None.

Returns:

A tuple containing the matplotlib figure and axes of the singular value plot.

Return type:

Any

Raises:

ValueError – If the algorithm has not been run before plotting.

run() → SSIResult

Executes the SSI algorithm for multiple setups and returns the results.

Processes the input data from multiple setups using the Data-Driven Stochastic Subspace Identification method. It builds Hankel matrices for each setup and computes the state and output matrices, along with frequency poles.

Returns:

An object containing the system matrices, poles, damping ratios, and mode shapes across multiple setups.

Return type:

SSIResult

set_run_params(run_params: T_RunParams) → BaseAlgorithm

Set the run parameters for the algorithm.

Parameters:

run_params (T_RunParams) – The run parameters for the algorithm.

Returns:

Returns the instance with updated run parameters.

Return type:

BaseAlgorithm

Note

This method allows dynamically setting or updating the run parameters for the algorithm after its initialization.