cuPhoton

cuPhoton is a collection of GPU-accelerated reference workflows for astronomical imaging, signal correlation and X-ray trace analysis. Research teams can run, inspect, and adapt these implementations to their own instruments and data products. The curated Python exports and structured run artifacts provide integration points for those workflows.

Choose a workflow

If you have...	Use...	You get...
FITS files whose pixels you need on a GPU	xDataReader	Decoded and scaled device arrays
Images with different pixel-to-sky mappings	xRep	Images resampled onto a common sky grid
Registered frames with known blur and variance	xImage	A reconstructed common scene and separate PSF calibration
An aligned reference image and a new observation	xPois	A matched reference and a difference image
Small cutouts containing positive/negative residuals	xFit	Fitted positions, amplitudes, shapes, uncertainties, and fit status
Candidate cutouts to score, or reviewed examples to train on	xScan	Real/bogus scores, evaluation metrics, and review material
X-ray detector images sampled over experimental delay	xRay	Signal traces and maps of fitted oscillations
Uniformly sampled signals or VDIF radio recordings	xBeam	Cross-spectra, lag correlations or radio visibilities
Scientific measurements and findings to monitor	cuPhoton xLens	Revision-aware evidence, dashboards and optional model reports

Each component can be used independently. An optical workflow can combine loading, reprojection, subtraction, and candidate analysis. xRay analyzes detector traces, while xBeam correlates sampled signals. See how the components fit together for the data flow and the adapters needed between stages.

Start here

These instructions follow the development branch. For a published version, select a tag from Releases and follow its installation notes. See the changelog for release history and migration details.

uv manages the supported development environments and lock file. On a Linux system with a CUDA 13-capable driver:

git clone https://github.com/NVIDIA/cuPhoton.git
cd cuPhoton
uv sync --locked --extra dev --extra gpu --extra viz
uv run python examples/run_quickstarts.py

The quickstart creates synthetic inputs for xRep, xPois, xFit, xScan, and xRay, then writes results to quickstart-output/. xDataReader has a separate native GPU setup. The JSON summary records the requested profile, the backend and device selected for each component, and the artifact paths. The default auto profile prefers a GPU and reports when it falls back to CPU.

For a deterministic CPU run:

uv sync --locked --extra dev --extra torch --extra viz --extra photometry
uv run python examples/run_quickstarts.py --profile cpu \
  --output-dir quickstart-cpu-output

Each run needs a new output directory. To require GPU execution, restore the GPU profile above and run with --require-gpu and a new --output-dir. See Quickstarts for individual components and output contracts.

For a synthetic imaging walkthrough from FITS loading through alignment, subtraction, dipole fitting, and plotting, run the notebook or equivalent script. Both include setup instructions and require a CUDA 13-capable NVIDIA GPU and xDR's native extension.

Components

xDataReader: load pixels into GPU memory

xDataReader (cuphoton.xdr) reads selected images from local FITS files, decodes supported compression, and applies byte-order and scaling rules to produce CuPy arrays. Use it to feed a GPU workflow while retaining the headers and scientific metadata in your application. Select the io extra for GPU runtime dependencies and build the native FITS extension from the checkout. Whether reads use native GPUDirect Storage depends on the storage and driver configuration.

xRep: put images on the same sky grid

xRep, short for xReproject (cuphoton.xrep), resamples images so corresponding pixels refer to the same sky positions. It uses the supplied World Coordinate System (WCS) mapping and a chosen output grid. This handles differences in pixel scale, rotation, and position; matching the images' blur is a separate operation. Outputs include the reprojected arrays, optional masks, and grid metadata.

xImage

xImage (cuphoton.ximage) estimates a common nonnegative scene from registered frames, known per-frame PSFs, good-pixel masks, and Gaussian noise variances. Each frame uses a spatially fixed PSF. It provides L2 and Huber reconstruction, experimental robust-loss extensions, and separate PSF calibration with Adam or multiplicative updates. See the xImage guide for input conventions, synthetic examples, and a worked Rubin adapter.

xPois: subtract a matched reference to reveal changes

xPois (cuphoton.xpois) starts with aligned reference and target images. It fits a convolution kernel and background correction to match their blur, brightness scale, and background, then subtracts the matched reference. Unchanged sources should largely cancel, leaving a difference image for candidate detection. Use the saved matching model and diagnostics to assess alignment, pixel quality, and the fit alongside candidate residuals.

xFit: turn a candidate's shape into measurements

A dipole is a positive lobe beside a negative lobe in a difference image; a small positional mismatch or a moving source can produce one. xFit (cuphoton.xfit) fits models to batches of small image cutouts, called stamps. It returns positions, amplitudes, and shape parameters with residuals, uncertainties, and fit status. These measurements describe the candidate and can optionally become inputs to an xScan classifier. Supply stamps as arrays or an NPZ archive, or use a FITS candidate manifest to select image regions, variance planes, and masks directly from local files.

xScan: score candidates and collect review labels

xScan (cuphoton.xscan) trains and evaluates real/bogus classifiers and runs inference on candidate stamps. Models use search and template images, optionally a difference image, and explicitly selected xFit features. Real/bogus scores help prioritize plausible detections over artifacts for further scientific classification. xScan also produces review material for inspecting predictions and collecting labels. Training requires reviewed labels and suitable train/validation/test splits. The Python predict_fits API scores caller-selected candidates from FITS images on a CUDA device. The infer-real-bogus command uses packaged datasets.

xRay: measure oscillations in detector signals

xRay (cuphoton.xray) analyzes X-ray detector measurements sampled over experimental delay. In a pump/probe experiment, one pulse excites a sample and another measures its response after a controlled delay. xRay extracts and normalizes signal traces from selected detector regions, then uses linear prediction to estimate their oscillatory modes. Outputs include frequencies, amplitudes, fit diagnostics, and detector review maps. Interpreting those measurements requires the experiment's geometry and calibration.

xBeam: correlate sampled signals and radio recordings

xBeam (cuphoton.xbeam) computes cross-spectra and lag correlations from uniformly sampled arrays or HDF5 signals. It also produces radio-interferometry visibilities from VDIF recordings, station clocks and delay models. Work runs in bounded windows using NumPy or CuPy, with explicit validity and coverage metadata. Start with the synthetic signal example or read the time-series API.

All Python code is in the cuphoton.* namespace. The shared Core (cuphoton.core) provides command discovery, application context, logging, and invariant checks. Each science component owns its algorithms and data contracts. The glossary explains the scientific and file-format terms used here.

The imaging workflows share a FITS reader policy: Astropy supplies the CPU path and xDR supplies eligible GPU reads. Reader selection is separate from the numerical backend. Read receipts record the requested and actual reader, selected HDUs, and any fallback reason; see FITS reading in a workflow. The xDR runtime controls select postprocessing, Gzip decoding and decompression backends through the CLI, Python APIs or input manifests.

Installation profiles

The base install contains the shared CPU data and scientific stack. Optional extras add the runtime and development dependencies for each workflow.

CPython 3.12 through 3.14 is supported on Linux, including the experimental cuTile backend. Dragon currently requires Python 3.12 or 3.13 because its upstream release has no Python 3.14 wheel.

Extra	Use
dev	Tests, formatting, linting, and build tools
photometry	Photutils source detection, backgrounds, and aperture measurements
io	CUDA 13 CuPy, KvikIO, cuFile, and nvCOMP for xDR and xBeam
torch	PyTorch workflows that can be forced to CPU execution
gpu	The io and photometry extras plus CUDA 13 PyTorch and Numba-CUDA
cutile	Experimental cuda.tile backend and CuPy
numba-cuda-mlir	Gaussian xFit kernels compiled with Numba-CUDA-MLIR and CuPy
mpi	mpi4py bindings for an existing MPI runtime
dragon	DragonHPC runtime on Python 3.12 or 3.13
viz	Bokeh reviews and Pillow image outputs

Select extras with uv sync from the checkout. The io and gpu profiles install GPU runtime dependencies; xDR's native FITS extension requires a separate source build. GPU execution needs a CUDA 13-compatible NVIDIA driver. On ARM64, Photutils currently builds from source; photometry and gpu therefore need a C compiler and Python development headers.

Typical editable installs are:

# CPU development
python -m pip install -e '.[dev,torch,viz,photometry]'

# CUDA 13 development
python -m pip install -e '.[dev,gpu,viz]'

For the cuTile profile, use a CUDA 13.2 or newer TileIR compiler (tileiras). See compiler and distributed runtime setup.

uv sync --locked --extra dev --extra gpu --extra cutile

Only CUDA 13 dependency variants are supported by this release.

See the xDR installation guide for native build prerequisites and Packaging for local package builds.

Python and command-line interfaces

Import through the namespaced modules:

from cuphoton.xdr import batch_to_device
from cuphoton.xfit import GaussianDipoleModel, fit_dipoles
from cuphoton.xpois import solve_separable_kernel
from cuphoton.xrep import ReprojectionSpec, reproject_array
from cuphoton.xbeam import ArraySource, CorrelationSpec, correlate_series

cuPhoton provides one Python console entry point:

cuphoton

Run cuphoton --help for the component list, cuphoton <group> --help for a group's commands, and cuphoton <group> help <command> for detailed options. The same interface is available through python -m cuphoton.

Installations also include cuphoton-openmpi-rank-exec, a low-level launch helper that binds one Open MPI rank to one visible GPU before Python starts. Invoke it through mpirun.

Data boundary

cuPhoton works with caller-supplied local files. Depending on the component, these may include FITS, HDF5, NumPy, CSV, or Parquet products. Applications handle observatory access, data permissions, and survey-specific preparation, then pass local products into cuPhoton. Store credentials, datasets, trained weights, and generated runs in application-managed locations.

See Data and artifact contracts before adapting a workflow to new products.

Development

uv lock --check
make lint
make test-cpu
make build

See Contributing for the full development workflow and Support for the project's best-effort support model.

Documentation

• Documentation index
• Getting started
• Quickstarts
• Architecture
• Adapting the workflows
• Command-line index
• Troubleshooting

License and citation

cuPhoton is licensed under the Apache License 2.0. See LICENSE and Third-party notices. Cite the software as described in CITATION.md.