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/


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

Prepare features — one file per trajectory, shape (n_frames, n_features):
```
features/
├── traj_0.npy
└── traj_1.pkl
```
Configure — edit examples/config.yaml (or create your own).
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 (forced for ensemble policy)
`ts_dar`	OOD-score frame selection via TS-DAR hyperspherical embeddings (Liu et al. 2025); no clustering (forced for ensemble policy)

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

adaptivepy_sampling-1.0.0.tar.gz (56.7 kB view details)

Uploaded Jul 31, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

adaptivepy_sampling-1.0.0-py3-none-any.whl (62.2 kB view details)

Uploaded Jul 31, 2026 Python 3

File details

Details for the file adaptivepy_sampling-1.0.0.tar.gz.

File metadata

Download URL: adaptivepy_sampling-1.0.0.tar.gz
Upload date: Jul 31, 2026
Size: 56.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for adaptivepy_sampling-1.0.0.tar.gz
Algorithm	Hash digest
SHA256	`2bbb9d6c99aab5e9f5c41ed5c72ca1c2ea5b22f8c6346b25b3ccbaed7ca5b4f1`
MD5	`f74ced0ce57b8a7f8c1092c7f2a666d6`
BLAKE2b-256	`298f9f13f711a3eb7b588fb5436d896d316003fc3ff06efc896872461cd4b33d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for adaptivepy_sampling-1.0.0.tar.gz:

Publisher: publish.yml on ShuklaGroup/AdaptivePy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: adaptivepy_sampling-1.0.0.tar.gz
- Subject digest: 2bbb9d6c99aab5e9f5c41ed5c72ca1c2ea5b22f8c6346b25b3ccbaed7ca5b4f1
- Sigstore transparency entry: 2305276750
- Sigstore integration time: Jul 31, 2026
Source repository:
- Permalink: ShuklaGroup/AdaptivePy@5bac380f8cd09537b530084a3099aac522b11b5c
- Branch / Tag: refs/tags/v1.0.0
- Owner: https://github.com/ShuklaGroup
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@5bac380f8cd09537b530084a3099aac522b11b5c
- Trigger Event: release