AdaptivePy

Adaptive sampling for molecular dynamics trajectories

Clustering-based and frame-level adaptive policies for MD workflows, including entropy-based MaxEnt VAMPNet and OOD-based TS-DAR seed selection.

Overview

AdaptivePy helps you identify under-sampled or high-uncertainty regions of conformational space and select seed frames for new simulations. It loads per-trajectory feature arrays, optionally clusters frames, applies adaptive policies, and writes reproducible metadata and optional PDB structures.

Most policies select seeds from clusters. MaxEnt VAMPNet (maxent_vampnet) and TS-DAR (ts_dar) are frame-level: they train Torch models on lagged features and select scored frames directly — no clustering required.

Full documentation: https://shuklagroup.github.io/AdaptivePy/

Installation

pip install adaptivepy-sampling

For Torch-backed policies such as MaxEnt VAMPNet and TS-DAR:

pip install adaptivepy-sampling[torch]

For development:

git clone https://github.com/shuklagroup/AdaptivePy.git
cd AdaptivePy
pip install -e ".[dev,docs]"

For Torch-backed policy development:

pip install -e ".[dev,docs,torch]"

Quick start

1. Prepare features — one file per trajectory, shape (n_frames, n_features):

   features/
   ├── traj_0.npy
   └── traj_1.pkl
   

2. Configure — edit examples/config.yaml (or create your own).

3. Run:

   adaptivepy run examples/config.yaml
   

See the Getting Started guide for a complete walkthrough.

CLI

adaptivepy run config.yaml       # run adaptive sampling
adaptivepy validate config.yaml  # validate inputs only
adaptivepy list-policies         # list available policies

Python API

from adaptivepy import run_adaptive_sampling

results = run_adaptive_sampling("config.yaml")

Policies

Built-in seed-selection policies:

fast, ma_reap, knn_as, maxent_vampnet, and ts_dar accept extra YAML under policy_params. MA-REAP requires mapping each trajectory to an agent. Torch-backed policies require the [torch] install extra (pip install adaptivepy-sampling[torch]). See the Policies guide and Configuration.

AdaptivePy also supports opt-in metapolicy ensembles with majority polling or per-policy seed allocation through the metapolicy YAML block.

Documentation

Contributors

• Hassan Nadeem
• Diego E. Kleiman

License

MIT. See LICENSE for details.