diffct 2.1.0__tar.gz → 2.2.1__tar.gz

{diffct-2.1.0 → diffct-2.2.1}/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.1] - 2026-10-13
+
+### Added
+
+- Public differentiable `fbp`, `fdk` and approximate slice-windowed `helical_fdk`
+  pipelines, with replaceable projection, angular and frequency-response tensors.
+  Low-precision measurements run in float32 and keep gradients in their own dtype.
+- Dedicated CUDA transposes of the analytical parallel/fan/cone gathers,
+  including sinogram gradients and higher derivatives with fixed geometry.
+- Circular short-scan checks for `short_scan=True`: orbit, detector-u handedness,
+  angular span, and constant detector distance and offset. Tolerances follow the
+  physical geometry scale and the original trajectory precision.
+- Public helical view weights and weighted gather. Slice centers and angular
+  quadrature use float64, so large angle or height offsets keep full-turn coverage.
+- Examples `learnable_reconstruction.py` and `helical_fdk.py`, and the
+  analytical learning guide.
+
+### Changed
+
+- `parallel_weighted_backproject`, `fan_weighted_backproject` and
+  `cone_weighted_backproject` support sinogram autograd. Geometry and isocenter
+  gradients raise an error.
+- The FDK baselines in `examples/_common.py` and `walnut_reconstruction.py` call `fdk`.
+
+## [2.2.0] - 2026-10-11
+
+### Added
+
+- Operation-specific automatic schedules and slab/block comparisons for
+  native projection and matched backprojection, with bounded CUDA pilots
+  and per-call execution/copy metadata.
+- Detector-pixel tiling and explicit `ParameterizedSurface` batches using
+  global pixel/view coordinates, saved parameter/frame values and local VJP
+  reduction. Legacy two-argument surface callbacks remain compatible.
+- Caller-owned numerical `project_into`/`backproject_into` outputs, tensor
+  block access and mapped `.npy` stores for data exceeding host RAM.
+- Distributed `partition="space"` with fixed volume slabs, ownership-aware
+  autograd/norms and disk CGLS state/checkpoints without full-volume gathering.
+- Independent CUDA tests and bounded formal protocol/ownership verification.
+
+### Changed
+
+- GPU backprojection accumulators now span all contributing view batches,
+  with final transfer after tile completion. Contiguous native volume layouts
+  and ray buffers are reused across batches.
+- Transfer execution uses bounded pinned slots, separate streams and events;
+  all extra staging/cached GPU buffers are included in capacity estimates.
+  Local GPU and NCCL reductions occur before completed-result downloads.
+- Example CGLS norms accumulate FP64 blocks and vector updates reuse buffers.
+  The disk example keeps all three volume states plus residual/projection state
+  blockwise and retains `q` until the global `alpha` decision.
+
+### Fixed
+
+- Tensor CGLS ranks agree on CPU fallback before jointly replanning unequal
+  spatial shards, preserving collective order.
+- Parameterized detector surfaces use a common arithmetic dtype of at least
+  float32, supporting mixed frame dtypes and finite half-precision inputs.
+- CUDA store uploads wait for newly generated blocks on their source stream,
+  including transfers within one GPU.
+- Single-slot execution retires prior native computation before allocating
+  the next tile, keeping deferred CUDA allocations within its admission bound.
+- Mapped input and output stores reject hard links to the same file before writes.
+- Example PSNR supports CPU reconstruction results with CUDA reference volumes.
+- Deferred CPU output writes retain their submission order across spatial tiles.
+- Coronal slice displays preserve the measured detector row orientation.
+
 ## [2.1.0] - 2026-10-10
 
 ### Added

{diffct-2.1.0 → diffct-2.2.1}/CITATION.cff

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

{diffct-2.1.0 → diffct-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.1.0
+Version: 2.2.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/
@@ -65,8 +65,6 @@ Description-Content-Type: text/markdown
   <a href="#citation">Citation</a>
 </p>
 
-> **Install** with the CUDA extra, `pip install "diffct[cu12]"` or `pip install "diffct[cu13]"`, after PyTorch. A plain `pip install diffct` needs a system CUDA Toolkit.
->
 > **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).
 
@@ -75,11 +73,11 @@ Description-Content-Type: text/markdown
 To our knowledge, diffct is the only open-source GPU CT library that combines arbitrary per-view trajectories, autograd through the volume, first-order gradients through the acquisition geometry, and built-in multi-GPU and multi-node execution. We compared it with LEAP, TIGRE, ASTRA/tomosipo, DiffDRR and others in October 2026.
 
 - **Arbitrary trajectories.** Each view has its own source, detector centre and detector axes. Circular, helical, saddle, sinusoidal, random and calibrated scans use the same code. Trajectory tensors with `requires_grad=True` receive geometry gradients for calibration.
-- **Curved detectors.** A `detector_surface(u, v)` callback defines each pixel's position for arc, cylindrical or other parameterized surfaces. Projection and matched backprojection support first-order surface gradients. See [the surface API](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#parameterized-detector-surfaces).
+- **Curved detectors.** `ParameterizedSurface` defines native arc, cylindrical or arbitrary pixels from global coordinates and explicit parameters, sampled in bounded view/pixel batches. Legacy `detector_surface(u, v)` callbacks remain available. Projection and matched backprojection support first-order surface gradients. See [the surface API](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#parameterized-detector-surfaces).
 - **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.** CPU volumes and sinograms automatically stream spatial tiles and view batches through CUDA. Full arrays and data gradients stay on CPU; tile sizes follow the available device memory and can be overridden. 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 one process per GPU with torchrun and NCCL. Views are partitioned. CPU-backed volumes stay in host RAM while GPUs compute tiles; distributed ranks retain replicated-volume semantics. 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.
+- **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. Default `partition="views"` shards projections and replicates volumes. `partition="space"` gives each rank an owned volume slab and combines ray contributions. Speedup depends on workload and communication costs.
+- **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).
 
 Capabilities, limits and isocenter rules: [docs/REFERENCE.md](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#capabilities-and-limits).
 
@@ -140,7 +138,7 @@ loss.backward()                     # x.grad = A^T (A x - y)
 
 **Geometry gradients.** Set `requires_grad=True` on trajectory tensors before you build `Projector`. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
 
-**Several GPUs and nodes.** Use `devices=[0, 1, 2, 3]` in one process, or one process per GPU with torchrun for one or more nodes. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#several-gpus-and-nodes) and [DISTRIBUTED.md](https://github.com/sypsyp97/diffct/blob/main/docs/DISTRIBUTED.md).
+**Several GPUs and nodes.** See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#several-gpus-and-nodes) and [DISTRIBUTED.md](https://github.com/sypsyp97/diffct/blob/main/docs/DISTRIBUTED.md).
 
 ```python
 A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, devices=[0, 1, 2, 3])
@@ -161,29 +159,36 @@ sinogram.square().mean().backward()          # CPU volume.grad
 Run `python examples/chunked_reconstruction.py` for CPU-backed CGLS and measured
 CUDA allocation. Chunking preserves the Siddon model, with float32 summation
 differences; smaller blocks can increase transfer and launch overhead. Full
-arrays and iterative state still need enough host RAM.
+tensor arrays and iterative state still need enough host RAM. For disk-backed
+state and sharded checkpoints, run
+`python examples/disk_reconstruction.py --output disk-run`; for fixed rank-local
+volume slabs use `--partition space` under torchrun. Run
+`python examples/benchmark_execution.py` to compare schedules and copy payloads.
 
 ## Performance
 
 <p align="center">
   <picture>
-    <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, 64^3 and 128^3">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.2.0">
+    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png?v=2.2.0" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
   </picture>
 </p>
 
-| 128³ volume | 1 GPU | 4 GPUs, 1 node | 8 GPUs, 2 nodes |
+| 512³ volume | 1 GPU | 4 GPUs, 1 node | 8 GPUs, 2 nodes |
 |---|---:|---:|---:|
-| Forward projection | 8.45 ms | 2.66 ms (3.2×) | 1.68 ms (5.0×) |
-| 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×) |
+| Forward projection | 493.05 ms | 132.22 ms (3.7×) | 73.18 ms (6.7×) |
+| Adjoint (backprojection) | 1400.80 ms | 369.29 ms (3.8×) | 265.87 ms (5.3×) |
+| CGLS iteration | 2054.36 ms | 547.06 ms (3.8×) | 373.38 ms (5.5×) |
 
-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](https://github.com/sypsyp97/diffct/blob/main/docs/assets/scaling.json).
+diffct 2.2.0, FP32, A100 64 GB GPUs; circular cone beam, 360 views, 1024×768 detector, pitch 1.25. Default memory settings, without an imposed allocator cap.
 
-To measure one against several GPUs on your machine (default scan of the script, not the table setup):
+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).
+
+Run the same workload:
 
 ```bash
-python examples/benchmark_projector.py --devices 0 1
+python examples/benchmark_scaling.py --output one.json
+torchrun --standalone --nproc-per-node=4 examples/benchmark_scaling.py --expected-nodes 1 --output four.json
 ```
 
 ## Gallery
@@ -215,7 +220,7 @@ Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](
 
 ## Examples
 
-`quickstart.py`, `curved_detector.py`, `chunked_reconstruction.py`, `analytical_reconstruction.py`, `iterative_reconstruction.py`, `walnut_reconstruction.py`, `geometry_calibration.py`, `benchmark_projector.py`, `plot_trajectory.py`, and the Slurm template `slurm/multi_node.sbatch`. Launch modes and distributed-loss rules are in [examples/README.md](https://github.com/sypsyp97/diffct/blob/main/examples/README.md).
+`quickstart.py`, `curved_detector.py`, `chunked_reconstruction.py`, `disk_reconstruction.py`, `benchmark_execution.py`, `analytical_reconstruction.py`, `learnable_reconstruction.py`, `helical_fdk.py`, `iterative_reconstruction.py`, `walnut_reconstruction.py`, `geometry_calibration.py`, `benchmark_projector.py`, `benchmark_scaling.py`, `plot_trajectory.py`, and the Slurm template `slurm/multi_node.sbatch`. Launch modes and distributed-loss rules are in [examples/README.md](https://github.com/sypsyp97/diffct/blob/main/examples/README.md).
 
 ## Documentation
 

{diffct-2.1.0 → diffct-2.2.1}/README.md

@@ -34,8 +34,6 @@
   <a href="#citation">Citation</a>
 </p>
 
-> **Install** with the CUDA extra, `pip install "diffct[cu12]"` or `pip install "diffct[cu13]"`, after PyTorch. A plain `pip install diffct` needs a system CUDA Toolkit.
->
 > **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).
 
@@ -44,11 +42,11 @@
 To our knowledge, diffct is the only open-source GPU CT library that combines arbitrary per-view trajectories, autograd through the volume, first-order gradients through the acquisition geometry, and built-in multi-GPU and multi-node execution. We compared it with LEAP, TIGRE, ASTRA/tomosipo, DiffDRR and others in October 2026.
 
 - **Arbitrary trajectories.** Each view has its own source, detector centre and detector axes. Circular, helical, saddle, sinusoidal, random and calibrated scans use the same code. Trajectory tensors with `requires_grad=True` receive geometry gradients for calibration.
-- **Curved detectors.** A `detector_surface(u, v)` callback defines each pixel's position for arc, cylindrical or other parameterized surfaces. Projection and matched backprojection support first-order surface gradients. See [the surface API](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#parameterized-detector-surfaces).
+- **Curved detectors.** `ParameterizedSurface` defines native arc, cylindrical or arbitrary pixels from global coordinates and explicit parameters, sampled in bounded view/pixel batches. Legacy `detector_surface(u, v)` callbacks remain available. Projection and matched backprojection support first-order surface gradients. See [the surface API](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#parameterized-detector-surfaces).
 - **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.** CPU volumes and sinograms automatically stream spatial tiles and view batches through CUDA. Full arrays and data gradients stay on CPU; tile sizes follow the available device memory and can be overridden. 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 one process per GPU with torchrun and NCCL. Views are partitioned. CPU-backed volumes stay in host RAM while GPUs compute tiles; distributed ranks retain replicated-volume semantics. 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.
+- **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. Default `partition="views"` shards projections and replicates volumes. `partition="space"` gives each rank an owned volume slab and combines ray contributions. Speedup depends on workload and communication costs.
+- **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).
 
 Capabilities, limits and isocenter rules: [docs/REFERENCE.md](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#capabilities-and-limits).
 
@@ -109,7 +107,7 @@ loss.backward()                     # x.grad = A^T (A x - y)
 
 **Geometry gradients.** Set `requires_grad=True` on trajectory tensors before you build `Projector`. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
 
-**Several GPUs and nodes.** Use `devices=[0, 1, 2, 3]` in one process, or one process per GPU with torchrun for one or more nodes. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#several-gpus-and-nodes) and [DISTRIBUTED.md](https://github.com/sypsyp97/diffct/blob/main/docs/DISTRIBUTED.md).
+**Several GPUs and nodes.** See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#several-gpus-and-nodes) and [DISTRIBUTED.md](https://github.com/sypsyp97/diffct/blob/main/docs/DISTRIBUTED.md).
 
 ```python
 A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, devices=[0, 1, 2, 3])
@@ -130,29 +128,36 @@ sinogram.square().mean().backward()          # CPU volume.grad
 Run `python examples/chunked_reconstruction.py` for CPU-backed CGLS and measured
 CUDA allocation. Chunking preserves the Siddon model, with float32 summation
 differences; smaller blocks can increase transfer and launch overhead. Full
-arrays and iterative state still need enough host RAM.
+tensor arrays and iterative state still need enough host RAM. For disk-backed
+state and sharded checkpoints, run
+`python examples/disk_reconstruction.py --output disk-run`; for fixed rank-local
+volume slabs use `--partition space` under torchrun. Run
+`python examples/benchmark_execution.py` to compare schedules and copy payloads.
 
 ## Performance
 
 <p align="center">
   <picture>
-    <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, 64^3 and 128^3">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.2.0">
+    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png?v=2.2.0" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
   </picture>
 </p>
 
-| 128³ volume | 1 GPU | 4 GPUs, 1 node | 8 GPUs, 2 nodes |
+| 512³ volume | 1 GPU | 4 GPUs, 1 node | 8 GPUs, 2 nodes |
 |---|---:|---:|---:|
-| Forward projection | 8.45 ms | 2.66 ms (3.2×) | 1.68 ms (5.0×) |
-| 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×) |
+| Forward projection | 493.05 ms | 132.22 ms (3.7×) | 73.18 ms (6.7×) |
+| Adjoint (backprojection) | 1400.80 ms | 369.29 ms (3.8×) | 265.87 ms (5.3×) |
+| CGLS iteration | 2054.36 ms | 547.06 ms (3.8×) | 373.38 ms (5.5×) |
 
-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](https://github.com/sypsyp97/diffct/blob/main/docs/assets/scaling.json).
+diffct 2.2.0, FP32, A100 64 GB GPUs; circular cone beam, 360 views, 1024×768 detector, pitch 1.25. Default memory settings, without an imposed allocator cap.
 
-To measure one against several GPUs on your machine (default scan of the script, not the table setup):
+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).
+
+Run the same workload:
 
 ```bash
-python examples/benchmark_projector.py --devices 0 1
+python examples/benchmark_scaling.py --output one.json
+torchrun --standalone --nproc-per-node=4 examples/benchmark_scaling.py --expected-nodes 1 --output four.json
 ```
 
 ## Gallery
@@ -184,7 +189,7 @@ Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](
 
 ## Examples
 
-`quickstart.py`, `curved_detector.py`, `chunked_reconstruction.py`, `analytical_reconstruction.py`, `iterative_reconstruction.py`, `walnut_reconstruction.py`, `geometry_calibration.py`, `benchmark_projector.py`, `plot_trajectory.py`, and the Slurm template `slurm/multi_node.sbatch`. Launch modes and distributed-loss rules are in [examples/README.md](https://github.com/sypsyp97/diffct/blob/main/examples/README.md).
+`quickstart.py`, `curved_detector.py`, `chunked_reconstruction.py`, `disk_reconstruction.py`, `benchmark_execution.py`, `analytical_reconstruction.py`, `learnable_reconstruction.py`, `helical_fdk.py`, `iterative_reconstruction.py`, `walnut_reconstruction.py`, `geometry_calibration.py`, `benchmark_projector.py`, `benchmark_scaling.py`, `plot_trajectory.py`, and the Slurm template `slurm/multi_node.sbatch`. Launch modes and distributed-loss rules are in [examples/README.md](https://github.com/sypsyp97/diffct/blob/main/examples/README.md).
 
 ## Documentation
 

{diffct-2.1.0 → diffct-2.2.1}/diffct/__init__.py

@@ -15,6 +15,15 @@ from .projectors import (
 )
 
 from .operators import Projector
+from .storage import TensorStore, NpyStore
+from .surfaces import ParameterizedSurface
+from .reconstruction import (
+    fbp,
+    fdk,
+    helical_fdk,
+    helical_view_weights,
+    helical_weighted_backproject,
+)
 
 from .geometry import (
     circular_trajectory_3d,
@@ -49,10 +58,18 @@ try:
 except ImportError:
     pass
 
-__version__ = '2.1.0'
+__version__ = '2.2.1'
 
 __all__ = [
     'Projector',
+    'TensorStore',
+    'NpyStore',
+    'ParameterizedSurface',
+    'fbp',
+    'fdk',
+    'helical_fdk',
+    'helical_view_weights',
+    'helical_weighted_backproject',
     'ParallelProjectorFunction',
     'ParallelBackprojectorFunction',
     'FanProjectorFunction',

{diffct-2.1.0 → diffct-2.2.1}/diffct/analytical.py

@@ -40,6 +40,9 @@ from .kernels import (
     _parallel_2d_fbp_backproject_kernel,
     _fan_2d_fbp_backproject_kernel,
     _cone_3d_fdk_backproject_kernel,
+    _parallel_2d_fbp_transpose_kernel,
+    _fan_2d_fbp_transpose_kernel,
+    _cone_3d_fdk_transpose_kernel,
 )
 
 
@@ -367,8 +370,8 @@ def _as_contig_f32(t, device):
 
 
 @_on_device_of("sinogram")
-def parallel_weighted_backproject(sinogram, ray_dir, det_origin, det_u_vec,
-                                  detector_spacing, H, W, voxel_spacing=1.0):
+def _parallel_weighted_backproject_raw(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.
 
     Runs the dedicated parallel-beam FBP gather kernel (one thread per
@@ -451,8 +454,8 @@ def _analytical_geometry(src_pos, det_center, n, isocenter):
 
 
 @_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):
+def _fan_weighted_backproject_raw(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.
 
     Runs the dedicated fan-beam FBP gather kernel (one thread per output
@@ -507,8 +510,8 @@ def fan_weighted_backproject(sinogram, src_pos, det_center, det_u_vec,
 
 
 @_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):
+def _cone_weighted_backproject_raw(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.
 
     Runs the dedicated cone-beam FDK gather kernel (one thread per output
@@ -571,3 +574,145 @@ def cone_weighted_backproject(sinogram, src_pos, det_center, det_u_vec, det_v_ve
     # Convert back to (D, H, W) layout for the user.
     reco = reco_perm.permute(2, 1, 0).contiguous() * scale
     return reco
+
+
+def _validate_analytical_inputs(sinogram, geometry, ndim, isocenter=None):
+    if not isinstance(sinogram, torch.Tensor) or sinogram.ndim != ndim:
+        raise ValueError(f"sinogram must have rank {ndim}")
+    if min(sinogram.shape[1:]) < 2:
+        raise ValueError("Analytical backprojection requires at least two detector bins on each axis")
+    for component in geometry:
+        if not isinstance(component, torch.Tensor) or component.shape != (sinogram.shape[0], ndim):
+            raise ValueError(f"Every geometry tensor must have shape (n_views, {ndim})")
+        if component.requires_grad:
+            raise ValueError("Analytical backprojection does not support geometry gradients")
+    if isinstance(isocenter, torch.Tensor) and isocenter.requires_grad:
+        raise ValueError("Analytical backprojection does not support isocenter gradients")
+    if not sinogram.is_cuda:
+        raise ValueError("sinogram must be on a CUDA device")
+
+
+def _analytical_gather_raw(sinogram, beam, geometry, parameters, isocenter):
+    if beam == "parallel":
+        return _parallel_weighted_backproject_raw(sinogram, *geometry, *parameters)
+    if beam == "fan":
+        return _fan_weighted_backproject_raw(sinogram, *geometry, *parameters, isocenter=isocenter)
+    return _cone_weighted_backproject_raw(sinogram, *geometry, *parameters, isocenter=isocenter)
+
+
+@_on_device_of("image")
+def _analytical_transpose_raw(image, beam, geometry, parameters, isocenter, sinogram_shape):
+    device = image.device
+    geometry = tuple(_as_contig_f32(component, device) for component in geometry)
+    image = _as_contig_f32(image, device)
+    sinogram = torch.zeros(sinogram_shape, device=device, dtype=torch.float32)
+    d_sino = TorchCUDABridge.tensor_to_cuda_array(sinogram)
+    d_geometry = tuple(TorchCUDABridge.tensor_to_cuda_array(component) for component in geometry)
+    stream = _get_numba_external_stream_for(torch.cuda.current_stream())
+
+    scale = 1.0 / (2.0 * math.pi)
+    iso = ()
+    if beam != "parallel":
+        source, detector, u = geometry[:3]
+        normal = (torch.stack((-u[:, 1], u[:, 0]), dim=1) if beam == "fan"
+                  else torch.cross(u, geometry[3], dim=1))
+        isocenter, sid_mean, sdd_mean = _analytical_geometry(source, detector, normal, isocenter)
+        scale = sdd_mean / (2.0 * math.pi * sid_mean)
+        iso = tuple(_DTYPE(value.item() / parameters[-1]) for value in isocenter)
+    image = image * scale
+
+    if beam == "cone":
+        D, H, W, du, dv, spacing = parameters
+        image = image.permute(2, 1, 0).contiguous()
+        d_image = TorchCUDABridge.tensor_to_cuda_array(image)
+        grid, tpb = _grid_3d(D, H, W)
+        _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,
+        )
+    else:
+        pitch, H, W, spacing = parameters
+        d_image = TorchCUDABridge.tensor_to_cuda_array(image)
+        grid, tpb = _grid_2d(W, H)
+        kernel = (_parallel_2d_fbp_transpose_kernel if beam == "parallel"
+                  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,
+        )
+    return sinogram
+
+
+class _AnalyticalGather(torch.autograd.Function):
+    @staticmethod
+    def forward(ctx, sinogram, beam, geometry, parameters, isocenter):
+        # Backward uses the exact geometry observed by forward, even if the
+        # caller edits its fixed trajectory or isocenter afterwards.
+        geometry = tuple(component.detach().clone() for component in geometry)
+        if isocenter is not None:
+            isocenter = torch.as_tensor(isocenter, device=sinogram.device,
+                                        dtype=torch.float32).detach().clone()
+        ctx.save_for_backward(*geometry, isocenter)
+        ctx.beam, ctx.parameters = beam, parameters
+        ctx.input_shape, ctx.input_dtype, ctx.input_device = sinogram.shape, sinogram.dtype, sinogram.device
+        return _analytical_gather_raw(sinogram, beam, geometry, parameters, isocenter)
+
+    @staticmethod
+    def backward(ctx, grad_output):
+        *geometry, isocenter = ctx.saved_tensors
+        grad_input = _AnalyticalTranspose.apply(
+            grad_output, ctx.beam, tuple(geometry), ctx.parameters, isocenter, ctx.input_shape,
+        ).to(device=ctx.input_device, dtype=ctx.input_dtype)
+        return grad_input, None, None, None, None
+
+
+class _AnalyticalTranspose(torch.autograd.Function):
+    @staticmethod
+    def forward(ctx, image, beam, geometry, parameters, isocenter, sinogram_shape):
+        ctx.beam, ctx.geometry, ctx.parameters, ctx.isocenter = beam, geometry, parameters, isocenter
+        ctx.input_dtype, ctx.input_device = image.dtype, image.device
+        return _analytical_transpose_raw(image, beam, geometry, parameters, isocenter, sinogram_shape)
+
+    @staticmethod
+    def backward(ctx, grad_output):
+        grad_input = _AnalyticalGather.apply(
+            grad_output, ctx.beam, ctx.geometry, ctx.parameters, ctx.isocenter,
+        ).to(device=ctx.input_device, dtype=ctx.input_dtype)
+        return grad_input, None, None, None, None, None
+
+
+def _analytical_backproject(sinogram, beam, geometry, parameters, isocenter=None):
+    _validate_analytical_inputs(sinogram, geometry, 3 if beam == "cone" else 2, isocenter)
+    if torch.is_grad_enabled() and sinogram.requires_grad:
+        return _AnalyticalGather.apply(sinogram, beam, geometry, parameters, isocenter)
+    return _analytical_gather_raw(sinogram, beam, geometry, parameters, isocenter)
+
+
+def parallel_weighted_backproject(sinogram, ray_dir, det_origin, det_u_vec,
+                                  detector_spacing, H, W, voxel_spacing=1.0):
+    return _analytical_backproject(
+        sinogram, "parallel", (ray_dir, det_origin, det_u_vec),
+        (detector_spacing, H, W, voxel_spacing),
+    )
+
+
+def fan_weighted_backproject(sinogram, src_pos, det_center, det_u_vec,
+                             detector_spacing, H, W, voxel_spacing=1.0, *, isocenter=None):
+    return _analytical_backproject(
+        sinogram, "fan", (src_pos, det_center, det_u_vec),
+        (detector_spacing, H, W, voxel_spacing), isocenter,
+    )
+
+
+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):
+    return _analytical_backproject(
+        sinogram, "cone", (src_pos, det_center, det_u_vec, det_v_vec),
+        (D, H, W, du, dv, voxel_spacing), isocenter,
+    )
+
+
+parallel_weighted_backproject.__doc__ = _parallel_weighted_backproject_raw.__doc__
+fan_weighted_backproject.__doc__ = _fan_weighted_backproject_raw.__doc__
+cone_weighted_backproject.__doc__ = _cone_weighted_backproject_raw.__doc__