CHMfactor-class            package:Matrix            R Documentation

_C_H_O_L_M_O_D-_b_a_s_e_d _C_h_o_l_e_s_k_y _F_a_c_t_o_r_i_z_a_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     The virtual class '"CHMfactor"' is a class of CHOLMOD-based
     Cholesky factorizations of symmetric, sparse, compressed,
     column-oriented matrices.  Such a factorization is simplicial
     (virtual class '"CHMsimpl"') or supernodal (virtual class
     '"CHMsuper"').  Objects that inherit from these classes are either
     numeric factorizations (classes '"dCHMsimpl"' and '"dCHMsuper"')
     or symbolic factorizations (classes '"nCHMsimpl"' and
     '"nCHMsuper"').

_U_s_a_g_e:

     ## S4 method for signature 'CHMfactor':
     update(object, parent, mult = 0, ...)

_A_r_g_u_m_e_n_t_s:

  object: a '"CHMfactor"' object.

  parent: a '"dsCMatrix"' matrix or '"dgCMatrix"' object with the same
          nonzero pattern as the matrix that generated 'object'.  If
          'parent' is a symmetric matrix (class '"dsCMatrix"') then
          'object' should be a decomposition of a matrix with the same
          nonzero pattern as 'parent'.  If 'parent' is not symmetric
          then 'object' should be the decomposition of a matrix with
          the same nonzero pattern as 'tcrossprod(parent)'.

    mult: a numeric scalar (default 0).  'mult' times the identity
          matrix is (implicitly) added to 'parent' or
          'tcrossprod(parent)' before updating the decomposition
          'object'.

     ...: Optional additional arguments to the methods.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     Objects can be created by calls of the form 'new("dCHMsuper",
     ...)' but are more commonly created via 'Cholesky()', applied to 
     'dsCMatrix' or 'lsCMatrix' objects.

_S_l_o_t_s:

     of '"CHMfactor"' and all classes inheriting from it:

     '_p_e_r_m': An integer vector giving the 0-based permutation of the
          rows and columns chosen to reduce fill-in and for
          post-ordering.

     '_c_o_l_c_o_u_n_t': Object of class '"integer"' .... 

     '_t_y_p_e': Object of class '"integer"' .... 

     Slots of the non virtual classes "[dl]CHM(super|simpl)":

     '_p': Object of class '"integer"' of pointers, one for each column,
          to the initial (zero-based) index of elements in the column.
          Only present in classes that contain '"CHMsimpl"'.

     '_i': Object of class '"integer"' of length nnzero (number of
          non-zero elements).  These are the row numbers for each
          non-zero element in the matrix.  Only present in classes that
          contain '"CHMsimpl"'.

     '_x': For the '"d*"' classes: '"numeric"' - the non-zero elements
          of the matrix.

_M_e_t_h_o_d_s:


     _c_o_e_r_c_e 'signature(from = "CHMfactor", to = "sparseMatrix")'
          Returns the lower triangular factor L from the LL' form of
          the Cholesky factorization.  Note that the factor from the
          LL' form is always returned, even if the '"CHMfactor"' object
          represents an LDL' decomposition. Furthermore, this is the
          factor after any fill-reducing permutation has been applied. 
          See the 'expand' method for obtaining both the permutation
          matrix, P, and the lower Cholesky factor, L.

     _c_o_e_r_c_e 'signature(from = "CHMfactor", to = "pMatrix")' Returns the
          permutation matrix, P, representing the fill-reducing
          permutation used in the decomposition.

     _e_x_p_a_n_d 'signature(x = "CHMfactor")' Returns a list with components
          'P', the matrix representing the fill-reducing permutation,
          and 'L', the lower triangular Cholesky factor. The original
          positive-definite matrix corresponds to the product P'LL'P.
          Because of fill-in during the decomposition the product may
          apparently have more non-zeros than the original matrix, even
          after applying 'drop0' to it. However, the extra "non-zeros"
          should be very small in magnitude.

     _i_m_a_g_e 'signature(x = "CHMfactor")' Plot the image of the lower
          triangular factor, L, from the decomposition.  This method is
          equivalent to 'image(as(x, "sparseMatrix"))' so the comments
          in the above description of the 'coerce' method apply here
          too.

     _s_o_l_v_e 'signature(a = "CHMfactor", b = "ddenseMatrix")' The 'solve'
          methods for a '"CHMfactor"' object take an optional third
          argument 'system' whose value can be one of the character
          strings '"A"', '"LDLt"', '"LD"', '"DLt"', '"L"', '"Lt"',
          '"D"', '"P"' or '"Pt"'.  This argument describes the system
          to be solved.  The default is to solve 'Ax = b' for 'x' where
          'A' is sparse, positive-definite matrix that was factored to
          produce '"a"'.

     _s_o_l_v_e 'signature(a = "CHMfactor", b = "matrix")', and

     _s_o_l_v_e 'signature(a = "CHMfactor", b = "numeric")' call the above
          'signature(*, b = "ddenseMatrix")' method.

     _s_o_l_v_e 'signature(a = "CHMfactor", b = "dsparseMatrix")' takes the
          same third argument 'system' and calls the corresponding
          sparse CHOLMOD algorithm.

     _d_e_t_e_r_m_i_n_a_n_t 'signature(x = "CHMfactor", logarithm = "logical")'
          returns the determinant (or the logarithm of the determinant,
          if 'logarithm = TRUE', the default) of _the matrix whose
          decomposition is represented by_ 'x'.  The determinant of the
          decomposition is not well defined because the decomposition
          may be "LDL'" or "LL'".  The determinant of the original
          matrix that was decomposed is well defined.

     _u_p_d_a_t_e 'signature(object = "CHMfactor")'.  The 'update' method
          requires an additional argument 'parent', which is a
          '"dsCMatrix"' object with the same structure of nonzeros as
          the matrix that was decomposed to produce 'object', and
          provides an optional argument 'mult', a numeric scalar.  This
          method updates the numeric values in 'object' to the
          decomposition of A+mI where A is the matrix represented by
          'parent' and m is the scalar 'mult'. Because only the numeric
          values are updated this method should be faster than creating
          and decomposing A+mI.  It is not uncommon to want, say, the
          determinant of A+mI for many different values of m.  This
          method would be the preferred approach in such cases.


_S_e_e _A_l_s_o:

     'Cholesky', also for examples; class 'dgCMatrix'.

_E_x_a_m_p_l_e_s:

     ## An example for the expand() method
     n <- 1000; m <- 200; nnz <- 2000
     set.seed(1)
     M1 <- spMatrix(n, m,
                    i = sample(n, nnz, replace = TRUE),
                    j = sample(m, nnz, replace = TRUE),
                    x = round(rnorm(nnz),1))
     XX <- crossprod(M1)
     CX <- Cholesky(XX)
     str(CX) ## a "dCHMsimpl" object
     r <- expand(CX <- Cholesky(XX))
     L.P <- with(r, crossprod(L,P))  ## == L'P
     PLLP <- crossprod(L.P)          ## == (L'P)' L'P == P'LL'P
     stopifnot( all.equal(PLLP, XX) )