Metadata-Version: 2.4
Name: adaptivepy-sampling
Version: 0.1.2
Summary: Adaptive sampling on MD trajectories via clustering and policy-driven seed selection
Author: AdaptivePy Contributors
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
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
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"

# AdaptivePy

**Adaptive sampling for molecular dynamics trajectories**

Clustering-based state space partitioning and policy-driven seed selection for MD workflows.

[![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 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://hnadeem2.github.io/AdaptivePy/](https://hnadeem2.github.io/AdaptivePy/)

| | |
|---|---|
| **Input** | Feature arrays (`.npy` / `.pkl`), optional coordinate trajectories |
| **Clustering** | KMeans, MiniBatch KMeans, regular-space |
| **Policies** | Least counts, random (extensible) |
| **Output** | Seeds, cluster assignments, model, logs, optional PDBs |

## Installation

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

For development:

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

## 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")
```

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

## License

MIT
