Metadata-Version: 2.4
Name: adaptivepy-sampling
Version: 0.3.0
Summary: Adaptive sampling on MD trajectories via clustering and policy-driven seed selection
Author: Hassan
License: MIT License
        
        Copyright (c) 2026 Hassan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scikit-learn>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0
Requires-Dist: joblib>=1.0
Requires-Dist: mdtraj>=1.9
Requires-Dist: scipy>=1.7
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: maxent
Requires-Dist: deeptime>=0.4; extra == "maxent"
Requires-Dist: torch>=2.0; extra == "maxent"
Dynamic: license-file

# AdaptivePy

**Adaptive sampling for molecular dynamics trajectories**

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

[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue?style=for-the-badge)](https://hnadeem2.github.io/AdaptivePy/)
[![PyPI](https://img.shields.io/badge/PyPI-adaptivepy--sampling-orange?style=for-the-badge)](https://pypi.org/project/adaptivepy-sampling/)
[![Python](https://img.shields.io/badge/python-3.9+-green?style=for-the-badge)](https://www.python.org/)

---

## 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/](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

```bash
pip install adaptivepy-sampling
```

For **MaxEnt VAMPNet** (requires PyTorch and deeptime):

```bash
pip install adaptivepy-sampling[maxent]
```

For development:

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

For MaxEnt development:

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

## Quick start

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

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

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

3. **Run**:

   ```bash
   adaptivepy run examples/config.yaml
   ```

See the [Getting Started guide](https://hnadeem2.github.io/AdaptivePy/getting-started/) for a complete walkthrough.

## CLI

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

## Python API

```python
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](https://hnadeem2.github.io/AdaptivePy/policies/) and
[Configuration](https://hnadeem2.github.io/AdaptivePy/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](https://hnadeem2.github.io/AdaptivePy/getting-started/) | First run in minutes |
| [Configuration](https://hnadeem2.github.io/AdaptivePy/configuration/) | YAML options and defaults |
| [Feature Inputs](https://hnadeem2.github.io/AdaptivePy/features/) | File formats and layout |
| [Policies](https://hnadeem2.github.io/AdaptivePy/policies/) | Seed selection strategies |
| [API Reference](https://hnadeem2.github.io/AdaptivePy/reference/api/) | Module documentation |

## Contributors

- Hassan

## License

MIT. See [LICENSE](LICENSE) for details.
