## `numeric::factorCholesky` -- Cholesky factorization of a matrix

#### Introduction

`numeric::factorCholesky``(A, ..)` returns a Cholesky factorization A=LL^H of a positive definite Hermitean matrix A.

`numeric::factorCholesky``(A, Symmetric, ..)` returns a Cholesky factorization A=LL^T of a symmetric matrix A.

#### Call(s)

`numeric::factorCholesky(A <, Symmetric> <, Symbolic> <, NoCheck>)`

#### Parameters

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

#### Options

`Symmetric` | - | makes `numeric::factorCholesky` compute a symmetric factorization A=LL^T rather than a Hermitean factorization A=LL^H
`Symbolic` | - | prevents `numeric::factorCholesky` from using floating point arithmetic
`NoCheck` | - | prevents `numeric::factorCholesky` from checking that the matrix is Hermitean and positive definite

#### Returns

The lower triangular Cholesky factor L is returned as a matrix of domain type `DOM_ARRAY`. Its components are real or complex floats, unless the option Symbolic is used. Without the option NoCheck an error is returned, if the matrix is not Hermitean or not positive definite.

#### Side Effects

Without the option Symbolic the function is sensitive to the environment variable `DIGITS`, which determines the numerical working precision.

#### Related Functions

`linalg::factorCholesky`, `numeric::factorLU`, `numeric::factorQR`

#### Details

- The Cholesky factorization of a square Hermitean matrix is A=LL^H, where L is a regular complex lower triangular matrix and L^H is the Hermitean transpose of L (i.e., the complex conjugate of the transpose of L). Such a factorization only exists, if A is positive definite.
- By default a numerical factorization is computed. If the option Symbolic is not used, then all components of the matrix are converted to floating point numbers. In this case the matrix must not contain symbolic objects that cannot be converted to floats. Numerical symbolic expressions such as `PI`, `sqrt(2)`, `exp(-1)` etc. are accepted.
- The Cholesky factor returned by `numeric::factorCholesky` is normalized such that its diagonal elements are real and positive.

#### Option: Symmetric

- The symmetric Cholesky factorization of a square symmetric matrix is A=LL^T, where L is a regular complex lower triangular matrix and L^T is the transpose of L. The matrix A does not have to be positive definite. Consequently, with the option Symmetric no internal check is performed whether A is positive definite. Note that the symmetric factorization with regular L does not exist for all matrices.
- For real symmetric positive definite matrices A the Cholesky factor L is real and the Hermitean factorization A=LL^H coincides with the symmetric factorization A=LL^T.

#### Option: Symbolic

- This option prevents conversion of the matrix entries to floats. The usual arithmetic for MuPAD expressions is used. With this option the matrix A may contain symbolic objects. Note that the option NoCheck must be used for the Hermitean factorization when non-numerical symbolic objects are present.

#### Option: NoCheck

- Without the option Symmetric `numeric::factorCholesky` checks that the matrix A is Hermitean and positive definite. The option NoCheck may be used to suppress these checks. It must be used when the matrix contains symbolic objects. Elements in the upper triangular part of the matrix will never be touched by the algorithm!

- This option is dangerous! It returns a result for matrices that are not Hermitean or not positive definite (i.e., no Cholesky factorization exists)!

- This option has no effect when the option Symmetric is used.

#### Example 1

We consider the matrix

    >> A := array(1..2, 1..2, [[1, I] , [-I, PI]]):

We compute a numerical factorization

    >> numeric::factorCholesky(A)

                             +-                     -+
                             |    1.0,        0      |
                             |                       |
                             |  - 1.0 I, 1.46341814  |
                             +-                     -+

and a symbolic factorization:

    >> L := numeric::factorCholesky(A, Symbolic, NoCheck)

                              +-                  -+
                              |   1,       0       |
                              |                    |
                              |               1/2  |
                              |  - I, (PI - 1)     |
                              +-                  -+

For further processing the Cholesky factor (of domain type `DOM_ARRAY`) is converted to an element of the matrix domain `Dom::Matrix()`:

    >> L := Dom::Matrix()(L):

Now the overloaded arithmetical operators `+`, `*`, `^` etc. can be used for further computations:

    >> L*linalg::transpose(map(L, conjugate))

                                   +-         -+
                                   |   1,   I  |
                                   |           |
                                   |  - I, PI  |
                                   +-         -+

    >> delete A, L:

#### Example 2

The following matrix is not positive definite:

    >> A := array(1..2, 1..2, [[-2, sqrt(2)], [sqrt(2), 1]]):

    >> numeric::factorCholesky(A)

          Error: matrix is not positive definite within working precision\
           [numeric::factorCholesky]

However, a symmetric factorization with a complex Cholesky factor does exist:

    >> numeric::factorCholesky(A, Symmetric)

                         +-                            -+
                         |  1.414213562 I,      0       |
                         |                              |
                         |     - 1.0 I,    1.414213562  |
                         +-                            -+

    >> delete A:

#### Example 3

The option NoCheck should be used, when the matrix contains symbolic objects:

    >> assume(x > 0): assume(z > 0):

    >> A := array(1..2, 1..2, [[x, conjugate(y)], [y, z]]):

    >> numeric::factorCholesky(A, Symbolic, NoCheck)

                          +-                          -+
                          |   1/2                      |
                          |  x   ,          0          |
                          |                            |
                          |        /           2 \1/2  |
                          |   y    |     abs(y)  |     |
                          |  ----, | z - ------- |     |
                          |   1/2  \        x    /     |
                          |  x                         |
                          +-                          -+

Note that with NoCheck it is assumed that the matrix is Hermitean and positive definite! All upper triangular entries ignored. The following result implicitly assumes `u=conjugate(y)`:

    >> A := array(1..2, 1..2, [[x, u], [y, z]]):

    >> numeric::factorCholesky(A, Symbolic, NoCheck)

                          +-                          -+
                          |   1/2                      |
                          |  x   ,          0          |
                          |                            |
                          |        /           2 \1/2  |
                          |   y    |     abs(y)  |     |
                          |  ----, | z - ------- |     |
                          |   1/2  \        x    /     |
                          |  x                         |
                          +-                          -+

    >> delete A:

#### Changes

- The new option Symmetric allows factorization of in-definite symmetric matrices.
- The return type was changed to `DOM_ARRAY`.

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