Tensor Struct

Universal tensor type — a labeled box of numbers that flows between Nodes. More...

Declaration

struct simaai::neat::Tensor { ... }

Included Headers

#include <TensorCore.h>

Public Member Functions Index

bool	is_dense () const
	True iff this tensor is single-plane (no composite plane records). More...
bool	is_composite () const
	True iff this tensor carries composite plane records (NV12, I420, …). More...
bool	has_axis_semantics () const noexcept
	True iff per-axis semantic tags have been populated. More...
bool	axis_semantics_match_shape () const noexcept
	True iff axis_semantics is empty or matches shape.size(). More...
bool	is_contiguous () const
	True iff strides describe a compact row-major layout with no internal padding. More...
const Plane *	try_plane (PlaneRole role) const noexcept
	Return a pointer to the plane with the given role, or nullptr if absent. More...
bool	has_plane (PlaneRole role) const noexcept
	True iff a plane with the given role exists. More...
const Plane &	plane (PlaneRole role) const
	Return the plane with the given role; throws if absent. More...
Mapping	map (MapMode mode) const
	Map the underlying storage for access (delegates to storage->map). More...
Mapping	map_read () const
	Convenience: map for read-only access. More...
Mapping	map_write () const
	Convenience: map for write-only access. More...
Mapping	view (MapMode mode=MapMode::Read) const
	Map a view of just this tensor's bytes (respecting byte_offset/strides). More...
Mapping	view_read () const
	Convenience: read-only view. More...
template <typename T>
T *	data_ptr ()
	Typed pointer into the (CPU-resident, dense, contiguous) tensor data; throws on mismatch. More...
template <typename T>
const T *	data_ptr () const
	Read-only typed pointer into the (CPU-resident, dense, contiguous) tensor data. More...
Tensor	contiguous () const
	Return a contiguous-strided copy of this tensor (no-op if already contiguous). More...
Tensor	clone () const
	Return a deep copy with independently-owned storage. More...
Tensor	to (Device target) const
	Return this tensor materialized on target device, copying if necessary. More...
Tensor	cpu () const
	Return this tensor on the host CPU, copying if necessary. More...
Tensor	cvu () const
	Return this tensor on the CVU (EV74), copying if necessary. More...
Tensor	mla (bool force=false) const
	Return this tensor on the MLA; pass force=true to always copy. More...
Tensor	to_cpu_if_needed () const
	Return a CPU copy if not already on CPU; otherwise return *this. More...
bool	validate (std::string *err) const
	Validate internal invariants; on failure writes a message to *err (if non-null) and returns false. More...
std::optional< Nv12Mapped >	map_nv12_read () const
	Map this tensor as an NV12 view (Y + UV); returns nullopt if not NV12. More...
std::size_t	nv12_required_bytes () const
	Bytes required to hold a tightly-packed NV12 copy of this tensor. More...
bool	copy_nv12_contiguous_to (uint8_t *dst, std::size_t dst_size) const
	Copy NV12 pixel data into dst (dst_size ≥ nv12_required_bytes()); returns success. More...
std::vector< uint8_t >	copy_nv12_contiguous () const
	Return a tightly-packed NV12 byte copy of this tensor's pixel data. More...
std::optional< I420Mapped >	map_i420_read () const
	Map this tensor as an I420 view (Y + U + V); returns nullopt if not I420. More...
std::size_t	i420_required_bytes () const
	Bytes required to hold a tightly-packed I420 copy of this tensor. More...
bool	copy_i420_contiguous_to (uint8_t *dst, std::size_t dst_size) const
	Copy I420 pixel data into dst (dst_size ≥ i420_required_bytes()); returns success. More...
std::vector< uint8_t >	copy_i420_contiguous () const
	Return a tightly-packed I420 byte copy of this tensor's pixel data. More...
std::size_t	dense_bytes_tight () const
	Bytes required to hold a tightly-packed (no-stride-padding) dense copy. More...
bool	copy_dense_bytes_tight_to (uint8_t *dst, std::size_t dst_size) const
	Copy dense data into dst with tight strides; returns success. More...
std::vector< uint8_t >	copy_dense_bytes_tight () const
	Return a tightly-packed dense byte copy of this tensor's data. More...
bool	copy_payload_bytes_to (uint8_t *dst, std::size_t dst_size) const
	Copy this tensor's raw payload bytes into dst; returns success. More...
std::vector< uint8_t >	copy_payload_bytes () const
	Return a copy of this tensor's raw payload bytes. More...
int	width () const
	Width in pixels (image tensors only). More...
int	height () const
	Height in pixels (image tensors only). More...
int	channels () const
	Number of color channels (image tensors only). More...
std::optional< ImageSpec::PixelFormat >	image_format () const
	Pixel format if this tensor carries an ImageSpec; nullopt otherwise. More...
bool	is_nv12 () const
	True iff this tensor is an NV12-format image. More...
bool	is_i420 () const
	True iff this tensor is an I420-format image. More...
std::string	debug_string () const
	Human-readable single-line summary (for logs and error messages). More...
std::string	to_text () const
	Decode a UTF-8 text tensor back into a string. More...

Private Member Functions Index

template <typename T>
const T *	const_data_ptr () const

Public Member Attributes Index

std::shared_ptr< TensorBuffer >	storage
	Shared storage handle (one tensor may have copies pointing at the same storage). More...
simaai::neat::TensorDType	dtype = simaai::neat::TensorDType::UInt8
	Element type. More...
simaai::neat::TensorLayout	layout = ...
	Coarse legacy layout token (transitional; prefer axis_semantics). More...
std::vector< int64_t >	shape
	Per-dimension sizes. More...
std::vector< int64_t >	strides_bytes
	Per-dimension strides in bytes (empty = compact row-major derived from shape+dtype). More...
int64_t	byte_offset = ...
	Offset from the start of storage->data to the first element of this tensor view. More...
std::vector< TensorAxisSemantic >	axis_semantics
	Per-axis role tags (N/D/H/W/C/Unknown). More...
Device	device {}
	Where the tensor lives. More...
Semantic	semantic {}
	What the numbers represent (image, audio, tess, etc.). More...
std::vector< Plane >	planes
	Per-plane sub-region records for composite formats (empty for dense tensors). More...
bool	read_only = true
	If true, framework refuses mutable data_ptr<T>() access. More...
TensorRouteMeta	route {}
	Routing metadata (output identity in multi-output models). More...

Public Static Functions Index

static Tensor	from_text (std::string_view text)
	Construct a CPU-owned UTF-8 text tensor. More...
static Tensor	from_vector (const std::vector< float > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensor	from_vector (const std::vector< uint8_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensor	from_vector (const std::vector< int8_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensor	from_vector (const std::vector< uint16_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensor	from_vector (const std::vector< int16_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensor	from_vector (const std::vector< int32_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

Private Static Functions Index

static std::size_t	dtype_bytes (simaai::neat::TensorDType dtype)

Description

Universal tensor type — a labeled box of numbers that flows between Nodes.

A Tensor is the framework's fundamental data type. It carries:

• Storage — a shared TensorBuffer describing where the bytes live and how to access them.
• Type — dtype (the element type) and layout (legacy coarse token).
• Shape & strides — shape[] (per-dimension sizes), strides_bytes[] (per-dimension byte strides).
• Axis semantics — axis_semantics[] tagging each axis (N/D/H/W/C); the long-term layout vocabulary.
• Device — where the tensor logically lives.
• Semantic — what the numbers represent (image, audio, tessellated, encoded, quantized, etc.).
• Planes — for composite formats (NV12, I420), per-plane sub-region records.
• Route metadata — for multi-output models, identifies which output this tensor is.

Tensors are shared_ptr-friendly for storage but value types for the metadata. Cheap to copy by value (the storage is reference-counted).

 sima::Tensor t = sima::Tensor::from_cv_mat(my_image, sima::ImageSpec::PixelFormat::BGR);

 auto m = t.storage->map(sima::MapMode::Read);

 // ... read m.size_bytes from m.data ...

See Also

TensorBuffer for the storage abstraction

See Also

Mapping for the access window

See Also

Semantic for the discriminated payload-meaning union

See Also

"Tensors: hiding the memory mess" (§0.10 of the design deep dive)

Definition at line 654 of file TensorCore.h.

Public Member Functions

axis_semantics_match_shape()

bool simaai::neat::Tensor::axis_semantics_match_shape ()

inline noexcept

True iff axis_semantics is empty or matches shape.size().

Definition at line 689 of file TensorCore.h.

channels()

int simaai::neat::Tensor::channels ()

Number of color channels (image tensors only).

Definition at line 817 of file TensorCore.h.

clone()

Tensor simaai::neat::Tensor::clone ()

Return a deep copy with independently-owned storage.

Definition at line 767 of file TensorCore.h.

contiguous()

Tensor simaai::neat::Tensor::contiguous ()

Return a contiguous-strided copy of this tensor (no-op if already contiguous).

Definition at line 765 of file TensorCore.h.

copy_dense_bytes_tight()

std::vector< uint8_t > simaai::neat::Tensor::copy_dense_bytes_tight ()

Return a tightly-packed dense byte copy of this tensor's data.

Definition at line 805 of file TensorCore.h.

copy_dense_bytes_tight_to()

bool simaai::neat::Tensor::copy_dense_bytes_tight_to (uint8_t * dst, std::size_t dst_size)

Copy dense data into dst with tight strides; returns success.

Definition at line 803 of file TensorCore.h.

copy_i420_contiguous()

std::vector< uint8_t > simaai::neat::Tensor::copy_i420_contiguous ()

Return a tightly-packed I420 byte copy of this tensor's pixel data.

Definition at line 798 of file TensorCore.h.

copy_i420_contiguous_to()

bool simaai::neat::Tensor::copy_i420_contiguous_to (uint8_t * dst, std::size_t dst_size)

Copy I420 pixel data into dst (dst_size ≥ i420_required_bytes()); returns success.

Definition at line 796 of file TensorCore.h.

copy_nv12_contiguous()

std::vector< uint8_t > simaai::neat::Tensor::copy_nv12_contiguous ()

Return a tightly-packed NV12 byte copy of this tensor's pixel data.

Definition at line 789 of file TensorCore.h.

copy_nv12_contiguous_to()

bool simaai::neat::Tensor::copy_nv12_contiguous_to (uint8_t * dst, std::size_t dst_size)

Copy NV12 pixel data into dst (dst_size ≥ nv12_required_bytes()); returns success.

Definition at line 787 of file TensorCore.h.

copy_payload_bytes()

std::vector< uint8_t > simaai::neat::Tensor::copy_payload_bytes ()

Return a copy of this tensor's raw payload bytes.

Definition at line 810 of file TensorCore.h.

copy_payload_bytes_to()

bool simaai::neat::Tensor::copy_payload_bytes_to (uint8_t * dst, std::size_t dst_size)

Copy this tensor's raw payload bytes into dst; returns success.

Definition at line 808 of file TensorCore.h.

cpu()

Tensor simaai::neat::Tensor::cpu ()

Return this tensor on the host CPU, copying if necessary.

Definition at line 771 of file TensorCore.h.

cvu()

Tensor simaai::neat::Tensor::cvu ()

Return this tensor on the CVU (EV74), copying if necessary.

Definition at line 773 of file TensorCore.h.

data_ptr()

template <typename T>

T * simaai::neat::Tensor::data_ptr ()

inline

Typed pointer into the (CPU-resident, dense, contiguous) tensor data; throws on mismatch.

Definition at line 752 of file TensorCore.h.

data_ptr()

template <typename T>

const T * simaai::neat::Tensor::data_ptr ()

inline

Read-only typed pointer into the (CPU-resident, dense, contiguous) tensor data.

Definition at line 760 of file TensorCore.h.

debug_string()

std::string simaai::neat::Tensor::debug_string ()

Human-readable single-line summary (for logs and error messages).

Definition at line 826 of file TensorCore.h.

dense_bytes_tight()

std::size_t simaai::neat::Tensor::dense_bytes_tight ()

Bytes required to hold a tightly-packed (no-stride-padding) dense copy.

Definition at line 801 of file TensorCore.h.

has_axis_semantics()

bool simaai::neat::Tensor::has_axis_semantics ()

inline noexcept

True iff per-axis semantic tags have been populated.

Definition at line 684 of file TensorCore.h.

has_plane()

bool simaai::neat::Tensor::has_plane (PlaneRole role)

inline noexcept

True iff a plane with the given role exists.

Definition at line 721 of file TensorCore.h.

height()

int simaai::neat::Tensor::height ()

Height in pixels (image tensors only).

Definition at line 815 of file TensorCore.h.

i420_required_bytes()

std::size_t simaai::neat::Tensor::i420_required_bytes ()

Bytes required to hold a tightly-packed I420 copy of this tensor.

Definition at line 794 of file TensorCore.h.

image_format()

std::optional< ImageSpec::PixelFormat > simaai::neat::Tensor::image_format ()

Pixel format if this tensor carries an ImageSpec; nullopt otherwise.

Definition at line 819 of file TensorCore.h.

is_composite()

bool simaai::neat::Tensor::is_composite ()

inline

True iff this tensor carries composite plane records (NV12, I420, …).

Definition at line 679 of file TensorCore.h.

is_contiguous()

bool simaai::neat::Tensor::is_contiguous ()

inline

True iff strides describe a compact row-major layout with no internal padding.

Definition at line 694 of file TensorCore.h.

is_dense()

bool simaai::neat::Tensor::is_dense ()

inline

True iff this tensor is single-plane (no composite plane records).

Definition at line 675 of file TensorCore.h.

is_i420()

bool simaai::neat::Tensor::is_i420 ()

True iff this tensor is an I420-format image.

Definition at line 823 of file TensorCore.h.

is_nv12()

bool simaai::neat::Tensor::is_nv12 ()

True iff this tensor is an NV12-format image.

Definition at line 821 of file TensorCore.h.

map()

Mapping simaai::neat::Tensor::map (MapMode mode)

Map the underlying storage for access (delegates to storage->map).

Definition at line 734 of file TensorCore.h.

map_i420_read()

std::optional< I420Mapped > simaai::neat::Tensor::map_i420_read ()

Map this tensor as an I420 view (Y + U + V); returns nullopt if not I420.

Definition at line 792 of file TensorCore.h.

map_nv12_read()

std::optional< Nv12Mapped > simaai::neat::Tensor::map_nv12_read ()

Map this tensor as an NV12 view (Y + UV); returns nullopt if not NV12.

Definition at line 783 of file TensorCore.h.

map_read()

Mapping simaai::neat::Tensor::map_read ()

inline

Convenience: map for read-only access.

Definition at line 737 of file TensorCore.h.

map_write()

Mapping simaai::neat::Tensor::map_write ()

inline

Convenience: map for write-only access.

Definition at line 741 of file TensorCore.h.

mla()

Tensor simaai::neat::Tensor::mla (bool force=false)

Return this tensor on the MLA; pass force=true to always copy.

Definition at line 775 of file TensorCore.h.

nv12_required_bytes()

std::size_t simaai::neat::Tensor::nv12_required_bytes ()

Bytes required to hold a tightly-packed NV12 copy of this tensor.

Definition at line 785 of file TensorCore.h.

plane()

const Plane & simaai::neat::Tensor::plane (PlaneRole role)

inline

Return the plane with the given role; throws if absent.

Definition at line 726 of file TensorCore.h.

to()

Tensor simaai::neat::Tensor::to (Device target)

Return this tensor materialized on target device, copying if necessary.

Definition at line 769 of file TensorCore.h.

to_cpu_if_needed()

Tensor simaai::neat::Tensor::to_cpu_if_needed ()

Return a CPU copy if not already on CPU; otherwise return *this.

Definition at line 777 of file TensorCore.h.

to_text()

std::string simaai::neat::Tensor::to_text ()

Decode a UTF-8 text tensor back into a string.

Definition at line 831 of file TensorCore.h.

try_plane()

const Plane * simaai::neat::Tensor::try_plane (PlaneRole role)

inline noexcept

Return a pointer to the plane with the given role, or nullptr if absent.

Definition at line 712 of file TensorCore.h.

validate()

bool simaai::neat::Tensor::validate (std::string * err)

Validate internal invariants; on failure writes a message to *err (if non-null) and returns false.

Definition at line 780 of file TensorCore.h.

view()

Mapping simaai::neat::Tensor::view (MapMode mode=MapMode::Read)

Map a view of just this tensor's bytes (respecting byte_offset/strides).

Definition at line 745 of file TensorCore.h.

view_read()

Mapping simaai::neat::Tensor::view_read ()

inline

Convenience: read-only view.

Definition at line 747 of file TensorCore.h.

width()

int simaai::neat::Tensor::width ()

Width in pixels (image tensors only).

Definition at line 813 of file TensorCore.h.

Private Member Functions

const_data_ptr()

template <typename T>

const T * simaai::neat::Tensor::const_data_ptr ()

inline

Definition at line 858 of file TensorCore.h.

Public Member Attributes

axis_semantics

std::vector<TensorAxisSemantic> simaai::neat::Tensor::axis_semantics

Per-axis role tags (N/D/H/W/C/Unknown).

Definition at line 666 of file TensorCore.h.

byte_offset

int64_t simaai::neat::Tensor::byte_offset

Offset from the start of storage->data to the first element of this tensor view.

Initialiser

= 0

Definition at line 664 of file TensorCore.h.

device

Device simaai::neat::Tensor::device {}

Where the tensor lives.

Definition at line 667 of file TensorCore.h.

dtype

simaai::neat::TensorDType simaai::neat::Tensor::dtype = simaai::neat::TensorDType::UInt8

Element type.

Definition at line 657 of file TensorCore.h.

layout

simaai::neat::TensorLayout simaai::neat::Tensor::layout

Coarse legacy layout token (transitional; prefer axis_semantics).

Initialiser

= simaai::neat::TensorLayout::Unknown

Definition at line 658 of file TensorCore.h.

planes

std::vector<Plane> simaai::neat::Tensor::planes

Per-plane sub-region records for composite formats (empty for dense tensors).

Definition at line 670 of file TensorCore.h.

read_only

bool simaai::neat::Tensor::read_only = true

If true, framework refuses mutable data_ptr<T>() access.

Definition at line 671 of file TensorCore.h.

route

TensorRouteMeta simaai::neat::Tensor::route {}

Routing metadata (output identity in multi-output models).

Definition at line 672 of file TensorCore.h.

semantic

Semantic simaai::neat::Tensor::semantic {}

What the numbers represent (image, audio, tess, etc.).

Definition at line 668 of file TensorCore.h.

shape

std::vector<int64_t> simaai::neat::Tensor::shape

Per-dimension sizes.

Definition at line 661 of file TensorCore.h.

storage

std::shared_ptr<TensorBuffer> simaai::neat::Tensor::storage

Shared storage handle (one tensor may have copies pointing at the same storage).

Definition at line 656 of file TensorCore.h.

strides_bytes

std::vector<int64_t> simaai::neat::Tensor::strides_bytes

Per-dimension strides in bytes (empty = compact row-major derived from shape+dtype).

Definition at line 662 of file TensorCore.h.

Public Static Functions

from_text()

Tensor simaai::neat::Tensor::from_text (std::string_view text)

static

Construct a CPU-owned UTF-8 text tensor.

Definition at line 829 of file TensorCore.h.

from_vector()

Tensor simaai::neat::Tensor::from_vector (const std::vector< float > & data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

static

Definition at line 893 of file TensorCore.h.

from_vector()

Tensor simaai::neat::Tensor::from_vector (const std::vector< uint8_t > & data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

static

Definition at line 895 of file TensorCore.h.

from_vector()

Tensor simaai::neat::Tensor::from_vector (const std::vector< int8_t > & data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

static

Definition at line 897 of file TensorCore.h.

from_vector()

Tensor simaai::neat::Tensor::from_vector (const std::vector< uint16_t > & data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

static

Definition at line 899 of file TensorCore.h.

from_vector()

Tensor simaai::neat::Tensor::from_vector (const std::vector< int16_t > & data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

static

Definition at line 901 of file TensorCore.h.

from_vector()

Tensor simaai::neat::Tensor::from_vector (const std::vector< int32_t > & data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

static

Definition at line 903 of file TensorCore.h.

Private Static Functions

dtype_bytes()

std::size_t simaai::neat::Tensor::dtype_bytes (simaai::neat::TensorDType dtype)

inline static

Definition at line 874 of file TensorCore.h.

---

The documentation for this struct was generated from the following file:

• TensorCore.h

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.