deeptime adds Markov state model analysis on top of a scikit-learn style estimator API

Two layers of API, not one

Most Python analysis libraries stop at producing a fitted model. deeptime is built around a second idea: the estimator is only half of the job.

The first half is the Estimator classes, and the project describes the library as largely compatible with scikit-learn. You fit an estimator to data, and the fit object is the familiar scikit-learn shape.

The second half is the Model classes. The documentation gives the example of a Markov state model, where the fitted model provides a set of analysis methods for thermodynamic and kinetic quantities: free energies, relaxation times and transition paths. In other words, the estimator produces the transition matrix and the metastable state decomposition, and the model layer turns that into the numbers a physical chemist would put in a paper.

That split is the whole design of the library, and it is why the project separates estimators from models rather than folding them together. It also means a first time user has two APIs to learn, not one. The topic tags on the repository point at the same territory: hidden Markov models, Markov state models, Koopman operators, coherent set detection and covariance estimation.

The estimator families the library covers

The project groups its models into two broad camps. The conventional linear methods are the Markov state models, the hidden Markov models and the Koopman models. The kernel and deep learning approaches are represented by VAMPnets and deep MSMs.

The components page of the documentation adds more of the map. It lists dimension reduction and deep dimension reduction as separate entries, plus SINDy, which is the sparse identification of nonlinear dynamics approach for recovering governing equations from data. Datasets appear as their own component, meaning the library ships example data rather than only estimators.

A Koopman model is worth singling out, because it is the member of the family that changes what you can ask of a trajectory. Instead of a discrete jump model between metastable basins, a Koopman model embeds the dynamics in a continuous space of eigenfunctions, which makes it the right tool when the quantity you care about varies smoothly rather than switching between well separated states.

The stated scope of the library is deliberately general. It is not tied to molecular simulation, even though that is where these estimators originated. The description positions it as a general purpose library for time series analysis, and the PyPI summary adds dimensionality reduction and clustering to the list.

Installing the binary wheels

Both conda and pip are supported, and both ship compiled binaries rather than building from source on the target machine. The documentation states that compiled binaries exist for Linux, Windows and macOS, for x86_64 and arm64.

The two documented commands are conda install -c conda-forge deeptime and pip install deeptime. The conda-forge package and the PyPI distribution are both published, with the PyPI page linked as the download location in the project metadata.

That packaging decision matters more than it sounds for a library with a C++ core and Python bindings, because a source build on macOS requires a working toolchain and a matching pybind11 install. The prebuilt artifacts remove that step for the common platforms.

The dependency floor is modest. The project metadata requires Python 3.9 or newer and lists numpy, scipy 1.9.0 or newer, scikit-learn 1.5.0 or newer and threadpoolctl 3.1.0 or newer as the runtime requirements. scikit-learn being a hard dependency at a fairly recent version is the one to check against an existing environment, since 1.5 is what the library is built and tested against.

The heavier parts are optional. The deep-learning extra adds torch, the plotting extra adds matplotlib and networkx, and a units extra adds pint 0.20 or newer, which is the standard way to attach physical dimensions to computed quantities.

Building the C++ layer and its own test suite

The C++ library and its tests can be built directly with CMake, which requires Python with development headers, NumPy and pybind11 to be present. The documented invocation enables the C++ tests explicitly.

cmake -B build \
  -DDEEPTIME_BUILD_CPP_TESTS=ON \
  -DPython_ROOT_DIR=/path/to/venv \
  -DPython_FIND_VIRTUALENV=ONLY \
  -Dpybind11_DIR=$(python -c "import pybind11; print(pybind11.get_cmake_dir())")

cmake --build build --target tests
./build/tests/tests

The two CMake variables that control discovery are the ones to copy carefully. Python_ROOT_DIR tells CMake where the interpreter lives, and Python_FIND_VIRTUALENV set to ONLY stops CMake from picking up the system Python when you are working inside a virtual environment. The pybind11_DIR value is computed rather than typed, which is the pattern to keep if your environment is unusual.

The option table lists three knobs: DEEPTIME_BUILD_CPP_TESTS, off by default, DEEPTIME_VERSION and DEEPTIME_VERSION_INFO, both defaulting to 0.0.0. That last pair is a small trap. The version in the Python distribution is marked as dynamic in the project metadata, so a hand rolled CMake build without overriding these options can produce a package that reports 0.0.0, which is not a version you want in a lock file or in a bug report.

Reading trunk without waiting for a release

For developers who need the newest commits, the documentation gives two paths. Clone the repository and install it locally.

git clone https://github.com/deeptime-ml/deeptime.git

cd deeptime
pip install .

Or install straight from the remote branch with the command pip install git+https://github.com/deeptime-ml/deeptime.git@main.

Both routes build from source, since the published wheels are produced from tagged releases. A local install with pip invokes scikit-build-core, and the build requirements in the project metadata name scikit-build-core 0.10 or newer, pybind11 2.10.1 or newer and numpy. On a machine without a compiler you are back to the toolchain problem the prebuilt wheels were meant to avoid.

The repository layout gives a hint at how the work is organised. There is a src directory for the implementation, a separate tests directory, docs for the documentation sources, an examples directory holding clustering, dataset and method examples, a devtools directory, and a CMakeLists.txt at the root. A .gitmodules entry indicates that some dependencies are pulled in as submodules, which is worth knowing before you try to build with unusual options.

A release list that has not moved since April 2025

The published versions are v0.4.5 from 2025-04-09, v0.4.4 from 2022-12-20 and v0.4.3 from 2022-09-08. That is a long flat stretch after the most recent tag.

The branch, however, is not idle. The last push to the repository was on 2026-10-16, so commits have continued for months after the last release. The consequences are the usual ones for a library with a gap between tagged versions: the code on main may contain changes that no released wheel has, and there is no release note to read when something behaves differently from the published version.

The repository does contain a ReleaseChecklist.md file at the root, which tells you that releases are a deliberate, documented process rather than an ad hoc tag. The documentation is also maintained separately from the repository, on the project documentation site, and the badge in the project page links to that site rather than to a docs directory in the tree.

Practically, teams should decide now whether they pin v0.4.5 or track main. Tracking main means accepting untagged changes and owning the build from source.

LGPL-3.0 and the practical licensing questions

The library is published under the LGPL-3.0, and the project page carries a badge for LGPL v3. For a Python library consumed as an installed package rather than linked into a binary, the practical effect is milder than the licence name suggests, since the import boundary sits between your application and the library.

Two supporting files are present in the repository root that are worth checking in a due diligence pass. ThirdPartyNotices.txt records the licensing position of bundled third party components, which matters for a library that vendors parts of the tree-sitter style C++ ecosystem. AUTHORS credits the contributors, and the project metadata carries a long author list, which is unusual to see in package metadata and suggests a project with a long institutional history.

Nothing in the project documentation addresses how to use the library in a commercial product, so that question is yours to answer with your own legal reading. The dependency floor is worth pairing with it: numpy, scipy and scikit-learn are all permissively licensed, so the licence question is concentrated in this one package rather than spread across the tree.

Editorial conclusion

Adopt deeptime if your data is a long trajectory whose metastable states you need to characterise quantitatively, since the Model layer computes relaxation times and transition paths rather than leaving you to derive them yourself. Do not adopt it for short series or single clustering passes, where a scikit-learn estimator is enough and the extra dependency floor of Python 3.9 and scikit-learn 1.5 is a needless constraint. Before you pin a version, check the release list against your environment, because the last published release is v0.4.5 from 2025-04-09 while commits have continued on the main branch, and confirm that the LGPL-3.0 terms suit how you intend to distribute an application that links it.

Frequently asked questions

Official sources

1. deeptime-ml/deeptime on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases