NAG Library Routine Document
f01mcf (real_vband_posdef_fac)
1
Purpose
f01mcf computes the Cholesky factorization of a real symmetric positive definite variablebandwidth matrix.
2
Specification
Fortran Interface
Integer, Intent (In)  ::  n, lal  Integer, Intent (Inout)  ::  nrow(n), ifail  Real (Kind=nag_wp), Intent (In)  ::  a(lal)  Real (Kind=nag_wp), Intent (Out)  ::  al(lal), d(n) 

C Header Interface
#include <nagmk26.h>
void 
f01mcf_ (const Integer *n, const double a[], const Integer *lal, Integer nrow[], double al[], double d[], Integer *ifail) 

3
Description
f01mcf determines the unit lower triangular matrix $L$ and the diagonal matrix $D$ in the Cholesky factorization $A=LD{L}^{\mathrm{T}}$ of a symmetric positive definite variablebandwidth matrix $A$ of order $n$. (Such a matrix is sometimes called a ‘skyline’ matrix.)
The matrix
$A$ is represented by the elements lying within the
envelope of its lower triangular part, that is, between the first nonzero of each row and the diagonal (see
Section 10 for an example). The
width
${\mathbf{nrow}}\left(i\right)$ of the
$i$th row is the number of elements between the first nonzero element and the element on the diagonal, inclusive. Although, of course, any matrix possesses an envelope as defined, this routine is primarily intended for the factorization of symmetric positive definite matrices with an
average bandwidth which is small compared with
$n$ (also see
Section 9).
The method is based on the property that during Cholesky factorization there is no fillin outside the envelope.
The determination of
$L$ and
$D$ is normally the first of two steps in the solution of the system of equations
$Ax=b$. The remaining step, viz. the solution of
$LD{L}^{\mathrm{T}}x=b$, may be carried out using
f04mcf.
4
References
Jennings A (1966) A compact storage scheme for the solution of symmetric linear simultaneous equations Comput. J. 9 281–285
Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra Springer–Verlag
5
Arguments
 1: $\mathbf{n}$ – IntegerInput

On entry: $n$, the order of the matrix $A$.
Constraint:
${\mathbf{n}}\ge 1$.
 2: $\mathbf{a}\left({\mathbf{lal}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the elements within the envelope of the lower triangle of the positive definite symmetric matrix
$A$, taken in row by row order.
The following code assigns the matrix elements within the envelope to the correct elements of the array:
k = 0
Do 20 i = 1, n
Do 10 j = inrow(i)+1, i
k = k + 1
a(k) = matrix (i,j)
10 Continue
20 Continue
 3: $\mathbf{lal}$ – IntegerInput

On entry: the dimension of the arrays
a and
al as declared in the (sub)program from which
f01mcf is called.
Constraint:
${\mathbf{lal}}\ge {\mathbf{nrow}}\left(1\right)+{\mathbf{nrow}}\left(2\right)+\dots +{\mathbf{nrow}}\left(n\right)$.
 4: $\mathbf{nrow}\left({\mathbf{n}}\right)$ – Integer arrayInput

On entry: ${\mathbf{nrow}}\left(i\right)$ must contain the width of row $i$ of the matrix $A$, i.e., the number of elements between the first (leftmost) nonzero element and the element on the diagonal, inclusive.
Constraint:
$1\le {\mathbf{nrow}}\left(\mathit{i}\right)\le \mathit{i}$, for $\mathit{i}=1,2,\dots ,n$.
 5: $\mathbf{al}\left({\mathbf{lal}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the elements within the envelope of the lower triangular matrix
$L$, taken in row by row order. The envelope of
$L$ is identical to that of the lower triangle of
$A$. The unit diagonal elements of
$L$ are stored explicitly. See also
Section 9.
 6: $\mathbf{d}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the diagonal elements of the diagonal matrix $D$. Note that the determinant of $A$ is equal to the product of these diagonal elements. If the value of the determinant is required it should not be determined by forming the product explicitly, because of the possibility of overflow or underflow. The logarithm of the determinant may safely be formed from the sum of the logarithms of the diagonal elements.
 7: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, $I=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{nrow}}\left(I\right)=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nrow}}\left(I\right)\ge 1$ and ${\mathbf{nrow}}\left(I\right)\le I$.
On entry, ${\mathbf{lal}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{nrow}}\left(1\right)+\dots +{\mathbf{nrow}}\left({\mathbf{n}}\right)=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{lal}}\ge {\mathbf{nrow}}\left(1\right)+\dots +{\mathbf{nrow}}\left({\mathbf{n}}\right)$.
On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 1$.
 ${\mathbf{ifail}}=2$

$A$ is not positive definite. Factorization abandoned.
 ${\mathbf{ifail}}=3$

$A$ is not positive definite. Factorization completed.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
If
${\mathbf{ifail}}={\mathbf{0}}$ on exit, then the
computed
$L$ and
$D$ satisfy the relation
$LD{L}^{\mathrm{T}}=A+F$, where
and
where
$k$ is a constant of order unity,
$m$ is the largest value of
${\mathbf{nrow}}\left(i\right)$, and
$\epsilon $ is the
machine precision. See pages 25–27 and 54–55 of
Wilkinson and Reinsch (1971).
8
Parallelism and Performance
f01mcf is not threaded in any implementation.
The time taken by f01mcf is approximately proportional to the sum of squares of the values of ${\mathbf{nrow}}\left(i\right)$.
The distribution of row widths may be very nonuniform without undue loss of efficiency. Moreover, the routine has been designed to be as competitive as possible in speed with routines designed for full or uniformly banded matrices, when applied to such matrices.
Unless otherwise stated in the
Users' Note for your implementation, the routine may be called with the same actual array supplied for arguments
a and
al, in which case
$L$ overwrites the lower triangle of
a. However this is not standard Fortran and may not work in all implementations.
10
Example
This example obtains the Cholesky factorization of the symmetric matrix, whose lower triangle is:
For this matrix, the elements of
nrow must be set to
$1$,
$2$,
$2$,
$1$,
$5$,
$3$, and the elements within the envelope must be supplied in row order as:
10.1
Program Text
Program Text (f01mcfe.f90)
10.2
Program Data
Program Data (f01mcfe.d)
10.3
Program Results
Program Results (f01mcfe.r)