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 (HMMs) 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 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.
| Dimension reduction | Deep dimension reduction | SINDy |
![]() |
![]() |
![]() |
| Markov state models | Hidden Markov models | Datasets |
![]() |
![]() |
![]() |
conda install -c conda-forge deeptime |
pip install deeptime |
Both channels ship compiled binaries for Linux, macOS (x86_64 and arm64), and Windows.
Optional extras: pip install "deeptime[deep-learning]" pulls in PyTorch for VAMPnets,
time-lagged autoencoders and deep MSMs; pip install "deeptime[plotting]" adds matplotlib and
networkx for deeptime.plots.
A Markov state model from a two-dimensional toy time series with two metastable states: project onto the slow coordinate with TICA, discretize with k-means, count transitions and estimate the MSM.
from deeptime.data import ellipsoids
from deeptime.decomposition import TICA
from deeptime.clustering import KMeans
from deeptime.markov import TransitionCountEstimator
from deeptime.markov.msm import MaximumLikelihoodMSM
traj = ellipsoids(seed=17).observations(n_steps=20000) # ndarray of shape (20000, 2)
tica = TICA(lagtime=10, dim=1).fit_fetch(traj) # fit_fetch() fits and returns the model
proj = tica.transform(traj) # slow coordinate, shape (20000, 1)
dtraj = KMeans(n_clusters=20).fit_transform(proj) # discrete trajectory of cluster indices
counts = TransitionCountEstimator(lagtime=10, count_mode='sliding').fit_fetch(dtraj)
msm = MaximumLikelihoodMSM(reversible=True).fit_fetch(counts)
print(msm.timescales(k=2)) # ≈ [16.5 3.1] steps; the process generating the data has 16.2The returned MarkovStateModel also provides the stationary distribution, PCCA+ metastable
sets, mean first passage times, reactive fluxes and more. The
MSM tutorial continues from here
with implied timescales and a Chapman–Kolmogorov test to validate the model.
Learn a nonlinear two-state decomposition with a VAMPnet, a neural network trained to maximize the VAMP score (requires PyTorch):
import torch
from deeptime.data import sqrt_model
from deeptime.decomposition import VAMP
from deeptime.decomposition.deep import VAMPNet
from deeptime.util.data import TrajectoryDataset
_, traj = sqrt_model(n_samples=10000, seed=17) # two metastable states that are not linearly separable
dataset = TrajectoryDataset(lagtime=1, trajectory=traj.astype('float32'))
loader = torch.utils.data.DataLoader(dataset, batch_size=512, shuffle=True)
lobe = torch.nn.Sequential(torch.nn.Linear(2, 32), torch.nn.ELU(), torch.nn.Linear(32, 2), torch.nn.Softmax(dim=1))
vampnet = VAMPNet(lobe=lobe, learning_rate=1e-3).fit(loader, n_epochs=20).fetch_model()
print(VAMP(lagtime=1, observable_transform=vampnet).fit_fetch(traj).score(2)) # ≈ 1.77
print(VAMP(lagtime=1, dim=1).fit_fetch(traj).score(2)) # ≈ 1.28, linear VAMP cannot resolve the two statesThe trained vampnet transforms frames to soft state memberships and plugs into the rest of
the library as an observable_transform, as shown, or as input to clustering and MSM
estimation.
Hidden Markov models
Segment a noisy one-dimensional signal into hidden states with a hidden Markov model with Gaussian output:
from deeptime.data import ellipsoids
from deeptime.markov.hmm import MaximumLikelihoodHMM, init
signal = ellipsoids(seed=17).observations(n_steps=20000)[:, 1] # two overlapping Gaussians
initial_hmm = init.gaussian.from_data(signal, n_hidden_states=2, reversible=True)
hmm = MaximumLikelihoodHMM(initial_hmm, lagtime=10).fit_fetch(signal)
print(hmm.transition_model.timescales()) # ≈ [16.0]
print(hmm.hidden_state_trajectories[0][:10]) # most likely hidden state per frameLonger worked examples, including an MSM of alanine dipeptide from molecular dynamics data and coherent sets in the Bickley jet, are collected in the examples section of the documentation.
If you use deeptime in your work, please cite
@article{hoffmann2021deeptime,
title = {Deeptime: a {P}ython library for machine learning dynamical models from time series data},
author = {Hoffmann, Moritz and Scherer, Martin Konrad and Hempel, Tim and Mardt, Andreas and de Silva, Brian and Husic, Brooke Elena and Klus, Stefan and Wu, Hao and Kutz, J. Nathan and Brunton, Steven and No{\'e}, Frank},
journal = {Machine Learning: Science and Technology},
volume = {3},
number = {1},
pages = {015009},
year = {2021},
publisher = {IOP Publishing},
doi = {10.1088/2632-2153/ac3de0}
}Please see the developer guide.
Bug reports, feature requests and pull requests are welcome on GitHub. The developer guide describes the estimator/model interfaces, how to build from source and how to run the tests.
Property tests marked fuzz use Hypothesis and run for about a second
each in the regular test suite. To fuzz them for longer, select them with -m fuzz and give a time budget
per test:
pytest tests -m fuzz --fuzz-seconds 600 -n 8The budget can also be set with DEEPTIME_FUZZ_SECONDS. Failing inputs are shrunk to a minimal example and
saved in .hypothesis/, so the next run replays them first.
Deeptime is distributed under the LGPL-3.0 license.





