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_fft_complex_3d_sep (c06fx)

## Purpose

nag_sum_fft_complex_3d_sep (c06fx) computes the three-dimensional discrete Fourier transform of a trivariate sequence of complex data values. This function is designed to be particularly efficient on vector processors.

## Syntax

[x, y, trign1, trign2, trign3, ifail] = c06fx(n1, n2, n3, x, y, init, trign1, trign2, trign3)
[x, y, trign1, trign2, trign3, ifail] = nag_sum_fft_complex_3d_sep(n1, n2, n3, x, y, init, trign1, trign2, trign3)

## Description

nag_sum_fft_complex_3d_sep (c06fx) computes the three-dimensional discrete Fourier transform of a trivariate sequence of complex data values z j1 j2 j3 ${z}_{{j}_{1}{j}_{2}{j}_{3}}$, for j1 = 0,1,,n11$\mathit{j1}=0,1,\dots ,{n}_{1}-1$, j2 = 0,1,,n21$\mathit{j2}=0,1,\dots ,{n}_{2}-1$ and j3 = 0,1,,n31$\mathit{j3}=0,1,\dots ,{n}_{3}-1$.
The discrete Fourier transform is here defined by
 n1 − 1 n2 − 1 n3 − 1 ẑ k1 k2 k3 = 1/(sqrt( n1 n2 n3 )) ∑ ∑ ∑ z j1 j2 j3 × exp( − 2πi((j1k1)/(n1) + (j2k2)/(n2) + (j3k3)/(n3))), j1 = 0 j2 = 0 j3 = 0
$z^ k1 k2 k3 = 1 n1 n2 n3 ∑ j1=0 n1-1 ∑ j2=0 n2-1 ∑ j3=0 n3-1 z j1 j2 j3 × exp( -2πi ( j1k1 n1 + j2k2 n2 + j3k3 n3 ) ) ,$
where k1 = 0,1,,n11 ${k}_{1}=0,1,\dots ,{n}_{1}-1$, k2 = 0,1,,n21 ${k}_{2}=0,1,\dots ,{n}_{2}-1$, k3 = 0,1,,n31 ${k}_{3}=0,1,\dots ,{n}_{3}-1$.
(Note the scale factor of 1/(sqrt( n1 n2 n3 )) $\frac{1}{\sqrt{{n}_{1}{n}_{2}{n}_{3}}}$ in this definition.)
To compute the inverse discrete Fourier transform, defined with exp( + 2πi()) $\mathrm{exp}\left(+2\pi i\left(\dots \right)\right)$ in the above formula instead of exp(2πi()) $\mathrm{exp}\left(-2\pi i\left(\dots \right)\right)$, this function should be preceded and followed by forming the complex conjugates of the data values and the transform.
This function performs, for each dimension, multiple one-dimensional discrete Fourier transforms by the fast Fourier transform (FFT) algorithm (see 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:     n1 – int64int32nag_int scalar
n1${n}_{1}$, the first dimension of the transform.
Constraint: n11${\mathbf{n1}}\ge 1$.
2:     n2 – int64int32nag_int scalar
n2${n}_{2}$, the second dimension of the transform.
Constraint: n21${\mathbf{n2}}\ge 1$.
3:     n3 – int64int32nag_int scalar
n3${n}_{3}$, the third dimension of the transform.
Constraint: n31${\mathbf{n3}}\ge 1$.
4:     x( n1 × n2 × n3 ${\mathbf{n1}}×{\mathbf{n2}}×{\mathbf{n3}}$) – double array
5:     y( n1 × n2 × n3 ${\mathbf{n1}}×{\mathbf{n2}}×{\mathbf{n3}}$) – 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 three-dimensional arrays of dimension (0 : n11,0 : n21,0 : n31)$\left(0:{\mathbf{n1}}-1,0:{\mathbf{n2}}-1,0:{\mathbf{n3}}-1\right)$, then x (j1,j2,j3)${\mathbf{x}}\left({j}_{1},{j}_{2},{j}_{3}\right)$ and y (j1,j2,j3)${\mathbf{y}}\left({j}_{1},{j}_{2},{j}_{3}\right)$ must contain the real and imaginary parts of z j1 j2 j3 ${z}_{{j}_{1}{j}_{2}{j}_{3}}$.
6:     init – string (length ≥ 1)
Indicates whether trigonometric coefficients are to be calculated.
init = 'I'${\mathbf{init}}=\text{'I'}$
Calculate the required trigonometric coefficients for the given values of n1${n}_{1}$, n2${n}_{2}$ and n3${n}_{3}$, and store in the corresponding arrays trign1, trign2 and trign3.
init = 'S'${\mathbf{init}}=\text{'S'}$ or 'R'$\text{'R'}$
The required trigonometric coefficients are assumed to have been calculated and stored in the arrays trign1, trign2 and trign3 in a prior call to nag_sum_fft_complex_3d_sep (c06fx). The function performs a simple check that the current values of n1${n}_{1}$, n2${n}_{2}$ and n3${n}_{3}$ are consistent with the corresponding values stored in trign1, trign2 and trign3.
Constraint: init = 'I'${\mathbf{init}}=\text{'I'}$, 'S'$\text{'S'}$ or 'R'$\text{'R'}$.
7:     trign1( 2 × n1 $2×{\mathbf{n1}}$) – double array
8:     trign2( 2 × n2 $2×{\mathbf{n2}}$) – double array
9:     trign3( 2 × n3 $2×{\mathbf{n3}}$) – double array
If init = 'S'${\mathbf{init}}=\text{'S'}$ or 'R'$\text{'R'}$, trign1, trign2 and trign3 must contain the required coefficients calculated in a previous call of the function. Otherwise trign1, trign2 and trign3 need not be set. If n1 = n2${\mathbf{n1}}={\mathbf{n2}}$, the same array may be supplied for trign1 and trign2. Similar considerations apply if n2 = n3${\mathbf{n2}}={\mathbf{n3}}$ or n1 = n3${\mathbf{n1}}={\mathbf{n3}}$.

None.

work

### Output Parameters

1:     x( n1 × n2 × n3 ${\mathbf{n1}}×{\mathbf{n2}}×{\mathbf{n3}}$) – double array
2:     y( n1 × n2 × n3 ${\mathbf{n1}}×{\mathbf{n2}}×{\mathbf{n3}}$) – double array
The real and imaginary parts respectively of the corresponding elements of the computed transform.
3:     trign1( 2 × n1 $2×{\mathbf{n1}}$) – double array
4:     trign2( 2 × n2 $2×{\mathbf{n2}}$) – double array
5:     trign3( 2 × n3 $2×{\mathbf{n3}}$) – double array
trign1, trign2 and trign3 contain the required coefficients (computed by the function if init = 'I'${\mathbf{init}}=\text{'I'}$).
6:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, n1 < 1${\mathbf{n1}}<1$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, n2 < 1${\mathbf{n2}}<1$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, n3 < 1${\mathbf{n3}}<1$.
ifail = 4${\mathbf{ifail}}=4$
 On entry, init ≠ 'I'${\mathbf{init}}\ne \text{'I'}$, 'S'$\text{'S'}$ or 'R'$\text{'R'}$.
ifail = 5${\mathbf{ifail}}=5$
Not used at this Mark.
ifail = 6${\mathbf{ifail}}=6$
 On entry, init = 'S'${\mathbf{init}}=\text{'S'}$ or 'R'$\text{'R'}$, but at least one of the arrays trign1, trign2 and trign3 is inconsistent with the current value of n1, n2 or n3.
ifail = 7${\mathbf{ifail}}=7$
An unexpected error has occurred in an internal call. Check all function calls and array dimensions. Seek expert help.

## 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 n1 n2 n3 × log(n1n2n3) ${n}_{1}{n}_{2}{n}_{3}×\mathrm{log}\left({n}_{1}{n}_{2}{n}_{3}\right)$, but also depends on the factorization of the individual dimensions n1 ${n}_{1}$, n2 ${n}_{2}$ and n3 ${n}_{3}$. nag_sum_fft_complex_3d_sep (c06fx) is faster if the only prime factors are 2$2$, 3$3$ or 5$5$; and fastest of all if they are powers of 2$2$.

## Example

```function nag_sum_fft_complex_3d_sep_example
n1 = int64(2);
n2 = int64(3);
n3 = int64(4);
x = [1;
0.5;
0.994;
0.494;
0.903;
0.403;
0.999;
0.499;
0.989;
0.489;
0.885;
0.385;
0.987;
0.487;
0.963;
0.463;
0.823;
0.323;
0.936;
0.436;
0.891;
0.391;
0.694;
0.194];
y = [0;
0.5;
-0.111;
0.111;
-0.43;
0.43;
-0.04;
0.04;
-0.151;
0.151;
-0.466;
0.466;
-0.159;
0.159;
-0.268;
0.268;
-0.568;
0.568;
-0.352;
0.352;
-0.454;
0.454;
-0.72;
0.72];
init = 'Initial';
trign1 = zeros(4,1);
trign2 = zeros(6,1);
trign3 = zeros(8,1);
[xOut, yOut, trign1Out, trign2Out, trign3Out, ifail] = ...
nag_sum_fft_complex_3d_sep(n1, n2, n3, x, y, init, trign1, trign2, trign3)
```
```

xOut =

3.2921
1.2247
0.1433
0.4243
0.1433
-0.4243
0.0506
0.3548
0.0155
0.0204
-0.0502
0.0070
0.1127
-0.0000
-0.0245
0.0134
-0.0245
-0.0134
0.0506
-0.3548
-0.0502
-0.0070
0.0155
-0.0204

yOut =

0.1021
-1.6203
-0.0860
0.3197
0.2902
0.3197
-0.0416
0.0833
0.1527
-0.1147
0.1180
-0.0800
0.1021
0.1621
0.1268
-0.0914
0.0773
-0.0914
0.2458
0.0833
0.0861
-0.0800
0.0515
-0.1147

trign1Out =

1
2
0
2

trign2Out =

1
1
3
0
0
3

trign3Out =

1
1
1
4
0
0
0
4

ifail =

0

```
```function c06fx_example
n1 = int64(2);
n2 = int64(3);
n3 = int64(4);
x = [1;
0.5;
0.994;
0.494;
0.903;
0.403;
0.999;
0.499;
0.989;
0.489;
0.885;
0.385;
0.987;
0.487;
0.963;
0.463;
0.823;
0.323;
0.936;
0.436;
0.891;
0.391;
0.694;
0.194];
y = [0;
0.5;
-0.111;
0.111;
-0.43;
0.43;
-0.04;
0.04;
-0.151;
0.151;
-0.466;
0.466;
-0.159;
0.159;
-0.268;
0.268;
-0.568;
0.568;
-0.352;
0.352;
-0.454;
0.454;
-0.72;
0.72];
init = 'Initial';
trign1 = zeros(4,1);
trign2 = zeros(6,1);
trign3 = zeros(8,1);
[xOut, yOut, trign1Out, trign2Out, trign3Out, ifail] = ...
c06fx(n1, n2, n3, x, y, init, trign1, trign2, trign3)
```
```

xOut =

3.2921
1.2247
0.1433
0.4243
0.1433
-0.4243
0.0506
0.3548
0.0155
0.0204
-0.0502
0.0070
0.1127
-0.0000
-0.0245
0.0134
-0.0245
-0.0134
0.0506
-0.3548
-0.0502
-0.0070
0.0155
-0.0204

yOut =

0.1021
-1.6203
-0.0860
0.3197
0.2902
0.3197
-0.0416
0.0833
0.1527
-0.1147
0.1180
-0.0800
0.1021
0.1621
0.1268
-0.0914
0.0773
-0.0914
0.2458
0.0833
0.0861
-0.0800
0.0515
-0.1147

trign1Out =

1
2
0
2

trign2Out =

1
1
3
0
0
3

trign3Out =

1
1
1
4
0
0
0
4

ifail =

0

```