## `linalg::factorCholesky` -- the Cholesky decomposition of a matrix

#### Introduction

`linalg::factorCholesky``(A)` computes the Cholesky decomposition of a symmetric and positive definite matrix A and returns a lower triangular matrix R such that R^T*R = A.

#### Call(s)

`linalg::factorCholesky(A <, NoCheck>)`

#### Parameters

`A` | - | a square matrix of a domain of category `Cat::Matrix`

#### Options

`NoCheck` | - | It is not checked whether `A` is symmetric and positive definite.

#### Returns

a matrix of the same domain type as `A`, or the value `FAIL`.

#### Side Effects

Properties of identifiers are taken into account.

#### Related Functions

`linalg::isHermitean`, `linalg::isPosDef`

#### Details

- The system checks whether the matrix `A` is symmetric and positive definite, and returns an error message if this is not the case.
- The Option NoCheck suppresses such errors (see example 2).
- The component ring of `A` must be a field, i.e., a domain of category `Cat::Field`.
- `linalg::factorCholesky` returns `FAIL` if it fails to compute the matrix R over the component ring of `A` (the algorithm requires the computation of square roots of some elements in R).

#### Example 1

We compute the Cholesky decomposition of the following matrix:

    >> S := Dom::Matrix(Dom::Rational)(
         [[4, -2, 4, 2], [-2, 10, -2, -7], [4, -2, 8, 4], [2, -7, 4, 7]]
       )

                               +-                -+
                               |   4, -2,  4,  2  |
                               |                  |
                               |  -2, 10, -2, -7  |
                               |                  |
                               |   4, -2,  8,  4  |
                               |                  |
                               |   2, -7,  4,  7  |
                               +-                -+

    >> R := linalg::factorCholesky(S)

                                +-              -+
                                |   2,  0, 0, 0  |
                                |                |
                                |  -1,  3, 0, 0  |
                                |                |
                                |   2,  0, 2, 0  |
                                |                |
                                |   1, -2, 1, 1  |
                                +-              -+

and check the result:

    >> R * linalg::transpose(R) = S

                    +-                -+   +-                -+
                    |   4, -2,  4,  2  |   |   4, -2,  4,  2  |
                    |                  |   |                  |
                    |  -2, 10, -2, -7  |   |  -2, 10, -2, -7  |
                    |                  | = |                  |
                    |   4, -2,  8,  4  |   |   4, -2,  8,  4  |
                    |                  |   |                  |
                    |   2, -7,  4,  7  |   |   2, -7,  4,  7  |
                    +-                -+   +-                -+

#### Example 2

The option NoCheck can be helpful for matrices with symbolic components. For example, if we define the following matrix:

    >> delete a, b:
       H := matrix([[a, b], [b, a]])

                                    +-      -+
                                    |  a, b  |
                                    |        |
                                    |  b, a  |
                                    +-      -+

and have in mind that `a` and `b` are real, then `linalg::factorCholesky` is not able to check `H` to be positive definite:

    >> linalg::factorCholesky(H)

          Error: cannot check whether matrix component is positive \
          [linalg::factorCholesky]

With the option NoCheck such errors are suppressed and `linalg::factorCholesky` continues the computation:

    >> linalg::factorCholesky(H, NoCheck)

                             +-                     -+
                             |   1/2                 |
                             |  a   ,       0        |
                             |                       |
                             |        /      2 \1/2  |
                             |   b    |     b  |     |
                             |  ----, | a - -- |     |
                             |   1/2  \     a  /     |
                             |  a                    |
                             +-                     -+

Of course, this result is only valid if a > 0 and |b| < a.

#### Background

- The Cholesky decomposition of a positive definite n x n matrix A is a decomposition of A in a product A = R^T*R such that R is lower triangular and has positive (real) entries on the main diagonal.

  R is called the ``Cholesky factor'' of A.

- If R is the Cholesky factor of A, then det(A) = Prod( R[i,i], i=1..n )^2.

#### Changes

- used to be called `linalg::cholesky`
- The new option NoCheck was added.
- The option `isPositiveDefinite` is no longer available. Use the function `linalg::isPosDef` instead.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000