cuPhoton 0.1.3

cuPhoton 0.1.3 is a source-only release for CPython 3.12–3.14 on Linux. It adds one FITS reader across the imaging workflows, spatially varying image subtraction in xPois, GPU-resident results in xPois and xFit, a reusable xPois → xFit → xScan device pipeline, and optional MPI and Dragon executors with persistent workers. xRay gains iterative fitting and compact detector spectra, and xDR fixes GPU buffer lifetimes and Gzip tile decoding.

For a hands-on walkthrough of cuPhoton’s GPU imaging workflow, read our NVIDIA Technical Blog post, Faster Scientific Image Analysis with NVIDIA cuPhoton.

cuPhoton 0.1.3 brings together 193 commits across 71 merged pull requests, adding 122 files and 82,553 net lines since v0.1.2 (86,231 added; 3,678 removed).

Contents 🔗

• Highlights
• Performance
• Install
• Upgrading from 0.1.2
• What changed
  • FITS reading
  • xPois
  • xFit
  • xScan and the device pipeline
  • Distributed execution
  • xRay
  • xDR and xRep
  • Documentation and examples
  • Packaging, CI, and tooling
• Known limitations and errata
• Contributors
  • Pull requests

Highlights 🔗

• One FITS reader for every imaging workflow. cuphoton.core.fits_io serves xPois, xRep, xFit, and xScan with a shared --fits-reader auto|astropy|xdr policy, header-first inspection, and read receipts. xFit fits candidate stamps straight from FITS manifests, and xScan scores FITS candidates through predict_fits. #61, #62, #63, #64
• Spatially varying image subtraction. solve_spatial_als (--solver spatial-als) fits separable kernels whose profiles vary across the image, in NumPy or CuPy FP64, alongside an experimental Gaussian-polynomial model. #25, #26, #27, #28, #29
• Results that stay on the GPU. solve_constant_kernel_device and fit_dipoles_device return CuPy results, and cuphoton.xscan.device_pipeline chains constant-kernel xPois, Gaussian xFit, and triplet xScan inference in one DeviceWorkerContext that loads the model once. #31, #12, #13, #42
• Persistent distributed workers. Shared MPI and Dragon executors run xPois image pairs, xFit candidate chunks, xScan inference minibatches, and the complete pipeline (xscan run-pipeline), keeping CUDA contexts, inputs, and models across warmup and measured rounds. #10, #54, #56
• More xRay fitting options. Damped-cosine iterative fitting (--fit-method iterative), batched detector FFTs, status-aware diagnostics with optional P2 ridge, and a lossless tile-rows artifact layout. #9, #22, #23, #75
• xDR correctness fixes. Buffers remain owned until GPU work completes on success, error, and cancellation paths; unaligned Gzip tile payloads are repacked before DEFLATE decoding; independent reads proceed during GDS waits. #36, #81, #39

Measured timings for these changes are collected under Performance.

Performance 🔗

Each figure is a measured speedup for the configuration and timing boundary stated in its pull request. Most compare whole workflows against a named baseline, so amortized startup, I/O, and transfer costs contribute as much as computation. Expect different factors on other hardware, data, and batch sizes.

• Persistent pipeline versus separate stages. On one RTX PRO 6000 Blackwell with synthetic 1024×1024 pairs (nine candidates each), warm xscan benchmark-pipeline rounds had medians of 0.884–0.901 s, against 8.211–8.407 s for freshly started xPois, xFit, and xScan stage processes (9.3×). The stage figure includes process startup and intermediate files. #55
• xDR reads in xPois and xRep. Reading a registered image pair for constant-kernel xPois took 0.133 s with xDR instead of 2.20 s with Astropy (16.5×), and xRep on an HSC coadd went from 0.973 s to 0.211 s (4.6×). #62
• FITS candidate manifests in xFit. For 16 stamps from a retained image subtraction on one GPU, median ingress, crop, and validation fell from 0.764 s to 0.107 s (7.1×). #63
• FITS inputs in the device pipeline. On registered FITS inputs with 32 candidates, the one-GPU batch median fell from 15.65 s with Astropy to 10.76 s with xDR (1.45×); two-worker MPI and Dragon batches gained 1.26× and 1.30×. #64
• Dragon control plane. In a two-node, 64-worker control experiment, consumer-local command queues reduced later-round control medians from 47.2/45.3 ms to 33.6/28.1 ms under Python TCP (1.4–1.6×), and native HSTA TCP reached 2.4–3.1 ms (9–20× below Python TCP, depending on queue layout). At 256 GPUs the per-batch coordination remainder fell from 210–357 ms to 24–33 ms with consumer queues (6–15×) and 8.1–8.6 ms with HSTA (24–44×). On eight GB200 GPUs, whole-pipeline batch medians stayed at 7.5–7.7 s under every layout and transport. Dragon execution guide

Install 🔗

Install from the v0.1.3 checkout with uv:

git clone --branch v0.1.3 https://github.com/NVIDIA/cuPhoton.git
cd cuPhoton

Choose a profile for your workflow:

# CPU data inspection and NumPy/SciPy workflows
uv sync --locked
# GPU FITS I/O runtime dependencies only
uv sync --locked --extra io
# GPU workflows: I/O, photometry, PyTorch, Numba-CUDA
uv sync --locked --extra gpu
# GPU workflows with visualization
uv sync --locked --extra gpu --extra viz

uv sync installs an editable Python package. The io and gpu extras supply runtime dependencies; native xDR requires a separate build with a C++17 compiler, CUDA 13 and cuFile development headers, and reentrant CFITSIO. Prepare the prerequisites in the xDR source build instructions, then run bash src/cuphoton/xdr/src/build.sh. The shared FITS reader can use Astropy without that extension. GPU execution needs a CUDA 13-compatible NVIDIA driver; GPUDirect Storage also needs a compatible host and storage configuration.

Extras compose: use uv sync --locked --extra gpu --extra viz --extra mpi for distributed GPU workflows with visualization. Include every extra you want to retain when changing profiles.

Extra	Adds
io	CuPy, the CUDA 13 runtime with cuFile, KvikIO 26.6, and nvCOMP 5.2 for native FITS I/O (Linux)
photometry	Photutils background estimation, source detection, and aperture photometry
torch	PyTorch for CPU-capable workflows
gpu	io and photometry, plus PyTorch and Numba-CUDA on Linux
viz	Bokeh, Pillow, and Tornado
cutile	Experimental cuTile backend; needs an external CUDA 13.2 or newer compiler with tileiras, ptxas, and NVVM
mpi	mpi4py; the MPI implementation and launcher come from your environment
dragon	DragonHPC on Linux with CPython 3.12 or 3.13
dev	Development, testing, formatting, and type-checking tools

See the packaging guide for runtime requirements and native source builds, and optional runtimes for MPI, Dragon, and the cuTile PyTorch/compiler constraint. ARM64 caveats for PyTorch and Photutils are under Known limitations.

Upgrading from 0.1.2 🔗

• Python. ...