# 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

example

````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.```

example

``````[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`).```

example

``````[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([])`.```

example

``````[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([])`.```

example

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

example

````___ = 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.```

example

````___ = 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.```

## Examples

### Compute Cholesky Factorization of Numeric and Symbolic Matrices

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]```

### Return Lower Triangular Matrix

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]```

### If Input is not Hermitian Positive Definite

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```

Alternatively, `'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 to make it Hermitian positive definite:

```syms a 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 = 2×2 logical array 0 0 0 0```

### Return Permutation Matrix

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```

### Return Permutation Information as Vector

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```

### Use Assumptions to Make Matrix Hermitian Positive Definite

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 = 2×2 logical array 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 on `a` by recreating it using `syms`:

`syms a`

### Return Real Result Without Complex Conjugates

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 = 2×2 logical array 1 1 1 1```
`isAlways(A == T'*T,'Unknown','false')`
```ans = 2×2 logical array 0 0 0 0```

## Input Arguments

collapse all

Input, specified as a number, vector, matrix, or array, or a symbolic number, variable, array, function, or expression.

## Output Arguments

collapse all

Upper triangular matrix, returned as a symbolic matrix such that ```T'*T = A```. If `T` is a lower triangular matrix, then `T*T' = A`.

Flag, returned as a symbolic number. 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)`.

Permutation matrix returned as a symbolic matrix.

Permutation vector returned as a symbolic vector.

## Limitations

Matrix computations involving many symbolic variables can be slow. To increase the computational speed, reduce the number of symbolic variables by substituting the given values for some variables.

collapse 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`.

## Version History

Introduced in R2013a