libdspl-2.0
Digital Signal Processing Algorithm Library
Analog and digital filter analysis.

Functions

int DSPL_API group_delay (double *pb, double *pa, int ord, int flag, double *w, int n, double *tau)
 Group delay calculation for digital or analog filter corresponds to \(H(s)\), or \(H(z)\) transfer function. More...
 
int DSPL_API filter_freq_resp (double *b, double *a, int ord, double *w, int n, int flag, double *mag, double *phi, double *tau)
 Magnitude, phase response and group delay vectors calculation for digital or analog filter corresponds to \(H(s)\), or \(H(z)\) transfer function. More...
 
int DSPL_API freqs (double *b, double *a, int ord, double *w, int n, complex_t *h)
 Analog filter frequency response \( H(j \omega) \) calculation. More...
 
int DSPL_API freqz (double *b, double *a, int ord, double *w, int n, complex_t *h)
 Function calculates the digital filter frequency response \( H \left(e^{j \omega} \right)\) corresponds to transfer function \(H(z)\). More...
 
int DSPL_API phase_delay (double *b, double *a, int ord, int flag, double *w, int n, double *tau)
 Phase delay calculation for digital or analog filter corresponds to \(H(s)\), or \(H(z)\) transfer function. More...
 

Detailed Description

This group describes the algorithm for calculation parameters for analog and digital filters: Magnitude, phase response, groupdelay, impulse response and other.

Function Documentation

◆ filter_freq_resp()

int filter_freq_resp ( double *  b,
double *  a,
int  ord,
double *  w,
int  n,
int  flag,
double *  mag,
double *  phi,
double *  tau 
)

Magnitude, phase response and group delay vectors calculation for digital or analog filter corresponds to \(H(s)\), or \(H(z)\) transfer function.


Parameters
[in]bPointer to the \( H(s) \) or \(H(z)\) transfer function numerator coefficients vector.
Vector size is [ord+1 x 1].

[in]aPointer to the \( H(s) \) or \(H(z)\) transfer function denominator coefficients vector.
Vector size is [ord+1 x 1].

[in]ordFilter order.
Transfer function \( H(s) \) or \(H(z)\) numerator and denominator coefficients number equals ord+1.

[in]wPointer to the angular frequency \( \omega \) (rad/s), which used for analog filter characteristics calculation (flag sets as DSPL_FLAG_ANALOG).
For digital filter (flag sets as DSPL_FLAG_DIGITAL), parameter w describes normalized frequency of frequency response \( H \left(\mathrm{e}^{j\omega} \right) \). Digital filter frequency response is \( 2\pi \)-periodic function, and vector w advisable to set from 0 to \( \pi \), or from 0 to \( 2\pi \), or from \( -\pi \) to \( \pi \). Vector size is [n x 1].

[in]nSize of frequency vector w.

[in]flagBinary flags to set calculation rules:
DSPL_FLAG_ANALOG  Coefficients corresponds to analog filter
DSPL_FLAG_DIGITAL Coefficients corresponds to digital filter
DSPL_FLAG_LOGMAG  Calculate magnitude in logarithmic scale (in dB) 
DSPL_FLAG_UNWRAP  Unwrap radian phases by adding multiples of 2*pi 
[out]magPointer to the filter magnitude vector.
Vector size is [n x 1].
If pointer is NULL, then magnitude will not calculted.

[out]phiPointer to the phase response vector.
Vector size is [n x 1].
If pointer is NULL, then phase response will not calculted.

[out]tauPointer to the group delay vector.
Vector size is [n x 1].
If pointer is NULL, then group delay will not calculted.

Returns
RES_OK if function is calculated successfully.
Else code error.

Example:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "dspl.h"
/* Filter order */
#define ORD 3
/* Frequency response vector size */
#define N 1000
int main(int argc, char* argv[])
{
void* hdspl; /* DSPL handle */
void* hplot; /* GNUPLOT handle */
/* Load DSPL functions */
hdspl = dspl_load();
double a[ORD+1]; /* H(s) numerator coefficients vector */
double b[ORD+1]; /* H(s) denominator coefficients vector */
double Rp = 1.0; /* Magnitude ripple from 0 to 1 rad/s */
double w[N]; /* Angular frequency (rad/s) */
double mag[N]; /* Filter Magnitude (dB) */
double phi[N]; /* Phase response */
double tau[N]; /* Group delay */
int k;
/* H(s) coefficients calculation */
int res = butter_ap(Rp, ORD, b, a);
if(res != RES_OK)
printf("error code = 0x%8x\n", res);
/* Print H(s) coefficients */
for(k = 0; k < ORD+1; k++)
printf("b[%2d] = %9.3f a[%2d] = %9.3f\n", k, b[k], k, a[k]);
/* Frequency in logarithmic scale from 0.01 to 100 rad/s */
logspace(-2.0, 2.0, N , DSPL_SYMMETRIC, w);
/* Filter frequency parameter calculation */
filter_freq_resp(b, a, ORD, w, N,
DSPL_FLAG_LOGMAG|DSPL_FLAG_UNWRAP|DSPL_FLAG_ANALOG,
mag, phi, tau);
/* Write Magnitude, phase response and group delay to the files */
writetxt(w, mag, N, "dat/butter_ap_test_mag.txt");
writetxt(w, phi, N, "dat/butter_ap_test_phi.txt");
writetxt(w, tau, N, "dat/butter_ap_test_tau.txt");
/* plotting by GNUPLOT */
gnuplot_create(argc, argv, 920, 260, "img/butter_ap_test.png", &hplot);
gnuplot_cmd(hplot, "set logscale x");
gnuplot_cmd(hplot, "unset key");
gnuplot_cmd(hplot, "set grid");
gnuplot_cmd(hplot, "set xlabel 'frequency, rad/s'");
gnuplot_cmd(hplot, "set multiplot layout 1,3 rowsfirst");
gnuplot_cmd(hplot, "set ylabel 'Magnitude, dB'");
gnuplot_cmd(hplot, "set yrange [-100:5]");
gnuplot_cmd(hplot, "plot 'dat/butter_ap_test_mag.txt' with lines");
gnuplot_cmd(hplot, "set ylabel 'Phase response, rad'");
gnuplot_cmd(hplot, "unset yrange");
gnuplot_cmd(hplot, "plot 'dat/butter_ap_test_phi.txt' with lines");
gnuplot_cmd(hplot, "set ylabel 'Groupdelay, sec'");
gnuplot_cmd(hplot, "unset yrange");
gnuplot_cmd(hplot, "plot 'dat/butter_ap_test_tau.txt' with lines");
gnuplot_cmd(hplot, "unset multiplot");
gnuplot_close(hplot);
/* free dspl handle */
dspl_free(hdspl);
return res;
}

Result:

b[ 0] =   1.002   a[ 0] =   1.002
b[ 1] =   0.000   a[ 1] =   2.618
b[ 2] =   0.000   a[ 2] =   3.418
b[ 3] =   0.000   a[ 3] =   2.615
b[ 4] =   0.000   a[ 4] =   1.000


In dat folder will be created 3 files:

butter_ap_test_mag.txt    magnitude
butter_ap_test_phi.txt    phase response
butter_ap_test_tau.txt    group delay

In addition, GNUPLOT will build the following graphs from data stored in files:

Author
Sergey Bakhurin www.dsplib.org

Definition at line 463 of file filter_an.c.

Referenced by phase_delay().

◆ freqs()

int freqs ( double *  b,
double *  a,
int  ord,
double *  w,
int  n,
complex_t h 
)

Analog filter frequency response \( H(j \omega) \) calculation.


Function calculates analog filter frequency response \( H(j \omega)\) corresponds to transfer function \( H(s) \):

\[ H(s) = \frac {\sum_{k = 0}^{N} b_k s^k} {\sum_{m = 0}^{N} a_m s^m}, \]

here \( N \) - filter order (equals to ord).

Parameters
[in]bPointer to the transfer function \( H(s) \) numerator coefficients vector.
Vector size is [ord+1 x 1].

[in]aPointer to the transfer function \( H(s) \) denominator coefficients vector.
Vector size is [ord+1 x 1].

[in]ordFilter order.
Transfer function \( H(s) \) numerator and denominator coefficients number equals ord+1.

[in]wPointer to the angular frequency \( \omega \) (rad/s), which used for frequency response \( H(j \omega) \) calculation.
Vector size is [n x 1].

[in]nThe size of the angular frequency vector w.

[out]hPointer to the frequency response vector \( H(j \omega) \), corresponds to angular frequency w.
Vector size is [n x 1].
Memory must be allocated.

Returns
RES_OK if frequency response vector is calculated successfully.
Else code error.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 659 of file filter_an.c.

Referenced by filter_freq_resp().

◆ freqz()

int freqz ( double *  b,
double *  a,
int  ord,
double *  w,
int  n,
complex_t h 
)

Function calculates the digital filter frequency response \( H \left(e^{j \omega} \right)\) corresponds to transfer function \(H(z)\).


Digital filter transfer function:

\[ H(z) = \frac{\sum\limits_{k = 0}^{N} b_k z^{-k}} {\sum\limits_{m = 0}^{N} a_m z^{-m}}, \]

here \(N\) — filter order (parameter ord).
Frequency response \( H \left(e^{j \omega} \right)\) we can get if substitute \(z = e^{j \omega} \).

Parameters
[in]bPointer to the \( H(z) \) transfer function numerator coefficients vector.
Vector size is [ord+1 x 1].

[in]aPointer to the \(H(z)\) transfer function denominator coefficients vector.
Vector size is [ord+1 x 1].

[in]ordFilter order.
Transfer function \(H(z)\) numerator and denominator coefficients number equals ord+1.

[in]wPointer to the normalized frequency of digital filter frequency response \( H \left(\mathrm{e}^{j\omega} \right) \).
Digital filter frequency response is \( 2\pi \)-periodic function, and vector w advisable to set from 0 to \( \pi \), or from 0 to \( 2\pi \), or from \( -\pi \) to \( \pi \). Vector size is [n x 1].

[in]nSize of frequency vector w.

[out]hPointer to the frequency response vector \( H \left(\mathrm{e}^{j\omega} \right) \), corresponds to normalized frequency w.
Vector size is [n x 1].
Memory must be allocated.

Returns
RES_OK if frequency response vector is calculated successfully.
Else code error.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 980 of file filter_an.c.

Referenced by filter_freq_resp().

◆ group_delay()

int DSPL_API group_delay ( double *  b,
double *  a,
int  ord,
int  flag,
double *  w,
int  n,
double *  tau 
)

Group delay calculation for digital or analog filter corresponds to \(H(s)\), or \(H(z)\) transfer function.


Group delay is describes as:

\[ \tau_g(\omega) = - \frac{d\Phi(\omega)}{d\omega}, \]

here \(\Phi(\omega)\) – filter phase response, \(\omega\) is angular frequency for analog filter, or normalized frequency for digital filter.

Parameters
[in]bPointer to the \( H(s) \) or \(H(z)\) transfer function numerator coefficients vector.
Vector size is [ord+1 x 1].

[in]aPointer to the \( H(s) \) or \(H(z)\) transfer function denominator coefficients vector.
Vector size is [ord+1 x 1].

[in]ordFilter order.
Transfer function \( H(s) \) or \(H(z)\) numerator and denominator coefficients number equals ord+1.

[in]flagBinary flags to set calculation rules:
DSPL_FLAG_ANALOG  Coefficients corresponds to analog filter
DSPL_FLAG_DIGITAL Coefficients corresponds to digital filter


[in]wPointer to the angular frequency \( \omega \) (rad/s), which used for analog filter characteristics calculation (flag sets as DSPL_FLAG_ANALOG).
For digital filter (flag sets as DSPL_FLAG_DIGITAL), parameter w describes normalized frequency of frequency response \( H \left(\mathrm{e}^{j\omega} \right) \). Digital filter frequency response is \( 2\pi \)-periodic function, and vector w advisable to set from 0 to \( \pi \), or from 0 to \( 2\pi \), or from \( -\pi \) to \( \pi \). Vector size is [n x 1].

[in]nSize of frequency vector w.

[out]tauPointer to the group delay vector.
Vector size is [n x 1].
Memory must be allocated.

Returns
RES_OK if function is calculated successfully.
Else code error.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 166 of file filter_an.c.

Referenced by filter_freq_resp().

◆ phase_delay()

int DSPL_API phase_delay ( double *  b,
double *  a,
int  ord,
int  flag,
double *  w,
int  n,
double *  tau 
)

Phase delay calculation for digital or analog filter corresponds to \(H(s)\), or \(H(z)\) transfer function.


Group delay is describes as:

\[ \tau_{\varphi}(\omega) = - \frac{\Phi(\omega)}{\omega}, \]

here \(\Phi(\omega)\) – filter phase response, \(\omega\) is angular frequency for analog filter, or normalized frequency for digital filter.

Parameters
[in]bPointer to the \( H(s) \) or \(H(z)\) transfer function numerator coefficients vector.
Vector size is [ord+1 x 1].

[in]aPointer to the \( H(s) \) or \(H(z)\) transfer function denominator coefficients vector.
Vector size is [ord+1 x 1].

[in]ordFilter order.
Transfer function \( H(s) \) or \(H(z)\) numerator and denominator coefficients number equals ord+1.

[in]flagBinary flags to set calculation rules:
DSPL_FLAG_ANALOG  Coefficients corresponds to analog filter
DSPL_FLAG_DIGITAL Coefficients corresponds to digital filter


[in]wPointer to the angular frequency \( \omega \) (rad/s), which used for analog filter characteristics calculation (flag sets as DSPL_FLAG_ANALOG).
For digital filter (flag sets as DSPL_FLAG_DIGITAL), parameter w describes normalized frequency of frequency response \( H \left(\mathrm{e}^{j\omega} \right) \). Digital filter frequency response is \( 2\pi \)-periodic function, and vector w advisable to set from 0 to \( \pi \), or from 0 to \( 2\pi \), or from \( -\pi \) to \( \pi \). Vector size is [n x 1].

[in]nSize of frequency vector w.

[out]tauPointer to the phase delay vector.
Vector size is [n x 1].
Memory must be allocated.

Returns
RES_OK if function is calculated successfully.
Else code error.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 1190 of file filter_an.c.

void DSPL_API gnuplot_close(void *h)
Close GNUPLOT handle.
Definition: gnuplot.c:325
int DSPL_API logspace(double x0, double x1, int n, int type, double *x)
Function fills a vector with n logarithmically spaced elements between and .
Definition: array.c:1224
void * dspl_load()
Perform dynamic linking and load libdspl-2.0 functions.
void DSPL_API gnuplot_cmd(void *h, char *cmd)
Function sends cmd command to GNUPLOT corresponds to h handle.
Definition: gnuplot.c:390
int DSPL_API butter_ap(double rp, int ord, double *b, double *a)
Function calculates the transfer function coefficients of analog normalized lowpass Butterworth filt...
Definition: filter_ap.c:174
int DSPL_API writetxt(double *x, double *y, int n, char *fn)
Save real data to the text file fn. .
Definition: inout.c:491
int DSPL_API filter_freq_resp(double *b, double *a, int ord, double *w, int n, int flag, double *mag, double *phi, double *tau)
Magnitude, phase response and group delay vectors calculation for digital or analog filter correspond...
Definition: filter_an.c:463
void dspl_free(void *handle)
Cleans up the previously linked DSPL-2.0 dynamic library.
#define RES_OK
The function completed correctly. No errors.
Definition: dspl.h:558
int DSPL_API gnuplot_create(int argc, char *argv[], int w, int h, char *fn_png, void **hplot)
Create GNUPLOT chart.
Definition: gnuplot.c:200