MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TensorSpec.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "NDData.hpp"
4#include "TensorDType.hpp"
5
6namespace MayaFlux::Kakshya {
7
8struct Region;
9
10/**
11 * @enum TensorDeviceType
12 * @brief Where tensor memory lives. Values equal the DLPack device types.
13 */
14enum class TensorDeviceType : int32_t {
15 CPU = 1,
16 CUDA = 2,
18 OPENCL = 4,
19 VULKAN = 7,
20 METAL = 8,
21 VPI = 9,
22 ROCM = 10,
24 EXT_DEV = 12,
26 ONEAPI = 14,
27 WEBGPU = 15,
28 HEXAGON = 16,
29 MAIA = 17,
30 TRN = 18,
31 TPU = 19,
33 ASCEND = 21
34};
35
36/**
37 * @struct TensorDevice
38 * @brief Device type and ordinal holding a tensor's memory.
39 */
40struct MAYAFLUX_API TensorDevice {
42 int32_t id {};
43
44 constexpr bool operator==(const TensorDevice&) const noexcept = default;
45
46 /** @brief Whether the host can read this memory directly. */
47 [[nodiscard]] constexpr bool is_host_accessible() const noexcept
48 {
49 switch (type) {
55 return true;
56 default:
57 return false;
58 }
59 }
60};
61
62/**
63 * @struct TensorQuantization
64 * @brief Affine quantization: real = scale * (stored - zero_point).
65 *
66 * Per tensor when axis is empty (one scale), otherwise per slice along axis
67 * (one scale per index of that axis). zero_point is empty for symmetric
68 * quantization or matches scale in length.
69 */
70struct MAYAFLUX_API TensorQuantization {
71 std::vector<double> scale;
72 std::vector<int64_t> zero_point;
73 std::optional<size_t> axis;
74};
75
76/**
77 * @struct TensorSpec
78 * @brief Complete description of a tensor: type, shape, layout, meaning.
79 *
80 * Follows the DLPack model. Strides are in elements and may be explicit,
81 * negative or broadcast (zero), so views, Fortran order and transposes are
82 * described without copying; empty strides mean C order. byte_offset locates
83 * element zero inside the storage. axes optionally gives each dimension a
84 * role and name, for example batch, channel and spatial axes.
85 *
86 * Usage:
87 * @code
88 * auto spec = TensorSpec::contiguous(TensorDType::of<float>(), { 1, 3, 224, 224 }, "input");
89 * if (auto why = spec.diagnose(); !why.empty()) { }
90 * @endcode
91 */
92struct MAYAFLUX_API TensorSpec {
93 std::string name;
95 std::vector<uint64_t> shape;
96 std::vector<int64_t> strides;
97 uint64_t byte_offset {};
98 std::vector<DataDimension> axes;
99 std::optional<TensorQuantization> quantization;
101
102 /** @brief C-ordered spec with no offset, axes or quantization. */
103 [[nodiscard]] static TensorSpec contiguous(
104 TensorDType dtype, std::vector<uint64_t> shape, std::string name = {});
105
106 /** @brief Number of dimensions. */
107 [[nodiscard]] size_t rank() const noexcept { return shape.size(); }
108
109 /** @brief Product of the shape, or std::nullopt on overflow. */
110 [[nodiscard]] std::optional<uint64_t> element_count() const noexcept;
111
112 /** @brief Whether elements are laid out densely in C order. */
113 [[nodiscard]] bool is_contiguous() const noexcept;
114
115 /** @brief Element strides, with C order filled in when none are stored. */
116 [[nodiscard]] std::vector<int64_t> resolved_strides() const;
117
118 /**
119 * @brief Storage bytes [first, last) the spec addresses, from storage start.
120 * @return Range, or std::nullopt for overflow or a negative start.
121 */
122 [[nodiscard]] std::optional<std::pair<uint64_t, uint64_t>> byte_range() const noexcept;
123
124 /** @brief Empty when the spec is self-consistent, otherwise the reason it is not. */
125 [[nodiscard]] std::string diagnose() const;
126
127 /** @brief Whether diagnose() reports no problem. */
128 [[nodiscard]] bool is_valid() const { return diagnose().empty(); }
129
130 /** @brief One DataDimension per axis, with size and stride taken from shape and strides. */
131 [[nodiscard]] std::vector<DataDimension> dimensions() const;
132
133 /**
134 * @brief Spec of the box that starts at @p origin and spans @p extent elements per axis.
135 *
136 * The result addresses the same storage with the same strides, so no data
137 * moves. Per-axis quantization is cut to the same range.
138 * @return The window, or std::nullopt when a rank differs, an extent is
139 * zero, the box leaves the shape, the offset leaves the addressable range,
140 * or the type is sub-byte and the box is not the whole tensor.
141 */
142 [[nodiscard]] std::optional<TensorSpec> window(
143 std::span<const uint64_t> origin, std::span<const uint64_t> extent) const;
144
145 /**
146 * @brief Spec of the box a Region selects.
147 *
148 * Bounds are inclusive. Trailing axes the region does not name span their
149 * full extent.
150 * @return The window, or std::nullopt when the region is empty, names more
151 * axes than the tensor, has mismatched bounds, or the box is not addressable
152 * as described for the span overload.
153 */
154 [[nodiscard]] std::optional<TensorSpec> window(const Region& region) const;
155};
156
157}
TensorDeviceType
Where tensor memory lives.
Represents a point or span in N-dimensional space.
Definition Region.hpp:74
Element type as kind, bit width and lane count.
constexpr bool is_host_accessible() const noexcept
Whether the host can read this memory directly.
constexpr bool operator==(const TensorDevice &) const noexcept=default
Device type and ordinal holding a tensor's memory.
std::vector< int64_t > zero_point
Affine quantization: real = scale * (stored - zero_point).
size_t rank() const noexcept
Number of dimensions.
std::vector< DataDimension > axes
std::string diagnose() const
Empty when the spec is self-consistent, otherwise the reason it is not.
std::optional< TensorQuantization > quantization
std::vector< int64_t > strides
static TensorSpec contiguous(TensorDType dtype, std::vector< uint64_t > shape, std::string name={})
C-ordered spec with no offset, axes or quantization.
bool is_valid() const
Whether diagnose() reports no problem.
std::vector< uint64_t > shape
Complete description of a tensor: type, shape, layout, meaning.