diffct 2.4.3__tar.gz → 2.4.4__tar.gz

{diffct-2.4.3 → diffct-2.4.4}/.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.4.4}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 
 ### Changed
@@ -254,7 +275,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.4.4}/CITATION.cff

@@ -13,8 +13,8 @@ authors:
     given-names: Yipeng
     email: yipeng.sun@fau.de
     alias: sypsyp97
-version: 2.4.3
-date-released: "2026-10-22"
+version: 2.4.4
+date-released: "2026-10-25"
 license: Apache-2.0
 repository-code: "https://github.com/sypsyp97/diffct"
 url: "https://sypsyp97.github.io/diffct/"

{diffct-2.4.3 → diffct-2.4.4}/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.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.4.3
+Version: 2.4.4
 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/
@@ -90,6 +90,7 @@ 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
 ```
@@ -142,6 +143,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 +180,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 +191,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.4.4}/README.md

@@ -59,6 +59,7 @@ 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
 ```
@@ -111,6 +112,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 +149,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 +160,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.4.4}/diffct/__init__.py

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

{diffct-2.4.3 → diffct-2.4.4}/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.4.4}/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):
@@ -336,14 +340,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)