MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Tensor.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "TensorAccess.hpp"
4
5namespace MayaFlux::Kakshya {
6
7namespace detail {
8
9 struct AlignedDelete {
10 void operator()(std::byte* pointer) const noexcept
11 {
12 ::operator delete(pointer, std::align_val_t { 256 });
13 }
14 };
15
16 using AlignedBytes = std::unique_ptr<std::byte, AlignedDelete>;
17
18}
19
20/**
21 * @class TensorData
22 * @brief Owning host tensor: a TensorSpec and the bytes it describes.
23 *
24 * Storage is one 256-byte aligned byte block, copied deeply with the object.
25 * Any element type the spec can name is stored the same way, so half, int8,
26 * int64 and the rest need no DataVariant alternative. A DataVariant is an
27 * optional bridge: from_variant() and to_variant() / to_vector() copy to and
28 * from it where the element types agree.
29 *
30 * Usage:
31 * @code
32 * std::vector<float> pixels(3 * 224 * 224);
33 * auto input = TensorData::from_values<float>(pixels, { 1, 3, 224, 224 }, "input");
34 * auto view = input->access();
35 * auto upload = view->gpu_view();
36 * auto variant = input->to_variant();
37 * @endcode
38 *
39 * @note Zero-copy exchange with other libraries goes through TensorAccess and
40 * the DLPack functions in TensorDLPack.hpp.
41 */
42class MAYAFLUX_API TensorData {
43public:
44 TensorData() = default;
45 TensorData(const TensorData& other);
46 TensorData& operator=(const TensorData& other);
47 TensorData(TensorData&&) noexcept = default;
48 TensorData& operator=(TensorData&&) noexcept = default;
49 ~TensorData() = default;
50
51 /**
52 * @brief Zero-filled tensor for a spec.
53 * @return Tensor, or std::nullopt when the spec is inconsistent or not
54 * host memory.
55 */
56 [[nodiscard]] static std::optional<TensorData> allocate(TensorSpec spec);
57
58 /**
59 * @brief Tensor holding a copy of @p bytes.
60 * @param spec Layout of the bytes.
61 * @param bytes Exactly the storage the spec addresses.
62 * @return Tensor, or std::nullopt for an inconsistent spec or a size mismatch.
63 */
64 [[nodiscard]] static std::optional<TensorData> from_bytes(
65 TensorSpec spec, std::span<const std::byte> bytes);
66
67 /**
68 * @brief Contiguous tensor holding a copy of typed values.
69 * @param values Elements in C order.
70 * @param shape Dimension sizes; empty means one dimension of values.size().
71 * @param name Optional tensor name.
72 * @return Tensor, or std::nullopt when the shape does not match the count.
73 */
74 template <TensorElement T>
75 [[nodiscard]] static std::optional<TensorData> from_values(
76 std::span<const T> values, std::vector<uint64_t> shape = {}, std::string name = {})
77 {
78 if (shape.empty())
79 shape.push_back(values.size());
80 return from_bytes(
81 TensorSpec::contiguous(TensorDType::of<T>(), std::move(shape), std::move(name)),
82 std::as_bytes(values));
83 }
84
85 /**
86 * @brief Tensor holding a copy of a DataVariant.
87 * @param variant Source data. glm vectors become [N, components] float
88 * tensors and glm::mat4 becomes [N, 4, 4].
89 * @param shape Dimension sizes; empty keeps the shape implied above.
90 * @param name Optional tensor name.
91 * @return Tensor, or std::nullopt when the shape does not match the data.
92 */
93 [[nodiscard]] static std::optional<TensorData> from_variant(
94 const DataVariant& variant, std::vector<uint64_t> shape = {}, std::string name = {});
95
96 /**
97 * @brief Dense C-ordered copy of any tensor view.
98 *
99 * Gathers through strides, so transposed, Fortran-ordered, offset and
100 * broadcast views all become ordinary contiguous tensors.
101 */
102 [[nodiscard]] static std::optional<TensorData> copy_of(const TensorAccess& view);
103
104 /** @brief Layout of the stored bytes. */
105 [[nodiscard]] const TensorSpec& spec() const noexcept { return m_spec; }
106 /** @brief Whether the tensor holds a consistent spec and its storage. */
107 [[nodiscard]] bool is_valid() const noexcept { return m_size > 0 || m_spec.element_count().value_or(1) == 0; }
108 /** @brief Storage size in bytes. */
109 [[nodiscard]] size_t byte_size() const noexcept { return m_size; }
110 /** @brief The whole stored block. */
111 [[nodiscard]] std::span<const std::byte> storage() const noexcept { return { m_data.get(), m_size }; }
112 /** @brief The whole stored block, writable. */
113 [[nodiscard]] std::span<std::byte> storage() noexcept { return { m_data.get(), m_size }; }
114
115 /** @brief Borrow the tensor, or std::nullopt when it holds nothing valid. */
116 [[nodiscard]] std::optional<TensorAccess> access() const;
117
118 /**
119 * @brief Copy into a flat DataVariant when the dtype has an alternative.
120 * @return Variant for f64, f32, u8, u16, u32, complex f32 and complex f64
121 * dense tensors, otherwise std::nullopt.
122 */
123 [[nodiscard]] std::optional<DataVariant> to_variant() const;
124
125 /**
126 * @brief Copy into a vector of T.
127 *
128 * Scalar and complex T need a dense tensor of that dtype. glm vector and
129 * matrix T need a dense f32 tensor whose bytes divide into whole elements.
130 */
131 template <DataVariantElement T>
132 [[nodiscard]] std::optional<std::vector<T>> to_vector() const
133 {
134 const auto view = access();
135 if (!view)
136 return std::nullopt;
137 const auto raw = view->bytes();
138 if constexpr (TensorElement<T>) {
139 if (!m_spec.dtype.is<T>())
140 return std::nullopt;
141 } else {
142 if (!m_spec.dtype.is<float>() || raw.size() % sizeof(T) != 0)
143 return std::nullopt;
144 }
145 if (raw.empty())
146 return view->element_count() == 0 ? std::optional<std::vector<T>>(std::vector<T> {}) : std::nullopt;
147 std::vector<T> result(raw.size() / sizeof(T));
148 std::memcpy(result.data(), raw.data(), result.size() * sizeof(T));
149 return result;
150 }
151
152private:
153 friend class TensorInsertion;
154
157 size_t m_size {};
158};
159
160/**
161 * @struct TensorSet
162 * @brief Named tensors that belong together, such as a model's weights or I/O.
163 *
164 * Mirrors a safetensors or ONNX initializer set: ordered tensors with unique
165 * names, plus free-form string metadata.
166 */
167struct MAYAFLUX_API TensorSet {
168 std::vector<TensorData> tensors;
169 std::map<std::string, std::string> metadata;
170
171 /** @brief Tensor with this exact name, or nullptr. */
172 [[nodiscard]] const TensorData* find(std::string_view name) const;
173 /** @brief Tensor with this exact name, or nullptr. */
174 [[nodiscard]] TensorData* find(std::string_view name);
175 /** @brief Whether every tensor is valid and named, with no duplicate names. */
176 [[nodiscard]] bool is_consistent() const;
177};
178
179}
static std::optional< TensorData > from_values(std::span< const T > values, std::vector< uint64_t > shape={}, std::string name={})
Contiguous tensor holding a copy of typed values.
Definition Tensor.hpp:75
detail::AlignedBytes m_data
Definition Tensor.hpp:156
std::optional< std::vector< T > > to_vector() const
Copy into a vector of T.
Definition Tensor.hpp:132
bool is_valid() const noexcept
Whether the tensor holds a consistent spec and its storage.
Definition Tensor.hpp:107
TensorData & operator=(const TensorData &other)
Definition Tensor.cpp:63
TensorData(TensorData &&) noexcept=default
const TensorSpec & spec() const noexcept
Layout of the stored bytes.
Definition Tensor.hpp:105
std::span< const std::byte > storage() const noexcept
The whole stored block.
Definition Tensor.hpp:111
size_t byte_size() const noexcept
Storage size in bytes.
Definition Tensor.hpp:109
static std::optional< TensorData > from_bytes(TensorSpec spec, std::span< const std::byte > bytes)
Tensor holding a copy of bytes.
Definition Tensor.cpp:93
std::optional< TensorAccess > access() const
Borrow the tensor, or std::nullopt when it holds nothing valid.
Definition Tensor.cpp:150
std::span< std::byte > storage() noexcept
The whole stored block, writable.
Definition Tensor.hpp:113
static std::optional< TensorData > allocate(TensorSpec spec)
Zero-filled tensor for a spec.
Definition Tensor.cpp:72
Owning host tensor: a TensorSpec and the bytes it describes.
Definition Tensor.hpp:42
A C++ scalar or std::complex that maps to a TensorDType.
std::unique_ptr< std::byte, AlignedDelete > AlignedBytes
Definition Tensor.hpp:16
std::vector< TensorData > tensors
Definition Tensor.hpp:168
const TensorData * find(std::string_view name) const
Tensor with this exact name, or nullptr.
Definition Tensor.cpp:176
std::map< std::string, std::string > metadata
Definition Tensor.hpp:169
bool is_consistent() const
Whether every tensor is valid and named, with no duplicate names.
Definition Tensor.cpp:194
Named tensors that belong together, such as a model's weights or I/O.
Definition Tensor.hpp:167
Complete description of a tensor: type, shape, layout, meaning.
void operator()(std::byte *pointer) const noexcept
Definition Tensor.hpp:10