Metadata-Version: 2.4
Name: diff-epr
Version: 0.1.0
Summary: Differentiable EPR distance distribution modeling in JAX
Author: George Elkins
License: MIT
Project-URL: Homepage, https://github.com/elkins/diff-epr
Project-URL: Repository, https://github.com/elkins/diff-epr
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax
Requires-Dist: jaxlib
Requires-Dist: numpy
Requires-Dist: biotite
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Dynamic: license-file

# 📻 diff-epr: Differentiable EPR/DEER Simulation in JAX

[![Tests](https://github.com/elkins/diff-epr/actions/workflows/test.yml/badge.svg)](https://github.com/elkins/diff-epr/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![JAX](https://img.shields.io/badge/backend-JAX-9cf.svg)](https://github.com/google/jax)

**diff-epr** provides differentiable kernels for simulating EPR distance distributions (DEER/PELDOR) from structural ensembles and spin-label rotamers.

---

## 🎯 Features

- **Spin-Label Modeling:** Differentiable distance calculations between paramagnetic centers.
- **Orientation Selection:** Support for the **Polyhach 5-angle formula** (Polyhach et al., 2007) to model relative domain orientations.
- **Time-Domain Simulation:** Simulate DEER modulation traces $V(t)$ with parameterizable background decay and modulation depth.
- **Rotamer Library Integration:** Support for weighted rotamer averages in distance distribution calculations.
- **Hardware Acceleration:** GPU-optimized distance kernels via JAX.

---

## 🏗️ Technical Architecture

- **Backend:** JAX (XLA-compiled).
- **Physics:** Dipolar coupling frequency ($\omega$) based kernels.
- **Performance:** $O(N)$ scaling for distance distribution integration.

---

## 🚀 Roadmap

- [x] Core DEER trace simulation kernels.
- [x] Background decay and modulation depth parameters.
- [ ] Integration with MMM (Multi-Scale Modeling of Macromolecules) rotamer libraries.
- [ ] Full orientation-dependence support.

---

## 🚀 Installation

```bash
pip install diff-epr
```

## 🧪 Scientific Validation

- **Dipolar Frequency Parity:** Coupling frequencies verified against the Pake pattern $1/r^3$ dependence.
- **Time-Domain Accuracy:** DEER traces validated for parity against standard simulation tools (e.g., DeerAnalysis/MMM).
- **Auto-Diff Gradients:** Differentiable distance-to-signal kernels verified with JAX `grad`.

---

## 🔗 Related Projects

diff-epr is part of the **differentiable biophysics** ecosystem:

- [diff-biophys](https://github.com/elkins/diff-biophys) — Core differentiable biophysics engine.
- [diff-hdx](https://github.com/elkins/diff-hdx) — Differentiable HDX-MS prediction.
- [diff-fret](https://github.com/elkins/diff-fret) — Differentiable FRET modeling.
- [synth-nmr](https://github.com/elkins/synth-nmr) — NMR observable simulation.

---

## 📖 Citation

```bibtex
@software{diff_epr,
  author  = {Elkins, George},
  title   = {diff-epr: Differentiable EPR/DEER simulation in JAX},
  year    = {2026},
  url     = {https://github.com/elkins/diff-epr},
  version = {0.1.0}
}
```

## ⚖️ License

MIT
