NAG Toolbox: nag_linsys_complex_herm_packed_solve (f04cj)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

If $\mathbf{uplo}=\text{'U'}$, the upper triangle of the matrix $A$ is stored.

If $\mathbf{uplo}=\text{'L'}$, the lower triangle of the matrix $A$ is stored.

Constraint: $\mathbf{uplo}=\text{'U'}$ or $\text{'L'}$.

2:     $\mathrm{ap}\left(:\right)$ – complex array

The dimension of the array ap must be at least $\max \left(1,\mathbf{n}\times \left(\mathbf{n}+1\right)/2\right)$

The $n$ by $n$ Hermitian matrix $A$, packed column-wise in a linear array. The $j$th column of the matrix $A$ is stored in the array ap as follows:

More precisely,

• if $\mathbf{uplo}=\text{'U'}$, the upper triangle of $A$ must be stored with element $A_{ij}$ in $\mathbf{ap}\left(i+j\left(j-1\right)/2\right)$ for $i\le j$;
• if $\mathbf{uplo}=\text{'L'}$, the lower triangle of $A$ must be stored with element $A_{ij}$ in $\mathbf{ap}\left(i+\left(2n-j\right)\left(j-1\right)/2\right)$ for $i\ge j$.

3:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array

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

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

The $n$ by $r$ matrix of right-hand sides $B$.

Optional Input Parameters

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

Default: the first dimension of the array b.

The number of linear equations $n$, i.e., the order of the matrix $A$.

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

2:     $\mathrm{nrhs\_p}$ – int64int32nag_int scalar

Default: the second dimension of the array b.

The number of right-hand sides $r$, i.e., the number of columns of the matrix $B$.

Constraint: $\mathbf{nrhs\_p}\ge 0$.

Output Parameters

1:     $\mathrm{ap}\left(:\right)$ – complex array

The dimension of the array ap will be $\max \left(1,\mathbf{n}\times \left(\mathbf{n}+1\right)/2\right)$

If $\mathbf{ifail}\ge \mathbf{0}$, the block diagonal matrix $D$ and the multipliers used to obtain the factor $U$ or $L$ from the factorization $A=UD{U}^{\mathrm{H}}$ or $A=LD{L}^{\mathrm{H}}$ as computed by nag_lapack_zhptrf (f07pr), stored as a packed triangular matrix in the same storage format as $A$.

2:     $\mathrm{ipiv}\left(\mathbf{n}\right)$ – int64int32nag_int array

If $\mathbf{ifail}\ge \mathbf{0}$, details of the interchanges and the block structure of $D$, as determined by nag_lapack_zhptrf (f07pr).

• If $\mathbf{ipiv}\left(k\right)>0$, then rows and columns $k$ and $\mathbf{ipiv}\left(k\right)$ were interchanged, and $d_{kk}$ is a $1$ by $1$ diagonal block;
• if $\mathbf{uplo}=\text{'U'}$ and $\mathbf{ipiv}\left(k\right)=\mathbf{ipiv}\left(k-1\right)<0$, then rows and columns $k-1$ and $-\mathbf{ipiv}\left(k\right)$ were interchanged and $d_{k-1:k,k-1:k}$ is a $2$ by $2$ diagonal block;
• if $\mathbf{uplo}=\text{'L'}$ and $\mathbf{ipiv}\left(k\right)=\mathbf{ipiv}\left(k+1\right)<0$, then rows and columns $k+1$ and $-\mathbf{ipiv}\left(k\right)$ were interchanged and $d_{k:k+1,k:k+1}$ is a $2$ by $2$ diagonal block.

3:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array

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

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

If $\mathbf{ifail}=\mathbf{0}$ or $\mathbf{n}+\mathbf{1}$, the $n$ by $r$ solution matrix $X$.

4:     $\mathrm{rcond}$ – double scalar

If no constraints are violated, an estimate of the reciprocal of the condition number of the matrix $A$, computed as $\mathbf{rcond}=1/\left({‖A‖}_1{‖A^{-1}‖}_1\right)$.

5:     $\mathrm{errbnd}$ – double scalar

If $\mathbf{ifail}=\mathbf{0}$ or $\mathbf{n}+\mathbf{1}$, an estimate of the forward error bound for a computed solution $\hat{x}$, such that ${‖\hat{x}-x‖}_1/{‖x‖}_1\le \mathbf{errbnd}$, where $\hat{x}$ is a column of the computed solution returned in the array b and $x$ is the corresponding column of the exact solution $X$. If rcond is less than machine precision, then errbnd is returned as unity.

6:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{ifail}>0\hspace{0.17em}\text{and}\hspace{0.17em}\mathbf{ifail}\le \mathbf{n}$

Diagonal block $\_$ of the block diagonal matrix is zero. The factorization has been completed, but the solution could not be computed.

W  $\mathbf{ifail}=\mathbf{n}+1$

A solution has been computed, but rcond is less than machine precision so that the matrix $A$ is numerically singular.

   $\mathbf{ifail}=-1$

On entry, $\mathbf{uplo}\ne \text{'U'}$ or $\text{'L'}$.

   $\mathbf{ifail}=-2$

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

   $\mathbf{ifail}=-3$

Constraint: $\mathbf{nrhs\_p}\ge 0$.

   $\mathbf{ifail}=-7$

Constraint: $\mathit{ldb}\ge \max \left(1,\mathbf{n}\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.

The double allocatable memory required is n, and the complex allocatable memory required is $2\times \mathbf{n}$. Allocation failed before the solution could be computed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f04cj_example

function f04cj_example


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

% Solve complex Ax = b for Hermitian packed A
% with error bound and condition number
uplo = 'U';
ap = [-1.84                                        ...
       0.11 -  0.11   -4.63 + 0i                   ...
      -1.78 -  1.18i  -1.84 + 0.03i  -8.87 + 0i    ...
       3.91 -  1.5i    2.21 + 0.21i   1.58 - 0.9i  -1.36 + 0i];
b = [ 2.98 - 10.18i,  28.68 - 39.89i;
     -9.58 +  3.88i, -24.79 -  8.4i;
     -0.77 - 16.05i,   4.23 - 70.02i;
      7.79 +  5.48i, -35.39 + 18.01i];

[ap, ipiv, x, rcond, errbnd, ifail] = ...
  f04cj(uplo, ap, b);

disp('Solution');
disp(x);
disp('Estimate of condition number');
fprintf('%10.1f\n\n',1/rcond);
disp('Estimate of error bound for computed solutions');
fprintf('%10.1e\n\n',errbnd);

f04cj example results

Solution
   2.0330 + 1.0218i  -8.1639 + 6.0692i
   3.0234 - 2.1166i   7.4388 - 2.0180i
  -1.0112 + 1.9975i  -1.0639 + 4.9118i
   1.0794 - 1.1045i   3.1469 - 4.2238i

Estimate of condition number
       6.7

Estimate of error bound for computed solutions
   7.5e-16