[places] Add checked execution grid reshaping

[caugonnet]

Summary

• add exec_place::reshape() to change grid coordinates while preserving linear place order
• add collapse_axes() for merging contiguous processor-grid axes
• reject shaped grids whose dimensions are zero or do not match the place count
• document the coordinate transformation semantics and pin them with co-located unit tests

Test plan

• pre-commit run --files cudax/include/cuda/experimental/__places/places.cuh docs/cudax/places.rst
• cmake --build build/preset-latest --target cudax.test.places.unittest_headers.__places.places -j 4
• ctest --test-dir build/preset-latest --output-on-failure -R '^cudax\.test\.places\.unittest_headers\.__places\.places$'

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

[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: 09bd788e-568f-4bd6-8952-ba2915ff387c

📥 Commits

Reviewing files that changed from the base of the PR and between c93c5f6 and 7aa089a.

📒 Files selected for processing (1)

• cudax/include/cuda/experimental/__places/places.cuh

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

• cudax/include/cuda/experimental/__places/places.cuh

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added reshape() to view a place grid with new dimensions while preserving linear place order.
  • Added collapse_axes(first, last) to merge a contiguous range of axes into a single dimension.
• Bug Fixes
  • Grid construction and transformation operations now validate inputs and throw clear std::invalid_argument errors for empty grids, zero dimensions, mismatched sizes, and invalid axis ranges.
• Documentation
  • Documented how to reshape grids and collapse axes, including examples.

Walkthrough

Changes

Adds reshape and collapse_axes to exec_place, preserves linear place order during transformations, replaces assertion-only grid validation with std::invalid_argument, and adds tests and documentation.

Grid transformations

Layer / File(s)	Summary
Validation and public API cudax/include/cuda/experimental/__places/places.cuh	Declares grid transformation methods and validates empty places, zero dimensions, and dimension-count mismatches with exceptions.
Grid transformations and coverage cudax/include/cuda/experimental/__places/places.cuh	Implements reshaping and contiguous axis collapsing while preserving linear order, with tests for valid dimensions, ordering, and invalid inputs.
Transformation documentation docs/cudax/places.rst	Documents reshape() and collapse_axes() behavior and dimension examples.

Suggested labels: places

Suggested reviewers: ericniebler

---

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

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

cudax/include/cuda/experimental/__places/places.cuh (1)

1539-1541: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

important: make_grid(::std::vector<exec_place>) still aborts on places.empty() in debug builds because of _CCCL_ASSERT, so callers can’t rely on std::invalid_argument here. Drop the assertion and add a regression test for make_grid({}).

🧹 Nitpick comments (1)

docs/cudax/places.rst (1)

437-465: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

suggestion: Document that reshape rejects zero extents and that collapse requires 0 <= first <= last < 4, with std::invalid_argument for violations. The current text explains semantics but omits the invocation constraints. As per path instructions, focus on technical accuracy and API/version consistency for documentation changes.

Source: Path instructions

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 74863ac0-8edd-4349-97f7-7d989ecc9518

📥 Commits

Reviewing files that changed from the base of the PR and between 0d919ed and c93c5f6.

📒 Files selected for processing (2)

• cudax/include/cuda/experimental/__places/places.cuh
• docs/cudax/places.rst

[caugonnet]

/ok to test c93c5f6

[caugonnet]

/ok to test 7aa089a

[github-actions]

🥳 CI Workflow Results

🟩 Finished in 1h 03m: Pass: 100%/57 | Total: 1d 01h | Max: 1h 03m | Hits: 14%/188486

See results here.