MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TensorSpec.cpp
Go to the documentation of this file.
1#include "TensorSpec.hpp"
2
4
5namespace MayaFlux::Kakshya {
6
7namespace {
8
9 constexpr uint64_t max_signed = static_cast<uint64_t>(std::numeric_limits<int64_t>::max());
10
11 bool magnitude_times(uint64_t a, uint64_t b, uint64_t& out)
12 {
13 if (a != 0 && b > max_signed / a)
14 return false;
15 out = a * b;
16 return true;
17 }
18
19 uint64_t stride_magnitude(int64_t stride)
20 {
21 return stride < 0 ? static_cast<uint64_t>(-(stride + 1)) + 1 : static_cast<uint64_t>(stride);
22 }
23
24 template <typename T>
25 std::vector<T> cut(const std::vector<T>& values, uint64_t first, uint64_t count)
26 {
27 return { values.begin() + static_cast<std::ptrdiff_t>(first),
28 values.begin() + static_cast<std::ptrdiff_t>(first + count) };
29 }
30
31}
32
33TensorSpec TensorSpec::contiguous(TensorDType dtype, std::vector<uint64_t> shape, std::string name)
34{
35 TensorSpec spec;
36 spec.name = std::move(name);
37 spec.dtype = dtype;
38 spec.shape = std::move(shape);
39 return spec;
40}
41
42std::optional<uint64_t> TensorSpec::element_count() const noexcept
43{
44 uint64_t count = 1;
45 for (const auto extent : shape) {
46 if (!magnitude_times(count, extent, count))
47 return std::nullopt;
48 }
49 return count;
50}
51
52bool TensorSpec::is_contiguous() const noexcept
53{
54 if (strides.empty())
55 return true;
56 if (strides.size() != shape.size())
57 return false;
58
59 const auto count = element_count();
60 if (count && *count == 0)
61 return true;
62
63 int64_t expected = 1;
64 for (size_t i = shape.size(); i-- > 0;) {
65 if (shape[i] != 1 && strides[i] != expected)
66 return false;
67 if (shape[i] > max_signed / static_cast<uint64_t>(std::max<int64_t>(expected, 1)))
68 return false;
69 expected *= static_cast<int64_t>(shape[i]);
70 }
71 return true;
72}
73
74std::vector<int64_t> TensorSpec::resolved_strides() const
75{
76 if (!strides.empty())
77 return strides;
78
79 std::vector<int64_t> result(shape.size(), 1);
80 int64_t running = 1;
81 for (size_t i = shape.size(); i-- > 0;) {
82 result[i] = running;
83 running *= static_cast<int64_t>(std::max<uint64_t>(shape[i], 1));
84 }
85 return result;
86}
87
88std::optional<std::pair<uint64_t, uint64_t>> TensorSpec::byte_range() const noexcept
89{
90 const auto count = element_count();
91 if (!count)
92 return std::nullopt;
93 if (*count == 0)
94 return std::pair<uint64_t, uint64_t> { byte_offset, byte_offset };
95
96 if (dtype.is_sub_byte()) {
97 const auto bytes = dtype.storage_bytes(*count);
98 if (!bytes || *bytes > std::numeric_limits<uint64_t>::max() - byte_offset)
99 return std::nullopt;
100 return std::pair<uint64_t, uint64_t> { byte_offset, byte_offset + *bytes };
101 }
102
103 const auto resolved = resolved_strides();
104 uint64_t low = 0;
105 uint64_t high = 0;
106 for (size_t i = 0; i < shape.size(); ++i) {
107 if (shape[i] <= 1)
108 continue;
109 const int64_t stride = resolved[i];
110 const uint64_t magnitude = stride < 0 ? static_cast<uint64_t>(-(stride + 1)) + 1 : static_cast<uint64_t>(stride);
111 uint64_t reach = 0;
112 if (!magnitude_times(shape[i] - 1, magnitude, reach))
113 return std::nullopt;
114 uint64_t& side = stride < 0 ? low : high;
115 if (reach > max_signed - side)
116 return std::nullopt;
117 side += reach;
118 }
119
120 const uint64_t element = dtype.element_bytes();
121 uint64_t low_bytes = 0;
122 uint64_t high_bytes = 0;
123 if (!magnitude_times(low, element, low_bytes) || !magnitude_times(high, element, high_bytes))
124 return std::nullopt;
125 if (low_bytes > byte_offset)
126 return std::nullopt;
127
128 const uint64_t first = byte_offset - low_bytes;
129 const uint64_t extent = high_bytes + low_bytes + element;
130 if (extent < element || extent > std::numeric_limits<uint64_t>::max() - first)
131 return std::nullopt;
132 return std::pair<uint64_t, uint64_t> { first, first + extent };
133}
134
135std::string TensorSpec::diagnose() const
136{
137 const std::string label = name.empty() ? std::string("tensor") : "tensor '" + name + "'";
138
139 if (dtype.bits == 0 || dtype.lanes == 0)
140 return label + ": element type has zero width";
141 if (static_cast<uint8_t>(dtype.kind) > static_cast<uint8_t>(TensorDTypeKind::BCOMPLEX))
142 return label + ": unknown element type kind";
143 if (!element_count())
144 return label + ": element count overflows";
145 if (!strides.empty() && strides.size() != shape.size())
146 return label + ": strides rank " + std::to_string(strides.size())
147 + " differs from shape rank " + std::to_string(shape.size());
148 if (!axes.empty() && axes.size() != shape.size())
149 return label + ": axes rank " + std::to_string(axes.size())
150 + " differs from shape rank " + std::to_string(shape.size());
151 if (dtype.is_sub_byte() && !is_contiguous())
152 return label + ": " + dtype.name() + " is sub-byte and must be contiguous";
153 if (!byte_range())
154 return label + ": layout addresses memory outside its storage";
155
156 if (quantization) {
157 const auto& q = *quantization;
158 if (q.scale.empty())
159 return label + ": quantization has no scale";
160 const size_t expected = q.axis ? (*q.axis < shape.size() ? shape[*q.axis] : 0) : 1;
161 if (q.axis && *q.axis >= shape.size())
162 return label + ": quantization axis " + std::to_string(*q.axis) + " is out of range";
163 if (q.scale.size() != expected)
164 return label + ": quantization has " + std::to_string(q.scale.size())
165 + " scales, expected " + std::to_string(expected);
166 if (!q.zero_point.empty() && q.zero_point.size() != q.scale.size())
167 return label + ": quantization zero points differ in length from scales";
168 }
169
170 return {};
171}
172
173std::vector<DataDimension> TensorSpec::dimensions() const
174{
175 const auto resolved = resolved_strides();
176 std::vector<DataDimension> result;
177 result.reserve(shape.size());
178
179 for (size_t i = 0; i < shape.size(); ++i) {
180 const int64_t stride = resolved[i];
181 const uint64_t magnitude = stride < 0 ? static_cast<uint64_t>(-(stride + 1)) + 1 : static_cast<uint64_t>(stride);
182 if (i < axes.size()) {
183 auto axis = axes[i];
184 axis.size = shape[i];
185 axis.stride = magnitude;
186 result.push_back(std::move(axis));
187 } else {
188 result.emplace_back("axis" + std::to_string(i), shape[i], magnitude, DataDimension::Role::CUSTOM);
189 }
190 }
191 return result;
192}
193
194std::optional<TensorSpec> TensorSpec::window(
195 std::span<const uint64_t> origin, std::span<const uint64_t> extent) const
196{
197 if (origin.size() != shape.size() || extent.size() != shape.size())
198 return std::nullopt;
199
200 bool whole = true;
201 for (size_t i = 0; i < shape.size(); ++i) {
202 if (extent[i] == 0 || origin[i] >= shape[i] || extent[i] > shape[i] - origin[i])
203 return std::nullopt;
204 whole = whole && origin[i] == 0 && extent[i] == shape[i];
205 }
206 if (whole)
207 return *this;
208 if (dtype.is_sub_byte())
209 return std::nullopt;
210
211 const auto resolved = resolved_strides();
212 const uint64_t element = dtype.element_bytes();
213 uint64_t forward = 0;
214 uint64_t backward = 0;
215 for (size_t i = 0; i < shape.size(); ++i) {
216 if (origin[i] == 0)
217 continue;
218 uint64_t step = 0;
219 if (!magnitude_times(stride_magnitude(resolved[i]), element, step)
220 || !magnitude_times(step, origin[i], step))
221 return std::nullopt;
222 uint64_t& side = resolved[i] < 0 ? backward : forward;
223 if (step > max_signed - side)
224 return std::nullopt;
225 side += step;
226 }
227 if (byte_offset > max_signed || forward > max_signed - byte_offset)
228 return std::nullopt;
229 const uint64_t up = byte_offset + forward;
230 if (backward > up)
231 return std::nullopt;
232
233 TensorSpec result = *this;
234 result.shape.assign(extent.begin(), extent.end());
235 result.strides = resolved;
236 result.byte_offset = up - backward;
237
238 if (result.quantization && result.quantization->axis) {
239 const size_t axis = *result.quantization->axis;
240 auto& q = *result.quantization;
241 if (axis >= shape.size() || q.scale.size() != shape[axis]
242 || (!q.zero_point.empty() && q.zero_point.size() != shape[axis]))
243 return std::nullopt;
244 q.scale = cut(q.scale, origin[axis], extent[axis]);
245 if (!q.zero_point.empty())
246 q.zero_point = cut(q.zero_point, origin[axis], extent[axis]);
247 }
248 return result;
249}
250
251std::optional<TensorSpec> TensorSpec::window(const Region& region) const
252{
253 const size_t named = region.start_coordinates.size();
254 if (named == 0 || named != region.end_coordinates.size() || named > shape.size())
255 return std::nullopt;
256
257 std::vector<uint64_t> origin(shape.size(), 0);
258 std::vector<uint64_t> extent = shape;
259 for (size_t axis = 0; axis < named; ++axis) {
260 const uint64_t first = region.start_coordinates[axis];
261 const uint64_t last = region.end_coordinates[axis];
262 if (first > last || last >= shape[axis])
263 return std::nullopt;
264 origin[axis] = first;
265 extent[axis] = last - first + 1;
266 }
267 return window(origin, extent);
268}
269
270}
std::vector< double > count(std::span< const double > data, size_t n_windows, uint32_t hop_size, uint32_t window_size)
Sample count per window (as double for pipeline uniformity).
Definition Analysis.cpp:506
@ CUSTOM
User-defined or application-specific.
Definition NDData.hpp:223
std::vector< uint64_t > end_coordinates
Ending frame index (inclusive).
Definition Region.hpp:79
std::vector< uint64_t > start_coordinates
Starting frame index (inclusive).
Definition Region.hpp:76
Represents a point or span in N-dimensional space.
Definition Region.hpp:74
Element type as kind, bit width and lane count.
std::vector< DataDimension > axes
std::optional< uint64_t > element_count() const noexcept
Product of the shape, or std::nullopt on overflow.
std::optional< std::pair< uint64_t, uint64_t > > byte_range() const noexcept
Storage bytes [first, last) the spec addresses, from storage start.
bool is_contiguous() const noexcept
Whether elements are laid out densely in C order.
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.
std::vector< DataDimension > dimensions() const
One DataDimension per axis, with size and stride taken from shape and strides.
std::optional< TensorSpec > window(std::span< const uint64_t > origin, std::span< const uint64_t > extent) const
Spec of the box that starts at origin and spans extent elements per axis.
std::vector< uint64_t > shape
std::vector< int64_t > resolved_strides() const
Element strides, with C order filled in when none are stored.
Complete description of a tensor: type, shape, layout, meaning.