diffct 2.4.3__tar.gz → 2.5.0__tar.gz

{diffct-2.4.3 → diffct-2.5.0}/.gitignore

@@ -193,3 +193,8 @@ projectBrief.md
 docs/video/media/
 docs/video/scenes.txt
 docs/video/palette.png
+
+# Sphinx autosummary stubs
+docs/source/generated/
+docs/search/node_modules/
+docs/search/tests/test-results/

{diffct-2.4.3 → diffct-2.5.0}/CHANGELOG.md

@@ -5,7 +5,54 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.5.0] - 2026-10-26
+
+### Added
+
+- Apple Silicon GPU (MPS) support for the portable PyTorch backend, including
+  the solvers, detector surfaces and streamed stores. MPS has no FP64, so ray
+  clipping and entry setup run in FP32 there; `precision="float64"` raises a
+  `ValueError` for MPS data, outputs or trajectories. See `docs/EXECUTION.md`
+  for the FP32 error bound. Thanks to @cslht11
+  ([#57](https://github.com/sypsyp97/diffct/pull/57)).
+- TLA+ protocol models with TLC/Apalache checks and execution trace validation
+  for memory budgets, native admission and distributed collectives, run in a
+  separate CI workflow. They live in `formal/` and do not change library
+  behavior ([#55](https://github.com/sypsyp97/diffct/pull/55)).
+
+### Fixed
+
+- Trajectory constructors reject degenerate inputs instead of building NaN or empty geometry: zero or non-finite `ray_dir_fn` directions in `custom_trajectory_2d_parallel`, `random_trajectory_3d` sources at the isocenter, and view counts that are not positive integers (`TypeError` for floats and booleans, `ValueError` for counts below 1). Explicit angle tensors are still accepted. Thanks to @cslht11 ([#56](https://github.com/sypsyp97/diffct/pull/56)).
+
+### Documentation
+
+- README, documentation landing page, `llms.txt` summary, `CITATION.cff` and package keywords name the native CUDA kernels and the portable backend on CPU, ROCm and Apple Silicon. The landing quickstart has an Apple Silicon (MPS) tab ([#60](https://github.com/sypsyp97/diffct/pull/60)).
+- Every documentation page uses the same three-column layout with the site navigation on the left ([#58](https://github.com/sypsyp97/diffct/pull/58)).
+
+### Changed
+
+- Continuous integration: pull requests that change only `docs/` skip the package, test and formal jobs; the documentation build still runs. Pushes to `main` and release tags run every job ([#59](https://github.com/sypsyp97/diffct/pull/59)).
+
+## [2.4.4] - 2026-10-25
+
+### Added
+
+- Native per-axis voxel spacing for projection, matched backprojection, geometry gradients and analytical FBP/FDK. Tensor axis order and physical length units match the PyTorch backend. Native pitches must be in `[1e-6, 1e6]`, with a maximum/minimum ratio of at most `1e4`. Outside these bounds, `numba` raises and `auto` selects PyTorch. On NVIDIA CUDA, the fallback warning names the reason. Scalar native arithmetic and admission are unchanged.
+
+### Fixed
+
+- Portable (`backend="torch"`) autograd no longer records every ray batch and volume tile. Data gradients apply the matched adjoint, and geometry gradients recompute one ray batch and tile at a time. Saved autograd memory no longer grows with the number of batches, also inside `torch.vmap` and `torch.func.jvp` with differentiable inputs or tangents. Geometry backward splits large leading batches like the forward call and accepts empty leading batches. First-order values are unchanged.
+- Second derivatives with respect to the geometry now raise an error on the single-process portable path, as documented. Before, they returned a value.
+- Forward-mode derivatives (`torch.func.jvp`, `jacfwd`) with respect to `Projector` trajectory tensors now raise an error. Before, they returned zero tangents.
+- Distributed operators reject trajectory dtype differences between ranks before gradient reduction, including per-call trajectory overrides.
+
+### Changed
+
+- The portable PyTorch backend sizes its automatic volume tiles, view batches and pixel batches from CUDA memory when the compute devices are CUDA or ROCm devices. One call uses at most a quarter of the memory that the PyTorch allocator can still use when the call starts. This quarter covers work arrays and reduction buffers; geometry backward recomputes each pair with half of that limit. Geometry backward may also keep one cotangent-sized buffer outside that quarter, for a contiguous copy or a distributed sum. With replicated distributed outputs, geometry backward may hold up to three cotangent-sized buffers outside that quarter during the cotangent reduction. CPU inputs, outputs and host stores with CUDA compute devices stage at most the smaller of a quarter of the free host memory and the CUDA limit, but never less than 8 MiB. One work array stays below 2^31 elements. CPU calls keep the 8 MiB ceiling and their previous plans. Distributed ranks agree on the smallest limits. Results change only in floating-point summation order.
+- Portable projection sets up the rays of a view/pixel batch once and reuses them for every volume tile. Projections, backprojections and their gradients are bitwise unchanged for the same chunks. Distributed backward through a backprojection keeps the previous tile order and holds one summed cotangent tile at a time.
+- Portable outputs accumulate in place, so a call no longer holds a second full-size output. Execution statistics report the loop order that ran.
+- `Projector(backend="auto")` emits one `UserWarning` when it selects the portable backend on an NVIDIA CUDA machine. The warning names the reasons. `backend="torch"` silences it.
+- `backend="auto"` selects native NVIDIA execution for per-axis spacing in fast mode with views/space ownership. Strict precision modes and hybrid ownership continue to use PyTorch.
 
 ## [2.4.3] - 2026-10-22
 
@@ -254,7 +301,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Version 2.0.0 replaces the circular-orbit API of 1.x with arbitrary
 per-view trajectories. It breaks the 1.x interface; see
-[docs/MIGRATION.md](docs/MIGRATION.md).
+[docs/MIGRATION.md](https://github.com/sypsyp97/diffct/blob/main/docs/MIGRATION.md).
 
 ### Breaking
 

{diffct-2.4.3 → diffct-2.5.0}/CITATION.cff

@@ -2,8 +2,9 @@ cff-version: 1.2.0
 message: "If you use this software, please cite both the software (below) and the technical report listed under preferred-citation."
 title: "diffct: Differentiable Computed Tomography Reconstruction with CUDA"
 abstract: >-
-  Differentiable CUDA projectors for computed tomography (CT) with PyTorch
-  autograd. Each view has its own source and detector geometry, so circular,
+  Differentiable projectors for computed tomography (CT) with PyTorch
+  autograd: native NVIDIA CUDA kernels and a portable PyTorch backend for
+  CPU, ROCm and Apple Silicon (MPS). Each view has its own source and detector geometry, so circular,
   helical, saddle and calibrated scans use the same matched Siddon operator.
   Projections run on one GPU, several GPUs in one process, or across nodes,
   and trajectory tensors receive geometry gradients for calibration.
@@ -13,8 +14,8 @@ authors:
     given-names: Yipeng
     email: yipeng.sun@fau.de
     alias: sypsyp97
-version: 2.4.3
-date-released: "2026-10-22"
+version: 2.5.0
+date-released: "2026-10-26"
 license: Apache-2.0
 repository-code: "https://github.com/sypsyp97/diffct"
 url: "https://sypsyp97.github.io/diffct/"

{diffct-2.4.3 → diffct-2.5.0}/NOTICE

@@ -16,3 +16,5 @@ https://creativecommons.org/licenses/by/4.0/). The walnut images in
 docs/assets/ (walnut_measured.png, walnut_helical.png, diffct_intro.gif,
 diffct_intro.mp4) are reconstructions from these data. Credit the dataset as
 above when you reuse them. examples/data/NOTICE describes the preprocessing.
+
+The documentation figures use third-party CT data; see docs/assets/gallery/NOTICE.

{diffct-2.4.3 → diffct-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.4.3
+Version: 2.5.0
 Summary: Differentiable CT projection and reconstruction: precision modes, streaming, distributed execution and geometry gradients
 Project-URL: Homepage, https://github.com/sypsyp97/diffct
 Project-URL: Documentation, https://sypsyp97.github.io/diffct/
@@ -10,7 +10,7 @@ Author-email: Yipeng Sun <yipeng.sun@fau.de>
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
-Keywords: CT reconstruction,CUDA,PyTorch,ROCm,computed tomography,differentiable programming
+Keywords: Apple Silicon,CT reconstruction,CUDA,MPS,PyTorch,ROCm,computed tomography,differentiable programming
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: GPU :: NVIDIA CUDA
 Classifier: Intended Audience :: Science/Research
@@ -34,7 +34,8 @@ Description-Content-Type: text/markdown
 <p align="center">English · <a href="https://github.com/sypsyp97/diffct/blob/main/README.zh.md">简体中文</a></p>
 
 <p align="center">
-  Differentiable CUDA projectors for CT: arbitrary trajectories, multi-GPU, multi-node, geometry gradients.
+  Differentiable CT projectors: arbitrary trajectories, multi-GPU, multi-node, geometry gradients.<br>
+  Native NVIDIA CUDA kernels, plus a portable PyTorch backend for CPU, ROCm and Apple Silicon (MPS).
 </p>
 
 <p align="center">
@@ -66,7 +67,7 @@ Description-Content-Type: text/markdown
 </p>
 
 > **Version 2.0** replaces the circular-orbit API of 1.x with per-view trajectories. Code written for 1.x needs changes; see the [migration notes](https://github.com/sypsyp97/diffct/blob/main/docs/MIGRATION.md).
-> For Apple Silicon, use the [MLX port by Linda-Sophie Schneider](https://github.com/Linda-SophieSchneider/DiffCT-MLX).
+> Apple Silicon runs through the built-in MPS support (`backend="torch"`); a community [MLX port by Linda-Sophie Schneider](https://github.com/Linda-SophieSchneider/DiffCT-MLX) also exists.
 
 This README describes the source checkout. Features listed under [Unreleased](CHANGELOG.md#unreleased) require installation from source.
 
@@ -79,7 +80,7 @@ To our knowledge, diffct is the only open-source GPU CT library that combines ar
 - **Matched operators.** `project()` and `backproject()` form an exact adjoint pair for the cell-constant Siddon model. Both support PyTorch autograd, with volume/sinogram gradients and Hessian-vector products.
 - **Large volumes.** Automatic spatial, view and pixel blocks with bounded transfer buffers control working memory. `project_into`/`backproject_into` accept caller-owned tensor or disk stores; tensor autograd keeps complete data on its input device. See [chunked execution](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#chunked-execution).
 - **Multi-GPU and multi-node.** Use `devices=[0, 1, 2, 3]` in one process, or torchrun and NCCL across ranks. Views, space and hybrid partitions control replication of volumes and projections. Speedup depends on workload and communication costs.
-- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU and PyTorch CUDA/ROCm devices; see [execution contracts](docs/EXECUTION.md).
+- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU, PyTorch CUDA/ROCm devices and Apple Silicon GPUs (MPS, `backend="torch"`); see [execution contracts](docs/EXECUTION.md).
 - **Solver API.** `cgls`, `sirt` and `tv_reconstruction` report residual history, tolerances and callbacks, with scan/data fingerprints and complete checkpoint state. `cgls_into` keeps state in bounded mapped blocks.
 - **Differentiable FBP and FDK.** `fbp`, `fdk` and approximate `helical_fdk` compose the public filters, weights and analytical backprojectors. Their backward kernels transpose the actual interpolation stencil; custom filters and weights can be learned. See the [analytical guide](docs/source/analytical_learning.rst).
 
@@ -90,11 +91,12 @@ Capabilities, limits and isocenter rules: [docs/REFERENCE.md](https://github.com
 For the native path, install NVIDIA CUDA PyTorch first, then diffct with the matching CUDA major extra:
 
 ```bash
+python -c "import torch; print(torch.version.cuda)"    # 12.x or 13.x
 pip install "diffct[cu12]"    # PyTorch built for CUDA 12
 pip install "diffct[cu13]"    # PyTorch built for CUDA 13
 ```
 
-The extra installs the CUDA compiler libraries Numba needs. For CPU or PyTorch ROCm execution, install the appropriate PyTorch build and plain `pip install diffct`, then select `backend="torch"`. Importing diffct and using this backend require no CUDA runtime; Numba CUDA initializes when native execution is used. Plain installation also works for native execution when a compatible CUDA Toolkit is already present.
+The extra installs the CUDA compiler libraries Numba needs. For CPU, PyTorch ROCm or Apple Silicon (MPS) execution, install the appropriate PyTorch build and plain `pip install diffct`, then select `backend="torch"`. Importing diffct and using this backend require no CUDA runtime; Numba CUDA initializes when native execution is used. Plain installation also works for native execution when a compatible CUDA Toolkit is already present.
 
 From source, with the examples:
 
@@ -142,6 +144,8 @@ loss.backward()                     # x.grad = A^T (A x - y)
 
 **Geometry gradients.** Reuse one projector with `A.project(volume, trajectory=current)` or `A.backproject(sinogram, trajectory=current)`. Circular helpers accept learnable angle tensors, and `transform_trajectory` applies differentiable rigid transforms. Omitting the override keeps the constructor trajectory. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
 
+**Per-axis voxel spacing.** Set `voxel_spacing=(dy, dx)` or `(dz, dy, dx)` in tensor axis order. Both backends support these pitches for projection, projection geometry gradients and FBP/FDK with fixed geometry.
+
 **3D parallel beams.** Use `circular_trajectory_3d_parallel(...)` and `beam="parallel3d"`. The PyTorch backend provides matched projection and backprojection on CPU and CUDA.
 
 **Native volume layout.** For unbatched, flat-detector cone operations, set `native_volume_layout=True` to avoid volume layout copies. This applies to the native full-CUDA path on one compute device. Shapes stay `(D, H, W)`; the returned strides follow the kernel layout. The default is `False`. See [chunked execution](docs/REFERENCE.md#chunked-execution) for limits.
@@ -177,8 +181,8 @@ volume slabs use `--partition space` under torchrun. Run
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.4.3">
-    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png?v=2.4.3" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png">
+    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
   </picture>
 </p>
 
@@ -188,7 +192,7 @@ volume slabs use `--partition space` under torchrun. Run
 | Adjoint (backprojection) | 1060.77 ms | 279.37 ms (3.8×) | 224.04 ms (4.7×) |
 | CGLS iteration | 1753.73 ms | 468.09 ms (3.7×) | 337.39 ms (5.2×) |
 
-diffct 2.4.3, FP32, A100 64 GB GPUs; circular cone beam, 360 views, 1024×768 detector, pitch 1.25. Default memory settings, without an imposed allocator cap.
+FP32, A100 64 GB GPUs; circular cone beam, 360 views, 1024×768 detector, pitch 1.25. Default memory settings, without an imposed allocator cap.
 
 Projection times are medians of seven samples after three warmups. CGLS uses three ten-iteration solves after a two-iteration warmup; the median includes initialization and is divided by ten. Timings use synchronized wall time and the slowest rank. Raw samples and configuration: [scaling.json](https://github.com/sypsyp97/diffct/blob/main/docs/assets/scaling.json).
 

{diffct-2.4.3 → diffct-2.5.0}/README.md

@@ -3,7 +3,8 @@
 <p align="center">English · <a href="https://github.com/sypsyp97/diffct/blob/main/README.zh.md">简体中文</a></p>
 
 <p align="center">
-  Differentiable CUDA projectors for CT: arbitrary trajectories, multi-GPU, multi-node, geometry gradients.
+  Differentiable CT projectors: arbitrary trajectories, multi-GPU, multi-node, geometry gradients.<br>
+  Native NVIDIA CUDA kernels, plus a portable PyTorch backend for CPU, ROCm and Apple Silicon (MPS).
 </p>
 
 <p align="center">
@@ -35,7 +36,7 @@
 </p>
 
 > **Version 2.0** replaces the circular-orbit API of 1.x with per-view trajectories. Code written for 1.x needs changes; see the [migration notes](https://github.com/sypsyp97/diffct/blob/main/docs/MIGRATION.md).
-> For Apple Silicon, use the [MLX port by Linda-Sophie Schneider](https://github.com/Linda-SophieSchneider/DiffCT-MLX).
+> Apple Silicon runs through the built-in MPS support (`backend="torch"`); a community [MLX port by Linda-Sophie Schneider](https://github.com/Linda-SophieSchneider/DiffCT-MLX) also exists.
 
 This README describes the source checkout. Features listed under [Unreleased](CHANGELOG.md#unreleased) require installation from source.
 
@@ -48,7 +49,7 @@ To our knowledge, diffct is the only open-source GPU CT library that combines ar
 - **Matched operators.** `project()` and `backproject()` form an exact adjoint pair for the cell-constant Siddon model. Both support PyTorch autograd, with volume/sinogram gradients and Hessian-vector products.
 - **Large volumes.** Automatic spatial, view and pixel blocks with bounded transfer buffers control working memory. `project_into`/`backproject_into` accept caller-owned tensor or disk stores; tensor autograd keeps complete data on its input device. See [chunked execution](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#chunked-execution).
 - **Multi-GPU and multi-node.** Use `devices=[0, 1, 2, 3]` in one process, or torchrun and NCCL across ranks. Views, space and hybrid partitions control replication of volumes and projections. Speedup depends on workload and communication costs.
-- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU and PyTorch CUDA/ROCm devices; see [execution contracts](docs/EXECUTION.md).
+- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU, PyTorch CUDA/ROCm devices and Apple Silicon GPUs (MPS, `backend="torch"`); see [execution contracts](docs/EXECUTION.md).
 - **Solver API.** `cgls`, `sirt` and `tv_reconstruction` report residual history, tolerances and callbacks, with scan/data fingerprints and complete checkpoint state. `cgls_into` keeps state in bounded mapped blocks.
 - **Differentiable FBP and FDK.** `fbp`, `fdk` and approximate `helical_fdk` compose the public filters, weights and analytical backprojectors. Their backward kernels transpose the actual interpolation stencil; custom filters and weights can be learned. See the [analytical guide](docs/source/analytical_learning.rst).
 
@@ -59,11 +60,12 @@ Capabilities, limits and isocenter rules: [docs/REFERENCE.md](https://github.com
 For the native path, install NVIDIA CUDA PyTorch first, then diffct with the matching CUDA major extra:
 
 ```bash
+python -c "import torch; print(torch.version.cuda)"    # 12.x or 13.x
 pip install "diffct[cu12]"    # PyTorch built for CUDA 12
 pip install "diffct[cu13]"    # PyTorch built for CUDA 13
 ```
 
-The extra installs the CUDA compiler libraries Numba needs. For CPU or PyTorch ROCm execution, install the appropriate PyTorch build and plain `pip install diffct`, then select `backend="torch"`. Importing diffct and using this backend require no CUDA runtime; Numba CUDA initializes when native execution is used. Plain installation also works for native execution when a compatible CUDA Toolkit is already present.
+The extra installs the CUDA compiler libraries Numba needs. For CPU, PyTorch ROCm or Apple Silicon (MPS) execution, install the appropriate PyTorch build and plain `pip install diffct`, then select `backend="torch"`. Importing diffct and using this backend require no CUDA runtime; Numba CUDA initializes when native execution is used. Plain installation also works for native execution when a compatible CUDA Toolkit is already present.
 
 From source, with the examples:
 
@@ -111,6 +113,8 @@ loss.backward()                     # x.grad = A^T (A x - y)
 
 **Geometry gradients.** Reuse one projector with `A.project(volume, trajectory=current)` or `A.backproject(sinogram, trajectory=current)`. Circular helpers accept learnable angle tensors, and `transform_trajectory` applies differentiable rigid transforms. Omitting the override keeps the constructor trajectory. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
 
+**Per-axis voxel spacing.** Set `voxel_spacing=(dy, dx)` or `(dz, dy, dx)` in tensor axis order. Both backends support these pitches for projection, projection geometry gradients and FBP/FDK with fixed geometry.
+
 **3D parallel beams.** Use `circular_trajectory_3d_parallel(...)` and `beam="parallel3d"`. The PyTorch backend provides matched projection and backprojection on CPU and CUDA.
 
 **Native volume layout.** For unbatched, flat-detector cone operations, set `native_volume_layout=True` to avoid volume layout copies. This applies to the native full-CUDA path on one compute device. Shapes stay `(D, H, W)`; the returned strides follow the kernel layout. The default is `False`. See [chunked execution](docs/REFERENCE.md#chunked-execution) for limits.
@@ -146,8 +150,8 @@ volume slabs use `--partition space` under torchrun. Run
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.4.3">
-    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png?v=2.4.3" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png">
+    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
   </picture>
 </p>
 
@@ -157,7 +161,7 @@ volume slabs use `--partition space` under torchrun. Run
 | Adjoint (backprojection) | 1060.77 ms | 279.37 ms (3.8×) | 224.04 ms (4.7×) |
 | CGLS iteration | 1753.73 ms | 468.09 ms (3.7×) | 337.39 ms (5.2×) |
 
-diffct 2.4.3, FP32, A100 64 GB GPUs; circular cone beam, 360 views, 1024×768 detector, pitch 1.25. Default memory settings, without an imposed allocator cap.
+FP32, A100 64 GB GPUs; circular cone beam, 360 views, 1024×768 detector, pitch 1.25. Default memory settings, without an imposed allocator cap.
 
 Projection times are medians of seven samples after three warmups. CGLS uses three ten-iteration solves after a two-iteration warmup; the median includes initialization and is divided by ten. Timings use synchronized wall time and the slowest rank. Raw samples and configuration: [scaling.json](https://github.com/sypsyp97/diffct/blob/main/docs/assets/scaling.json).
 

{diffct-2.4.3 → diffct-2.5.0}/diffct/__init__.py

@@ -64,7 +64,7 @@ try:
 except ImportError:
     pass
 
-__version__ = '2.4.3'
+__version__ = '2.5.0'
 
 __all__ = [
     'Projector',

{diffct-2.4.3 → diffct-2.5.0}/diffct/_solver_state.py

@@ -12,6 +12,7 @@ import torch.distributed as dist
 from .pipeline import _fragments
 from .storage import NpyStore, TensorStore
 from .distribution import control_status, preflight
+from .utils import _work_dtype
 
 
 def count(value, name, positive=False):
@@ -65,20 +66,46 @@ def scalar_sum(operator, value, kind, *, return_tensor=False):
         dist.all_reduce(accumulator, group=group)
         return accumulator if return_tensor else accumulator.item()
     if return_tensor:
-        return torch.as_tensor(value, dtype=torch.float64, device=result_device)
+        return torch.as_tensor(value, dtype=_work_dtype(result_device), device=result_device)
     return float(value)
 
 
 def squared_norm(operator, value, kind, elements=1048576, *, return_tensor=False):
     store = TensorStore(value) if isinstance(value, torch.Tensor) else value
-    total = torch.zeros((), dtype=torch.float64, device=getattr(store, "device", "cpu"))
+    # Scale every block by its own peak before squaring and track the
+    # running maximum on the device: unscaled FP32 squares overflow for
+    # large measurements and underflow for tiny geometries.
+    device = getattr(store, "device", torch.device("cpu"))
+    if _work_dtype(device) == torch.float64:
+        total = torch.zeros((), dtype=torch.float64, device=device)
+        if owns_values(operator, kind):
+            for selected in _fragments(tuple(store.shape), elements):
+                # Clone even an FP64 view: norms must never alter caller measurements.
+                block = store.read(selected).to(dtype=torch.float64).clone()
+                # Preserve the block reductions and their sequential FP64 order.
+                total.add_(block.square_().sum().to(device=total.device))
+        return scalar_sum(operator, total, kind, return_tensor=return_tensor)
+    # FP32 devices (MPS): squares of large measurements overflow and tiny
+    # geometries underflow, so every block is rescaled by its peak and the
+    # running sum follows the largest peak seen. All block math stays on the
+    # device; the two closing scalar reads fit the per-iteration reduction
+    # budget, and their product leaves FP32 before it can overflow.
+    peak = torch.zeros((), device=device, dtype=torch.float32)
+    total = torch.zeros((), device=device, dtype=torch.float32)
     if owns_values(operator, kind):
         for selected in _fragments(tuple(store.shape), elements):
-            # Clone even an FP64 view: norms must never alter caller measurements.
-            block = store.read(selected).to(dtype=torch.float64).clone()
-            # Preserve the block reductions and their sequential FP64 order.
-            total.add_(block.square_().sum().to(device=total.device))
-    return scalar_sum(operator, total, kind, return_tensor=return_tensor)
+            block = store.read(selected)
+            if not block.numel():
+                continue
+            block_peak = block.detach().abs().amax()
+            safe = torch.where(block_peak > 0, block_peak, torch.ones_like(block_peak))
+            combined = torch.maximum(peak, block_peak)
+            guard = torch.where(combined > 0, combined, torch.ones_like(combined))
+            total = (total * (peak / guard).square()
+                     + (block.detach() / safe).square().sum() * (block_peak / guard).square())
+            peak = combined
+    return scalar_sum(operator, peak.item() ** 2 * total.item(), kind,
+                      return_tensor=return_tensor)
 
 
 def copy_blocks(source, target, elements):

{diffct-2.4.3 → diffct-2.5.0}/diffct/analytical.py

@@ -27,7 +27,7 @@ import math
 
 import torch
 
-from .constants import _DTYPE
+from .constants import _DTYPE, _native_spacing
 from .utils import (
     DeviceManager,
     TorchCUDABridge,
@@ -431,7 +431,7 @@ def _parallel_weighted_backproject_raw(sinogram, ray_dir, det_origin, det_u_vec,
     _resolve_kernel('_parallel_2d_fbp_backproject_kernel')[grid, tpb, numba_stream](
         d_sino, n_views, n_det, d_reco, Nx, Ny,
         _DTYPE(detector_spacing), d_ray_dir, d_det_origin, d_det_u_vec,
-        cx, cy, _DTYPE(voxel_spacing),
+        cx, cy, _native_spacing(voxel_spacing),
     )
 
     return reco * (1.0 / (2.0 * math.pi))
@@ -522,8 +522,9 @@ def _fan_weighted_backproject_raw(sinogram, src_pos, det_center, det_u_vec,
     _resolve_kernel('_fan_2d_fbp_backproject_kernel')[grid, tpb, numba_stream](
         d_sino, n_views, n_det, d_reco, Nx, Ny,
         _DTYPE(detector_spacing), d_src_pos, d_det_center, d_det_u_vec,
-        cx, cy, _DTYPE(voxel_spacing),
-        *(_DTYPE(value / voxel_spacing) for value in isocenter.tolist()),
+        cx, cy, _native_spacing(voxel_spacing),
+        *(_DTYPE(value if isinstance(voxel_spacing, (tuple, list)) else value / voxel_spacing)
+          for value in isocenter.tolist()),
     )
 
     return reco
@@ -584,8 +585,9 @@ def _cone_weighted_backproject_raw(sinogram, src_pos, det_center, det_u_vec, det
         d_sino, n_views, n_u, n_v, d_reco, Nx, Ny, Nz,
         _DTYPE(du), _DTYPE(dv),
         d_src_pos, d_det_center, d_det_u_vec, d_det_v_vec,
-        cx, cy, cz, _DTYPE(voxel_spacing),
-        *(_DTYPE(value / voxel_spacing) for value in isocenter.tolist()),
+        cx, cy, cz, _native_spacing(voxel_spacing),
+        *(_DTYPE(value if isinstance(voxel_spacing, (tuple, list)) else value / voxel_spacing)
+          for value in isocenter.tolist()),
     )
 
     # Convert back to (D, H, W) layout for the user.
@@ -637,7 +639,8 @@ def _analytical_transpose_raw(image, beam, geometry, parameters, isocenter, sino
         scale = (sdd_n / (2.0 * math.pi * sid_n)).view(
             (-1,) + (1,) * (len(sinogram_shape) - 1)
         )
-        iso = tuple(_DTYPE(value / parameters[-1]) for value in isocenter.tolist())
+        iso = tuple(_DTYPE(value if isinstance(parameters[-1], (tuple, list)) else value / parameters[-1])
+                    for value in isocenter.tolist())
 
     if beam == "cone":
         D, H, W, du, dv, spacing = parameters
@@ -647,7 +650,7 @@ def _analytical_transpose_raw(image, beam, geometry, parameters, isocenter, sino
         _resolve_kernel('_cone_3d_fdk_transpose_kernel')[grid, tpb, stream](
             d_sino, *sinogram_shape, d_image, W, H, D, _DTYPE(du), _DTYPE(dv),
             *d_geometry, _DTYPE(W * 0.5), _DTYPE(H * 0.5), _DTYPE(D * 0.5),
-            _DTYPE(spacing), *iso,
+            _native_spacing(spacing), *iso,
         )
     else:
         pitch, H, W, spacing = parameters
@@ -657,7 +660,7 @@ def _analytical_transpose_raw(image, beam, geometry, parameters, isocenter, sino
                                  else '_fan_2d_fbp_transpose_kernel')
         kernel[grid, tpb, stream](
             d_sino, *sinogram_shape, d_image, W, H, _DTYPE(pitch), *d_geometry,
-            _DTYPE(W * 0.5), _DTYPE(H * 0.5), _DTYPE(spacing), *iso,
+            _DTYPE(W * 0.5), _DTYPE(H * 0.5), _native_spacing(spacing), *iso,
         )
     return sinogram * scale
 

{diffct-2.4.3 → diffct-2.5.0}/diffct/analytical_execution.py

@@ -16,6 +16,7 @@ from .analytical import (
     fan_weighted_backproject, parallel_weighted_backproject,
 )
 from .backends import _zero_dependency, select_backend, voxel_spacing_tuple
+from .constants import _native_spacing
 from .chunking import _memory_budget, _pixel_tiles
 from .distribution import Partition, preflight
 from .operators import _detector_spacing, _normalize_devices, _positive_int, _shape, _validate_trajectory
@@ -143,6 +144,9 @@ class AnalyticalExecution:
         self.rank = 3 if beam == "cone" else 2
         self.global_volume_shape = _shape(volume_shape, self.rank, "volume_shape")
         self.spacing = voxel_spacing_tuple(voxel_spacing, self.rank)
+        self.voxel_spacing = self.spacing if isinstance(voxel_spacing, (tuple, list)) else self.spacing[0]
+        if self.backend == "numba" and isinstance(self.voxel_spacing, tuple):
+            _native_spacing(self.voxel_spacing)
         self.pitch = _detector_spacing(detector_spacing, beam)
         self.devices = _normalize_devices(devices)
         if not isinstance(source, torch.Tensor):
@@ -156,6 +160,8 @@ class AnalyticalExecution:
             raise TypeError("sinogram store must have dtype float32 or float64")
         self.source = source
         self.output_device = torch.device(getattr(source, "device", "cpu"))
+        if self.dtype == torch.float64 and self.output_device.type == "mps":
+            raise ValueError("precision must be 'fast' or 'float32' on MPS; MPS provides no float64")
         self.detector_shape = tuple(source.shape[1:])
         for component in trajectory:
             _fixed(component, "trajectory")
@@ -336,14 +342,14 @@ class AnalyticalExecution:
                               device=data.device, dtype=self.dtype)
         if self.beam == "parallel":
             geometry = (geometry[0], geometry[1] - centre, geometry[2])
-            return parallel_weighted_backproject(data, *geometry, self.pitch[0], *shape, self.spacing[0])
+            return parallel_weighted_backproject(data, *geometry, self.pitch[0], *shape, self.voxel_spacing)
         geometry = (geometry[0] - centre, geometry[1] - centre, *geometry[2:])
         isocenter = self.isocenter.to(data.device) - centre
         if self.beam == "fan":
             return fan_weighted_backproject(data, *geometry, self.pitch[0], *shape,
-                                            self.spacing[0], isocenter=isocenter)
+                                            self.voxel_spacing, isocenter=isocenter)
         return cone_weighted_backproject(data, *geometry, *shape, *self.pitch,
-                                         self.spacing[0], isocenter=isocenter)
+                                         self.voxel_spacing, isocenter=isocenter)
 
     def _tile(self, spatial):
         shape = tuple(part.stop - part.start for part in spatial)