Cholesky               package:Matrix               R Documentation

_C_h_o_l_e_s_k_y _D_e_c_o_m_p_o_s_i_t_i_o_n _o_f _a _S_p_a_r_s_e _M_a_t_r_i_x

_D_e_s_c_r_i_p_t_i_o_n:

     Computes the Cholesky decomposition of a sparse, symmetric,
     positive-definite matrix.  However, typically 'chol()' should
     rather be used unless you are interested in the different kinds of
     sparse Cholesky decompositions.

_U_s_a_g_e:

     Cholesky(A, perm = TRUE, LDL = !super, super = FALSE, Imult = 0, ...)

_A_r_g_u_m_e_n_t_s:

       A: sparse symmetric matrix.  No missing values or IEEE special
          values are allowed.

    perm: logical scalar indicating if a fill-reducing permutation
          should be computed and applied to the rows and columns of
          'A'. Default is 'TRUE'.

     LDL: logical scalar indicating if the decomposition should be
          computed as LDL' where 'L' is a unit lower triangular matrix.
          The alternative is LL' where 'L' is lower triangular with
          arbitrary diagonal elements.  Default is 'TRUE'.

   super: logical scalar indicating is a supernodal decomposition
          should be created.  The alternative is a simplicial
          decomposition. Default is 'FALSE'.

   Imult: numeric scalar which defaults to zero. The matrix that is
          decomposed is A+m*I where m is the value of 'Imult' and 'I'
          is the identity matrix of order 'ncol(A)'.

     ...: further arguments passed to or from other methods.

_D_e_t_a_i_l_s:

     This is a generic function with special methods for different
     types of matrices.  Use 'showMethods("Cholesky")' to list all the
     methods for the 'Cholesky' generic.

     The method for class 'dsCMatrix' of sparse matrices - the only one
     available currently - is based on functions from the CHOLMOD
     library.

     Again: If you just want the Cholesky decomposition of a matrix,
     you should probably rather use 'chol(.)'.

_V_a_l_u_e:

     an object inheriting from either '"CHMsuper"', or '"CHMsimpl"',
     depending on the 'super' argument; both classes extend
     '"CHMfactor"' which extends '"MatrixFactorization"'.

     In other words, the result of 'Cholesky()' is _not_ a matrix, and
     if you want one, you should probably rather use 'chol()'.

_R_e_f_e_r_e_n_c_e_s:

     Tim Davis (2005) _{CHOLMOD}: sparse supernodal {Cholesky}
     factorization and update/downdate_ <URL:
     http://www.cise.ufl.edu/research/sparse/cholmod/>

     Timothy A. Davis (2006) _Direct Methods for Sparse Linear
     Systems_, SIAM Series "Fundamentals of Algorithms".

_S_e_e _A_l_s_o:

     Class definitions 'CHMfactor' and 'dsCMatrix' and function
     'expand'. Note the extra 'solve(*, system = . )' options in
     'CHMfactor'.

     Note that 'chol()' returns matrices (inheriting from '"Matrix"')
     whereas 'Cholesky()' returns a '"CHMfactor"' object, and hence a
     typical user will rather use 'chol(A)'.

_E_x_a_m_p_l_e_s:

     data(KNex)
     mtm <- with(KNex, crossprod(mm))
     str(mtm@factors) # empty list()
     (C1 <- Cholesky(mtm))             # uses show(<MatrixFactorization>)
     str(mtm@factors) # 'sPDCholesky' (simpl)
     (Cm <- Cholesky(mtm, super = TRUE))
     str(mtm@factors) # 'sPDCholesky'  *and* 'SPdCholesky'
     str(cm1  <- as(C1, "sparseMatrix"))
     str(cmat <- as(Cm, "sparseMatrix"))# hmm: super is *less* sparse here
     cm1[1:20, 1:20]

     b <- matrix(c(rep(0, 711), 1), nc = 1)
     ## solve(Cm, b) by default solves  Ax = b, where A = Cm'Cm !
     x <- solve(Cm, b)
     stopifnot(identical(x, solve(Cm, b, system = "A")),
               all.equal(x, solve(mtm, b)))

     Cn <- Cholesky(mtm, perm = FALSE)# no permutation -- much worse:
     sizes <- c(simple = object.size(C1),
                super  = object.size(Cm),
                noPerm = object.size(Cn))
     format(cbind(100 * sizes / sizes[1]), digits=4)

     ## Visualize the sparseness:
     dq <- function(ch) paste('"',ch,'"', sep="") ## dQuote(<UTF-8>) gives bad plots
     image(mtm, main=paste("crossprod(mm) : Sparse", dq(class(mtm))))
     image(cm1, main= paste("as(Cholesky(crossprod(mm)),\"sparseMatrix\"):",
                             dq(class(cm1))))