Crate idsp 

Embedded DSP algorithms

This crate contains some tuned DSP algorithms for general and especially embedded use. Many of the algorithms are implemented on integer (fixed point) datatypes.

One comprehensive user for these algorithms is Stabilizer.

Fixed point

Cosine/Sine

cossin() uses a small (128 element or 512 byte) LUT, smart octant (un)mapping, linear interpolation and comprehensive analysis of corner cases to achieve a very clean signal (4e-6 RMS error, 9e-6 max error, 108 dB SNR typ), low spurs, and no bias with about 40 cortex-m instruction per call. It computes both cosine and sine (i.e. the complex signal) at once given a phase input.

Two-argument arcus-tangens

atan2() returns a phase given a complex signal (a pair of in-phase/x/cosine and quadrature/y/sine). The RMS phase error is less than 5e-6 rad, max error is less than 1.2e-5 rad, i.e. 20.5 bit RMS, 19.1 bit max accuracy. The bias is minimal.

PLL, RPLL

PLL, RPLL: High accuracy, zero-assumption, fully robust, forward and reciprocal PLLs with dynamically adjustable time constant and arbitrary (in the Nyquist sampling sense) capture range, and noise shaping.

Unwrapper, Accu, saturating_scale()

Unwrapper, Accu, saturating_scale(): Tools to handle, track, and unwrap phase signals or generate them.

Float and Fixed point

IIR/Biquad

iir::Biquad and iir::BiquadClamp are fixed point (i8, i16, i32, i64) and floating point (f32, f64) biquad IIR filters. Robust and clean clipping and offset (anti-windup, no derivative kick, dynamically adjustable gains and gain limits) suitable for PID controller applications. Four kinds of filter action are supported for each Biquad: Direct Form 1, Direct Form 2 Transposed, Direct Form 1 with noise shaping, and Direct Form 1 with wide output. Coefficient sharing for multiple channels is implemented through dsp_process::SplitProcess, dsp_process::Channels.

Comparison

This is a rough feature comparison of several available biquad crates, with no claim for completeness, accuracy, or even fairness. TL;DR: idsp is slower but offers more features.

Feature\Crate	biquad-rs	fixed-filters	idsp::iir
Floating point f32/f64	✅	❌	✅
Fixed point i32	❌	✅	✅
Parametric fixed point i32	❌	✅	✅
Fixed point i8/i16/i64/i128	❌	❌	✅
DF2T	✅	❌	✅
Limiting/Clamping	❌	✅	✅
Fixed point accumulator guard bits	❌	❌	✅
Summing junction offset	❌	❌	✅
Fixed point noise shaping	❌	❌	✅
Wide output storage and feedback	❌	❌	✅
Configuration/state decoupling/multi-channel	❌	❌	✅
f32 parameter audio filter builder	✅	✅	✅
f64 parameter audio filter builder	✅	❌	✅
Q fixed point parameter audio filter builder	❌	❌	✅
Additional filter shapes (I/HO)	❌	❌	✅
f32 PI builder	❌	✅	✅
f32/f64 PI²D² builder	❌	❌	✅
Q fixed point PI²D² builder	❌	❌	✅
PI²D² builder limits	❌	❌	✅
Support for fixed point a1=-2 second order integrator	❌	❌	✅

Three crates have been compared when processing 4x1M samples (4 channels) with a biquad lowpass. Hardware was thumbv7em-none-eabihf, cortex-m7, code in ITCM, data in DTCM, caches enabled.

Crate	Type, features	Cycles per sample
biquad-rs	f32	11.4
idsp::iir	f32, limits, offset	15.5
fixed-filters	i32, limits	20.3
idsp::iir	i32, limits, offset	23.5
idsp::iir	i32, limits, offset, noise shaping	30.0

State variable, normal form, wave digital filter

iir::svf is a simple IIR state variable filter simultaneously providing highpass, lowpass, bandpass, and notch filtering of a signal. iir::normal is a Normal Form IIR filter for narrowband applications. iir::wdf has wave digital allpass filters that can be combined in a coupled dsp_process::Pair.

Lowpass, Lockin

Lowpass, Lockin are fast, infinitely cascadable, first- and second-order lowpass and the corresponding integration into a lockin amplifier algorithm.

FIR filters

hbf::HbfDec, hbf::HbfInt, hbf::HbfDec32, hbf::HbfInt32 etc: Fast f32 symmetric FIR filters, optimized half-band filters, half-band filter decimators and integators and cascades. These are used in stabilizer-stream for online PSD calculation for arbitrarily low offset frequencies.

Delta Sigma modulator/noise shaper

Dsm is a delta sigma modulator/noise shaper in MASH-(1)^K architecture.

Modules

hbf

Half-band filters and cascades

iir

IIR filters, coefficients and applications

Structs

Accu

Accumulator

AccuOsc

Accumulating oscillator

Cic

Cascaded integrator comb structure

ClampWrap

Maps wraps to saturation

Complex

A complex number in cartesian coordinates

Dsm

Delta-sigma modulator

Lockin

Lockin filter

Lowpass

Arbitrary order, high dynamic range, wide coefficient range, lowpass filter implementation. DC gain is 1.

LowpassState

Lowpass filter state

PLL

Type-II, sampled phase, discrete time PLL

RPLL

Reciprocal PLL.

RPLLConfig

RPLL configuration

Sweep

Exponential sweep

Unwrapper

Overflow unwrapper.

Enums

SweepError

Sweep parameter error

Wrap

Wrap classification

Constants

CORDIC_CIRCULAR_GAIN

Gain of cordic in circular mode.

CORDIC_HYPERBOLIC_GAIN

Gain of cordic in hyperbolic mode.

Traits

Clamp

Constants

Functions

atan2

2-argument arctangent function.

cos_sin

Returns F*(x*cos(z*PI) - y*sin(z*PI)), F*(x*sin(z*PI) + y*cos(z*PI))

cosh_sinh

Returns G*(x*cosh(z) + y*sinh(z)), G*(x*sinh(z) + y*cosh(z))

cossin

Compute the cosine and sine of an angle. This is ported from the MiSoC cossin core. https://github.com/m-labs/misoc/blob/master/misoc/cores/cossin.py

div

Returns x, z + y/x

mul

Returns x, y + x*z

overflowing_sub

Subtract y - x with signed overflow.

saturating_scale

Combine high and low i32 into a single downscaled i32, saturating monotonically.

sqrt_atan2

Returns F*sqrt(x**2 + y**2), z + atan2(y, x)/PI

sqrt_atanh2

Returns G*sqrt(x**2 - y**2), z + atanh2(y, x)

Type Aliases

Lowpass1

First order lowpass

Lowpass2

Second order lowpass