Finite Impulse Reseponse Decimator (``firdecim``)
=================================================

.. author   jgaeddert Joseph D. Gaeddert <joseph@liquidsdr.org>
.. date     January 1, 1975
.. location Boston, MA
.. header   /doc/firdecim/banner.png
.. keywords firdecim
.. api      firdecim_crcf

The ``firdecim`` object family implements a basic decimator with an
integer output-to-input resampling ratio :math:`D`.
For example, an input signal sampled at 96 MHz is decimated by a factor
:math:`D=25` results in an output signal with a sample rate 3.84 MHz.
It is essentially just a ``firfilt`` object which operates on a block
of samples at a time.
An example of the firdecimator can be seen in [fig-filter-firdecim-crcf].

.. qplot:: series filter/firdecim_example.c
    :kwargs: {
        "format":{
            "xlabel" : "Time [samples]",
            "xrange" : [-20, 160],
            "yrange" : [-1.5, 1.5],
            "legend" : ["input","decimated"]
        },
        "plots":[
            {"ylabel":"Real",
             "series" : [
                ["tx","x-real",".-",{"color":"#aaaaaa"}],
                ["ty","y-real",".", {"color":"#004080"}]
            ]},
            {"ylabel":"Imag",
             "series" : [
                ["tx","x-imag",".-",{"color":"#aaaaaa"}],
                ["ty","y-imag",".", {"color":"#008040"}]
            ]}
        ]}
    :width: 75%
    :caption: ``firdecim_crcf`` example with :math:`D=4`, compensating for filter delay.
    :name: fig-filter-firdecim-crcf


Filter Delay
------------

The delay of the decimator will depend upon the filter coefficients themselves.
Normally, an FIR filter has symmetric coefficients and has a length :math:`2Mm+1` in
which case the output delay is :math:`Mm` samples, where :math:`M` is the decimation rate
and :math:`m` is the filter semi-length. But if the filter coefficients are _not_
symmetric or if the filter length follows a different length, the delay will be
something different.
Unfortunately the decimator cannot compensate for this automatically since it
doesn't know the filter response. The delay could even be a fraction of a sample.

If the filter does have a length :math:`2Mm+1` then the output delay will be :math:`m`
samples; this is one of the reasons designing a filter of this length is convenient.
If this is the case, you can then just ignore the first :math:`m` output samples
(e.g. after decimation), and then flush :math:`m` blocks of :math:`M` samples each through
the filter to compensate for that delay.


Example
-------

An example of the ``firdecim`` interface is listed below.

.. code-block:: c

    #include <liquid/liquid.h>

    int main() {
        // options
        unsigned int M = 4;         // decimation factor
        unsigned int h_len = 21;    // filter length

        // design filter and create decimator object
        float h[h_len];             // filter coefficients
        firdecim_crcf q = firdecim_crcf_create(M,h,h_len);

        // generate input signal and decimate
        float complex x[M];         // input samples
        float complex y;            // output sample

        // run decimator (repeat as necessary)
        {
            firdecim_crcf_execute(q, x, &y);
        }

        // destroy decimator object
        firdecim_crcf_destroy(q);
    }

Interface
---------

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

.. api:: firdecim