oa::Matrix

A multidimensional semantic value backed by OA-managed storage. A matrix carries shape, element stride, dtype, device, byte-offset, and optional autograd metadata. Copying a matrix shares its storage and autograd state. Metadata-only views also alias storage; use `clone()` when independent storage is required. Matrix operations use OA's Vulkan execution path. Direct host observation is an explicit synchronization boundary, not a CPU compute fallback. Stateful device ownership remains with `oa::Engine`; a matrix only retains the storage required for its value and recorded graph lifetime.

ClC++ public headers

Public Methods

void oa::Matrix::accumulateGrad(const Matrix & inContribution)

const Matrix & oa::Matrix::asMatrixView()

oa::F32 oa::Matrix::at(oa::I64 inIdx)

oa::U64 oa::Matrix::byteOffset()

oa::I64 oa::Matrix::byteSize()

Matrix oa::Matrix::clone()

Matrix oa::Matrix::contiguous()

void oa::Matrix::copyFrom(const Matrix & inOther)

oa::U64 oa::Matrix::currentStorageMutationVersion()

const void * oa::Matrix::data()

void * oa::Matrix::data()

T * oa::Matrix::dataAs()

const T * oa::Matrix::dataAs()

void oa::Matrix::detachForGradAttach(bool inRequiresGrad)

Matrix oa::Matrix::flatten()

oa::Device oa::Matrix::getDevice()

oa::ScalarType oa::Matrix::getDtype()

oa::SharedPtr<GradNode> oa::Matrix::getGradFn()

oa::MemoryPlacement oa::Matrix::getMemoryPlacement()

MatrixShape oa::Matrix::getShape()

const Stride & oa::Matrix::getStride()

Matrix oa::Matrix::gradMatrix()

bool oa::Matrix::hasStorage()

oa::I32 oa::Matrix::heapSlot()

MemoryBlock oa::Matrix::hostBlock()

bool oa::Matrix::isEmpty()

bool oa::Matrix::isHostAccessible()

bool oa::Matrix::isLeaf()

bool oa::Matrix::isOnDevice()

oa::F32 oa::Matrix::item()

void oa::Matrix::markStorageMutation()

AutogradMeta & oa::Matrix::mutAutograd()

Matrix & oa::Matrix::mutGradMatrix()

oa::I64 oa::Matrix::numElements()

oa::U64 oa::Matrix::observeStorageMutationVersion()

Matrix oa::Matrix::operator*(const Matrix & inOther)

Matrix oa::Matrix::operator*(oa::F32 inScalar)

Matrix & oa::Matrix::operator*=(const Matrix & inOther)

Matrix & oa::Matrix::operator*=(oa::F32 inScalar)

Matrix oa::Matrix::operator+(const Matrix & inOther)

Matrix oa::Matrix::operator+(oa::F32 inScalar)

Matrix & oa::Matrix::operator+=(const Matrix & inOther)

Matrix & oa::Matrix::operator+=(oa::F32 inScalar)

Matrix oa::Matrix::operator-()

Matrix oa::Matrix::operator-(const Matrix & inOther)

Matrix oa::Matrix::operator-(oa::F32 inScalar)

Matrix & oa::Matrix::operator-=(const Matrix & inOther)

Matrix & oa::Matrix::operator-=(oa::F32 inScalar)

Matrix oa::Matrix::operator/(const Matrix & inOther)

Matrix oa::Matrix::operator/(oa::F32 inScalar)

Matrix & oa::Matrix::operator/=(const Matrix & inOther)

Matrix & oa::Matrix::operator/=(oa::F32 inScalar)

Matrix oa::Matrix::permute(oa::Span<const oa::I32> inDims)

oa::I32 oa::Matrix::rank()

bool oa::Matrix::requiresGrad()

Matrix oa::Matrix::reshape(MatrixShape inNewShape)

void oa::Matrix::set(oa::I64 inIdx, oa::F32 inValue)

void oa::Matrix::setRequiresGrad(bool inValue)

oa::I64 oa::Matrix::size(oa::I32 inDim)

Matrix oa::Matrix::squeeze(oa::I32 inDim)

Matrix oa::Matrix::transpose(oa::I32 inDim0, oa::I32 inDim1)

Matrix oa::Matrix::unsqueeze(oa::I32 inDim)

Matrix oa::Matrix::view(MatrixShape inNewShape)

void oa::Matrix::zero()

void oa::Matrix::zeroGrad()

Constructor & Destructor Documentation

oa::Matrix::Matrix()

Construct an empty matrix without storage.

oa::Matrix::Matrix(
	MatrixShape inShape,
	oa::F32 inFillValue,
	oa::ScalarType inDtype = oa::ScalarType::Float32
)

Allocate and fill a matrix through `oa::FnMatrix::full`.

Parameters

inShape

MatrixShape

Logical dimensions of the matrix.

inFillValue

oa::F32

Value written to every element.

inDtype

oa::ScalarType

Scalar representation used by the allocation.

void oa::Matrix::~Matrix()

Release this value's references without submitting or waiting for work.

Public Method Documentation

void oa::Matrix::accumulateGrad(
	const Matrix & inContribution
)

Defer addition of one contribution into this leaf's gradient accumulator.

Parameters

inContribution

const Matrix &

Gradient contribution with a compatible element count.

Returns

void

The declared return value.

const Matrix & oa::Matrix::asMatrixView()

Synchronize cached descriptors and return this matrix as a const view.

Returns

const Matrix &

The declared return value.

oa::F32 oa::Matrix::at(
	oa::I64 inIdx
)

Read one logical flat element as FP32. This host observation submits and waits for recorded work when required and performs device readback when storage is not host-accessible.

Parameters

inIdx

oa::I64

Row-major logical flat index. It must be in range.

Returns

oa::F32

The selected value converted to FP32.

oa::U64 oa::Matrix::byteOffset()

Return this view's byte offset within shared storage.

Returns

oa::U64

The declared return value.

oa::I64 oa::Matrix::byteSize()

Return the logical element count multiplied by the scalar size in bytes.

Returns

oa::I64

The declared return value.

Matrix oa::Matrix::clone()

Copy this matrix into independent storage through `oa::FnMatrix::copy`.

Returns

Matrix

The independent copy, or an empty matrix when this matrix is empty.

Matrix oa::Matrix::contiguous()

Return an independently stored row-major matrix with the same values. The current non-row-major path may cross a host-access boundary while materializing the result.

Returns

Matrix

A contiguous copy, or an empty matrix when allocation fails.

void oa::Matrix::copyFrom(
	const Matrix & inOther
)

Record a copy or dtype conversion into existing destination storage. Both matrices must have storage and compatible element counts. Missing storage leaves this matrix unchanged.

Parameters

inOther

const Matrix &

Source values to copy.

Returns

void

The declared return value.

oa::U64 oa::Matrix::currentStorageMutationVersion()

Return the current shared saved-value mutation version.

Returns

oa::U64

The declared return value.

const void * oa::Matrix::data()

Return a read-only pointer when this matrix is host-accessible. This function does not make a device-only allocation host-visible and does not synchronize recorded GPU work.

Returns

const void *

Pointer to this view's first byte, or `nullptr` when inaccessible.

void * oa::Matrix::data()

Return a writable pointer when this matrix is host-accessible. This function does not make a device-only allocation host-visible and does not synchronize recorded GPU work.

Returns

void *

Pointer to this view's first byte, or `nullptr` when inaccessible.

T * oa::Matrix::dataAs()

Return `data()` cast to the requested element type.

Returns

T *

The declared return value.

const T * oa::Matrix::dataAs()

Return const `data()` cast to the requested element type.

Returns

const T *

The declared return value.

void oa::Matrix::detachForGradAttach(
	bool inRequiresGrad
)

Replace shared autograd metadata before attaching a producer node.

Parameters

inRequiresGrad

bool

Initial tracking state for the detached metadata.

Returns

void

The declared return value.

Matrix oa::Matrix::flatten()

Return a one-dimensional storage-sharing view.

Returns

Matrix

The declared return value.

oa::Device oa::Matrix::getDevice()

Return the device identity associated with this matrix.

Returns

oa::Device

The declared return value.

oa::ScalarType oa::Matrix::getDtype()

Return the scalar dtype stored by this matrix.

Returns

oa::ScalarType

The declared return value.

oa::SharedPtr<GradNode> oa::Matrix::getGradFn()

Return the producing gradient node, or `nullptr` for a leaf.

Returns

oa::SharedPtr<GradNode>

The declared return value.

oa::MemoryPlacement oa::Matrix::getMemoryPlacement()

Return the allocation's current memory-placement policy.

Returns

oa::MemoryPlacement

The declared return value.

MatrixShape oa::Matrix::getShape()

Return the logical shape descriptor.

Returns

MatrixShape

The declared return value.

const Stride & oa::Matrix::getStride()

Return the element-stride descriptor.

Returns

const Stride &

The declared return value.

Matrix oa::Matrix::gradMatrix()

Return the persistent gradient accumulator, or an empty matrix when absent.

Returns

Matrix

The declared return value.

bool oa::Matrix::hasStorage()

Return whether this value has a non-empty shape and live backing storage.

Returns

bool

The declared return value.

oa::I32 oa::Matrix::heapSlot()

Return the current runtime bindless slot, or `-1` when none is bound.

Returns

oa::I32

The declared return value.

MemoryBlock oa::Matrix::hostBlock()

Return the current host-visible span, or an empty span when inaccessible.

Returns

MemoryBlock

The declared return value.

bool oa::Matrix::isEmpty()

Return whether this value has no usable backing storage.

Returns

bool

The declared return value.

bool oa::Matrix::isHostAccessible()

Return whether `data()` exposes this matrix directly to the host.

Returns

bool

The declared return value.

bool oa::Matrix::isLeaf()

Return whether this matrix has no producing gradient node.

Returns

bool

The declared return value.

bool oa::Matrix::isOnDevice()

Return whether this matrix currently has a device bindless slot.

Returns

bool

The declared return value.

oa::F32 oa::Matrix::item()

Read a single-element matrix as FP32. This host observation submits and waits for recorded work when required. The matrix must contain exactly one element.

Returns

oa::F32

The scalar value converted to FP32.

void oa::Matrix::markStorageMutation()

Advance the shared mutation version after an in-place write.

Returns

void

The declared return value.

AutogradMeta & oa::Matrix::mutAutograd()

Return mutable autograd metadata, allocating it on first access.

Returns

AutogradMeta &

The declared return value.

Matrix & oa::Matrix::mutGradMatrix()

Return the persistent gradient accumulator, allocating it when absent.

Returns

Matrix &

The declared return value.

oa::I64 oa::Matrix::numElements()

Return the product of all logical dimensions.

Returns

oa::I64

The declared return value.

oa::U64 oa::Matrix::observeStorageMutationVersion()

Observe and initialize the shared saved-value mutation version.

Returns

oa::U64

The declared return value.

Matrix oa::Matrix::operator*(
	const Matrix & inOther
)

Return the element-wise product; this operator is not matrix multiplication.

Parameters

inOther

const Matrix &

—

Returns

Matrix

The declared return value.

Matrix oa::Matrix::operator*(
	oa::F32 inScalar
)

Return this matrix with every element multiplied by a scalar.

Parameters

inScalar

oa::F32

—

Returns

Matrix

The declared return value.

Matrix & oa::Matrix::operator*=(
	const Matrix & inOther
)

Multiply this storage by a broadcast-compatible matrix in place.

Parameters

inOther

const Matrix &

—

Returns

Matrix &

The declared return value.

Matrix & oa::Matrix::operator*=(
	oa::F32 inScalar
)

Multiply every element of this storage by a scalar in place.

Parameters

inScalar

oa::F32

—

Returns

Matrix &

The declared return value.

Matrix oa::Matrix::operator+(
	const Matrix & inOther
)

Return the element-wise sum using `oa::FnMatrix` broadcasting rules.

Parameters

inOther

const Matrix &

—

Returns

Matrix

The declared return value.

Matrix oa::Matrix::operator+(
	oa::F32 inScalar
)

Return this matrix with a scalar added to every element.

Parameters

inScalar

oa::F32

—

Returns

Matrix

The declared return value.

Matrix & oa::Matrix::operator+=(
	const Matrix & inOther
)

Add a broadcast-compatible matrix into this storage in place.

Parameters

inOther

const Matrix &

—

Returns

Matrix &

The declared return value.

Matrix & oa::Matrix::operator+=(
	oa::F32 inScalar
)

Add a scalar to every element of this storage in place.

Parameters

inScalar

oa::F32

—

Returns

Matrix &

The declared return value.

Matrix oa::Matrix::operator-()

Return the element-wise negation of this matrix.

Returns

Matrix

The declared return value.

Matrix oa::Matrix::operator-(
	const Matrix & inOther
)

Return the element-wise difference using `oa::FnMatrix` broadcasting rules.

Parameters

inOther

const Matrix &

—

Returns

Matrix

The declared return value.

Matrix oa::Matrix::operator-(
	oa::F32 inScalar
)

Return this matrix with a scalar subtracted from every element.

Parameters

inScalar

oa::F32

—

Returns

Matrix

The declared return value.

Matrix & oa::Matrix::operator-=(
	const Matrix & inOther
)

Subtract a broadcast-compatible matrix from this storage in place.

Parameters

inOther

const Matrix &

—

Returns

Matrix &

The declared return value.

Matrix & oa::Matrix::operator-=(
	oa::F32 inScalar
)

Subtract a scalar from every element of this storage in place.

Parameters

inScalar

oa::F32

—

Returns

Matrix &

The declared return value.

Matrix oa::Matrix::operator/(
	const Matrix & inOther
)

Return the element-wise quotient using `oa::FnMatrix` broadcasting rules.

Parameters

inOther

const Matrix &

—

Returns

Matrix

The declared return value.

Matrix oa::Matrix::operator/(
	oa::F32 inScalar
)

Return this matrix with every element divided by a scalar.

Parameters

inScalar

oa::F32

—

Returns

Matrix

The declared return value.

Matrix & oa::Matrix::operator/=(
	const Matrix & inOther
)

Divide this storage by a broadcast-compatible matrix in place.

Parameters

inOther

const Matrix &

—

Returns

Matrix &

The declared return value.

Matrix & oa::Matrix::operator/=(
	oa::F32 inScalar
)

Divide every element of this storage by a scalar in place.

Parameters

inScalar

oa::F32

—

Returns

Matrix &

The declared return value.

Matrix oa::Matrix::permute(
	oa::Span<const oa::I32> inDims
)

Reorder dimensions and element strides without copying storage. Negative dimension indices are accepted. Every source dimension must occur exactly once.

Parameters

inDims

oa::Span<const oa::I32>

Source dimension for every output dimension.

Returns

Matrix

A strided storage-sharing view; an empty matrix for an invalid permutation, or this matrix unchanged when the rank does not match.

oa::I32 oa::Matrix::rank()

Return the number of logical dimensions.

Returns

oa::I32

The declared return value.

bool oa::Matrix::requiresGrad()

Return whether this matrix participates in autograd.

Returns

bool

The declared return value.

Matrix oa::Matrix::reshape(
	MatrixShape inNewShape
)

Create a storage-sharing view with a new shape. This method currently has the same row-major element-count contract as `view()` and does not materialize a copy.

Parameters

inNewShape

MatrixShape

Logical shape of the returned view.

Returns

Matrix

The storage-sharing view, or an empty matrix on count mismatch.

void oa::Matrix::set(
	oa::I64 inIdx,
	oa::F32 inValue
)

Write one logical flat element from FP32. The index must be in range. Device-only storage uses an explicit upload after completing prior recorded work.

Parameters

inIdx

oa::I64

Row-major logical flat index to update.

inValue

oa::F32

Value converted to the matrix dtype and written.

Returns

void

The declared return value.

void oa::Matrix::setRequiresGrad(
	bool inValue
)

Enable or disable leaf-gradient tracking. Enabling tracking lazily allocates a persistent gradient accumulator. Disabling it preserves allocated gradient storage for reuse.

Parameters

inValue

bool

Whether this leaf should accumulate gradients.

Returns

void

The declared return value.

oa::I64 oa::Matrix::size(
	oa::I32 inDim
)

Return the size of one logical dimension. Negative indices count from the final dimension, so `-1` names the last dimension. The resolved index must be in range.

Parameters

inDim

oa::I32

Dimension index to query.

Returns

oa::I64

Number of elements along the resolved dimension.

Matrix oa::Matrix::squeeze(
	oa::I32 inDim
)

Remove one size-one dimension without copying storage.

Parameters

inDim

oa::I32

Dimension to remove.

Returns

Matrix

A storage-sharing view, or this matrix unchanged when the dimension is invalid or is not size one.

Matrix oa::Matrix::transpose(
	oa::I32 inDim0,
	oa::I32 inDim1
)

Exchange two dimensions through the canonical matrix operation path.

Parameters

inDim0

oa::I32

First dimension to exchange.

inDim1

oa::I32

Second dimension to exchange.

Returns

Matrix

A matrix with the requested dimensions exchanged.

Matrix oa::Matrix::unsqueeze(
	oa::I32 inDim
)

Insert a size-one dimension without copying storage.

Parameters

inDim

oa::I32

Position of the inserted dimension.

Returns

Matrix

A storage-sharing view with rank increased by one.

Matrix oa::Matrix::view(
	MatrixShape inNewShape
)

Create a metadata-only row-major view with a new shape. The new shape must contain exactly the same number of elements. The returned matrix shares storage and byte offset with this matrix.

Parameters

inNewShape

MatrixShape

Logical shape of the returned view.

Returns

Matrix

The storage-sharing view, or an empty matrix on count mismatch.

void oa::Matrix::zero()

Set every element to zero through the placement-appropriate path.

Returns

void

The declared return value.

void oa::Matrix::zeroGrad()

Record a zero fill for the persistent gradient accumulator when present.

Returns

void

The declared return value.