faster-diffbloch 0.1.1__tar.gz → 0.1.2__tar.gz

{faster_diffbloch-0.1.1 → faster_diffbloch-0.1.2}/PKG-INFO

@@ -1,14 +1,18 @@
 Metadata-Version: 2.5
 Name: faster-diffbloch
-Version: 0.1.1
+Version: 0.1.2
 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@example.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
@@ -27,13 +31,15 @@ Provides-Extra: diffbloch
 Requires-Dist: diffbloch; extra == 'diffbloch'
 Description-Content-Type: text/markdown
 
-# faster-diffBloch
+# faster-diffbloch
 
 Drop-in Apple Silicon Metal GPU and optimized CPU acceleration for [diffBloch](https://diffbloch.com) electron crystallography structure refinement.
 
-Documentation and comparison benchmarks: [https://godofecht.github.io/diffFlow/](https://godofecht.github.io/diffFlow/)
+**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.
 
-Original diffBloch project: [https://diffbloch.com](https://diffbloch.com)
+| 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) |
 
 ---
 
@@ -52,20 +58,45 @@ Runtime platform guards automatically detect your operating system and hardware
 
 ## Why faster-diffBloch?
 
-1. **Native Metal GPU Execution on macOS:**
-   PyTorch MPS lacks a native GPU kernel for `aten::linalg_matrix_exp`, which causes PyTorch to fall back to CPU execution with host-device memory transfers. `faster-diffBloch` executes matrix exponentials directly on Apple Silicon Metal with zero-copy unified memory.
+`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.
 
-2. **Blocked-Pair Adjoint Formulation:**
-   Standard matrix exponential autograd embeds the operator into a $2N \times 2N$ block matrix, costing $8 \times N^3$ FLOPs. `faster-diffBloch` evaluates the pullback in the block-triangular pair algebra $(Y_a Y_b, Y_a L_b + L_a Y_b)$, reducing the work to $3 \times N^3$ FLOPs (2.67x fewer products).
-
-3. **Bit-for-Bit Validation:**
-   Passes all 738 unit tests in diffBloch and reproduces the experimental 99-rotation quartz dataset ($R_{\text{obs}} = 0.0486$).
+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
 
-Forward and backward timing comparison on Apple Silicon (M4 Max) at $N=579$ beams (CsPbBr3 scale):
+End-to-end forward-plus-backward timing on an Apple M4 Max, measured across the
+same diffBloch workload at different beam counts:
+
+| Beams | faster-diffBloch | PyTorch | Speedup |
+| :---: | :---: | :---: | :---: |
+| 31 | 0.90 ms | 1.62 ms | **1.80×** |
+| 61 | 1.37 ms | 2.24 ms | **1.63×** |
+| 91 | 2.84 ms | 3.99 ms | **1.41×** |
+| 163 | 7.67 ms | 10.98 ms | **1.43×** |
+| 579 | 89.81 ms | 135.77 ms | **1.51×** |
+
+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
 
 | Implementation | Forward | Forward + Backward | Speedup vs PyTorch CPU | Speedup vs PyTorch MPS |
 | :--- | :---: | :---: | :---: | :---: |

faster_diffbloch-0.1.2/README.md

@@ -0,0 +1,112 @@
+# faster-diffbloch
+
+Drop-in Apple Silicon Metal GPU and optimized CPU acceleration for [diffBloch](https://diffbloch.com) 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.
+
+| 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 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:
+
+| Beams | faster-diffBloch | PyTorch | Speedup |
+| :---: | :---: | :---: | :---: |
+| 31 | 0.90 ms | 1.62 ms | **1.80×** |
+| 61 | 1.37 ms | 2.24 ms | **1.63×** |
+| 91 | 2.84 ms | 3.99 ms | **1.41×** |
+| 163 | 7.67 ms | 10.98 ms | **1.43×** |
+| 579 | 89.81 ms | 135.77 ms | **1.51×** |
+
+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
+
+| 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
+```

{faster_diffbloch-0.1.1 → faster_diffbloch-0.1.2}/pyproject.toml

@@ -4,10 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "faster-diffbloch"
-version = "0.1.1"
+version = "0.1.2"
 description = "Drop-in Metal GPU (macOS) and optimized CPU (macOS/Linux) acceleration for diffBloch"
 readme = "README.md"
 requires-python = ">=3.10"
+keywords = ["diffBloch", "electron diffraction", "electron crystallography", "structure refinement", "PyTorch acceleration", "Metal GPU"]
 license = "MIT"
 authors = [
     { name = "Abhishek Shivakumar", email = "abhishek@example.com" }
@@ -41,8 +42,11 @@ diffbloch-fast = "faster_diffbloch.cli:main"
 
 [project.urls]
 Homepage = "https://godofecht.github.io/diffFlow/"
+Documentation = "https://godofecht.github.io/diffFlow/"
 Repository = "https://github.com/godofecht/diffFlow"
 Issues = "https://github.com/godofecht/diffFlow/issues"
+PyPI = "https://pypi.org/project/faster-diffbloch/"
+piwheels = "https://www.piwheels.org/project/faster-diffbloch/"
 "Original diffBloch" = "https://diffbloch.com"
 
 [tool.hatch.build.targets.wheel]

{faster_diffbloch-0.1.1 → faster_diffbloch-0.1.2}/src/faster_diffbloch/__init__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from .backend import enable, disable, matrix_exp, matrix_exp_backward, faster_propagate
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __all__ = [
     "enable",
     "disable",

{faster_diffbloch-0.1.1 → faster_diffbloch-0.1.2}/src/faster_diffbloch/backend.py

@@ -46,15 +46,15 @@ def matrix_exp(a: np.ndarray, device: str = "gpu") -> np.ndarray:
         fn = getattr(lib, "bridge_matrix_exp_gpu_ptr_c64_i32_i32_ptr_c64", None)
         if fn:
             fn.argtypes = [ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.c_void_p]
-            fn.restype = None
-            fn(ptr_in, batch, n, ptr_out)
-            return out
+            fn.restype = ctypes.c_int32
+            if fn(ptr_in, n, batch, ptr_out) == 0:
+                return out
 
     fn = getattr(lib, "bridge_matrix_exp_ptr_c64_i32_i32_ptr_c64", None)
     if fn:
         fn.argtypes = [ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.c_void_p]
         fn.restype = None
-        fn(ptr_in, batch, n, ptr_out)
+        fn(ptr_in, n, batch, ptr_out)
         return out
 
     return torch.matrix_exp(torch.from_numpy(a)).numpy()
@@ -63,10 +63,13 @@ def matrix_exp(a: np.ndarray, device: str = "gpu") -> np.ndarray:
 def matrix_exp_backward(a: np.ndarray, ebar: np.ndarray, dense: bool = False, device: str = "gpu") -> np.ndarray:
     lib = get_library()
     if lib is None:
-        tA = torch.from_numpy(a).requires_grad_(True)
-        tE = torch.matrix_exp(tA)
-        tE.backward(torch.from_numpy(ebar))
-        return tA.grad.numpy()
+        # Custom autograd.Function backward methods run with grad mode disabled.
+        # Re-enable it for the correctness fallback.
+        with torch.enable_grad():
+            tA = torch.from_numpy(a).requires_grad_(True)
+            tE = torch.matrix_exp(tA)
+            tE.backward(torch.from_numpy(ebar))
+            return tA.grad.numpy()
 
     a_c = np.ascontiguousarray(a, dtype=np.complex64)
     ebar_c = np.ascontiguousarray(ebar, dtype=np.complex64)
@@ -83,15 +86,15 @@ def matrix_exp_backward(a: np.ndarray, ebar: np.ndarray, dense: bool = False, de
         fn = getattr(lib, "bridge_matrix_exp_backward_gpu_ptr_c64_ptr_c64_i32_i32_i32_ptr_c64", None)
         if fn:
             fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.c_int32, ctypes.c_void_p]
-            fn.restype = None
-            fn(ptr_a, ptr_ebar, dense_val, batch, n, ptr_out)
-            return out
+            fn.restype = ctypes.c_int32
+            if fn(ptr_a, ptr_ebar, n, batch, dense_val, ptr_out) == 0:
+                return out
 
     fn = getattr(lib, "bridge_matrix_exp_backward_ptr_c64_ptr_c64_i32_i32_i32_ptr_c64", None)
     if fn:
         fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.c_int32, ctypes.c_void_p]
         fn.restype = None
-        fn(ptr_a, ptr_ebar, dense_val, batch, n, ptr_out)
+        fn(ptr_a, ptr_ebar, n, batch, dense_val, ptr_out)
         return out
 
     tA = torch.from_numpy(a).requires_grad_(True)

faster_diffbloch-0.1.1/README.md

@@ -1,85 +0,0 @@
-# faster-diffBloch
-
-Drop-in Apple Silicon Metal GPU and optimized CPU acceleration for [diffBloch](https://diffbloch.com) electron crystallography structure refinement.
-
-Documentation and comparison benchmarks: [https://godofecht.github.io/diffFlow/](https://godofecht.github.io/diffFlow/)
-
-Original diffBloch project: [https://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?
-
-1. **Native Metal GPU Execution on macOS:**
-   PyTorch MPS lacks a native GPU kernel for `aten::linalg_matrix_exp`, which causes PyTorch to fall back to CPU execution with host-device memory transfers. `faster-diffBloch` executes matrix exponentials directly on Apple Silicon Metal with zero-copy unified memory.
-
-2. **Blocked-Pair Adjoint Formulation:**
-   Standard matrix exponential autograd embeds the operator into a $2N \times 2N$ block matrix, costing $8 \times N^3$ FLOPs. `faster-diffBloch` evaluates the pullback in the block-triangular pair algebra $(Y_a Y_b, Y_a L_b + L_a Y_b)$, reducing the work to $3 \times N^3$ FLOPs (2.67x fewer products).
-
-3. **Bit-for-Bit Validation:**
-   Passes all 738 unit tests in diffBloch and reproduces the experimental 99-rotation quartz dataset ($R_{\text{obs}} = 0.0486$).
-
----
-
-## Performance
-
-Forward and backward timing comparison on Apple Silicon (M4 Max) at $N=579$ beams (CsPbBr3 scale):
-
-| 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
-```