AdaptivePy

Adaptive sampling for molecular dynamics trajectories

Adaptive sampling for MD workflows via clustering and policy-driven 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, clusters frames, applies adaptive policies, and writes reproducible metadata and optional PDB structures.

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

Input	Feature arrays (.npy / .pkl), optional coordinate trajectories
Clustering	KMeans, MiniBatch KMeans, regular-space
Policies	Least counts, random, FAST, MA-REAP, kNN-AS, MaxEnt VAMPNet, TS-DAR (extensible)
Output	Seeds, cluster assignments, model, logs, policy scores, optional PDBs

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

fromadaptivepyimportrun_adaptive_samplingresults=run_adaptive_sampling("config.yaml")

Policies

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 (clustering is forced when they participate in a metapolicy ensemble).

Policy	Use case
least_counts	Target under-sampled clusters
random	Baseline random sampling
fast	Goal-directed sampling via feature columns (Zimmerman & Bowman 2015)
ma_reap	Multi-agent coordinated sampling with learned CV weights (Kleiman & Shukla 2022)
knn_as	k-nearest-neighbors adaptive sampling over cluster representatives (Rovers et al. 2025)
maxent_vampnet	Entropy-based frame selection via VAMPNet soft state assignments (Kleiman & Shukla 2023)
ts_dar	OOD-score frame selection via TS-DAR hyperspherical embeddings (Liu et al. 2025)

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

Guide	Description
Getting Started	First run in minutes
Configuration	YAML options and defaults
Feature Inputs	File formats and layout
Policies	Seed selection strategies
API Reference	Module documentation

Contributors

• Hassan Nadeem
• Diego E. Kleiman

License

MIT. See LICENSE for details.