collections

Modules:

• array –
• array_primitives –
• list –

Classes:

• ArrayPrimitiveTypeSpec –
• NDArrayLayout –
• NDArrayOrder –

Functions:

• list_element_type –
• list_has_concrete_element_type –
• ndarray_byte_bounds –
• ndarray_default_strides –
• ndarray_element_count –
• ndarray_element_size_bytes –
• ndarray_element_size_bytes_from_dtype –
• ndarray_is_c_contiguous –
• ndarray_is_f_contiguous –
• ndarray_primitive_type_name –
• validate_ndarray_layout –

ArrayPrimitiveTypeSpec dataclass

ArrayPrimitiveTypeSpec(
    name: str,
    type_id: int,
    dtype_token: int,
    element_size_bytes: int | None,
    buffer_view_compatible: bool,
)

NDArrayLayout dataclass

NDArrayLayout(
    shape: tuple[int, ...],
    strides: tuple[int, ...],
    offset_bytes: int = 0,
)

Represent the logical rank, shape, strides, and byte offset of one NDArray value without duplicating the lower-level storage machinery. attributes: shape: type: tuple[int, Ellipsis] strides: type: tuple[int, Ellipsis] offset_bytes: type: int

Attributes:

• ndim (int) –

ndim property

ndim: int

NDArrayOrder

Bases: str, Enum

list_element_type

list_element_type(
    type_: DataType | None,
) -> DataType | None

Source code in src/irx/builtins/collections/list.py

@typechecked
def list_element_type(type_: astx.DataType | None) -> astx.DataType | None:
    """
    title: Return one concrete list element type when available.
    parameters:
      type_:
        type: astx.DataType | None
    returns:
      type: astx.DataType | None
    """
    if not isinstance(type_, astx.ListType):
        return None
    if len(type_.element_types) != 1:
        return None
    element_type = type_.element_types[0]
    return element_type if isinstance(element_type, astx.DataType) else None

list_has_concrete_element_type

list_has_concrete_element_type(
    type_: DataType | None,
) -> bool

Source code in src/irx/builtins/collections/list.py

@typechecked
def list_has_concrete_element_type(type_: astx.DataType | None) -> bool:
    """
    title: Return whether one list type has a single concrete element type.
    parameters:
      type_:
        type: astx.DataType | None
    returns:
      type: bool
    """
    return list_element_type(type_) is not None

ndarray_byte_bounds

ndarray_byte_bounds(
    layout: NDArrayLayout,
) -> tuple[int, int] | None

The result is relative to the underlying data pointer. None means the logical layout has zero extent and therefore addresses no elements. parameters: layout: type: NDArrayLayout returns: type: tuple[int, int] | None

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def ndarray_byte_bounds(
    layout: NDArrayLayout,
) -> tuple[int, int] | None:
    """
    title: Return the minimum and maximum element-start byte offsets.
    summary: >-
      The result is relative to the underlying data pointer. None means the
      logical layout has zero extent and therefore addresses no elements.
    parameters:
      layout:
        type: NDArrayLayout
    returns:
      type: tuple[int, int] | None
    """
    if ndarray_element_count(layout) == 0:
        return None

    minimum = layout.offset_bytes
    maximum = layout.offset_bytes

    for dim, stride in zip(layout.shape, layout.strides, strict=True):
        if dim <= 1:
            continue
        span = (dim - 1) * stride
        if span < 0:
            minimum += span
        else:
            maximum += span

    return minimum, maximum

ndarray_default_strides

ndarray_default_strides(
    shape: tuple[int, ...],
    item_size_bytes: int,
    *,
    order: NDArrayOrder = C,
) -> tuple[int, ...]

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def ndarray_default_strides(
    shape: tuple[int, ...],
    item_size_bytes: int,
    *,
    order: NDArrayOrder = NDArrayOrder.C,
) -> tuple[int, ...]:
    """
    title: Return canonical byte strides for one contiguous NDArray shape.
    parameters:
      shape:
        type: tuple[int, Ellipsis]
      item_size_bytes:
        type: int
      order:
        type: NDArrayOrder
    returns:
      type: tuple[int, Ellipsis]
    """
    if item_size_bytes <= 0:
        raise ValueError("ndarray item_size_bytes must be positive")
    if not shape:
        return ()

    strides = [0] * len(shape)
    stride = item_size_bytes

    if order is NDArrayOrder.C:
        indices = range(len(shape) - 1, -1, -1)
    else:
        indices = range(len(shape))

    for axis in indices:
        strides[axis] = stride
        stride *= max(shape[axis], 1)

    return tuple(strides)

ndarray_element_count

ndarray_element_count(layout: NDArrayLayout) -> int

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def ndarray_element_count(layout: NDArrayLayout) -> int:
    """
    title: Return the logical element count for one layout.
    parameters:
      layout:
        type: NDArrayLayout
    returns:
      type: int
    """
    return _shape_extent(layout.shape)

ndarray_element_size_bytes

ndarray_element_size_bytes(
    type_: DataType | None,
) -> int | None

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def ndarray_element_size_bytes(type_: astx.DataType | None) -> int | None:
    """
    title: Return the byte width for one NDArray element type.
    parameters:
      type_:
        type: astx.DataType | None
    returns:
      type: int | None
    """
    primitive_name = ndarray_primitive_type_name(type_)
    if primitive_name is None:
        return None
    spec = ARRAY_PRIMITIVE_TYPE_SPECS.get(primitive_name)
    if spec is None:
        return None
    return spec.element_size_bytes

ndarray_element_size_bytes_from_dtype

ndarray_element_size_bytes_from_dtype(
    dtype: BufferHandle,
) -> int | None

Source code in src/irx/builtins/collections/array.py

@typechecked
def ndarray_element_size_bytes_from_dtype(dtype: BufferHandle) -> int | None:
    """
    title: Return the byte width for one canonical primitive dtype handle.
    parameters:
      dtype:
        type: BufferHandle
    returns:
      type: int | None
    """
    if dtype.is_null:
        return None
    return _DTYPE_ELEMENT_SIZE_BYTES.get(dtype)

ndarray_is_c_contiguous

ndarray_is_c_contiguous(
    layout: NDArrayLayout, item_size_bytes: int
) -> bool

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def ndarray_is_c_contiguous(
    layout: NDArrayLayout,
    item_size_bytes: int,
) -> bool:
    """
    title: Return whether one layout matches canonical C-order strides.
    parameters:
      layout:
        type: NDArrayLayout
      item_size_bytes:
        type: int
    returns:
      type: bool
    """
    return layout.strides == ndarray_default_strides(
        layout.shape,
        item_size_bytes,
        order=NDArrayOrder.C,
    )

ndarray_is_f_contiguous

ndarray_is_f_contiguous(
    layout: NDArrayLayout, item_size_bytes: int
) -> bool

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def ndarray_is_f_contiguous(
    layout: NDArrayLayout,
    item_size_bytes: int,
) -> bool:
    """
    title: Return whether one layout matches canonical Fortran-order strides.
    parameters:
      layout:
        type: NDArrayLayout
      item_size_bytes:
        type: int
    returns:
      type: bool
    """
    return layout.strides == ndarray_default_strides(
        layout.shape,
        item_size_bytes,
        order=NDArrayOrder.F,
    )

ndarray_primitive_type_name

ndarray_primitive_type_name(
    type_: DataType | None,
) -> str | None

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def ndarray_primitive_type_name(type_: astx.DataType | None) -> str | None:
    """
    title: Return the builtin primitive storage name for one NDArray element.
    parameters:
      type_:
        type: astx.DataType | None
    returns:
      type: str | None
    """
    if isinstance(type_, astx.Boolean):
        return "bool"
    if isinstance(type_, astx.Int8):
        return "int8"
    if isinstance(type_, astx.Int16):
        return "int16"
    if isinstance(type_, astx.Int32):
        return "int32"
    if isinstance(type_, astx.Int64):
        return "int64"
    if isinstance(type_, astx.UInt8):
        return "uint8"
    if isinstance(type_, astx.UInt16):
        return "uint16"
    if isinstance(type_, astx.UInt32):
        return "uint32"
    if isinstance(type_, astx.UInt64):
        return "uint64"
    if isinstance(type_, astx.Float32):
        return "float32"
    if isinstance(type_, astx.Float64):
        return "float64"
    return None

validate_ndarray_layout

validate_ndarray_layout(
    layout: NDArrayLayout,
) -> tuple[str, ...]

Source code in src/irx/builtins/collections/array.py

@public
@typechecked
def validate_ndarray_layout(
    layout: NDArrayLayout,
) -> tuple[str, ...]:
    """
    title: Validate one static NDArray layout.
    parameters:
      layout:
        type: NDArrayLayout
    returns:
      type: tuple[str, Ellipsis]
    """
    errors: list[str] = []

    if len(layout.strides) != layout.ndim:
        errors.append("ndarray stride length must match ndim")
    if any(dim < 0 for dim in layout.shape):
        errors.append("ndarray shape dimensions must be non-negative")
    if layout.offset_bytes < 0:
        errors.append("ndarray offset_bytes must be non-negative")

    return tuple(errors)