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_fft_complex_1d_multi_rfmt (c06fr)

## Purpose

nag_sum_fft_complex_1d_multi_rfmt (c06fr) computes the discrete Fourier transforms of $m$ sequences, each containing $n$ complex data values. This function is designed to be particularly efficient on vector processors.
Note: this function is scheduled to be withdrawn, please see c06fr in Advice on Replacement Calls for Withdrawn/Superseded Routines..

## Syntax

[x, y, trig, ifail] = c06fr(m, n, x, y, init, trig)
[x, y, trig, ifail] = nag_sum_withdraw_fft_complex_1d_multi_rfmt(m, n, x, y, init, trig)

## Description

Given $m$ sequences of $n$ complex data values ${z}_{\mathit{j}}^{\mathit{p}}$, for $\mathit{j}=0,1,\dots ,n-1$ and $\mathit{p}=1,2,\dots ,m$, nag_sum_fft_complex_1d_multi_rfmt (c06fr) simultaneously calculates the Fourier transforms of all the sequences defined by
 $z^kp = 1n ∑ j=0 n-1 zjp × exp -i 2πjk n , k= 0, 1, …, n-1 ​ and ​ p= 1,2,…,m .$
(Note the scale factor $\frac{1}{\sqrt{n}}$ in this definition.)
The discrete Fourier transform is sometimes defined using a positive sign in the exponential term
 $z^kp = 1n ∑ j=0 n-1 zjp × exp +i 2πjk n .$
To compute this form, this function should be preceded and followed by a call of nag_sum_conjugate_complex_sep (c06gc) to form the complex conjugates of the ${z}_{j}^{p}$ and the ${\stackrel{^}{z}}_{k}^{p}$.
The function uses a variant of the fast Fourier transform (FFT) algorithm (see Brigham (1974)) known as the Stockham self-sorting algorithm, which is described in Temperton (1983). Special code is provided for the factors $2$, $3$, $4$, $5$ and $6$. This function is designed to be particularly efficient on vector processors, and it becomes especially fast as $m$, the number of transforms to be computed in parallel, increases.

## References

Brigham E O (1974) The Fast Fourier Transform Prentice–Hall
Temperton C (1983) Self-sorting mixed-radix fast Fourier transforms J. Comput. Phys. 52 1–23

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
$m$, the number of sequences to be transformed.
Constraint: ${\mathbf{m}}\ge 1$.
2:     $\mathrm{n}$int64int32nag_int scalar
$n$, the number of complex values in each sequence.
Constraint: ${\mathbf{n}}\ge 1$.
3:     $\mathrm{x}\left({\mathbf{m}}×{\mathbf{n}}\right)$ – double array
4:     $\mathrm{y}\left({\mathbf{m}}×{\mathbf{n}}\right)$ – double array
The real and imaginary parts of the complex data must be stored in x and y respectively as if in a two-dimensional array of dimension $\left(1:{\mathbf{m}},0:{\mathbf{n}}-1\right)$; each of the $m$ sequences is stored in a row of each array. In other words, if the real parts of the $p$th sequence to be transformed are denoted by ${x}_{\mathit{j}}^{p}$, for $\mathit{j}=0,1,\dots ,n-1$, then the $mn$ elements of the array x must contain the values
 $x01 , x02 ,…, x0m , x11 , x12 ,…, x1m ,…, x n-1 1 , x n-1 2 ,…, x n-1 m .$
5:     $\mathrm{init}$ – string (length ≥ 1)
Indicates whether trigonometric coefficients are to be calculated.
${\mathbf{init}}=\text{'I'}$
Calculate the required trigonometric coefficients for the given value of $n$, and store in the array trig.
${\mathbf{init}}=\text{'S'}$ or $\text{'R'}$
The required trigonometric coefficients are assumed to have been calculated and stored in the array trig in a prior call to one of nag_sum_fft_real_1d_multi_rfmt (c06fp), nag_sum_fft_hermitian_1d_multi_rfmt (c06fq) or nag_sum_fft_complex_1d_multi_rfmt (c06fr). The function performs a simple check that the current value of $n$ is consistent with the values stored in trig.
Constraint: ${\mathbf{init}}=\text{'I'}$, $\text{'S'}$ or $\text{'R'}$.
6:     $\mathrm{trig}\left(2×{\mathbf{n}}\right)$ – double array
If ${\mathbf{init}}=\text{'S'}$ or $\text{'R'}$, trig must contain the required trigonometric coefficients that have been previously calculated. Otherwise trig need not be set.

None.

### Output Parameters

1:     $\mathrm{x}\left({\mathbf{m}}×{\mathbf{n}}\right)$ – double array
2:     $\mathrm{y}\left({\mathbf{m}}×{\mathbf{n}}\right)$ – double array
x and y store the real and imaginary parts of the complex transforms.
3:     $\mathrm{trig}\left(2×{\mathbf{n}}\right)$ – double array
Contains the required coefficients (computed by the function if ${\mathbf{init}}=\text{'I'}$).
4:     $\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{m}}<1$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{n}}<1$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{init}}\ne \text{'I'}$, $\text{'S'}$ or $\text{'R'}$.
${\mathbf{ifail}}=4$
Not used at this Mark.
${\mathbf{ifail}}=5$
 On entry, ${\mathbf{init}}=\text{'S'}$ or $\text{'R'}$, but the array trig and the current value of n are inconsistent.
${\mathbf{ifail}}=6$
An unexpected error has occurred in an internal call. Check all function calls and array dimensions. Seek expert help.
${\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

Some indication of accuracy can be obtained by performing a subsequent inverse transform and comparing the results with the original sequence (in exact arithmetic they would be identical).

The time taken by nag_sum_fft_complex_1d_multi_rfmt (c06fr) is approximately proportional to $nm\mathrm{log}\left(n\right)$, but also depends on the factors of $n$. nag_sum_fft_complex_1d_multi_rfmt (c06fr) is fastest if the only prime factors of $n$ are $2$, $3$ and $5$, and is particularly slow if $n$ is a large prime, or has large prime factors.

## Example

This example reads in sequences of complex data values and prints their discrete Fourier transforms (as computed by nag_sum_fft_complex_1d_multi_rfmt (c06fr)). Inverse transforms are then calculated using nag_sum_fft_complex_1d_multi_rfmt (c06fr) and nag_sum_conjugate_complex_sep (c06gc) and printed out, showing that the original sequences are restored.
```function c06fr_example

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

% 3 complex sequences, ral and imaginary parts stored as rows
% in separate arrays.
m = int64(3);
n = int64(6);
zr = [0.3854  0.6772  0.1138  0.6751  0.6362  0.1424;
0.9172  0.0644  0.6037  0.6430  0.0428  0.4815;
0.1156  0.0685  0.2060  0.8630  0.6967  0.2792];
zi = [0.5417  0.2983  0.1181  0.7255  0.8638  0.8723;
0.9089  0.3118  0.3465  0.6198  0.2668  0.1614;
0.6214  0.8681  0.7060  0.8652  0.9190  0.3355];

z = zr + i*zi;
title = 'Original sequences:';
[ifail] = x04da('General','Non-unit', z, title);

% Transform
init = 'Initial';
trig = zeros(2*n,1);
[ztr, zti, trig, ifail] = c06fr(m, n, zr, zi, init, trig);

zt = ztr + i*zti;
disp(' ');
title = 'Discrete Fourier Transforms:';
[ifail] = x04da('General','Non-unit', zt, title);

% Restore by transform with pre- and post-conjugation
zti = -zti;
init = 'Subsequent';
[zrr, zri, trig, ifail] = c06fr(m, n, ztr, zti, init, trig);
zr = zrr - i*zri;

disp(' ');
title = 'Original data as restored by inverse transform';
[ifail] = x04da('General','Non-unit', zr, title);

```
```c06fr example results

Original sequences:
1       2       3       4       5       6
1   0.3854  0.6772  0.1138  0.6751  0.6362  0.1424
0.5417  0.2983  0.1181  0.7255  0.8638  0.8723

2   0.9172  0.0644  0.6037  0.6430  0.0428  0.4815
0.9089  0.3118  0.3465  0.6198  0.2668  0.1614

3   0.1156  0.0685  0.2060  0.8630  0.6967  0.2792
0.6214  0.8681  0.7060  0.8652  0.9190  0.3355

Discrete Fourier Transforms:
1          2          3          4          5          6
1      1.0737    -0.5706     0.1733    -0.1467     0.0518     0.3625
1.3961    -0.0409    -0.2958    -0.1521     0.4517    -0.0321

2      1.1237     0.1728     0.4185     0.1530     0.3686     0.0101
1.0677     0.0386     0.7481     0.1752     0.0565     0.1403

3      0.9100    -0.3054     0.4079    -0.0785    -0.1193    -0.5314
1.7617     0.0624    -0.0695     0.0725     0.1285    -0.4335

Original data as restored by inverse transform
1       2       3       4       5       6
1   0.3854  0.6772  0.1138  0.6751  0.6362  0.1424
0.5417  0.2983  0.1181  0.7255  0.8638  0.8723

2   0.9172  0.0644  0.6037  0.6430  0.0428  0.4815
0.9089  0.3118  0.3465  0.6198  0.2668  0.1614

3   0.1156  0.0685  0.2060  0.8630  0.6967  0.2792
0.6214  0.8681  0.7060  0.8652  0.9190  0.3355
```