Finite Impulse Response Filter (``firfilt``)
============================================

Finite impulse response (FIR) filters are implemented in liquid with
the ``firfilt`` family of objects.

Operation
---------

FIR filters (also known as *non-recursive filters*) operate on
discrete-time samples, computing the output :math:`y` as the convolution of
the input :math:`\vec{x}` with the filter coefficients :math:`\vec{h}` as

.. math::
    y(n) = \sum_{k=0}^{N-1}{ h(k) x(N-k-1) }
   :label: eqn-filter-firfilt

where :math:`\vec{h} = [h(0),h(1),\ldots,h(N-1)]`
is the filter impulse response.
Notice that the output sample in the above equation
is simply the vector dot product (see [dotprod](/doc/dotprod))
of the filter coefficients :math:`\vec{h}` with the time-reversed sequence
:math:`\vec{x}`.

.. qplot:: series filter/firfilt_example.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-filter-firfilt_crcf
    :caption: ``firfilt_crcf`` (finite impulse response filter) demonstration


An example of the ``firfilt`` object can be seen in
:numref:`fig-filter-firfilt_crcf`
in which a low-pass filter is applied to a signal to remove a
high-frequency component.

Examples
--------

An example of the ``firfilt`` interface is provided in
the listing, below:

.. code-block:: c

    #include <liquid/liquid.h>

    int main() {
        // options
        unsigned int h_len=21;  // filter order
        float h[h_len];         // filter coefficients

        // ... initialize filter coefficients ...

        // create filter object
        firfilt_crcf q = firfilt_crcf_create(h,h_len);

        float complex x;    // input sample
        float complex y;    // output sample

        // execute filter (repeat as necessary)
        {
            firfilt_crcf_push(q, x);    // push input sample
            firfilt_crcf_execute(q,&y); // compute output
        }

        // destroy filter object
        firfilt_crcf_destroy(q);
    }

Interface
---------

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

.. api:: firfilt