Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_sum_convcorr_complex (c06pk)

## Purpose

nag_sum_convcorr_complex (c06pk) calculates the circular convolution or correlation of two complex vectors of period $n$.

## Syntax

[x, y, ifail] = c06pk(job, x, y, 'n', n)
[x, y, ifail] = nag_sum_convcorr_complex(job, x, y, 'n', n)

## Description

nag_sum_convcorr_complex (c06pk) computes:
• if ${\mathbf{job}}=1$, the discrete convolution of $x$ and $y$, defined by
 $zk = ∑ j=0 n-1 xj y k-j = ∑ j=0 n-1 x k-j yj ;$
• if ${\mathbf{job}}=2$, the discrete correlation of $x$ and $y$ defined by
 $wk = ∑ j=0 n-1 x-j y k+j .$
Here $x$ and $y$ are complex vectors, assumed to be periodic, with period $n$, i.e., ${x}_{j}={x}_{j±n}={x}_{j±2n}=\dots \text{}$; $z$ and $w$ are then also periodic with period $n$.
Note:  this usage of the terms ‘convolution’ and ‘correlation’ is taken from Brigham (1974). The term ‘convolution’ is sometimes used to denote both these computations.
If $\stackrel{^}{x}$, $\stackrel{^}{y}$, $\stackrel{^}{z}$ and $\stackrel{^}{w}$ are the discrete Fourier transforms of these sequences, and $\stackrel{~}{x}$ is the inverse discrete Fourier transform of the sequence ${x}_{j}$, i.e.,
 $x^k = 1n ∑ j=0 n-1 xj × exp -i 2πjk n , etc.,$
and
 $x~k = 1n ∑ j= 0 n- 1 xj × exp i 2πjk n ,$
then ${\stackrel{^}{z}}_{k}=\sqrt{n}.{\stackrel{^}{x}}_{k}{\stackrel{^}{y}}_{k}$ and ${\stackrel{^}{w}}_{k}=\sqrt{n}.{\stackrel{-}{\stackrel{^}{x}}}_{k}{\stackrel{^}{y}}_{k}$ (the bar denoting complex conjugate).

## References

Brigham E O (1974) The Fast Fourier Transform Prentice–Hall

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{job}$int64int32nag_int scalar
The computation to be performed:
${\mathbf{job}}=1$
${z}_{k}=\sum _{j=0}^{n-1}{x}_{j}{y}_{k-j}$ (convolution);
${\mathbf{job}}=2$
${w}_{k}=\sum _{j=0}^{n-1}{\stackrel{-}{x}}_{j}{y}_{k+j}$ (correlation).
Constraint: ${\mathbf{job}}=1$ or $2$.
2:     $\mathrm{x}\left({\mathbf{n}}\right)$ – complex array
The elements of one period of the vector $x$. If x is declared with bounds $\left(0:{\mathbf{n}}-1\right)$ in the function from which nag_sum_convcorr_complex (c06pk) is called, then ${\mathbf{x}}\left(\mathit{j}\right)$ must contain ${x}_{\mathit{j}}$, for $\mathit{j}=0,1,\dots ,n-1$.
3:     $\mathrm{y}\left({\mathbf{n}}\right)$ – complex array
The elements of one period of the vector $y$. If y is declared with bounds $\left(0:{\mathbf{n}}-1\right)$ in the function from which nag_sum_convcorr_complex (c06pk) is called, then ${\mathbf{y}}\left(\mathit{j}\right)$ must contain ${y}_{\mathit{j}}$, for $\mathit{j}=0,1,\dots ,n-1$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the arrays x, y. (An error is raised if these dimensions are not equal.)
$n$, the number of values in one period of the vectors x and y. The total number of prime factors of n, counting repetitions, must not exceed $30$.
Constraint: ${\mathbf{n}}\ge 1$.

### Output Parameters

1:     $\mathrm{x}\left({\mathbf{n}}\right)$ – complex array
The corresponding elements of the discrete convolution or correlation.
2:     $\mathrm{y}\left({\mathbf{n}}\right)$ – complex array
The discrete Fourier transform of the convolution or correlation returned in the array x.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<1$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{job}}\ne 1$ or $2$.
${\mathbf{ifail}}=3$
An unexpected error has occurred in an internal call. Check all function calls and array dimensions. Seek expert help.
${\mathbf{ifail}}=4$
 On entry, n has more than $30$ prime factors.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The results should be accurate to within a small multiple of the machine precision.

The time taken is approximately proportional to $n×\mathrm{log}\left(n\right)$, but also depends on the factorization of $n$. nag_sum_convcorr_complex (c06pk) is faster if the only prime factors of $n$ are $2$, $3$ or $5$; and fastest of all if $n$ is a power of $2$.

## Example

This example reads in the elements of one period of two complex vectors $x$ and $y$, and prints their discrete convolution and correlation (as computed by nag_sum_convcorr_complex (c06pk)). In realistic computations the number of data values would be much larger.
```function c06pk_example

fprintf('c06pk example results\n\n');

a = 1 - 0.5i;
b =   - 0.5i;
x(1:5) = a;
x(6:9) = b;
y(1:4) = a/2;
y(5:9) = b/2;

job = int64(1);
[conv, tconv, ifail] = c06pk(job, x, y);
job = int64(2);
[corr, tcorr, ifail] = c06pk(job, x, y);

result = [transpose(conv) transpose(corr)];
disp('      Convolution        Correlation');
disp(result);

```
```c06pk example results

Convolution        Correlation
-0.6250 - 2.2500i   3.1250 - 0.2500i
-0.1250 - 2.2500i   2.6250 - 0.2500i
0.3750 - 2.2500i   2.1250 - 0.2500i
0.8750 - 2.2500i   1.6250 - 0.2500i
0.8750 - 2.2500i   1.1250 - 0.2500i
0.3750 - 2.2500i   1.6250 - 0.2500i
-0.1250 - 2.2500i   2.1250 - 0.2500i
-0.6250 - 2.2500i   2.6250 - 0.2500i
-1.1250 - 2.2500i   3.1250 - 0.2500i

```