Deeptime: a Python library for machine learning dynamical models from time series data

Moritz Hoffmann, Martin Scherer, Tim Hempel, Andreas Mardt, Brian de Silva, Brooke E. Husic, Stefan Klus, Hao Wu, J. Nathan Kutz, Steven L. Brunton, Frank Noé

Abstract

Generation and analysis of time-series data is relevant to many quantitative fields ranging from economics to fluid mechanics. In the physical sciences, structures such as metastable and coherent sets, slow relaxation processes, collective variables dominant transition pathways or manifolds and channels of probability flow can be of great importance for understanding and characterizing the kinetic, thermodynamic and mechanistic properties of the system. Deeptime is a general purpose Python library offering various tools to estimate dynamical models based on time-series data including conventional linear learning methods, such as Markov state models (MSMs), Hidden Markov Models and Koopman models, as well as kernel and deep learning approaches such as VAMPnets and deep MSMs. The library is largely compatible with scikit-learn, having a range of Estimator classes for these different models, but in contrast to scikit-learn also provides deep Model classes, e.g. in the case of an MSM, which provide a multitude of analysis methods to compute interesting thermodynamic, kinetic and dynamical quantities, such as free energies, relaxation times and transition paths. The library is designed for ease of use but also easily maintainable and extensible code. In this paper we introduce the main features and structure of the deeptime software.

Introduction

Analyzing time-series data to understand underlying physical processes—such as molecular folding, climate patterns, or fluid flows—is a cornerstone of many scientific disciplines. Historically, software tools for these tasks have been domain-specific or limited to narrow model classes. Integrating modern deep learning with traditional mathematical frameworks often requires researchers to develop custom, complex pipelines from scratch.

Deeptime addresses this gap by providing a domain-agnostic, general-purpose Python library. It bridges the divide between traditional linear methods and modern deep learning, enabling researchers to extract kinetic, thermodynamic, and mechanistic properties from temporal data within a unified environment. By framing methods from molecular dynamics (like MSMs) and fluid dynamics (like DMD) under the single umbrella of transfer operators, Deeptime allows researchers to easily swap and compare techniques that were previously siloed in different scientific communities.

Methods and Architecture

Deeptime is built upon the mathematical framework of transfer operators, specifically Koopman and Perron-Frobenius operators. This approach allows highly nonlinear system dynamics to be analyzed using the tools of linear algebra. The library unifies various methods based on their mathematical relationships, as shown in Figure 1.

Relationships between various dynamical modeling methods supported in Deeptime, categorized by time-homogeneity and their mathematical equivalents.

The library's architecture is designed for flexibility and scalability:

  • API Design: Inspired by scikit-learn, Deeptime uses Estimators as factories to produce standalone Model objects. This decoupling facilitates model serialization, parameter studies without side effects, and extensive downstream analysis.
  • Methodological Breadth: The library includes conventional dimension reduction techniques like Time-lagged Independent Component Analysis (TICA), Dynamic Mode Decomposition (DMD), Markov State Models (MSMs), and Hidden Markov Models (HMMs). It also supports kernel-based methods such as Kernel CCA and Kernel EDMD.
  • Deep Learning Integration: Through PyTorch integration, users can train deep models like VAMPNets, KVADNets, and Time-lagged Autoencoders (TAEs). These models output standard NumPy arrays, ensuring compatibility with the broader scientific Python ecosystem.
  • Variational Scoring: The library utilizes variational scores (like the VAMP score) which have a theoretical upper bound. These can be used directly as objective functions for neural networks to automatically find optimal feature representations for complex dynamics.

Evaluation and Results

The library was validated using several synthetic datasets and benchmarks, including asymmetric potential wells, the Bickley jet fluid flow, and the Rössler attractor.

  • Nonlinear Dimension Reduction: In tests on non-linearly separable states, traditional linear methods like TICA achieved only 87.6% accuracy. In contrast, kernel methods (Kernel EDMD) and deep learning (VAMPNets) reached near-perfect separation (99.9% and 100%, respectively).
  • Coherent Set Detection: In analyzing the Bickley jet, deep learning-based KVADNets outperformed traditional Kernel CCA, achieving a higher coherence score (0.87 vs 0.85) in identifying fluid vortices.
  • Computational Performance: Deeptime's native C++ data generators provide significant speedups—roughly 10x faster than mixed Python/C++ implementations and 100x faster than pure Python implementations.

Conclusion and Future Directions

While Deeptime offers a robust suite of tools, the authors identify areas for growth, such as incorporating more noise-robust DMD variants and addressing numerical integration noise in deterministic systems that can affect VAMPNet scores. Future work will focus on supporting experimental data in VAMPNets, extending SINDy (Sparse Identification of Nonlinear Dynamics) with neural network-based estimation, and implementing streaming capabilities for online learning on continuous data. By providing a unified, extensible toolkit, Deeptime empowers researchers to apply sophisticated dynamical modeling techniques across a wide range of scientific domains.

Summary updated

Abstract

Generation and analysis of time-series data is relevant to many quantitative fields ranging from economics to fluid mechanics. In the physical sciences, structures such as metastable and coherent sets, slow relaxation processes, collective variables dominant transition pathways or manifolds and channels of probability flow can be of great importance for understanding and characterizing the kinetic, thermodynamic and mechanistic properties of the system. Deeptime is a general purpose Python library offering various tools to estimate dynamical models based on time-series data including conventional linear learning methods, such as Markov state models (MSMs), Hidden Markov Models and Koopman models, as well as kernel and deep learning approaches such as VAMPnets and deep MSMs. The library is largely compatible with scikit-learn, having a range of Estimator classes for these different models, but in contrast to scikit-learn also provides deep Model classes, e.g. in the case of an MSM, which provide a multitude of analysis methods to compute interesting thermodynamic, kinetic and dynamical quantities, such as free energies, relaxation times and transition paths. The library is designed for ease of use but also easily maintainable and extensible code. In this paper we introduce the main features and structure of the deeptime software.
BibTeX
@article{hoffmann2021deeptime,
  author = {Moritz Hoffmann and Martin Scherer and Tim Hempel and Andreas Mardt and Brian de Silva and Brooke E. Husic and Stefan Klus and Hao Wu and J. Nathan Kutz and Steven L. Brunton and Frank Noé},
  title = {{Deeptime: a Python library for machine learning dynamical models from time series data}},
  journal = {Mach. Learn. Sci. Technol.},
  year = {2021},
  doi = {10.1088/2632-2153/ac3de0},
}
Figure