Vector Dot Product (``dotprod``)
================================

.. author   jgaeddert Joseph D. Gaeddert <joseph@liquidsdr.org>
.. date     January 1, 1975
.. location Boston, MA
.. header   /doc/dotprod/banner.png
.. keywords vector dot product, dotprod, dotprod_rrrf, dotprod_crcf, dotprod_cccf
.. api dotprod_cccf

This module provides interfaces for computing a vector dot product
between two equally-sized vectors.
Dot products are commonly used in digital signal processing for
communications, particularly in filtering and matrix operations.
Given two vectors of equal length
:math:`\vec{x} = \left[x(0),x(1),\ldots,x(N-1)\right]^T` and
:math:`\vec{v} = \left[v(0),v(1),\ldots,v(N-1)\right]^T`,
the vector dot product between them is computed as

.. math::
    \vec{x} \cdot \vec{v}   =
    \vec{x}^T \vec{v}       =
    \sum_{k=0}^{N-1}{ x(k) v(k) }

A number of other `liquid` modules rely on `dotprod`,
such as filtering and equalization.

Specific machine architectures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The vector dot product has a complexity of :math:`\mathcal{O}(N)` multiply-and-accumulate
operations.
Because of its prevalence in multimedia applications, a considerable amount of
research has been put into computing the vector dot product as efficiently as
possible.
Software-defined radio is no exception as basic profiling will likely
demonstrate that a considerable portion of the processor is spent computing
it.
Certain machine architectures have specific instructions for computing vector
dot products, particularly those which use a single instruction for
multiple data (SIMD) such as
`MMX <https://en.wikipedia.org/wiki/MMX_(instruction_set)>`_,
`SSE <https://en.wikipedia.org/wiki/Streaming_SIMD_Extensions>`_,
`AVX <https://en.wikipedia.org/wiki/Advanced_Vector_Extensions>`_,
`AltiVec <https://en.wikipedia.org/wiki/AltiVec>`_,
and
`Neon <https://en.wikipedia.org/wiki/ARM_architecture_family#Advanced_SIMD_(Neon)>`_.

Interface
~~~~~~~~~

There are effectively two ways to use the `dotprod` module.
In the first and most general case, a vector dot product is computed on two
input vectors :math:`\vec{x}`
and :math:`\vec{v}` whose values are not known
*a priori*.
In the second case, a `dotprod` object is created around vector :math:`\vec{v}`
which does not change (or rarely changes) throughout its life cycle.
This is the more convenient method for filtering objects which don't usually
have time-dependent coefficients.
Listed below is a simple interface example to the `dotprod` module
object:

.. literalinclude:: dotprod_rrrf.example.c
   :language: c

In both cases the `dotprod` can be easily integrated with the
`window` object ([section-buffer-window])
for managing input data and alignment.
There are three types of dot product objects and are listed in
[tab-dotprod-objects].

.. table::  Data types for `dotprod` family of objects
   :widths: auto
   :name:  tab-dotprod-objects

   ============ =============== =============== ================
   Precision    Input/Output    Coefficients    Interface
   ============ =============== =============== ================
   :c:`float`   :c:`real`       :c:`real`       ``dotprod_rrrf``
   :c:`float`   :c:`complex`    :c:`complex`    ``dotprod_cccf``
   :c:`float`   :c:`complex`    :c:`real`       ``dotprod_crcf``
   ============ =============== =============== ================

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

.. api:: dotprod