NAG Toolbox: nag_matop_complex_gen_rq_formq (f01rk)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{wheret}$ – string (length ≥ 1)

Indicates where the elements of $\theta$ are to be found.

$\mathbf{wheret}=\text{'I'}$ (In a)

The elements of $\theta$ are in a.

$\mathbf{wheret}=\text{'S'}$ (Separate)

The elements of $\theta$ are separate from a, in theta.

Constraint: $\mathbf{wheret}=\text{'I'}$ or $\text{'S'}$.

2:     $\mathrm{m}$ – int64int32nag_int scalar

$m$, the number of rows of the matrix $A$.

Constraint: $\mathbf{m}\ge 0$.

3:     $\mathrm{nrowp}$ – int64int32nag_int scalar

$\ell$, the required number of rows of $P$.

If $\mathbf{nrowp}=0$, an immediate return is effected.

Constraint: $0\le \mathbf{nrowp}\le \mathbf{n}$.

4:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array

The first dimension of the array a must be at least $\max \left(1,\mathbf{m},\mathbf{nrowp}\right)$.

The second dimension of the array a must be at least $\max \left(1,\mathbf{n}\right)$.

The leading $m$ by $m$ strictly lower triangular part of the array a, and the $m$ by $\left(n-m\right)$ rectangular part of a with top left-hand corner at element $\mathbf{a}\left(1,\mathbf{m}+1\right)$ must contain details of the matrix $P$. In addition, if $\mathbf{wheret}=\text{'I'}$, the diagonal elements of a must contain the elements of $\theta$.

5:     $\mathrm{theta}\left(:\right)$ – complex array

The dimension of the array theta must be at least $\max \left(1,\mathbf{m}\right)$ if $\mathbf{wheret}=\text{'S'}$, and at least $1$ otherwise

If $\mathbf{wheret}=\text{'S'}$, the array theta must contain the elements of $\theta$. If $\mathbf{theta}\left(k\right)=0.0$, $P_k$ is assumed to be $I$, if $\mathbf{theta}\left(k\right)=\alpha$ and $\mathrm{Re}\left(\alpha \right)<0.0$, $P_k$ is assumed to be of the form

$$P_k=\left(\begin{array}{lll}I& 0& 0\\ 0& \alpha & 0\\ 0& 0& I\end{array}\right)\text{,}$$

otherwise $\mathbf{theta}\left(k\right)$ is assumed to contain ${\theta }_k$ given by

$${\theta }_k=\left({\zeta }_k,\mathrm{Im}\left({\gamma }_k\right)\right)\text{.}$$

If $\mathbf{wheret}=\text{'I'}$, the array theta is not referenced.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the second dimension of the array a.

$n$, the number of columns of the matrix $A$.

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

Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array

The first dimension of the array a will be $\max \left(1,\mathbf{m},\mathbf{nrowp}\right)$.

The second dimension of the array a will be $\max \left(1,\mathbf{n}\right)$.

The first nrowp rows of the array a store the first nrowp rows of the $n$ by $n$ unitary matrix $P^{\mathrm{H}}$.

2:     $\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{wheret}\ne \text{'I'}$ or $\text{'S'}$,
or	$\mathbf{m}<0$,
or	$\mathbf{n}<\mathbf{m}$,
or	$\mathbf{nrowp}<0$ or $\mathbf{nrowp}>\mathbf{n}$,
or	$\mathit{lda}<\max \left(1,\mathbf{m},\mathbf{nrowp}\right)$.

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

function f01rk_example


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

a = [  0   - 0.5i,  0.4 - 0.3i,  0.4 + 0i,    0.3 + 0.4i,  0   + 0.3i;
      -0.5 - 1.5i,  0.9 - 1.3i, -0.4 - 0.4i,  0.1 - 0.7i,  0.3 - 0.3i;
      -1   - i,     0.2 - 1.4i,  1.8 + 0i,    0   + 0i,    0   - 2.4i];

[RQ, theta, ifail] = f01rj(a);

wheret = 'Separate';
m     = int64(size(a,1));
nrowp = int64(size(a,2));
RQ(m+1:nrowp,1:nrowp) = complex(0);

[PT, ifail] = f01rk( ...
                     wheret, m, nrowp, RQ, theta);

P = PT';
disp('Matrix P');
disp(P);

f01rk example results

Matrix P
  -0.1970 + 0.1970i   0.1639 - 0.4916i   0.2774 - 0.2774i   0.3637 + 0.3213i   0.0123 + 0.5142i
   0.0394 + 0.2757i  -0.2950 - 0.4261i  -0.0555 - 0.3883i  -0.4752 + 0.0982i  -0.4187 - 0.2987i
   0.3151 - 0.1576i   0.4516 - 0.3205i  -0.4992 + 0.0000i  -0.2762 - 0.3049i  -0.0339 + 0.3867i
   0.1970 - 0.5909i  -0.0473 - 0.3314i   0.0000 + 0.0000i   0.5121 - 0.0475i  -0.3613 - 0.3239i
  -0.1182 - 0.5646i   0.0328 + 0.2076i   0.0000 - 0.6656i  -0.2287 + 0.2072i   0.2901 + 0.0254i