How luigibonati/mlcolvar works
1. What this repository is
mlcolvar is a Python package for building and training machine-learning collective variables (CVs) for enhanced sampling in molecular simulation. The architecture is centered on reusable PyTorch/Lightning components that turn molecular descriptors and simulation data into trained CV models.
2. Top-level layering
The codebase is organized in three main layers: low-level primitives in mlcolvar.core, data handling in mlcolvar.data, and higher-level CV models in mlcolvar.cvs. Around those are supporting modules for explanation, utilities, tests, and documentation.
3. Core building blocks
mlcolvar.core contains the generic ML/math pieces reused across all model families:
- nn: feed-forward neural network components.
- loss: task-specific losses such as MSE, TDA, DeepLDA/Fisher-style objectives, autocorrelation, ELBO, and generator/committor-related losses.
- stats: classical methods and covariance/eigenvalue-based tools like PCA, LDA, and TICA.
- transform: feature preprocessing and descriptor extraction, including pairwise distances, torsional angles, coordination numbers, adjacency/eigenvalue descriptors, normalization, histograms, and switching functions.
This layer is the main “feature engineering + objective function” boundary.
4. CV model layer
mlcolvar.cvs builds user-facing CV classes on top of the core pieces. It is split by learning setting:
- unsupervised: AutoEncoder, Variational AutoEncoder.
- supervised: Regression, DeepLDA, DeepTDA.
- timelagged: DeepTICA.
- committor: committor-based models.
- multitask: combined-objective CVs.
- generator: generator-based CV construction.
These classes are the main training/inference entry points for applications.
5. Data flow and training input
mlcolvar.data provides dataset, dataloader, and Lightning datamodule abstractions. This is the boundary where simulation-derived tables, labels, and time-lagged pairs are packaged into trainable batches. The surrounding utilities in mlcolvar.utils.io and mlcolvar.utils.timelagged help construct these inputs from files and trajectories.
6. Feature extraction pipeline
In practical use, data enters as molecular coordinates or precomputed CV descriptors, passes through core.transform to generate learned or handcrafted features, then into data objects for batching, and finally into a CV model in cvs. This pipeline is what connects raw simulation outputs to learned low-dimensional variables.
7. Analysis and interpretability
mlcolvar.explain focuses on model interpretation, with LASSO- and sensitivity-based analyses for feature relevance. These modules operate downstream of trained models and are used to explain which input features most influence the learned CVs.
8. Shared utilities
mlcolvar.utils contains cross-cutting support functions:
- fes: free-energy surface estimation.
- plot: plotting utilities for distributions and metrics.
- trainer: Lightning training helpers and callbacks.
- io: file loading and dataset creation.
- timelagged: helpers for constructing time-lagged samples.
These utilities support the training/analysis workflow but are not themselves model-specific.
9. External technology boundaries
The package is built on PyTorch for tensor computation and Lightning for training orchestration. The README also notes deployment to PLUMED through the PyTorch model interface, which is important because it turns trained CVs into simulation-time components rather than only offline predictors.
10. Examples and documentation as workflow guides
The docs/ tree is substantial and includes API docs, tutorials, and notebooks covering unsupervised, supervised, timelagged, and multitask workflows. The notebook data/results directories show the intended end-to-end usage: prepare simulation data, train a CV, evaluate it, and reuse the trained model in later analysis or simulation.
11. Testing and quality boundaries
mlcolvar/tests mirrors the package structure, with unit tests for core transforms, losses, datasets, CV classes, explainers, and utilities. This suggests the architectural contract is component-level: each transform, loss, or CV class is expected to be independently testable and reusable.
12. Release and distribution infrastructure
The repo is packaged as a Python library with pyproject.toml, setup.cfg, and PyPI/GitHub Actions workflows. CI, code coverage, and code scanning are integrated, but they support the library architecture rather than define runtime behavior.
Main entry points: __init__.py mlcolvar · cv.py Base CV · loss Losses · docs Docs
Components 22
Core ML
Reusable neural network, loss, statistics, and feature transform primitives.
- Neural net · Feed-forward network building blocks and helpers.
mlcolvar/core/nn/feedforward.py - Losses · Task losses for regression, TDA, LDA/Fisher, ELBO, committor, and generator objectives.
mlcolvar/core/loss - Stats · Classical linear methods and slow-mode analysis tools such as PCA, LDA, and TICA.
mlcolvar/core/stats - Transforms · Descriptor extraction, preprocessing, normalization, and feature construction.
mlcolvar/core/transform
CV Models
User-facing collective variable model families built on the core layer.
- Base CV · Shared CV interface and common model behavior.
mlcolvar/cvs/cv.py - Unsupervised · Autoencoder and variational autoencoder CVs.
mlcolvar/cvs/unsupervised - Supervised · Regression, DeepLDA, and DeepTDA models.
mlcolvar/cvs/supervised - DeepTICA · Time-lagged CV model for slow collective modes.
mlcolvar/cvs/timelagged/deeptica.py - Committor · Committor-based CV construction and training.
mlcolvar/cvs/committor/committor.py - MultiTask · Combined-objective CV models.
mlcolvar/cvs/multitask/multitask.py - Generator · Generator-based CV construction and training.
mlcolvar/cvs/generator/generator.py
Data Pipeline
Dataset and batching abstractions for simulation-derived training inputs.
- Data API · Dataset, dataloader, and Lightning datamodule abstractions.
mlcolvar/data
Support
Interpretability and utility modules that support training and analysis.
- Explain · Feature relevance analysis via LASSO and sensitivity methods.
mlcolvar/explain - IO & Lag · File loading, dataset creation, and time-lagged sample helpers.
mlcolvar/utils/io.py - Trainer · Lightning training helpers and callbacks.
mlcolvar/utils/trainer.py - FES · Free-energy surface estimation utilities.
mlcolvar/utils/fes.py
Repo Surface
Package entry points, docs, tests, and release infrastructure.
- mlcolvar · Top-level package namespace and public entry point.
mlcolvar/__init__.py - Docs · API reference, tutorials, notebooks, and usage guides.
docs - Tests · Component-level tests mirroring package structure.
mlcolvar/tests - Build & CI · Project metadata, packaging, and automation workflows.
pyproject.toml - PyTorch/Lightning · Primary tensor and training runtime dependencies.
- PLUMED · Simulation-time integration target for trained CV models.
Connections 43
- mlcolvar → Neural net: exports · Package surface exposes core neural components.
- mlcolvar → Losses: exports · Package surface exposes loss objectives.
- mlcolvar → Stats: exports · Package surface exposes classical statistics tools.
- mlcolvar → Transforms: exports · Package surface exposes feature transforms.
- mlcolvar → Base CV: exports · Package surface exposes CV base interfaces.
- mlcolvar → Unsupervised: exports · Package surface exposes unsupervised CVs.
- mlcolvar → Supervised: exports · Package surface exposes supervised CVs.
- mlcolvar → DeepTICA: exports · Package surface exposes deep TICA.
- mlcolvar → Committor: exports · Package surface exposes committor models.
- mlcolvar → MultiTask: exports · Package surface exposes multitask CVs.
- mlcolvar → Generator: exports · Package surface exposes generator CVs.
- mlcolvar → Data API: exports · Package surface exposes data abstractions.
- mlcolvar → Explain: exports · Package surface exposes explainability tools.
- mlcolvar → IO & Lag: exports · Package surface exposes IO and time-lagged helpers.
- mlcolvar → Trainer: exports · Package surface exposes training helpers.
- mlcolvar → FES: exports · Package surface exposes free-energy utilities.
- Unsupervised → Neural net: uses · Unsupervised CVs are built from feed-forward networks.
- Unsupervised → Losses: uses · Unsupervised CVs optimize reconstruction and variational losses.
- Supervised → Losses: uses · Supervised CVs rely on regression and discriminant losses.
- Supervised → Stats: uses · DeepLDA/DeepTDA are aligned with statistical objectives.
- DeepTICA → Stats: uses · DeepTICA connects to time-lagged statistical structure.
- Committor → Losses: uses · Committor models use committor-specific objectives.
- MultiTask → Losses: uses · Multitask CVs combine multiple losses.
- Generator → Losses: uses · Generator CVs use generator-related objectives.
- Base CV → Data API: trains on · CVs consume datasets and dataloaded batches.
- Data API → IO & Lag: assembled by · Datasets and datamodules are commonly built from IO helpers.
- Data API → Trainer: orchestrates · Data objects feed Lightning training helpers.
- Transforms → IO & Lag: feeds · Transforms turn loaded simulation data into model features.
- Explain → Base CV: analyzes · Interpretability runs on trained CV models.
- FES → Base CV: evaluates · FES tools are used downstream of learned CVs.
- Base CV → PLUMED: integrates · Trained CVs can be deployed into simulation workflows.
- Base CV → PyTorch/Lightning: built on · Models are implemented with PyTorch and Lightning.
- Trainer → PyTorch/Lightning: built on · Training helpers wrap Lightning orchestration.
- Docs → Unsupervised: documents · Docs include unsupervised workflows and tutorials.
- Docs → Supervised: documents · Docs include supervised workflows and tutorials.
- Docs → DeepTICA: documents · Docs include time-lagged workflows and tutorials.
- Docs → MultiTask: documents · Docs include multitask workflows and tutorials.
- Tests → Transforms: covers · Tests mirror transform components.
- Tests → Losses: covers · Tests cover loss functions and utilities.
- Tests → Data API: covers · Tests cover data abstractions.
- Tests → Base CV: covers · Tests cover CV interfaces and variants.
- Build & CI → Docs: supports · Build and CI infrastructure supports docs generation and publishing.
- Build & CI → Tests: supports · Build and CI infrastructure runs validation.