adaptivepy-sampling 0.3.0

Adaptive sampling on MD trajectories via clustering and policy-driven seed selection

AdaptivePy

Adaptive sampling for molecular dynamics trajectories

Clustering-based and frame-level adaptive policies for MD workflows, including entropy-based MaxEnt VAMPNet 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) is frame-level: it trains a VAMPNet on lagged features and selects frames with the highest Shannon entropy of softmax state probabilities — no clustering required.

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

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

Installation

pip install adaptivepy-sampling

For MaxEnt VAMPNet (requires PyTorch and deeptime):

pip install adaptivepy-sampling[maxent]

For development:

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

For MaxEnt development:

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

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:

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); no clustering

fast, ma_reap, knn_as, and maxent_vampnet accept extra YAML under policy_params. MA-REAP requires mapping each trajectory to an agent. MaxEnt VAMPNet requires the [maxent] install extra (pip install adaptivepy-sampling[maxent]). 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

License

MIT. See LICENSE for details.