[CUB, docs-only] Adds docs page on the requirements users can express for DeviceTopK and DeviceBatchedTopK

[elstehle]

Understanding the top-k requirements that users can express, such as determinism, tie-break, and output-ordering are quite involved. While they are common in the LLM application domain, it may be challenging to grasp for other users. This PR adds a page, describing the determinism, tie-break, and output-ordering requirement that we plan to use with the top-k family of algorithms (e.g., DeviceTopK and DeviceBatchedTopK).

Docs are based on #9354.

The plan is to only link this page from the top-k algorithms for now and only add them to the toctree as a follow-up once #9350 is merged.

Previews:

• this page is new: Top-K: Determinism, Tie-Break…— CUDA Core Compute Libraries.pdf
• this has only a small change: cub:DeviceTopK — CUDA Core Compute Libraries.pdf

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: dfaddc7c-f719-4a5d-8992-24ad7ec1662a

📥 Commits

Reviewing files that changed from the base of the PR and between 6d27715 and 2011698.

📒 Files selected for processing (2)

• cub/cub/device/device_topk.cuh
• docs/cub/api_docs/device_topk_requirements.rst

✅ Files skipped from review due to trivial changes (1)

• cub/cub/device/device_topk.cuh

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/cub/api_docs/device_topk_requirements.rst

---

Note: CodeRabbit is enabled on this repository as a convenience for maintainers
and contributors. Use your best judgment when considering its review comments and
suggestions — a suggested change may be inadequate, unnecessary, or safe to ignore.
Contributors are not expected to address every comment. Human reviews are what
ultimately matter for merging.

Overview

This pull request adds a new CUB documentation page that explains how to express user requirements for the top-k algorithm family (including DeviceTopK / DeviceBatchedTopK entry points) via CUDA execution environment requirements—covering determinism, tie-breaking, and output ordering.

Changes

Documentation updates

cub/cub/device/device_topk.cuh

• Updated the DeviceTopK documentation by replacing the prior “Determinism” section with a combined “Determinism, tie-breaking, and output ordering” section.
• Documents how cuda::execution::determinism (optionally refined by cuda::execution::tie_break) controls set membership, and how cuda::execution::output_ordering controls the order written to the output.
• States that the current release only supports the fully opted-out configuration and rejects other requirement combinations at compile time.

docs/cub/api_docs/device_topk_requirements.rst (new)

• Introduces a dedicated “Top-K: Determinism, Tie-Breaking, and Output Ordering” page.
• Separates requirements into two orthogonal concerns:
  • Set membership: cuda::execution::determinism (optionally refined by cuda::execution::tie_break)
  • Output sequence ordering: cuda::execution::output_ordering
• Defines allowed values and their meanings for determinism, tie_break, and output_ordering (including stable_sorted behavior).
• Documents the committed default contract (deterministic run-to-run with prefer_smaller_index tie-breaking and stable_sorted output).
• Notes current support is limited to the fully opted-out configuration (determinism::not_guaranteed + output_ordering::unsorted) and that other combinations (including invalid tie_break pairings) are rejected at compile time.
• Provides guidance for composing requirements via cuda::execution::require(...), worked examples demonstrating how selections and ordering change across requirement combinations, and a concise recommendations summary.

Walkthrough

Updates the DeviceTopK inline header doc to replace the old single-section determinism block with a new section covering determinism, tie-breaking, and output ordering. Adds a new RST reference page defining requirement values, constraints, worked examples, a recommendation table, and a concluding summary.

Changes

DeviceTopK Requirements Documentation

Layer / File(s)	Summary
Updated inline header doc cub/cub/device/device_topk.cuh	Replaces the old "Determinism" doc section with "Determinism, tie-breaking, and output ordering," covering default committed behavior, the only currently supported opted-out configuration (determinism::not_guaranteed + output_ordering::unsorted), and compile-time rejection of other combinations.
New RST page: intro and reference tables docs/cub/api_docs/device_topk_requirements.rst	Adds the page title, introduction separating set membership from output sequence concerns, the default behavior contract, and reference tables for determinism, tie_break (with validity constraints), and output_ordering values.
Composing requirements and set membership docs/cub/api_docs/device_topk_requirements.rst	Adds a cuda::execution::require(...) composition example and the set membership section explaining how determinism + tie_break together pin boundary-tie behavior including prefer_smaller_index and prefer_larger_index.
Worked example: result matrix docs/cub/api_docs/device_topk_requirements.rst	Provides a concrete input dataset and a result matrix comparing multiple requirement combinations across two runs, with explanation of how set membership versus output ordering effects appear in the results.
Recommendations table and summary docs/cub/api_docs/device_topk_requirements.rst	Adds a goal-to-configuration recommendation table mapping stated goals to require(...) configurations and a concluding summary restating which requirements govern set membership versus output ordering.

Possibly related PRs

• NVIDIA/cccl#9238: Introduced cuda::execution::tie_break and its interaction model with cuda::execution::determinism, which this PR documents in detail for DeviceTopK.

Suggested reviewers

• davebayer

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🥳 CI Workflow Results

🟩 Finished in 1h 29m: Pass: 100%/287 | Total: 1d 19h | Max: 1h 04m | Hits: 99%/196426

See results here.

[jrhemstad]

These additions are chefs kiss.

I really like your table of worked examples and including both a behavior debugging guide as well as guidance for what options to use based on desired outcome.

This is how reference docs should be done!