feat(cuda.core): add cluster scheduling policy to LaunchConfig

[atiaomar1978-hub]

Description

closes #2629

Add cluster_scheduling_policy_preference to LaunchConfig, mapping to
CU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE via
ClusterSchedulingPolicyType (DEFAULT, SPREAD, LOAD_BALANCING).

Unlike stream synchronization policy (#2628), cluster scheduling policy is
documented as valid for graph nodes and kernel launches, so LaunchConfig is
the correct surface.

This is a signed re-issue of #2702 (same change, linear history on current
main). Commits are SSH-signed. GitHub would not reopen #2668.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

Test plan

• Native attribute mapping for DEFAULT / SPREAD / LOAD_BALANCING
• Getter/setter round-trip for each policy
• Driver enum acceptance; invalid value rejection; CC < 9.0 gate
• Combined cluster + policy attributes
• Hopper+ launch() smoke for all three policies
• RunPod H100 80GB HBM3 / driver 580 / CTK 13.3 — 13 passed, 0 skipped
• pre-commit.ci stubgen-pyx stubs regenerated

[copy-pr-bot]

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.

[atiaomar1978-hub]

Hi @lijinf2 — when you have a moment, could you please review this PR?

This is the signed re-issue of #2702 (GitHub would not reopen #2668). It implements the plan we aligned on in #2629: LaunchConfig.cluster_scheduling_policy_preference maps to CU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE (DEFAULT / SPREAD / LOAD_BALANCING), with CC >= 9.0 gating.

Tests follow your guidance (getter/setter plus a launch() run-through; no attempt to observe the live scheduler). On RunPod H100 80GB HBM3 (CC 9.0, driver 580, CTK 13.3) the cluster-policy suite is 13 passed, 0 skipped.

I do not have permission to set assignee or milestone on this account; cuda.core 1.3.0 would match the related work if that is still the right milestone.

Sorry for the force-push on this branch. I know rewriting published history is against the project rules. I did it only so the commits would be SSH-signed and show as Verified on GitHub. I will not force-push again.

[lijinf2]

/ok to test c6c283b

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-2703/
https://nvidia.github.io/cuda-python/pr-preview/pr-2703/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-2703/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-2703/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[atiaomar1978-hub]

Posted a docs fix for the CI failure on test_subpackage_exports_are_documented[typing].

ClusterSchedulingPolicyType was exported from cuda.core.typing but missing from docs/source/*.rst. Commit 39c9fc0843 adds it to api_private.rst (SSH-signed / Verified).

RunPod (RTX 2000 Ada, CC 8.9 — L4 community was out of stock; same compute capability as the failing L4 jobs):

• test_subpackage_exports_are_documented[typing] passed
• cluster launcher suite: 10 passed, 3 skipped (launch smokes require CC >= 9.0)

PR metadata is now set (cuda.core, feature, assignee, milestone).

[atiaomar1978-hub]

Hi @lijinf2 — could you please trigger CI again on 39c9fc0843?

The previous /ok to test covered c6c283bb5d3f. That matrix failed; this SHA has the docs fix and has not gotten a new GPU run yet.

Why CI failed

Every GPU job died on the same assertion — not on LaunchConfig or Hopper launch:

tests/test_api_docs_consistency.py::test_subpackage_exports_are_documented[typing] FAILED
E   AssertionError: public by cuda.core.typing.__all__ but missing from docs/source/*.rst:
E       ['ClusterSchedulingPolicyType']

ClusterSchedulingPolicyType was added to cuda.core.typing.__all__ but was not listed in cuda_core/docs/source/api_private.rst (the autosummary the consistency test reads). Example: linux-64 / py3.10 / CUDA 13.3 wheels / L4 — 1 failed, launcher cluster tests passed or skipped by CC.

Why it works again

39c9fc0843 adds the missing autosummary line:

typing.ClusterSchedulingPolicyType

That name is now present in docs/source/*.rst, so the export-vs-docs check passes. Runtime tests were already green.

RunPod replay (pod 7xp9vqqo44kk1s, RTX 2000 Ada, CC 8.9)

L4 community was out of stock; Ada is the same CC 8.9 as the failing L4 jobs. HEAD on the pod was 39c9fc0.

############ CI FAILURE: docs export consistency (typing) ############
tests/test_api_docs_consistency.py::test_subpackage_exports_are_documented[typing] PASSED [100%]
======================= 1 passed, 5 deselected in 1.10s ========================

############ CLUSTER SCHEDULING POLICY TESTS (CI-like GPU) ############
compute_capability ComputeCapability(major=8, minor=9)
tests/test_launcher.py::test_to_native_launch_config_cluster_scheduling_policy[0] PASSED
tests/test_launcher.py::test_to_native_launch_config_cluster_scheduling_policy[1] PASSED
tests/test_launcher.py::test_to_native_launch_config_cluster_scheduling_policy[2] PASSED
tests/test_launcher.py::test_to_native_launch_config_cluster_scheduling_policy_accepts_driver_enum PASSED
tests/test_launcher.py::test_launch_config_cluster_scheduling_policy_invalid PASSED
tests/test_launcher.py::test_launch_config_cluster_scheduling_policy_rejects_pre_hopper_cc PASSED
tests/test_launcher.py::test_to_native_launch_config_cluster_and_policy PASSED
tests/test_launcher.py::test_launch_config_cluster_scheduling_policy_getter_setter[0] PASSED
tests/test_launcher.py::test_launch_config_cluster_scheduling_policy_getter_setter[1] PASSED
tests/test_launcher.py::test_launch_config_cluster_scheduling_policy_getter_setter[2] PASSED
tests/test_launcher.py::test_launch_cluster_scheduling_policy_smoke[0] SKIPPED
tests/test_launcher.py::test_launch_cluster_scheduling_policy_smoke[1] SKIPPED
tests/test_launcher.py::test_launch_cluster_scheduling_policy_smoke[2] SKIPPED
=========== 10 passed, 3 skipped, 61 deselected, 1 warning in 0.74s ============

Launch smokes skip on CC < 9.0, same as the L4 CI jobs. Pod has been deleted.

Full pod log (nvidia-smi + pytest; apt/pip noise omitted)

Thu Aug 27 21:56:33 2026
NVIDIA-SMI 570.195.03   Driver Version: 570.195.03   CUDA Version: 12.8
GPU: NVIDIA RTX 2000 Ada Generation

HEAD: 39c9fc0 docs(cuda.core): document ClusterSchedulingPolicyType in API RST
Fetching mini CUDA toolkit 13.3.0...
#define CUDA_VERSION 13030
cuda.core 0.0.0

tests/test_api_docs_consistency.py::test_subpackage_exports_are_documented[typing] PASSED
======================= 1 passed, 5 deselected in 1.10s ========================

compute_capability ComputeCapability(major=8, minor=9)
10 passed, 3 skipped, 61 deselected, 1 warning in 0.74s

Thank you.

[lijinf2]

/ok to test 39c9fc0

[lijinf2]

@atiaomar1978-hub Hey, there are 7 test cases, and it looks like some are redundant. Could we remove redundancy and merge them into at most 3 cases to reduce code maintenance overhead going forward?

[atiaomar1978-hub]

I will do now @lijinf2

[atiaomar1978-hub]

@lijinf2 folded the seven cluster-policy tests into three in 1a78ad5cd1 (Verified):

1. test_launch_config_cluster_scheduling_policy — ctor / getter-setter / driver enum / native attrs for DEFAULT, SPREAD, LOAD_BALANCING (including cluster + policy together)
2. test_launch_config_cluster_scheduling_policy_rejected — invalid value and CC < 9.0
3. test_launch_cluster_scheduling_policy_smoke — launch() for all three policies on Hopper+

Could you /ok to test 1a78ad5cd1cf0294d91994b0214ec71bdf9bdd2f when you have a moment?

[lijinf2]

/ok to test 1a78ad5

[atiaomar1978-hub]

@lijinf2 CUDA 13.0.2 jobs failed on test_launch_config_cluster_scheduling_policy (AttributeError — that setter reads .value, so a raw int breaks). 3a90298eb1 passes CUclusterSchedulingPolicy instead.

RunPod replay (RTX 2000 Ada, bindings 13.0.3): mapping + reject PASSED; smoke SKIPPED on CC 8.9 (already passed on CI H100).

Could you please /ok to test 3a90298eb1e788047e702076b81dcdb28073e699?