PyDMD
2024.11.01
Description
Dépendances et installation
Guide de démarrage rapide
Récompenses
Citant PyDMD
Références
Développeurs et contributeurs
Financement
Affiliations
PyDMD est un package Python conçu pour la décomposition en mode dynamique (DMD) , une méthode basée sur les données utilisée pour analyser et extraire des structures spatio-temporelles cohérentes à partir d'ensembles de données variant dans le temps. Il fournit une interface complète et conviviale pour effectuer des analyses DMD, ce qui en fait un outil précieux pour les chercheurs, les ingénieurs et les data scientists travaillant dans divers domaines.
Avec PyDMD, les utilisateurs peuvent facilement décomposer des ensembles de données complexes de grande dimension en un ensemble de modes spatiaux et temporels cohérents, capturant la dynamique sous-jacente et extrayant des caractéristiques importantes. Le package implémente à la fois des algorithmes DMD standard et des variantes avancées, permettant aux utilisateurs de choisir la méthode la plus adaptée à leurs besoins spécifiques. Ces extensions permettent de traiter des données bruitées, des big dataset, des variables de contrôle, ou d'imposer des structures physiques.
PyDMD offre une intégration transparente avec l'écosystème scientifique Python, exploitant des bibliothèques populaires telles que NumPy et SciPy pour des calculs numériques et une manipulation de données efficaces. Il offre également une variété d'outils de visualisation, notamment la reconstruction de mode, l'analyse du spectre énergétique et le traçage de l'évolution temporelle. Ces capacités permettent aux utilisateurs d'avoir un aperçu des modes dominants du système, d'identifier les caractéristiques significatives et de comprendre l'évolution temporelle de la dynamique.
PyDMD favorise la facilité d'utilisation et la personnalisation, en fournissant une API bien documentée avec des noms de fonctions intuitifs et des descriptions claires des paramètres. Le package est activement maintenu et mis à jour, garantissant la compatibilité avec les dernières versions de Python et intégrant les commentaires des utilisateurs pour améliorer les fonctionnalités et les performances. Nous mettons à disposition de nombreux tutoriels présentant les caractéristiques du logiciel. Consultez la section Exemples ci-dessous et les didacticiels pour avoir une idée du potentiel de ce package. Consultez également le schéma ci-dessous pour un résumé de tous les outils et fonctionnalités disponibles. Les contributions actuellement en cours sont représentées par des cases semi-transparentes.
PyDMD est disponible sur PyPI, vous pouvez donc installer la dernière version publiée avec :
> pip installer pydmd
Pour installer la version Bing Edge, clonez ce référentiel avec :
> clone git https://github.com/PyDMD/PyDMD
puis installez le package en mode développement :
> pip install -e .
Les fonctionnalités principales de PyDMD dépendent de numpy et scipy . Afin d'utiliser les fonctionnalités de traçage, vous aurez également besoin matplotlib .
Pour exécuter DMD, commencez simplement par initialiser un module PyDMD qui implémente la méthode DMD de votre choix. Les modèles peuvent ensuite être ajustés en appelant la méthode fit() et en transmettant les données nécessaires. Cette étape exécute l'algorithme DMD, après quoi les utilisateurs peuvent utiliser les outils de traçage PyDMD afin de visualiser leurs résultats.
from pydmd import DMDfrom pydmd.plotter import plot_summary# Créez un modèle DMD exact avec 12 modes spatio-temporels.dmd = DMD(svd_rank=12)# Ajustez le modèle DMD.# X = (n, m) tableau numpy de données d'instantanés variables dans le temps .dmd.fit(X)# Tracez un résumé des modes spatio-temporels clés.plot_summary(dmd)
Les modules PyDMD peuvent également être encapsulés avec des préprocesseurs de données si vous le souhaitez. Ces wrappers prétraiteront automatiquement les données et post-traiteront les reconstructions de données.
from pydmd import DMDfrom pydmd.preprocessing import zero_mean_preprocessing# Construisez et ajustez un modèle DMD exact avec data centering.centered_dmd = zero_mean_preprocessing(DMD(svd_rank=12))centered_dmd.fit(X)
Les utilisateurs peuvent également créer des modèles DMD très complexes avec PyDMD. Vous trouverez ci-dessous un exemple de la façon dont on peut créer et ajuster un modèle DMD optimisé personnalisé avec un regroupement, des contraintes de valeurs propres et des arguments de projection de variables personnalisés.
from pydmd import BOPDMD# Créez un modèle DMD d'ensachage optimisé (BOP-DMD).# Pour un DMD optimisé (sans ensachage), utilisez BOPDMD(svd_rank=12, num_trials=0).bopdmd = BOPDMD(svd_rank=12, # Rank of le DMD fit.num_trials=100, # Nombre d'essais d'ensachage à effectuer.trial_size=0.5, # Utiliser 50 % du nombre total d'instantanés par essai.eig_constraints={"imag", "conjugate_pairs"}, # Les valeurs propres doivent être des paires imaginaires et conjuguées.varpro_opts_dict={"tol":0.2, "verbose":True}, # Définissez la tolérance de convergence et utilisez des mises à jour détaillées.)# Ajustez le modèle BOP-DMD.# X = (n, m) tableau numpy de valeurs variables dans le temps données d'instantané# t = (m,) tableau numpy d'heures de collecte de donnéesbopdmd.fit(X, t)Les modules et fonctions PyDMD peuvent être paramétrés par une variété d'entrées pour une personnalisation supplémentaire. Nous recommandons donc généralement aux nouveaux utilisateurs de se référer à notre documentation, ainsi qu'à nos didacticiels spécifiques aux modules pour plus d'exemples et d'informations.
Vous trouverez également ci-dessous un exemple d'appel à la fonction plot_summary() lorsqu'on lui donne un modèle DMD ajusté à un écoulement centré sur la moyenne au-delà d'une donnée de cylindre disponible sur dmdbook.com/DATA.zip . Un modèle DMD exact de rang 12 a été utilisé pour générer ce chiffre. Les valeurs propres, les modes et la dynamique sont codés par couleur pour indiquer les associations. Les tailles des marqueurs de valeurs propres indiquent également les amplitudes ou l'importance des modes spatio-temporels.
La documentation de l'outil de traçage peut être trouvée ici.
à partir de pydmd.plotter import plot_summaryplot_summary(dmd, # <-- Modèle PyDMD ajusté. Peut être DMD, BOPDMD, etc.figsize=(12, 7),index_modes=(0, 2, 4),snapshots_shape=(449, 199),order="F",mode_cmap="sismique",dynamics_color="k",flip_continuous_axes=True,max_sval_plot=30, )
Exemple de sortie de la fonction plot_summary.
Pour les utilisateurs qui ne savent pas quelle méthode DMD leur convient le mieux, nous fournissons l'organigramme suivant, qui décrit comment choisir une variante DMD appropriée en fonction de types de problèmes ou d'ensembles de données spécifiques.
Gagnant du premier prix du concours DSWeb 2019 Tutoriels sur les logiciels de systèmes dynamiques (catégorie Faculté junior). Vous pouvez lire le tutoriel du gagnant (format PDF) dans le dossier des tutoriels.
Lorsque vous citez PyDMD, veuillez citer les deux références suivantes :
Démo, Tezzele, Rozza. PyDMD : Décomposition en mode dynamique Python . Journal des logiciels open source, 2018. [DOI][bibitem]
Ichinaga, Andreuzzi, Demo, Tezzele, Lapo, Rozza, Brunton, Kutz. PyDMD : un package Python pour une décomposition robuste en mode dynamique . Préimpression arXiv, 2024. [arXiv]
Pour implémenter les différentes versions de l'algorithme DMD nous suivons ces travaux :
Kutz, Brunton, Brunton, Proctor. Décomposition en mode dynamique : modélisation basée sur les données de systèmes complexes . SIAM Autres titres en mathématiques appliquées, 2016. [DOI] [bibitem].
Schmid. Décomposition en mode dynamique de données numériques et expérimentales . Journal de mécanique des fluides, 2010. [DOI][bibitem]
Tu, Rowley, Luchtenburg, Brunton, Kutz. Sur la décomposition en mode dynamique : théorie et applications . Journal of Computational Dynamics, 2014. [DOI] [bibitem]
Schmid. Décomposition en mode dynamique et ses variantes . Revue annuelle de la mécanique des fluides, 2022. [DOI][bibitem]
DMD avant-arrière : Dawson, Hemati, Williams, Rowley. Caractérisation et correction de l'effet du bruit du capteur dans la décomposition en mode dynamique . Expériences dans les fluides, 2016. [DOI] [bibitem].
DMD total des moindres carrés : Hemati, Rowley, Deem, Cattafesta. "Débiaiser la décomposition en mode dynamique pour l'analyse spectrale Koopman appliquée aux ensembles de données bruyants" . Dynamique des fluides théorique et computationnelle, 2017. [DOI] [bibitem].
DMD optimal sous forme fermée : Héas, Herzet. "Décomposition en mode dynamique de bas rang : une solution exacte et réalisable" . Journal of Nonlinear Science, 2022. [DOI] [bibitem].
DMD sous-spatial : Takeishi, Kawahara, Yairi. Décomposition en mode dynamique du sous-espace pour l'analyse stochastique de Koopman . Examen physique E, 2017. [DOI] [bibitem].
DMD informé par la physique : Baddoo, Herrmann, McKeon, Kutz, Brunton. Décomposition en mode dynamique basée sur la physique . Actes de la Royal Society A, 2023. [DOI] [bibitem].
DMD optimisé : Askham, Kutz. Méthodes de projection variables pour une décomposition en mode dynamique optimisée . SIAM Journal sur les systèmes dynamiques appliqués, 2018. [DOI] [bibitem].
Ensachage, DMD optimisé : Sashidhar, Kutz. Bagging, décomposition en mode dynamique optimisée pour des prévisions robustes et stables avec quantification de l'incertitude spatiale et temporelle . Actes de la Royal Society A, 2022. [DOI] [bibitem].
DMD avec contrôle : Proctor, Brunton, Kutz. Décomposition en mode dynamique avec contrôle . SIAM Journal sur les systèmes dynamiques appliqués, 2016. [DOI] [bibitem].
DMD multirésolution : Kutz, Fu, Brunton. Décomposition en mode dynamique multirésolution . SIAM Journal sur les systèmes dynamiques appliqués, 2016. [DOI] [bibitem].
DMD favorisant la parcimonie : Jovanović, Schmid, Nichols Décomposition en mode dynamique favorisant la parcimonie . Physique des Fluides, 2014. [DOI] [bibitem].
DMD compressé : Erichson, Brunton, Kutz. Décomposition en mode dynamique compressé pour la modélisation en arrière-plan . Journal of Real-Time Image Processing, 2016. [DOI] [bibitem].
DMD randomisé : Erichson, Mathelin, Kutz, Brunton. Décomposition en mode dynamique aléatoire . SIAM Journal sur les systèmes dynamiques appliqués, 2019. [DOI] [bibitem].
DMD d'ordre supérieur : Le Clainche, Vega. Décomposition en mode dynamique d'ordre supérieur . Journal sur les systèmes dynamiques appliqués, 2017. [DOI] [bibitem].
HAVOK : Brunton, Brunton, Proctor, Kaiser, Kutz. Le chaos comme système linéaire forcé par intermittence . Nature Communications, 2017. [DOI] [bibitem].
DMD paramétrique : Andreuzzi, Démo, Rozza. Une extension de décomposition en mode dynamique pour la prévision des systèmes dynamiques paramétriques . SIAM Journal sur les systèmes dynamiques appliqués, 2023. [DOI] [bibitem].
DMD étendu : Williams, Rowley, Kevrekidis. "Une méthode basée sur le noyau pour l'analyse spectrale Koopman basée sur les données" . Journal of Computational Dynamics, 2015. [DOI] [bibitem].
LANDO : Baddoo, Herrmann, McKeon, Brunton. Apprentissage du noyau pour une décomposition robuste en mode dynamique : optimisation de la désambiguïsation linéaire et non linéaire . Actes de la Royal Society A, 2022. [DOI] [bibitem].
DMD avec centrage : Hirsh, Harris, Kutz, Brunton. Le centrage des données améliore la décomposition en mode dynamique . SIAM Journal sur les systèmes dynamiques appliqués, 2020. [DOI] [bibitem]
Gavish, Donoho. Le seuil strict optimal pour les valeurs singulières est 4/sqrt(3) . Transactions IEEE sur la théorie de l'information, 2014. [DOI] [bibitem].
Matsumoto, Indinger. Algorithme à la volée pour la décomposition en mode dynamique utilisant la décomposition incrémentielle de valeurs singulières et les moindres carrés totaux . 2017. [arXiv] [bibitem].
Vous pouvez trouver une liste des travaux scientifiques utilisant PyDMD ici.
Les principaux développeurs sont
Nous remercions chaleureusement tous les contributeurs qui ont soutenu PyDMD !
Vous souhaitez rejoindre l'équipe ? Lisez les directives de contribution et les didacticiels pour les développeurs avant de commencer à jouer !
Réalisé avec contrib.rocks.
Nous utilisons pytest pour exécuter nos tests unitaires. Utilisez la commande suivante pour installer les dépendances requises pour tester un clone local de PyDMD (en supposant que le chemin relatif du référentiel soit ./PyDMD/ ) :
python -m pip installer PyDMD/[test]
Vous pouvez exécuter l'intégralité de la suite de tests en utilisant la commande suivante dans le répertoire de base du référentiel :
python -m pytest
Une partie importante de PyDMD a été écrite soit comme sous-produit d'autres projets pour lesquels des personnes ont été financées, soit par des personnes occupant des postes financés par l'université. Il existe probablement de nombreux projets de ce type qui ont conduit au développement de PyDMD. Nous sommes très reconnaissants pour ce soutien !
Au-delà de cela, PyDMD a également été soutenu par certains projets dédiés qui nous ont permis de travailler sur des extensions, de la documentation, de la formation et de la diffusion qui n'auraient pas été possibles autrement. Nous remercions en particulier les sources de soutien suivantes avec une grande gratitude :
H2020 ERC CoG 2015 Projet AROMA-CFD 681447, PI Professeur Gianluigi Rozza au SISSA mathLab.
Projet FSE HEaD Optimisation de la forme de l'arc bulbeux grâce à une modélisation d'ordre réduit, FVG, Italie.
