[Doc] Add user guide page for subgroup shuffle

[hughperkins]

Document the portable qd.simt.subgroup.shuffle op: backend support matrix, semantics, examples (broadcast, identity, neighbour swap, per-lane gather), and performance notes. Note that shuffle_up, shuffle_down, and shuffle_xor are not yet implemented across backends. Link from the SIMT primitives section of the user guide index.

Issue: #

Brief Summary

copilot:summary

Walkthrough

copilot:walkthrough

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6f781916bf

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Reference the actual subgroup size API

The new guide points users to subgroup.size(), but the SIMT API exposes group_size() and does not define a size() alias (python/quadrants/lang/simt/subgroup.py). Anyone following this section will hit an AttributeError instead of getting subgroup size, so the doc should use the real callable name.

Useful? React with 👍 / 👎.

[claude]

Additional findings (outside current diff — PR may have been updated during review):

• 🔴 docs/source/user_guide/shuffle.md:120-123 — The Related section of shuffle.md (line 123) references subgroup.size(), but this function does not exist in the subgroup module — the correct name is subgroup.group_size(). Any user following the docs and calling subgroup.size() will get an AttributeError at runtime; fix by changing subgroup.size() to subgroup.group_size() on line 123.

  Extended reasoning...

  What the bug is: The newly added shuffle.md documentation page includes a Related section that lists subgroup.size() as a function that returns the active subgroup size. This function name is wrong — it does not exist in the subgroup module.

  Specific code path: In python/quadrants/lang/simt/subgroup.py, line 42 defines the function as def group_size():, which calls impl.call_internal("subgroupSize", ...). There is no size() function anywhere in the module, and size does not appear in __all__ either.

  Why existing code doesn't prevent it: This is a documentation-only error introduced in this PR. The Python module itself is correct; the mistake is purely in the prose of shuffle.md at line 123, which says subgroup.size() — returns the active subgroup size.

  Impact: A user reading the guide and writing lane_count = subgroup.size() will receive an AttributeError: module 'quadrants.lang.simt.subgroup' has no attribute 'size' at runtime. This is directly misleading documentation that references a non-existent API.

  Step-by-step proof:

  1. Open python/quadrants/lang/simt/subgroup.py — the exported names in __all__ are shuffle, shuffle_xor, shuffle_up, shuffle_down; group_size and invocation_id exist as functions but are not in __all__.
  2. Search def size in the file — no results.
  3. A user reads shuffle.md line 123: subgroup.size() — returns the active subgroup size.
  4. User writes n = subgroup.size() in a kernel.
  5. At runtime: AttributeError: module '...' has no attribute 'size'.

  Fix: Change line 123 of shuffle.md from subgroup.size() to subgroup.group_size().

  Note on the refutations: The only refutations filed were duplicate-of claims between bug_001 and bug_004, which described the same underlying issue. The synthesis agent correctly merged them into a single report. There is no substantive disagreement that this is a real bug.

• 🔴 docs/source/user_guide/shuffle.md:19-22 — The docs incorrectly describe shuffle_up, shuffle_down, and shuffle_xor as all failing at codegen: shuffle_xor is a Python stub that silently returns None (never reaching the compiler), while shuffle_up and shuffle_down are fully implemented on the SPIR-V/Vulkan backend. Vulkan users should use shuffle_up/shuffle_down freely; for shuffle_xor, callers get a silent None causing a cryptic downstream TypeError rather than the codegen error described.

  Extended reasoning...

  Two distinct inaccuracies are introduced by the documentation on lines 19–22.

  Inaccuracy 1 — shuffle_xor silently returns None (not a codegen error)

  In python/quadrants/lang/simt/subgroup.py, shuffle_xor (lines 145–147) is a stub with only a # TODO comment and a bare pass body. Because it never calls impl.call_internal, it returns None implicitly at the Python level and never touches the compiler. A user calling result = subgroup.shuffle_xor(val, mask) receives None silently; any subsequent use of result (e.g. writing it to an array element) produces a cryptic TypeError rather than the clear codegen error the documentation promises.

  In contrast, shuffle_up (line 150) and shuffle_down (line 154) both call impl.call_internal('subgroupShuffleUp', ...) / impl.call_internal('subgroupShuffleDown', ...), so they do reach the compiler, and a codegen failure is the correct description for them on unsupported backends.

  Inaccuracy 2 — shuffle_up and shuffle_down are fully implemented on SPIR-V/Vulkan

  The SPIR-V codegen (quadrants/codegen/spirv/spirv_codegen.cpp lines 1284–1300) explicitly handles both subgroupShuffleUp and subgroupShuffleDown, lowering them to spv::OpGroupNonUniformShuffleUp and spv::OpGroupNonUniformShuffleDown respectively. A Vulkan user calling either operation will get correct, hardware-accelerated behaviour — not a codegen error.

  Addressing the refutation for this point: One verifier argued that the phrase 'not yet implemented across backends' is still accurate because CUDA and AMDGPU do not handle these ops. That reading is correct in a narrow sense, but the sentence the docs actually writes is 'Calling them will fail at codegen' — an unqualified statement with no backend qualification. A Vulkan user reading this warning would wrongly avoid two operations that work correctly for them. The documentation needs to distinguish between backends.

  Step-by-step proof (shuffle_xor)

  1. User writes: out = subgroup.shuffle_xor(val, 1)
  2. Python calls shuffle_xor(val, 1); the function body is pass; return value is None.
  3. User then writes: arr[i] = out inside a kernel.
  4. The compiler receives None as the RHS, producing a TypeError such as unsupported operand type(s) or a confusing tracing error — not a 'codegen error for unimplemented op' as the docs claim.

  How to fix

  Split the note into two: (a) shuffle_xor is not yet implemented and currently returns None — avoid it; (b) shuffle_up and shuffle_down are supported on SPIR-V/Vulkan but not yet on CUDA or AMDGPU backends — use with awareness of backend limitations.

[hughperkins]

Thanks! 🙌