Setup Classes

This module offers classes specifically designed for Operational Modal Analysis (OMA), suitable for both single and multiple setup scenarios. The classes includes methods for data management and processing, executing algorithms, visualizing outcomes, and setting up the geometry of structures. The module utilises two methods when dealing with data from multiple experimental setups: Post Separate Estimation Re-scaling (PoSER) [CRGF14], [RBCV15], and Pre Global Estimation Re-scaling (PreGER) [MiDo11], [SARB21].

Classes:
SingleSetup

Manages and processes single-setup data for OMA.

MultiSetup_PoSER

Conducts OMA for multi-setup experiments using the PoSER approach.

MultiSetup_PreGER

Conducts OMA for multi-setup experiments with the PreGER approach.

Note

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

The SingleSetup class

class pyoma2.setup.single.SingleSetup(data: ndarray, fs: float)[source]

Bases: BaseSetup, GeometryMixin

Class for managing and processing single setup data for Operational Modal Analysis.

This class handles data from a single setup, offering functionalities like plotting, data processing, and interaction with various analysis algorithms. It inherits attributes and methods from the BaseSetup class.

Parameters:

  • data (Iterable[float]) – The data to be processed, expected as an iterable of floats.

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

data

Stores the input data.

Type:

Iterable[float]

fs

Stores the sampling frequency.

Type:

float

dt

The sampling interval, calculated as the inverse of the sampling frequency.

Type:

float

algorithms

A dictionary to store algorithms associated with the setup.

Type:

Dict[str, BaseAlgorithm]

Notes

The algorithms dictionary is initialized empty and is meant to store various algorithms as needed.

__init__(data: ndarray, fs: float)[source]

Initialize a SingleSetup instance with data and sampling frequency.

Parameters:

  • data (np.ndarray) – The data to be processed, expected as a 2D array of shape (N, M)

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

add_algorithms(*algorithms: BaseAlgorithm) → None

Adds algorithms to the setup and configures them with data and sampling frequency.

Parameters:

algorithms (variable number of BaseAlgorithm) – One or more algorithm instances to be added to the setup.

Notes

The algorithms must be instantiated before adding them to the setup, and their names must be unique.

anim_mode_geo2(algo_res: BaseResult, *, mode_nr: int = 1, scaleF: float = 1.0, show_lines: bool = True, show_surf: bool = True, def_sett: dict | None = None, save_gif: bool = False, pl: pv.Plotter | None = None) → pv.Plotter | str

Creates an animation of the mode shape for the second geometry setup (geo2).

This wraps PvGeoPlotter.animate_mode, letting you animate a single mode (with optional GIF export) on geo2.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int, optional) – Mode number to animate (1-based). Default is 1.

  • scaleF (float, optional) – Scale factor for oscillation amplitude. Default is 1.0.

  • show_lines (bool, optional) – Whether to render connection lines during the animation. Default is True.

  • show_surf (bool, optional) – Whether to render surface faces during the animation. Default is True.

  • def_sett (dict or None, optional) – Plot settings for animation frames; falls back to defaults if None.

  • save_gif (bool, optional) – If True, save the animation as a GIF and return its filepath. Default is False.

  • pl (pv.Plotter or None, optional) – Existing Plotter to use; if None, one is created. Default is None.

Returns:

The Plotter instance for live animation, or filepath string if GIF was saved.

Return type:

pv.Plotter or str

Raises:

ValueError – If geo2 is not defined or if algo_res.Fn is None.

decimate_data(q: int, **kwargs) → None[source]

Decimates the data using the scipy.signal.decimate function.

This method reduces the sampling rate of the data by a factor of ‘q’. The decimation process includes low-pass filtering to reduce aliasing. The method updates the instance’s data and sampling frequency attributes.

Parameters:

  • q (int) – The decimation factor. Must be greater than 1.

  • **kwargs (dict, optional) –

    Additional keyword arguments for the scipy.signal.decimate function:

    nint, optional

    The order of the filter (if ‘ftype’ is ‘fir’) or the number of times to apply the filter (if ‘ftype’ is ‘iir’). If None, a default value is used.

    ftype{‘iir’, ‘fir’}, optional

    The type of filter to use for decimation: ‘iir’ for an IIR filter or ‘fir’ for an FIR filter. Default is ‘iir’.

    zero_phasebool, optional

    If True, applies a zero-phase filter, which has no phase distortion. If False, uses a causal filter with some phase distortion. Default is True.

Raises:

ValueError – If the decimation factor ‘q’ is not greater than 1.

Notes

For further information, see scipy.signal.decimate.

def_geo1(sens_names: List[str] | List[List[str]] | DataFrame | ndarray[tuple[Any, ...], dtype[str_]], sens_coord: DataFrame, sens_dir: ndarray[tuple[Any, ...], dtype[int64]], sens_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_surf: ndarray[tuple[Any, ...], dtype[float64]] = None) → None

Defines the first geometry setup (geo1) for the instance.

This method sets up the geometry involving sensors’ names, coordinates, directions, and optional elements like sensor lines, background nodes, lines, and surfaces.

Parameters:

  • sens_names (Union[numpy.ndarray of string, List of string]) – An array or list containing the names of the sensors.

  • sens_coord (pandas.DataFrame) – A DataFrame containing the coordinates of the sensors.

  • sens_dir (numpy.ndarray of int64) – An array defining the directions of the sensors.

  • sens_lines (numpy.ndarray of int64, optional) – An array defining lines connecting sensors. Default is None.

  • bg_nodes (numpy.ndarray of float64, optional) – An array defining background nodes. Default is None.

  • bg_lines (numpy.ndarray of int64, optional) – An array defining background lines. Default is None.

  • bg_surf (numpy.ndarray of float64, optional) – An array defining background surfaces. Default is None.

def_geo1_by_file(path: str, **read_excel_file_kwargs) → None

Defines the first geometry (geo1) from an Excel file.

This method reads an Excel file to extract sensor information, including sensor names, coordinates, and other optional geometry elements such as lines and background nodes. The information is used to set up the geometry for the instance.

Parameters:

  • path (str) – The file path to the Excel file containing the geometry data.

  • read_excel_file_kwargs (dict, optional) – Additional keyword arguments to pass to the read_excel_file function.

Raises:

ValueError – If the input data is invalid or missing required fields.

def_geo2(sens_names: List[str] | List[List[str]] | DataFrame | ndarray[tuple[Any, ...], dtype[str_]], pts_coord: DataFrame, sens_map: DataFrame, cstr: DataFrame = None, sens_sign: DataFrame = None, sens_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, sens_surf: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_lines: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_surf: ndarray[tuple[Any, ...], dtype[float64]] = None) → None

Defines the second geometry setup (geo2) for the instance.

This method sets up an alternative geometry configuration, including sensors’ names, points’ coordinates, mapping, sign data, and optional elements like constraints, sensor lines, background nodes, lines, and surfaces.

Parameters:

  • sens_names (Union[list of str, list of list of str, pandas.DataFrame, numpy.ndarray of str]) – Sensors’ names. It can be a list of strings, a list of lists of strings, a DataFrame, or a NumPy array.

  • pts_coord (pandas.DataFrame) – A DataFrame containing the coordinates of the points.

  • sens_map (pandas.DataFrame) – A DataFrame containing the mapping data for sensors.

  • cstrn (pandas.DataFrame, optional) – A DataFrame containing constraints. Default is None.

  • sens_sign (pandas.DataFrame, optional) – A DataFrame containing sign data for the sensors. Default is None.

  • sens_lines (numpy.ndarray of int64, optional) – An array defining lines connecting sensors. Default is None.

  • bg_nodes (numpy.ndarray of float64, optional) – An array defining background nodes. Default is None.

  • bg_lines (numpy.ndarray of float64, optional) – An array defining background lines. Default is None.

  • bg_surf (numpy.ndarray of float64, optional) – An array defining background surfaces. Default is None.

Notes

This method adapts indices for 0-indexed lines in bg_lines, sens_lines, and bg_surf.

def_geo2_by_file(path: str, **read_excel_file_kwargs) → None

Defines the second geometry (geo2) from an Excel file.

This method reads an Excel file to extract information related to the geometry configuration, including sensor names, points’ coordinates, mapping, and optional background nodes and surfaces. The information is used to set up the second geometry for the instance.

Parameters:

  • path (str) – The file path to the Excel file containing the geometry data.

  • read_excel_file_kwargs (dict, optional) – Additional keyword arguments to pass to the read_excel_file function.

Raises:

ValueError – If the input data is invalid or missing required fields.

detrend_data(**kwargs) → None[source]

Detrends the data using the scipy.signal.detrend function.

This method removes a linear or constant trend from the data, commonly used to remove drifts or offsets in time series data. It’s a preprocessing step, often necessary for methods that assume stationary data. The method updates the instance’s data attribute.

Parameters:

**kwargs (dict, optional) –

Additional keyword arguments for the scipy.signal.detrend function:

type{‘linear’, ‘constant’}, optional

The type of detrending: ‘linear’ for linear detrend, or ‘constant’ for just subtracting the mean. Default is ‘linear’.

bpint or numpy.ndarray of int, optional

Breakpoints where the data is split for piecewise detrending. Default is 0.

Raises:

ValueError – If invalid parameters are provided.

Notes

For further information, see scipy.signal.detrend.

filter_data(Wn: float | Tuple[float, float], order: int = 8, btype: str = 'lowpass') → None[source]

Apply a Butterworth filter to the input data and return the filtered signal.

This function designs and applies a Butterworth filter with the specified parameters to the input data. It can be used to apply lowpass, highpass, bandpass, or bandstop filters.

Parameters:

  • Wn (float or tuple of float) – The critical frequency or frequencies. For lowpass and highpass filters, Wn is a scalar; for bandpass and bandstop filters, Wn is a length-2 sequence.

  • order (int, optional) – The order of the filter. A higher order leads to a sharper frequency cutoff but can also lead to instability and significant phase delay. Default is 8.

  • btype (str, optional) – The type of filter to apply. Options are “lowpass”, “highpass”, “bandpass”, or “bandstop”. Default is “lowpass”.

Notes

For more information, see the scipy documentation for signal.butter (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.butter.html) and signal.sosfiltfilt (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.sosfiltfilt.html).

get(name: str, default: Optional[BaseAlgorithm] = None) → Optional[BaseAlgorithm]

Retrieves an algorithm from the setup by its name, returning a default value if not found.

Parameters:

  • name (str) – The name of the algorithm to retrieve.

  • default (BaseAlgorithm, optional) – The default value to return if the specified algorithm is not found.

Returns:

The algorithm instance with the specified name or the default value if not found.

Return type:

BaseAlgorithm or None

mpe(name: str, *args, **kwargs) → None

Extracts modal parameters from selected poles/peaks of a specified algorithm.

Parameters:

  • name (str) – Name of the algorithm from which to extract modal parameters.

  • args (tuple) – Positional arguments to be passed to the algorithm’s mpe method.

  • kwargs (dict) – Keyword arguments to be passed to the algorithm’s mpe method.

Raises:

KeyError – If the specified algorithm name does not exist in the setup.

mpe_from_plot(name: str, *args, **kwargs) → None

Extracts modal parameters directly from plot selections of a specified algorithm.

Parameters:

  • name (str) – Name of the algorithm from which to extract modal parameters.

  • args (tuple) – Positional arguments to be passed to the algorithm’s mpe method.

  • kwargs (dict) – Keyword arguments to be passed to the algorithm’s mpe method.

Raises:

KeyError – If the specified algorithm name does not exist in the setup.

plot_STFT(nxseg: float = 512, pov: float = 0.9, ch_idx: str | List[int] = 'all', freqlim: tuple[float, float] | None = None, win: str = 'hann') → Tuple[Figure, ndarray][source]

Plot the Short-Time Fourier Transform (STFT) magnitude spectrogram for the specified channels.

This method computes and plots the STFT magnitude spectrogram for each selected channel in the data. The spectrogram is plotted as a heatmap where the x-axis represents time, the y-axis represents frequency, and the color intensity represents the magnitude of the STFT.

Parameters:

  • data (ndarray) – The input signal data.

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

  • nxseg (int, optional) – The number of data points used in each segment of the STFT. Default is 512.

  • pov (float, optional) – The proportion of overlap between consecutive segments, expressed as a decimal between 0 and 1. Default is 0.9.

  • win (str, optional) – The type of window function to apply to each segment. Default is “hann”.

  • freqlim (tuple of float, optional) – The frequency limits (min, max) for the spectrogram display. Default is None, which uses the full frequency range.

  • ch_idx (str or list of int, optional) – The indices of the channels to plot. If “all”, the STFT for all channels is plotted. Default is “all”.

Returns:

  • figs (list of matplotlib.figure.Figure) – A list of figure objects, one for each channel plotted.

  • axs (list of matplotlib.axes.Axes) – A list of Axes objects corresponding to the figures.

plot_ch_info(nxseg: float = 1024, ch_idx: str | List[int] = 'all', freqlim: tuple[float, float] | None = None, logscale: bool = True, unit: str = 'unit') → Tuple[Figure, ndarray][source]

Plot channel information including time history, normalized auto-correlation, power spectral density (PSD), probability density function, and normal probability plot for each channel in the data.

Parameters:

  • data (ndarray) – The input signal data.

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

  • nxseg (int, optional) – The number of points per segment for the PSD estimation. Default is 1024.

  • freqlim (tuple of float, optional) – The frequency limits (min, max) for the PSD plot. Default is None.

  • logscale (bool, optional) – If True, the PSD plot will use a logarithmic scale. Default is False.

  • ch_idx (str or list of int, optional) – The indices of the channels to plot. If “all”, information for all channels is plotted. Default is “all”.

  • unit (str, optional) – The unit of the input data for labeling the plots. Default is “unit”.

Returns:

  • figs (list of matplotlib.figure.Figure) – A list of figure objects, one for each channel plotted.

  • axs (list of matplotlib.axes.Axes) – A list of Axes objects corresponding to the subplots for each channel’s information.

plot_data(nc: int = 1, names: List[str] | None = None, unit: str = 'unit', show_rms: bool = False) → Tuple[Figure, ndarray][source]

Plots the time histories of the data channels in a subplot format.

Parameters:

  • nc (int, optional) – Number of columns for the subplot. Default is 1.

  • names (List[str], optional) – List of names for the channels. If provided, these names are used as labels. Default is None.

  • unit (str, optional) – String label for the y-axis representing the unit of measurement. Default is “unit”.

  • show_rms (bool, optional) – If True, the RMS acceleration is shown in the plot. Default is False.

Returns:

A tuple containing the figure and axis objects of the plot for further customization or saving externally.

Return type:

tuple

plot_geo1(scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'red', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray', col_txt: str = 'red') → Tuple[Figure, Axes]

Plots the first geometry setup (geo1) using Matplotlib.

This method creates a 2D or 3D plot of the first geometry, including sensors, lines, background nodes, and surfaces, using customizable color schemes for each element.

Parameters:

  • scaleF (int, optional) – Scaling factor for the plot. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz'}, optional) – The view angle of the plot. Default is ‘3D’.

  • col_sns (str, optional) – Color of the sensors. Default is ‘red’.

  • col_sns_lines (str, optional) – Color of the lines connecting sensors. Default is ‘red’.

  • col_BG_nodes (str, optional) – Color of the background nodes. Default is ‘gray’.

  • col_BG_lines (str, optional) – Color of the background lines. Default is ‘gray’.

  • col_BG_surf (str, optional) – Color of the background surfaces. Default is ‘gray’.

  • col_txt (str, optional) – Color of the text labels for sensors. Default is ‘red’.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

tuple

Raises:

ValueError – If geo1 is not defined.

plot_geo2(*, scaleF: float = 1.0, col_sens: str = 'red', show_points: bool = True, show_lines: bool = True, show_surf: bool = True, points_sett: dict | None = None, lines_sett: dict | None = None, surf_sett: dict | None = None, background: bool = True, notebook: bool = False) → pv.Plotter

Plots the second geometry setup (geo2) using PyVista for 3D visualization.

This method creates a 3D interactive plot of the second geometry setup with options to visualize sensor points, connecting lines, and surfaces. It provides various customization options for coloring and rendering.

Parameters:

  • scaleF (float, optional) – Scaling factor for sensor arrow length. Default is 1.0.

  • col_sens (str, optional) – Color of the sensors. Default is ‘red’.

  • show_points (bool, optional) – Whether to plot sensor points. Default is True.

  • show_lines (bool, optional) – Whether to plot lines connecting sensors. Default is True.

  • show_surf (bool, optional) – Whether to plot surfaces connecting sensors. Default is True.

  • points_sett (dict or None, optional) – Settings for the points’ appearance; falls back to defaults if None.

  • lines_sett (dict or None, optional) – Settings for the lines’ appearance; falls back to defaults if None.

  • surf_sett (dict or None, optional) – Settings for the surfaces’ appearance; falls back to defaults if None.

  • background (bool, optional) – Whether to use a background Qt plotter if creating new. Default is True.

  • notebook (bool, optional) – Whether to render the plot in a Jupyter notebook environment. Default is False.

Returns:

A PyVista Plotter object with the geometry visualization.

Return type:

pyvista.Plotter

Raises:

ValueError – If geo2 is not defined.

plot_geo2_mpl(scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz', 'x', 'y', 'z'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'black', col_sns_surf: str = 'lightcoral', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray', col_txt: str = 'red') → Tuple[Figure, Axes]

Plots the second geometry setup (geo2) using Matplotlib.

This method creates a 2D or 3D plot of the second geometry, including sensors, lines, surfaces, background nodes, and surfaces, with customizable colors.

Parameters:

  • scaleF (int, optional) – Scaling factor for the plot. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz', 'x', 'y', 'z'}, optional) – The view angle of the plot. Default is ‘3D’.

  • col_sns (str, optional) – Color of the sensors. Default is ‘red’.

  • col_sns_lines (str, optional) – Color of the lines connecting sensors. Default is ‘black’.

  • col_sns_surf (str, optional) – Color of the surfaces connecting sensors. Default is ‘lightcoral’.

  • col_BG_nodes (str, optional) – Color of the background nodes. Default is ‘gray’.

  • col_BG_lines (str, optional) – Color of the background lines. Default is ‘gray’.

  • col_BG_surf (str, optional) – Color of the background surfaces. Default is ‘gray’.

  • col_txt (str, optional) – Color of the text labels for sensors. Default is ‘red’.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

tuple

Raises:

ValueError – If geo2 is not defined.

plot_mode_geo1(algo_res: BaseResult, mode_nr: int, scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'red', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray') → Tuple[Figure, Axes]

Plots the mode shapes for the first geometry setup (geo1) using Matplotlib.

This method visualizes the mode shapes corresponding to the specified mode number, with customizable colors and scaling for different geometrical elements such as sensors, lines, and background surfaces.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int) – The mode number to be plotted.

  • scaleF (int, optional) – Scaling factor to adjust the size of the mode shapes. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz'}, optional) – The viewing plane or angle for the plot. Default is ‘3D’.

  • col_sns (str, optional) – Color of the sensors in the plot. Default is ‘red’.

  • col_sns_lines (str, optional) – Color of the lines connecting the sensors. Default is ‘red’.

  • col_BG_nodes (str, optional) – Color of the background nodes in the plot. Default is ‘gray’.

  • col_BG_lines (str, optional) – Color of the background lines in the plot. Default is ‘gray’.

  • col_BG_surf (str, optional) – Color of the background surfaces in the plot. Default is ‘gray’.

Returns:

A tuple containing the Matplotlib figure and axes objects for further customization or saving.

Return type:

tuple

Raises:

ValueError – If geo1 is not defined or if the algorithm results are missing.

plot_mode_geo2(algo_res: BaseResult, *, mode_nr: int = 1, scaleF: float = 1.0, show_lines: bool = True, show_surf: bool = True, def_sett: dict | None = None, undef_sett: dict | None = None, background: bool = True, notebook: bool = False) → pv.Plotter

Plots the mode shapes for the second geometry setup (geo2) using PyVista.

This method creates an interactive 3D plot of a single mode shape (with undeformed geometry underneath) for the second geometry setup. You can toggle connection lines and surface faces, and supply custom plot settings.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int, optional) – Mode number to visualize (1-based). Default is 1.

  • scaleF (float, optional) – Scale factor for deformation amplitude. Default is 1.0.

  • show_lines (bool, optional) – Whether to render connection lines on the mode shape. Default is True.

  • show_surf (bool, optional) – Whether to render surface faces on the mode shape. Default is True.

  • def_sett (dict or None, optional) – Plot settings for the deformed shape; falls back to defaults if None.

  • undef_sett (dict or None, optional) – Plot settings for the undeformed shape; falls back to defaults if None.

  • background (bool, optional) – Whether to use a background Qt plotter if creating new. Default is True.

  • notebook (bool, optional) – Whether to render the plot in a Jupyter notebook environment. Default is False.

Returns:

A PyVista Plotter object with the mode‐shape visualization.

Return type:

pv.Plotter

Raises:

ValueError – If geo2 is not defined or if algo_res.Fn is None.

plot_mode_geo2_mpl(algo_res: BaseResult, mode_nr: int | None, scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', color: str = 'cmap', *args, **kwargs) → Tuple[Figure, Axes]

Plots the mode shapes for the second geometry setup (geo2) using Matplotlib.

This method visualizes the mode shapes for geo2, with customizable scaling, color, and viewing options. The plot can be configured for different modes and color maps.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int, optional) – The mode number to be plotted. If None, the default mode is plotted.

  • scaleF (int, optional) – Scaling factor to adjust the size of the mode shapes. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz'}, optional) – The viewing plane or angle for the plot. Default is ‘3D’.

  • color (str, optional) – Color scheme or colormap to be used for the mode shapes. Default is ‘cmap’.

Returns:

A tuple containing the Matplotlib figure and axes objects for further customization or saving.

Return type:

tuple

Raises:

ValueError – If geo2 is not defined or if the algorithm results are missing (e.g., Fn is None).

rollback() → None[source]

Restores the data and sampling frequency to their initial state.

This method reverts the data and fs attributes to their original values, effectively undoing any operations that modify the data, such as filtering, detrending, or decimation. It can be used to reset the setup to the state it was in after instantiation.

run_all() → None

Runs all the algorithms added to the setup.

Iterates through each algorithm stored in the setup and executes it. The results are saved within each algorithm instance.

Notes

This method assumes that all algorithms are properly initialized and can be executed without additional parameters.

run_by_name(name: str) → None

Runs a specific algorithm by its name.

Parameters:

name (str) – The name of the algorithm to be executed.

Raises:

KeyError – If the specified algorithm name does not exist in the setup.

Notes

The result of the algorithm execution is saved within the algorithm instance.

The MultiSetup_PoSER class

class pyoma2.setup.multi.MultiSetup_PoSER(ref_ind: List[List[int]], single_setups: List[SingleSetup], names: List[str])[source]

Bases: GeometryMixin

Class for conducting Operational Modal Analysis (OMA) on multi-setup experiments using the Post Separate Estimation Re-scaling (PoSER) approach. This approach is designed to merge and analyze data from multiple experimental setups for operational modal analysis.

ref_ind

Indices of reference sensors for each dataset, as a list of lists.

Type:

List[List[int]]

setups

A list of SingleSetup instances representing individual measurement setups.

Type:

List[SingleSetup]

names

A list of names for the algorithms used in each setup. Used to retrieve results.

Type:

List[str]

__result

Private attribute to store the merged results from multiple setups. Each entry in the dictionary corresponds to a specific algorithm used across setups, with its results.

Type:

Optional[Dict[str, MsPoserResult]]

Warning

The PoSER approach assumes that the setups used are compatible in terms of their experimental setup and data characteristics.

__init__(ref_ind: List[List[int]], single_setups: List[SingleSetup], names: List[str])[source]

Initializes the MultiSetup_PoSER instance with reference indices and a list of SingleSetup instances.

Parameters:

  • ref_ind (List[List[int]]) – Reference indices for merging results from different setups.

  • single_setups (List[SingleSetup]) – A list of SingleSetup instances to be merged using the PoSER approach.

  • names (List[str]) – A list of names for the algorithms used in each setup. Used to retrieve results. Te list must be len as the number of algorithms in each setup.

Raises:

ValueError – If any of the provided setups are invalid or incompatible.

merge_results() → Dict[str, MsPoserResult][source]

Merges results from individual setups into a combined result using the PoSER method.

Groups algorithms by type across all setups and merges their results. Calculates the mean and covariance of natural frequencies and damping ratios, and merges mode shapes.

Returns:

A dictionary containing the merged results for each algorithm type.

Return type:

Dict[str, MsPoserResult]

Raises:

ValueError – If the method is called before running algorithms on the setups.

property result: Dict[str, MsPoserResult]

Returns the merged results after applying the PoSER method.

Raises:

ValueError – If the merge_results() method has not been run yet.

property setups: List[SingleSetup]

Returns the list of SingleSetup instances representing individual measurement setups.

The MultiSetup_PreGER class

class pyoma2.setup.multi.MultiSetup_PreGER(fs: float, ref_ind: List[List[int]], datasets: List[ndarray[tuple[Any, ...], dtype[float64]]])[source]

Bases: BaseSetup, GeometryMixin

Class for conducting Operational Modal Analysis on multi-setup experiments using the Pre-Global Estimation Re-scaling (PreGER) approach. This class is tailored for handling and processing multiple datasets, applying the PreGER method efficiently. It offers functionalities for data visualization, preprocessing, and geometric configuration for the structure under analysis.

fs

The common sampling frequency across all datasets.

Type:

float

dt

The sampling interval, calculated as the inverse of the sampling frequency.

Type:

float

ref_ind

Indices of reference sensors for each dataset, as a list of lists.

Type:

list[list[int]]

datasets

The original list of datasets, each represented as a NumPy array.

Type:

list[npt.NDArray[np.float64]]

data

Processed data after applying the PreGER method, ready for analysis.

Type:

npt.NDArray[np.float64]

algorithms

Dictionary storing algorithms added to the setup, keyed by their names.

Type:

dict[str, BaseAlgorithm]

Nchs

A list containing the number of channels for each dataset.

Type:

list[int]

Ndats

A list containing the number of data points for each dataset.

Type:

list[int]

Ts

A list containing the total duration (in seconds) of each dataset.

Type:

list[float]

Nsetup

The number of setups (or datasets) included in the analysis.

Type:

int

Warning

The PreGER approach assumes that the setups used are compatible in terms of their experimental setup and data characteristics.

__init__(fs: float, ref_ind: List[List[int]], datasets: List[ndarray[tuple[Any, ...], dtype[float64]]])[source]

Initializes the MultiSetup_PreGER instance with specified sampling frequency, reference indices, and datasets.

Parameters:

  • fs (float) – The sampling frequency common to all datasets.

  • ref_ind (List[List[int]]) – Reference indices for each dataset, used in the PreGER method.

  • datasets (List[npt.NDArray[np.float64]]) – A list of datasets, each as a NumPy array.

add_algorithms(*algorithms: BaseAlgorithm) → None

Adds algorithms to the setup and configures them with data and sampling frequency.

Parameters:

algorithms (variable number of BaseAlgorithm) – One or more algorithm instances to be added to the setup.

Notes

The algorithms must be instantiated before adding them to the setup, and their names must be unique.

anim_mode_geo2(algo_res: BaseResult, *, mode_nr: int = 1, scaleF: float = 1.0, show_lines: bool = True, show_surf: bool = True, def_sett: dict | None = None, save_gif: bool = False, pl: pv.Plotter | None = None) → pv.Plotter | str

Creates an animation of the mode shape for the second geometry setup (geo2).

This wraps PvGeoPlotter.animate_mode, letting you animate a single mode (with optional GIF export) on geo2.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int, optional) – Mode number to animate (1-based). Default is 1.

  • scaleF (float, optional) – Scale factor for oscillation amplitude. Default is 1.0.

  • show_lines (bool, optional) – Whether to render connection lines during the animation. Default is True.

  • show_surf (bool, optional) – Whether to render surface faces during the animation. Default is True.

  • def_sett (dict or None, optional) – Plot settings for animation frames; falls back to defaults if None.

  • save_gif (bool, optional) – If True, save the animation as a GIF and return its filepath. Default is False.

  • pl (pv.Plotter or None, optional) – Existing Plotter to use; if None, one is created. Default is None.

Returns:

The Plotter instance for live animation, or filepath string if GIF was saved.

Return type:

pv.Plotter or str

Raises:

ValueError – If geo2 is not defined or if algo_res.Fn is None.

decimate_data(q: int, **kwargs: Any) → None[source]

Applies decimation to the data using the scipy.signal.decimate function.

This method reduces the sampling rate of the data by a factor of ‘q’. The decimation process includes low-pass filtering to reduce aliasing. The method updates the instance’s data and sampling frequency attributes.

Parameters:

  • q (int) – The decimation factor. Must be greater than 1.

  • **kwargs (dict, optional, will be passed to scipy.signal.decimate) –

    Additional keyword arguments for the scipy.signal.decimate function:

    nint, optional

    The order of the filter (if ‘ftype’ is ‘fir’) or the number of times to apply the filter (if ‘ftype’ is ‘iir’). If None, a default value is used.

    ftype{‘iir’, ‘fir’}, optional

    The type of filter to use for decimation: ‘iir’ for an IIR filter or ‘fir’ for an FIR filter. Default is ‘iir’.

    zero_phasebool, optional

    If True, applies a zero-phase filter, which has no phase distortion. If False, uses a causal filter with some phase distortion. Default is True.

Raises:

ValueError – If the decimation factor ‘q’ is not greater than 1.

Notes

For further information, see scipy.signal.decimate.

def_geo1(sens_names: List[str] | List[List[str]] | DataFrame | ndarray[tuple[Any, ...], dtype[str_]], sens_coord: DataFrame, sens_dir: ndarray[tuple[Any, ...], dtype[int64]], sens_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_surf: ndarray[tuple[Any, ...], dtype[float64]] = None) → None

Defines the first geometry setup (geo1) for the instance.

This method sets up the geometry involving sensors’ names, coordinates, directions, and optional elements like sensor lines, background nodes, lines, and surfaces.

Parameters:

  • sens_names (Union[numpy.ndarray of string, List of string]) – An array or list containing the names of the sensors.

  • sens_coord (pandas.DataFrame) – A DataFrame containing the coordinates of the sensors.

  • sens_dir (numpy.ndarray of int64) – An array defining the directions of the sensors.

  • sens_lines (numpy.ndarray of int64, optional) – An array defining lines connecting sensors. Default is None.

  • bg_nodes (numpy.ndarray of float64, optional) – An array defining background nodes. Default is None.

  • bg_lines (numpy.ndarray of int64, optional) – An array defining background lines. Default is None.

  • bg_surf (numpy.ndarray of float64, optional) – An array defining background surfaces. Default is None.

def_geo1_by_file(path: str, **read_excel_file_kwargs) → None

Defines the first geometry (geo1) from an Excel file.

This method reads an Excel file to extract sensor information, including sensor names, coordinates, and other optional geometry elements such as lines and background nodes. The information is used to set up the geometry for the instance.

Parameters:

  • path (str) – The file path to the Excel file containing the geometry data.

  • read_excel_file_kwargs (dict, optional) – Additional keyword arguments to pass to the read_excel_file function.

Raises:

ValueError – If the input data is invalid or missing required fields.

def_geo2(sens_names: List[str] | List[List[str]] | DataFrame | ndarray[tuple[Any, ...], dtype[str_]], pts_coord: DataFrame, sens_map: DataFrame, cstr: DataFrame = None, sens_sign: DataFrame = None, sens_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, sens_surf: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_lines: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_surf: ndarray[tuple[Any, ...], dtype[float64]] = None) → None

Defines the second geometry setup (geo2) for the instance.

This method sets up an alternative geometry configuration, including sensors’ names, points’ coordinates, mapping, sign data, and optional elements like constraints, sensor lines, background nodes, lines, and surfaces.

Parameters:

  • sens_names (Union[list of str, list of list of str, pandas.DataFrame, numpy.ndarray of str]) – Sensors’ names. It can be a list of strings, a list of lists of strings, a DataFrame, or a NumPy array.

  • pts_coord (pandas.DataFrame) – A DataFrame containing the coordinates of the points.

  • sens_map (pandas.DataFrame) – A DataFrame containing the mapping data for sensors.

  • cstrn (pandas.DataFrame, optional) – A DataFrame containing constraints. Default is None.

  • sens_sign (pandas.DataFrame, optional) – A DataFrame containing sign data for the sensors. Default is None.

  • sens_lines (numpy.ndarray of int64, optional) – An array defining lines connecting sensors. Default is None.

  • bg_nodes (numpy.ndarray of float64, optional) – An array defining background nodes. Default is None.

  • bg_lines (numpy.ndarray of float64, optional) – An array defining background lines. Default is None.

  • bg_surf (numpy.ndarray of float64, optional) – An array defining background surfaces. Default is None.

Notes

This method adapts indices for 0-indexed lines in bg_lines, sens_lines, and bg_surf.

def_geo2_by_file(path: str, **read_excel_file_kwargs) → None

Defines the second geometry (geo2) from an Excel file.

This method reads an Excel file to extract information related to the geometry configuration, including sensor names, points’ coordinates, mapping, and optional background nodes and surfaces. The information is used to set up the second geometry for the instance.

Parameters:

  • path (str) – The file path to the Excel file containing the geometry data.

  • read_excel_file_kwargs (dict, optional) – Additional keyword arguments to pass to the read_excel_file function.

Raises:

ValueError – If the input data is invalid or missing required fields.

detrend_data(**kwargs: Any) → None[source]

Detrends the data using the scipy.signal.detrend function.

This method removes a linear or constant trend from the data, commonly used to remove drifts or offsets in time series data. It’s a preprocessing step, often necessary for methods that assume stationary data. The method updates the instance’s data attribute.

Parameters:

**kwargs (dict, optional) –

Additional keyword arguments for the scipy.signal.detrend function:

type{‘linear’, ‘constant’}, optional

The type of detrending: ‘linear’ for linear detrend, or ‘constant’ for just subtracting the mean. Default is ‘linear’.

bpint or numpy.ndarray of int, optional

Breakpoints where the data is split for piecewise detrending. Default is 0.

Raises:

ValueError – If invalid parameters are provided.

Notes

For further information, see scipy.signal.detrend.

filter_data(Wn: float | Tuple[float, float], order: int = 8, btype: str = 'lowpass') → None[source]

Apply a Butterworth filter to the input data and return the filtered signal.

This function designs and applies a Butterworth filter with the specified parameters to the input data. It can be used to apply lowpass, highpass, bandpass, or bandstop filters.

Parameters:

  • Wn (float or tuple of float) – The critical frequency or frequencies. For lowpass and highpass filters, Wn is a scalar; for bandpass and bandstop filters, Wn is a length-2 sequence.

  • order (int, optional) – The order of the filter. A higher order leads to a sharper frequency cutoff but can also lead to instability and significant phase delay. Default is 8.

  • btype (str, optional) – The type of filter to apply. Options are “lowpass”, “highpass”, “bandpass”, or “bandstop”. Default is “lowpass”.

Notes

For more information, see the scipy documentation for signal.butter (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.butter.html) and signal.sosfiltfilt (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.sosfiltfilt.html).

get(name: str, default: Optional[BaseAlgorithm] = None) → Optional[BaseAlgorithm]

Retrieves an algorithm from the setup by its name, returning a default value if not found.

Parameters:

  • name (str) – The name of the algorithm to retrieve.

  • default (BaseAlgorithm, optional) – The default value to return if the specified algorithm is not found.

Returns:

The algorithm instance with the specified name or the default value if not found.

Return type:

BaseAlgorithm or None

mpe(name: str, *args, **kwargs) → None

Extracts modal parameters from selected poles/peaks of a specified algorithm.

Parameters:

  • name (str) – Name of the algorithm from which to extract modal parameters.

  • args (tuple) – Positional arguments to be passed to the algorithm’s mpe method.

  • kwargs (dict) – Keyword arguments to be passed to the algorithm’s mpe method.

Raises:

KeyError – If the specified algorithm name does not exist in the setup.

mpe_from_plot(name: str, *args, **kwargs) → None

Extracts modal parameters directly from plot selections of a specified algorithm.

Parameters:

  • name (str) – Name of the algorithm from which to extract modal parameters.

  • args (tuple) – Positional arguments to be passed to the algorithm’s mpe method.

  • kwargs (dict) – Keyword arguments to be passed to the algorithm’s mpe method.

Raises:

KeyError – If the specified algorithm name does not exist in the setup.

plot_STFT(data_idx: str | List[int] = 'all', nxseg: float = 256, pov: float = 0.9, ch_idx: str | List[int] = 'all', freqlim: Tuple[float, float] | None = None, win: str = 'hann') → Tuple[Figure, ndarray[Axes]][source]

Plot the Short-Time Fourier Transform (STFT) magnitude spectrogram for the specified channels.

This method computes and plots the STFT magnitude spectrogram for each selected channel in the specified datasets. The spectrogram is plotted as a heatmap where the x-axis represents time, the y-axis represents frequency, and the color intensity represents the magnitude of the STFT.

Parameters:

  • data_idx (str or list[int], optional) – Indices of the datasets to plot. Use ‘all’ to plot data for all datasets. Default is ‘all’.

  • nxseg (float, optional) – The number of data points per segment for the STFT calculation. Default is 256.

  • pov (float, optional) – Proportion of overlap between consecutive segments, expressed as a decimal between 0 and 1. Default is 0.9 (90% overlap).

  • ch_idx (str or list[int], optional) – Indices of the channels to plot. Use ‘all’ to plot information for all channels. Default is ‘all’.

  • freqlim (tuple of float, optional) – Frequency limits (min, max) for the STFT plot. Default is None, using the full range.

  • win (str, optional) – The windowing function to apply to each segment. Default is ‘hann’.

Returns:

A tuple containing lists of figure and axes objects for further customization or saving.

Return type:

tuple

plot_ch_info(data_idx: str | List[int] = 'all', nxseg: float = 1024, ch_idx: str | List[int] = 'all', freqlim: Tuple[float, float] | None = None, logscale: bool = True, unit: str = 'unit') → Tuple[Figure, ndarray[Axes]][source]

Plot channel information including time history, normalized auto-correlation, power spectral density (PSD), probability density function, and normal probability plot for each channel in the selected datasets.

Parameters:

  • data_idx (str or list[int], optional) – Indices of the datasets to plot. Use ‘all’ to plot data for all datasets. Default is ‘all’.

  • nxseg (float, optional) – The number of data points per segment for the PSD estimation. Default is 1024.

  • ch_idx (str or list[int], optional) – Indices of the channels to plot. Use ‘all’ to plot information for all channels. Default is ‘all’.

  • freqlim (tuple of float, optional) – Frequency limits (min, max) for the PSD plot. Default is None, using the full range.

  • logscale (bool, optional) – Whether to use a logarithmic scale for the PSD plot. Default is True.

  • unit (str, optional) – Unit of measurement for the data, used in labeling the plots. Default is ‘unit’.

Returns:

A tuple containing lists of figure and axes objects for further customization or saving.

Return type:

tuple

plot_data(data_idx: str | List[int] = 'all', nc: int = 1, names: List[str] | None = None, unit: str = 'unit', show_rms: bool = False) → Tuple[Figure, Axes][source]

Plots the time histories of the data channels for selected datasets.

Allows for visualization of the time history of each data channel across multiple datasets. Users can specify which datasets to plot, configure subplot layout, and optionally display RMS acceleration.

Parameters:

  • data_idx (str | list[int], optional) – Indices of datasets to be plotted. Can be a list of indices or ‘all’ for all datasets. Default is ‘all’.

  • nc (int, optional) – Number of columns for the subplot layout. Default is 1.

  • names (Optional[List[str]], optional) – Names for the channels in each dataset. If provided, these names are used as labels. Default is None.

  • unit (str, optional) – Unit of measurement for the y-axis. Default is “unit”.

  • show_rms (bool, optional) – If True, shows the RMS acceleration in the plot. Default is False.

Returns:

A list of tuples, each containing the figure and axes objects for the plots of each dataset.

Return type:

list

plot_geo1(scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'red', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray', col_txt: str = 'red') → Tuple[Figure, Axes]

Plots the first geometry setup (geo1) using Matplotlib.

This method creates a 2D or 3D plot of the first geometry, including sensors, lines, background nodes, and surfaces, using customizable color schemes for each element.

Parameters:

  • scaleF (int, optional) – Scaling factor for the plot. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz'}, optional) – The view angle of the plot. Default is ‘3D’.

  • col_sns (str, optional) – Color of the sensors. Default is ‘red’.

  • col_sns_lines (str, optional) – Color of the lines connecting sensors. Default is ‘red’.

  • col_BG_nodes (str, optional) – Color of the background nodes. Default is ‘gray’.

  • col_BG_lines (str, optional) – Color of the background lines. Default is ‘gray’.

  • col_BG_surf (str, optional) – Color of the background surfaces. Default is ‘gray’.

  • col_txt (str, optional) – Color of the text labels for sensors. Default is ‘red’.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

tuple

Raises:

ValueError – If geo1 is not defined.

plot_geo2(*, scaleF: float = 1.0, col_sens: str = 'red', show_points: bool = True, show_lines: bool = True, show_surf: bool = True, points_sett: dict | None = None, lines_sett: dict | None = None, surf_sett: dict | None = None, background: bool = True, notebook: bool = False) → pv.Plotter

Plots the second geometry setup (geo2) using PyVista for 3D visualization.

This method creates a 3D interactive plot of the second geometry setup with options to visualize sensor points, connecting lines, and surfaces. It provides various customization options for coloring and rendering.

Parameters:

  • scaleF (float, optional) – Scaling factor for sensor arrow length. Default is 1.0.

  • col_sens (str, optional) – Color of the sensors. Default is ‘red’.

  • show_points (bool, optional) – Whether to plot sensor points. Default is True.

  • show_lines (bool, optional) – Whether to plot lines connecting sensors. Default is True.

  • show_surf (bool, optional) – Whether to plot surfaces connecting sensors. Default is True.

  • points_sett (dict or None, optional) – Settings for the points’ appearance; falls back to defaults if None.

  • lines_sett (dict or None, optional) – Settings for the lines’ appearance; falls back to defaults if None.

  • surf_sett (dict or None, optional) – Settings for the surfaces’ appearance; falls back to defaults if None.

  • background (bool, optional) – Whether to use a background Qt plotter if creating new. Default is True.

  • notebook (bool, optional) – Whether to render the plot in a Jupyter notebook environment. Default is False.

Returns:

A PyVista Plotter object with the geometry visualization.

Return type:

pyvista.Plotter

Raises:

ValueError – If geo2 is not defined.

plot_geo2_mpl(scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz', 'x', 'y', 'z'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'black', col_sns_surf: str = 'lightcoral', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray', col_txt: str = 'red') → Tuple[Figure, Axes]

Plots the second geometry setup (geo2) using Matplotlib.

This method creates a 2D or 3D plot of the second geometry, including sensors, lines, surfaces, background nodes, and surfaces, with customizable colors.

Parameters:

  • scaleF (int, optional) – Scaling factor for the plot. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz', 'x', 'y', 'z'}, optional) – The view angle of the plot. Default is ‘3D’.

  • col_sns (str, optional) – Color of the sensors. Default is ‘red’.

  • col_sns_lines (str, optional) – Color of the lines connecting sensors. Default is ‘black’.

  • col_sns_surf (str, optional) – Color of the surfaces connecting sensors. Default is ‘lightcoral’.

  • col_BG_nodes (str, optional) – Color of the background nodes. Default is ‘gray’.

  • col_BG_lines (str, optional) – Color of the background lines. Default is ‘gray’.

  • col_BG_surf (str, optional) – Color of the background surfaces. Default is ‘gray’.

  • col_txt (str, optional) – Color of the text labels for sensors. Default is ‘red’.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

tuple

Raises:

ValueError – If geo2 is not defined.

plot_mode_geo1(algo_res: BaseResult, mode_nr: int, scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'red', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray') → Tuple[Figure, Axes]

Plots the mode shapes for the first geometry setup (geo1) using Matplotlib.

This method visualizes the mode shapes corresponding to the specified mode number, with customizable colors and scaling for different geometrical elements such as sensors, lines, and background surfaces.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int) – The mode number to be plotted.

  • scaleF (int, optional) – Scaling factor to adjust the size of the mode shapes. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz'}, optional) – The viewing plane or angle for the plot. Default is ‘3D’.

  • col_sns (str, optional) – Color of the sensors in the plot. Default is ‘red’.

  • col_sns_lines (str, optional) – Color of the lines connecting the sensors. Default is ‘red’.

  • col_BG_nodes (str, optional) – Color of the background nodes in the plot. Default is ‘gray’.

  • col_BG_lines (str, optional) – Color of the background lines in the plot. Default is ‘gray’.

  • col_BG_surf (str, optional) – Color of the background surfaces in the plot. Default is ‘gray’.

Returns:

A tuple containing the Matplotlib figure and axes objects for further customization or saving.

Return type:

tuple

Raises:

ValueError – If geo1 is not defined or if the algorithm results are missing.

plot_mode_geo2(algo_res: BaseResult, *, mode_nr: int = 1, scaleF: float = 1.0, show_lines: bool = True, show_surf: bool = True, def_sett: dict | None = None, undef_sett: dict | None = None, background: bool = True, notebook: bool = False) → pv.Plotter

Plots the mode shapes for the second geometry setup (geo2) using PyVista.

This method creates an interactive 3D plot of a single mode shape (with undeformed geometry underneath) for the second geometry setup. You can toggle connection lines and surface faces, and supply custom plot settings.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int, optional) – Mode number to visualize (1-based). Default is 1.

  • scaleF (float, optional) – Scale factor for deformation amplitude. Default is 1.0.

  • show_lines (bool, optional) – Whether to render connection lines on the mode shape. Default is True.

  • show_surf (bool, optional) – Whether to render surface faces on the mode shape. Default is True.

  • def_sett (dict or None, optional) – Plot settings for the deformed shape; falls back to defaults if None.

  • undef_sett (dict or None, optional) – Plot settings for the undeformed shape; falls back to defaults if None.

  • background (bool, optional) – Whether to use a background Qt plotter if creating new. Default is True.

  • notebook (bool, optional) – Whether to render the plot in a Jupyter notebook environment. Default is False.

Returns:

A PyVista Plotter object with the mode‐shape visualization.

Return type:

pv.Plotter

Raises:

ValueError – If geo2 is not defined or if algo_res.Fn is None.

plot_mode_geo2_mpl(algo_res: BaseResult, mode_nr: int | None, scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', color: str = 'cmap', *args, **kwargs) → Tuple[Figure, Axes]

Plots the mode shapes for the second geometry setup (geo2) using Matplotlib.

This method visualizes the mode shapes for geo2, with customizable scaling, color, and viewing options. The plot can be configured for different modes and color maps.

Parameters:

  • algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

  • mode_nr (int, optional) – The mode number to be plotted. If None, the default mode is plotted.

  • scaleF (int, optional) – Scaling factor to adjust the size of the mode shapes. Default is 1.

  • view ({'3D', 'xy', 'xz', 'yz'}, optional) – The viewing plane or angle for the plot. Default is ‘3D’.

  • color (str, optional) – Color scheme or colormap to be used for the mode shapes. Default is ‘cmap’.

Returns:

A tuple containing the Matplotlib figure and axes objects for further customization or saving.

Return type:

tuple

Raises:

ValueError – If geo2 is not defined or if the algorithm results are missing (e.g., Fn is None).

rollback() → None[source]

Restores the data and sampling frequency to their initial state.

This method reverts the data and fs attributes to their original values, effectively undoing any operations that modify the data, such as filtering, detrending, or decimation. It can be used to reset the setup to the state it was in after instantiation.

run_all() → None

Runs all the algorithms added to the setup.

Iterates through each algorithm stored in the setup and executes it. The results are saved within each algorithm instance.

Notes

This method assumes that all algorithms are properly initialized and can be executed without additional parameters.

run_by_name(name: str) → None

Runs a specific algorithm by its name.

Parameters:

name (str) – The name of the algorithm to be executed.

Raises:

KeyError – If the specified algorithm name does not exist in the setup.

Notes

The result of the algorithm execution is saved within the algorithm instance.