Infinite Impulse Response Filter (``iirfilt``)
==============================================

.. author   jgaeddert Joseph D. Gaeddert <joseph@liquidsdr.org>
.. date     January 1, 1975
.. location Boston, MA
.. header   /doc/iirfilt/banner.png
.. keywords iirfilt, infinite impulse response, IIR, filter
.. api      iirfilt_crcf

The ``iirfilt_crcf`` object and family implement the infinite impulse
response (IIR) filters.
Also known as recursive filters, IIR filters allow a portion of the output to
be fed back into the input, thus creating an impulse response which is
non-zero for an infinite amount of time.
Formally, the output signal :math:`y[n]` may be written in terms of the input signal
:math:`x[n]` as

.. math::
    y[n] = \frac{1}{a_0} \left(
           \sum_{j=0}^{n_b-1}{ b_j x[n-j] } -
           \sum_{k=1}^{n_a-1}{ a_k y[n-k] }
           \right)
    :label: eqn-filter-iirfilt-y

where :math:`\vec{b} = [b_0,b_1,\ldots,b_{n_b-1}]^T` are the feed-forward parameters
and   :math:`\vec{a} = [a_0,a_1,\ldots,a_{n_a-1}]^T` are the feed-back parameters
of length :math:`n_b` and :math:`n_a`, respectively.
The :math:`z`-transform of the transfer function is therefore

.. math::
    H(z) = \frac{Y(z)}{X(z)}
         = \frac{\sum\limits_{j=0}^{n_b-1}{b_j z^{-j}}}
                {\sum\limits_{k=0}^{n_a-1}{a_k z^{-k}}}
         = \frac{ b_0 + b_1 z^{-1} + \cdots + b_{n_b-1} z^{n_b-1}}
                { a_0 + a_1 z^{-1} + \cdots + a_{n_a-1} z^{n_a-1}}
    :label: eqn-filter-iirfilt-Hz

Typically the coefficients in :math:`H(z)` are normalized such that :math:`a_0=1`.

For larger order filters (even as small as :math:`n\approx 8`) the filter can become
unstable due to finite machine precision.
It is often therefore useful to express :math:`H(z)` in terms of second-order
sections.
For a filter of order :math:`n`, these sections are denoted by the two
:math:`(L+r)\times 3` matrices :math:`\vec{B}` and :math:`\vec{A}`
where :math:`r=n \mod 2` (0 for odd :math:`n`, 1 for even :math:`n`) and :math:`L=(n-r)/2`.

.. math::
    H_d(z) =
             \left[
                \frac{B_{r,0} + B_{r,1}z^{-1}}
                     {1       + A_{r,1}z^{-1}}
             \right]^r
             \prod_{k=1}^{L} {\left[
                \frac{B_{k,0} + B_{k,1}z^{-1} + B_{k,2}z^{-2}}
                     {1       + A_{k,1}z^{-1} + A_{k,2}z^{-2}}
             \right]}
    :label: eqn-filter-iirfilt-Hdz

Notice that :math:`H(z)` is now a series of cascaded second-order IIR filters.
The `sos` form is practical when filters are designed from analog prototypes
where the poles and zeros are known.
liquid implements second-order sections efficiently with the internal
`iirfiltsos_crcf` family of objects.
For a cascaded second-order section IIR filter, use
:ref:`iirfilt_create_sos`.

.. *See also*: `iirdes` (IIR filter design) in [section-filter-iirdes].

Examples
--------

Listed below is a basic example of the interface
in which a low-pass filter is applied to a signal to remove a
high-frequency component.

.. literalinclude:: iirfilt.c
   :language: c

The output of this example is plotted below in
:numref:`fig-iirfilt`, below:

.. qplot:: series filter/iirfilt.c
    :kwargs: {
        "format":
        {
            "xlabel" : "Time [samples]",
            "xrange" : [0, 120],
            "yrange" : [-1.5, 1.5],
            "legend" : true
        },
        "plots":
        [
            {
                "ylabel" : "Real",
                "series" : [
                    ["x-real",{"color":"#aaaaaa","label":"Input"}],
                    ["y-real",{"color":"#004080","label":"Filtered"}]
                ]
            },
            {
                "ylabel" : "Imag",
                "series" : [
                    ["x-imag",{"color":"#aaaaaa","label":"Input"}],
                    ["y-imag",{"color":"#004080","label":"Filtered"}]
                ]
            }
        ]}
    :width: 75%
    :name: fig-iirfilt
    :caption: ``iirfilt_crcf`` (infinite impulse response filter) demonstration


You can create a filter from a given set of filter coefficients as
well, viz.

.. literalinclude:: iirfilt_example.c
   :language: c



Interface
---------

Listed below is the full interface to the ``iirfilt`` family of
objects.

.. api:: iirfilt