diffct 2.0.0__tar.gz → 2.0.2__tar.gz

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

@@ -5,6 +5,56 @@ 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.2] - 2026-10-09
+
+### Fixed
+
+- The exit-time cleanup from 2.0.1 set numba-cuda's pending-deallocation
+  ratio to infinity. numba-cuda converts ``capacity * ratio`` to ``int``, so
+  each deallocation queued during shutdown raised ``ValueError`` or
+  ``OverflowError``. The exit code stayed 0, but stderr showed the error. The
+  exit hook now disables numba-cuda's pending-deallocation queues instead of
+  changing the limits, so no queue is flushed at exit and no error is raised.
+  The hook no longer imports ``numba.cuda.core.config``, which older
+  numba-cuda releases do not have.
+
+### Documentation
+
+- The install instructions state that ``pip install diffct`` without a CUDA
+  extra needs a system CUDA Toolkit. Use ``diffct[cu12]`` or ``diffct[cu13]``.
+- README images and links use absolute URLs, so they also work on PyPI.
+
+## [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.
+- A process that ran diffct kernels on several GPUs no longer crashes at
+  interpreter exit: numba-cuda's flush of pending CUDA module unloads during
+  shutdown is skipped, and process exit releases the modules.
+- ``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 +78,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.2}/CITATION.cff

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.0.0
+Version: 2.0.2
 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/
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 
 <h1 align="center">diffct</h1>
 
-<p align="center">English · <a href="README.zh.md">简体中文</a></p>
+<p align="center">English · <a href="https://github.com/sypsyp97/diffct/blob/main/README.zh.md">简体中文</a></p>
 
 <p align="center">
   Differentiable CUDA projectors for CT: arbitrary trajectories, multi-GPU, multi-node, geometry gradients.
@@ -43,15 +43,15 @@ Description-Content-Type: text/markdown
   <a href="https://pypi.org/project/diffct/"><img src="https://img.shields.io/pypi/v/diffct.svg?style=flat-square&logo=pypi&logoColor=white" alt="PyPI version"></a>
   <a href="https://sypsyp97.github.io/diffct/"><img src="https://img.shields.io/github/actions/workflow/status/sypsyp97/diffct/docs.yml?branch=main&label=docs&style=flat-square" alt="Documentation"></a>
   <a href="https://github.com/sypsyp97/diffct/actions"><img src="https://img.shields.io/github/actions/workflow/status/sypsyp97/diffct/ci.yml?branch=main&label=CI&style=flat-square" alt="CI/CD"></a>
-  <a href="https://deepwiki.com/sypsyp97/diffct"><img src="docs/assets/deepwiki-badge.svg" alt="Ask DeepWiki"></a>
+  <a href="https://deepwiki.com/sypsyp97/diffct"><img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/deepwiki-badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
 <p align="center">
-  <img src="docs/assets/diffct_intro.gif" width="100%" alt="diffct intro: projection, sinogram, trajectories, multi-GPU split, reconstruction and geometry calibration">
+  <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/diffct_intro.gif" width="100%" alt="diffct intro: projection, sinogram, trajectories, multi-GPU split, reconstruction and geometry calibration">
 </p>
 
 <p align="center">
-  <a href="docs/assets/diffct_intro.mp4">Intro video (MP4)</a> ·
+  <a href="https://github.com/sypsyp97/diffct/blob/main/docs/assets/diffct_intro.mp4">Intro video (MP4)</a> ·
   <a href="https://www.preprints.org/manuscript/202605.1446/v1">Technical report</a> ·
   <a href="https://doi.org/10.20944/preprints202605.1446.v1">DOI</a>
 </p>
@@ -65,7 +65,9 @@ Description-Content-Type: text/markdown
   <a href="#citation">Citation</a>
 </p>
 
-> **Version 2.0** replaces the circular-orbit API of 1.x with per-view trajectories. Code written for 1.x needs changes; see the [migration notes](docs/MIGRATION.md).
+> **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).
 
 ## Why diffct
@@ -76,18 +78,20 @@ 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).
+Capabilities, limits and isocenter rules: [docs/REFERENCE.md](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#capabilities-and-limits).
 
 ## Install
 
-You need a CUDA GPU and PyTorch. Install PyTorch for your CUDA version first.
+You need an NVIDIA GPU. Install PyTorch for your CUDA version first. Then install diffct with the extra for the same CUDA major version:
 
 ```bash
-pip install "diffct[cu12]"    # [cu13] for CUDA 13; install PyTorch for your CUDA first
+pip install "diffct[cu12]"    # PyTorch built for CUDA 12
+pip install "diffct[cu13]"    # PyTorch built for CUDA 13
 ```
 
+The extra installs the CUDA compiler libraries that Numba CUDA needs to compile the kernels. A plain `pip install diffct` does not install them. Use it only if a CUDA Toolkit is already installed on the system.
+
 From source, with the examples:
 
 ```bash
@@ -130,11 +134,11 @@ loss = 0.5 * (A.project(x) - sinogram).square().sum()
 loss.backward()                     # x.grad = A^T (A x - y)
 ```
 
-**Custom or calibrated trajectories.** Pass calibrated tensors directly instead of a generator; no circular fit is needed. See [REFERENCE](docs/REFERENCE.md#custom-or-calibrated-trajectories).
+**Custom or calibrated trajectories.** Pass calibrated tensors directly instead of a generator; no circular fit is needed. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#custom-or-calibrated-trajectories).
 
-**Geometry gradients.** Set `requires_grad=True` on trajectory tensors before you build `Projector`. See [REFERENCE](docs/REFERENCE.md#geometry-gradients).
+**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](docs/REFERENCE.md#several-gpus-and-nodes) and [DISTRIBUTED.md](docs/DISTRIBUTED.md).
+**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).
 
 ```python
 A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, devices=[0, 1, 2, 3])
@@ -144,8 +148,8 @@ A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, dev
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/scaling_dark.png">
-    <img src="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">
+    <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">
   </picture>
 </p>
 
@@ -155,7 +159,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](https://github.com/sypsyp97/diffct/blob/main/docs/assets/scaling.json).
 
 To measure one against several GPUs on your machine (default scan of the script, not the table setup):
 
@@ -168,7 +172,7 @@ python examples/benchmark_projector.py --devices 0 1
 **Measured walnut.** 240 measured views, circular cone beam, 256³: FDK (Hann window), SIRT (200 iterations), CGLS (20), TV (300, weight 0.3); axial and coronal centre slices.
 
 <p align="center">
-  <img src="docs/assets/walnut_measured.png" width="100%" alt="Measured walnut: FDK, SIRT, CGLS and TV reconstructions">
+  <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/walnut_measured.png" width="100%" alt="Measured walnut: FDK, SIRT, CGLS and TV reconstructions">
 </p>
 
 ```bash
@@ -178,7 +182,7 @@ python examples/walnut_reconstruction.py --figure out.png
 **Simulated helical scan of the walnut.** The FDK walnut volume as ground truth, 720 views, 1% noise, 256³. PSNR: FDK 26.67 dB, CGLS (30 iterations) 34.13 dB, SIRT (200) 34.52 dB, TV (200, weight 1.0) 37.77 dB.
 
 <p align="center">
-  <img src="docs/assets/walnut_helical.png" width="100%" alt="Simulated helical scan of the walnut: FDK, CGLS, SIRT and TV reconstructions">
+  <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/walnut_helical.png" width="100%" alt="Simulated helical scan of the walnut: FDK, CGLS, SIRT and TV reconstructions">
 </p>
 
 ```bash
@@ -186,23 +190,22 @@ python examples/walnut_reconstruction.py --algorithms --save-volume walnut256.np
 python examples/iterative_reconstruction.py --size 256 --views 720 --trajectory helical --noise 0.01 --phantom walnut256.npy --figure out.png
 ```
 
-Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](examples/data/NOTICE).
+Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](https://github.com/sypsyp97/diffct/blob/main/examples/data/NOTICE).
 
 ## Examples
 
-`quickstart.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, distributed-loss rules and measured results are in [examples/README.md](examples/README.md).
+`quickstart.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).
 
 ## Documentation
 
 | Document | Contents |
 |---|---|
-| [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 |
+| [Trajectory guide](https://github.com/sypsyp97/diffct/blob/main/docs/source/trajectories.rst) | Trajectory tuples and `Projector` usage |
+| [docs/REFERENCE.md](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md) | Capabilities and limits, custom trajectories, geometry gradients, multi-GPU details, geometry and units |
+| [docs/DISTRIBUTED.md](https://github.com/sypsyp97/diffct/blob/main/docs/DISTRIBUTED.md) | Execution/memory choices, distributed loss rules, Slurm and cross-node checks |
+| [docs/MIGRATION.md](https://github.com/sypsyp97/diffct/blob/main/docs/MIGRATION.md) | Moving from the circular-only API |
+| [docs/video/README.md](https://github.com/sypsyp97/diffct/blob/main/docs/video/README.md) | How the intro video is rendered |
+| [CHANGELOG.md](https://github.com/sypsyp97/diffct/blob/main/CHANGELOG.md) | Release history |
 
 Run the test suite on a CUDA host with `python -m pytest tests/ -q`.
 
@@ -234,7 +237,7 @@ If you use this library in your research, please cite the software and the techn
 
 ## License and acknowledgements
 
-Apache 2.0, see [LICENSE](LICENSE). The project draws on
+Apache 2.0, see [LICENSE](https://github.com/sypsyp97/diffct/blob/main/LICENSE). The project draws on
 [PYRO-NN](https://github.com/csyben/PYRO-NN) and
 [geometry_gradients_CT](https://github.com/mareikethies/geometry_gradients_CT).
-Issues and pull requests are welcome. The walnut data are CC BY 4.0 (Meaney 2022); see [NOTICE](NOTICE).
+Issues and pull requests are welcome. The walnut data are CC BY 4.0 (Meaney 2022); see [NOTICE](https://github.com/sypsyp97/diffct/blob/main/NOTICE).

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

@@ -1,6 +1,6 @@
 <h1 align="center">diffct</h1>
 
-<p align="center">English · <a href="README.zh.md">简体中文</a></p>
+<p align="center">English · <a href="https://github.com/sypsyp97/diffct/blob/main/README.zh.md">简体中文</a></p>
 
 <p align="center">
   Differentiable CUDA projectors for CT: arbitrary trajectories, multi-GPU, multi-node, geometry gradients.
@@ -12,15 +12,15 @@
   <a href="https://pypi.org/project/diffct/"><img src="https://img.shields.io/pypi/v/diffct.svg?style=flat-square&logo=pypi&logoColor=white" alt="PyPI version"></a>
   <a href="https://sypsyp97.github.io/diffct/"><img src="https://img.shields.io/github/actions/workflow/status/sypsyp97/diffct/docs.yml?branch=main&label=docs&style=flat-square" alt="Documentation"></a>
   <a href="https://github.com/sypsyp97/diffct/actions"><img src="https://img.shields.io/github/actions/workflow/status/sypsyp97/diffct/ci.yml?branch=main&label=CI&style=flat-square" alt="CI/CD"></a>
-  <a href="https://deepwiki.com/sypsyp97/diffct"><img src="docs/assets/deepwiki-badge.svg" alt="Ask DeepWiki"></a>
+  <a href="https://deepwiki.com/sypsyp97/diffct"><img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/deepwiki-badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
 <p align="center">
-  <img src="docs/assets/diffct_intro.gif" width="100%" alt="diffct intro: projection, sinogram, trajectories, multi-GPU split, reconstruction and geometry calibration">
+  <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/diffct_intro.gif" width="100%" alt="diffct intro: projection, sinogram, trajectories, multi-GPU split, reconstruction and geometry calibration">
 </p>
 
 <p align="center">
-  <a href="docs/assets/diffct_intro.mp4">Intro video (MP4)</a> ·
+  <a href="https://github.com/sypsyp97/diffct/blob/main/docs/assets/diffct_intro.mp4">Intro video (MP4)</a> ·
   <a href="https://www.preprints.org/manuscript/202605.1446/v1">Technical report</a> ·
   <a href="https://doi.org/10.20944/preprints202605.1446.v1">DOI</a>
 </p>
@@ -34,7 +34,9 @@
   <a href="#citation">Citation</a>
 </p>
 
-> **Version 2.0** replaces the circular-orbit API of 1.x with per-view trajectories. Code written for 1.x needs changes; see the [migration notes](docs/MIGRATION.md).
+> **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).
 
 ## Why diffct
@@ -45,18 +47,20 @@ 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).
+Capabilities, limits and isocenter rules: [docs/REFERENCE.md](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#capabilities-and-limits).
 
 ## Install
 
-You need a CUDA GPU and PyTorch. Install PyTorch for your CUDA version first.
+You need an NVIDIA GPU. Install PyTorch for your CUDA version first. Then install diffct with the extra for the same CUDA major version:
 
 ```bash
-pip install "diffct[cu12]"    # [cu13] for CUDA 13; install PyTorch for your CUDA first
+pip install "diffct[cu12]"    # PyTorch built for CUDA 12
+pip install "diffct[cu13]"    # PyTorch built for CUDA 13
 ```
 
+The extra installs the CUDA compiler libraries that Numba CUDA needs to compile the kernels. A plain `pip install diffct` does not install them. Use it only if a CUDA Toolkit is already installed on the system.
+
 From source, with the examples:
 
 ```bash
@@ -99,11 +103,11 @@ loss = 0.5 * (A.project(x) - sinogram).square().sum()
 loss.backward()                     # x.grad = A^T (A x - y)
 ```
 
-**Custom or calibrated trajectories.** Pass calibrated tensors directly instead of a generator; no circular fit is needed. See [REFERENCE](docs/REFERENCE.md#custom-or-calibrated-trajectories).
+**Custom or calibrated trajectories.** Pass calibrated tensors directly instead of a generator; no circular fit is needed. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#custom-or-calibrated-trajectories).
 
-**Geometry gradients.** Set `requires_grad=True` on trajectory tensors before you build `Projector`. See [REFERENCE](docs/REFERENCE.md#geometry-gradients).
+**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](docs/REFERENCE.md#several-gpus-and-nodes) and [DISTRIBUTED.md](docs/DISTRIBUTED.md).
+**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).
 
 ```python
 A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, devices=[0, 1, 2, 3])
@@ -113,8 +117,8 @@ A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8, dev
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/scaling_dark.png">
-    <img src="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">
+    <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">
   </picture>
 </p>
 
@@ -124,7 +128,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](https://github.com/sypsyp97/diffct/blob/main/docs/assets/scaling.json).
 
 To measure one against several GPUs on your machine (default scan of the script, not the table setup):
 
@@ -137,7 +141,7 @@ python examples/benchmark_projector.py --devices 0 1
 **Measured walnut.** 240 measured views, circular cone beam, 256³: FDK (Hann window), SIRT (200 iterations), CGLS (20), TV (300, weight 0.3); axial and coronal centre slices.
 
 <p align="center">
-  <img src="docs/assets/walnut_measured.png" width="100%" alt="Measured walnut: FDK, SIRT, CGLS and TV reconstructions">
+  <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/walnut_measured.png" width="100%" alt="Measured walnut: FDK, SIRT, CGLS and TV reconstructions">
 </p>
 
 ```bash
@@ -147,7 +151,7 @@ python examples/walnut_reconstruction.py --figure out.png
 **Simulated helical scan of the walnut.** The FDK walnut volume as ground truth, 720 views, 1% noise, 256³. PSNR: FDK 26.67 dB, CGLS (30 iterations) 34.13 dB, SIRT (200) 34.52 dB, TV (200, weight 1.0) 37.77 dB.
 
 <p align="center">
-  <img src="docs/assets/walnut_helical.png" width="100%" alt="Simulated helical scan of the walnut: FDK, CGLS, SIRT and TV reconstructions">
+  <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/walnut_helical.png" width="100%" alt="Simulated helical scan of the walnut: FDK, CGLS, SIRT and TV reconstructions">
 </p>
 
 ```bash
@@ -155,23 +159,22 @@ python examples/walnut_reconstruction.py --algorithms --save-volume walnut256.np
 python examples/iterative_reconstruction.py --size 256 --views 720 --trajectory helical --noise 0.01 --phantom walnut256.npy --figure out.png
 ```
 
-Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](examples/data/NOTICE).
+Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](https://github.com/sypsyp97/diffct/blob/main/examples/data/NOTICE).
 
 ## Examples
 
-`quickstart.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, distributed-loss rules and measured results are in [examples/README.md](examples/README.md).
+`quickstart.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).
 
 ## Documentation
 
 | Document | Contents |
 |---|---|
-| [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 |
+| [Trajectory guide](https://github.com/sypsyp97/diffct/blob/main/docs/source/trajectories.rst) | Trajectory tuples and `Projector` usage |
+| [docs/REFERENCE.md](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md) | Capabilities and limits, custom trajectories, geometry gradients, multi-GPU details, geometry and units |
+| [docs/DISTRIBUTED.md](https://github.com/sypsyp97/diffct/blob/main/docs/DISTRIBUTED.md) | Execution/memory choices, distributed loss rules, Slurm and cross-node checks |
+| [docs/MIGRATION.md](https://github.com/sypsyp97/diffct/blob/main/docs/MIGRATION.md) | Moving from the circular-only API |
+| [docs/video/README.md](https://github.com/sypsyp97/diffct/blob/main/docs/video/README.md) | How the intro video is rendered |
+| [CHANGELOG.md](https://github.com/sypsyp97/diffct/blob/main/CHANGELOG.md) | Release history |
 
 Run the test suite on a CUDA host with `python -m pytest tests/ -q`.
 
@@ -203,7 +206,7 @@ If you use this library in your research, please cite the software and the techn
 
 ## License and acknowledgements
 
-Apache 2.0, see [LICENSE](LICENSE). The project draws on
+Apache 2.0, see [LICENSE](https://github.com/sypsyp97/diffct/blob/main/LICENSE). The project draws on
 [PYRO-NN](https://github.com/csyben/PYRO-NN) and
 [geometry_gradients_CT](https://github.com/mareikethies/geometry_gradients_CT).
-Issues and pull requests are welcome. The walnut data are CC BY 4.0 (Meaney 2022); see [NOTICE](NOTICE).
+Issues and pull requests are welcome. The walnut data are CC BY 4.0 (Meaney 2022); see [NOTICE](https://github.com/sypsyp97/diffct/blob/main/NOTICE).

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

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

{diffct-2.0.0 → diffct-2.0.2}/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.2}/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.2}/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.