diffct

English · 简体中文

Differentiable CUDA projectors for CT: arbitrary trajectories, multi-GPU, multi-node, geometry gradients.

Intro video (MP4) · Technical report · DOI

Install · Quickstart · Features · Performance · Examples · Citation

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. For Apple Silicon, use the MLX port by Linda-Sophie Schneider.

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.
• 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.
• Matched operators. project() and backproject() form an exact adjoint pair for the cell-constant Siddon model. Both support PyTorch autograd, with volume/sinogram gradients and Hessian-vector products.
• Large volumes. CPU volumes and sinograms automatically stream spatial tiles and view batches through CUDA. Full arrays and data gradients stay on CPU; tile sizes follow the available device memory and can be overridden. See chunked execution.
• 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.

Install

You need an NVIDIA GPU. Install PyTorch for your CUDA version first. Then install diffct with the extra for the same CUDA major version:

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:

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

Quickstart

Create the acquisition once. Then call project() and backproject().

import torch
from diffct import Projector, spiral_trajectory_3d

trajectory = spiral_trajectory_3d(360, sid=320.0, sdd=512.0, z_range=40.0, n_turns=1.0, device="cpu")
A = Projector(trajectory, volume_shape=(128, 128, 128), detector_shape=(384, 256), detector_spacing=0.8)

volume = torch.rand(A.volume_shape, device="cuda")
sinogram = A.project(volume)        # (360, 384, 256) line integrals
adjoint = A.backproject(sinogram)   # matched adjoint A^T

x = torch.zeros_like(volume, requires_grad=True)
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.

Geometry gradients. Set requires_grad=True on trajectory tensors before you build Projector. See REFERENCE.

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 and DISTRIBUTED.md.

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:

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

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.

To measure one against several GPUs on your machine (default scan of the script, not the table setup):

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.

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.

python examples/walnut_reconstruction.py --algorithms --save-volume walnut256.npy
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

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.

Documentation

Run the test suite on a CUDA host with python -m pytest tests/ -q.

Citation

If you use this library in your research, please cite the software and the technical report:

@software{diffct2025,
  author    = {Yipeng Sun},
  title     = {diffct: Differentiable Computed Tomography Reconstruction with CUDA},
  year      = 2025,
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.14999333},
  url       = {https://doi.org/10.5281/zenodo.14999333}
}

@article{202605.1446,
  doi       = {10.20944/preprints202605.1446.v1},
  url       = {https://doi.org/10.20944/preprints202605.1446.v1},
  year      = 2026,
  month     = {May},
  publisher = {Preprints},
  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}
}

License and acknowledgements

Apache 2.0, see LICENSE. The project draws on PYRO-NN and geometry_gradients_CT. Issues and pull requests are welcome. The walnut data are CC BY 4.0 (Meaney 2022); see NOTICE.