faster-diffbloch

Drop-in Apple Silicon Metal GPU and optimized CPU acceleration for diffBloch electron crystallography structure refinement.

Up to 1.80× faster than PyTorch CPU in measured end-to-end forward-plus-backward benchmarks, with a Metal GPU path for Apple Silicon and an optimized CPU path for macOS and Linux.

Operating System and Platform Support

Runtime platform guards automatically detect your operating system and hardware configuration. When device="gpu" is requested on Linux, faster-diffbloch automatically selects the optimized CPU backend with an informative warning.

Why faster-diffBloch?

faster-diffbloch keeps the diffBloch workflow and public API intact while moving the expensive propagation and gradient work onto an accelerated native backend. You get the same scientific calculation, with a faster path on supported hardware and a safe PyTorch fallback when the native backend is unavailable.

The package is validated against the diffBloch test suite and reference results. It passes all 738 diffBloch tests, 55 additional conformance tests, and reproduces the experimental quartz refinement result.

Performance

End-to-end forward-plus-backward timing on an Apple M4 Max, measured across the same diffBloch workload at different beam counts:

That is 1.41×–1.80× faster than PyTorch CPU across the measured cases, including the largest 579-beam case. The same benchmark is 1.21× faster than the Mojo reference at 31 beams, remains ahead through 163 beams, and is essentially level at 579 beams.

On Apple Silicon, the Metal GPU path is also available. In the package's M4 Max comparison run at 579 beams, it measured 2.24× faster than PyTorch CPU for the forward pass and 2.63× faster than PyTorch MPS for forward plus backward.

These figures are workload benchmarks, not a promise that every crystal, hardware configuration, or beam count will see the same result. The CPU table uses single-threaded PyTorch and the same Apple Accelerate environment for a like-for-like comparison.

Package benchmark snapshot

Installation

pip install faster-diffbloch

Usage

1. Drop-in CLI

Use diffbloch-fast or faster-diffbloch anywhere you would use diffbloch:

diffbloch-fast infer examples/Colmey_et_al_2026/data/quartz-no-abs
diffbloch-fast refine examples/Colmey_et_al_2026/data/quartz-no-abs

2. Python API Injection

Enable acceleration inside any existing diffBloch script:

import faster_diffbloch

# Enable Metal GPU acceleration (macOS Apple Silicon)
faster_diffbloch.enable(device="gpu")

# Or CPU acceleration (macOS and Linux)
faster_diffbloch.enable(device="cpu")

# Run standard diffBloch code
import diffBloch
# All propagate and matrix_exp calls now route through faster-diffBloch