1: $n1$ – int64int32nag_int scalar: $n_{1}$ , the first dimension of the transform.

Constraint: $n1 \geq 1$ .
2: $n2$ – int64int32nag_int scalar: $n_{2}$ , the second dimension of the transform.

Constraint: $n2 \geq 1$ .
3: $n3$ – int64int32nag_int scalar: $n_{3}$ , the third dimension of the transform.

Constraint: $n3 \geq 1$ .
4: $x (n1 \times n2 \times n3)$ – double array: The real input dataset $x$ , where $x_{j1 j2 j3}$ is stored in $x (j3 \times n_{1} n_{2} + j2 \times n_{1} + j1 + 1)$ , for $j1 = 0, 1, \dots, n_{1} - 1$ , $j2 = 0, 1, \dots, n_{2} - 1$ and $j3 = 0, 1, \dots, n_{3} - 1$ . That is, if x is regarded as a three-dimensional array of dimension $(0 : n1 - 1, 0 : n2 - 1, 0 : n3 - 1)$ , then $x (j_{1}, j_{2}, j_{3})$ must contain $x_{j_{1} j_{2} j_{3}}$ .

Optional Input Parameters

None.

Output Parameters

1: $y ((n1 / 2 + 1) \times n2 \times n3)$ – complex array: The complex output dataset $\hat{z}$ , where ${\hat{z}}_{k1 k2 k3}$ is stored in $y (k3 \times (n_{1} / 2 + 1) n_{2} + k2 \times (n_{1} / 2 + 1) + k1 + 1)$ , for $k1 = 0, 1, \dots, n_{1} / 2$ , $k2 = 0, 1, \dots, n_{2} - 1$ and $k3 = 0, 1, \dots, n_{3} - 1$ . That is, if y is regarded as a three-dimensional array of dimension $(0 : n1 / 2, 0 : n2 - 1, 0 : n3 - 1)$ , then $y (k_{1}, k_{2}, k_{3})$ contains ${\hat{z}}_{k_{1} k_{2} k_{3}}$ . Note the first dimension is cut roughly by half to remove the redundant information due to conjugate symmetry.
2: $ifail$ – int64int32nag_int scalar: $ifail = 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$: Constraint: $n1 \geq 1$ .

$ifail = 2$: Constraint: $n2 \geq 1$ .

$ifail = 3$: Constraint: $n3 \geq 1$ .

$ifail = 4$: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

Some indication of accuracy can be obtained by performing a forward transform using nag_sum_fft_real_3d (c06py) and a backward transform using nag_sum_fft_hermitian_3d (c06pz), and comparing the results with the original sequence (in exact arithmetic they would be identical).

Further Comments

The time taken by nag_sum_fft_real_3d (c06py) is approximately proportional to

n_{1} n_{2} n_{3} \log (n_{1} n_{2} n_{3})

, but also depends on the factors of

n_{1}

n_{2}

and

n_{3}

. nag_sum_fft_real_3d (c06py) is fastest if the only prime factors of

n_{1}

n_{2}

and

n_{3}

are

2

3

and

5

, and is particularly slow if one of the dimensions is a large prime, or has large prime factors.

Workspace is internally allocated by nag_sum_fft_real_3d (c06py). The total size of these arrays is approximately proportional to

n_{1} n_{2} n_{3}

Example

This example reads in a trivariate sequence of real data values and prints their discrete Fourier transforms as computed by nag_sum_fft_real_3d (c06py). Inverse transforms are then calculated by calling nag_sum_fft_hermitian_3d (c06pz) showing that the original sequences are restored.

Open in the MATLAB editor: c06py_example

function c06py_example


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

n1 = int64(3);
n2 = int64(3);
n3 = int64(4);
x = zeros(n1, n2, n3);
x(1, :, :) = [1.541, 0.161, 1.989, 0.037;
              0.346, 1.907, 0.001, 1.915;
              1.754, 0.042, 1.991, 0.151];

x(2, :, :) = [0.584, 1.004, 1.408, 0.252;
              1.284, 1.137, 0.467, 1.834;
              0.855, 0.725, 1.647, 0.096];

x(3, :, :) = [0.010, 1.844, 0.452, 1.154;
              1.960, 0.240, 1.424, 0.987;
              0.089, 1.660, 0.708, 0.872];
% Compute Transform.  Reshape x into a 1-d array
[y, ifail] = c06py(n1, n2, n3, reshape(x,n1*n2*n3,1));

% Display y as a 3-d array
fprintf('\nComponents of discrete Fourier transform:\n');
reshape(y,n1/2,n2,n3)

% Compute Inverse Transform
[x1, ifail] = c06pz(n1, n2, n3, y) ;
fprintf('Original sequence as restored by inverse transform:\n');
reshape(x1, n1, n2, n3)

c06py example results


Components of discrete Fourier transform:

ans(:,:,1) =

   5.7547 + 0.0000i  -0.2683 - 0.4203i  -0.2683 + 0.4203i
   0.0814 + 0.0154i   0.0382 + 0.1983i   0.0674 - 0.1220i


ans(:,:,2) =

  -0.2773 - 0.2370i   0.1085 - 0.7560i  -0.6882 + 0.2100i
   0.0605 + 0.1563i  -0.2752 + 0.2954i   0.2804 + 0.0122i


ans(:,:,3) =

   0.4153 + 0.0000i   0.1753 + 0.8712i   0.1753 - 0.8712i
   0.6446 - 0.4779i   1.5848 + 0.6163i  -0.1134 - 1.5552i


ans(:,:,4) =

  -0.2773 + 0.2370i  -0.6882 - 0.2100i   0.1085 + 0.7560i
   0.0469 - 0.0772i   0.2005 + 0.0614i  -0.1281 - 0.1173i

Original sequence as restored by inverse transform:

ans(:,:,1) =

    1.5410    0.3460    1.7540
    0.5840    1.2840    0.8550
    0.0100    1.9600    0.0890


ans(:,:,2) =

    0.1610    1.9070    0.0420
    1.0040    1.1370    0.7250
    1.8440    0.2400    1.6600


ans(:,:,3) =

    1.9890    0.0010    1.9910
    1.4080    0.4670    1.6470
    0.4520    1.4240    0.7080


ans(:,:,4) =

    0.0370    1.9150    0.1510
    0.2520    1.8340    0.0960
    1.1540    0.9870    0.8720

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox