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_withdraw_convcorr_real_nowork (c06ek)

## Purpose

nag_sum_convcorr_real_nowork (c06ek) calculates the circular convolution or correlation of two real vectors of period $n$. (No extra workspace is required.)
Note: this function is scheduled to be withdrawn, please see c06ek in Advice on Replacement Calls for Withdrawn/Superseded Routines..

## Syntax

[x, y, ifail] = c06ek(job, x, y, 'n', n)
[x, y, ifail] = nag_sum_withdraw_convcorr_real_nowork(job, x, y, 'n', n)

## Description

nag_sum_convcorr_real_nowork (c06ek) 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 xj y k+j .$
Here $x$ and $y$ are real 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, i.e.,
 $x^k = 1n ∑ j=0 n-1 xj × exp -i 2πjk n , etc.,$
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).
This function calls the same auxiliary functions as nag_sum_fft_real_1d_nowork (c06ea) and nag_sum_fft_hermitian_1d_nowork (c06eb) to compute discrete Fourier transforms, and there are some restrictions on the value of $n$.

## 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}{x}_{j}{y}_{k+j}$ (correlation).
Constraint: ${\mathbf{job}}=1$ or $2$.
2:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double 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_real_nowork (c06ek) 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)$ – double 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_real_nowork (c06ek) 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.
Constraint: ${\mathbf{n}}>1$.

### Output Parameters

1:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double array
The corresponding elements of the discrete convolution or correlation.
2:     $\mathrm{y}\left({\mathbf{n}}\right)$ – double array
The discrete Fourier transform of the convolution or correlation returned in the array x; the transform is stored in Hermitian form. If the components of the transform are:
 $Z^k = ak + i bk Z^ n-k = ak - i bk k=0,1,…n/2$
where ${b}_{0}$ and ${b}_{n/2}$ when $n$ is even then ${\mathbf{x}}\left(k+1\right)$ holds ${a}_{k}$ and ${\mathbf{x}}\left(n-k+1\right)$ holds nonzero ${b}_{k}$ (see Real transforms in the C06 Chapter Introduction).
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$
At least one of the prime factors of n is greater than $19$.
${\mathbf{ifail}}=2$
n has more than $20$ prime factors.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{n}}\le 1$.
${\mathbf{ifail}}=4$
 On entry, ${\mathbf{job}}\ne 1$ or $2$.
${\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_real_nowork (c06ek) 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$.
On the other hand, nag_sum_convcorr_real_nowork (c06ek) is particularly slow if $n$ has several unpaired prime factors, i.e., if the ‘square-free’ part of $n$ has several factors. For such values of $n$, nag_sum_convcorr_real (c06fk) (which requires additional double workspace) is considerably faster.

## Example

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

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

x = [1;    1;    1;    1;    1;    0;    0;    0;    0];
y = [0.5;  0.5;  0.5;  0.5;  0;    0;    0;    0;    0];

job = int64(1);
[conv, tconv, ifail] = c06ek(job, x, y);

job = int64(2);
[corr, tcorr, ifail] = c06ek(job, x, y);

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

```
```c06ek example results

Convolution  Correlation
0.5000    2.0000
1.0000    1.5000
1.5000    1.0000
2.0000    0.5000
2.0000    0.0000
1.5000    0.5000
1.0000    1.0000
0.5000    1.5000
0.0000    2.0000

```