IIRFilters::ButterFilter Function

IIRFilters Namespace

Overload List

#SignatureDescription
1double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TVec *z, TVec *p, double &k, TIirFrequencyTransform IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalog);Design a complete Butterworth IIR filter of the given Order, cutoff(s) CutoffFreq and band type FilterType, returning the transfer function in zero-pole form (z, p, k): H(z)=k (prod_i (z-z_i))/(prod_i (z-p_i)). Set Analog=True for an s-plane design or Analog=False for a z-plane (digital) design; for a digital design CutoffFreq lies in $(0,1)$ with sampling frequency 2 (so 1 = Nyquist). FilterType is lp/hp (1 cutoff) or bp/bs (2 cutoffs); a bandpass/bandstop design has twice the prototype order. IirFrequencyTransform selects when the frequency-band transform is applied (state-space-analog, zero-pole-analog or zero-pole-discrete). Digital poles satisfy |p_i|<1 (stable). The function result is the natural 3 dB cutoff W_c. The other overloads return the same filter as num/den (ba), second-order sections (sos) or state space (A,B,C,D). NOTE: a digital cutoff outside $(0,1)$ is NOT range-checked and yields a degenerate filter.
2double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TVec *Num, TVec *Den, TIirFrequencyTransform IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalog);The resulting transfer function is returned in the numerator/denumerator form with num and den.
3double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TVec *sos, TIirFrequencyTransform IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalog);The resulting transfer function is returned in the second order section form stored in the sos variable.
4double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TMtx *A, TVec *B, TVec *C, double &d);The resulting transfer function is returned in the state-space form with A,B,C,D variables.

Overload 1: double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TVec *z, TVec *p, double &k, TIirFrequencyTransform IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalog);

Design a complete Butterworth IIR filter of the given Order, cutoff(s) CutoffFreq and band type FilterType, returning the transfer function in zero-pole form (z, p, k): H(z)=k (prod_i (z-z_i))/(prod_i (z-p_i)). Set Analog=True for an s-plane design or Analog=False for a z-plane (digital) design; for a digital design CutoffFreq lies in (0,1)(0,1) with sampling frequency 2 (so 1 = Nyquist). FilterType is lp/hp (1 cutoff) or bp/bs (2 cutoffs); a bandpass/bandstop design has twice the prototype order. IirFrequencyTransform selects when the frequency-band transform is applied (state-space-analog, zero-pole-analog or zero-pole-discrete). Digital poles satisfy |p_i|<1 (stable). The function result is the natural 3 dB cutoff W_c. The other overloads return the same filter as num/den (ba), second-order sections (sos) or state space (A,B,C,D). NOTE: a digital cutoff outside (0,1)(0,1) is NOT range-checked and yields a degenerate filter.

#NameTypeDescription
1Orderint
2CutoffFreqconst DewArray<double> &
3FilterTypeTFilterType
4Analogbool
5zTVec *
6pTVec *
7kdouble &
8IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalogTIirFrequencyTransform
Remarks:

Design Butterworth filter of Order with CutoffFreq frequencies and of FilterType type. Set Analog to True, to request and analog filter design in s-plane or set it to false to obtain a digital filter design in z-plane. The CutoffFreq must be in range between 0 and 1 (Sampling frequency = 2) in case of a digital filter design.

IIrFrequencyTransform specifies when and how will the frequency band transformation be applied. The resulting transfer function is returned in the zero-pole form, with z,p,k variables.

Examples
#include "MtxExpr.h"
#include "Units.IIrFilters.h"
#include "Units.SignalUtils.h"

using namespace Dew;
using namespace Dew::Math;
using namespace Dew::Signal;
using namespace Dew::Signal::Units::IIRFilters;
using namespace Dew::Signal::Units::SignalUtils;

void Example()
{
    Vector z, p, num, den, FreqFr, Response;
    int Order;
    double k, Bw, Wc;
    DewArray<double> WcArray; //modified 3dB frequency

    WcArray.SetLength(2);
    Order = ButterOrder(DewArray<double>{0.2, 0.3, 0.6, 0.7}, 0.2, 50, TFilterType::ftBandstop, WcArray);
    ButterFilter(Order, WcArray, TFilterType::ftBandstop, false, num, den);

    // Alternative 1. Specify the order and the 3 dB frequencies explicitely:
    //
    //     ButterFilter(5, DewArray<double>{0.2, 0.7}, TFilterType::ftBandstop, false, num, den);


    // Alternative 2. Specifying the 3 dB frequencies explicitely
    // will result in 3 dB ripple (and not 0.2 as requested) in the passband,
    // but one coulde always move the 3 dB frequencies a little:
    //
    //     ButterFilter(5, DewArray<double>{0.22, 0.68}, TFilterType::ftBandstop, false, num, den);

    // Alternative 3. Specifying the order explicitely
    // will not ensure 50 dB attenuation in the edges of the stopband,
    // but one can increase filter order:
    //
    //     ButterFilter(10, DewArray<double>{0.22, 0.68}, TFilterType::ftBandstop, false, num, den);

    FrequencyResponse(num, den, Response, 64);
}
Declared in Dew::Signal::Units::IIRFilters · Dew.Signal/Units.IIrFilters.h · Cross-compiler

Overload 2: double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TVec *Num, TVec *Den, TIirFrequencyTransform IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalog);

The resulting transfer function is returned in the numerator/denumerator form with num and den.

#NameTypeDescription
1Orderint
2CutoffFreqconst DewArray<double> &
3FilterTypeTFilterType
4Analogbool
5NumTVec *
6DenTVec *
7IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalogTIirFrequencyTransform
Declared in Dew::Signal::Units::IIRFilters · Dew.Signal/Units.IIrFilters.h · Cross-compiler

Overload 3: double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TVec *sos, TIirFrequencyTransform IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalog);

The resulting transfer function is returned in the second order section form stored in the sos variable.

#NameTypeDescription
1Orderint
2CutoffFreqconst DewArray<double> &
3FilterTypeTFilterType
4Analogbool
5sosTVec *
6IirFrequencyTransform = TIirFrequencyTransform::ftStateSpaceAnalogTIirFrequencyTransform
Remarks:

The sos variable can be passed directly to the IirInitBQ filter initialization routine. Second order section form delivers substantially higher numerical stability and range than filtering with num/den form which is used by the IirInit routine.

Declared in Dew::Signal::Units::IIRFilters · Dew.Signal/Units.IIrFilters.h · Cross-compiler

Overload 4: double ButterFilter(int Order, const DewArray<double> &CutoffFreq, TFilterType FilterType, bool Analog, TMtx *A, TVec *B, TVec *C, double &d);

The resulting transfer function is returned in the state-space form with A,B,C,D variables.

#NameTypeDescription
1Orderint
2CutoffFreqconst DewArray<double> &
3FilterTypeTFilterType
4Analogbool
5ATMtx *
6BTVec *
7CTVec *
8ddouble &
Examples
#include "MtxExpr.h"
#include "Units.IIrFilters.h"
#include "Units.SignalUtils.h"

using namespace Dew;
using namespace Dew::Math;
using namespace Dew::Signal;
using namespace Dew::Signal::Units::IIRFilters;
using namespace Dew::Signal::Units::SignalUtils;

void Example()
{
    Vector z(0);
    Vector p(0);
    Vector num(0);
    Vector den(0);
    Vector Response(0);
    Vector FreqFr(0);
    DewArray<double> WcArray(2);
    int Order; //design a fifth order filter.

    Order = ButterOrder(DewArray<double>{0.2, 0.3, 0.6, 0.7}, 0.2, 50, TFilterType::ftBandstop, WcArray, false);  //design analog protype
    ButterFilter(Order, WcArray, TFilterType::ftBandstop, false, num, den, TIirFrequencyTransform::ftStateSpaceAnalog);

    // Alternative 1. Specify the order and the 3 dB frequencies explicitely:
    //
    //     ButterFilter(5, DewArray<double>{0.2, 0.7}, TFilterType::ftBandstop, false, num, den, TIirFrequencyTransform::ftStateSpaceAnalog);


    // Alternative 2. Specifying the 3 dB frequencies explicitely
    // will result in 3 dB ripple (and not 0.2 as requested) in the passband,
    // but one coulde always move the 3 dB frequencies a little:
    //
    //     ButterFilter(5, DewArray<double>{0.22, 0.68}, TFilterType::ftBandstop, false, num, den, TIirFrequencyTransform::ftStateSpaceAnalog);

    // Alternative 3. Specifying the order explicitely
    // will not ensure 50 dB attenuation in the edges of the stopband,
    // but one can increase filter order:
    //
    //     ButterFilter(10, DewArray<double>{0.22, 0.68}, TFilterType::ftBandstop, false, num, den, TIirFrequencyTransform::ftStateSpaceAnalog);

    FrequencyResponse(num, den, Response, 32, false, TSignalWindowType::wtRectangular, 0);
}
See Also: IIRFilters::ButterOrder, IIRFilters::ChebyshevIFilter, IIRFilters::ChebyshevIIFilter, IIRFilters::EllipticFilter, IIRFilters::BesselFilter
Declared in Dew::Signal::Units::IIRFilters · Dew.Signal/Units.IIrFilters.h · Cross-compiler