mPOD

modulo_vki.modulo.ModuloVKI.mPOD(self, Nf, Ex, F_V, Keep, SAT, boundaries, MODE, dt, SAVE=False, K_in=None, Sigma_type='accurate', conv_type: str = '1d', verbose=True)

Multi-Scale Proper Orthogonal Decomposition (mPOD) of a signal.

Parameters:

  • Nf (np.array) – Orders of the FIR filters used to isolate each scale. Must be of size len(F_V) + 1.

  • Ex (int) – Extension length at the boundaries to impose boundary conditions (must be at least as large as Nf).

  • F_V (np.array) – Frequency splitting vector, containing the cutoff frequencies for each scale. Units depend on the temporal step dt.

  • Keep (np.array) – Boolean array indicating scales to retain. Must be of size len(F_V) + 1.

  • SAT (int) – Maximum number of modes per scale.

  • boundaries ({'nearest', 'reflect', 'wrap', 'extrap'}) – Boundary conditions for filtering to avoid edge effects. Refer to: https://docs.scipy.org/doc/scipy/reference/tutorial/ndimage.html

  • MODE ({'reduced', 'complete', 'r', 'raw'}) – Mode option for QR factorization, used to enforce orthonormality of the mPOD basis to account for non-ideal filter responses.

  • dt (float) – Temporal step size between snapshots.

  • SAVE (bool, default=False) – Whether to save intermediate results to disk.

  • K_in (np.array, default = none) – K matrix. If none, compute it with D.

  • Sigma_type ({'accurate', 'fast'}) – If accurate, recompute the Sigmas after QR polishing. Slightly slower than the fast option in which the Sigmas are not recomputed.

  • conv_type ({'1d', '2d'}) – If 1d, compute Kf applying 1d FIR filters to the columns and then rows of the extended K. More robust against windowing effects but more expensive (useful for modes that are slow compared to the observation time). If 2d, compute Kf applying a 2d FIR filter on the extended K.

Returns:

  • Phi_M (np.array) – Spatial mPOD modes (spatial structures matrix).

  • Psi_M (np.array) – Temporal mPOD modes (temporal structures matrix).

  • Sigma_M (np.array) – Modal amplitudes.

Fast spectral mPOD

modulo_vki.modulo.ModuloVKI.fastmPOD(self, F_V, fs, Keep=None, winType='hann', taper=None, mode='fullK', GThresh=-1, ncpus=4, oversampling=10, n_iter=-1, useFortran=False)

Fast spectral variant of Multi-Scale Proper Orthogonal Decomposition (mPOD) of a signal.

Parameters:

  • F_V (list of float in ascending order, >0 and <f_Nyq) – Frequency splitting vector. Must NOT include 0 and f_Nyq.

  • fs (float > 0) – Sampling frequency of the dataset.

  • Keep (list of bool, optional) – Which frequency bands to keep. No of elements is len(F_V)+1. Default = None (initialize to keep all scales)

  • winType (str, optional) – Type of window to be used for creating tapering functions. Simple smooth windows are recommended. Default = “hann”.

  • taper (list of float, optional) – Tapering width for each scale in Hz. Default = None (no taper).

  • mode (str, optional) – Computation backend: fullK, bandK, fullSVD, or randSVD. The K-based modes use correlation matrices; the SVD-based modes operate on the spectral data matrix. Default is fullK.

  • GThresh (float >= 0, optional) – Energy ratio at which the K-based backends start using Gershgorin bounds to estimate the number of significant modes. Values below one disable the estimate. The special value -1 selects n_Modes/2.

  • ncpus (int >0, optional) – Number of CPUs available for FFT parallelization. Set to number of physical cores / number of physical cores - 1 for best performance. Default = os.cpu_count()

  • oversampling (int >0, optional) – Oversampling parameter for randomized SVD. Higher values can increase accuracy of randomized SVD, but also increase computational cost. This is the first parameter to tweak when randomized SVD does not give good results. For “randSVD” mode only, for other modes has no effect. Default = 10, as in scikit-learn implementation of randomized SVD.

  • n_iter (int >0, optional) – Power iteration parameter for randomized SVD. Higher values can increase accuracy of randomized SVD, especially when singular values decay slowly, but also increase computational cost. Change only when changing oversampling does not improve the results. Set to -1 to let the algorithm set it on-the-fly based on the number of modes and size of the processed band matrix. For “randSVD” mode only, for other modes has no effect. Default = -1 (Set value on-the fly, in the same way as in scikit-learn).

  • useFortran (bool, optional) – Whether to use Fortran implementations for assembly of correlation matrices. Can give up to 2x speedup for assembly of K (mode = ‘fullK’) and up to 2.7x speedup for assembly of K_Fsc (mode = ‘bandK’) under the assumption of FLOP-bound computation. For memory-bound computation this option has little to no effect. Default = False.

Returns:

  • phi (2D np.ndarray of float) – Spatial modes in descending signifficancy order. Column-wise (i-th column = i-th mode).

  • psi (2D np.ndarray of float) – Temporal modes in descending signifficancy order. Column-wise (i-th column = i-th mode).

  • sigTot (1D np.ndarray of float >0) – Mode amplitudes in descending signifficancy order.

Raises:

  • TypeError – When an input has an invalid type.

  • ValueError – When an input value or computation mode is invalid.

  • NotImplementedError – When memory saving or weighted inner products are requested.