pyOMA.core.PLSCF.PLSCF#

class pyOMA.core.PLSCF.PLSCF(*args, **kwargs)[source]#

Bases: ModalBase

__init__(*args, **kwargs)[source]#

Methods

__init__(*args, **kwargs)

build_half_spectra([nperseg, ...])

Extracts an array of positive half spectra between begin_frequency and end_frequency from a spectrum of nperseg frequency lines.

compute_modal_params(max_model_order[, ...])

Perform a multi-order computation of modal parameters.

estimate_model(order[, complex_coefficients])

Estimate a right matrix-fraction model from positive half-spectra, by constructing a set of reduced normal equations as shown in Peeters 2004.

init_from_config(conf_file, prep_signals)

A method for initializing a modal object from configuration data bypassing common operations in explicit code for semi-automated analyses

integrate_quantities(vector, accel_channels, ...)

Rescales mode shapes from modal accelerations / velocities to modal displacements, by multiplication of the relevant modal coordinates (where accelerometers, or velocimeters were used, with $-1 omega^2$ or $i omega$, respectively,

load_state(fname, prep_signals)

Loads the state of the object from a compressed numpy archive file and returns the object This is only a stub for reimplementing the method in a derived class

modal_analysis_residuals(alpha, *args)

Perform a modal analysis of the identified polyomial with the least-squares residual-based method as outlined in Steffensen-2025-VarianceEstimation.

modal_analysis_state_space(alpha, beta_l_i)

Perform a modal analysis of the identified polyomial by converting it into a state-space model, as outlined in Reynders-2012: Lemma 2.2, followed by an eigendecomposition.

remove_conjugates(eigval[, eigvec_r, ...])

This method finds complex conjugate modes, and removes unstable and overdamped poles.

rescale_mode_shape(modeshape[, rotate_only])

Rescales and rotates modeshapes in the complex plane.

save_state(fname)

Saves the state of the object to a compressed numpy archive file This is only a stub for reimplementing the method in a derived class

synthesize_spectrum(alpha, beta_l_i[, modal])

Spectral synthetization in a modal decoupled form follows Steffensen-2025-VarianceEstimation.

Attributes

num_omega

build_half_spectra(nperseg=None, begin_frequency=None, end_frequency=None, window_decay=0.001, **kwargs)[source]#

Extracts an array of positive half spectra between begin_frequency and end_frequency from a spectrum of nperseg frequency lines. If begin_frequency > 0.0 or end_frequency<nyquist freqeuncy, the resulting array has less than nperseg lines.

Positive power spectra are constructed from positive correlation functions, that are windowed by an exponential window and transformed to frequency domain by and (R)FFT. Correlation functions are computed in prep_signals by either Welch’s or Blackman-Tukey’s method, though, Welch’s method is not recommmended, because the artificial damping introduced by windowing can not be corrected.

See: Cauberghe-2004-Applied Frequency-Domain System … : Sections 3.4ff

Note: The previous implementation contained severe mistakes in the computation of positive power spectra, e.g. doubled squaring of spectral values, lazy handling of array dimensions and therefore effectively only a quarter of nperseg being used as well as numerical inefficiencies.

Todo

  • Move spectral estimation into prep_signals.pds_blackman_tukey and only keep bandwidth selection and argument checking here

  • Allow other windows than exponential

Parameters:

  • nperseg (integer, optional) – Number of (positive) frequency lines to consider (rfft)

  • begin_frequency (float, optional) – Frequency range to restrict the identified system.

  • end_frequency (float, optional) – Frequency range to restrict the identified system.

  • window_decay (float, (0,1)) – Final value of the exponential window, that is applied to the correlation functions.

  • kwargs – Additional kwargs are passed to prep_signals.correlation

compute_modal_params(max_model_order, complex_coefficients=False, algo='residuals', modal_contrib=None)[source]#

Perform a multi-order computation of modal parameters. Successively calls

  • estimate_model(order, complex_coefficients)

  • modal_analysis_residuals(alpha, beta_l_i) or modal_analysis_state_space(alpha, beta_l_i)

  • synthesize_spectrum(alpha, beta_l_i), if modal_contrib == True

At ascending model orders, up to max_model_order. See the explanations in the the respective methods, for a detailed explanation of parameters.

Parameters:

  • max_model_order (integer) – Maximum model order, where to interrupt the algorithm.

  • complex_coefficients (bool, optional) – Whether to estimate a real or complex RMFD model

  • algo (str, optional) – Algorithm to use for modal analysis. Either ‘state-space’ or ‘residuals’ Both algorithms are approximately equally fast. The state space based algorithm seems to yield less complex mode shapes.

  • modal_contrib (bool, optional) – Synthesize modal spectra and estimate modal contributions. Only to be used with residual-based modal analysis algorithm.

estimate_model(order, complex_coefficients=False)[source]#

Estimate a right matrix-fraction model from positive half-spectra, by constructing a set of reduced normal equations as shown in Peeters 2004. The polynomial is identified following Cauberghe 2004. Sec. 5.2.1

Verboven 2002: Sect. 5.3.3 has a discussion on the use of real or complex valued coefficients, favoring complex ones. Guillaume 2003, Peeters 2004 just assume real coefficients, while later references, e.g. Cauberghe 2004, Reynders 2012 use complex coefficients. However, with complex coefficients, stabilization diagrams seem to become corrupted.

Note: The previous implementation was wrong in the estimation of alpha coefficients and led to “bad” stabilization. Additionally there was a wrong sign in the assembly of the C_c matrix, which led to corrupted mode shapes.

Todo

  • implement weighting function; c.p. Peeters 2004 Sect. 2.2

  • improve assembly by exploiting the Toeplitz structure of S, R, T; c.p. Cauberghe 2004 Eq. 5.17ff

  • Investigate LS-TLS solution by using a SVD

  • estimate polynomial once at highest order and construct all lower order models from these coefficients; c.p. Peeters 2004 Sect. 2.4

  • Check, if alternative solution for lpha in Reynders 2012. Sec. 5.2.4 leads to clearer stabilization, or it it is actually equivalent to the current implementation

Parameters:

  • order (integer, required) – Model order, at which the RMF model should be estimated

  • complex_coefficients (bool, optional) – Whether to assume real or complex coefficients

Returns:

  • alpha (numpy.ndarray) – Denominator coefficients: Array of shape ((order + 1) * n_r, n_r)

  • beta_l_i (numpy.ndarray) – Numerator coefficients: Array of shape (order + 1, n_r, n_l)

classmethod init_from_config(conf_file, prep_signals)[source]#

A method for initializing a modal object from configuration data bypassing common operations in explicit code for semi-automated analyses

This is a stub of the method that must be reimplemented by every derived class

classmethod load_state(fname, prep_signals)[source]#

Loads the state of the object from a compressed numpy archive file and returns the object This is only a stub for reimplementing the method in a derived class

modal_analysis_residuals(alpha, *args)[source]#

Perform a modal analysis of the identified polyomial with the least-squares residual-based method as outlined in Steffensen-2025-VarianceEstimation… Sect. 2.1 Mode shapes are scaled to unit modal displacements. Complex conjugate and real modes are removed prior to further processing. Damping values are corrected, if half-spectra were constructed with an exponential window.

Todo

  • numerical optimization to increase speed

Parameters:

alpha (numpy.ndarray) – Denominator coefficients: Array of shape ((order + 1) * n_r, n_r)

Returns:

  • modal_frequencies ((order * n_r,) numpy.ndarray) – Array holding the modal frequencies for each mode

  • modal_damping ((order * n_r,) numpy.ndarray) – Array holding the modal damping ratios (0,100) for each mode

  • mode_shapes ((n_l, order * n_r,) numpy.ndarray) – Complex array holding the mode shapes

  • eigenvalues ((order * n_r,) numpy.ndarray) – Complex array holding the _eigenvalues for each mode

modal_analysis_state_space(alpha, beta_l_i)[source]#

Perform a modal analysis of the identified polyomial by converting it into a state-space model, as outlined in Reynders-2012: Lemma 2.2, followed by an eigendecomposition. Mode shapes are scaled to unit modal displacements. Complex conjugate and real modes are removed prior to further processing. Damping values are corrected, if half-spectra were constructed with an exponential window.

Todo

  • numerical optimization to increase speed

Parameters:

  • alpha (numpy.ndarray) – Denominator coefficients: Array of shape ((order + 1) * n_r, n_r)

  • beta_l_i (numpy.ndarray) – Numerator coefficients: Array of shape (order + 1, n_r, n_l)

Returns:

  • modal_frequencies ((order * n_r,) numpy.ndarray) – Array holding the modal frequencies for each mode

  • modal_damping ((order * n_r,) numpy.ndarray) – Array holding the modal damping ratios (0,100) for each mode

  • mode_shapes ((n_l, order * n_r,) numpy.ndarray) – Complex array holding the mode shapes

  • eigenvalues ((order * n_r,) numpy.ndarray) – Complex array holding the eigenvalues for each mode

save_state(fname)[source]#

Saves the state of the object to a compressed numpy archive file This is only a stub for reimplementing the method in a derived class

synthesize_spectrum(alpha, beta_l_i, modal=True)[source]#

Spectral synthetization in a modal decoupled form follows Steffensen-2025-VarianceEstimation… Sect. 2.1.2 The spectral synthetization without modal decomposition follows Peeters-2004-ThePolyMAX…

Todo

  • numerical optimization to increase speed

Parameters:

  • alpha (numpy.ndarray) – Denominator coefficients: Array of shape ((order + 1) * n_r, n_r)

  • beta_l_i (numpy.ndarray) – Numerator coefficients: Array of shape (order + 1, n_r, n_l)

  • modal (bool, optional) – Synthesize a spectrum for each mode and its modal contribution to the full spectrum

Returns:

  • half_spec_modal ((n_l, n_r, num_omega, n_modes) numpy.ndarray) – Array holding the (modally decomposed) synthesized positive half spectra for each channel n_l and reference channel n_r and all modes

  • modal_contributions ((order,) numpy.ndarray) – Array holding the contributions of each mode to the input spectrum