Skip to content

feat: preserve CUDA nonlocal output range semantics - #4464

Merged
ianna merged 2 commits into
mainfrom
ianna/4183-nonlocal-output-ranges
Oct 26, 2026
Merged

ianna merged 2 commits into
mainfrom
ianna/4183-nonlocal-output-ranges

Conversation

@ianna

@ianna ianna commented Oct 23, 2026 •

Copy link
Copy Markdown
Member

Replace the nonlocal output-range kernel proposed in #4183 with a focused implementation based on current main. Part of #4463; the remaining migrations stay tracked there. The unrelated lazy-execution changes are already covered by #4173.

The canonical kernel extends each group's stop to its last nonmissing position. Both #4183's proposed replacement and the existing raw CUDA kernel instead count nonmissing entries: for [0,-1,2,-1,-1,5] in two groups, that gives stops [2,4] rather than the CPU/reference [3,6].

This replacement computes the last present column on the device, preserving interior holes, all-missing groups and empty inputs. It does not explicitly read device scalars on the host. It replaces only awkward_ListOffsetArray_reduce_nonlocal_outstartsstops_64; all other active raw kernels remain registered.

  • Keep the canonical signature/reference unchanged; clarify its description and add the hole case to canonical explicit test data.
  • Update dispatch and generation inputs, remove the replaced raw source and its template exclusion, and regenerate signatures/tests.
  • Add 11 CUDA regression cases covering all CPU output buffers, untouched output capacity, nonzero input-buffer offsets, empty inputs, negative values, holes and dimensions crossing CUDA block boundaries.
  • Add benchmarks/bench_4463_nonlocal_output_ranges.py, measuring median host-dispatch, total wall and CUDA-event time after validation/warmup on small and large workloads. Copy the script into a main checkout and run both revisions on identical hardware and dependencies with matching --iterations, --repeats and a commit --label. Benchmark inputs have prefix occupancy so the old implementation's hole bug does not invalidate the comparison.

Validation:

  • 55 focused canonical reference/native CPU/signature-consistency checks passed; two automatic suites skipped because no automatic cases were generated. The explicit suites ran, including the new canonical case.
  • 2,000 randomized NumPy simulations of the replacement matched the compiled CPU kernel, including all output buffers and untouched capacity.
  • Signature/test generation, Ruff, formatting, Pylint, Python compilation and diff checks passed.
  • No local NVIDIA GPU/CuPy is available. CUDA execution and performance results are pending; no speedup is claimed.

Draft: require passing GPU suites and attach comparative benchmark results before marking ready. Retain the raw approach or revise this implementation if measurements show relevant regressions. No C++ implementation, dependency or package-version changes.

AI assistance: Codex assisted with the extraction, correction, tests and benchmark.

Documentation CI follow-up: use direct raw.githubusercontent.com URLs for five ROOT/Parquet data references in three tutorial notebooks. The old GitHub redirect response exceeded aiohttp's header-size limit. Both replacement data URLs were verified through fsspec/aiohttp, and notebook JSON/diff checks pass. Full documentation execution remains for CI.

@github-actions github-actions Bot added the type/fix PR title type: fix (set automatically) label Oct 23, 2026
@ianna
ianna marked this pull request as ready for review October 23, 2026 20:32
@ianna
ianna requested a review from ariostas October 23, 2026 20:32
@codecov

codecov Bot commented Oct 23, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.31%. Comparing base (d5c2812) to head (1aefa20).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files
Files with missing lines Coverage Δ
src/awkward/_backends/cupy.py 97.72% <ø> (ø)
src/awkward/_connect/cuda/__init__.py 91.89% <ø> (ø)
src/awkward/_connect/cuda/_compute.py 45.83% <100.00%> (+0.42%) ⬆️

... and 2 files with indirect coverage changes

@github-actions

Copy link
Copy Markdown
Contributor

The documentation preview is ready to be viewed at https://preview.awkward-array.org/PR4464/

@TaiSakuma TaiSakuma left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@ianna thank you. I approve the PR.

Optionally, you could consider a different title prefix, such as feat: or refactor:. It is currently fix:. However, the PR doesn't seem to fix anything that users can observe.

🤖 The text below was written by Claude.

Parity with the CPU kernel (at 1aefa20)

  • The new implementation computes each stop as the group start plus one past the last slot that is not -1, which is what the canonical definition and the CPU kernel compute. Running the same code on NumPy against the compiled CPU kernel on 5,000 random inputs (0–5 groups, 0–5 slots per group, about half the slots -1) gave identical outstarts and outstops, including the untouched capacity past outlength.
  • In run 40021666334, both GPU Tests jobs passed. In Run GPU Tests (12), all 11 tests in tests-cuda/test_4463_nonlocal_output_ranges.py and the 27 generated explicit tests for this kernel passed, including the new [0,-1,2,-1,-1,5] case.
  • Inputs where lendistincts is not a multiple of outlength make reshape raise ValueError. The only caller (ListOffsetArray._reduce_next) allocates distincts with outlength * maxcount entries, so these inputs do not occur.

fix: in the PR title: no change in ak.* results

The previous raw CUDA kernel differs from the CPU kernel only when a group has a missing slot before a present one. The kernel's only caller passes distincts from awkward_ListOffsetArray_reduce_nonlocal_preparenext_64, whose CPU and cuda.compute implementations mark slot col as present only when some row in the group has more than col elements, so missing slots occur only at the end of a group. Results of ak.* functions on the CUDA backend are the same before and after this PR. The difference that the fix: title refers to is therefore not observable through any ak.* function; it is observable only when the kernel is called directly with such inputs, as the new tests do.

The commits move one kernel from a raw CUDA source to an implementation in _connect/cuda/_compute.py dispatched through the cuda.compute tables, which matches the feat: prefix more closely than fix:: all five merged PRs whose titles describe migrating kernels to cuda.compute (for example, "feat: migrate UnionArray kernels to cuda.compute") are titled feat:. In the Angular commit convention, from which Conventional Commits takes its types other than feat and fix, refactor: is the prefix for a code change that neither fixes a defect nor adds a feature; by that definition, refactor: also matches these commits.

Public API changes

No change. No public names are added, removed, or renamed, and no signatures or defaults change. The changed source files are src/awkward/_backends/cupy.py and files under src/awkward/_connect/cuda/, which are private, and results of ak.* functions are unchanged as described above.

Existing-test modifications

No expectation changes. No existing test file is modified. kernel-test-data.json gains one case at the start of this kernel's list (13 lines added, none removed); the existing cases are unchanged. The generated test files are renumbered as a result, with the same expectations.

PR description status

The PR description still says GPU execution results are pending; the GPU jobs above have passed. No comparative benchmark results are attached yet.

Scope of test_no_explicit_host_scalar_conversion

The test replaces only cp.asnumpy and a module-level int; it would still pass if the implementation transferred data with .get(), .item(), .tolist(), float(), or a device array in an if.

CUDA_COMPUTE_KERNELS entry

The new entry in dev/generate-tests.py has no effect on the generated tests: that set changes only how error cases are generated, and this kernel has no error cases.

🤖 Generated with Claude Code

@ianna ianna changed the title fix: preserve CUDA nonlocal output range semantics feat: preserve CUDA nonlocal output range semantics Oct 26, 2026
@ianna
ianna merged commit fe91823 into main Oct 26, 2026
39 of 40 checks passed
@ianna
ianna deleted the ianna/4183-nonlocal-output-ranges branch October 26, 2026 20:27
@github-actions github-actions Bot added type/feat PR title type: feat (set automatically) and removed type/fix PR title type: fix (set automatically) labels Oct 26, 2026
ikrommyd referenced this pull request in CoffeaTeam/awkward-lite Oct 27, 2026

This branch was previously deployed

1 inactive deployment
docs — 1aefa20a Deployed Oct 26, 2026 by ianna via Remove Branch Preview #94
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type/feat PR title type: feat (set automatically)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants