diff --git a/CHOLMOD/Config/cholmod.h.in b/CHOLMOD/Config/cholmod.h.in index f126766b2..34f442544 100644 --- a/CHOLMOD/Config/cholmod.h.in +++ b/CHOLMOD/Config/cholmod.h.in @@ -94,7 +94,7 @@ // parameter. It is always an input/output parameter. //------------------------------------------------------------------------------ -// CHOLMOD matrix formats NEW +// CHOLMOD matrix formats //------------------------------------------------------------------------------ // A CHOLMOD sparse, dense, or triplet matrix A, or a sparse factorization L @@ -120,9 +120,9 @@ // // (3): CHOLMOD_ZOMPLEX: The matrix is complex, with separate array for // the real and imaginary parts. The kth value in -// the matrix is held in A->x [k], where A->x and -// A->z can hold up to A->nzmax values each. -// +// the matrix is held in A->x [k] and A->z [k], +// where A->x and A->z can hold up to A->nzmax +// values each. // A->xtype values: #define CHOLMOD_PATTERN 0 @@ -140,7 +140,7 @@ // zomplex, both A->x and A->z have size A->nzmax // * sizeof (double). // -// (1) CHOLMOD_SINGLE: A->x (and A->z for zomplex matrices) is float. +// (4) CHOLMOD_SINGLE: A->x (and A->z for zomplex matrices) is float. // If A is real, A->x has a size of A->nzmax * // sizeof (float). If A is complex, A->x has size // A->nzmax * 2 * sizeof (float). If zomplex, @@ -684,7 +684,7 @@ typedef struct cholmod_common_struct int64_t mark ; // Flag is cleared if Flag [0..nrow-1] < mark. size_t iworksize ; // size of Iwork, in Ints (int32 or int64). // This is at most 6*nrow + ncol. - size_t xworkbytes ; // size of Xwork, in bytes. // NEW (revised defn) + size_t xworkbytes ; // size of Xwork, in bytes. // NOTE: in CHOLMOD v4 and earlier, xworkwise was in terms // of # of doubles, not # of bytes. @@ -801,11 +801,11 @@ typedef struct cholmod_common_struct // as well. This mitigates any changes between v4.0 and v5.0, and may make // it easier to upgrade from v4 to v5. - double nsbounds_hit ; // # of times diagonal modified by sbound. // NEW + double nsbounds_hit ; // # of times diagonal modified by sbound. // This ought to be int64_t, but ndbounds_hit was double in // v4 (see above), so nsbounds_hit is made the same type // for consistency. - float sbound ; // Same as dbound, // NEW + float sbound ; // Same as dbound, // but for single precision factorization. float other_6 ; // for future expansion @@ -970,7 +970,7 @@ int cholmod_l_allocate_work (size_t, size_t, size_t, cholmod_common *) ; // Added for CHOLMOD v5: allocates Xwork as either double or single. -int cholmod_alloc_work // NEW +int cholmod_alloc_work ( // input: size_t nrow, // size of Common->Flag (nrow int32's) @@ -1031,8 +1031,8 @@ int cholmod_l_error (int, const char *, int, const char *, cholmod_common *) ; double cholmod_dbound (double, cholmod_common *) ; double cholmod_l_dbound (double, cholmod_common *) ; -float cholmod_sbound (float, cholmod_common *) ; // NEW -float cholmod_l_sbound (float, cholmod_common *) ; // NEW +float cholmod_sbound (float, cholmod_common *) ; +float cholmod_l_sbound (float, cholmod_common *) ; //------------------------------------------------------------------------------ // cholmod_hypot: compute sqrt (x*x + y*y) accurately @@ -1092,7 +1092,7 @@ typedef struct cholmod_sparse_struct // if CHOLMOD_INT, these arrays are all of type int32_t. // if CHOLMOD_LONG, these arrays are all of type int64_t. int xtype ; // pattern, real, complex, or zomplex - int dtype ; // x and z are double or single // NEW (now used) + int dtype ; // x and z are double or single int sorted ; // true if columns are sorted, false otherwise int packed ; // true if packed (A->nz ignored), false if unpacked @@ -1111,7 +1111,7 @@ cholmod_sparse *cholmod_allocate_sparse int sorted, // true if columns are sorted int packed, // true if A is be packed (A->nz NULL), false if unpacked int stype, // the stype of the matrix (unsym, tril, or triu) - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1166,7 +1166,7 @@ cholmod_sparse *cholmod_speye // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1186,7 +1186,7 @@ cholmod_sparse *cholmod_spzeros // return a sparse matrix with no entries size_t nrow, // # of rows size_t ncol, // # of columns size_t nzmax, // max # of entries the matrix can hold - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1202,7 +1202,7 @@ cholmod_sparse *cholmod_transpose // return new sparse matrix C ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.) // 0: pattern (with diag) cholmod_common *Common @@ -1221,7 +1221,7 @@ int cholmod_transpose_unsym ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.), // 0: pattern (with diag) int32_t *Perm, // permutation for C=A(p,f)', or NULL @@ -1246,7 +1246,7 @@ int cholmod_transpose_sym ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.), // 0: pattern (with diag) int32_t *Perm, // permutation for C=A(p,p)', or NULL @@ -1265,7 +1265,7 @@ cholmod_sparse *cholmod_ptranspose // return new sparse matrix C ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.) // 0: pattern (with diag) int32_t *Perm, // permutation for C=A(p,f)', or NULL @@ -1292,7 +1292,7 @@ int cholmod_l_sort (cholmod_sparse *, cholmod_common *) ; // cholmod_band_nnz: # of entries within a band of a sparse matrix //------------------------------------------------------------------------------ -int64_t cholmod_band_nnz // return # of entries in a band (-1 if error) // NEW +int64_t cholmod_band_nnz // return # of entries in a band (-1 if error) ( // input: cholmod_sparse *A, // matrix to examine @@ -1347,7 +1347,7 @@ cholmod_sparse *cholmod_aat // return sparse matrix C cholmod_sparse *A, // input matrix int32_t *fset, // a list of column indices in range 0:A->ncol-1 size_t fsize, // # of entries in fset - int mode, // 2: numerical (conj) NEW + int mode, // 2: numerical (conj) // 1: numerical (non-conj.), // 0: pattern (with diag) // -1: pattern (remove diag), @@ -1382,7 +1382,7 @@ cholmod_sparse *cholmod_copy // return new sparse matrix // input: cholmod_sparse *A, // input matrix, not modified int stype, // stype of C - int mode, // 2: numerical (conj) NEW + int mode, // 2: numerical (conj) // 1: numerical (non-conj.) // 0: pattern (with diag) // -1: pattern (remove diag) @@ -1402,7 +1402,7 @@ cholmod_sparse *cholmod_add // return C = alpha*A + beta*B cholmod_sparse *B, // input matrix double alpha [2], // scale factor for A (two entires used if complex) double beta [2], // scale factor for A (two entires used if complex) - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern int sorted, // ignored; C is now always returned as sorted @@ -1418,7 +1418,7 @@ cholmod_sparse *cholmod_l_add (cholmod_sparse *, cholmod_sparse *, double *, int cholmod_sparse_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_sparse *A, // sparse matrix to change cholmod_common *Common @@ -1451,24 +1451,19 @@ typedef struct cholmod_factor_struct // simplicial factorization (not supernodal) //-------------------------------------------------------------------------- - size_t nzmax ; // # of entries that L->i, L->x, and L->z can hold + // The row indices of L(:,j) are held in L->i [L->p [j] ... L->p [j] + + // L->nz [j] - 1]. The numeical values of L(:,j) are held in the same + // positions in L->x (and L->z if L is zomplex). L->next and L->prev hold + // a link list of columns of L, that tracks the order they appear in the + // arrays L->i, L->x, and L->z. The head and tail of the list is n+1 and + // n, respectively. + size_t nzmax ; // # of entries that L->i, L->x, and L->z can hold void *p ; // int32/int64, size n+1, column pointers void *i ; // int32/int64, size nzmax, row indices void *x ; // float/double, size nzmax or 2*nzmax, numerical values void *z ; // float/double, size nzmax or empty, imaginary values void *nz ; // int32/int64, size ncol, # of entries in each column - - // The row indices of L(:,j) are held in - // L->i [L->p [j] ... L->p [j] + L->nz [j] - 1]. - - // The numeical values of L(:,j) are held in the same positions in L->x - // (and L->z if L is zomplex) - - // L->next and L->prev hold a link list of columns of L, that tracks the - // order they appear in the arrays L->i, L->x, and L->z. The head and tail - // of the list is n+1 and n, respectively. - void *next ; // int32/int64, size n+2 void *prev ; // int32/int64, size n+2 @@ -1484,13 +1479,12 @@ typedef struct cholmod_factor_struct size_t xsize ; // # of entries in L->x size_t maxcsize ; // size of largest update matrix size_t maxesize ; // max # of rows in supernodes, excl. triangular part - // the following are int32/int64 and are size nsuper+1: void *super ; // first column in each supernode void *pi ; // index into L->s for integer part of a supernode void *px ; // index into L->x for numeric part of a supernode - - void *s ; // int32/int64, ssize, integer part of supernodes + // int32/int64, of size ssize: + void *s ; // integer part of supernodes //-------------------------------------------------------------------------- // type of the factorization @@ -1524,7 +1518,6 @@ typedef struct cholmod_factor_struct // If L->xtype is CHOLMOD_REAL, CHOLMOD_COMPLEX, or CHOLMOD_ZOMPLEX, // then L is a numeric factor: // - // // simplicial LDL': (is_ll false, is_super false). Stored in compressed // column form, using the simplicial components above (nzmax, p, i, // x, z, nz, next, and prev). The unit diagonal of L is not stored, @@ -1546,7 +1539,7 @@ typedef struct cholmod_factor_struct // if L->itype is CHOLMOD_LONG. int xtype ; // pattern, real, complex, or zomplex - int dtype ; // x and z are double or single // NEW + int dtype ; // x and z are double or single int useGPU; // if true, symbolic factorization allows for use of the GPU @@ -1570,7 +1563,7 @@ cholmod_factor *cholmod_l_allocate_factor (size_t, cholmod_common *) ; // cholmod_alloc_factor: allocate a numerical factor (double or single) //------------------------------------------------------------------------------ -cholmod_factor *cholmod_alloc_factor // return the new factor L // NEW +cholmod_factor *cholmod_alloc_factor // return the new factor L ( // input: size_t n, // L is factorization of an n-by-n matrix @@ -1688,7 +1681,7 @@ cholmod_factor *cholmod_l_copy_factor (cholmod_factor *, cholmod_common *) ; int cholmod_factor_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_factor *L, // factor to change cholmod_common *Common @@ -1722,7 +1715,7 @@ cholmod_dense *cholmod_allocate_dense size_t nrow, // # of rows size_t ncol, // # of columns size_t d, // leading dimension - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1739,7 +1732,7 @@ cholmod_dense *cholmod_zeros // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1755,7 +1748,7 @@ cholmod_dense *cholmod_ones // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1771,7 +1764,7 @@ cholmod_dense *cholmod_eye // return a dense identity matrix // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1802,7 +1795,7 @@ cholmod_dense *cholmod_ensure_dense size_t nrow, // # of rows size_t ncol, // # of columns size_t d, // leading dimension - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1826,7 +1819,7 @@ cholmod_dense *cholmod_l_sparse_to_dense (cholmod_sparse *, cholmod_common *) ; // cholmod_dense_nnz: count # of nonzeros in a dense matrix //------------------------------------------------------------------------------ -int64_t cholmod_dense_nnz // return # of entries in the dense matrix // NEW +int64_t cholmod_dense_nnz // return # of entries in the dense matrix ( // input: cholmod_dense *X, // input matrix @@ -1842,7 +1835,7 @@ cholmod_sparse *cholmod_dense_to_sparse // return a sparse matrix C ( // input: cholmod_dense *X, // input matrix - int mode, // 1: copy the values NEW + int mode, // 1: copy the values // 0: C is pattern cholmod_common *Common ) ; @@ -1882,7 +1875,7 @@ int cholmod_l_copy_dense2 (cholmod_dense *, cholmod_dense *, cholmod_common *) ; int cholmod_dense_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_dense *X, // dense matrix to change cholmod_common *Common @@ -1927,7 +1920,7 @@ typedef struct cholmod_triplet_struct // if CHOLMOD_INT, these arrays are all of type int32_t. // if CHOLMOD_LONG, these arrays are all of type int64_t. int xtype ; // pattern, real, complex, or zomplex - int dtype ; // x and z are double or single // NEW + int dtype ; // x and z are double or single } cholmod_triplet ; @@ -1942,7 +1935,7 @@ cholmod_triplet *cholmod_allocate_triplet // return triplet matrix T size_t ncol, // # of columns size_t nzmax, // max # of entries the matrix can hold int stype, // the stype of the matrix (unsym, tril, or triu) - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -2022,7 +2015,7 @@ cholmod_triplet *cholmod_l_copy_triplet (cholmod_triplet *, cholmod_common *) ; int cholmod_triplet_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_triplet *T, // triplet matrix to change cholmod_common *Common @@ -2089,7 +2082,7 @@ int cholmod_realloc_multiple // returns true if successful, false otherwise size_t nnew, // # of items in newly reallocate memory int nint, // 0: do not allocate I_block or J_block, 1: just I_block, // 2: both I_block and J_block - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) // input/output: @@ -2398,7 +2391,7 @@ int cholmod_l_print_parent (int64_t *, size_t, const char *, cholmod_common *) ; // cholmod_read_sparse: read a sparse matrix from a file (double only) //------------------------------------------------------------------------------ -cholmod_sparse *cholmod_read_sparse +cholmod_sparse *cholmod_read_sparse // return sparse matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2410,7 +2403,7 @@ cholmod_sparse *cholmod_l_read_sparse (FILE *, cholmod_common *) ; // cholmod_read_sparse2: read a sparse matrix from a file (float or double) //------------------------------------------------------------------------------ -cholmod_sparse *cholmod_read_sparse2 // NEW +cholmod_sparse *cholmod_read_sparse2 // return sparse matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2423,7 +2416,7 @@ cholmod_sparse *cholmod_l_read_sparse2 (FILE *, int, cholmod_common *) ; // cholmod_read_triplet: read a triplet matrix from a file (double only) //------------------------------------------------------------------------------ -cholmod_triplet *cholmod_read_triplet +cholmod_triplet *cholmod_read_triplet // return triplet matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2435,7 +2428,7 @@ cholmod_triplet *cholmod_l_read_triplet (FILE *, cholmod_common *) ; // cholmod_read_triplet: read a triplet matrix from a file (float or double) //------------------------------------------------------------------------------ -cholmod_triplet *cholmod_read_triplet2 // NEW +cholmod_triplet *cholmod_read_triplet2 // return triplet matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2448,7 +2441,7 @@ cholmod_triplet *cholmod_l_read_triplet2 (FILE *, int, cholmod_common *) ; // cholmod_read_dense: read a dense matrix from a file (double only) //------------------------------------------------------------------------------ -cholmod_dense *cholmod_read_dense +cholmod_dense *cholmod_read_dense // return dense matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2460,7 +2453,7 @@ cholmod_dense *cholmod_l_read_dense (FILE *, cholmod_common *) ; // cholmod_read_dense2: read a dense matrix from a file (float or double) //------------------------------------------------------------------------------ -cholmod_dense *cholmod_read_dense2 // NEW +cholmod_dense *cholmod_read_dense2 // return dense matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2473,7 +2466,7 @@ cholmod_dense *cholmod_l_read_dense2 (FILE *, int, cholmod_common *) ; // cholmod_read_matrix: read a sparse or dense matrix from a file (double only) //------------------------------------------------------------------------------ -void *cholmod_read_matrix +void *cholmod_read_matrix // return sparse/triplet/double matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2498,7 +2491,7 @@ void *cholmod_l_read_matrix (FILE *, int, int *, cholmod_common *) ; // cholmod_read_matrix2: read a sparse or dense matrix (float or double) //------------------------------------------------------------------------------ -void *cholmod_read_matrix2 // NEW +void *cholmod_read_matrix2 // sparse/triplet/double matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2638,6 +2631,8 @@ cholmod_factor *cholmod_l_analyze_p (cholmod_sparse *, int64_t *, int64_t *, // cholmod_analyze_p2: analyze for sparse Cholesky or sparse QR //------------------------------------------------------------------------------ +// This is normally not need by the user application. + cholmod_factor *cholmod_analyze_p2 ( // input: @@ -2875,7 +2870,7 @@ int cholmod_l_colamd (cholmod_sparse *, int64_t *, size_t, int, int64_t *, // identity matrix. Row k can only be factorized if all descendants of node // k in the elimination tree have been factorized. -int cholmod_rowfac +int cholmod_rowfac ( // input: cholmod_sparse *A, // matrix to factorize @@ -2894,8 +2889,9 @@ int cholmod_l_rowfac (cholmod_sparse *, cholmod_sparse *, double *, size_t, // cholmod_rowfac_mask: incremental simplicial factorization //------------------------------------------------------------------------------ -// cholmod_rowfac_mask is a version of cholmod_rowfac that is specific to -// LPDASA. It is unlikely to be needed by any other application. +// cholmod_rowfac_mask and cholmod_rowfac_mask2 are version of cholmod_rowfac +// that are specific to LPDASA. It is unlikely to be needed by any other +// application, and is not documented in the CHOLMOD User Guide. int cholmod_rowfac_mask ( @@ -3148,7 +3144,7 @@ cholmod_sparse *cholmod_horzcat // returns C = [A B] // input: cholmod_sparse *A, // left matrix to concatenate cholmod_sparse *B, // right matrix to concatenate - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern cholmod_common *Common @@ -3213,7 +3209,7 @@ cholmod_sparse *cholmod_ssmult // return C=A*B cholmod_sparse *A, // left matrix to multiply cholmod_sparse *B, // right matrix to multiply int stype, // requested stype of C - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern int sorted, // if TRUE then return C with sorted columns @@ -3243,7 +3239,7 @@ cholmod_sparse *cholmod_submatrix // return C = A (rset,cset) int64_t rsize, // size of rset, or -1 for ":" int32_t *cset, // set of column indices, duplicates OK int64_t csize, // size of cset, or -1 for ":" - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern int sorted, // if TRUE then return C with sorted columns @@ -3265,7 +3261,7 @@ cholmod_sparse *cholmod_vertcat // returns C = [A ; B] // input: cholmod_sparse *A, // top matrix to concatenate cholmod_sparse *B, // bottom matrix to concatenate - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric // 0: pattern cholmod_common *Common @@ -3861,7 +3857,7 @@ int64_t cholmod_l_collapse_septree (size_t, size_t, double, size_t, int64_t *, // factorization. The user need not call this directly; cholmod_analyze is // a "simple" wrapper for this routine. -int cholmod_super_symbolic +int cholmod_super_symbolic ( // input: cholmod_sparse *A, // matrix to analyze diff --git a/CHOLMOD/Doc/CHOLMOD_UserGuide.pdf b/CHOLMOD/Doc/CHOLMOD_UserGuide.pdf index bf7b22dc4..dcaa7d383 100644 Binary files a/CHOLMOD/Doc/CHOLMOD_UserGuide.pdf and b/CHOLMOD/Doc/CHOLMOD_UserGuide.pdf differ diff --git a/CHOLMOD/Doc/CHOLMOD_UserGuide.tex b/CHOLMOD/Doc/CHOLMOD_UserGuide.tex index 0f51c02ac..34474a01c 100644 --- a/CHOLMOD/Doc/CHOLMOD_UserGuide.tex +++ b/CHOLMOD/Doc/CHOLMOD_UserGuide.tex @@ -25,28 +25,23 @@ \input{cholmod_version.tex} \maketitle -% FIXME: TODO: discuss single precision - %------------------------------------------------------------------------------- \begin{abstract} - CHOLMOD\footnote{CHOLMOD is short for CHOLesky MODification, - since a key feature of the package is its ability to update/downdate - a sparse Cholesky factorization} - is a set of routines for factorizing sparse symmetric positive - definite matrices of the form $\m{A}$ or $\m{AA}\tr$, updating/downdating - a sparse Cholesky factorization, solving linear systems, updating/downdating - the solution to the triangular system $\m{Lx}=\m{b}$, and many other sparse - matrix functions for both symmetric and unsymmetric matrices. - Its supernodal Cholesky factorization - relies on LAPACK and the Level-3 BLAS, and obtains a substantial fraction - of the peak performance of the BLAS. Both real and complex matrices - are supported. - It also includes a non-supernodal $\m{LDL}^T$ factorization method - that can factorize symmetric indefinite matrices if all of their - leading submatrices are well-conditioned ($\m{D}$ is diagonal). - CHOLMOD is written in ANSI/ISO C, with both - C and MATLAB interfaces. This code works on Microsoft Windows and many - versions of Unix and Linux. + CHOLMOD\footnote{CHOLMOD is short for CHOLesky MODification, since a key + feature of the package is its ability to update/downdate a sparse Cholesky + factorization} is a set of routines for factorizing sparse symmetric + positive definite matrices of the form $\m{A}$ or $\m{AA}\tr$, + updating/downdating a sparse Cholesky factorization, solving linear + systems, updating/downdating the solution to the triangular system + $\m{Lx}=\m{b}$, and many other sparse matrix functions for both symmetric + and unsymmetric matrices. Its supernodal Cholesky factorization relies on + LAPACK and the Level-3 BLAS, and obtains a substantial fraction of the peak + performance of the BLAS. Both real and complex matrices are supported. It + also includes a non-supernodal $\m{LDL}^T$ factorization method that can + factorize symmetric indefinite matrices if all of their leading submatrices + are well-conditioned ($\m{D}$ is diagonal). CHOLMOD is written in C11, + with both C and MATLAB interfaces. The package works on Linux, Mac, and + Windows. \end{abstract} %------------------------------------------------------------------------------- @@ -68,61 +63,59 @@ \newpage \section{Overview} %------------------------------------------------------------------------------- -CHOLMOD is a set of ANSI C routines for solving systems of linear -equations, $\m{Ax}=\m{b}$, when $\m{A}$ is sparse and symmetric positive definite, -and $\m{x}$ and $\m{b}$ can be either sparse or dense.\footnote{Some support -is provided for symmetric indefinite matrices.} -Complex matrices are supported, in two different formats. -CHOLMOD includes high-performance left-looking supernodal factorization -and solve methods \cite{NgPeyton91b}, -based on LAPACK \cite{LAPACK} and the BLAS \cite{ACM679a}. -After a matrix is factorized, its factors can be updated or downdated using -the techniques described by Davis and Hager -in \cite{DavisHager99,DavisHager01,DavisHager05}. -Many additional sparse matrix operations are provided, for both -symmetric and unsymmetric matrices (square or rectangular), including -sparse matrix multiply, add, transpose, permutation, scaling, -norm, concatenation, sub-matrix access, and converting to alternate data structures. -Interfaces to many ordering methods are provided, including minimum degree -(AMD \cite{AmestoyDavisDuff96,AmestoyDavisDuff03}, -COLAMD \cite{DavisGilbertLarimoreNg00_algo,DavisGilbertLarimoreNg00}), -constrained minimum degree (CSYMAMD, CCOLAMD, CAMD), and -graph-partitioning-based nested dissection (METIS \cite{KarypisKumar98}). -Most of its operations are available within MATLAB via mexFunction interfaces. - - CHOLMOD also includes a non-supernodal $\m{LDL}^T$ factorization method - that can factorize symmetric indefinite matrices if all of their - leading submatrices are well-conditioned ($\m{D}$ is diagonal). +CHOLMOD is a set of ANSI C routines for solving systems of linear equations, +$\m{Ax}=\m{b}$, when $\m{A}$ is sparse and symmetric positive definite, and +$\m{x}$ and $\m{b}$ can be either sparse or dense.\footnote{Some support is +provided for symmetric indefinite matrices.} Complex matrices are supported, in +two different formats. CHOLMOD includes high-performance left-looking +supernodal factorization and solve methods \cite{NgPeyton91b}, based on LAPACK +\cite{LAPACK} and the BLAS \cite{ACM679a}. After a matrix is factorized, its +factors can be updated or downdated using the techniques described by Davis and +Hager in \cite{DavisHager99,DavisHager01,DavisHager05}. Many additional sparse +matrix operations are provided, for both symmetric and unsymmetric matrices +(square or rectangular), including sparse matrix multiply, add, transpose, +permutation, scaling, norm, concatenation, sub-matrix access, and converting to +alternate data structures. My recent GraphBLAS package will typically be +faster for these kinds of operations, however. Interfaces to many ordering +methods are provided, including minimum degree (AMD +\cite{AmestoyDavisDuff96,AmestoyDavisDuff03}, COLAMD +\cite{DavisGilbertLarimoreNg00_algo,DavisGilbertLarimoreNg00}), constrained +minimum degree (CSYMAMD, CCOLAMD, CAMD), and graph-partitioning-based nested +dissection (METIS \cite{KarypisKumar98}). Most of its operations are available +within MATLAB via mexFunction interfaces. + +CHOLMOD also includes a non-supernodal $\m{LDL}^T$ factorization method that +can factorize symmetric indefinite matrices if all of their leading submatrices +are well-conditioned ($\m{D}$ is diagonal). A pair of articles on CHOLMOD appears in the ACM Transactions on Mathematical Software: \cite{ChenDavisHagerRajamanickam06,DavisHager06}. -CHOLMOD 1.0 replaces {\tt chol} (the sparse case), {\tt symbfact}, and {\tt -etree} in MATLAB 7.2 (R2006a), and is used for {\tt x=A}$\backslash${\tt b} -when {\tt A} is symmetric positive definite \cite{GilbertMolerSchreiber}. It -will replace {\tt sparse} in a future version of MATLAB. +CHOLMOD appears as {\tt chol} (the sparse case), {\tt symbfact}, and {\tt +etree} in MATLAB 7.2 (R2006a) and later, and is used for {\tt +x=A}$\backslash${\tt b} when {\tt A} is symmetric positive definite +\cite{GilbertMolerSchreiber}. -The C-callable CHOLMOD library consists of 133 user-callable routines and one -include file. Each routine comes in two versions, one for {\tt int} integers -and another for {\tt long}. Many of the routines can support either real or +The C-callable CHOLMOD library consists of many user-callable routines and one +include file. Each routine comes in two versions, one for {\tt int32\_t} integers +and another for {\tt int64\_t}. Many of the routines can support either real or complex matrices, simply by passing a matrix of the appropriate type. +All of the routines support both {\tt double} and single ({\tt float}) +precision matrices (this is new in CHOLMOD 5.1). Nick Gould, Yifan Hu, and Jennifer Scott have independently tested CHOLMOD's performance, comparing it with nearly a dozen or so other solvers \cite{GouldHuScott05,GouldHuScott05b}. Its performance was quite competitive. %------------------------------------------------------------------------------- -\newpage \section{Single-precision sparse matrix support} +\section{Single-precision sparse matrix support} %------------------------------------------------------------------------------- -{\bf CHOLMOD v5.0.0}: introduces the first part of support for single - precision sparse matrices, with the introduction of the new - CHOLMOD:Utility Module. The CHOLMOD:Utility Module replaces the - CHOLMOD:Core Module that appeared in prior versions of CHOLMOD. - Single precision is not yet incorporated into the remaining Modules, - however. This feature will be implemented soon in a later version - of CHOLMOD. +{\bf CHOLMOD v5.1.0}: introduces full of support for single precision sparse +matrices, with the introduction of the new CHOLMOD:Utility Module. The +CHOLMOD:Utility Module replaces the CHOLMOD:Core Module that appeared in prior +versions of CHOLMOD. %------------------------------------------------------------------------------- \newpage \section{Primary routines and data structures} @@ -140,9 +133,10 @@ either simplicial (non-supernodal) or supernodal. \item {\tt cholmod\_factorize}: - Numerical factorization, either simplicial or supernodal, $\m{LL}\tr$ or $\m{LDL}\tr$ - using either the symbolic factorization from {\tt cholmod\_analyze} or the numerical - factorization from a prior call to {\tt cholmod\_factorize}. + Numerical factorization, either simplicial or supernodal, $\m{LL}\tr$ or + $\m{LDL}\tr$ using either the symbolic factorization from {\tt + cholmod\_analyze} or the numerical factorization from a prior call to {\tt + cholmod\_factorize}. \item {\tt cholmod\_solve}: Solves $\m{Ax}=\m{b}$, or many other related systems, where $\m{x}$ and @@ -154,101 +148,118 @@ This must be the last call to CHOLMOD. \end{enumerate} -Additional routines are also required to create and destroy -the matrices $\m{A}$, $\m{x}$, $\m{b}$, and the $\m{LL}\tr$ or $\m{LDL}\tr$ factorization. -CHOLMOD has five kinds of data structures, referred to as objects and implemented -as pointers to {\tt struct}'s: +Additional routines are also required to create and destroy the matrices +$\m{A}$, $\m{x}$, $\m{b}$, and the $\m{LL}\tr$ or $\m{LDL}\tr$ factorization. +CHOLMOD has five kinds of data structures, referred to as objects and +implemented as pointers to {\tt struct}'s: \begin{enumerate} \item {\tt cholmod\_common}: parameter settings, statistics, and workspace - used internally by CHOLMOD. - See Section~\ref{cholmod_common} for details. + used internally by CHOLMOD. See Section~\ref{cholmod_common} for details. \item {\tt cholmod\_sparse}: a sparse matrix in compressed-column form, either pattern-only, real, complex, or ``zomplex.'' In its basic form, the matrix {\tt A} contains: \begin{itemize} - \item {\tt A->p}, an integer array of size {\tt A->ncol+1}. - \item {\tt A->i}, an integer array of size {\tt A->nzmax}. - \item {\tt A->x}, a {\tt double} % FIXME + \item {\tt A->p}, an integer array of size {\tt A->ncol+1}. + \item {\tt A->i}, an integer array of size {\tt A->nzmax}. + \item {\tt A->x}, a {\tt double} or {\tt float} array of size {\tt A->nzmax} or twice that for the complex case. - This is compatible with the Fortran and ANSI C99 complex data type. - \item {\tt A->z}, a {\tt double} % FIXME - array of size {\tt A->nzmax} if {\tt A} is zomplex. - A zomplex matrix has a {\tt z} array, thus the name. - This is compatible with the MATLAB representation of complex matrices. + This is compatible with the Fortran and ANSI C99 complex data type. + \item {\tt A->z}, a {\tt double} or {\tt float} + array of size {\tt A->nzmax} if {\tt A} is zomplex. A zomplex + matrix has a {\tt z} array, thus the name. This is compatible with + the MATLAB representation of complex matrices. + \item {\tt A->nz}, an integer array of size {\tt A->ncol}, if + {\tt A} is in the {\em unpacked} format. In this format, + the columns of {\tt A} can appear out of order, and gaps of + unused space can appear between columns. \end{itemize} - For all four types of matrices, the row indices of entries of column {\tt j} - are located in {\tt A->i [A->p [j] ... A->p [j+1]-1]}. - For a real matrix, the corresponding numerical values are in {\tt A->x} at the same location. - For a complex matrix, the entry whose row index is {\tt A->i [p]} is contained in - {\tt A->x [2*p]} (the real part) and {\tt A->x [2*p+1]} (the imaginary part). - For a zomplex matrix, the real part is in {\tt A->x [p]} and imaginary part is in {\tt A->z [p]}. - See Section~\ref{cholmod_sparse} for more details. + + For all four types of matrices, the row indices of entries of column {\tt + j} are located in {\tt A->i [A->p [j] ... A->p [j+1]-1]}, or in {\tt A->i + [A->p [j] ... A->p [j] + A->nz [j] -1]}, if in the unpacked format. For a + real matrix, the corresponding numerical values are in {\tt A->x} at the + same location. For a complex matrix, the entry whose row index is {\tt + A->i [p]} is contained in {\tt A->x [2*p]} (the real part) and {\tt A->x + [2*p+1]} (the imaginary part). For a zomplex matrix, the real part is in + {\tt A->x [p]} and imaginary part is in {\tt A->z [p]}. See + Section~\ref{cholmod_sparse} for more details. \item {\tt cholmod\_factor}: - A symbolic or numeric factorization, either real, complex, or zomplex. - It can be either an $\m{LL}\tr$ or $\m{LDL}\tr$ factorization, and either - simplicial or supernodal. You will normally not need to examine its contents. - See Section~\ref{cholmod_factor} for more details. + A symbolic or numeric factorization, either real, complex, or zomplex. It + can be either an $\m{LL}\tr$ or $\m{LDL}\tr$ factorization, and either + simplicial or supernodal. You will normally not need to examine its + contents. See Section~\ref{cholmod_factor} for more details. \item {\tt cholmod\_dense}: A dense matrix, either real, complex or zomplex, in column-major order. - This differs from the row-major convention used in C. A dense matrix {\tt X} contains + This differs from the row-major convention used in C. A dense matrix {\tt + X} contains \begin{itemize} - \item {\tt X->x}, a {\tt double} % FIXME + + \item {\tt X->x}, a {\tt double} or {\tt float} array of size {\tt X->nzmax} or twice that for the complex case. - \item {\tt X->z}, a {\tt double} % FIXME + \item {\tt X->z}, a {\tt double} or {\tt float} array of size {\tt X->nzmax} if {\tt X} is zomplex. \end{itemize} - For a real dense matrix $x_{ij}$ is {\tt X->x [i+j*d]} where {\tt d = X->d} is the leading dimension of {\tt X}. - For a complex dense matrix, the real part of $x_{ij}$ is {\tt X->x [2*(i+j*d)]} and the imaginary part is {\tt X->x [2*(i+j*d)+1]}. - For a zomplex dense matrix, the real part of $x_{ij}$ is {\tt X->x [i+j*d]} and the imaginary part is {\tt X->z [i+j*d]}. - Real and complex dense matrices can be passed to LAPACK and the BLAS. - See Section~\ref{cholmod_dense} for more details. + + For a real dense matrix $x_{ij}$ is {\tt X->x [i+j*d]} where {\tt d = X->d} + is the leading dimension of {\tt X}. For a complex dense matrix, the real + part of $x_{ij}$ is {\tt X->x [2*(i+j*d)]} and the imaginary part is {\tt + X->x [2*(i+j*d)+1]}. For a zomplex dense matrix, the real part of $x_{ij}$ + is {\tt X->x [i+j*d]} and the imaginary part is {\tt X->z [i+j*d]}. Real + and complex dense matrices can be passed to LAPACK and the BLAS. See + Section~\ref{cholmod_dense} for more details. \item {\tt cholmod\_triplet}: - CHOLMOD's sparse matrix ({\tt cholmod\_sparse}) is the primary input for nearly all CHOLMOD - routines, but it can be difficult for the user to construct. - A simpler method of creating a sparse matrix is to first create a {\tt cholmod\_triplet} matrix, - and then convert it to a {\tt cholmod\_sparse} matrix via - the {\tt cholmod\_triplet\_to\_sparse} routine. + CHOLMOD's sparse matrix ({\tt cholmod\_sparse}) is the primary input for + nearly all CHOLMOD routines, but it can be difficult for the user to + construct. A simpler method of creating a sparse matrix is to first create + a {\tt cholmod\_triplet} matrix, and then convert it to a {\tt + cholmod\_sparse} matrix via the {\tt cholmod\_triplet\_to\_sparse} routine. In its basic form, the triplet matrix {\tt T} contains + \begin{itemize} - \item {\tt T->i} and {\tt T->j}, integer arrays of size {\tt T->nzmax}. - \item {\tt T->x}, a {\tt double} % FIXME + \item {\tt T->i} and {\tt T->j}, integer arrays of size {\tt T->nzmax}. + \item {\tt T->x}, a {\tt double} or {\tt float} array of size {\tt T->nzmax} or twice that for the complex case. - \item {\tt T->z}, a {\tt double} % FIXME + \item {\tt T->z}, a {\tt double} or {\tt float} array of size {\tt T->nzmax} if {\tt T} is zomplex. \end{itemize} - The {\tt k}th entry in the data structure has row index - {\tt T->i [k]} and column index {\tt T->j [k]}. - For a real triplet matrix, its numerical value is {\tt T->x [k]}. - For a complex triplet matrix, its real part is {\tt T->x [2*k]} and its imaginary part is {\tt T->x [2*k+1]}. - For a zomplex matrix, the real part is {\tt T->x [k]} and imaginary part is {\tt T->z [k]}. - The entries can be in any order, and duplicates are permitted. + + The {\tt k}th entry in the data structure has row index {\tt T->i [k]} and + column index {\tt T->j [k]}. For a real triplet matrix, its numerical + value is {\tt T->x [k]}. For a complex triplet matrix, its real part is + {\tt T->x [2*k]} and its imaginary part is {\tt T->x [2*k+1]}. For a + zomplex matrix, the real part is {\tt T->x [k]} and imaginary part is {\tt + T->z [k]}. The entries can be in any order, and duplicates are permitted. See Section~\ref{cholmod_triplet} for more details. \end{enumerate} Each of the five objects has a routine in CHOLMOD to create and destroy it. -CHOLMOD provides many other operations on these objects as well. -A few of the most important ones are illustrated in the sample program in the -next section. +CHOLMOD provides many other operations on these objects as well. A few of the +most important ones are illustrated in the sample program in the next section. %------------------------------------------------------------------------------- \newpage \section{Simple example program} %------------------------------------------------------------------------------- \input{_simple.tex} -The {\tt Demo/cholmod\_simple.c} program illustrates the -basic usage of CHOLMOD. It reads a triplet matrix from a file -(in Matrix Market format), converts it into a sparse matrix, -creates a linear system, solves it, and prints the norm of the residual. +The {\tt Demo/cholmod\_*\_simple.c} programs illustrate the basic usage of +CHOLMOD. Each of them reads a triplet matrix from a file (in Matrix Market +format), convert it into a sparse matrix, creates a linear system, solves it, +and prints the norm of the residual. See the {\tt +CHOLMOD/Demo/cholmod\_*\_demo.c} program for a more elaborate example. These +two sets of programs come in four variants: -See the {\tt CHOLMOD/Demo/cholmod\_demo.c} program for a more elaborate -example, and \newline -{\tt CHOLMOD/Demo/cholmod\_l\_demo.c} for its {\tt long} integer version. + \begin{itemize} + \item di: {\tt double} values, {\tt int32\_t} integers. + \item dl: {\tt double} values, {\tt int64\_t} integers. + \item si: {\tt float} values, {\tt int32\_t} integers. + \item sl: {\tt float} values, {\tt int64\_t} integers. + \end{itemize} %------------------------------------------------------------------------------- \newpage \section{Installation of the C-callable library} @@ -256,7 +267,9 @@ %------------------------------------------------------------------------------- CHOLMOD requires a suite of external packages, many of which are distributed -along with CHOLMOD, but three of which are not. Those included with CHOLMOD are: +along with CHOLMOD, but three of which are not. Those included with CHOLMOD +are: + \begin{itemize} \item AMD: an approximate minimum degree ordering algorithm, by Tim Davis, Patrick Amestoy, and Iain Duff @@ -265,36 +278,27 @@ by Tim Davis, Stefan Larimore, John Gilbert, and Esmond Ng \cite{DavisGilbertLarimoreNg00_algo,DavisGilbertLarimoreNg00}. \item CCOLAMD: a constrained approximate column minimum degree ordering - algorithm, - by Tim Davis and Siva Rajamanickam, based directly on COLAMD. - This package is not required if CHOLMOD is compiled with the - {\tt -DNCAMD} flag. -\item CAMD: a constrained approximate minimum degree ordering - algorithm, - by Tim Davis and Yanqing Chen, based directly on AMD. - This package is not required if CHOLMOD is compiled with the - {\tt -DNCAMD} flag. -\item {\tt SuiteSparse\_config}: - a single place where all sparse matrix packages authored - or co-authored by Davis are configured. + algorithm, by Tim Davis and Siva Rajamanickam, based directly on COLAMD. + This package is not required if CHOLMOD is compiled with the {\tt -DNCAMD} + flag. +\item CAMD: a constrained approximate minimum degree ordering algorithm, by Tim + Davis and Yanqing Chen, based directly on AMD. This package is not + required if CHOLMOD is compiled with the {\tt -DNCAMD} flag. +\item {\tt SuiteSparse\_config}: a single place where all sparse matrix + packages authored or co-authored by Davis are configured. +\item {\tt METIS 5.1.0}: a graph partitioning package by George Karypis, + Univ. of Minnesota. A slightly revised copy appears in + {\tt CHOLMOD/SuiteSparse\_metis}. Not needed if {\tt -DNPARTITION} is + used. See http://www-users.cs.umn.edu/$\sim$karypis/metis. \end{itemize} Three other packages are required for optimal performance: \begin{itemize} -\item {\tt METIS 5.1.0}: a graph partitioning package by George Karypis, - Univ. of Minnesota. Not needed if {\tt -DNPARTITION} is used. - See http://www-users.cs.umn.edu/$\sim$karypis/metis. + \item BLAS: the Basic Linear Algebra Subprograms. Not needed if {\tt -DNSUPERNODAL} is used. See http://www.netlib.org for the reference BLAS (not meant for production - use). For Kazushige Goto's optimized BLAS (highly recommended for CHOLMOD) - see \newline - http://www.tacc.utexas.edu/$\sim$kgoto/ or - http://www.cs.utexas.edu/users/flame/goto/. - I recommend that you avoid the Intel MKL BLAS; one recent - version returns NaN's, where both the Goto BLAS and the standard - Fortran reference BLAS return the correct answer. - See {\tt CHOLMOD/README} for more information. + use). I recommend the Intel MKL BLAS. \item LAPACK: the Basic Linear Algebra Subprograms. Not needed if {\tt -DNSUPERNODAL} is used. See http://www.netlib.org. @@ -303,12 +307,11 @@ \end{itemize} You must first obtain and install LAPACK, and the BLAS. -METIS 5.1.0 is optional; a copy of it is in {\tt SuiteSparse\_metis}. \noindent -CHOLMOD's specific settings are given by the {\tt CHOLMOD\_CONFIG} string: +CHOLMOD's specific settings are revised by the following compile-time flags: \begin{itemize} -\item {\tt -DNCHECK}: do not include the Check module. +\item {\tt -DNCHECK}: do not include the Check module. \item {\tt -DNCHOLESKY}: do not include the Cholesky module. \item {\tt -DNPARTITION}: do not include the interface to METIS in the Partition module. @@ -316,39 +319,30 @@ and CSYMAMD in the Partition module. \item {\tt -DNMATRIXOPS}: do not include the MatrixOps module. Note that the Demo requires the MatrixOps module. -\item {\tt -DNMODIFY}: do not include the Modify module. +\item {\tt -DNMODIFY}: do not include the Modify module. \item {\tt -DNSUPERNODAL}: do not include the Supernodal module. -\item {\tt -DNPRINT}: do not print anything. +\item {\tt -DNPRINT}: do not print anything. \end{itemize} -SuiteSparse now has a complete \verb'cmake'-based build system. -Each package (SuiteSparse\_congig, AMD, CAMD, CCOLAMD, CAMD, and CHOLMOD) has its own -\verb'CMakeLists.txt'. Use \verb'cmake' to build each package in -that order. +SuiteSparse now has a complete \verb'cmake'-based build system. Each package +(SuiteSparse\_congig, AMD, CAMD, CCOLAMD, CAMD, and CHOLMOD) has its own +\verb'CMakeLists.txt'. Use \verb'cmake' to build each package in that order. An optional \verb'Makefile' is provided at the top-level of \verb'SuiteSparse' -Type {\tt make} in that directory. The AMD, -COLAMD, CAMD, CCOLAMD, and {\tt CHOLMOD} libraries will be compiled. -To compile and run demo programs for each package, -type \verb'make demos'. For CHOLMOD, the residuals should all be small. - -CHOLMOD is now ready for use in your own applications. You must link -your programs with the -{\tt libcholmod.*}, -{\tt libamd.*}, -{\tt libcolamd.*}, -LAPACK, -and -BLAS libraries. -Unless {\tt -DNCAMD} is present at compile time, -you must link with {\tt CAMD/libcamd.*}, and {\tt CCOLAMD/libccolamd.*}. -Each library has its own \verb'Find*.cmake' script to use in -the \verb'cmake' +Type {\tt make} in that directory. The AMD, COLAMD, CAMD, CCOLAMD, and {\tt +CHOLMOD} libraries will be compiled. To compile and run demo programs for each +package, type \verb'make demos'. For CHOLMOD, the residuals should all be +small. + +CHOLMOD is now ready for use in your own applications. You must link your +programs with the {\tt libcholmod.*}, {\tt libamd.*}, {\tt libcolamd.*}, +LAPACK, and BLAS libraries. Unless {\tt -DNCAMD} is present at compile time, +you must link with {\tt CAMD/libcamd.*}, and {\tt CCOLAMD/libccolamd.*}. Each +library has its own \verb'Find*.cmake' script to use in the \verb'cmake' \verb'find_library' command. -To install CHOLMOD in default locations use -{\tt make install}. -To remove CHOLMOD, do {\tt make uninstall}. +To install CHOLMOD in default locations use {\tt make install}. To remove +CHOLMOD, do {\tt make uninstall}. %------------------------------------------------------------------------------- \newpage \section{Using CHOLMOD in MATLAB} @@ -360,70 +354,105 @@ \vspace{0.1in} \begin{tabular}{ll} \hline -{\tt analyze} & order and analyze a matrix \\ -{\tt bisect} & find a node separator \\ -{\tt chol2} & same as {\tt chol} \\ -{\tt cholmod2} & same as {\tt x=A}$\backslash${\tt b} if {\tt A} is symmetric positive definite \\ +{\tt analyze} & order and analyze a matrix \\ +{\tt bisect} & find a node separator \\ +{\tt chol2} & same as {\tt chol} \\ +{\tt cholmod2} & same as \verb'x=A\b' \verb'A' is symmetric positive + definite \\ {\tt cholmod\_demo} & a short demo program \\ {\tt cholmod\_make} & compiles CHOLMOD for use in MATLAB \\ -{\tt etree2} & same as {\tt etree} \\ +{\tt etree2} & same as {\tt etree} \\ {\tt graph\_demo} & graph partitioning demo \\ -{\tt lchol} & {\tt L*L'} factorization \\ -{\tt ldlchol} & {\tt L*D*L'} factorization \\ +{\tt lchol} & {\tt L*L'} factorization \\ +{\tt ldlchol} & {\tt L*D*L'} factorization \\ {\tt ldl\_normest} & estimate {\tt norm(A-L*D*L')} \\ -{\tt ldlsolve} & {\tt x = L'}$\backslash${\tt (D}$\backslash${\tt (L}$\backslash${\tt b))} \\ -{\tt ldlsplit} & split the output of {\tt ldlchol} into {\tt L} and {\tt D} \\ -{\tt ldlupdate} & update/downdate an {\tt L*D*L'} factorization \\ -{\tt ldlrowmod} & add/delete a row from an {\tt L*D*L'} factorization \\ -{\tt metis} & interface to {\tt METIS\_NodeND} ordering \\ -{\tt mread} & read a sparse or dense Matrix Market file \\ -{\tt mwrite} & write a sparse or dense Matrix Market file \\ -{\tt nesdis} & CHOLMOD's nested dissection ordering \\ -{\tt resymbol} & recomputes the symbolic factorization \\ -{\tt sdmult} & {\tt S*F} where {\tt S} is sparse and {\tt F} is dense \\ -{\tt spsym} & determine symmetry \\ -{\tt sparse2} & same as {\tt sparse} \\ -{\tt symbfact2} & same as {\tt symbfact} \\ +{\tt ldlsolve} & \verb"x = L'\ (D \(L \ b))" \\ +{\tt ldlsplit} & split the output of {\tt ldlchol} into {\tt L} and + {\tt D} \\ +{\tt ldlupdate} & update/downdate an {\tt L*D*L'} factorization \\ +{\tt ldlrowmod} & add/delete a row from an {\tt L*D*L'} factorization \\ +{\tt metis} & interface to {\tt METIS\_NodeND} ordering \\ +{\tt mread} & read a sparse or dense Matrix Market file \\ +{\tt mwrite} & write a sparse or dense Matrix Market file \\ +{\tt nesdis} & CHOLMOD's nested dissection ordering \\ +{\tt resymbol} & recomputes the symbolic factorization \\ +{\tt sdmult} & {\tt S*F} where {\tt S} is sparse and {\tt F} is dense \\ +{\tt spsym} & determine symmetry \\ +{\tt symbfact2} & same as {\tt symbfact} \\ \hline \end{tabular} \vspace{0.1in}\noindent Each function is described in the next sections. -\newpage -\subsection{{\tt analyze}: order and analyze} \input{_analyze_m.tex} -\subsection{{\tt bisect}: find a node separator} \input{_bisect_m.tex} -\subsection{{\tt chol2}: same as {\tt chol}} \input{_chol2_m.tex} -\subsection{{\tt cholmod2}: supernodal backslash} \input{_cholmod2_m.tex} -\newpage -\subsection{{\tt cholmod\_demo}: a short demo program} \input{_cholmod_demo_m.tex} -\subsection{{\tt cholmod\_make}: compile CHOLMOD in MATLAB} \input{_cholmod_make_m.tex} -\newpage -\subsection{{\tt etree2}: same as {\tt etree}} \input{_etree2_m.tex} -\subsection{{\tt graph\_demo}: graph partitioning demo} \input{_graph_demo_m.tex} -\subsection{{\tt lchol}: $\m{LL}\tr$ factorization} \input{_lchol_m.tex} -\subsection{{\tt ldlchol}: $\m{LDL}\tr$ factorization} \input{_ldlchol_m.tex} -\subsection{{\tt ldlsolve}: solve using an $\m{LDL}\tr$ factorization} \input{_ldlsolve_m.tex} -\subsection{{\tt ldlsplit}: split an $\m{LDL}\tr$ factorization} \input{_ldlsplit_m.tex} -\subsection{{\tt ldlupdate}: update/downdate an $\m{LDL}\tr$ factorization} \input{_ldlupdate_m.tex} -\newpage -\subsection{{\tt ldlrowmod}: add/delete a row from an $\m{LDL}\tr$ factorization} \input{_ldlrowmod_m.tex} -\newpage -\subsection{{\tt mread}: read a sparse or dense matrix from a Matrix Market file}\input{_mread_m.tex} -\subsection{{\tt mwrite}: write a sparse or dense matrix to a Matrix Market file} \input{_mwrite_m.tex} -\newpage -\subsection{{\tt metis}: order with METIS} \input{_metis_m.tex} -\newpage -\subsection{{\tt nesdis}: order with CHOLMOD nested dissection} \input{_nesdis_m.tex} -\newpage -\subsection{{\tt resymbol}: re-do symbolic factorization} \input{_resymbol_m.tex} -\subsection{{\tt sdmult}: sparse matrix times dense matrix} \input{_sdmult_m.tex} -\newpage -\subsection{{\tt spsym}: determine symmetry} \input{_spsym_m.tex} -\newpage -\subsection{{\tt sparse2}: same as {\tt sparse}} \input{_sparse2_m.tex} -\newpage -\subsection{{\tt symbfact2}: same as {\tt symbfact}} \input{_symbfact2_m.tex} +\subsection{{\tt analyze}: order and analyze} +\input{_analyze_m.tex} + +\subsection{{\tt bisect}: find a node separator} +\input{_bisect_m.tex} + +\subsection{{\tt chol2}: same as {\tt chol}} +\input{_chol2_m.tex} + +\subsection{{\tt cholmod2}: supernodal backslash} +\input{_cholmod2_m.tex} + +\subsection{{\tt cholmod\_demo}: a short demo program} +\input{_cholmod_demo_m.tex} + +\subsection{{\tt cholmod\_make}: compile CHOLMOD in MATLAB} +\input{_cholmod_make_m.tex} + +\subsection{{\tt etree2}: same as {\tt etree}} +\input{_etree2_m.tex} + +\subsection{{\tt graph\_demo}: graph partitioning demo} +\input{_graph_demo_m.tex} + +\subsection{{\tt lchol}: $\m{LL}\tr$ factorization} +\input{_lchol_m.tex} + +\subsection{{\tt ldlchol}: $\m{LDL}\tr$ factorization} +\input{_ldlchol_m.tex} + +\subsection{{\tt ldlsolve}: solve using an $\m{LDL}\tr$ factorization} +\input{_ldlsolve_m.tex} + +\subsection{{\tt ldlsplit}: split an $\m{LDL}\tr$ factorization} +\input{_ldlsplit_m.tex} + +\subsection{{\tt ldlupdate}: update/downdate an $\m{LDL}\tr$ factorization} +\input{_ldlupdate_m.tex} + +\subsection{{\tt ldlrowmod}: add/delete a row from an $\m{LDL}\tr$ +factorization} +\input{_ldlrowmod_m.tex} + +\subsection{{\tt mread}: read a sparse or dense matrix from a Matrix Market +file} +\input{_mread_m.tex} + +\subsection{{\tt mwrite}: write a sparse or dense matrix to a Matrix Market +file} +\input{_mwrite_m.tex} + +\subsection{{\tt metis}: order with METIS} +\input{_metis_m.tex} + +\subsection{{\tt nesdis}: order with CHOLMOD nested dissection} +\input{_nesdis_m.tex} + +\subsection{{\tt resymbol}: re-do symbolic factorization} +\input{_resymbol_m.tex} + +\subsection{{\tt sdmult}: sparse matrix times dense matrix} +\input{_sdmult_m.tex} + +\subsection{{\tt spsym}: determine symmetry} +\input{_spsym_m.tex} + +\subsection{{\tt symbfact2}: same as {\tt symbfact}} +\input{_symbfact2_m.tex} %------------------------------------------------------------------------------- \newpage \section{Installation for use in MATLAB} @@ -433,21 +462,17 @@ \subsection{{\tt symbfact2}: same as {\tt symbfact}} \input{_symbfact2_m.tex} \subsection{{\tt cholmod\_make}: compiling CHOLMOD in MATLAB} %------------------------------------------------------------------------------- -This is the preferred method, since it allows METIS to be reconfigured to -use the MATLAB memory-management functions instead of {\tt malloc} and {\tt free}; -this avoids the issue of METIS terminating MATLAB if it runs out of memory. - Start MATLAB, {\tt cd} to the {\tt CHOLMOD/MATLAB} directory, and type {\tt cholmod\_make} in the MATLAB command window. This will compile -the MATLAB interfaces for AMD, COLAMD, CAMD, CCOLAMD, METIS, and CHOLMOD. +the MATLAB interfaces for METIS and CHOLMOD. %------------------------------------------------------------------------------- \section{Using CHOLMOD with OpenMP acceleration} %------------------------------------------------------------------------------- -CHOLMOD includes OpenMP acceleration for some operations. -In CHOLMOD versions prior to v6.0.0, the number of threads to use was controlled -by a compile time parameter. This is now replaced with run-time controls. +CHOLMOD includes OpenMP acceleration for some operations. In CHOLMOD versions +prior to v6.0.0, the number of threads to use was controlled by a compile time +parameter. This is now replaced with run-time controls. \verb'Common->nthreads_max' defaults to \verb'omp_get_max_threads()', or 1 if OpenMP is not in use. This value controls the maximum number of threads that @@ -476,15 +501,17 @@ \section{Using CHOLMOD with GPU acceleration} GPU that supports CUDA and has at least 64MB of memory. (But substantially more memory, typically about 3 GB, is recommended for best performance.) -Only the {\tt long} integer version of CHOLMOD can leverage GPU acceleration. +Only the ({\tt double}, {\tt int64\_t}) version of CHOLMOD can leverage GPU +acceleration (both real and complex). %------------------------------------------------------------------------------- \subsection{Compiling CHOLMOD with GPU support} %------------------------------------------------------------------------------- In order to support GPU processing, CHOLMOD must be compiled with the -preprocessor macro \verb'ENABLE_CUDA' defined. It is enabled by default -but can be disabled by setting this to false when using cmake. +preprocessor macro \verb'SUITESPARSE_CUDA' defined. It is enabled by default +in {\tt cmake} if you have a GPU, but this can be disabled by setting this to +false when using cmake. %------------------------------------------------------------------------------- \subsection{Enabling GPU acceleration in CHOLMOD} @@ -546,7 +573,7 @@ \subsection{Adjustable parameters} {\tt CHOLMOD\_GPU\_SKIP} : Number of small descendant supernodes to assembled on the CPU before querying if the GPU is needs more descendant supernodes - queued + queued. \end{quote} @@ -582,11 +609,13 @@ \subsection{Adjustable parameters} \begin{quote} {\tt CHOLMOD\_GPU\_MEM\_BYTES} : Environment variable with a meaning - equivalent to {\tt Common->maxGpuMemBytes}. This will only be queried if + equivalent to \newline + {\tt Common->maxGpuMemBytes}. This will only be queried if {\tt Common->useGPU = -1}. {\tt CHOLMOD\_GPU\_MEM\_FRACTION} : Environment variable with a meaning - equivalent to {\tt Common->maxGpuMemFraction}. This will only be queried if + equivalent to \newline + {\tt Common->maxGpuMemFraction}. This will only be queried if {\tt Common->useGPU = -1}. \end{quote} @@ -597,128 +626,157 @@ \subsection{Adjustable parameters} CHOLMOD supports both {\tt int32\_t} and {\tt int64\_t} integers. CHOLMOD routines with the prefix {\tt cholmod\_} use {\tt int32\_t} integers, -{\tt cholmod\_l\_} routines use {\tt int64\_t}. All floating-point -values are {\tt double}. % FIXME - -Two kinds of complex matrices are supported: complex and zomplex. -A complex matrix is held in a manner that is compatible with the -Fortran and ANSI C99 complex data type. A complex array of size {\tt n} -is a {\tt double} % FIXME -array {\tt x} of size {\tt 2*n}, with the real and imaginary -parts interleaved (the real part comes first, as a {\tt double}, % FIXME -followed the -imaginary part, also as a {\tt double}. % FIXME -Thus, the real part of the {\tt k}th -entry is {\tt x[2*k]} and the imaginary part is {\tt x[2*k+1]}. - -A zomplex matrix of size {\tt n} stores its real part in one -{\tt double} % FIXME -array of size {\tt n} called {\tt x} and its imaginary part -in another {\tt double} % FIXME -array of size {\tt n} called {\tt z} (thus the -name ``zomplex''). This also how MATLAB stores its complex matrices. -The real part of the {\tt k}th entry is {\tt x[k]} and the imaginary part is -{\tt z[k]}. - -Unlike {\tt UMFPACK}, the same routine name in CHOLMOD is used for pattern-only, -real, complex, and zomplex matrices. For example, the statement +{\tt cholmod\_l\_} routines use {\tt int64\_t}. Floating-point +values are {\tt double} or {\tt float}, depending on the {\tt A->dtype} +field for a sparse matrix, triplet matrix, dense matrix, or factorization +object. + +Two kinds of complex matrices are supported: complex and zomplex. A complex +matrix is held in a manner that is compatible with the Fortran and ANSI C99 +complex data type. A complex array of size {\tt n} is a {\tt double} or {\tt +float} array {\tt x} of size {\tt 2*n}, with the real and imaginary parts +interleaved, with the real part comes first, as a {\tt double} or {\tt float} +followed the imaginary part, also as a {\tt double} or {\tt float}. Thus, the +real part of the {\tt k}th entry is {\tt x[2*k]} and the imaginary part is {\tt +x[2*k+1]}. + +A zomplex matrix of size {\tt n} stores its real part in one {\tt double} or +{\tt float} array of size {\tt n} called {\tt x} and its imaginary part in +another {\tt double} or {\tt float} array of size {\tt n} called {\tt z} (thus +the name ``zomplex''). This also how MATLAB stored its complex matrices in +R2017b and earlier. The real part of the {\tt k}th entry is {\tt x[k]} and the +imaginary part is {\tt z[k]}. In MATLAB R2018a, complex matrices are stored +in the standard interleaved format. The CHOLMOD MATLAB interface uses this, +and thus requires MATLAB R2018a or later. + +Unlike {\tt UMFPACK}, the same routine name in CHOLMOD is used for +pattern-only, real, complex, and zomplex matrices, and also for both +{\tt double} and {\tt float} values. For example, the statement + \begin{verbatim} C = cholmod_copy_sparse (A, &Common) ; \end{verbatim} + creates a copy of a pattern, real, complex, or zomplex sparse matrix {\tt A}. -The xtype (pattern, real, complex, or zomplex) of the resulting sparse matrix {\tt C} -is the same as {\tt A} (a pattern-only sparse matrix contains no floating-point -values). In the above case, {\tt C} and {\tt A} use {\tt int} integers. -For {\tt int64\_t} integers, the statement would become: +The xtype (pattern, real, complex, or zomplex) of the resulting sparse matrix +{\tt C} is the same as {\tt A} (a pattern-only sparse matrix contains no +floating-point values). In the above case, {\tt C} and {\tt A} use {\tt int32\_t} +integers. For {\tt int64\_t} integers, the statement would become: + \begin{verbatim} C = cholmod_l_copy_sparse (A, &Common) ; \end{verbatim} -The last parameter of all CHOLMOD routines is always {\tt \&Common}, -a pointer to the -{\tt cholmod\_common} object, which contains parameters, statistics, -and workspace used throughout CHOLMOD. -The {\tt xtype} of a CHOLMOD object (sparse matrix, triplet matrix, dense -matrix, or factorization) determines whether it is pattern-only, -real, complex, or zomplex. +The last parameter of all CHOLMOD routines is always {\tt \&Common}, a pointer +to the {\tt cholmod\_common} object, which contains parameters, statistics, and +workspace used throughout CHOLMOD. -The names of the {\tt int} versions are primarily used in this document. -To obtain the name of the {\tt int64\_t} version of the same routine, simply +The {\tt xtype} of a CHOLMOD object (sparse matrix, triplet matrix, dense +matrix, or factorization) determines whether it is pattern-only, real, complex, +or zomplex. The {\tt dtype} of a CHOLMOD object (sparse matrix, triplet +matrix, dense matrix, or factorization) determines whether it is {\tt double} +or {\tt float}. These two terms are often added together when passing +parameters to CHOLMOD, as {\tt xtype + dtype}. This API design was chosen +for backward compatibility with CHOLMOD 4.x and earlier. + +The names of the {\tt int32\_t} versions are primarily used in this document. To +obtain the name of the {\tt int64\_t} version of the same routine, simply replace {\tt cholmod\_} with {\tt cholmod\_l\_}. -MATLAB matrix notation is used throughout this document and in -the comments in the CHOLMOD code itself. If you are not familiar with -MATLAB, here is a short introduction to the notation, and a few -minor variations used in CHOLMOD: +MATLAB matrix notation is used throughout this document and in the comments in +the CHOLMOD code itself. If you are not familiar with MATLAB, here is a short +introduction to the notation, and a few minor variations used in CHOLMOD: \begin{itemize} - \item {\tt C=A+B} and {\tt C=A*B}, respectively are a matrix add and multiply if both - {\tt A} and {\tt B} are matrices of appropriate size. If {\tt A} is - a scalar, then it is added to or multiplied with every entry in {\tt B}. + \item {\tt C=A+B} and {\tt C=A*B}, respectively are a matrix add and + multiply if both {\tt A} and {\tt B} are matrices of appropriate size. + If {\tt A} is a scalar, then it is added to or multiplied with every + entry in {\tt B}. \item {\tt a:b} where {\tt a} and {\tt b} are integers refers to the - sequence {\tt a}, {\tt a+1}, ... {\tt b}. - \item {\tt [A B]} and {\tt [A,B]} are the horizontal concatenation of {\tt A} and {\tt B}. + sequence {\tt a}, {\tt a+1}, ... {\tt b}. + \item {\tt [A B]} and {\tt [A,B]} are the horizontal concatenation of {\tt + A} and {\tt B}. \item {\tt [A;B]} is the vertical concatenation of {\tt A} and {\tt B}. \item {\tt A(i,j)} can refer either to a scalar or a submatrix. - For example: \newline - \vspace{0.05in} - \begin{tabular}{ll} - \hline - {\tt A(1,1)} & a scalar. \\ - {\tt A(:,j)} & column {\tt j} of {\tt A}. \\ - {\tt A(i,:)} & row {\tt i} of {\tt A}. \\ - {\tt A([1 2], [1 2])} & a 2-by-2 matrix containing the 2-by-2 leading minor of {\tt A}. \\ - \hline - \end{tabular} \newline - \vspace{0.1in} - If {\tt p} is a permutation of {\tt 1:n}, and {\tt A} is {\tt n}-by-{\tt n}, - then {\tt A(p,p)} corresponds to the permuted matrix $\m{PAP}\tr$. - \item {\tt tril(A)} is the lower triangular part of {\tt A}, including the diagonal. - \item {\tt tril(A,k)} is the lower triangular part of {\tt A}, including entries - on and below the $k$th diagonal. - \item {\tt triu(A)} is the upper triangular part of {\tt A}, including the diagonal. - \item {\tt triu(A,k)} is the upper triangular part of {\tt A}, including entries - on and above the $k$th diagonal. + For example: \newline + \vspace{0.05in} + \begin{tabular}{ll} + \hline + {\tt A(1,1)} & a scalar. \\ + {\tt A(:,j)} & column {\tt j} of {\tt A}. \\ + {\tt A(i,:)} & row {\tt i} of {\tt A}. \\ + {\tt A([1 2], [1 2])} & a 2-by-2 matrix containing the 2-by-2 leading + minor of {\tt A}. \\ + \hline + \end{tabular} \newline + \vspace{0.1in} + If {\tt p} is a permutation of {\tt 1:n}, and {\tt A} is {\tt + n}-by-{\tt n}, then {\tt A(p,p)} corresponds to the permuted matrix + $\m{PAP}\tr$. + + \item {\tt tril(A)} is the lower triangular part of {\tt A}, including the + diagonal. + + \item {\tt tril(A,k)} is the lower triangular part of {\tt A}, including + entries on and below the $k$th diagonal. + + \item {\tt triu(A)} is the upper triangular part of {\tt A}, including the + diagonal. + + \item {\tt triu(A,k)} is the upper triangular part of {\tt A}, including + entries on and above the $k$th diagonal. + \item {\tt size(A)} returns the dimensions of {\tt A}. - \item {\tt find(x)} if {\tt x} is a vector returns a list of indices {\tt i} - for which {\tt x(i)} is nonzero. - \item {\tt A'} is the transpose of {\tt A} if {\tt A} is real, or - the complex conjugate transpose if {\tt A} is complex. + + \item {\tt find(x)} if {\tt x} is a vector returns a list of indices {\tt + i} for which {\tt x(i)} is nonzero. + + \item {\tt A'} is the transpose of {\tt A} if {\tt A} is real, or the + complex conjugate transpose if {\tt A} is complex. + \item {\tt A.'} is the array transpose of {\tt A}. + \item {\tt diag(A)} is the diagonal of {\tt A} if {\tt A} is a matrix. + \item {\tt C=diag(s)} is a diagonal matrix if {\tt s} is a vector, - with the values of {\tt s} on the diagonal of {\tt C}. + with the values of {\tt s} on the diagonal of {\tt C}. + \item {\tt S=spones(A)} returns a binary matrix {\tt S} with the - same nonzero pattern of {\tt A}. + same nonzero pattern of {\tt A}. + \item {\tt nnz(A)} is the number of nonzero entries in {\tt A}. + \end{itemize} \noindent Variations to MATLAB notation used in this document: \begin{itemize} \item CHOLMOD uses 0-based notation (the first entry in the matrix is - {\tt A(0,0)}). MATLAB is 1-based. The context is usually clear. + {\tt A(0,0)}). MATLAB is 1-based. The context is usually clear. \item {\tt I} is the identity matrix. \item {\tt A(:,f)}, where {\tt f} is a set of columns, is interpreted - differently in CHOLMOD, but just for the set named {\tt f}. - See {\tt cholmod\_transpose\_unsym} for details. + differently in CHOLMOD, but just for the set named {\tt f}. + See {\tt cholmod\_transpose\_unsym} for details. \end{itemize} + %------------------------------------------------------------------------------- \newpage \section{The CHOLMOD Modules, objects, and functions} \label{Modules} %------------------------------------------------------------------------------- -CHOLMOD contains a total of 133 {\tt int}-based routines (and the same number -of {\tt int64\_t} routines), divided into a set of inter-related -Modules. Each Module contains a set of related functions. The functions -are divided into two types: Primary and Secondary, to reflect how a user will -typically use CHOLMOD. Most users will find the Primary routines to be -sufficient to use CHOLMOD in their programs. Each Module exists as a -sub-directory (a folder for Windows users) within the CHOLMOD directory -(or folder). +CHOLMOD contains over 150 {\tt int32\_t}-based routines and the same number of +{\tt int64\_t} routines with the same name except for {\tt \_l\_} added. These +are divided into a set of inter-related Modules. Each Module contains a set of +related functions. The functions are divided into two types: Primary and +Secondary, to reflect how a user will typically use CHOLMOD. Most users will +find the Primary routines to be sufficient to use CHOLMOD in their programs. +Each Module exists as a sub-directory (a folder for Windows users) within the +CHOLMOD directory (or folder). \vspace{0.1in} -\noindent There are seven Modules that provide user-callable routines for CHOLMOD. +\noindent There are seven Modules that provide user-callable routines for +CHOLMOD. + \begin{enumerate} \item {\tt Utility}: basic data structures and definitions \item {\tt Check}: prints/checks each of CHOLMOD's objects @@ -745,8 +803,173 @@ \subsection{Adjustable parameters} \verb'cholmod.h' include file, via cmake. \end{enumerate} + %------------------------------------------------------------------------------- -\newpage \subsection{{\tt Utility} Module: basic data structures and definitions} +\subsection{CHOLMOD objects} +%------------------------------------------------------------------------------- + +A CHOLMOD sparse, dense, or triplet matrix A, or a sparse factorization L can +hold numeric values of 8 different types, according to its {\tt A->xtype} and +{\tt A->dtype} parameters (or {\tt L->xtype} and {\tt L->dtype} for a sparse +factor object). These values are held in the {\tt A->x} array, and also {\tt +A->z} for zomplex matrices. + +{\bf xtype:} the matrix is real, complex, "zomplex", or pattern-only. + + \begin{itemize} + \item + (0): \verb'CHOLMOD_PATTERN': \verb'A->x' and \verb'A->z' are + \verb'NULL'. The matrix has no numerical values. Only the pattern is + stored. + + \item + (1): \verb'CHOLMOD_REAL': The matrix is real, and the values are + held in \verb'A->x', whose size (in terms of double or float values) is + given by \verb'A->nzmax'. The kth value in the matrix is held in + \verb'A->x[k]'. + + \item + (2): \verb'CHOLMOD_COMPLEX': The matrix is complex, with interleaved + real and imaginary parts. The kth value in the matrix is held in + \verb'A->x[2*k]' and \verb'A->x[2*k+1]', where \verb'A->x' can hold up + to \verb'2*A->nzmax' values. + + \item + (3): \verb'CHOLMOD_ZOMPLEX': The matrix is complex, with separate + array for the real and imaginary parts. The kth value in the matrix is + held in \verb'A->x[k]', and \verb'A->z[k]', where \verb'A->x' and + \verb'A->z' can hold up to A->nzmax values each. + \end{itemize} + + +{\bf dtype}: this parameter determines the type of values in A->x (and A->z + if zomplex). + + \begin{itemize} + \item + (0) \verb'CHOLMOD_DOUBLE': \verb'A->x' and \verb'A->z' (for zomplex + matrices) are \verb'double'. If A is real, \verb'A->x' has a size of + \verb'A->nzmax * sizeof (double)' bytes. If A is complex, \verb'A->x' + has size \verb'A->nzmax * 2 * sizeof (double)'. + If zomplex, both \verb'A->x' and \verb'A->z' have size + \verb'A->nzmax * sizeof (double)'. + + \item + (4) \verb'CHOLMOD_SINGLE': \verb'A->x' and \verb'A->z' (for zomplex + matrices) are \verb'float'. If A is real, \verb'A->x' has a size of + \verb'A->nzmax * sizeof (float)'. If A is complex, \verb'A->x' has + \verb'size A->nzmax * 2 * sizeof (float)'. + If zomplex, both \verb'A->x' and \verb'A->z' have size + \verb'A->nzmax * sizeof (float)'. + This feature is new to CHOLMOD v5. + \end{itemize} + + Unless stated otherwise, the xtype and dtypes of all inputs to a method must + be the same. + + Many methods accept an xdtype parameter, which is simply xtype + dtype, + combining the two parameters into a single number handling all 8 cases: + + \begin{itemize} + \item + (0) \verb'CHOLMOD_DOUBLE' + \verb'CHOLMOD_PATTERN': a pattern-only matrix + \item + (1) \verb'CHOLMOD_DOUBLE' + \verb'CHOLMOD_REAL': a double real matrix + \item + (2) \verb'CHOLMOD_DOUBLE' + \verb'CHOLMOD_COMPLEX': a double complex matrix + \item + (3) \verb'CHOLMOD_DOUBLE' + \verb'CHOLMOD_ZOMPLEX': a double zomplex matrix + \item + (4) \verb'CHOLMOD_SINGLE' + \verb'CHOLMOD_PATTERN': a pattern-only matrix + \item + (5) \verb'CHOLMOD_SINGLE' + \verb'CHOLMOD_REAL': a float real matrix + \item + (6) \verb'CHOLMOD_SINGLE' + \verb'CHOLMOD_COMPLEX': a float complex matrix + \item + (7) \verb'CHOLMOD_SINGLE' + \verb'CHOLMOD_ZOMPLEX': a float zomplex matrix + \end{itemize} + + This approach was selected for backward compatibility with CHOLMOD v4 and + earlier, where only the first four values were supported, and where the + parameter was called \verb'xtype' instead of \verb'xdtype'. Several + function names reflect the older parameter name (\verb'cholmod_*_xtype'), + but they have not been renamed \verb"_xdtype", for backward compatibility. + + A CHOLMOD sparse or triplet matrix A can held in three symmetry formats + according to its \verb'A->stype' parameter. Dense matrices do not have this + parameter and are always treated as unsymmetric. A sparse factor object L + is always held in lower triangular form, with no entries ever held in the + strictly upper triangular part. + + \begin{itemize} + \item + 0: the matrix is unsymmetric with both lower and upper parts stored. + + \item + $<0$: the matrix is symmetric, with just the lower triangular part and + diagonal stored. Any entries in the upper part are ignored. + + \item + $>0$: the matrix is symmetric, with just the upper triangular part + stored and diagonal. Any entries in the upper part are ignored. + \end{itemize} + + If a sparse or triplet matrix A is complex or zomplex, most methods treat + the matrix as Hermitian, where A(i,j) is the complex conjugate of A(j,i), + when i is not equal to j. Some methods can also interpret the matrix as + complex symmetric, where A(i,j) == A(j,i) when i != j. This is not + determined by the matrix itself, but by a "mode" parameter of the function. + This mode parameter also determines if the values of any matrix are to be + ignored entirely, in which case only the pattern is operated on. Any output + matrix will have an xtype of \verb'CHOLMOD_PATTERN'. + + The valid mode values are given below, except that many methods do not + handle the negative cases. Values below the range accepted by the method + are treated as its lowest accepted value, and values above the range + accepted by the method are treated as its highest accepted value. + + \begin{itemize} + \item + mode = 2: the numerical values of a real, complex, or zomplex matrix are + handled. If the matrix is complex or zomplex, an entry A(i,j) + that not stored (or in the ignored part) is treated as the + complex conjugate of A (j,i). Use this mode to treat a + complex or zomplex matrix as Hermitian. + + \item + mode = 1: the numerical values of a real, complex, or zomplex matrix are + handled. If the matrix is complex or zomplex, an entry A(i,j) + that not stored (or in the ignored part) is treated as equal A + (j,i). Use this mode to treat a complex or zomplex matrix as + complex symmetric. + + \item + mode = 0: the numerical values are ignored. Any output matrix will have + an xtype of \verb'CHOLMOD_PATTERN'. This mode allows inputs to + have different dtypes. + + \item + mode = -1: the same as mode = 0, except that the diagonal entries are + ignored, and do not appear in any output matrix. + + \item + mode = -2: the same as mode = -1, except that the output matrix is given an + additional slack space so that it can hold about 50% more + entries. This mode is documented here but it is primarily + meant for internal use, for CHOLMOD's interface to the AMD, + CAMD, COLAMD, and CCOLAMD ordering methods. + \end{itemize} + + The integer arrays in all objects are either int32 or int64, as determined + by \verb'A->type'. This integer type must be identical for all inputs, and + must also match both the function name (\verb'cholmod_method' for int32, or + \verb'cholmod_l_method' for int64) and the \verb'Common->itype' as defined + when CHOLMOD was initialized (via \verb'cholmod_start' for int32, or + \verb'cholmod_l_start' for int64). + +%------------------------------------------------------------------------------- +\subsection{{\tt Utility} Module: basic data structures and +definitions} %------------------------------------------------------------------------------- CHOLMOD includes five basic objects, defined in the {\tt Utility} Module. @@ -754,61 +977,70 @@ \subsection{Adjustable parameters} and is required by all six other CHOLMOD library Modules: \subsubsection{{\tt cholmod\_common}: parameters, statistics, and workspace} - You must call {\tt cholmod\_start} before calling any other - CHOLMOD routine, and you must call {\tt cholmod\_finish} as your - last call to CHOLMOD (with the exception of - {\tt cholmod\_print\_common} and {\tt cholmod\_check\_common} - in the {\tt Check} Module). - Once the {\tt cholmod\_common} object is initialized, - the user may modify CHOLMOD's parameters held in this object, - and obtain statistics on CHOLMOD's activity. + You must call {\tt cholmod\_start} before calling any other CHOLMOD + routine, and you must call {\tt cholmod\_finish} as your last call to + CHOLMOD (with the exception of {\tt cholmod\_print\_common} and {\tt + cholmod\_check\_common} in the {\tt Check} Module). Once the {\tt + cholmod\_common} object is initialized, the user may modify CHOLMOD's + parameters held in this object, and obtain statistics on CHOLMOD's + activity. + + When using 64-bit integers, use {\tt cholmod\_l\_start} and {\tt + cholmod\_l\_finish} instead. Matrices and other objects from different + integer sizes cannot be mixed \vspace{0.1in} \noindent Primary routines for the {\tt cholmod\_common} object: % 2 \begin{itemize} \item {\tt cholmod\_start}: the first call to CHOLMOD. - \item {\tt cholmod\_finish}: the last call to CHOLMOD (frees workspace in the {\tt cholmod\_common} object). + \item {\tt cholmod\_finish}: the last call to CHOLMOD (frees workspace in + the {\tt cholmod\_common} object). \end{itemize} \noindent Secondary routines for the {\tt cholmod\_common} object: -% 9 +% 11 \begin{itemize} \item {\tt cholmod\_defaults}: restores default parameters \item {\tt cholmod\_maxrank}: determine maximum rank for update/downdate. - \item {\tt cholmod\_allocate\_work}: allocate workspace. + \item {\tt cholmod\_allocate\_work}: allocate workspace ({\tt double} only). + \item {\tt cholmod\_alloc\_work}: allocate workspace, + {\tt double} or {\tt float}. \item {\tt cholmod\_free\_work}: free workspace. \item {\tt cholmod\_clear\_flag}: clear {\tt Flag} array. \item {\tt cholmod\_error}: called when CHOLMOD encounters and error. - \item {\tt cholmod\_dbound}: bounds the diagonal of $\m{L}$ or $\m{D}$. + \item {\tt cholmod\_dbound}: bounds the diagonal of $\m{L}$ or $\m{D}$ + ({\tt double} case). + \item {\tt cholmod\_sbound}: bounds the diagonal of $\m{L}$ or $\m{D}$. + ({\tt float} case). \item {\tt cholmod\_hypot}: compute {\tt sqrt(x*x+y*y)} accurately. \item {\tt cholmod\_divcomplex}: complex divide. \end{itemize} %------------------------------------------------------------------------------- -\newpage \subsubsection{{\tt cholmod\_sparse}: a sparse matrix in compressed column form} +\subsubsection{{\tt cholmod\_sparse}: a sparse matrix in compressed +column form} %------------------------------------------------------------------------------- + A sparse matrix {\tt A} is held in compressed column form. In the basic type (``packed,'' which corresponds to how MATLAB stores its sparse - matrices), and {\tt nrow}-by-{\tt ncol} matrix with {\tt nzmax} entries - is held in three arrays: {\tt p} of size {\tt ncol+1}, - {\tt i} of size {\tt nzmax}, and {\tt x} of size {\tt nzmax}. - Row indices of nonzero entries in column {\tt j} are held in - {\tt i [p[j] ... p[j+1]-1]}, and their corresponding numerical values - are held in {\tt x [p[j] ... p[j+1]-1]}. The first column starts at - location zero ({\tt p[0]=0}). - There may be no duplicate entries. Row indices in each column may - be sorted or unsorted (the {\tt A->sorted} flag must be false if - the columns are unsorted). The {\tt A->stype} determines the - storage mode: 0 if the matrix is unsymmetric, 1 if the matrix is - symmetric with just the upper triangular part stored, and -1 if - the matrix is symmetric with just the lower triangular part stored. - - In ``unpacked'' form, an additional array {\tt nz} of size {\tt ncol} - is used. The end of column {\tt j} in {\tt i} and {\tt x} - is given by {\tt p[j]+nz[j]}. Columns not need be in any particular - order ({\tt p[0]} need not be zero), and there may be gaps between - the columns. + matrices), and {\tt nrow}-by-{\tt ncol} matrix with {\tt nzmax} entries is + held in three arrays: {\tt p} of size {\tt ncol+1}, {\tt i} of size {\tt + nzmax}, and {\tt x} of size {\tt nzmax}. Row indices of nonzero entries in + column {\tt j} are held in {\tt i [p[j] ... p[j+1]-1]}, and their + corresponding numerical values are held in {\tt x [p[j] ... p[j+1]-1]}. + The first column starts at location zero ({\tt p[0]=0}). There may be no + duplicate entries. Row indices in each column may be sorted or unsorted + (the {\tt A->sorted} flag must be false if the columns are unsorted). The + {\tt A->stype} determines the storage: 0 if the matrix is unsymmetric, + 1 if the matrix is symmetric with just the upper triangular part stored, + and -1 if the matrix is symmetric with just the lower triangular part + stored. + + In ``unpacked'' form, an additional array {\tt nz} of size {\tt ncol} is + used. The end of column {\tt j} in {\tt i} and {\tt x} is given by {\tt + p[j]+nz[j]}. Columns not need be in any particular order ({\tt p[0]} need + not be zero), and there may be gaps between the columns. \vspace{0.1in} \noindent Primary routines for the {\tt cholmod\_sparse} object: @@ -819,35 +1051,42 @@ \subsubsection{{\tt cholmod\_common}: parameters, statistics, and workspace} \end{itemize} \noindent Secondary routines for the {\tt cholmod\_sparse} object: -% 16 +% 17 \begin{itemize} - \item {\tt cholmod\_reallocate\_sparse}: change the size (number of entries) of a sparse matrix. + \item {\tt cholmod\_reallocate\_sparse}: change the size (number of + entries) of a sparse matrix. \item {\tt cholmod\_nnz}: number of nonzeros in a sparse matrix. \item {\tt cholmod\_speye}: sparse identity matrix. \item {\tt cholmod\_spzeros}: sparse zero matrix. \item {\tt cholmod\_transpose}: transpose a sparse matrix. + \item {\tt cholmod\_transpose\_unsym}: transpose/permute an unsymmetric + sparse matrix. + \item {\tt cholmod\_transpose\_sym}: transpose/permute a symmetric sparse + matrix. \item {\tt cholmod\_ptranspose}: transpose/permute a sparse matrix. - \item {\tt cholmod\_transpose\_unsym}: transpose/permute an unsymmetric sparse matrix. - \item {\tt cholmod\_transpose\_sym}: transpose/permute a symmetric sparse matrix. - \item {\tt cholmod\_sort}: sort row indices in each column of a sparse matrix. + \item {\tt cholmod\_sort}: sort row indices in each column of a sparse + matrix. + \item {\tt cholmod\_band\_nnz}: number of entries in a band of a sparse + matrix. \item {\tt cholmod\_band}: extract a band of a sparse matrix. \item {\tt cholmod\_band\_inplace}: remove entries not with a band. \item {\tt cholmod\_aat}: {\tt C = A*A'}. - \item {\tt cholmod\_copy\_sparse}: {\tt C = A}, create an exact copy of a sparse matrix. + \item {\tt cholmod\_copy\_sparse}: {\tt C = A}, create an exact copy of a + sparse matrix. \item {\tt cholmod\_copy}: {\tt C = A}, with possible change of {\tt stype}. \item {\tt cholmod\_add}: {\tt C = alpha*A + beta*B}. - \item {\tt cholmod\_sparse\_xtype}: change the {\tt xtype} of a sparse matrix. + \item {\tt cholmod\_sparse\_xtype}: change the {\tt xtype} and/or + {\tt dtype} of a sparse matrix. \end{itemize} %------------------------------------------------------------------------------- -\newpage \subsubsection{{\tt cholmod\_factor}: a symbolic or numeric factorization} +\subsubsection{{\tt cholmod\_factor}: a symbolic or numeric factorization} %------------------------------------------------------------------------------- - A factor can be in $\m{LL}\tr$ or $\m{LDL}\tr$ form, and either supernodal - or simplicial form. In simplicial form, this is very much like a - packed or unpacked {\tt cholmod\_sparse} matrix. In supernodal - form, adjacent columns with similar nonzero pattern are stored as - a single block (a supernode). +A factor can be in $\m{LL}\tr$ or $\m{LDL}\tr$ form, and either supernodal or +simplicial form. In simplicial form, this is very much like a packed or +unpacked {\tt cholmod\_sparse} matrix. In supernodal form, adjacent columns +with similar nonzero pattern are stored as a single block (a supernode). \vspace{0.1in} \noindent Primary routine for the {\tt cholmod\_factor} object: @@ -857,16 +1096,24 @@ \subsubsection{{\tt cholmod\_common}: parameters, statistics, and workspace} \end{itemize} \noindent Secondary routines for the {\tt cholmod\_factor} object: -% 8 +% 9 \begin{itemize} - \item {\tt cholmod\_allocate\_factor}: allocate a factor. You will normally use {\tt cholmod\_analyze} to create a factor. - \item {\tt cholmod\_reallocate\_factor}: change the number of entries in a factor. - \item {\tt cholmod\_change\_factor}: change the type of a factor ($\m{LDL}\tr$ to $\m{LL}\tr$, supernodal to simplicial, etc.). + \item {\tt cholmod\_allocate\_factor}: allocate a factor. + ({\tt double} or {\tt float}). + You will normally use {\tt cholmod\_analyze} to create a factor. + \item {\tt cholmod\_alloc\_factor}: allocate a factor + ({\tt double} or {\tt float}). + \item {\tt cholmod\_reallocate\_factor}: change the number of entries in a + factor. + \item {\tt cholmod\_change\_factor}: change the type of a factor + ($\m{LDL}\tr$ to $\m{LL}\tr$, supernodal to simplicial, etc.). \item {\tt cholmod\_pack\_factor}: pack the columns of a factor. \item {\tt cholmod\_reallocate\_column}: resize a single column of a factor. - \item {\tt cholmod\_factor\_to\_sparse}: create a sparse matrix copy of a factor. + \item {\tt cholmod\_factor\_to\_sparse}: create a sparse matrix copy of a + factor. \item {\tt cholmod\_copy\_factor}: create a copy of a factor. - \item {\tt cholmod\_factor\_xtype}: change the xtype of a factor. + \item {\tt cholmod\_factor\_xtype}: change the {\tt xtype} and/or + {\tt dtype} of a factor. \end{itemize} %------------------------------------------------------------------------------- @@ -884,28 +1131,34 @@ \subsubsection{{\tt cholmod\_dense}: a dense matrix} \vspace{0.1in} \noindent Secondary routines for the {\tt cholmod\_dense} object: -% 8 +% 10 \begin{itemize} \item {\tt cholmod\_zeros}: allocate a dense matrix of all zeros. \item {\tt cholmod\_ones}: allocate a dense matrix of all ones. \item {\tt cholmod\_eye}: allocate a dense identity matrix . - \item {\tt cholmod\_sparse\_to\_dense}: create a dense matrix copy of a sparse matrix. - \item {\tt cholmod\_dense\_to\_sparse}: create a sparse matrix copy of a dense matrix. + \item {\tt cholmod\_ensure\_dense}: ensure a dense matrix has a given + size and type. + \item {\tt cholmod\_sparse\_to\_dense}: create a dense matrix copy of a + sparse matrix. + \item {\tt cholmod\_dense\_nnz}: number of nonzeros in a dense matrix. + \item {\tt cholmod\_dense\_to\_sparse}: create a sparse matrix copy of a + dense matrix. \item {\tt cholmod\_copy\_dense}: create a copy of a dense matrix. \item {\tt cholmod\_copy\_dense2}: copy a dense matrix (pre-allocated). - \item {\tt cholmod\_dense\_xtype}: change the {\tt xtype} of a dense matrix. + \item {\tt cholmod\_dense\_xtype}: change the {\tt xtype} + and/or {\tt dtype} of a dense matrix. \end{itemize} %------------------------------------------------------------------------------- -\newpage \subsubsection{{\tt cholmod\_triplet}: a sparse matrix in ``triplet'' form} +\subsubsection{{\tt cholmod\_triplet}: a sparse matrix in ``triplet'' form} %------------------------------------------------------------------------------- - The {\tt cholmod\_sparse} matrix is the basic sparse matrix used in - CHOLMOD, but it can be difficult for the user to construct. It also - does not easily support the inclusion of new entries in the matrix. - The {\tt cholmod\_triplet} matrix is provided to address these issues. - A sparse matrix in triplet form consists of three arrays of size - {\tt nzmax}: {\tt i}, {\tt j}, and {\tt x}, and a {\tt z} array - for the zomplex case. + +The {\tt cholmod\_sparse} matrix is the basic sparse matrix used in CHOLMOD, +but it can be difficult for the user to construct. It also does not easily +support the inclusion of new entries in the matrix. The {\tt cholmod\_triplet} +matrix is provided to address these issues. A sparse matrix in triplet form +consists of three arrays of size {\tt nzmax}: {\tt i}, {\tt j}, and {\tt x}, +and a {\tt z} array for the zomplex case. \vspace{0.1in} \noindent Primary routines for the {\tt cholmod\_triplet} object: @@ -913,24 +1166,30 @@ \subsubsection{{\tt cholmod\_dense}: a dense matrix} \begin{itemize} \item {\tt cholmod\_allocate\_triplet}: allocate a triplet matrix. \item {\tt cholmod\_free\_triplet}: free a triplet matrix. - \item {\tt cholmod\_triplet\_to\_sparse}: create a sparse matrix copy of a triplet matrix. + \item {\tt cholmod\_triplet\_to\_sparse}: create a sparse matrix copy of a + triplet matrix. \end{itemize} \noindent Secondary routines for the {\tt cholmod\_triplet} object: % 4 \begin{itemize} - \item {\tt cholmod\_reallocate\_triplet}: change the number of entries in a triplet matrix. - \item {\tt cholmod\_sparse\_to\_triplet}: create a triplet matrix copy of a sparse matrix. + \item {\tt cholmod\_reallocate\_triplet}: change the number of entries in a + triplet matrix. + \item {\tt cholmod\_sparse\_to\_triplet}: create a triplet matrix copy of a + sparse matrix. \item {\tt cholmod\_copy\_triplet}: create a copy of a triplet matrix. - \item {\tt cholmod\_triplet\_xtype}: change the {\tt xtype} of a triplet matrix. + \item {\tt cholmod\_triplet\_xtype}: change the {\tt xtype} and/or + {\tt dtype} of a triplet matrix. \end{itemize} %------------------------------------------------------------------------------- \subsubsection{Memory management routines} %------------------------------------------------------------------------------- - By default, CHOLMOD uses the ANSI C {\tt malloc}, {\tt free}, - {\tt calloc}, and {\tt realloc} routines. You may use different - routines by modifying function pointers in the {\tt cholmod\_common} object. + +By default, CHOLMOD uses the ANSI C {\tt malloc}, {\tt free}, +{\tt calloc}, and {\tt realloc} routines. You may use different +routines by modifying function pointers in the {\tt SuiteSparse\_config} +package. Refer to the user guide for that package for more details. \vspace{0.1in} \noindent Primary routines: @@ -945,41 +1204,47 @@ \subsubsection{Memory management routines} \begin{itemize} \item {\tt cholmod\_calloc}: {\tt calloc} wrapper. \item {\tt cholmod\_realloc}: {\tt realloc} wrapper. - \item {\tt cholmod\_realloc\_multiple}: {\tt realloc} wrapper for multiple objects. + \item {\tt cholmod\_realloc\_multiple}: {\tt realloc} wrapper for multiple + objects. \end{itemize} %------------------------------------------------------------------------------- \subsubsection{{\tt cholmod\_version:} Version control} %------------------------------------------------------------------------------- + The {\tt cholmod\_version} function returns the current version of CHOLMOD. %------------------------------------------------------------------------------- -\newpage \subsection{{\tt Check} Module: print/check the CHOLMOD objects} +\subsection{{\tt Check} Module: print/check the CHOLMOD objects} %------------------------------------------------------------------------------- - The {\tt Check} Module contains routines that check and print the five - basic objects in CHOLMOD, and three kinds of integer vectors (a set, - a permutation, and a tree). It also provides a routine to read a sparse - matrix from a file in Matrix Market format (http://www.nist.gov/MatrixMarket). - Requires the {\tt Utility} Module. + +The {\tt Check} Module contains routines that check and print the five basic +objects in CHOLMOD, and three kinds of integer vectors (a set, a permutation, +and a tree). It also provides a routine to read a sparse matrix from a file in +Matrix Market format (http://www.nist.gov/MatrixMarket). Requires the {\tt +Utility} Module. \vspace{0.1in} \noindent Primary routines: -% 4 +% 5 \begin{itemize} \item {\tt cholmod\_print\_common}: print the {\tt cholmod\_common} object, - including statistics on CHOLMOD's behavior (fill-in, flop count, - ordering methods used, and so on). + including statistics on CHOLMOD's behavior (fill-in, flop count, + ordering methods used, and so on). \item {\tt cholmod\_write\_sparse}: write a sparse matrix to a file - in Matrix Market format. + in Matrix Market format. \item {\tt cholmod\_write\_dense}: write a sparse matrix to a file - in Matrix Market format. + in Matrix Market format. \item {\tt cholmod\_read\_matrix}: read a sparse or dense matrix from a file - in Matrix Market format. + in Matrix Market format. + \item {\tt cholmod\_read\_matrix2}: read a sparse or dense matrix from a + file in Matrix Market format + ({\tt double} or {\tt float}). \end{itemize} \vspace{0.1in} \noindent Secondary routines: -% 18 +% 19 \begin{itemize} \item {\tt cholmod\_check\_common}: check the {\tt cholmod\_common} object \item {\tt cholmod\_check\_sparse}: check a sparse matrix @@ -990,119 +1255,154 @@ \subsubsection{{\tt cholmod\_version:} Version control} \item {\tt cholmod\_print\_factor}: print a Cholesky factorization \item {\tt cholmod\_check\_triplet}: check a triplet matrix \item {\tt cholmod\_print\_triplet}: print a triplet matrix - \item {\tt cholmod\_check\_subset}: check a subset (integer vector in given range) - \item {\tt cholmod\_print\_subset}: print a subset (integer vector in given range) + \item {\tt cholmod\_check\_subset}: check a subset (integer vector in given + range) + \item {\tt cholmod\_print\_subset}: print a subset (integer vector in given + range) \item {\tt cholmod\_check\_perm}: check a permutation (an integer vector) \item {\tt cholmod\_print\_perm}: print a permutation (an integer vector) - \item {\tt cholmod\_check\_parent}: check an elimination tree (an integer vector) - \item {\tt cholmod\_print\_parent}: print an elimination tree (an integer vector) + \item {\tt cholmod\_check\_parent}: check an elimination tree (an integer + vector) + \item {\tt cholmod\_print\_parent}: print an elimination tree (an integer + vector) \item {\tt cholmod\_read\_triplet}: read a triplet matrix from a file + \item {\tt cholmod\_read\_triplet2}: read a triplet matrix from a file + ({\tt double} or {\tt float}) \item {\tt cholmod\_read\_sparse}: read a sparse matrix from a file + \item {\tt cholmod\_read\_sparse2}: read a sparse matrix from a file + ({\tt double} or {\tt float}) \item {\tt cholmod\_read\_dense}: read a dense matrix from a file + \item {\tt cholmod\_read\_dense2}: read a dense matrix from a file + ({\tt double} or {\tt float}) + % + \item {\tt cholmod\_gpu\_stats}: print GPU timing statistics \end{itemize} %------------------------------------------------------------------------------- -\newpage \subsection{{\tt Cholesky} Module: sparse Cholesky factorization} +\subsection{{\tt Cholesky} Module: sparse Cholesky factorization} %------------------------------------------------------------------------------- The primary routines are all that a user requires to order, analyze, and -factorize a sparse symmetric positive definite matrix $\m{A}$ (or $\m{AA}\tr$), and -to solve $\m{Ax}=\m{b}$ (or $\m{AA}\tr\m{x}=\m{b}$). The primary routines rely on the secondary -routines, the {\tt Utility} Module, and the AMD and COLAMD packages. They -make optional use of the {\tt Supernodal} and {\tt Partition} Modules, the -METIS package, the CAMD package, and -the CCOLAMD package. The {\tt Cholesky} Module is -required by the {\tt Partition} Module. +factorize a sparse symmetric positive definite matrix $\m{A}$ (or $\m{AA}\tr$), +and to solve $\m{Ax}=\m{b}$ (or $\m{AA}\tr\m{x}=\m{b}$). The primary routines +rely on the secondary routines, the {\tt Utility} Module, and the AMD and +COLAMD packages. They make optional use of the {\tt Supernodal} and {\tt +Partition} Modules, the METIS package, the CAMD package, and the CCOLAMD +package. The {\tt Cholesky} Module is required by the {\tt Partition} Module. \vspace{0.1in} \noindent Primary routines: -% 4 + \begin{itemize} \item {\tt cholmod\_analyze}: order and analyze (simplicial or supernodal). - \item {\tt cholmod\_factorize}: simplicial or supernodal Cholesky factorization. - \item {\tt cholmod\_solve}: solve a linear system (simplicial or supernodal, dense $\m{x}$ and $\m{b}$). - \item {\tt cholmod\_spsolve}: solve a linear system (simplicial or supernodal, sparse $\m{x}$ and $\m{b}$ ). + \item {\tt cholmod\_factorize}: simplicial or supernodal Cholesky + factorization. + \item {\tt cholmod\_solve}: solve a linear system (simplicial or + supernodal, dense $\m{x}$ and $\m{b}$). + \item {\tt cholmod\_spsolve}: solve a linear system (simplicial or + supernodal, sparse $\m{x}$ and $\m{b}$ ). \end{itemize} \noindent Secondary routines: -% 15 + \begin{itemize} - \item {\tt cholmod\_analyze\_p}: analyze, with user-provided permutation or $\m{f}$ set. - \item {\tt cholmod\_factorize\_p}: factorize, with user-provided permutation or $\m{f}$. + \item {\tt cholmod\_analyze\_p}: analyze, with user-provided permutation or + $\m{f}$ set. +% \item {\tt cholmod\_analyze\_p2}: analyze for sparse QR or Cholesky. + \item {\tt cholmod\_factorize\_p}: factorize, with user-provided + permutation or $\m{f}$. \item {\tt cholmod\_analyze\_ordering}: analyze a permutation \item {\tt cholmod\_solve2}: solve a linear system, reusing workspace. \item {\tt cholmod\_etree}: find the elimination tree. - \item {\tt cholmod\_rowcolcounts}: compute the row/column counts of $\m{L}$. + \item {\tt cholmod\_rowcolcounts}: compute the row/column counts of + $\m{L}$. \item {\tt cholmod\_amd}: order using AMD. \item {\tt cholmod\_colamd}: order using COLAMD. \item {\tt cholmod\_rowfac}: incremental simplicial factorization. - \item {\tt cholmod\_row\_subtree}: find the nonzero pattern of a row of $\m{L}$. - \item {\tt cholmod\_row\_lsubtree}: find the nonzero pattern of a row of $\m{L}$. - \item {\tt cholmod\_row\_lsubtree}: find the nonzero pattern of $\m{L}^{-1}b$. + \item {\tt cholmod\_row\_subtree}: find the nonzero pattern of a row of + $\m{L}$. + \item {\tt cholmod\_lsolve\_pattern}: find the nonzero pattern of + $\m{L}^{-1}b$. + \item {\tt cholmod\_row\_lsubtree}: find the nonzero pattern of a row of + $\m{L}$. \item {\tt cholmod\_resymbol}: recompute the symbolic pattern of $\m{L}$. - \item {\tt cholmod\_resymbol\_noperm}: recompute the symbolic pattern of $\m{L}$, no permutation. + \item {\tt cholmod\_resymbol\_noperm}: recompute the symbolic pattern of + $\m{L}$, no permutation. + \item {\tt cholmod\_rcond}: compute the reciprocal condition number \item {\tt cholmod\_postorder}: postorder a tree. - \item {\tt cholmod\_rcond}: compute the reciprocal condition number estimate. - \item {\tt cholmod\_rowfac\_mask}: for use in LPDASA only. + estimate. +% \item {\tt cholmod\_rowfac\_mask}: for use in LPDASA only. \end{itemize} %------------------------------------------------------------------------------- -\newpage \subsection{{\tt Modify} Module: update/downdate a sparse Cholesky factorization} +\subsection{{\tt Modify} Module: update/downdate a sparse Cholesky +factorization} %------------------------------------------------------------------------------- -The {\tt Modify} Module contains sparse Cholesky modification routines: -update, downdate, row-add, and row-delete. -It can also modify a corresponding solution to $\m{Lx}=\m{b}$ when L is modified. -This module is most useful when applied on a Cholesky factorization computed by -the {\tt Cholesky} module, but it does not actually require the {\tt Cholesky} module. -The {\tt Utility} module can create an identity Cholesky factorization ($\m{LDL}\tr$ where -$\m{L}=\m{D}=\m{I}$) that can then be modified by these routines. -Requires the {\tt Utility} module. Not required by any other CHOLMOD Module. +The {\tt Modify} Module contains sparse Cholesky modification routines: update, +downdate, row-add, and row-delete. It can also modify a corresponding solution +to $\m{Lx}=\m{b}$ when L is modified. This module is most useful when applied +on a Cholesky factorization computed by the {\tt Cholesky} module, but it does +not actually require the {\tt Cholesky} module. The {\tt Utility} module can +create an identity Cholesky factorization ($\m{LDL}\tr$ where +$\m{L}=\m{D}=\m{I}$) that can then be modified by these routines. Requires the +{\tt Utility} module. Not required by any other CHOLMOD Module. \vspace{0.1in} \noindent Primary routine: -% 1 + \begin{itemize} \item {\tt cholmod\_updown}: multiple rank update/downdate \end{itemize} \noindent Secondary routines: -% 8 + \begin{itemize} - \item {\tt cholmod\_updown\_solve}: update/downdate, and modify solution to $\m{Lx=b}$ - \item {\tt cholmod\_updown\_mark}: update/downdate, and modify solution to partial $\m{Lx=b}$ - \item {\tt cholmod\_updown\_mask}: for use in LPDASA only. + \item {\tt cholmod\_updown\_solve}: update/downdate, and modify solution to + $\m{Lx=b}$ +% \item {\tt cholmod\_updown\_mark}: update/downdate, and modify solution to +% partial $\m{Lx=b}$ +% \item {\tt cholmod\_updown\_mask}: for use in LPDASA only. \item {\tt cholmod\_rowadd}: add a row to an $\m{LDL}\tr$ factorization - \item {\tt cholmod\_rowadd\_solve}: add a row, and update solution to $\m{Lx=b}$ - \item {\tt cholmod\_rowadd\_mark}: add a row, and update solution to partial $\m{Lx=b}$ + \item {\tt cholmod\_rowadd\_solve}: add a row, and update solution to + $\m{Lx=b}$ +% \item {\tt cholmod\_rowadd\_mark}: add a row, and update solution to +% partial $\m{Lx=b}$ \item {\tt cholmod\_rowdel}: delete a row from an $\m{LDL}\tr$ factorization \item {\tt cholmod\_rowdel\_solve}: delete a row, and downdate $\m{Lx=b}$ - \item {\tt cholmod\_rowdel\_mark}: delete a row, and downdate solution to partial $\m{Lx=b}$ +% \item {\tt cholmod\_rowdel\_mark}: delete a row, and downdate solution to +% partial $\m{Lx=b}$ \end{itemize} %------------------------------------------------------------------------------- \subsection{{\tt MatrixOps} Module: basic sparse matrix operations} %------------------------------------------------------------------------------- -The {\tt MatrixOps} Module provides -basic operations on sparse and dense matrices. -Requires the {\tt Utility} module. Not required by any other CHOLMOD module. -In the descriptions below, -{\tt A}, {\tt B}, and {\tt C:} are sparse matrices ({\tt cholmod\_sparse}), -{\tt X} and {\tt Y} are dense matrices ({\tt cholmod\_dense}), -{\tt s} is a scalar or vector, and -{\tt alpha} {\tt beta} are scalars. +The {\tt MatrixOps} Module provides basic operations on sparse and dense +matrices. Requires the {\tt Utility} module. Not required by any other +CHOLMOD module. In the descriptions below, {\tt A}, {\tt B}, and {\tt C:} are +sparse matrices ({\tt cholmod\_sparse}), {\tt X} and {\tt Y} are dense matrices +({\tt cholmod\_dense}), {\tt s} is a scalar or vector, and {\tt alpha} {\tt +beta} are scalars. + +Many of these operations are also available in GraphBLAS, with better +performance. -% 10 \begin{itemize} - \item {\tt cholmod\_drop}: drop entries from A with absolute value $\ge$ a given tolerance. - \item {\tt cholmod\_norm\_dense}: {\tt s = norm (X)}, 1-norm, infinity-norm, or 2-norm - \item {\tt cholmod\_norm\_sparse}: {\tt s = norm (A)}, 1-norm or infinity-norm - \item {\tt cholmod\_horzcat}: {\tt C = [A,B]} - \item {\tt cholmod\_scale}: {\tt A = diag(s)*A}, {\tt A*diag(s)}, {\tt s*A} or {\tt diag(s)*A*diag(s)}. - \item {\tt cholmod\_sdmult}: {\tt Y = alpha*(A*X) + beta*Y} or {\tt alpha*(A'*X) + beta*Y}. + \item {\tt cholmod\_drop}: drop entries from A with absolute value $\ge$ a + given tolerance. + \item {\tt cholmod\_norm\_dense}: {\tt s = norm (X)}, 1-norm, + infinity-norm, or 2-norm + \item {\tt cholmod\_norm\_sparse}: {\tt s = norm (A)}, 1-norm or + infinity-norm + \item {\tt cholmod\_scale}: {\tt A = diag(s)*A}, {\tt A*diag(s)}, {\tt s*A} + or {\tt diag(s)*A*diag(s)}. + \item {\tt cholmod\_sdmult}: {\tt Y = alpha*(A*X) + beta*Y} or {\tt + alpha*(A'*X) + beta*Y}. \item {\tt cholmod\_ssmult}: {\tt C = A*B} - \item {\tt cholmod\_submatrix}: {\tt C = A (i,j)}, where {\tt i} and {\tt j} are arbitrary integer vectors. + \item {\tt cholmod\_submatrix}: {\tt C = A (i,j)}, where {\tt i} and {\tt + j} are arbitrary integer vectors. + \item {\tt cholmod\_horzcat}: {\tt C = [A,B]} \item {\tt cholmod\_vertcat}: {\tt C = [A ; B]}. \item {\tt cholmod\_symmetry}: determine symmetry of a matrix. \end{itemize} @@ -1111,21 +1411,21 @@ \subsection{{\tt MatrixOps} Module: basic sparse matrix operations} \subsection{{\tt Supernodal} Module: supernodal sparse Cholesky factorization} %------------------------------------------------------------------------------- -The {\tt Supernodal} Module performs -supernodal analysis, factorization, and solve. The simplest way to use -these routines is via the {\tt Cholesky} Module. This Module does not provide any -fill-reducing orderings. It normally operates on matrices ordered by the -{\tt Cholesky} Module. -It does not require the {\tt Cholesky} Module itself, however. -Requires the {\tt Utility} Module, and two external packages: LAPACK and the BLAS. -Optionally used by the {\tt Cholesky} Module. All are secondary routines -since these functions are more easily used via the {\tt Cholesky} Module. +The {\tt Supernodal} Module performs supernodal analysis, factorization, and +solve. The simplest way to use these routines is via the {\tt Cholesky} +Module. This Module does not provide any fill-reducing orderings. It normally +operates on matrices ordered by the {\tt Cholesky} Module. It does not require +the {\tt Cholesky} Module itself, however. Requires the {\tt Utility} Module, +and two external packages: LAPACK and the BLAS. Optionally used by the {\tt +Cholesky} Module. All are secondary routines since these functions are more +easily used via the {\tt Cholesky} Module. \vspace{0.1in} \noindent Secondary routines: -% 4 + \begin{itemize} \item {\tt cholmod\_super\_symbolic}: supernodal symbolic analysis +% \item {\tt cholmod\_super\_symbolic2}: for sparse QR \item {\tt cholmod\_super\_numeric}: supernodal numeric factorization \item {\tt cholmod\_super\_lsolve}: supernodal $\m{Lx}=\m{b}$ solve \item {\tt cholmod\_super\_ltsolve}: supernodal $\m{L}\tr\m{x}=\m{b}$ solve @@ -1135,26 +1435,28 @@ \subsection{{\tt Supernodal} Module: supernodal sparse Cholesky factorization} \subsection{{\tt Partition} Module: graph-partitioning-based orderings} %------------------------------------------------------------------------------- -The {\tt Partition} Module provides -graph partitioning and graph-partition-based orderings. It includes an -interface to CAMD, CCOLAMD, and CSYMAMD, constrained minimum degree ordering -methods which order a matrix following constraints determined via nested -dissection. -Requires the {\tt Utility} and {\tt Cholesky} Modules, and two packages: {\tt METIS 5.1.0}, CAMD, and CCOLAMD. -Optionally used by the {\tt Cholesky} Module. All are secondary routines since -these are more easily used by the {\tt Cholesky} Module. +The {\tt Partition} Module provides graph partitioning and +graph-partition-based orderings. It includes an interface to CAMD, CCOLAMD, +and CSYMAMD, constrained minimum degree ordering methods which order a matrix +following constraints determined via nested dissection. Requires the {\tt +Utility} and {\tt Cholesky} Modules, and two packages: {\tt METIS 5.1.0}, CAMD, +and CCOLAMD. Optionally used by the {\tt Cholesky} Module. All are secondary +routines since these are more easily used by the {\tt Cholesky} Module. \vspace{0.1in} \noindent Secondary routines: -% 8 + \begin{itemize} - \item {\tt cholmod\_nested\_dissection}: CHOLMOD nested dissection ordering - \item {\tt cholmod\_metis}: METIS nested dissection ordering ({\tt METIS\_NodeND}) - \item {\tt cholmod\_camd}: interface to CAMD ordering \item {\tt cholmod\_ccolamd}: interface to CCOLAMD ordering \item {\tt cholmod\_csymamd}: interface to CSYMAMD ordering + \item {\tt cholmod\_camd}: interface to CAMD ordering + % + \item {\tt cholmod\_nested\_dissection}: CHOLMOD nested dissection ordering + \item {\tt cholmod\_metis}: METIS nested dissection ordering ({\tt + METIS\_NodeND}) \item {\tt cholmod\_bisect}: graph partitioner (currently based on METIS) - \item {\tt cholmod\_metis\_bisector}: direct interface to {\tt METIS\_NodeComputeSeparator}. + \item {\tt cholmod\_metis\_bisector}: direct interface to {\tt + METIS\_NodeComputeSeparator}. \item {\tt cholmod\_collapse\_septree}: pruned a separator tree from {\tt cholmod\_nested\_dissection}. \end{itemize} @@ -1163,10 +1465,10 @@ \subsection{{\tt Partition} Module: graph-partitioning-based orderings} \newpage \section{CHOLMOD naming convention, parameters, and return values} %------------------------------------------------------------------------------- -All routine names, data types, and CHOLMOD library files use the -{\tt cholmod\_} prefix. All macros and other {\tt \#define} statements -visible to the user program use the {\tt CHOLMOD} prefix. -The {\tt cholmod.h} file must be included in user programs that use CHOLMOD: +All routine names, data types, and CHOLMOD library files use the {\tt +cholmod\_} prefix. All macros and other {\tt \#define} statements visible to +the user program use the {\tt CHOLMOD} prefix. The {\tt cholmod.h} file must +be included in user programs that use CHOLMOD: {\footnotesize \begin{verbatim} @@ -1177,59 +1479,59 @@ \subsection{{\tt Partition} Module: graph-partitioning-based orderings} \noindent All CHOLMOD routines (in all modules) use the following protocol for return values: \begin{itemize} -\item {\tt int}: {\tt TRUE} (1) if successful, or {\tt FALSE} (0) otherwise. (exception: {\tt cholmod\_divcomplex}). +\item {\tt int}: {\tt TRUE} (1) if successful, or {\tt FALSE} (0) otherwise. +(exception: {\tt cholmod\_divcomplex}). \item {\tt int32\_t} or {\tt int64\_t}: a value $\ge 0$ if successful, or -1 otherwise. \item {\tt float} or {\tt double}: a value $\ge 0$ if successful, or -1 otherwise. \item {\tt size\_t}: a value $>$ 0 if successful, or 0 otherwise. -\item {\tt void *}: a non-{\tt NULL} pointer to newly allocated memory if successful, or {\tt NULL} otherwise. -\item {\tt cholmod\_sparse *}: a non-{\tt NULL} pointer to a newly allocated sparse matrix if successful, or {\tt NULL} otherwise. -\item {\tt cholmod\_factor *}: a non-{\tt NULL} pointer to a newly allocated factor if successful, or {\tt NULL} otherwise. -\item {\tt cholmod\_triplet *}: a non-{\tt NULL} pointer to a newly allocated triplet matrix if successful, or {\tt NULL} otherwise. -\item {\tt cholmod\_dense *}: a non-{\tt NULL} pointer to a newly allocated dense matrix if successful, or {\tt NULL} otherwise. +\item {\tt void *}: a non-{\tt NULL} pointer to newly allocated memory if + successful, or {\tt NULL} otherwise. +\item {\tt cholmod\_sparse *}: a non-{\tt NULL} pointer to a newly allocated + sparse matrix if successful, or {\tt NULL} otherwise. +\item {\tt cholmod\_factor *}: a non-{\tt NULL} pointer to a newly allocated + factor if successful, or {\tt NULL} otherwise. +\item {\tt cholmod\_triplet *}: a non-{\tt NULL} pointer to a newly allocated + triplet matrix if successful, or {\tt NULL} otherwise. +\item {\tt cholmod\_dense *}: a non-{\tt NULL} pointer to a newly allocated + dense matrix if successful, or {\tt NULL} otherwise. \end{itemize} -{\tt TRUE} and {\tt FALSE} are not defined in {\tt cholmod.h}, -since they may conflict with the user program. A routine that described -here returning {\tt TRUE} or {\tt FALSE} returns 1 or 0, respectively. -Any {\tt TRUE}/{\tt FALSE} parameter is true if nonzero, false if zero. +{\tt TRUE} and {\tt FALSE} are not defined in {\tt cholmod.h}, since they may +conflict with the user program. A routine that described here returning {\tt +TRUE} or {\tt FALSE} returns 1 or 0, respectively. Any {\tt TRUE}/{\tt FALSE} +parameter is true if nonzero, false if zero. \noindent Input, output, and input/output parameters: \begin{itemize} -\item Input parameters appear first in the parameter lists of all CHOLMOD routines. -They are not modified by CHOLMOD. +\item Input parameters appear first in the parameter lists of all CHOLMOD +routines. They are not modified by CHOLMOD. \item Input/output parameters (except for {\tt Common}) appear next. They must be defined on input, and are modified on output. \item Output parameters are listed next. If they are pointers, they must point to allocated space on input, but their contents are not defined on input. -\item Workspace parameters appear next. They are used in only two routines in the Supernodal module. -\item The {\tt cholmod\_common *Common} parameter always appears as the last parameter -(with two exceptions: {\tt cholmod\_hypot} and {\tt cholmod\_divcomplex}). -It is always an input/output parameter. +\item Workspace parameters appear next. They are used in only two routines in +the Supernodal module. +\item The {\tt cholmod\_common *Common} parameter always appears as the last +parameter (with two exceptions: {\tt cholmod\_hypot} and {\tt +cholmod\_divcomplex}). It is always an input/output parameter. \end{itemize} -% FIXME: also uses double when the method is single A floating-point scalar is passed to CHOLMOD as a pointer to a {\tt double} array of size two. The first entry in this array is the real part of the scalar, and the second entry is the imaginary part. The imaginary part is only accessed if the other inputs are complex or zomplex. In some cases the imaginary part is always ignored ({\tt cholmod\_factor\_p}, for example). +This method for passing scalars is used when the computations are done +both in {\tt double} and single ({\tt float}) precision. %------------------------------------------------------------------------------- \newpage \section{{\tt Utility} Module: {\tt cholmod\_common} object} \label{cholmod_common} %------------------------------------------------------------------------------- -%--------------------------------------- -\subsection{Constant definitions} -%--------------------------------------- - -\input{_defn.tex} -These definitions are used within the {\tt cholmod\_common} object, -called {\tt Common} both here and throughout the code. - %--------------------------------------- \subsection{{\tt cholmod\_common}: parameters, statistics, and workspace} %--------------------------------------- @@ -1240,12 +1542,12 @@ \subsection{{\tt cholmod\_common}: parameters, statistics, and workspace} {\tt cholmod\_start}, which initializes this object. %--------------------------------------- -\newpage \subsection{{\tt cholmod\_start}: start CHOLMOD} +\subsection{{\tt cholmod\_start}: start CHOLMOD} %--------------------------------------- \input{_start.tex} Sets the default parameters, clears the statistics, and initializes all -workspace pointers to {\tt NULL}. The {\tt int}/{\tt long} type +workspace pointers to {\tt NULL}. The {\tt int32}/{\tt int64\_t} type is set in {\tt Common->itype}. %--------------------------------------- @@ -1274,29 +1576,23 @@ \subsection{{\tt cholmod\_allocate\_work}: allocate workspace} %--------------------------------------- \input{_allocate_work.tex} -Allocates workspace in {\tt Common}. The workspace consists -of the integer {\tt Head}, {\tt Flag}, and {\tt Iwork} arrays, -of size {\tt nrow+1}, {\tt nrow}, and {\tt iworksize}, -respectively, and a {\tt double} % FIXME -array {\tt Xwork} of size -{\tt xworksize} entries. The {\tt Head} array is normally equal to -1 -when it is cleared. If the {\tt Flag} array is cleared, -all entries are less than {\tt Common->mark}. The {\tt Iwork} array is -not kept in any particular state. -The integer type is {\tt int} or {\tt long}, depending -on whether the {\tt cholmod\_} or {\tt cholmod\_l\_} routines -are used. +Allocates workspace in {\tt Common}. The workspace consists of the integer +{\tt Head}, {\tt Flag}, and {\tt Iwork} arrays, of size {\tt nrow+1}, {\tt +nrow}, and {\tt iworksize}, respectively, and a {\tt double} array {\tt Xwork} +of size {\tt xworksize} entries. The {\tt Head} array is normally equal to -1 +when it is cleared. If the {\tt Flag} array is cleared, all entries are less +than {\tt Common->mark}. The {\tt Iwork} array is not kept in any particular +state. The integer type is {\tt int32\_t} or {\tt int64\_t}, depending on +whether the {\tt cholmod\_} or {\tt cholmod\_l\_} routines are used. %--------------------------------------- -% \subsection{{\tt cholmod\_alloc\_work}: allocate workspace} +\subsection{{\tt cholmod\_alloc\_work}: allocate workspace} %--------------------------------------- -% FIXME: add this - -% \input{_alloc_work.tex} -% This is the same as {\tt cholmod\_allocate\_work}, except that -% the {\tt Xwork} array can be {\tt float} or {\tt double}, as -% determined by the {\tt dtype} input parameter. +\input{_alloc_work.tex} +This is the same as {\tt cholmod\_allocate\_work}, except that +the {\tt Xwork} array can be {\tt float} or {\tt double}, as +determined by the {\tt dtype} input parameter. %--------------------------------------- \subsection{{\tt cholmod\_free\_work}: free workspace} @@ -1317,11 +1613,9 @@ \subsection{{\tt cholmod\_error}: report error} %--------------------------------------- \input{_error.tex} -This routine is called when CHOLMOD encounters an error. -It prints a message (if printing is enabled), sets -{\tt Common->status}. It then calls the -user error handler routine {\tt Common->error\_handler}, -if it is not {\tt NULL}. +This routine is called when CHOLMOD encounters an error. It prints a message +(if printing is enabled), sets {\tt Common->status}. It then calls the user +error handler routine {\tt Common->error\_handler}, if it is not {\tt NULL}. %--------------------------------------- \subsection{{\tt cholmod\_dbound}: bound diagonal of $\m{L}$} @@ -1329,33 +1623,39 @@ \subsection{{\tt cholmod\_dbound}: bound diagonal of $\m{L}$} \input{_dbound.tex} Ensures that entries on the diagonal of $\m{L}$ for an $\m{LL}\tr$ -factorization are greater than or equal to {\tt Common->dbound}. +factorization are greater than or equal to {\tt Common->dbound}, +when computing in double precision ({\tt double}). For an $\m{LDL}\tr$ factorization, it ensures that the magnitude of the entries of $\m{D}$ are greater than or equal to {\tt Common->dbound}. +%--------------------------------------- +\subsection{{\tt cholmod\_sbound}: bound diagonal of $\m{L}$} +%--------------------------------------- + +\input{_sbound.tex} +Ensures that entries on the diagonal of $\m{L}$ for an $\m{LL}\tr$ +factorization are greater than or equal to {\tt Common->sbound}, when computing +in single precision ({\tt float}). For an $\m{LDL}\tr$ factorization, it +ensures that the magnitude of the entries of $\m{D}$ are greater than or equal +to {\tt Common->sbound}. + %--------------------------------------- \subsection{{\tt cholmod\_hypot}: {\tt sqrt(x*x+y*y)}} %--------------------------------------- \input{_hypot.tex} Computes the magnitude of a complex number. -This routine is the default value for the {\tt Common->hypotenuse} function pointer. -See also {\tt hypot}, in the standard {\tt math.h} header. If you have -the ANSI C99 {\tt hypot}, you can use {\tt Common->hypotenuse = hypot}. -The {\tt cholmod\_hypot} routine is provided in case you are using the -ANSI C89 standard, which does not have {\tt hypot}. +This routine calls {\tt SuiteSparse\_config\_hypot}. Refer to the +{\tt SuiteSparse\_config} package for details. %--------------------------------------- \subsection{{\tt cholmod\_divcomplex}: complex divide} %--------------------------------------- \input{_divcomplex.tex} -Divides two complex numbers. It returns 1 if a divide-by-zero occurred, or 0 otherwise. -This routine is the default value for the {\tt Common->complex\_divide} function pointer. -This return value is the single exception to the CHOLMOD rule that states all {\tt int} return -values are {\tt TRUE} if successful or {\tt FALSE} otherwise. -The exception is made to match the return value of a different complex divide routine -that is not a part of CHOLMOD, but can be used via the function pointer. +Divides two complex numbers. +This routine calls {\tt SuiteSparse\_config\_divcomplex}. Refer to the +{\tt SuiteSparse\_config} package for details. %------------------------------------------------------------------------------- \newpage \section{{\tt Utility} Module: {\tt cholmod\_sparse} object} @@ -1374,8 +1674,9 @@ \subsection{{\tt cholmod\_allocate\_sparse}: allocate sparse matrix} %--------------------------------------- \input{_allocate_sparse.tex} -Allocates a sparse matrix. {\tt A->i}, {\tt A->x}, and {\tt A->z} are not initialized. -The matrix returned is all zero, but it contains space enough for {\tt nzmax} entries. +Allocates a sparse matrix. Indices and values ({\tt A->i}, {\tt A->x}, and +{\tt A->z}) are allocated but not initialized. The matrix returned is valid, +has no entries, but contains space enough for {\tt nzmax} entries. %--------------------------------------- \subsection{{\tt cholmod\_free\_sparse}: free sparse matrix} @@ -1420,53 +1721,35 @@ \subsection{{\tt cholmod\_transpose}: transpose sparse matrix} \input{_transpose.tex} Returns the transpose or complex conjugate transpose of a sparse matrix. +Three kinds of transposes are available, depending on the {\tt mode} +parameter: -%--------------------------------------- -\subsection{{\tt cholmod\_ptranspose}: transpose/permute sparse matrix} -%--------------------------------------- - -\input{_ptranspose.tex} -Returns {\tt A'} or {\tt A(p,p)'} if {\tt A} is symmetric. -Returns {\tt A'}, {\tt A(:,f)'}, or {\tt A(p,f)'} if {\tt A} is unsymmetric. -See {\tt cholmod\_transpose\_unsym} for a discussion of how {\tt f} is used; -this usage deviates from the MATLAB notation. -Can also return the array transpose. - -%--------------------------------------- -\subsection{{\tt cholmod\_sort}: sort columns of a sparse matrix} -%--------------------------------------- - -\input{_sort.tex} -Sorts the columns of the matrix {\tt A}. Returns {\tt A} in packed form, even if it -starts as unpacked. Removes entries in the ignored part of a symmetric matrix. +\begin{itemize} +\item 0: do not compute the numerical values; create a + {\tt CHOLMOD\_PATTERN} matrix +\item 1: array transpose +\item 2: complex conjugate transpose (same as 2 if input is real or pattern) +\end{itemize} %--------------------------------------- -\subsection{{\tt cholmod\_transpose\_unsym}: transpose/permute unsymmetric sparse matrix} +\subsection{{\tt cholmod\_transpose\_unsym}: transpose/permute unsymmetric +sparse matrix} %--------------------------------------- \input{_transpose_unsym.tex} -Transposes and optionally permutes an unsymmetric sparse matrix. -The output matrix must be preallocated before calling this routine. +Transposes and optionally permutes an unsymmetric sparse matrix. The output +matrix must be preallocated before calling this routine. +The \verb'mode' parameter is the same as for \verb'cholmod_transpose'. Computes {\tt F=A'}, {\tt F=A(:,f)'} or {\tt F=A(p,f)'}, except that the indexing by {\tt f} does not work the same as the MATLAB notation (see below). -{\tt A->stype} is zero, which denotes that both the upper and lower triangular -parts of A are present (and used). The matrix {\tt A} may in fact be symmetric in pattern -and/or value; {\tt A->stype} just denotes which part of {\tt A} are stored. {\tt A} may be -rectangular. - -The integer vector -{\tt p} is a permutation of {\tt 0:m-1}, and {\tt f} is a subset of {\tt 0:n-1}, -where A is {\tt m}-by-{\tt n}. -There can be no duplicate entries in {\tt p} or {\tt f}. +{\tt A->stype} must be zero on input, which denotes that the matrix is +unsymmetric, with both the upper and lower triangular parts of A are present. +{\tt A} may be rectangular. -\noindent -Three kinds of transposes are available, depending on the {\tt values} parameter: -\begin{itemize} -\item 0: do not transpose the numerical values; create a {\tt CHOLMOD\_PATTERN} matrix -\item 1: array transpose -\item 2: complex conjugate transpose (same as 2 if input is real or pattern) -\end{itemize} +The integer vector {\tt p} is a permutation of {\tt 0:m-1}, and {\tt f} is a +subset of {\tt 0:n-1}, where A is {\tt m}-by-{\tt n}. There can be no +duplicate entries in {\tt p} or {\tt f}. \noindent The set {\tt f} is held in fset and fsize: @@ -1475,7 +1758,7 @@ \subsection{{\tt cholmod\_transpose\_unsym}: transpose/permute unsymmetric spars \item {\tt fset != NULL} means {\tt f = fset [0..fsize-1]}. \item {\tt fset != NULL} and {\tt fsize = 0} means {\tt f} is the empty set. \end{itemize} - + Columns not in the set {\tt f} are considered to be zero. That is, if {\tt A} is 5-by-10 then {\tt F=A(:,[3 4])'} is not 2-by-5, but 10-by-5, and rows 3 and 4 of {\tt F} are equal to columns 3 and 4 of {\tt A} (the other @@ -1490,86 +1773,118 @@ \subsection{{\tt cholmod\_transpose\_unsym}: transpose/permute unsymmetric spars F = F' \end{verbatim} -If you want the MATLAB equivalent {\tt F=A(p,f)} operation, use -{\tt cholmod\_submatrix} instead (which does not compute the transpose). -{\tt F->nzmax} must be large enough to hold the matrix {\tt F}. -If {\tt F->nz} is present then {\tt F->nz [j]} is equal to the number of entries in column {\tt j} of {\tt F}. -{\tt A} can be sorted or unsorted, with packed or unpacked columns. -If {\tt f} is present and not sorted in ascending order, then {\tt F} is unsorted -(that is, it may contain columns whose row indices do not appear in -ascending order). Otherwise, {\tt F} is sorted (the row indices in each -column of {\tt F} appear in strictly ascending order). +If you want the MATLAB equivalent {\tt F=A(p,f)} operation, use {\tt +cholmod\_submatrix} instead (which does not compute the transpose). {\tt +F->nzmax} must be large enough to hold the matrix {\tt F}. If {\tt F->nz} is +present then {\tt F->nz [j]} is equal to the number of entries in column {\tt +j} of {\tt F}. {\tt A} can be sorted or unsorted, with packed or unpacked +columns. If {\tt f} is present and not sorted in ascending order, then {\tt F} +is unsorted (that is, it may contain columns whose row indices do not appear in +ascending order). Otherwise, {\tt F} is sorted (the row indices in each column +of {\tt F} appear in strictly ascending order). -{\tt F} is returned in packed or unpacked form, depending on {\tt F->packed} on input. -If {\tt F->packed} is {\tt FALSE}, then {\tt F} is returned in unpacked form ({\tt F->nz} must be -present). Each row {\tt i} of {\tt F} is large enough to hold all the entries in row {\tt i} -of {\tt A}, even if {\tt f} is provided. That is, {\tt F->i} and -{\tt F->x [F->p [i] .. F->p [i] + F->nz [i] - 1]} contain all entries in {\tt A(i,f)}, -but {\tt F->p [i+1] - F->p [i]} is equal to the number of nonzeros in {\tt A (i,:)}, -not just {\tt A (i,f)}. -The {\tt cholmod\_transpose\_unsym} routine is the only operation in CHOLMOD that -can produce an unpacked matrix. +{\tt F} is returned in packed or unpacked form, depending on {\tt F->packed} on +input. If {\tt F->packed} is {\tt FALSE}, then {\tt F} is returned in unpacked +form ({\tt F->nz} must be present). Each row {\tt i} of {\tt F} is large +enough to hold all the entries in row {\tt i} of {\tt A}, even if {\tt f} is +provided. That is, {\tt F->i} and {\tt F->x [F->p [i] .. F->p [i] + F->nz [i] +- 1]} contain all entries in {\tt A(i,f)}, but {\tt F->p [i+1] - F->p [i]} is +equal to the number of nonzeros in {\tt A (i,:)}, not just {\tt A (i,f)}. The +{\tt cholmod\_transpose\_unsym} routine is the only operation in CHOLMOD that +can produce an unpacked sparse matrix. %--------------------------------------- -\subsection{{\tt cholmod\_transpose\_sym}: transpose/permute symmetric sparse matrix} +\subsection{{\tt cholmod\_transpose\_sym}: transpose/permute symmetric sparse +matrix} %--------------------------------------- \input{_transpose_sym.tex} -Computes {\tt F = A'} or {\tt F = A(p,p)'}, the transpose or permuted transpose, where -{\tt A->stype} is nonzero. {\tt A} must be square and symmetric. -If {\tt A->stype} $> 0$, then {\tt A} is a symmetric matrix where just the upper part -of the matrix is stored. Entries in the lower triangular part may be -present, but are ignored. -If {\tt A->stype} $< 0$, then {\tt A} is a symmetric matrix where just the lower part -of the matrix is stored. Entries in the upper triangular part may be present, but are ignored. -If {\tt F=A'}, then {\tt F} is returned -sorted; otherwise {\tt F} is unsorted for the {\tt F=A(p,p)'} case. -There can be no duplicate entries in {\tt p}. - -Three kinds of transposes are available, depending on the {\tt values} parameter: -\begin{itemize} -\item 0: do not transpose the numerical values; create a {\tt CHOLMOD\_PATTERN} matrix -\item 1: array transpose -\item 2: complex conjugate transpose (same as 2 if input is real or pattern) -\end{itemize} +Computes {\tt F = A'} or {\tt F = A(p,p)'}, the transpose or permuted +transpose, where {\tt A->stype} is nonzero. {\tt A} must be square and +symmetric. If {\tt A->stype} $> 0$, then {\tt A} is a symmetric matrix where +just the upper part of the matrix is stored. Entries in the lower triangular +part may be present, but are ignored. If {\tt A->stype} $< 0$, then {\tt A} is +a symmetric matrix where just the lower part of the matrix is stored. Entries +in the upper triangular part may be present, but are ignored. If {\tt F=A'}, +then {\tt F} is returned sorted; otherwise {\tt F} is unsorted for the {\tt +F=A(p,p)'} case. There can be no duplicate entries in {\tt p}. + +The \verb'mode' parameter is the same as for \verb'cholmod_transpose'. + +For {\tt cholmod\_transpose\_unsym} and {\tt cholmod\_transpose\_sym}, the +output matrix {\tt F} must already be pre-allocated by the caller, with the +correct dimensions. If {\tt F} is not valid or has the wrong dimensions, it is +not modified. Otherwise, if {\tt F} is too small, the transpose is not +computed; the contents of {\tt F->p} contain the column pointers of the +resulting matrix, where {\tt F->p [F->ncol] > F->nzmax}. In this case, the +remaining contents of {\tt F} are not modified. {\tt F} can still be properly +freed with {\tt cholmod\_free\_sparse}. -For {\tt cholmod\_transpose\_unsym} and {\tt cholmod\_transpose\_sym}, the output matrix -{\tt F} must already be pre-allocated by the caller, with the correct dimensions. -If {\tt F} is not valid or has the wrong dimensions, it is not modified. -Otherwise, if {\tt F} is too small, the transpose is not computed; the contents -of {\tt F->p} contain the column pointers of the resulting matrix, where -{\tt F->p [F->ncol] > F->nzmax}. In this case, the remaining contents of {\tt F} are -not modified. {\tt F} can still be properly freed with {\tt cholmod\_free\_sparse}. +%--------------------------------------- +\subsection{{\tt cholmod\_ptranspose}: transpose/permute sparse matrix} +%--------------------------------------- + +\input{_ptranspose.tex} +Returns {\tt A'} or {\tt A(p,p)'} if {\tt A} is symmetric. +Returns {\tt A'}, {\tt A(:,f)'}, or {\tt A(p,f)'} if {\tt A} is unsymmetric. +The \verb'mode' parameter is the same as for \verb'cholmod_transpose'. +See {\tt cholmod\_transpose\_unsym} for a discussion of how {\tt f} is used; +this usage deviates from the MATLAB notation. +Can also return the array transpose. + +%--------------------------------------- +\subsection{{\tt cholmod\_sort}: sort columns of a sparse matrix} +%--------------------------------------- + +\input{_sort.tex} +Sorts the columns of the matrix {\tt A}. Returns {\tt A} in packed form, even +if it starts as unpacked. Removes entries in the ignored part of a symmetric +matrix. + +%--------------------------------------- +\subsection{{\tt cholmod\_band\_nnz}: count entries in a band of a sparse +matrix} +%--------------------------------------- + +\input{_band_nnz.tex} +This method has the same inputs as \verb'cholmod_band', except that it +returns the count of entries instead of returning the new matrix. +The \verb'mode' parameter has no effect on this count. %--------------------------------------- \subsection{{\tt cholmod\_band}: extract band of a sparse matrix} %--------------------------------------- \input{_band.tex} -Returns {\tt C = tril (triu (A,k1), k2)}. -{\tt C} is a matrix consisting of the diagonals of A from {\tt k1} to {\tt k2}. -{\tt k=0} is the main diagonal of {\tt A}, {\tt k=1} is the superdiagonal, {\tt k=-1} is the -subdiagonal, and so on. If {\tt A} is {\tt m}-by-{\tt n}, then: +Returns {\tt C = tril (triu (A,k1), k2)}. {\tt C} is a matrix consisting of +the diagonals of A from {\tt k1} to {\tt k2}. {\tt k=0} is the main diagonal +of {\tt A}, {\tt k=1} is the superdiagonal, {\tt k=-1} is the subdiagonal, and +so on. If {\tt A} is {\tt m}-by-{\tt n}, then: + \begin{itemize} \item {\tt k1=-m} means {\tt C = tril (A,k2)} \item {\tt k2=n} means {\tt C = triu (A,k1)} -\item {\tt k1=0} and {\tt k2=0} means {\tt C = diag(A)}, except {\tt C} is a matrix, not a vector +\item {\tt k1=0} and {\tt k2=0} means {\tt C = diag(A)}, except {\tt C} is a +matrix, not a vector \end{itemize} -Values of {\tt k1} and {\tt k2} less than {\tt -m} are treated as {\tt -m}, and values greater -than {\tt n} are treated as {\tt n}. -{\tt A} can be of any symmetry (upper, lower, or unsymmetric); {\tt C} is returned in -the same form, and packed. If {\tt A->stype} $> 0$, entries in the lower -triangular part of {\tt A} are ignored, and the opposite is true if -{\tt A->stype} $< 0$. If {\tt A} has sorted columns, then so does {\tt C}. -{\tt C} has the same size as {\tt A}. +Values of {\tt k1} and {\tt k2} less than {\tt -m} are treated as {\tt -m}, and +values greater than {\tt n} are treated as {\tt n}. -{\tt C} can be returned as a numerical valued matrix (if {\tt A} has numerical values -and {\tt mode} $> 0$), as a pattern-only ({\tt mode} $=0$), or as a pattern-only but with -the diagonal entries removed ({\tt mode} $< 0$). +{\tt A} can be of any symmetry (upper, lower, or unsymmetric); {\tt C} is +returned in the same form, and packed. If {\tt A->stype} $> 0$, entries in the +lower triangular part of {\tt A} are ignored, and the opposite is true if {\tt +A->stype} $< 0$. If {\tt A} has sorted columns, then so does {\tt C}. {\tt C} +has the same size as {\tt A}. -The xtype of {\tt A} can be pattern or real. Complex or zomplex cases are supported only -if {\tt mode} is $\le 0$ (in which case the numerical values are ignored). +The \verb'mode' parameter determines how the numerical values are handled. +{\tt C} can be returned as a numerical valued matrix (if {\tt A} has numerical +values and {\tt mode} $> 0$), as a pattern-only ({\tt mode} $=0$), or as a +pattern-only but with the diagonal entries removed ({\tt mode} $< 0$). + +The xtype of {\tt A} can be pattern or real. Complex or zomplex cases are +supported only if {\tt mode} is $\le 0$ (in which case the numerical values are +ignored). %--------------------------------------- \subsection{{\tt cholmod\_band\_inplace}: extract band, in place} @@ -1586,14 +1901,14 @@ \subsection{{\tt cholmod\_aat}: compute $\m{AA}\tr$} \input{_aat.tex} Computes {\tt C = A*A'} or {\tt C = A(:,f)*A(:,f)'}. {\tt A} can be packed or unpacked, sorted or unsorted, but must be stored with -both upper and lower parts ({\tt A->stype} of zero). {\tt C} is returned as packed, -{\tt C->stype} of zero (both upper and lower parts present), and unsorted. See -{\tt cholmod\_ssmult} in the {\tt MatrixOps} Module for a more general matrix-matrix -multiply. -The xtype of {\tt A} can be pattern or real. Complex or zomplex cases are supported only -if {\tt mode} is $\le 0$ (in which case the numerical values are ignored). -You can trivially convert {\tt C} to a symmetric upper/lower matrix -by changing {\tt C->stype} to 1 or -1, respectively, after calling this routine. +both upper and lower parts ({\tt A->stype} of zero). {\tt C} is returned as +packed, {\tt C->stype} of zero (both upper and lower parts present), and +unsorted. See {\tt cholmod\_ssmult} in the {\tt MatrixOps} Module for a more +general matrix-matrix multiply. The xtype of {\tt A} can be pattern or real. +Complex or zomplex cases are supported only if {\tt mode} is $\le 0$ (in which +case the numerical values are ignored). You can trivially convert {\tt C} to a +symmetric upper/lower matrix by changing {\tt C->stype} to 1 or -1, +respectively, after calling this routine. %--------------------------------------- \subsection{{\tt cholmod\_copy\_sparse}: copy sparse matrix} @@ -1607,26 +1922,30 @@ \subsection{{\tt cholmod\_copy}: copy (and change) sparse matrix} %--------------------------------------- \input{_copy.tex} -{\tt C = A}, which allocates {\tt C} and copies {\tt A} into {\tt C}, with possible change of -{\tt stype}. The diagonal can optionally be removed. The numerical entries -can optionally be copied. This routine differs from {\tt cholmod\_copy\_sparse}, -which makes an exact copy of a sparse matrix. +{\tt C = A}, which allocates {\tt C} and copies {\tt A} into {\tt C}, with +possible change of {\tt stype}. The diagonal can optionally be removed. The +numerical entries can optionally be copied. This routine differs from {\tt +cholmod\_copy\_sparse}, which makes an exact copy of a sparse matrix. -{\tt A} can be of any type (packed/unpacked, upper/lower/unsymmetric). {\tt C} is -packed and can be of any stype (upper/lower/unsymmetric), except that if -{\tt A} is rectangular {\tt C} can only be unsymmetric. If the stype of A and C -differ, then the appropriate conversion is made. +{\tt A} can be of any type (packed/unpacked, upper/lower/unsymmetric). {\tt C} +is packed and can be of any stype (upper/lower/unsymmetric), except that if +{\tt A} is rectangular {\tt C} can only be unsymmetric. If the stype of A and +C differ, then the appropriate conversion is made. \noindent There are three cases for {\tt A->stype}: \begin{itemize} -\item $<0$, lower: assume {\tt A} is symmetric with just {\tt tril(A)} stored; the rest of {\tt A} is ignored -\item $ 0$, unsymmetric: assume {\tt A} is unsymmetric; consider all entries in A -\item $>0$, upper: assume {\tt A} is symmetric with just {\tt triu(A)} stored; the rest of {\tt A} is ignored +\item $<0$, lower: assume {\tt A} is symmetric with just {\tt tril(A)} stored; +the rest of {\tt A} is ignored +\item $ 0$, unsymmetric: assume {\tt A} is unsymmetric; consider all entries +in A +\item $>0$, upper: assume {\tt A} is symmetric with just {\tt triu(A)} stored; +the rest of {\tt A} is ignored \end{itemize} \noindent -There are three cases for the requested symmetry of {\tt C} ({\tt stype} parameter): +There are three cases for the requested symmetry of {\tt C} ({\tt stype} +parameter): \begin{itemize} \item $<0$, lower: return just {\tt tril(C)} \item $0$, unsymmetric: return all of {\tt C} @@ -1635,25 +1954,31 @@ \subsection{{\tt cholmod\_copy}: copy (and change) sparse matrix} \noindent This gives a total of nine combinations: \newline + +{\small \begin{tabular}{ll} \hline -Equivalent MATLAB statements & Using {\tt cholmod\_copy} \\ +Equivalent MATLAB statements & Using {\tt cholmod\_copy} \\ \hline -{\tt C = A ; }& {\tt A} unsymmetric, {\tt C} unsymmetric \\ -{\tt C = tril (A) ; }& {\tt A} unsymmetric, {\tt C} lower \\ -{\tt C = triu (A) ; }& {\tt A} unsymmetric, {\tt C} upper \\ -{\tt U = triu (A) ; L = tril (U',-1) ; C = L+U ; }& {\tt A} upper, {\tt C} unsymmetric \\ -{\tt C = triu (A)' ; }& {\tt A} upper, {\tt C} lower \\ -{\tt C = triu (A) ; }& {\tt A} upper, {\tt C} upper \\ -{\tt L = tril (A) ; U = triu (L',1) ; C = L+U ; }& {\tt A} lower, {\tt C} unsymmetric \\ -{\tt C = tril (A) ; }& {\tt A} lower, {\tt C} lower \\ -{\tt C = tril (A)' ; }& {\tt A} lower, {\tt C} upper \\ +{\tt C = A ; }& {\tt A} unsymmetric, {\tt C} unsymmetric \\ +{\tt C = tril (A) ; }& {\tt A} unsymmetric, {\tt C} lower \\ +{\tt C = triu (A) ; }& {\tt A} unsymmetric, {\tt C} upper \\ +{\tt U = triu (A) ; L = tril (U',-1) ; C = L+U ;} + & {\tt A} upper, {\tt C} unsymmetric \\ +{\tt C = triu (A)' ; }& {\tt A} upper, {\tt C} lower \\ +{\tt C = triu (A) ; }& {\tt A} upper, {\tt C} upper \\ +{\tt L = tril (A) ; U = triu (L',1) ; C = L+U ;} + & {\tt A} lower, {\tt C} unsymmetric \\ +{\tt C = tril (A) ; }& {\tt A} lower, {\tt C} lower \\ +{\tt C = tril (A)' ; }& {\tt A} lower, {\tt C} upper \\ \hline -\end{tabular} +\end{tabular}} \vspace{0.1in} -The xtype of {\tt A} can be pattern or real. Complex or zomplex cases are supported only -if {\tt values} is {\tt FALSE} (in which case the numerical values are ignored). +The \verb'mode' parameter determines whether a pattern-only copy is made, or +whether a numerical copy is make, and also how the transpose is done above for +the complex case (conjugate matrix transpose, or non-conjugate array +transpose). %--------------------------------------- \subsection{{\tt cholmod\_add}: add sparse matrices} @@ -1661,17 +1986,19 @@ \subsection{{\tt cholmod\_add}: add sparse matrices} \input{_add.tex} Returns {\tt C = alpha*A + beta*B}. -If the {\tt stype} of {\tt A} and {\tt B} match, then {\tt C} has -the same {\tt stype}. Otherwise, {\tt C->stype} is zero ({\tt C} is -unsymmetric). +If the {\tt stype} of {\tt A} and {\tt B} match, then {\tt C} has the same {\tt +stype}. Otherwise, {\tt C->stype} is zero ({\tt C} is unsymmetric). If the +\verb'stype' of any input matrix is nonzero, it must be converted to +unsymmetric, controlled by the \verb'mode' parameter. %--------------------------------------- \subsection{{\tt cholmod\_sparse\_xtype}: change sparse xtype} %--------------------------------------- \input{_sparse_xtype.tex} -Changes the {\tt xtype} of a sparse matrix, to pattern, real, complex, or zomplex. -Changing from complex or zomplex to real discards the imaginary part. +Changes the {\tt xtype} and/or \verb'dtype' of a sparse matrix, to pattern, +real, complex, or zomplex. Changing from complex or zomplex to real discards +the imaginary part. %------------------------------------------------------------------------------- \newpage \section{{\tt Utility} Module: {\tt cholmod\_factor} object} @@ -1702,6 +2029,14 @@ \subsection{{\tt cholmod\_allocate\_factor}: allocate factor} \input{_allocate_factor.tex} Allocates a factor and sets it to identity. +%--------------------------------------- +\subsection{{\tt cholmod\_alloc\_factor}: allocate factor} +%--------------------------------------- + +\input{_alloc_factor.tex} +Allocates a factor and sets it to identity +({\tt double} or {\tt float}). + %--------------------------------------- \subsection{{\tt cholmod\_reallocate\_factor}: reallocate factor} %--------------------------------------- @@ -1714,79 +2049,83 @@ \subsection{{\tt cholmod\_change\_factor}: change factor} %--------------------------------------- \input{_change_factor.tex} -Change the numeric or symbolic, $\m{LL}\tr$ or $\m{LDL}\tr$, simplicial or super, packed or unpacked, and -monotonic or non-monotonic status of a {\tt cholmod\_factor} object. +Change the numeric or symbolic, $\m{LL}\tr$ or $\m{LDL}\tr$, simplicial or +super, packed or unpacked, and monotonic or non-monotonic status of a {\tt +cholmod\_factor} object. There are four basic classes of factor types: \begin{enumerate} -\item simplicial symbolic: Consists of two size-{\tt n} arrays: the fill-reducing - permutation ({\tt L->Perm}) and the nonzero count for each column of L - ({\tt L->ColCount}). All other factor types also include this information. - {\tt L->ColCount} may be exact (obtained from the analysis routines), or it - may be a guess. During factorization, and certainly after update/downdate, - the columns of {\tt L} can have a different number of nonzeros. {\tt - L->ColCount} is used to allocate space. {\tt L->ColCount} is exact for the - supernodal factorizations. The nonzero pattern of {\tt L} is not kept. - -\item simplicial numeric: These represent {\tt L} in a compressed column form. The - variants of this type are: +\item simplicial symbolic: Consists of two size-{\tt n} arrays: the + fill-reducing permutation ({\tt L->Perm}) and the nonzero count for each + column of L ({\tt L->ColCount}). All other factor types also include this + information. {\tt L->ColCount} may be exact (obtained from the analysis + routines), or it may be a guess. During factorization, and certainly after + update/downdate, the columns of {\tt L} can have a different number of + nonzeros. {\tt L->ColCount} is used to allocate space. {\tt L->ColCount} + is exact for the supernodal factorizations. The nonzero pattern of {\tt L} + is not kept. + +\item simplicial numeric: These represent {\tt L} in a compressed column form. + The variants of this type are: \begin{itemize} - \item $\m{LDL}\tr$: {\tt L} is unit diagonal. Row indices in column {\tt j} are located in - {\tt L->i [L->p [j] ... L->p [j] + L->nz [j]]}, and corresponding numeric - values are in the same locations in {\tt L->x}. The total number of - entries is the sum of {\tt L->nz [j]}. The unit diagonal is not stored; - {\tt D} is stored on the diagonal of {\tt L} instead. {\tt L->p} may or may not be - monotonic. The order of storage of the columns in {\tt L->i} and {\tt L->x} is - given by a doubly-linked list ({\tt L->prev} and {\tt L->next}). {\tt L->p} is of - size {\tt n+1}, but only the first {\tt n} entries are used. - - For the complex case, {\tt L->x} is stored interleaved with real and imaginary - parts, and is of size {\tt 2*lnz*sizeof(double)}. % FIXME - For the zomplex case, - {\tt L->x} is of size {\tt lnz*sizeof(double)} % FIXME - and holds the real part; {\tt L->z} - is the same size and holds the imaginary part. - - \item $\m{LL}\tr$: This is identical to the $\m{LDL}\tr$ form, except that the non-unit - diagonal of {\tt L} is stored as the first entry in each column of {\tt L}. + \item $\m{LDL}\tr$: {\tt L} is unit diagonal. Row indices in column {\tt + j} are located in {\tt L->i [L->p [j] ... L->p [j] + L->nz [j]]}, and + corresponding numeric values are in the same locations in {\tt L->x}. + The total number of entries is the sum of {\tt L->nz [j]}. The unit + diagonal is not stored; {\tt D} is stored on the diagonal of {\tt L} + instead. {\tt L->p} may or may not be monotonic. The order of storage + of the columns in {\tt L->i} and {\tt L->x} is given by a doubly-linked + list ({\tt L->prev} and {\tt L->next}). {\tt L->p} is of size {\tt + n+1}, but only the first {\tt n} entries are used. + + For the complex case, {\tt L->x} is stored interleaved with real and + imaginary parts, and is of size {\tt 2*lnz*sizeof(double)} or {\tt + 2*lnz*sizeof(float)}. For the zomplex case, {\tt L->x} is of size {\tt + lnz*sizeof(double)} or {\tt lnz*sizeof(float)} and holds the real part; + {\tt L->z} is the same size and holds the imaginary part. + + \item $\m{LL}\tr$: This is identical to the $\m{LDL}\tr$ form, except that + the non-unit diagonal of {\tt L} is stored as the first entry in each + column of {\tt L}. + \end{itemize} \item supernodal symbolic: A representation of the nonzero pattern of the supernodes for a supernodal factorization. There are {\tt L->nsuper} - supernodes. Columns {\tt L->super [k]} to {\tt L->super [k+1]-1} are in the {\tt k}th - supernode. The row indices for the {\tt k}th supernode are in - {\tt L->s [L->pi [k] ... L->pi [k+1]-1]}. The numerical values are not - allocated ({\tt L->x}), but when they are they will be located in - {\tt L->x [L->px [k] ... L->px [k+1]-1]}, and the {\tt L->px} array is defined - in this factor type. - - For the complex case, {\tt L->x} is stored interleaved with real/imaginary parts, - and is of size \newline - {\tt 2*L->xsize*sizeof(double)}. % FIXME - The zomplex supernodal case - is not supported, since it is not compatible with LAPACK and the BLAS. - -\item supernodal numeric: Always an $\m{LL}\tr$ factorization. {\tt L} has a non-unit - diagonal. {\tt L->x} contains the numerical values of the supernodes, as - described above for the supernodal symbolic factor. - For the complex case, {\tt L->x} is stored interleaved, and is of size - {\tt 2*L->xsize*sizeof(double)}. % FIXME - The zomplex supernodal case is not - supported, since it is not compatible with LAPACK and the BLAS. + supernodes. Columns {\tt L->super [k]} to {\tt L->super [k+1]-1} are in + the {\tt k}th supernode. The row indices for the {\tt k}th supernode are + in {\tt L->s [L->pi [k] ... L->pi [k+1]-1]}. The numerical values are not + allocated ({\tt L->x}), but when they are they will be located in {\tt L->x + [L->px [k] ... L->px [k+1]-1]}, and the {\tt L->px} array is defined in + this factor type. + + For the complex case, {\tt L->x} is stored interleaved with real/imaginary + parts, and is of size \newline {\tt 2*L->xsize*sizeof(double)} or {\tt + 2*L->xsize*sizeof(float)}. The zomplex supernodal case is not + supported, since it is not compatible with LAPACK and the BLAS. + +\item supernodal numeric: Always an $\m{LL}\tr$ factorization. {\tt L} has a + non-unit diagonal. {\tt L->x} contains the numerical values of the + supernodes, as described above for the supernodal symbolic factor. For the + complex case, {\tt L->x} is stored interleaved, and is of size {\tt + 2*L->xsize*sizeof(double)} or {\tt 2*L->xsize*sizeof(double)}. The zomplex + supernodal case is not supported, since it is not compatible with LAPACK + and the BLAS. + \end{enumerate} -In all cases, the row indices in each column ({\tt L->i} for simplicial {\tt L} and -{\tt L->s} for supernodal {\tt L}) are kept sorted from low indices to high indices. -This means the diagonal of {\tt L} (or {\tt D} for a $\m{LDL}\tr$ factorization) is always kept as the -first entry in each column. The elimination tree is not kept. The parent -of node {\tt j} can be found as the second row index in the {\tt j}th column. -If column {\tt j} has no off-diagonal entries then node {\tt j} is a root -of the elimination tree. +In all cases, the row indices in each column ({\tt L->i} for simplicial {\tt L} +and {\tt L->s} for supernodal {\tt L}) are kept sorted from low indices to high +indices. This means the diagonal of {\tt L} (or {\tt D} for a $\m{LDL}\tr$ +factorization) is always kept as the first entry in each column. The +elimination tree is not kept. The parent of node {\tt j} can be found as the +second row index in the {\tt j}th column. If column {\tt j} has no +off-diagonal entries then node {\tt j} is a root of the elimination tree. -The {\tt cholmod\_change\_factor} routine can do almost all possible conversions. -It cannot do the following conversions: +The {\tt cholmod\_change\_factor} routine can do almost all possible +conversions. It cannot do the following conversions: \begin{itemize} \item Simplicial numeric types cannot be converted to a supernodal @@ -1809,9 +2148,9 @@ \subsection{{\tt cholmod\_change\_factor}: change factor} Supports all xtypes, except that there is no supernodal zomplex L. -The {\tt to\_xtype} parameter is used only when converting from symbolic to numeric -or numeric to symbolic. It cannot be used to convert a numeric xtype (real, -complex, or zomplex) to a different numeric xtype. For that conversion, +The {\tt to\_xdtype} parameter is used only when converting from symbolic to +numeric or numeric to symbolic. It cannot be used to convert a numeric xtype +(real, complex, or zomplex) to a different numeric xtype. For that conversion, use {\tt cholmod\_factor\_xtype} instead. %--------------------------------------- @@ -1819,21 +2158,24 @@ \subsection{{\tt cholmod\_pack\_factor}: pack the columns of a factor} %--------------------------------------- \input{_pack_factor.tex} -Pack the columns of a simplicial $\m{LDL}\tr$ or $\m{LL}\tr$ factorization. This can be followed -by a call to {\tt cholmod\_reallocate\_factor} to reduce the size of {\tt L} to the exact -size required by the factor, if desired. Alternatively, you can leave the -size of {\tt L->i} and {\tt L->x} the same, to allow space for future updates/rowadds. -Each column is reduced in size so that it has at most {\tt Common->grow2} free -space at the end of the column. -Does nothing and returns silently if given any other type of factor. -Does not force the columns of {\tt L} to be monotonic. It thus differs from +Pack the columns of a simplicial $\m{LDL}\tr$ or $\m{LL}\tr$ factorization. +This can be followed by a call to {\tt cholmod\_reallocate\_factor} to reduce +the size of {\tt L} to the exact size required by the factor, if desired. +Alternatively, you can leave the size of {\tt L->i} and {\tt L->x} the same, to +allow space for future updates/rowadds. Each column is reduced in size so that +it has at most {\tt Common->grow2} free space at the end of the column. Does +nothing and returns silently if given any other type of factor. Does not force +the columns of {\tt L} to be monotonic. It thus differs from + \begin{verbatim} cholmod_change_factor (xtype, L->is_ll, FALSE, TRUE, TRUE, L, Common) \end{verbatim} + which packs the columns and ensures that they appear in monotonic order. %--------------------------------------- -\subsection{{\tt cholmod\_reallocate\_column}: reallocate one column of a factor} +\subsection{{\tt cholmod\_reallocate\_column}: reallocate one column of a +factor} %--------------------------------------- \input{_reallocate_column.tex} @@ -1896,14 +2238,6 @@ \subsection{{\tt cholmod\_free\_dense}: free dense matrix} \input{_free_dense.tex} Frees a dense matrix. -%--------------------------------------- -\subsection{{\tt cholmod\_ensure\_dense}: ensure dense matrix has a given size -and type} -%--------------------------------------- - -\input{_ensure_dense.tex} -Ensures a dense matrix has a given size and type. - %--------------------------------------- %--------------------------------------- @@ -1927,6 +2261,14 @@ \subsection{{\tt cholmod\_eye}: dense identity matrix} \input{_eye.tex} Returns a dense identity matrix. +%--------------------------------------- +\subsection{{\tt cholmod\_ensure\_dense}: ensure dense matrix has a given size +and type} +%--------------------------------------- + +\input{_ensure_dense.tex} +Ensures a dense matrix has a given size and type. + %--------------------------------------- \subsection{{\tt cholmod\_sparse\_to\_dense}: dense matrix copy of a sparse matrix} %--------------------------------------- @@ -1960,15 +2302,17 @@ \subsection{{\tt cholmod\_copy\_dense2}: copy dense matrix (preallocated)} %--------------------------------------- \input{_copy_dense2.tex} -Returns a copy of a dense matrix, placing the result in a preallocated matrix {\tt Y}. +Returns a copy of a dense matrix, placing the result in a preallocated matrix +{\tt Y}. %--------------------------------------- \subsection{{\tt cholmod\_dense\_xtype}: change dense matrix xtype} %--------------------------------------- \input{_dense_xtype.tex} -Changes the {\tt xtype} of a dense matrix, to real, complex, or zomplex. -Changing from complex or zomplex to real discards the imaginary part. +Changes the {\tt xtype} and/or {\tt dtype} of a dense matrix, to real, complex, +or zomplex. Changing from complex or zomplex to real discards the imaginary +part. A dense matrix cannot be converted to an xtype of pattern-only. %------------------------------------------------------------------------------- \newpage \section{{\tt Utility} Module: {\tt cholmod\_triplet} object} @@ -1996,6 +2340,20 @@ \subsection{{\tt cholmod\_free\_triplet}: free triplet matrix} \input{_free_triplet.tex} Frees a triplet matrix. +%--------------------------------------- +\subsection{{\tt cholmod\_triplet\_to\_sparse}: sparse matrix copy of a triplet +matrix} +%--------------------------------------- + +\input{_triplet_to_sparse.tex} +Returns a sparse matrix copy of a triplet matrix. If the triplet matrix is +symmetric with just the lower part present ({\tt T->stype} $< 0$), then entries +in the upper part are transposed and placed in the lower part when converting +to a sparse matrix. Similarly, if the triplet matrix is symmetric with just +the upper part present ({\tt T->stype} $> 0$), then entries in the lower part +are transposed and placed in the upper part when converting to a sparse matrix. +Any duplicate entries are summed. + %--------------------------------------- \subsection{{\tt cholmod\_reallocate\_triplet}: reallocate triplet matrix} %--------------------------------------- @@ -2010,20 +2368,6 @@ \subsection{{\tt cholmod\_sparse\_to\_triplet}: triplet matrix copy of a sparse \input{_sparse_to_triplet.tex} Returns a triplet matrix copy of a sparse matrix. -%--------------------------------------- -\subsection{{\tt cholmod\_triplet\_to\_sparse}: sparse matrix copy of a triplet matrix} -%--------------------------------------- - -\input{_triplet_to_sparse.tex} -Returns a sparse matrix copy of a triplet matrix. -If the triplet matrix is symmetric with just the lower part present ({\tt T->stype} $< 0$), -then entries in the upper part are transposed and placed in the lower part when -converting to a sparse matrix. Similarly, -if the triplet matrix is symmetric with just the upper part present ({\tt T->stype} $> 0$), -then entries in the lower part are transposed and placed in the upper part when -converting to a sparse matrix. -Any duplicate entries are summed. - %--------------------------------------- \subsection{{\tt cholmod\_copy\_triplet}: copy triplet matrix} %--------------------------------------- @@ -2048,63 +2392,61 @@ \subsection{{\tt cholmod\_malloc}: allocate memory} %--------------------------------------- \input{_malloc.tex} -Allocates a block of memory of size {\tt n*size}, -using the {\tt SuiteSparse\_config.malloc\_func} -function pointer (default is to use the ANSI C {\tt malloc} routine). -A value of {\tt n=0} is treated as {\tt n=1}. -If not successful, {\tt NULL} is returned and {\tt Common->status} is set to {\tt CHOLMOD\_OUT\_OF\_MEMORY}. +Allocates a block of memory of size {\tt n*size}, using the {\tt +SuiteSparse\_config.malloc\_func} function pointer (default is to use the ANSI +C {\tt malloc} routine). A value of {\tt n=0} is treated as {\tt n=1}. +If not successful, {\tt NULL} is returned and {\tt Common->status} is set to +{\tt CHOLMOD\_OUT\_OF\_MEMORY}. %--------------------------------------- \subsection{{\tt cholmod\_calloc}: allocate and clear memory} %--------------------------------------- \input{_calloc.tex} -Allocates a block of memory of size {\tt n*size}, -using the {\tt SuiteSparse\_config.calloc\_func} -function pointer (default is to use the ANSI C {\tt calloc} routine). -A value of {\tt n=0} is treated as {\tt n=1}. -If not successful, {\tt NULL} is returned and {\tt Common->status} is set to {\tt CHOLMOD\_OUT\_OF\_MEMORY}. +Allocates a block of memory of size {\tt n*size}, using the {\tt +SuiteSparse\_config.calloc\_func} function pointer (default is to use the ANSI +C {\tt calloc} routine). A value of {\tt n=0} is treated as {\tt n=1}. If not +successful, {\tt NULL} is returned and {\tt Common->status} is set to {\tt +CHOLMOD\_OUT\_OF\_MEMORY}. %--------------------------------------- \subsection{{\tt cholmod\_free}: free memory} %--------------------------------------- \input{_free.tex} -Frees a block of memory of size {\tt n*size}, -using the {\tt SuiteSparse\_config.free\_func} -function pointer (default is to use the ANSI C {\tt free} routine). -The size of the block ({\tt n} and {\tt size}) is only required so that CHOLMOD -can keep track of its current and peak memory usage. This is a useful statistic, -and it can also help in tracking down memory leaks. After the call to -{\tt cholmod\_finish}, the count of allocated blocks ({\tt Common->malloc\_count}) -should be zero, and the count of bytes in use ({\tt Common->memory\_inuse}) also -should be zero. If you allocate a block with one size and free it with another, -the {\tt Common->memory\_inuse} count will be wrong, but CHOLMOD will not -have a memory leak. +Frees a block of memory of size {\tt n*size}, using the {\tt +SuiteSparse\_config.free\_func} function pointer (default is to use the ANSI C +{\tt free} routine). The size of the block ({\tt n} and {\tt size}) is only +required so that CHOLMOD can keep track of its current and peak memory usage. +This is a useful statistic, and it can also help in tracking down memory leaks. +After the call to {\tt cholmod\_finish}, the count of allocated blocks ({\tt +Common->malloc\_count}) should be zero, and the count of bytes in use ({\tt +Common->memory\_inuse}) also should be zero. If you allocate a block with one +size and free it with another, the {\tt Common->memory\_inuse} count will be +wrong, but CHOLMOD will not have a memory leak. %--------------------------------------- \subsection{{\tt cholmod\_realloc}: reallocate memory} %--------------------------------------- \input{_realloc.tex} -Reallocates a block of memory whose current size {\tt n*size}, -and whose new size will be {\tt nnew*size} if successful, -using the {\tt SuiteSparse\_config.calloc\_func} -function pointer (default is to use the ANSI C {\tt realloc} routine). -If the reallocation is not successful, {\tt p} is returned unchanged -and {\tt Common->status} is set to {\tt CHOLMOD\_OUT\_OF\_MEMORY}. -The value of {\tt n} is set to {\tt nnew} if successful, or left -unchanged otherwise. -A value of {\tt nnew=0} is treated as {\tt nnew=1}. +Reallocates a block of memory whose current size {\tt n*size}, and whose new +size will be {\tt nnew*size} if successful, using the {\tt +SuiteSparse\_config.calloc\_func} function pointer (default is to use the ANSI +C {\tt realloc} routine). If the reallocation is not successful, {\tt p} is +returned unchanged and {\tt Common->status} is set to {\tt +CHOLMOD\_OUT\_OF\_MEMORY}. The value of {\tt n} is set to {\tt nnew} if +successful, or left unchanged otherwise. A value of {\tt nnew=0} is treated as +{\tt nnew=1}. %--------------------------------------- \subsection{{\tt cholmod\_realloc\_multiple}: reallocate memory} %--------------------------------------- \input{_realloc_multiple.tex} -Reallocates multiple blocks of memory, all with the same number of items -(but with different item sizes). Either all reallocations succeed, -or all are returned to their original size. +Reallocates multiple blocks of memory, all with the same number of items (but +with different item sizes). Either all reallocations succeed, or all are +returned to their original size. %------------------------------------------------------------------------------- \newpage \section{{\tt Utility} Module: version control} @@ -2130,13 +2472,7 @@ \subsection{{\tt cholmod\_version}: return current CHOLMOD version} Note that {\tt cholmod\_version} and {\tt cholmod\_l\_version} have identical prototypes. Both use {\tt int}'s. Unlike all other CHOLMOD functions, this -function does not take the {\tt Common} object as an input parameter, and it -does not use any definitions from any include files. Thus, the caller can -access this function even if the caller does not include any CHOLMOD include -files. - -The above code fragment does require the {\tt \#include "cholmod.h"}, -of course, but {\tt cholmod\_version} can be called without it, if necessary. +function does not take the {\tt Common} object as an input parameter. %------------------------------------------------------------------------------- \newpage \section{{\tt Check} Module routines} @@ -2144,15 +2480,17 @@ \subsection{{\tt cholmod\_version}: return current CHOLMOD version} No CHOLMOD routines print anything, except for the {\tt cholmod\_print\_*} routines in the {\tt Check} Module, and the {\tt cholmod\_error} routine. The -{\tt SuiteSparse\_config.printf\_function} is a pointer to {\tt printf} by default; -you can redirect the output of CHOLMOD by redefining this pointer. -If the function pointer is {\tt NULL}, CHOLMOD does not print anything. +{\tt SuiteSparse\_config.printf\_function} is a pointer to {\tt printf} by +default; you can redirect the output of CHOLMOD by redefining this pointer. If +the function pointer is {\tt NULL}, CHOLMOD does not print anything. + +The {\tt Common->print} parameter determines how much detail is printed. Each +value of {\tt Common->print} listed below also prints the items listed for +smaller values of {\tt Common->print}: -The {\tt Common->print} parameter determines how much detail is printed. -Each value of {\tt Common->print} listed below also prints the items listed -for smaller values of {\tt Common->print}: \begin{itemize} -\item 0: print nothing; check the data structures and return {\tt TRUE} or {\tt FALSE}. +\item 0: print nothing; check the data structures and return {\tt TRUE} or {\tt +FALSE}. \item 1: print error messages. \item 2: print warning messages. \item 3: print a one-line summary of the object. @@ -2280,14 +2618,13 @@ \subsection{{\tt cholmod\_read\_triplet}: read triplet matrix from file} %--------------------------------------- \input{_read_triplet.tex} -Read a sparse matrix in triplet form, using the the {\tt coord} -Matrix Market format (http://www.nist.gov/MatrixMarket). -Skew-symmetric and complex symmetric matrices are returned with -both upper and lower triangular parts present (an stype of zero). -Real symmetric and complex Hermitian matrices are returned with just -their upper or lower triangular part, depending on their stype. -The Matrix Market {\tt array} data type for dense matrices is not supported -(use {\tt cholmod\_read\_dense} for that case). +Read a sparse matrix in triplet form, using the the {\tt coord} Matrix Market +format (http://www.nist.gov/MatrixMarket). Skew-symmetric and complex +symmetric matrices are returned with both upper and lower triangular parts +present (an stype of zero). Real symmetric and complex Hermitian matrices are +returned with just their upper or lower triangular part, depending on their +stype. The Matrix Market {\tt array} data type for dense matrices is not +supported (use {\tt cholmod\_read\_dense} for that case). If the first line of the file starts with {\tt \%\%MatrixMarket}, then it is interpreted as a file in Matrix Market format. The header line is optional. @@ -2298,121 +2635,160 @@ \subsection{{\tt cholmod\_read\_triplet}: read triplet matrix from file} \vspace{0.1in} \noindent -where {\em type} is one of: {\tt real}, {\tt complex}, {\tt pattern}, -or {\tt integer}, and {\em storage} is one of: {\tt general}, {\tt hermitian}, -{\tt symmetric}, or {\tt skew-symmetric}. -In CHOLMOD, these roughly correspond to the {\tt xtype} -(pattern, real, complex, or zomplex) and {\tt stype} -(unsymmetric, symmetric/upper, and symmetric/lower). -The strings are case-insensitive. Only the first character (or the -first two for skew-symmetric) is significant. -The {\tt coord} token can be replaced with {\tt array} in the Matrix Market format, but -this format not supported by {\tt cholmod\_read\_triplet}. -The {\tt integer} type is converted to real. -The {\em type} is ignored; the actual type (real, complex, or pattern) is -inferred from the number of tokens in each line of the file (2: pattern, -3: real, 4: complex). This is compatible with the Matrix Market format. - -A storage of {\tt general} implies an stype of zero -(see below). A storage of {\tt symmetric} and {\tt hermitian} imply an stype of -1. -Skew-symmetric and complex symmetric matrices are returned with an stype of 0. -Blank lines, any other lines starting with ``{\tt \%}'' are treated as comments, and are ignored. +where {\em type} is one of: {\tt real}, {\tt complex}, {\tt pattern}, or {\tt +integer}, and {\em storage} is one of: {\tt general}, {\tt hermitian}, {\tt +symmetric}, or {\tt skew-symmetric}. In CHOLMOD, these roughly correspond to +the {\tt xtype} (pattern, real, complex, or zomplex) and {\tt stype} +(unsymmetric, symmetric/upper, and symmetric/lower). The strings are +case-insensitive. Only the first character (or the first two for +skew-symmetric) is significant. The {\tt coord} token can be replaced with +{\tt array} in the Matrix Market format, but this format not supported by {\tt +cholmod\_read\_triplet}. The {\tt integer} type is converted to real. The +{\em type} is ignored; the actual type (real, complex, or pattern) is inferred +from the number of tokens in each line of the file (2: pattern, 3: real, 4: +complex). This is compatible with the Matrix Market format. + +The matrix is read in {\tt double} precision. To read a matrix +in either double or single precision ({\tt double} or {\tt float}), +use \verb'cholmod_read_triplet2'. + +A storage of {\tt general} implies an stype of zero (see below). A storage of +{\tt symmetric} and {\tt hermitian} imply an stype of -1. Skew-symmetric and +complex symmetric matrices are returned with an stype of 0. Blank lines, any +other lines starting with ``{\tt \%}'' are treated as comments, and are +ignored. The first non-comment line contains 3 or 4 integers: \vspace{0.1in} - {\em nrow ncol nnz stype} + {\em nrow ncol nnz stype} \vspace{0.1in} \noindent -where {\em stype} is optional (stype does not appear in the Matrix Market format). -The matrix is {\em nrow}-by-{\em ncol}. The following {\em nnz} lines (excluding comments) -each contain a single entry. Duplicates are permitted, and are summed in -the output matrix. +where {\em stype} is optional (stype does not appear in the Matrix Market +format). The matrix is {\em nrow}-by-{\em ncol}. The following {\em nnz} +lines (excluding comments) each contain a single entry. Duplicates are +permitted, and are summed in the output matrix. If stype is present, it denotes the storage format for the matrix. \begin{itemize} \item stype = 0 denotes an unsymmetric matrix (same as Matrix Market {\tt general}). -\item stype = -1 denotes a symmetric or Hermitian matrix whose lower triangular - entries are stored. Entries may be present in the upper triangular - part, but these are ignored (same as Matrix Market {\tt symmetric} - for the real case, {\tt hermitian} for the complex case). -\item stype = 1 denotes a symmetric or Hermitian matrix whose upper triangular - entries are stored. Entries may be present in the lower triangular - part, but these are ignored. This format is not available in the Matrix - Market format. +\item stype = -1 denotes a symmetric or Hermitian matrix whose lower triangular + entries are stored. Entries may be present in the upper triangular + part, but these are ignored (same as Matrix Market {\tt symmetric} + for the real case, {\tt hermitian} for the complex case). +\item stype = 1 denotes a symmetric or Hermitian matrix whose upper triangular + entries are stored. Entries may be present in the lower triangular + part, but these are ignored. This format is not available in the Matrix + Market format. \end{itemize} -If neither the stype nor the Matrix Market header are present, then -the stype is inferred from the rest of the data. If the matrix is -rectangular, or has -entries in both the upper and lower triangular parts, then it is assumed to -be unsymmetric (stype=0). If only entries in the lower triangular part are +If neither the stype nor the Matrix Market header are present, then the stype +is inferred from the rest of the data. If the matrix is rectangular, or has +entries in both the upper and lower triangular parts, then it is assumed to be +unsymmetric (stype=0). If only entries in the lower triangular part are present, the matrix is assumed to have stype = -1. If only entries in the upper triangular part are present, the matrix is assumed to have stype = 1. -Each nonzero consists of one line with 2, 3, or 4 entries. All lines must -have the same number of entries. The first two entries are the row and -column indices of the nonzero. If 3 entries are present, the 3rd entry is -the numerical value, and the matrix is real. If 4 entries are present, -the 3rd and 4th entries in the line are the real and imaginary parts of -a complex value. +Each nonzero consists of one line with 2, 3, or 4 entries. All lines must have +the same number of entries. The first two entries are the row and column +indices of the nonzero. If 3 entries are present, the 3rd entry is the +numerical value, and the matrix is real. If 4 entries are present, the 3rd and +4th entries in the line are the real and imaginary parts of a complex value. The matrix can be either 0-based or 1-based. It is first assumed to be -one-based (compatible with Matrix Market), with row indices in the range -1 to ncol and column indices in the range 1 to nrow. If a row or column -index of zero is found, the matrix is assumed to be zero-based (with row -indices in the range 0 to ncol-1 and column indices in the range 0 to -nrow-1). This test correctly determines that all Matrix Market -matrices are in 1-based form. +one-based (compatible with Matrix Market), with row indices in the range 1 to +ncol and column indices in the range 1 to nrow. If a row or column index of +zero is found, the matrix is assumed to be zero-based (with row indices in the +range 0 to ncol-1 and column indices in the range 0 to nrow-1). This test +correctly determines that all Matrix Market matrices are in 1-based form. For symmetric pattern-only matrices, the kth diagonal (if present) is set to one plus the degree of the row k or column k (whichever is larger), and the -off-diagonals are set to -1. A symmetric pattern-only matrix with a -zero-free diagonal is thus converted into a symmetric positive definite -matrix. All entries are set to one for an unsymmetric pattern-only matrix. -This differs from the MatrixMarket format ({\tt A = mmread ('file')} returns -a binary pattern for A for symmetric pattern-only matrices). -To return a binary format for all pattern-only matrices, use -{\tt A = mread('file',1)}. +off-diagonals are set to -1. A symmetric pattern-only matrix with a zero-free +diagonal is thus converted into a symmetric positive definite matrix. All +entries are set to one for an unsymmetric pattern-only matrix. This differs +from the MatrixMarket format ({\tt A = mmread ('file')} returns a binary +pattern for A for symmetric pattern-only matrices). To return a binary format +for all pattern-only matrices, use {\tt A = mread('file',1)}. + +Example matrices that follow this format can be found in the {\tt +CHOLMOD/Demo/Matrix} and \newline {\tt CHOLMOD/Tcov/Matrix} directories. You +can also try any of the matrices in the Matrix Market collection at +http://www.nist.gov/MatrixMarket. + +%--------------------------------------- +\subsection{{\tt cholmod\_read\_triplet2}: read triplet matrix from file} +%--------------------------------------- -Example matrices that follow this format can be found in the -{\tt CHOLMOD/Demo/Matrix} and \newline -{\tt CHOLMOD/Tcov/Matrix} directories. -You can also try any of the matrices in the Matrix Market collection -at http://www.nist.gov/MatrixMarket. +\input{_read_triplet2.tex} +Identical to \verb'cholmod_read_triplet', except that the dtype can be +specified (\verb'CHOLMOD_DOUBLE' or \verb'CHOLMOD_SINGLE'). %--------------------------------------- \subsection{{\tt cholmod\_read\_sparse}: read sparse matrix from file} %--------------------------------------- \input{_read_sparse.tex} -Read a sparse matrix in triplet form from a file (using {\tt cholmod\_read\_triplet}) -and convert to a CHOLMOD sparse matrix. -The Matrix Market format is used. -If {\tt Common->prefer\_upper} is {\tt TRUE} (the default case), a symmetric matrix is -returned stored in upper-triangular form ({\tt A->stype} is 1). -Otherwise, it is left in its original form, either upper or lower. +Read a sparse matrix in triplet form from a file (using {\tt +cholmod\_read\_triplet}) and convert to a CHOLMOD sparse matrix. The Matrix +Market format is used. If {\tt Common->prefer\_upper} is {\tt TRUE} (the +default case), a symmetric matrix is returned stored in upper-triangular form +({\tt A->stype} is 1). Otherwise, it is left in its original form, either +upper or lower. +% +The matrix is read in {\tt double} precision. To read a matrix +in either double or single precision ({\tt double} or {\tt float}), +use \verb'cholmod_read_sparse2'. + +%--------------------------------------- +\subsection{{\tt cholmod\_read\_sparse2}: read sparse matrix from file} +%--------------------------------------- + +\input{_read_sparse2.tex} +Identical to \verb'cholmod_read_sparse', except that the dtype can be +specified (\verb'CHOLMOD_DOUBLE' or \verb'CHOLMOD_SINGLE'). %--------------------------------------- \subsection{{\tt cholmod\_read\_dense}: read dense matrix from file} %--------------------------------------- \input{_read_dense.tex} -Read a dense matrix from a file, using the the {\tt array} -Matrix Market format +Read a dense matrix from a file, using the {\tt array} Matrix Market format \newline (http://www.nist.gov/MatrixMarket). +% +The matrix is read in {\tt double} precision. To read a matrix +in either double or single precision ({\tt double} or {\tt float}), +use \verb'cholmod_read_dense2'. + +%--------------------------------------- +\subsection{{\tt cholmod\_read\_dense2}: read dense matrix from file} +%--------------------------------------- + +\input{_read_dense2.tex} +Identical to \verb'cholmod_read_dense', except that the dtype can be +specified (\verb'CHOLMOD_DOUBLE' or \verb'CHOLMOD_SINGLE'). %--------------------------------------- \subsection{{\tt cholmod\_read\_matrix}: read a matrix from file} %--------------------------------------- \input{_read_matrix.tex} -Read a sparse or dense matrix from a file, in Matrix Market format. -Returns a {\tt void} pointer to either a -{\tt cholmod\_triplet}, -{\tt cholmod\_sparse}, or -{\tt cholmod\_dense} object. +Read a sparse or dense matrix from a file, in Matrix Market format. Returns a +{\tt void} pointer to either a {\tt cholmod\_triplet}, {\tt cholmod\_sparse}, +or {\tt cholmod\_dense} object. +% +The matrix is read in {\tt double} precision. To read a matrix +in either double or single precision ({\tt double} or {\tt float}), +use \verb'cholmod_read_matrix2'. + +%--------------------------------------- +\subsection{{\tt cholmod\_read\_matrix2}: read a matrix from file} +%--------------------------------------- + +\input{_read_matrix2.tex} +Identical to \verb'cholmod_read_matrix', except that the dtype can be +specified (\verb'CHOLMOD_DOUBLE' or \verb'CHOLMOD_SINGLE'). %--------------------------------------- \subsection{{\tt cholmod\_write\_sparse}: write a sparse matrix to a file} @@ -2424,16 +2800,14 @@ \subsection{{\tt cholmod\_write\_sparse}: write a sparse matrix to a file} matrix. If not NULL, the {\tt Z} matrix must have the same dimensions and stype as {\tt A}. -Returns the symmetry in which the matrix was printed -(1 to 7) or -1 on failure. See the {\tt cholmod\_symmetry} function for -a description of the return codes. +Returns the symmetry in which the matrix was printed (1 to 7) or -1 on failure. +See the {\tt cholmod\_symmetry} function for a description of the return codes. -If {\tt A} and {\tt Z} are sorted on input, and either unsymmetric (stype = 0) or -symmetric-lower (stype < 0), and if {\tt A} and {\tt Z} do not overlap, -then the triplets -are sorted, first by column and then by row index within each column, with -no duplicate entries. If all the above holds except stype > 0, then the -triplets are sorted by row first and then column. +If {\tt A} and {\tt Z} are sorted on input, and either unsymmetric (stype = 0) +or symmetric-lower (stype $< 0$), and if {\tt A} and {\tt Z} do not overlap, +then the triplets are sorted, first by column and then by row index within each +column, with no duplicate entries. If all the above holds except stype $> 0$, +then the triplets are sorted by row first and then column. %--------------------------------------- \subsection{{\tt cholmod\_write\_dense}: write a dense matrix to a file} @@ -2441,10 +2815,9 @@ \subsection{{\tt cholmod\_write\_dense}: write a dense matrix to a file} \input{_write_dense.tex} Write a dense matrix to a file in Matrix Market format. Optionally include -comments. Returns > 0 if successful, -1 otherwise (1 if rectangular, 2 if -square). -A dense matrix is written in "general" format; symmetric formats in the -Matrix Market standard are not exploited. +comments. Returns $> 0$ if successful, -1 otherwise (1 if rectangular, 2 if +square). A dense matrix is written in "general" format; symmetric formats in +the Matrix Market standard are not exploited. %------------------------------------------------------------------------------- \newpage \section{{\tt Cholesky} Module routines} @@ -2459,60 +2832,60 @@ \subsection{{\tt cholmod\_analyze}: symbolic factorization} for numerical factorization via {\tt cholmod\_factorize} or via the ``expert'' routines {\tt cholmod\_rowfac} and {\tt cholmod\_super\_numeric}. -In the symmetric case, {\tt A} or {\tt A(p,p)} is analyzed, -where {\tt p} is the fill-reducing ordering. -In the unsymmetric case, {\tt A*A'} or {\tt A(p,:)*A(p,:)'} is analyzed. -The {\tt cholmod\_analyze\_p} routine can be given a user-provided permutation {\tt p} -(see below). - -The default ordering strategy is to first try AMD. -The ordering quality is analyzed, and if AMD obtains an ordering where -{\tt nnz(L)} is greater than or equal to {\tt 5*nnz(tril(A))} -(or {\tt 5*nnz(tril(A*A'))} if {\tt A} is unsymmetric) and -the floating-point operation count for the subsequent factorization is -greater than or equal to {\tt 500*nnz(L)}, then METIS is tried (if installed). -For {\tt cholmod\_analyze\_p}, the user-provided ordering is also tried. -This default behavior is obtained when {\tt Common->nmethods} is zero. -In this case, methods 0, 1, and 2 in {\tt Common->method[...]} are reset -to user-provided, AMD, and METIS, respectively. -The ordering with the smallest {\tt nnz(L)} is kept. - -If {\tt Common->default\_nesdis} is true (nonzero), then CHOLMOD's -nested dissection (NESDIS) is used for the default strategy described -above, in place of METIS. +In the symmetric case, {\tt A} or {\tt A(p,p)} is analyzed, where {\tt p} is +the fill-reducing ordering. In the unsymmetric case, {\tt A*A'} or {\tt +A(p,:)*A(p,:)'} is analyzed. The {\tt cholmod\_analyze\_p} routine can be +given a user-provided permutation {\tt p} (see below). + +The default ordering strategy is to first try AMD. The ordering quality is +analyzed, and if AMD obtains an ordering where {\tt nnz(L)} is greater than or +equal to {\tt 5*nnz(tril(A))} (or {\tt 5*nnz(tril(A*A'))} if {\tt A} is +unsymmetric) and the floating-point operation count for the subsequent +factorization is greater than or equal to {\tt 500*nnz(L)}, then METIS is tried +(if installed). For {\tt cholmod\_analyze\_p}, the user-provided ordering is +also tried. This default behavior is obtained when {\tt Common->nmethods} is +zero. In this case, methods 0, 1, and 2 in {\tt Common->method[...]} are reset +to user-provided, AMD, and METIS, respectively. The ordering with the smallest +{\tt nnz(L)} is kept. + +If {\tt Common->default\_nesdis} is true (nonzero), then CHOLMOD's nested +dissection (NESDIS) is used for the default strategy described above, in place +of METIS. Other ordering options can be requested. These include: \begin{enumerate} -\item natural: A is not permuted to reduce fill-in. -\item user-provided: a permutation can be provided to {\tt cholmod\_analyze\_p}. -\item AMD: approximate minimum degree (AMD for the symmetric case, COLAMD for the {\tt A*A'} case). -\item METIS: nested dissection with {\tt METIS\_NodeND} -\item {\tt NESDIS}: CHOLMOD's nested dissection using - {\tt METIS\_NodeComputeSeparator}, - followed by a constrained minimum degree +\item natural: A is not permuted to reduce fill-in. +\item user-provided: a permutation can be provided to {\tt + cholmod\_analyze\_p}. +\item AMD: approximate minimum degree (AMD for the symmetric case, + COLAMD for the {\tt A*A'} case). +\item METIS: nested dissection with {\tt METIS\_NodeND} +\item {\tt NESDIS}: CHOLMOD's nested dissection using + {\tt METIS\_NodeComputeSeparator}, followed by a constrained minimum degree (CAMD or CSYMAMD for the symmetric case, CCOLAMD for the {\tt A*A'} case). - This is typically slower than METIS, but typically provides better orderings. + This is typically slower than METIS, but typically provides better + orderings. \end{enumerate} -Multiple ordering options can be tried (up to 9 of them), and the best one -is selected (the one that gives the smallest number of nonzeros in the -simplicial factor L). If one method fails, {\tt cholmod\_analyze} keeps going, and -picks the best among the methods that succeeded. This routine fails (and -returns {\tt NULL}) if either the initial memory allocation fails, all ordering methods -fail, or the supernodal analysis (if requested) fails. Change {\tt Common->nmethods} to the -number of methods you wish to try. By default, the 9 methods available are: +Multiple ordering options can be tried (up to 9 of them), and the best one is +selected (the one that gives the smallest number of nonzeros in the simplicial +factor L). If one method fails, {\tt cholmod\_analyze} keeps going, and picks +the best among the methods that succeeded. This routine fails (and returns +{\tt NULL}) if either the initial memory allocation fails, all ordering methods +fail, or the supernodal analysis (if requested) fails. Change {\tt +Common->nmethods} to the number of methods you wish to try. By default, the 9 +methods available are: \begin{enumerate} \item user-provided permutation (only for {\tt cholmod\_analyze\_p}). \item AMD with default parameters. \item METIS with default parameters. \item {\tt NESDIS} with default parameters: stopping the partitioning when - the graph is of size {\tt nd\_small} = 200 or less, remove nodes with - more than {\tt max (16, prune\_dense * sqrt (n))} nodes where - {\tt prune\_dense} = 10, and follow partitioning with - constrained minimum degree ordering - (CAMD for the symmetric case, - CCOLAMD for the unsymmetric case). + the graph is of size {\tt nd\_small} = 200 or less, remove nodes + with more than {\tt max (16, prune\_dense * sqrt (n))} nodes where + {\tt prune\_dense} = 10, and follow partitioning with constrained + minimum degree ordering (CAMD for the symmetric case, CCOLAMD for + the unsymmetric case). \item natural ordering (with weighted postorder). \item NESDIS, {\tt nd\_small} = 20000, {\tt prune\_dense} = 10. \item NESDIS, {\tt nd\_small} = 4, {\tt prune\_dense} = 10, @@ -2522,24 +2895,24 @@ \subsection{{\tt cholmod\_analyze}: symbolic factorization} \end{enumerate} You can modify these 9 methods and the number of methods tried by changing -parameters in the {\tt Common} argument. If you know the best ordering for your -matrix, set {\tt Common->nmethods} to 1 and set {\tt Common->method[0].ordering} to the -requested ordering method. Parameters for each method can also be modified -(refer to the description of {\tt cholmod\_common} for details). +parameters in the {\tt Common} argument. If you know the best ordering for +your matrix, set {\tt Common->nmethods} to 1 and set {\tt +Common->method[0].ordering} to the requested ordering method. Parameters for +each method can also be modified (refer to the description of {\tt +cholmod\_common} for details). -Note that it is possible for METIS to terminate your program if it runs out -of memory. This is not the case for any CHOLMOD or minimum degree ordering -routine (AMD, COLAMD, CAMD, CCOLAMD, or CSYMAMD). -Since {\tt NESDIS} relies on METIS, it too can terminate your program. +Note that it is possible for METIS to terminate your program if it runs out of +memory. This is not the case for any CHOLMOD or minimum degree ordering +routine (AMD, COLAMD, CAMD, CCOLAMD, or CSYMAMD). Since {\tt NESDIS} relies on +METIS, it too can terminate your program. The selected ordering is followed by a weighted postorder of the elimination -tree by default (see {\tt cholmod\_postorder} for details), -unless {\tt Common->postorder} is set to {\tt FALSE}. -The postorder does not change the number of nonzeros in $\m{L}$ or -the floating-point operation count. It does improve performance, -particularly for the supernodal factorization. -If you truly want the natural ordering with no postordering, -you must set {\tt Common->postorder} to {\tt FALSE}. +tree by default (see {\tt cholmod\_postorder} for details), unless {\tt +Common->postorder} is set to {\tt FALSE}. The postorder does not change the +number of nonzeros in $\m{L}$ or the floating-point operation count. It does +improve performance, particularly for the supernodal factorization. If you +truly want the natural ordering with no postordering, you must set {\tt +Common->postorder} to {\tt FALSE}. The factor {\tt L} is returned as simplicial symbolic if {\tt Common->supernodal} is {\tt CHOLMOD\_SIMPLICIAL} (zero) or as supernodal @@ -2592,48 +2965,56 @@ \subsection{{\tt cholmod\_factorize}: numeric factorization} $\m{LDL}\tr$ factorization). Once the factorization is complete, it can be left as is or optionally -converted into any simplicial numeric type, depending on the -{\tt Common->final\_*} parameters. If converted from a supernodal to simplicial -type, and {\tt Common->final\_resymbol} is {\tt TRUE}, then numerically -zero entries in {\tt L} due to relaxed supernodal amalgamation are removed from -the simplicial factor (they are always left in the supernodal form of {\tt L}). +converted into any simplicial numeric type, depending on the {\tt +Common->final\_*} parameters. If converted from a supernodal to simplicial +type, and {\tt Common->final\_resymbol} is {\tt TRUE}, then numerically zero +entries in {\tt L} due to relaxed supernodal amalgamation are removed from the +simplicial factor (they are always left in the supernodal form of {\tt L}). Entries that are numerically zero but present in the simplicial symbolic pattern of {\tt L} are left in place (the graph of {\tt L} remains chordal). This is required for the update/downdate/rowadd/rowdel routines to work properly. -If the matrix is not positive definite the routine returns {\tt TRUE}, but -{\tt Common->status} is set to {\tt CHOLMOD\_NOT\_POSDEF} and {\tt L->minor} is set to the -column at which the failure occurred. Columns {\tt L->minor} to {\tt L->n-1} -are set to zero. +If the matrix is not positive definite the routine returns {\tt TRUE}, but {\tt +Common->status} is set to {\tt CHOLMOD\_NOT\_POSDEF} and {\tt L->minor} is set +to the column at which the failure occurred. Columns {\tt L->minor} to {\tt +L->n-1} are set to zero. -Supports any xtype (pattern, real, complex, or zomplex), except that the -input matrix {\tt A} cannot be pattern-only. If {\tt L} is simplicial, its numeric -xtype matches {\tt A} on output. If {\tt L} is supernodal, its xtype is real if {\tt A} is -real, or complex if {\tt A} is complex or zomplex. CHOLMOD does not provide -a supernodal zomplex factor, since it is incompatible with how complex numbers are -stored in LAPACK and the BLAS. +Supports any xtype (pattern, real, complex, or zomplex), except that the input +matrix {\tt A} cannot be pattern-only and any dtype (double or single). If +{\tt L} is simplicial, its numeric xtype matches {\tt A} on output. If {\tt L} +is supernodal, its xtype is real if {\tt A} is real, or complex if {\tt A} is +complex or zomplex. CHOLMOD does not provide a supernodal zomplex factor, +since it is incompatible with how complex numbers are stored in LAPACK and the +BLAS. + +If the \verb'L' factor on input is a purely symbolic factorizatin (with +\verb'L->xtype' of \verb'CHOLMOD_PATTERN', then it is converted to a numeric +factorization with same dtype as A. Otherwise, the dtypes of L and A must +match. %--------------------------------------- -\subsection{{\tt cholmod\_analyze\_p}: symbolic factorization, given permutation} +\subsection{{\tt cholmod\_analyze\_p}: symbolic factorization, given +permutation} %--------------------------------------- \input{_analyze_p.tex} -Identical to {\tt cholmod\_analyze}, except that a user-provided -permutation {\tt p} can be provided, and the set {\tt f} for the unsymmetric case -can be provided. The matrices {\tt A(:,f)*A(:,f)'} or {\tt A(p,f)*A(p,f)'} -can be analyzed in the the unsymmetric case. +Identical to {\tt cholmod\_analyze}, except that a user-provided permutation +{\tt p} can be provided, and the set {\tt f} for the unsymmetric case can be +provided. The matrices {\tt A(:,f)*A(:,f)'} or {\tt A(p,f)*A(p,f)'} can be +analyzed in the the unsymmetric case. %--------------------------------------- -\subsection{{\tt cholmod\_factorize\_p}: numeric factorization, given permutation} +\subsection{{\tt cholmod\_factorize\_p}: numeric factorization, given +permutation} %--------------------------------------- \input{_factorize_p.tex} -Identical to {\tt cholmod\_factorize}, but with additional options. -The set {\tt f} can be provided for the unsymmetric case; -{\tt A(p,f)*A(p,f)'} is factorized. The term {\tt beta*I} can be added to -the matrix before it is factorized, where {\tt beta} is real. -Only the real part, {\tt beta[0]}, is used. +Identical to {\tt cholmod\_factorize}, but with additional options. The set +{\tt f} can be provided for the unsymmetric case; {\tt A(p,f)*A(p,f)'} is +factorized. The term {\tt beta*I} can be added to the matrix before it is +factorized, where {\tt beta} is real. Only the real part, {\tt beta[0]}, is +used. %--------------------------------------- \subsection{{\tt cholmod\_solve}: solve a linear system} @@ -2643,36 +3024,39 @@ \subsection{{\tt cholmod\_solve}: solve a linear system} Returns a solution {\tt X} that solves one of the following systems: \begin{tabular}{ll|ll} - \hline - system & {\tt sys} parameter & system & {\tt sys} parameter \\ - $\m{Ax}=\m{b}$ & 0: {\tt CHOLMOD\_A} & & \\ - $\m{LDL}\tr\m{x}=\m{b}$ & 1: {\tt CHOLMOD\_LDLt} & $\m{L}\tr\m{x}=\m{b}$ & 5: {\tt CHOLMOD\_Lt} \\ - $\m{LDx}=\m{b}$ & 2: {\tt CHOLMOD\_LD} & $\m{Dx}=\m{b}$ & 6: {\tt CHOLMOD\_D} \\ - $\m{DL}\tr\m{x}=\m{b}$ & 3: {\tt CHOLMOD\_DLt} & $\m{x}=\m{Pb}$ & 7: {\tt CHOLMOD\_P} \\ - $\m{Lx}=\m{b}$ & 4: {\tt CHOLMOD\_L} & $\m{x}=\m{P}\tr\m{b}$ & 8: {\tt CHOLMOD\_Pt} \\ - \hline +\hline +system & {\tt sys} parameter & system & {\tt sys} parameter \\ +$\m{Ax}=\m{b}$ & 0: {\tt CHOLMOD\_A} & & \\ +$\m{LDL}\tr\m{x}=\m{b}$ & 1: {\tt CHOLMOD\_LDLt} & $\m{L}\tr\m{x}=\m{b}$ & 5: {\tt CHOLMOD\_Lt} \\ +$\m{LDx}=\m{b}$ & 2: {\tt CHOLMOD\_LD} & $\m{Dx}=\m{b}$ & 6: {\tt CHOLMOD\_D} \\ +$\m{DL}\tr\m{x}=\m{b}$ & 3: {\tt CHOLMOD\_DLt} & $\m{x}=\m{Pb}$ & 7: {\tt CHOLMOD\_P} \\ +$\m{Lx}=\m{b}$ & 4: {\tt CHOLMOD\_L} & $\m{x}=\m{P}\tr\m{b}$ & 8: {\tt CHOLMOD\_Pt} \\ +\hline \end{tabular} -The factorization can be simplicial $\m{LDL}\tr$, simplicial $\m{LL}\tr$, or supernodal $\m{LL}\tr$. -For an $\m{LL}\tr$ factorization, $\m{D}$ is the identity matrix. Thus {\tt CHOLMOD\_LD} and -{\tt CHOLMOD\_L} solve the same system if an $\m{LL}\tr$ factorization was performed, -for example. -This is one of the few routines in CHOLMOD for which the xtype of the input -arguments need not match. -If both {\tt L} and {\tt B} are real, then {\tt X} is returned real. If either is complex -or zomplex, {\tt X} is returned as either complex or zomplex, depending on the -{\tt Common->prefer\_zomplex} parameter (default is complex). - -This routine does not check to see if the diagonal of $\m{L}$ or $\m{D}$ is zero, -because sometimes a partial solve can be done with an indefinite or singular -matrix. If you wish to check in your own code, test {\tt L->minor}. If -{\tt L->minor == L->n}, then the matrix has no zero diagonal entries. -If {\tt k = L->minor < L->n}, then {\tt L(k,k)} is zero for an $\m{LL}\tr$ factorization, or -{\tt D(k,k)} is zero for an $\m{LDL}\tr$ factorization. +The factorization can be simplicial $\m{LDL}\tr$, simplicial $\m{LL}\tr$, or +supernodal $\m{LL}\tr$. For an $\m{LL}\tr$ factorization, $\m{D}$ is the +identity matrix. Thus {\tt CHOLMOD\_LD} and {\tt CHOLMOD\_L} solve the same +system if an $\m{LL}\tr$ factorization was performed, for example. This is one +of the few routines in CHOLMOD for which the xtype of the input arguments need +not match. If both {\tt L} and {\tt B} are real, then {\tt X} is returned +real. If either is complex or zomplex, {\tt X} is returned as either complex +or zomplex, depending on the {\tt Common->prefer\_zomplex} parameter (default +is complex). + +This routine does not check to see if the diagonal of $\m{L}$ or $\m{D}$ is +zero, because sometimes a partial solve can be done with an indefinite or +singular matrix. If you wish to check in your own code, test {\tt L->minor}. +If {\tt L->minor == L->n}, then the matrix has no zero diagonal entries. If +{\tt k = L->minor < L->n}, then {\tt L(k,k)} is zero for an $\m{LL}\tr$ +factorization, or {\tt D(k,k)} is zero for an $\m{LDL}\tr$ factorization. Iterative refinement is not performed, but this can be easily done with the {\tt MatrixOps} Module. See {\tt Demo/cholmod\_demo.c} for an example. +The dtypes of \verb'L' and \verb'B' must match, and \verb'X' is returned +with the same dtype. + %--------------------------------------- \subsection{{\tt cholmod\_spsolve}: solve a linear system} %--------------------------------------- @@ -2692,33 +3076,20 @@ \subsection{{\tt cholmod\_solve2}: solve a linear system, reusing workspace} Solve a linear system, optionally reusing workspace from a prior call to {\tt cholmod\_solve2}. -The inputs to this function are the same as {\tt cholmod\_solve}, -with the addition of three parameters: -{\tt X}, -{\tt Y}, -and -{\tt E}. The dense matrix {\tt X} is the solution on output. -On input, {\tt \&X} can point to a NULL matrix, or be the wrong size. -If that is the case, it is freed and allocated to be the proper size. -If {\tt X} has the right size and type on input, then the allocation -is skipped. In contrast, the {\tt cholmod\_solve} function always -allocates its output {\tt X}. This {\tt cholmod\_solve2} function -allows you to reuse the memory space of a prior {\tt X}, thereby -saving time. - -The two workspace matrices {\tt Y} and {\tt E} can also be reused -between calls. -You must free -{\tt X} -{\tt Y}, -and -{\tt E} yourself, when your computations are done. Below is an -example of usage. -Note that -{\tt X} -{\tt Y}, -and -{\tt E} must be defined on input (either NULL, or valid dense matrices). +The inputs to this function are the same as {\tt cholmod\_solve}, with the +addition of three parameters: {\tt X}, {\tt Y}, and {\tt E}. The dense matrix +{\tt X} is the solution on output. On input, {\tt \&X} can point to a NULL +matrix, or be the wrong size. If that is the case, it is freed and allocated +to be the proper size. If {\tt X} has the right size and type on input, then +the allocation is skipped. In contrast, the {\tt cholmod\_solve} function +always allocates its output {\tt X}. This {\tt cholmod\_solve2} function +allows you to reuse the memory space of a prior {\tt X}, thereby saving time. + +The two workspace matrices {\tt Y} and {\tt E} can also be reused between +calls. You must free {\tt X} {\tt Y}, and {\tt E} yourself, when your +computations are done. Below is an example of usage. Note that {\tt X} {\tt +Y}, and {\tt E} must be defined on input (either NULL, or valid dense +matrices). \begin{verbatim} cholmod_dense *X = NULL, *Y = NULL, *E = NULL ; @@ -2744,9 +3115,9 @@ \subsection{{\tt cholmod\_solve2}: solve a linear system, reusing workspace} cholmod_l_free_dense (&X, Common) ; \end{verbatim} -Both methods work fine, but in the second method with {\tt cholmod\_solve}, -the internal workspaces ({\tt Y} and {\tt E}) and the solution ({\tt X}) -are allocated and freed on each call. +Both methods work fine, but in the second method with {\tt cholmod\_solve}, the +internal workspaces ({\tt Y} and {\tt E}) and the solution ({\tt X}) are +allocated and freed on each call. The {\tt cholmod\_solve2 function} can also solve for a subset of the solution vector {\tt X}, if the optional {\tt Bset} parameter is non-NULL. The @@ -2761,61 +3132,60 @@ \subsection{{\tt cholmod\_solve2}: solve a linear system, reusing workspace} {\tt Bset} are a subset of {\tt Xset} (except if {\tt sys} is {\tt CHOLMOD\_P} or {\tt CHOLMOD\_Pt}). -No memory allocations are done if the outputs and internal -workspaces ({\tt X}, {\tt Xset}, {\tt Y}, and {\tt E}) have been allocated -by a prior call (or if allocated by the user). To let {\tt cholmod\_solve2} -allocate these outputs and workspaces for you, simply initialize them to -NULL (as in the example above). Since it is possible for this function -to reallocate these 4 arrays, you should always re-acquire the pointers to -their internal data ({\tt X->x} for example) after calling -{\tt cholmod\_solve2}, since they may change. They normally will not -change except in the first call to this function. - -On the first call to {\tt cholmod\_solve2} when {\tt Bset} is NULL, -the factorization is converted from supernodal to simplicial, if needed. -The inverse permutation is also computed and stored in the factorization -object, {\tt L}. This can take a modest amount of time. Subsequent -calls to {\tt cholmod\_solve2} with a small {\tt Bset} -are very fast (both asymptotically and in practice). +No memory allocations are done if the outputs and internal workspaces ({\tt X}, +{\tt Xset}, {\tt Y}, and {\tt E}) have been allocated by a prior call (or if +allocated by the user). To let {\tt cholmod\_solve2} allocate these outputs +and workspaces for you, simply initialize them to NULL (as in the example +above). Since it is possible for this function to reallocate these 4 arrays, +you should always re-acquire the pointers to their internal data ({\tt X->x} +for example) after calling {\tt cholmod\_solve2}, since they may change. They +normally will not change except in the first call to this function. + +On the first call to {\tt cholmod\_solve2} when {\tt Bset} is NULL, the +factorization is converted from supernodal to simplicial, if needed. The +inverse permutation is also computed and stored in the factorization object, +{\tt L}. This can take a modest amount of time. Subsequent calls to {\tt +cholmod\_solve2} with a small {\tt Bset} are very fast (both asymptotically and +in practice). + +The dtypes of all parameters must match. You can find an example of how to use {\tt cholmod\_solve2} in the -two demo programs, {\tt cholmod\_demo} and {\tt cholmod\_l\_demo}. +four demo programs, {\tt cholmod\_*\_demo}. %--------------------------------------- \subsection{{\tt cholmod\_etree}: find elimination tree} %--------------------------------------- \input{_etree.tex} -Computes the elimination tree of {\tt A} or {\tt A'*A}. -In the symmetric case, the upper triangular part of {\tt A} is used. Entries not -in this part of the matrix are ignored. Computing the etree of a symmetric -matrix from just its lower triangular entries is not supported. -In the unsymmetric case, all of {\tt A} is used, and the etree of {\tt A'*A} is computed. -Refer to \cite{Liu90a} for a discussion of the elimination tree -and its use in sparse Cholesky factorization. -% J. Liu, "The role of elimination trees in sparse factorization", SIAM J. -% Matrix Analysis \& Applic., vol 11, 1990, pp. 134-172. +Computes the elimination tree of {\tt A} or {\tt A'*A}. In the symmetric case, +the upper triangular part of {\tt A} is used. Entries not in this part of the +matrix are ignored. Computing the etree of a symmetric matrix from just its +lower triangular entries is not supported. In the unsymmetric case, all of +{\tt A} is used, and the etree of {\tt A'*A} is computed. Refer to +\cite{Liu90a} for a discussion of the elimination tree and its use in sparse +Cholesky factorization. %--------------------------------------- \subsection{{\tt cholmod\_rowcolcounts}: nonzeros counts of a factor} %--------------------------------------- \input{_rowcolcounts.tex} -Compute the row and column counts of the Cholesky factor {\tt L} of the matrix -{\tt A} or {\tt A*A'}. The etree and its postordering must already be computed (see -{\tt cholmod\_etree} and {\tt cholmod\_postorder}) and given as inputs to this routine. -For the symmetric case ($\m{LL}\tr=\m{A}$), {\tt A} must be stored in -symmetric/lower form ({\tt A->stype = -1}). -In the unsymmetric case, {\tt A*A'} or {\tt A(:,f)*A(:,f)'} can be analyzed. -The fundamental floating-point operation count is returned in {\tt Common->fl} -(this excludes extra flops due to relaxed supernodal amalgamation). -Refer to {\tt cholmod\_transpose\_unsym} for a description of {\tt f}. -The algorithm is described in \cite{GilbertLiNgPeyton01,GilbertNgPeyton94}. +Computes the row and column counts of the Cholesky factor {\tt L} of the matrix +{\tt A} or {\tt A*A'}. The etree and its postordering must already be computed +(see {\tt cholmod\_etree} and {\tt cholmod\_postorder}) and given as inputs to +this routine. For the symmetric case ($\m{LL}\tr=\m{A}$), {\tt A} must be +stored in symmetric/lower form ({\tt A->stype = -1}). In the unsymmetric case, +{\tt A*A'} or {\tt A(:,f)*A(:,f)'} can be analyzed. The fundamental +floating-point operation count is returned in {\tt Common->fl} (this excludes +extra flops due to relaxed supernodal amalgamation). Refer to {\tt +cholmod\_transpose\_unsym} for a description of {\tt f}. The algorithm is +described in \cite{GilbertLiNgPeyton01,GilbertNgPeyton94}. % J. Gilbert, E. Ng, B. Peyton, "An efficient algorithm to compute row and % column counts for sparse Cholesky factorization", SIAM J. Matrix Analysis \& % Applic., vol 15, 1994, pp. 1075-1091. -% +% % J. Gilbert, X. Li, E. Ng, B. Peyton, "Computing row and column counts for % sparse QR and LU factorization", BIT, vol 41, 2001, pp. 693-710. @@ -2824,13 +3194,13 @@ \subsection{{\tt cholmod\_analyze\_ordering}: analyze a permutation} %--------------------------------------- \input{_analyze_ordering.tex} -Given a matrix {\tt A} and its fill-reducing permutation, compute the elimination -tree, its (non-weighted) postordering, and the number of nonzeros in each -column of {\tt L}. Also computes the flop count, the total nonzeros in {\tt L}, and -the nonzeros in {\tt tril(A)} ({\tt Common->fl}, {\tt Common->lnz}, and {\tt Common->anz}). -In the unsymmetric case, {\tt A(p,f)*A(p,f)'} is analyzed, and {\tt Common->anz} -is the number of nonzero entries in the lower triangular part of the product, -not in {\tt A} itself. +Given a matrix {\tt A} and its fill-reducing permutation, compute the +elimination tree, its (non-weighted) postordering, and the number of nonzeros +in each column of {\tt L}. Also computes the flop count, the total nonzeros in +{\tt L}, and the nonzeros in {\tt tril(A)} ({\tt Common->fl}, {\tt +Common->lnz}, and {\tt Common->anz}). In the unsymmetric case, {\tt +A(p,f)*A(p,f)'} is analyzed, and {\tt Common->anz} is the number of nonzero +entries in the lower triangular part of the product, not in {\tt A} itself. Refer to {\tt cholmod\_transpose\_unsym} for a description of {\tt f}. @@ -2843,88 +3213,85 @@ \subsection{{\tt cholmod\_amd}: interface to AMD} \input{_amd.tex} CHOLMOD interface to the AMD ordering package. Orders {\tt A} if the matrix is -symmetric. On output, {\tt Perm [k] = i} if row/column {\tt i} of {\tt A} is the {\tt k}th -row/column of {\tt P*A*P'}. This corresponds to {\tt A(p,p)} in MATLAB notation. -If A is unsymmetric, {\tt cholmod\_amd} orders {\tt A*A'} or {\tt A(:,f)*A(:,f)'}. -On output, {\tt Perm [k] = i} if -row/column {\tt i} of {\tt A*A'} is the {\tt k}th row/column of {\tt P*A*A'*P'}. -This corresponds to {\tt A(p,:)*A(p,:)'} in MATLAB notation. -If {\tt f} is present, {\tt A(p,f)*A(p,f)'} is the permuted matrix. -Refer to {\tt cholmod\_transpose\_unsym} for a description of {\tt f}. +symmetric. On output, {\tt Perm [k] = i} if row/column {\tt i} of {\tt A} is +the {\tt k}th row/column of {\tt P*A*P'}. This corresponds to {\tt A(p,p)} in +MATLAB notation. If A is unsymmetric, {\tt cholmod\_amd} orders {\tt A*A'} or +{\tt A(:,f)*A(:,f)'}. On output, {\tt Perm [k] = i} if row/column {\tt i} of +{\tt A*A'} is the {\tt k}th row/column of {\tt P*A*A'*P'}. This corresponds to +{\tt A(p,:)*A(p,:)'} in MATLAB notation. If {\tt f} is present, {\tt +A(p,f)*A(p,f)'} is the permuted matrix. Refer to {\tt +cholmod\_transpose\_unsym} for a description of {\tt f}. Computes the flop count for a subsequent $\m{LL}\tr$ factorization, the number -of nonzeros in {\tt L}, and the number of nonzeros in the matrix ordered -({\tt A}, {\tt A*A'} or {\tt A(:,f)*A(:,f)'}). -These statistics are returned in -{\tt Common->fl}, {\tt Common->lnz}, and {\tt Common->anz}, respectively. +of nonzeros in {\tt L}, and the number of nonzeros in the matrix ordered ({\tt +A}, {\tt A*A'} or {\tt A(:,f)*A(:,f)'}). These statistics are returned in {\tt +Common->fl}, {\tt Common->lnz}, and {\tt Common->anz}, respectively. %--------------------------------------- \subsection{{\tt cholmod\_colamd}: interface to COLAMD} %--------------------------------------- \input{_colamd.tex} -CHOLMOD interface to the COLAMD ordering package. -Finds a permutation {\tt p} such that the Cholesky factorization of {\tt P*A*A'*P'} is -sparser than {\tt A*A'}, using COLAMD. If the {\tt postorder} input parameter is {\tt TRUE}, -the column elimination tree is found and postordered, and the COLAMD ordering is then -combined with its postordering (COLAMD itself does not perform this postordering). -{\tt A} must be unsymmetric ({\tt A->stype = 0}). +CHOLMOD interface to the COLAMD ordering package. Finds a permutation {\tt p} +such that the Cholesky factorization of {\tt P*A*A'*P'} is sparser than {\tt +A*A'}, using COLAMD. If the {\tt postorder} input parameter is {\tt TRUE}, the +column elimination tree is found and postordered, and the COLAMD ordering is +then combined with its postordering (COLAMD itself does not perform this +postordering). {\tt A} must be unsymmetric ({\tt A->stype = 0}). %--------------------------------------- \subsection{{\tt cholmod\_rowfac}: row-oriented Cholesky factorization} %--------------------------------------- \input{_rowfac.tex} -Full or incremental numerical $\m{LDL}\tr$ or $\m{LL}\tr$ factorization (simplicial, not -supernodal). {\tt cholmod\_factorize} is the ``easy'' wrapper for this code, but it -does not provide access to incremental factorization. -The algorithm is the row-oriented, up-looking method described in \cite{Davis05}. -See also \cite{Liu86c}. No 2-by-2 pivoting (or any other pivoting) is performed. - -{\tt cholmod\_rowfac} computes the full or incremental $\m{LDL}\tr$ or $\m{LL}\tr$ factorization of -{\tt A+beta*I} (where {\tt A} is symmetric) or {\tt A*F+beta*I} -(where {\tt A} and {\tt F} are unsymmetric -and only the upper triangular part of {\tt A*F+beta*I} is used). It computes -{\tt L} (and {\tt D}, for $\m{LDL}\tr$) one row at a time. -The input scalar {\tt beta} is real; only the real part ({\tt beta[0]}) is used. - -{\tt L} can be a simplicial symbolic or numeric ({\tt L->is\_super} must be {\tt FALSE}). -A symbolic factor is converted immediately into a numeric factor containing -the identity matrix. - -For a full factorization, use {\tt kstart = 0} and {\tt kend = nrow}. The existing nonzero -entries (numerical values in {\tt L->x} and {\tt L->z} for the zomplex case, and indices -in {\tt L->i}) are overwritten. - -To compute an incremental factorization, select {\tt kstart} and {\tt kend} as the range -of rows of {\tt L} you wish to compute. Rows {\tt kstart} to {\tt kend-1} of {\tt L} -will be computed. A correct factorization will be computed -only if all descendants of all nodes {\tt kstart} to {\tt kend-1} in the elimination tree have -been factorized by a prior call to this routine, and if rows {\tt kstart} to {\tt kend-1} -have not been factorized. This condition is {\bf not} checked on input. - -In the symmetric case, {\tt A} must be stored in upper form ({\tt A->stype} is greater than zero). -The matrix {\tt F} is not accessed and may be {\tt NULL}. Only -columns {\tt kstart} to {\tt kend-1} of {\tt A} are accessed. - -In the unsymmetric case, - the typical case is {\tt F=A'}. Alternatively, if {\tt F=A(:,f)'}, then this - routine factorizes the matrix {\tt S = beta*I + A(:,f)*A(:,f)'}. - The product {\tt A*F} is assumed to be symmetric; - only the upper triangular part of {\tt A*F} is used. - {\tt F} must be of size {\tt A->ncol} by {\tt A->nrow}. +Full or incremental numerical $\m{LDL}\tr$ or $\m{LL}\tr$ factorization +(simplicial, not supernodal). {\tt cholmod\_factorize} is the ``easy'' wrapper +for this code, but it does not provide access to incremental factorization. +The algorithm is the row-oriented, up-looking method described in +\cite{Davis05}. See also \cite{Liu86c}. No 2-by-2 pivoting (or any other +pivoting) is performed. + +{\tt cholmod\_rowfac} computes the full or incremental $\m{LDL}\tr$ or +$\m{LL}\tr$ factorization of {\tt A+beta*I} (where {\tt A} is symmetric) or +{\tt A*F+beta*I} (where {\tt A} and {\tt F} are unsymmetric and only the upper +triangular part of {\tt A*F+beta*I} is used). It computes {\tt L} (and {\tt +D}, for $\m{LDL}\tr$) one row at a time. The input scalar {\tt beta} is real; +only the real part ({\tt beta[0]}) is used. + +{\tt L} can be a simplicial symbolic or numeric ({\tt L->is\_super} must be +{\tt FALSE}). A symbolic factor is converted immediately into a numeric factor +containing the identity matrix. + +For a full factorization, use {\tt kstart = 0} and {\tt kend = nrow}. The +existing nonzero entries (numerical values in {\tt L->x} and {\tt L->z} for the +zomplex case, and indices in {\tt L->i}) are overwritten. + +To compute an incremental factorization, select {\tt kstart} and {\tt kend} as +the range of rows of {\tt L} you wish to compute. Rows {\tt kstart} to {\tt +kend-1} of {\tt L} will be computed. A correct factorization will be computed +only if all descendants of all nodes {\tt kstart} to {\tt kend-1} in the +elimination tree have been factorized by a prior call to this routine, and if +rows {\tt kstart} to {\tt kend-1} have not been factorized. This condition is +{\bf not} checked on input. + +In the symmetric case, {\tt A} must be stored in upper form ({\tt A->stype} is +greater than zero). The matrix {\tt F} is not accessed and may be {\tt NULL}. +Only columns {\tt kstart} to {\tt kend-1} of {\tt A} are accessed. + +In the unsymmetric case, the typical case is {\tt F=A'}. Alternatively, if +{\tt F=A(:,f)'}, then this routine factorizes the matrix {\tt S = beta*I + +A(:,f)*A(:,f)'}. The product {\tt A*F} is assumed to be symmetric; only the +upper triangular part of {\tt A*F} is used. {\tt F} must be of size {\tt +A->ncol} by {\tt A->nrow}. + +If the \verb'L' factor on input is a purely symbolic factorization (with +\verb'L->xtype' of \verb'CHOLMOD_PATTERN'), then it is converted to a numeric +factorization with same dtype as A. Otherwise, the dtypes of L and A must +match. % J. Liu, "A compact row storage scheme for Cholesky factors", ACM Trans. % Math. Software, vol 12, 1986, pp. 127-148. -%--------------------------------------- -\subsection{{\tt cholmod\_rowfac\_mask}: row-oriented Cholesky factorization} -%--------------------------------------- - -\input{_rowfac_mask.tex} -For use in LPDASA only. - - %--------------------------------------- \subsection{{\tt cholmod\_row\_subtree}: pattern of row of a factor} %--------------------------------------- @@ -2938,26 +3305,26 @@ \subsection{{\tt cholmod\_row\_subtree}: pattern of row of a factor} \begin{verbatim} L(0:k-1,0:k-1) * x = A (0:k-1,:) * A (:,k)' \end{verbatim} -if {\tt A} is unsymmetric. -This gives the nonzero pattern of row {\tt k} of {\tt L} (excluding the diagonal). -The pattern is returned postordered, according to the subtree of the elimination -tree rooted at node {\tt k}. +if {\tt A} is unsymmetric. This gives the nonzero pattern of row {\tt k} of +{\tt L} (excluding the diagonal). The pattern is returned postordered, +according to the subtree of the elimination tree rooted at node {\tt k}. The symmetric case requires {\tt A} to be in symmetric-upper form. -The result is returned in {\tt R}, a pre-allocated sparse matrix of size {\tt nrow}-by-1, -with {\tt R->nzmax >= nrow}. {\tt R} is assumed to be packed ({\tt Rnz [0]} is not updated); -the number of entries in {\tt R} is given by {\tt Rp [0]}. +The result is returned in {\tt R}, a pre-allocated sparse matrix of size {\tt +nrow}-by-1, with {\tt R->nzmax >= nrow}. {\tt R} is assumed to be packed ({\tt +Rnz [0]} is not updated); the number of entries in {\tt R} is given by {\tt Rp +[0]}. %--------------------------------------- \subsection{{\tt cholmod\_row\_lsubtree}: pattern of row of a factor} %--------------------------------------- \input{_row_lsubtree.tex} -Identical to {\tt cholmod\_row\_subtree}, except the elimination tree is -found from {\tt L} itself, not {\tt Parent}. Also, {\tt F=A'} is not provided; -the nonzero pattern of the {\tt k}th column of {\tt F} is given by -{\tt Fi} and {\tt fnz} instead. +Identical to {\tt cholmod\_row\_subtree}, except the elimination tree is found +from {\tt L} itself, not {\tt Parent}. Also, {\tt F=A'} is not provided; the +nonzero pattern of the {\tt k}th column of {\tt F} is given by {\tt Fi} and +{\tt fnz} instead. %--------------------------------------- \subsection{{\tt cholmod\_resymbol}: re-do symbolic factorization} @@ -2965,9 +3332,9 @@ \subsection{{\tt cholmod\_resymbol}: re-do symbolic factorization} \input{_resymbol.tex} Recompute the symbolic pattern of {\tt L}. Entries not in the symbolic pattern -of the factorization of {\tt A(p,p)} or {\tt F*F'}, where -{\tt F=A(p,f)} or {\tt F=A(:,f)}, are dropped, where -{\tt p = L->Perm} is used to permute the input matrix {\tt A}. +of the factorization of {\tt A(p,p)} or {\tt F*F'}, where {\tt F=A(p,f)} or +{\tt F=A(:,f)}, are dropped, where {\tt p = L->Perm} is used to permute the +input matrix {\tt A}. Refer to {\tt cholmod\_transpose\_unsym} for a description of {\tt f}. @@ -2985,53 +3352,54 @@ \subsection{{\tt cholmod\_resymbol\_noperm}: re-do symbolic factorization} %--------------------------------------- \input{_resymbol_noperm.tex} -Identical to {\tt cholmod\_resymbol}, except that the fill-reducing -ordering {\tt L->Perm} is not used. +Identical to {\tt cholmod\_resymbol}, except that the fill-reducing ordering +{\tt L->Perm} is not used. %--------------------------------------- \subsection{{\tt cholmod\_postorder}: tree postorder} %--------------------------------------- \input{_postorder.tex} -Postorder a tree. The tree is either an elimination tree (the output from -{\tt cholmod\_etree}) or a component tree (from {\tt cholmod\_nested\_dissection}). - -An elimination tree is a complete tree of {\tt n} nodes with {\tt Parent [j] > j} or -{\tt Parent [j] = -1} if j is a root. On output {\tt Post [0..n-1]} is a complete -permutation vector; -{\tt Post [k] = j} if node {\tt j} is the {\tt k}th node in the -postordered elimination tree, where {\tt k} is in the range 0 to {\tt n-1}. - -A component tree is a subset of {\tt 0:n-1}. {\tt Parent [j] = -2} if node {\tt j} is not -in the component tree. {\tt Parent [j] = -1} if {\tt j} is a root of the component -tree, and {\tt Parent [j]} is in the range 0 to {\tt n-1} if {\tt j} is in the component -tree but not a root. On output, {\tt Post [k]} is defined only for nodes in -the component tree. {\tt Post [k] = j} if node {\tt j} is the {\tt k}th node in the -postordered component tree, where {\tt k} is in the range 0 to the number of -components minus 1. -Node {\tt j} is ignored and not included in the postorder if {\tt Parent [j] < -1}. -As a result, {\tt cholmod\_check\_parent (Parent, ...)} and {\tt cholmod\_check\_perm (Post, ...)} -fail if used for a component tree and its postordering. - -An optional node weight can be given. When starting a postorder at node {\tt j}, -the children of {\tt j} are ordered in decreasing order of their weight. -If no weights are given ({\tt Weight} is {\tt NULL}) then children are ordered in -decreasing order of their node number. The weight of a node must be in the -range 0 to {\tt n-1}. Weights outside that range are silently converted to that -range (weights $<$ 0 are treated as zero, and weights $\ge$ {\tt n} are treated as {\tt n-1}). +Postorder a tree. The tree is either an elimination tree (the output from {\tt +cholmod\_etree}) or a component tree (from {\tt cholmod\_nested\_dissection}). + +An elimination tree is a complete tree of {\tt n} nodes with {\tt Parent [j] > +j} or {\tt Parent [j] = -1} if j is a root. On output {\tt Post [0..n-1]} is a +complete permutation vector; {\tt Post [k] = j} if node {\tt j} is the {\tt +k}th node in the postordered elimination tree, where {\tt k} is in the range 0 +to {\tt n-1}. + +A component tree is a subset of {\tt 0:n-1}. {\tt Parent [j] = -2} if node +{\tt j} is not in the component tree. {\tt Parent [j] = -1} if {\tt j} is a +root of the component tree, and {\tt Parent [j]} is in the range 0 to {\tt n-1} +if {\tt j} is in the component tree but not a root. On output, {\tt Post [k]} +is defined only for nodes in the component tree. {\tt Post [k] = j} if node +{\tt j} is the {\tt k}th node in the postordered component tree, where {\tt k} +is in the range 0 to the number of components minus 1. Node {\tt j} is ignored +and not included in the postorder if {\tt Parent [j] < -1}. As a result, {\tt +cholmod\_check\_parent (Parent, ...)} and {\tt cholmod\_check\_perm (Post, +...)} fail if used for a component tree and its postordering. + +An optional node weight can be given. When starting a postorder at node {\tt +j}, the children of {\tt j} are ordered in decreasing order of their weight. +If no weights are given ({\tt Weight} is {\tt NULL}) then children are ordered +in decreasing order of their node number. The weight of a node must be in the +range 0 to {\tt n-1}. Weights outside that range are silently converted to +that range (weights $<$ 0 are treated as zero, and weights $\ge$ {\tt n} are +treated as {\tt n-1}). %--------------------------------------- \subsection{{\tt cholmod\_rcond}: reciprocal condition number} %--------------------------------------- \input{_rcond.tex} -Returns a rough estimate of the reciprocal of the condition number: -the minimum entry on the diagonal of {\tt L} (or absolute entry of {\tt D} for an $\m{LDL}\tr$ -factorization) divided by the maximum entry. {\tt L} can be real, complex, or -zomplex. Returns -1 on error, 0 if the matrix is singular or has a zero or NaN -entry on the diagonal of {\tt L}, 1 if the matrix is 0-by-0, or -{\tt min(diag(L))/max(diag(L))} otherwise. Never returns NaN; if {\tt L} has a NaN on -the diagonal it returns zero instead. +Returns a rough estimate of the reciprocal of the condition number: the minimum +entry on the diagonal of {\tt L} (or absolute entry of {\tt D} for an +$\m{LDL}\tr$ factorization) divided by the maximum entry. {\tt L} can be real, +complex, or zomplex. Returns -1 on error, 0 if the matrix is singular or has a +zero or NaN entry on the diagonal of {\tt L}, 1 if the matrix is 0-by-0, or +{\tt min(diag(L))/max(diag(L))} otherwise. Never returns NaN; if {\tt L} has a +NaN on the diagonal it returns zero instead. %------------------------------------------------------------------------------- \newpage \section{{\tt Modify} Module routines} @@ -3047,14 +3415,13 @@ \subsection{{\tt cholmod\_updown}: update/downdate} \[ \new{\m{L}}\new{\m{D}}\new{\m{L}}\tr = \m{LDL}\tr \pm \m{CC}\tr \] -where $\new{\m{L}}$ denotes the new factor. -{\tt C} must be sorted. It can be either packed or unpacked. As in all CHOLMOD -routines, the columns of {\tt L} are sorted on input, and also on output. -If {\tt L} does not contain a simplicial numeric $\m{LDL}\tr$ factorization, it -is converted into one. Thus, a supernodal $\m{LL}\tr$ factorization -can be passed to {\tt cholmod\_updown}. -A symbolic {\tt L} is converted into a numeric identity matrix. -If the initial conversion fails, the factor is returned unchanged. +where $\new{\m{L}}$ denotes the new factor. {\tt C} must be sorted. It can be +either packed or unpacked. As in all CHOLMOD routines, the columns of {\tt L} +are sorted on input, and also on output. If {\tt L} does not contain a +simplicial numeric $\m{LDL}\tr$ factorization, it is converted into one. Thus, +a supernodal $\m{LL}\tr$ factorization can be passed to {\tt cholmod\_updown}. +A symbolic {\tt L} is converted into a numeric identity matrix. If the initial +conversion fails, the factor is returned unchanged. If memory runs out during the update, the factor is returned as a simplicial symbolic factor. That is, everything is freed except for the fill-reducing @@ -3062,10 +3429,10 @@ \subsection{{\tt cholmod\_updown}: update/downdate} {\tt cholmod\_analyze}). Note that the fill-reducing permutation {\tt L->Perm} is not used. The row -indices of {\tt C} refer to the rows of {\tt L}, not {\tt A}. If your original system is -$\m{LDL}\tr = \m{PAP}\tr$ (where $\m{P} =$ {\tt L->Perm}), and you want to compute the $\m{LDL}\tr$ -factorization of $\m{A}+\m{CC}\tr$, then you must permute $\m{C}$ first. That is, -if +indices of {\tt C} refer to the rows of {\tt L}, not {\tt A}. If your original +system is $\m{LDL}\tr = \m{PAP}\tr$ (where $\m{P} =$ {\tt L->Perm}), and you +want to compute the $\m{LDL}\tr$ factorization of $\m{A}+\m{CC}\tr$, then you +must permute $\m{C}$ first. That is, if \[ \m{PAP}\tr = \m{LDL}\tr \] @@ -3076,107 +3443,71 @@ \subsection{{\tt cholmod\_updown}: update/downdate} = \m{LDL}\tr + (\m{PC})(\m{PC})\tr = \m{LDL}\tr + \new{\m{C}}\new{\m{C}}\tr \] -where $\new{\m{C}} = \m{PC}$. - -You can use the {\tt cholmod\_submatrix} routine in the {\tt MatrixOps} Module -to permute {\tt C}, with: +where $\new{\m{C}} = \m{PC}$. You can use the {\tt cholmod\_submatrix} routine +in the {\tt MatrixOps} Module to permute {\tt C}, with: \begin{verbatim} Cnew = cholmod_submatrix (C, L->Perm, L->n, NULL, -1, TRUE, TRUE, Common) ; \end{verbatim} - -Note that the {\tt sorted} input parameter to {\tt cholmod\_submatrix} must be {\tt TRUE}, -because {\tt cholmod\_updown} requires {\tt C} with sorted columns. -Only real matrices are supported. -The algorithms are described in \cite{DavisHager99,DavisHager01}. +Note that the {\tt sorted} input parameter to {\tt cholmod\_submatrix} must be +{\tt TRUE}, because {\tt cholmod\_updown} requires {\tt C} with sorted columns. +Only real matrices are supported (double or single). The algorithms are +described in \cite{DavisHager99,DavisHager01}. %--------------------------------------- -\subsection{{\tt cholmod\_updown\_solve}: update/downdate} +\subsection{{\tt cholmod\_updown\_solve}: update/downdate of a factorization +and a solution} %--------------------------------------- \input{_updown_solve.tex} -Identical to {\tt cholmod\_updown}, except -the system $\m{Lx}=\m{b}$ is also updated/downdated. -The new system is $\new{\m{L}}\new{\m{x}}=\m{b} + \Delta \m{b}$. The old solution $\m{x}$ is overwritten -with $\new{\m{x}}$. Note that as in the update/downdate of $\m{L}$ itself, the fill- -reducing permutation {\tt L->Perm} is not used. The vectors $\m{x}$ and $\m{b}$ are in the permuted -ordering, not your original ordering. This routine does not handle multiple right-hand-sides. - -%--------------------------------------- -\subsection{{\tt cholmod\_updown\_mark}: update/downdate} -%--------------------------------------- - -\input{_updown_mark.tex} -Identical to {\tt cholmod\_updown\_solve}, except that only part of $\m{L}$ -is used in the update of the solution to $\m{Lx}=\m{b}$. For more details, -see the source code file {\tt CHOLMOD/Modify/cholmod\_updown.c}. -This routine is meant for use in the {\tt LPDASA} linear program solver only, -by Hager and Davis. - -%--------------------------------------- -\subsection{{\tt cholmod\_updown\_mask}: update/downdate} -%--------------------------------------- - -\input{_updown_mask.tex} -For use in LPDASA only. +Identical to {\tt cholmod\_updown}, except the system $\m{Lx}=\m{b}$ is also +updated/downdated. The new system is $\new{\m{L}}\new{\m{x}}=\m{b} + \Delta +\m{b}$. The old solution $\m{x}$ is overwritten with $\new{\m{x}}$. Note that +as in the update/downdate of $\m{L}$ itself, the fill-reducing permutation +{\tt L->Perm} is not used. The vectors $\m{x}$ and $\m{b}$ are in the permuted +ordering. %--------------------------------------- \subsection{{\tt cholmod\_rowadd}: add row to factor} %--------------------------------------- \input{_rowadd.tex} -Adds a row and column to an $\m{LDL}\tr$ factorization. The {\tt k}th -row and column of {\tt L} must be equal to the {\tt k}th row and -column of the identity matrix on input. -Only real matrices are supported. -The algorithm is described in \cite{DavisHager05}. +Adds a row and column to an $\m{LDL}\tr$ factorization. The {\tt k}th row and +column of {\tt L} must be equal to the {\tt k}th row and column of the identity +matrix on input. Only real matrices are supported (double or single). The +dtypes of all matrices must match, except when \verb'L' is symbolic (with an +xtype of \verb'CHOLMOD_PATTERN'). In this case, \verb'L' is converted to the +dtype of \verb'R'. The algorithm is described in \cite{DavisHager05}. %--------------------------------------- -\subsection{{\tt cholmod\_rowadd\_solve}: add row to factor} +\subsection{{\tt cholmod\_rowadd\_solve}: add row to factor and update a +solution} %--------------------------------------- \input{_rowadd_solve.tex} -Identical to {\tt cholmod\_rowadd}, except the system $\m{Lx}=\m{b}$ is also updated/downdated, just like {\tt cholmod\_updown\_solve}. +Identical to {\tt cholmod\_rowadd}, except the system $\m{Lx}=\m{b}$ is also +updated/downdated, just like {\tt cholmod\_updown\_solve}. %--------------------------------------- \subsection{{\tt cholmod\_rowdel}: delete row from factor} %--------------------------------------- \input{_rowdel.tex} -Deletes a row and column from an $\m{LDL}\tr$ factorization. The {\tt k}th -row and column of {\tt L} is equal to the {\tt k}th row and -column of the identity matrix on output. -Only real matrices are supported. +Deletes a row and column from an $\m{LDL}\tr$ factorization. The {\tt k}th row +and column of {\tt L} is equal to the {\tt k}th row and column of the identity +matrix on output. The dtypes of all matrices must match. Only real matrices +are supported (double or single). %--------------------------------------- -\subsection{{\tt cholmod\_rowdel\_solve}: delete row from factor} +\subsection{{\tt cholmod\_rowdel\_solve}: delete row from factor and update a solution} %--------------------------------------- \input{_rowdel_solve.tex} -Identical to {\tt cholmod\_rowdel}, except the system $\m{Lx}=\m{b}$ is also updated/downdated, just like {\tt cholmod\_updown\_solve}. -When row/column $k$ of $\m{A}$ is deleted from the system $\m{Ay}=\m{b}$, this can induce -a change to $\m{x}$, in addition to changes arising when $\m{L}$ and $\m{b}$ are modified. -If this is the case, the kth entry of $\m{y}$ is required as input ({\tt yk}). -The algorithm is described in \cite{DavisHager05}. - -%--------------------------------------- -\subsection{{\tt cholmod\_rowadd\_mark}: add row to factor} -%--------------------------------------- - -\input{_rowadd_mark.tex} -Identical to {\tt cholmod\_rowadd\_solve}, except that only part of $\m{L}$ -is used in the update of the solution to $\m{Lx}=\m{b}$. For more details, -see the source code file {\tt CHOLMOD/Modify/cholmod\_rowadd.c}. -This routine is meant for use in the {\tt LPDASA} linear program solver only. - -%--------------------------------------- -\subsection{{\tt cholmod\_rowdel\_mark}: delete row from factor} -%--------------------------------------- - -\input{_rowdel_mark.tex} -Identical to {\tt cholmod\_rowadd\_solve}, except that only part of $\m{L}$ -is used in the update of the solution to $\m{Lx}=\m{b}$. For more details, -see the source code file {\tt CHOLMOD/Modify/cholmod\_rowdel.c}. -This routine is meant for use in the {\tt LPDASA} linear program solver only. +Identical to {\tt cholmod\_rowdel}, except the system $\m{Lx}=\m{b}$ is also +updated/downdated, just like {\tt cholmod\_updown\_solve}. When row/column $k$ +of $\m{A}$ is deleted from the system $\m{Ay}=\m{b}$, this can induce a change +to $\m{x}$, in addition to changes arising when $\m{L}$ and $\m{b}$ are +modified. If this is the case, the kth entry of $\m{y}$ is required as input +({\tt yk}). The algorithm is described in \cite{DavisHager05}. %------------------------------------------------------------------------------- \newpage \section{{\tt MatrixOps} Module routines} @@ -3187,11 +3518,9 @@ \subsection{{\tt cholmod\_drop}: drop small entries} %--------------------------------------- \input{_drop.tex} -Drop small entries from {\tt A}, and entries in the ignored part of {\tt A} if {\tt A} -is symmetric. No CHOLMOD routine drops small numerical entries -from a matrix, except for this one. NaN's and Inf's are kept. - -Supports pattern and real matrices; complex and zomplex matrices are not supported. +Drop small entries from {\tt A}, and entries in the ignored part of {\tt A} if +{\tt A} is symmetric. No CHOLMOD routine drops small numerical entries from a +matrix, except for this one. NaN's and Inf's are kept. %--------------------------------------- \subsection{{\tt cholmod\_norm\_dense}: dense matrix norm} @@ -3200,7 +3529,6 @@ \subsection{{\tt cholmod\_norm\_dense}: dense matrix norm} \input{_norm_dense.tex} Returns the infinity-norm, 1-norm, or 2-norm of a dense matrix. Can compute the 2-norm only for a dense column vector. -All xtypes are supported. %--------------------------------------- \subsection{{\tt cholmod\_norm\_sparse}: sparse matrix norm} @@ -3208,151 +3536,157 @@ \subsection{{\tt cholmod\_norm\_sparse}: sparse matrix norm} \input{_norm_sparse.tex} Returns the infinity-norm or 1-norm of a sparse matrix. -All xtypes are supported. %--------------------------------------- \subsection{{\tt cholmod\_scale}: scale sparse matrix} %--------------------------------------- \input{_scale.tex} -Scales a matrix: {\tt A = diag(s)*A}, {\tt A*diag(s)}, {\tt s*A}, or {\tt diag(s)*A*diag(s)}. +Scales a matrix: {\tt A = diag(s)*A}, {\tt A*diag(s)}, {\tt s*A}, or {\tt +diag(s)*A*diag(s)}. {\tt A} can be of any type (packed/unpacked, upper/lower/unsymmetric). The symmetry of {\tt A} is ignored; all entries in the matrix are modified. -If {\tt A} is {\tt m}-by-{\tt n} unsymmetric but scaled symmetrically, the result is +If {\tt A} is {\tt m}-by-{\tt n} unsymmetric but scaled symmetrically, the +result is + \begin{verbatim} A = diag (s (1:m)) * A * diag (s (1:n)) \end{verbatim} Row or column scaling of a symmetric matrix still results in a symmetric -matrix, since entries are still ignored by other routines. -For example, when row-scaling a symmetric matrix where just the upper -triangular part is stored (and lower triangular entries ignored) -{\tt A = diag(s)*triu(A)} is performed, where the result {\tt A} is also -symmetric-upper. This has the effect of modifying the implicit lower -triangular part. In MATLAB notation: +matrix, since entries are still ignored by other routines. For example, when +row-scaling a symmetric matrix where just the upper triangular part is stored +(and lower triangular entries ignored) {\tt A = diag(s)*triu(A)} is performed, +where the result {\tt A} is also symmetric-upper. This has the effect of +modifying the implicit lower triangular part. In MATLAB notation: + \begin{verbatim} U = diag(s)*triu(A) ; L = tril (U',-1) A = L + U ; \end{verbatim} -The scale parameter determines the kind of scaling to perform and the size of {\tt S}: +The scale parameter determines the kind of scaling to perform and the size of +{\tt S}: \begin{tabular}{lll} \hline {\tt scale} & operation & size of {\tt S} \\ \hline -{\tt CHOLMOD\_SCALAR} & {\tt s[0]*A} & 1 \\ -{\tt CHOLMOD\_ROW} & {\tt diag(s)*A} & {\tt nrow}-by-1 or 1-by-{\tt nrow} \\ -{\tt CHOLMOD\_COL} & {\tt A*diag(s)} & {\tt ncol}-by-1 or 1-by-{\tt ncol} \\ -{\tt CHOLMOD\_SYM} & {\tt diag(s)*A*diag(s)} & {\tt max(nrow,ncol)}-by-1, or 1-by-{\tt max(nrow,ncol)} \\ +{\tt CHOLMOD\_SCALAR} & {\tt s[0]*A} & 1 \\ +{\tt CHOLMOD\_ROW} & {\tt diag(s)*A} & {\tt nrow}-by-1 or 1-by-{\tt nrow} \\ +{\tt CHOLMOD\_COL} & {\tt A*diag(s)} & {\tt ncol}-by-1 or 1-by-{\tt ncol} \\ +{\tt CHOLMOD\_SYM} & {\tt diag(s)*A*diag(s)} & {\tt max(nrow,ncol)}-by-1, or 1-by-{\tt max(nrow,ncol)} \\ \hline \end{tabular} -Only real matrices are supported. - %--------------------------------------- \subsection{{\tt cholmod\_sdmult}: sparse-times-dense matrix} %--------------------------------------- \input{_sdmult.tex} -Sparse matrix times dense matrix: -{\tt Y = alpha*(A*X) + beta*Y} or {\tt Y = alpha*(A'*X) + beta*Y}, -where {\tt A} is sparse and {\tt X} and {\tt Y} are dense. -When using {\tt A}, -{\tt X} has {\tt A->ncol} rows and -{\tt Y} has {\tt A->nrow} rows. -When using {\tt A'}, -{\tt X} has {\tt A->nrow} rows and -{\tt Y} has {\tt A->ncol} rows. -If {\tt transpose = 0}, then {\tt A} is used; +Sparse matrix times dense matrix: {\tt Y = alpha*(A*X) + beta*Y} or {\tt Y = +alpha*(A'*X) + beta*Y}, where {\tt A} is sparse and {\tt X} and {\tt Y} are +dense. When using {\tt A}, {\tt X} has {\tt A->ncol} rows and {\tt Y} has {\tt +A->nrow} rows. When using {\tt A'}, {\tt X} has {\tt A->nrow} rows and {\tt Y} +has {\tt A->ncol} rows. If {\tt transpose = 0}, then {\tt A} is used; otherwise, {\tt A'} is used (the complex conjugate transpose). -The {\tt transpose} parameter is ignored if the matrix is symmetric or Hermitian. -(the array transpose {\tt A.'} is not supported). -Supports real, complex, and zomplex matrices, but the xtypes of {\tt A}, {\tt X}, and {\tt Y} must all match. + +The {\tt transpose} parameter is ignored if the matrix is symmetric or +Hermitian. Supports real, complex, and zomplex matrices, but the xtypes and +dtypes of {\tt A}, {\tt X}, and {\tt Y} must all match. %--------------------------------------- \subsection{{\tt cholmod\_ssmult}: sparse-times-sparse matrix} %--------------------------------------- \input{_ssmult.tex} -Computes {\tt C = A*B}; multiplying two sparse matrices. -{\tt C} is returned as packed, and either unsorted or sorted, depending on the -{\tt sorted} input parameter. If {\tt C} is returned sorted, then either {\tt C = (B'*A')'} -or {\tt C = (A*B)''} is computed, depending on the number of nonzeros in {\tt A}, {\tt B}, and {\tt C}. -The stype of {\tt C} is determined by the {\tt stype} parameter. -Only pattern and real matrices are supported. Complex and zomplex matrices -are supported only when the numerical values are not computed ({\tt values} -is {\tt FALSE}). +Computes {\tt C = A*B}; multiplying two sparse matrices. {\tt C} is returned +as packed, and either unsorted or sorted, depending on the {\tt sorted} input +parameter. If {\tt C} is returned sorted, then either {\tt C = (B'*A')'} or +{\tt C = (A*B)''} is computed, depending on the number of nonzeros in {\tt A}, +{\tt B}, and {\tt C}. The stype of {\tt C} is determined by the {\tt stype} +parameter. The xtypes and dtypes of \verb'A' and \verb'B' must match, +unless \verb'mode' is 0. +% +If \verb'A' and/or \verb'B' are symmetric, a temporary unsymmetric copy is +made, and the conversion is controlled by the \verb'mode' parameter. %--------------------------------------- \subsection{{\tt cholmod\_submatrix}: sparse submatrix} %--------------------------------------- \input{_submatrix.tex} -Returns {\tt C = A (rset,cset)}, where {\tt C} becomes {\tt length(rset)}-by-{\tt length(cset)} in dimension. -{\tt rset} and {\tt cset} can have duplicate entries. {\tt A} must be unsymmetric. {\tt C} unsymmetric and -is packed. If {\tt sorted} is {\tt TRUE} on input, or {\tt rset} is sorted and {\tt A} is -sorted, then {\tt C} is sorted; otherwise {\tt C} is unsorted. - -If {\tt rset} is {\tt NULL}, it means ``{\tt [ ]}'' in MATLAB notation, the empty set. -The number of rows in the result {\tt C} will be zero if {\tt rset} is {\tt NULL}. -Likewise if {\tt cset} means the empty set; the number of columns in the result {\tt C} will be zero if {\tt cset} is {\tt NULL}. -If {\tt rsize} or {\tt csize} is negative, it denotes ``{\tt :}'' in MATLAB notation. -Thus, if both {\tt rsize} and {\tt csize} are negative {\tt C = A(:,:) = A} is returned. - -For permuting a matrix, this routine is an alternative to {\tt cholmod\_ptranspose} -(which permutes and transposes a matrix and can work on symmetric matrices). - -The time taken by this routine is O({\tt A->nrow}) if the {\tt Common} workspace needs -to be initialized, plus O({\tt C->nrow + C->ncol + nnz (A (:,cset))}). Thus, if {\tt C} -is small and the workspace is not initialized, the time can be dominated by -the call to {\tt cholmod\_allocate\_work}. However, once the workspace is -allocated, subsequent calls take less time. - -Only pattern and real matrices are supported. Complex and zomplex matrices -are supported only when {\tt values} is {\tt FALSE}. +Returns {\tt C = A (rset,cset)}, where {\tt C} becomes {\tt +length(rset)}-by-{\tt length(cset)} in dimension. {\tt rset} and {\tt cset} +can have duplicate entries. {\tt A} must be unsymmetric. {\tt C} unsymmetric +and is packed. If {\tt sorted} is {\tt TRUE} on input, or {\tt rset} is sorted +and {\tt A} is sorted, then {\tt C} is sorted; otherwise {\tt C} is unsorted. +% +If \verb'A' and/or \verb'B' are symmetric, a temporary unsymmetric copy is +made, and the conversion is controlled by the \verb'mode' parameter. + +If {\tt rset} is {\tt NULL}, it means ``{\tt [ ]}'' in MATLAB notation, the +empty set. The number of rows in the result {\tt C} will be zero if {\tt rset} +is {\tt NULL}. Likewise if {\tt cset} means the empty set; the number of +columns in the result {\tt C} will be zero if {\tt cset} is {\tt NULL}. If +{\tt rsize} or {\tt csize} is negative, it denotes ``{\tt :}'' in MATLAB +notation. Thus, if both {\tt rsize} and {\tt csize} are negative {\tt C = +A(:,:) = A} is returned. + +For permuting a matrix, this routine is an alternative to {\tt +cholmod\_ptranspose} (which permutes and transposes a matrix and can work on +symmetric matrices). + +The time taken by this routine is O({\tt A->nrow}) if the {\tt Common} +workspace needs to be initialized, plus O({\tt C->nrow + C->ncol + nnz (A +(:,cset))}). Thus, if {\tt C} is small and the workspace is not initialized, +the time can be dominated by the call to {\tt cholmod\_allocate\_work}. +However, once the workspace is allocated, subsequent calls take less time. %--------------------------------------- \subsection{{\tt cholmod\_horzcat}: horizontal concatenation} %--------------------------------------- \input{_horzcat.tex} -Horizontal concatenation, returns {\tt C = [A,B]} in MATLAB notation. -{\tt A} and {\tt B} can have any stype. {\tt C} is returned unsymmetric and packed. -{\tt A} and {\tt B} must have the same number of rows. -{\tt C} is sorted if both {\tt A} and {\tt B} are sorted. -{\tt A} and {\tt B} must have the same numeric xtype, unless {\tt values} is {\tt FALSE}. -{\tt A} and {\tt B} cannot be complex or zomplex, unless {\tt values} is {\tt FALSE}. +Horizontal concatenation, returns {\tt C = [A,B]} in MATLAB notation. {\tt A} +and {\tt B} can have any stype. {\tt C} is returned unsymmetric and packed. +{\tt A} and {\tt B} must have the same number of rows. {\tt C} is sorted if +both {\tt A} and {\tt B} are sorted. {\tt A} and {\tt B} must have the same +xtype and dtype, unless {\tt mode} is 0. +% +If \verb'A' and/or \verb'B' are symmetric, a temporary unsymmetric copy is +made, and the conversion is controlled by the \verb'mode' parameter. %--------------------------------------- \subsection{{\tt cholmod\_vertcat}: vertical concatenation} %--------------------------------------- \input{_vertcat.tex} -Vertical concatenation, returns {\tt C = [A;B]} in MATLAB notation. -{\tt A} and {\tt B} can have any stype. {\tt C} is returned unsymmetric and packed. -{\tt A} and {\tt B} must have the same number of columns. -{\tt C} is sorted if both {\tt A} and {\tt B} are sorted. -{\tt A} and {\tt B} must have the same numeric xtype, unless {\tt values} is {\tt FALSE}. -{\tt A} and {\tt B} cannot be complex or zomplex, unless {\tt values} is {\tt FALSE}. +Vertical concatenation, returns {\tt C = [A;B]} in MATLAB notation. {\tt A} +and {\tt B} can have any stype. {\tt C} is returned unsymmetric and packed. +{\tt A} and {\tt B} must have the same number of columns. {\tt C} is sorted if +both {\tt A} and {\tt B} are sorted. {\tt A} and {\tt B} must have the same +xtype and dtype, unless {\tt mode} is 0. +% +If \verb'A' and/or \verb'B' are symmetric, a temporary unsymmetric copy is +made, and the conversion is controlled by the \verb'mode' parameter. %--------------------------------------- \subsection{{\tt cholmod\_symmetry}: compute the symmetry of a matrix} %--------------------------------------- \input{_symmetry.tex} - Determines if a sparse matrix is rectangular, unsymmetric, symmetric, skew-symmetric, or Hermitian. It does so by looking at its numerical values of both upper and lower triangular parts of a CHOLMOD "unsymmetric" -matrix, where A->stype == 0. The transpose of A is NOT constructed. +matrix, where \verb'A->stype' == 0. The transpose of A is NOT constructed. If not unsymmetric, it also determines if the matrix has a diagonal whose entries are all real and positive (and thus a candidate for sparse Cholesky -if A->stype is changed to a nonzero value). +if \verb'A->stype' is changed to a nonzero value). Note that a Matrix Market "general" matrix is either rectangular or unsymmetric. @@ -3364,12 +3698,12 @@ \subsection{{\tt cholmod\_symmetry}: compute the symmetry of a matrix} If option == 0, then this routine returns immediately when it finds a non-positive diagonal entry (or one with nonzero imaginary part). If the -matrix is not a candidate for sparse Cholesky, it returns the value -{\tt CHOLMOD\_MM\_UNSYMMETRIC}, even if the matrix might in fact be symmetric or +matrix is not a candidate for sparse Cholesky, it returns the value {\tt +CHOLMOD\_MM\_UNSYMMETRIC}, even if the matrix might in fact be symmetric or Hermitian. This routine is useful inside the MATLAB backslash, which must look at an -arbitrary matrix (A->stype == 0) and determine if it is a candidate for +arbitrary matrix (\verb'A->stype' == 0) and determine if it is a candidate for sparse Cholesky. In that case, option should be 0. This routine is also useful when writing a MATLAB matrix to a file in @@ -3383,112 +3717,118 @@ \subsection{{\tt cholmod\_symmetry}: compute the symmetry of a matrix} perfectly symmetric matrix. This option is used when computing the following statistics for the matrices in the SuiteSparse Matrix Collection. - numerical symmetry: number of matched off-diagonal nonzeros over - the total number of off-diagonal entries. A real entry $a_{ij}$, $i \ne j$, - is matched if $a_{ji} = a_{ij}$, but this is only counted if both - $a_{ji}$ and $a_{ij}$ are nonzero. This does not depend on {\tt Z}. - (If A is complex, then the above test is modified; $a_{ij}$ is matched - if $\mbox{conj}(a_{ji}) = a_{ij}$). - - Then numeric symmetry = xmatched / nzoffdiag, or 1 if nzoffdiag = 0. - - pattern symmetry: number of matched offdiagonal entries over the - total number of offdiagonal entries. An entry $a_{ij}$, $i \ne j$, is - matched if $a_{ji}$ is also an entry. - - Then pattern symmetry = pmatched / nzoffdiag, or 1 if nzoffdiag = 0. - -The symmetry of a matrix with no offdiagonal entries is equal to 1. +\begin{itemize} + + \item {\bf numerical symmetry}: number of matched off-diagonal nonzeros over + the total number of off-diagonal entries. A real entry $a_{ij}$, $i + \ne j$, is matched if $a_{ji} = a_{ij}$, but this is only counted if + both $a_{ji}$ and $a_{ij}$ are nonzero. This does not depend on {\tt + Z}. (If A is complex, then the above test is modified; $a_{ij}$ is + matched if $\mbox{conj}(a_{ji}) = a_{ij}$). + + Then numeric symmetry = xmatched / nzoffdiag, or 1 if nzoffdiag = 0. -A workspace of size ncol integers is allocated; EMPTY is returned if this -allocation fails. + \item {\bf pattern symmetry}: number of matched offdiagonal entries over + the total number of offdiagonal entries. An entry $a_{ij}$, $i \ne j$, + is matched if $a_{ji}$ is also an entry. + + Then pattern symmetry = pmatched / nzoffdiag, or 1 if nzoffdiag = 0. +\end{itemize} + +The symmetry of a matrix with no offdiagonal entries is equal to 1. Summary of return values: \begin{tabular}{ll} -{\tt EMPTY (-1)} & out of memory, stype not zero, A not sorted \\ -{\tt CHOLMOD\_MM\_RECTANGULAR 1} & A is rectangular \\ -{\tt CHOLMOD\_MM\_UNSYMMETRIC 2} & A is unsymmetric \\ -{\tt CHOLMOD\_MM\_SYMMETRIC 3} & A is symmetric, but with non-pos. diagonal \\ -{\tt CHOLMOD\_MM\_HERMITIAN 4} & A is Hermitian, but with non-pos. diagonal \\ +{\tt EMPTY (-1)} & out of memory, stype not zero, A not sorted \\ +{\tt CHOLMOD\_MM\_RECTANGULAR 1} & A is rectangular \\ +{\tt CHOLMOD\_MM\_UNSYMMETRIC 2} & A is unsymmetric \\ +{\tt CHOLMOD\_MM\_SYMMETRIC 3} & A is symmetric, but with non-pos. diagonal \\ +{\tt CHOLMOD\_MM\_HERMITIAN 4} & A is Hermitian, but with non-pos. diagonal \\ {\tt CHOLMOD\_MM\_SKEW\_SYMMETRIC 5} & A is skew symmetric \\ {\tt CHOLMOD\_MM\_SYMMETRIC\_POSDIAG 6} & A is symmetric with positive diagonal \\ {\tt CHOLMOD\_MM\_HERMITIAN\_POSDIAG 7} & A is Hermitian with positive diagonal \\ \end{tabular} -See also the {\tt spsym} mexFunction, which is a MATLAB interface for this code. - -If the matrix is a candidate for sparse Cholesky, it will return a result -\newline -{\tt CHOLMOD\_MM\_SYMMETRIC\_POSDIAG} if real, or {\tt CHOLMOD\_MM\_HERMITIAN\_POSDIAG} if -complex. Otherwise, it will return a value less than this. This is true -regardless of the value of the option parameter. - +See also the {\tt spsym} mexFunction, which is a MATLAB interface for this +code. If the matrix is a candidate for sparse Cholesky, it will return a +result \newline {\tt CHOLMOD\_MM\_SYMMETRIC\_POSDIAG} if real, or {\tt +CHOLMOD\_MM\_HERMITIAN\_POSDIAG} if complex. Otherwise, it will return a value +less than this. This is true regardless of the value of the option parameter. %------------------------------------------------------------------------------- \newpage \section{{\tt Supernodal} Module routines} %------------------------------------------------------------------------------- +Normally these methods are not called directly, but are accessed via the +\verb'cholmod_analyze', \verb'cholmod_factorize', and \verb'cholmod_solve' +methods. + %--------------------------------------- \subsection{{\tt cholmod\_super\_symbolic}: supernodal symbolic factorization} %--------------------------------------- \input{_super_symbolic.tex} -Supernodal symbolic analysis of the $\m{LL}\tr$ factorization of {\tt A}, {\tt A*A'}, or {\tt A(:,f)*A(:,f)'}. -This routine must be preceded by a simplicial symbolic analysis -({\tt cholmod\_rowcolcounts}). See {\tt Cholesky/cholmod\_analyze.c} for an example of how to use -this routine. -The user need not call this directly; {\tt cholmod\_analyze} is a ``simple'' wrapper for this routine. -{\tt A} can be symmetric (upper), or unsymmetric. The symmetric/lower form is not supported. -In the unsymmetric case {\tt F} is the normally transpose of {\tt A}. -Alternatively, if {\tt F=A(:,f)'} then {\tt F*F'} is analyzed. -Requires {\tt Parent} and {\tt L->ColCount} to be defined on input; these are the -simplicial {\tt Parent} and {\tt ColCount} arrays as computed by {\tt cholmod\_rowcolcounts}. -Does not use {\tt L->Perm}; the input matrices {\tt A} and {\tt F} must already be properly -permuted. Allocates and computes the supernodal pattern of {\tt L} -({\tt L->super}, {\tt L->pi}, {\tt L->px}, and {\tt L->s}). -Does not allocate the real part ({\tt L->x}). +Supernodal symbolic analysis of the $\m{LL}\tr$ factorization of {\tt A}, {\tt +A*A'}, or {\tt A(:,f)*A(:,f)'}. This routine must be preceded by a simplicial +symbolic analysis ({\tt cholmod\_rowcolcounts}). See {\tt +Cholesky/cholmod\_analyze.c} for an example of how to use this routine. The +user need not call this directly; {\tt cholmod\_analyze} is a ``simple'' +wrapper for this routine. {\tt A} can be symmetric (upper), or unsymmetric. +The symmetric/lower form is not supported. In the unsymmetric case {\tt F} is +the normally transpose of {\tt A}. Alternatively, if {\tt F=A(:,f)'} then {\tt +F*F'} is analyzed. Requires {\tt Parent} and {\tt L->ColCount} to be defined +on input; these are the simplicial {\tt Parent} and {\tt ColCount} arrays as +computed by {\tt cholmod\_rowcolcounts}. Does not use {\tt L->Perm}; the input +matrices {\tt A} and {\tt F} must already be properly permuted. Allocates and +computes the supernodal pattern of {\tt L} ({\tt L->super}, {\tt L->pi}, {\tt +L->px}, and {\tt L->s}). Does not allocate the real part ({\tt L->x}). %--------------------------------------- \subsection{{\tt cholmod\_super\_numeric}: supernodal numeric factorization} %--------------------------------------- \input{_super_numeric.tex} -Computes the numerical Cholesky factorization of {\tt A+beta*I} or {\tt A*F+beta*I}. Only the -lower triangular part of {\tt A+beta*I} or {\tt A*F+beta*I} is accessed. The -matrices {\tt A} and {\tt F} must already be permuted according to the fill-reduction -permutation {\tt L->Perm}. {\tt cholmod\_factorize} is an "easy" wrapper for this code -which applies that permutation. -The input scalar {\tt beta} is real; only the real part ({\tt beta[0]}) is used. - -Symmetric case: {\tt A} is a symmetric (lower) matrix. {\tt F} is not accessed and may be {\tt NULL}. -With a fill-reducing permutation, {\tt A(p,p)} should be passed for {\tt A}, where is -{\tt p} is {\tt L->Perm}. - -Unsymmetric case: {\tt A} is unsymmetric, and {\tt F} must be present. Normally, {\tt F=A'}. -With a fill-reducing permutation, {\tt A(p,f)} and {\tt A(p,f)'} should be passed as the -parameters {\tt A} and {\tt F}, respectively, where {\tt f} is a list of the subset of the columns of {\tt A}. - -The input factorization {\tt L} must be supernodal ({\tt L->is\_super} is {\tt TRUE}). It can -either be symbolic or numeric. In the first case, {\tt L} has been analyzed by -{\tt cholmod\_analyze} or {\tt cholmod\_super\_symbolic}, but the matrix has not yet been -numerically factorized. The numerical values are allocated here and the -factorization is computed. In the second case, a prior matrix has been -analyzed and numerically factorized, and a new matrix is being factorized. -The numerical values of {\tt L} are replaced with the new numerical factorization. - -{\tt L->is\_ll} is ignored on input, and set to {\tt TRUE} on output. This routine always computes an $\m{LL}\tr$ -factorization. Supernodal $\m{LDL}\tr$ factorization is not supported. +Computes the numerical Cholesky factorization of {\tt A+beta*I} or {\tt +A*F+beta*I}. Only the lower triangular part of {\tt A+beta*I} or {\tt +A*F+beta*I} is accessed. The matrices {\tt A} and {\tt F} must already be +permuted according to the fill-reduction permutation {\tt L->Perm}. {\tt +cholmod\_factorize} is an "easy" wrapper for this code which applies that +permutation. The input scalar {\tt beta} is real; only the real part ({\tt +beta[0]}) is used. + +Symmetric case: {\tt A} is a symmetric (lower) matrix. {\tt F} is not accessed +and may be {\tt NULL}. With a fill-reducing permutation, {\tt A(p,p)} should +be passed for {\tt A}, where is {\tt p} is {\tt L->Perm}. + +Unsymmetric case: {\tt A} is unsymmetric, and {\tt F} must be present. +Normally, {\tt F=A'}. With a fill-reducing permutation, {\tt A(p,f)} and {\tt +A(p,f)'} should be passed as the parameters {\tt A} and {\tt F}, respectively, +where {\tt f} is a list of the subset of the columns of {\tt A}. + +The input factorization {\tt L} must be supernodal ({\tt L->is\_super} is {\tt +TRUE}). It can either be symbolic or numeric. In the first case, {\tt L} has +been analyzed by {\tt cholmod\_analyze} or {\tt cholmod\_super\_symbolic}, but +the matrix has not yet been numerically factorized. The numerical values are +allocated here and the factorization is computed. In the second case, a prior +matrix has been analyzed and numerically factorized, and a new matrix is being +factorized. The numerical values of {\tt L} are replaced with the new +numerical factorization. + +{\tt L->is\_ll} is ignored on input, and set to {\tt TRUE} on output. This +routine always computes an $\m{LL}\tr$ factorization. Supernodal $\m{LDL}\tr$ +factorization is not supported. If the matrix is not positive definite the routine returns {\tt TRUE}, but sets -{\tt Common->status} to {\tt CHOLMOD\_NOT\_POSDEF} and {\tt L->minor} is set to the column at -which the failure occurred. Columns {\tt L->minor} to {\tt L->n-1} are set to zero. +{\tt Common->status} to {\tt CHOLMOD\_NOT\_POSDEF} and {\tt L->minor} is set to +the column at which the failure occurred. Columns {\tt L->minor} to {\tt +L->n-1} are set to zero. -If {\tt L} is supernodal symbolic on input, it is converted to a supernodal numeric -factor on output, with an xtype of real if {\tt A} is real, or complex if {\tt A} is -complex or zomplex. If {\tt L} is supernodal numeric on input, its xtype must -match {\tt A} (except that {\tt L} can be complex and {\tt A} zomplex). The xtype of {\tt A} and {\tt F} -must match. +If {\tt L} is supernodal symbolic on input, it is converted to a supernodal +numeric factor on output, with an xtype of real if {\tt A} is real, or complex +if {\tt A} is complex or zomplex. If {\tt L} is supernodal numeric on input, +its xtype must match {\tt A} (except that {\tt L} can be complex and {\tt A} +zomplex). The xtype of {\tt A} and {\tt F} must match. %--------------------------------------- \subsection{{\tt cholmod\_super\_lsolve}: supernodal forward solve} @@ -3496,21 +3836,19 @@ \subsection{{\tt cholmod\_super\_lsolve}: supernodal forward solve} \input{_super_lsolve.tex} Solve $\m{Lx}=\m{b}$ for a supernodal factorization. This routine does not -apply the permutation {\tt L->Perm}. See {\tt cholmod\_solve} for a more general -interface that performs that operation. -Only real and complex xtypes are supported. -{\tt L}, {\tt X}, and {\tt E} must have the same xtype. +apply the permutation {\tt L->Perm}. See {\tt cholmod\_solve} for a more +general interface that performs that operation. Only real and complex xtypes +are supported. {\tt L}, {\tt X}, and {\tt E} must have the same xtype. %--------------------------------------- \subsection{{\tt cholmod\_super\_ltsolve}: supernodal backsolve} %--------------------------------------- \input{_super_ltsolve.tex} -Solve $\m{L}\tr\m{x}=\m{b}$ for a supernodal factorization. This routine does not -apply the permutation {\tt L->Perm}. See {\tt cholmod\_solve} for a more general -interface that performs that operation. -Only real and complex xtypes are supported. -{\tt L}, {\tt X}, and {\tt E} must have the same xtype. +Solve $\m{L}\tr\m{x}=\m{b}$ for a supernodal factorization. This routine does +not apply the permutation {\tt L->Perm}. See {\tt cholmod\_solve} for a more +general interface that performs that operation. Only real and complex xtypes +are supported. {\tt L}, {\tt X}, and {\tt E} must have the same xtype. %------------------------------------------------------------------------------- \newpage \section{{\tt Partition} Module routines} @@ -3521,93 +3859,89 @@ \subsection{{\tt cholmod\_nested\_dissection}: nested dissection ordering} %--------------------------------------- \input{_nested_dissection.tex} -CHOLMOD's nested dissection algorithm: - using its own compression and connected-components - algorithms, an external graph partitioner (METIS), and a constrained - minimum degree ordering algorithm (CAMD, CCOLAMD, or CSYMAMD). Typically - gives better orderings than {\tt METIS\_NodeND} (about 5\% to 10\% fewer - nonzeros in {\tt L}). +CHOLMOD's nested dissection algorithm: using its own compression and +connected-components algorithms, an external graph partitioner (METIS), and a +constrained minimum degree ordering algorithm (CAMD, CCOLAMD, or CSYMAMD). +Typically gives better orderings than {\tt METIS\_NodeND} (about 5\% to 10\% +fewer nonzeros in {\tt L}). This method uses a node bisector, applied recursively (but using a non-recursive implementation). Once the graph is partitioned, it calls a -constrained minimum degree code (CAMD or CSYMAMD for {\tt A+A'}, -and CCOLAMD for {\tt A*A'}) to -order all the nodes in the graph - but obeying the constraints determined -by the separators. This routine is similar to {\tt METIS\_NodeND}, except for -how -it treats the leaf nodes. {\tt METIS\_NodeND} orders the leaves of the separator -tree with {\tt MMD}, ignoring the rest of the matrix when ordering a single leaf. -This routine orders the whole matrix with CAMD, CSYMAMD, or CCOLAMD, all at once, -when the graph partitioning is done. +constrained minimum degree code (CAMD or CSYMAMD for {\tt A+A'}, and CCOLAMD +for {\tt A*A'}) to order all the nodes in the graph - but obeying the +constraints determined by the separators. This routine is similar to {\tt +METIS\_NodeND}, except for how it treats the leaf nodes. {\tt METIS\_NodeND} +orders the leaves of the separator tree with {\tt MMD}, ignoring the rest of +the matrix when ordering a single leaf. This routine orders the whole matrix +with CAMD, CSYMAMD, or CCOLAMD, all at once, when the graph partitioning is +done. %--------------------------------------- \subsection{{\tt cholmod\_metis}: interface to METIS nested dissection} %--------------------------------------- \input{_metis.tex} -CHOLMOD wrapper for the {\tt METIS\_NodeND} ordering routine. Creates {\tt A+A'}, -{\tt A*A'} or {\tt A(:,f)*A(:,f)'} and then calls {\tt METIS\_NodeND} on the resulting graph. -This routine is comparable to {\tt cholmod\_nested\_dissection}, except that it -calls {\tt METIS\_NodeND} directly, and it does not return the separator tree. +CHOLMOD wrapper for the {\tt METIS\_NodeND} ordering routine. Creates {\tt +A+A'}, {\tt A*A'} or {\tt A(:,f)*A(:,f)'} and then calls {\tt METIS\_NodeND} on +the resulting graph. This routine is comparable to {\tt +cholmod\_nested\_dissection}, except that it calls {\tt METIS\_NodeND} +directly, and it does not return the separator tree. %--------------------------------------- \subsection{{\tt cholmod\_camd}: interface to CAMD} %--------------------------------------- \input{_camd.tex} -CHOLMOD interface to the CAMD ordering routine. Finds a permutation -{\tt p} such that the Cholesky factorization of {\tt A(p,p)} -is sparser than {\tt A}. If {\tt A} is unsymmetric, -{\tt A*A'} is ordered. -If {\tt Cmember[i]=c} then node {\tt i} is in set {\tt c}. -All nodes in set 0 are ordered first, followed by all nodes in set 1, and so on. +CHOLMOD interface to the CAMD ordering routine. Finds a permutation {\tt p} +such that the Cholesky factorization of {\tt A(p,p)} is sparser than {\tt A}. +If {\tt A} is unsymmetric, {\tt A*A'} is ordered. If {\tt Cmember[i]=c} then +node {\tt i} is in set {\tt c}. All nodes in set 0 are ordered first, followed +by all nodes in set 1, and so on. %--------------------------------------- \subsection{{\tt cholmod\_ccolamd}: interface to CCOLAMD} %--------------------------------------- \input{_ccolamd.tex} -CHOLMOD interface to the CCOLAMD ordering routine. Finds a permutation -{\tt p} such that the Cholesky factorization of {\tt A(p,:)*A(p,:)'} is sparser than {\tt A*A'}. -The column elimination is found and postordered, and the CCOLAMD ordering is then -combined with its postordering. {\tt A} must be unsymmetric. -If {\tt Cmember[i]=c} then node {\tt i} is in set {\tt c}. -All nodes in set 0 are ordered first, followed by all nodes in set 1, and so on. +CHOLMOD interface to the CCOLAMD ordering routine. Finds a permutation {\tt p} +such that the Cholesky factorization of {\tt A(p,:)*A(p,:)'} is sparser than +{\tt A*A'}. The column elimination is found and postordered, and the CCOLAMD +ordering is then combined with its postordering. {\tt A} must be unsymmetric. +If {\tt Cmember[i]=c} then node {\tt i} is in set {\tt c}. All nodes in set 0 +are ordered first, followed by all nodes in set 1, and so on. %--------------------------------------- \subsection{{\tt cholmod\_csymamd}: interface to CSYMAMD} %--------------------------------------- \input{_csymamd.tex} -CHOLMOD interface to the CSYMAMD ordering routine. Finds a permutation -{\tt p} such that the Cholesky factorization of {\tt A(p,p)} is sparser than {\tt A}. -The elimination tree is found and postordered, and the CSYMAMD -ordering is then combined with its postordering. If {\tt A} is unsymmetric, -{\tt A+A'} is ordered ({\tt A} must be square). -If {\tt Cmember[i]=c} then node {\tt i} is in set {\tt c}. -All nodes in set 0 are ordered first, followed by all nodes in set 1, and so on. +CHOLMOD interface to the CSYMAMD ordering routine. Finds a permutation {\tt p} +such that the Cholesky factorization of {\tt A(p,p)} is sparser than {\tt A}. +The elimination tree is found and postordered, and the CSYMAMD ordering is then +combined with its postordering. If {\tt A} is unsymmetric, {\tt A+A'} is +ordered ({\tt A} must be square). If {\tt Cmember[i]=c} then node {\tt i} is +in set {\tt c}. All nodes in set 0 are ordered first, followed by all nodes in +set 1, and so on. %--------------------------------------- \subsection{{\tt cholmod\_bisect}: graph bisector} %--------------------------------------- \input{_bisect.tex} -Finds a node bisector of {\tt A}, {\tt A*A'}, {\tt A(:,f)*A(:,f)'}: -a set of nodes that partitions the graph into two parts. -Compresses the graph first, ensures the graph is symmetric with -no diagonal entries, and then calls METIS. +Finds a node bisector of {\tt A}, {\tt A*A'}, {\tt A(:,f)*A(:,f)'}: a set of +nodes that partitions the graph into two parts. Compresses the graph first, +ensures the graph is symmetric with no diagonal entries, and then calls METIS. %--------------------------------------- \subsection{{\tt cholmod\_metis\_bisector}: interface to METIS node bisector} %--------------------------------------- \input{_metis_bisector.tex} -Finds a set of nodes that bisects the graph of {\tt A} or {\tt A*A'} (a direct interface to \newline -{\tt METIS\_NodeComputeSeparator}). - -The input matrix {\tt A} must be square, symmetric (with both upper and lower -parts present) and with no diagonal entries. These conditions are not -checked. Use cholmod\_bisect to check these conditions. +Finds a set of nodes that bisects the graph of {\tt A} or {\tt A*A'} (a direct +interface to \newline {\tt METIS\_NodeComputeSeparator}). The input matrix +{\tt A} must be square, symmetric (with both upper and lower parts present) and +with no diagonal entries. These conditions are not checked. Use +{\tt cholmod\_bisect} to check these conditions. %--------------------------------------- \subsection{{\tt cholmod\_collapse\_septree}: prune a separator tree} @@ -3620,3 +3954,4 @@ \subsection{{\tt cholmod\_collapse\_septree}: prune a separator tree} \bibliographystyle{plain} \bibliography{UserGuide} \end{document} + diff --git a/CHOLMOD/Doc/Makefile b/CHOLMOD/Doc/Makefile index 365c4d142..69b30b345 100644 --- a/CHOLMOD/Doc/Makefile +++ b/CHOLMOD/Doc/Makefile @@ -3,7 +3,7 @@ all: CHOLMOD_UserGuide.pdf I = ../Include/cholmod.h -C = ../Demo/cholmod_simple.c +C = ../Demo/cholmod_di_simple.c M = \ ../MATLAB/analyze.m \ @@ -25,7 +25,6 @@ M = \ ../MATLAB/nesdis.m \ ../MATLAB/resymbol.m \ ../MATLAB/sdmult.m \ - ../MATLAB/sparse2.m \ ../MATLAB/spsym.m \ ../MATLAB/mread.m \ ../MATLAB/mwrite.m \ @@ -54,19 +53,20 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getmproto ../MATLAB/nesdis.m > _nesdis_m.tex ./getmproto ../MATLAB/resymbol.m > _resymbol_m.tex ./getmproto ../MATLAB/sdmult.m > _sdmult_m.tex - ./getmproto ../MATLAB/sparse2.m > _sparse2_m.tex ./getmproto ../MATLAB/symbfact2.m > _symbfact2_m.tex - ./getproto '/include/, /^}/' ../Demo/cholmod_simple.c > _simple.tex + ./getproto '/include/, /^}/' ../Demo/cholmod_di_simple.c > _simple.tex ./getproto '/typedef struct cholmod_common/, /^}/' ../Include/cholmod.h > _common.tex ./getproto '/int cholmod_start/, /\*\) ;/' ../Include/cholmod.h > _start.tex ./getproto '/int cholmod_finish/, /\*\) ;/' ../Include/cholmod.h > _finish.tex ./getproto '/int cholmod_defaults/, /\*\) ;/' ../Include/cholmod.h > _defaults.tex ./getproto '/size_t cholmod_maxrank/, /\*\) ;/' ../Include/cholmod.h > _maxrank.tex ./getproto '/int cholmod_allocate_work/, /\*\) ;/' ../Include/cholmod.h > _allocate_work.tex + ./getproto '/int cholmod_alloc_work/, /\*\) ;/' ../Include/cholmod.h > _alloc_work.tex ./getproto '/int cholmod_free_work/, /\*\) ;/' ../Include/cholmod.h > _free_work.tex ./getproto '/int64_t cholmod_clear_flag/, /\*\) ;/' ../Include/cholmod.h > _clear_flag.tex ./getproto '/int cholmod_error/, /\*\) ;/' ../Include/cholmod.h > _error.tex - ./getproto '/double cholmod_dbound/, /l_sbound/' ../Include/cholmod.h > _dbound.tex + ./getproto '/double cholmod_dbound/, /l_dbound/' ../Include/cholmod.h > _dbound.tex + ./getproto '/float cholmod_sbound/, /l_sbound/' ../Include/cholmod.h > _sbound.tex ./getproto '/double cholmod_hypot/, /double\) ;/' ../Include/cholmod.h > _hypot.tex ./getproto '/int cholmod_divcomplex/, /\*\) ;/' ../Include/cholmod.h > _divcomplex.tex ./getproto '/typedef struct cholmod_sparse/, /^}/' ../Include/cholmod.h > _sparse.tex @@ -83,6 +83,7 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getproto '/cholmod_sparse \*cholmod_ptranspose/, /\*\) ;/' ../Include/cholmod.h > _ptranspose.tex ./getproto '/int cholmod_sort/, /\*\) ;/' ../Include/cholmod.h > _sort.tex ./getproto '/cholmod_sparse \*cholmod_band/, /\*\) ;/' ../Include/cholmod.h > _band.tex + ./getproto '/int64_t cholmod_band_nnz/, /\*\) ;/' ../Include/cholmod.h > _band_nnz.tex ./getproto '/int cholmod_band_inplace/, /\*\) ;/' ../Include/cholmod.h > _band_inplace.tex ./getproto '/cholmod_sparse \*cholmod_aat/, /\*\) ;/' ../Include/cholmod.h > _aat.tex ./getproto '/cholmod_sparse \*cholmod_copy_sparse/, /\*\) ;/' ../Include/cholmod.h > _copy_sparse.tex @@ -91,6 +92,7 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getproto '/int cholmod_sparse_xtype/, /\*\) ;/' ../Include/cholmod.h > _sparse_xtype.tex ./getproto '/typedef struct cholmod_factor/, /^}/' ../Include/cholmod.h > _factor.tex ./getproto '/cholmod_factor \*cholmod_allocate_factor/, /\*\) ;/' ../Include/cholmod.h > _allocate_factor.tex + ./getproto '/cholmod_factor \*cholmod_alloc_factor/, /\*\) ;/' ../Include/cholmod.h > _alloc_factor.tex ./getproto '/int cholmod_free_factor/, /\*\) ;/' ../Include/cholmod.h > _free_factor.tex ./getproto '/int cholmod_reallocate_factor/, /\*\) ;/' ../Include/cholmod.h > _reallocate_factor.tex ./getproto '/int cholmod_change_factor/, /\*\) ;/' ../Include/cholmod.h > _change_factor.tex @@ -125,7 +127,6 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getproto '/void \*cholmod_realloc/, /\*\) ;/' ../Include/cholmod.h > _realloc.tex ./getproto '/int cholmod_realloc_multiple/, /\*\) ;/' ../Include/cholmod.h > _realloc_multiple.tex ./getproto '/int cholmod_version/, /l_version/' ../Include/cholmod.h > _version.tex - ./getproto '/itype: integer sizes/, /define CHOLMOD_SUPERNODAL/' ../Include/cholmod.h > _defn.tex ./getproto '/int cholmod_check_common/, /\*\) ;/' ../Include/cholmod.h > _check_common.tex ./getproto '/int cholmod_print_common/, /\*\) ;/' ../Include/cholmod.h > _print_common.tex ./getproto '/int cholmod_check_sparse/, /\*\) ;/' ../Include/cholmod.h > _check_sparse.tex @@ -142,10 +143,14 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getproto '/int cholmod_print_perm/, /\*\) ;/' ../Include/cholmod.h > _print_perm.tex ./getproto '/int cholmod_check_parent/, /\*\) ;/' ../Include/cholmod.h > _check_parent.tex ./getproto '/int cholmod_print_parent/, /\*\) ;/' ../Include/cholmod.h > _print_parent.tex - ./getproto '/cholmod_triplet \*cholmod_read_triplet/, /\*\) ;/' ../Include/cholmod.h > _read_triplet.tex - ./getproto '/cholmod_sparse \*cholmod_read_sparse/, /\*\) ;/' ../Include/cholmod.h > _read_sparse.tex - ./getproto '/cholmod_dense \*cholmod_read_dense/, /\*\) ;/' ../Include/cholmod.h > _read_dense.tex - ./getproto '/void \*cholmod_read_matrix/, /\*\) ;/' ../Include/cholmod.h > _read_matrix.tex + ./getproto '/cholmod_triplet \*cholmod_read_triplet /, /\*\) ;/' ../Include/cholmod.h > _read_triplet.tex + ./getproto '/cholmod_triplet \*cholmod_read_triplet2/, /\*\) ;/' ../Include/cholmod.h > _read_triplet2.tex + ./getproto '/cholmod_sparse \*cholmod_read_sparse /, /\*\) ;/' ../Include/cholmod.h > _read_sparse.tex + ./getproto '/cholmod_sparse \*cholmod_read_sparse2/, /\*\) ;/' ../Include/cholmod.h > _read_sparse2.tex + ./getproto '/cholmod_dense \*cholmod_read_dense /, /\*\) ;/' ../Include/cholmod.h > _read_dense.tex + ./getproto '/cholmod_dense \*cholmod_read_dense2/, /\*\) ;/' ../Include/cholmod.h > _read_dense2.tex + ./getproto '/void \*cholmod_read_matrix /, /\*\) ;/' ../Include/cholmod.h > _read_matrix.tex + ./getproto '/void \*cholmod_read_matrix2/, /\*\) ;/' ../Include/cholmod.h > _read_matrix2.tex ./getproto '/int cholmod_write_sparse/, /\*\) ;/' ../Include/cholmod.h > _write_sparse.tex ./getproto '/int cholmod_write_dense/, /\*\) ;/' ../Include/cholmod.h > _write_dense.tex ./getproto '/cholmod_factor \*cholmod_analyze /, /\*\) ;/' ../Include/cholmod.h > _analyze.tex @@ -160,8 +165,7 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getproto '/int cholmod_analyze_ordering/, /\*\) ;/' ../Include/cholmod.h > _analyze_ordering.tex ./getproto '/int cholmod_amd/, /\*\) ;/' ../Include/cholmod.h > _amd.tex ./getproto '/int cholmod_colamd/, /\*\) ;/' ../Include/cholmod.h > _colamd.tex - ./getproto '/int cholmod_rowfac/, /\*\) ;/' ../Include/cholmod.h > _rowfac.tex - ./getproto '/int cholmod_rowfac_mask/, /\*\) ;/' ../Include/cholmod.h > _rowfac_mask.tex + ./getproto '/int cholmod_rowfac /, /\*\) ;/' ../Include/cholmod.h > _rowfac.tex ./getproto '/int cholmod_row_subtree/, /\*\) ;/' ../Include/cholmod.h > _row_subtree.tex ./getproto '/int cholmod_row_lsubtree/, /\*\) ;/' ../Include/cholmod.h > _row_lsubtree.tex ./getproto '/int cholmod_lsolve_pattern/, /\*\) ;/' ../Include/cholmod.h > _lsolve_pattern.tex @@ -171,14 +175,10 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getproto '/int32_t cholmod_postorder/, /\*\) ;/' ../Include/cholmod.h > _postorder.tex ./getproto '/int cholmod_updown /, /\*\) ;/' ../Include/cholmod.h > _updown.tex ./getproto '/int cholmod_updown_solve/, /\*\) ;/' ../Include/cholmod.h > _updown_solve.tex - ./getproto '/int cholmod_updown_mark/, /\*\) ;/' ../Include/cholmod.h > _updown_mark.tex - ./getproto '/int cholmod_updown_mask/, /\*\) ;/' ../Include/cholmod.h > _updown_mask.tex ./getproto '/int cholmod_rowadd /, /\*\) ;/' ../Include/cholmod.h > _rowadd.tex ./getproto '/int cholmod_rowadd_solve/, /\*\) ;/' ../Include/cholmod.h > _rowadd_solve.tex - ./getproto '/int cholmod_rowadd_mark/, /\*\) ;/' ../Include/cholmod.h > _rowadd_mark.tex ./getproto '/int cholmod_rowdel /, /\*\) ;/' ../Include/cholmod.h > _rowdel.tex ./getproto '/int cholmod_rowdel_solve/, /\*\) ;/' ../Include/cholmod.h > _rowdel_solve.tex - ./getproto '/int cholmod_rowdel_mark/, /\*\) ;/' ../Include/cholmod.h > _rowdel_mark.tex ./getproto '/int cholmod_drop/, /\*\) ;/' ../Include/cholmod.h > _drop.tex ./getproto '/double cholmod_norm_dense/, /\*\) ;/' ../Include/cholmod.h > _norm_dense.tex ./getproto '/double cholmod_norm_sparse/, /\*\) ;/' ../Include/cholmod.h > _norm_sparse.tex @@ -189,7 +189,7 @@ CHOLMOD_UserGuide.pdf: CHOLMOD_UserGuide.tex UserGuide.bib $(I) $(C) $(M) Makefi ./getproto '/cholmod_sparse \*cholmod_submatrix/, /\*\) ;/' ../Include/cholmod.h > _submatrix.tex ./getproto '/cholmod_sparse \*cholmod_vertcat/, /\*\) ;/' ../Include/cholmod.h > _vertcat.tex ./getproto '/int cholmod_symmetry/, /\*\) ;/' ../Include/cholmod.h > _symmetry.tex - ./getproto '/int cholmod_super_symbolic/, /\*\) ;/' ../Include/cholmod.h > _super_symbolic.tex + ./getproto '/int cholmod_super_symbolic /, /\*\) ;/' ../Include/cholmod.h > _super_symbolic.tex ./getproto '/int cholmod_super_numeric/, /\*\) ;/' ../Include/cholmod.h > _super_numeric.tex ./getproto '/int cholmod_super_lsolve/, /\*\) ;/' ../Include/cholmod.h > _super_lsolve.tex ./getproto '/int cholmod_super_ltsolve/, /\*\) ;/' ../Include/cholmod.h > _super_ltsolve.tex diff --git a/CHOLMOD/Include/cholmod.h b/CHOLMOD/Include/cholmod.h index a66bdd0e8..b2aaa2b97 100644 --- a/CHOLMOD/Include/cholmod.h +++ b/CHOLMOD/Include/cholmod.h @@ -94,7 +94,7 @@ // parameter. It is always an input/output parameter. //------------------------------------------------------------------------------ -// CHOLMOD matrix formats NEW +// CHOLMOD matrix formats //------------------------------------------------------------------------------ // A CHOLMOD sparse, dense, or triplet matrix A, or a sparse factorization L @@ -120,9 +120,9 @@ // // (3): CHOLMOD_ZOMPLEX: The matrix is complex, with separate array for // the real and imaginary parts. The kth value in -// the matrix is held in A->x [k], where A->x and -// A->z can hold up to A->nzmax values each. -// +// the matrix is held in A->x [k] and A->z [k], +// where A->x and A->z can hold up to A->nzmax +// values each. // A->xtype values: #define CHOLMOD_PATTERN 0 @@ -140,7 +140,7 @@ // zomplex, both A->x and A->z have size A->nzmax // * sizeof (double). // -// (1) CHOLMOD_SINGLE: A->x (and A->z for zomplex matrices) is float. +// (4) CHOLMOD_SINGLE: A->x (and A->z for zomplex matrices) is float. // If A is real, A->x has a size of A->nzmax * // sizeof (float). If A is complex, A->x has size // A->nzmax * 2 * sizeof (float). If zomplex, @@ -684,7 +684,7 @@ typedef struct cholmod_common_struct int64_t mark ; // Flag is cleared if Flag [0..nrow-1] < mark. size_t iworksize ; // size of Iwork, in Ints (int32 or int64). // This is at most 6*nrow + ncol. - size_t xworkbytes ; // size of Xwork, in bytes. // NEW (revised defn) + size_t xworkbytes ; // size of Xwork, in bytes. // NOTE: in CHOLMOD v4 and earlier, xworkwise was in terms // of # of doubles, not # of bytes. @@ -801,11 +801,11 @@ typedef struct cholmod_common_struct // as well. This mitigates any changes between v4.0 and v5.0, and may make // it easier to upgrade from v4 to v5. - double nsbounds_hit ; // # of times diagonal modified by sbound. // NEW + double nsbounds_hit ; // # of times diagonal modified by sbound. // This ought to be int64_t, but ndbounds_hit was double in // v4 (see above), so nsbounds_hit is made the same type // for consistency. - float sbound ; // Same as dbound, // NEW + float sbound ; // Same as dbound, // but for single precision factorization. float other_6 ; // for future expansion @@ -970,7 +970,7 @@ int cholmod_l_allocate_work (size_t, size_t, size_t, cholmod_common *) ; // Added for CHOLMOD v5: allocates Xwork as either double or single. -int cholmod_alloc_work // NEW +int cholmod_alloc_work ( // input: size_t nrow, // size of Common->Flag (nrow int32's) @@ -1031,8 +1031,8 @@ int cholmod_l_error (int, const char *, int, const char *, cholmod_common *) ; double cholmod_dbound (double, cholmod_common *) ; double cholmod_l_dbound (double, cholmod_common *) ; -float cholmod_sbound (float, cholmod_common *) ; // NEW -float cholmod_l_sbound (float, cholmod_common *) ; // NEW +float cholmod_sbound (float, cholmod_common *) ; +float cholmod_l_sbound (float, cholmod_common *) ; //------------------------------------------------------------------------------ // cholmod_hypot: compute sqrt (x*x + y*y) accurately @@ -1092,7 +1092,7 @@ typedef struct cholmod_sparse_struct // if CHOLMOD_INT, these arrays are all of type int32_t. // if CHOLMOD_LONG, these arrays are all of type int64_t. int xtype ; // pattern, real, complex, or zomplex - int dtype ; // x and z are double or single // NEW (now used) + int dtype ; // x and z are double or single int sorted ; // true if columns are sorted, false otherwise int packed ; // true if packed (A->nz ignored), false if unpacked @@ -1111,7 +1111,7 @@ cholmod_sparse *cholmod_allocate_sparse int sorted, // true if columns are sorted int packed, // true if A is be packed (A->nz NULL), false if unpacked int stype, // the stype of the matrix (unsym, tril, or triu) - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1166,7 +1166,7 @@ cholmod_sparse *cholmod_speye // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1186,7 +1186,7 @@ cholmod_sparse *cholmod_spzeros // return a sparse matrix with no entries size_t nrow, // # of rows size_t ncol, // # of columns size_t nzmax, // max # of entries the matrix can hold - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1202,7 +1202,7 @@ cholmod_sparse *cholmod_transpose // return new sparse matrix C ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.) // 0: pattern (with diag) cholmod_common *Common @@ -1221,7 +1221,7 @@ int cholmod_transpose_unsym ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.), // 0: pattern (with diag) int32_t *Perm, // permutation for C=A(p,f)', or NULL @@ -1246,7 +1246,7 @@ int cholmod_transpose_sym ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.), // 0: pattern (with diag) int32_t *Perm, // permutation for C=A(p,p)', or NULL @@ -1265,7 +1265,7 @@ cholmod_sparse *cholmod_ptranspose // return new sparse matrix C ( // input: cholmod_sparse *A, // input matrix - int mode, // 2: numerical (conj) NEW: same effect, new name + int mode, // 2: numerical (conj) // 1: numerical (non-conj.) // 0: pattern (with diag) int32_t *Perm, // permutation for C=A(p,f)', or NULL @@ -1292,7 +1292,7 @@ int cholmod_l_sort (cholmod_sparse *, cholmod_common *) ; // cholmod_band_nnz: # of entries within a band of a sparse matrix //------------------------------------------------------------------------------ -int64_t cholmod_band_nnz // return # of entries in a band (-1 if error) // NEW +int64_t cholmod_band_nnz // return # of entries in a band (-1 if error) ( // input: cholmod_sparse *A, // matrix to examine @@ -1347,7 +1347,7 @@ cholmod_sparse *cholmod_aat // return sparse matrix C cholmod_sparse *A, // input matrix int32_t *fset, // a list of column indices in range 0:A->ncol-1 size_t fsize, // # of entries in fset - int mode, // 2: numerical (conj) NEW + int mode, // 2: numerical (conj) // 1: numerical (non-conj.), // 0: pattern (with diag) // -1: pattern (remove diag), @@ -1382,7 +1382,7 @@ cholmod_sparse *cholmod_copy // return new sparse matrix // input: cholmod_sparse *A, // input matrix, not modified int stype, // stype of C - int mode, // 2: numerical (conj) NEW + int mode, // 2: numerical (conj) // 1: numerical (non-conj.) // 0: pattern (with diag) // -1: pattern (remove diag) @@ -1402,7 +1402,7 @@ cholmod_sparse *cholmod_add // return C = alpha*A + beta*B cholmod_sparse *B, // input matrix double alpha [2], // scale factor for A (two entires used if complex) double beta [2], // scale factor for A (two entires used if complex) - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern int sorted, // ignored; C is now always returned as sorted @@ -1418,7 +1418,7 @@ cholmod_sparse *cholmod_l_add (cholmod_sparse *, cholmod_sparse *, double *, int cholmod_sparse_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_sparse *A, // sparse matrix to change cholmod_common *Common @@ -1451,24 +1451,19 @@ typedef struct cholmod_factor_struct // simplicial factorization (not supernodal) //-------------------------------------------------------------------------- - size_t nzmax ; // # of entries that L->i, L->x, and L->z can hold + // The row indices of L(:,j) are held in L->i [L->p [j] ... L->p [j] + + // L->nz [j] - 1]. The numeical values of L(:,j) are held in the same + // positions in L->x (and L->z if L is zomplex). L->next and L->prev hold + // a link list of columns of L, that tracks the order they appear in the + // arrays L->i, L->x, and L->z. The head and tail of the list is n+1 and + // n, respectively. + size_t nzmax ; // # of entries that L->i, L->x, and L->z can hold void *p ; // int32/int64, size n+1, column pointers void *i ; // int32/int64, size nzmax, row indices void *x ; // float/double, size nzmax or 2*nzmax, numerical values void *z ; // float/double, size nzmax or empty, imaginary values void *nz ; // int32/int64, size ncol, # of entries in each column - - // The row indices of L(:,j) are held in - // L->i [L->p [j] ... L->p [j] + L->nz [j] - 1]. - - // The numeical values of L(:,j) are held in the same positions in L->x - // (and L->z if L is zomplex) - - // L->next and L->prev hold a link list of columns of L, that tracks the - // order they appear in the arrays L->i, L->x, and L->z. The head and tail - // of the list is n+1 and n, respectively. - void *next ; // int32/int64, size n+2 void *prev ; // int32/int64, size n+2 @@ -1484,13 +1479,12 @@ typedef struct cholmod_factor_struct size_t xsize ; // # of entries in L->x size_t maxcsize ; // size of largest update matrix size_t maxesize ; // max # of rows in supernodes, excl. triangular part - // the following are int32/int64 and are size nsuper+1: void *super ; // first column in each supernode void *pi ; // index into L->s for integer part of a supernode void *px ; // index into L->x for numeric part of a supernode - - void *s ; // int32/int64, ssize, integer part of supernodes + // int32/int64, of size ssize: + void *s ; // integer part of supernodes //-------------------------------------------------------------------------- // type of the factorization @@ -1524,7 +1518,6 @@ typedef struct cholmod_factor_struct // If L->xtype is CHOLMOD_REAL, CHOLMOD_COMPLEX, or CHOLMOD_ZOMPLEX, // then L is a numeric factor: // - // // simplicial LDL': (is_ll false, is_super false). Stored in compressed // column form, using the simplicial components above (nzmax, p, i, // x, z, nz, next, and prev). The unit diagonal of L is not stored, @@ -1546,7 +1539,7 @@ typedef struct cholmod_factor_struct // if L->itype is CHOLMOD_LONG. int xtype ; // pattern, real, complex, or zomplex - int dtype ; // x and z are double or single // NEW + int dtype ; // x and z are double or single int useGPU; // if true, symbolic factorization allows for use of the GPU @@ -1570,7 +1563,7 @@ cholmod_factor *cholmod_l_allocate_factor (size_t, cholmod_common *) ; // cholmod_alloc_factor: allocate a numerical factor (double or single) //------------------------------------------------------------------------------ -cholmod_factor *cholmod_alloc_factor // return the new factor L // NEW +cholmod_factor *cholmod_alloc_factor // return the new factor L ( // input: size_t n, // L is factorization of an n-by-n matrix @@ -1688,7 +1681,7 @@ cholmod_factor *cholmod_l_copy_factor (cholmod_factor *, cholmod_common *) ; int cholmod_factor_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_factor *L, // factor to change cholmod_common *Common @@ -1722,7 +1715,7 @@ cholmod_dense *cholmod_allocate_dense size_t nrow, // # of rows size_t ncol, // # of columns size_t d, // leading dimension - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1739,7 +1732,7 @@ cholmod_dense *cholmod_zeros // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1755,7 +1748,7 @@ cholmod_dense *cholmod_ones // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1771,7 +1764,7 @@ cholmod_dense *cholmod_eye // return a dense identity matrix // input: size_t nrow, // # of rows size_t ncol, // # of columns - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1802,7 +1795,7 @@ cholmod_dense *cholmod_ensure_dense size_t nrow, // # of rows size_t ncol, // # of columns size_t d, // leading dimension - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -1826,7 +1819,7 @@ cholmod_dense *cholmod_l_sparse_to_dense (cholmod_sparse *, cholmod_common *) ; // cholmod_dense_nnz: count # of nonzeros in a dense matrix //------------------------------------------------------------------------------ -int64_t cholmod_dense_nnz // return # of entries in the dense matrix // NEW +int64_t cholmod_dense_nnz // return # of entries in the dense matrix ( // input: cholmod_dense *X, // input matrix @@ -1842,7 +1835,7 @@ cholmod_sparse *cholmod_dense_to_sparse // return a sparse matrix C ( // input: cholmod_dense *X, // input matrix - int mode, // 1: copy the values NEW + int mode, // 1: copy the values // 0: C is pattern cholmod_common *Common ) ; @@ -1882,7 +1875,7 @@ int cholmod_l_copy_dense2 (cholmod_dense *, cholmod_dense *, cholmod_common *) ; int cholmod_dense_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_dense *X, // dense matrix to change cholmod_common *Common @@ -1927,7 +1920,7 @@ typedef struct cholmod_triplet_struct // if CHOLMOD_INT, these arrays are all of type int32_t. // if CHOLMOD_LONG, these arrays are all of type int64_t. int xtype ; // pattern, real, complex, or zomplex - int dtype ; // x and z are double or single // NEW + int dtype ; // x and z are double or single } cholmod_triplet ; @@ -1942,7 +1935,7 @@ cholmod_triplet *cholmod_allocate_triplet // return triplet matrix T size_t ncol, // # of columns size_t nzmax, // max # of entries the matrix can hold int stype, // the stype of the matrix (unsym, tril, or triu) - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) cholmod_common *Common @@ -2022,7 +2015,7 @@ cholmod_triplet *cholmod_l_copy_triplet (cholmod_triplet *, cholmod_common *) ; int cholmod_triplet_xtype ( // input: - int to_xdtype, // requested xtype and dtype // NEW + int to_xdtype, // requested xtype and dtype // input/output: cholmod_triplet *T, // triplet matrix to change cholmod_common *Common @@ -2089,7 +2082,7 @@ int cholmod_realloc_multiple // returns true if successful, false otherwise size_t nnew, // # of items in newly reallocate memory int nint, // 0: do not allocate I_block or J_block, 1: just I_block, // 2: both I_block and J_block - int xdtype, // xtype + dtype of the matrix: // NEW + int xdtype, // xtype + dtype of the matrix: // (CHOLMOD_DOUBLE, _SINGLE) + // (CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX) // input/output: @@ -2398,7 +2391,7 @@ int cholmod_l_print_parent (int64_t *, size_t, const char *, cholmod_common *) ; // cholmod_read_sparse: read a sparse matrix from a file (double only) //------------------------------------------------------------------------------ -cholmod_sparse *cholmod_read_sparse +cholmod_sparse *cholmod_read_sparse // return sparse matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2410,7 +2403,7 @@ cholmod_sparse *cholmod_l_read_sparse (FILE *, cholmod_common *) ; // cholmod_read_sparse2: read a sparse matrix from a file (float or double) //------------------------------------------------------------------------------ -cholmod_sparse *cholmod_read_sparse2 // NEW +cholmod_sparse *cholmod_read_sparse2 // return sparse matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2423,7 +2416,7 @@ cholmod_sparse *cholmod_l_read_sparse2 (FILE *, int, cholmod_common *) ; // cholmod_read_triplet: read a triplet matrix from a file (double only) //------------------------------------------------------------------------------ -cholmod_triplet *cholmod_read_triplet +cholmod_triplet *cholmod_read_triplet // return triplet matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2435,7 +2428,7 @@ cholmod_triplet *cholmod_l_read_triplet (FILE *, cholmod_common *) ; // cholmod_read_triplet: read a triplet matrix from a file (float or double) //------------------------------------------------------------------------------ -cholmod_triplet *cholmod_read_triplet2 // NEW +cholmod_triplet *cholmod_read_triplet2 // return triplet matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2448,7 +2441,7 @@ cholmod_triplet *cholmod_l_read_triplet2 (FILE *, int, cholmod_common *) ; // cholmod_read_dense: read a dense matrix from a file (double only) //------------------------------------------------------------------------------ -cholmod_dense *cholmod_read_dense +cholmod_dense *cholmod_read_dense // return dense matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2460,7 +2453,7 @@ cholmod_dense *cholmod_l_read_dense (FILE *, cholmod_common *) ; // cholmod_read_dense2: read a dense matrix from a file (float or double) //------------------------------------------------------------------------------ -cholmod_dense *cholmod_read_dense2 // NEW +cholmod_dense *cholmod_read_dense2 // return dense matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2473,7 +2466,7 @@ cholmod_dense *cholmod_l_read_dense2 (FILE *, int, cholmod_common *) ; // cholmod_read_matrix: read a sparse or dense matrix from a file (double only) //------------------------------------------------------------------------------ -void *cholmod_read_matrix +void *cholmod_read_matrix // return sparse/triplet/double matrix (double) ( // input: FILE *f, // file to read from, must already be open @@ -2498,7 +2491,7 @@ void *cholmod_l_read_matrix (FILE *, int, int *, cholmod_common *) ; // cholmod_read_matrix2: read a sparse or dense matrix (float or double) //------------------------------------------------------------------------------ -void *cholmod_read_matrix2 // NEW +void *cholmod_read_matrix2 // sparse/triplet/double matrix (double/single) ( // input: FILE *f, // file to read from, must already be open @@ -2638,6 +2631,8 @@ cholmod_factor *cholmod_l_analyze_p (cholmod_sparse *, int64_t *, int64_t *, // cholmod_analyze_p2: analyze for sparse Cholesky or sparse QR //------------------------------------------------------------------------------ +// This is normally not need by the user application. + cholmod_factor *cholmod_analyze_p2 ( // input: @@ -2875,7 +2870,7 @@ int cholmod_l_colamd (cholmod_sparse *, int64_t *, size_t, int, int64_t *, // identity matrix. Row k can only be factorized if all descendants of node // k in the elimination tree have been factorized. -int cholmod_rowfac +int cholmod_rowfac ( // input: cholmod_sparse *A, // matrix to factorize @@ -2894,8 +2889,9 @@ int cholmod_l_rowfac (cholmod_sparse *, cholmod_sparse *, double *, size_t, // cholmod_rowfac_mask: incremental simplicial factorization //------------------------------------------------------------------------------ -// cholmod_rowfac_mask is a version of cholmod_rowfac that is specific to -// LPDASA. It is unlikely to be needed by any other application. +// cholmod_rowfac_mask and cholmod_rowfac_mask2 are version of cholmod_rowfac +// that are specific to LPDASA. It is unlikely to be needed by any other +// application, and is not documented in the CHOLMOD User Guide. int cholmod_rowfac_mask ( @@ -3148,7 +3144,7 @@ cholmod_sparse *cholmod_horzcat // returns C = [A B] // input: cholmod_sparse *A, // left matrix to concatenate cholmod_sparse *B, // right matrix to concatenate - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern cholmod_common *Common @@ -3213,7 +3209,7 @@ cholmod_sparse *cholmod_ssmult // return C=A*B cholmod_sparse *A, // left matrix to multiply cholmod_sparse *B, // right matrix to multiply int stype, // requested stype of C - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern int sorted, // if TRUE then return C with sorted columns @@ -3243,7 +3239,7 @@ cholmod_sparse *cholmod_submatrix // return C = A (rset,cset) int64_t rsize, // size of rset, or -1 for ":" int32_t *cset, // set of column indices, duplicates OK int64_t csize, // size of cset, or -1 for ":" - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric. // 0: pattern int sorted, // if TRUE then return C with sorted columns @@ -3265,7 +3261,7 @@ cholmod_sparse *cholmod_vertcat // returns C = [A ; B] // input: cholmod_sparse *A, // top matrix to concatenate cholmod_sparse *B, // bottom matrix to concatenate - int mode, // 2: numerical (conj) if A and/or B are symmetric, NEW + int mode, // 2: numerical (conj) if A and/or B are symmetric, // 1: numerical (non-conj.) if A and/or B are symmetric // 0: pattern cholmod_common *Common @@ -3861,7 +3857,7 @@ int64_t cholmod_l_collapse_septree (size_t, size_t, double, size_t, int64_t *, // factorization. The user need not call this directly; cholmod_analyze is // a "simple" wrapper for this routine. -int cholmod_super_symbolic +int cholmod_super_symbolic ( // input: cholmod_sparse *A, // matrix to analyze diff --git a/CHOLMOD/MATLAB/analyze.m b/CHOLMOD/MATLAB/analyze.m index 3e612b5e3..49e032a48 100644 --- a/CHOLMOD/MATLAB/analyze.m +++ b/CHOLMOD/MATLAB/analyze.m @@ -58,9 +58,9 @@ % k = 9: also try COLAMD if ordering A'*A or A*A', AMD if ordering A % k > 9 is treated as k = 9 % -% See also metis, nesdis, bisect, symbfact, amd +% See also metis, nesdis, bisect, symbfact, amd. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('analyze mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/bisect.m b/CHOLMOD/MATLAB/bisect.m index 8b279b6c5..b1a66963d 100644 --- a/CHOLMOD/MATLAB/bisect.m +++ b/CHOLMOD/MATLAB/bisect.m @@ -17,9 +17,9 @@ % Requires METIS, authored by George Karypis, Univ. of Minnesota. This % MATLAB interface, via CHOLMOD, is by Tim Davis. % -% See also metis, nesdis +% See also metis, nesdis. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('bisect mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/chol2.m b/CHOLMOD/MATLAB/chol2.m index 01af88f8d..7303ffb33 100644 --- a/CHOLMOD/MATLAB/chol2.m +++ b/CHOLMOD/MATLAB/chol2.m @@ -15,7 +15,7 @@ % % See also lchol, ldlchol, chol, ldlupdate. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('chol2 mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/cholmod2.m b/CHOLMOD/MATLAB/cholmod2.m index 75f39354c..6a0813be5 100644 --- a/CHOLMOD/MATLAB/cholmod2.m +++ b/CHOLMOD/MATLAB/cholmod2.m @@ -37,7 +37,7 @@ % % See also chol, mldivide. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('cholmod2 mexFunction not found\n') ; diff --git a/CHOLMOD/MATLAB/cholmod_demo.m b/CHOLMOD/MATLAB/cholmod_demo.m index ae46988ce..6202c7d05 100644 --- a/CHOLMOD/MATLAB/cholmod_demo.m +++ b/CHOLMOD/MATLAB/cholmod_demo.m @@ -11,22 +11,22 @@ % Example: % cholmod_demo % -% See also bench +% See also bench. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ help cholmod_demo -% matrix from bench (n = 600 is used in 'bench'): + % matrix from bench (n = 600 is used in 'bench'): for n = [600 1200] A = delsq (numgrid ('L', n)) ; try_matrix (A) ; end -%------------------------------------------------------------------------- + %------------------------------------------------------------------------- function try_matrix (A) -% try_matrix: try a matrix with CHOLMOD + % try_matrix: try a matrix with CHOLMOD n = size (A,1) ; S = sparse (A) ; @@ -75,7 +75,7 @@ function try_matrix (A) fprintf ('CHOLMOD ldlupdate(sparse(A),C) time: %6.2f (rank-1, C dense)\n', t3) ; [L,D] = ldlsplit (LD2) ; -% err = norm ((S+C*C') - L*D*L', 1) / norm (S,1) ; + % err = norm ((S+C*C') - L*D*L', 1) / norm (S,1) ; err = ldl_normest ((S+C*C'), L, D) / norm (S,1) ; fprintf ('err: %g\n', err) ; @@ -89,13 +89,13 @@ function try_matrix (A) I = speye (n) ; S2 (k,:) = I (k,:) ; S2 (:,k) = I (:,k) ; -% err = norm (S2 - L*D*L', 1) / norm (S,1) ; + % err = norm (S2 - L*D*L', 1) / norm (S,1) ; err = ldl_normest (S2, L, D) / norm (S,1) ; fprintf ('err: %g\n', err) ; LD4 = ldlchol (S2) ; [L,D] = ldlsplit (LD4) ; -% err = norm (S2 - L*D*L', 1) / norm (S,1) ; + % err = norm (S2 - L*D*L', 1) / norm (S,1) ; err = ldl_normest (S2, L, D) / norm (S,1) ; fprintf ('err: %g\n', err) ; @@ -129,7 +129,7 @@ function try_matrix (A) return ; end -% tests with full matrices: + % tests with full matrices: X = full (C) ; E = full (A) ; tic diff --git a/CHOLMOD/MATLAB/cholmod_make.m b/CHOLMOD/MATLAB/cholmod_make.m index fccf60b84..ad75ccf11 100644 --- a/CHOLMOD/MATLAB/cholmod_make.m +++ b/CHOLMOD/MATLAB/cholmod_make.m @@ -12,8 +12,8 @@ % ldlsolve, ldlupdate, metis, spsym, nesdis, septree, resymbol, sdmult, % symbfact2, mread, mwrite, ldlrowmod. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ if verLessThan ('matlab', '9.4') error ('MATLAB 9.4 (R2018a) or later is required') ; @@ -32,7 +32,7 @@ mac = 0 ; end -% -R2018a: interleaved complex is required + % -R2018a: interleaved complex is required flags = '-O -R2018a -silent ' ; include = '-I. -I.. -I../../AMD/Include -I../../COLAMD/Include -I../../CCOLAMD/Include -I../../CAMD/Include -I../Include -I../../SuiteSparse_config' ; @@ -42,7 +42,7 @@ include = [include ' -D_FILE_OFFSET_BITS=64 -D_LARGEFILE64_SOURCE'] ; end -% Determine if METIS is available + % Determine if METIS is available have_metis = exist ('../SuiteSparse_metis', 'dir') ; if (have_metis) @@ -55,12 +55,12 @@ include = ['-DNPARTITION ' include] ; end -%--------------------------------------------------------------------------- -% BLAS option -%--------------------------------------------------------------------------- + %--------------------------------------------------------------------------- + % BLAS option + %--------------------------------------------------------------------------- -% This is exceedingly ugly. The MATLAB mex command needs to be told where to -% find the LAPACK and BLAS libraries, which is a real portability nightmare. + % This is exceedingly ugly. The MATLAB mex command needs to be told where to + % find the LAPACK and BLAS libraries, which is a real portability nightmare. if (pc) % BLAS/LAPACK functions have no underscore on Windows @@ -76,7 +76,7 @@ lapack = '-lmwlapack -lmwblas' ; end -% using the 64-bit BLAS + % using the 64-bit BLAS flags = [flags ' -DBLAS64'] ; if (~(pc || mac)) @@ -84,7 +84,7 @@ lapack = [lapack ' -lrt'] ; end -%------------------------------------------------------------------------------- + %------------------------------------------------------------------------------ config_src = { '../../SuiteSparse_config/SuiteSparse_config' } ; @@ -253,7 +253,7 @@ obj_extension = '.o' ; end -% compile each library source file + % compile each library source file obj = '' ; source = [sputil2 ordering_src config_src cholmod_src ] ; @@ -276,21 +276,21 @@ kk = do_cmd (s, kk, details, '.') ; end -% compile each mexFunction + % compile each mexFunction for f = cholmod_mex_src s = sprintf ('mex %s %s %s.c', flags, include, f{1}) ; s = [s obj ' ' lapack] ; %#ok kk = do_cmd (s, kk, details, ':') ; end -% clean up + % clean up s = ['delete ' obj] ; do_cmd (s, kk, details, '.') ; fprintf ('\nCHOLMOD successfully compiled\n') ; -%------------------------------------------------------------------------------ + %----------------------------------------------------------------------------- function kk = do_cmd (s, kk, details, progress) -%DO_CMD: evaluate a command, and either print it or print a "." + %DO_CMD: evaluate a command, and either print it or print a "." if (details) fprintf ('%s\n', s) ; else diff --git a/CHOLMOD/MATLAB/etree2.m b/CHOLMOD/MATLAB/etree2.m index f5d7c9af0..8409dfcb2 100644 --- a/CHOLMOD/MATLAB/etree2.m +++ b/CHOLMOD/MATLAB/etree2.m @@ -37,7 +37,7 @@ % % See also treelayout, treeplot, etreeplot, etree. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('etree2 mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/graph_demo.m b/CHOLMOD/MATLAB/graph_demo.m index f83bc06d6..41fc0a35a 100644 --- a/CHOLMOD/MATLAB/graph_demo.m +++ b/CHOLMOD/MATLAB/graph_demo.m @@ -8,8 +8,8 @@ function graph_demo (n) % % See also delsq, numgrid, gplot, treeplot. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ if (nargin < 1) % construct a 60-by-60 grid @@ -90,8 +90,7 @@ function graph_demo (n) end end -function my_gplot (A, x, y) -% my_gplot : like gplot, just a lot faster +function my_gplot (A, x, y) % like gplot, just a lot faster [i, j] = find (A) ; [~, p] = sort (max(i, j)) ; i = i (p) ; diff --git a/CHOLMOD/MATLAB/lchol.m b/CHOLMOD/MATLAB/lchol.m index d43b36ab9..a02974664 100644 --- a/CHOLMOD/MATLAB/lchol.m +++ b/CHOLMOD/MATLAB/lchol.m @@ -12,8 +12,8 @@ % % See also chol2, ldlchol, chol. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('lchol mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/ldl_normest.m b/CHOLMOD/MATLAB/ldl_normest.m index bdf85e273..51773c502 100644 --- a/CHOLMOD/MATLAB/ldl_normest.m +++ b/CHOLMOD/MATLAB/ldl_normest.m @@ -11,9 +11,9 @@ % % See also condest, normest. -% Copyright 2006-2023, William W. Hager and Timothy A. Davis, -% All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, William W. Hager and Timothy A. Davis, + % All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ [m,n] = size (A) ; diff --git a/CHOLMOD/MATLAB/ldlchol.m b/CHOLMOD/MATLAB/ldlchol.m index f6904e7d7..497124b81 100644 --- a/CHOLMOD/MATLAB/ldlchol.m +++ b/CHOLMOD/MATLAB/ldlchol.m @@ -9,8 +9,7 @@ % [LD,p] = ldlchol (A) similar [R,p] = chol(A), but for L*D*L' % [LD,p,q] = ldlchol (A) factorizes A(q,q) into L*D*L', where q is % a fill-reducing ordering -% LD = ldlchol (A,beta) return the LDL' factorization of -% A*A'+beta*I +% LD = ldlchol (A,beta) LDL' factorization of A*A'+beta*I % [LD,p] = ldlchol (A,beta) like [R,p] = chol(A*A'+beta+I) % [LD,p,q] = ldlchol (A,beta) factorizes A(q,:)*A(q,:)'+beta*I = L*D*L' % @@ -35,7 +34,7 @@ % % See also ldlupdate, ldlsolve, ldlsplit, chol2, lchol, chol. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('ldlchol mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/ldlrowmod.m b/CHOLMOD/MATLAB/ldlrowmod.m index 83c8fb002..c5de5abce 100644 --- a/CHOLMOD/MATLAB/ldlrowmod.m +++ b/CHOLMOD/MATLAB/ldlrowmod.m @@ -37,6 +37,7 @@ % ======================================================================== % ============================ WARNING =================================== % ======================================================================== +% % MATLAB drops zero entries from its sparse matrices. LD can contain % numerically zero entries that are symbolically present in the sparse % matrix data structure. These are essential for ldlrowmod and ldlsolve @@ -48,10 +49,9 @@ % MATLAB). It takes much more time to ensure this property holds than % the time it takes to do the row add/delete or the solve, so ldlrowmod % and ldlsolve simply assume the propertly holds. -% ======================================================================== -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('ldlrowmod mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/ldlsolve.m b/CHOLMOD/MATLAB/ldlsolve.m index 700b07f08..b5c8ad5d6 100644 --- a/CHOLMOD/MATLAB/ldlsolve.m +++ b/CHOLMOD/MATLAB/ldlsolve.m @@ -15,7 +15,7 @@ % % See also ldlchol, ldlupdate, ldlsplit, ldlrowmod. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('ldlsolve mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/ldlsplit.m b/CHOLMOD/MATLAB/ldlsplit.m index 698a7a67e..20c62915a 100644 --- a/CHOLMOD/MATLAB/ldlsplit.m +++ b/CHOLMOD/MATLAB/ldlsplit.m @@ -11,8 +11,8 @@ % % See also ldlchol, ldlsolve, ldlupdate. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ n = size (LD,1) ; D = diag (diag (LD)) ; diff --git a/CHOLMOD/MATLAB/ldlupdate.m b/CHOLMOD/MATLAB/ldlupdate.m index 69f198a22..9afba819f 100644 --- a/CHOLMOD/MATLAB/ldlupdate.m +++ b/CHOLMOD/MATLAB/ldlupdate.m @@ -36,6 +36,7 @@ % ======================================================================== % ============================ WARNING =================================== % ======================================================================== +% % MATLAB drops zero entries from its sparse matrices. LD can contain % numerically zero entries that are symbolically present in the sparse % matrix data structure. These are essential for ldlupdate and ldlsolve @@ -47,10 +48,9 @@ % MATLAB). It takes much more time to ensure this property holds than % the time it takes to do the update/downdate or the solve, so ldlupdate % and ldlsolve simply assume the propertly holds. -% ======================================================================== -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('ldlupdate mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/metis.m b/CHOLMOD/MATLAB/metis.m index ec6a0ee00..2a16711bc 100644 --- a/CHOLMOD/MATLAB/metis.m +++ b/CHOLMOD/MATLAB/metis.m @@ -18,7 +18,7 @@ % % See also nesdis, bisect. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('metis mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/mread.m b/CHOLMOD/MATLAB/mread.m index ac188d7b4..6c4f3218a 100644 --- a/CHOLMOD/MATLAB/mread.m +++ b/CHOLMOD/MATLAB/mread.m @@ -20,7 +20,7 @@ % % See also load. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('mread mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/mwrite.m b/CHOLMOD/MATLAB/mwrite.m index 01e184bc6..1ebe8f241 100644 --- a/CHOLMOD/MATLAB/mwrite.m +++ b/CHOLMOD/MATLAB/mwrite.m @@ -18,7 +18,7 @@ % % See also mread. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('mwrite mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/nesdis.m b/CHOLMOD/MATLAB/nesdis.m index 36e9a125a..f477a8903 100644 --- a/CHOLMOD/MATLAB/nesdis.m +++ b/CHOLMOD/MATLAB/nesdis.m @@ -51,7 +51,7 @@ % % See also metis, bisect, amd. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('nesdis mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/resymbol.m b/CHOLMOD/MATLAB/resymbol.m index 4267c3e36..52299914d 100644 --- a/CHOLMOD/MATLAB/resymbol.m +++ b/CHOLMOD/MATLAB/resymbol.m @@ -14,7 +14,7 @@ % % See also lchol, ldlupdate, ldlrowmod. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('resymbol not found') ; diff --git a/CHOLMOD/MATLAB/sdmult.m b/CHOLMOD/MATLAB/sdmult.m index 7c3532a98..4355694af 100644 --- a/CHOLMOD/MATLAB/sdmult.m +++ b/CHOLMOD/MATLAB/sdmult.m @@ -10,8 +10,8 @@ % % See also mtimes. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('sdmult mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/septree.m b/CHOLMOD/MATLAB/septree.m index 0703bf179..a2b50d71d 100644 --- a/CHOLMOD/MATLAB/septree.m +++ b/CHOLMOD/MATLAB/septree.m @@ -20,7 +20,7 @@ % % See also nesdis. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('septree mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/spsym.m b/CHOLMOD/MATLAB/spsym.m index b1eba9d37..962772590 100644 --- a/CHOLMOD/MATLAB/spsym.m +++ b/CHOLMOD/MATLAB/spsym.m @@ -21,63 +21,21 @@ % If quick is nonzero, then the function can return more quickly, as soon % as it finds a diagonal entry that is <= 0 or with a nonzero imaginary % part. In this case, it returns 2 for a square matrix, even if the -% matrix might otherwise be symmetric or Hermitian. -% -% Regardless of the value of "quick", this function returns 6 or 7 if A -% is a candidate for sparse Cholesky. -% -% For an MATLAB M-file function that computes the same thing as this -% mexFunction (but much slower), see the get_symmetry function by typing -% "type spsym". -% -% This spsym function does not compute the transpose of A, nor does it -% need to examine the entire matrix if it is unsymmetric. It uses very -% little memory as well (just size-n workspace, where n = size (A,1)). +% matrix might otherwise be symmetric or Hermitian. Regardless of the +% value of "quick", this function returns 6 or 7 if A is a candidate for +% sparse Cholesky. spsym does not compute the transpose of A, nor does +% it need to examine the entire matrix if it is unsymmetric. % % Examples: -% load west0479 -% A = west0479 ; -% spsym (A) -% spsym (A+A') -% spsym (A-A') -% spsym (A+A'+3*speye(size(A,1))) +% load west0479 +% A = west0479 ; +% spsym (A) +% spsym (A+A') +% spsym (A-A') +% spsym (A+A'+3*speye(size(A,1))) % -% See also mldivide. - -% function result = get_symmetry (A,quick) -% %GET_SYMMETRY: does the same thing as the spsym mexFunction -% [m n] = size (A) ; -% if (m ~= n) -% result = 1 ; % rectangular -% return -% end -% if (nargin < 2) -% quick = 0 ; -% end -% d = diag (A) ; -% posdiag = all (real (d) > 0) & all (imag (d) == 0) ; -% if (quick & ~posdiag) -% result = 2 ; % Not a candidate for sparse Cholesky. -% elseif (~isreal (A) & nnz (A-A') == 0) -% if (posdiag) -% result = 7 ; % complex Hermitian, with positive diagonal -% else -% result = 4 ; % complex Hermitian, nonpositive diagonal -% end -% elseif (nnz (A-A.') == 0) -% if (posdiag) -% result = 6 ; % symmetric with positive diagonal -% else -% result = 3 ; % symmetric, nonpositive diagonal -% end -% elseif (nnz (A+A.') == 0) -% result = 5 ; % skew symmetric -% else -% result = 2 ; % unsymmetric -% end - % With additional outputs, spsym computes the following for square -% matrices: (in this case "quick" is ignored, and set to zero): +% matrices (in this case "quick" is ignored, and treated as zero): % % [result xmatched pmatched nzoffdiag nnzdiag] = spsym(A) % @@ -90,8 +48,10 @@ % nzoffdiag, and nzdiag are not computed (all of them are returned as % zero). Note that a matched pair, A(i,j) and A(j,i) for i != j, is % counted twice (once per entry). +% +% See also mldivide. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('spsym mexFunction not found') ; diff --git a/CHOLMOD/MATLAB/symbfact2.m b/CHOLMOD/MATLAB/symbfact2.m index bdf84eae0..702bb26f0 100644 --- a/CHOLMOD/MATLAB/symbfact2.m +++ b/CHOLMOD/MATLAB/symbfact2.m @@ -42,8 +42,8 @@ % % See also chol, etree, treelayout, symbfact. -% Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. -% SPDX-License-Identifier: GPL-2.0+ + % Copyright 2006-2023, Timothy A. Davis, All Rights Reserved. + % SPDX-License-Identifier: GPL-2.0+ error ('symbfact2 mexFunction not found!') ; diff --git a/CHOLMOD/MatrixOps/cholmod_submatrix.c b/CHOLMOD/MatrixOps/cholmod_submatrix.c index 77d882eed..b699097b6 100644 --- a/CHOLMOD/MatrixOps/cholmod_submatrix.c +++ b/CHOLMOD/MatrixOps/cholmod_submatrix.c @@ -95,7 +95,7 @@ cholmod_sparse *CHOLMOD(submatrix) // return C = A (rset,cset) int64_t rsize, // size of rset, or -1 for ":" Int *cset, // set of column indices, duplicates OK int64_t csize, // size of cset, or -1 for ":" - int mode, // 2: numerical (conj) if A is symmetric, NEW + int mode, // 2: numerical (conj) if A is symmetric, // 1: numerical (non-conj.) if A is symmetric // 0: pattern int sorted, // if TRUE then return C with sorted columns diff --git a/CHOLMOD/MatrixOps/t_cholmod_sdmult_worker.c b/CHOLMOD/MatrixOps/t_cholmod_sdmult_worker.c index e6eeb8c6e..d7ad2f01f 100644 --- a/CHOLMOD/MatrixOps/t_cholmod_sdmult_worker.c +++ b/CHOLMOD/MatrixOps/t_cholmod_sdmult_worker.c @@ -422,7 +422,7 @@ static void TEMPLATE (cholmod_sdmult_worker) { //---------------------------------------------------------------------- - // Y += alpha * (A or A') * x, symmetric case (upper/lower) + // Y += alpha * A * x, symmetric case (upper/lower) //---------------------------------------------------------------------- // Only the upper/lower triangular part and the diagonal of A is used. diff --git a/CHOLMOD/README.txt b/CHOLMOD/README.txt index d38656e7b..1e243bd1e 100644 --- a/CHOLMOD/README.txt +++ b/CHOLMOD/README.txt @@ -13,8 +13,8 @@ http://www.suitesparse.com C and MATLAB interfaces. This code works on Microsoft Windows and many versions of Unix and Linux. -CHOLMOD v5.1 and later support single precision sparse matrices (both real and -complex), with the introduction of the new CHOLMOD:Utility Module. +CHOLMOD supports single precision sparse matrices (both real and complex), with +the introduction of the new CHOLMOD:Utility Module. One CHOLMOD Module is copyrighted by the University of Florida (the Partition Module). The rest are copyrighted by the authors: Timothy A. Davis (all of