Metadata-Version: 2.4
Name: torchref
Version: 0.6.3
Summary: Pytorch based crystallographic refinement
Author: HansPeterSeidel
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.4.0,>=2.0.0
Requires-Dist: pandas<2.4.0,>=2.0.0
Requires-Dist: torch<2.14.0,>=2.4.0
Requires-Dist: tqdm<4.69.0,>=4.61.0
Requires-Dist: numba<0.67.0,>=0.59.0
Requires-Dist: gemmi<0.8.0,>=0.5.0
Requires-Dist: scipy<1.18.0,>=1.10.0
Requires-Dist: matplotlib<3.11.0,>=3.7.0
Requires-Dist: reciprocalspaceship<1.1.0,>=0.9.18
Requires-Dist: pyarrow<26.0.0,>=12.0.0
Requires-Dist: ninja>=1.10
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.12.0; extra == "dev"
Requires-Dist: black>=21.5b2; extra == "dev"
Requires-Dist: isort>=5.9.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Provides-Extra: alignment
Requires-Dist: jax>=0.4.0; extra == "alignment"
Requires-Dist: s2fft>=1.0.0; extra == "alignment"
Requires-Dist: s2ball>=0.0.2; extra == "alignment"
Requires-Dist: spherical>=1.0.0; extra == "alignment"
Requires-Dist: quaternionic>=1.0.0; extra == "alignment"
Provides-Extra: forcefield
Requires-Dist: torchmd-net>=2.0.0; extra == "forcefield"
Provides-Extra: amber
Requires-Dist: openmm>=8.0.0; extra == "amber"
Requires-Dist: pdbfixer; extra == "amber"
Provides-Extra: ihm
Requires-Dist: ihm>=1.0; extra == "ihm"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: numpydoc>=1.1.0; extra == "docs"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/torchref-banner-dark.svg">
    <img src="assets/torchref-banner-light.svg" alt="TorchRef" width="380">
  </picture>
</p>

<h1 align="center">A Py<ins>Torch</ins>-based crystallographic <ins>Ref</ins>inement library</h1>

<div align="center">

[![Tests](https://github.com/HatPdotS/TorchRef/actions/workflows/tests.yml/badge.svg)](https://github.com/HatPdotS/TorchRef/actions/workflows/tests.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.4+-ee4c2c.svg)](https://pytorch.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://readthedocs.org/projects/torchref/badge/?version=latest)](https://torchref.readthedocs.io/)
[![CUDA](https://img.shields.io/badge/CUDA-supported-76b900.svg)](https://developer.nvidia.com/cuda-zone)
[![Apple Silicon MPS](https://img.shields.io/badge/Apple%20Silicon-MPS-000000.svg?logo=apple)](https://developer.apple.com/metal/pytorch/)

</div>

TorchRef is a crystallographic refinement package built entirely on PyTorch. Autograd and GPU acceleration make it composable with machine-learning workflows and cheap to extend with new targets.

> **Scope.** TorchRef is mainly a library/framework to build and experiment with. It is not intended to replace mainline refinement programs for standard problems.

## Benchmark

![TorchRef AlphaFold-start refinement benchmark](paper/figure2_alphafold_start/figures/figure_af_benchmark.png)

*Refinement of Phaser-placed AlphaFold models against experimental data, on a conserved set of 723 PDB structures (1.40–3.00 Å). All engines start from the same placed models and are scored by one common validator (PHENIX).*

**(A)** R-work and R-free per engine. Median R-free 0.3197 (TorchRef), 0.3165 (PHENIX), 0.3136 (REFMAC5); paired median difference, TorchRef minus reference, +0.0006 against PHENIX and +0.0047 against REFMAC. **(B)** Geometry RMS Z against REFMAC restraints, ideal 1.0: bond 0.58 (REFMAC 0.58, PHENIX 0.83), main-chain B 1.56 (REFMAC 0.90, PHENIX 1.03). **(C)** Wall-clock runtime per structure on 4 CPU cores: median 0.77 min (REFMAC 0.25, PHENIX 3.09). **(D)** Fraction of the total R-free improvement reached per macrocycle.

## Key Features

- **Native PyTorch Integration**: Built on PyTorch's `nn.Module` architecture, so TorchRef composes with PyTorch models, optimizers, and devices.

- **Automatic Differentiation**: No hand-written gradients. Define a new refinement target's forward pass and PyTorch supplies the derivatives.

- **Modular Architecture**: Custom targets, restraints, and optimizers plug in without modifying core code.

- **GPU Acceleration**: CUDA for structure factors, scaling, and optimization. Apple Silicon works through PyTorch's MPS backend — unsupported ops fall back to CPU automatically via `PYTORCH_ENABLE_MPS_FALLBACK=1`, which TorchRef sets on import.

- **FFT-based Structure Factors**: F_calc via FFT, so large unit cells stay tractable.

## Getting Started

| Notebook | Description |
|----------|-------------|
| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/HatPdotS/TorchRef/blob/main/example_notebooks/quickstart.ipynb) | Quickstart — MTZ + PDB to refined structure, refined MTZ and CCP4 map; selection- and parameter-type-based refinement |
| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/HatPdotS/TorchRef/blob/main/example_notebooks/structure_factors.ipynb) | Structure factors — one-liner, `FFT` class, and manual voxel pipeline; standalone scaling; autograd |
| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/HatPdotS/TorchRef/blob/main/example_notebooks/targets_and_weighting.ipynb) | Targets and weighting — standard targets, target-offset weighting, X-ray mode comparison, custom targets, driving an optimizer from a `LossState` |

### Installation

```bash
pip install torchref
```

For development:

```bash
git clone --filter=blob:none --sparse https://github.com/HatPdotS/TorchRef.git
cd TorchRef
git sparse-checkout set torchref tests
pip install -e ".[dev]"
```

This fetches ~40 MB instead of ~436 MB; most of the repository is `paper/` history. Files outside
the checkout are fetched on demand, so add paths later with `git sparse-checkout add paper`, or
`git sparse-checkout disable` for all of it. Requires Git ≥ 2.27.

### Dependencies

Python ≥ 3.10, PyTorch ≥ 2.4, NumPy ≥ 2.0, Pandas ≥ 2.0, SciPy ≥ 1.10, Gemmi ≥ 0.5, reciprocalspaceship ≥ 0.9.18, Numba ≥ 0.59, Matplotlib ≥ 3.7. `pyproject.toml` carries the authoritative pinned ranges; upper bounds are set one minor version above the tested maximum, so a newer dependency will refuse to install rather than fail at runtime.

### Testing

```bash
pytest tests/                      # all tests
pytest tests/ --cov=torchref       # with coverage
pytest tests/unit/                 # fast unit tests only
```

Slow tests need `--run-slow`. Accelerator tests are not opt-in: they run wherever CUDA or MPS is available and are skipped when it is not.

### Contributing

Contributions are welcome. Please use [NumPy docstring style](https://numpydoc.readthedocs.io/en/latest/format.html), add tests for new functionality, and make sure the suite passes before submitting.

### License

MIT. See [LICENSE](LICENSE).
