LAL  7.1.7.1-56c71ae

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. Furthermore, this code block is surrounded with compiler directives to exclude the code entirely if the module is compiled with the NDEBUG flag set.

Prototypes

REAL4IIRFilterXLALCreateREAL4IIRFilter (COMPLEX8ZPGFilter *input)
 
REAL8IIRFilterXLALCreateREAL8IIRFilter (COMPLEX16ZPGFilter *input)
 
COMPLEX16IIRFilterXLALCreateCOMPLEX16IIRFilter (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 101 of file CreateIIRFilter.c.

◆ XLALCreateREAL8IIRFilter()

REAL8IIRFilter * XLALCreateREAL8IIRFilter ( COMPLEX16ZPGFilter input)
See also
See Module CreateIIRFilter.c for documentation

Definition at line 334 of file CreateIIRFilter.c.

◆ XLALCreateCOMPLEX16IIRFilter()

COMPLEX16IIRFilter* XLALCreateCOMPLEX16IIRFilter ( COMPLEX16ZPGFilter input)
See also
See Module CreateIIRFilter.c for documentation

Definition at line 567 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 804 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 846 of file CreateIIRFilter.c.