NAG C Library Chapter Introduction

f07 — Linear Equations (LAPACK)

3 Recommendations on Choice and Use of Available Functions

3.2 NAG Names and LAPACK Names

3.5 Tables of Available Functions

5 Functions Withdrawn or Scheduled for Withdrawal

1 Scope of the Chapter

This chapter provides functions for the solution of systems of simultaneous linear equations, and associated computations. It provides functions for

– matrix factorizations;
– solution of linear equations;
– estimating matrix condition numbers;
– computing error bounds for the solution of linear equations;
– matrix inversion.

Functions are provided for both real and complex data.

For a general introduction to the solution of systems of linear equations, you should turn first to the f04 Chapter Introduction. The decision trees, at the end of the f04 Chapter Introduction, direct you to the most appropriate functions in Chapters f04 or f07 for solving your particular problem. In particular, Chapter f04 contains Black Box functions which enable some standard types of problem to be solved by a call to a single function. Where possible, functions in Chapter f04 call Chapter f07 functions to perform the necessary computational tasks.

The functions in this chapter (f07) handle only dense and band matrices (not matrices with more specialized structures, or general sparse matrices).

The functions in this chapter have all been derived from the LAPACK project (see Anderson et al. (1999)). They have been designed to be efficient on a wide range of high-performance computers, without compromising efficiency on conventional serial machines.

2 Background to the Problems

This section is only a brief introduction to the numerical solution of systems of linear equations. Consult a standard textbook, for example Golub and Van Loan (1996) for a more thorough discussion.

2.1 Notation

We use the standard notation for a system of simultaneous linear equations:

A x = b

(1)

where

A

is the coefficient matrix,

b

is the right-hand side, and

x

is the solution.

A

is assumed to be a square matrix of order

n

If there are several right-hand sides, we write

A X = B

(2)

where the columns of

B

are the individual right-hand sides, and the columns of

X

are the corresponding solutions.

We also use the following notation, both here and in the function documents:

$\hat{x}$	a computed solution to $A x = b$ , (which usually differs from the exact solution $x$ because of round-off error)
$r = b - A \hat{x}$	the residual corresponding to the computed solution $\hat{x}$
${‖x‖}_{\infty} = \max_{i} \|x_{i}\|$	the infinity-norm of the vector $x$
${‖A‖}_{\infty} = \max_{i} \sum_{j} \|a_{i j}\|$	the infinity-norm of the vector $A$
$\|x\|$	the vector with elements $\|x_{i}\|$
$\|A\|$	the matrix with elements $\|a_{i j}\|$

Inequalities of the form

|A| \leq |B|

are interpreted componentwise, that is

|a_{i j}| \leq |b_{i j}|

for all

i, j

2.2 Matrix Factorizations

A

is upper or lower triangular,

A x = b

can be solved by a straightforward process of backward or forward substitution.

Otherwise, the solution is obtained after first factorizing

A

, as follows.

General matrices (LU factorization with partial pivoting)

A = P L U

where

P

is a permutation matrix,

L

is lower-triangular with diagonal elements equal to 1, and

U

is upper-triangular; the permutation matrix

P

(which represents row interchanges) is needed to ensure numerical stability.

Symmetric positive-definite matrices (Cholesky factorization)

A = U^{T} U or A = L L^{T}

where

U

is upper triangular and

L

is lower triangular.

Symmetric indefinite matrices (Bunch–Kaufman factorization)

A = P U D U^{T} P^{T} or A = P L D L^{T} P^{T}

where

P

is a permutation matrix,

U

is upper triangular,

L

is lower triangular, and

D

is a block diagonal matrix with diagonal blocks of order 1 or 2;

U

and

L

have diagonal elements equal to 1, and have

2

2

unit matrices on the diagonal corresponding to the

2

2

blocks of

D

. The permutation matrix

P

(which represents symmetric row-and-column interchanges) and the

2

2

blocks in

D

are needed to ensure numerical stability. If

A

is in fact positive-definite, no interchanges are needed and the factorization reduces to

A = U D U^{T}

A = L D L^{T}

with diagonal

D

, which is simply a variant form of the Cholesky factorization.

2.3 Solution of Systems of Equations

Given one of the above matrix factorizations, it is straightforward to compute a solution to

A x = b

by solving two subproblems, as shown below, first for

y

and then for

x

. Each subproblem consists essentially of solving a triangular system of equations by forward or backward substitution; the permutation matrix

P

and the block diagonal matrix

D

introduce only a little extra complication:

General matrices ( LU factorization)

\begin{array}{l} L y = P^{T} b \\ U x = y \end{array}

Symmetric positive-definite matrices (Cholesky factorization)

\begin{array}{l} U^{T} y = b \\ U x = y \end{array} or \begin{array}{l} L y = b \\ L^{T} x = y \end{array}

Symmetric indefinite matrices (Bunch–Kaufman factorization)

\begin{array}{l} P U D y = b \\ U^{T} P^{T} x = y \end{array} or \begin{array}{l} P L D y = b \\ L^{T} P^{T} x = y \end{array}

2.4 Sensitivity and Error Analysis

2.4.1 Normwise error bounds

Frequently, in practical problems the data

A

and

b

are not known exactly, and it is then important to understand how uncertainties or perturbations in the data can affect the solution.

x

is the exact solution to

A x = b

, and

x + δ x

is the exact solution to a perturbed problem

(A + δ A) (x + δ x) = (b + δ b)

, then

\frac{‖δ x‖}{‖x‖} \leq κ (A) (\frac{‖δ A‖}{‖A‖} + \frac{‖δ b‖}{‖b‖}) + \dots (2nd - order terms)

where

κ (A)

is the condition number of

A

defined by

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

(3)

In other words, relative errors in

A

b

may be amplified in

x

by a factor

κ (A)

. Section 2.4.2 discusses how to compute or estimate

κ (A)

Similar considerations apply when we study the effects of rounding errors introduced by computation in finite precision. The effects of rounding errors can be shown to be equivalent to perturbations in the original data, such that

\frac{‖δ A‖}{‖A‖}

and

\frac{‖δ b‖}{‖b‖}

are usually at most

p (n) ε

, where

ε

is the machine precision and

p (n)

is an increasing function of

n

which is seldom larger than

10 n

(although in theory it can be as large as

2^{n - 1}

In other words, the computed solution

\hat{x}

is the exact solution of a linear system

(A + δ A) \hat{x} = b + δ b

which is close to the original system in a normwise sense.

2.4.2 Estimating condition numbers

The previous section has emphasized the usefulness of the quantity

κ (A)

in understanding the sensitivity of the solution of

A x = b

. To compute the value of

κ (A)

from equation (3) is more expensive than solving

A x = b

in the first place. Hence it is standard practice to estimate

κ (A)

, in either the 1-norm or the

\infty

norm, by a method which only requires

O (n^{2})

additional operations, assuming that a suitable factorization of

A

is available.

The method used in this chapter is Higham's modification of Hager's method (see Higham (1988)). It yields an estimate which is never larger than the true value, but which seldom falls short by more than a factor of 3 (although artificial examples can be constructed where it is much smaller). This is acceptable since it is the order of magnitude of

κ (A)

which is important rather than its precise value.

Because

κ (A)

is infinite if

A

is singular, the functions in this chapter actually return the reciprocal of

κ (A)

2.4.3 Componentwise error bounds

A disadvantage of normwise error bounds is that they do not reflect any special structure in the data

A

and

b

– that is, a pattern of elements which are known to be zero – and the bounds are dominated by the largest elements in the data.

Componentwise error bounds overcome these limitations. Instead of the normwise relative error, we can bound the relative error in each component of

A

and

b

\max_{i j k} (\frac{|δ a_{i j}|}{|a_{i j}|}, \frac{|δ b_{k}|}{|b_{k}|}) \leq ω

where the componentwise backward error bound

ω

is given by

ω = \max_{i} \frac{|r_{i}|}{{(|A| . |\hat{x}| + |b|)}_{i}} .

Functions are provided in this chapter which compute

ω

, and also compute a forward error bound which is sometimes much sharper than the normwise bound given earlier:

\frac{{‖x - \hat{x}‖}_{\infty}}{{‖x‖}_{\infty}} \leq \frac{{‖|A^{- 1}| . |r|‖}_{\infty}}{{‖x‖}_{\infty}} .

Care is taken when computing this bound to allow for rounding errors in computing

r

. The norm

{‖|A^{- 1}| . |r|‖}_{\infty}

is estimated cheaply (without computing

A^{- 1}

) by a modification of the method used to estimate

κ (A)

2.4.4 Iterative refinement of the solution

\hat{x}

is an approximate computed solution to

A x = b

, and

r

is the corresponding residual, then a procedure for iterative refinement of

\hat{x}

can be defined as follows, starting with

x_{0} = \hat{x}

for

i = 0, 1, \dots

, until convergence

compute	$r_{i} = b - A x_{i}$
solve	$A d_{i} = r_{i}$
compute	$x_{i + 1} = x_{i} + d_{i}$

In Chapter f04, functions are provided which perform this procedure using additional precision to compute

r

, and are thus able to reduce the forward error to the level of machine precision.

The functions in this chapter do not use additional precision to compute

r

, and cannot guarantee a small forward error, but can guarantee a small backward error (except in rare cases when

A

is very ill-conditioned, or when

A

and

x

are sparse in such a way that

|A| . |x|

has a zero or very small component). The iterations continue until the backward error has been reduced as much as possible; usually only one iteration is needed, and at most five iterations are allowed.

2.5 Matrix Inversion

It is seldom necessary to compute an explicit inverse of a matrix. In particular, do not attempt to solve

A x = b

by first computing

A^{- 1}

and then forming the matrix-vector product

x = A^{- 1} b

; the procedure described in Section 2.3 is more efficient and more accurate.

However, functions are provided for the rare occasions when an inverse is needed, using one of the factorizations described in Section 2.2.

2.6 Packed Storage

Functions which handle symmetric matrices are usually designed so that they use either the upper or lower triangle of the matrix; it is not necessary to store the whole matrix. If the upper or lower triangle is stored conventionally in the upper or lower triangle of a two-dimensional array, the remaining elements of the array can be used to store other useful data. However, that is not always convenient, and if it is important to economize on storage, the upper or lower triangle can be stored in a one-dimensional array of length

n (n + 1) / 2

; in other words, the storage is almost halved.

This storage format is referred to as packed storage; it is described in Section 3.3.2. It may also be used for triangular matrices.

Functions designed for packed storage perform the same number of arithmetic operations as functions which use conventional storage, but they are usually less efficient, especially on high-performance computers, so there is then a trade-off between storage and efficiency.

2.7 Band Matrices

A band matrix is one whose non-zero elements are confined to a relatively small number of sub-diagonals or super-diagonals on either side of the main diagonal. Algorithms can take advantage of bandedness to reduce the amount of work and storage required. The storage scheme used for band matrices is described in Section 3.3.3.

The

L U

factorization for general matrices, and the Cholesky factorization for symmetric positive-definite matrices both preserve bandedness. Hence functions are provided which take advantage of the band structure when solving systems of linear equations.

The Cholesky factorization preserves bandedness in a very precise sense: the factor

U

L

has the same number of super-diagonals or sub-diagonals as the original matrix. In the

L U

factorization, the row-interchanges modify the band structure: if

A

has

k_{l}

sub-diagonals and

k_{u}

super-diagonals, then

L

is not a band matrix but still has at most

k_{l}

non-zero elements below the diagonal in each column; and

U

has at most

k_{l} + k_{u}

super-diagonals.

The Bunch–Kaufman factorization does not preserve bandedness, because of the need for symmetric row-and-column permutations; hence no functions are provided for symmetric indefinite band matrices.

The inverse of a band matrix does not in general have a band structure, so no functions are provided for computing inverses of band matrices.

2.8 Block Algorithms

Many of the functions in this chapter use what is termed a block algorithm. This means that at each major step of the algorithm a block of rows or columns is updated, and most of the computation is performed by matrix-matrix operations on these blocks. The matrix-matrix operations are performed by calls to the Level 3 BLAS (see Chapter f16), which are the key to achieving high performance on many modern computers. See Golub and Van Loan (1996) or Anderson et al. (1999) for more about block algorithms.

The performance of a block algorithm varies to some extent with the blocksize – that is, the number of rows or columns per block. This is a machine-dependent parameter, which is set to a suitable value when the library is implemented on each range of machines. Users of the library do not normally need to be aware of what value is being used. Different block sizes may be used for different functions. Values in the range 16 to 64 are typical.

On some machines there may be no advantage from using a block algorithm, and then the functions use an unblocked algorithm (effectively a blocksize of 1), relying solely on calls to the Level 2 BLAS (see Chapter f16 again).

3 Recommendations on Choice and Use of Available Functions

3.1 Available Functions

Tables 1 and 2 in Section 3.5 show the functions which are provided for performing different computations on different types of matrices. Table 1 shows functions for real matrices; Table 2 shows functions for complex matrices. Each entry in the table gives the NAG function name, the LAPACK single precision name, and the LAPACK double precision name (see Section 3.2).

Functions are provided for the following types of matrix:

general
general band
symmetric or Hermitian positive-definite
symmetric or Hermitian positive-definite (packed storage)
symmetric or Hermitian positive-definite band
symmetric or Hermitian indefinite
symmetric or Hermitian indefinite (packed storage)
triangular
triangular (packed storage)
triangular band

For each of the above types of matrix (except where indicated), functions are provided to perform the following computations:

(except for triangular matrices) factorize the matrix (see Section 2.2);
solve a system of linear equations, using the factorization (see Section 2.3);
estimate the condition number of the matrix, using the factorization (see Section 2.4.2); these functions also require the norm of the original matrix (except when the matrix is triangular) which may be computed by a function in Chapter f16;
refine the solution and compute forward and backward error bounds (see Sections 2.4.3 and 2.4.4); these functions require the original matrix and right-hand side, as well as the factorization returned from (a) and the solution returned from (b);
(except for band matrices) invert the matrix, using the factorization (see Section 2.5).

Thus, to solve a particular problem, it is usually necessary to call two or more functions in succession. This is illustrated in the example programs in the function documents.

3.2 NAG Names and LAPACK Names

As well as the NAG function name (beginning f07-), Tables 1 and 2 show the LAPACK function names in both single and double precision.

The functions may be called either by their NAG short names or by their NAG long names. The NAG long names for a function is simply the LAPACK name (in lower case) prepended by nag_, for example, nag_dpotrf is the long name for f07fdc.

References to Chapter f07 functions in the Manual normally include the LAPACK double precision names, for example, nag_dgetrf (f07adc).

The LAPACK function names follow a simple scheme (which is similar to that used for the BLAS in Chapter f16). Each name has the structure XYYZZZ, where the components have the following meanings:

–

the initial letter X indicates the data type (real or complex) and precision:

	S – real, single precision
	D – real, double precision
	C – complex, single precision
	Z – complex, double precision

–

the 2nd and 3rd letters YY indicate the type of the matrix

A

(and in some cases its storage scheme):

	GE – general
	GB – general band
	PO – symmetric or Hermitian positive-definite
	PP – symmetric or Hermitian positive-definite (packed storage)
	PB – symmetric or Hermitian positive-definite band
	SY – symmetric indefinite
	SP – symmetric indefinite (packed storage)
	HE – (complex) Hermitian indefinite
	HP – (complex) Hermitian indefinite (packed storage)
	TR – triangular
	TP – triangular (packed storage)
	TB – triangular band

–

the last 3 letters ZZZ indicate the computation performed:

	TRF – triangular factorization
	TRS – solution of linear equations, using the factorization
	CON – estimate condition number
	RFS – refine solution and compute error bounds
	TRI – compute inverse, using the factorization

Thus the function SGETRF performs a triangular factorization of a real general matrix in a single precision implementation ; the corresponding function in a double precision implementation is DGETRF.

3.3 Matrix Storage Schemes

In this chapter the following different storage schemes are used for matrices:

– conventional storage;
– packed storage for symmetric, Hermitian or triangular matrices;
– band storage for band matrices.

These storage schemes are compatible with those used in Chapter f16 (especially in the BLAS) and Chapter f08, but different schemes for packed or band storage are used in a few older functions in Chapters f01, f02, f03 and f04.

In the examples below,

*

indicates an array element which need not be set and is not referenced by the functions. The examples illustrate only the relevant part of the arrays; array arguments may of course have additional rows or columns, according to the usual rules for passing array arguments in C or Fortran 77.

3.3.1 Conventional storage

Matrices may be stored column-wise or row-wise as described in Section 2.2.1.4 of the Essential Introduction: a matrix

A

is stored in a one-dimensional array a, with matrix element

a_{i, j}

stored column-wise in array element

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

or row-wise in array element

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

where pda is the principle dimension of the array (i.e., the stride separating row or column elements of the matrix respectively). Most functions in this chapter contain the order argument which can be set to Nag_ColMajor for column-wise storage or Nag_RowMajor for row-wise storage of matrices. Where groups of functions are intended to be used together, the value of the order argument passed must be consistent throughout.

If a matrix is triangular (upper or lower, as specified by the argument uplo), only the elements of the relevant triangle are stored; the remaining elements of the array need not be set. Such elements are indicated by * in the examples below.

For example, when

n = 3

order	uplo	Triangular matrix $A$	Storage in array a
Nag_ColMajor	Nag_Upper	$(\begin{array}{l} a_{11} & a_{12} & a_{13} \\ a_{22} & a_{23} \\ a_{33} \end{array})$	$a_{11} * * a_{12} a_{22} * a_{13} a_{23} a_{33}$
Nag_RowMajor	Nag_Upper	$(\begin{array}{l} a_{11} & a_{12} & a_{13} \\ a_{22} & a_{23} \\ a_{33} \end{array})$	$a_{11} a_{12} a_{13} * a_{22} a_{23} * * a_{33}$
Nag_ColMajor	Nag_Lower	$(\begin{array}{l} a_{11} \\ a_{21} & a_{22} \\ a_{31} & a_{32} & a_{33} \end{array})$	$a_{11} a_{21} a_{31} * a_{22} a_{32} * * a_{33}$
Nag_RowMajor	Nag_Lower	$(\begin{array}{l} a_{11} \\ a_{21} & a_{22} \\ a_{31} & a_{32} & a_{33} \end{array})$	$a_{11} * * a_{21} a_{22} * a_{31} a_{32} a_{33}$

Functions which handle symmetric or Hermitian matrices allow for either the upper or lower triangle of the matrix (as specified by uplo) to be stored in the corresponding elements of the array; the remaining elements of the array need not be set.

For example, when

n = 3

order	uplo	Hermitian matrix $A$	Storage in array a
Nag_ColMajor	Nag_Upper	$(\begin{array}{l} a_{11} & a_{12} & a_{13} \\ {\bar{a}}_{12} & a_{22} & a_{23} \\ {\bar{a}}_{13} & {\bar{a}}_{23} & a_{33} \end{array})$	$a_{11} * * a_{12} a_{22} * a_{13} a_{23} a_{33}$
Nag_RowMajor	Nag_Upper	$(\begin{array}{l} a_{11} & a_{12} & a_{13} \\ {\bar{a}}_{12} & a_{22} & a_{23} \\ {\bar{a}}_{13} & {\bar{a}}_{23} & a_{33} \end{array})$	$a_{11} a_{12} a_{13} * a_{22} a_{23} * * a_{33}$
Nag_ColMajor	Nag_Lower	$(\begin{array}{l} a_{11} & {\bar{a}}_{21} & {\bar{a}}_{31} \\ a_{21} & a_{22} & {\bar{a}}_{32} \\ a_{31} & a_{32} & a_{33} \end{array})$	$a_{11} a_{21} a_{31} * a_{22} a_{32} * * a_{33}$
Nag_RowMajor	Nag_Lower	$(\begin{array}{l} a_{11} & {\bar{a}}_{21} & {\bar{a}}_{31} \\ a_{21} & a_{22} & {\bar{a}}_{32} \\ a_{31} & a_{32} & a_{33} \end{array})$	$a_{11} * * a_{21} a_{22} * a_{31} a_{32} a_{33}$

3.3.2 Packed storage

Symmetric, Hermitian or triangular matrices may be stored more compactly, if the relevant triangle (again as specified by uplo) is packed by columns or rows in a one-dimensional array. In Chapters f07 and f08, arrays which hold matrices in packed storage have names ending in

P

. The storage of matrix elements

a_{i, j}

are stored in the packed array ap as follows:

if uplo = Nag_Upper then
- if $order = Nag_ColMajor$ , $a_{i j}$ is stored in $ap [(i - 1) + j (j - 1) / 2]$ for $i \leq j$ ;
- if $order = Nag_RowMajor$ , $a_{i j}$ is stored in $ap [(j - 1) + (2 n - i) (i - 1) / 2]$ for $i \leq j$ .
if uplo = Nag_Lower then
- if $order = Nag_ColMajor$ , $a_{i j}$ is stored in $ap [(i - 1) + (2 n - j) (j - 1) / 2]$ for $j \leq i$ ;
- if $order = Nag_RowMajor$ , $a_{i j}$ is stored in $ap [(j - 1) + i (i - 1) / 2]$ for $j \leq i$ .

For example:

order	uplo	Triangle of matrix $A$	Packed storage in array ap
Nag_ColMajor	Nag_Upper	$(\begin{array}{l} a_{11} & a_{12} & a_{13} \\ a_{22} & a_{23} \\ a_{33} \end{array})$	$a_{11} \underset{︸}{a_{12} a_{22}} \underset{︸}{a_{13} a_{23} a_{33}}$
Nag_RowMajor	Nag_Upper	$(\begin{array}{l} a_{11} & a_{12} & a_{13} \\ a_{22} & a_{23} \\ a_{33} \end{array})$	$\underset{︸}{a_{11} a_{12} a_{13}} \underset{︸}{a_{22} a_{23}} a_{33}$
Nag_ColMajor	Nag_Lower	$(\begin{array}{l} a_{11} \\ a_{21} & a_{22} \\ a_{31} & a_{32} & a_{33} \end{array})$	$\underset{︸}{a_{11} a_{21} a_{31}} \underset{︸}{a_{22} a_{32}} a_{33}$
Nag_RowMajor	Nag_Lower	$(\begin{array}{l} a_{11} \\ a_{21} & a_{22} \\ a_{31} & a_{32} & a_{33} \end{array})$	$a_{11} \underset{︸}{a_{21} a_{22}} \underset{︸}{a_{31} a_{32} a_{33}}$

Note that for real symmetric matrices, packing the upper triangle by columns is equivalent to packing the lower triangle by rows; packing the lower triangle by columns is equivalent to packing the upper triangle by rows. (For complex Hermitian matrices, the only difference is that the off-diagonal elements are conjugated.)

3.3.3 Band storage

A band matrix with

k_{l}

sub-diagonals and

k_{u}

super-diagonals may be stored compactly in a notional two-dimensional array with

k_{l} + k_{u} + 1

rows and

n

columns if stored column-wise or

n

rows and

k_{l} + k_{u} + 1

columns if stored row-wise. In column-major order, elements of a column of the matrix are stored contiguously in the array, and elements of the diagonals of the matrix are stored with constant stride (i.e., in a row of the two-dimensional array). In row-major order, elements of a row of the matrix are stored contiguously in the array, and elements of a diagonal of the matrix are stored with constant stride (i.e., in a column of the two-dimensional array). These storage schemes should only be used in practice if

k_{l}

k_{u} ≪ n

, although the functions in Chapters f07 and f08 work correctly for all values of

k_{l}

and

k_{u}

. In Chapters f07 and f08 arrays which hold matrices in band storage have names ending in

B

To be precise, elements of matrix elements

a_{i j}

are stored as follows:

if $order = Nag_ColMajor$ , $a_{i j}$ is stored in $ab [(k_{u} + i - j) \times pdab + j]$ ;
if $order = Nag_RowMajor$ , $a_{i j}$ is stored in $ab [(k_{l} + j - i) \times pdab + i]$ ,

where

pdab \geq k_{l} + k_{u} + 1

is the stride between diagonal elements and where

\max (1, i - k_{l}) \leq j \leq \min (n, i + k_{u})

For example, when

n = 5

k_{l} = 2

and

k_{u} = 1

Band matrix $A$	Band storage in array ab
	$order = Nag_ColMajor$	$order = Nag_RowMajor$
$\begin{array}{l} a_{11} & a_{12} \\ a_{21} & a_{22} & a_{23} \\ a_{31} & a_{32} & a_{33} & a_{34} \\ a_{42} & a_{43} & a_{44} & a_{45} \\ a_{53} & a_{54} & a_{55} \end{array}$	$\begin{array}{l} * & a_{12} & a_{23} & a_{34} & a_{45} \\ a_{11} & a_{22} & a_{33} & a_{44} & a_{55} \\ a_{21} & a_{32} & a_{43} & a_{54} & * \\ a_{31} & a_{42} & a_{53} & * & * \end{array}$	$\begin{array}{l} * & * & a_{11} & a_{12} \\ * & a_{21} & a_{22} & a_{23} \\ a_{31} & a_{32} & a_{33} & a_{34} \\ a_{42} & a_{43} & a_{44} & a_{45} \\ a_{53} & a_{54} & a_{55} & * \end{array}$

The elements marked

*

in the upper left and lower right corners of the array ab need not be set, and are not referenced by the functions.

Note: when a general band matrix is supplied for

L U

factorization, space must be allowed to store an additional

k_{l}

super-diagonals, generated by fill-in as a result of row interchanges. This means that the matrix is stored according to the above scheme, but with

k_{l} + k_{u}

super-diagonals.

Triangular band matrices are stored in the same format, with either

k_{l} = 0

if upper triangular, or

k_{u} = 0

if lower triangular.

For symmetric or Hermitian band matrices with

k

sub-diagonals or super-diagonals, only the upper or lower triangle (as specified by uplo) need be stored:

if uplo = Nag_Upper then
- if $order = Nag_ColMajor$ , $a_{i j}$ is stored in $ab [(j - 1) \times pdab + k + i - j]$ ;
- if $order = Nag_RowMajor$ , $a_{i j}$ is stored in $ab [(i - 1) \times pdab + j - i]$ .
for max⁡1,j-k≤i≤j;
if uplo = Nag_Lower then
- if $order = Nag_ColMajor$ , $a_{i j}$ is stored in $ab [(j - 1) \times pdab + i - j]$ ;
- if $order = Nag_RowMajor$ , $a_{i j}$ is stored in $ab [(i - 1) \times pdab + k + j - i]$ .
for j≤i≤min⁡n,j+k,

where

pdab \geq k + 1

is the stride separating diagonal matrix elements in the array ab.

For example, when

n = 5

and

k = 2

uplo	Hermitian band matrix $A$	Band storage in array a
		$order = Nag_ColMajor$	$order = Nag_RowMajor$
Nag_Upper	$(\begin{array}{l} a_{11} & a_{12} & a_{13} \\ {\bar{a}}_{12} & a_{22} & a_{23} & a_{24} \\ {\bar{a}}_{13} & {\bar{a}}_{23} & a_{33} & a_{34} & a_{35} \\ {\bar{a}}_{24} & {\bar{a}}_{34} & a_{44} & a_{45} \\ {\bar{a}}_{35} & {\bar{a}}_{45} & a_{55} \end{array})$	$\begin{array}{l} * & * & a_{13} & a_{24} & a_{35} \\ * & a_{12} & a_{23} & a_{34} & a_{45} \\ a_{11} & a_{22} & a_{33} & a_{44} & a_{55} \end{array}$	$\begin{array}{l} a_{11} & a_{12} & a_{13} \\ a_{22} & a_{23} & a_{24} \\ a_{33} & a_{34} & a_{35} \\ a_{44} & a_{45} & * \\ a_{55} & * & * \end{array}$
Nag_Lower	$(\begin{array}{l} a_{11} & {\bar{a}}_{21} & {\bar{a}}_{31} \\ a_{21} & a_{22} & {\bar{a}}_{32} & {\bar{a}}_{42} \\ a_{31} & a_{32} & a_{33} & {\bar{a}}_{43} & {\bar{a}}_{53} \\ a_{42} & a_{43} & a_{44} & {\bar{a}}_{54} \\ a_{53} & a_{54} & a_{55} \end{array})$	$\begin{array}{l} a_{11} & a_{22} & a_{33} & a_{44} & a_{55} \\ a_{21} & a_{32} & a_{43} & a_{54} & * \\ a_{31} & a_{42} & a_{53} & * & * \end{array}$	$\begin{array}{l} * & * & a_{11} \\ * & a_{21} & a_{22} \\ a_{31} & a_{32} & a_{33} \\ a_{42} & a_{43} & a_{44} \\ a_{53} & a_{54} & a_{55} \end{array}$

Note that different storage schemes for band matrices are used by some functions in Chapters f01, f02, f03 and f04.

3.3.4 Unit triangular matrices

Some functions in this chapter have an option to handle unit triangular matrices (that is, triangular matrices with diagonal elements

= 1

). This option is specified by an argument diag. If

diag

=

Nag_UnitDiag (Unit triangular), the diagonal elements of the matrix need not be stored, and the corresponding array elements are not referenced by the functions. The storage scheme for the rest of the matrix (whether conventional, packed or band) remains unchanged.

3.3.5 Real diagonal elements of complex matrices

Complex Hermitian matrices have diagonal elements that are by definition purely real. In addition, complex triangular matrices which arise in Cholesky factorization are defined by the algorithm to have real diagonal elements.

If such matrices are supplied as input to functions in this chapter, the imaginary parts of the diagonal elements are not referenced, but are assumed to be zero. If such matrices are returned as output by the functions, the computed imaginary parts are explicitly set to zero.

3.4 Parameter Conventions

3.4.1 Option parameters

In addition to the order argument of type Nag_OrderType, most functions in this Chapter have one or more option arguments of various types; only options of the correct type may be supplied.

For example,

 f07fdc(Nag_RowMajor,Nag_Upper,...)

3.4.2 Problem dimensions

It is permissible for the problem dimensions (for example,

M

N

NRHS

) to be passed as zero, in which case the computation (or part of it) is skipped. Negative dimensions are regarded as an error.

3.5 Tables of Available Functions

Type of matrix and storage scheme	factorize	solve	condition number	error estimate	invert
general	f07adc DGETRF	f07aec DGETRS	f07agc DGECON	f07ahc DGERFS	f07ajc DGETRI
general band	f07bdc DGBTRF	f07bec DGBTRS	f07bgc DGBCON	f07bhc DGBRFS
symmetric positive-definite	f07fdc DPOTRF	f07fec DPOTRS	f07fgc DPOCON	f07fhc DPORFS	f07fjc DPOTRI
symmetric positive-definite (packed storage)	f07gdc DPPTRF	f07gec DPPTRS	f07ggc DPPCON	f07ghc DPPRFS	f07gjc DPPTRI
symmetric positive-definite band	f07hdc DPBTRF	f07hec DPBTRS	f07hgc DPBCON	f07hhc DPBRFS
symmetric indefinite	f07mdc DSYTRF	f07mec DSYTRS	f07mgc DSYCON	f07mhc DSYRFS	f07mjc DSYTRI
symmetric indefinite (packed storage)	f07pdc DSPTRF	f07pec DSPTRS	f07pgc DSPCON	f07phc DSPRFS	f07pjc DSPTRI
triangular		f07tec DTRTRS	f07tgc DTRCON	f07thc DTRRFS	f07tjc DTRTRI
triangular (packed storage)		f07uec DTPTRS	f07ugc DTPCON	f07uhc DTPRFS	f07ujc DTPTRI
triangular band		f07vec DTBTRS	f07vgc DTBCON	f07vhc DTBRFS

Table 1

Each entry gives:

the NAG function short name
the LAPACK function name from which the NAG function long name is derived by prepending nag_.

Type of matrix and storage scheme	factorize	solve	condition number	error estimate	invert
general	f07arc ZGETRF	f07asc ZGETRS	f07auc ZGECON	f07avc ZGERFS	f07awc ZGETRI
general band	f07brc ZGBTRF	f07bsc ZGBTRS	f07buc ZGBCON	f07bvc ZGBRFS
Hermitian positive-definite	f07frc ZPOTRF	f07fsc ZPOTRS	f07fuc ZPOCON	f07fvc ZPORFS	f07fwc ZPOTRI
Hermitian positive-definite (packed storage)	f07grc ZPPTRF	f07gsc ZPPTRS	f07guc ZPPCON	f07gvc ZPPRFS	f07gwc ZPPTRI
Hermitian positive-definite band	f07hrc ZPBTRF	f07hsc ZPBTRS	f07huc ZPBCON	f07hvc ZPBRFS
Hermitian indefinite	f07mrc ZHETRF	f07msc ZHETRS	f07muc ZHECON	f07mvc ZHERFS	f07mwc ZHETRI
symmetric indefinite	f07nrc ZSYTRF	f07nsc ZSYTRS	f07nuc ZSYCON	f07nvc ZSYRFS	f07nwc ZSYTRI
Hermitian indefinite (packed storage)	f07prc ZHPTRF	f07psc ZHPTRS	f07puc ZHPCON	f07pvc ZHPRFS	f07pwc ZHPTRI
symmetric indefinite (packed storage)	f07qrc ZSPTRF	f07qsc ZSPTRS	f07quc ZSPCON	f07qvc ZSPRFS	f07qwc ZSPTRI
triangular		f07tsc ZTRTRS	f07tuc ZTRCON	f07tvc ZTRRFS	f07twc ZTRTRI
triangular (packed storage)		f07usc ZTPTRS	f07uuc ZTPCON	f07uvc ZTPRFS	f07uwc ZTPTRI
triangular band		f07vsc ZTBTRS	f07vuc ZTBCON	f07vvc ZTBRFS

Table 2

Each entry gives:

the NAG function short name
the LAPACK function name from which the NAG function long name is derived by prepending nag_.

4 Index

Apply iterative refinement to the solution and compute error estimates:
after factorizing the matrix of coefficients:
complex band matrix	f07bvc
complex Hermitian indefinite matrix	f07mvc
complex Hermitian indefinite matrix, packed storage	f07pvc
complex Hermitian positive-definite band matrix	f07hvc
complex Hermitian positive-definite matrix	f07fvc
complex Hermitian positive-definite matrix, packed storage	f07gvc
complex matrix	f07avc
complex symmetric indefinite matrix	f07nvc
complex symmetric indefinite matrix, packed storage	f07qvc
real band matrix	f07bhc
real matrix	f07ahc
real symmetric indefinite matrix	f07mhc
real symmetric indefinite matrix, packed storage	f07phc
real symmetric positive-definite band matrix	f07hhc
real symmetric positive-definite matrix	f07fhc
real symmetric positive-definite matrix, packed storage	f07ghc
Compute error estimates:
complex triangular band matrix	f07vvc
complex triangular matrix	f07tvc
complex triangular matrix, packed storage	f07uvc
real triangular band matrix	f07vhc
real triangular matrix	f07thc
real triangular matrix, packed storage	f07uhc
Condition number estimation:
after factorizing the matrix of coefficients:
complex band matrix	f07buc
complex Hermitian indefinite matrix	f07muc
complex Hermitian indefinite matrix, packed storage	f07puc
complex Hermitian positive-definite band matrix	f07huc
complex Hermitian positive-definite matrix	f07fuc
complex Hermitian positive-definite matrix, packed storage	f07guc
complex matrix	f07auc
complex symmetric indefinite matrix	f07nuc
complex symmetric indefinite matrix, packed storage	f07quc
real band matrix	f07bgc
real matrix	f07agc
real symmetric indefinite matrix	f07mgc
real symmetric indefinite matrix, packed storage	f07pgc
real symmetric positive-definite band matrix	f07hgc
real symmetric positive-definite matrix	f07fgc
real symmetric positive-definite matrix, packed storage	f07ggc
complex triangular band matrix	f07vuc
complex triangular matrix	f07tuc
complex triangular matrix, packed storage	f07uuc
real triangular band matrix	f07vgc
real triangular matrix	f07tgc
real triangular matrix, packed storage	f07ugc
$L L^{T}$ or $U^{T} U$ factorization:
complex Hermitian positive-definite band matrix	f07hrc
complex Hermitian positive-definite matrix	f07frc
complex Hermitian positive-definite matrix, packed storage	f07grc
real symmetric positive-definite band matrix	f07hdc
real symmetric positive-definite matrix	f07fdc
real symmetric positive-definite matrix, packed storage	f07gdc
$L U$ factorization:
complex band matrix	f07brc
complex matrix	f07arc
real band matrix	f07bdc
real matrix	f07adc
Matrix inversion:
after factorizing the matrix of coefficients:
complex Hermitian indefinite matrix	f07mwc
complex Hermitian indefinite matrix, packed storage	f07pwc
complex Hermitian positive-definite matrix	f07fwc
complex Hermitian positive-definite matrix, packed storage	f07gwc
complex matrix	f07awc
complex symmetric indefinite matrix	f07nwc
complex symmetric indefinite matrix, packed storage	f07qwc
real matrix	f07ajc
real symmetric indefinite matrix	f07mjc
real symmetric indefinite matrix, packed storage	f07pjc
real symmetric positive-definite matrix	f07fjc
real symmetric positive-definite matrix, packed storage	f07gjc
complex triangular matrix	f07twc
complex triangular matrix, packed storage	f07uwc
real triangular matrix	f07tjc
real triangular matrix, packed storage	f07ujc
$P L D L^{T} P^{T}$ or $P U D U^{T} P^{T}$ factorization:
complex Hermitian indefinite matrix	f07mrc
complex Hermitian indefinite matrix, packed storage	f07prc
complex symmetric indefinite matrix	f07nrc
complex symmetric indefinite matrix, packed storage	f07qrc
real symmetric indefinite matrix	f07mdc
real symmetric indefinite matrix, packed storage	f07pdc
Solution of simultaneous linear equations:
after factorizing the matrix of coefficients:
complex band matrix	f07bsc
complex Hermitian indefinite matrix	f07msc
complex Hermitian indefinite matrix, packed storage	f07psc
complex Hermitian positive-definite band matrix	f07hsc
complex Hermitian positive-definite matrix	f07fsc
complex Hermitian positive-definite matrix, packed storage	f07gsc
complex matrix	f07asc
complex symmetric indefinite matrix	f07nsc
complex symmetric indefinite matrix, packed storage	f07qsc
complex triangular band matrix	f07vsc
complex triangular matrix	f07tsc
complex triangular matrix, packed storage	f07usc
real band matrix	f07bec
real matrix	f07aec
real symmetric indefinite matrix	f07mec
real symmetric indefinite matrix, packed storage	f07pec
real symmetric positive-definite band matrix	f07hec
real symmetric positive-definite matrix	f07fec
real symmetric positive-definite matrix, packed storage	f07gec
real triangular matrix	f07tec
real triangular matrix, packed storage	f07uec
triangular band matrix	f07vec

5 Functions Withdrawn or Scheduled for Withdrawal

None.

6 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

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

Higham N J (1988) Algorithm 674: Fortran codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation ACM Trans. Math. Software 14 381–396

f07 Chapter Introduction (pdf version)

Chapter Contents

NAG C Library Contents

NAG C Library Chapter Introductionf07 — Linear Equations (LAPACK)

Contents

NAG C Library Chapter Introduction

f07 — Linear Equations (LAPACK)