LAL  7.4.1.1-f1ed79c

## Detailed Description

Provides routines to make and apply IIR filters.

### Synopsis

#include <lal/IIRFilter.h>

The Header IIRFilter.h provides routines for creating actual time-domain filters from the ZPG representation, and applying these filters to data.

This header covers routines that create, destroy, and apply generic time-domain filters, given by objects of type <datatype>IIRFilter, where <datatype> is either REAL4 or REAL8.

An IIR (Infinite Impulse Response) filter is a generalized linear causal time-domain filter, in which the filter output $$y_n=y(t_n)$$ at any sampled time $$t_n=t_0+n\Delta t$$ is a linear combination of the input $$x$$ and output $$y$$ at previous sampled times:

$y_n = \sum_{k=0}^M c_k x_{n-k} + \sum_{l=1}^N d_l y_{n-l} \; .$

The coefficients $$c_k$$ are called the direct filter coefficients, and the coefficients $$d_l$$ are the recursive filter coefficients. The filter order is the larger of $$M$$ or $$N$$, and determines how far back in time the filter must look to determine its next output. However, the recursive nature of the filter means that the output can depend on input arbitrarily far in the past; hence the name "infinite impulse response". Nonetheless, for a well-designed, stable filter, the actual filter response to an impulse should diminish rapidly beyond some characteristic timescale.

Note that nonrecursive FIR (Finite Impulse Response) filters are considered a subset of IIR filters, having $$N=0$$.

For practical implementation, it is convenient to express the bilinear equation above as two linear equations involving an auxiliary sequence $$w$$:

$w_n = x_n + \sum_{l=1}^N d_l w_{n-l} \; ,$

$y_n = \sum_{k=0}^M c_k w_{n-k} \; .$

The equivalence of this to the first expression is not obvious, but can be proven by mathematical induction. The advantage of the auxiliary variable representation is twofold. First, when one is feeding data point by point to the filter, the filter needs only "remember" the previous $$M$$ or $$N$$ (whichever is larger) values of $$w$$, rather than remembering the previous $$M$$ values of $$x$$ and the previous $$N$$ values of $$y$$. Second, when filtering a large stored data vector, the filter response can be computed in place: one first runs forward through the vector replacing $$x$$ with $$w$$, and then backward replacing $$w$$ with $$y$$.

Although the IIR filters in these routines are explicitly real, one can consider formally their complex response. A sinusoidal input can thus be written as $$x_n=X\exp(2\pi ifn\Delta t)=Xz^n$$, where $$X$$ is a complex amplitude and $$z=\exp(2\pi if\Delta t)$$ is a complex parametrization of the frequency. By linearity, the output must also be sinusoidal: $$y_m=Y\exp(2\pi ifm\Delta t)=Yz^m$$. Putting these into the bilinear equation, one can easily compute the filter's complex transfer function:

$T(z) = \frac{Y}{X} = \frac{\sum_{k=0}^M c_k z^{-k}} {1 - \sum_{l=1}^N d_l z^{-l}}$

This can be readily converted to and from the "zeros, poles, gain" representation of a filter, which expresses $$T(z)$$ as a factored rational function of $$z$$.

It should also be noted that, in the routines covered by this header, I have adopted the convention of including a redundant recursive coefficient $$d_0$$, in order to make the indexing more intuitive. For formal correctness $$d_0$$ should be set to $$-1$$, although the filtering routines never actually use this coefficient.

## Modules

Module CreateIIRFilter.c
Creates IIR filter objects.

Module DestroyIIRFilter.c
Destroys IIR filter objects.

Module IIRFilter.c
Computes an instant-by-instant IIR filter response.

Module IIRFilterVector.c
Applies an IIR filter to a data stream.

Module IIRFilterVectorR.c
Applies a time-reversed IIR filter to a data stream.

## Data Structures

struct  REAL4IIRFilter
This structure stores the direct and recursive REAL4 filter coefficients, as well as the history of the auxiliary sequence $$w$$. More...

struct  REAL8IIRFilter
This structure stores the direct and recursive REAL8 filter coefficients, as well as the history of the auxiliary sequence $$w$$. More...

struct  COMPLEX16IIRFilter
This structure stores the direct and recursive REAL8 filter coefficients, as well as the complex-valued history of the auxiliary sequence $$w$$. More...

## Files

file  IIRFilterTest.c
Tests the routines in Header IIRFilter.h.

## Error Codes

#define IIRFILTERH_ENUL   1
Unexpected null pointer in arguments. More...

#define IIRFILTERH_EOUT   2
Output handle points to a non-null pointer. More...

#define IIRFILTERH_EMEM   3
Memory allocation error. More...

#define IIRFILTERH_EPAIR   4
Input has unpaired nonreal poles or zeros. More...

## ◆ IIRFILTERH_ENUL

 #define IIRFILTERH_ENUL   1

Unexpected null pointer in arguments.

Definition at line 131 of file IIRFilter.h.

## ◆ IIRFILTERH_EOUT

 #define IIRFILTERH_EOUT   2

Output handle points to a non-null pointer.

Definition at line 132 of file IIRFilter.h.

## ◆ IIRFILTERH_EMEM

 #define IIRFILTERH_EMEM   3

Memory allocation error.

Definition at line 133 of file IIRFilter.h.

## ◆ IIRFILTERH_EPAIR

 #define IIRFILTERH_EPAIR   4

Input has unpaired nonreal poles or zeros.

Definition at line 134 of file IIRFilter.h.