Metadata-Version: 2.4
Name: adaptivepy-sampling
Version: 0.2.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"
Dynamic: license-file

# 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, FAST, MA-REAP (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 |

## Contributors

- Hassan

## License

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