Skip to content

Keep scaled 32-bit xDR images exact in float64 - #192

Open
0z5a wants to merge 3 commits into
NVIDIA:mainfrom
0z5a:fix/xdr-scaled-int32-precision
Open

0z5a wants to merge 3 commits into
NVIDIA:mainfrom
0z5a:fix/xdr-scaled-int32-precision

Conversation

@0z5a

@0z5a 0z5a commented Nov 12, 2026 •

Copy link
Copy Markdown

Summary

Fixes #189 (cuphoton.xdr).

GpuImageReader.read(), and the output specs of batch_to_device / batch_to_device_stream, promote a scaled integer image (BSCALE != 1 or BZERO != 0) to float32 whenever the on-disk item size is at most 4 bytes. float32 has a 24-bit significand, so BITPIX = 32 values above 224 are rounded. With the FITS unsigned 32-bit convention (BZERO = 231), 4294967295 is returned as 4294967296.0, outside the uint32 range. Astropy, CFITSIO and cuphoton.core.fits_io._logical_dtype all keep these values exact.

The three sites (xdr/reader.py, and _probe_output_specs / _consume_image in xdr/prefetch.py) now use float32 only for 8- and 16-bit integers and float64 otherwise. 8- and 16-bit images are unchanged. xDR still returns float64 where Astropy returns uint32 for the unsigned convention, but the values are exact; matching uint32 would be a larger change and is not part of this PR.

Tests: the existing promotion tests in tests/xdr/test_prefetch.py get an i4 case each (CPU, fake CuPy, like the existing cases). tests/xdr/test_reader.py::test_image_reader_scales_int32_images_without_rounding writes uint32 (BZERO = 2**31) and int32 + BZERO = 0.5 files with Astropy, reads them with GpuImageReader under KvikIO compatibility mode, and compares with Astropy. The routine GPU job explicitly selects both parametrizations and rejects skipped tests. The regression forces KvikIO compatibility mode, so it requires a CUDA device but does not require GPUDirect Storage.

Residual risk: tile-compressed images (GpuCompImageReader) do not apply BZERO/BSCALE at all; that is a separate question and is not changed here.

Validation

x86_64 Linux, Python 3.12.3, uv sync --locked --extra dev --extra io at cc16e05. GPU steps on a Blackwell (sm_103) GPU with KVIKIO_COMPAT_MODE=ON, without the native extensions.

uv lock --check                                       # Resolved 203 packages, rc 0
make lint                                             # mypy: no issues in 268 source files; ruff check: all passed; ruff format: 568 files already formatted
pytest -q tests/xdr/test_reader.py::test_image_reader_scales_int32_images_without_rounding \
  tests/xdr/test_prefetch.py::test_probe_output_specs_promotes_scaled_integer_images \
  tests/xdr/test_prefetch.py::test_consume_image_stages_raw_bytes_before_scaling
                                                      # GPU, cc16e05 + new tests: 4 failed, 3 passed; with this change: 7 passed
pytest -q -rs tests/xdr                               # GPU, with this change: 451 passed, 115 skipped (native extensions not built)
make test-cpu                                         # cc16e05: 6125 passed, 1086 skipped; with this change: 6127 passed, 1088 skipped

pre-commit run --all-files was not run. The code change touches only Python, which make lint covers. The CHANGELOG commit passes the pre-commit whitespace and end-of-file hooks.

Repository hygiene

  • No credentials, private paths, local datasets, notebook outputs, or generated run artifacts were added.
  • Large binary artifacts are excluded or intentionally tracked through an approved storage plan.
  • Security-sensitive information is not included.
  • User-visible behavior changes are documented. (Scaled 32-bit images from the xDR readers are now float64 instead of float32; noted under ### xDR in the Unreleased section of CHANGELOG.md.)
  • New dependencies and their licenses are documented. (None added.)

This change was drafted with Claude Code (claude-opus-5-5); the test results above are from the runs described.

@0z5a
0z5a requested review from melo-gonzo and tpn as code owners November 12, 2026 18:29
@copy-pr-bot

copy-pr-bot Bot commented Nov 12, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@coderabbitai

coderabbitai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Scaled 32-bit integer images now use float64 in GpuImageReader.read, batch_to_device, and batch_to_device_stream. Tests cover unsigned-convention and fractional-BZERO FITS images. The Unreleased changelog documents the output dtype and device memory use.

Changes: Scaled Image Precision

Layer / File(s) Summary
Select output dtype for scaled integer images
src/cuphoton/xdr/reader.py, src/cuphoton/xdr/prefetch.py
The reader and prefetch paths now use float32 for scaled integer images of 8 or 16 bits and float64 for larger integer images.
Validate and document 32-bit output
tests/xdr/test_prefetch.py, tests/xdr/test_reader.py, .github/workflows/ci.yml, CHANGELOG.md
Prefetch tests cover 16- and 32-bit inputs. GPU-backed reader tests check exact float64 results for unsigned-convention and fractional-BZERO 32-bit images. The CI command includes the reader test. The changelog describes the output dtype and device memory use.

Severity of issue fixed: Medium

Merge Risk: Minimal · up to 5e4b6

Scaled 32-bit integer images now return exact float64 values instead of float32-rounded ones, using about twice the device memory for those images. The change is small, tested, and documented, so merge risk is minimal.

Architecture risk: Low · up to 5e4b6

The change affects 3 systems.

Changed systems: src, tests, CHANGELOG.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — src (service) was modified; 2 changed files map to changed impact.
  • observed — tests (service) was modified; 2 changed files map to changed impact.
  • observed — CHANGELOG.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in src/cuphoton/xdr/prefetch.py: Output dtype selection for scaled integer images now chooses float32 only when image_itemsize <= 2; previously, item sizes up to 4 bytes used float32.
  • observed — Modified behavior in src/cuphoton/xdr/prefetch.py: Image consumption now converts scaled integer output to float32 only when image_itemsize <= 2; previously, the threshold was 4 bytes.
  • observed — Modified behavior in src/cuphoton/xdr/reader.py: GpuImageReader.read documents float32 scaling for 8- and 16-bit data and changes the promotion threshold from itemsize <= 4 to itemsize <= 2; 32-bit integer data now uses float64.
  • observed — Modified behavior in tests/xdr/test_prefetch.py: The scaled-image promotion test adds a 32-bit integer case with float64 as its expected dtype; the existing 16-bit and 64-bit cases remain.
Pre-merge checks: Passed 2

Check name Status Explanation
Linked Issues check Passed [#189] requires exact values from GpuImageReader.read() for scaled, uncompressed BITPIX=32 images, and the same exact dtype rule for batch_to_device and batch_to_device_stream. At the reviewed head, s…
Out of Scope Changes check Passed All changed hunks connect to #189. The reader.py hunk changes only the float32/float64 promotion rule and adds a comment. The two prefetch.py hunks apply the same rule at the two output-spec sites. Th…
Full details: Linked Issues check

Explanation

[#189] requires exact values from GpuImageReader.read() for scaled, uncompressed BITPIX=32 images, and the same exact dtype rule for batch_to_device and batch_to_device_stream. At the reviewed head, src/cuphoton/xdr/reader.py uses cp.float32 only when itemsize <= 2 and cp.float64 otherwise. src/cuphoton/xdr/prefetch.py applies the same rule in _probe_output_specs (line ~168) and _consume_image (line ~830). The issue accepts float64 or uint32 output, so float64 satisfies it. 8- and 16-bit behavior is unchanged. Automated coverage: tests/xdr/test_prefetch.py adds i4 promotion cases using CPU and fake CuPy. tests/xdr/test_reader.py adds a GPU test comparing GpuImageReader output with Astropy for uint32 (BZERO=2**31) and int32 with BZERO=0.5. The GPU result is taken from the PR's reported runs and was not re-executed. The CI selection change in .github/workflows/ci.yml is present at head, so the GPU job runs the regression test. The PR description says CI selection is unchanged; that statement is stale and does not affect the code requirement. Not inspected: apply_bzero_bscale internals, which the issue does not require to change.

Full details: Out of Scope Changes check

Explanation

All changed hunks connect to #189. The reader.py hunk changes only the float32/float64 promotion rule and adds a comment. The two prefetch.py hunks apply the same rule at the two output-spec sites. The tests in tests/xdr/test_prefetch.py and tests/xdr/test_reader.py verify that rule. The .github/workflows/ci.yml change adds the regression test to the GPU selection, which supports verifying #189. The CHANGELOG.md entry under ### xDR documents the dtype and memory change for the affected APIs. GpuCompImageReader scaling and uint32 output are not changed. No unrelated changes were found.

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 374c3ad and 5e4b62b.

Files selected for processing: 2

  • .github/workflows/ci.yml
  • CHANGELOG.md
Files skipped from review as they are similar to previous changes: 1

  • CHANGELOG.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

@melo-gonzo melo-gonzo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the fix and the clear write-up. The change is right. float32 has a 24-bit significand, so it holds every 8- and 16-bit integer but not every 32-bit one. The new rule matches Astropy and cuphoton.core.fits_io._logical_dtype, which returns float64 for scaled data above 16 bits. All three promotion sites now agree: GpuImageReader.read, _probe_output_specs and _consume_image. No other itemsize <= 4 promotion is left in src/.

The new tests check the right values. 2**31 + 2**24 + 1 lies between float32 values, which are 256 apart at that size, so the old float32 path cannot pass the new _consume_image case. The new i4 case in test_probe_output_specs_promotes_scaled_integer_images expects f8 where the old code gives f4.

Considerations, none blocking:

  • I checked this by reading the code and tests. I did not run them in this review, and CI has not run yet, because workflows from outside contributors wait for a maintainer to approve them.
  • Scaled 32-bit images now come back as float64 instead of float32. That doubles their device memory and changes the result dtype for callers. A CHANGELOG line would help, as you offered.
  • As you note, CI does not run test_image_reader_scales_int32_images_without_rounding, because the GPU job's tests/xdr selection skips test_reader.py.
  • GpuCompImageReader not applying BZERO/BSCALE is worth its own issue.

@0z5a

0z5a commented Nov 12, 2026

Copy link
Copy Markdown
Author

Thanks for the review. I added the CHANGELOG entry in 080ddef, as a new ### xDR section under Unreleased. It says that scaled 32-bit images from GpuImageReader.read(), batch_to_device and batch_to_device_stream are now float64 and use twice the device memory, and that 8- and 16-bit images stay float32. The commit changes only CHANGELOG.md.

I left the CI selection as it is. Adding test_reader.py to the GPU job's tests/xdr selection would change CI for every PR, so I'd rather do it separately if you want it. I can open an issue for GpuCompImageReader not applying BZERO/BSCALE.

@melo-gonzo

Copy link
Copy Markdown
Collaborator

Thanks. The entry at 080ddef is accurate, and a separate change for the CI selection is fine. Please open the GpuCompImageReader issue.

@tpn tpn added the ai-review Request a focused CodeRabbit review label Nov 16, 2026
0z5a and others added 3 commits November 16, 2026 14:49
GpuImageReader, batch_to_device and batch_to_device_stream promote a
scaled integer image (BSCALE != 1 or BZERO != 0) to float32 whenever
the on-disk item size is at most 4 bytes. float32 has a 24-bit
significand, so BITPIX = 32 values above 2**24 are rounded. With the
FITS unsigned 32-bit convention (BZERO = 2**31), 4294967295 is returned
as 4294967296.0, which is outside the uint32 range.

Astropy, CFITSIO and cuphoton.core.fits_io._logical_dtype all use
float64 for scaled BITPIX = 32. Use float32 only for 8- and 16-bit
integers, and add BITPIX = 32 cases to the promotion tests plus a GPU
test that compares GpuImageReader with Astropy.

Signed-off-by: Dezhen Lu <dezhen.lu@student.uni-tuebingen.de>
Scaled BITPIX = 32 images from GpuImageReader, batch_to_device and
batch_to_device_stream now come back as float64 instead of float32,
which changes the result dtype and doubles their device memory.

Signed-off-by: Dezhen Lu <dezhen.lu@student.uni-tuebingen.de>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Include the scaled-int32 reader regression in the existing GPU test
selection so its compatibility-mode cases run and cannot silently skip.

Signed-off-by: Trent Nelson <trentn@nvidia.com>
@tpn
tpn force-pushed the fix/xdr-scaled-int32-precision branch from 374c3ad to 5e4b62b Compare November 16, 2026 22:50

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-review Request a focused CodeRabbit review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: xDR GpuImageReader rounds scaled 32-bit integer images to float32

3 participants