tenzr::Array¶

More...

#include <array.h>

Public Functions¶

Detailed Description¶

class tenzr::Array;

The central n-dimensional array type. An Array wraps a lazy expression graph node (or a symbolic tracing handle) and materializes resident data on evaluation.

Public Functions Documentation¶

function Array¶

Array() =default

function Array¶

explicit Array(
    std::shared_ptr< Node > node
)

Parameters:

• node Graph node to reference.

Wrap an existing AST node in an Array handle.

function shape¶

constShape & shape() const

The array's shape.

Return: Reference to the shape.

Shape of the array, whether materialized or symbolic.

function Dtype¶

DType Dtype() const

The array's element type.

Return: The dtype.

Element type of the array.

function Sharding¶

constShardingSpec & Sharding() const

The array's sharding spec.

Return: Reference to the sharding spec.

Sharding attached to the array.

function Shard¶

void Shard(
    ShardingSpec spec
)

Replace the sharding with spec.

Parameters:

• spec Sharding to apply.

Attach a sharding spec to the underlying node.

function Shard¶

void Shard(
    constNamedSharding & ns
)

Replace the sharding with ns.

Parameters:

• ns Named sharding to apply.

Attach a named sharding to the underlying node.

function Layout¶

constStridedLayout & Layout() const

The array's strided layout.

Return: Reference to the layout.

Strides and offset describing the array's memory layout.

function IsContiguous¶

bool IsContiguous() const

Whether the underlying buffer is densely packed.

Return: true when contiguous.

Whether the array's layout is contiguous.

function node¶

inline const std::shared_ptr< Node > & node() const

The backing graph node, or nullptr for a bare array.

function IsDefined¶

inline bool IsDefined() const

Whether the array has backing data or a symbolic handle.

function IsSymbolic¶

inline bool IsSymbolic() const

Whether the array is a symbolic tracing handle.

function SymbolicVarId¶

inline txpr::VarId SymbolicVarId() const

The symbolic tracing handle, when is_symbolic().

function Id¶

inline uint64_t Id() const

The node id, or the symbolic handle id.

function ObtainVarId¶

txpr::VarId ObtainVarId(
    txpr::Txpr * tape
) const

Resolve or allocate this array's variable id on tape.

Parameters:

• tape Active tracing graph.

Return: The variable id representing this array.

Return this array's variable id on tape, materializing a constant or input as needed.

function BindData¶

void BindData(
    std::shared_ptr< PinnedBuffer > buffer
)

Bind buffer as this array's host storage.

Parameters:

• buffer Host buffer to attach.

Bind a host buffer to the underlying variable node.

function Data¶

std::shared_ptr< PinnedBuffer > Data() const

The bound host storage, or nullptr.

Return: The host buffer, or nullptr.

Host buffer bound to the underlying variable, if any.

function HasData¶

bool HasData() const

Whether host storage is bound.

Return: true when host data is present.

Whether a host buffer is bound.

function IsLazy¶

inline bool IsLazy() const

Whether the array has no resident host data.

function BindDeviceData¶

void BindDeviceData(
    std::shared_ptr< DeviceBuffer > buffer
)

Bind buffer as this array's device storage.

Parameters:

• buffer Device buffer to attach.

Bind a device buffer to the underlying variable node.

function DeviceData¶

std::shared_ptr< DeviceBuffer > DeviceData() const

The bound device storage, or nullptr.

Return: The device buffer, or nullptr.

Device buffer bound to the underlying variable, if any.

function HasDeviceData¶

bool HasDeviceData() const

Whether device storage is bound.

Return: true when device data is present.

Whether a device buffer is bound.

function SyncHost¶

void SyncHost() const

Copy device data back into host storage.

Ensure the host buffer is populated from the device buffer.

function SyncDevice¶

void SyncDevice() const

Upload host data to device storage.

Ensure the device buffer reflects the current host data.

function Clone¶

Array Clone() const

Deep-copy the array.

Return: An independent copy.

Deep-copy the array, preserving layout and sharding.

function Eval¶

Array Eval() const

Explicitly triggers graph compilation and execution via the ExecutionEngine, returning a materialized Array with resident data buffer.

Return: A materialized array.

Force evaluation through the execution engine.

function Materialize¶

Array Materialize() const

Return: A materialized array.

Consumption boundary: returns a resident Array for a lazy expression graph, a no-op for an already resident Array, and throws for a symbolic (tracing) Array.

Ensure the array has bound data, evaluating it if necessary.

function Item¶

template <typenameT >
inline T Item() const

The single element of a one-element array, read back as T.

function SetData¶

template <typenameT >
inline void SetData(
    const std::vector< T > & values
)

Copy values into newly allocated host storage; T must match the array dtype.

function ToVector¶

template <typenameT >
inline std::vector< T > ToVector() const

Retrieve array data as a host std::vector. NOTE: If the array represents an un-evaluated lazy computation graph, this triggers synchronous compilation and execution (.eval()) before reading back buffer memory.

function Astype¶

Array Astype(
    DType target_dtype
) const

Convert to target_dtype.

Parameters:

• target_dtype Destination element type.

Return: The converted array.

Convert elements to target_dtype, materializing on the host when data is present.

function ToVectorAs¶

template <typenameT >
inline std::vector< T > ToVectorAs() const

Read the array back as a host vector, converting to the dtype of T first.

function CustomOp¶

Array CustomOp(
    std::string op_name
) const

Apply the registered operator op_name to this array.

Parameters:

• op_name Operation name registered in OpRegistry.

Return: The custom-op array.

Build a unary custom-op node from *this.

function Reshape¶

Array Reshape(
    Shape new_shape
) const

View as new_shape.

Parameters:

• new_shape Target shape with an unchanged element count.

Return: The reshaped array.

Reshape the array, emitting a symbolic node when tracing.

function Flatten¶

Array Flatten() const

1-D row-major view/copy; NumPy flatten/ravel cousins.

Return: Rank-1 array.

Collapse the array to one dimension.

function Ravel¶

Array Ravel() const

1-D row-major copy of the array.

Return: Rank-1 array.

Alias for flatten.

function Transpose¶

Array Transpose(
    int64_t dim0 =-1,
    int64_t dim1 =-2
) const

Swap dimensions dim0 and dim1.

Parameters:

• dim0 First dimension.
• dim1 Second dimension.

Return: The transposed array.

Swap two dimensions.

function Permute¶

Array Permute(
    const std::vector< int64_t > & axes
) const

Reorder dimensions by axes.

Parameters:

• axes Target position of each source dimension.

Return: The permuted view.

Reorder dimensions according to axes.

function Squeeze¶

Array Squeeze(
    std::optional< int64_t > dim =std::nullopt
) const

Remove a length-1 dimension; dim selects one, nullopt removes all.

Parameters:

• dim Optional axis to squeeze; all unit dimensions when empty.

Return: The squeezed array.

Remove unit dimensions.

function Unsqueeze¶

Array Unsqueeze(
    int64_t dim
) const

Insert a length-1 dimension at dim.

Parameters:

• dim Insertion position.

Return: The expanded array.

Insert a unit dimension at dim.

function slice¶

Array slice(
    const std::vector< Slice > & slices
) const

Restrict the array by per-axis slices.

Parameters:

• slices Slice per dimension; trailing dimensions are kept whole.

Return: The sliced view.

Build a strided view for the given per-dimension slices.

function BroadcastTo¶

Array BroadcastTo(
    constShape & target_shape
) const

View broadcast to target_shape.

Parameters:

• target_shape Shape to broadcast to.

Return: The broadcast view.

Broadcast the array to target_shape.

function AsStrided¶

Array AsStrided(
    constShape & shape,
    const std::vector< int64_t > & strides,
    int64_t offset =0
) const

View with explicit shape, strides, and offset.

Parameters:

• target_shape View shape.
• strides Stride per dimension.
• offset Element offset of the first element.

Return: The strided view.

Build an explicit strided view over the existing buffer.

function Contiguous¶

Array Contiguous() const

A contiguous copy of the array, if it is not already contiguous.

Return: A contiguous array, possibly *this.

Materialize a C-contiguous copy when the layout is strided or offset.

function Matmul¶

Array Matmul(
    constArray & other
) const

Matrix multiply with other.

Parameters:

• other Right-hand operand.

Return: The matrix product.

Matrix-multiply with other, supporting batched ranks.

function Relu¶

Array Relu() const

Rectified linear unit.

Return: relu(*this).

Rectified linear unit activation.

function sigmoid¶

Array sigmoid() const

Logistic sigmoid.

Return: sigmoid(*this).

Logistic sigmoid activation.

function tanh¶

Array tanh() const

Hyperbolic tangent.

Return: tanh(*this).

Hyperbolic tangent.

function Exp¶

Array Exp() const

Elementwise exponential.

Return: exp(*this).

Elementwise exponential.

function Log¶

Array Log() const

Elementwise natural logarithm.

Return: log(*this).

Elementwise natural logarithm.

function Abs¶

Array Abs() const

Elementwise absolute value.

Return: |*this|.

Elementwise absolute value.

function Neg¶

Array Neg() const

Elementwise negation.

Return: -*this.

Elementwise negation.

function Sin¶

Array Sin() const

Elementwise sine.

Return: sin(*this).

Elementwise sine.

function Cos¶

Array Cos() const

Elementwise cosine.

Return: cos(*this).

Elementwise cosine.

function Sqrt¶

Array Sqrt() const

Elementwise square root.

Return: sqrt(*this).

Elementwise square root.

function Rsqrt¶

Array Rsqrt() const

Elementwise reciprocal square root.

Return: 1 / sqrt(*this).

Elementwise reciprocal square root.

function Ceil¶

Array Ceil() const

Elementwise ceiling.

Return: ceil(*this).

Elementwise ceiling.

function Floor¶

Array Floor() const

Elementwise floor.

Return: floor(*this).

Elementwise floor.

function Round¶

Array Round() const

Elementwise round to nearest.

Return: round(*this).

Elementwise round-to-nearest.

function Sign¶

Array Sign() const

Elementwise sign.

Return: sign(*this).

Elementwise sign.

function Cbrt¶

Array Cbrt() const

Elementwise cube root.

Return: cbrt(*this).

Elementwise cube root.

function Tan¶

Array Tan() const

Elementwise tangent.

Return: tan(*this).

Elementwise tangent.

function Expm1¶

Array Expm1() const

Elementwise exp(x) - 1.

Return: expm1(*this).

Elementwise exp(x) - 1.

function Log1p¶

Array Log1p() const

Elementwise log(1 + x).

Return: log1p(*this).

Elementwise log(1 + x).

function IsFinite¶

Array IsFinite() const

Elementwise finiteness predicate.

Return: Boolean array that is true for finite values.

Elementwise finiteness test.

function LogicalNot¶

Array LogicalNot() const

Elementwise logical NOT.

Return: Boolean array.

Elementwise logical negation.

function Silu¶

Array Silu() const

Sigmoid linear unit (SiLU/Swish).

Return: x * sigmoid(x).

Sigmoid linear unit activation.

function Gelu¶

Array Gelu() const

Gaussian error linear unit.

Return: gelu(*this).

Gaussian error linear unit activation (tanh approximation).

function Pow¶

Array Pow(
    constArray & other
) const

Elementwise power.

Parameters:

• other Exponent.

Return: *this ** other.

Elementwise exponentiation.

function Remainder¶

Array Remainder(
    constArray & other
) const

Elementwise remainder (a % b).

Parameters:

• other Divisor.

Return: *this % other.

Elementwise remainder.

function Atan2¶

Array Atan2(
    constArray & other
) const

Elementwise two-argument arctangent.

Parameters:

• other Second operand.

Return: atan2(*this, other).

Elementwise two-argument arctangent.

function Minimum¶

Array Minimum(
    constArray & other
) const

Elementwise minimum.

Parameters:

• other Second operand.

Return: Elementwise minimum.

Elementwise minimum.

function Maximum¶

Array Maximum(
    constArray & other
) const

Elementwise maximum.

Parameters:

• other Second operand.

Return: Elementwise maximum.

Elementwise maximum.

function BitwiseAnd¶

Array BitwiseAnd(
    constArray & other
) const

Elementwise bitwise AND.

Parameters:

• other Second operand.

Return: *this & other.

Elementwise bitwise AND.

function BitwiseOr¶

Array BitwiseOr(
    constArray & other
) const

Elementwise bitwise OR.

Parameters:

• other Second operand.

Return: *this | other.

Elementwise bitwise OR.

function BitwiseXor¶

Array BitwiseXor(
    constArray & other
) const

Elementwise bitwise XOR.

Parameters:

• other Second operand.

Return: *this ^ other.

Elementwise bitwise XOR.

function ShiftLeft¶

Array ShiftLeft(
    constArray & other
) const

Elementwise left shift.

Parameters:

• other Shift amount.

Return: *this << other.

Elementwise left shift.

function ShiftRight¶

Array ShiftRight(
    constArray & other
) const

Elementwise arithmetic right shift.

Parameters:

• other Shift amount.

Return: *this >> other.

Elementwise arithmetic right shift.

function Clamp¶

Array Clamp(
    constArray & min,
    constArray & max
) const

Clamp elements into [min, max].

Parameters:

• min Lower bound.
• max Upper bound.

Return: The clamped array.

Clamp elements into [min, max].

function Equal¶

Array Equal(
    constArray & other
) const

Elementwise equality predicate.

Parameters:

• other Second operand.

Return: Boolean array.

Elementwise equality comparison.

function NotEqual¶

Array NotEqual(
    constArray & other
) const

Elementwise inequality predicate.

Parameters:

• other Second operand.

Return: Boolean array.

Elementwise inequality comparison.

function GreaterEqual¶

Array GreaterEqual(
    constArray & other
) const

Elementwise greater-or-equal predicate.

Parameters:

• other Second operand.

Return: Boolean array.

Elementwise greater-than-or-equal comparison.

function GreaterThan¶

Array GreaterThan(
    constArray & other
) const

Elementwise greater-than predicate.

Parameters:

• other Second operand.

Return: Boolean array.

Elementwise greater-than comparison.

function LessEqual¶

Array LessEqual(
    constArray & other
) const

Elementwise less-or-equal predicate.

Parameters:

• other Second operand.

Return: Boolean array.

Elementwise less-than-or-equal comparison.

function LessThan¶

Array LessThan(
    constArray & other
) const

Elementwise less-than predicate.

Parameters:

• other Second operand.

Return: Boolean array.

Elementwise less-than comparison.

function Sum¶

Array Sum(
    std::optional< std::vector< int64_t > > dims =std::nullopt,
    bool keepdims =false
) const

Sum over dims, or all dimensions when nullopt.

Parameters:

• dims Axes to reduce; all when empty.
• keepdims Whether reduced axes are retained.

Return: The reduced array.

Sum over the given axes.

function Mean¶

Array Mean(
    std::optional< std::vector< int64_t > > dims =std::nullopt,
    bool keepdims =false
) const

Arithmetic mean over dims, or all dimensions when nullopt.

Parameters:

• dims Axes to reduce; all when empty.
• keepdims Whether reduced axes are retained.

Return: The reduced array.

Arithmetic mean over the given axes.

function Max¶

Array Max(
    std::optional< std::vector< int64_t > > dims =std::nullopt,
    bool keepdims =false
) const

Maximum over dims, or all dimensions when nullopt.

Parameters:

• dims Axes to reduce; all when empty.
• keepdims Whether reduced axes are retained.

Return: The reduced array.

Maximum over the given axes.

function Min¶

Array Min(
    std::optional< std::vector< int64_t > > dims =std::nullopt,
    bool keepdims =false
) const

Minimum over dims, or all dimensions when nullopt.

Parameters:

• dims Axes to reduce; all when empty.
• keepdims Whether reduced axes are retained.

Return: The reduced array.

Minimum over the given axes.

function Prod¶

Array Prod(
    std::optional< std::vector< int64_t > > dims =std::nullopt,
    bool keepdims =false
) const

Product over dims, or all dimensions when nullopt.

Parameters:

• dims Axes to reduce; all when empty.
• keepdims Whether reduced axes are retained.

Return: The reduced array.

Product over the given axes.

function Var¶

Array Var(
    std::optional< std::vector< int64_t > > dims =std::nullopt,
    bool keepdims =false
) const

Variance over dims, or all dimensions when nullopt.

Parameters:

• dims Axes to reduce; all when empty.
• keepdims Whether reduced axes are retained.

Return: The reduced array.

Variance over the given axes.

function StdDev¶

Array StdDev(
    std::optional< std::vector< int64_t > > dims =std::nullopt,
    bool keepdims =false
) const

Standard deviation over dims, or all dimensions when nullopt.

Parameters:

• dims Axes to reduce; all when empty.
• keepdims Whether reduced axes are retained.

Return: The reduced array.

Standard deviation over the given axes.

function operator+¶

Array operator+(
    constArray & other
) const

function operator*¶

Array operator*(
    constArray & other
) const

function operator-¶

Array operator-(
    constArray & other
) const

function operator/¶

Array operator/(
    constArray & other
) const

function operator==¶

Array operator==(
    constArray & other
) const

function operator!=¶

Array operator!=(
    constArray & other
) const

function operator<¶

Array operator<(
    constArray & other
) const

function operator<=¶

Array operator<=(
    constArray & other
) const

function operator>¶

Array operator>(
    constArray & other
) const

function operator>=¶

Array operator>=(
    constArray & other
) const

function ToString¶

std::string ToString() const

Human-readable summary of the array.

Return: Human-readable summary.

Short description of the array's node, shape, and dtype.

function Parameter¶

static Array Parameter(
    Shape shape,
    DType dtype =DType::kFloat32,
    std::string name =""
)

Create a trainable parameter leaf with optional name.

Parameters:

• shape Parameter shape.
• dtype Parameter dtype.
• name Optional debug name.

Return: The new array.

Create an uninitialized parameter (leaf) array.

function Constant¶

static Array Constant(
    const std::vector< float > & data,
    Shape shape
)

Create a constant array by copying data.

Parameters:

• data Element values.
• shape Result shape.

Return: The new constant array.

Create a kFloat32 constant holding data.

function Zeros¶

static Array Zeros(
    Shape shape,
    DType dtype =DType::kFloat32
)

Create a zero-filled array.

Parameters:

• shape Target shape.
• dtype Element type.

Return: The new array.

Create a zero-filled array.

function Ones¶

static Array Ones(
    Shape shape,
    DType dtype =DType::kFloat32
)

Create a one-filled array.

Parameters:

• shape Target shape.
• dtype Element type.

Return: The new array.

Create a one-filled array.

function Full¶

static Array Full(
    Shape shape,
    double value,
    DType dtype =DType::kFloat32
)

Create an array filled with value.

Parameters:

• shape Target shape.
• value Fill value.
• dtype Element type.

Return: The new array.

Create an array filled with value, emitting a constant node when tracing.

function Symbolic¶

static inline Array Symbolic(
    txpr::VarId vid,
    Shape shape,
    DType dtype
)

Create a symbolic array bound to tracing variable vid.

function FromVector¶

template <typenameT >
static inline Array FromVector(
    const std::vector< T > & data,
    Shape shape
)

Create an array of shape from data, using the dtype of T.

function CustomOp¶

static Array CustomOp(
    std::string op_name,
    std::vector< Array > inputs
)

Apply the registered operator op_name to inputs.

Parameters:

• op_name Operation name registered in OpRegistry.
• inputs Input arrays.

Return: The custom-op array.

Build a custom-op node from named inputs, promoting binary operands.