MODULO (MODal mULtiscale pOd): Data-Driven Modal Analysis

MODULO (MODal mULtiscale pOd) is a software developed at the von Karman Institute for Fluid Dynamics to perform data-driven modal decompositions. Initially focused on the Multiscale Proper Orthogonal Decomposition (mPOD), it has recently been extended to perform also other decompositions that include POD, SPODs, DFT, DMD, mPOD.

Getting Started

Data pre-processing

Data-Driven Modal Decompositions

All modal decompositions are implemented in MODULO [1] as matrix factorization of the snapshot matrix \(D(\mathbf{x}, t) \in \mathbb{R}^{n_S \times n_t}\). Each entry of the snapshot matrix is a flattened realization of the data, regardless of the data dimensionality (2D, 3D). Thus, this decomposition reads

\[D(\mathbf{x}, t) = \mathbf{\Phi}\mathbf{\Sigma}\mathbf{\Psi}^T\]

where \(\mathbf{\Phi} \in \mathbb{R}^{n_S \times r}\) and \(\mathbf{\Psi} \in \mathbb{R}^{n_t \times r}\) are the spatial and temporal modes, respectively, and \(\mathbf{\Sigma} \in \mathbb{R}^{r \times r}\) is a diagonal matrix containing the modal energy associated with each mode.

Each mode \(r`\) is characterized by:

  • Spatial structure \(\mathbf{\phi}_r\), which encodes the pattern in space,

  • Temporal structure \(\mathbf{\psi}_r\), which describes how that pattern evolves in time,

  • Amplitude \(\sigma_r\), which quantifies the modal amplitude, e.g. energy or variance captured by the mode.

The reminder of this section overviews the salient theoretical aspects of the implement modal decompositions, and the corresponding implementation in MODULO. The following decompositions are available:

The field of applications ranges from reduced-order modeling (ROM) and flow control to filtering, and feature extraction. For a comprehensive review of modal methods in fluid dynamics, see Mendez et al. (2023) [2].

Data-Driven Modal Decompositions

Key features of MODULO

  • Multiple decomposition algorithms:

    • POD (Proper Orthogonal Decomposition) via the snapshot method or SVD

    • mPOD (Multiscale POD) for frequency‐band separation

    • SPOD (Spectral POD)

    • DFT (Discrete Fourier Transform)

    • DMD (Dynamic Mode Decomposition)

    • KPOD (Kernel POD)

  • Memory‐saving implementations (Ninni et al., (2020) [3]):

    • Partition‐based loading for very large datasets

    • On‐disk correlation matrices

API Reference

Quick Start

MODULO is published on PyPI and can be installed with pip install modulo_vki (see Installation). The user is first requested to assemble the matrix field to be decomposed, or the folder of the raw files to be imported if she wants to use the data loading routines present in the auxialliary code of MODULO. We refer the reader to Importing data and D matrix preparation for an example on the usage of these routines, and now we illustrate the case in which the matrix \(\mathbf{D}\) is already available in memory. In this case, the decomposition can be carried out as:

from modulo_vki import ModuloVKI # this is to create modulo objects

D = np.array([]) # snapshot matrix containing the data

m = ModuloVKI(data=D)

# Compute the DFT
Phi_F, Psi_F, Sorted_Sigmas = m.DFT(Fs)

This output is consistent regardless of the decomposition; MODULO will always yield the spatial structures first.

Contributing

Changelog

References & Acknowledgements