MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
SpectralAnalyzer.hpp
Go to the documentation of this file.
1#pragma once
2
6
7#include "Analyzer.hpp"
8#include <Eigen/Dense>
9
12
14
15/**
16 * @file SpectralAnalyzer.hpp
17 * @brief Windowed spectral descriptors computed on the GPU, exactly, with no fp64 on the device.
18 *
19 * Each window is tapered, transformed and reduced against rows of weights on the
20 * device, so only a handful of doubles per window come back. That makes the
21 * analysis cheap to run over many windows, such as every grain of a long corpus.
22 */
23
24namespace MayaFlux::Yantra {
25
26/**
27 * @enum SpectralMethod
28 * @brief The per-window value a SpectralAnalyzer reports as its output data.
29 */
30enum class SpectralMethod : uint8_t {
31 TOTAL_POWER, ///< Sum of the power spectrum over the bins 0 to window_size / 2
32 CENTROID, ///< Power weighted mean bin index, zero for a silent window
33 FLUX ///< Sum over bands of the rise in band energy since the previous window, zero for the first
34};
35
36/**
37 * @struct SpectralAnalyzerConfig
38 * @brief Settings of a SpectralAnalyzer.
39 *
40 * window_size is the transform length: a power of two from 2 to 2048.
41 */
43 /** Value reported as the output data, as a SpectralMethod value. */
45 /** Ascending band boundaries as fractions of the Nyquist frequency, 0 to 1. N edges make N - 1 bands. */
46 std::vector<double> band_edges { 0.0, 0.25, 0.5, 1.0 };
47 /** Multiply each window by a Hann taper before the transform. */
48 bool taper { true };
49};
50
51MF_DESCRIBE(SpectralAnalyzerConfig)
52
53/**
54 * @struct ChannelSpectrum
55 * @brief Spectral descriptors of one channel, one entry per window.
56 */
57struct MAYAFLUX_API ChannelSpectrum {
58 /** The value selected by the method. */
59 std::vector<double> values;
60 /** Power in each band, per window. */
61 std::vector<std::vector<double>> band_energies;
62 /** First and one past the last sample of each window. */
63 std::vector<std::pair<size_t, size_t>> window_positions;
64};
65
66/**
67 * @struct SpectralAnalysis
68 * @brief Analysis result of a SpectralAnalyzer.
69 */
70struct MAYAFLUX_API SpectralAnalysis {
71 /** Settings the analysis was produced under. */
73 std::vector<ChannelSpectrum> channels;
74};
75
77
78/**
79 * @class SpectralAnalyzer
80 * @brief Windowed spectral descriptors of every channel, run on the GPU.
81 *
82 * One dispatch per channel transforms all windows and projects each power
83 * spectrum onto rows of weights: its total, its first moment and one row per
84 * band. The method picks which value becomes the output data; the band energies
85 * are always in the analysis. Sums run in emulated double arithmetic on word
86 * pairs, so results agree with Kinesis spectral_projection to rounding and the
87 * device needs no float64.
88 *
89 * It is a distinct operation on the vulkan target, not a replacement for an
90 * existing analyzer, and has no CPU twin. A channel shorter than one window
91 * gives no windows.
92 */
93template <ComputeData InputType = std::vector<Kakshya::DataVariant>, ComputeData OutputType = Eigen::MatrixXd>
94class SpectralAnalyzer : public Analyzer<InputType, OutputType> {
95public:
100
101 static constexpr Target target = targets::vulkan;
102
103 /**
104 * @brief Construct a spectral analyzer from its settings.
105 * @param config Analysis settings, validated before they are stored.
106 */
108 {
110 this->set_config(std::move(config));
111 }
112
113 [[nodiscard]] ConfigRefs configs() const override
114 {
115 return this->stored_configs(supports {});
116 }
117
118 /**
119 * @struct SpectralBuffer
120 * @brief Where the descriptors of the latest record are on the device.
121 *
122 * Word pair doubles, window major: values_per_window of them per window, the
123 * total power, the first moment, then the power of each band.
124 */
126 const GpuDispatchCore* context { nullptr };
127 uint32_t set { 0 };
128 size_t binding { 0 };
129 size_t windows { 0 };
130 size_t values_per_window { 0 };
131 };
132
133 /**
134 * @brief Append to a recording the caller shares with other work.
135 *
136 * With a shared recording the transform goes to the device in the same
137 * submission as the work recorded around it. Call it before the first
138 * analysis or record. The recording must be compute isolated.
139 *
140 * @throws std::logic_error when the analyzer has already started.
141 */
142 void share_recording(std::shared_ptr<GpuDispatchRecorder> recording)
143 {
144 if (m_context) {
146 std::source_location::current(), "The recording can only be shared before the analyzer starts");
147 }
148 m_recording = std::move(recording);
149 }
150
151 /**
152 * @brief Transform the windows of one channel without waiting for the result.
153 *
154 * The descriptors stay on the device, in descriptor_buffer, recorded into
155 * the analyzer's recording with no submission and no read back. A consumer
156 * on the same recording, for instance a WordPairMap ToFloat32 stage that
157 * hands them to a network, reads them in place. Bind the consumer after the
158 * analyzer's settings are final, since a change of window or bands makes a
159 * new context.
160 *
161 * @param channel Samples of one channel.
162 * @return The number of windows recorded.
163 */
164 [[nodiscard]] size_t record(std::span<const double> channel)
165 {
166 const auto& cfg = this->template config<SpectralAnalyzerConfig>();
167 auto& context = this->context(cfg);
168 const size_t windows = channel.size() < cfg.window_size
169 ? 0
170 : (channel.size() - cfg.window_size) / cfg.hop_size + 1;
171 m_resident_windows = windows;
172 if (windows == 0) {
173 return 0;
174 }
175 const std::vector<double> taper = cfg.taper ? Kinesis::Discrete::hann(cfg.window_size) : std::vector<double> {};
176 context.ensure_shared_buffer(0, FftContext::result_binding, windows * context.descriptors(), GpuBufferBinding::ElementType::VEC2_U32);
177 context.record_real(channel,
178 { .length = cfg.window_size, .stride = cfg.hop_size, .offset = 0, .count = static_cast<uint32_t>(windows) }, taper);
179 return windows;
180 }
181
182 /**
183 * @brief The device buffer of the descriptors of the latest record. It exists from this call on.
184 */
185 [[nodiscard]] SpectralBuffer descriptor_buffer()
186 {
187 const auto& cfg = this->template config<SpectralAnalyzerConfig>();
188 auto& context = this->context(cfg);
190 return { .context = &context, .set = 0, .binding = FftContext::result_binding,
191 .windows = m_resident_windows, .values_per_window = context.descriptors() };
192 }
193
194 /**
195 * @brief Type-safe spectral analysis
196 */
198 {
199 auto result = this->analyze_data(data);
200 return safe_any_cast_or_throw<SpectralAnalysis>(result);
201 }
202
203 SpectralAnalysis analyze_spectrum(const InputType& data)
204 {
205 return this->analyze_spectrum(input_type { data });
206 }
207
209 {
210 return safe_any_cast_or_throw<SpectralAnalysis>(this->get_current_analysis());
211 }
212
213 [[nodiscard]] AnalysisType get_analysis_type() const override
214 {
216 }
217
218 [[nodiscard]] std::string get_name() const override
219 {
220 return "SpectralAnalyzer";
221 }
222
223 /**
224 * @brief One while a device is up, zero otherwise.
225 */
226 static float fitness(const input_type& /*input*/)
227 {
229 }
230
231protected:
233 {
234 try {
235 const auto& cfg = this->template config<SpectralAnalyzerConfig>();
236
237 auto [data_span, structure_info] = OperationHelper::extract_structured_double(
238 const_cast<input_type&>(input));
239
240 auto& context = this->context(cfg);
241 const std::vector<double> taper = cfg.taper ? Kinesis::Discrete::hann(cfg.window_size) : std::vector<double> {};
242 const size_t rows = context.descriptors();
243 const size_t bands = rows - 2;
244
245 SpectralAnalysis analysis;
246 analysis.config = cfg;
247 analysis.channels.resize(data_span.size());
248
249 std::vector<std::vector<double>> channel_values;
250 channel_values.reserve(data_span.size());
251
252 for (size_t channel = 0; channel < data_span.size(); ++channel) {
253 const std::span<const double> samples { data_span[channel].data(), data_span[channel].size() };
254 const size_t windows = samples.size() < cfg.window_size
255 ? 0
256 : (samples.size() - cfg.window_size) / cfg.hop_size + 1;
257
258 auto& result = analysis.channels[channel];
259 if (windows > 0) {
260 const auto projected = context.transform(samples,
261 { .length = cfg.window_size, .stride = cfg.hop_size, .offset = 0, .count = static_cast<uint32_t>(windows) },
262 taper);
263 fill_channel(result, projected, windows, rows, bands, cfg);
264 }
265 channel_values.push_back(result.values);
266 }
267
268 this->store_current_analysis(analysis);
269
270 output_type output = this->convert_result(channel_values, structure_info);
271 output.metadata = input.metadata;
272 output.facets = input.facets;
273 output.facets.set(analysis);
274 return output;
275 } catch (const std::exception& e) {
276 MF_ERROR(Journal::Component::Yantra, Journal::Context::ComputeMatrix, "Spectral analysis failed: {}", e.what());
277 output_type error_result;
278 error_result.metadata = input.metadata;
279 error_result.facets = input.facets;
280 return error_result;
281 }
282 }
283
284private:
285 struct ContextKey {
286 uint32_t window_size {};
287 std::vector<double> band_edges;
288 bool operator==(const ContextKey&) const = default;
289 };
290
291 mutable std::unique_ptr<FftContext> m_context;
292 mutable ContextKey m_key;
293 std::shared_ptr<GpuDispatchRecorder> m_recording;
294 size_t m_resident_windows { 0 };
295
297 {
298 const auto fail = [](std::string_view message) {
300 std::source_location::current(), "{}", message);
301 };
302 if (cfg.window_size < 2 || cfg.window_size > 2048 || (cfg.window_size & (cfg.window_size - 1)) != 0) {
303 fail("Window size must be a power of two from 2 to 2048");
304 }
305 if (cfg.hop_size == 0) {
306 fail("Hop size must be greater than 0");
307 }
308 if (cfg.band_edges.size() < 2) {
309 fail("At least two band edges are needed");
310 }
311 for (size_t i = 0; i < cfg.band_edges.size(); ++i) {
312 const double edge = cfg.band_edges[i];
313 if (std::isnan(edge) || edge < 0.0 || edge > 1.0 || (i > 0 && edge <= cfg.band_edges[i - 1])) {
314 fail("Band edges must ascend strictly within 0 to 1");
315 }
316 }
317 }
318
319 /**
320 * @brief Rows of weights: total, first moment, then one row per band.
321 */
322 static std::vector<double> weights_for(const SpectralAnalyzerConfig& cfg)
323 {
324 const size_t bins = static_cast<size_t>(cfg.window_size) / 2 + 1;
325 const size_t bands = cfg.band_edges.size() - 1;
326 std::vector<double> weights((2 + bands) * bins, 0.0);
327 for (size_t k = 0; k < bins; ++k) {
328 const double fraction = static_cast<double>(k) / static_cast<double>(bins - 1);
329 weights[k] = 1.0;
330 weights[bins + k] = static_cast<double>(k);
331 for (size_t b = 0; b < bands; ++b) {
332 const bool last = b + 1 == bands;
333 if (fraction >= cfg.band_edges[b] && (fraction < cfg.band_edges[b + 1] || (last && fraction <= cfg.band_edges[b + 1]))) {
334 weights[(2 + b) * bins + k] = 1.0;
335 }
336 }
337 }
338 return weights;
339 }
340
342 {
343 const ContextKey key { cfg.window_size, cfg.band_edges };
344 if (!m_context || !(m_key == key)) {
345 const auto weights = weights_for(cfg);
346 m_context = std::make_unique<FftContext>(cfg.window_size, weights);
347 if (m_recording) {
348 m_context->set_recording(m_recording);
349 }
350 m_key = key;
351 }
352 return *m_context;
353 }
354
355 static void fill_channel(ChannelSpectrum& out, const std::vector<double>& projected,
356 size_t windows, size_t rows, size_t bands, const SpectralAnalyzerConfig& cfg)
357 {
358 out.values.resize(windows);
359 out.band_energies.resize(windows);
360 out.window_positions.reserve(windows);
361
362 for (size_t w = 0; w < windows; ++w) {
363 const double* row = projected.data() + w * rows;
364 out.band_energies[w].assign(row + 2, row + 2 + bands);
365 const size_t start = w * cfg.hop_size;
366 out.window_positions.emplace_back(start, start + cfg.window_size);
367
368 switch (static_cast<SpectralMethod>(cfg.method)) {
370 out.values[w] = row[0] > 0.0 ? row[1] / row[0] : 0.0;
371 break;
373 double rise = 0.0;
374 if (w > 0) {
375 for (size_t b = 0; b < bands; ++b) {
376 rise += std::max(0.0, out.band_energies[w][b] - out.band_energies[w - 1][b]);
377 }
378 }
379 out.values[w] = rise;
380 break;
381 }
383 default:
384 out.values[w] = row[0];
385 break;
386 }
387 }
388 }
389};
390
391/// Standard spectral analyzer: DataVariant -> MatrixXd
393
394/// Container spectral analyzer: SignalContainer -> MatrixXd
396
397} // namespace MayaFlux::Yantra
Modern, digital-first analyzer framework for Maya Flux.
#define MF_ERROR(comp, ctx,...)
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
Batched FFT of doubles on the GPU, exactly, with no fp64 on the device.
Discrete taper (window) coefficient generation and in-place application for MayaFlux::Kinesis.
void set(T value)
Stores a struct under its type identity.
Definition Facets.hpp:107
bool is_initialized() const
Check if compiler is initialized.
void store_current_analysis(AnalysisResultType &&result) const
Definition Analyzer.hpp:234
std::any get_current_analysis() const
Access cached analysis from last operation.
Definition Analyzer.hpp:175
std::any analyze_data(const input_type &data)
User-facing analysis method - returns analysis results directly.
Definition Analyzer.hpp:138
Template-flexible analyzer base with instance-defined I/O types.
Definition Analyzer.hpp:101
void set_config(Config config)
Stores a config struct, whole, under its own type.
ConfigRefs stored_configs(Supports< Configs... >) const
The stored configs among those listed, in listed order.
output_type convert_result(std::vector< std::vector< double > > &result_data, DataStructureInfo &metadata)
Convert processed double data back to OutputType using metadata and optional callback.
static constexpr uint32_t result_binding
The binding that holds the result of a dispatch.
One FFT per window, as one dispatch of the FFT template.
Non-template base that owns all type-independent GPU dispatch logic.
static std::tuple< NumericChannels, DataStructureInfo > extract_structured_double(T &compute_data)
Extract structured double data from Datum container or direct ComputeData with automatic container ha...
SpectralBuffer descriptor_buffer()
The device buffer of the descriptors of the latest record.
size_t record(std::span< const double > channel)
Transform the windows of one channel without waiting for the result.
Analyzer< InputType, OutputType > base_type
static float fitness(const input_type &)
One while a device is up, zero otherwise.
ConfigRefs configs() const override
The base view of the config structs this operation holds.
void share_recording(std::shared_ptr< GpuDispatchRecorder > recording)
Append to a recording the caller shares with other work.
static std::vector< double > weights_for(const SpectralAnalyzerConfig &cfg)
Rows of weights: total, first moment, then one row per band.
std::string get_name() const override
Get operation name for debugging/introspection.
output_type analyze_implementation(const input_type &input) override
Pure virtual analysis implementation - derived classes implement this.
SpectralAnalysis analyze_spectrum(const input_type &data)
Type-safe spectral analysis.
AnalysisType get_analysis_type() const override
Gets the analysis type category for this analyzer.
SpectralAnalysis analyze_spectrum(const InputType &data)
static void fill_channel(ChannelSpectrum &out, const std::vector< double > &projected, size_t windows, size_t rows, size_t bands, const SpectralAnalyzerConfig &cfg)
Supports< SpectralAnalyzerConfig > supports
SpectralAnalyzer(SpectralAnalyzerConfig config={})
Construct a spectral analyzer from its settings.
SpectralAnalysis get_spectral_analysis() const
static void validate_config(const SpectralAnalyzerConfig &cfg)
Windowed spectral descriptors of every channel, run on the GPU.
@ ComputeMatrix
Compute operations (Yantra - algorithms, matrices, DSP).
@ Yantra
DSP algorithms, computational units, matrix operations, Grammar.
std::vector< double > hann(size_t n)
Hann (raised cosine) taper coefficients.
Definition Taper.cpp:11
MAYAFLUX_API ShaderFoundry & get_shader_foundry()
Get the global shader compiler instance.
AnalysisType
Categories of analysis operations for discovery and organization.
Definition Analyzer.hpp:33
@ SPECTRAL
FFT, frequency domain analysis.
Definition Analyzer.hpp:35
SpectralAnalyzer< std::shared_ptr< Kakshya::SignalSourceContainer >, Eigen::MatrixXd > ContainerSpectralAnalyzer
Container spectral analyzer: SignalContainer -> MatrixXd.
std::vector< std::reference_wrapper< const OperationConfig > > ConfigRefs
Borrowed views of the configs an operation holds.
SpectralMethod
The per-window value a SpectralAnalyzer reports as its output data.
@ CENTROID
Power weighted mean bin index, zero for a silent window.
@ TOTAL_POWER
Sum of the power spectrum over the bins 0 to window_size / 2.
@ FLUX
Sum over bands of the rise in band energy since the previous window, zero for the first.
SpectralAnalyzer< std::vector< Kakshya::DataVariant >, Eigen::MatrixXd > StandardSpectralAnalyzer
Standard spectral analyzer: DataVariant -> MatrixXd.
Stores a scoped enum in its underlying integer type.
uint32_t window_size
Analysis window length in samples.
Definition Analyzer.hpp:64
uint32_t hop_size
Distance between successive windows in samples.
Definition Analyzer.hpp:66
Settings every analyzer family accepts.
Definition Analyzer.hpp:62
std::vector< std::pair< size_t, size_t > > window_positions
First and one past the last sample of each window.
std::vector< std::vector< double > > band_energies
Power in each band, per window.
std::vector< double > values
The value selected by the method.
Spectral descriptors of one channel, one entry per window.
Facets facets
Typed results that travel with the data, read by type.
Definition DataIO.hpp:68
std::unordered_map< std::string, std::any > metadata
Associated metadata.
Definition DataIO.hpp:67
Input/Output container for computation pipeline data flow with structure preservation.
Definition DataIO.hpp:63
SpectralAnalyzerConfig config
Settings the analysis was produced under.
std::vector< ChannelSpectrum > channels
Analysis result of a SpectralAnalyzer.
bool taper
Multiply each window by a Hann taper before the transform.
Reflect::EnumByte< SpectralMethod > method
Value reported as the output data, as a SpectralMethod value.
std::vector< double > band_edges
Ascending band boundaries as fractions of the Nyquist frequency, 0 to 1.
Settings of a SpectralAnalyzer.
bool operator==(const ContextKey &) const =default
Where the descriptors of the latest record are on the device.
The config structs an operation class accepts, declared as using supports.
A set of (device, runtime) pairs.