%CHOL   Cholesky factorization.
%   R = CHOL(A) calculates the Cholesky factor of full or sparse A using
%   the diagonal and upper triangle of A, such that A = R'*R. A must be
%   positive definite, and the lower triangle is assumed to be the (complex
%   conjugate) transpose of the upper triangle.
%
%   R = CHOL(A,TRIANGLE) specifies which triangle of A to use. For example,
%   if TRIANGLE is 'lower', then CHOL uses only the diagonal and lower
%   triangle of A to produce a lower triangular R such that A = R*R'. The
%   default value of TRIANGLE is 'upper'. Using the 'lower' option is
%   equivalent to calling CHOL with the 'upper' option and the transpose of
%   A, and then transposing the output matrix R. In the following syntaxes,
%   the output R is described only for the case when TRIANGLE is 'upper'.
%
%   [R,FLAG] = CHOL(___) also returns the output FLAG indicating whether A
%   is positive definite. Use this syntax to suppress errors produced when
%   A is not positive definite.
%   * If A is positive definite, then FLAG is 0 and R is the same as above.
%   * If A is not positive definite, then FLAG is a positive integer. 
%       - If A is full, then R is an upper triangular matrix of size
%         q = FLAG-1 such that R'*R = A(1:q,1:q). 
%       - If A is sparse, then R is an upper triangular matrix of size
%         q-by-n such that the L-shaped region of the first q rows and
%         first q columns of R'*R agree with those of A.
%
%   [R,FLAG,P] = CHOL(S), for sparse S, additionally returns a permutation
%   matrix P, which is a preordering of S obtained by AMD. The Cholesky
%   factor of P'*S*P tends to be sparser than that of S.
%   If FLAG = 0, then R is an upper triangular matrix such that R'*R = P'*S*P.
%
%   [R,FLAG,p] = CHOL(___,OUTPUTFORM) specifies whether to return the
%   permutation information as a vector p or matrix P. With this syntax you
%   must specify a sparse input matrix S, and you optionally can specify
%   TRIANGLE. For example, if OUTPUTFORM is 'vector' and FLAG = 0, then
%   S(p,p) = R'*R. The default value of OUTPUTFORM is 'matrix' such that
%   P'*S*P = R'*R.
%
%   See also CHOLUPDATE, ICHOL, LDL, LU.

%   Copyright 1984-2018 The MathWorks, Inc.
%   Built-in function.

