# chol

## Purpose

Cholesky factorization.

## Synopsis

    R = chol(X)
    [R,p] = chol(X)

## Description

`R = chol(X)`, where `X` is positive definite, produces an upper triangular `R` so that `R'*R = X`. If `X` is not positive definite, an error message is printed.`chol` uses only the diagonal and upper triangle of `X`. The lower triangular is assumed to be the (complex conjugate) transpose of the upper, that is, `X` is Hermitian.

`[R,p] = chol(X)` never produces an error message. If `X` is positive definite, then `p` is 0 and `R` is the same as above. If `X` is not positive definite, then `p` is a positive integer and `R` is an upper triangular matrix of order `q = p-1` so that `R'*R = X(1:q,1:q)`.

## Examples

The binomial coefficients arranged in a symmetric array create an interesting positive definite matrix.

    n = 5;
    X = pascal(n)

    X =
        1    1    1    1    1
        1    2    3    4    5
        1    3    6   10   15
        1    4   10   20   35
        1    5   15   35   70

It is interesting because its Cholesky factor consists of the same coefficients, arranged in an upper triangular matrix.

    R = chol(X)

    R =
        1    1    1    1    1
        0    1    2    3    4
        0    0    1    3    6
        0    0    0    1    4
        0    0    0    0    1

You can destroy the positive definiteness (and actually make the matrix singular) by subtracting 1 from the last element.

    X(n,n) = X(n,n)-1

    X =
        1    1    1    1    1
        1    2    3    4    5
        1    3    6   10   15
        1    4   10   20   35
        1    5   15   35   69

Now an attempt to find the Cholesky factorization fails.

## Algorithm

`chol` uses the algorithm from the LINPACK subroutine `ZPOFA`. For a detailed description of the use of the Cholesky decomposition, see Chapter 8 of the LINPACK User's Guide.

## References

[1] J.J. Dongarra, J.R. Bunch, C.B. Moler, and G.W. Stewart, LINPACK User's Guide, SIAM, Philadelphia, 1979.

(c) Copyright 1994 by The MathWorks, Inc.