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_2d_sep (c06fu)

## Purpose

nag_sum_fft_complex_2d_sep (c06fu) computes the two-dimensional discrete Fourier transform of a bivariate sequence of complex data values. This function is designed to be particularly efficient on vector processors.
Note: this function is scheduled to be withdrawn, please see c06fu in Advice on Replacement Calls for Withdrawn/Superseded Routines..

## Syntax

[x, y, trigm, trign, ifail] = c06fu(m, n, x, y, init, trigm, trign)
[x, y, trigm, trign, ifail] = nag_sum_withdraw_fft_complex_2d_sep(m, n, x, y, init, trigm, trign)

## Description

nag_sum_fft_complex_2d_sep (c06fu) computes the two-dimensional discrete Fourier transform of a bivariate sequence of complex data values ${z}_{{j}_{1}{j}_{2}}$, for $\mathit{j1}=0,1,\dots ,m-1$ and $\mathit{j2}=0,1,\dots ,n-1$.
The discrete Fourier transform is here defined by
 $z^ k1k2 = 1mn ∑ j1=0 m-1 ∑ j2=0 n-1 z j1 j2 × exp -2πi j1 k1 m + j2 k2 n ,$
where ${k}_{1}=0,1,\dots ,m-1$, ${k}_{2}=0,1,\dots ,n-1$.
(Note the scale factor of $\frac{1}{\sqrt{mn}}$ in this definition.)
To compute the inverse discrete Fourier transform, defined with $\mathrm{exp}\left(+2\pi i\left(\dots \right)\right)$ in the above formula instead of $\mathrm{exp}\left(-2\pi i\left(\dots \right)\right)$, this function should be preceded and followed by calls of nag_sum_conjugate_complex_sep (c06gc) to form the complex conjugates of the data values and the transform.
This function calls nag_sum_fft_complex_1d_multi_rfmt (c06fr) to perform multiple one-dimensional discrete Fourier transforms by the fast Fourier transform (FFT) algorithm in Brigham (1974). It is designed to be particularly efficient on vector processors.

## 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 length of the first dimension of $Z$. Consider the matrix $Z$ with elements ${Z}_{ij}={z}_{i+1j+1}$, where $z$ is the bivariate sequence defined in Description, then $m$ is the number of rows of $Z$.
Constraint: ${\mathbf{m}}\ge 1$.
2:     $\mathrm{n}$int64int32nag_int scalar
$n$, the length of the second dimension of $Z$. Consider the matrix $Z$ with elements ${Z}_{ij}={z}_{i+1j+1}$, where $z$ is the bivariate sequence defined in Description, then $n$ is the number of columns of $Z$.
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 values must be stored in arrays x and y respectively. If x and y are regarded as two-dimensional arrays of dimension $\left(0:{\mathbf{m}}-1,0:{\mathbf{n}}-1\right)$, then ${\mathbf{x}}\left({j}_{1},{j}_{2}\right)$ and ${\mathbf{y}}\left({j}_{1},{j}_{2}\right)$ must contain the real and imaginary parts of ${z}_{{j}_{1}{j}_{2}}$.
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 values of $m$ and $n$, and store in the corresponding arrays trigm and trign.
${\mathbf{init}}=\text{'S'}$ or $\text{'R'}$
The required trigonometric coefficients are assumed to have been calculated and stored in the arrays trigm and trign in a prior call to nag_sum_fft_complex_2d_sep (c06fu). The function performs a simple check that the current values of $m$ and $n$ are consistent with the corresponding values stored in trigm and trign.
Constraint: ${\mathbf{init}}=\text{'I'}$, $\text{'S'}$ or $\text{'R'}$.
6:     $\mathrm{trigm}\left(2×{\mathbf{m}}\right)$ – double array
7:     $\mathrm{trign}\left(2×{\mathbf{n}}\right)$ – double array
If ${\mathbf{init}}=\text{'S'}$ or $\text{'R'}$, trigm and trign must contain the required coefficients calculated in a previous call of the function. Otherwise trigm and trign need not be set.
If $m=n$ the same array may be supplied for trigm and trign.

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
The real and imaginary parts respectively of the corresponding elements of the computed transform.
3:     $\mathrm{trigm}\left(2×{\mathbf{m}}\right)$ – double array
4:     $\mathrm{trign}\left(2×{\mathbf{n}}\right)$ – double array
trigm and trign contain the required coefficients (computed by the function if ${\mathbf{init}}=\text{'I'}$).
5:     $\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 at least one of the arrays trigm and trign is inconsistent with the current value of m or n.
${\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 is approximately proportional to $mn×\mathrm{log}\left(mn\right)$, but also depends on the factorization of the individual dimensions $m$ and $n$. nag_sum_fft_complex_2d_sep (c06fu) is faster if the only prime factors are $2$, $3$ or $5$; and fastest of all if they are powers of $2$.

## Example

This example reads in a bivariate sequence of complex data values and prints the two-dimensional Fourier transform. It then performs an inverse transform and prints the sequence so obtained, which may be compared to the original data values.
```function c06fu_example

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

m = int64(3);
n = int64(5);
x = [ 1.000     0.999     0.987     0.936     0.802;
0.994     0.989     0.963     0.891     0.731;
0.903     0.885     0.823     0.694     0.467];
y = [ 0.000    -0.040    -0.159    -0.352    -0.597;
-0.111    -0.151    -0.268    -0.454    -0.682
-0.430    -0.466    -0.568    -0.720    -0.884];

% transform, then inverse transform to restore data
init = 'Initial';
trigm = zeros(6,1);
trign = zeros(10,1);
[xt, yt, trigm, trign, ifail] = c06fu(m, n, x, y, init, trigm, trign);
init = 'Subsequent';
[xr, yr, trigm, trign, ifail] = c06fu(m, n, xt, -yt, init, trigm, trign);

% Display as complex matrices
z = x + i*y;
nd = [m,n];
zt = reshape(xt+i*yt,nd);
zr = reshape(xr-i*yr,nd);

matrix = 'general';
diag = ' ';
usefrm = 'Above';
format = 'F9.3';
labrow = 'None';
labcol = 'None';
ncols  = int64(80);
indent = int64(0);

title  = 'Original data:';
[ifail] = x04db(...
matrix, diag, z, usefrm, format, title, labrow, labcol, ncols, indent);
disp(' ');
title = 'Discrete Fourier transform:';
[ifail] = x04db(...
matrix, diag, zt, usefrm, format, title, labrow, labcol, ncols, indent);
disp(' ');
title = 'Original sequence as restored by inverse transform:';
[ifail] = x04db(...
matrix, diag, zr, usefrm, format, title, labrow, labcol, ncols, indent);

```
```c06fu example results

Original data:
1.000    0.999    0.987    0.936    0.802
0.000   -0.040   -0.159   -0.352   -0.597

0.994    0.989    0.963    0.891    0.731
-0.111   -0.151   -0.268   -0.454   -0.682

0.903    0.885    0.823    0.694    0.467
-0.430   -0.466   -0.568   -0.720   -0.884

Discrete Fourier transform:
3.373    0.481    0.251    0.054   -0.419
-1.519   -0.091    0.178    0.319    0.415

0.457    0.055    0.009   -0.022   -0.076
0.137    0.032    0.039    0.036    0.004

-0.170   -0.037   -0.042   -0.038   -0.002
0.493    0.058    0.008   -0.025   -0.083

Original sequence as restored by inverse transform:
1.000    0.999    0.987    0.936    0.802
0.000   -0.040   -0.159   -0.352   -0.597

0.994    0.989    0.963    0.891    0.731
-0.111   -0.151   -0.268   -0.454   -0.682

0.903    0.885    0.823    0.694    0.467
-0.430   -0.466   -0.568   -0.720   -0.884
```