mlcolvar: Machine Learning Collective Variables

mlcolvar is a Python library designed to help design data-driven collective-variables (CVs) for enhanced sampling simulations. It provides a unified framework to test and use CVs from literature, a modular interface for developing new approaches, and a streamlined way to distribute CVs for advanced sampling.

The library is built on top of PyTorch and Lightning.

Implemented CVs are organized by learning setting:

• Unsupervised: PCA, (Variational) AutoEncoders
• Supervised: LDA, DeepLDA, DeepTDA
• Time-informed: TICA, DeepTICA/SRVs, VDE

The mlcolvar.data module provides the core classes required to manage datasets and feed them into a Lightning trainer. It uses a dictionary-based approach to handle data structures.

Key components include:

• DictDataset: A class for managing the dataset itself.
• DictLoader: A class for handling data loading (likely a wrapper around PyTorch DataLoaders).
• DictModule: A class used to integrate these data structures with the Lightning trainer.

Supervised CVs are optimized using classification or regression tasks.

Available classes in mlcolvar.cvs:

• DeepLDA
• DeepTDA
• RegressionCV

The Datasets module provides specialized classes designed to simplify and improve the efficiency of data access. These classes are fully compatible with PyTorch and PyTorch Lightning workflows.

Refer to the api_data documentation to learn how to implement or use these datasets in your training pipelines.

Time-informed CVs are optimized using pairs of time-lagged configurations. They also support optional reweighting for time-correlation functions. Note that autoencoder-based CVs can function as time-informed CVs if the target reference is time-lagged data.

Available class in mlcolvar.cvs:

• DeepTICA

The library provides two main categories of auxiliary tools:

• Utils: Miscellaneous helper functions and general-purpose tools (see api_utils).
• Explain: Specialized tools for inspecting and interpreting the trained models (see api_explain).

The project uses Versioneer to automatically infer the installed version based on git tags and commit distance. The versioning follows PEP 440 and uses the following regular expression format:

\d+.\d+.\d+(?+\d+-[a-z0-9]+)

Version Logic:

• If the current commit matches a git tag, the version is exactly that tag (e.g., mlcolvar-0.1.2).
• If the commit is ahead of the last tag, the version is appended with +X (where X is the number of commits ahead) and -YYYYYY (where Y is the git commit hash).

The library implements neural network-based Collective Variables (CVs) within the mlcolvar.cvs module. All CV implementations inherit from the BaseCV class, which provides default methods for the CV lifecycle.

Note that linear statistical methods are not part of this hierarchy; they are located in mlcolvar.core.stats instead.

The MultiTaskCV framework allows you to optimize a single model using different loss functions applied to different datasets simultaneously.

Available class in mlcolvar.cvs:

• MultiTaskCV

The core modules provide the fundamental components required to construct custom CV classes. The architecture is organized into the following submodules:

• nn: Neural network components.
• loss: Loss functions used for CV optimization.
• stats: Statistical tools and methods.
• transform: Data transformation utilities.

Refer to the api_core documentation for detailed API signatures of these building blocks.

The library implements several CVs categorized by their learning setting:

• Unsupervised: PCA, (Variational) AutoEncoders
• Supervised: LDA, DeepLDA, DeepTDA
• Time-informed: TICA, DeepTICA/SRVs, VDE
• Committor-based

Users can also implement new CVs using the library's building blocks.

The cvs module provides pre-built Collective Variable (CV) classes. These are categorized into three sub-packages based on the data type used for their optimization:

• unsupervised: CVs optimized without explicit labels.
• supervised: CVs optimized using supervised learning techniques.
• time-lagged: CVs optimized using time-lagged information.

Refer to the api_cvs documentation for specific class implementations and usage.