diffct 2.3.0__tar.gz → 2.4.0__tar.gz

{diffct-2.3.0 → diffct-2.4.0}/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.4.0] - 2026-10-20
+
+### Added
+
+- Per-call `trajectory` overrides on `Projector` operations, preserving the constructor default and each call's geometry graph without rebuilding the projector (#29).
+- Angle-tensor inputs for circular trajectory helpers and differentiable `transform_trajectory` rigid transforms (#29).
+- `beam="parallel3d"` and `circular_trajectory_3d_parallel`, using infinite parallel rays and the PyTorch backend on CPU and CUDA, with data and first-order geometry gradients (#29).
+- `Projector(native_volume_layout=True)` returns native full-CUDA cone backprojections of unbatched flat-detector inputs as `(D, H, W)` tensors with the kernels' `(W, H, D)`-contiguous strides instead of contiguous copies, and native cone projections accept such tensors without copying. An iterative solver that keeps its volumes in this layout saves two whole-volume copies per normal-operator application on one device. The default is unchanged (#27).
+
+### Changed
+
+- The native cone backprojection kernel steps through the z crossings of each xy cell in an inner loop and groups adjacent detector rows in a warp, so the atomic additions of a warp hit neighbouring voxels of one column. Each ray's segments and arithmetic are unchanged; backprojection takes 1.25–1.8x less time on large cone and helical problems, depending on the geometry (#35).
+- Projector execution planning takes no allocator snapshot when a full launch clearly fits: lower bounds of the memory limits come from `mem_get_info` and one statistics query, and the exact planner runs only when they do not suffice. Plans are unchanged. Host time per call for small problems drops by about 1 ms. Distributed operators keep the exact planner (#26).
+- Distributed calls and solvers check rank agreement with one fixed-size collective per request instead of Python object exchanges, skip the callback protocol when no callback is given, and accumulate solver norms on the device with one host read per norm. Results are unchanged (#34).
+- The introduction video explains 2.3.0 tiled execution and view, space and hybrid partitions with a computed walnut example; the README GIF is 12 MB instead of 22 MB (#25).
+
+### Fixed
+
+- Detector surfaces expand world points on each compute device after view sharding, preserving native composition precision. Memory planning uses local view counts and composition dtypes. Streamed execution accepts CPU or CUDA offsets from both surface interfaces (#30).
+- Surface snapshots preserve gradient connections on CPU. Streamed composition and geometry backward use bounded fragments. Distributed calls check callback layouts and propagate validation errors before numerical work (#30).
+- Native surface admission sizes validation batches from available memory and staging limits, replacing fixed one-view batches (#32).
+- Rigid trajectory transforms accept valid surface detector frames whose reference center coincides with the source or whose reference plane is edge-on (#29).
+- Call-time trajectory validation checks flat detectors by corners and coordinate bounds, with exact pixel checks for ambiguous views. Frames stage once per validation device. Native surface validation uses bounded batches on each compute device after view sharding (#29).
+
 ## [2.3.0] - 2026-10-14
 
 ### Added

{diffct-2.3.0 → diffct-2.4.0}/CITATION.cff

@@ -13,8 +13,8 @@ authors:
     given-names: Yipeng
     email: yipeng.sun@fau.de
     alias: sypsyp97
-version: 2.3.0
-date-released: "2026-10-14"
+version: 2.4.0
+date-released: "2026-10-20"
 license: Apache-2.0
 repository-code: "https://github.com/sypsyp97/diffct"
 url: "https://sypsyp97.github.io/diffct/"
@@ -43,9 +43,9 @@ preferred-citation:
     - family-names: Maier
       given-names: Andreas
   year: 2026
-  month: 5
+  month: 10
   journal: Preprints
   publisher:
     name: Preprints
-  doi: 10.20944/preprints202605.1446.v1
-  url: "https://doi.org/10.20944/preprints202605.1446.v1"
+  doi: 10.20944/preprints202605.1446.v2
+  url: "https://doi.org/10.20944/preprints202605.1446.v2"

{diffct-2.3.0 → diffct-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.3.0
+Version: 2.4.0
 Summary: Differentiable CT projection and reconstruction: precision modes, streaming, distributed execution and geometry gradients
 Project-URL: Homepage, https://github.com/sypsyp97/diffct
 Project-URL: Documentation, https://sypsyp97.github.io/diffct/
@@ -52,8 +52,8 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <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>
+  <a href="https://www.preprints.org/manuscript/202605.1446/v2">Technical report</a> ·
+  <a href="https://doi.org/10.20944/preprints202605.1446.v2">DOI</a>
 </p>
 
 <p align="center">
@@ -68,16 +68,18 @@ Description-Content-Type: text/markdown
 > **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).
 
+This README describes the source checkout, including [unreleased APIs](CHANGELOG.md#unreleased). Per-call trajectories, angle-tensor circular helpers, `transform_trajectory`, `parallel3d` and `native_volume_layout` require installation from source.
+
 ## Why diffct
 
 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.
+- **Arbitrary trajectories.** Each view has its own ray direction or 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.** `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.** 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. Views, space and hybrid partitions control replication of volumes and projections. Speedup depends on workload and communication costs.
-- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU and PyTorch CUDA/ROCm devices; see [execution contracts and validation limits](docs/EXECUTION.md).
+- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU and PyTorch CUDA/ROCm devices; see [execution contracts](docs/EXECUTION.md).
 - **Solver API.** `cgls`, `sirt` and `tv_reconstruction` report residual history, tolerances and callbacks, with scan/data fingerprints and complete checkpoint state. `cgls_into` keeps state in bounded mapped blocks.
 - **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).
 
@@ -99,7 +101,7 @@ From source, with the examples:
 ```bash
 git clone https://github.com/sypsyp97/diffct.git
 cd diffct && pip install -e ".[cu12]"
-python examples/quickstart.py               # smoke test: prints adjoint mismatch ~1e-8 for each beam
+python examples/quickstart.py               # prints adjoint mismatch and gradients for each beam
 ```
 
 <details>
@@ -138,7 +140,11 @@ 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](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](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
+**Geometry gradients.** Reuse one projector with `A.project(volume, trajectory=current)` or `A.backproject(sinogram, trajectory=current)`. Circular helpers accept learnable angle tensors, and `transform_trajectory` applies differentiable rigid transforms. Omitting the override keeps the constructor trajectory. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
+
+**3D parallel beams.** Use `circular_trajectory_3d_parallel(...)` and `beam="parallel3d"`. The PyTorch backend provides matched projection and backprojection on CPU and CUDA.
+
+**Native volume layout.** For unbatched, flat-detector cone operations, set `native_volume_layout=True` to avoid volume layout copies. This applies to the native full-CUDA path on one compute device. Shapes stay `(D, H, W)`; the returned strides follow the kernel layout. The default is `False`. See [chunked execution](docs/REFERENCE.md#chunked-execution) for limits.
 
 **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).
 
@@ -171,18 +177,18 @@ volume slabs use `--partition space` under torchrun. Run
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.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">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.4.0">
+    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png?v=2.4.0" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
   </picture>
 </p>
 
 | 512³ volume | 1 GPU | 4 GPUs, 1 node | 8 GPUs, 2 nodes |
 |---|---:|---:|---:|
-| 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×) |
+| Forward projection | 493.40 ms | 131.78 ms (3.7×) | 72.42 ms (6.8×) |
+| Adjoint (backprojection) | 1118.98 ms | 293.01 ms (3.8×) | 232.50 ms (4.8×) |
+| CGLS iteration | 1744.92 ms | 465.62 ms (3.7×) | 337.98 ms (5.2×) |
 
-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.
+diffct 2.4.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.
 
 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).
 
@@ -222,7 +228,7 @@ Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](
 
 ## Examples
 
-`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).
+`quickstart.py`, `curved_detector.py`, `chunked_reconstruction.py`, `disk_reconstruction.py`, `benchmark_execution.py`, `benchmark_trajectory_admission.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
 
@@ -253,12 +259,12 @@ If you use this library in your research, please cite the software and the techn
 }
 
 @article{202605.1446,
-  doi       = {10.20944/preprints202605.1446.v1},
-  url       = {https://doi.org/10.20944/preprints202605.1446.v1},
+  doi       = {10.20944/preprints202605.1446.v2},
+  url       = {https://doi.org/10.20944/preprints202605.1446.v2},
   year      = 2026,
-  month     = {May},
+  month     = {Oct},
   publisher = {Preprints},
-  author    = {Yipeng Sun and Linda-Sophie Schneider and Chengze ye and Andreas Maier},
+  author    = {Yipeng Sun and Linda-Sophie Schneider and Chengze Ye and Andreas Maier},
   title     = {diffct: Differentiable CT Operators from Circular Orbits to Arbitrary Trajectories},
   journal   = {Preprints}
 }

{diffct-2.3.0 → diffct-2.4.0}/README.md

@@ -21,8 +21,8 @@
 
 <p align="center">
   <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>
+  <a href="https://www.preprints.org/manuscript/202605.1446/v2">Technical report</a> ·
+  <a href="https://doi.org/10.20944/preprints202605.1446.v2">DOI</a>
 </p>
 
 <p align="center">
@@ -37,16 +37,18 @@
 > **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).
 
+This README describes the source checkout, including [unreleased APIs](CHANGELOG.md#unreleased). Per-call trajectories, angle-tensor circular helpers, `transform_trajectory`, `parallel3d` and `native_volume_layout` require installation from source.
+
 ## Why diffct
 
 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.
+- **Arbitrary trajectories.** Each view has its own ray direction or 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.** `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.** 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. Views, space and hybrid partitions control replication of volumes and projections. Speedup depends on workload and communication costs.
-- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU and PyTorch CUDA/ROCm devices; see [execution contracts and validation limits](docs/EXECUTION.md).
+- **Precision and training.** Explicit native/PyTorch backends, FP32/FP64 modes, per-axis voxel spacing, leading batch/channel dimensions and data `torch.func` transforms. The portable path supports CPU and PyTorch CUDA/ROCm devices; see [execution contracts](docs/EXECUTION.md).
 - **Solver API.** `cgls`, `sirt` and `tv_reconstruction` report residual history, tolerances and callbacks, with scan/data fingerprints and complete checkpoint state. `cgls_into` keeps state in bounded mapped blocks.
 - **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).
 
@@ -68,7 +70,7 @@ From source, with the examples:
 ```bash
 git clone https://github.com/sypsyp97/diffct.git
 cd diffct && pip install -e ".[cu12]"
-python examples/quickstart.py               # smoke test: prints adjoint mismatch ~1e-8 for each beam
+python examples/quickstart.py               # prints adjoint mismatch and gradients for each beam
 ```
 
 <details>
@@ -107,7 +109,11 @@ 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](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](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
+**Geometry gradients.** Reuse one projector with `A.project(volume, trajectory=current)` or `A.backproject(sinogram, trajectory=current)`. Circular helpers accept learnable angle tensors, and `transform_trajectory` applies differentiable rigid transforms. Omitting the override keeps the constructor trajectory. See [REFERENCE](https://github.com/sypsyp97/diffct/blob/main/docs/REFERENCE.md#geometry-gradients).
+
+**3D parallel beams.** Use `circular_trajectory_3d_parallel(...)` and `beam="parallel3d"`. The PyTorch backend provides matched projection and backprojection on CPU and CUDA.
+
+**Native volume layout.** For unbatched, flat-detector cone operations, set `native_volume_layout=True` to avoid volume layout copies. This applies to the native full-CUDA path on one compute device. Shapes stay `(D, H, W)`; the returned strides follow the kernel layout. The default is `False`. See [chunked execution](docs/REFERENCE.md#chunked-execution) for limits.
 
 **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).
 
@@ -140,18 +146,18 @@ volume slabs use `--partition space` under torchrun. Run
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.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">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_dark.png?v=2.4.0">
+    <img src="https://raw.githubusercontent.com/sypsyp97/diffct/main/docs/assets/scaling_light.png?v=2.4.0" width="100%" alt="Time per forward, adjoint and CGLS iteration on 1, 4 and 8 GPUs, 512^3 volume">
   </picture>
 </p>
 
 | 512³ volume | 1 GPU | 4 GPUs, 1 node | 8 GPUs, 2 nodes |
 |---|---:|---:|---:|
-| 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×) |
+| Forward projection | 493.40 ms | 131.78 ms (3.7×) | 72.42 ms (6.8×) |
+| Adjoint (backprojection) | 1118.98 ms | 293.01 ms (3.8×) | 232.50 ms (4.8×) |
+| CGLS iteration | 1744.92 ms | 465.62 ms (3.7×) | 337.98 ms (5.2×) |
 
-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.
+diffct 2.4.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.
 
 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).
 
@@ -191,7 +197,7 @@ Walnut data: Meaney 2022, Zenodo 6986012, CC BY 4.0; see [examples/data/NOTICE](
 
 ## Examples
 
-`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).
+`quickstart.py`, `curved_detector.py`, `chunked_reconstruction.py`, `disk_reconstruction.py`, `benchmark_execution.py`, `benchmark_trajectory_admission.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
 
@@ -222,12 +228,12 @@ If you use this library in your research, please cite the software and the techn
 }
 
 @article{202605.1446,
-  doi       = {10.20944/preprints202605.1446.v1},
-  url       = {https://doi.org/10.20944/preprints202605.1446.v1},
+  doi       = {10.20944/preprints202605.1446.v2},
+  url       = {https://doi.org/10.20944/preprints202605.1446.v2},
   year      = 2026,
-  month     = {May},
+  month     = {Oct},
   publisher = {Preprints},
-  author    = {Yipeng Sun and Linda-Sophie Schneider and Chengze ye and Andreas Maier},
+  author    = {Yipeng Sun and Linda-Sophie Schneider and Chengze Ye and Andreas Maier},
   title     = {diffct: Differentiable CT Operators from Circular Orbits to Arbitrary Trajectories},
   journal   = {Preprints}
 }

{diffct-2.3.0 → diffct-2.4.0}/diffct/__init__.py

@@ -30,6 +30,8 @@ from .reconstruction import (
 from .solvers import SolverResult, cgls, sirt, tv_reconstruction, cgls_into, total_variation
 
 from .geometry import (
+    transform_trajectory,
+    circular_trajectory_3d_parallel,
     circular_trajectory_3d,
     random_trajectory_3d,
     spiral_trajectory_3d,
@@ -62,7 +64,7 @@ try:
 except ImportError:
     pass
 
-__version__ = '2.3.0'
+__version__ = '2.4.0'
 
 __all__ = [
     'Projector',
@@ -88,6 +90,8 @@ __all__ = [
     'FanBackprojectorFunction',
     'ConeProjectorFunction',
     'ConeBackprojectorFunction',
+    'transform_trajectory',
+    'circular_trajectory_3d_parallel',
     'circular_trajectory_3d',
     'random_trajectory_3d',
     'spiral_trajectory_3d',

{diffct-2.3.0 → diffct-2.4.0}/diffct/_solver_state.py

@@ -11,6 +11,7 @@ import torch.distributed as dist
 
 from .pipeline import _fragments
 from .storage import NpyStore, TensorStore
+from .distribution import control_status, preflight
 
 
 def count(value, name, positive=False):
@@ -25,47 +26,56 @@ def finite(value, name, positive=False):
     return float(value)
 
 
-def agreement(operator, error=None, token=None):
+def agreement(operator, error=None, token=None, *, cache_key=None):
     """Every rank rejects a bad request before numerical execution starts."""
     world = getattr(operator, "world_size", 1)
     if world == 1:
         if error is not None:
             raise error
         return
-    records = [None] * world
-    dist.all_gather_object(records, (None if error is None else str(error), token),
-                           group=operator.process_group)
-    failures = [record[0] for record in records if record[0] is not None]
-    if failures or any(record[1] != records[0][1] for record in records):
-        raise ValueError("distributed solver agreement failed: " + (failures[0] if failures else "inconsistent checkpoint iteration or controls"))
+    error = None if error is None else ValueError("distributed solver agreement failed: " + str(error))
+    mismatch = "distributed solver agreement failed: inconsistent checkpoint iteration or controls"
+    partition = getattr(operator, "_partition", None)
+    if partition is not None:
+        partition.preflight(error, token, cache_key=cache_key, mismatch=mismatch)
+    else:
+        preflight(error, token, process_group=operator.process_group, world_size=world,
+                  mismatch=mismatch)
 
 
-def scalar_sum(operator, value, kind):
-    """Count physical rays/voxels once, including view/space replicas."""
-    world = getattr(operator, "world_size", 1)
+def owns_values(operator, kind):
+    """Select one copy of each physical ray or voxel for scalar reductions."""
     partition = getattr(operator, "partition", "views")
     rank = getattr(operator, "rank", 0)
-    owns = (getattr(operator, "view_rank", 0) == 0 if kind == "volume"
+    return (getattr(operator, "view_rank", 0) == 0 if kind == "volume"
             else getattr(operator, "space_rank", 0) == 0) if partition == "hybrid" else (
         rank == 0 if (kind == "volume") == (partition == "views") else True
     )
-    value = float(value) if owns else 0.
+
+
+def scalar_sum(operator, value, kind):
+    """Count physical rays/voxels once, including view/space replicas."""
+    world = getattr(operator, "world_size", 1)
+    value = value if owns_values(operator, kind) else 0.
     if world > 1:
         group = operator.process_group
         device = torch.device("cuda", torch.cuda.current_device()) if dist.get_backend(group) == "nccl" else torch.device("cpu")
-        accumulator = torch.tensor(value, dtype=torch.float64, device=device)
+        accumulator = torch.as_tensor(value, dtype=torch.float64, device=device).clone()
         dist.all_reduce(accumulator, group=group)
-        value = accumulator.item()
-    return value
+        return accumulator.item()
+    return float(value)
 
 
 def squared_norm(operator, value, kind, elements=1048576):
     store = TensorStore(value) if isinstance(value, torch.Tensor) else value
     total = 0.
-    for selected in _fragments(tuple(store.shape), elements):
-        # Clone even an FP64 view: norms must never alter caller measurements.
-        block = store.read(selected).to(dtype=torch.float64).clone()
-        total += block.square_().sum().item()
+    if owns_values(operator, kind):
+        total = torch.zeros((), dtype=torch.float64, device=getattr(store, "device", "cpu"))
+        for selected in _fragments(tuple(store.shape), elements):
+            # Clone even an FP64 view: norms must never alter caller measurements.
+            block = store.read(selected).to(dtype=torch.float64).clone()
+            # Preserve the block reductions and their sequential FP64 order.
+            total.add_(block.square_().sum().to(device=total.device))
     return scalar_sum(operator, total, kind)
 
 
@@ -270,15 +280,22 @@ def save_checkpoint(operator, directory, states, metadata, iteration, history, m
     agreement(operator, error, iteration)
 
 
+def callbacks_enabled(operator, callback):
+    """Check callback presence once, including callbacks on only some ranks."""
+    return bool(control_status((int(callback is not None),),
+                               process_group=getattr(operator, "process_group", None),
+                               world_size=getattr(operator, "world_size", 1))[0])
+
+
 def callback_stop(operator, callback, iteration, residual, volume):
     error, stop = None, False
     try:
         stop = callback is not None and callback(iteration, residual, volume) is False
     except Exception as caught:
         error = caught
-    agreement(operator, error)
-    if getattr(operator, "world_size", 1) > 1:
-        records = [None] * operator.world_size
-        dist.all_gather_object(records, stop, group=operator.process_group)
-        stop = any(records)
-    return stop
+    failed, stop = control_status((int(error is not None), int(stop)),
+                                  process_group=getattr(operator, "process_group", None),
+                                  world_size=getattr(operator, "world_size", 1))
+    if failed:
+        agreement(operator, error)
+    return bool(stop)