 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.

## ◆ 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] b Pointer to the $$H(s)$$ or $$H(z)$$ transfer function numerator coefficients vector. Vector size is [ord+1 x 1]. [in] a Pointer to the $$H(s)$$ or $$H(z)$$ transfer function denominator coefficients vector. Vector size is [ord+1 x 1]. [in] ord Filter order. Transfer function $$H(s)$$ or $$H(z)$$ numerator and denominator coefficients number equals ord+1. [in] w Pointer 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] n Size of frequency vector w. [in] flag Binary 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] mag Pointer to the filter magnitude vector. Vector size is [n x 1]. If pointer is NULL, then magnitude will not calculted. [out] phi Pointer to the phase response vector. Vector size is [n x 1]. If pointer is NULL, then phase response will not calculted. [out] tau Pointer 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 */
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 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: 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] b Pointer to the transfer function $$H(s)$$ numerator coefficients vector. Vector size is [ord+1 x 1]. [in] a Pointer to the transfer function $$H(s)$$ denominator coefficients vector. Vector size is [ord+1 x 1]. [in] ord Filter order. Transfer function $$H(s)$$ numerator and denominator coefficients number equals ord+1. [in] w Pointer to the angular frequency $$\omega$$ (rad/s), which used for frequency response $$H(j \omega)$$ calculation. Vector size is [n x 1]. [in] n The size of the angular frequency vector w. [out] h Pointer 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.

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] b Pointer to the $$H(z)$$ transfer function numerator coefficients vector. Vector size is [ord+1 x 1]. [in] a Pointer to the $$H(z)$$ transfer function denominator coefficients vector. Vector size is [ord+1 x 1]. [in] ord Filter order. Transfer function $$H(z)$$ numerator and denominator coefficients number equals ord+1. [in] w Pointer 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] n Size of frequency vector w. [out] h Pointer 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.

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] b Pointer to the $$H(s)$$ or $$H(z)$$ transfer function numerator coefficients vector. Vector size is [ord+1 x 1]. [in] a Pointer to the $$H(s)$$ or $$H(z)$$ transfer function denominator coefficients vector. Vector size is [ord+1 x 1]. [in] ord Filter order. Transfer function $$H(s)$$ or $$H(z)$$ numerator and denominator coefficients number equals ord+1. [in] flag Binary flags to set calculation rules: DSPL_FLAG_ANALOG Coefficients corresponds to analog filter DSPL_FLAG_DIGITAL Coefficients corresponds to digital filter  [in] w Pointer 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] n Size of frequency vector w. [out] tau Pointer 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.

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] b Pointer to the $$H(s)$$ or $$H(z)$$ transfer function numerator coefficients vector. Vector size is [ord+1 x 1]. [in] a Pointer to the $$H(s)$$ or $$H(z)$$ transfer function denominator coefficients vector. Vector size is [ord+1 x 1]. [in] ord Filter order. Transfer function $$H(s)$$ or $$H(z)$$ numerator and denominator coefficients number equals ord+1. [in] flag Binary flags to set calculation rules: DSPL_FLAG_ANALOG Coefficients corresponds to analog filter DSPL_FLAG_DIGITAL Coefficients corresponds to digital filter  [in] w Pointer 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] n Size of frequency vector w. [out] tau Pointer 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.

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_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