NAG Library Function Document

nag_zsysv (f07nnc)

void	nag_zsysv (Nag_OrderType order, Nag_UploType uplo, Integer n, Integer nrhs, Complex a[], Integer pda, Integer ipiv[], Complex b[], Integer pdb, NagError *fail)

3 Description

nag_zsysv (f07nnc) uses the diagonal pivoting method to factor

A

order	uplo	$A$
Nag_ColMajor	Nag_Upper	$U D U^{T}$
Nag_ColMajor	Nag_Lower	$L D L^{T}$
Nag_RowMajor	Nag_Upper	$U^{T} D U$
Nag_RowMajor	Nag_Lower	$L^{T} D L$

where

U

(or

L

) is a product of permutation and unit upper (lower) triangular matrices, and

D

is symmetric and block diagonal with

1

1

and

2

2

diagonal blocks. The factored form of

A

is then used to solve the system of equations

A X = B

4 References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Higham N J (2002) Accuracy and Stability of Numerical Algorithms (2nd Edition) SIAM, Philadelphia

5 Arguments

1: order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: uplo – Nag_UploTypeInput

On entry: if

uplo = Nag_Upper

, the upper triangle of

A

is stored.

uplo = Nag_Lower

, the lower triangle of

A

is stored.

Constraint:

uplo = Nag_Upper

Nag_Lower

3: n – IntegerInput

On entry:

n

, the number of linear equations, i.e., the order of the matrix

A

Constraint:

n \geq 0

4: nrhs – IntegerInput

On entry:

r

, the number of right-hand sides, i.e., the number of columns of the matrix

B

Constraint:

nrhs \geq 0

5: a[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array a must be at least

\max (1, pda \times n)

On entry: the

n

n

symmetric matrix

A

order = Nag_ColMajor

A_{i j}

is stored in

a [(j - 1) \times pda + i - 1]

order = Nag_RowMajor

A_{i j}

is stored in

a [(i - 1) \times pda + j - 1]

uplo = Nag_Upper

, the upper triangular part of

A

must be stored and the elements of the array below the diagonal are not referenced.

uplo = Nag_Lower

, the lower triangular part of

A

must be stored and the elements of the array above the diagonal are not referenced.

On exit: if

fail . code =

NE_NOERROR, the block diagonal matrix

D

and the multipliers used to obtain the factor

U

L

from the factorization

A = U D U^{T}

A = L D L^{T}

A = U^{T} D U

A = L^{T} D L

as computed by nag_zsytrf (f07nrc).

6: pda – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) of the matrix

A

in the array a.

Constraint:

pda \geq \max (1, n)

7: ipiv[ $\dim$ ] – IntegerOutput

Note: the dimension, dim, of the array ipiv must be at least

\max (1, n)

On exit: details of the interchanges and the block structure of

D

. More precisely,

if $ipiv [i - 1] = k > 0$ , $d_{i i}$ is a $1$ by $1$ pivot block and the $i$ th row and column of $A$ were interchanged with the $k$ th row and column;
if $uplo = Nag_Upper$ and $ipiv [i - 2] = ipiv [i - 1] = - l < 0$ , $(\begin{matrix} d_{i - 1, i - 1} & {\bar{d}}_{i, i - 1} \\ {\bar{d}}_{i, i - 1} & d_{i i} \end{matrix})$ is a $2$ by $2$ pivot block and the $(i - 1)$ th row and column of $A$ were interchanged with the $l$ th row and column;
if $uplo = Nag_Lower$ and $ipiv [i - 1] = ipiv [i] = - m < 0$ , $(\begin{matrix} d_{i i} & d_{i + 1, i} \\ d_{i + 1, i} & d_{i + 1, i + 1} \end{matrix})$ is a $2$ by $2$ pivot block and the $(i + 1)$ th row and column of $A$ were interchanged with the $m$ th row and column.

8: b[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array b must be at least

$\max (1, pdb \times nrhs)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdb)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

B

is stored in

$b [(j - 1) \times pdb + i - 1]$ when $order = Nag_ColMajor$ ;
$b [(i - 1) \times pdb + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

n

r

right-hand side matrix

B

On exit: if

fail . code =

NE_NOERROR, the

n

r

solution matrix

X

9: pdb – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array b.

Constraints:

if $order = Nag_ColMajor$ , $pdb \geq \max (1, n)$ ;
if $order = Nag_RowMajor$ , $pdb \geq \max (1, nrhs)$ .

10: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $nrhs = 〈value〉$ .
Constraint: $nrhs \geq 0$ .; On entry, $pda = 〈value〉$ .
Constraint: $pda > 0$ .; On entry, $pdb = 〈value〉$ .
Constraint: $pdb > 0$ .
NE_INT_2: On entry, $pda = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pda \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdb \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $nrhs = 〈value〉$ .
Constraint: $pdb \geq \max (1, nrhs)$ .
NE_INTERNAL_ERROR: 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.
NE_SINGULAR: $D (〈value〉, 〈value〉)$ is exactly zero. The factorization has been completed, but the block diagonal matrix $D$ is exactly singular, so the solution could not be computed.

7 Accuracy

The computed solution for a single right-hand side,

\hat{x}

, satisfies an equation of the form

(A + E) \hat{x} = b,

where

{‖E‖}_{1} = O (ε) {‖A‖}_{1}

and

ε

is the machine precision. An approximate error bound for the computed solution is given by

\frac{{‖\hat{x} - x‖}_{1}}{{‖x‖}_{1}} \leq κ (A) \frac{{‖E‖}_{1}}{{‖A‖}_{1}},

where

κ (A) = {‖A^{- 1}‖}_{1} {‖A‖}_{1}

, the condition number of

A

with respect to the solution of the linear equations. See Section 4.4 of Anderson et al. (1999) and Chapter 11 of Higham (2002) for further details.

nag_zsysvx (f07npc) is a comprehensive LAPACK driver that returns forward and backward error bounds and an estimate of the condition number. Alternatively, nag_complex_sym_lin_solve (f04dhc) solves

A x = b

and returns a forward error bound and condition estimate. nag_complex_sym_lin_solve (f04dhc) calls nag_zsysv (f07nnc) to solve the equations.

8 Further Comments

The total number of floating point operations is approximately

\frac{4}{3} n^{3} + 8 n^{2} r

, where

r

is the number of right-hand sides.

The real analogue of this function is nag_dsysv (f07mac). The complex Hermitian analogue of this function is nag_zhesv (f07mnc).

9 Example

This example solves the equations

A x = b,

where

A

is the complex symmetric matrix

A = (\begin{array}{r} - 0.56 + 0.12 i & - 1.54 - 2.86 i & 5.32 - 1.59 i & 3.80 + 0.92 i \\ - 1.54 - 2.86 i & - 2.83 - 0.03 i & - 3.52 + 0.58 i & - 7.86 - 2.96 i \\ 5.32 - 1.59 i & - 3.52 + 0.58 i & 8.86 + 1.81 i & 5.14 - 0.64 i \\ 3.80 + 0.92 i & - 7.86 - 2.96 i & 5.14 - 0.64 i & - 0.39 - 0.71 i \end{array})

and

b = (\begin{array}{r} - 6.43 + 19.24 i \\ - 0.49 - 1.47 i \\ - 48.18 + 66.00 i \\ - 55.64 + 41.22 i \end{array}) .

Details of the factorization of

A

are also output.

NAG Library Function Documentnag_zsysv (f07nnc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_zsysv (f07nnc)