Appendix A — Reference

This guide covers common tasks. The cuPhoton repository holds the full reference: each module’s options, data contracts and limits, the command-line index and troubleshooting. This page lists where each part lives. The links point to the repository’s main branch, which can be newer than this guide.

A.1 Modules

The table lists each module’s Python package, command group and reference page:

Table A.1: Modules and where their documentation lives.

Module	Python package	CLI group	Repository reference	Guide page
Core	`cuphoton.core`	none, Core supplies the `cuphoton` root	Core	Chapter 3, Chapter 14
xDataReader (xDR)	`cuphoton.xdr`	`xdr`	xDataReader	Chapter 4
xRep	`cuphoton.xrep`	`xrep`	xRep	Chapter 5
xImage	`cuphoton.ximage`	`ximage`	xImage	Chapter 11
xPois	`cuphoton.xpois`	`xpois`	xPois	Chapter 6
xFit	`cuphoton.xfit`	`xfit`	xFit	Chapter 7
xScan	`cuphoton.xscan`	`xscan`	xScan	Chapter 8
xRay	`cuphoton.xray`	`xray`	xRay	Chapter 12
xBeam	`cuphoton.xbeam`	`xbeam`	xBeam	Chapter 13
xLens	`cuphoton.xlens`	`xlens`	xLens	Chapter 15

Three topics span several modules:

Table A.2: Topics across modules.

Topic	Where	Repository reference	Guide page
Transient chain, from FITS files to a candidate catalog	`examples/transient-chain/`	README	Chapter 9
Error bars of transient catalogs	the transient chain	Uncertainty quantification	Chapter 10
Dragon and MPI execution	`--executor`, `cuphoton.core.executors`	Distributed launch guide	Chapter 14

A.2 Command line

cuphoton --help lists the command groups, one per module:

cuphoton

GPU-accelerated astronomy and imaging tools.

Available groups:
  xdr  xDataReader: GPU-native FITS loading.
  xfit  xFit: Batched nonlinear least-squares fitting for astronomical models.
  ximage  Multi-frame image reconstruction and PSF calibration.
  xpois  Optimal image subtraction for astronomical images.
  xscan  Transient-candidate dataset, training, and review workflows.
  xrep  xRep (xReproject): WCS-aware astronomical image reprojection and stacking.
  xray  GPU-accelerated X-ray detector analysis tools.
  xlens  cuPhoton xLens: scientific monitoring and evidence review.
  xbeam  xBeam: Time-series correlation and VLBI visibility generation.

Use 'cuphoton GROUP --help' for group help.

cuphoton <group> --help lists a group’s commands, and cuphoton <group> help <command> prints one command’s options with their defaults. The command-line index describes every group. Chapter 3 explains the flags that the groups share.

A.3 Python API

Each function’s docstring documents its arguments, defaults and return fields. Print a signature with inspect, or the whole docstring with help:

import inspect
from cuphoton.xrep import reproject_masked_array

print(inspect.signature(reproject_masked_array))

(image: 'np.ndarray', variance: 'np.ndarray', mask: 'np.ndarray', spec: 'ReprojectionSpec', *, backend: 'str | None' = None, prepared: 'PreparedReprojection | None' = None, variance_fill_value: 'float' = nan) -> 'MaskedReprojectionResult'

Each package lists its public names in __all__:

import importlib

print("package          public names")
for name in ("core", "xdr", "xrep", "ximage", "xpois", "xfit", "xscan", "xray", "xbeam", "xlens"):
    package = importlib.import_module(f"cuphoton.{name}")
    print(f"cuphoton.{name:7s} {len(package.__all__):12d}")

package          public names
cuphoton.core               2
cuphoton.xdr               11
cuphoton.xrep              27
cuphoton.ximage            14
cuphoton.xpois             44
cuphoton.xfit              34
cuphoton.xscan              1
cuphoton.xray               1
cuphoton.xbeam             52
cuphoton.xlens             11

xScan and xRay export only their version at the top level. They are command-line tools first. Their reference pages show the submodules to import from, such as cuphoton.xscan.fits_inference and cuphoton.xray.detector_artifacts. Core’s shared code also lives in submodules:

cuphoton.core.fits_io: the FITS reader and its receipts.
cuphoton.core.arrays: helpers that serve NumPy and CuPy arrays with one code path.
cuphoton.core.cli: the command-line framework.
cuphoton.core.executors: Dragon and MPI execution.

A.4 Documents that span modules

Documentation index: entry points to the repository’s guides and references.
Getting started: install profiles and platform notes.
Quickstarts: synthetic smoke runs for xFit, xPois, xScan, xRep and xRay, plus a separate xBeam example.
Command-line index: each group’s commands and the options they share.
Data and artifact contracts: array shapes, axis order, mask rules and the files each run writes.
Architecture: how the modules fit together, and the order auto tries backends in.
Troubleshooting: environment, CUDA, FITS reader and input errors.
Glossary: cuPhoton and astronomy terms.
Changelog: changes and migration notes by release.

A.5 Getting help

cuPhoton has best-effort community support through its GitHub repository. Its support policy gives the details.

Search the GitHub issues for your problem.
If no issue matches, open a bug report with a minimal reproducer. Include the following:
- the output of cuphoton --version
- the cuPhoton commit, Python version, operating system and installed extras
- the command line and the shapes of your inputs
- for a GPU problem, the GPU model, driver, CUDA runtime, the backend from summary.json, and whether the CPU profile works
Open a feature request for a new workflow or data contract, or a pull request for a concrete fix.

Remove credentials, private paths and proprietary data from what you post. Do not report security problems on GitHub. Follow the security policy instead.