

   TThhee CChhoolleesskkii DDeeccoommppoossiittiioonn

        chol(x)

   AArrgguummeennttss::

          x: a symmetric positive-definite matrix.

   VVaalluuee::

        This function computes the Choleski factorization of
        the square matrix `x'.  It returns the upper triangular
        factor of the decomposition, i.e., the matrix R such
        that R'R = x (see example).

        Note that effectively, only the upper triangular part
        of `x' is used such that the above only holds when `x'
        is symmetric.

   RReeffeerreenncceess::

        Dongarra, J. J., J. R. Bunch, C. B. Moler and G. W.
        Stewart (1978).  LINPACK Users Guide.  Philadelphia:
        SIAM Publications.

   SSeeee AAllssoo::

        `chol2inv' for its inverse, `backsolve' for solving
        linear systems with upper triangular left sides.

        `qr', `svd' for related matrix factorizations.

   EExxaammpplleess::

        ( m <- matrix(c(5,1,1,3),2,2) )
        ( cm <- chol(m) )
        t(cm) %*% cm  #-- = 'm'
        all(abs(m  -  t(cm) %*% cm) < 100* .Machine$double.eps) # TRUE

