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

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. 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.
• 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.
• Multi-GPU and multi-node. Use devices=[0, 1, 2, 3] in one process, or torchrun and NCCL across ranks. Default partition="views" shards projections and replicates volumes. partition="space" gives each rank an owned volume slab and combines ray contributions. Speedup depends on workload and communication costs.
• 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. 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 tensor arrays and iterative state still need enough host RAM. For disk-backed state and sharded checkpoints, run python examples/disk_reconstruction.py --output disk-run; for fixed rank-local volume slabs use --partition space under torchrun. Run python examples/benchmark_execution.py to compare schedules and copy payloads.

Performance

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.

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.

Run the same workload:

python examples/benchmark_scaling.py --output one.json
torchrun --standalone --nproc-per-node=4 examples/benchmark_scaling.py --expected-nodes 1 --output four.json

Gallery

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.