\chapter{Convolution}
\label{cha:convolve}

%begin{latexonly}
\makeatletter
\py@reset
\makeatother
%end{latexonly}
\declaremodule{extension}{numarray.convolve}
\moduleauthor{The numarray team}{numpy-discussion@lists.sourceforge.net}
\modulesynopsis{Convolution,correlation}

\begin{quote}
   This package (numarray.convolve) provides functions for one- and 
   two-dimensional convolutions and correlations of \class{numarray}s.
   Each of the following examples assumes that the following code has been 
   executed:
\begin{verbatim}
import numarray.convolve as conv
\end{verbatim}
\end{quote}


\section{Convolution functions}
\label{sec:CONV:convolution-functions}

\begin{funcdesc}{boxcar}{data, boxshape, output=None, mode='nearest', cval=0.0}
   \function{boxcar} computes a 1-D or 2-D boxcar filter on every 1-D or
   2-D subarray of \constant{data}. \constant{boxshape} is a tuple of integers
   specifying the dimensions of the filter, e.g. \code{(3,3)}.  If
   \constant{output} is specified, it should be the same shape as
   \constant{data} and the result will be stored in it.  In that case
   \class{None} will be returned.
        
   \constant{mode} can be any of the following values:
   \begin{description}
   \item[\var{nearest}]: Elements beyond boundary come from nearest edge pixel.
   \item[\var{wrap}]: Elements beyond boundary come from the opposite array
      edge.
   \item[\var{reflect}]: Elements beyond boundary come from reflection on same
      array edge.
   \item[\var{constant}]: Elements beyond boundary are set to what is specified
      in \constant{cval}, an optional numerical parameter; the default value is
      \code{0.0}.
   \end{description}        
\end{funcdesc}
\begin{verbatim}
>>> print a
[1 5 4 7 2 9 3 6]
>>> print conv.boxcar(a,(3,))
[ 2.33333333  3.33333333  5.33333333  4.33333333  6.          4.66666667
  6.          5.        ]
# for even number box size, it will take the extra point from the lower end
>>> print conv.boxcar(a,(2,))
[ 1.   3.   4.5  5.5  4.5  5.5  6.   4.5]
\end{verbatim}

\begin{funcdesc}{convolve}{data, kernel, mode=FULL}
   \label{func:CONV:convolve}
   Returns the discrete, linear convolution of 1-D sequences \constant{data} 
   and \constant{kernel}; \constant{mode} can be \class{VALID}, \class{SAME}, 
   or \code{FULL} to specify the size of the resulting sequence.  See section
   \ref{sec:CONV:global-constants}.
\end{funcdesc}

\begin{funcdesc}{convolve2d}{data, kernel, output=None, fft=0, mode='nearest', 
    cval=0.0} Return the 2-dimensional convolution of \constant{data} and
  \constant{kernel}.  If \constant{output} is not \class{None}, the result is
  stored in \constant{output} and \class{None} is returned.  \constant{fft} is
  used to switch between FFT-based convolution and the naive algorithm,
  defaulting to naive.  Using \constant{fft} mode becomes more beneficial as
  the size of the kernel grows; for small kernels, the naive algorithm is more
  efficient.  \constant{mode} has the same choices as those of
  \function{boxcar}.  A number of storage considerations come into play with
  large arrays: (1) boundary modes are implemented by making an oversized
  temporary copy of the \constant{data} array which has a shape equal to the
  sum of the \constant{data} and \constant{kernel} shapes.  (2) likewise, the
  \constant{kernel} is copied into an array with the same shape as the
  oversized \constant{data} array.  (3) In FFT mode, the fourier transforms of
  the \constant{data} and \constant{kernel} arrays are stored in double
  precision complex temporaries. The aggregate effect is that storage roughly
  equal to a factor of eight (x2 from 2 and x4 from 3) times the size of the
  \constant{data} is required to compute the convolution of a Float32
  \constant{data} array.
\end{funcdesc}

\begin{funcdesc}{correlate}{data, kernel, mode=FULL}
   Return the cross-correlation of \constant{data} and \constant{kernel};
   \constant{mode} can be \class{VALID}, \class{SAME}, or \code{FULL} to 
   specify the size of the resulting sequence.  \function{correlate} is
   very closely related to \function{convolve} in implementation.
   See section \ref{sec:CONV:global-constants}.
\end{funcdesc}

\begin{funcdesc}{correlate2d}{data, kernel, output=None, fft=0, mode='nearest', cval=0.0}
   \label{func:CONV:correlate2d}
  Return the 2-dimensional convolution of \constant{data} and
  \constant{kernel}.  If \constant{output} is not \class{None}, the result is
  stored in \constant{output} and \class{None} is returned.  \constant{fft} is
  used to switch between FFT-based convolution and the naive algorithm,
  defaulting to naive.  Using \constant{fft} mode becomes more beneficial as
  the size of the kernel grows; for small kernels, the naive algorithm is more
  efficient.  \constant{mode} has the same choices as those of
  \function{boxcar}.  See also \function{convolve2d} for notes regarding 
  storage consumption.
\end{funcdesc}

\note{\function{cross_correlate} is deprecated and should not be used.}



\section{Global constants}
\label{sec:CONV:global-constants}

These constants specify what part of the result the \function{convolve} and
\function{correlate} functions of this module return.  Each of the following
examples assumes that the following code has been executed:

\begin{verbatim}
arr = numarray.arange(8)
\end{verbatim}

\begin{datadesc}{FULL}
   Return the full convolution or correlation of two arrays.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.FULL)
array([ 0,  3,  8, 14, 20, 26, 32, 38, 20,  7])
\end{verbatim}
\end{datadesc}

\begin{datadesc}{PASS}
   Correlate the arrays without padding the data.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.PASS)
array([ 0,  8, 14, 20, 26, 32, 38,  7])
\end{verbatim}
\end{datadesc}

\begin{datadesc}{SAME}
   Return the part of the convolution or correlation of two arrays that
   corresponds to an array of the same shape as the input data.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.SAME)
array([ 3,  8, 14, 20, 26, 32, 38, 20])
\end{verbatim}
\end{datadesc}

\begin{datadesc}{VALID}
   Return the valid part of the convolution or correlation of two arrays.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.VALID)
array([ 8, 14, 20, 26, 32, 38])
\end{verbatim}
\end{datadesc}



%% Local Variables:
%% mode: LaTeX
%% mode: auto-fill
%% fill-column: 79
%% indent-tabs-mode: nil
%% ispell-dictionary: "american"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "numarray"
%% TeX-parse-self: t
%% End:
