Module CreateIIRFilter.c

Detailed Description

Creates IIR filter objects.

Author

Creighton, T. D.

Description

These functions create an object **output of type <datatype>IIRFilter, where <datatype> is REAL4 or REAL8. The filter coefficients are computed from the zeroes, poles, and gain of an input object *input of type COMPLEX8ZPGFilter or COMPLEX16ZPGFilter, respectively; the sampling time interval is taken directly from input->deltaT. The ZPG filter should express the factored transfer function in the \(z=\exp(2\pi if)\) plane. Initially the output handle must be a valid handle (output \(\neq\)NULL) but should not point to an existing object (*output=NULL)

Algorithm

An IIR filter is a real time-domain filter, which imposes certain constraints on the zeros, poles, and gain of the filter transfer function. The function Create<datatype>IIRFilter() deals with the constraints either by aborting if they are not met, or by adjusting the filter response so that they are met. In the latter case, warning messages will be issued if the external parameter lalDebugLevel is set to allow such messages. The specific constraints, and how they are dealt with, are as follows:

First, the filter must be causal; that is, the output at any time can be generated entirely from the input at previous times. In practice this means that the number of (finite) poles in the \(z\) plane must equal or exceed the number of (finite) zeros. If this is not the case, Create<datatype>IIRFilter() will add additional poles at \(z=0\). Effectively this is just adding a delay to the filter response in order to make it causal.

Second, the filter should be stable, which means that all poles should be located on or within the circle \(|z|=1\). This is not enforced by Create<datatype>IIRFilter(), which can be used to make unstable filters; however, warnings will be issued. (In some sense the first condition is a special case of this one, since a transfer function with more zeros than poles actually has corresponding poles at infinity.)

Third, the filter must be physically realizable; that is, the transfer function should expand to a rational function of \(z\) with real coefficients. Necessary and sufficient conditions for this are that the gain be real, and that all zeros and poles either be real or come in complex conjugate pairs. The routine Create<datatype>IIRFilter() enforces this by using only the real part of the gain, and only the real or positive-imaginary zeros and poles; it assumes that the latter are paired with negative-imaginary conjugates. The routine will abort if this assumption results in a change in the given number of zeros or poles. If lalDebugLevel is set to allow warnings, the routine will actually check to see that each pair of nonreal poles or zeros are in fact complex conjugates, and will issue a warning if an unmatched pair is detected; however, the algorithm will then simply proceed as if the negative-imaginary points were relocated to the "correct" positions.

The code associated with the warning messages is potentially rather cumbersome for production algorithms; therefore, the value of lalDebugLevel is tested before performing any other tests associated with warning messages.

Author

Creighton, T. D.

Description

These functions create an object **output of type <datatype>IIRFilter, where <datatype> is REAL4 or REAL8. The filter coefficients are computed from the zeroes, poles, and gain of an input object *input of type COMPLEX8ZPGFilter or COMPLEX16ZPGFilter, respectively; the sampling time interval is taken directly from input->deltaT. The ZPG filter should express the factored transfer function in the \(z=\exp(2\pi if)\) plane. Initially the output handle must be a valid handle (output \(\neq\)NULL) but should not point to an existing object (*output=NULL)

Algorithm

An IIR filter is a real time-domain filter, which imposes certain constraints on the zeros, poles, and gain of the filter transfer function. The function Create<datatype>IIRFilter() deals with the constraints either by aborting if they are not met, or by adjusting the filter response so that they are met. In the latter case, warning messages will be issued if the external parameter lalDebugLevel is set to allow such messages. The specific constraints, and how they are dealt with, are as follows:

First, the filter must be causal; that is, the output at any time can be generated entirely from the input at previous times. In practice this means that the number of (finite) poles in the \(z\) plane must equal or exceed the number of (finite) zeros. If this is not the case, Create<datatype>IIRFilter() will add additional poles at \(z=0\). Effectively this is just adding a delay to the filter response in order to make it causal.

Second, the filter should be stable, which means that all poles should be located on or within the circle \(|z|=1\). This is not enforced by Create<datatype>IIRFilter(), which can be used to make unstable filters; however, warnings will be issued. (In some sense the first condition is a special case of this one, since a transfer function with more zeros than poles actually has corresponding poles at infinity.)

Third, the filter must be physically realizable; that is, the transfer function should expand to a rational function of \(z\) with real coefficients. Necessary and sufficient conditions for this are that the gain be real, and that all zeros and poles either be real or come in complex conjugate pairs. The routine Create<datatype>IIRFilter() enforces this by using only the real part of the gain, and only the real or positive-imaginary zeros and poles; it assumes that the latter are paired with negative-imaginary conjugates. The routine will abort if this assumption results in a change in the given number of zeros or poles. If lalDebugLevel is set to allow warnings, the routine will actually check to see that each pair of nonreal poles or zeros are in fact complex conjugates, and will issue a warning if an unmatched pair is detected; however, the algorithm will then simply proceed as if the negative-imaginary points were relocated to the "correct" positions.

The code associated with the warning messages is potentially rather cumbersome for production algorithms; therefore, the value of lalDebugLevel is tested before performing any other tests associated with warning messages.

Prototypes
REAL4IIRFilter *	XLALCreateREAL4IIRFilter (COMPLEX8ZPGFilter *input)
REAL8IIRFilter *	XLALCreateREAL8IIRFilter (COMPLEX16ZPGFilter *input)
COMPLEX16IIRFilter *	XLALCreateCOMPLEX16IIRFilter (COMPLEX16ZPGFilter *input)
void	LALCreateREAL4IIRFilter (LALStatus *stat, REAL4IIRFilter **output, COMPLEX8ZPGFilter *input)
	Deprecated. More...
void	LALCreateREAL8IIRFilter (LALStatus *stat, REAL8IIRFilter **output, COMPLEX16ZPGFilter *input)
	Deprecated. More...

Function Documentation

XLALCreateREAL4IIRFilter()

REAL4IIRFilter * XLALCreateREAL4IIRFilter

(

COMPLEX8ZPGFilter *

input

)

See also

See Module CreateIIRFilter.c for documentation

Definition at line 99 of file CreateIIRFilter.c.

XLALCreateREAL8IIRFilter()

REAL8IIRFilter * XLALCreateREAL8IIRFilter

(

COMPLEX16ZPGFilter *

input

)

See also

See Module CreateIIRFilter.c for documentation

Definition at line 326 of file CreateIIRFilter.c.

XLALCreateCOMPLEX16IIRFilter()

COMPLEX16IIRFilter* XLALCreateCOMPLEX16IIRFilter

(

COMPLEX16ZPGFilter *

input

)

See also

See Module CreateIIRFilter.c for documentation

Definition at line 553 of file CreateIIRFilter.c.

LALCreateREAL4IIRFilter()

void LALCreateREAL4IIRFilter	(	LALStatus *	stat,
		REAL4IIRFilter **	output,
		COMPLEX8ZPGFilter *	input
	)

Deprecated.

Deprecated:

Use XLALCreateREAL4IIRFilter() instead

Deprecated:

Use XLALCreateREAL4IIRFilter() instead

Definition at line 784 of file CreateIIRFilter.c.

LALCreateREAL8IIRFilter()

void LALCreateREAL8IIRFilter	(	LALStatus *	stat,
		REAL8IIRFilter **	output,
		COMPLEX16ZPGFilter *	input
	)

Deprecated.

Deprecated:

Use XLALCreateREAL8IIRFilter() instead

Deprecated:

Use XLALCreateREAL8IIRFilter() instead

Definition at line 826 of file CreateIIRFilter.c.