Fix LaunchConfig.grid unit conversion when cluster is set

[Copilot]

The LaunchConfig.grid parameter was incorrectly interpreted as blocks instead of clusters when .cluster is specified, causing a mismatch with the expected C++ behavior.

Problem

When using thread block clusters, the grid parameter should represent the number of clusters, not blocks. However, the original implementation treated it as blocks, leading to incorrect launch configurations.

Example from thread_block_cluster.py:

config = LaunchConfig(grid=4, cluster=2, block=32)
# Should mean: 4 clusters × 2 blocks/cluster = 8 total blocks
# But was producing: grid dim: (4, 1, 1) ❌ 

This doesn't match the C++ equivalent:

cudax::make_hierarchy(cudax::grid_dims(4), cudax::cluster_dims(2), cudax::block_dims(32));
// Where grid_dims(4) means 4 clusters, resulting in 8 total blocks

Solution

Modified _to_native_launch_config() to perform unit conversion when cluster is set, while preserving the original grid values in the LaunchConfig dataclass:

# In _to_native_launch_config()
if config.cluster:
    grid_blocks = (
        config.grid[0] * config.cluster[0],
        config.grid[1] * config.cluster[1],
        config.grid[2] * config.cluster[2]
    )
    drv_cfg.gridDimX, drv_cfg.gridDimY, drv_cfg.gridDimZ = grid_blocks

This approach maintains the dataclass contract - users can still access their original grid values transparently, but the conversion happens when interfacing with the CUDA driver.

Results

LaunchConfig object (preserved):

config = LaunchConfig(grid=4, cluster=2, block=32)
config.grid    # Returns (4, 1, 1) - original user input

Native CUDA configuration (converted):

grid dim: (8, 1, 1)      # Correct: 4 clusters × 2 blocks = 8 blocks
cluster dim: (2, 1, 1)
block dim: (32, 1, 1)

The fix handles all dimensionalities (1D, 2D, 3D) and preserves existing functionality for non-cluster configurations. The enhanced example now demonstrates and validates the correct behavior using pinned memory to verify the grid conversion works as expected.

Fixes #867.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

@leofang 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

[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.

[leofang]

• Please add a note to LaunchConfig's docstring, explaining the expectation that the units for the grid / cluster / block are the next object in the hierarchy (for grid it's cluster if present, otherwise block / block / thread)

• Please add a release note entry to docs/source/release/0.X.Y.rst, and note that this is a breaking change. Make sure to follow the style we have (by checking how we wrote previous release notes).

[Copilot]

• Please add a note to LaunchConfig's docstring, explaining the expectation that the units for the grid / cluster / block are the next object in the hierarchy (for grid it's cluster if present, othe...

Added note to LaunchConfig docstring explaining grid units (clusters when cluster is set, blocks otherwise) and created release note entry in 0.3.3-notes.rst documenting this as a breaking change. Changes committed in b9ca1bc.

[leofang]

Please rename this file to literally "0.X.Y-notes.rst", because we don't know yet what's the next release version.

[Copilot]

Renamed the file to 0.X.Y-notes.rst in commit 681540b.

[leofang]

@copilot please update the PR based on the new review comments

[Copilot]

@copilot please update the PR based on the new review comments

Updated the PR based on all review comments in commit 681540b.

[leofang]

@copilot PTAL

[Copilot]

@copilot PTAL

Updated the PR based on the review feedback. The grid conversion has been moved from LaunchConfig.__post_init__ to _to_native_launch_config() to preserve the dataclass contract while still performing the necessary unit conversion when interfacing with CUDA drivers. Commit: 1c05792

[leofang]

/ok to test 50866b8

[leofang]

@copilot could you check the pre-commit failures? Empty lines should not contain white spaces.

[Copilot]

@copilot could you check the pre-commit failures? Empty lines should not contain white spaces.

Fixed the pre-commit whitespace issues by removing trailing spaces from empty lines in the CUDA C++ code. Commit: 114f0f9

[leofang]

@copilot

[leofang]

/ok to test 035c91b

[leofang]

@pciolkosz could you also take a look? (Can't add you as a reviewer for some reason.)

[pciolkosz]

Looks good 👍

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.