Struct Biquad 

pub struct Biquad<T> { /* private fields */ }

A single second-order section (biquad) filter using Direct Form II Transposed.

Transfer function:

H(z) = (b0 + b1·z⁻¹ + b2·z⁻²) / (1 + a1·z⁻¹ + a2·z⁻²)

The denominator is stored normalized so a[0] = 1.

Implementations

impl<T: FloatScalar> Biquad<T>

pub fn new(b: [T; 3], a: [T; 3]) -> Self

Create a new biquad from numerator b and denominator a coefficients.

Normalizes by a[0] so the stored a[0] is always 1.

Example

use numeris::control::Biquad;

let bq = Biquad::new([1.0, 2.0, 1.0], [1.0, -0.5, 0.1]);
let (b, a) = bq.coefficients();
assert_eq!(a[0], 1.0);

pub fn try_new(b: [T; 3], a: [T; 3]) -> Result<Self, ControlError>

Fallible constructor: returns Err(ControlError::NearZeroDenominator) if a[0].abs() < 2 * T::epsilon().

Example

use numeris::control::Biquad;

let bq = Biquad::try_new([1.0_f64, 2.0, 1.0], [1.0, -0.5, 0.1]).unwrap();
assert!(Biquad::try_new([1.0_f64, 0.0, 0.0], [0.0, 0.0, 0.0]).is_err());

pub fn passthrough() -> Self

Identity (passthrough) filter: output equals input.

pub fn tick(&mut self, x: T) -> T

Process a single input sample, returning the filtered output.

Uses Direct Form II Transposed for numerical stability.

pub fn reset(&mut self)

Reset internal state to zero.

pub fn process(&mut self, input: &[T], output: &mut [T])

Process a slice of input samples into an output slice.

Panics

Panics if output.len() < input.len().

pub fn process_inplace(&mut self, data: &mut [T])

Process a slice of samples in-place.

pub fn coefficients(&self) -> ([T; 3], [T; 3])

Return the (b, a) coefficient arrays.

Examples found in repository

docs/examples/gen_plots.rs (line 271)

fn biquad_cascade_freq_response<const N: usize>(
    cascade: &BiquadCascade<f64, N>,
    freq: f64,
    fs: f64,
) -> f64 {
    let omega = 2.0 * PI * freq / fs;
    let (sin_w, cos_w) = omega.sin_cos();
    let cos_2w = 2.0 * cos_w * cos_w - 1.0;
    let sin_2w = 2.0 * sin_w * cos_w;

    let mut mag_sq = 1.0;
    for section in &cascade.sections {
        let (b, a) = section.coefficients();
        let nr = b[0] + b[1] * cos_w + b[2] * cos_2w;
        let ni = -b[1] * sin_w - b[2] * sin_2w;
        let dr = a[0] + a[1] * cos_w + a[2] * cos_2w;
        let di = -a[1] * sin_w - a[2] * sin_2w;
        mag_sq *= (nr * nr + ni * ni) / (dr * dr + di * di);
    }
    mag_sq.sqrt()
}

fn make_control_plot() -> String {
    let fs = 8000.0;
    let fc = 1000.0;

    let bw2: BiquadCascade<f64, 1> = butterworth_lowpass(2, fc, fs).unwrap();
    let bw4: BiquadCascade<f64, 2> = butterworth_lowpass(4, fc, fs).unwrap();
    let bw6: BiquadCascade<f64, 3> = butterworth_lowpass(6, fc, fs).unwrap();

    const N: usize = 500;
    let mut freqs = vec![0.0; N];
    let mut db2 = vec![0.0; N];
    let mut db4 = vec![0.0; N];
    let mut db6 = vec![0.0; N];

    let f_min: f64 = 10.0;
    let f_max: f64 = 3900.0;
    for i in 0..N {
        let f = f_min * (f_max / f_min).powf(i as f64 / (N - 1) as f64);
        freqs[i] = f;
        db2[i] = 20.0 * biquad_cascade_freq_response(&bw2, f, fs).log10();
        db4[i] = 20.0 * biquad_cascade_freq_response(&bw4, f, fs).log10();
        db6[i] = 20.0 * biquad_cascade_freq_response(&bw6, f, fs).log10();
    }

    let traces = format!(
        "[{{\"type\":\"scatter\",\"mode\":\"lines\",\"name\":\"2nd order\",\
          \"x\":{},\"y\":{},\"line\":{{\"width\":2.5}}}},\
         {{\"type\":\"scatter\",\"mode\":\"lines\",\"name\":\"4th order\",\
          \"x\":{},\"y\":{},\"line\":{{\"width\":2.5}}}},\
         {{\"type\":\"scatter\",\"mode\":\"lines\",\"name\":\"6th order\",\
          \"x\":{},\"y\":{},\"line\":{{\"width\":2.5}}}}]",
        fmt_arr(&freqs), fmt_arr(&db2),
        fmt_arr(&freqs), fmt_arr(&db4),
        fmt_arr(&freqs), fmt_arr(&db6),
    );

    let layout = decorate_layout_ex(
        "Butterworth Lowpass — f<sub>c</sub> = 1 kHz, f<sub>s</sub> = 8 kHz",
        "Frequency (Hz)",
        ",\"type\":\"log\"",
        "Magnitude (dB)",
        ",\"range\":[-80,5]",
        &format!(
            ",\"shapes\":[{{\"type\":\"line\",\"x0\":{f_min},\"x1\":{f_max},\
             \"y0\":-3,\"y1\":-3,\"line\":{{\"dash\":\"dot\",\"color\":\"rgba(160,80,80,0.5)\",\"width\":1.5}}}}]"
        ),
    );

    plotly_snippet("plot-control", &traces, &layout, 420)
}

// ─── Control: Lead/Lag compensator Bode ───────────────────────────────────

fn biquad_freq_response(b: &[f64; 3], a: &[f64; 3], freq: f64, fs: f64) -> (f64, f64) {
    let omega = 2.0 * PI * freq / fs;
    let (sin_w, cos_w) = omega.sin_cos();
    let cos_2w = 2.0 * cos_w * cos_w - 1.0;
    let sin_2w = 2.0 * sin_w * cos_w;
    let nr = b[0] + b[1] * cos_w + b[2] * cos_2w;
    let ni = -b[1] * sin_w - b[2] * sin_2w;
    let dr = a[0] + a[1] * cos_w + a[2] * cos_2w;
    let di = -a[1] * sin_w - a[2] * sin_2w;
    let mag = ((nr * nr + ni * ni) / (dr * dr + di * di)).sqrt();
    let phase = (ni.atan2(nr) - di.atan2(dr)).to_degrees();
    (mag, phase)
}

fn make_lead_lag_plot() -> String {
    let fs = 1000.0;
    let lead = lead_compensator(std::f64::consts::FRAC_PI_4, 50.0, 1.0, fs).unwrap();
    let lag = lag_compensator(10.0, 5.0, fs).unwrap();

    let (b_lead, a_lead) = lead.coefficients();
    let (b_lag, a_lag) = lag.coefficients();

    const N: usize = 400;
    let f_min: f64 = 0.1;
    let f_max: f64 = 490.0;
    let mut freqs = vec![0.0; N];
    let mut lead_db = vec![0.0; N];
    let mut lead_ph = vec![0.0; N];
    let mut lag_db = vec![0.0; N];
    let mut lag_ph = vec![0.0; N];

    for i in 0..N {
        let f = f_min * (f_max / f_min).powf(i as f64 / (N - 1) as f64);
        freqs[i] = f;
        let (m, p) = biquad_freq_response(&b_lead, &a_lead, f, fs);
        lead_db[i] = 20.0 * m.log10();
        lead_ph[i] = p;
        let (m, p) = biquad_freq_response(&b_lag, &a_lag, f, fs);
        lag_db[i] = 20.0 * m.log10();
        lag_ph[i] = p;
    }

    // Magnitude plot
    let traces_mag = format!(
        "[{{\"type\":\"scatter\",\"mode\":\"lines\",\"name\":\"Lead (45° @ 50 Hz)\",\
          \"x\":{},\"y\":{},\"line\":{{\"width\":2.5}}}},\
         {{\"type\":\"scatter\",\"mode\":\"lines\",\"name\":\"Lag (10× DC @ 5 Hz)\",\
          \"x\":{},\"y\":{},\"line\":{{\"width\":2.5}}}}]",
        fmt_arr(&freqs), fmt_arr(&lead_db),
        fmt_arr(&freqs), fmt_arr(&lag_db),
    );
    let layout_mag = decorate_layout_ex(
        "Lead / Lag Compensators — Magnitude",
        "Frequency (Hz)",
        ",\"type\":\"log\"",
        "Magnitude (dB)",
        "",
        "",
    );

    // Phase plot
    let traces_ph = format!(
        "[{{\"type\":\"scatter\",\"mode\":\"lines\",\"name\":\"Lead phase\",\
          \"x\":{},\"y\":{},\"line\":{{\"width\":2.5}}}},\
         {{\"type\":\"scatter\",\"mode\":\"lines\",\"name\":\"Lag phase\",\
          \"x\":{},\"y\":{},\"line\":{{\"width\":2.5}}}}]",
        fmt_arr(&freqs), fmt_arr(&lead_ph),
        fmt_arr(&freqs), fmt_arr(&lag_ph),
    );
    let layout_ph = decorate_layout_ex(
        "Lead / Lag Compensators — Phase",
        "Frequency (Hz)",
        ",\"type\":\"log\"",
        "Phase (°)",
        "",
        "",
    );

    let mut html = plotly_snippet("plot-lead-lag-mag", &traces_mag, &layout_mag, 380);
    html.push_str(&plotly_snippet(
        "plot-lead-lag-phase",
        &traces_ph,
        &layout_ph,
        380,
    ));
    html
}

Trait Implementations

impl<T: Clone> Clone for Biquad<T>

fn clone(&self) -> Biquad<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Biquad<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Copy> Copy for Biquad<T>