# chol

Cholesky factorization

## Syntax

```T = chol(A)[T,p] = chol(A)[T,p,S] = chol(A)[T,p,s] = chol(A,'vector')___ = chol(A,'lower')___ = chol(A,'nocheck')___ = chol(A,'real')___ = chol(A,'lower','nocheck','real')[T,p,s] = chol(A,'lower','vector','nocheck','real')```

## Description

`T = chol(A)` returns an upper triangular matrix `T`, such that ```T'*T = A```. `A` must be a Hermitian positive definite matrix. Otherwise, this syntax throws an error.

```[T,p] = chol(A)``` computes the Cholesky factorization of `A`. This syntax does not error if `A` is not a Hermitian positive definite matrix. If `A` is a Hermitian positive definite matrix, then `p` is 0. Otherwise, `T` is `sym([])`, and `p` is a positive integer (typically, `p = 1`).

```[T,p,S] = chol(A)``` returns a permutation matrix `S`, such that `T'*T = S'*A*S`, and the value ```p = 0``` if matrix `A` is Hermitian positive definite. Otherwise, it returns a positive integer `p` and an empty object `S = sym([])`.

```[T,p,s] = chol(A,'vector')``` returns the permutation information as a vector `s`, such that `A(s,s) = T'*T`. If `A` is not recognized as a Hermitian positive definite matrix, then `p` is a positive integer and `s = sym([])`.

`___ = chol(A,'lower')` returns a lower triangular matrix `T`, such that ```T*T' = A```.

`___ = chol(A,'nocheck')` skips checking whether matrix `A` is Hermitian positive definite. `'nocheck'` lets you compute Cholesky factorization of a matrix that contains symbolic parameters without setting additional assumptions on those parameters.

`___ = chol(A,'real')` computes the Cholesky factorization of `A` using real arithmetic. In this case, `chol` computes a symmetric factorization ```A = T.'*T``` instead of a Hermitian factorization ```A = T'*T```. This approach is based on the fact that if `A` is real and symmetric, then `T'*T = T.'*T`. Use `'real'` to avoid complex conjugates in the result.

`___ = chol(A,'lower','nocheck','real')` computes the Cholesky factorization of `A` with one or more of these optional arguments: `'lower'`, `'nocheck'`, and `'real'`. These optional arguments can appear in any order.

```[T,p,s] = chol(A,'lower','vector','nocheck','real')``` computes the Cholesky factorization of `A` and returns the permutation information as a vector `s`. You can use one or more of these optional arguments: `'lower'`, `'nocheck'`, and `'real'`. These optional arguments can appear in any order.

## Input Arguments

 `A` Symbolic matrix. `'lower'` Flag that prompts `chol` to return a lower triangular matrix instead of an upper triangular matrix. `'vector'` Flag that prompts `chol` to return the permutation information in the form of a vector. To use this flag, you must specify three output arguments. `'nocheck'` Flag that prompts `chol` to avoid checking whether matrix `A` is Hermitian positive definite. Use this flag if `A` contains symbolic parameters, and you want to avoid additional assumptions on these parameters. `'real'` Flag that prompts `chol` to use real arithmetic. Use this flag if `A` contains symbolic parameters, and you want to avoid complex conjugates.

## Output Arguments

 `T` Upper triangular matrix, such that `T'*T = A`, or lower triangular matrix, such that `T*T' = A`. `p` Value `0` if `A` is Hermitian positive definite or if you use `'nocheck'`. If `chol` does not identify `A` as a Hermitian positive definite matrix, then `p` is a positive integer. `R` is an upper triangular matrix of order `q = p - 1`, such that `R'*R = A(1:q,1:q)`. `S` Permutation matrix. `s` Permutation vector.

## Examples

Compute the Cholesky factorization of the 3-by-3 Hilbert matrix. Because these numbers are not symbolic objects, you get floating-point results.

`chol(hilb(3))`
```ans = 1.0000 0.5000 0.3333 0 0.2887 0.2887 0 0 0.0745```

Now convert this matrix to a symbolic object, and compute the Cholesky factorization:

`chol(sym(hilb(3)))`
```ans = [ 1, 1/2, 1/3] [ 0, 3^(1/2)/6, 3^(1/2)/6] [ 0, 0, 5^(1/2)/30]```

Compute the Cholesky factorization of the 3-by-3 Pascal matrix returning a lower triangular matrix as a result:

`chol(sym(pascal(3)), 'lower')`
```ans = [ 1, 0, 0] [ 1, 1, 0] [ 1, 2, 1]```

Try to compute the Cholesky factorization of this matrix. Because this matrix is not Hermitian positive definite, `chol` used without output arguments or with one output argument throws an error:

```A = sym([1 1 1; 1 2 3; 1 3 5]); ```
`T = chol(A)`
```Error using sym/chol (line 132) Cannot prove that input matrix is Hermitian positive definite. Define a Hermitian positive definite matrix by setting appropriate assumptions on matrix components, or use 'nocheck' to skip checking whether the matrix is Hermitian positive definite.```

To suppress the error, use two output arguments, `T` and `p`. If the matrix is not recognized as Hermitian positive definite, then this syntax assigns an empty symbolic object to `T` and the value `1` to `p`:

`[T,p] = chol(A)`
```T = [ empty sym ] p = 1```

For a Hermitian positive definite matrix, `p` is 0:

`[T,p] = chol(sym(pascal(3)))`
```T = [ 1, 1, 1] [ 0, 1, 2] [ 0, 0, 1] p = 0```

Compute the Cholesky factorization of the 3-by-3 inverse Hilbert matrix returning the permutation matrix:

```A = sym(invhilb(3)); [T, p, S] = chol(A)```
```T = [ 3, -12, 10] [ 0, 4*3^(1/2), -5*3^(1/2)] [ 0, 0, 5^(1/2)] p = 0 S = 1 0 0 0 1 0 0 0 1```

Compute the Cholesky factorization of the 3-by-3 inverse Hilbert matrix returning the permutation information as a vector:

```A = sym(invhilb(3)); [T, p, S] = chol(A, 'vector')```
```T = [ 3, -12, 10] [ 0, 4*3^(1/2), -5*3^(1/2)] [ 0, 0, 5^(1/2)] p = 0 S = 1 2 3```

Compute the Cholesky factorization of matrix `A` containing symbolic parameters. Without additional assumptions on the parameter `a`, this matrix is not Hermitian. To make `isAlways` return logical `0` (`false`) for undecidable conditions, set `Unknown` to `false`.

```syms a A = [a 0; 0 a]; isAlways(A == A','Unknown','false')```
```ans = 0 1 1 0```

By setting assumptions on `a` and `b`, you can define `A` to be Hermitian positive definite. Therefore, you can compute the Cholesky factorization of `A`:

```assume(a > 0) chol(A)```
```ans = [ a^(1/2), 0] [ 0, a^(1/2)]```

For further computations, remove the assumptions:

`syms a clear`

`'nocheck'` lets you skip checking whether `A` is a Hermitian positive definite matrix. Thus, this flag lets you compute the Cholesky factorization of a symbolic matrix without setting additional assumptions on its components:

```A = [a 0; 0 a]; chol(A,'nocheck')```
```ans = [ a^(1/2), 0] [ 0, a^(1/2)]```

If you use `'nocheck'` for computing the Cholesky factorization of a matrix that is not Hermitian positive definite, `chol` can return a matrix `T` for which the identity ```T'*T = A``` does not hold. To make `isAlways` return logical `0` (`false`) for undecidable conditions, set `Unknown` to `false`.

`T = chol(sym([1 1; 2 1]), 'nocheck')`
```T = [ 1, 2] [ 0, 3^(1/2)*1i]```
`isAlways(A == T'*T,'Unknown','false')`
```ans = 0 0 0 0```

Compute the Cholesky factorization of this matrix. To skip checking whether it is Hermitian positive definite, use `'nocheck'`. By default, `chol` computes a Hermitian factorization ```A = T'*T```. Thus, the result contains complex conjugates.

```syms a b A = [a b; b a]; T = chol(A, 'nocheck')```
```T = [ a^(1/2), conj(b)/conj(a^(1/2))] [ 0, (a*abs(a) - abs(b)^2)^(1/2)/abs(a)^(1/2)]```

To avoid complex conjugates in the result, use `'real'`:

`T = chol(A, 'nocheck', 'real')`
```T = [ a^(1/2), b/a^(1/2)] [ 0, ((a^2 - b^2)/a)^(1/2)]```

When you use this flag, `chol` computes a symmetric factorization `A = T.'*T` instead of a Hermitian factorization `A = T'*T`. To make `isAlways` return logical `0` (`false`) for undecidable conditions, set `Unknown` to `false`.

`isAlways(A == T.'*T)`
```ans = 1 1 1 1```
`isAlways(A == T'*T,'Unknown','false')`
```ans = 0 0 0 0```

expand all

### Hermitian Positive Definite Matrix

A square complex matrix A is Hermitian positive definite if `v'*A*v` is real and positive for all nonzero complex vectors `v`, where `v'` is the conjugate transpose (Hermitian transpose) of `v`.

### Cholesky Factorization of a Matrix

The Cholesky factorization of a Hermitian positive definite n-by-n matrix `A` is defined by an upper or lower triangular matrix with positive entries on the main diagonal. The Cholesky factorization of matrix `A` can be defined as `T'*T = A`, where `T` is an upper triangular matrix. Here `T'` is the conjugate transpose of `T`. The Cholesky factorization also can be defined as `T*T' = A`, where `T` is a lower triangular matrix. `T` is called the Cholesky factor of `A`.

### Tips

• Calling `chol` for numeric arguments that are not symbolic objects invokes the MATLAB® `chol` function.

• If you use `'nocheck'`, then the identities `T'*T = A` (for an upper triangular matrix `T`) and `T*T' = A` (for a lower triangular matrix `T`) are not guaranteed to hold.

• If you use `'real'`, then the identities ```T'*T = A``` (for an upper triangular matrix `T`) and `T*T' = A` (for a lower triangular matrix `T`) are only guaranteed to hold for a real symmetric positive definite `A`.

• To use `'vector'`, you must specify three output arguments. Other flags do not require a particular number of output arguments.

• If you use `'matrix'` instead of `'vector'`, then `chol` returns permutation matrices, as it does by default.

• If you use `'upper'` instead of `'lower'`, then `chol` returns an upper triangular matrix, as it does by default.

• If `A` is not a Hermitian positive definite matrix, then the syntaxes containing the argument `p` typically return `p = 1` and an empty symbolic object `T`.

• To check whether a matrix is Hermitian, use the operator `'` (or its functional form `ctranspose`). Matrix `A` is Hermitian if and only if ```A'= A```, where `A'` is the conjugate transpose of `A`.