Module CreateIIRFilter.c

Creates IIR filter objects.

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`

)

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.

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`

)

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

REAL4IIRFilter * XLALCreateREAL4IIRFilter | ( | COMPLEX8ZPGFilter * | input | ) |

- See also
- See Module CreateIIRFilter.c for documentation

Definition at line 99 of file CreateIIRFilter.c.

REAL8IIRFilter * XLALCreateREAL8IIRFilter | ( | COMPLEX16ZPGFilter * | input | ) |

- See also
- See Module CreateIIRFilter.c for documentation

Definition at line 326 of file CreateIIRFilter.c.

COMPLEX16IIRFilter* XLALCreateCOMPLEX16IIRFilter | ( | COMPLEX16ZPGFilter * | input | ) |

- See also
- See Module CreateIIRFilter.c for documentation

Definition at line 553 of file CreateIIRFilter.c.

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.

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.