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	has_tiled_storage () const
	True when an explicit physical tile description requires detessellation. More...
bool	is_dense () const
	True iff this tensor is single-plane. 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 this tensor for access, retaining its storage/producer loan. 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
	Compatibility alias for map(); this does not narrow the mapping to shape. 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 668 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 709 of file TensorCore.h.

channels()

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

Number of color channels (image tensors only).

Definition at line 842 of file TensorCore.h.

clone()

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

Return a deep copy with independently-owned storage.

Definition at line 792 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 790 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 830 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 828 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 823 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 821 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 814 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 812 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 835 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 833 of file TensorCore.h.

cpu()

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

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

Definition at line 796 of file TensorCore.h.

cvu()

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

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

Definition at line 798 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 777 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 785 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 851 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 826 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 704 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 743 of file TensorCore.h.

has_tiled_storage()

bool simaai::neat::Tensor::has_tiled_storage ()

inline

True when an explicit physical tile description requires detessellation.

is_dense() continues to mean single-plane, not numerical storage order.

Definition at line 690 of file TensorCore.h.

height()

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

Height in pixels (image tensors only).

Definition at line 840 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 819 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 844 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 699 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 714 of file TensorCore.h.

is_dense()

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

inline

True iff this tensor is single-plane.

Definition at line 695 of file TensorCore.h.

is_i420()

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

True iff this tensor is an I420-format image.

Definition at line 848 of file TensorCore.h.

is_nv12()

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

True iff this tensor is an NV12-format image.

Definition at line 846 of file TensorCore.h.

map()

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

Map this tensor for access, retaining its storage/producer loan.

The selected storage mapping applies byte_offset once; its accessible extent may include trailing backing bytes. Custom mapping callbacks and existing named-segment view bounds remain authoritative.

Definition at line 759 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 817 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 808 of file TensorCore.h.

map_read()

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

inline

Convenience: map for read-only access.

Definition at line 762 of file TensorCore.h.

map_write()

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

inline

Convenience: map for write-only access.

Definition at line 766 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 800 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 810 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 748 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 794 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 802 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 856 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 734 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 805 of file TensorCore.h.

view()

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

Compatibility alias for map(); this does not narrow the mapping to shape.

Definition at line 770 of file TensorCore.h.

view_read()

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

inline

Convenience: read-only view.

Definition at line 772 of file TensorCore.h.

width()

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

Width in pixels (image tensors only).

Definition at line 838 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 883 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 680 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 678 of file TensorCore.h.

device

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

Where the tensor lives.

Definition at line 681 of file TensorCore.h.

dtype

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

Element type.

Definition at line 671 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 672 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 684 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 685 of file TensorCore.h.

route

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

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

Definition at line 686 of file TensorCore.h.

semantic

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

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

Definition at line 682 of file TensorCore.h.

shape

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

Per-dimension sizes.

Definition at line 675 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 670 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 676 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 854 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 921 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 923 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 925 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 927 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 929 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 931 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 902 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.15.0.