Skip to content

Getting Started

This guide walks through a minimal feature-only run using the bundled example configuration.

1. Install AdaptivePy

pip install adaptivepy-sampling

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

pip install adaptivepy-sampling[torch]

For local 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]"

2. Prepare feature files

Create one feature file per trajectory in a directory:

features/
├── traj_0.npy   # shape (n_frames, n_features)
├── traj_1.npy
└── ...

Each array must be 2D: rows are frames, columns are features. See Feature Inputs for .pkl support and validation rules.

Generate synthetic example data:

python examples/generate_data.py

3. Create a configuration file

Use examples/config.yaml as a template:

features_dir: examples/data/features
output_dir: examples/results

clustering:
  method: kmeans
  n_clusters: 5

policies:
  - least_counts
  - random

n_seeds: 3
random_seed: 42
write_pdbs: false

4. Validate inputs (optional)

adaptivepy validate examples/config.yaml

5. Run adaptive sampling

adaptivepy run examples/config.yaml

6. Inspect results

After a successful run, output_dir contains shared clustering artifacts plus one subdirectory per policy:

results/
├── assignments.npy
├── cluster_model.pkl
├── metadata.csv
├── run_config.yaml
├── logs.txt
├── least_counts/
│   ├── seeds.csv
│   └── metadata.csv
├── random/
│   ├── seeds.csv
│   └── metadata.csv
└── combined_metadata.csv

When using fast, ma_reap, or knn_as, those policies add their own subdirectories with extra score sidecars. MaxEnt VAMPNet and TS-DAR write per-frame scores.csv and skip clustering when used alone — see Outputs.

See Outputs for a full description of each file.

Next steps

  • Add coordinate trajectories and topology for PDB export — see Configuration
  • Compare policies — see Policies (least_counts, random, fast, ma_reap, knn_as, maxent_vampnet, ts_dar)
  • Use goal-oriented sampling with fast, multi-agent ma_reap, entropy-based maxent_vampnet, or OOD-based ts_dar — see Configuration and Policies
  • Integrate into a pipeline — see Python API