BiquadFilter

class wpimath.BiquadFilter(sections: List[wpimath._wpimath.BiquadFilter.Section])

Bases: pybind11_object

This class implements a cascade of second-order IIR filter sections (biquads) in Direct Form II Transposed. It is intended for running higher-order filters (Butterworth, Chebyshev, etc.) produced by a filter designer without the numerical instability that direct-form implementations of a single high-order polynomial exhibit.

Each section implements: y[n] = b₀ x[n] + s₁[n-1] s₁[n] = b₁ x[n] - a₁ y[n] + s₂[n-1] s₂[n] = b₂ x[n] - a₂ y[n]

Sections are normalized so that a₀ = 1 and are applied in series.

For 1st-order IIR filters or simple FIR filters (moving averages, finite differences), prefer LinearFilter and its factory methods — they cover those cases more ergonomically. Use BiquadFilter for high-order IIR cascades.

Note: Calculate() should be called by the user on a known, regular period. Like any digital filter, the coefficients are a function of the sample rate they were designed for.

Creates a biquad filter cascade from the given sections.

Parameters:

sections – The biquad sections, applied in series. @throws std::runtime_error if sections is empty.

class Kind(value: SupportsInt | SupportsIndex)

Bases: pybind11_object

Frequency response shape for the classical IIR design factories. For BandPass/BandStop, two cutoff frequencies (f1, f2) are required.

Members:

LOW_PASS

HIGH_PASS

BAND_PASS

BAND_STOP

BAND_PASS = <Kind.BAND_PASS: 2>
BAND_STOP = <Kind.BAND_STOP: 3>
HIGH_PASS = <Kind.HIGH_PASS: 1>
LOW_PASS = <Kind.LOW_PASS: 0>
BiquadFilter.Kind.name -> str
property value
class Section(*args, **kwargs)

Bases: pybind11_object

A single biquad (second-order) section. a₀ is assumed normalized to 1.

Overloaded function.

  1. __init__(self: wpimath._wpimath.BiquadFilter.Section) -> None

  2. __init__(self: wpimath._wpimath.BiquadFilter.Section, b0: typing.SupportsFloat | typing.SupportsIndex, b1: typing.SupportsFloat | typing.SupportsIndex, b2: typing.SupportsFloat | typing.SupportsIndex, a1: typing.SupportsFloat | typing.SupportsIndex, a2: typing.SupportsFloat | typing.SupportsIndex) -> None

static butterworth(*args, **kwargs)

Overloaded function.

  1. butterworth(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, cutoff: wpimath.units.hertz) -> wpimath._wpimath.BiquadFilter

Designs a Butterworth IIR low-pass or high-pass filter (single cutoff).

Coefficients match @c scipy.signal.butter(order, Wn, btype, fs, output=’sos’) to within ~1e-10.

Parameters:

  • kind – Must be LowPass or HighPass.

  • order – Prototype order (>= 1).

  • sample_rate – Sample rate. Must be positive.

  • cutoff – Cutoff frequency. Must satisfy 0 < cutoff < sampleRate/2. @throws std::invalid_argument if any argument is out of range or @a kind is BandPass / BandStop.

  1. butterworth(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, low_cutoff: wpimath.units.hertz, high_cutoff: wpimath.units.hertz) -> wpimath._wpimath.BiquadFilter

Designs a Butterworth IIR band-pass or band-stop filter as a cascade of biquad sections.

BandPass/BandStop outputs are numerically equivalent to scipy but may differ in section ordering / zero pairing; the product response matches.

Parameters:

  • kind – Must be BandPass or BandStop.

  • order – Prototype order (>= 1). The resulting cascade has 2*order poles.

  • sample_rate – Sample rate. Must be positive.

  • low_cutoff – Low edge of the band. Must satisfy 0 < lowCutoff < highCutoff < sampleRate/2.

  • high_cutoff – High edge of the band. @throws std::invalid_argument if any argument is out of range or @a kind is LowPass / HighPass.

calculate(input: SupportsFloat | SupportsIndex) → float

Calculates the next value of the filter.

Parameters:

input – Current input value.

Returns:

The filtered value at this step.

static chebyshev_i(*args, **kwargs)

Overloaded function.

  1. chebyshev_i(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, low_cutoff: wpimath.units.hertz, high_cutoff: wpimath.units.hertz, ripple_db: typing.SupportsFloat | typing.SupportsIndex) -> wpimath._wpimath.BiquadFilter

Designs a Chebyshev type-I IIR filter as a cascade of biquad sections. Equiripple in the passband, monotonic in the stopband. Coefficients match @c scipy.signal.cheby1(order, rp, Wn, btype, fs, output=’sos’).

Parameters:

  • kind – Must be BandPass or BandStop.

  • order – Prototype order (>= 1). The cascade has 2*order poles.

  • sample_rate – Sample rate. Must be positive.

  • low_cutoff – Low edge of the band. Must satisfy 0 < lowCutoff < highCutoff < sampleRate/2.

  • high_cutoff – High edge of the band.

  • ripple_db – Peak-to-peak passband ripple in dB. Must be > 0; values from ~0.1 to ~3 dB are typical. @throws std::invalid_argument if any argument is out of range or @a kind is LowPass / HighPass.

  1. chebyshev_i(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, cutoff: wpimath.units.hertz, ripple_db: typing.SupportsFloat | typing.SupportsIndex) -> wpimath._wpimath.BiquadFilter

Designs a Chebyshev type-I IIR low-pass or high-pass filter (single cutoff). The cutoff is the frequency at which the response first drops to -rippleDb dB.

Parameters:

  • kind – Must be LowPass or HighPass.

  • order – Prototype order (>= 1).

  • sample_rate – Sample rate. Must be positive.

  • cutoff – Cutoff frequency. Must satisfy 0 < cutoff < sampleRate/2.

  • ripple_db – Peak-to-peak passband ripple in dB. Must be > 0. @throws std::invalid_argument if any argument is out of range or @a kind is BandPass / BandStop.

static chebyshev_ii(*args, **kwargs)

Overloaded function.

  1. chebyshev_ii(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, low_cutoff: wpimath.units.hertz, high_cutoff: wpimath.units.hertz, stop_atten_db: typing.SupportsFloat | typing.SupportsIndex) -> wpimath._wpimath.BiquadFilter

Designs a Chebyshev type-II (inverse Chebyshev) IIR filter as a cascade of biquad sections. Monotonic in the passband, equiripple in the stopband. Coefficients match @c scipy.signal.cheby2(order, rs, Wn, btype, fs, output=’sos’).

Parameters:

  • kind – Must be BandPass or BandStop.

  • order – Prototype order (>= 1). The cascade has 2*order poles.

  • sample_rate – Sample rate. Must be positive.

  • low_cutoff – Low edge of the stop band. Must satisfy 0 < lowCutoff < highCutoff < sampleRate/2.

  • high_cutoff – High edge of the stop band.

  • stop_atten_db – Stopband attenuation in dB. Must be > 0; values from ~20 to ~80 dB are typical. @throws std::invalid_argument if any argument is out of range or @a kind is LowPass / HighPass.

  1. chebyshev_ii(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, cutoff: wpimath.units.hertz, stop_atten_db: typing.SupportsFloat | typing.SupportsIndex) -> wpimath._wpimath.BiquadFilter

Designs a Chebyshev type-II IIR low-pass or high-pass filter (single cutoff). The cutoff is the frequency at which the response first reaches @a stopAttenDb of attenuation.

Parameters:

  • kind – Must be LowPass or HighPass.

  • order – Prototype order (>= 1).

  • sample_rate – Sample rate. Must be positive.

  • cutoff – Stopband-edge frequency. Must satisfy 0 < cutoff < sampleRate/2.

  • stop_atten_db – Stopband attenuation in dB. Must be > 0. @throws std::invalid_argument if any argument is out of range or @a kind is BandPass / BandStop.

static elliptic(*args, **kwargs)

Overloaded function.

  1. elliptic(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, low_cutoff: wpimath.units.hertz, high_cutoff: wpimath.units.hertz, ripple_db: typing.SupportsFloat | typing.SupportsIndex, stop_atten_db: typing.SupportsFloat | typing.SupportsIndex) -> wpimath._wpimath.BiquadFilter

Designs an elliptic (Cauer) IIR filter as a cascade of biquad sections. Equiripple in both passband and stopband — the steepest transition for a given order, at the cost of ripple everywhere. Coefficients match @c scipy.signal.ellip(order, rp, rs, Wn, btype, fs, output=’sos’).

Parameters:

  • kind – Must be BandPass or BandStop.

  • order – Filter order (>= 1).

  • sample_rate – Sample rate. Must be positive.

  • low_cutoff – Low edge of the band. Must satisfy 0 < lowCutoff < highCutoff < sampleRate/2.

  • high_cutoff – High edge of the band.

  • ripple_db – Passband ripple in dB (> 0).

  • stop_atten_db – Stopband attenuation in dB (must exceed @a rippleDb). @throws std::invalid_argument if any argument is out of range or @a kind is LowPass / HighPass.

  1. elliptic(kind: wpimath._wpimath.BiquadFilter.Kind, order: typing.SupportsInt | typing.SupportsIndex, sample_rate: wpimath.units.hertz, cutoff: wpimath.units.hertz, ripple_db: typing.SupportsFloat | typing.SupportsIndex, stop_atten_db: typing.SupportsFloat | typing.SupportsIndex) -> wpimath._wpimath.BiquadFilter

Designs an elliptic (Cauer) IIR low-pass or high-pass filter (single cutoff). The cutoff is the frequency at which the response first drops to -rippleDb dB.

Parameters:

  • kind – Must be LowPass or HighPass.

  • order – Filter order (>= 1).

  • sample_rate – Sample rate. Must be positive.

  • cutoff – Cutoff frequency. Must satisfy 0 < cutoff < sampleRate/2.

  • ripple_db – Passband ripple in dB (> 0).

  • stop_atten_db – Stopband attenuation in dB (must exceed @a rippleDb). @throws std::invalid_argument if any argument is out of range or @a kind is BandPass / BandStop.

last_value() → float

Returns the last value calculated by the BiquadFilter.

Returns:

The last value.

static moving_average(taps: SupportsInt | SupportsIndex) → wpimath._wpimath.BiquadFilter

Designs an N-tap moving-average filter as a cascade of FIR biquads.

Each section has a1 = a2 = 0 (all poles at the origin). The total gain 1/taps is folded into the first section’s numerator so the DC gain of the cascade is 1.

Parameters:

taps – Length of the moving-average window. Must be >= 1. @throws std::invalid_argument if taps < 1.

static notch(sample_rate: wpimath.units.hertz, center_frequency: wpimath.units.hertz, quality_factor: SupportsFloat | SupportsIndex) → wpimath._wpimath.BiquadFilter

Designs a second-order IIR notch at the given center frequency with the given quality factor. Matches @c scipy.signal.iirnotch.

Parameters:

  • sample_rate – Sample rate. Must be positive.

  • center_frequency – Notch center frequency. Must satisfy 0 < centerFrequency < sampleRate/2.

  • quality_factor – Quality factor (Q). Higher values give a narrower notch. Must be positive. @throws std::invalid_argument if any argument is out of range.

num_sections() → int

Returns the number of sections in the cascade.

Returns:

The number of sections.

reset(*args, **kwargs)

Overloaded function.

  1. reset(self: wpimath._wpimath.BiquadFilter) -> None

Resets the filter state to zero.

  1. reset(self: wpimath._wpimath.BiquadFilter, value: typing.SupportsFloat | typing.SupportsIndex) -> None

Resets the filter state so that subsequent calls to Calculate() with a constant input equal to value immediately return the filter’s steady-state response to that input.

Parameters:

value – The constant input value to seed with.

sections() → List[wpimath._wpimath.BiquadFilter.Section]

Returns a view over the cascade’s sections, in application order. Useful for inspection, logging, or serialization of designed filters.

Returns:

Span over the section list. Valid for the filter’s lifetime.