Subrange Support

[alanray-tech]

Core Principle

Principle	Reason
Fast Fail	Catch GPU errors immediately with early GPU kernel trap, auto-sync
Agent friendly	Structured error messages and stack traces parsable by AI for automated debugging

BufferView — Safe Sub-range Access

BufferView provides bounds-checked sub-range views, avoiding OOB risks from raw pointer + offset, and which provide us with the ability to support more Logical-Level OOB check.

N = 32
data = qd.ndarray(qd.f32, shape=(N,))
# Will it be better to have:
# view = data[0:16]
# view = data.subview(offset=0, count=16) 
# ?
# the way above requires an invasion into the qd.ndarray class.
view = qd.BufferView(data, offset=0, count=16)

@qd.kernel
# It will be better to have:
# def kernel(v: BufferView[qd.f32]):
def kernel(v: qd.types.buffer_view(qd.f32)):
    for i in range(v.count):
        v[i] = ...  # auto-inserts assertion: 0 <= i < count

TODO: API discussion.

OOB error in debug mode (includes kernel name, thread ID, full callstack):

QuadrantsAssertionError:
BufferView Out Of Range: kernel[kernel] tid=0, got index 16 (offset=0, count=16).
Callstack:
kernel (playground/2_buffer_view_oob.py:13)
  func (playground/2_buffer_view_oob.py:8)

[hughperkins]

Gentle opinion: factorize into 3 separate discussions, one for each feature.

[alanray-tech]

done

[hughperkins]

prefer square brackets for types BufferView[...]

[hughperkins]

I have nothing against any of these proposals.

Am I right in thinking you intend to AI generate the code?

I expect you to give a thorough codereview of the AI-generated code, in the github PR. Keep it in 'draft', whilst you are reviewing it yourself. I expect you to ensure you understand what each line does, and to ask questions to the AI if you don't. I expect you to copy and paste your conversations with the AI into the PR.

Exampless of convestaion:

• [Perf] Tiles 1: _load, _store, _eye_ #466 (review)
• [Perf] Tiles 1: _load, _store, _eye_ #466 (review)
• [Misc] Add cross-platform shuffle #447 (comment)

[alanray-tech]

Square bracket style

To make the square bracket style the preferred API, we could expose a PascalCase alias:

from quadrants.types.ndarray_type import NdarrayType


class BufferViewType:
    """Type annotation for BufferView kernel parameters.
    """

    def __init__(self, dtype=None, boundary="unsafe"):
        self.dtype = dtype
        self.boundary = boundary
        self.ndarray_type = NdarrayType(dtype=dtype, ndim=1, boundary=boundary)

    @classmethod
    def __class_getitem__(cls, args, **kwargs):
        if not isinstance(args, tuple):
            args = (args,)
        return cls(*args, **kwargs)

    def __repr__(self):
        return f"BufferViewType(dtype={self.dtype}, boundary={self.boundary})"

BufferView = BufferViewType

Then the user-facing API becomes:

from quadrants import BufferView

@qd.kernel
def kernel(v: BufferView[qd.f32]):
    for i in range(v.count):
        v[i] *= 2.0

This matches Python's generic conventions (list[int], dict[str, float], Optional[int]).

[hughperkins]

Cool. Quadrants typing is pretty broken right now (there are prs to address this, but I havent got time to review them #411, #412, #413, #414, #415 ...). But would be good to at least strive to go in the right direction I feel.

[alanray-tech]

data = qd.ndarray(qd.f32, shape=(N,))
view = data[0:16]

For the slice based syntax, I'm not sure if we need to support full functionality of slice?
As far as I concern, we only need start and stop, step is somehow meaningless?

What's your idea @duburcqa?

[hughperkins]

speaking for myself, the important thing is that the syntax is intuitive to read.

if it's missing functionalit ythat you don't need, that does not concern me.

[hughperkins]

Note that my tiles pr is highly relevant I feel.

https://github.com/Genesis-Embodied-AI/Genesis/pull/2659/changes

• I add a proxy class,that supports slicing, within quadrants kernels, for these tiles
• I replace creating an instance of a class, with calling .zeros() and .eye()
  (both things requested by Alexis to be clear).

[hughperkins]

(I mean, Alexis didn't request the proxy class; just requested the slicing syntax; and the proxy class was how I implemetned it)

[hughperkins]

(I pointed you at the GEnesi pr, rather than the quadrants pr, since the key thing is the design I feel, which the genesis pr shows. The implementation will be hanlded by your magic AI anyway I assume :) )

[alanray-tech]

Yep I agree, design is much more important.

[hughperkins]

Note: update on PR review:

• leaning towards primairly reviewing design and API (which you are handling in this discussion in fact)
• then I run a bunch of AI speiccalized questions for the most part
• but also skim the tests by hand