Detailed Description

Provides routines to manipulate ZPG filters.

Author: Creighton, T. D.

Synopsis

#include <lal/ZPGFilter.h>

The Header ZPGFilter.h provides routines for manipulating filters in the `‘zeros, poles, gain’' representation, which is typically the simplest way of representing a filter response. These routines create and destroy ZPG filters, and can transform the complex variable used to represent them.

This header covers routines that create, destroy, and transform objects of type <datatype>ZPGFilter, where <datatype> is either COMPLEX8 or COMPLEX16. Generically, these data types can be used to store any rational complex function in a factored form. Normally this function is a filter response, or "transfer function" \(T(z)\), expressed in terms of a complex frequency parameter \(z=\exp(2\pi if\Delta t)\), where \(\Delta t\) is the sampling interval. The rational function is factored as follows:

\[ T(f) = g\times\frac{\prod_k (z-a_k)}{\prod_l (z-b_l)} \]

where \(g\) is the gain, \(a_k\) are the (finite) zeros, and \(b_l\) are the (finite) poles. It should be noted that rational functions always have the same number of zeros as poles if one includes the point \(z=\infty\); any excess in the number of finite zeros or poles in the rational expression simply indicates that there is a corresponding pole or zero of that order at infinity. It is also worth pointing out that the "gain" is just the overall prefactor of this rational function, and is not necessarily equal to the actual gain of the transfer function at any particular frequency.

Another common complex frequency space is the \(w\)-space, obtained from the \(z\)-space by the bilinear transformation:

\[ w = i\left(\frac{1-z}{1+z}\right) = \tan(\pi f\Delta t) , \quad z = \frac{1+iw}{1-iw} \; . \]

Other variables can also be used to represent the complex frequency plane. The <datatype>ZPGFilter structure can be used to represent the transfer function in any of these spaces by transforming the coordinates of the zeros and poles, and incorporating any residual factors into the gain. Care must be taken to include any zeros or poles that are brought in from infinity by the transformation, and to remove any zeros or poles which were sent to infinity. Thus the number of zeros and poles of the <datatype>ZPGFilter is not necessarily constant under transformations! Routines invoking the <datatype>ZPGFilter data types should document which complex variable is assumed.

Modules
	Module CreateZPGFilter.c
	Creates ZPG filter objects.

	Module DestroyZPGFilter.c
	Destroys ZPG filter objects.

	Module BilinearTransform.c
	Transforms the complex frequency coordinate of a ZPG filter.

Error Codes
#define	ZPGFILTERH_ENUL 1
	Unexpected null pointer in arguments. More...

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

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

#define	ZPGFILTERH_EBAD 4
	Bad filter parameters. More...

Macro Definition Documentation

◆ ZPGFILTERH_ENUL

#define ZPGFILTERH_ENUL 1

Unexpected null pointer in arguments.

Definition at line 103 of file ZPGFilter.h.

◆ ZPGFILTERH_EOUT

#define ZPGFILTERH_EOUT 2

Output handle points to a non-null pointer.

Definition at line 104 of file ZPGFilter.h.

◆ ZPGFILTERH_EMEM

#define ZPGFILTERH_EMEM 3

Memory allocation error.

Definition at line 105 of file ZPGFilter.h.

◆ ZPGFILTERH_EBAD

#define ZPGFILTERH_EBAD 4

Bad filter parameters.

Definition at line 106 of file ZPGFilter.h.