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

614 bool axis_semantics_match_shape() const noexcept {
615 return axis_semantics.empty() || axis_semantics.size() == shape.size();
616 }

channels()

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

Number of color channels (image tensors only).

Definition at line 742 of file TensorCore.h.

clone()

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

Return a deep copy with independently-owned storage.

Definition at line 692 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 690 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 730 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 728 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 723 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 721 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 714 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 712 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 735 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 733 of file TensorCore.h.

cpu()

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

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

Definition at line 696 of file TensorCore.h.

cvu()

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

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

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

677 template <typename T> T* data_ptr() {
678 if (read_only) {
679 throw std::runtime_error("Tensor::data_ptr: tensor is read-only");
680 }
681 return const_cast<T*>(const_data_ptr<T>());
682 }

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

685 template <typename T> const T* data_ptr() const {
686 return const_data_ptr<T>();
687 }

debug_string()

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

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

Definition at line 751 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 726 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 609 of file TensorCore.h.

609 bool has_axis_semantics() const noexcept {
610 return !axis_semantics.empty();
611 }

has_plane()

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

True iff a plane with the given role exists.

Definition at line 646 of file TensorCore.h.

646 bool has_plane(PlaneRole role) const noexcept {
647 return try_plane(role) != nullptr;
648 }

height()

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

Height in pixels (image tensors only).

Definition at line 740 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 719 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 744 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 604 of file TensorCore.h.

604 bool is_composite() const {
605 return !planes.empty();
606 }

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

619 bool is_contiguous() const {
620 if (shape.empty())
621 return true;
622 if (strides_bytes.empty())
623 return true;
624 std::size_t elem = dtype_bytes(dtype);
625 if (elem == 0)
626 return false;
627 std::int64_t expected = static_cast<std::int64_t>(elem);
628 for (int i = static_cast<int>(shape.size()) - 1; i >= 0; --i) {
629 if (strides_bytes[static_cast<size_t>(i)] != expected)
630 return false;
631 expected *= shape[static_cast<size_t>(i)];
632 }
633 return true;
634 }

is_dense()

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

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

Definition at line 600 of file TensorCore.h.

600 bool is_dense() const {
601 return planes.empty();
602 }

is_i420()

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

True iff this tensor is an I420-format image.

Definition at line 748 of file TensorCore.h.

is_nv12()

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

True iff this tensor is an NV12-format image.

Definition at line 746 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 659 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 717 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 708 of file TensorCore.h.

map_read()

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

Convenience: map for read-only access.

Definition at line 662 of file TensorCore.h.

662 Mapping map_read() const {
663 return map(MapMode::Read);
664 }

map_write()

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

Convenience: map for write-only access.

Definition at line 666 of file TensorCore.h.

667 return map(MapMode::Write);
668 }

mla()

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

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

Definition at line 700 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 710 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 651 of file TensorCore.h.

651 const Plane& plane(PlaneRole role) const {
652 const Plane* found = try_plane(role);
653 if (!found)
654 throw std::runtime_error("Tensor::plane: plane not found");
655 return *found;
656 }

to()

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

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

Definition at line 694 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 702 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 756 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 637 of file TensorCore.h.

637 const Plane* try_plane(PlaneRole role) const noexcept {
638 for (const auto& plane : planes) {
639 if (plane.role == role)
640 return &plane;
641 }
642 return nullptr;
643 }

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

view_read()

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

Convenience: read-only view.

Definition at line 672 of file TensorCore.h.

673 return view(MapMode::Read);
674 }

width()

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

Width in pixels (image tensors only).

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

783 template <typename T> const T* const_data_ptr() const {
785 throw std::runtime_error("Tensor::data_ptr: tensor is not on CPU");
786 }
787 if (!is_dense()) {
788 throw std::runtime_error("Tensor::data_ptr: tensor is composite");
789 }
790 if (!is_contiguous()) {
791 throw std::runtime_error("Tensor::data_ptr: call cpu().contiguous() first");
792 }
793 if (!storage || !storage->data) {
794 throw std::runtime_error("Tensor::data_ptr: tensor storage is not mappable");
795 }
796 return reinterpret_cast<const T*>(static_cast<const uint8_t*>(storage->data) + byte_offset);
797 }

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

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

589 int64_t byte_offset =

device

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

Where the tensor lives.

Definition at line 592 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 583 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 595 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 596 of file TensorCore.h.

596 bool read_only = true;

route

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

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

Definition at line 597 of file TensorCore.h.

semantic

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

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

Definition at line 593 of file TensorCore.h.

shape

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

Per-dimension sizes.

Definition at line 586 of file TensorCore.h.

586 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 581 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 587 of file TensorCore.h.

587 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 754 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 818 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 820 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 822 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 824 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 826 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 828 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 799 of file TensorCore.h.

799 static std::size_t dtype_bytes(simaai::neat::TensorDType dtype) {
800 switch (dtype) {
803 return 1;
807 return 2;
810 return 4;
812 return 8;
813 }
814 return 0;
815 }

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


Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.