# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# chol

Cholesky factorization

## Syntax

```R = chol(A) L = chol(A,'lower') R = chol(A,'upper') [R,p] = chol(A) [L,p] = chol(A,'lower') [R,p] = chol(A,'upper') [R,p,S] = chol(A) [R,p,s] = chol(A,'vector') [L,p,s] = chol(A,'lower','vector') [R,p,s] = chol(A,'upper','vector') ```

## Description

`R = chol(A)` produces an upper triangular matrix `R` from the diagonal and upper triangle of matrix `A`, satisfying the equation `R'*R=A`. The `chol` function assumes that `A` is (complex Hermitian) symmetric. If it is not, `chol` uses the (complex conjugate) transpose of the upper triangle as the lower triangle. Matrix `A` must be positive definite.

`L = chol(A,'lower')` produces a lower triangular matrix `L` from the diagonal and lower triangle of matrix `A`, satisfying the equation `L*L'=A`. The `chol` function assumes that `A` is (complex Hermitian) symmetric. If it is not, `chol` uses the (complex conjugate) transpose of the lower triangle as the upper triangle. When `A` is sparse, this syntax of `chol` is typically faster. Matrix `A` must be positive definite. ```R = chol(A,'upper')``` is the same as `R = chol(A)`.

`[R,p] = chol(A)` for positive definite `A`, produces an upper triangular matrix `R` from the diagonal and upper triangle of matrix `A`, satisfying the equation `R'*R=A` and `p` is zero. If `A` is not positive definite, then `p` is a positive integer and MATLAB® does not generate an error. When `A` is full, `R` is an upper triangular matrix of order `q=p-1` such that `R'*R=A(1:q,1:q)`. When `A` is sparse, `R` is an upper triangular matrix of size `q`-by-`n` so that the `L`-shaped region of the first `q` rows and first `q` columns of `R'*R` agree with those of `A`.

`[L,p] = chol(A,'lower')` for positive definite `A`, produces a lower triangular matrix `L` from the diagonal and lower triangle of matrix `A`, satisfying the equation `L*L'=A` and `p` is zero. If `A` is not positive definite, then `p` is a positive integer and MATLAB does not generate an error. When `A` is full, `L` is a lower triangular matrix of order `q=p-1` such that `L*L'=A(1:q,1:q)`. When `A` is sparse, `L` is a lower triangular matrix of size `q`-by-`n` so that the `L`-shaped region of the first `q` rows and first `q` columns of `L*L'` agree with those of `A`. `[R,p] = chol(A,'upper')` is the same as `[R,p] = chol(A)`.

The following three-output syntaxes require sparse input `A`.

`[R,p,S] = chol(A)`, when `A` is sparse, returns a permutation matrix `S`. Note that the preordering `S` may differ from that obtained from `amd` since `chol` will slightly change the ordering for increased performance. When `p=0`, `R` is an upper triangular matrix such that `R'*R=S'*A*S`. When `p` is not zero, `R` is an upper triangular matrix of size `q`-by-`n` so that the `L`-shaped region of the first `q` rows and first `q` columns of `R'*R` agree with those of `S'*A*S`. The factor of `S'*A*S` tends to be sparser than the factor of `A`.

`[R,p,s] = chol(A,'vector')`, when `A` is sparse, returns the permutation information as a vector `s` such that `A(s,s)=R'*R`, when `p=0`. You can use the `'matrix'` option in place of `'vector'` to obtain the default behavior.

`[L,p,s] = chol(A,'lower','vector')`, when `A` is sparse, uses only the diagonal and the lower triangle of `A` and returns a lower triangular matrix `L` and a permutation vector `s` such that `A(s,s)=L*L'`, when `p=0`. As above, you can use the `'matrix'` option in place of `'vector'` to obtain a permutation matrix. ```[R,p,s] = chol(A,'upper','vector')``` is the same as ```[R,p,s] = chol(A,'vector')```.

### Note

Using `chol` is preferable to using `eig` for determining positive definiteness.

## Examples

### Example 1

The `gallery` function provides several symmetric, positive, definite matrices.

```A=gallery('moler',5) A = 1 -1 -1 -1 -1 -1 2 0 0 0 -1 0 3 1 1 -1 0 1 4 2 -1 0 1 2 5 C=chol(A) ans = 1 -1 -1 -1 -1 0 1 -1 -1 -1 0 0 1 -1 -1 0 0 0 1 -1 0 0 0 0 1 isequal(C'*C,A) ans = 1```

For sparse input matrices, `chol` returns the Cholesky factor.

```N = 100; A = gallery('poisson', N); ```

`N` represents the number of grid points in one direction of a square `N`-by-`N` grid. Therefore, `A` is ${\text{N}}^{2}$ by ${\text{N}}^{2}$.

```L = chol(A, 'lower'); D = norm(A - L*L', 'fro');```

The value of `D` will vary somewhat among different versions of MATLAB but will be on order of ${10}^{-14}$.

### Example 2

The binomial coefficients arranged in a symmetric array create a positive definite matrix.

```n = 5; X = pascal(n) X = 1 1 1 1 1 1 2 3 4 5 1 3 6 10 15 1 4 10 20 35 1 5 15 35 70```

This matrix is interesting because its Cholesky factor consists of the same coefficients, arranged in an upper triangular matrix.

```R = chol(X) R = 1 1 1 1 1 0 1 2 3 4 0 0 1 3 6 0 0 0 1 4 0 0 0 0 1```

Destroy the positive definiteness (and actually make the matrix singular) by subtracting 1 from the last element.

```X(n,n) = X(n,n)-1 X = 1 1 1 1 1 1 2 3 4 5 1 3 6 10 15 1 4 10 20 35 1 5 15 35 69```

Now an attempt to find the Cholesky factorization of `X` fails.

```chol(X) Error using chol Matrix must be positive definite.```