The plscf algorithm module

This module implements the Poly-reference Least Square Complex Frequency (pLSCF) algorithm [PAGL04], a robust identification method in the frequency domain. It is specifically designed for both single and multi-setup experimental scenarios. The module includes classes and methods for process measurement data, extract modal parameters and visualisation tools.

Classes:

pLSCF

Implements the Data-Driven SSI algorithm for single setup.

pLSCF_MS

Implements the Covariance-Driven SSI algorithm for single setup.

Important

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

Note

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

The pLSCF class

class pyoma2.algorithms.plscf.pLSCF(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)

Bases: BaseAlgorithm

Implementation of the poly-reference Least Square Complex Frequency (pLSCF) algorithm for modal analysis.

This class inherits from BaseAlgorithm and specializes in handling modal analysis computations and visualizations based on the pLSCF method. It provides methods to run the analysis, extract modal parameter estimation (mpe), plot stability diagrams, cluster diagrams, mode shapes, and animations of mode shapes.

Parameters:

BaseAlgorithm (type) – Inherits from the BaseAlgorithm class with specified type parameters for pLSCFRunParams, pLSCFResult, and Iterable[float].

RunParamCls

Class attribute for run parameters specific to pLSCF algorithm.

Type:

pLSCFRunParams

ResultCls

Class attribute for results specific to pLSCF algorithm.

Type:

pLSCFResult

ResultCls

alias of pLSCFResult

RunParamCls

alias of pLSCFRunParams

__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: int | str = 'find_min', rtol: float = 0.05) → Any

Extract the modal parameters at the selected frequencies and order.

Parameters:

• sel_freq (List[float]) – A list of frequencies for which the modal parameters are to be estimated.

• order (int or str, optional) – The order for modal parameter estimation or “find_min”. Default is ‘find_min’.

• deltaf (float, optional) – The frequency range around each selected frequency to consider for estimation. Default is 0.05.

• rtol (float, optional) – Relative tolerance for convergence in the iterative estimation process. Default is 1e-2.

Returns:

The results of the modal parameter estimation, typically including estimated frequencies, damping ratios, and mode shapes.

Return type:

Any

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

Extract the modal parameters directly from the stabilisation chart.

Parameters:

• freqlim (tuple of float, optional) – A tuple specifying the frequency limits (min, max) for the plot. If None, the limits are determined automatically. Default is None.

• deltaf (float, optional) – The frequency range around each selected frequency to consider for estimation. Default is 0.05.

• rtol (float, optional) – Relative tolerance for convergence in the iterative estimation process. Default is 1e-2.

Returns:

The results of the modal parameter estimation based on user selection from the plot.

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 distribution of identified modal frequencies and their corresponding damping ratios. It helps identify clusters of stable 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.

• 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 pLSCF analysis.

The stability diagram helps visualize the stability of poles across different model orders. It can be used to identify stable poles, which correspond to physical modes.

Parameters:

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

• hide_poles (bool, optional) – Option to hide the unstable poles in the diagram 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 objects for the stability diagram.

Return type:

Any

run() → pLSCFResult

Execute the pLSCF algorithm to perform modal analysis on the provided data.

This method conducts a frequency domain analysis using the Least Square Complex Frequency method. It computes system matrices, identifies poles, and labels them based on stability and other criteria.

Returns:

An instance of pLSCFResult containing the analysis results, including frequencies, system matrices, identified poles, and their labels.

Return type:

pLSCFResult

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 pLSCF_MS class

class pyoma2.algorithms.plscf.pLSCF_MS(run_params: T_RunParams | None = None, name: str | None = None, *args: Any, **kwargs: Any)

Bases: pLSCF

A multi-setup extension of the pLSCF class for the poly-reference Least Square Complex Frequency (pLSCF) algorithm.

Parameters:

pLSCF (type) – Inherits from the pLSCF class with specified type parameters for pLSCFRunParams, pLSCFResult, and Iterable[dict].

RunParamCls

Class attribute for run parameters specific to pLSCF algorithm.

Type:

pLSCFRunParams

ResultCls

Class attribute for results specific to pLSCF algorithm.

Type:

pLSCFResult

ResultCls

alias of pLSCFResult

RunParamCls

alias of pLSCFRunParams

__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: int | str = 'find_min', rtol: float = 0.05) → Any

Extract the modal parameters at the selected frequencies and order.

Parameters:

• sel_freq (List[float]) – A list of frequencies for which the modal parameters are to be estimated.

• order (int or str, optional) – The order for modal parameter estimation or “find_min”. Default is ‘find_min’.

• deltaf (float, optional) – The frequency range around each selected frequency to consider for estimation. Default is 0.05.

• rtol (float, optional) – Relative tolerance for convergence in the iterative estimation process. Default is 1e-2.

Returns:

The results of the modal parameter estimation, typically including estimated frequencies, damping ratios, and mode shapes.

Return type:

Any

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

Extract the modal parameters directly from the stabilisation chart.

Parameters:

• freqlim (tuple of float, optional) – A tuple specifying the frequency limits (min, max) for the plot. If None, the limits are determined automatically. Default is None.

• deltaf (float, optional) – The frequency range around each selected frequency to consider for estimation. Default is 0.05.

• rtol (float, optional) – Relative tolerance for convergence in the iterative estimation process. Default is 1e-2.

Returns:

The results of the modal parameter estimation based on user selection from the plot.

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 distribution of identified modal frequencies and their corresponding damping ratios. It helps identify clusters of stable 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.

• 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 pLSCF analysis.

The stability diagram helps visualize the stability of poles across different model orders. It can be used to identify stable poles, which correspond to physical modes.

Parameters:

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

• hide_poles (bool, optional) – Option to hide the unstable poles in the diagram 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 objects for the stability diagram.

Return type:

Any

run() → pLSCFResult

Execute the pLSCF algorithm to perform modal analysis on the provided data.

This method conducts a frequency domain analysis using the Least Square Complex Frequency method. It computes system matrices, identifies poles, and labels them based on stability and other criteria.

Returns:

An instance of pLSCFResult containing the analysis results, including frequencies, system matrices, identified poles, and their labels.

Return type:

pLSCFResult

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.