Machine Learning Collective Variables for Enhanced Sampling

CODE

PAPER

The documentation is available at:

• stable version: https://mlcolvar.readthedocs.io
• latest version: https://mlcolvar.readthedocs.io/en/latest/

mlcolvar is a Python library aimed to help design data-driven collective-variables (CVs) for enhanced sampling simulations. The key features are:

1. A unified framework to help test and use (some) of the CVs proposed in the literature.
2. A modular interface to simplify the development of new approaches and the contamination between them.
3. A streamlined distribution of CVs in the context of advanced sampling.

The library is built upon the PyTorch ML library as well as the Lightning high-level framework.

Some of the CVs which are implemented, organized by learning setting:

• Unsupervised: PCA, (Variational) AutoEncoders [1,2]
• Supervised: LDA [3], DeepLDA [4], DeepTDA [5]
• Time-informed: TICA [6], DeepTICA/SRVs [7,8], VDE [9]

And many others can be implemented based on the building blocks or with simple modifications. Check out the tutorials and the examples section of the documentation.

Install with pip

The library is available on PyPi and can be installed with pip. This is the preferred choice for users as it automatically installs the package requirements.

pip install mlcolvar

To validate your installation, install the test extras and run pytest against the installed package:

pip install mlcolvar[test]
pytest --pyargs mlcolvar.tests

Clone from GitHub

The library can also be installed cloning the repository from GitHub. This is the preferred choice for developers as it provides more flexibility and allows editable installation.

git clone https://github.com/luigibonati/mlcolvar.git
cd mlcolvar
pip -e install .

PLUMED interface: the resulting CVs can be deployed for enhancing sampling with the PLUMED package via the pytorch interface, available since version 2.9.

Notes: in early versions (v<=0.2.*) the library was called mlcvs. This is still accessible for compatibility with PLUMED masterclasses in the releases or by cloning the pre-lightning branch.

Copyright (c) 2023 Luigi Bonati, Enrico Trizio, Andrea Rizzi and Michele Parrinello. Structure of the project is based on Computational Molecular Science Python Cookiecutter.