Metadata-Version: 2.4
Name: pystarc
Version: 1.1.0
Summary: PySTARC - Python Simulation Toolkit for Association Rate Constants
Author: PySTARC Contributors
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: click>=8.0
Requires-Dist: pdb2pqr>=3.5
Requires-Dist: numba>=0.57
Requires-Dist: matplotlib>=3.7
Requires-Dist: pytest>=7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Provides-Extra: notebook
Requires-Dist: jupyter; extra == "notebook"
Requires-Dist: matplotlib; extra == "notebook"
Dynamic: license-file

[![CI](https://github.com/anandojha/PySTARC/actions/workflows/ci.yml/badge.svg)](https://github.com/anandojha/PySTARC/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/anandojha/PySTARC/graph/badge.svg)](https://codecov.io/gh/anandojha/PySTARC) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![CUDA](https://img.shields.io/badge/CUDA-12%2B-green.svg)](https://developer.nvidia.com/cuda-toolkit)

# PySTARC - Python Simulation Toolkit for Association Rate Constants

**PySTARC** computes bimolecular association rate constants (k<sub>on</sub>) via GPU-accelerated rigid-body Brownian dynamics.

## Features

- **GPU batch simulation** - All trajectories run simultaneously on GPU via CuPy.
- **Physics** - Ermak-McCammon integrator, RPY hydrodynamics, Born desolvation, APBS electrostatics, adaptive time step, and Yukawa monopole fallback.
- **Brownian bridge** - Catches mid-step reaction crossings.
- **Multi-GPU workflow** - Split simulations across N GPUs with automatic grid generation, symlinked DX files, and pooled result combining.
- **Automated system setup** - From a PDB and topology file to a ready-to-run simulation in one command via `setup.py`.
- **Convergence analysis** - Wilson score CI, relative SE, and trajectory-count estimates for target precision.
- **Output files** - 14 structured files, including trajectories, encounters, radial density, angular maps, and transition matrices.
- **Checkpointing** - Automatic save/resume for long production runs.
- **Live progress** - k<sub>on</sub> and P<sub>rxn</sub> printed at configurable intervals.
- **Temperature scaling** - Correct thermodynamics at any temperature.

## Installation

**GPU (Linux/HPC):**
```bash
git clone https://github.com/anandojha/PySTARC.git
cd PySTARC
bash install_PySTARC.sh
```

**On Mac/CPU:**
```bash
git clone https://github.com/anandojha/PySTARC.git
cd PySTARC
conda create -n PySTARC python=3.11 -y
conda activate PySTARC
conda install -c conda-forge ambertools apbs -y
pip install matplotlib pdb2pqr
pip install dist/pystarc-1.1.0-py3-none-any.whl --force-reinstall
```

## Testing

```bash
python -m pytest tests/ -v          
```

## Quick start

```bash
conda activate PySTARC
module load cuda                # HPC only, skip on local machines
cd examples/two_charged_spheres
chmod +x run.sh
bash run.sh
```

## Examples

See `examples/README.md` for complete instructions.

## License

MIT

## Citation

When using PySTARC, please cite:

Ojha, A. A. et al. PySTARC: GPU-accelerated Brownian dynamics for bimolecular association rate constants (2026).

## Requirements

- Python 3.11+
- AmberTools (tleap, cpptraj, ambpdb)
- APBS
- CuPy (GPU) or NumPy (CPU fallback)
- NVIDIA GPU with CUDA 12+ (recommended)
