modulo-vki 2.1.2__py3-none-any.whl → 2.1.4__py3-none-any.whl

modulo_vki/modulo.py

@@ -131,6 +131,9 @@ class ModuloVKI:
 
         if self.MEMORY_SAVING:
             os.makedirs(self.FOLDER_OUT, exist_ok=True)
+            
+            if data is not None: 
+                raise ValueError("The memory saving option is active, so MODULO cannot be initialized with the full snapshot matrix. Use 'ReadData' routines to process the data in chunks instead.")        
         
         # Load the data matrix
         if isinstance(data, np.ndarray):

modulo_vki/utils/others.py

@@ -53,7 +53,7 @@ def Plot_Field_TEXT_JET(File):
     ax.set_xlim([0, 35])
     ax.set_ylim(10, 29)
     ax.invert_yaxis()  # Invert Axis for plotting purpose
-    plt.show()
+    # plt.show()
     Name[len(Name) - 12:len(Name)] + ' Plotted'
     return n_s, Xg, Yg, Vxg, -Vyg, X_S, Y_S
 

{modulo_vki-2.1.2.dist-info → modulo_vki-2.1.4.dist-info}/METADATA

@@ -1,313 +1,356 @@
-Metadata-Version: 2.4
-Name: modulo_vki
-Version: 2.1.2
-Summary: MODULO (MODal mULtiscale pOd) is a software developed at the von Karman Institute to perform Multiscale Modal Analysis of numerical and experimental data.
-Home-page: https://github.com/mendezVKI/MODULO/tree/master/modulo_python_package/
-Author: ['R. Poletti', 'L. Schena', 'D. Ninni', 'M. A. Mendez']
-Author-email: mendez@vki.ac.be
-License: BSD (3-clause)
-Classifier: Development Status :: 4 - Beta
-Classifier: Natural Language :: English
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.6
-Description-Content-Type: text/x-rst
-License-File: LICENSE
-Requires-Dist: tqdm
-Requires-Dist: numpy
-Requires-Dist: scipy
-Requires-Dist: scikit-learn
-Requires-Dist: ipykernel
-Requires-Dist: ipython
-Requires-Dist: ipython-genutils
-Requires-Dist: ipywidgets
-Requires-Dist: matplotlib
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-MODULO: a python toolbox for data-driven modal decomposition
-------------------------------------------------------------
-
-.. image:: https://modulo.readthedocs.io/en/latest/_images/modulo_logo.png
-   :alt: MODULO logo
-   :width: 500px
-   :align: center
-
-
-**MODULO** is a modal decomposition package developed at the von Karman Institute for Fluid Dynamics (VKI). It offers a wide range of decomposition techniques, allowing users to choose the most appropriate method for their specific problem. MODULO can efficiently handle large datasets natively, thanks to a memory-saving feature that partitions the data and processes the decomposition in chunks (`Nini et al. (2022) <https://www.sciencedirect.com/science/article/pii/S2352711020303356>`_). Moreover, it supports non-uniform meshes through a weighted inner product formulation. Currently, MODULO heavily relies on NumPy routines and does not offer additional parallel computing capabilities beyond those naturally provided by NumPy.
-
-While the discontinued MATLAB version of MODULO is accessible in the “Old_Matlab_Implementation” branch, 
-it is no longer maintained. The latest decomposition techniques are exclusively available in the current Python version (`Poletti et al. (2024) <https://joss.theoj.org/papers/10.21105/joss.06753>`_).
-
-As a part of the MODULO project, we provide a series of lectures on data-driven modal decomposition, and its applications.
-These are available at the `MODULO YouTube channel <https://www.youtube.com/@modulompod5682>`_.
-
-.. contents:: Table of contents
-
-Modal decompositions
---------------------
-Modal decompositions aim to describe the data as a linear combination of *modes*, obtained by projecting the data 
-onto a suitable set of basis. Different decompositions employ different bases, such as prescribed Fourier basis for 
-the Discrete Fourier Transform (DFT), or data-driven basis, i.e. tailored on the dataset at hand, 
-for the Proper Orthogonal Decomposition (POD). We refer to `Mendez (2022) <https://doi.org/10.48550/arXiv.2201.03847>`_, `Mendez (2023) <https://doi.org/10.1017/9781108896214.013>`_, and `Mendez et al. (2023) <https://arxiv.org/abs/2208.07746>`_  for an introduction to the topic. 
-MODULO currently features the following decompositions: 
-
-- Discrete Fourier Transform (DFT) (`Briggs et al. (1997) <https://epubs.siam.org/doi/book/10.1137/1.9781611971514>`_)
-- Proper Orthogonal Decomposition (POD) (`Sirovich et al. (1987) <https://www.ams.org/journals/qam/1987-45-03/S0033-569X-1987-0910464-1/S0033-569X-1987-0910464-1.pdf>`_ , `Berkooz et al. (1993) <https://doi.org/10.1146/annurev.fl.25.010193.002543>`_)
-- Multi-Scale Proper Orthogonal Decomposition (mPOD) (`Mendez et al. (2019) <https://arxiv.org/abs/1804.09646>`_)
-- Dynamic Mode Decomposition (DMD) (`Schmid (2010) <https://doi.org/10.1017/S0022112010001217>`_)
-- Spectral Proper Orthogonal Decomposition (SPOD) (`Sieber et al. (2016) <https://doi.org/10.48550/arXiv.1508.04642>`_, `Towne et al. (2018) <https://doi.org/10.48550/arXiv.1708.04393>`_), 
-  note that the two are different formulations, and both are available in MODULO.
-- Kernel Proper Orthogonal Decomposition (KPOD) (`Mika et al. (1998) <https://proceedings.neurips.cc/paper_files/paper/1998/file/226d1f15ecd35f784d2a20c3ecf56d7f-Paper.pdf>`_)
-
-We remind the curious reader to the respective references for a detailed description of each decomposition, and to the
-documentation for a practical guide on how to use them in MODULO.
-
-Release Notes
--------------
-This version of MODULO includes the following updates:
-
-1. **mPOD bug fix:** the previous version of mPOD was skipping the last scale of the frequency splitting vector. Fixed in this version.
-
-2. **SPOD parallelisation:** CSD - SPOD can now be parallelized, leveraging `joblib`. The user needs just to pass the argument `n_processes` for the computation to be
-   split between different workers.
-   
-3. **Simplified decomposition interface:** the interface of the decomposition methods has been simplified to improve user experience. 
-
-4. **Enhanced POD selection:** the POD function has been redesigned, allowing users to easily choose between different POD methods.  
-   
-5. **Improved computational efficiency:** the code of the decomposition functions has been optimised, resulting in reduced computation time. mPOD now includes two additional optional arguments to enable faster filtering and to avoid recomputing the Sigmas after QR polishing. 
-	
-6. **Extended documentation:** the documentation has been significantly enriched, now including theoretical foundations for all the supported modal decomposition techniques. 
-
-	
-Documentation
--------------
-
-The documentation of MODULO is available `here <https://lorenzoschena.github.io/MODULO/intro.html>`_. It 
-contains a comprehensive guide on how to install and use the package, as well as a detailed description of the
-decompositions required inputs and outputs. A `list of YouTube videos <https://www.youtube.com/@modulompod5682>`_ 
-is also available to guide the introduce the user to modal decomposition and MODULO.
-
-Installation
--------------
-
-Installation via pip
-^^^^^^^^^^^^^^^^^^^^
-
-You can access the latest update of the modulo python package on PyPI using the command line:
-
-.. code-block:: bash
-
-    $ pip install modulo_vki
-
-Installation from source 
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Alternatively, you can clone the repository and install the package locally:
-
-.. code-block:: bash
-
-    $ git clone https://github.com/mendezVKI/MODULO.git
-
-    $ cd MODULO
-
-    $ python setup.py install
-
-or, if you have pip installed in your environment, 
-
-.. code-block:: bash
-
-    $ pip install .
-
-
-Example 
--------------
-
-Example 1: POD decomposition
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following example illustrates how to decompose a data set (D) using the POD decomposition.
-
-.. code-block:: python 
-
-    from modulo_vki import ModuloVKI 
-    import numpy as np
-
-    # Create a random dataset
-    D = np.random.rand(100, 1000)
-
-    # Initialize the ModuloVKI object
-    m = ModuloVKI(D) 
-
-    # Compute the POD decomposition
-    phi_POD, Sigma_POD, psi_POD = m.POD()
-
-which returns the spatial basis ($\phi$), the temporal basis ($\psi$), and the modal 
-amplitudes ($\Sigma$) of the POD decomposition. 
-
-Example 2: Memory Saving option 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For the Memory Saving option, MODULO decomposes $D$ in `N_partitions`, defined 
-by the user (refer to `examples/ex_04_Memory_Saving.py`).
-
-.. code-block:: python
-
-    from modulo_vki import ModuloVKI 
-    import numpy as np
-
-    # Create a random dataset
-    D = np.random.rand(100, 1000)
- 
-    # Initialize the ModuloVKI object
-    m = ModuloVKI(D, N_PARTITIONS=10) 
-
-    # Compute the POD decomposition
-    phi_POD, Sigma_POD, psi_POD = m.POD()
-
-Example 3: non-uniform grid
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you are dealing with non-uniform grid (e.g. output of a Computational Fluid Dynamic (CFD) simulation),
-you can use the weighted inner product formulation (refer to `examples/ex_05_nonUniform_POD.py`).
-
-.. code-block:: python 
-
-    from modulo_vki import ModuloVKI 
-    import numpy as np
-
-    # Create a random dataset
-    D = np.random.rand(100, 1000)
-
-    # Get the area of the grid
-    a_dataSet = gridData.compute_cell_sizes()
-    area = a_dataSet['Area']
-
-    # Compute weights
-    areaTot = np.sum(area)
-    weights = area/areaTot # sum should be equal to 1
-
-    # Initialize the ModuloVKI object
-    m = ModuloVKI(D, weights=weights) 
-
-    # Compute the POD decomposition
-    phi_POD, Sigma_POD, psi_POD = m.POD()
-	
-Community guidelines
----------------------
-
-Contributing to MODULO
-^^^^^^^^^^^^^^^^^^^^^^^
-We welcome contributions to MODULO. 
-
-It is recommended to perform a shallow clone of the repository to avoid downloading the entire history of the project:
-
-.. code-block:: bash
-
-    $ git clone --depth 1 https://github.com/mendezVKI/MODULO.git
-
-This will download only the latest version of the repository, which is sufficient for contributing to the project, and will save 
-you time and disk space.
-
-To create a new feature, please submit a pull request, specifying the proposed changes and 
-providing an example of how to use the new feature (that will be included in the `examples/` folder).
-
-The pull request will be reviewed by the MODULO team before being merged into the main branch, and your contribution duly acknowledged.
-
-Report bugs 
-^^^^^^^^^^^^
-If you find a bug, or you encounter unexpected behaviour, please open an issue on the MODULO GitHub repository.
-
-Ask for help
-^^^^^^^^^^^^
-If you have troubles using MODULO, or you need help with a specific decomposition, please open an issue on the MODULO GitHub repository.
-
-Citation
---------
-
-If you use MODULO in your research, please cite it as follows:
-
-Poletti, R., Schena, L., Ninni, D., Mendez, M. A. (2024).  
-*MODULO: A Python toolbox for data-driven modal decomposition*.  
-Journal of Open Source Software, 9(102), 6753. https://doi.org/10.21105/joss.06753
-
-.. code-block:: text
-
-    @article{Poletti2024, 
-      doi = {10.21105/joss.06753}, 
-      url = {https://doi.org/10.21105/joss.06753}, 
-      year = {2024},
-      publisher = {The Open Journal}, 
-      volume = {9}, 
-      number = {102}, 
-      pages = {6753},
-      author = {R. Poletti and L. Schena and D. Ninni and M. A. Mendez}, 
-      title = {MODULO: A Python toolbox for data-driven modal decomposition},
-      journal = {Journal of Open Source Software}
-    }
-	
-and 
-
-Ninni, D., & Mendez, M. A. (2020).  
-*MODULO: A software for Multiscale Proper Orthogonal Decomposition of data*.  
-SoftwareX, 12, 100622. https://doi.org/10.1016/j.softx.2020.100622
-
-.. code-block:: text
-
-    @article{ninni2020modulo,
-        title={MODULO: A software for Multiscale Proper Orthogonal Decomposition of data},
-        author={Ninni, Davide and Mendez, Miguel A},
-        journal={SoftwareX},
-        volume={12},
-        pages={100622},
-        year={2020},
-        publisher={Elsevier}
-    }
-
-
-References
-----------
-
-- Mendez, Miguel Alfonso. "Statistical Treatment, Fourier and Modal Decomposition." arXiv preprint arXiv:2201.03847 (2022).
-- Mendez, M. A. (2023) "Generalized and Multiscale Modal Analysis". In : Mendez M.A., Ianiro, A., Noack, B.R., Brunton, S. L. (Eds), 
-  "Data-Driven Fluid Mechanics: Combining First Principles and Machine Learning". Cambridge University Press, 2023:153-181. 
-  https://doi.org/10.1017/9781108896214.013. The pre-print is available at https://arxiv.org/abs/2208.12630.
-- Ninni, Davide, and Miguel A. Mendez. "MODULO: A software for Multiscale Proper Orthogonal Decomposition of data." SoftwareX 12 (2020): 100622.
-- Poletti, Romain, Schena, Lorenzo, Ninni, David, and Mendez, Miguel A. "Modulo: A python toolbox for data-driven modal decomposition". Journal of Open Source Software (2024), 9(102), 6753.
-- Mendez, Miguel A. "Linear and nonlinear dimensionality reduction from fluid mechanics to machine learning." Measurement Science and Technology 34.4 (2023): 042001. 
-- Briggs, William L., and Van Emden Henson. The DFT: an owner's manual for the discrete Fourier transform. Society for Industrial and Applied Mathematics, 1995.
-- Berkooz, Gal, Philip Holmes, and John L. Lumley. "The proper orthogonal decomposition in the analysis of turbulent flows." Annual review of fluid mechanics 25.1 (1993): 539-575.
-- Sirovich, Lawrence. "Turbulence and the dynamics of coherent structures. III. Dynamics and scaling." Quarterly of Applied mathematics 45.3 (1987): 583-590.
-- Mendez, M. A., M. Balabane, and J-M. Buchlin. "Multi-scale proper orthogonal decomposition of complex fluid flows." Journal of Fluid Mechanics 870 (2019): 988-1036.
-- Schmid, Peter J. "Dynamic mode decomposition of numerical and experimental data." Journal of fluid mechanics 656 (2010): 5-28.
-- Sieber, Moritz, C. Oliver Paschereit, and Kilian Oberleithner. "Spectral proper orthogonal decomposition." Journal of Fluid Mechanics 792 (2016): 798-828.
-- Towne, Aaron, Oliver T. Schmidt, and Tim Colonius. "Spectral proper orthogonal decomposition and its relationship to dynamic mode decomposition and resolvent analysis." Journal of Fluid Mechanics 847 (2018): 821-867.
-- Mika, Sebastian, et al. "Kernel PCA and de-noising in feature spaces." Advances in neural information processing systems 11 (1998).
-
-Related projects
-----------------
-MODULO encapsulates a wide range of decomposition techniques, but not all of them. We refer to the project below for an additional set of decomposition techniques:
-
-- ModRed, https://github.com/belson17/modred
-
-There are also decomposition-specific projects, some of which are listed below:
-
-- Rogowski, Marcin, Brandon CY Yeung, Oliver T. Schmidt, Romit Maulik, Lisandro Dalcin, Matteo Parsani, and Gianmarco Mengaldo. "Unlocking massively parallel spectral proper orthogonal decompositions in the PySPOD package." Computer Physics Communications 302 (2024): 109246.
-- Lario, A., Maulik, R., Schmidt, O.T., Rozza, G. and Mengaldo, G., 2022. Neural-network learning of SPOD latent dynamics. Journal of Computational Physics, 468, p.111475.
-- Ichinaga, Andreuzzi, Demo, Tezzele, Lapo, Rozza, Brunton, Kutz. PyDMD: A Python package for robust dynamic mode decomposition. arXiv preprint, 2024.
-- Rogowski, Marcin, et al. "Unlocking massively parallel spectral proper orthogonal decompositions in the PySPOD package." Computer Physics Communications 302 (2024): 109246.
-
-
-
-
-
-
+Metadata-Version: 2.4
+Name: modulo_vki
+Version: 2.1.4
+Summary: MODULO (MODal mULtiscale pOd) is a software developed at the von Karman Institute to perform Multiscale Modal Analysis of numerical and experimental data.
+Home-page: https://github.com/mendezVKI/MODULO/tree/master/modulo_python_package/
+Author: ['R. Poletti', 'L. Schena', 'D. Ninni', 'M. A. Mendez']
+Author-email: mendez@vki.ac.be
+License: BSD (3-clause)
+Classifier: Development Status :: 4 - Beta
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.6
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: tqdm
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: ipykernel
+Requires-Dist: ipython
+Requires-Dist: ipython-genutils
+Requires-Dist: ipywidgets
+Requires-Dist: matplotlib
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+MODULO: a python toolbox for data-driven modal decomposition
+-------------------------------------------------------------
+
+.. image:: https://modulo.readthedocs.io/en/latest/_images/modulo_logo.png
+   :alt: MODULO logo
+   :width: 500px
+   :align: center
+
+
+**MODULO** is a modal decomposition package developed at the von Karman Institute for Fluid Dynamics (VKI). It offers a wide range of decomposition techniques, allowing users to choose the most appropriate method for their specific problem. MODULO can efficiently handle large datasets natively, thanks to a memory-saving feature that partitions the data and processes the decomposition in chunks (`Nini et al. (2022) <https://www.sciencedirect.com/science/article/pii/S2352711020303356>`_). Moreover, it supports non-uniform meshes through a weighted inner product formulation. Currently, MODULO heavily relies on NumPy routines and does not offer additional parallel computing capabilities beyond those naturally provided by NumPy.
+
+While the discontinued MATLAB version of MODULO is accessible in the “Old_Matlab_Implementation” branch, 
+it is no longer maintained. The latest decomposition techniques are exclusively available in the current Python version (`Poletti et al. (2024) <https://joss.theoj.org/papers/10.21105/joss.06753>`_).
+
+As a part of the MODULO project, we provide a series of lectures on data-driven modal decomposition, and its applications.
+These are available at the `MODULO YouTube channel <https://www.youtube.com/@modulompod5682>`_.
+
+.. contents:: Table of contents
+
+Modal decompositions
+--------------------
+Modal decompositions aim to describe the data as a linear combination of *modes*, obtained by projecting the data 
+onto a suitable set of basis. Different decompositions employ different bases, such as prescribed Fourier basis for 
+the Discrete Fourier Transform (DFT), or data-driven basis, i.e. tailored on the dataset at hand, 
+for the Proper Orthogonal Decomposition (POD). We refer to `Mendez (2022) <https://doi.org/10.48550/arXiv.2201.03847>`_, `Mendez (2023) <https://doi.org/10.1017/9781108896214.013>`_, and `Mendez et al. (2023) <https://arxiv.org/abs/2208.07746>`_  for an introduction to the topic. 
+MODULO currently features the following decompositions: 
+
+- Discrete Fourier Transform (DFT) (`Briggs et al. (1997) <https://epubs.siam.org/doi/book/10.1137/1.9781611971514>`_)
+- Proper Orthogonal Decomposition (POD) (`Sirovich et al. (1987) <https://www.ams.org/journals/qam/1987-45-03/S0033-569X-1987-0910464-1/S0033-569X-1987-0910464-1.pdf>`_ , `Berkooz et al. (1993) <https://doi.org/10.1146/annurev.fl.25.010193.002543>`_)
+- Multi-Scale Proper Orthogonal Decomposition (mPOD) (`Mendez et al. (2019) <https://arxiv.org/abs/1804.09646>`_)
+- Dynamic Mode Decomposition (DMD) (`Schmid (2010) <https://doi.org/10.1017/S0022112010001217>`_)
+- Spectral Proper Orthogonal Decomposition (SPOD) (`Sieber et al. (2016) <https://doi.org/10.48550/arXiv.1508.04642>`_, `Towne et al. (2018) <https://doi.org/10.48550/arXiv.1708.04393>`_), 
+  note that the two are different formulations, and both are available in MODULO.
+- Kernel Proper Orthogonal Decomposition (KPOD) (`Mika et al. (1998) <https://proceedings.neurips.cc/paper_files/paper/1998/file/226d1f15ecd35f784d2a20c3ecf56d7f-Paper.pdf>`_)
+
+We remind the curious reader to the respective references for a detailed description of each decomposition, and to the
+documentation for a practical guide on how to use them in MODULO.
+
+Release Notes
+-------------
+This version of MODULO includes the following updates:
+
+1. **mPOD bug fix:** the previous version of mPOD was skipping the last scale of the frequency splitting vector. Fixed in this version.
+
+2. **SPOD parallelisation:** CSD - SPOD can now be parallelized, leveraging `joblib`. The user needs just to pass the argument `n_processes` for the computation to be
+   split between different workers.
+   
+3. **Simplified decomposition interface:** the interface of the decomposition methods has been simplified to improve user experience. 
+
+4. **Enhanced POD selection:** the POD function has been redesigned, allowing users to easily choose between different POD methods.  
+   
+5. **Improved computational efficiency:** the code of the decomposition functions has been optimised, resulting in reduced computation time. mPOD now includes two additional optional arguments to enable faster filtering and to avoid recomputing the Sigmas after QR polishing. 
+	
+6. **Extended documentation:** the documentation has been significantly enriched, now including theoretical foundations for all the supported modal decomposition techniques. 
+
+	
+Documentation
+-------------
+
+The documentation of MODULO is available `here <https://lorenzoschena.github.io/MODULO/intro.html>`_. It 
+contains a comprehensive guide on how to install and use the package, as well as a detailed description of the
+decompositions required inputs and outputs. A `list of YouTube videos <https://www.youtube.com/@modulompod5682>`_ 
+is also available to guide the introduce the user to modal decomposition and MODULO.
+
+Installation
+-------------
+
+Installation via pip
+^^^^^^^^^^^^^^^^^^^^
+
+You can access the latest update of the modulo python package on PyPI using the command line:
+
+.. code-block:: bash
+
+    $ pip install modulo_vki
+
+Installation from source 
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Alternatively, you can clone the repository and install the package locally:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/mendezVKI/MODULO.git
+
+    $ cd MODULO
+
+    $ python setup.py install
+
+or, if you have pip installed in your environment, 
+
+.. code-block:: bash
+
+    $ pip install .
+
+
+Example 
+-------------
+
+Example 1: POD decomposition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following example illustrates how to decompose a data set (D) using the POD decomposition.
+
+.. code-block:: python 
+
+    from modulo_vki import ModuloVKI 
+    import numpy as np
+
+    # Create a random dataset
+    D = np.random.rand(100, 1000)
+
+    # Initialize the ModuloVKI object
+    m = ModuloVKI(D) 
+
+    # Compute the POD decomposition
+    phi_POD, Sigma_POD, psi_POD = m.POD()
+
+which returns the spatial basis ($\phi$), the temporal basis ($\psi$), and the modal 
+amplitudes ($\Sigma$) of the POD decomposition. 
+
+Example 2: Memory Saving option 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For the Memory Saving option, MODULO decomposes $D$ in `N_partitions`, defined 
+by the user (refer to `examples/ex_04_Memory_Saving.py`).
+
+.. code-block:: python
+
+    import os
+    import numpy as np
+    from modulo_vki import ModuloVKI
+    from modulo_vki.utils.read_db import ReadData
+
+    # --- 1. User-defined settings ---
+    # Define the path to your data and the file naming convention.
+    FOLDER = 'path/to/your/snapshot_data'
+    FILE_ROOT_NAME = 'Res'  # The base name, e.g., 'Res' for 'Res00001.dat'
+    n_t = 100               # The total number of snapshots (time steps) to process.
+
+    # --- 2. Data format parameters ---
+    # Specify how to read your text-based snapshot files.
+    H = 1  # H: Number of header lines to skip
+    F = 0  # F: Number of footer lines to skip
+    C = 0  # C: Number of initial columns to skip
+
+    # --- 3. Determine data dimensions from a sample file ---
+    # To understand the structure, we load the first snapshot.
+    first_snapshot_file = os.path.join(FOLDER, f"{FILE_ROOT_NAME}00001.dat")
+    Dat = np.genfromtxt(first_snapshot_file, skip_header=H, skip_footer=F)
+
+    # N: Number of components per point (e.g., 2 for 2D velocity u,v)
+    N = Dat.shape[1]
+    # nxny: Number of spatial points in the mesh
+    nxny = Dat.shape[0]
+    # N_T: Total number of snapshots (aliased from n_t for clarity)
+    N_T = n_t
+
+    # --- 4. Process the dataset into partitions on disk ---
+    # The ReadData utility reads all snapshots and chunks the snapshot matrix.
+
+    D = ReadData._data_processing(
+        D=None,                      # We start with no data in memory
+        FOLDER_IN=FOLDER,
+        filename=f'{FILE_ROOT_NAME}%05d', # File pattern for snapshot files
+        N=N,                         # Number of components per point
+        N_S=N * nxny,                # Total size of a single snapshot vector
+        N_T=N_T,                     # Total number of snapshots
+        h=H, f=F, c=C,               # Header, footer, and column skip parameters
+        N_PARTITIONS=10,             # The dataset will be split into 10 chunks
+        MR=False,                    # Mean-removal flag
+        FOLDER_OUT=os.path.join('.', 'MODULO_tmp') # Where to save temp files
+    )
+
+    # --- 5. Initialize ModuloVKI and compute the POD ---
+    # Initialize the object, passing the number of partitions. D must be set to None 
+    # MODULO will look for the partitions in FOLDER_OUT/MODULO_tmp
+    m = ModuloVKI(None, N_PARTITIONS=10, FOLDER_OUT=FOLDER_OUT)
+
+    # The POD method will now automatically read the data from the partitioned files.
+    phi_POD, Sigma_POD, psi_POD = m.POD()
+
+    print("POD computation complete.")
+
+Example 3: non-uniform grid
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are dealing with non-uniform grid (e.g. output of a Computational Fluid Dynamic (CFD) simulation),
+you can use the weighted inner product formulation (refer to `examples/ex_05_nonUniform_POD.py`).
+
+.. code-block:: python 
+
+    from modulo_vki import ModuloVKI 
+    import numpy as np
+
+    # Create a random dataset
+    D = np.random.rand(100, 1000)
+
+    # Get the area of the grid
+    a_dataSet = gridData.compute_cell_sizes()
+    area = a_dataSet['Area']
+
+    # Compute weights
+    areaTot = np.sum(area)
+    weights = area/areaTot # sum should be equal to 1
+
+    # Initialize the ModuloVKI object
+    m = ModuloVKI(D, weights=weights) 
+
+    # Compute the POD decomposition
+    phi_POD, Sigma_POD, psi_POD = m.POD()
+	
+Community guidelines
+---------------------
+
+Contributing to MODULO
+^^^^^^^^^^^^^^^^^^^^^^^
+We welcome contributions to MODULO. 
+
+It is recommended to perform a shallow clone of the repository to avoid downloading the entire history of the project:
+
+.. code-block:: bash
+
+    $ git clone --depth 1 https://github.com/mendezVKI/MODULO.git
+
+This will download only the latest version of the repository, which is sufficient for contributing to the project, and will save 
+you time and disk space.
+
+To create a new feature, please submit a pull request, specifying the proposed changes and 
+providing an example of how to use the new feature (that will be included in the `examples/` folder).
+
+The pull request will be reviewed by the MODULO team before being merged into the main branch, and your contribution duly acknowledged.
+
+Report bugs 
+^^^^^^^^^^^^
+If you find a bug, or you encounter unexpected behaviour, please open an issue on the MODULO GitHub repository.
+
+Ask for help
+^^^^^^^^^^^^
+If you have troubles using MODULO, or you need help with a specific decomposition, please open an issue on the MODULO GitHub repository.
+
+Citation
+--------
+
+If you use MODULO in your research, please cite it as follows:
+
+Poletti, R., Schena, L., Ninni, D., Mendez, M. A. (2024).  
+*MODULO: A Python toolbox for data-driven modal decomposition*.  
+Journal of Open Source Software, 9(102), 6753. https://doi.org/10.21105/joss.06753
+
+.. code-block:: text
+
+    @article{Poletti2024, 
+      doi = {10.21105/joss.06753}, 
+      url = {https://doi.org/10.21105/joss.06753}, 
+      year = {2024},
+      publisher = {The Open Journal}, 
+      volume = {9}, 
+      number = {102}, 
+      pages = {6753},
+      author = {R. Poletti and L. Schena and D. Ninni and M. A. Mendez}, 
+      title = {MODULO: A Python toolbox for data-driven modal decomposition},
+      journal = {Journal of Open Source Software}
+    }
+	
+and 
+
+Ninni, D., & Mendez, M. A. (2020).  
+*MODULO: A software for Multiscale Proper Orthogonal Decomposition of data*.  
+SoftwareX, 12, 100622. https://doi.org/10.1016/j.softx.2020.100622
+
+.. code-block:: text
+
+    @article{ninni2020modulo,
+        title={MODULO: A software for Multiscale Proper Orthogonal Decomposition of data},
+        author={Ninni, Davide and Mendez, Miguel A},
+        journal={SoftwareX},
+        volume={12},
+        pages={100622},
+        year={2020},
+        publisher={Elsevier}
+    }
+
+
+References
+----------
+
+- Mendez, Miguel Alfonso. "Statistical Treatment, Fourier and Modal Decomposition." arXiv preprint arXiv:2201.03847 (2022).
+- Mendez, M. A. (2023) "Generalized and Multiscale Modal Analysis". In : Mendez M.A., Ianiro, A., Noack, B.R., Brunton, S. L. (Eds), 
+  "Data-Driven Fluid Mechanics: Combining First Principles and Machine Learning". Cambridge University Press, 2023:153-181. 
+  https://doi.org/10.1017/9781108896214.013. The pre-print is available at https://arxiv.org/abs/2208.12630.
+- Ninni, Davide, and Miguel A. Mendez. "MODULO: A software for Multiscale Proper Orthogonal Decomposition of data." SoftwareX 12 (2020): 100622.
+- Poletti, Romain, Schena, Lorenzo, Ninni, David, and Mendez, Miguel A. "Modulo: A python toolbox for data-driven modal decomposition". Journal of Open Source Software (2024), 9(102), 6753.
+- Mendez, Miguel A. "Linear and nonlinear dimensionality reduction from fluid mechanics to machine learning." Measurement Science and Technology 34.4 (2023): 042001. 
+- Briggs, William L., and Van Emden Henson. The DFT: an owner's manual for the discrete Fourier transform. Society for Industrial and Applied Mathematics, 1995.
+- Berkooz, Gal, Philip Holmes, and John L. Lumley. "The proper orthogonal decomposition in the analysis of turbulent flows." Annual review of fluid mechanics 25.1 (1993): 539-575.
+- Sirovich, Lawrence. "Turbulence and the dynamics of coherent structures. III. Dynamics and scaling." Quarterly of Applied mathematics 45.3 (1987): 583-590.
+- Mendez, M. A., M. Balabane, and J-M. Buchlin. "Multi-scale proper orthogonal decomposition of complex fluid flows." Journal of Fluid Mechanics 870 (2019): 988-1036.
+- Schmid, Peter J. "Dynamic mode decomposition of numerical and experimental data." Journal of fluid mechanics 656 (2010): 5-28.
+- Sieber, Moritz, C. Oliver Paschereit, and Kilian Oberleithner. "Spectral proper orthogonal decomposition." Journal of Fluid Mechanics 792 (2016): 798-828.
+- Towne, Aaron, Oliver T. Schmidt, and Tim Colonius. "Spectral proper orthogonal decomposition and its relationship to dynamic mode decomposition and resolvent analysis." Journal of Fluid Mechanics 847 (2018): 821-867.
+- Mika, Sebastian, et al. "Kernel PCA and de-noising in feature spaces." Advances in neural information processing systems 11 (1998).
+
+Related projects
+----------------
+MODULO encapsulates a wide range of decomposition techniques, but not all of them. We refer to the project below for an additional set of decomposition techniques:
+
+- ModRed, https://github.com/belson17/modred
+
+There are also decomposition-specific projects, some of which are listed below:
+
+- Rogowski, Marcin, Brandon CY Yeung, Oliver T. Schmidt, Romit Maulik, Lisandro Dalcin, Matteo Parsani, and Gianmarco Mengaldo. "Unlocking massively parallel spectral proper orthogonal decompositions in the PySPOD package." Computer Physics Communications 302 (2024): 109246.
+- Lario, A., Maulik, R., Schmidt, O.T., Rozza, G. and Mengaldo, G., 2022. Neural-network learning of SPOD latent dynamics. Journal of Computational Physics, 468, p.111475.
+- Ichinaga, Andreuzzi, Demo, Tezzele, Lapo, Rozza, Brunton, Kutz. PyDMD: A Python package for robust dynamic mode decomposition. arXiv preprint, 2024.
+- Rogowski, Marcin, et al. "Unlocking massively parallel spectral proper orthogonal decompositions in the PySPOD package." Computer Physics Communications 302 (2024): 109246.
+
+
+
+
+
+

{modulo_vki-2.1.2.dist-info → modulo_vki-2.1.4.dist-info}/RECORD

@@ -1,5 +1,5 @@
 modulo_vki/__init__.py,sha256=AOjmeFjHj69m45iZzfTHM6-SLUelgKdGeu3VdSg9hIo,39
-modulo_vki/modulo.py,sha256=OYMLteELmAHyhfByCoy2Vqg4h7bUMsgbmIDF7jUXf3A,38261
+modulo_vki/modulo.py,sha256=bpevQHd6fGwd1fIn3VSEHKgBxc9oa1Q8Fpr_qzVeqA0,38517
 modulo_vki/modulo_old.py,sha256=3r_BBYQfbmZWGDyPukyJTVYVVcAVuEE0CmREEJkzsxU,59413
 modulo_vki/core/__init__.py,sha256=y9mIqtmSg3o8TXMqFxoiMCoMSle6mK0LBrvNJCVM1Zg,226
 modulo_vki/core/_dft.py,sha256=W98vC4HR1fivZjYRQXrFKV7RBa-O3RSRwq-nCKoxqjQ,4374
@@ -17,10 +17,13 @@ modulo_vki/core/utils.py,sha256=Ac9Im9knlbZRByP6Qgv-LCDt5zEC8PbyidqXzVdeYtQ,1788
 modulo_vki/utils/__init__.py,sha256=F5yy5R19dONK9oaBEpKzylorVJNcjT2kiJ5Og-ZX1ek,94
 modulo_vki/utils/_plots.py,sha256=m43t08cVq-TY0BW0YPqT71hN-54hBphIYKZEn8Kw16E,1453
 modulo_vki/utils/_utils.py,sha256=WFD7nwjSzVHpevVwTEvMdjAmcbeqwoXT9M48tIIniJw,14355
-modulo_vki/utils/others.py,sha256=26ES5EmsLhwkvcXTwNhDMkblGrxoWepX5c9TXeLTRWg,17336
+modulo_vki/utils/others.py,sha256=9yZzD0_rZIOWYjV2Hbi74N5oXEYct7o5h9ZjNkmxHPw,17338
 modulo_vki/utils/read_db.py,sha256=lJFauxJxS0_mYoxrbn-43UqZjOkr-qb9f6RTUq4IxZU,15149
-modulo_vki-2.1.2.dist-info/licenses/LICENSE,sha256=5TivriXFErrYrJgBq3M72kHNHqtSiCft3xESM1zHc0k,1091
-modulo_vki-2.1.2.dist-info/METADATA,sha256=dCTKzUK0d91uWzg-CoySY5towOn3-ZhExDPXmLF7w-g,14816
-modulo_vki-2.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-modulo_vki-2.1.2.dist-info/top_level.txt,sha256=4PA4AmafKU6M7us7gvt_Q976Khx3qjNUEThRRM5zxeA,11
-modulo_vki-2.1.2.dist-info/RECORD,,
+modulo_vki-2.1.4.dist-info/licenses/LICENSE,sha256=5TivriXFErrYrJgBq3M72kHNHqtSiCft3xESM1zHc0k,1091
+modulo_vki_2/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modulo_vki_2/modulo.py,sha256=JhQFHsoyQ3Bp0FZ80M0WOq9hYMVkMV1lMoEnxwf2Vng,7861
+modulo_vki_2/utils.py,sha256=9Zwikg7x7MtvIK1Om1JKKnCH1OQd0nf3m76APjOIyas,858
+modulo_vki-2.1.4.dist-info/METADATA,sha256=5S4EkRJbdLMriyOTNqb3jjcxPj8SEaglfHGbmXWYNn8,16733
+modulo_vki-2.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+modulo_vki-2.1.4.dist-info/top_level.txt,sha256=xP1gbt8FGvhIM5-zQagZXO7ut-yjUI4cXuM2GeypNuw,24
+modulo_vki-2.1.4.dist-info/RECORD,,

modulo_vki-2.1.4.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+modulo_vki
+modulo_vki_2

modulo_vki_2/modulo.py

@@ -0,0 +1,187 @@
+import numpy as np 
+import os 
+
+
+
+class ModuloVKI:
+    """
+    MODULO (MODal mULtiscale pOd) is a software developed at the von Karman Institute
+    to perform Multiscale Modal Analysis using Multiscale Proper Orthogonal Decomposition (mPOD)
+    on numerical and experimental data.
+
+    References
+    ----------
+    - Theoretical foundation:
+      https://arxiv.org/abs/1804.09646
+
+    - MODULO framework presentation:
+      https://arxiv.org/pdf/2004.12123.pdf
+
+    - Hands-on tutorial videos:
+      https://youtube.com/playlist?list=PLEJZLD0-4PeKW6Ze984q08bNz28GTntkR
+
+    Notes
+    -----
+    MODULO operations assume the dataset is uniformly spaced in both space
+    (Cartesian grid) and time. For non-cartesian grids, the user must 
+    provide a weights vector `[w_1, w_2, ..., w_Ns]` where `w_i = area_cell_i / area_grid`.
+    """
+
+    def __init__(self,
+                 data: np.ndarray,
+                 N_PARTITIONS: int = 1,
+                 FOLDER_OUT: str = './',
+                 SAVE_K: bool = False,
+                 N_T: int = 100,
+                 N_S: int = 200,
+                 n_Modes: int = 10,
+                 dtype: str = 'float32',
+                 eig_solver: str = 'eigh',
+                 svd_solver: str = 'svd_sklearn_truncated',
+                 weights: np.ndarray = np.array([])):
+        """
+        Initialize the MODULO analysis.
+
+        Parameters
+        ----------
+        data : np.ndarray
+            Data matrix of shape (N_S, N_T) to factorize. If not yet formatted, use the `ReadData`
+            method provided by MODULO. When memory saving mode (N_PARTITIONS > 1) is active,
+            set this parameter to None and use prepared partitions instead.
+
+        N_PARTITIONS : int, default=1
+            Number of partitions used for memory-saving computation. If set greater than 1,
+            data must be partitioned in advance and `data` set to None.
+
+        FOLDER_OUT : str, default='./'
+            Directory path to store output (Phi, Sigma, Psi matrices) and intermediate
+            calculation files (e.g., partitions, correlation matrix).
+
+        SAVE_K : bool, default=False
+            Whether to store the correlation matrix K to disk in
+            `FOLDER_OUT/correlation_matrix`.
+
+        N_T : int, default=100
+            Number of temporal snapshots. Mandatory when using partitions (N_PARTITIONS > 1).
+
+        N_S : int, default=200
+            Number of spatial grid points. Mandatory when using partitions (N_PARTITIONS > 1).
+
+        n_Modes : int, default=10
+            Number of modes to compute.
+
+        dtype : str, default='float32'
+            Data type for casting input data.
+
+        eig_solver : str, default='eigh'
+            Solver for eigenvalue decomposition.
+
+        svd_solver : str, default='svd_sklearn_truncated'
+            Solver for Singular Value Decomposition (SVD).
+
+        weights : np.ndarray, default=np.array([])
+            Weights vector `[w_1, w_2, ..., w_Ns]` to account for non-uniform spatial grids.
+            Defined as `w_i = area_cell_i / area_grid`. Leave empty for uniform grids.
+        """
+
+        print("MODULO (MODal mULtiscale pOd) is a software developed at the von Karman Institute to perform "
+              "data driven modal decomposition of numerical and experimental data. \n")
+
+        if not isinstance(data, np.ndarray) and N_PARTITIONS == 1:
+            raise TypeError(
+                "Please check that your database is in an numpy array format. If D=None, then you must have memory saving (N_PARTITIONS>1)")
+
+        if N_PARTITIONS > 1:
+            self.MEMORY_SAVING = True
+        else:
+            self.MEMORY_SAVING = False
+
+            # Assign the number of modes
+        self.n_Modes = n_Modes
+        # If particular needs, override choice for svd and eigen solve
+        self.svd_solver = svd_solver.lower()
+        self.eig_solver = eig_solver.lower()
+        possible_svds = ['svd_numpy', 'svd_scipy_sparse', 'svd_sklearn_randomized', 'svd_sklearn_truncated']
+        possible_eigs = ['svd_sklearn_randomized', 'eigsh', 'eigh']
+
+        if self.svd_solver not in possible_svds:
+            raise NotImplementedError("The requested SVD solver is not implemented. Please pick one of the following:"
+                                      "which belongs to: \n {}".format(possible_svds))
+
+        if self.eig_solver not in possible_eigs:
+            raise NotImplementedError("The requested EIG solver is not implemented. Please pick one of the following: "
+                                      " \n {}".format(possible_eigs))
+
+        # if N_PARTITIONS >= self.N_T:
+        #     raise AttributeError("The number of requested partitions is greater of the total columns (N_T). Please,"
+        #                          "try again.")
+
+        self.N_PARTITIONS = N_PARTITIONS
+        self.FOLDER_OUT = FOLDER_OUT
+        self.SAVE_K = SAVE_K
+
+        if self.MEMORY_SAVING:
+            os.makedirs(self.FOLDER_OUT, exist_ok=True)
+        
+        # Load the data matrix
+        if isinstance(data, np.ndarray):
+            # Number of points in time and space
+            self.N_T = data.shape[1]
+            self.N_S = data.shape[0]
+            # Check the data type
+            self.D = data.astype(dtype)
+        else:
+            self.D = None  # D is never saved when N_partitions >1
+            self.N_S = N_S  # so N_S and N_t must be given as parameters of modulo
+            self.N_T = N_T
+        
+        '''If the grid is not cartesian, ensure inner product is properly defined using weights.'''
+        
+        if weights.size == 0:
+                print('Modulo assumes you have a uniform grid. If not, please provide weights as parameters.')
+        else: 
+                if len(weights) == self.N_S:
+                        print("The weights you have input have the size of the columns of D \n"
+                                  "MODULO has considered that you have already duplicated the dimensions of the weights "
+                                  "to match the dimensions of the D columns \n")
+                        self.weights = weights
+                elif len(weights) == 2 * self.N_S:
+                        print("Assuming 2D domain. Automatically duplicating the weights to match the dimension of the D columns \n")
+                        self.weights = np.concatenate((weights, weights))
+                else:
+                        raise AttributeError("Make sure the size of the weight array is twice smaller than the size of D")
+                
+                if isinstance(data, np.ndarray):
+                        # Apply the weights only if D exist.
+                        # If not (i.e. N_partitions >1), weights are applied in _k_matrix.py when loading partitions of D
+                        self.Dstar = np.transpose(np.transpose(self.D) * np.sqrt(self.weights))
+                else:
+                        self.Dstar = None
+                        
+    def compute(
+        self,
+        kind: str,
+        **engine_kwargs
+        ) -> tuple:
+        """
+        Unified entry point for all decompositions: POD, SPOD, kPOD, DMD, DFT.
+        Any engine‐specific parameters (e.g. F_S, L_B, gamma…) can be passed here
+        and will be forwarded to the chosen engine’s constructor.
+        """
+        engine_cls = self._engines.get(kind.lower())
+        if engine_cls is None:
+            raise ValueError(f"Unknown decomposition '{kind}'")
+
+        # pick the right data array
+        D_use = self.Dstar  # or self.D if you want un-weighted
+
+        engine = engine_cls(
+            D=D_use,
+            folder_out=self.FOLDER_OUT,
+            save_k=self.SAVE_K,
+            memory_saving=self.MEMORY_SAVING,
+            n_partitions=self.N_PARTITIONS,
+            **engine_kwargs
+        )
+        return engine.run()
+                        

modulo_vki_2/utils.py

@@ -0,0 +1,22 @@
+import numpy as np
+
+def apply_weights(D: np.ndarray, weights: np.ndarray) -> np.ndarray:
+    """
+    If `weights` is empty, return D unchanged.
+    If `weights` has length n_s, assume 1D grid and tile automatically.
+    If `weights` has length 2*n_s, assume 2D grid and use directly.
+    Returns D_star = D * sqrt(w) applied column-wise.
+    """
+    n_s, n_t = D.shape
+    if weights.size == 0:
+        return D
+    w = np.asarray(weights, dtype=D.dtype)
+    if w.size == n_s:
+        # 1D grid: automatically broadcast each weight to full time series
+        w_full = np.repeat(w, n_t//n_s)  # or tile as needed for time dims
+    elif w.size == 2*n_s:
+        w_full = w
+    else:
+        raise ValueError(f"weights must be length {n_s} or {2*n_s}, got {w.size}")
+    # apply weights: scale each row i by sqrt(w_full[i])
+    return (D.T * np.sqrt(w_full)).T

modulo_vki-2.1.2.dist-info/top_level.txt

@@ -1 +0,0 @@
-modulo_vki