Metadata-Version: 2.4
Name: torchref
Version: 0.7.0
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: 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: torchref-kernels<0.2,>=0.1.0; (sys_platform == "linux" and (platform_machine == "x86_64" or platform_machine == "aarch64")) or (sys_platform == "darwin" and platform_machine == "arm64") or (sys_platform == "win32" and platform_machine == "AMD64")
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: ruff>=0.1.0; extra == "dev"
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: parmed; 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"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/HatPdotS/TorchRef/main/assets/torchref-banner-dark.svg">
    <img src="https://raw.githubusercontent.com/HatPdotS/TorchRef/main/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/)
[![Forum](https://img.shields.io/badge/Forum-rs--station-0088CC.svg?logo=discourse&logoColor=white)](https://discourse.rs-station.org/c/software/torchref/54)
[![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](https://raw.githubusercontent.com/HatPdotS/TorchRef/main/assets/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.3189 (TorchRef), 0.3164 (PHENIX), 0.3136 (REFMAC5); paired median difference, TorchRef minus reference, +0.0008 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.55 (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, `SfFFT` class, and manual voxel pipeline; 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, static group weights, 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 kernels
pip install ./kernels        # the prebuilt CPU kernels; needs a Rust toolchain (rustup.rs)
pip install -e ".[dev]"
```

Skipping `pip install ./kernels` is fine when the published `torchref-kernels` wheel
matches the checkout; pip then installs it from PyPI. Rebuild after editing anything in
`kernels/`.

This fetches ~40 MB instead of the full history (~800 MB, mostly test data and the paper
figures that lived in `paper/` before v0.7.0). Files outside the checkout are fetched on demand,
so add paths later with `git sparse-checkout add docs`, 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, 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.

Questions, feature ideas and usage discussion are welcome on the [TorchRef category of the rs-station forum](https://discourse.rs-station.org/c/software/torchref/54).

### Citing

If you use TorchRef in published work, please cite

> Seidel, H.-P., Standfuss, J. & Weinert, T. (2026). *TorchRef: An open-source PyTorch
> Framework for Crystallographic Refinement.* Journal of Applied Crystallography, accepted.

The figure scripts, per-panel source data and the author accepted manuscript are in
[HatPdotS/TorchRef-paper](https://github.com/HatPdotS/TorchRef-paper).

### License

MIT. See [LICENSE](https://github.com/HatPdotS/TorchRef/blob/main/LICENSE).
