diffct 2.0.1__tar.gz → 2.1.0__tar.gz

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

@@ -5,6 +5,54 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.1.0] - 2026-10-10
+
+### Added
+
+- `Projector(..., detector_surface=surface)` samples local parameterized surfaces
+  into per-pixel world positions for native parallel, fan and cone projection
+  and matched backprojection. Shared or per-view surfaces can contain trainable
+  PyTorch parameters. Flat detectors remain the default; analytical helpers
+  retain their flat-detector assumptions.
+- CUDA regression tests and CPU formal verification for detector
+  surfaces, including bounded production-kernel checks against cell intersections.
+- Automatic CPU-backed spatial tiles and view batches for native `Projector`
+  projection, matched backprojection, data autograd/Hessians and first-order
+  geometry gradients. CUDA inputs retain the full-volume path when its estimated
+  working set fits. Optional `volume_chunk_shape` and `view_chunk_size` override
+  automatic limits; full CPU arrays are not staged on CUDA. Several local
+  devices compute their view batches concurrently.
+- A CPU-backed CGLS example and chunk-boundary, CUDA memory and
+  formal partition/translation/adjoint checks.
+
+### Fixed
+
+- The exit-time cleanup hook returns early under the CUDA simulator
+  (``NUMBA_ENABLE_CUDASIM=1``). Before, each simulator process printed an
+  ``ImportError`` for ``_PendingDeallocs`` at exit. The simulator loads no
+  CUDA modules, so it needs no cleanup.
+
+## [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
@@ -13,6 +61,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.0.1
+Version: 2.1.0
 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/edf7c52227ec2cc14c988918faa7313f8ee0fe03/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/edf7c52227ec2cc14c988918faa7313f8ee0fe03/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
@@ -73,20 +75,25 @@ 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).
 - **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.
+- **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.
 
-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
@@ -129,22 +136,39 @@ 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])
 ```
 
+**Volumes larger than GPU memory.** Keep the arrays on CPU. The same calls use
+CUDA tiles automatically; CUDA inputs retain the full-volume path when its
+estimated working set fits. Explicit limits are optional:
+
+```python
+A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8)
+volume = torch.ones(A.volume_shape, device="cpu", requires_grad=True)
+sinogram = A.project(volume)                 # CPU output, CUDA computation
+sinogram.square().mean().backward()          # CPU volume.grad
+# Optional: volume_chunk_shape=(32, 64, 64), view_chunk_size=16
+```
+
+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.
+
 ## Performance
 
 <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>
 
@@ -154,7 +178,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 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).
+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):
 
@@ -164,10 +188,12 @@ python examples/benchmark_projector.py --devices 0 1
 
 ## Gallery
 
+TV denotes TV-regularized iterative reconstruction; Adam is the optimizer. Figure labels distinguish the method from its optimizer.
+
 **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?v=e0092c4" width="100%" alt="Measured walnut: FDK, SIRT, CGLS and TV reconstructions">
 </p>
 
 ```bash
@@ -177,7 +203,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?v=e0092c4" width="100%" alt="Simulated helical scan of the walnut: FDK, CGLS, SIRT and TV reconstructions">
 </p>
 
 ```bash
@@ -185,22 +211,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`, `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).
 
 ## 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/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`.
 
@@ -232,7 +258,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.1 → diffct-2.1.0}/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/edf7c52227ec2cc14c988918faa7313f8ee0fe03/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/edf7c52227ec2cc14c988918faa7313f8ee0fe03/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
@@ -42,20 +44,25 @@
 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).
 - **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.
+- **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.
 
-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
@@ -98,22 +105,39 @@ 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])
 ```
 
+**Volumes larger than GPU memory.** Keep the arrays on CPU. The same calls use
+CUDA tiles automatically; CUDA inputs retain the full-volume path when its
+estimated working set fits. Explicit limits are optional:
+
+```python
+A = Projector(trajectory, (128, 128, 128), (384, 256), detector_spacing=0.8)
+volume = torch.ones(A.volume_shape, device="cpu", requires_grad=True)
+sinogram = A.project(volume)                 # CPU output, CUDA computation
+sinogram.square().mean().backward()          # CPU volume.grad
+# Optional: volume_chunk_shape=(32, 64, 64), view_chunk_size=16
+```
+
+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.
+
 ## Performance
 
 <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>
 
@@ -123,7 +147,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 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).
+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):
 
@@ -133,10 +157,12 @@ python examples/benchmark_projector.py --devices 0 1
 
 ## Gallery
 
+TV denotes TV-regularized iterative reconstruction; Adam is the optimizer. Figure labels distinguish the method from its optimizer.
+
 **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?v=e0092c4" width="100%" alt="Measured walnut: FDK, SIRT, CGLS and TV reconstructions">
 </p>
 
 ```bash
@@ -146,7 +172,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?v=e0092c4" width="100%" alt="Simulated helical scan of the walnut: FDK, CGLS, SIRT and TV reconstructions">
 </p>
 
 ```bash
@@ -154,22 +180,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`, `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).
 
 ## 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/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`.
 
@@ -201,7 +227,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.1 → diffct-2.1.0}/diffct/__init__.py

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

diffct-2.1.0/diffct/chunking.py

@@ -0,0 +1,73 @@
+"""Spatial slices and immutable execution limits for streamed projectors."""
+
+from dataclasses import dataclass
+from itertools import product
+import math
+
+import torch
+
+
+@dataclass(frozen=True)
+class _ChunkPlan:
+    chunk_shape: tuple
+    view_chunk_size: int
+    devices: tuple
+
+
+def _memory_budget(device):
+    """Usable allocator bytes, retaining 25% headroom for allocation overhead.
+
+    Reusable reserved blocks count as available, but never bypass the process
+    fraction ceiling. Older PyTorch without its public fraction getter can
+    only observe driver/allocator memory; explicit limits remain available.
+    """
+    free, total = torch.cuda.mem_get_info(device)
+    allocated = torch.cuda.memory_allocated(device)
+    reusable = max(0, torch.cuda.memory_reserved(device) - allocated)
+    getter = getattr(torch.cuda, "get_per_process_memory_fraction", None)
+    fraction = getter(device) if getter is not None else 1.0
+    allocator_room = max(0, int(total * fraction) - allocated)
+    available = max(0, min(free + reusable, allocator_room))
+    budget = available * 3 // 4
+    allocation_limit = (1 << 63) - 1  # Unbounded limit in scalar int64 agreement.
+    backend = getattr(torch.cuda, "get_allocator_backend", lambda: "native")()
+    # Native requests >1 MiB and <10 MiB reserve a 20 MiB segment. A smaller
+    # current available room must use the <=1 MiB small pool, whose segments are 2 MiB.
+    # Source: pytorch/c10/cuda/CUDACachingAllocator.cpp (Native allocator notes).
+    if backend == "native" and available < 20 * 1024 ** 2:
+        allocation_limit = 1024 ** 2
+    return budget, allocation_limit
+
+
+def _working_set_bytes(beam, shape, views, detector_shape, surface):
+    """Conservative native staging/layout, cotangent, geometry and VJP scratch."""
+    rank = len(shape)
+    voxels = math.prod(shape)
+    rays = views * math.prod(detector_shape)
+    geometry = (rank * (views + rays) if surface
+                else rank * (4 if beam == "cone" else 3) * views)
+    # Cone permuted layout and its returned tensor can coexist with staging.
+    # Two ray buffers cover native output/cotangent and transfer scratch; two
+    # geometry buffers cover staged values and their first-order VJP/reduction.
+    tile_buffers = 3 if beam == "cone" else 2
+    return 4 * (tile_buffers * voxels + 2 * rays + 2 * geometry)
+
+
+def _largest_buffer_bytes(beam, shape, views, detector_shape, surface):
+    rank = len(shape)
+    rays = views * math.prod(detector_shape)
+    geometry = (rank * (views + rays) if surface
+                else rank * (4 if beam == "cone" else 3) * views)
+    return 4 * max(math.prod(shape), rays, geometry)
+
+
+def _tiles(shape, chunk_shape, spacing):
+    """Yield tensor slices, clipped shapes and physical centres in xyz order."""
+    starts = (range(0, size, chunk) for size, chunk in zip(shape, chunk_shape))
+    for start in product(*starts):
+        tile_shape = tuple(min(chunk, size - first)
+                           for size, chunk, first in zip(shape, chunk_shape, start))
+        slices = tuple(slice(first, first + size) for first, size in zip(start, tile_shape))
+        centre = tuple((first + size / 2 - full / 2) * spacing
+                       for first, size, full in zip(start, tile_shape, shape))
+        yield slices, tile_shape, centre[::-1]