Crate harmos_signal

Expand description

Signal processing over plain &[f64]: the transform, the reductions, the readings, and the one mergeable accumulator.

Every name here is a kernel. Nothing owns your data, nothing is shared, nothing is locked, and nothing is cached: a function takes the slices you already have and answers a value, a Vec, or — for anything that selects samples — the indices it selected, so the caller reads its own columns. That is the whole design rule, and it is what lets two applications with two different series types share one implementation of the mathematics.

This crate depends on rustfft and std, and on nothing else. It does not depend on harmos, and it must not: a runtime’s read path stays free of algorithms, and this crate stays liftable into a repository of its own unchanged.

This is measurement math and not a data engine. Everything here computes a property of a signal — a spectrum, an envelope, a crossing, a reduction, a calibrated conversion — and nothing here arranges data: tables, joins, group-by, lazy pipelines, generic aggregation frameworks, and columnar containers are a DataFrame’s work, which meti left behind to arrive at exactly this content. An application that needs relational row manipulation reaches for a DataFrame of its own, above the runtime’s algorithm-free reads.

use harmos_signal::{Summary, Taper, transform};

let rate = 1_000.0;
let samples: Vec<f64> = (0..1_000)
    .map(|i| (std::f64::consts::TAU * 50.0 * f64::from(i) / rate).sin())
    .collect();

// The RMS of a unit sine is one over root two, whichever way it is measured.
let summary = Summary::of(&samples);
assert!((summary.rms().unwrap() - 1.0 / 2.0_f64.sqrt()).abs() < 1e-3);

// And the tone reads its own amplitude off the bin it lands on.
let spectrum = transform(&samples, rate, Taper::Rectangular);
let magnitude = harmos_signal::magnitude(&spectrum.real, &spectrum.imag);
assert!((magnitude[50] - 1.0).abs() < 1e-9);

Structs§

Decibel: A decibel scale: dB = factor · log10(linear / reference).
Edge: One transition of a waveform through its trigger, at an interpolated coordinate.
Estimate: One averaged spectral estimate: a bin step, and a magnitude per bin.
Spectrum: One single-window transform: a bin step, and a complex amplitude per bin.
Summary: The statistics of a run of samples, as accumulators that merge.
Welch: Welch’s method: what resolution to estimate at, and how hard to average.

Enums§

Band: A frequency-domain window: which bins survive a reconstruction, and how sharply the surviving band ends.
Scale: What a column of numbers means: base units, decibels against a reference, or a bare decibel difference.
Taper: A window function applied to samples before the forward transform.

Functions§

above_floor: Keeps the samples within db_below_peak decibels of the largest one.
band_energy: The energy of one band, by Parseval: Σ |X|² · df.
band_rms: The RMS amplitude of one band: sqrt(energy / bandwidth).
bins: The frequency axis of count bins spaced step Hz apart, in Hz.
centroid: The spectral centroid of one band: its centre of energy, in Hz.
crossing: The coordinate at which the waveform first reaches target.
decimate: Keeps every nth index of a run of length, for at most count of them.
derivative: The derivative of y with respect to x, sample for sample.
edges: Every edge a waveform makes through a two-level trigger.
extrema: Keeps the lowest and highest sample of each of buckets equal spans.
fundamental: The bin of the fundamental: the strongest peak that is not DC.
harmonics: The peaks at or above fraction of the strongest one, in bin order.
integral: The cumulative integral of y over x by the trapezoidal rule.
lttb: Thins (x, y) to count samples by largest-triangle-three-buckets.
lttb_log: Thins (x, y) to at most count samples with logarithmically spaced buckets.
magnitude: The magnitude of each bin: hypot(real, imag).
nearest: The index of the sample nearest at, when there is one.
occupied_bandwidth: The narrowest span of the band holding fraction of its energy.
papr: The peak-to-average power ratio of one band, as a linear ratio.
peaks: The bins that are local maxima, strongest first.
phase: The phase of each bin in radians, -π..=π.
reconstruct: Reconstructs real samples from a spectrum, optionally keeping one band.
resample: The waveform read at each coordinate of at.
resample_count: The run stretched or squeezed to exactly count samples.
resample_uniform: The waveform read onto a uniform grid of step, spanning what it covers.
rolloff: The frequency beneath which fraction of the band’s energy lies, in Hz.
thd: Total harmonic distortion as a percentage of the fundamental.
transform: Transforms real samples into one single-window spectrum.
value_at: The value at at, linearly interpolated between the samples bracketing it.