NAG Toolbox: nag_sum_withdraw_fft_hermitian_1d_multi_rfmt (c06fq)

Purpose

Syntax

Description

References

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 data values in each sequence.

Constraint: $\mathbf{n}\ge 1$.

3:     $\mathrm{x}\left(\mathbf{m}\times \mathbf{n}\right)$ – double array

The data must be stored in x 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 the array in Hermitian form. If the $n$ data values $z_j^p$ are written as $x_j^p+i{y}_j^p$, then for $0\le j\le n/2$, $x_j^p$ is contained in $\mathbf{x}\left(p,j\right)$, and for $1\le j\le \left(n-1\right)/2$, $y_j^p$ is contained in $\mathbf{x}\left(p,n-j\right)$. (See also Real transforms in the C06 Chapter Introduction.)

4:     $\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'}$.

5:     $\mathrm{trig}\left(2\times \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.

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{x}\left(\mathbf{m}\times \mathbf{n}\right)$ – double array

The components of the $m$ discrete Fourier transforms, stored as if in a two-dimensional array of dimension $\left(1:\mathbf{m},0:\mathbf{n}-1\right)$. Each of the $m$ transforms is stored as a row of the array, overwriting the corresponding original sequence. If the $n$ components of the discrete Fourier transform are denoted by ${\hat{x}}_{\mathit{k}}^p$, for $\mathit{k}=0,1,\dots ,n-1$, then the $mn$ elements of the array x contain the values

$${\hat{x}}_0^1,{\hat{x}}_0^2,\dots ,{\hat{x}}_0^m,{\hat{x}}_1^1,{\hat{x}}_1^2,\dots ,{\hat{x}}_1^m,\dots ,{\hat{x}}_{n-1}^1,{\hat{x}}_{n-1}^2,\dots ,{\hat{x}}_{n-1}^m\text{.}$$

2:     $\mathrm{trig}\left(2\times \mathbf{n}\right)$ – double array

Contains the required coefficients (computed by the function if $\mathbf{init}=\text{'I'}$).

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

   $\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$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: c06fq_example

function c06fq_example


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

% 3 Hermitian sequences stored as rows in compact form
m = int64(3);
n = int64(6);
x = [0.3854  0.6772  0.1138  0.6751  0.6362  0.1424;
     0.5417  0.2983  0.1181  0.7255  0.8638  0.8723;
     0.9172  0.0644  0.6037  0.6430  0.0428  0.4815];

disp('Original values in compact Hermitian form:');
disp(x);

for j = 1

  [u, v, ifail] = c06gs(m, n, x);
  z(j,:) = nag_herm2complex(x(j,:));
end
title = 'Original data written in full complex form:';
[ifail] = x04da('General','Non-unit', z, title);

% Transform to get Hermitian sequences
init = 'Initial';
trig = zeros(2*n,1);
[xt, trig, ifail] = c06fq(m, n, x, init, trig);
disp(' ');
disp('Discrete Fourier transforms (real values):');
disp(xt);

% Restore data by back transform and conjugation
init = 'Subsequent';
[xr, trig, ifail] = c06fp(m, n, xt, init, trig);
nd = double(n);
xr(1:m,floor(nd/2)+2:n) = -xr(1:m,floor(nd/2)+2:n);

disp('Original data as restored by inverse transform');
disp(xr);



function [z] = nag_herm2complex(x);
  n = size(x,2);
  z(1) = complex(x(1));
  for j = 2:floor((n-1)/2) + 1
    z(j) = x(j) + i*x(n-j+2);
    z(n-j+2) = x(j) - i*x(n-j+2);
  end
  if (mod(n,2)==0)
    z(n/2+1) = complex(x(n/2+1));
  end

c06fq example results

Original values in compact Hermitian form:
    0.3854    0.6772    0.1138    0.6751    0.6362    0.1424
    0.5417    0.2983    0.1181    0.7255    0.8638    0.8723
    0.9172    0.0644    0.6037    0.6430    0.0428    0.4815

 Original data written in full complex form:
          1       2       3       4       5       6
 1   0.3854  0.6772  0.1138  0.6751  0.1138  0.6772
     0.0000  0.1424  0.6362  0.0000 -0.6362 -0.1424
 
Discrete Fourier transforms (real values):
    1.0788    0.6623   -0.2391   -0.5783    0.4592   -0.4388
    0.8573    1.2261    0.3533   -0.2222    0.3413   -1.2291
    1.1825    0.2625    0.6744    0.5523    0.0540   -0.4790

Original data as restored by inverse transform
    0.3854    0.6772    0.1138    0.6751    0.6362    0.1424
    0.5417    0.2983    0.1181    0.7255    0.8638    0.8723
    0.9172    0.0644    0.6037    0.6430    0.0428    0.4815