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, ...)
     isLDL(x)

_A_r_g_u_m_e_n_t_s:

object,x: 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:


     _i_s_L_D_L '(x)' returns a 'logical' indicating if 'x' is an LDL'
          decomposition or (when 'FALSE') an LL' one.

     _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 (currently) 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,  '"A"', is to solve Ax = b for x
          where 'A' is sparse, positive-definite matrix that was
          factored to produce 'a'.  Analogously, 'system = "L"' returns
          the solution x, of Lx = b; similarly, for all system codes
          *but* '"P"' and '"Pt"' where, e.g., 'x <- solve(a,
          b,system="P")' is equivalent to 'x <- P %*% b'.

     _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 factor L from the
          LL' decomposition (even if the decomposition represented by
          'x' is of the LDL' form (!)).  This is the square root of the
          determinant (half the logarithm of the determinant when
          'logarithm = TRUE') of the positive-definite matrix that was
          decomposed.

     _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)
     isLDL(CX)
     str(CX) ## a "dCHMsimpl" object
     r <- expand(CX)
     L.P <- with(r, crossprod(L,P))  ## == L'P
     PLLP <- crossprod(L.P)          ## == (L'P)' L'P == P'LL'P
     b <- sample(m)
     stopifnot(all.equal(PLLP, XX), 
               all(as.vector(solve(CX, b, system="P" )) == r$P %*% b),
               all(as.vector(solve(CX, b, system="Pt")) == t(r$P) %*% b) )

        ## [ See  help(Cholesky)  for more examples ]

