# luigibonati/mlcolvar architecture

> Architecture diagram of the GitHub repository luigibonati/mlcolvar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luigibonati/mlcolvar
- Repository: https://github.com/luigibonati/mlcolvar

## Overview

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: [`mlcolvar/__init__.py`](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/__init__.py) (mlcolvar), [`mlcolvar/cvs/cv.py`](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/cv.py) (Base CV), [`mlcolvar/core/loss`](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/core/loss) (Losses), [`docs`](https://github.com/luigibonati/mlcolvar/tree/main/docs) (Docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core ML"]
  node_node_core_nn["Neural net<br/>core.nn<br/>[feedforward.py]"]
  node_node_core_loss["Losses<br/>core.loss"]
  node_node_core_stats["Stats"]
  node_node_core_transform["Transforms<br/>core.transform"]
end

subgraph group_group_cvs["CV Models"]
  node_node_cv_base["Base CV<br/>cvs.base<br/>[cv.py]"]
  node_node_cv_unsup["Unsupervised"]
  node_node_cv_sup["Supervised"]
  node_node_cv_tica["DeepTICA<br/>cvs.timelagged<br/>[deeptica.py]"]
  node_node_cv_committor["Committor<br/>[committor.py]"]
  node_node_cv_multitask["MultiTask<br/>[multitask.py]"]
  node_node_cv_generator["Generator<br/>[generator.py]"]
end

subgraph group_group_data["Data Pipeline"]
  node_node_data["Data API"]
end

subgraph group_group_support["Support"]
  node_node_explain["Explain<br/>interpretability"]
  node_node_utils_io["IO & Lag<br/>utils.io/timelagged<br/>[io.py]"]
  node_node_utils_trainer["Trainer<br/>[trainer.py]"]
  node_node_utils_fes["FES<br/>[fes.py]"]
end

subgraph group_group_top["Repo Surface"]
  node_node_mlcolvar_pkg["mlcolvar<br/>python package<br/>[__init__.py]"]
  node_node_docs["Docs<br/>documentation"]
  node_node_tests["Tests<br/>test suite"]
  node_node_build["Build & CI<br/>packaging/ci<br/>[pyproject.toml]"]
  node_node_external(("PyTorch/Lightning<br/>external runtime"))
  node_node_plumed(("PLUMED<br/>external integration"))
end

node_node_mlcolvar_pkg -->|"exports"| node_node_core_nn
node_node_mlcolvar_pkg -->|"exports"| node_node_core_loss
node_node_mlcolvar_pkg -->|"exports"| node_node_core_stats
node_node_mlcolvar_pkg -->|"exports"| node_node_core_transform
node_node_mlcolvar_pkg -->|"exports"| node_node_cv_base
node_node_mlcolvar_pkg -->|"exports"| node_node_cv_unsup
node_node_mlcolvar_pkg -->|"exports"| node_node_cv_sup
node_node_mlcolvar_pkg -->|"exports"| node_node_cv_tica
node_node_mlcolvar_pkg -->|"exports"| node_node_cv_committor
node_node_mlcolvar_pkg -->|"exports"| node_node_cv_multitask
node_node_mlcolvar_pkg -->|"exports"| node_node_cv_generator
node_node_mlcolvar_pkg -->|"exports"| node_node_data
node_node_mlcolvar_pkg -->|"exports"| node_node_explain
node_node_mlcolvar_pkg -->|"exports"| node_node_utils_io
node_node_mlcolvar_pkg -->|"exports"| node_node_utils_trainer
node_node_mlcolvar_pkg -->|"exports"| node_node_utils_fes
node_node_cv_unsup -->|"uses"| node_node_core_nn
node_node_cv_unsup -->|"uses"| node_node_core_loss
node_node_cv_sup -->|"uses"| node_node_core_loss
node_node_cv_sup -->|"uses"| node_node_core_stats
node_node_cv_tica -->|"uses"| node_node_core_stats
node_node_cv_committor -->|"uses"| node_node_core_loss
node_node_cv_multitask -->|"uses"| node_node_core_loss
node_node_cv_generator -->|"uses"| node_node_core_loss
node_node_cv_base -->|"trains on"| node_node_data
node_node_data -->|"assembled by"| node_node_utils_io
node_node_data -->|"orchestrates"| node_node_utils_trainer
node_node_core_transform -->|"feeds"| node_node_utils_io
node_node_explain -->|"analyzes"| node_node_cv_base
node_node_utils_fes -->|"evaluates"| node_node_cv_base
node_node_cv_base -->|"integrates"| node_node_plumed
node_node_cv_base -->|"built on"| node_node_external
node_node_utils_trainer -->|"built on"| node_node_external
node_node_docs -.->|"documents"| node_node_cv_unsup
node_node_docs -.->|"documents"| node_node_cv_sup
node_node_docs -.->|"documents"| node_node_cv_tica
node_node_docs -.->|"documents"| node_node_cv_multitask
node_node_tests -.->|"covers"| node_node_core_transform
node_node_tests -.->|"covers"| node_node_core_loss
node_node_tests -.->|"covers"| node_node_data
node_node_tests -.->|"covers"| node_node_cv_base
node_node_build -.->|"supports"| node_node_docs
node_node_build -.->|"supports"| node_node_tests

click node_node_mlcolvar_pkg "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/__init__.py"
click node_node_core_nn "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/core/nn/feedforward.py"
click node_node_core_loss "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/core/loss"
click node_node_core_stats "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/core/stats"
click node_node_core_transform "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/core/transform"
click node_node_cv_base "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/cv.py"
click node_node_cv_unsup "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/cvs/unsupervised"
click node_node_cv_sup "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/cvs/supervised"
click node_node_cv_tica "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/timelagged/deeptica.py"
click node_node_cv_committor "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/committor/committor.py"
click node_node_cv_multitask "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/multitask/multitask.py"
click node_node_cv_generator "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/generator/generator.py"
click node_node_data "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/data"
click node_node_explain "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/explain"
click node_node_utils_io "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/utils/io.py"
click node_node_utils_trainer "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/utils/trainer.py"
click node_node_utils_fes "https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/utils/fes.py"
click node_node_docs "https://github.com/luigibonati/mlcolvar/tree/main/docs"
click node_node_tests "https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/tests"
click node_node_build "https://github.com/luigibonati/mlcolvar/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_core_nn,node_node_core_loss,node_node_core_stats,node_node_core_transform toneBlue
class node_node_cv_base,node_node_cv_unsup,node_node_cv_sup,node_node_cv_tica,node_node_cv_committor,node_node_cv_multitask,node_node_cv_generator toneAmber
class node_node_data toneMint
class node_node_explain,node_node_utils_io,node_node_utils_trainer,node_node_utils_fes toneRose
class node_node_mlcolvar_pkg,node_node_docs,node_node_tests,node_node_build,node_node_external,node_node_plumed toneIndigo
```

## Components

### Core ML

Reusable neural network, loss, statistics, and feature transform primitives.

- [Neural net](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/core/nn/feedforward.py): core.nn · Feed-forward network building blocks and helpers. · `mlcolvar/core/nn/feedforward.py`
- [Losses](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/core/loss): core.loss · Task losses for regression, TDA, LDA/Fisher, ELBO, committor, and generator objectives. · `mlcolvar/core/loss`
- [Stats](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/core/stats): core.stats · Classical linear methods and slow-mode analysis tools such as PCA, LDA, and TICA. · `mlcolvar/core/stats`
- [Transforms](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/core/transform): core.transform · 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](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/cv.py): cvs.base · Shared CV interface and common model behavior. · `mlcolvar/cvs/cv.py`
- [Unsupervised](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/cvs/unsupervised): cvs.unsupervised · Autoencoder and variational autoencoder CVs. · `mlcolvar/cvs/unsupervised`
- [Supervised](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/cvs/supervised): cvs.supervised · Regression, DeepLDA, and DeepTDA models. · `mlcolvar/cvs/supervised`
- [DeepTICA](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/timelagged/deeptica.py): cvs.timelagged · Time-lagged CV model for slow collective modes. · `mlcolvar/cvs/timelagged/deeptica.py`
- [Committor](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/committor/committor.py): cvs.committor · Committor-based CV construction and training. · `mlcolvar/cvs/committor/committor.py`
- [MultiTask](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/multitask/multitask.py): cvs.multitask · Combined-objective CV models. · `mlcolvar/cvs/multitask/multitask.py`
- [Generator](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/cvs/generator/generator.py): cvs.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](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/data): data · Dataset, dataloader, and Lightning datamodule abstractions. · `mlcolvar/data`

### Support

Interpretability and utility modules that support training and analysis.

- [Explain](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/explain): interpretability · Feature relevance analysis via LASSO and sensitivity methods. · `mlcolvar/explain`
- [IO & Lag](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/utils/io.py): utils.io/timelagged · File loading, dataset creation, and time-lagged sample helpers. · `mlcolvar/utils/io.py`
- [Trainer](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/utils/trainer.py): utils.trainer · Lightning training helpers and callbacks. · `mlcolvar/utils/trainer.py`
- [FES](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/utils/fes.py): utils.fes · Free-energy surface estimation utilities. · `mlcolvar/utils/fes.py`

### Repo Surface

Package entry points, docs, tests, and release infrastructure.

- [mlcolvar](https://github.com/luigibonati/mlcolvar/blob/main/mlcolvar/__init__.py): python package · Top-level package namespace and public entry point. · `mlcolvar/__init__.py`
- [Docs](https://github.com/luigibonati/mlcolvar/tree/main/docs): documentation · API reference, tutorials, notebooks, and usage guides. · `docs`
- [Tests](https://github.com/luigibonati/mlcolvar/tree/main/mlcolvar/tests): test suite · Component-level tests mirroring package structure. · `mlcolvar/tests`
- [Build & CI](https://github.com/luigibonati/mlcolvar/blob/main/pyproject.toml): packaging/ci · Project metadata, packaging, and automation workflows. · `pyproject.toml`
- **PyTorch/Lightning**: external runtime · Primary tensor and training runtime dependencies.
- **PLUMED**: external integration · Simulation-time integration target for trained CV models.

## Connections

- 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.
