diffct 2.0.0__tar.gz → 2.0.1__tar.gz

{diffct-2.0.0 → diffct-2.0.1}/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [2.0.1] - 2026-10-09
+
+### Fixed
+
+- The low-level projector and backprojector Functions and the analytical
+  weighted backprojections run in the CUDA context of their input. Before,
+  inputs on another GPU than the current device could use the wrong context
+  and stream.
+- ``custom_trajectory_3d`` and ``custom_trajectory_2d_fan`` raise
+  ``ValueError`` for a source at the isocenter or a non-finite source,
+  instead of returning NaN geometry. The figure-8 example in the
+  ``custom_trajectory_3d`` docstring no longer puts a source at the origin.
+- The class docstring examples of the six projector Functions use the
+  per-view trajectory API.
+- ``_trig_tables`` accepts NumPy dtypes for tensor input.
+- Walnut example: ``preprocess_walnut.py`` raises when projection archives or
+  views are missing or an air level is not positive, instead of writing NaN
+  data. A non-default crop keeps the detector centre offset, and
+  ``walnut_reconstruction.py`` applies it to the geometry and the FDK
+  weights. The default crop has no offset.
+- Examples: ``psnr`` returns infinity for identical images; distributed
+  reductions in CGLS, TV and the noise peak use the operator's process
+  group.
+
+### Added
+
+- ``Projector.process_group``: the process group of a distributed operator.
+
 ## [2.0.0] - 2026-10-09
 
 Version 2.0.0 replaces the circular-orbit API of 1.x with arbitrary
@@ -28,7 +56,7 @@ per-view trajectories. It breaks the 1.x interface; see
 - Install extras ``diffct[cu12]`` and ``diffct[cu13]`` pull in the matching
   numba-cuda CUDA bindings, so one ``pip install`` gives a working import.
 - Measured walnut example (``examples/walnut_reconstruction.py``), intro video
-  and README figures with provenance records in ``docs/assets``.
+  and README figures.
 - Geometry gradients. Trajectory tensors may require gradients; ``Projector``
   and the low-level Function classes return gradients for source, detector
   centre and detector axes (parallel: ray direction, detector origin and

{diffct-2.0.0 → diffct-2.0.1}/CITATION.cff

@@ -13,7 +13,7 @@ authors:
     given-names: Yipeng
     email: yipeng.sun@fau.de
     alias: sypsyp97
-version: 2.0.0
+version: 2.0.1
 date-released: "2026-10-09"
 license: Apache-2.0
 repository-code: "https://github.com/sypsyp97/diffct"

{diffct-2.0.0 → diffct-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.0.0
+Version: 2.0.1
 Summary: Differentiable CUDA projectors for CT: arbitrary trajectories, multi-GPU and multi-node execution, geometry gradients
 Project-URL: Homepage, https://github.com/sypsyp97/diffct
 Project-URL: Documentation, https://sypsyp97.github.io/diffct/
@@ -76,7 +76,6 @@ 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.
 - **Multi-GPU and multi-node.** Use `devices=[0, 1, 2, 3]` in one process, or one process per GPU with torchrun and NCCL. Views are partitioned and the volume is replicated. Speedup depends on workload and communication costs.
 - **Analytical helpers.** `diffct.analytical` provides ramp filters (ram-lak, shepp-logan, cosine, hamming, hann), fan, cone and Parker weights, and FBP and FDK backprojection.
-- **Validated.** FDK matches ASTRA 2.5.0 `FDK_CUDA`: PSNR within 0.3 dB. Geometry gradients match an independent float64 reference to about 1e-6. The [recorded A100 validation](docs/VALIDATION.md) reports 229 passing pytest tests. Full notes: [REFERENCE](docs/REFERENCE.md#validation-summary).
 
 Capabilities, limits and isocenter rules: [docs/REFERENCE.md](docs/REFERENCE.md#capabilities-and-limits).
 
@@ -155,7 +154,7 @@ A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, dev
 | Adjoint (backprojection) | 20.66 ms | 5.89 ms (3.5×) | 4.62 ms (4.5×) |
 | CGLS iteration | 30.08 ms | 8.08 ms (3.7×) | 5.59 ms (5.4×) |
 
-Circular trajectory, 360 views, detector (2n, 1.5n) cells at pitch 1.25, A100 64 GB on Leonardo Booster. Small volumes scale less: at 64³, one CGLS iteration takes 4.63 ms on 1 GPU, 1.57 ms on 4 and 1.56 ms on 8. Raw data: [docs/assets/scaling.json](docs/assets/scaling.json).
+Circular trajectory, 360 views, detector (2n, 1.5n) cells at pitch 1.25, A100 64 GB GPUs. Small volumes scale less: at 64³, one CGLS iteration takes 4.63 ms on 1 GPU, 1.57 ms on 4 and 1.56 ms on 8. Raw data: [docs/assets/scaling.json](docs/assets/scaling.json).
 
 To measure one against several GPUs on your machine (default scan of the script, not the table setup):
 
@@ -199,7 +198,6 @@ Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](
 | [Trajectory guide](docs/source/trajectories.rst) | Trajectory tuples and `Projector` usage |
 | [docs/REFERENCE.md](docs/REFERENCE.md) | Capabilities and limits, custom trajectories, geometry gradients, multi-GPU details, geometry and units |
 | [docs/DISTRIBUTED.md](docs/DISTRIBUTED.md) | Execution/memory choices, distributed loss rules, Slurm and cross-node checks |
-| [docs/VALIDATION.md](docs/VALIDATION.md) | Test commands, validation details and the limits of each check |
 | [docs/MIGRATION.md](docs/MIGRATION.md) | Moving from the circular-only API |
 | [docs/video/README.md](docs/video/README.md) | How the intro video is rendered |
 | [CHANGELOG.md](CHANGELOG.md) | Release history |

{diffct-2.0.0 → diffct-2.0.1}/README.md

@@ -45,7 +45,6 @@ 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.
 - **Multi-GPU and multi-node.** Use `devices=[0, 1, 2, 3]` in one process, or one process per GPU with torchrun and NCCL. Views are partitioned and the volume is replicated. Speedup depends on workload and communication costs.
 - **Analytical helpers.** `diffct.analytical` provides ramp filters (ram-lak, shepp-logan, cosine, hamming, hann), fan, cone and Parker weights, and FBP and FDK backprojection.
-- **Validated.** FDK matches ASTRA 2.5.0 `FDK_CUDA`: PSNR within 0.3 dB. Geometry gradients match an independent float64 reference to about 1e-6. The [recorded A100 validation](docs/VALIDATION.md) reports 229 passing pytest tests. Full notes: [REFERENCE](docs/REFERENCE.md#validation-summary).
 
 Capabilities, limits and isocenter rules: [docs/REFERENCE.md](docs/REFERENCE.md#capabilities-and-limits).
 
@@ -124,7 +123,7 @@ A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, dev
 | Adjoint (backprojection) | 20.66 ms | 5.89 ms (3.5×) | 4.62 ms (4.5×) |
 | CGLS iteration | 30.08 ms | 8.08 ms (3.7×) | 5.59 ms (5.4×) |
 
-Circular trajectory, 360 views, detector (2n, 1.5n) cells at pitch 1.25, A100 64 GB on Leonardo Booster. Small volumes scale less: at 64³, one CGLS iteration takes 4.63 ms on 1 GPU, 1.57 ms on 4 and 1.56 ms on 8. Raw data: [docs/assets/scaling.json](docs/assets/scaling.json).
+Circular trajectory, 360 views, detector (2n, 1.5n) cells at pitch 1.25, A100 64 GB GPUs. Small volumes scale less: at 64³, one CGLS iteration takes 4.63 ms on 1 GPU, 1.57 ms on 4 and 1.56 ms on 8. Raw data: [docs/assets/scaling.json](docs/assets/scaling.json).
 
 To measure one against several GPUs on your machine (default scan of the script, not the table setup):
 
@@ -168,7 +167,6 @@ Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](
 | [Trajectory guide](docs/source/trajectories.rst) | Trajectory tuples and `Projector` usage |
 | [docs/REFERENCE.md](docs/REFERENCE.md) | Capabilities and limits, custom trajectories, geometry gradients, multi-GPU details, geometry and units |
 | [docs/DISTRIBUTED.md](docs/DISTRIBUTED.md) | Execution/memory choices, distributed loss rules, Slurm and cross-node checks |
-| [docs/VALIDATION.md](docs/VALIDATION.md) | Test commands, validation details and the limits of each check |
 | [docs/MIGRATION.md](docs/MIGRATION.md) | Moving from the circular-only API |
 | [docs/video/README.md](docs/video/README.md) | How the intro video is rendered |
 | [CHANGELOG.md](CHANGELOG.md) | Release history |

{diffct-2.0.0 → diffct-2.0.1}/diffct/__init__.py

@@ -49,7 +49,7 @@ try:
 except ImportError:
     pass
 
-__version__ = '2.0.0'
+__version__ = '2.0.1'
 
 __all__ = [
     'Projector',

{diffct-2.0.0 → diffct-2.0.1}/diffct/analytical.py

@@ -34,6 +34,7 @@ from .utils import (
     _get_numba_external_stream_for,
     _grid_2d,
     _grid_3d,
+    _on_device_of,
 )
 from .kernels import (
     _parallel_2d_fbp_backproject_kernel,
@@ -365,6 +366,7 @@ def _as_contig_f32(t, device):
     return DeviceManager.ensure_device(t, device).to(dtype=torch.float32).contiguous()
 
 
+@_on_device_of("sinogram")
 def parallel_weighted_backproject(sinogram, ray_dir, det_origin, det_u_vec,
                                   detector_spacing, H, W, voxel_spacing=1.0):
     """Voxel-driven parallel-beam FBP backprojection with analytical constant.
@@ -448,6 +450,7 @@ def _analytical_geometry(src_pos, det_center, n, isocenter):
     return isocenter, float(sid_n.mean().item()), float(sdd_n.mean().item())
 
 
+@_on_device_of("sinogram")
 def fan_weighted_backproject(sinogram, src_pos, det_center, det_u_vec,
                              detector_spacing, H, W, voxel_spacing=1.0, *, isocenter=None):
     """Voxel-driven fan-beam FBP backprojection with analytical constant.
@@ -503,6 +506,7 @@ def fan_weighted_backproject(sinogram, src_pos, det_center, det_u_vec,
     return reco * scale
 
 
+@_on_device_of("sinogram")
 def cone_weighted_backproject(sinogram, src_pos, det_center, det_u_vec, det_v_vec,
                               D, H, W, du, dv, voxel_spacing=1.0, *, isocenter=None):
     """Voxel-driven cone-beam FDK backprojection with analytical constant.

{diffct-2.0.0 → diffct-2.0.1}/diffct/geometry.py

@@ -13,6 +13,17 @@ from typing import Callable, Tuple
 # Trajectory Generation Functions
 # ============================================================================
 
+def _check_source_positions(src_pos):
+    """Reject non-finite sources and sources at the isocenter, which have no viewing direction."""
+    if not torch.isfinite(src_pos).all():
+        raise ValueError("source_path_fn returned non-finite source positions")
+    if (torch.linalg.vector_norm(src_pos.detach(), dim=1) == 0).any():
+        raise ValueError(
+            "source_path_fn returned a source at the isocenter; every source needs a "
+            "nonzero distance from the origin"
+        )
+
+
 def circular_trajectory_3d(n_views, sid, sdd, start_angle=0.0, end_angle=None, device='cuda', dtype=torch.float32):
     """Generate circular trajectory geometry for cone-beam CT.
 
@@ -500,11 +511,11 @@ def custom_trajectory_3d(n_views, sid, sdd,
 
     Examples
     --------
-    >>> # Define a custom figure-8 trajectory
+    >>> # Circular orbit with a two-lobe (figure-8) vertical motion
     >>> def figure8_path(angles, sid):
     ...     src_pos = torch.zeros((len(angles), 3), device=angles.device, dtype=angles.dtype)
     ...     src_pos[:, 0] = -sid * torch.sin(angles)
-    ...     src_pos[:, 1] = sid * torch.cos(angles) * torch.sin(angles)
+    ...     src_pos[:, 1] = sid * torch.cos(angles)
     ...     src_pos[:, 2] = 50 * torch.sin(2 * angles)
     ...     return src_pos
     >>>
@@ -523,6 +534,7 @@ def custom_trajectory_3d(n_views, sid, sdd,
     if src_pos.shape != (n_views, 3):
         raise ValueError(f"source_path_fn must return tensor of shape ({n_views}, 3), "
                         f"got {src_pos.shape}")
+    _check_source_positions(src_pos)
 
     # Keep the entire frame in the source-path autograd graph. Constructing
     # tensors from scalar tensors detaches them; rewriting view slices in
@@ -750,6 +762,7 @@ def custom_trajectory_2d_fan(n_views, sid, sdd,
     if src_pos.shape != (n_views, 2):
         raise ValueError(f"source_path_fn must return tensor of shape ({n_views}, 2), "
                         f"got {src_pos.shape}")
+    _check_source_positions(src_pos)
 
     # Preallocate remaining position matrices
     det_center = torch.zeros((n_views, 2), device=device, dtype=dtype)

{diffct-2.0.0 → diffct-2.0.1}/diffct/operators.py

@@ -523,6 +523,15 @@ class Projector:
             *self.detector_spacing, self.voxel_spacing,
         )
 
+    @property
+    def process_group(self):
+        """Process group of a distributed operator, or None for the default group.
+
+        Pass it as ``group=`` to collectives that combine per-rank results of this
+        operator, so they use the same ranks as the operator.
+        """
+        return self._process_group
+
     def project(self, volume):
         """Project a ``(H, W)`` or ``(D, H, W)`` CUDA tensor to float32.
 

{diffct-2.0.0 → diffct-2.0.1}/diffct/projectors.py

@@ -12,6 +12,7 @@ from .utils import (
     DeviceManager,
     TorchCUDABridge,
     _get_numba_external_stream_for,
+    _on_device_of,
     _trig_tables,
     _validate_3d_memory_layout,
     _grid_2d,
@@ -77,6 +78,7 @@ class _GeometryVJPFunction(torch.autograd.Function):
     """First-order geometry gradient; differentiating it again raises."""
 
     @staticmethod
+    @_on_device_of("volume")
     def forward(ctx, beam, volume, grad_sino, detector_spacing, voxel_spacing, *geometry):
         return _geometry_vjp(beam, volume, grad_sino, geometry, detector_spacing, voxel_spacing)
 
@@ -119,23 +121,17 @@ class ParallelProjectorFunction(torch.autograd.Function):
     Examples
     --------
     >>> import torch
-    >>> from diffct.differentiable import ParallelProjectorFunction
+    >>> from diffct import ParallelProjectorFunction, circular_trajectory_2d_parallel
     >>>
-    >>> # Create a 2D image with gradient tracking
     >>> image = torch.randn(128, 128, device='cuda', requires_grad=True)
-    >>> # Define projection parameters
-    >>> angles = torch.linspace(0, torch.pi, 180, device='cuda')
-    >>> num_detectors = 128
-    >>> detector_spacing = 1.0
-    >>> # Compute forward projection
-    >>> projector = ParallelProjectorFunction.apply
-    >>> sinogram = projector(image, angles, num_detectors, detector_spacing)
-    >>> # Compute loss and gradients
-    >>> loss = sinogram.sum()
-    >>> loss.backward()
-    >>> print(f"Gradient shape: {image.grad.shape}")  # (128, 128)
+    >>> ray_dir, det_origin, det_u_vec = circular_trajectory_2d_parallel(180, device='cuda')
+    >>> sinogram = ParallelProjectorFunction.apply(image, ray_dir, det_origin, det_u_vec, 192, 1.0)
+    >>> sinogram.sum().backward()
+    >>> image.grad.shape
+    torch.Size([128, 128])
     """
     @staticmethod
+    @_on_device_of("image")
     def forward(ctx, image, ray_dir, det_origin, det_u_vec, num_detectors, detector_spacing=1.0, voxel_spacing=1.0):
         """Compute the 2D parallel beam forward projection with arbitrary trajectories using CUDA acceleration.
 
@@ -254,16 +250,17 @@ class ParallelBackprojectorFunction(torch.autograd.Function):
     Examples
     --------
     >>> import torch
-    >>> from diffct.differentiable import ParallelBackprojectorFunction
+    >>> from diffct import ParallelBackprojectorFunction, circular_trajectory_2d_parallel
     >>>
-    >>> sinogram = torch.randn(180, 128, device='cuda', requires_grad=True)
-    >>> angles = torch.linspace(0, torch.pi, 180, device='cuda')
-    >>> recon = ParallelBackprojectorFunction.apply(sinogram, angles, 1.0, 128, 128)
-    >>> loss = recon.sum()
-    >>> loss.backward()
-    >>> print(sinogram.grad.shape)  # (180, 128)
+    >>> sinogram = torch.randn(180, 192, device='cuda', requires_grad=True)
+    >>> ray_dir, det_origin, det_u_vec = circular_trajectory_2d_parallel(180, device='cuda')
+    >>> image = ParallelBackprojectorFunction.apply(sinogram, ray_dir, det_origin, det_u_vec, 1.0, 128, 128)
+    >>> image.sum().backward()
+    >>> sinogram.grad.shape
+    torch.Size([180, 192])
     """
     @staticmethod
+    @_on_device_of("sinogram")
     def forward(ctx, sinogram, ray_dir, det_origin, det_u_vec, detector_spacing=1.0, H=128, W=128, voxel_spacing=1.0):
         """Compute the 2D parallel beam backprojection with arbitrary trajectories using CUDA acceleration.
 
@@ -384,16 +381,17 @@ class FanProjectorFunction(torch.autograd.Function):
     Examples
     --------
     >>> import torch
-    >>> from diffct.differentiable import FanProjectorFunction
+    >>> from diffct import FanProjectorFunction, circular_trajectory_2d_fan
     >>>
     >>> image = torch.randn(256, 256, device='cuda', requires_grad=True)
-    >>> angles = torch.linspace(0, 2 * torch.pi, 360, device='cuda')
-    >>> sinogram = FanProjectorFunction.apply(image, angles, 512, 1.0, 1500.0, 1000.0)
-    >>> loss = sinogram.sum()
-    >>> loss.backward()
-    >>> print(image.grad.shape)  # (256, 256)
+    >>> src_pos, det_center, det_u_vec = circular_trajectory_2d_fan(360, sid=1000.0, sdd=1500.0, device='cuda')
+    >>> sinogram = FanProjectorFunction.apply(image, src_pos, det_center, det_u_vec, 512, 1.0)
+    >>> sinogram.sum().backward()
+    >>> image.grad.shape
+    torch.Size([256, 256])
     """
     @staticmethod
+    @_on_device_of("image")
     def forward(ctx, image, src_pos, det_center, det_u_vec, num_detectors, detector_spacing, voxel_spacing=1.0):
         """Compute the 2D fan beam forward projection with arbitrary trajectories using CUDA acceleration.
 
@@ -511,16 +509,17 @@ class FanBackprojectorFunction(torch.autograd.Function):
     Examples
     --------
     >>> import torch
-    >>> from diffct.differentiable import FanBackprojectorFunction
+    >>> from diffct import FanBackprojectorFunction, circular_trajectory_2d_fan
     >>>
     >>> sinogram = torch.randn(360, 512, device='cuda', requires_grad=True)
-    >>> angles = torch.linspace(0, 2 * torch.pi, 360, device='cuda')
-    >>> recon = FanBackprojectorFunction.apply(sinogram, angles, 1.0, 256, 256, 1500.0, 1000.0)
-    >>> loss = recon.sum()
-    >>> loss.backward()
-    >>> print(sinogram.grad.shape)  # (360, 512)
+    >>> src_pos, det_center, det_u_vec = circular_trajectory_2d_fan(360, sid=1000.0, sdd=1500.0, device='cuda')
+    >>> image = FanBackprojectorFunction.apply(sinogram, src_pos, det_center, det_u_vec, 1.0, 256, 256)
+    >>> image.sum().backward()
+    >>> sinogram.grad.shape
+    torch.Size([360, 512])
     """
     @staticmethod
+    @_on_device_of("sinogram")
     def forward(ctx, sinogram, src_pos, det_center, det_u_vec, detector_spacing, H, W, voxel_spacing=1.0):
         """Compute the 2D fan beam backprojection with arbitrary trajectories using CUDA acceleration.
 
@@ -639,16 +638,19 @@ class ConeProjectorFunction(torch.autograd.Function):
     Examples
     --------
     >>> import torch
-    >>> from diffct.differentiable import ConeProjectorFunction
+    >>> from diffct import ConeProjectorFunction, circular_trajectory_3d
     >>>
     >>> volume = torch.randn(128, 128, 128, device='cuda', requires_grad=True)
-    >>> angles = torch.linspace(0, 2 * torch.pi, 360, device='cuda')
-    >>> projections = ConeProjectorFunction.apply(volume, angles, 256, 256, 1.0, 1.0, 1500.0, 1000.0)
-    >>> loss = projections.sum()
-    >>> loss.backward()
-    >>> print(volume.grad.shape)  # (128, 128, 128)
+    >>> src_pos, det_center, det_u_vec, det_v_vec = circular_trajectory_3d(360, sid=1000.0, sdd=1500.0, device='cuda')
+    >>> projections = ConeProjectorFunction.apply(
+    ...     volume, src_pos, det_center, det_u_vec, det_v_vec, 256, 256, 1.0, 1.0
+    ... )
+    >>> projections.sum().backward()
+    >>> volume.grad.shape
+    torch.Size([128, 128, 128])
     """
     @staticmethod
+    @_on_device_of("volume")
     def forward(ctx, volume, src_pos, det_center, det_u_vec, det_v_vec, det_u, det_v, du, dv, voxel_spacing=1.0):
         """Compute the 3D cone beam forward projection with arbitrary trajectories using CUDA acceleration.
 
@@ -784,20 +786,19 @@ class ConeBackprojectorFunction(torch.autograd.Function):
     Examples
     --------
     >>> import torch
-    >>> from diffct.differentiable import ConeBackprojectorFunction
+    >>> from diffct import ConeBackprojectorFunction, circular_trajectory_3d
     >>>
     >>> projections = torch.randn(360, 256, 256, device='cuda', requires_grad=True)
-    >>> angles = torch.linspace(0, 2 * torch.pi, 360, device='cuda')
-    >>> D, H, W = 128, 128, 128
-    >>> du, dv = 1.0, 1.0
-    >>> sdd, sid = 1500.0, 1000.0
-    >>> backprojector = ConeBackprojectorFunction.apply
-    >>> volume = backprojector(projections, angles, D, H, W, du, dv, sdd, sid)
-    >>> loss = volume.sum()
-    >>> loss.backward()
-    >>> print(f"Projection gradient shape: {projections.grad.shape}")  # (360, 256, 256)
+    >>> src_pos, det_center, det_u_vec, det_v_vec = circular_trajectory_3d(360, sid=1000.0, sdd=1500.0, device='cuda')
+    >>> volume = ConeBackprojectorFunction.apply(
+    ...     projections, src_pos, det_center, det_u_vec, det_v_vec, 128, 128, 128, 1.0, 1.0
+    ... )
+    >>> volume.sum().backward()
+    >>> projections.grad.shape
+    torch.Size([360, 256, 256])
     """
     @staticmethod
+    @_on_device_of("sinogram")
     def forward(ctx, sinogram, src_pos, det_center, det_u_vec, det_v_vec, D, H, W, du, dv, voxel_spacing=1.0):
         """Compute the 3D cone beam backprojection with arbitrary trajectories using CUDA acceleration.
 

{diffct-2.0.0 → diffct-2.0.1}/diffct/utils.py

@@ -5,7 +5,13 @@ PyTorch-CUDA bridging, stream caching, trigonometric table generation,
 memory layout validation, and CUDA grid computation.
 """
 
+import atexit
+import contextlib
+import functools
+import inspect
 import math
+import sys
+import weakref
 import numpy as np
 import torch
 from numba import cuda
@@ -150,6 +156,64 @@ def _get_numba_external_stream_for(pt_stream=None):
     return numba_stream
 
 
+@contextlib.contextmanager
+def _cuda_context(device):
+    """Make ``device`` the current device for PyTorch and Numba.
+
+    Kernel launches then use the CUDA context and the current stream of the
+    device that holds the data, not of the device that happens to be current.
+    """
+    device = torch.device(device)
+    with torch.cuda.device(device), cuda.gpus[device.index]:
+        yield
+
+
+def _on_device_of(name):
+    """Run the decorated function in the CUDA context of its argument ``name``.
+
+    The argument may be passed by position or by keyword.
+    """
+    def decorate(fn):
+        signature = inspect.signature(fn)
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            bound = signature.bind_partial(*args, **kwargs).arguments
+            tensor = bound[name] if name in bound else None
+            if not (isinstance(tensor, torch.Tensor) and tensor.is_cuda):
+                return fn(*args, **kwargs)
+            with _cuda_context(tensor.device):
+                return fn(*args, **kwargs)
+        return wrapper
+    return decorate
+
+
+def _keep_cuda_modules_at_exit():
+    """Stop numba-cuda from unloading CUDA modules while the interpreter exits.
+
+    numba-cuda queues module unloads and flushes the queue once it holds more
+    than ``CUDA_DEALLOCS_COUNT`` items. After kernels were loaded on several
+    GPUs, a flush during interpreter shutdown can unload the same library twice
+    and corrupt the heap, so the process crashes after all work is done. The
+    process exit releases these resources anyway.
+    """
+    from numba.cuda.core import config as cuda_config
+
+    cuda_config.CUDA_DEALLOCS_COUNT = sys.maxsize
+    cuda_config.CUDA_DEALLOCS_RATIO = float("inf")
+
+
+class _ExitOrderAnchor:
+    pass
+
+
+# weakref.finalize registers its atexit hook with its first finalizer. Create one
+# now, so that the handler below is registered later and runs before it.
+_EXIT_ORDER_ANCHOR = _ExitOrderAnchor()
+weakref.finalize(_EXIT_ORDER_ANCHOR, lambda: None)
+atexit.register(_keep_cuda_modules_at_exit)
+
+
 # ============================================================================
 # GPU-aware Trigonometric Table Generation
 # ============================================================================
@@ -185,6 +249,8 @@ def _trig_tables(angles, dtype=_DTYPE, device=None):
     """
     if isinstance(angles, torch.Tensor):
         device = angles.device if device is None else device
+        if not isinstance(dtype, torch.dtype):
+            dtype = torch.from_numpy(np.zeros(0, dtype=dtype)).dtype
         # Compute both cos and sin in one call to avoid redundant kernel launches
         angles_device = angles.to(dtype=dtype, device=device)
         cos = torch.cos(angles_device)

{diffct-2.0.0 → diffct-2.0.1}/docs/video/README.md

@@ -6,6 +6,7 @@ and `docs/assets/diffct_intro.mp4`. Make the inputs on a CUDA GPU, then render a
 ```bash
 python docs/video/make_inputs.py --gpu      # walnut reconstructions; without --gpu only data2d.npz
 cd docs/video
+rm -f scenes.txt
 for s in S00Intro S01Trajectory S02Autograd S03Geometry S04MultiGPU S05Measured S06End; do
   manim -qh diffct_intro.py $s
   echo "file 'media/videos/diffct_intro/1080p60/$s.mp4'" >> scenes.txt
@@ -19,4 +20,4 @@ ffmpeg -i ../assets/diffct_intro.mp4 -i palette.png \
 
 The reconstructions come from the measured walnut in `examples/data/walnut_cone.npz`
 (Meaney 2022, CC BY 4.0; see `examples/data/NOTICE`). The timings in the multi-GPU scene
-are measured diffct results on A100 64 GB GPUs (Leonardo Booster); see `docs/assets/scaling.json`.
+are measured diffct results on A100 64 GB GPUs; see `docs/assets/scaling.json`.

{diffct-2.0.0 → diffct-2.0.1}/examples/README.md

@@ -130,74 +130,6 @@ These rules apply when you write your own loss with `Projector(..., distributed=
 
 `iterative_reconstruction.py` and `geometry_calibration.py` show these rules in use.
 
-## Results
-
-The following are recorded measurements from Leonardo Booster (A100 64 GB,
-PyTorch 2.10 cu126, numba-cuda 0.30.4) on 2026-10-09, not expected results for
-every GPU. See the [validation record](https://github.com/sypsyp97/diffct/blob/main/docs/VALIDATION.md) for related
-correctness and cross-node results.
-
-### Iterative reconstruction
-
-128³ Shepp-Logan, 360 views, one GPU, noise-free. Values are PSNR (dB).
-
-| trajectory | FDK | CGLS 30 it | SIRT 200 it | TV 200 it |
-| --- | ---: | ---: | ---: | ---: |
-| circular | 34.10 | 38.58 | 32.73 | 48.37 |
-| helical | 32.13 | 38.49 | 32.80 | 48.37 |
-| saddle | 29.83 | 38.82 | 32.63 | 48.27 |
-| sinusoidal | 33.84 | 38.49 | 32.76 | 48.50 |
-
-FDK is designed for the circular orbit and is approximate away from its central plane. For the other orbits the approximation is coarser.
-
-With 1% Gaussian noise (helical): FDK 31.19, CGLS 35.83, SIRT 32.68, TV 47.46.
-
-Time per iteration, same helical run (CGLS / SIRT / TV):
-
-| launch mode | CGLS | SIRT | TV |
-| --- | ---: | ---: | ---: |
-| 1 GPU | 69.2 ms | 66.2 ms | 67.5 ms |
-| one process, 4 GPUs | 22.7 ms | 20.3 ms | 21.7 ms |
-| torchrun, 4 GPUs | 19.3 ms | 17.5 ms | 18.5 ms |
-| torchrun, 8 GPUs on 2 nodes | 12.0 ms | 10.6 ms | 11.5 ms |
-
-PSNR is identical in every launch mode.
-
-### Projector scaling
-
-Circular scan, 360 views, detector (2n, 1.5n) with pitch 1.25, 128³ volume. Times are for 1 GPU, then 4 GPUs (1 node), then 8 GPUs (2 nodes). Speedup is relative to 1 GPU.
-
-| operation | 1 GPU | 4 GPUs | 8 GPUs (2 nodes) |
-| --- | ---: | ---: | ---: |
-| forward | 8.46 ms | 2.67 ms (3.2×) | 1.69 ms (5.0×) |
-| adjoint | 20.69 ms | 5.91 ms (3.5×) | 4.53 ms (4.6×) |
-| CGLS iteration | 30.07 ms | 8.09 ms (3.7×) | 5.54 ms (5.4×) |
-
-64³ CGLS iteration: 4.75 ms on 1 GPU, 1.57 ms on 4 GPUs (3.0×), 1.56 ms on 8 GPUs (3.0×). Small problems are dominated by transfers and kernel launches.
-
-### Analytical reconstruction
-
-128² and 128³ Shepp-Logan. PSNR (dB):
-
-| window | parallel FBP | fan FBP | cone FDK |
-| --- | ---: | ---: | ---: |
-| shepp-logan | 38.10 | 34.92 | 34.10 |
-| hann | 27.66 | 28.12 | 29.22 |
-
-The window and the detector sampling set the sharpness.
-
-### Geometry calibration
-
-64³ volume, 360 views. The true per-view angle error is 0.54° RMS. The true detector shift is (1.5, -1.0) voxels. Adam runs 300 steps.
-
-- Angle error after calibration: 0.0001° to 0.0025° RMS.
-- Detector shift: recovered to less than 0.001 voxel in every launch mode.
-- Time per step: 19.4 ms on 1 GPU, 8.2 ms on torchrun with 4 GPUs, 6.7 ms on 8 GPUs (2 nodes).
-
-### FDK check against ASTRA
-
-FDK from diffct matches ASTRA 2.5.0 `FDK_CUDA` on the same projections. The PSNR difference is within 0.3 dB. The maximum pixel difference is below 1% of the phantom maximum.
-
 ## Example scan
 
 The examples use this scan for an n³ volume, unit voxels:

{diffct-2.0.0 → diffct-2.0.1}/examples/data/NOTICE

@@ -28,10 +28,10 @@ been:
   - spatially binned 8x (2368x2240 -> 296x280 detector pixels),
   - cropped to the central 256x256 detector region,
   - angularly subsampled every 3rd view (721 -> 241 projections),
-  - flat-field normalised per-projection (using the 99.5th percentile
-    of each raw uint16 image as the "air" reference; no separate
-    dark scan is available in the source record, so we assume zero
-    dark field) and converted to line integrals via ``-log(I / I0)``,
+  - divided per projection by an air level I0 (the 99.5th percentile
+    of each image; the published projections are already dark- and
+    flat-field corrected) and converted to line integrals via
+    ``-log(I / I0)``,
   - stored as float16 in a compressed .npz together with the
     physical geometry (sdd, sid, binned pixel pitch, angles in
     radians in diffct handedness) plus regeneration metadata such

{diffct-2.0.0 → diffct-2.0.1}/formal/README.md

@@ -44,7 +44,7 @@ All finite domains and numerical tolerances are in the check files.
 Numba's [simulator documentation](https://nvidia.github.io/numba-cuda/user/simulator.html) describes its execution and limitations.
 The simulator executes Python kernel bodies—its arithmetic and scheduling do not establish the behavior of compiled GPU code.
 This suite does not verify CUDA type inference, LLVM fastmath, streams, multi-GPU execution, geometry gradients, or PyTorch autograd wrappers.
-The existing GPU validation remains necessary for those paths; see [VALIDATION.md](../docs/VALIDATION.md).
+The GPU test suite in `tests/` covers those paths on a CUDA machine.
 
 ## Installation
 

{diffct-2.0.0 → diffct-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "diffct"
-version = "2.0.0"
+version = "2.0.1"
 description = "Differentiable CUDA projectors for CT: arbitrary trajectories, multi-GPU and multi-node execution, geometry gradients"
 readme = "README.md"
 requires-python = ">=3.10"

{diffct-2.0.0 → diffct-2.0.1}/tests/benchmarks/README.md

@@ -11,7 +11,7 @@ test suite stays fast.
 Run everything:
 
 ```bash
-/c/Users/sun/miniconda3/envs/cuda12/python.exe -m pytest tests/benchmarks/ \
+python -m pytest tests/benchmarks/ \
     --benchmark-only --benchmark-columns=min,mean,median,stddev,rounds
 ```
 

diffct-2.0.1/tests/test_multi_gpu_exit.py

@@ -0,0 +1,83 @@
+"""Interpreter shutdown after CUDA kernels run on two devices."""
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+import textwrap
+
+import pytest
+import torch
+
+
+@pytest.mark.cuda
+def test_multi_gpu_exit():
+    if torch.cuda.device_count() < 2:
+        pytest.skip("At least two CUDA devices are required")
+
+    workload = textwrap.dedent("""\
+        import torch
+        import diffct
+
+        for index in (0, 1):
+            device = torch.device(f"cuda:{index}")
+            with torch.cuda.device(device):
+                parallel = diffct.circular_trajectory_2d_parallel(4, device=device)
+                fan = diffct.circular_trajectory_2d_fan(
+                    4, sid=20.0, sdd=30.0, device=device
+                )
+                for geometry, projector, backprojector, weighted in (
+                    (parallel, diffct.ParallelProjectorFunction,
+                     diffct.ParallelBackprojectorFunction,
+                     diffct.parallel_weighted_backproject),
+                    (fan, diffct.FanProjectorFunction,
+                     diffct.FanBackprojectorFunction,
+                     diffct.fan_weighted_backproject),
+                ):
+                    image = torch.ones(
+                        (8, 8), device=device, dtype=torch.float32,
+                        requires_grad=True,
+                    )
+                    projected = projector.apply(image, *geometry, 12, 1.0)
+                    projected.sum().backward()
+                    sinogram = projected.detach().requires_grad_(True)
+                    backprojector.apply(sinogram, *geometry, 1.0, 8, 8).sum().backward()
+                    weighted(sinogram.detach(), *geometry, 1.0, 8, 8)
+
+                cone = diffct.circular_trajectory_3d(
+                    4, sid=20.0, sdd=30.0, device=device
+                )
+                volume = torch.ones(
+                    (4, 4, 4), device=device, dtype=torch.float32,
+                    requires_grad=True,
+                )
+                projected = diffct.ConeProjectorFunction.apply(
+                    volume, *cone, 8, 8, 1.0, 1.0,
+                )
+                projected.sum().backward()
+                sinogram = projected.detach().requires_grad_(True)
+                diffct.ConeBackprojectorFunction.apply(
+                    sinogram, *cone, 4, 4, 4, 1.0, 1.0,
+                ).sum().backward()
+                diffct.cone_weighted_backproject(
+                    sinogram.detach(), *cone, 4, 4, 4, 1.0, 1.0,
+                )
+                torch.cuda.synchronize(device)
+        """)
+    env = os.environ.copy()
+    repository = Path(__file__).resolve().parents[1]
+    env["PYTHONPATH"] = os.pathsep.join([
+        str(repository),
+        *(str(Path(entry or os.getcwd()).resolve()) for entry in sys.path),
+    ])
+    child = subprocess.run(
+        [sys.executable, "-c", workload],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=300,
+    )
+    assert child.returncode == 0, (
+        f"CUDA subprocess exited with return code {child.returncode}\n"
+        f"Child stderr tail:\n{child.stderr[-8000:]}"
+    )

diffct-2.0.1/tests/test_release_2_0_1.py

@@ -0,0 +1,326 @@
+"""Release contracts for device selection, geometry, and walnut examples."""
+
+import doctest
+import importlib
+import io
+import math
+import sys
+import zipfile
+from functools import partial
+from pathlib import Path
+
+import numpy as np
+import pytest
+import torch
+
+
+ROOT = Path(__file__).resolve().parents[1]
+FUNCTIONS = [
+    "ParallelProjectorFunction", "ParallelBackprojectorFunction",
+    "FanProjectorFunction", "FanBackprojectorFunction",
+    "ConeProjectorFunction", "ConeBackprojectorFunction",
+]
+BEAMS = ["parallel", "fan", "cone"]
+requires_cuda = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="requires CUDA"
+)
+requires_two_gpus = pytest.mark.skipif(
+    torch.cuda.device_count() < 2, reason="requires two CUDA devices"
+)
+
+
+@pytest.fixture
+def examples(monkeypatch):
+    monkeypatch.syspath_prepend(str(ROOT / "examples"))
+    return importlib.import_module("data.preprocess_walnut")
+
+
+def trajectory(beam, device):
+    geometry = importlib.import_module("diffct.geometry")
+    if beam == "parallel":
+        return geometry.circular_trajectory_2d_parallel(5, start_angle=0.13, device=device)
+    if beam == "fan":
+        return geometry.circular_trajectory_2d_fan(5, 20.0, 35.0, start_angle=0.13, device=device)
+    return geometry.circular_trajectory_3d(5, 20.0, 35.0, start_angle=0.13, device=device)
+
+
+def function_arguments(name, geometry):
+    if name == "ConeProjectorFunction":
+        return (*geometry, 9, 7, 0.9, 1.1, 0.8)
+    if name == "ConeBackprojectorFunction":
+        return (*geometry, 4, 6, 8, 0.9, 1.1, 0.8)
+    if "Backprojector" in name:
+        return (*geometry, 0.9, 6, 8, 0.8)
+    return (*geometry, 9, 0.9, 0.8)
+
+
+@pytest.mark.cuda
+@requires_two_gpus
+@pytest.mark.parametrize("name", FUNCTIONS)
+def test_function_uses_input_cuda_device_for_output_and_gradients(name):
+    projectors = importlib.import_module("diffct.projectors")
+    beam = next(beam for beam in BEAMS if name.lower().startswith(beam))
+    geometry = trajectory(beam, "cuda:1")
+    if "Backprojector" in name:
+        shape = (5, 9, 7) if beam == "cone" else (5, 9)
+    else:
+        shape = (4, 6, 8) if beam == "cone" else (6, 8)
+    data = torch.linspace(0.1, 0.9, math.prod(shape), device="cuda:1").reshape(shape)
+
+    def evaluate(current_device):
+        with torch.cuda.device(current_device):
+            inputs = [value.detach().clone().requires_grad_() for value in (data, *geometry)]
+            result = getattr(projectors, name).apply(
+                inputs[0], *function_arguments(name, inputs[1:])
+            )
+            assert result.device == torch.device("cuda:1")
+            assert torch.isfinite(result).all()
+            weights = torch.linspace(0.2, 1.0, result.numel(), device="cuda:1").reshape(result.shape)
+            gradients = torch.autograd.grad(result, inputs, grad_outputs=weights)
+            torch.cuda.synchronize(1)
+            assert torch.cuda.current_device() == current_device
+            for gradient in gradients:
+                assert gradient.device == torch.device("cuda:1")
+                assert torch.isfinite(gradient).all()
+            return result.detach(), tuple(gradient.detach() for gradient in gradients)
+
+    expected, expected_gradients = evaluate(1)
+    actual, actual_gradients = evaluate(0)
+    torch.testing.assert_close(actual, expected, rtol=1e-5, atol=1e-6)
+    for actual_gradient, expected_gradient in zip(actual_gradients, expected_gradients):
+        torch.testing.assert_close(actual_gradient, expected_gradient, rtol=1e-5, atol=1e-6)
+
+
+@pytest.mark.cuda
+@requires_two_gpus
+@pytest.mark.parametrize("beam", BEAMS)
+def test_analytical_backprojection_uses_input_cuda_device(beam):
+    analytical = importlib.import_module("diffct.analytical")
+    geometry = trajectory(beam, "cuda:1")
+    shape = (5, 9, 7) if beam == "cone" else (5, 9)
+    sinogram = torch.linspace(0.1, 0.9, math.prod(shape), device="cuda:1").reshape(shape)
+    sizes = (4, 6, 8, 0.9, 1.1) if beam == "cone" else (0.9, 6, 8)
+    function = getattr(analytical, f"{beam}_weighted_backproject")
+
+    def evaluate(current_device):
+        with torch.cuda.device(current_device):
+            result = function(sinogram, *geometry, *sizes, voxel_spacing=0.8)
+            assert result.device == torch.device("cuda:1")
+            torch.cuda.synchronize(1)
+            assert torch.isfinite(result).all()
+            assert torch.cuda.current_device() == current_device
+            return result
+
+    torch.testing.assert_close(evaluate(0), evaluate(1), rtol=1e-5, atol=1e-6)
+
+
+def weighted_backprojection_arguments(beam, device):
+    geometry = trajectory(beam, device)
+    shape = (5, 9, 7) if beam == "cone" else (5, 9)
+    sinogram = torch.linspace(0.1, 0.9, math.prod(shape), device=device).reshape(shape)
+    if beam == "cone":
+        names = ("sinogram", "src_pos", "det_center", "det_u_vec", "det_v_vec",
+                 "D", "H", "W", "du", "dv", "voxel_spacing")
+        args = (sinogram, *geometry, 4, 6, 8, 0.9, 1.1, 0.8)
+    else:
+        geometry_names = ("ray_dir", "det_origin", "det_u_vec") if beam == "parallel" else (
+            "src_pos", "det_center", "det_u_vec"
+        )
+        names = ("sinogram", *geometry_names, "detector_spacing", "H", "W", "voxel_spacing")
+        args = (sinogram, *geometry, 0.9, 6, 8, 0.8)
+    keyword_only = {} if beam == "parallel" else {
+        "isocenter": torch.zeros(3 if beam == "cone" else 2, device=device)
+    }
+    return args, dict(zip(names, args), **keyword_only), keyword_only
+
+
+@pytest.mark.cuda
+@requires_cuda
+@pytest.mark.parametrize("beam", BEAMS)
+def test_analytical_backprojection_accepts_all_arguments_by_keyword(beam):
+    analytical = importlib.import_module("diffct.analytical")
+    function = getattr(analytical, f"{beam}_weighted_backproject")
+    args, kwargs, keyword_only = weighted_backprojection_arguments(beam, "cuda:0")
+    with torch.cuda.device(0):
+        expected = function(*args, **keyword_only)
+        actual = function(**kwargs)
+        assert actual.device == args[0].device
+        assert torch.isfinite(actual).all()
+        torch.testing.assert_close(actual, expected, rtol=1e-5, atol=1e-6)
+
+
+@pytest.mark.cuda
+@requires_two_gpus
+@pytest.mark.parametrize("beam", BEAMS)
+def test_analytical_keyword_backprojection_uses_input_cuda_device(beam):
+    analytical = importlib.import_module("diffct.analytical")
+    function = getattr(analytical, f"{beam}_weighted_backproject")
+    args, kwargs, keyword_only = weighted_backprojection_arguments(beam, "cuda:1")
+    with torch.cuda.device(1):
+        expected = function(*args, **keyword_only)
+    with torch.cuda.device(0):
+        actual = function(**kwargs)
+        assert actual.device == torch.device("cuda:1")
+        torch.cuda.synchronize(1)
+        assert torch.cuda.current_device() == 0
+        assert torch.isfinite(actual).all()
+        torch.testing.assert_close(actual, expected, rtol=1e-5, atol=1e-6)
+
+
+@pytest.mark.parametrize("dimensions", [2, 3])
+@pytest.mark.parametrize("bad_value", [0.0, math.nan, math.inf, -math.inf], ids=["origin", "nan", "inf", "negative-inf"])
+@pytest.mark.parametrize("bad_view", [0, 2, 4])
+def test_custom_trajectory_rejects_invalid_source(dimensions, bad_value, bad_view):
+    geometry = importlib.import_module("diffct.geometry")
+    function = geometry.custom_trajectory_3d if dimensions == 3 else geometry.custom_trajectory_2d_fan
+
+    def source_path(angles, sid):
+        positions = torch.zeros((len(angles), dimensions), device=angles.device, dtype=angles.dtype)
+        positions[:, 0] = -sid * torch.sin(angles)
+        positions[:, 1] = sid * torch.cos(angles)
+        positions[bad_view] = bad_value
+        return positions
+
+    with pytest.raises(ValueError):
+        function(5, 20.0, 35.0, source_path, device="cpu")
+
+
+def test_figure8_docstring_example_is_finite_and_constructs_projector():
+    import diffct
+
+    function = diffct.custom_trajectory_3d
+    snippets = doctest.DocTestParser().get_examples(function.__doc__)
+    assert any("def figure8_path" in snippet.source for snippet in snippets)
+    namespace = {"torch": torch, "custom_trajectory_3d": partial(function, device="cpu")}
+    for snippet in snippets:
+        exec(compile(snippet.source, "<custom_trajectory_3d docstring>", "exec"), namespace)
+    geometry = tuple(namespace[name] for name in ("src_pos", "det_center", "det_u_vec", "det_v_vec"))
+    assert all(value.device.type == "cpu" for value in geometry)
+    assert all(torch.isfinite(value).all() for value in geometry)
+    assert (torch.linalg.vector_norm(geometry[0], dim=1) > 0).all()
+    operator = diffct.Projector(geometry, (8, 8, 8), (9, 7))
+    assert operator is not None
+
+
+@pytest.mark.cuda
+@requires_cuda
+@pytest.mark.parametrize("name", FUNCTIONS)
+def test_function_class_docstring_example(name):
+    projectors = importlib.import_module("diffct.projectors")
+    function = getattr(projectors, name)
+    example = doctest.DocTestParser().get_doctest(
+        function.__doc__, {}, name, str(ROOT / "diffct" / "projectors.py"), 0
+    )
+    assert example.examples
+    runner = doctest.DocTestRunner()
+    result = runner.run(example)
+    assert result.failed == 0
+    assert result.attempted == len(example.examples)
+
+
+def kept_region_offset(raw_size, bin_factor, crop):
+    """Compute the midpoint of the kept raw-pixel interval from the contract."""
+    binned = raw_size // bin_factor
+    size = binned if crop == 0 else crop
+    start = (binned - size) // 2
+    left_edge = start * bin_factor
+    right_edge = (start + size) * bin_factor
+    return (left_edge + right_edge) / 2 - raw_size / 2
+
+
+@pytest.mark.parametrize("raw_size,bin_factor,crop", [
+    (2240, 8, 256), (2368, 8, 256), (2240, 8, 255),
+    (2368, 8, 255), (11, 2, 0), (11, 2, 4), (12, 2, 3),
+    (13, 3, 3), (14, 3, 0), (9, 1, 4), (8, 1, 3), (9, 1, 3),
+])
+def test_detector_center_offset(examples, raw_size, bin_factor, crop):
+    expected = kept_region_offset(raw_size, bin_factor, crop)
+    assert examples.detector_center_offset(raw_size, bin_factor, crop) == expected
+
+
+def test_preprocess_without_projection_zips_raises(examples, tmp_path, monkeypatch):
+    output = tmp_path / "result.npz"
+    monkeypatch.setattr(sys, "argv", ["preprocess_walnut.py", str(output), str(tmp_path), "--view-stride", "721"])
+    with pytest.raises(FileNotFoundError):
+        examples.main()
+    assert not output.exists()
+
+
+@pytest.mark.parametrize("projection_number", [1, 2, 721])
+def test_preprocess_kept_projection_presence(examples, tmp_path, monkeypatch, projection_number):
+    tifffile = pytest.importorskip("tifffile")
+    image = np.full((2368, 2240), 1000, dtype=np.uint16)
+    buffer = io.BytesIO()
+    tifffile.imwrite(buffer, image)
+    with zipfile.ZipFile(tmp_path / "20201111_walnut_projections_1.zip", "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr(f"nested/20201111_walnut_{projection_number:04d}.tif", buffer.getvalue())
+    output = tmp_path / "result.npz"
+    monkeypatch.setattr(sys, "argv", ["preprocess_walnut.py", str(output), str(tmp_path), "--view-stride", "721"])
+    if projection_number == 1:
+        examples.main()
+        with np.load(output) as data:
+            assert data["sinogram"].shape == (1, 256, 256)
+            np.testing.assert_array_equal(data["sinogram"], np.zeros((1, 256, 256)))
+            np.testing.assert_array_equal(data["view_indices"], [0])
+    else:
+        with pytest.raises(ValueError, match="missing"):
+            examples.main()
+        assert not output.exists()
+
+
+@pytest.mark.parametrize("bin_factor,crop_h,crop_w,du,dv", [
+    (8, 255, 255, 0.4, 0.4), (7, 0, 0, 0.35, 0.35),
+    (8, 255, 256, 0.4, 0.4), (8, 255, 255, 0.4, 0.6),
+])
+def test_load_scan_detector_offsets(examples, tmp_path, bin_factor, crop_h, crop_w, du, dv):
+    walnut = importlib.import_module("walnut_reconstruction")
+    path = tmp_path / "scan.npz"
+    stored = np.arange(24, dtype=np.float16).reshape(2, 3, 4)
+    angles = np.array([0.0, 0.7], dtype=np.float64)
+    np.savez(path, sinogram=stored, angles=angles, sid=20.0, sdd=35.0,
+             du=du, dv=dv, detector_bin=bin_factor, crop_h=crop_h, crop_w=crop_w)
+    result = walnut.load_scan(path)
+    assert len(result) == 8
+    sinogram, actual_angles, sid, sdd, actual_du, actual_dv, offset_u, offset_v = result
+    np.testing.assert_array_equal(sinogram, stored.astype(np.float32).transpose(0, 2, 1))
+    np.testing.assert_array_equal(actual_angles, angles)
+    assert (sid, sdd, actual_du, actual_dv) == (20.0, 35.0, du, dv)
+    assert offset_u == pytest.approx(kept_region_offset(2240, bin_factor, crop_w) * du / bin_factor)
+    assert offset_v == pytest.approx(kept_region_offset(2368, bin_factor, crop_h) * dv / bin_factor)
+
+
+@pytest.mark.parametrize("offset_u,offset_v", [(0.0, 0.0), (1.25, 0.0), (0.0, -2.5), (-1.25, 2.5)])
+def test_circular_geometry_moves_detector_along_axes(examples, offset_u, offset_v):
+    walnut = importlib.import_module("walnut_reconstruction")
+    angles = np.array([0.0, math.pi / 2, 0.37])
+    source, detector, u_axis, v_axis = walnut.circular_geometry(angles, 20.0, 35.0, offset_u, offset_v)
+    sin, cos = np.sin(angles), np.cos(angles)
+    zero = np.zeros_like(angles)
+    expected_u = np.column_stack((cos, sin, zero))
+    expected_v = np.column_stack((zero, zero, np.ones_like(angles)))
+    nominal_detector = np.column_stack((15 * sin, -15 * cos, zero))
+    np.testing.assert_allclose(source.numpy(), np.column_stack((-20 * sin, 20 * cos, zero)), rtol=1e-6, atol=1e-6)
+    np.testing.assert_allclose(u_axis.numpy(), expected_u, rtol=1e-6, atol=1e-6)
+    np.testing.assert_allclose(v_axis.numpy(), expected_v, rtol=1e-6, atol=1e-6)
+    np.testing.assert_allclose(detector.numpy(), nominal_detector + offset_u * expected_u + offset_v * expected_v,
+                               rtol=1e-6, atol=1e-6)
+
+
+@pytest.mark.parametrize("values", [[0.0, 0.0], [0.1, 0.7, -0.2]])
+def test_psnr_identical_images_is_positive_infinity(examples, values):
+    common = importlib.import_module("_common")
+    image = torch.tensor(values, dtype=torch.float32)
+    assert common.psnr(image.clone(), image) == math.inf
+
+
+@pytest.mark.parametrize("beam", BEAMS)
+def test_projector_process_group_is_none_and_read_only(beam):
+    import diffct
+
+    shape = (4, 6, 8) if beam == "cone" else (6, 8)
+    detector = (9, 7) if beam == "cone" else 9
+    operator = diffct.Projector(trajectory(beam, "cpu"), shape, detector, beam=beam)
+    assert operator.process_group is None
+    with pytest.raises(AttributeError):
+        operator.process_group = object()
+    assert operator.process_group is None