Skip to main content

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

boolis_dense () const

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

boolis_composite () const

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

boolhas_axis_semantics () const noexcept

True iff per-axis semantic tags have been populated. More...

boolaxis_semantics_match_shape () const noexcept

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

boolis_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...

boolhas_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...

Mappingmap (MapMode mode) const

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

Mappingmap_read () const

Convenience: map for read-only access. More...

Mappingmap_write () const

Convenience: map for write-only access. More...

Mappingview (MapMode mode=MapMode::Read) const

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

Mappingview_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...

Tensorcontiguous () const

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

Tensorclone () const

Return a deep copy with independently-owned storage. More...

Tensorto (Device target) const

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

Tensorcpu () const

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

Tensorcvu () const

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

Tensormla (bool force=false) const

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

Tensorto_cpu_if_needed () const

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

boolvalidate (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_tnv12_required_bytes () const

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

boolcopy_nv12_contiguous_to (uint8_t *dst, std::size_t dst_size) const

Copy NV12 pixel data into dst (dst_sizenv12_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_ti420_required_bytes () const

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

boolcopy_i420_contiguous_to (uint8_t *dst, std::size_t dst_size) const

Copy I420 pixel data into dst (dst_sizei420_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_tdense_bytes_tight () const

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

boolcopy_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...

boolcopy_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...

intwidth () const

Width in pixels (image tensors only). More...

intheight () const

Height in pixels (image tensors only). More...

intchannels () 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...

boolis_nv12 () const

True iff this tensor is an NV12-format image. More...

boolis_i420 () const

True iff this tensor is an I420-format image. More...

std::stringdebug_string () const

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

std::stringto_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::TensorDTypedtype = simaai::neat::TensorDType::UInt8

Element type. More...

simaai::neat::TensorLayoutlayout = ...

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_tbyte_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...

Devicedevice {}

Where the tensor lives. More...

Semanticsemantic {}

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...

boolread_only = true

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

TensorRouteMetaroute {}

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

Public Static Functions Index

static Tensorfrom_text (std::string_view text)

Construct a CPU-owned UTF-8 text tensor. More...

static Tensorfrom_vector (const std::vector< float > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensorfrom_vector (const std::vector< uint8_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensorfrom_vector (const std::vector< int8_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensorfrom_vector (const std::vector< uint16_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensorfrom_vector (const std::vector< int16_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)
static Tensorfrom_vector (const std::vector< int32_t > &data, std::vector< int64_t > shape, TensorMemory memory=TensorMemory::EV74)

Private Static Functions Index

static std::size_tdtype_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.
  • Typedtype (the element type) and layout (legacy coarse token).
  • Shape & stridesshape[] (per-dimension sizes), strides_bytes[] (per-dimension byte strides).
  • Axis semanticsaxis_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 606 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 641 of file TensorCore.h.

641 bool axis_semantics_match_shape() const noexcept {
642 return axis_semantics.empty() || axis_semantics.size() == shape.size();
643 }

channels()

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

Number of color channels (image tensors only).

Definition at line 769 of file TensorCore.h.

clone()

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

Return a deep copy with independently-owned storage.

Definition at line 719 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 717 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 757 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 755 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 750 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_sizei420_required_bytes()); returns success.

Definition at line 748 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 741 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_sizenv12_required_bytes()); returns success.

Definition at line 739 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 762 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 760 of file TensorCore.h.

cpu()

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

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

Definition at line 723 of file TensorCore.h.

cvu()

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

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

Definition at line 725 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 704 of file TensorCore.h.

704 template <typename T> T* data_ptr() {
705 if (read_only) {
706 throw std::runtime_error("Tensor::data_ptr: tensor is read-only");
707 }
708 return const_cast<T*>(const_data_ptr<T>());
709 }

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 712 of file TensorCore.h.

712 template <typename T> const T* data_ptr() const {
713 return const_data_ptr<T>();
714 }

debug_string()

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

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

Definition at line 778 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 753 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 636 of file TensorCore.h.

636 bool has_axis_semantics() const noexcept {
637 return !axis_semantics.empty();
638 }

has_plane()

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

True iff a plane with the given role exists.

Definition at line 673 of file TensorCore.h.

673 bool has_plane(PlaneRole role) const noexcept {
674 return try_plane(role) != nullptr;
675 }

height()

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

Height in pixels (image tensors only).

Definition at line 767 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 746 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 771 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 631 of file TensorCore.h.

631 bool is_composite() const {
632 return !planes.empty();
633 }

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 646 of file TensorCore.h.

646 bool is_contiguous() const {
647 if (shape.empty())
648 return true;
649 if (strides_bytes.empty())
650 return true;
651 std::size_t elem = dtype_bytes(dtype);
652 if (elem == 0)
653 return false;
654 std::int64_t expected = static_cast<std::int64_t>(elem);
655 for (int i = static_cast<int>(shape.size()) - 1; i >= 0; --i) {
656 if (strides_bytes[static_cast<size_t>(i)] != expected)
657 return false;
658 expected *= shape[static_cast<size_t>(i)];
659 }
660 return true;
661 }

is_dense()

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

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

Definition at line 627 of file TensorCore.h.

627 bool is_dense() const {
628 return planes.empty();
629 }

is_i420()

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

True iff this tensor is an I420-format image.

Definition at line 775 of file TensorCore.h.

is_nv12()

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

True iff this tensor is an NV12-format image.

Definition at line 773 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 686 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 744 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 735 of file TensorCore.h.

map_read()

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

Convenience: map for read-only access.

Definition at line 689 of file TensorCore.h.

689 Mapping map_read() const {
690 return map(MapMode::Read);
691 }

map_write()

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

Convenience: map for write-only access.

Definition at line 693 of file TensorCore.h.

694 return map(MapMode::Write);
695 }

mla()

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

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

Definition at line 727 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 737 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 678 of file TensorCore.h.

678 const Plane& plane(PlaneRole role) const {
679 const Plane* found = try_plane(role);
680 if (!found)
681 throw std::runtime_error("Tensor::plane: plane not found");
682 return *found;
683 }

to()

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

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

Definition at line 721 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 729 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 783 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 664 of file TensorCore.h.

664 const Plane* try_plane(PlaneRole role) const noexcept {
665 for (const auto& plane : planes) {
666 if (plane.role == role)
667 return &plane;
668 }
669 return nullptr;
670 }

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 732 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 697 of file TensorCore.h.

view_read()

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

Convenience: read-only view.

Definition at line 699 of file TensorCore.h.

700 return view(MapMode::Read);
701 }

width()

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

Width in pixels (image tensors only).

Definition at line 765 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 810 of file TensorCore.h.

810 template <typename T> const T* const_data_ptr() const {
812 throw std::runtime_error("Tensor::data_ptr: tensor is not on CPU");
813 }
814 if (!is_dense()) {
815 throw std::runtime_error("Tensor::data_ptr: tensor is composite");
816 }
817 if (!is_contiguous()) {
818 throw std::runtime_error("Tensor::data_ptr: call cpu().contiguous() first");
819 }
820 if (!storage || !storage->data) {
821 throw std::runtime_error("Tensor::data_ptr: tensor storage is not mappable");
822 }
823 return reinterpret_cast<const T*>(static_cast<const uint8_t*>(storage->data) + byte_offset);
824 }

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 618 of file TensorCore.h.

618 std::vector<TensorAxisSemantic> axis_semantics;

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 616 of file TensorCore.h.

616 int64_t byte_offset =

device

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

Where the tensor lives.

Definition at line 619 of file TensorCore.h.

dtype

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

layout

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

Coarse legacy layout token (transitional; prefer axis_semantics).

Initialiser

Definition at line 610 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 622 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 623 of file TensorCore.h.

623 bool read_only = true;

route

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

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

Definition at line 624 of file TensorCore.h.

semantic

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

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

Definition at line 620 of file TensorCore.h.

shape

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

Per-dimension sizes.

Definition at line 613 of file TensorCore.h.

613 std::vector<int64_t> shape;

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 608 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 614 of file TensorCore.h.

614 std::vector<int64_t> strides_bytes;

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 781 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 845 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 847 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 849 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 851 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 853 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 855 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 826 of file TensorCore.h.

826 static std::size_t dtype_bytes(simaai::neat::TensorDType dtype) {
827 switch (dtype) {
830 return 1;
834 return 2;
837 return 4;
839 return 8;
840 }
841 return 0;
842 }

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


Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.