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

faster_diffbloch-0.1.2/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: faster-diffbloch
+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
+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.
+
+**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.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.0 → faster_diffbloch-0.1.2}/pyproject.toml

@@ -4,10 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "faster-diffbloch"
-version = "0.1.0"
-description = "Drop-in Metal GPU and CPU acceleration for diffBloch electron crystallography"
+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" }
@@ -16,6 +17,9 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -38,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.0 → 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.0 → faster_diffbloch-0.1.2}/src/faster_diffbloch/backend.py

@@ -3,17 +3,25 @@
 from __future__ import annotations
 
 import ctypes
+import warnings
 from typing import Literal
 import numpy as np
 import torch
 
-from .builder import build_and_load_library
+from .builder import (
+    build_and_load_library,
+    has_metal_support,
+    is_apple_silicon,
+    is_linux,
+    is_macos,
+    is_windows,
+)
 
 _LIB: ctypes.CDLL | None = None
 _CURRENT_DEVICE: Literal["cpu", "gpu"] = "gpu"
 
 
-def get_library() -> ctypes.CDLL:
+def get_library() -> ctypes.CDLL | None:
     global _LIB
     if _LIB is None:
         _LIB = build_and_load_library()
@@ -22,6 +30,11 @@ def get_library() -> ctypes.CDLL:
 
 def matrix_exp(a: np.ndarray, device: str = "gpu") -> np.ndarray:
     lib = get_library()
+    if lib is None:
+        # Fallback to PyTorch ATen
+        t = torch.from_numpy(a)
+        return torch.matrix_exp(t).numpy()
+
     a_c = np.ascontiguousarray(a, dtype=np.complex64)
     out = np.empty_like(a_c)
     n = a_c.shape[-1]
@@ -29,23 +42,35 @@ def matrix_exp(a: np.ndarray, device: str = "gpu") -> np.ndarray:
     ptr_in = a_c.ctypes.data_as(ctypes.c_void_p)
     ptr_out = out.ctypes.data_as(ctypes.c_void_p)
 
-    if device == "gpu":
+    if device == "gpu" and is_macos():
         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, n, batch, ptr_out)
+        return out
 
-    fn = getattr(lib, "bridge_matrix_exp_ptr_c64_i32_i32_ptr_c64")
-    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
+    return torch.matrix_exp(torch.from_numpy(a)).numpy()
 
 
 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:
+        # 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)
     out = np.empty_like(a_c)
@@ -57,19 +82,25 @@ def matrix_exp_backward(a: np.ndarray, ebar: np.ndarray, dense: bool = False, de
     ptr_ebar = ebar_c.ctypes.data_as(ctypes.c_void_p)
     ptr_out = out.ctypes.data_as(ctypes.c_void_p)
 
-    if device == "gpu":
+    if device == "gpu" and is_macos():
         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")
-    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 = 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, n, batch, dense_val, ptr_out)
+        return out
+
+    tA = torch.from_numpy(a).requires_grad_(True)
+    tE = torch.matrix_exp(tA)
+    tE.backward(torch.from_numpy(ebar))
+    return tA.grad.numpy()
 
 
 class FasterMatrixExp(torch.autograd.Function):
@@ -126,8 +157,26 @@ def faster_propagate(system, thicknesses, *, method="matrix_exp", max_batch=None
 
 
 def enable(device: Literal["cpu", "gpu"] = "gpu") -> None:
-    """Inject faster-diffbloch acceleration into diffBloch runtime."""
+    """Inject faster-diffbloch acceleration into diffBloch runtime with platform checking."""
     global _CURRENT_DEVICE
+
+    if device == "gpu":
+        if not is_macos():
+            warnings.warn(
+                "Metal GPU acceleration is available on macOS only. "
+                "Automatically selecting device='cpu' on this platform.",
+                UserWarning,
+                stacklevel=2,
+            )
+            device = "cpu"
+        elif not is_apple_silicon():
+            warnings.warn(
+                "Metal GPU acceleration is optimized for Apple Silicon unified memory. "
+                "Running on Intel macOS.",
+                UserWarning,
+                stacklevel=2,
+            )
+
     _CURRENT_DEVICE = device
     import importlib
     try:

faster_diffbloch-0.1.2/src/faster_diffbloch/builder.py

@@ -0,0 +1,122 @@
+"""Native runtime builder, platform guards, and loader for faster-diffbloch."""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import warnings
+from pathlib import Path
+
+NATIVE_DIR = Path(__file__).resolve().parent / "native"
+BUILD_DIR = Path.home() / ".cache" / "faster_diffbloch"
+
+
+def is_macos() -> bool:
+    return sys.platform == "darwin"
+
+
+def is_apple_silicon() -> bool:
+    return is_macos() and platform.machine() in ("arm64", "aarch64")
+
+
+def is_linux() -> bool:
+    return sys.platform.startswith("linux")
+
+
+def is_windows() -> bool:
+    return sys.platform.startswith("win") or sys.platform == "cygwin"
+
+
+def has_metal_support() -> bool:
+    if not is_macos():
+        return False
+    # Check if xcrun and metal compiler are available
+    return shutil.which("xcrun") is not None
+
+
+def get_c_compiler() -> str | None:
+    for cc in ("clang", "gcc", "cc"):
+        if shutil.which(cc) is not None:
+            return cc
+    return None
+
+
+def build_and_load_library() -> ctypes.CDLL | None:
+    """Build or load the cached native acceleration library with platform guards."""
+    if is_windows():
+        warnings.warn(
+            "faster-diffbloch native acceleration is not currently supported on Windows. "
+            "Falling back to standard PyTorch execution.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return None
+
+    compiler = get_c_compiler()
+    if compiler is None:
+        warnings.warn(
+            "No C compiler (clang/gcc) found. "
+            "Install clang or build-essential to enable faster-diffbloch acceleration. "
+            "Falling back to standard PyTorch execution.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return None
+
+    BUILD_DIR.mkdir(parents=True, exist_ok=True)
+    lib_name = "libfaster_diffbloch.dylib" if is_macos() else "libfaster_diffbloch.so"
+    lib_path = BUILD_DIR / lib_name
+
+    sources = [
+        NATIVE_DIR / "bridge_lib.c",
+        NATIVE_DIR / "batch_cgemm.c",
+        NATIVE_DIR / "native_scattering.c",
+    ]
+
+    if is_macos():
+        sources.append(NATIVE_DIR / "metal_batch_cgemm.m")
+        if has_metal_support():
+            metal_src = NATIVE_DIR / "batch_cgemm.metal"
+            metallib_path = BUILD_DIR / "batch_cgemm.metallib"
+            if metal_src.exists() and (not metallib_path.exists() or metallib_path.stat().st_mtime < metal_src.stat().st_mtime):
+                try:
+                    subprocess.run(
+                        ["xcrun", "-sdk", "macosx", "metal", "-O3", "-c", str(metal_src), "-o", str(BUILD_DIR / "batch_cgemm.air")],
+                        check=True, capture_output=True,
+                    )
+                    subprocess.run(
+                        ["xcrun", "-sdk", "macosx", "metallib", str(BUILD_DIR / "batch_cgemm.air"), "-o", str(metallib_path)],
+                        check=True, capture_output=True,
+                    )
+                except Exception as exc:
+                    warnings.warn(f"Metal shader precompilation skipped: {exc}", RuntimeWarning, stacklevel=2)
+
+    stale = not lib_path.exists() or any(lib_path.stat().st_mtime < s.stat().st_mtime for s in sources if s.exists())
+    if stale:
+        frameworks = ["-framework", "Accelerate", "-framework", "Metal", "-framework", "Foundation"] if is_macos() else ["-lblas"]
+        cmd = [
+            compiler, "-std=c11", "-O3", "-fPIC", "-shared",
+            "-D_DEFAULT_SOURCE", "-Wno-unused-function", "-Wno-unused-variable",
+            f"-I{NATIVE_DIR}",
+            *[str(s) for s in sources if s.exists()],
+            *frameworks, "-lm", "-o", str(lib_path),
+        ]
+        res = subprocess.run(cmd, capture_output=True, text=True)
+        if res.returncode != 0:
+            warnings.warn(
+                f"Failed to build faster-diffbloch native library with {compiler}:\n{res.stderr}\n"
+                "Falling back to standard PyTorch execution.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return None
+
+    try:
+        return ctypes.CDLL(str(lib_path))
+    except Exception as exc:
+        warnings.warn(f"Could not load faster-diffbloch library: {exc}", RuntimeWarning, stacklevel=2)
+        return None

faster_diffbloch-0.1.0/PKG-INFO

@@ -1,98 +0,0 @@
-Metadata-Version: 2.5
-Name: faster-diffbloch
-Version: 0.1.0
-Summary: Drop-in Metal GPU and CPU acceleration for diffBloch electron crystallography
-Project-URL: Homepage, https://godofecht.github.io/diffFlow/
-Project-URL: Repository, https://github.com/godofecht/diffFlow
-Project-URL: Issues, https://github.com/godofecht/diffFlow/issues
-Project-URL: Original diffBloch, https://diffbloch.com
-Author-email: Abhishek Shivakumar <abhishek@example.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-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.
-
-Documentation and comparison benchmarks: [https://godofecht.github.io/diffFlow/](https://godofecht.github.io/diffFlow/)
-
-Original diffBloch project: [https://diffbloch.com](https://diffbloch.com)
-
----
-
-## Why faster-diffBloch?
-
-1. **Native Metal GPU Execution:**
-   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
-faster_diffbloch.enable(device="gpu")
-
-# Or CPU acceleration
-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.0/README.md

@@ -1,72 +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)
-
----
-
-## Why faster-diffBloch?
-
-1. **Native Metal GPU Execution:**
-   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
-faster_diffbloch.enable(device="gpu")
-
-# Or CPU acceleration
-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.0/src/faster_diffbloch/builder.py

@@ -1,58 +0,0 @@
-"""Native runtime builder and loader for faster-diffbloch."""
-
-from __future__ import annotations
-
-import ctypes
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-NATIVE_DIR = Path(__file__).resolve().parent / "native"
-BUILD_DIR = Path.home() / ".cache" / "faster_diffbloch"
-
-
-def build_and_load_library() -> ctypes.CDLL:
-    """Build or load the cached native acceleration library."""
-    BUILD_DIR.mkdir(parents=True, exist_ok=True)
-    lib_name = "libfaster_diffbloch.dylib" if sys.platform == "darwin" else "libfaster_diffbloch.so"
-    lib_path = BUILD_DIR / lib_name
-
-    sources = [
-        NATIVE_DIR / "bridge_lib.c",
-        NATIVE_DIR / "batch_cgemm.c",
-        NATIVE_DIR / "native_scattering.c",
-    ]
-    if sys.platform == "darwin":
-        sources.append(NATIVE_DIR / "metal_batch_cgemm.m")
-        # Build metallib if metal is available
-        metal_src = NATIVE_DIR / "batch_cgemm.metal"
-        metallib_path = BUILD_DIR / "batch_cgemm.metallib"
-        if metal_src.exists() and (not metallib_path.exists() or metallib_path.stat().st_mtime < metal_src.stat().st_mtime):
-            try:
-                subprocess.run(
-                    ["xcrun", "-sdk", "macosx", "metal", "-O3", "-c", str(metal_src), "-o", str(BUILD_DIR / "batch_cgemm.air")],
-                    check=True, capture_output=True
-                )
-                subprocess.run(
-                    ["xcrun", "-sdk", "macosx", "metallib", str(BUILD_DIR / "batch_cgemm.air"), "-o", str(metallib_path)],
-                    check=True, capture_output=True
-                )
-            except Exception:
-                pass
-
-    stale = not lib_path.exists() or any(lib_path.stat().st_mtime < s.stat().st_mtime for s in sources if s.exists())
-    if stale:
-        frameworks = ["-framework", "Accelerate", "-framework", "Metal", "-framework", "Foundation"] if sys.platform == "darwin" else ["-lblas"]
-        cmd = [
-            "clang", "-std=c11", "-O3", "-fPIC", "-shared",
-            "-D_DEFAULT_SOURCE", "-Wno-unused-function", "-Wno-unused-variable",
-            f"-I{NATIVE_DIR}",
-            *[str(s) for s in sources if s.exists()],
-            *frameworks, "-lm", "-o", str(lib_path),
-        ]
-        res = subprocess.run(cmd, capture_output=True, text=True)
-        if res.returncode != 0:
-            raise RuntimeError(f"Failed to build faster-diffbloch native library:\n{res.stderr}")
-
-    return ctypes.CDLL(str(lib_path))