faster-diffbloch

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

A Metal GPU path for Apple Silicon and an optimized CPU path for macOS and Linux, measured against diffBloch running on PyTorch.

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 diffBloch's own test suite. With acceleration enabled it passes all 738 diffBloch tests and 55 conformance tests that compare the accelerated results against diffBloch's, field by field, including gradients. The diffBloch run makes 4855 calls into the native matrix exponential, so the accelerated path is exercised rather than skipped.

It also reproduces the published quartz result. Running diffbloch-fast infer over the 99-rotation Colmey et al. 2026 quartz dataset through the Metal path scores every rotation and gives a mean R_obs of 0.0485, against the 0.0486 the example documents.

Performance

Forward-plus-backward timing on an Apple M4 Max, single-threaded PyTorch, running the same diffBloch workload through bench/compare_faster.py. This is what pip install faster-diffbloch gives you: the accelerated matrix exponential bridged into diffBloch, with PyTorch handling everything else.

Best of three alternating runs per mode. The gain grows with beam count, because the matrix exponential takes a larger share of the work as the system grows and the fixed ctypes and PyTorch overhead matters less.

The standalone Flow port

The diffFlow repository also holds a standalone port of the whole calculation, compiled from Flow rather than bridged into PyTorch. It avoids the framework overhead entirely and is considerably faster. At 579 beams, forward plus backward, minimum of five runs:

Those numbers are not what this package delivers. They are reachable by running the port directly, and they are why the package exists. See the diffFlow documentation.

These figures come from one workload on one machine. Other crystals, hardware configurations and beam counts will differ.

Metal GPU

The Metal path is available on Apple Silicon through enable(device="gpu"). Correctness on this path is checked: the quartz reproduction above runs through it. The timings below come from an earlier run and have not been reproduced against the current package, so treat those as indicative.

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