# cholfact(A)

cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor

Compute the Cholesky factorization of a sparse positive definite matrix `A`. A fill-reducing permutation is used. `F = cholfact(A)` is most frequently used to solve systems of equations with `F\b`, but also the methods `diag`, `det`, `logdet` are defined for `F`. You can also extract individual factors from `F`, using `F[:L]`. However, since pivoting is on by default, the factorization is internally represented as `A == P'*L*L'*P` with a permutation matrix `P`; using just `L` without accounting for `P` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like `PtL = F[:PtL]` (the equivalent of `P'*L`) and `LtP = F[:UP]` (the equivalent of `L'*P`).

Setting optional `shift` keyword argument computes the factorization of `A+shift*I` instead of `A`. If the `perm` argument is nonempty, it should be a permutation of `1:size(A,1)` giving the ordering to use (instead of CHOLMOD's default AMD ordering).

The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported.

## Examples

``````# Cholesky factorization of a matrix A
# Return type depends on the value of pivot

function cholfact(A, LU=:U, pivot=Val{false}; tol=-1.0)``````

Examples:

1. Compute Cholesky factorization of a matrix:

``````julia> A = [4.0 12.0 -16.0; 12.0 37.0 -43.0; -16.0 -43.0 98.0];
julia> F = cholfact(A);
julia> F[:U]
3×3 UpperTriangular{Float64,Array{Float64,2}}:
2.0  6.0  -8.0
⋅   1.0   5.0
⋅    ⋅    3.0``````
2. Compute Cholesky factorization with lower triangular matrix:

``````julia> A = [4.0 12.0 -16.0; 12.0 37.0 -43.0; -16.0 -43.0 98.0];
julia> F = cholfact(A, :L);
julia> F[:L]
3×3 LowerTriangular{Float64,Array{Float64,2}}:
2.0   ⋅   ⋅
6.0  1.0  ⋅
-8.0  5.0  3.0``````
3. Compute Cholesky factorization with pivoting:

``````julia> A = [4.0 12.0 -16.0; 12.0 37.0 -43.0; -16.0 -43.0 98.0];
julia> F = cholfact(A, pivot=Val{true});
julia> F[:U]
3×3 UpperTriangular{Float64,Array{Float64,2}}:
9.89949  -1.21268   1.61696
⋅    6.26343  -0.225991
⋅         ⋅     9.88671``````
4. Compute Cholesky factorization with custom tolerance:
``````julia> A = [4.0 12.0 -16.0; 12.0 37.0 -43.0; -16.0 -43.0 98.0];
julia> F = cholfact(A, tol=1e-5);``````

Additional Functions for `Cholesky` Objects:

1. `size`: Get the size of the Cholesky factorization.

``````julia> F = cholfact(A);
julia> size(F)
(3, 3)``````
2. `inv`: Compute the inverse of the original matrix `A` using the Cholesky factorization.

``````julia> F = cholfact(A);
julia> inv(F)
3×3 Array{Float64,2}:
0.25       -0.666667   -0.666667
-0.666667    0.777778    0.259259
-0.666667    0.259259    0.925926``````
3. `det`: Compute the determinant of the original matrix `A` using the Cholesky factorization.
``````julia> F = cholfact(A);
julia> det(F)
454.9999999999999``````

Additional Functions for `CholeskyPivoted` Objects:

1. `rank`: Compute the rank of the original matrix `A` using the Cholesky factorization with pivoting.
``````julia> F = cholfact(A, pivot=Val{true});
julia> rank(F)
3``````

Common Mistake:

``````julia> A = [1 2; 2 1];
julia> F = cholfact(A);
ERROR: PosDefException: matrix is not positive definite``````

In this example, the matrix `A` is not positive definite, but the `cholfact` function is called with the default `pivot=Val{false}` argument. If the matrix is not positive definite, a `PosDefException` exception is thrown. Make sure to check the positive definiteness of the matrix before using `cholfact`.