Tensor¶

class Tensor¶

Reference-counted, device-aware N-dimensional array.

The runtime’s tensor type: a typed, strided view onto a block of memory on a specific Device (CPU, CUDA, or HIP), shared through reference counting so copying a Tensor is cheap. Compute-graph values, matrix element results, trainable globals and event data all flow through this type. From Python a Tensor is only ever obtained from another madspace call, never constructed directly; it exports itself through the __dlpack__ / __dlpack_device__ protocol so it converts to a NumPy array or a PyTorch tensor without copying.

Public Functions

inline Tensor()¶: Empty tensor holding no storage.

inline Tensor(const Tensor &other)¶: Shares other’s storage.

inline Tensor(Tensor &&other) noexcept¶: Takes ownership of other’s storage, leaving it empty.

inline Tensor(DataType dtype, const Sizes &shape, AllocHint hint = AllocHint::normal)¶: Allocates a new tensor of dtype and shape on the CPU.

inline Tensor(DataType dtype, const Sizes &shape, DevicePtr device, AllocHint hint = AllocHint::normal)¶: Allocates a new tensor of dtype and shape on device.

template<typename D> inline Tensor(DataType dtype, const Sizes &shape, const D &device, AllocHint hint = AllocHint::normal)¶: Same as above, statically dispatched to a compile-time device type.

inline Tensor(DataType dtype, const Sizes &shape, void *data, std::function<void()> external_reset)¶: Wraps externally-owned CPU memory; external_reset runs when the last reference is dropped, instead of freeing data.

inline Tensor(DataType dtype, const Sizes &shape, DevicePtr device, void *data, std::function<void()> external_reset)¶: Wraps externally-owned memory on device; see the CPU overload above.

inline Tensor(DataType dtype, const Sizes &shape, const Sizes &stride, DevicePtr device, void *data, std::function<void()> external_reset, std::optional<std::uintptr_t> stream = std::nullopt)¶: Wraps externally-owned memory with an explicit stride, for a non-contiguous view onto existing data, ordered on stream if given.

inline Tensor(const SizeVec &batch_sizes)¶: A DataType::batch_sizes tensor holding literal per-channel batch sizes.

template<ScalarType T> inline Tensor(T value, DevicePtr device, AllocHint hint = AllocHint::normal)¶: Single-value tensor holding value, allocated on device.

template<ScalarType T, typename D> inline Tensor(T value, const D &device, AllocHint hint = AllocHint::normal)¶

inline Tensor(TensorValue value, DevicePtr device, AllocHint hint = AllocHint::normal)¶: Tensor built from a literal TensorValue (nested int/float data).

inline ~Tensor()¶: Releases this reference; frees the storage once the last one drops.

inline Tensor &operator=(const Tensor &other)¶: Shares the assigned tensor’s storage, releasing the previous one.

inline Tensor &operator=(Tensor &&other) noexcept¶: Takes ownership of the assigned tensor’s storage.

inline operator bool() const¶: Whether this tensor holds any storage.

template<class T, int dim> inline TensorView<T, dim> view()¶: Typed, dimension-checked view onto the data for direct element access.

template<class T, int dim> inline const TensorView<T, dim> view() const¶: Typed, dimension-checked view onto the data for direct element access.

template<class T, int dim> inline PackedTensorView<T, dim> flat_view(std::size_t flatten_count) const¶: Like view, with the leading flatten_count dimensions merged into one.

inline void *data()¶: Raw pointer to the underlying storage.

inline void *data() const¶: Raw pointer to the underlying storage.

inline const Sizes &shape() const¶: Size of each dimension.

inline const Sizes &stride() const¶: Element stride of each dimension.

inline std::size_t size(std::size_t i) const¶: Size of dimension i.

inline DataType dtype() const¶: Element type.

inline const SizeVec &batch_sizes() const¶: Per-channel batch sizes, for a DataType::batch_sizes tensor.

inline DevicePtr device() const¶: The device this tensor’s storage lives on.

inline std::optional<std::uintptr_t> stream() const¶: The GPU stream the storage is ordered on, if known.

inline void set_stream(std::optional<std::uintptr_t> stream)¶: Set the stream returned by stream, if the storage is stream-ordered.

inline std::size_t index_value() const¶: The single integer value of a scalar DataType::batch_sizes tensor.

inline std::size_t dtype_size() const¶: Size in bytes of one element.

inline std::size_t byte_size() const¶: Total size in bytes of the storage.

inline void reset()¶: Releases this reference; the tensor is empty afterwards.

template<typename D> inline void reset(const D &device)¶: Releases this reference on device; the tensor is empty afterwards.

inline void reset_on_stream(std::optional<std::uintptr_t> stream)¶: Releases this reference, freeing stream-ordered storage on stream or, if unknown, on the device’s default free stream.

Tensor select(std::size_t axis, std::size_t index) const¶: A single index along axis, dropping that dimension.

Tensor slice(std::size_t axis, std::size_t start, std::size_t stop) const¶: A contiguous range [start, stop) along axis.

std::vector<Tensor> split(std::size_t axis, const SizeVec &sizes) const¶: Splits axis into consecutive chunks of the given sizes.

std::vector<Tensor> unstack(std::size_t axis) const¶: Splits axis into one tensor per index, dropping that dimension.

Tensor unsqueeze(std::size_t axis) const¶: Inserts a size-1 dimension at axis.

Tensor expand(const Sizes &shape) const¶: Broadcasts size-1 dimensions to shape, without copying.

Tensor reshape(const Sizes &shape) const¶: A view with a different shape over the same elements.

Tensor factor_dim(std::size_t axis, std::size_t factor)¶: Splits dimension axis into two, the second of size factor.

std::vector<Tensor> split_and_reshape(const std::vector<Sizes> &shapes) const¶: Splits along the batch dimension and reshapes each piece.

template<typename D> inline Tensor cpu(const D &device) const¶: A copy of this tensor on the CPU, allocated through device, or *this if it is already there.

inline Tensor cpu() const¶: A copy of this tensor on the CPU, or *this if it is already there.

template<typename D> inline void zero(const D &device)¶: Sets every element to zero.

inline void zero()¶: Sets every element to zero.

template<typename D> inline void copy_from(const Tensor &source, const D &device)¶: Copies source’s data into this tensor’s storage.

inline void copy_from(const Tensor &source)¶: Copies source’s data into this tensor’s storage.

template<typename D> inline void add(const Tensor &source, const D &device)¶: Adds source into this tensor element-wise.

inline void add(const Tensor &source)¶: Adds source into this tensor element-wise.

template<typename D> inline Tensor copy(const D &device, AllocHint hint = AllocHint::normal) const¶: An independent copy of this tensor, allocated through device.

inline Tensor copy(AllocHint hint = AllocHint::normal) const¶: An independent copy of this tensor.

inline bool is_contiguous() const¶

Whether the elements are stored without gaps in column-major (Fortran) order, i.e.

the first index varies fastest.

inline std::size_t contiguous_dims() const¶: Number of leading dimensions that are contiguous.

template<typename D> inline Tensor contiguous(const D &device, AllocHint hint = AllocHint::normal) const¶: A contiguous copy allocated through device, or *this if already contiguous.

inline Tensor contiguous(AllocHint hint = AllocHint::normal) const¶: A contiguous copy, or *this if already contiguous.

template<typename D> inline Tensor contiguous(std::size_t batch_size, const D &device, AllocHint hint = AllocHint::normal) const¶: Like contiguous, broadcasting a leading size-1 dimension to batch_size.

inline Tensor contiguous(std::size_t batch_size) const¶: Like contiguous, broadcasting a leading size-1 dimension to batch_size.

inline bool is_only_reference() const¶: Whether this is the only reference to its storage.

Public Static Attributes

static std::size_t tensor_count¶: Number of live tensors that currently own their storage.