MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
WaveformAnalyzer.hpp
Go to the documentation of this file.
1#pragma once
2
6
7#include "Analyzer.hpp"
8#include <Eigen/Dense>
9
15
17
18/**
19 * @file WaveformAnalyzer.hpp
20 * @brief Time-domain descriptors of a waveform computed on the GPU, exactly, with no fp64 on the device.
21 *
22 * The time-domain counterpart of SpectralAnalyzer. Every window of every
23 * channel is measured by one submission of several device passes, and only a
24 * few doubles per window come back, or a lag profile per window when asked.
25 */
26
27namespace MayaFlux::Yantra {
28
29/**
30 * @enum WaveformMethod
31 * @brief The per-window value a WaveformAnalyzer reports as its output data.
32 */
33enum class WaveformMethod : uint8_t {
34 LEVEL, ///< Root mean square of the window
35 CROSSING_RATE, ///< Sign changes between neighbours per sample pair, 0 to 1
36 PERIODICITY, ///< Strength of the best repetition lag in the searched range, as a normalised correlation
37 PERIOD, ///< Best repetition lag in samples, zero when no lag qualified
38 FREQUENCY, ///< Sample rate over the best lag in Hz, zero when no lag qualified
39 PEAK, ///< Largest absolute sample
40 DC_OFFSET, ///< Mean sample
41 CREST_FACTOR, ///< Peak over level, zero for a silent window
42 HARMONICITY, ///< Periodicity over one minus periodicity, zero when no lag qualified
43 LEVEL_CHANGE, ///< Level minus the previous window's level, zero for the first window
44 PERIOD_CHANGE ///< Relative change of the period since the previous window, zero unless both have one
45};
46
47/**
48 * @struct WaveformAnalyzerConfig
49 * @brief Settings of a WaveformAnalyzer.
50 *
51 * The passes are double, as every path of the library is. The device runs them
52 * on word pairs because 64 bit floats are not guaranteed, and they agree with
53 * the Kinesis references to rounding. native_float is a fallback to float32 for
54 * a stream that cannot afford them: every pass of a window runs in one float32
55 * kernel, with the lanes of a workgroup sharing the lag search. It keeps no
56 * profiles, and a lag whose correlation differs from the best by less than
57 * float rounding may be chosen instead of it.
58 *
59 * The repetition search covers periods from sample_rate / high_frequency to
60 * sample_rate / low_frequency samples, truncated to whole samples. The window
61 * must hold at least twice the longest period. The hop is any length above 0.
62 *
63 * The strength of a lag is its correlation over the window divided by the
64 * correlation at lag 0, and a lag can pair only the samples that lie a lag
65 * apart, so a perfectly periodic signal reads at most (window - lag) / window:
66 * 0.84 at 200 Hz and 0.55 at 70 Hz for a 1536 sample window at 48 kHz. With
67 * unbiased_periodicity the lag is still chosen on that strength, which keeps
68 * the shortest of a signal's repeating lags, and the strength reported for it
69 * is divided by that share of pairs, so one threshold serves every pitch. A
70 * window whose level changes can then read slightly above 1.
71 */
74 {
75 window_size = 512;
76 hop_size = 256;
77 }
78
79 /** Value reported as the output data, as a WaveformMethod value. */
81 /** Samples per second of the analysed signal. */
82 double sample_rate { 16000.0 };
83 /** Lowest repetition frequency searched, in Hz. */
84 double low_frequency { 70.0 };
85 /** Highest repetition frequency searched, in Hz. */
86 double high_frequency { 400.0 };
87 /** Keep the autocorrelation and mean difference profile of every window. They are large: one row of lags per window. */
88 bool keep_profiles { false };
89 /** Report the strength of the chosen lag divided by the share of window pairs that lag has, so it does not fall with the period. */
90 bool unbiased_periodicity { false };
91 /** Fallback: run the device passes in float32 instead of double. Faster, accurate only to float precision, no profiles. */
92 bool native_float { false };
93};
94
95MF_DESCRIBE(WaveformAnalyzerConfig)
96
97namespace detail {
98
99 /**
100 * Body of the native kernel in the windowed kernel layout, 128 lanes per window. Outputs per window: energy,
101 * sum, peak, sign changes, centred energy at lag 0, the best raw correlation over the searched lags and its
102 * lag. Parameters: the first and last lag.
103 */
104 inline constexpr const char* waveform_native_kernel = R"(
105 float acc_sum = 0.0;
106 float acc_square = 0.0;
107 float acc_peak = 0.0;
108 float acc_cross = 0.0;
109 for (uint k = lane; k < window_length; k += lanes) {
110 float v = sample_at(window, k);
111 acc_sum += v;
112 acc_square += v * v;
113 acc_peak = max(acc_peak, abs(v));
114 if (k + 1u < window_length) {
115 float w = sample_at(window, k + 1u);
116 acc_cross += ((v >= 0.0) != (w >= 0.0)) ? 1.0 : 0.0;
117 }
118 }
119 float total = lane_reduce_sum(acc_sum);
120 float energy = lane_reduce_sum(acc_square);
121 float peak = lane_reduce_max(acc_peak);
122 float crossings = lane_reduce_sum(acc_cross);
123 float mean = total / float(window_length);
124
125 float acc_zero = 0.0;
126 for (uint k = lane; k < window_length; k += lanes) {
127 float c = sample_at(window, k) - mean;
128 acc_zero += c * c;
129 }
130 float at_zero = lane_reduce_sum(acc_zero);
131
132 uint first_lag = uint(parameters[0]);
133 uint last_lag = uint(parameters[1]);
134 float best = 0.0;
135 uint best_lag = 0u;
136 for (uint lag = first_lag + lane; lag <= last_lag; lag += lanes) {
137 float acc = 0.0;
138 for (uint k = 0u; k + lag < window_length; ++k) {
139 acc += (sample_at(window, k) - mean) * (sample_at(window, k + lag) - mean);
140 }
141 if (acc > best) {
142 best = acc;
143 best_lag = lag;
144 }
145 }
146 float top = lane_reduce_max(best);
147 float mine = (best == top && best > 0.0) ? float(best_lag) : 3.0e38;
148 float chosen = lane_reduce_min(mine);
149 if (lane == 0u) {
150 results[result_base] = energy;
151 results[result_base + 1u] = total;
152 results[result_base + 2u] = peak;
153 results[result_base + 3u] = crossings;
154 results[result_base + 4u] = at_zero;
155 results[result_base + 5u] = top;
156 results[result_base + 6u] = top > 0.0 ? chosen : 0.0;
157 }
158)";
159
160} // namespace detail
161
162/**
163 * @struct LagProfile
164 * @brief One row of values per window, one column per consecutive lag.
165 */
166struct MAYAFLUX_API LagProfile {
167 /** Window major: window w, column c is values[w * lag_count + c]. Empty when profiles are not kept. */
168 std::vector<double> values;
169 /** Lag of the first column, in samples. */
170 uint32_t first_lag { 0 };
171 /** Columns per window. */
172 uint32_t lag_count { 0 };
173
174 /**
175 * @brief The profile as a windows by lags float64 tensor.
176 * @param name Name of the tensor.
177 * @return The container, or nullptr when the profile holds nothing.
178 */
179 [[nodiscard]] std::shared_ptr<Kakshya::TensorContainer> to_tensor(std::string name) const
180 {
181 if (values.empty() || lag_count == 0) {
182 return nullptr;
183 }
184 auto data = Kakshya::TensorData::from_values<double>(values, { values.size() / lag_count, lag_count }, std::move(name));
185 return data ? std::make_shared<Kakshya::TensorContainer>(std::move(*data)) : nullptr;
186 }
187};
188
189/**
190 * @struct ChannelWaveform
191 * @brief Waveform descriptors of one channel, one entry per window.
192 */
193struct MAYAFLUX_API ChannelWaveform {
194 /** The value selected by the method. */
195 std::vector<double> values;
196 /** Root mean square. */
197 std::vector<double> level;
198 /** Sign changes per sample pair. */
199 std::vector<double> crossing_rate;
200 /** Largest absolute sample. */
201 std::vector<double> peak;
202 /** Mean sample. */
203 std::vector<double> dc_offset;
204 /** Peak over level, zero for a silent window. */
205 std::vector<double> crest_factor;
206 /** Normalised correlation at the best lag, zero when none qualified. */
207 std::vector<double> periodicity;
208 /** Best lag in samples, zero when none qualified. */
209 std::vector<double> period;
210 /** Sample rate over the best lag in Hz, zero when none qualified. */
211 std::vector<double> frequency;
212 /** Periodicity over one minus periodicity, finite, zero when none qualified. */
213 std::vector<double> harmonicity;
214 /** Level minus the previous window's level, zero for the first window. */
215 std::vector<double> level_change;
216 /** Relative change of the period since the previous window, zero unless both windows have one. */
217 std::vector<double> period_change;
218 /** First and one past the last sample of each window. */
219 std::vector<std::pair<size_t, size_t>> window_positions;
220 /** Autocorrelation of the mean-removed window divided by its lag 0 value, lags 0 to the longest searched. Kept on request. */
222 /** Mean absolute difference between samples a lag apart, lags over the searched range. Kept on request. */
224};
225
226/**
227 * @struct WaveformAnalysis
228 * @brief Analysis result of a WaveformAnalyzer.
229 */
230struct MAYAFLUX_API WaveformAnalysis {
231 /** Settings the analysis was produced under. */
233 std::vector<ChannelWaveform> channels;
234};
235
237
238/**
239 * @class WaveformAnalyzer
240 * @brief Time-domain descriptors of every channel, run on the GPU.
241 *
242 * Measures the shape of the waveform: its level and extremes, how often it
243 * changes sign, and at what lag, and how strongly, it repeats. It makes no
244 * claim about what the signal is. A sung note, a bowed string and a fan hum
245 * all repeat, so deciding that a sound is voice or speech is left to
246 * operations built on top of this one.
247 *
248 * Six device passes (energy, sum, peak, sign changes, centred correlation and
249 * optionally mean difference) read one shared upload of the chunk, and a
250 * selection pass picks the best lag from the correlation row on the device.
251 * The row is downloaded only with keep_profiles. They are recorded into one
252 * command buffer and submitted once per chunk of windows. The method picks which descriptor
253 * becomes the output data; all of them are always in the analysis. Sums run
254 * in emulated double arithmetic on word pairs, so results agree with the
255 * Kinesis references (Discrete::rms, mean, peak, zero_crossing_rate and
256 * periodicity) to rounding and the device needs no float64. The profiles are
257 * the full autocorrelation and mean difference rows a model can read, not
258 * only the lag they reduce to; to_tensor hands them over as a tensor.
259 * A channel shorter than one window gives no windows.
260 *
261 * The set of descriptors is a starting point and is expected to grow. It is a
262 * distinct operation on the vulkan target and has no CPU twin.
263 */
264template <ComputeData InputType = std::vector<Kakshya::DataVariant>, ComputeData OutputType = Eigen::MatrixXd>
265class WaveformAnalyzer : public Analyzer<InputType, OutputType> {
266public:
271
272 static constexpr Target target = targets::vulkan;
273
274 /**
275 * @brief Construct a waveform analyzer from its settings.
276 * @param config Analysis settings, validated before they are stored.
277 */
279 {
281 this->set_config(std::move(config));
282 }
283
284 [[nodiscard]] ConfigRefs configs() const override
285 {
286 return this->stored_configs(supports {});
287 }
288
289 /**
290 * @brief Type-safe waveform analysis
291 */
293 {
294 auto result = this->analyze_data(data);
295 return safe_any_cast_or_throw<WaveformAnalysis>(result);
296 }
297
298 WaveformAnalysis analyze_waveform(const InputType& data)
299 {
300 return this->analyze_waveform(input_type { data });
301 }
302
304 {
305 return safe_any_cast_or_throw<WaveformAnalysis>(this->get_current_analysis());
306 }
307
308 [[nodiscard]] AnalysisType get_analysis_type() const override
309 {
311 }
312
313 [[nodiscard]] std::string get_name() const override
314 {
315 return "WaveformAnalyzer";
316 }
317
318 /**
319 * @brief One while a device is up, zero otherwise.
320 */
321 static float fitness(const input_type& /*input*/)
322 {
324 }
325
326protected:
328 {
329 try {
330 const auto& cfg = this->template config<WaveformAnalyzerConfig>();
331
332 auto [data_span, structure_info] = OperationHelper::extract_structured_double(
333 const_cast<input_type&>(input));
334
335 if (cfg.native_float) {
337 } else {
339 }
340 const uint32_t min_lag = shortest_lag(cfg);
341 const uint32_t max_lag = longest_lag(cfg);
342
343 WaveformAnalysis analysis;
344 analysis.config = cfg;
345 analysis.channels.resize(data_span.size());
346
347 std::vector<std::vector<double>> channel_values;
348 channel_values.reserve(data_span.size());
349
350 for (size_t channel = 0; channel < data_span.size(); ++channel) {
351 const std::span<const double> samples { data_span[channel].data(), data_span[channel].size() };
352 const size_t windows = samples.size() < cfg.window_size
353 ? 0
354 : (samples.size() - cfg.window_size) / cfg.hop_size + 1;
355
356 auto& result = analysis.channels[channel];
357 if (cfg.keep_profiles) {
358 result.autocorrelation.first_lag = 0;
359 result.autocorrelation.lag_count = max_lag + 1;
360 result.mean_difference.first_lag = min_lag;
361 result.mean_difference.lag_count = max_lag - min_lag + 1;
362 }
363 for (size_t first = 0; first < windows; first += k_chunk_windows) {
364 const size_t count = std::min(k_chunk_windows, windows - first);
365 if (cfg.native_float) {
366 measure_chunk_native(result, samples, first, count, min_lag, max_lag, cfg);
367 } else {
368 measure_chunk(result, samples, first, count, min_lag, max_lag, cfg);
369 }
370 }
371 derive_changes(result);
372 select_values(result, static_cast<WaveformMethod>(cfg.method));
373 channel_values.push_back(result.values);
374 }
375
376 this->store_current_analysis(analysis);
377
378 output_type output = this->convert_result(channel_values, structure_info);
379 output.metadata = input.metadata;
380 output.facets = input.facets;
381 output.facets.set(analysis);
382 return output;
383 } catch (const std::exception& e) {
384 MF_ERROR(Journal::Component::Yantra, Journal::Context::ComputeMatrix, "Waveform analysis failed: {}", e.what());
385 output_type error_result;
386 error_result.metadata = input.metadata;
387 error_result.facets = input.facets;
388 return error_result;
389 }
390 }
391
392private:
393 static constexpr size_t k_chunk_windows = 4096;
394 static constexpr uint32_t k_values_binding = 0;
395 static constexpr uint32_t k_row_binding = 1;
396 static constexpr double k_variance_floor = 1e-12;
397 static constexpr double k_strength_ceiling = 1.0 - 1e-12;
398
399 mutable std::shared_ptr<GpuDispatchRecorder> m_recording;
400 mutable std::unique_ptr<SegmentedReductionContext> m_energy;
401 mutable std::unique_ptr<SegmentedReductionContext> m_sum;
402 mutable std::unique_ptr<SegmentedReductionContext> m_peak;
403
404 struct WordPass {
405 std::unique_ptr<WordPairExecutionContext> context;
407 };
408
409 mutable WordPass m_crossings;
410 mutable WordPass m_zero;
411 mutable WordPass m_correlation;
412 mutable WordPass m_distance;
413 mutable WordPass m_select;
414
415 static constexpr uint32_t k_native_lanes = 128;
416 static constexpr uint32_t k_native_outputs = 7;
417 mutable std::unique_ptr<ShaderExecutionContext<>> m_native;
419
421 std::vector<double> energy;
422 std::vector<double> sum;
423 std::vector<double> peak;
424 std::vector<double> crossings;
425 std::vector<double> zero;
426 std::vector<double> rows;
427 std::vector<double> distance;
428 std::vector<ArgMaxResult> picks;
429 uint32_t correlation_lags { 0 };
430 uint32_t distance_lags { 0 };
431 };
432
434 {
435 return { .lanes = k_native_lanes, .inputs = 1 };
436 }
437
438 void ensure_native() const
439 {
440 if (m_native) {
441 return;
442 }
444 if (config.shader_id == Portal::Graphics::INVALID_SHADER) {
446 std::source_location::current(), "The native waveform kernel did not compile; the shader log has the compiler's message");
447 }
448 m_native = std::make_unique<ShaderExecutionContext<>>(config, windowed_kernel_layout(native_shape()), "WaveformNative");
449 m_native_config = std::move(config);
450 }
451
452 static uint32_t shortest_lag(const WaveformAnalyzerConfig& cfg)
453 {
454 return std::max<uint32_t>(1, static_cast<uint32_t>(cfg.sample_rate / cfg.high_frequency));
455 }
456
457 static uint32_t longest_lag(const WaveformAnalyzerConfig& cfg)
458 {
459 return static_cast<uint32_t>(cfg.sample_rate / cfg.low_frequency);
460 }
461
463 {
464 const auto fail = [](std::string_view message) {
466 std::source_location::current(), "{}", message);
467 };
468 if (!std::isfinite(cfg.sample_rate) || cfg.sample_rate <= 0.0) {
469 fail("Sample rate must be finite and greater than 0");
470 }
471 if (!std::isfinite(cfg.low_frequency) || !std::isfinite(cfg.high_frequency)
472 || cfg.low_frequency <= 0.0 || cfg.high_frequency <= cfg.low_frequency
473 || cfg.high_frequency >= cfg.sample_rate / 2.0) {
474 fail("Frequencies must satisfy 0 < low < high < sample rate / 2");
475 }
476 const uint32_t min_lag = shortest_lag(cfg);
477 const uint32_t max_lag = longest_lag(cfg);
478 if (min_lag >= max_lag) {
479 fail("The frequency range spans fewer than two lags");
480 }
481 if (max_lag >= std::numeric_limits<uint16_t>::max()) {
482 fail("The longest period is too long to search");
483 }
484 if (cfg.window_size < 2U * max_lag) {
485 fail("The window must hold at least twice the longest period");
486 }
487 if (cfg.hop_size == 0) {
488 fail("The hop size must be greater than 0");
489 }
490 if (cfg.native_float && cfg.keep_profiles) {
491 fail("Profiles are kept only by the double passes, not with native_float");
492 }
493 }
494
495 void ensure_contexts() const
496 {
497 if (m_recording) {
498 return;
499 }
503
504 m_recording = std::make_shared<GpuDispatchRecorder>(true);
505 m_energy = std::make_unique<SegmentedReductionContext>(KernelOp::Sum, ReductionMap::Square);
506 m_sum = std::make_unique<SegmentedReductionContext>(KernelOp::Sum, ReductionMap::Identity);
507 m_peak = std::make_unique<SegmentedReductionContext>(KernelOp::Max, ReductionMap::Abs);
508 m_crossings = make_lagged(PairMap::SignChange, false);
509 m_zero = make_lagged(PairMap::Product, true);
510 m_correlation = make_lagged(PairMap::Product, true);
511 m_distance = make_lagged(PairMap::AbsDifference, false);
513 for (GpuDispatchCore* context : std::initializer_list<GpuDispatchCore*> {
514 m_energy.get(), m_sum.get(), m_peak.get(), m_crossings.context.get(), m_zero.context.get(),
515 m_correlation.context.get(), m_distance.context.get(), m_select.context.get() }) {
516 context->set_recording(m_recording);
517 }
518
519 constexpr auto word = GpuBufferBinding::ElementType::VEC2_U32;
520 m_energy->ensure_shared_buffer(0, k_values_binding, 1, word);
521 for (GpuDispatchCore* context : std::initializer_list<GpuDispatchCore*> {
522 m_sum.get(), m_peak.get(), m_crossings.context.get(), m_zero.context.get(),
523 m_correlation.context.get(), m_distance.context.get() }) {
524 context->import_shared(0, k_values_binding, *m_energy, 0, k_values_binding, word);
525 }
526
527 m_correlation.context->ensure_shared_buffer(0, k_row_binding, 1, word);
528 m_select.context->import_shared(0, k_values_binding, *m_correlation.context, 0, k_row_binding, word);
529 }
530
531 void upload_chunk(std::span<const double> chunk) const
532 {
533 const auto words = OperationHelper::encode_word_pairs(chunk, 0, false, false);
534 m_energy->ensure_shared_buffer(0, k_values_binding, chunk.size(), GpuBufferBinding::ElementType::VEC2_U32);
535 m_energy->upload_shared_raw(0, k_values_binding, words.data(), words.size());
536 }
537
538 static WordPass make_lagged(Portal::Graphics::PairMap map, bool centred)
539 {
540 const auto spec = lagged_pair_spec(map, centred);
541 auto config = config_from_spec(spec);
542 auto context = std::make_unique<WordPairExecutionContext>(config, bindings_from_spec(spec), false, "LaggedPair");
543 return { std::move(context), std::move(config) };
544 }
545
546 static WordPass make_select()
547 {
548 const auto spec = segmented_argmax_spec();
549 auto config = config_from_spec(spec);
550 auto context = std::make_unique<WordPairExecutionContext>(config, bindings_from_spec(spec), false, "SegmentedArgMax");
551 return { std::move(context), std::move(config) };
552 }
553
554 static void record_lagged(WordPass& pass, const SegmentGeometry& geometry, uint32_t first_lag, uint32_t lag_count)
555 {
556 pass.context->record_stages({ lagged_pair_stage(*pass.context, pass.config, geometry, first_lag, lag_count) });
557 }
558
559 static std::vector<double> download_lagged(WordPass& pass, size_t windows, uint32_t lag_count)
560 {
561 return pass.context->download_words(1, windows * lag_count);
562 }
563
564 template <typename Context>
565 static std::vector<double> collect(Context& context)
566 {
567 return context.decode_primary(context.collect_result());
568 }
569
570 void measure_chunk(ChannelWaveform& out, std::span<const double> samples, size_t first, size_t count,
571 uint32_t min_lag, uint32_t max_lag, const WaveformAnalyzerConfig& cfg) const
572 {
573 const size_t begin = first * cfg.hop_size;
574 const size_t end = (first + count - 1) * cfg.hop_size + cfg.window_size;
575 const auto chunk = samples.subspan(begin, end - begin);
576 const SegmentGeometry geometry { .length = cfg.window_size, .stride = cfg.hop_size, .offset = 0, .count = static_cast<uint32_t>(count) };
577 const bool full_row = cfg.keep_profiles;
578 const uint32_t first_lag = full_row ? 0 : min_lag;
579 const uint32_t correlation_lags = max_lag + 1 - first_lag;
580 const uint32_t distance_lags = max_lag - min_lag + 1;
581
582 upload_chunk(chunk);
583 m_energy->stage(geometry);
584 m_sum->stage(geometry);
585 m_peak->stage(geometry);
586
588 static_cast<void>(m_energy->dispatch_async(none));
589 static_cast<void>(m_sum->dispatch_async(none));
590 static_cast<void>(m_peak->dispatch_async(none));
591 record_lagged(m_crossings, geometry, 1, 1);
592 m_correlation.context->ensure_shared_buffer(0, k_row_binding, count * correlation_lags, GpuBufferBinding::ElementType::VEC2_U32);
593 record_lagged(m_correlation, geometry, first_lag, correlation_lags);
594 const SegmentGeometry searched {
595 .length = max_lag - min_lag + 1,
596 .stride = correlation_lags,
597 .offset = min_lag - first_lag,
598 .count = static_cast<uint32_t>(count)
599 };
600 m_select.context->record_stages({ segmented_argmax_stage(*m_select.context, m_select.config, searched) });
601 if (!full_row) {
602 record_lagged(m_zero, geometry, 0, 1);
603 }
604 if (cfg.keep_profiles) {
605 record_lagged(m_distance, geometry, min_lag, distance_lags);
606 }
607
608 ChunkMeasures measures;
609 measures.energy = collect(*m_energy);
610 measures.sum = collect(*m_sum);
611 measures.peak = collect(*m_peak);
612 measures.crossings = download_lagged(m_crossings, count, 1);
613 measures.picks = read_argmax(*m_select.context, count);
614 measures.rows = cfg.keep_profiles ? download_lagged(m_correlation, count, correlation_lags) : std::vector<double> {};
615 measures.zero = full_row ? std::vector<double> {} : download_lagged(m_zero, count, 1);
616 measures.distance = cfg.keep_profiles ? download_lagged(m_distance, count, distance_lags) : std::vector<double> {};
617 measures.correlation_lags = correlation_lags;
618 measures.distance_lags = distance_lags;
619
620 append_windows(out, first, count, min_lag, cfg, measures);
621 }
622
623 void measure_chunk_native(ChannelWaveform& out, std::span<const double> samples, size_t first, size_t count,
624 uint32_t min_lag, uint32_t max_lag, const WaveformAnalyzerConfig& cfg) const
625 {
627 const size_t begin = first * cfg.hop_size;
628 const size_t end = (first + count - 1) * cfg.hop_size + cfg.window_size;
629 const auto chunk = samples.subspan(begin, end - begin);
630 const std::vector<float> floats(chunk.begin(), chunk.end());
631 const std::array<float, 2> parameters { static_cast<float>(min_lag), static_cast<float>(max_lag) };
632 const WindowedInput input { .samples = floats, .stride = cfg.hop_size, .offset = 0 };
633
635 std::span<const WindowedInput>(&input, 1), cfg.window_size, static_cast<uint32_t>(count), k_native_outputs, parameters);
636
637 ChunkMeasures measures;
638 for (size_t w = 0; w < count; ++w) {
639 const float* r = results.data() + w * k_native_outputs;
640 measures.energy.push_back(r[0]);
641 measures.sum.push_back(r[1]);
642 measures.peak.push_back(r[2]);
643 measures.crossings.push_back(r[3]);
644 measures.zero.push_back(r[4]);
645 const auto lag = static_cast<uint32_t>(r[6]);
646 measures.picks.push_back({ .value = r[5], .index = lag >= min_lag && r[5] > 0.0F ? lag - min_lag : no_argmax_index });
647 }
648 measures.correlation_lags = max_lag + 1 - min_lag;
649 measures.distance_lags = max_lag - min_lag + 1;
650
651 append_windows(out, first, count, min_lag, cfg, measures);
652 }
653
654 void append_windows(ChannelWaveform& out, size_t first, size_t count, uint32_t min_lag,
655 const WaveformAnalyzerConfig& cfg, const ChunkMeasures& m) const
656 {
657 const bool full_row = cfg.keep_profiles;
658 const uint32_t correlation_lags = m.correlation_lags;
659 const uint32_t distance_lags = m.distance_lags;
660 const double window = static_cast<double>(cfg.window_size);
661 for (size_t w = 0; w < count; ++w) {
662 const size_t start = (first + w) * cfg.hop_size;
663 out.window_positions.emplace_back(start, start + cfg.window_size);
664
665 const double level = std::sqrt(m.energy[w] / window);
666 out.level.push_back(level);
667 out.crossing_rate.push_back(m.crossings[w] / (window - 1.0));
668 out.peak.push_back(m.peak[w]);
669 out.dc_offset.push_back(m.sum[w] / window);
670 out.crest_factor.push_back(level > 0.0 ? m.peak[w] / level : 0.0);
671
672 const double* row = full_row ? m.rows.data() + w * correlation_lags : nullptr;
673 const double at_zero = full_row ? row[0] : m.zero[w];
674 const bool varying = at_zero >= k_variance_floor;
675 double best = 0.0;
676 uint32_t best_lag = 0;
677 if (varying && m.picks[w].found() && m.picks[w].value > 0.0) {
678 best = m.picks[w].value / at_zero;
679 best_lag = min_lag + m.picks[w].index;
680 if (cfg.unbiased_periodicity) {
681 best *= window / (window - static_cast<double>(best_lag));
682 }
683 }
684 const double bounded = std::min(best, k_strength_ceiling);
685 out.periodicity.push_back(best);
686 out.period.push_back(static_cast<double>(best_lag));
687 out.frequency.push_back(best_lag > 0 ? cfg.sample_rate / static_cast<double>(best_lag) : 0.0);
688 out.harmonicity.push_back(best > 0.0 ? bounded / (1.0 - bounded) : 0.0);
689
690 if (cfg.keep_profiles) {
691 for (uint32_t lag = 0; lag < correlation_lags; ++lag) {
692 out.autocorrelation.values.push_back(varying ? row[lag] / row[0] : 0.0);
693 }
694 const double* gaps = m.distance.data() + w * distance_lags;
695 for (uint32_t column = 0; column < distance_lags; ++column) {
696 out.mean_difference.values.push_back(gaps[column] / (window - static_cast<double>(min_lag + column)));
697 }
698 }
699 }
700 }
701
703 {
704 const size_t windows = out.level.size();
705 out.level_change.assign(windows, 0.0);
706 out.period_change.assign(windows, 0.0);
707 for (size_t w = 1; w < windows; ++w) {
708 out.level_change[w] = out.level[w] - out.level[w - 1];
709 if (out.period[w] > 0.0 && out.period[w - 1] > 0.0) {
710 out.period_change[w] = std::abs(out.period[w] - out.period[w - 1]) / out.period[w];
711 }
712 }
713 }
714
716 {
717 switch (method) {
719 out.values = out.crossing_rate;
720 break;
722 out.values = out.periodicity;
723 break;
725 out.values = out.period;
726 break;
728 out.values = out.frequency;
729 break;
731 out.values = out.peak;
732 break;
734 out.values = out.dc_offset;
735 break;
737 out.values = out.crest_factor;
738 break;
740 out.values = out.harmonicity;
741 break;
743 out.values = out.level_change;
744 break;
746 out.values = out.period_change;
747 break;
749 default:
750 out.values = out.level;
751 break;
752 }
753 }
754};
755
756/// Standard waveform analyzer: DataVariant -> MatrixXd
758
759/// Container waveform analyzer: SignalContainer -> MatrixXd
761
762} // 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
Lagged pairwise sums of doubles on the GPU, exactly, with no fp64 on the device.
The largest value of each segment of doubles and where it is, on the GPU, with no fp64 on the device.
Reduces segments of doubles on the GPU, exactly, with no fp64 on the device.
Runs a supplied compute kernel over every window of a sequence.
void set(T value)
Stores a struct under its type identity.
Definition Facets.hpp:107
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
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.
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...
static std::vector< uint8_t > encode_word_pairs(std::span< const double > values, size_t padded_words=0, bool order_key=false, bool complement=false)
Encode doubles as little-endian 64-bit words, two 32-bit lanes each.
Supports< WaveformAnalyzerConfig > supports
static void derive_changes(ChannelWaveform &out)
static WordPass make_lagged(Portal::Graphics::PairMap map, bool centred)
void measure_chunk(ChannelWaveform &out, std::span< const double > samples, size_t first, size_t count, uint32_t min_lag, uint32_t max_lag, const WaveformAnalyzerConfig &cfg) const
static uint32_t shortest_lag(const WaveformAnalyzerConfig &cfg)
static void validate_config(const WaveformAnalyzerConfig &cfg)
static void record_lagged(WordPass &pass, const SegmentGeometry &geometry, uint32_t first_lag, uint32_t lag_count)
output_type analyze_implementation(const input_type &input) override
Pure virtual analysis implementation - derived classes implement this.
AnalysisType get_analysis_type() const override
Gets the analysis type category for this analyzer.
static void select_values(ChannelWaveform &out, WaveformMethod method)
std::string get_name() const override
Get operation name for debugging/introspection.
Analyzer< InputType, OutputType > base_type
WaveformAnalyzer(WaveformAnalyzerConfig config={})
Construct a waveform analyzer from its settings.
void measure_chunk_native(ChannelWaveform &out, std::span< const double > samples, size_t first, size_t count, uint32_t min_lag, uint32_t max_lag, const WaveformAnalyzerConfig &cfg) const
static WindowedKernelShape native_shape() noexcept
static std::vector< double > download_lagged(WordPass &pass, size_t windows, uint32_t lag_count)
void upload_chunk(std::span< const double > chunk) const
ConfigRefs configs() const override
The base view of the config structs this operation holds.
static std::vector< double > collect(Context &context)
static float fitness(const input_type &)
One while a device is up, zero otherwise.
WaveformAnalysis get_waveform_analysis() const
WaveformAnalysis analyze_waveform(const input_type &data)
Type-safe waveform analysis.
WaveformAnalysis analyze_waveform(const InputType &data)
void append_windows(ChannelWaveform &out, size_t first, size_t count, uint32_t min_lag, const WaveformAnalyzerConfig &cfg, const ChunkMeasures &m) const
static uint32_t longest_lag(const WaveformAnalyzerConfig &cfg)
Time-domain descriptors of every channel, run on the GPU.
@ ComputeMatrix
Compute operations (Yantra - algorithms, matrices, DSP).
@ Yantra
DSP algorithms, computational units, matrix operations, Grammar.
constexpr ShaderID INVALID_SHADER
MAYAFLUX_API ShaderFoundry & get_shader_foundry()
Get the global shader compiler instance.
ReductionMap
Pointwise map applied to each element before a SegmentedReduction combines it.
PairMap
Map of two elements, x[i] and x[i + lag], summed by a LaggedPair kernel.
KernelOp
Named operation the SPIR-V emitter knows how to lower to opcodes.
constexpr const char * waveform_native_kernel
Body of the native kernel in the windowed kernel layout, 128 lanes per window.
GpuComputeConfig windowed_kernel_config(const std::string &body, const WindowedKernelShape &shape={})
Config of a GLSL body wrapped in the layout.
constexpr uint32_t no_argmax_index
The index reported for a segment that holds no value to select.
std::vector< float > run_windowed_kernel(ShaderExecutionContext<> &context, const GpuComputeConfig &config, const WindowedKernelShape &shape, std::span< const WindowedInput > inputs, uint32_t window_length, uint32_t window_count, uint32_t outputs, std::span< const float > parameters)
Run a windowed kernel over every window of one or more sequences.
AnalysisType
Categories of analysis operations for discovery and organization.
Definition Analyzer.hpp:33
@ TEMPORAL
Time-based patterns, onset detection.
Definition Analyzer.hpp:36
@ PEAK
Peak amplitude.
std::vector< ArgMaxResult > read_argmax(WordPairExecutionContext &context, size_t segments)
Read the selections of the segments of the last recorded stage.
Portal::Graphics::ShaderSpec lagged_pair_spec(Portal::Graphics::PairMap map, bool centred, uint32_t workgroup=256)
The spec of a LaggedPair kernel.
DependencyStage lagged_pair_stage(WordPairExecutionContext &context, const GpuComputeConfig &config, const SegmentGeometry &geometry, uint32_t first_lag, uint32_t lag_count)
The stage that sums every window at every lag in a range, over values already on the device.
WaveformMethod
The per-window value a WaveformAnalyzer reports as its output data.
@ FREQUENCY
Sample rate over the best lag in Hz, zero when no lag qualified.
@ CREST_FACTOR
Peak over level, zero for a silent window.
@ CROSSING_RATE
Sign changes between neighbours per sample pair, 0 to 1.
@ HARMONICITY
Periodicity over one minus periodicity, zero when no lag qualified.
@ LEVEL_CHANGE
Level minus the previous window's level, zero for the first window.
@ PERIODICITY
Strength of the best repetition lag in the searched range, as a normalised correlation.
@ PEAK
Largest absolute sample.
@ PERIOD_CHANGE
Relative change of the period since the previous window, zero unless both have one.
@ PERIOD
Best repetition lag in samples, zero when no lag qualified.
@ LEVEL
Root mean square of the window.
WaveformAnalyzer< std::vector< Kakshya::DataVariant >, Eigen::MatrixXd > StandardWaveformAnalyzer
Standard waveform analyzer: DataVariant -> MatrixXd.
std::vector< GpuBufferBinding > windowed_kernel_layout(const WindowedKernelShape &shape={})
The binding layout of a windowed kernel.
DependencyStage segmented_argmax_stage(WordPairExecutionContext &context, const GpuComputeConfig &config, const SegmentGeometry &geometry)
The stage that selects the largest value of every segment of values already on the device.
GpuComputeConfig config_from_spec(const Portal::Graphics::ShaderSpec &spec)
Derive a GpuComputeConfig from a ShaderSpec.
std::vector< std::reference_wrapper< const OperationConfig > > ConfigRefs
Borrowed views of the configs an operation holds.
std::vector< GpuBufferBinding > bindings_from_spec(const Portal::Graphics::ShaderSpec &spec)
Derive a GpuBufferBinding list from a ShaderSpec.
Portal::Graphics::ShaderSpec segmented_argmax_spec(uint32_t workgroup=256)
The spec of a SegmentedArgMax kernel.
WaveformAnalyzer< std::shared_ptr< Kakshya::SignalSourceContainer >, Eigen::MatrixXd > ContainerWaveformAnalyzer
Container waveform analyzer: SignalContainer -> MatrixXd.
Plain-data description of the compute shader to dispatch.
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< double > period
Best lag in samples, zero when none qualified.
LagProfile autocorrelation
Autocorrelation of the mean-removed window divided by its lag 0 value, lags 0 to the longest searched...
std::vector< double > level_change
Level minus the previous window's level, zero for the first window.
std::vector< double > period_change
Relative change of the period since the previous window, zero unless both windows have one.
std::vector< std::pair< size_t, size_t > > window_positions
First and one past the last sample of each window.
std::vector< double > frequency
Sample rate over the best lag in Hz, zero when none qualified.
std::vector< double > harmonicity
Periodicity over one minus periodicity, finite, zero when none qualified.
std::vector< double > crest_factor
Peak over level, zero for a silent window.
LagProfile mean_difference
Mean absolute difference between samples a lag apart, lags over the searched range.
std::vector< double > level
Root mean square.
std::vector< double > crossing_rate
Sign changes per sample pair.
std::vector< double > peak
Largest absolute sample.
std::vector< double > dc_offset
Mean sample.
std::vector< double > periodicity
Normalised correlation at the best lag, zero when none qualified.
std::vector< double > values
The value selected by the method.
Waveform 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
uint32_t lag_count
Columns per window.
std::shared_ptr< Kakshya::TensorContainer > to_tensor(std::string name) const
The profile as a windows by lags float64 tensor.
uint32_t first_lag
Lag of the first column, in samples.
std::vector< double > values
Window major: window w, column c is values[w * lag_count + c].
One row of values per window, one column per consecutive lag.
Where the windows of a GPU pass sit in the value array.
The config structs an operation class accepts, declared as using supports.
A set of (device, runtime) pairs.
WaveformAnalyzerConfig config
Settings the analysis was produced under.
std::vector< ChannelWaveform > channels
Analysis result of a WaveformAnalyzer.
Reflect::EnumByte< WaveformMethod > method
Value reported as the output data, as a WaveformMethod value.
double low_frequency
Lowest repetition frequency searched, in Hz.
bool unbiased_periodicity
Report the strength of the chosen lag divided by the share of window pairs that lag has,...
double high_frequency
Highest repetition frequency searched, in Hz.
double sample_rate
Samples per second of the analysed signal.
bool native_float
Fallback: run the device passes in float32 instead of double.
bool keep_profiles
Keep the autocorrelation and mean difference profile of every window.
Settings of a WaveformAnalyzer.
std::unique_ptr< WordPairExecutionContext > context
One sequence a windowed kernel reads, and how its windows are laid out.
How many lanes share a window and how many sequences a kernel reads.