NAG Toolbox: nag_linsys_complex_symm_packed_solve (f04dj)

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$ symmetric 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{T}}$ or $A=LD{L}^{\mathrm{T}}$ as computed by nag_lapack_zsptrf (f07qr), stored as a packed triangular matrix in the same storage format as $A$.

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

If no constraints are violated, details of the interchanges and the block structure of $D$, as determined by nag_lapack_zsptrf (f07qr).

• 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: f04dj_example

function f04dj_example


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

% Solve complex Ax = b for symmetric packed A
% with error bound and condition number
uplo = 'U';
ap = [ -0.56 +  0.12i                                    ...
       -1.54 -  2.86i     -2.83 - 0.03i                  ...
        5.32 -  1.59i     -3.52 + 0.58i    8.86 + 1.81i  ...
        3.8  +  0.92i     -7.86 - 2.96i    5.14 - 0.64i  -0.39 - 0.71i];
b = [  -6.43 + 19.24i,   -4.59 - 35.53i;
       -0.49 -  1.47i,    6.95 + 20.49i;
      -48.18 + 66.00i,  -12.08 - 27.02i;
      -55.64 + 41.22i,  -19.09 - 35.97i];

[ap, ipiv, x, rcond, errbnd, ifail] = ...
  f04dj(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);

f04dj example results

Solution
  -4.0000 + 3.0000i  -1.0000 + 1.0000i
   3.0000 - 2.0000i   3.0000 + 2.0000i
  -2.0000 + 5.0000i   1.0000 - 3.0000i
   1.0000 - 1.0000i  -2.0000 - 1.0000i

Estimate of condition number
      20.6

Estimate of error bound for computed solutions
   2.3e-15