Metadata-Version: 2.5
Name: faster-diffbloch
Version: 0.1.5
Summary: Drop-in Metal GPU (macOS) and optimized CPU (macOS/Linux) acceleration for diffBloch
Project-URL: Homepage, https://godofecht.github.io/diffFlow/
Project-URL: Documentation, https://godofecht.github.io/diffFlow/
Project-URL: Repository, https://github.com/godofecht/diffFlow
Project-URL: Issues, https://github.com/godofecht/diffFlow/issues
Project-URL: PyPI, https://pypi.org/project/faster-diffbloch/
Project-URL: piwheels, https://www.piwheels.org/project/faster-diffbloch/
Project-URL: Original diffBloch, https://diffbloch.com
Author-email: Abhishek Shivakumar <abhishek.shivakumar@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: Metal GPU,PyTorch acceleration,diffBloch,electron crystallography,electron diffraction,structure refinement
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
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 :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: torch>=2.0
Provides-Extra: diffbloch
Requires-Dist: diffbloch; extra == 'diffbloch'
Description-Content-Type: text/markdown

# faster-diffbloch

Drop-in Apple Silicon Metal GPU and optimized CPU acceleration for [diffBloch](https://diffbloch.com) 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.

| Package | Documentation | Source repository | Original project |
| :--- | :--- | :--- | :--- |
| [PyPI](https://pypi.org/project/faster-diffbloch/) · [piwheels](https://www.piwheels.org/project/faster-diffbloch/) | [diffFlow documentation and benchmarks](https://godofecht.github.io/diffFlow/) | [github.com/godofecht/diffFlow](https://github.com/godofecht/diffFlow) | [diffbloch.com](https://diffbloch.com) |

---

## Operating System and Platform Support

| Operating System / Hardware | CPU Acceleration (`device="cpu"`) | GPU Acceleration (`device="gpu"`) | Backend Runtime |
| :--- | :---: | :---: | :--- |
| **macOS Apple Silicon (M1/M2/M3/M4/Max/Ultra)** | **Supported** | **Supported** | Native Metal Compute Shaders + Apple Accelerate BLAS |
| **macOS Intel (x86_64)** | **Supported** | Fallback to CPU | Apple Accelerate BLAS |
| **Linux (x86_64 / aarch64)** | **Supported** | Fallback to CPU | OpenBLAS / C11 BLAS |
| **Windows** | PyTorch Reference | PyTorch Reference | Pure PyTorch Reference Fallback |

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.

| Beams | faster-diffbloch | PyTorch | Speedup |
| :---: | :---: | :---: | :---: |
| 31 | 1.48 ms | 1.54 ms | 1.05x |
| 61 | 1.93 ms | 2.07 ms | 1.07x |
| 91 | 3.48 ms | 3.69 ms | 1.06x |
| 163 | 8.76 ms | 10.14 ms | 1.16x |

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:

| Implementation | Forward + Backward |
| :--- | :---: |
| PyTorch | 117.21 ms |
| Mojo port | 85.52 ms |
| Flow port, C backend | 82.84 ms |
| Flow port, MLIR backend | 79.74 ms |

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](https://godofecht.github.io/diffFlow/).

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

| Implementation | Forward | Forward + Backward | Speedup vs PyTorch CPU | Speedup vs PyTorch MPS |
| :--- | :---: | :---: | :---: | :---: |
| PyTorch CPU | 25.7 ms | 130.3 ms | 1.00x | 1.17x |
| PyTorch MPS (fallback) | 26.2 ms | 153.0 ms | 0.85x | 1.00x |
| **faster-diffBloch CPU** | **24.4 ms** | **83.5 ms** | **1.56x** | **1.83x** |
| **faster-diffBloch Metal GPU** | **13.1 ms** | **58.1 ms** | **2.24x** | **2.63x** |

---

## Installation

```bash
pip install faster-diffbloch
```

---

## Usage

### 1. Drop-in CLI

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

```bash
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:

```python
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
```
