Giters

xgxg1314 / PyDMD

Python Dynamic Mode Decomposition

Home Page:https://pydmd.github.io/PyDMD/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Python Dynamic Mode Decomposition

Docs PyPI version Python versions Software License
CI Status Codacy Badge black code style
All Contributors GitHub Repo stars PyPI downloads per month JOSS DOI

Table of contents

Description

PyDMD is a Python package designed for Dynamic Mode Decomposition (DMD), a data-driven method used for analyzing and extracting spatiotemporal coherent structures from time-varying datasets. It provides a comprehensive and user-friendly interface for performing DMD analysis, making it a valuable tool for researchers, engineers, and data scientists working in various fields.

With PyDMD, users can easily decompose complex, high-dimensional datasets into a set of coherent spatial and temporal modes, capturing the underlying dynamics and extracting important features. The package implements both standard DMD algorithms and advanced variations, enabling users to choose the most suitable method for their specific needs. These extensions allow to deal with noisy data, big dataset, control variables, or to impose physical structures.

PyDMD offers a seamless integration with the scientific Python ecosystem, leveraging popular libraries such as NumPy and SciPy for efficient numerical computations and data manipulation. It also offers a variety of visualization tools, including mode reconstruction, energy spectrum analysis, and time evolution plotting. These capabilities enable users to gain insights into the dominant modes of the system, identify significant features, and understand the temporal evolution of the dynamics.

PyDMD promotes ease of use and customization, providing a well-documented API with intuitive function names and clear parameter descriptions. The package is actively maintained and updated, ensuring compatibility with the latest Python versions and incorporating user feedback to improve functionality and performance. We provide many tutorials showing the characteristics of the software. See the Examples section below and the Tutorials to have an idea of the potential of this package. Also see the diagram below for a summary of all available tools and functionalities. Currently in-progress contributions are represented by semi-transparent boxes.

Dependencies and installation

Installing via PIP

PyDMD is available on PyPI, therefore you can install the latest released version with:

> pip install pydmd

Installing from source

To install the bleeding edge version, clone this repository with:

> git clone https://github.com/PyDMD/PyDMD

and then install the package in development mode:

> pip install -e .

Dependencies

The core features of PyDMD depend on numpy and scipy. In order to use the plotting functionalities you will also need matplotlib.

Quickstart Guide

To perform DMD, simply begin by initializing a PyDMD module that implements your DMD method of choice. Models may then be fitted by calling the fit() method and passing in the necessary data. This step performs the DMD algorithm, after which users may use PyDMD plotting tools in order to visualize their results.

from pydmd import DMD
from pydmd.plotter import plot_summary

# Build an exact DMD model with 12 spatiotemporal modes.
dmd = DMD(svd_rank=12)

# Fit the DMD model.
# X = (n, m) numpy array of time-varying snapshot data.
dmd.fit(X)

# Plot a summary of the key spatiotemporal modes.
plot_summary(dmd)

PyDMD modules can also be wrapped with data preprocessors if desired. These wrappers will preprocess the data and postprocess data reconstructions automatically.

from pydmd import DMD
from pydmd.preprocessing import zero_mean_preprocessing

# Build and fit an exact DMD model with data centering.
centered_dmd = zero_mean_preprocessing(DMD(svd_rank=12))
centered_dmd.fit(X)

Users may also build highly complex DMD models with PyDMD. Below is an example of how one might build and fit a customized Optimized DMD model with bagging, eigenvalue constraints, and custom variable projection arguments.

from pydmd import BOPDMD

# Build a Bagging, Optimized DMD (BOP-DMD) model.
# For Optimized DMD (without bagging), use BOPDMD(svd_rank=12, num_trials=0).
bopdmd = BOPDMD(
    svd_rank=12,                                  # Rank of the DMD fit.
    num_trials=100,                               # Number of bagging trials to perform.
    trial_size=0.5,                               # Use 50% of the total number of snapshots per trial.
    eig_constraints={"imag", "conjugate_pairs"},  # Eigenvalues must be imaginary and conjugate pairs.
    varpro_opts_dict={"tol":0.2, "verbose":True}, # Set convergence tolerance and use verbose updates.
)

# Fit the BOP-DMD model.
# X = (n, m) numpy array of time-varying snapshot data
# t = (m,) numpy array of times of data collection
bopdmd.fit(X, t)

PyDMD modules and functions may be parameterized by a variety of inputs for added customization, so we generally recommend that new users refer to our documentation, as well as to our module-specific tutorials for more examples and information.

Also provided below is an example call to the plot_summary() function when given a DMD model fitted to mean-centered flow past a cylinder data available at dmdbook.com/DATA.zip. A rank-12 exact DMD model was used to generate this figure. Eigenvalues, modes, and dynamics are color-coded to indicate associations. Eigenvalue marker sizes also indicate spatiotemporal mode amplitudes or importance.

Plotting tool documentation can be found here.

from pydmd.plotter import plot_summary

plot_summary(
    dmd, # <-- Fitted PyDMD model. Can be DMD, BOPDMD, etc.
    figsize=(12, 7),
    index_modes=(0, 2, 4),
    snapshots_shape=(449, 199),
    order="F",
    mode_cmap="seismic",
    dynamics_color="k",
    flip_continuous_axes=True,
    max_sval_plot=30,
)


Sample output of the plot_summary function.

For users who are unsure of which DMD method is best for them, we provide the following flow chart, which outlines how one might choose an appropriate DMD variant based on specific problem types or data sets.

Awards

First prize winner in DSWeb 2019 Contest Tutorials on Dynamical Systems Software (Junior Faculty Category). You can read the winner tutorial (PDF format) in the tutorials folder.

Citing PyDMD

When citing PyDMD, please cite both of the following references:

  • Demo, Tezzele, Rozza. PyDMD: Python Dynamic Mode Decomposition. Journal of Open Source Software, 2018. [DOI][bibitem]
  • Ichinaga, Andreuzzi, Demo, Tezzele, Lapo, Rozza, Brunton, Kutz. PyDMD: A Python package for robust dynamic mode decomposition. arXiv preprint, 2024. [arXiv]

References

To implement the various versions of the DMD algorithm we follow these works:

General DMD References

  • Kutz, Brunton, Brunton, Proctor. Dynamic Mode Decomposition: Data-Driven Modeling of Complex Systems. SIAM Other Titles in Applied Mathematics, 2016. [DOI] [bibitem].
  • Schmid. Dynamic mode decomposition of numerical and experimental data. Journal of Fluid Mechanics, 2010. [DOI][bibitem]
  • Tu, Rowley, Luchtenburg, Brunton, Kutz. On Dynamic Mode Decomposition: Theory and Applications. Journal of Computational Dynamics, 2014. [DOI][bibitem]
  • Schmid. Dynamic mode decomposition and its variants. Annual Review of Fluid Mechanics, 2022. [DOI][bibitem]

DMD Variants: Noise-robust Methods

  • Forward-backward DMD: Dawson, Hemati, Williams, Rowley. Characterizing and correcting for the effect of sensor noise in the dynamic mode decomposition. Experiments in Fluids, 2016. [DOI] [bibitem].
  • Total least-squares DMD: Hemati, Rowley, Deem, Cattafesta. De-biasing the dynamic mode decomposition for applied Koopman spectral analysis of noisy datasets. Theoretical and Computational Fluid Dynamics, 2017. [DOI] [bibitem].
  • Optimal closed-form DMD: Héas, Herzet. Low-rank dynamic mode decomposition: An exact and tractable solution. Journal of Nonlinear Science, 2022. [DOI] [bibitem].
  • Subspace DMD: Takeishi, Kawahara, Yairi. Subspace dynamic mode decomposition for stochastic Koopman analysis. Physical Review E, 2017. [DOI] [bibitem].
  • Physics-informed DMD: Baddoo, Herrmann, McKeon, Kutz, Brunton. Physics-informed dynamic mode decomposition. Proceedings of the Royal Society A, 2023. [DOI] [bibitem].
  • Optimized DMD: Askham, Kutz. Variable projection methods for an optimized dynamic mode decomposition. SIAM Journal on Applied Dynamical Systems, 2018. [DOI] [bibitem].
  • Bagging, optimized DMD: Sashidhar, Kutz. Bagging, optimized dynamic mode decomposition for robust, stable forecasting with spatial and temporal uncertainty quantification. Proceedings of the Royal Society A, 2022. [DOI] [bibitem].

DMD Variants: Additional Methods and Extensions

  • DMD with Control: Proctor, Brunton, Kutz. Dynamic mode decomposition with control. SIAM Journal on Applied Dynamical Systems, 2016. [DOI] [bibitem].
  • Multiresolution DMD: Kutz, Fu, Brunton. Multiresolution dynamic mode decomposition. SIAM Journal on Applied Dynamical Systems, 2016. [DOI] [bibitem].
  • Sparsity-promoting DMD: Jovanović, Schmid, Nichols Sparsity-promoting dynamic mode decomposition. Physics of Fluids, 2014. [DOI] [bibitem].
  • Compressed DMD: Erichson, Brunton, Kutz. Compressed dynamic mode decomposition for background modeling. Journal of Real-Time Image Processing, 2016. [DOI] [bibitem].
  • Randomized DMD: Erichson, Mathelin, Kutz, Brunton. Randomized dynamic mode decomposition. SIAM Journal on Applied Dynamical Systems, 2019. [DOI] [bibitem].
  • Higher Order DMD: Le Clainche, Vega. Higher order dynamic mode decomposition. Journal on Applied Dynamical Systems, 2017. [DOI] [bibitem].
  • HAVOK: Brunton, Brunton, Proctor, Kaiser, Kutz. Chaos as an intermittently forced linear system. Nature Communications, 2017. [DOI] [bibitem].
  • Parametric DMD: Andreuzzi, Demo, Rozza. A dynamic mode decomposition extension for the forecasting of parametric dynamical systems. SIAM Journal on Applied Dynamical Systems, 2023. [DOI] [bibitem].
  • Extended DMD: Williams, Rowley, Kevrekidis. A kernel-based method for data-driven koopman spectral analysis. Journal of Computational Dynamics, 2015. [DOI] [bibitem].
  • LANDO: Baddoo, Herrmann, McKeon, Brunton. Kernel learning for robust dynamic mode decomposition: linear and nonlinear disambiguation optimization. Proceedings of the Royal Society A, 2022. [DOI] [bibitem].
  • DMD with Centering: Hirsh, Harris, Kutz, Brunton. Centering data improves the dynamic mode decomposition. SIAM Journal on Applied Dynamical Systems, 2020. [DOI] [bibitem]

General Implementation Tools

  • Gavish, Donoho. The optimal hard threshold for singular values is 4/sqrt(3). IEEE Transactions on Information Theory, 2014. [DOI] [bibitem].
  • Matsumoto, Indinger. On-the-fly algorithm for dynamic mode decomposition using incremental singular value decomposition and total least squares. 2017. [arXiv] [bibitem].

Recent works using PyDMD

You can find a list of the scientific works using PyDMD here.

Developers and contributors

The main developers are

We warmly thank all the contributors that have supported PyDMD!

Do you want to join the team? Read the Contributing guidelines and the Tutorials for Developers before starting to play!

Made with contrib.rocks.

Testing

We use pytest to run our unit tests. You can run the whole test suite by using the following command in the base directory of the repository:

pytest

Funding

A significant part of PyDMD has been written either as a by-product for other projects people were funded for, or by people on university-funded positions. There are probably many of such projects that have led to some development of PyDMD. We are very grateful for this support!

Beyond this, PyDMD has also been supported by some dedicated projects that have allowed us to work on extensions, documentation, training and dissemination that would otherwise not have been possible. In particular, we acknowledge the following sources of support with great gratitude:

Affiliations

About

Python Dynamic Mode Decomposition

https://pydmd.github.io/PyDMD/

License:MIT License

Languages

Language:Python 98.4%Language:TeX 1.6%