Main Content

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

## More About

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

## See Also

Introduced in R2013a

## Support

#### Mathematical Modeling with Symbolic Math Toolbox

Get examples and videos