optim_tensor.h#

Lightweight, non-owning tensor description used by ONNX graph optimisation passes.

The onnx_optim namespace exposes three small value types:

:cpp:class:OptimDim — a single shape dimension, either a concrete int64_t or a symbolic string expression.
:cpp:class:OptimShape — an ordered, bounded-rank collection of :cpp:class:OptimDim.
:cpp:class:OptimTensor — a non-owning view over a contiguous buffer carrying a :cpp:type:TensorType, an :cpp:class:OptimShape, and an optional shape annotation when the tensor itself represents a shape (e.g. the shape input of Reshape).

These types are intentionally header-only friendly and never allocate the tensor data they describe; callers are responsible for the lifetime of the underlying buffer.

namespace ONNX_LIGHT_NAMESPACE

namespace onnx_optim

Typedefs

using TensorType = ONNX_LIGHT_NAMESPACE::onnx_op::TensorType #: Reuse the TensorType enumeration defined by onnx_op so that onnx_optim is fully aligned with the rest of the operator stack.

Enums

enum class OptimCmpResult#

Result of comparing two :cpp:class:OptimTensor descriptors with :cpp:func:OptimTensor::Cmp. The four outcomes describe the relative precision of the two descriptors when they are interpreted as statements about the same logical tensor.

:cpp:enumerator:OptimCmpResult::kConflict — the two descriptors carry contradictory information (e.g. different known element types, different ranks, or incompatible concrete dimension values) and cannot both be true at the same time.
:cpp:enumerator:OptimCmpResult::kMorePrecise — *this is at least as precise as other on every field and strictly more precise on at least one (or both are equivalent — the equal case is reported as kMorePrecise).
:cpp:enumerator:OptimCmpResult::kLessPrecise — other is strictly more precise than *this.
:cpp:enumerator:OptimCmpResult::kComplementary — neither descriptor dominates: each one carries some information the other one is missing, but the two are mutually compatible.

Values:

enumerator kConflict#

enumerator kMorePrecise#

enumerator kLessPrecise#

enumerator kComplementary#

Functions

TensorType DataTypeToTensorType(TensorProto::DataType dtype)#: Maps a TensorProto::DataType to the matching :cpp:type:TensorType enumerator used by :cpp:class:OptimTensor. Returns :cpp:enumerator:TensorType::kUndefined for any data type that is not representable in the onnx_optim stack (e.g. UNDEFINED).

TensorProto::DataType TensorTypeToDataType(TensorType t)#

Maps a :cpp:type:TensorType enumerator back to the matching TensorProto::DataType. This is the inverse of :cpp:func:DataTypeToTensorType and is used to write inferred element types into ValueInfoProto / TypeProto::Tensor.

Only the scalar tensor types are supported (the sequence- and optional-typed enumerators do not have a single matching scalar DataType). For sequence/optional types or for :cpp:enumerator:TensorType::kUndefined, the function returns TensorProto::DataType::UNDEFINED.

bool IsIntegerTensorType(TensorType t)#

Returns whether a tensor element type can be interpreted as shape dimensions for ValueAsShape.

Accepted integer types are signed/unsigned 8, 16, 32 and 64-bit integers.

Parameters:: t – Tensor element type to evaluate.
Returns:: true if t is one of the supported integer types.

OptimShape ShapeFromTensorProtoDims(const TensorProto &tensor_proto)#

Builds an :cpp:class:OptimShape from tensor_proto.dims().

ONNX stores tensor dimensions as non-negative 64-bit integers in TensorProto::dims; this helper converts every dimension into an :cpp:class:OptimDim and appends them in order.

Parameters:: tensor_proto – Tensor whose dims field is converted.
Returns:: Converted shape with the same rank and dimension values.

Variables

constexpr std::size_t kMaxOptimRank = 8#: Maximum number of dimensions an OptimShape can describe inline. Shapes in practice rarely exceed this rank, so storing the dimensions in a small container keeps the structure compact and cache-friendly.

class OptimDim#

#include <optim_tensor.h>

A single shape dimension that is either a concrete non-negative integer or a symbolic expression represented as a string. OptimDim is used by OptimShape to describe both fully-known and partially-symbolic shapes.

Public Functions

inline OptimDim()#: Default constructs a zero-valued integer dimension.

inline OptimDim(int64_t value)#: Constructs an integer-valued dimension.

inline OptimDim(std::string expr)#: Constructs a symbolic dimension expressed as a string expression.

inline OptimDim(const char *expr)#: Convenience overload for C string literals.

inline bool IsInt() const noexcept#: Returns true when the dimension holds a concrete integer value.

inline bool IsExpr() const noexcept#: Returns true when the dimension holds a symbolic expression string.

inline int64_t AsInt() const#: Returns the integer value. Throws std::bad_variant_access if the dimension is not an integer.

inline const std::string &AsExpr() const#: Returns the symbolic expression. Throws std::bad_variant_access if the dimension is not a string expression.

inline bool operator==(const OptimDim &other) const noexcept#: Equality compares both the alternative and the underlying value.

inline bool operator!=(const OptimDim &other) const noexcept#

std::string ToString() const#: Returns a human-readable representation of the dimension: the integer value for concrete dimensions, or the symbolic expression for string dimensions.

Private Members

std::variant<int64_t, std::string> value_#

class OptimShape#

#include <optim_tensor.h>

A short, value-typed shape composed of OptimDim entries. The rank is bounded by kMaxOptimRank so that the structure fits comfortably on the stack. Symbolic and concrete dimensions can be mixed freely.

Public Types

using value_type = OptimDim #

Public Functions

OptimShape() = default#

OptimShape(std::initializer_list<OptimDim> dims)#: Constructs a shape from an initializer list of dimensions.

explicit OptimShape(const std::vector<OptimDim> &dims)#: Constructs a shape from any iterable container of OptimDim.

inline std::size_t Rank() const noexcept#: Number of dimensions.

inline bool Empty() const noexcept#: true when the shape contains no dimensions (scalar / rank-0).

inline const OptimDim &operator[](std::size_t i) const#: Access a dimension by index. Throws std::out_of_range if invalid.

inline OptimDim &operator[](std::size_t i)#

void PushBack(OptimDim dim)#: Appends a new dimension. Throws std::length_error when the maximum rank kMaxOptimRank would be exceeded.

bool IsFullyKnown() const noexcept#: Returns true when every dimension is a concrete integer.

int64_t NumElements() const#: Computes the product of all integer dimensions. Returns 1 for a rank-0 (empty) shape, matching the standard scalar-element-count semantic. Throws std::runtime_error if any dimension is symbolic.

inline bool operator==(const OptimShape &other) const noexcept#: Equality compares the dimensions element-wise.

inline bool operator!=(const OptimShape &other) const noexcept#

inline const std::vector<OptimDim> &Dims() const noexcept#: Read-only access to the underlying dimensions.

std::string ToString() const#: Returns a human-readable representation of the shape as a comma-separated list of dimensions enclosed in square brackets, e.g. "[2,3,N]". A rank-0 shape returns "[]".

Private Members

std::vector<OptimDim> dims_#

class OptimTensor#

#include <optim_tensor.h>

A non-owning view over a contiguous tensor buffer. OptimTensor never allocates: the caller is responsible for the lifetime of the underlying memory referenced by data. The shape may contain symbolic dimensions which is useful for representing intermediate values during optimisation passes where the concrete shape is not yet known.

Public Functions

OptimTensor() = default#: Constructs an empty (null) tensor.

inline OptimTensor(void *data, TensorType dtype, OptimShape shape)#

Constructs an OptimTensor referencing an external buffer.

Parameters:

data – Pointer to the first element of the externally-owned buffer. May be nullptr only when shape is empty or all integer dimensions are zero.
dtype – Element type of the data referenced by data.
shape – Shape describing the layout of the data.

inline void *Data() const noexcept#: Pointer to the externally-owned buffer. The view itself is const but the buffer it references is not, mirroring std::span semantics.

inline TensorType Dtype() const noexcept#: Element type of the referenced buffer.

inline const OptimShape &Shape() const noexcept#: Shape of the tensor (may contain symbolic dimensions).

inline OptimShape &Shape() noexcept#

inline bool IsNull() const noexcept#: true when the tensor has no associated data pointer.

inline void SetValueAsShape(OptimShape shape)#: Tags the tensor as carrying a shape value (e.g. the shape input of a Reshape node) and stores that shape. An empty OptimShape is permitted: it denotes a rank-0 / scalar shape value.

inline void ClearValueAsShape() noexcept#: Clears the value-as-shape annotation so that HasValueAsShape becomes false again.

inline bool HasValueAsShape() const noexcept#: true when the tensor’s value is interpreted as a shape. An empty stored shape still returns true — use ValueAsShape().Empty() to distinguish the empty case.

inline const OptimShape &ValueAsShape() const#: Returns the shape value carried by this tensor. Throws std::bad_optional_access if HasValueAsShape() is false.

inline OptimShape &ValueAsShape()#

inline bool operator==(const OptimTensor &other) const noexcept#: Equality compares the data pointer, dtype, shape, and the optional value-as-shape annotation. Because :cpp:class:OptimTensor is a non-owning view, two tensors are considered equal only when they refer to the same external buffer.

inline bool operator!=(const OptimTensor &other) const noexcept#

std::string ToString() const#: Returns a human-readable representation of the tensor of the form "OptimTensor(dtype=<name>, shape=<shape>[, value_as_shape=<shape>][, data=<ptr>])". The data component is omitted when the tensor holds no buffer. The value_as_shape component is omitted when no shape annotation is attached. The <name> is the unqualified TensorType enumerator name (e.g. "Float", "Int64", "Undefined").

OptimCmpResult Cmp(const OptimTensor &other) const noexcept#

Compares the information carried by *this and other and reports which descriptor is more precise (see :cpp:enum:OptimCmpResult).

The comparison covers, in order:

the element type (an unknown :cpp:enumerator:TensorType::kUndefined is treated as “no information”; two different known types yield :cpp:enumerator:OptimCmpResult::kConflict);
the shape rank (different ranks yield kConflict);
each dimension (two different concrete integers or two different symbolic expressions yield kConflict; an integer is considered more precise than a symbolic expression at the same position);
the optional :cpp:func:ValueAsShape annotation (handled with the same rules as the main shape; a present annotation is more precise than an absent one);
the data-pointer presence (a non-null pointer is more precise than a null one; two distinct non-null pointers carry no precision signal because :cpp:class:OptimTensor is a non-owning view and the buffer contents are not inspected).

When *this and other are equivalent on every field, the result is :cpp:enumerator:OptimCmpResult::kMorePrecise (*this is at least as precise as other).

Private Members

void *data_ = nullptr#

TensorType dtype_ = TensorType::kUndefined#

OptimShape shape_ = {}#

std::optional<OptimShape> value_as_shape_ = {}#