Amesos Package Browser (Single Doxygen Collection) Development
amesos_cholmod_core.h
Go to the documentation of this file.
00001 /* ========================================================================== */
00002 /* === Include/cholmod_core.h =============================================== */
00003 /* ========================================================================== */
00004 
00005 /* -----------------------------------------------------------------------------
00006  * CHOLMOD/Include/cholmod_core.h.
00007  * Copyright (C) 2005-2006, Univ. of Florida.  Author: Timothy A. Davis
00008  * CHOLMOD/Include/cholmod_core.h is licensed under Version 2.1 of the GNU
00009  * Lesser General Public License.  See lesser.txt for a text of the license.
00010  * CHOLMOD is also available under other licenses; contact authors for details.
00011  * http://www.cise.ufl.edu/research/sparse
00012  * -------------------------------------------------------------------------- */
00013 
00014 /* CHOLMOD Core module: basic CHOLMOD objects and routines.
00015  * Required by all CHOLMOD modules.  Requires no other module or package.
00016  *
00017  * The CHOLMOD modules are:
00018  *
00019  * Core   basic data structures and definitions
00020  * Check  check/print the 5 CHOLMOD objects, & 3 types of integer vectors
00021  * Cholesky sparse Cholesky factorization
00022  * Modify sparse Cholesky update/downdate/row-add/row-delete
00023  * MatrixOps  sparse matrix functions (add, multiply, norm, ...)
00024  * Supernodal supernodal sparse Cholesky factorization
00025  * Partition  graph-partitioning based orderings
00026  *
00027  * The CHOLMOD objects:
00028  * --------------------
00029  *
00030  * cholmod_common   parameters, statistics, and workspace
00031  * cholmod_sparse   a sparse matrix in compressed column form
00032  * cholmod_factor   an LL' or LDL' factorization
00033  * cholmod_dense    a dense matrix
00034  * cholmod_triplet  a sparse matrix in "triplet" form
00035  *
00036  * The Core module described here defines the CHOLMOD data structures, and
00037  * basic operations on them.  To create and solve a sparse linear system Ax=b,
00038  * the user must create A and b, populate them with values, and then pass them
00039  * to the routines in the CHOLMOD Cholesky module.  There are two primary
00040  * methods for creating A: (1) allocate space for a column-oriented sparse
00041  * matrix and fill it with pattern and values, or (2) create a triplet form
00042  * matrix and convert it to a sparse matrix.  The latter option is simpler.
00043  *
00044  * The matrices b and x are typically dense matrices, but can also be sparse.
00045  * You can allocate and free them as dense matrices with the
00046  * cholmod_allocate_dense and cholmod_free_dense routines.
00047  *
00048  * The cholmod_factor object contains the symbolic and numeric LL' or LDL'
00049  * factorization of sparse symmetric matrix.  The matrix must be positive
00050  * definite for an LL' factorization.  It need only be symmetric and have well-
00051  * conditioned leading submatrices for it to have an LDL' factorization
00052  * (CHOLMOD does not pivot for numerical stability).  It is typically created
00053  * with the cholmod_factorize routine in the Cholesky module, but can also
00054  * be initialized to L=D=I in the Core module and then modified by the Modify
00055  * module.  It must be freed with cholmod_free_factor, defined below.
00056  *
00057  * The Core routines for each object are described below.  Each list is split
00058  * into two parts: the primary routines and secondary routines.
00059  *
00060  * ============================================================================
00061  * === cholmod_common =========================================================
00062  * ============================================================================
00063  *
00064  * The Common object contains control parameters, statistics, and
00065  * You must call cholmod_start before calling any other CHOLMOD routine, and
00066  * must call cholmod_finish as your last call to CHOLMOD, with two exceptions:
00067  * you may call cholmod_print_common and cholmod_check_common in the Check
00068  * module after calling cholmod_finish.
00069  *
00070  * cholmod_start    first call to CHOLMOD
00071  * cholmod_finish   last call to CHOLMOD
00072  * -----------------------------
00073  * cholmod_defaults   restore default parameters
00074  * cholmod_maxrank    maximum rank for update/downdate
00075  * cholmod_allocate_work  allocate workspace in Common
00076  * cholmod_free_work    free workspace in Common
00077  * cholmod_clear_flag   clear Flag workspace in Common
00078  * cholmod_error    called when CHOLMOD encounters an error
00079  * cholmod_dbound   for internal use in CHOLMOD only
00080  * cholmod_hypot    compute sqrt (x*x + y*y) accurately
00081  * cholmod_divcomplex   complex division, c = a/b
00082  *
00083  * ============================================================================
00084  * === cholmod_sparse =========================================================
00085  * ============================================================================
00086  *
00087  * A sparse matrix is held in compressed column form.  In the basic type
00088  * ("packed", which corresponds to a MATLAB sparse matrix), an n-by-n matrix
00089  * with nz entries is held in three arrays: p of size n+1, i of size nz, and x
00090  * of size nz.  Row indices of column j are held in i [p [j] ... p [j+1]-1] and
00091  * in the same locations in x.  There may be no duplicate entries in a column.
00092  * Row indices in each column may be sorted or unsorted (CHOLMOD keeps track).
00093  * A->stype determines the storage mode: 0 if both upper/lower parts are stored,
00094  * -1 if A is symmetric and just tril(A) is stored, +1 if symmetric and triu(A)
00095  * is stored.
00096  *
00097  * cholmod_allocate_sparse  allocate a sparse matrix
00098  * cholmod_free_sparse    free a sparse matrix
00099  * -----------------------------
00100  * cholmod_reallocate_sparse  change the size (# entries) of sparse matrix
00101  * cholmod_nnz      number of nonzeros in a sparse matrix
00102  * cholmod_speye    sparse identity matrix
00103  * cholmod_spzeros    sparse zero matrix
00104  * cholmod_transpose    transpose a sparse matrix
00105  * cholmod_ptranspose   transpose/permute a sparse matrix
00106  * cholmod_transpose_unsym  transpose/permute an unsymmetric sparse matrix
00107  * cholmod_transpose_sym  transpose/permute a symmetric sparse matrix
00108  * cholmod_sort     sort row indices in each column of sparse matrix
00109  * cholmod_band     C = tril (triu (A,k1), k2)
00110  * cholmod_band_inplace   A = tril (triu (A,k1), k2)
00111  * cholmod_aat      C = A*A'
00112  * cholmod_copy_sparse    C = A, create an exact copy of a sparse matrix
00113  * cholmod_copy     C = A, with possible change of stype
00114  * cholmod_add      C = alpha*A + beta*B
00115  * cholmod_sparse_xtype   change the xtype of a sparse matrix
00116  *
00117  * ============================================================================
00118  * === cholmod_factor =========================================================
00119  * ============================================================================
00120  *
00121  * The data structure for an LL' or LDL' factorization is too complex to
00122  * describe in one sentence.  This object can hold the symbolic analysis alone,
00123  * or in combination with a "simplicial" (similar to a sparse matrix) or
00124  * "supernodal" form of the numerical factorization.  Only the routine to free
00125  * a factor is primary, since a factor object is created by the factorization
00126  * routine (cholmod_factorize).  It must be freed with cholmod_free_factor.
00127  *
00128  * cholmod_free_factor    free a factor
00129  * -----------------------------
00130  * cholmod_allocate_factor  allocate a factor (LL' or LDL')
00131  * cholmod_reallocate_factor  change the # entries in a factor
00132  * cholmod_change_factor  change the type of factor (e.g., LDL' to LL')
00133  * cholmod_pack_factor    pack the columns of a factor
00134  * cholmod_reallocate_column  resize a single column of a factor
00135  * cholmod_factor_to_sparse create a sparse matrix copy of a factor
00136  * cholmod_copy_factor    create a copy of a factor
00137  * cholmod_factor_xtype   change the xtype of a factor
00138  *
00139  * Note that there is no cholmod_sparse_to_factor routine to create a factor
00140  * as a copy of a sparse matrix.  It could be done, after a fashion, but a
00141  * lower triangular sparse matrix would not necessarily have a chordal graph,
00142  * which would break the many CHOLMOD routines that rely on this property.
00143  *
00144  * ============================================================================
00145  * === cholmod_dense ==========================================================
00146  * ============================================================================
00147  *
00148  * The solve routines and some of the MatrixOps and Modify routines use dense
00149  * matrices as inputs.  These are held in column-major order.  With a leading
00150  * dimension of d, the entry in row i and column j is held in x [i+j*d].
00151  *
00152  * cholmod_allocate_dense allocate a dense matrix
00153  * cholmod_free_dense   free a dense matrix
00154  * -----------------------------
00155  * cholmod_zeros    allocate a dense matrix of all zeros
00156  * cholmod_ones     allocate a dense matrix of all ones
00157  * cholmod_eye      allocate a dense identity matrix
00158  * cholmod_sparse_to_dense  create a dense matrix copy of a sparse matrix
00159  * cholmod_dense_to_sparse  create a sparse matrix copy of a dense matrix
00160  * cholmod_copy_dense   create a copy of a dense matrix
00161  * cholmod_copy_dense2    copy a dense matrix (pre-allocated)
00162  * cholmod_dense_xtype    change the xtype of a dense matrix
00163  *
00164  * ============================================================================
00165  * === cholmod_triplet ========================================================
00166  * ============================================================================
00167  *
00168  * A sparse matrix held in triplet form is the simplest one for a user to
00169  * create.  It consists of a list of nz entries in arbitrary order, held in
00170  * three arrays: i, j, and x, each of length nk.  The kth entry is in row i[k],
00171  * column j[k], with value x[k].  There may be duplicate values; if A(i,j)
00172  * appears more than once, its value is the sum of the entries with those row
00173  * and column indices.
00174  *
00175  * cholmod_allocate_triplet allocate a triplet matrix
00176  * cholmod_triplet_to_sparse  create a sparse matrix copy of a triplet matrix
00177  * cholmod_free_triplet   free a triplet matrix
00178  * -----------------------------
00179  * cholmod_reallocate_triplet change the # of entries in a triplet matrix
00180  * cholmod_sparse_to_triplet  create a triplet matrix copy of a sparse matrix
00181  * cholmod_copy_triplet   create a copy of a triplet matrix
00182  * cholmod_triplet_xtype  change the xtype of a triplet matrix
00183  *
00184  * ============================================================================
00185  * === memory management ======================================================
00186  * ============================================================================
00187  *
00188  * cholmod_malloc   malloc wrapper
00189  * cholmod_calloc   calloc wrapper
00190  * cholmod_free     free wrapper
00191  * cholmod_realloc    realloc wrapper
00192  * cholmod_realloc_multiple realloc wrapper for multiple objects
00193  *
00194  * ============================================================================
00195  * === Core CHOLMOD prototypes ================================================
00196  * ============================================================================
00197  *
00198  * All CHOLMOD routines (in all modules) use the following protocol for return
00199  * values, with one exception:
00200  *
00201  * int      TRUE (1) if successful, or FALSE (0) otherwise.
00202  *      (exception: cholmod_divcomplex)
00203  * UF_long    a value >= 0 if successful, or -1 otherwise.
00204  * double   a value >= 0 if successful, or -1 otherwise.
00205  * size_t   a value > 0 if successful, or 0 otherwise.
00206  * void *   a non-NULL pointer to newly allocated memory if
00207  *      successful, or NULL otherwise.
00208  * cholmod_sparse * a non-NULL pointer to a newly allocated matrix
00209  *      if successful, or NULL otherwise.
00210  * cholmod_factor * a non-NULL pointer to a newly allocated factor
00211  *      if successful, or NULL otherwise.
00212  * cholmod_triplet *  a non-NULL pointer to a newly allocated triplet
00213  *      matrix if successful, or NULL otherwise.
00214  * cholmod_dense *  a non-NULL pointer to a newly allocated triplet
00215  *      matrix if successful, or NULL otherwise.
00216  *
00217  * The last parameter to all routines is always a pointer to the CHOLMOD
00218  * Common object.
00219  *
00220  * TRUE and FALSE are not defined here, since they may conflict with the user
00221  * program.  A routine that described here returning TRUE or FALSE returns 1
00222  * or 0, respectively.  Any TRUE/FALSE parameter is true if nonzero, false if
00223  * zero.
00224  */
00225 
00226 #ifndef AMESOS_CHOLMOD_CORE_H
00227 #define AMESOS_CHOLMOD_CORE_H
00228 
00229 /* ========================================================================== */
00230 /* === CHOLMOD version ====================================================== */
00231 /* ========================================================================== */
00232 
00233 /* All versions of CHOLMOD will include the following definitions.
00234  * As an example, to test if the version you are using is 1.3 or later:
00235  *
00236  *  if (CHOLMOD_VERSION >= CHOLMOD_VER_CODE (1,3)) ...
00237  *
00238  * This also works during compile-time:
00239  *
00240  *  #if CHOLMOD_VERSION >= CHOLMOD_VER_CODE (1,3)
00241  *      printf ("This is version 1.3 or later\n") ;
00242  *  #else
00243  *      printf ("This is version is earlier than 1.3\n") ;
00244  *  #endif
00245  */
00246 
00247 #define CHOLMOD_DATE "May 31, 2007"
00248 #define CHOLMOD_VER_CODE(main,sub) ((main) * 1000 + (sub))
00249 #define CHOLMOD_MAIN_VERSION 1
00250 #define CHOLMOD_SUB_VERSION 5
00251 #define CHOLMOD_SUBSUB_VERSION 0
00252 #define CHOLMOD_VERSION \
00253     CHOLMOD_VER_CODE(CHOLMOD_MAIN_VERSION,CHOLMOD_SUB_VERSION)
00254 
00255 
00256 /* ========================================================================== */
00257 /* === non-CHOLMOD include files ============================================ */
00258 /* ========================================================================== */
00259 
00260 /* This is the only non-CHOLMOD include file imposed on the user program.
00261  * It required for size_t definition used here.  CHOLMOD itself includes other
00262  * ANSI C89 standard #include files, but does not expose them to the user.
00263  *
00264  * CHOLMOD assumes that your C compiler is ANSI C89 compliant.  It does not make
00265  * use of ANSI C99 features.
00266  */
00267 
00268 #include <stddef.h>
00269 #include <stdlib.h>
00270 
00271 /* ========================================================================== */
00272 /* === CHOLMOD objects ====================================================== */
00273 /* ========================================================================== */
00274 
00275 /* Each CHOLMOD object has its own type code. */
00276 
00277 #define CHOLMOD_COMMON 0
00278 #define CHOLMOD_SPARSE 1
00279 #define CHOLMOD_FACTOR 2
00280 #define CHOLMOD_DENSE 3
00281 #define CHOLMOD_TRIPLET 4
00282 
00283 /* ========================================================================== */
00284 /* === CHOLMOD Common ======================================================= */
00285 /* ========================================================================== */
00286 
00287 /* itype defines the types of integer used: */
00288 #define CHOLMOD_INT 0   /* all integer arrays are int */
00289 #define CHOLMOD_INTLONG 1 /* most are int, some are UF_long */
00290 #define CHOLMOD_LONG 2    /* all integer arrays are UF_long */
00291 
00292 /* The itype of all parameters for all CHOLMOD routines must match.
00293  * FUTURE WORK: CHOLMOD_INTLONG is not yet supported.
00294  */
00295 
00296 /* dtype defines what the numerical type is (double or float): */
00297 #define CHOLMOD_DOUBLE 0  /* all numerical values are double */
00298 #define CHOLMOD_SINGLE 1  /* all numerical values are float */
00299 
00300 /* The dtype of all parameters for all CHOLMOD routines must match.
00301  *
00302  * Scalar floating-point values are always passed as double arrays of size 2
00303  * (for the real and imaginary parts).  They are typecast to float as needed.
00304  * FUTURE WORK: the float case is not supported yet.
00305  */
00306 
00307 /* xtype defines the kind of numerical values used: */
00308 #define CHOLMOD_PATTERN 0 /* pattern only, no numerical values */
00309 #define CHOLMOD_REAL 1    /* a real matrix */
00310 #define CHOLMOD_COMPLEX 2 /* a complex matrix (ANSI C99 compatible) */
00311 #define CHOLMOD_ZOMPLEX 3 /* a complex matrix (MATLAB compatible) */
00312 
00313 /* The xtype of all parameters for all CHOLMOD routines must match.
00314  *
00315  * CHOLMOD_PATTERN: x and z are ignored.
00316  * CHOLMOD_DOUBLE:  x is non-null of size nzmax, z is ignored.
00317  * CHOLMOD_COMPLEX: x is non-null of size 2*nzmax doubles, z is ignored.
00318  * CHOLMOD_ZOMPLEX: x and z are non-null of size nzmax
00319  *
00320  * In the real case, z is ignored.  The kth entry in the matrix is x [k].
00321  * There are two methods for the complex case.  In the ANSI C99-compatible
00322  * CHOLMOD_COMPLEX case, the real and imaginary parts of the kth entry
00323  * are in x [2*k] and x [2*k+1], respectively.  z is ignored.  In the
00324  * MATLAB-compatible CHOLMOD_ZOMPLEX case, the real and imaginary
00325  * parts of the kth entry are in x [k] and z [k].
00326  *
00327  * Scalar floating-point values are always passed as double arrays of size 2
00328  * (real and imaginary parts).  The imaginary part of a scalar is ignored if
00329  * the routine operates on a real matrix.
00330  *
00331  * These Modules support complex and zomplex matrices, with a few exceptions:
00332  *
00333  *  Check     all routines
00334  *  Cholesky    all routines
00335  *  Core      all except cholmod_aat, add, band, copy
00336  *  Demo      all routines
00337  *  Partition   all routines
00338  *  Supernodal  all routines support any real, complex, or zomplex input.
00339  *      There will never be a supernodal zomplex L; a complex
00340  *      supernodal L is created if A is zomplex.
00341  *  Tcov      all routines
00342  *  Valgrind    all routines
00343  *
00344  * These Modules provide partial support for complex and zomplex matrices:
00345  *
00346  *  MATLAB      all routines support real and zomplex only, not complex,
00347  *      with the exception of ldlupdate, which supports
00348  *      real matrices only.  This is a minor constraint since
00349  *      MATLAB's matrices are all real or zomplex.
00350  *  MatrixOps   only norm_dense, norm_sparse, and sdmult support complex
00351  *      and zomplex
00352  *
00353  * These Modules do not support complex and zomplex matrices at all:
00354  *
00355  *  Modify      all routines support real matrices only
00356  */
00357 
00358 /* Definitions for cholmod_common: */
00359 #define CHOLMOD_MAXMETHODS 9  /* maximum number of different methods that
00360          * cholmod_analyze can try. Must be >= 9. */
00361 
00362 /* Common->status values.  zero means success, negative means a fatal error,
00363  * positive is a warning. */
00364 #define CHOLMOD_OK 0      /* success */
00365 #define CHOLMOD_NOT_INSTALLED (-1)  /* failure: method not installed */
00366 #define CHOLMOD_OUT_OF_MEMORY (-2)  /* failure: out of memory */
00367 #define CHOLMOD_TOO_LARGE (-3)    /* failure: integer overflow occured */
00368 #define CHOLMOD_INVALID (-4)    /* failure: invalid input */
00369 #define CHOLMOD_NOT_POSDEF (1)    /* warning: matrix not pos. def. */
00370 #define CHOLMOD_DSMALL (2)    /* warning: D for LDL'  or diag(L) or
00371            * LL' has tiny absolute value */
00372 
00373 /* ordering method (also used for L->ordering) */
00374 #define CHOLMOD_NATURAL 0 /* use natural ordering */
00375 #define CHOLMOD_GIVEN 1   /* use given permutation */
00376 #define CHOLMOD_AMD 2   /* use minimum degree (AMD) */
00377 #define CHOLMOD_METIS 3   /* use METIS' nested dissection */
00378 #define CHOLMOD_NESDIS 4  /* use CHOLMOD's version of nested dissection:
00379          * node bisector applied recursively, followed
00380          * by constrained minimum degree (CSYMAMD or
00381          * CCOLAMD) */
00382 #define CHOLMOD_COLAMD 5  /* use AMD for A, COLAMD for A*A' */
00383 
00384 /* POSTORDERED is not a method, but a result of natural ordering followed by a
00385  * weighted postorder.  It is used for L->ordering, not method [ ].ordering. */
00386 #define CHOLMOD_POSTORDERED 6 /* natural ordering, postordered. */
00387 
00388 /* supernodal strategy (for Common->supernodal) */
00389 #define CHOLMOD_SIMPLICIAL 0  /* always do simplicial */
00390 #define CHOLMOD_AUTO 1    /* select simpl/super depending on matrix */
00391 #define CHOLMOD_SUPERNODAL 2  /* always do supernodal */
00392 
00393 typedef struct cholmod_common_struct
00394 {
00395     /* ---------------------------------------------------------------------- */
00396     /* parameters for symbolic/numeric factorization and update/downdate */
00397     /* ---------------------------------------------------------------------- */
00398 
00399     double dbound ; /* Smallest absolute value of diagonal entries of D
00400        * for LDL' factorization and update/downdate/rowadd/
00401   * rowdel, or the diagonal of L for an LL' factorization.
00402   * Entries in the range 0 to dbound are replaced with dbound.
00403   * Entries in the range -dbound to 0 are replaced with -dbound.  No
00404   * changes are made to the diagonal if dbound <= 0.  Default: zero */
00405 
00406     double grow0 ;  /* For a simplicial factorization, L->i and L->x can
00407        * grow if necessary.  grow0 is the factor by which
00408   * it grows.  For the initial space, L is of size MAX (1,grow0) times
00409   * the required space.  If L runs out of space, the new size of L is
00410   * MAX(1.2,grow0) times the new required space.   If you do not plan on
00411   * modifying the LDL' factorization in the Modify module, set grow0 to
00412   * zero (or set grow2 to 0, see below).  Default: 1.2 */
00413 
00414     double grow1 ;
00415 
00416     size_t grow2 ;  /* For a simplicial factorization, each column j of L
00417        * is initialized with space equal to
00418   * grow1*L->ColCount[j] + grow2.  If grow0 < 1, grow1 < 1, or grow2 == 0,
00419   * then the space allocated is exactly equal to L->ColCount[j].  If the
00420   * column j runs out of space, it increases to grow1*need + grow2 in
00421   * size, where need is the total # of nonzeros in that column.  If you do
00422   * not plan on modifying the factorization in the Modify module, set
00423   * grow2 to zero.  Default: grow1 = 1.2, grow2 = 5. */
00424 
00425     size_t maxrank ;  /* rank of maximum update/downdate.  Valid values:
00426        * 2, 4, or 8.  A value < 2 is set to 2, and a
00427   * value > 8 is set to 8.  It is then rounded up to the next highest
00428   * power of 2, if not already a power of 2.  Workspace (Xwork, below) of
00429   * size nrow-by-maxrank double's is allocated for the update/downdate.
00430   * If an update/downdate of rank-k is requested, with k > maxrank,
00431   * it is done in steps of maxrank.  Default: 8, which is fastest.
00432   * Memory usage can be reduced by setting maxrank to 2 or 4.
00433   */
00434 
00435     double supernodal_switch ;  /* supernodal vs simplicial factorization */
00436     int supernodal ;    /* If Common->supernodal <= CHOLMOD_SIMPLICIAL
00437          * (0) then cholmod_analyze performs a
00438   * simplicial analysis.  If >= CHOLMOD_SUPERNODAL (2), then a supernodal
00439   * analysis is performed.  If == CHOLMOD_AUTO (1) and
00440   * flop/nnz(L) < Common->supernodal_switch, then a simplicial analysis
00441   * is done.  A supernodal analysis done otherwise.
00442   * Default:  CHOLMOD_AUTO.  Default supernodal_switch = 40 */
00443 
00444     int final_asis ;  /* If TRUE, then ignore the other final_* parameters
00445        * (except for final_pack).
00446        * The factor is left as-is when done.  Default: TRUE.*/
00447 
00448     int final_super ; /* If TRUE, leave a factor in supernodal form when
00449        * supernodal factorization is finished.  If FALSE,
00450        * then convert to a simplicial factor when done.
00451        * Default: TRUE */
00452 
00453     int final_ll ;  /* If TRUE, leave factor in LL' form when done.
00454        * Otherwise, leave in LDL' form.  Default: FALSE */
00455 
00456     int final_pack ;  /* If TRUE, pack the columns when done.  If TRUE, and
00457        * cholmod_factorize is called with a symbolic L, L is
00458   * allocated with exactly the space required, using L->ColCount.  If you
00459   * plan on modifying the factorization, set Common->final_pack to FALSE,
00460   * and each column will be given a little extra slack space for future
00461   * growth in fill-in due to updates.  Default: TRUE */
00462 
00463     int final_monotonic ;   /* If TRUE, ensure columns are monotonic when done.
00464        * Default: TRUE */
00465 
00466     int final_resymbol ;/* if cholmod_factorize performed a supernodal
00467        * factorization, final_resymbol is true, and
00468   * final_super is FALSE (convert a simplicial numeric factorization),
00469   * then numerically zero entries that resulted from relaxed supernodal
00470   * amalgamation are removed.  This does not remove entries that are zero
00471   * due to exact numeric cancellation, since doing so would break the
00472   * update/downdate rowadd/rowdel routines.  Default: FALSE. */
00473 
00474     /* supernodal relaxed amalgamation parameters: */
00475     double zrelax [3] ;
00476     size_t nrelax [3] ;
00477 
00478   /* Let ns be the total number of columns in two adjacent supernodes.
00479    * Let z be the fraction of zero entries in the two supernodes if they
00480    * are merged (z includes zero entries from prior amalgamations).  The
00481    * two supernodes are merged if:
00482    *    (ns <= nrelax [0]) || (no new zero entries added) ||
00483    *    (ns <= nrelax [1] && z < zrelax [0]) ||
00484    *    (ns <= nrelax [2] && z < zrelax [1]) || (z < zrelax [2])
00485    *
00486    * Default parameters result in the following rule:
00487    *    (ns <= 4) || (no new zero entries added) ||
00488    *    (ns <= 16 && z < 0.8) || (ns <= 48 && z < 0.1) || (z < 0.05)
00489    */
00490 
00491     int prefer_zomplex ;    /* X = cholmod_solve (sys, L, B, Common) computes
00492            * x=A\b or solves a related system.  If L and B are
00493    * both real, then X is real.  Otherwise, X is returned as
00494    * CHOLMOD_COMPLEX if Common->prefer_zomplex is FALSE, or
00495    * CHOLMOD_ZOMPLEX if Common->prefer_zomplex is TRUE.  This parameter
00496    * is needed because there is no supernodal zomplex L.  Suppose the
00497    * caller wants all complex matrices to be stored in zomplex form
00498    * (MATLAB, for example).  A supernodal L is returned in complex form
00499    * if A is zomplex.  B can be real, and thus X = cholmod_solve (L,B)
00500    * should return X as zomplex.  This cannot be inferred from the input
00501    * arguments L and B.  Default: FALSE, since all data types are
00502    * supported in CHOLMOD_COMPLEX form and since this is the native type
00503    * of LAPACK and the BLAS.  Note that the MATLAB/cholmod.c mexFunction
00504    * sets this parameter to TRUE, since MATLAB matrices are in
00505    * CHOLMOD_ZOMPLEX form.
00506    */
00507 
00508     int prefer_upper ;      /* cholmod_analyze and cholmod_factorize work
00509            * fastest when a symmetric matrix is stored in
00510    * upper triangular form when a fill-reducing ordering is used.  In
00511    * MATLAB, this corresponds to how x=A\b works.  When the matrix is
00512    * ordered as-is, they work fastest when a symmetric matrix is in lower
00513    * triangular form.  In MATLAB, R=chol(A) does the opposite.  This
00514    * parameter affects only how cholmod_read returns a symmetric matrix.
00515    * If TRUE (the default case), a symmetric matrix is always returned in
00516    * upper-triangular form (A->stype = 1).  */
00517 
00518     int quick_return_if_not_posdef ;  /* if TRUE, the supernodal numeric
00519            * factorization will return quickly if
00520   * the matrix is not positive definite.  Default: FALSE. */
00521 
00522     /* ---------------------------------------------------------------------- */
00523     /* printing and error handling options */
00524     /* ---------------------------------------------------------------------- */
00525 
00526     int print ;   /* print level. Default: 3 */
00527     int precise ; /* if TRUE, print 16 digits.  Otherwise print 5 */
00528     int (*print_function) (const char *, ...) ; /* pointer to printf */
00529 
00530     int try_catch ; /* if TRUE, then ignore errors; CHOLMOD is in the middle
00531        * of a try/catch block.  No error message is printed
00532    * and the Common->error_handler function is not called. */
00533 
00534     void (*error_handler) (int status, char *file, int line, char *message) ;
00535 
00536   /* Common->error_handler is the user's error handling routine.  If not
00537    * NULL, this routine is called if an error occurs in CHOLMOD.  status
00538    * can be CHOLMOD_OK (0), negative for a fatal error, and positive for
00539    * a warning. file is a string containing the name of the source code
00540    * file where the error occured, and line is the line number in that
00541    * file.  message is a string describing the error in more detail. */
00542 
00543     /* ---------------------------------------------------------------------- */
00544     /* ordering options */
00545     /* ---------------------------------------------------------------------- */
00546 
00547     /* The cholmod_analyze routine can try many different orderings and select
00548      * the best one.  It can also try one ordering method multiple times, with
00549      * different parameter settings.  The default is to use three orderings,
00550      * the user's permutation (if provided), AMD which is the fastest ordering
00551      * and generally gives good fill-in, and METIS.  CHOLMOD's nested dissection
00552      * (METIS with a constrained AMD) usually gives a better ordering than METIS
00553      * alone (by about 5% to 10%) but it takes more time.
00554      *
00555      * If you know the method that is best for your matrix, set Common->nmethods
00556      * to 1 and set Common->method [0] to the set of parameters for that method.
00557      * If you set it to 1 and do not provide a permutation, then only AMD will
00558      * be called.
00559      *
00560      * If METIS is not available, the default # of methods tried is 2 (the user
00561      * permutation, if any, and AMD).
00562      *
00563      * To try other methods, set Common->nmethods to the number of methods you
00564      * want to try.  The suite of default methods and their parameters is
00565      * described in the cholmod_defaults routine, and summarized here:
00566      *
00567      *      Common->method [i]:
00568      *      i = 0: user-provided ordering (cholmod_analyze_p only)
00569      *      i = 1: AMD (for both A and A*A')
00570      *      i = 2: METIS
00571      *      i = 3: CHOLMOD's nested dissection (NESDIS), default parameters
00572      *      i = 4: natural
00573      *      i = 5: NESDIS with nd_small = 20000
00574      *      i = 6: NESDIS with nd_small = 4, no constrained minimum degree
00575      *      i = 7: NESDIS with no dense node removal
00576      *      i = 8: AMD for A, COLAMD for A*A'
00577      *
00578      * You can modify the suite of methods you wish to try by modifying
00579      * Common.method [...] after calling cholmod_start or cholmod_defaults.
00580      *
00581      * For example, to use AMD, followed by a weighted postordering:
00582      *
00583      *      Common->nmethods = 1 ;
00584      *      Common->method [0].ordering = CHOLMOD_AMD ;
00585      *      Common->postorder = TRUE ;
00586      *
00587      * To use the natural ordering (with no postordering):
00588      *
00589      *      Common->nmethods = 1 ;
00590      *      Common->method [0].ordering = CHOLMOD_NATURAL ;
00591      *      Common->postorder = FALSE ;
00592      *
00593      * If you are going to factorize hundreds or more matrices with the same
00594      * nonzero pattern, you may wish to spend a great deal of time finding a
00595      * good permutation.  In this case, try setting Common->nmethods to 9.
00596      * The time spent in cholmod_analysis will be very high, but you need to
00597      * call it only once.
00598      *
00599      * cholmod_analyze sets Common->current to a value between 0 and nmethods-1.
00600      * Each ordering method uses the set of options defined by this parameter.
00601      */
00602 
00603     int nmethods ;  /* The number of ordering methods to try.  Default: 0.
00604        * nmethods = 0 is a special case.  cholmod_analyze
00605   * will try the user-provided ordering (if given) and AMD.  Let fl and
00606   * lnz be the flop count and nonzeros in L from AMD's ordering.  Let
00607   * anz be the number of nonzeros in the upper or lower triangular part
00608   * of the symmetric matrix A.  If fl/lnz < 500 or lnz/anz < 5, then this
00609   * is a good ordering, and METIS is not attempted.  Otherwise, METIS is
00610   * tried.   The best ordering found is used.  If nmethods > 0, the
00611   * methods used are given in the method[ ] array, below.  The first
00612   * three methods in the default suite of orderings is (1) use the given
00613   * permutation (if provided), (2) use AMD, and (3) use METIS.  Maximum
00614   * allowed value is CHOLMOD_MAXMETHODS.  */
00615 
00616     int current ; /* The current method being tried.  Default: 0.  Valid
00617        * range is 0 to nmethods-1. */
00618 
00619     int selected ;  /* The best method found. */
00620 
00621     /* The suite of ordering methods and parameters: */
00622 
00623     struct cholmod_method_struct
00624     {
00625   /* statistics for this method */
00626   double lnz ;      /* nnz(L) excl. zeros from supernodal amalgamation,
00627            * for a "pure" L */
00628 
00629   double fl ;     /* flop count for a "pure", real simplicial LL'
00630            * factorization, with no extra work due to
00631       * amalgamation.  Subtract n to get the LDL' flop count.   Multiply
00632       * by about 4 if the matrix is complex or zomplex. */
00633 
00634   /* ordering method parameters */
00635   double prune_dense ;/* dense row/col control for AMD, SYMAMD, CSYMAMD,
00636            * and NESDIS (cholmod_nested_dissection).  For a
00637       * symmetric n-by-n matrix, rows/columns with more than
00638       * MAX (16, prune_dense * sqrt (n)) entries are removed prior to
00639       * ordering.  They appear at the end of the re-ordered matrix.
00640       *
00641       * If prune_dense < 0, only completely dense rows/cols are removed.
00642       *
00643       * This paramater is also the dense column control for COLAMD and
00644       * CCOLAMD.  For an m-by-n matrix, columns with more than
00645       * MAX (16, prune_dense * sqrt (MIN (m,n))) entries are removed prior
00646       * to ordering.  They appear at the end of the re-ordered matrix.
00647       * CHOLMOD factorizes A*A', so it calls COLAMD and CCOLAMD with A',
00648       * not A.  Thus, this parameter affects the dense *row* control for
00649       * CHOLMOD's matrix, and the dense *column* control for COLAMD and
00650       * CCOLAMD.
00651       *
00652       * Removing dense rows and columns improves the run-time of the
00653       * ordering methods.  It has some impact on ordering quality
00654       * (usually minimal, sometimes good, sometimes bad).
00655       *
00656       * Default: 10. */
00657 
00658   double prune_dense2 ;/* dense row control for COLAMD and CCOLAMD.
00659           *  Rows with more than MAX (16, dense2 * sqrt (n))
00660       * for an m-by-n matrix are removed prior to ordering.  CHOLMOD's
00661       * matrix is transposed before ordering it with COLAMD or CCOLAMD,
00662       * so this controls the dense *columns* of CHOLMOD's matrix, and
00663       * the dense *rows* of COLAMD's or CCOLAMD's matrix.
00664       *
00665       * If prune_dense2 < 0, only completely dense rows/cols are removed.
00666       *
00667       * Default: -1.  Note that this is not the default for COLAMD and
00668       * CCOLAMD.  -1 is best for Cholesky.  10 is best for LU.  */
00669 
00670   double nd_oksep ;   /* in NESDIS, when a node separator is computed, it
00671            * discarded if nsep >= nd_oksep*n, where nsep is
00672       * the number of nodes in the separator, and n is the size of the
00673       * graph being cut.  Valid range is 0 to 1.  If 1 or greater, the
00674       * separator is discarded if it consists of the entire graph.
00675       * Default: 1 */
00676 
00677   double other1 [4] ; /* future expansion */
00678 
00679   size_t nd_small ;    /* do not partition graphs with fewer nodes than
00680            * nd_small, in NESDIS.  Default: 200 (same as
00681            * METIS) */
00682 
00683   size_t other2 [4] ; /* future expansion */
00684 
00685   int aggressive ;    /* Aggresive absorption in AMD, COLAMD, SYMAMD,
00686            * CCOLAMD, and CSYMAMD.  Default: TRUE */
00687 
00688   int order_for_lu ;  /* CCOLAMD can be optimized to produce an ordering
00689            * for LU or Cholesky factorization.  CHOLMOD only
00690       * performs a Cholesky factorization.  However, you may wish to use
00691       * CHOLMOD as an interface for CCOLAMD but use it for your own LU
00692       * factorization.  In this case, order_for_lu should be set to FALSE.
00693       * When factorizing in CHOLMOD itself, you should *** NEVER *** set
00694       * this parameter FALSE.  Default: TRUE. */
00695 
00696   int nd_compress ;   /* If TRUE, compress the graph and subgraphs before
00697            * partitioning them in NESDIS.  Default: TRUE */
00698 
00699   int nd_camd ;     /* If 1, follow the nested dissection ordering
00700            * with a constrained minimum degree ordering that
00701       * respects the partitioning just found (using CAMD).  If 2, use
00702       * CSYMAMD instead.  If you set nd_small very small, you may not need
00703       * this ordering, and can save time by setting it to zero (no
00704       * constrained minimum degree ordering).  Default: 1. */
00705 
00706   int nd_components ; /* The nested dissection ordering finds a node
00707            * separator that splits the graph into two parts,
00708       * which may be unconnected.  If nd_components is TRUE, each of
00709       * these connected components is split independently.  If FALSE,
00710       * each part is split as a whole, even if it consists of more than
00711       * one connected component.  Default: FALSE */
00712 
00713   /* fill-reducing ordering to use */
00714   int ordering ;
00715 
00716   size_t other3 [4] ; /* future expansion */
00717 
00718     } method [CHOLMOD_MAXMETHODS + 1] ;
00719 
00720     int postorder ; /* If TRUE, cholmod_analyze follows the ordering with a
00721        * weighted postorder of the elimination tree.  Improves
00722   * supernode amalgamation.  Does not affect fundamental nnz(L) and
00723   * flop count.  Default: TRUE. */
00724 
00725     /* ---------------------------------------------------------------------- */
00726     /* memory management routines */
00727     /* ---------------------------------------------------------------------- */
00728 
00729     void *(*malloc_memory) (size_t) ;   /* pointer to malloc */
00730     void *(*realloc_memory) (void *, size_t) ;  /* pointer to realloc */
00731     void (*free_memory) (void *) ;    /* pointer to free */
00732     void *(*calloc_memory) (size_t, size_t) ; /* pointer to calloc */
00733 
00734     /* ---------------------------------------------------------------------- */
00735     /* routines for complex arithmetic */
00736     /* ---------------------------------------------------------------------- */
00737 
00738     int (*complex_divide) (double ax, double az, double bx, double bz,
00739       double *cx, double *cz) ;
00740 
00741   /* flag = complex_divide (ax, az, bx, bz, &cx, &cz) computes the complex
00742    * division c = a/b, where ax and az hold the real and imaginary part
00743    * of a, and b and c are stored similarly.  flag is returned as 1 if
00744    * a divide-by-zero occurs, or 0 otherwise.  By default, the function
00745    * pointer Common->complex_divide is set equal to cholmod_divcomplex.
00746    */
00747 
00748     double (*hypotenuse) (double x, double y) ;
00749 
00750   /* s = hypotenuse (x,y) computes s = sqrt (x*x + y*y), but does so more
00751    * accurately.  By default, the function pointer Common->hypotenuse is
00752    * set equal to cholmod_hypot.  See also the hypot function in the C99
00753    * standard, which has an identical syntax and function.  If you have
00754    * a C99-compliant compiler, you can set Common->hypotenuse = hypot.  */
00755 
00756     /* ---------------------------------------------------------------------- */
00757     /* METIS workarounds */
00758     /* ---------------------------------------------------------------------- */
00759 
00760     double metis_memory ;   /* This is a parameter for CHOLMOD's interface to
00761            * METIS, not a parameter to METIS itself.  METIS
00762   * uses an amount of memory that is difficult to estimate precisely
00763   * beforehand.  If it runs out of memory, it terminates your program.
00764   * All routines in CHOLMOD except for CHOLMOD's interface to METIS
00765   * return an error status and safely return to your program if they run
00766   * out of memory.  To mitigate this problem, the CHOLMOD interface
00767   * can allocate a single block of memory equal in size to an empirical
00768   * upper bound of METIS's memory usage times the Common->metis_memory
00769   * parameter, and then immediately free it.  It then calls METIS.  If
00770   * this pre-allocation fails, it is possible that METIS will fail as
00771   * well, and so CHOLMOD returns with an out-of-memory condition without
00772   * calling METIS.
00773   *
00774   * METIS_NodeND (used in the CHOLMOD_METIS ordering option) with its
00775   * default parameter settings typically uses about (4*nz+40n+4096)
00776   * times sizeof(int) memory, where nz is equal to the number of entries
00777   * in A for the symmetric case or AA' if an unsymmetric matrix is
00778   * being ordered (where nz includes both the upper and lower parts
00779   * of A or AA').  The observed "upper bound" (with 2 exceptions),
00780   * measured in an instrumented copy of METIS 4.0.1 on thousands of
00781   * matrices, is (10*nz+50*n+4096) * sizeof(int).  Two large matrices
00782   * exceeded this bound, one by almost a factor of 2 (Gupta/gupta2).
00783   *
00784   * If your program is terminated by METIS, try setting metis_memory to
00785   * 2.0, or even higher if needed.  By default, CHOLMOD assumes that METIS
00786   * does not have this problem (so that CHOLMOD will work correctly when
00787   * this issue is fixed in METIS).  Thus, the default value is zero.
00788   * This work-around is not guaranteed anyway.
00789   *
00790   * If a matrix exceeds this predicted memory usage, AMD is attempted
00791   * instead.  It, too, may run out of memory, but if it does so it will
00792   * not terminate your program.
00793   */
00794 
00795     double metis_dswitch ;  /* METIS_NodeND in METIS 4.0.1 gives a seg */
00796     size_t metis_nswitch ;  /* fault with one matrix of order n = 3005 and
00797          * nz = 6,036,025.  This is a very dense graph.
00798      * The workaround is to use AMD instead of METIS for matrices of dimension
00799      * greater than Common->metis_nswitch (default 3000) or more and with
00800      * density of Common->metis_dswitch (default 0.66) or more.
00801      * cholmod_nested_dissection has no problems with the same matrix, even
00802      * though it uses METIS_NodeComputeSeparator on this matrix.  If this
00803      * seg fault does not affect you, set metis_nswitch to zero or less,
00804      * and CHOLMOD will not switch to AMD based just on the density of the
00805      * matrix (it will still switch to AMD if the metis_memory parameter
00806      * causes the switch).
00807      */
00808 
00809     /* ---------------------------------------------------------------------- */
00810     /* workspace */
00811     /* ---------------------------------------------------------------------- */
00812 
00813     /* CHOLMOD has several routines that take less time than the size of
00814      * workspace they require.  Allocating and initializing the workspace would
00815      * dominate the run time, unless workspace is allocated and initialized
00816      * just once.  CHOLMOD allocates this space when needed, and holds it here
00817      * between calls to CHOLMOD.  cholmod_start sets these pointers to NULL
00818      * (which is why it must be the first routine called in CHOLMOD).
00819      * cholmod_finish frees the workspace (which is why it must be the last
00820      * call to CHOLMOD).
00821      */
00822 
00823     size_t nrow ; /* size of Flag and Head */
00824     UF_long mark ;  /* mark value for Flag array */
00825     size_t iworksize ;  /* size of Iwork.  Upper bound: 6*nrow+ncol */
00826     size_t xworksize ;  /* size of Xwork,  in bytes.
00827        * maxrank*nrow*sizeof(double) for update/downdate.
00828        * 2*nrow*sizeof(double) otherwise */
00829 
00830     /* initialized workspace: contents needed between calls to CHOLMOD */
00831     void *Flag ;  /* size nrow, an integer array.  Kept cleared between
00832        * calls to cholmod rouines (Flag [i] < mark) */
00833 
00834     void *Head ;  /* size nrow+1, an integer array. Kept cleared between
00835        * calls to cholmod routines (Head [i] = EMPTY) */
00836 
00837     void *Xwork ;   /* a double array.  Its size varies.  It is nrow for
00838        * most routines (cholmod_rowfac, cholmod_add,
00839   * cholmod_aat, cholmod_norm, cholmod_ssmult) for the real case, twice
00840   * that when the input matrices are complex or zomplex.  It is of size
00841   * 2*nrow for cholmod_rowadd and cholmod_rowdel.  For cholmod_updown,
00842   * its size is maxrank*nrow where maxrank is 2, 4, or 8.  Kept cleared
00843   * between calls to cholmod (set to zero). */
00844 
00845     /* uninitialized workspace, contents not needed between calls to CHOLMOD */
00846     void *Iwork ; /* size iworksize, 2*nrow+ncol for most routines,
00847        * up to 6*nrow+ncol for cholmod_analyze. */
00848 
00849     int itype ;   /* If CHOLMOD_LONG, Flag, Head, and Iwork are UF_long.
00850        * Otherwise all three arrays are int. */
00851 
00852     int dtype ;   /* double or float */
00853 
00854   /* Common->itype and Common->dtype are used to define the types of all
00855    * sparse matrices, triplet matrices, dense matrices, and factors
00856    * created using this Common struct.  The itypes and dtypes of all
00857    * parameters to all CHOLMOD routines must match.  */
00858 
00859     int no_workspace_reallocate ;   /* this is an internal flag, used as a
00860   * precaution by cholmod_analyze.  It is normally false.  If true,
00861   * cholmod_allocate_work is not allowed to reallocate any workspace;
00862   * they must use the existing workspace in Common (Iwork, Flag, Head,
00863   * and Xwork).  Added for CHOLMOD v1.1 */
00864 
00865     /* ---------------------------------------------------------------------- */
00866     /* statistics */
00867     /* ---------------------------------------------------------------------- */
00868 
00869     /* fl and lnz are set only in cholmod_analyze and cholmod_rowcolcounts,
00870      * in the Cholesky modudle.  modfl is set only in the Modify module. */
00871 
00872     int status ;      /* error code */
00873     double fl ;       /* LL' flop count from most recent analysis */
00874     double lnz ;      /* fundamental nz in L */
00875     double anz ;      /* nonzeros in tril(A) if A is symmetric/lower,
00876            * triu(A) if symmetric/upper, or tril(A*A') if
00877            * unsymmetric, in last call to cholmod_analyze. */
00878     double modfl ;      /* flop count from most recent update/downdate/
00879            * rowadd/rowdel (excluding flops to modify the
00880            * solution to Lx=b, if computed) */
00881     size_t malloc_count ;   /* # of objects malloc'ed minus the # free'd*/
00882     size_t memory_usage ;   /* peak memory usage in bytes */
00883     size_t memory_inuse ;   /* current memory usage in bytes */
00884 
00885     double nrealloc_col ;   /* # of column reallocations */
00886     double nrealloc_factor ;/* # of factor reallocations due to col. reallocs */
00887     double ndbounds_hit ;   /* # of times diagonal modified by dbound */
00888 
00889     double rowfacfl ;     /* # of flops in last call to cholmod_rowfac */
00890     double aatfl ;      /* # of flops to compute A(:,f)*A(:,f)' */
00891 
00892     /* ---------------------------------------------------------------------- */
00893     /* future expansion */
00894     /* ---------------------------------------------------------------------- */
00895 
00896     /* To allow CHOLMOD to be updated without recompiling the user application,
00897      * additional space is set aside here for future statistics, parameters,
00898      * and workspace.  Note:  additional entries were added in v1.1 to the
00899      * method array, above, and thus v1.0 and v1.1 are not binary compatible.
00900      *
00901      * v1.1 to the current version are binary compatible.
00902      */
00903 
00904     double  other1 [16] ;
00905     UF_long other2 [16] ;
00906     int     other3 [13] ;   /* reduced from size 16 in v1.1. */
00907 
00908     int prefer_binary ;     /* cholmod_read_triplet converts a symmetric
00909            * pattern-only matrix into a real matrix.  If
00910   * prefer_binary is FALSE, the diagonal entries are set to 1 + the degree
00911   * of the row/column, and off-diagonal entries are set to -1 (resulting
00912   * in a positive definite matrix if the diagonal is zero-free).  Most
00913   * symmetric patterns are the pattern a positive definite matrix.  If
00914   * this parameter is TRUE, then the matrix is returned with a 1 in each
00915   * entry, instead.  Default: FALSE.  Added in v1.3. */
00916 
00917     /* control parameter (added for v1.2): */
00918     int default_nesdis ;    /* Default: FALSE.  If FALSE, then the default
00919            * ordering strategy (when Common->nmethods == 0)
00920   * is to try the given ordering (if present), AMD, and then METIS if AMD
00921   * reports high fill-in.  If Common->default_nesdis is TRUE then NESDIS
00922   * is used instead in the default strategy. */
00923 
00924     /* statistic (added for v1.2): */
00925     int called_nd ;     /* TRUE if the last call to
00926            * cholmod_analyze called NESDIS or METIS. */
00927 
00928     size_t  other4 [16] ;
00929     void   *other5 [16] ;
00930 
00931 } cholmod_common ;
00932 
00933 /* -------------------------------------------------------------------------- */
00934 /* cholmod_start:  first call to CHOLMOD */
00935 /* -------------------------------------------------------------------------- */
00936 
00937 int amesos_cholmod_start
00938 (
00939     cholmod_common *Common
00940 ) ;
00941 
00942 int amesos_cholmod_l_start (cholmod_common *) ;
00943 
00944 /* -------------------------------------------------------------------------- */
00945 /* cholmod_finish:  last call to CHOLMOD */
00946 /* -------------------------------------------------------------------------- */
00947 
00948 int amesos_cholmod_finish
00949 (
00950     cholmod_common *Common
00951 ) ;
00952 
00953 int amesos_cholmod_l_finish (cholmod_common *) ;
00954 
00955 /* -------------------------------------------------------------------------- */
00956 /* cholmod_defaults:  restore default parameters */
00957 /* -------------------------------------------------------------------------- */
00958 
00959 int amesos_cholmod_defaults
00960 (
00961     cholmod_common *Common
00962 ) ;
00963 
00964 int amesos_cholmod_l_defaults (cholmod_common *) ;
00965 
00966 /* -------------------------------------------------------------------------- */
00967 /* cholmod_maxrank:  return valid maximum rank for update/downdate */
00968 /* -------------------------------------------------------------------------- */
00969 
00970 size_t amesos_cholmod_maxrank /* returns validated value of Common->maxrank */
00971 (
00972     /* ---- input ---- */
00973     size_t n,   /* A and L will have n rows */
00974     /* --------------- */
00975     cholmod_common *Common
00976 ) ;
00977 
00978 size_t amesos_cholmod_l_maxrank (size_t, cholmod_common *) ;
00979 
00980 /* -------------------------------------------------------------------------- */
00981 /* cholmod_allocate_work:  allocate workspace in Common */
00982 /* -------------------------------------------------------------------------- */
00983 
00984 int amesos_cholmod_allocate_work
00985 (
00986     /* ---- input ---- */
00987     size_t nrow,  /* size: Common->Flag (nrow), Common->Head (nrow+1) */
00988     size_t iworksize, /* size of Common->Iwork */
00989     size_t xworksize, /* size of Common->Xwork */
00990     /* --------------- */
00991     cholmod_common *Common
00992 ) ;
00993 
00994 int amesos_cholmod_l_allocate_work (size_t, size_t, size_t, cholmod_common *) ;
00995 
00996 /* -------------------------------------------------------------------------- */
00997 /* cholmod_free_work:  free workspace in Common */
00998 /* -------------------------------------------------------------------------- */
00999 
01000 int amesos_cholmod_free_work
01001 (
01002     cholmod_common *Common
01003 ) ;
01004 
01005 int amesos_cholmod_l_free_work (cholmod_common *) ;
01006 
01007 /* -------------------------------------------------------------------------- */
01008 /* cholmod_clear_flag:  clear Flag workspace in Common */
01009 /* -------------------------------------------------------------------------- */
01010 
01011 /* use a macro for speed */
01012 #define CHOLMOD_CLEAR_FLAG(Common) \
01013 { \
01014     Common->mark++ ; \
01015     if (Common->mark <= 0) \
01016     { \
01017         Common->mark = EMPTY ; \
01018         CHOLMOD (clear_flag) (Common) ; \
01019     } \
01020 }
01021 
01022 UF_long amesos_cholmod_clear_flag
01023 (
01024     cholmod_common *Common
01025 ) ;
01026 
01027 UF_long amesos_cholmod_l_clear_flag (cholmod_common *) ;
01028 
01029 /* -------------------------------------------------------------------------- */
01030 /* cholmod_error:  called when CHOLMOD encounters an error */
01031 /* -------------------------------------------------------------------------- */
01032 
01033 int amesos_cholmod_error
01034 (
01035     /* ---- input ---- */
01036     int status,   /* error status */
01037     char *file,   /* name of source code file where error occured */
01038     int line,   /* line number in source code file where error occured*/
01039     char *message,  /* error message */
01040     /* --------------- */
01041     cholmod_common *Common
01042 ) ;
01043 
01044 int amesos_cholmod_l_error (int, char *, int, char *, cholmod_common *) ;
01045 
01046 /* -------------------------------------------------------------------------- */
01047 /* cholmod_dbound:  for internal use in CHOLMOD only */
01048 /* -------------------------------------------------------------------------- */
01049 
01050 double amesos_cholmod_dbound  /* returns modified diagonal entry of D or L */
01051 (
01052     /* ---- input ---- */
01053     double dj,    /* diagonal entry of D for LDL' or L for LL' */
01054     /* --------------- */
01055     cholmod_common *Common
01056 ) ;
01057 
01058 double amesos_cholmod_l_dbound (double, cholmod_common *) ;
01059 
01060 /* -------------------------------------------------------------------------- */
01061 /* cholmod_hypot:  compute sqrt (x*x + y*y) accurately */
01062 /* -------------------------------------------------------------------------- */
01063 
01064 double amesos_cholmod_hypot
01065 (
01066     /* ---- input ---- */
01067     double x, double y
01068 ) ;
01069 
01070 double amesos_cholmod_l_hypot (double, double) ;
01071 
01072 /* -------------------------------------------------------------------------- */
01073 /* cholmod_divcomplex:  complex division, c = a/b */
01074 /* -------------------------------------------------------------------------- */
01075 
01076 int amesos_cholmod_divcomplex   /* return 1 if divide-by-zero, 0 otherise */
01077 (
01078     /* ---- input ---- */
01079     double ar, double ai, /* real and imaginary parts of a */
01080     double br, double bi, /* real and imaginary parts of b */
01081     /* ---- output --- */
01082     double *cr, double *ci  /* real and imaginary parts of c */
01083 ) ;
01084 
01085 int amesos_cholmod_l_divcomplex (double, double, double, double, double *, double *) ;
01086 
01087 
01088 /* ========================================================================== */
01089 /* === Core/cholmod_sparse ================================================== */
01090 /* ========================================================================== */
01091 
01092 /* A sparse matrix stored in compressed-column form. */
01093 
01094 typedef struct cholmod_sparse_struct
01095 {
01096     size_t nrow ; /* the matrix is nrow-by-ncol */
01097     size_t ncol ;
01098     size_t nzmax ;  /* maximum number of entries in the matrix */
01099 
01100     /* pointers to int or UF_long: */
01101     void *p ;   /* p [0..ncol], the column pointers */
01102     void *i ;   /* i [0..nzmax-1], the row indices */
01103 
01104     /* for unpacked matrices only: */
01105     void *nz ;    /* nz [0..ncol-1], the # of nonzeros in each col.  In
01106        * packed form, the nonzero pattern of column j is in
01107   * A->i [A->p [j] ... A->p [j+1]-1].  In unpacked form, column j is in
01108   * A->i [A->p [j] ... A->p [j]+A->nz[j]-1] instead.  In both cases, the
01109   * numerical values (if present) are in the corresponding locations in
01110   * the array x (or z if A->xtype is CHOLMOD_ZOMPLEX). */
01111 
01112     /* pointers to double or float: */
01113     void *x ;   /* size nzmax or 2*nzmax, if present */
01114     void *z ;   /* size nzmax, if present */
01115 
01116     int stype ;   /* Describes what parts of the matrix are considered:
01117        *
01118   * 0:  matrix is "unsymmetric": use both upper and lower triangular parts
01119   *     (the matrix may actually be symmetric in pattern and value, but
01120   *     both parts are explicitly stored and used).  May be square or
01121   *     rectangular.
01122   * >0: matrix is square and symmetric, use upper triangular part.
01123   *     Entries in the lower triangular part are ignored.
01124   * <0: matrix is square and symmetric, use lower triangular part.
01125   *     Entries in the upper triangular part are ignored.
01126   *
01127   * Note that stype>0 and stype<0 are different for cholmod_sparse and
01128   * cholmod_triplet.  See the cholmod_triplet data structure for more
01129   * details.
01130   */
01131 
01132     int itype ;   /* CHOLMOD_INT:     p, i, and nz are int.
01133        * CHOLMOD_INTLONG: p is UF_long, i and nz are int.
01134        * CHOLMOD_LONG:    p, i, and nz are UF_long.  */
01135 
01136     int xtype ;   /* pattern, real, complex, or zomplex */
01137     int dtype ;   /* x and z are double or float */
01138     int sorted ;  /* TRUE if columns are sorted, FALSE otherwise */
01139     int packed ;  /* TRUE if packed (nz ignored), FALSE if unpacked
01140        * (nz is required) */
01141 
01142 } cholmod_sparse ;
01143 
01144 /* -------------------------------------------------------------------------- */
01145 /* cholmod_allocate_sparse:  allocate a sparse matrix */
01146 /* -------------------------------------------------------------------------- */
01147 
01148 cholmod_sparse *amesos_cholmod_allocate_sparse
01149 (
01150     /* ---- input ---- */
01151     size_t nrow,  /* # of rows of A */
01152     size_t ncol,  /* # of columns of A */
01153     size_t nzmax, /* max # of nonzeros of A */
01154     int sorted,   /* TRUE if columns of A sorted, FALSE otherwise */
01155     int packed,   /* TRUE if A will be packed, FALSE otherwise */
01156     int stype,    /* stype of A */
01157     int xtype,    /* CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX */
01158     /* --------------- */
01159     cholmod_common *Common
01160 ) ;
01161 
01162 cholmod_sparse *amesos_cholmod_l_allocate_sparse (size_t, size_t, size_t, int, int,
01163     int, int, cholmod_common *) ;
01164 
01165 /* -------------------------------------------------------------------------- */
01166 /* cholmod_free_sparse:  free a sparse matrix */
01167 /* -------------------------------------------------------------------------- */
01168 
01169 int amesos_cholmod_free_sparse
01170 (
01171     /* ---- in/out --- */
01172     cholmod_sparse **A, /* matrix to deallocate, NULL on output */
01173     /* --------------- */
01174     cholmod_common *Common
01175 ) ;
01176 
01177 int amesos_cholmod_l_free_sparse (cholmod_sparse **, cholmod_common *) ;
01178 
01179 /* -------------------------------------------------------------------------- */
01180 /* cholmod_reallocate_sparse:  change the size (# entries) of sparse matrix */
01181 /* -------------------------------------------------------------------------- */
01182 
01183 int amesos_cholmod_reallocate_sparse
01184 (
01185     /* ---- input ---- */
01186     size_t nznew, /* new # of entries in A */
01187     /* ---- in/out --- */
01188     cholmod_sparse *A,  /* matrix to reallocate */
01189     /* --------------- */
01190     cholmod_common *Common
01191 ) ;
01192 
01193 int amesos_cholmod_l_reallocate_sparse ( size_t, cholmod_sparse *, cholmod_common *) ;
01194 
01195 /* -------------------------------------------------------------------------- */
01196 /* cholmod_nnz:  return number of nonzeros in a sparse matrix */
01197 /* -------------------------------------------------------------------------- */
01198 
01199 UF_long amesos_cholmod_nnz
01200 (
01201     /* ---- input ---- */
01202     cholmod_sparse *A,
01203     /* --------------- */
01204     cholmod_common *Common
01205 ) ;
01206 
01207 UF_long amesos_cholmod_l_nnz (cholmod_sparse *, cholmod_common *) ;
01208 
01209 /* -------------------------------------------------------------------------- */
01210 /* cholmod_speye:  sparse identity matrix */
01211 /* -------------------------------------------------------------------------- */
01212 
01213 cholmod_sparse *amesos_cholmod_speye
01214 (
01215     /* ---- input ---- */
01216     size_t nrow,  /* # of rows of A */
01217     size_t ncol,  /* # of columns of A */
01218     int xtype,    /* CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX */
01219     /* --------------- */
01220     cholmod_common *Common
01221 ) ;
01222 
01223 cholmod_sparse *amesos_cholmod_l_speye (size_t, size_t, int, cholmod_common *) ;
01224 
01225 /* -------------------------------------------------------------------------- */
01226 /* cholmod_spzeros:  sparse zero matrix */
01227 /* -------------------------------------------------------------------------- */
01228 
01229 cholmod_sparse *amesos_cholmod_spzeros
01230 (
01231     /* ---- input ---- */
01232     size_t nrow,  /* # of rows of A */
01233     size_t ncol,  /* # of columns of A */
01234     size_t nzmax, /* max # of nonzeros of A */
01235     int xtype,    /* CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX */
01236     /* --------------- */
01237     cholmod_common *Common
01238 ) ;
01239 
01240 cholmod_sparse *amesos_cholmod_l_spzeros (size_t, size_t, size_t, int,
01241     cholmod_common *) ;
01242 
01243 /* -------------------------------------------------------------------------- */
01244 /* cholmod_transpose:  transpose a sparse matrix */
01245 /* -------------------------------------------------------------------------- */
01246 
01247 /* Return A' or A.'  The "values" parameter is 0, 1, or 2 to denote the pattern
01248  * transpose, the array transpose (A.'), and the complex conjugate transpose
01249  * (A').
01250  */
01251 
01252 cholmod_sparse *amesos_cholmod_transpose
01253 (
01254     /* ---- input ---- */
01255     cholmod_sparse *A,  /* matrix to transpose */
01256     int values,   /* 0: pattern, 1: array transpose, 2: conj. transpose */
01257     /* --------------- */
01258     cholmod_common *Common
01259 ) ;
01260 
01261 cholmod_sparse *amesos_cholmod_l_transpose (cholmod_sparse *, int, cholmod_common *) ;
01262 
01263 /* -------------------------------------------------------------------------- */
01264 /* cholmod_transpose_unsym:  transpose an unsymmetric sparse matrix */
01265 /* -------------------------------------------------------------------------- */
01266 
01267 /* Compute F = A', A (:,f)', or A (p,f)', where A is unsymmetric and F is
01268  * already allocated.  See cholmod_transpose for a simpler routine. */
01269 
01270 int amesos_cholmod_transpose_unsym
01271 (
01272     /* ---- input ---- */
01273     cholmod_sparse *A,  /* matrix to transpose */
01274     int values,   /* 0: pattern, 1: array transpose, 2: conj. transpose */
01275     int *Perm,    /* size nrow, if present (can be NULL) */
01276     int *fset,    /* subset of 0:(A->ncol)-1 */
01277     size_t fsize, /* size of fset */
01278     /* ---- output --- */
01279     cholmod_sparse *F,  /* F = A', A(:,f)', or A(p,f)' */
01280     /* --------------- */
01281     cholmod_common *Common
01282 ) ;
01283 
01284 int amesos_cholmod_l_transpose_unsym (cholmod_sparse *, int, UF_long *, UF_long *,
01285     size_t, cholmod_sparse *, cholmod_common *) ;
01286 
01287 /* -------------------------------------------------------------------------- */
01288 /* cholmod_transpose_sym:  transpose a symmetric sparse matrix */
01289 /* -------------------------------------------------------------------------- */
01290 
01291 /* Compute F = A' or A (p,p)', where A is symmetric and F is already allocated.
01292  * See cholmod_transpose for a simpler routine. */
01293 
01294 int amesos_cholmod_transpose_sym
01295 (
01296     /* ---- input ---- */
01297     cholmod_sparse *A,  /* matrix to transpose */
01298     int values,   /* 0: pattern, 1: array transpose, 2: conj. transpose */
01299     int *Perm,    /* size nrow, if present (can be NULL) */
01300     /* ---- output --- */
01301     cholmod_sparse *F,  /* F = A' or A(p,p)' */
01302     /* --------------- */
01303     cholmod_common *Common
01304 ) ;
01305 
01306 int amesos_cholmod_l_transpose_sym (cholmod_sparse *, int, UF_long *, cholmod_sparse *,
01307     cholmod_common *) ;
01308 
01309 /* -------------------------------------------------------------------------- */
01310 /* cholmod_ptranspose:  transpose a sparse matrix */
01311 /* -------------------------------------------------------------------------- */
01312 
01313 /* Return A' or A(p,p)' if A is symmetric.  Return A', A(:,f)', or A(p,f)' if
01314  * A is unsymmetric. */
01315 
01316 cholmod_sparse *amesos_cholmod_ptranspose
01317 (
01318     /* ---- input ---- */
01319     cholmod_sparse *A,  /* matrix to transpose */
01320     int values,   /* 0: pattern, 1: array transpose, 2: conj. transpose */
01321     int *Perm,    /* if non-NULL, F = A(p,f) or A(p,p) */
01322     int *fset,    /* subset of 0:(A->ncol)-1 */
01323     size_t fsize, /* size of fset */
01324     /* --------------- */
01325     cholmod_common *Common
01326 ) ;
01327 
01328 cholmod_sparse *amesos_cholmod_l_ptranspose (cholmod_sparse *, int, UF_long *,
01329     UF_long *, size_t, cholmod_common *) ;
01330 
01331 /* -------------------------------------------------------------------------- */
01332 /* cholmod_sort:  sort row indices in each column of sparse matrix */
01333 /* -------------------------------------------------------------------------- */
01334 
01335 int amesos_cholmod_sort
01336 (
01337     /* ---- in/out --- */
01338     cholmod_sparse *A,  /* matrix to sort */
01339     /* --------------- */
01340     cholmod_common *Common
01341 ) ;
01342 
01343 int amesos_cholmod_l_sort (cholmod_sparse *, cholmod_common *) ;
01344 
01345 /* -------------------------------------------------------------------------- */
01346 /* cholmod_band:  C = tril (triu (A,k1), k2) */
01347 /* -------------------------------------------------------------------------- */
01348 
01349 cholmod_sparse *amesos_cholmod_band
01350 (
01351     /* ---- input ---- */
01352     cholmod_sparse *A,  /* matrix to extract band matrix from */
01353     UF_long k1,   /* ignore entries below the k1-st diagonal */
01354     UF_long k2,   /* ignore entries above the k2-nd diagonal */
01355     int mode,   /* >0: numerical, 0: pattern, <0: pattern (no diag) */
01356     /* --------------- */
01357     cholmod_common *Common
01358 ) ;
01359 
01360 cholmod_sparse *amesos_cholmod_l_band (cholmod_sparse *, UF_long, UF_long, int,
01361     cholmod_common *) ;
01362 
01363 /* -------------------------------------------------------------------------- */
01364 /* cholmod_band_inplace:  A = tril (triu (A,k1), k2) */
01365 /* -------------------------------------------------------------------------- */
01366 
01367 int amesos_cholmod_band_inplace
01368 (
01369     /* ---- input ---- */
01370     UF_long k1,   /* ignore entries below the k1-st diagonal */
01371     UF_long k2,   /* ignore entries above the k2-nd diagonal */
01372     int mode,   /* >0: numerical, 0: pattern, <0: pattern (no diag) */
01373     /* ---- in/out --- */
01374     cholmod_sparse *A,  /* matrix from which entries not in band are removed */
01375     /* --------------- */
01376     cholmod_common *Common
01377 ) ;
01378 
01379 int amesos_cholmod_l_band_inplace (UF_long, UF_long, int, cholmod_sparse *,
01380     cholmod_common *) ;
01381 
01382 /* -------------------------------------------------------------------------- */
01383 /* cholmod_aat:  C = A*A' or A(:,f)*A(:,f)' */
01384 /* -------------------------------------------------------------------------- */
01385 
01386 cholmod_sparse *amesos_cholmod_aat
01387 (
01388     /* ---- input ---- */
01389     cholmod_sparse *A,  /* input matrix; C=A*A' is constructed */
01390     int *fset,    /* subset of 0:(A->ncol)-1 */
01391     size_t fsize, /* size of fset */
01392     int mode,   /* >0: numerical, 0: pattern, <0: pattern (no diag),
01393        * -2: pattern only, no diagonal, add 50%+n extra
01394        * space to C */
01395     /* --------------- */
01396     cholmod_common *Common
01397 ) ;
01398 
01399 cholmod_sparse *amesos_cholmod_l_aat (cholmod_sparse *, UF_long *, size_t, int,
01400     cholmod_common *) ;
01401 
01402 /* -------------------------------------------------------------------------- */
01403 /* cholmod_copy_sparse:  C = A, create an exact copy of a sparse matrix */
01404 /* -------------------------------------------------------------------------- */
01405 
01406 cholmod_sparse *amesos_cholmod_copy_sparse
01407 (
01408     /* ---- input ---- */
01409     cholmod_sparse *A,  /* matrix to copy */
01410     /* --------------- */
01411     cholmod_common *Common
01412 ) ;
01413 
01414 cholmod_sparse *amesos_cholmod_l_copy_sparse (cholmod_sparse *, cholmod_common *) ;
01415 
01416 /* -------------------------------------------------------------------------- */
01417 /* cholmod_copy:  C = A, with possible change of stype */
01418 /* -------------------------------------------------------------------------- */
01419 
01420 cholmod_sparse *amesos_cholmod_copy 
01421 (
01422     /* ---- input ---- */
01423     cholmod_sparse *A,  /* matrix to copy */
01424     int stype,    /* requested stype of C */
01425     int mode,   /* >0: numerical, 0: pattern, <0: pattern (no diag) */
01426     /* --------------- */
01427     cholmod_common *Common
01428 ) ;
01429 
01430 cholmod_sparse *amesos_cholmod_l_copy (cholmod_sparse *, int, int, cholmod_common *) ;
01431 
01432 /* -------------------------------------------------------------------------- */
01433 /* cholmod_add: C = alpha*A + beta*B */
01434 /* -------------------------------------------------------------------------- */
01435 
01436 cholmod_sparse *amesos_cholmod_add
01437 (
01438     /* ---- input ---- */
01439     cholmod_sparse *A,      /* matrix to add */
01440     cholmod_sparse *B,      /* matrix to add */
01441     double alpha [2],     /* scale factor for A */
01442     double beta [2],      /* scale factor for B */
01443     int values,       /* if TRUE compute the numerical values of C */
01444     int sorted,       /* if TRUE, sort columns of C */
01445     /* --------------- */
01446     cholmod_common *Common
01447 ) ;
01448 
01449 cholmod_sparse *amesos_cholmod_l_add (cholmod_sparse *, cholmod_sparse *, double *,
01450     double *, int, int, cholmod_common *) ;
01451 
01452 /* -------------------------------------------------------------------------- */
01453 /* cholmod_sparse_xtype: change the xtype of a sparse matrix */
01454 /* -------------------------------------------------------------------------- */
01455 
01456 int amesos_cholmod_sparse_xtype
01457 (
01458     /* ---- input ---- */
01459     int to_xtype, /* requested xtype (pattern, real, complex, zomplex) */
01460     /* ---- in/out --- */
01461     cholmod_sparse *A,  /* sparse matrix to change */
01462     /* --------------- */
01463     cholmod_common *Common
01464 ) ;
01465 
01466 int amesos_cholmod_l_sparse_xtype (int, cholmod_sparse *, cholmod_common *) ;
01467 
01468 
01469 /* ========================================================================== */
01470 /* === Core/cholmod_factor ================================================== */
01471 /* ========================================================================== */
01472 
01473 /* A symbolic and numeric factorization, either simplicial or supernodal.
01474  * In all cases, the row indices in the columns of L are kept sorted. */
01475 
01476 typedef struct cholmod_factor_struct
01477 {
01478     /* ---------------------------------------------------------------------- */
01479     /* for both simplicial and supernodal factorizations */
01480     /* ---------------------------------------------------------------------- */
01481 
01482     size_t n ;    /* L is n-by-n */
01483 
01484     size_t minor ;  /* If the factorization failed, L->minor is the column
01485        * at which it failed (in the range 0 to n-1).  A value
01486        * of n means the factorization was successful or
01487        * the matrix has not yet been factorized. */
01488 
01489     /* ---------------------------------------------------------------------- */
01490     /* symbolic ordering and analysis */
01491     /* ---------------------------------------------------------------------- */
01492 
01493     void *Perm ;  /* size n, permutation used */
01494     void *ColCount ;  /* size n, column counts for simplicial L */
01495 
01496     /* ---------------------------------------------------------------------- */
01497     /* simplicial factorization */
01498     /* ---------------------------------------------------------------------- */
01499 
01500     size_t nzmax ;  /* size of i and x */
01501 
01502     void *p ;   /* p [0..ncol], the column pointers */
01503     void *i ;   /* i [0..nzmax-1], the row indices */
01504     void *x ;   /* x [0..nzmax-1], the numerical values */
01505     void *z ;
01506     void *nz ;    /* nz [0..ncol-1], the # of nonzeros in each column.
01507        * i [p [j] ... p [j]+nz[j]-1] contains the row indices,
01508        * and the numerical values are in the same locatins
01509        * in x. The value of i [p [k]] is always k. */
01510 
01511     void *next ;  /* size ncol+2. next [j] is the next column in i/x */
01512     void *prev ;  /* size ncol+2. prev [j] is the prior column in i/x.
01513        * head of the list is ncol+1, and the tail is ncol. */
01514 
01515     /* ---------------------------------------------------------------------- */
01516     /* supernodal factorization */
01517     /* ---------------------------------------------------------------------- */
01518 
01519     /* Note that L->x is shared with the simplicial data structure.  L->x has
01520      * size L->nzmax for a simplicial factor, and size L->xsize for a supernodal
01521      * factor. */
01522 
01523     size_t nsuper ; /* number of supernodes */
01524     size_t ssize ;  /* size of s, integer part of supernodes */
01525     size_t xsize ;  /* size of x, real part of supernodes */
01526     size_t maxcsize ; /* size of largest update matrix */
01527     size_t maxesize ; /* max # of rows in supernodes, excl. triangular part */
01528 
01529     void *super ; /* size nsuper+1, first col in each supernode */
01530     void *pi ;    /* size nsuper+1, pointers to integer patterns */
01531     void *px ;    /* size nsuper+1, pointers to real parts */
01532     void *s ;   /* size ssize, integer part of supernodes */
01533 
01534     /* ---------------------------------------------------------------------- */
01535     /* factorization type */
01536     /* ---------------------------------------------------------------------- */
01537 
01538     int ordering ;  /* ordering method used */
01539 
01540     int is_ll ;   /* TRUE if LL', FALSE if LDL' */
01541     int is_super ;  /* TRUE if supernodal, FALSE if simplicial */
01542     int is_monotonic ;  /* TRUE if columns of L appear in order 0..n-1.
01543        * Only applicable to simplicial numeric types. */
01544 
01545     /* There are 8 types of factor objects that cholmod_factor can represent
01546      * (only 6 are used):
01547      *
01548      * Numeric types (xtype is not CHOLMOD_PATTERN)
01549      * --------------------------------------------
01550      *
01551      * simplicial LDL':  (is_ll FALSE, is_super FALSE).  Stored in compressed
01552      *      column form, using the simplicial components above (nzmax, p, i,
01553      *      x, z, nz, next, and prev).  The unit diagonal of L is not stored,
01554      *      and D is stored in its place.  There are no supernodes.
01555      *
01556      * simplicial LL': (is_ll TRUE, is_super FALSE).  Uses the same storage
01557      *      scheme as the simplicial LDL', except that D does not appear.
01558      *      The first entry of each column of L is the diagonal entry of
01559      *      that column of L.
01560      *
01561      * supernodal LDL': (is_ll FALSE, is_super TRUE).  Not used.
01562      *      FUTURE WORK:  add support for supernodal LDL'
01563      *
01564      * supernodal LL': (is_ll TRUE, is_super TRUE).  A supernodal factor,
01565      *      using the supernodal components described above (nsuper, ssize,
01566      *      xsize, maxcsize, maxesize, super, pi, px, s, x, and z).
01567      *
01568      *
01569      * Symbolic types (xtype is CHOLMOD_PATTERN)
01570      * -----------------------------------------
01571      *
01572      * simplicial LDL': (is_ll FALSE, is_super FALSE).  Nothing is present
01573      *      except Perm and ColCount.
01574      *
01575      * simplicial LL': (is_ll TRUE, is_super FALSE).  Identical to the
01576      *      simplicial LDL', except for the is_ll flag.
01577      *
01578      * supernodal LDL': (is_ll FALSE, is_super TRUE).  Not used.
01579      *      FUTURE WORK:  add support for supernodal LDL'
01580      *
01581      * supernodal LL': (is_ll TRUE, is_super TRUE).  A supernodal symbolic
01582      *      factorization.  The simplicial symbolic information is present
01583      *      (Perm and ColCount), as is all of the supernodal factorization
01584      *      except for the numerical values (x and z).
01585      */
01586 
01587     int itype ;   /* The integer arrays are Perm, ColCount, p, i, nz,
01588        * next, prev, super, pi, px, and s.  If itype is
01589        * CHOLMOD_INT, all of these are int arrays.
01590        * CHOLMOD_INTLONG: p, pi, px are UF_long, others int.
01591        * CHOLMOD_LONG:    all integer arrays are UF_long. */
01592     int xtype ;   /* pattern, real, complex, or zomplex */
01593     int dtype ;   /* x and z double or float */
01594 
01595 } cholmod_factor ;
01596 
01597 
01598 /* -------------------------------------------------------------------------- */
01599 /* cholmod_allocate_factor: allocate a factor (symbolic LL' or LDL') */
01600 /* -------------------------------------------------------------------------- */
01601 
01602 cholmod_factor *amesos_cholmod_allocate_factor
01603 (
01604     /* ---- input ---- */
01605     size_t n,   /* L is n-by-n */
01606     /* --------------- */
01607     cholmod_common *Common
01608 ) ;
01609 
01610 cholmod_factor *amesos_cholmod_l_allocate_factor (size_t, cholmod_common *) ;
01611 
01612 /* -------------------------------------------------------------------------- */
01613 /* cholmod_free_factor:  free a factor */
01614 /* -------------------------------------------------------------------------- */
01615 
01616 int amesos_cholmod_free_factor
01617 (
01618     /* ---- in/out --- */
01619     cholmod_factor **L, /* factor to free, NULL on output */
01620     /* --------------- */
01621     cholmod_common *Common
01622 ) ;
01623 
01624 int amesos_cholmod_l_free_factor (cholmod_factor **, cholmod_common *) ;
01625 
01626 /* -------------------------------------------------------------------------- */
01627 /* cholmod_reallocate_factor:  change the # entries in a factor */
01628 /* -------------------------------------------------------------------------- */
01629 
01630 int amesos_cholmod_reallocate_factor
01631 (
01632     /* ---- input ---- */
01633     size_t nznew, /* new # of entries in L */
01634     /* ---- in/out --- */
01635     cholmod_factor *L,  /* factor to modify */
01636     /* --------------- */
01637     cholmod_common *Common
01638 ) ;
01639 
01640 int amesos_cholmod_l_reallocate_factor (size_t, cholmod_factor *, cholmod_common *) ;
01641 
01642 /* -------------------------------------------------------------------------- */
01643 /* cholmod_change_factor:  change the type of factor (e.g., LDL' to LL') */
01644 /* -------------------------------------------------------------------------- */
01645 
01646 int amesos_cholmod_change_factor
01647 (
01648     /* ---- input ---- */
01649     int to_xtype, /* to CHOLMOD_PATTERN, _REAL, _COMPLEX, _ZOMPLEX */
01650     int to_ll,    /* TRUE: convert to LL', FALSE: LDL' */
01651     int to_super, /* TRUE: convert to supernodal, FALSE: simplicial */
01652     int to_packed,  /* TRUE: pack simplicial columns, FALSE: do not pack */
01653     int to_monotonic, /* TRUE: put simplicial columns in order, FALSE: not */
01654     /* ---- in/out --- */
01655     cholmod_factor *L,  /* factor to modify */
01656     /* --------------- */
01657     cholmod_common *Common
01658 ) ;
01659 
01660 int amesos_cholmod_l_change_factor ( int, int, int, int, int, cholmod_factor *,
01661     cholmod_common *) ;
01662 
01663 /* -------------------------------------------------------------------------- */
01664 /* cholmod_pack_factor:  pack the columns of a factor */
01665 /* -------------------------------------------------------------------------- */
01666 
01667 /* Pack the columns of a simplicial factor.  Unlike cholmod_change_factor,
01668  * it can pack the columns of a factor even if they are not stored in their
01669  * natural order (non-monotonic). */
01670 
01671 int amesos_cholmod_pack_factor
01672 (
01673     /* ---- in/out --- */
01674     cholmod_factor *L,  /* factor to modify */
01675     /* --------------- */
01676     cholmod_common *Common
01677 ) ;
01678 
01679 int amesos_cholmod_l_pack_factor (cholmod_factor *, cholmod_common *) ;
01680 
01681 /* -------------------------------------------------------------------------- */
01682 /* cholmod_reallocate_column:  resize a single column of a factor */
01683 /* -------------------------------------------------------------------------- */
01684 
01685 int amesos_cholmod_reallocate_column
01686 (
01687     /* ---- input ---- */
01688     size_t j,   /* the column to reallocate */
01689     size_t need,  /* required size of column j */
01690     /* ---- in/out --- */
01691     cholmod_factor *L,  /* factor to modify */
01692     /* --------------- */
01693     cholmod_common *Common
01694 ) ;
01695 
01696 int amesos_cholmod_l_reallocate_column (size_t, size_t, cholmod_factor *,
01697     cholmod_common *) ;
01698 
01699 /* -------------------------------------------------------------------------- */
01700 /* cholmod_factor_to_sparse:  create a sparse matrix copy of a factor */
01701 /* -------------------------------------------------------------------------- */
01702 
01703 /* Only operates on numeric factors, not symbolic ones */
01704 
01705 cholmod_sparse *amesos_cholmod_factor_to_sparse
01706 (
01707     /* ---- in/out --- */
01708     cholmod_factor *L,  /* factor to copy, converted to symbolic on output */
01709     /* --------------- */
01710     cholmod_common *Common
01711 ) ;
01712 
01713 cholmod_sparse *amesos_cholmod_l_factor_to_sparse (cholmod_factor *,
01714   cholmod_common *) ;
01715 
01716 /* -------------------------------------------------------------------------- */
01717 /* cholmod_copy_factor:  create a copy of a factor */
01718 /* -------------------------------------------------------------------------- */
01719 
01720 cholmod_factor *amesos_cholmod_copy_factor
01721 (
01722     /* ---- input ---- */
01723     cholmod_factor *L,  /* factor to copy */
01724     /* --------------- */
01725     cholmod_common *Common
01726 ) ;
01727 
01728 cholmod_factor *amesos_cholmod_l_copy_factor (cholmod_factor *, cholmod_common *) ;
01729 
01730 /* -------------------------------------------------------------------------- */
01731 /* cholmod_factor_xtype: change the xtype of a factor */
01732 /* -------------------------------------------------------------------------- */
01733 
01734 int amesos_cholmod_factor_xtype
01735 (
01736     /* ---- input ---- */
01737     int to_xtype, /* requested xtype (real, complex, or zomplex) */
01738     /* ---- in/out --- */
01739     cholmod_factor *L,  /* factor to change */
01740     /* --------------- */
01741     cholmod_common *Common
01742 ) ;
01743 
01744 int amesos_cholmod_l_factor_xtype (int, cholmod_factor *, cholmod_common *) ;
01745 
01746 
01747 /* ========================================================================== */
01748 /* === Core/cholmod_dense =================================================== */
01749 /* ========================================================================== */
01750 
01751 /* A dense matrix in column-oriented form.  It has no itype since it contains
01752  * no integers.  Entry in row i and column j is located in x [i+j*d].
01753  */
01754 
01755 typedef struct cholmod_dense_struct
01756 {
01757     size_t nrow ; /* the matrix is nrow-by-ncol */
01758     size_t ncol ;
01759     size_t nzmax ;  /* maximum number of entries in the matrix */
01760     size_t d ;    /* leading dimension (d >= nrow must hold) */
01761     void *x ;   /* size nzmax or 2*nzmax, if present */
01762     void *z ;   /* size nzmax, if present */
01763     int xtype ;   /* pattern, real, complex, or zomplex */
01764     int dtype ;   /* x and z double or float */
01765 
01766 } cholmod_dense ;
01767 
01768 /* -------------------------------------------------------------------------- */
01769 /* cholmod_allocate_dense:  allocate a dense matrix (contents uninitialized) */
01770 /* -------------------------------------------------------------------------- */
01771 
01772 cholmod_dense *amesos_cholmod_allocate_dense
01773 (
01774     /* ---- input ---- */
01775     size_t nrow,  /* # of rows of matrix */
01776     size_t ncol,  /* # of columns of matrix */
01777     size_t d,   /* leading dimension */
01778     int xtype,    /* CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX */
01779     /* --------------- */
01780     cholmod_common *Common
01781 ) ;
01782 
01783 cholmod_dense *amesos_cholmod_l_allocate_dense (size_t, size_t, size_t, int,
01784     cholmod_common *) ;
01785 
01786 /* -------------------------------------------------------------------------- */
01787 /* cholmod_zeros: allocate a dense matrix and set it to zero */
01788 /* -------------------------------------------------------------------------- */
01789 
01790 cholmod_dense *amesos_cholmod_zeros
01791 (
01792     /* ---- input ---- */
01793     size_t nrow,  /* # of rows of matrix */
01794     size_t ncol,  /* # of columns of matrix */
01795     int xtype,    /* CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX */
01796     /* --------------- */
01797     cholmod_common *Common
01798 ) ;
01799 
01800 cholmod_dense *amesos_cholmod_l_zeros (size_t, size_t, int, cholmod_common *) ;
01801 
01802 /* -------------------------------------------------------------------------- */
01803 /* cholmod_ones: allocate a dense matrix and set it to all ones */
01804 /* -------------------------------------------------------------------------- */
01805 
01806 cholmod_dense *amesos_cholmod_ones
01807 (
01808     /* ---- input ---- */
01809     size_t nrow,  /* # of rows of matrix */
01810     size_t ncol,  /* # of columns of matrix */
01811     int xtype,    /* CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX */
01812     /* --------------- */
01813     cholmod_common *Common
01814 ) ;
01815 
01816 cholmod_dense *amesos_cholmod_l_ones (size_t, size_t, int, cholmod_common *) ;
01817 
01818 /* -------------------------------------------------------------------------- */
01819 /* cholmod_eye: allocate a dense matrix and set it to the identity matrix */
01820 /* -------------------------------------------------------------------------- */
01821 
01822 cholmod_dense *amesos_cholmod_eye
01823 (
01824     /* ---- input ---- */
01825     size_t nrow,  /* # of rows of matrix */
01826     size_t ncol,  /* # of columns of matrix */
01827     int xtype,    /* CHOLMOD_REAL, _COMPLEX, or _ZOMPLEX */
01828     /* --------------- */
01829     cholmod_common *Common
01830 ) ;
01831 
01832 cholmod_dense *amesos_cholmod_l_eye (size_t, size_t, int, cholmod_common *) ;
01833 
01834 /* -------------------------------------------------------------------------- */
01835 /* cholmod_free_dense:  free a dense matrix */
01836 /* -------------------------------------------------------------------------- */
01837 
01838 int amesos_cholmod_free_dense
01839 (
01840     /* ---- in/out --- */
01841     cholmod_dense **X,  /* dense matrix to deallocate, NULL on output */
01842     /* --------------- */
01843     cholmod_common *Common
01844 ) ;
01845 
01846 int amesos_cholmod_l_free_dense (cholmod_dense **, cholmod_common *) ;
01847 
01848 /* -------------------------------------------------------------------------- */
01849 /* cholmod_sparse_to_dense:  create a dense matrix copy of a sparse matrix */
01850 /* -------------------------------------------------------------------------- */
01851 
01852 cholmod_dense *amesos_cholmod_sparse_to_dense
01853 (
01854     /* ---- input ---- */
01855     cholmod_sparse *A,  /* matrix to copy */
01856     /* --------------- */
01857     cholmod_common *Common
01858 ) ;
01859 
01860 cholmod_dense *amesos_cholmod_l_sparse_to_dense (cholmod_sparse *,
01861     cholmod_common *) ;
01862 
01863 /* -------------------------------------------------------------------------- */
01864 /* cholmod_dense_to_sparse:  create a sparse matrix copy of a dense matrix */
01865 /* -------------------------------------------------------------------------- */
01866 
01867 cholmod_sparse *amesos_cholmod_dense_to_sparse
01868 (
01869     /* ---- input ---- */
01870     cholmod_dense *X, /* matrix to copy */
01871     int values,   /* TRUE if values to be copied, FALSE otherwise */
01872     /* --------------- */
01873     cholmod_common *Common
01874 ) ;
01875 
01876 cholmod_sparse *amesos_cholmod_l_dense_to_sparse (cholmod_dense *, int,
01877     cholmod_common *) ;
01878 
01879 /* -------------------------------------------------------------------------- */
01880 /* cholmod_copy_dense:  create a copy of a dense matrix */
01881 /* -------------------------------------------------------------------------- */
01882 
01883 cholmod_dense *amesos_cholmod_copy_dense
01884 (
01885     /* ---- input ---- */
01886     cholmod_dense *X, /* matrix to copy */
01887     /* --------------- */
01888     cholmod_common *Common
01889 ) ;
01890 
01891 cholmod_dense *amesos_cholmod_l_copy_dense (cholmod_dense *, cholmod_common *) ;
01892 
01893 /* -------------------------------------------------------------------------- */
01894 /* cholmod_copy_dense2:  copy a dense matrix (pre-allocated) */
01895 /* -------------------------------------------------------------------------- */
01896 
01897 int amesos_cholmod_copy_dense2
01898 (
01899     /* ---- input ---- */
01900     cholmod_dense *X, /* matrix to copy */
01901     /* ---- output --- */
01902     cholmod_dense *Y, /* copy of matrix X */
01903     /* --------------- */
01904     cholmod_common *Common
01905 ) ;
01906 
01907 int amesos_cholmod_l_copy_dense2 (cholmod_dense *, cholmod_dense *, cholmod_common *) ;
01908 
01909 /* -------------------------------------------------------------------------- */
01910 /* cholmod_dense_xtype: change the xtype of a dense matrix */
01911 /* -------------------------------------------------------------------------- */
01912 
01913 int amesos_cholmod_dense_xtype
01914 (
01915     /* ---- input ---- */
01916     int to_xtype, /* requested xtype (real, complex,or zomplex) */
01917     /* ---- in/out --- */
01918     cholmod_dense *X, /* dense matrix to change */
01919     /* --------------- */
01920     cholmod_common *Common
01921 ) ;
01922 
01923 int amesos_cholmod_l_dense_xtype (int, cholmod_dense *, cholmod_common *) ;
01924 
01925 
01926 /* ========================================================================== */
01927 /* === Core/cholmod_triplet ================================================= */
01928 /* ========================================================================== */
01929 
01930 /* A sparse matrix stored in triplet form. */
01931 
01932 typedef struct cholmod_triplet_struct
01933 {
01934     size_t nrow ; /* the matrix is nrow-by-ncol */
01935     size_t ncol ;
01936     size_t nzmax ;  /* maximum number of entries in the matrix */
01937     size_t nnz ;  /* number of nonzeros in the matrix */
01938 
01939     void *i ;   /* i [0..nzmax-1], the row indices */
01940     void *j ;   /* j [0..nzmax-1], the column indices */
01941     void *x ;   /* size nzmax or 2*nzmax, if present */
01942     void *z ;   /* size nzmax, if present */
01943 
01944     int stype ;   /* Describes what parts of the matrix are considered:
01945        *
01946   * 0:  matrix is "unsymmetric": use both upper and lower triangular parts
01947   *     (the matrix may actually be symmetric in pattern and value, but
01948   *     both parts are explicitly stored and used).  May be square or
01949   *     rectangular.
01950   * >0: matrix is square and symmetric.  Entries in the lower triangular
01951   *     part are transposed and added to the upper triangular part when
01952   *     the matrix is converted to cholmod_sparse form.
01953   * <0: matrix is square and symmetric.  Entries in the upper triangular
01954   *     part are transposed and added to the lower triangular part when
01955   *     the matrix is converted to cholmod_sparse form.
01956   *
01957   * Note that stype>0 and stype<0 are different for cholmod_sparse and
01958   * cholmod_triplet.  The reason is simple.  You can permute a symmetric
01959   * triplet matrix by simply replacing a row and column index with their
01960   * new row and column indices, via an inverse permutation.  Suppose
01961   * P = L->Perm is your permutation, and Pinv is an array of size n.
01962   * Suppose a symmetric matrix A is represent by a triplet matrix T, with
01963   * entries only in the upper triangular part.  Then the following code:
01964   *
01965   * Ti = T->i ;
01966   * Tj = T->j ;
01967   * for (k = 0 ; k < n  ; k++) Pinv [P [k]] = k ;
01968   * for (k = 0 ; k < nz ; k++) Ti [k] = Pinv [Ti [k]] ;
01969   * for (k = 0 ; k < nz ; k++) Tj [k] = Pinv [Tj [k]] ;
01970   *
01971   * creates the triplet form of C=P*A*P'.  However, if T initially
01972   * contains just the upper triangular entries (T->stype = 1), after
01973   * permutation it has entries in both the upper and lower triangular
01974   * parts.  These entries should be transposed when constructing the
01975   * cholmod_sparse form of A, which is what cholmod_triplet_to_sparse
01976   * does.  Thus:
01977   *
01978   * C = cholmod_triplet_to_sparse (T, 0, &Common) ;
01979   *
01980   * will return the matrix C = P*A*P'.
01981   *
01982   * Since the triplet matrix T is so simple to generate, it's quite easy
01983   * to remove entries that you do not want, prior to converting T to the
01984   * cholmod_sparse form.  So if you include these entries in T, CHOLMOD
01985   * assumes that there must be a reason (such as the one above).  Thus,
01986   * no entry in a triplet matrix is ever ignored.
01987   */
01988 
01989     int itype ;   /* CHOLMOD_LONG: i and j are UF_long.  Otherwise int. */
01990     int xtype ;   /* pattern, real, complex, or zomplex */
01991     int dtype ;   /* x and z are double or float */
01992 
01993 } cholmod_triplet ;
01994 
01995 /* -------------------------------------------------------------------------- */
01996 /* cholmod_allocate_triplet:  allocate a triplet matrix */
01997 /* -------------------------------------------------------------------------- */
01998 
01999 cholmod_triplet *amesos_cholmod_allocate_triplet
02000 (
02001     /* ---- input ---- */
02002     size_t nrow,  /* # of rows of T */
02003     size_t ncol,  /* # of columns of T */
02004     size_t nzmax, /* max # of nonzeros of T */
02005     int stype,    /* stype of T */
02006     int xtype,    /* CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX */
02007     /* --------------- */
02008     cholmod_common *Common
02009 ) ;
02010 
02011 cholmod_triplet *amesos_cholmod_l_allocate_triplet (size_t, size_t, size_t, int, int,
02012     cholmod_common *) ;
02013 
02014 /* -------------------------------------------------------------------------- */
02015 /* cholmod_free_triplet:  free a triplet matrix */
02016 /* -------------------------------------------------------------------------- */
02017 
02018 int amesos_cholmod_free_triplet
02019 (
02020     /* ---- in/out --- */
02021     cholmod_triplet **T,    /* triplet matrix to deallocate, NULL on output */
02022     /* --------------- */
02023     cholmod_common *Common
02024 ) ;
02025 
02026 int amesos_cholmod_l_free_triplet (cholmod_triplet **, cholmod_common *) ;
02027 
02028 /* -------------------------------------------------------------------------- */
02029 /* cholmod_reallocate_triplet:  change the # of entries in a triplet matrix */
02030 /* -------------------------------------------------------------------------- */
02031 
02032 int amesos_cholmod_reallocate_triplet
02033 (
02034     /* ---- input ---- */
02035     size_t nznew, /* new # of entries in T */
02036     /* ---- in/out --- */
02037     cholmod_triplet *T, /* triplet matrix to modify */
02038     /* --------------- */
02039     cholmod_common *Common
02040 ) ;
02041 
02042 int amesos_cholmod_l_reallocate_triplet (size_t, cholmod_triplet *, cholmod_common *) ;
02043 
02044 /* -------------------------------------------------------------------------- */
02045 /* cholmod_sparse_to_triplet:  create a triplet matrix copy of a sparse matrix*/
02046 /* -------------------------------------------------------------------------- */
02047 
02048 cholmod_triplet *amesos_cholmod_sparse_to_triplet
02049 (
02050     /* ---- input ---- */
02051     cholmod_sparse *A,  /* matrix to copy */
02052     /* --------------- */
02053     cholmod_common *Common
02054 ) ;
02055 
02056 cholmod_triplet *amesos_cholmod_l_sparse_to_triplet (cholmod_sparse *,
02057     cholmod_common *) ;
02058 
02059 /* -------------------------------------------------------------------------- */
02060 /* cholmod_triplet_to_sparse:  create a sparse matrix copy of a triplet matrix*/
02061 /* -------------------------------------------------------------------------- */
02062 
02063 cholmod_sparse *amesos_cholmod_triplet_to_sparse
02064 (
02065     /* ---- input ---- */
02066     cholmod_triplet *T, /* matrix to copy */
02067     size_t nzmax, /* allocate at least this much space in output matrix */
02068     /* --------------- */
02069     cholmod_common *Common
02070 ) ;
02071 
02072 cholmod_sparse *amesos_cholmod_l_triplet_to_sparse (cholmod_triplet *, size_t,
02073     cholmod_common *) ;
02074 
02075 /* -------------------------------------------------------------------------- */
02076 /* cholmod_copy_triplet:  create a copy of a triplet matrix */
02077 /* -------------------------------------------------------------------------- */
02078 
02079 cholmod_triplet *amesos_cholmod_copy_triplet
02080 (
02081     /* ---- input ---- */
02082     cholmod_triplet *T, /* matrix to copy */
02083     /* --------------- */
02084     cholmod_common *Common
02085 ) ;
02086 
02087 cholmod_triplet *amesos_cholmod_l_copy_triplet (cholmod_triplet *, cholmod_common *) ;
02088 
02089 /* -------------------------------------------------------------------------- */
02090 /* cholmod_triplet_xtype: change the xtype of a triplet matrix */
02091 /* -------------------------------------------------------------------------- */
02092 
02093 int amesos_cholmod_triplet_xtype
02094 (
02095     /* ---- input ---- */
02096     int to_xtype, /* requested xtype (pattern, real, complex,or zomplex)*/
02097     /* ---- in/out --- */
02098     cholmod_triplet *T, /* triplet matrix to change */
02099     /* --------------- */
02100     cholmod_common *Common
02101 ) ;
02102 
02103 int amesos_cholmod_l_triplet_xtype (int, cholmod_triplet *, cholmod_common *) ;
02104 
02105 
02106 /* ========================================================================== */
02107 /* === Core/cholmod_memory ================================================== */
02108 /* ========================================================================== */
02109 
02110 /* The user may make use of these, just like malloc and free.  You can even
02111  * malloc an object and safely free it with cholmod_free, and visa versa
02112  * (except that the memory usage statistics will be corrupted).  These routines
02113  * do differ from malloc and free.  If cholmod_free is given a NULL pointer,
02114  * for example, it does nothing (unlike the ANSI free).  cholmod_realloc does
02115  * not return NULL if given a non-NULL pointer and a nonzero size, even if it
02116  * fails (it returns the original pointer and sets an error code in
02117  * Common->status instead).
02118  *
02119  * CHOLMOD keeps track of the amount of memory it has allocated, and so the
02120  * cholmod_free routine also takes the size of the object being freed.  This
02121  * is only used for statistics.  If you, the user of CHOLMOD, pass the wrong
02122  * size, the only consequence is that the memory usage statistics will be
02123  * corrupted.
02124  */
02125 
02126 void *amesos_cholmod_malloc /* returns pointer to the newly malloc'd block */
02127 (
02128     /* ---- input ---- */
02129     size_t n,   /* number of items */
02130     size_t size,  /* size of each item */
02131     /* --------------- */
02132     cholmod_common *Common
02133 ) ;
02134 
02135 void *amesos_cholmod_l_malloc (size_t, size_t, cholmod_common *) ;
02136 
02137 void *amesos_cholmod_calloc /* returns pointer to the newly calloc'd block */
02138 (
02139     /* ---- input ---- */
02140     size_t n,   /* number of items */
02141     size_t size,  /* size of each item */
02142     /* --------------- */
02143     cholmod_common *Common
02144 ) ;
02145 
02146 void *amesos_cholmod_l_calloc (size_t, size_t, cholmod_common *) ;
02147 
02148 void *amesos_cholmod_free /* always returns NULL */
02149 (
02150     /* ---- input ---- */
02151     size_t n,   /* number of items */
02152     size_t size,  /* size of each item */
02153     /* ---- in/out --- */
02154     void *p,    /* block of memory to free */
02155     /* --------------- */
02156     cholmod_common *Common
02157 ) ;
02158 
02159 void *amesos_cholmod_l_free (size_t, size_t, void *, cholmod_common *) ;
02160 
02161 void *amesos_cholmod_realloc  /* returns pointer to reallocated block */
02162 (
02163     /* ---- input ---- */
02164     size_t nnew,  /* requested # of items in reallocated block */
02165     size_t size,  /* size of each item */
02166     /* ---- in/out --- */
02167     void *p,    /* block of memory to realloc */
02168     size_t *n,    /* current size on input, nnew on output if successful*/
02169     /* --------------- */
02170     cholmod_common *Common
02171 ) ;
02172 
02173 void *amesos_cholmod_l_realloc (size_t, size_t, void *, size_t *, cholmod_common *) ;
02174 
02175 int amesos_cholmod_realloc_multiple
02176 (
02177     /* ---- input ---- */
02178     size_t nnew,  /* requested # of items in reallocated blocks */
02179     int nint,   /* number of int/UF_long blocks */
02180     int xtype,    /* CHOLMOD_PATTERN, _REAL, _COMPLEX, or _ZOMPLEX */
02181     /* ---- in/out --- */
02182     void **I,   /* int or UF_long block */
02183     void **J,   /* int or UF_long block */
02184     void **X,   /* complex, double, or float block */
02185     void **Z,   /* zomplex case only: double or float block */
02186     size_t *n,    /* current size of the I,J,X,Z blocks on input,
02187        * nnew on output if successful */
02188     /* --------------- */
02189     cholmod_common *Common
02190 ) ;
02191 
02192 int amesos_cholmod_l_realloc_multiple (size_t, int, int, void **, void **, void **,
02193     void **, size_t *, cholmod_common *) ;
02194 
02195 /* ========================================================================== */
02196 /* === symmetry types ======================================================= */
02197 /* ========================================================================== */
02198 
02199 #define CHOLMOD_MM_RECTANGULAR 1
02200 #define CHOLMOD_MM_UNSYMMETRIC 2
02201 #define CHOLMOD_MM_SYMMETRIC 3
02202 #define CHOLMOD_MM_HERMITIAN 4
02203 #define CHOLMOD_MM_SKEW_SYMMETRIC 5
02204 #define CHOLMOD_MM_SYMMETRIC_POSDIAG 6
02205 #define CHOLMOD_MM_HERMITIAN_POSDIAG 7
02206 
02207 /* ========================================================================== */
02208 /* === Numerical relop macros =============================================== */
02209 /* ========================================================================== */
02210 
02211 /* These macros correctly handle the NaN case.
02212  *
02213  *  CHOLMOD_IS_NAN(x):
02214  *  True if x is NaN.  False otherwise.  The commonly-existing isnan(x)
02215  *  function could be used, but it's not in Kernighan & Ritchie 2nd edition
02216  *  (ANSI C89).  It may appear in <math.h>, but I'm not certain about
02217  *  portability.  The expression x != x is true if and only if x is NaN,
02218  *  according to the IEEE 754 floating-point standard.
02219  *
02220  *  CHOLMOD_IS_ZERO(x):
02221  *  True if x is zero.  False if x is nonzero, NaN, or +/- Inf.
02222  *  This is (x == 0) if the compiler is IEEE 754 compliant.
02223  *
02224  *  CHOLMOD_IS_NONZERO(x):
02225  *  True if x is nonzero, NaN, or +/- Inf.  False if x zero.
02226  *  This is (x != 0) if the compiler is IEEE 754 compliant.
02227  *
02228  *  CHOLMOD_IS_LT_ZERO(x):
02229  *  True if x is < zero or -Inf.  False if x is >= 0, NaN, or +Inf.
02230  *  This is (x < 0) if the compiler is IEEE 754 compliant.
02231  *
02232  *  CHOLMOD_IS_GT_ZERO(x):
02233  *  True if x is > zero or +Inf.  False if x is <= 0, NaN, or -Inf.
02234  *  This is (x > 0) if the compiler is IEEE 754 compliant.
02235  *
02236  *  CHOLMOD_IS_LE_ZERO(x):
02237  *  True if x is <= zero or -Inf.  False if x is > 0, NaN, or +Inf.
02238  *  This is (x <= 0) if the compiler is IEEE 754 compliant.
02239  */
02240 
02241 #ifdef CHOLMOD_WINDOWS
02242 
02243 /* Yes, this is exceedingly ugly.  Blame Microsoft, which hopelessly */
02244 /* violates the IEEE 754 floating-point standard in a bizarre way. */
02245 /* If you're using an IEEE 754-compliant compiler, then x != x is true */
02246 /* iff x is NaN.  For Microsoft, (x < x) is true iff x is NaN. */
02247 /* So either way, this macro safely detects a NaN. */
02248 #define CHOLMOD_IS_NAN(x) (((x) != (x)) || (((x) < (x))))
02249 #define CHOLMOD_IS_ZERO(x)  (((x) == 0.) && !CHOLMOD_IS_NAN(x))
02250 #define CHOLMOD_IS_NONZERO(x) (((x) != 0.) || CHOLMOD_IS_NAN(x))
02251 #define CHOLMOD_IS_LT_ZERO(x) (((x) < 0.) && !CHOLMOD_IS_NAN(x))
02252 #define CHOLMOD_IS_GT_ZERO(x) (((x) > 0.) && !CHOLMOD_IS_NAN(x))
02253 #define CHOLMOD_IS_LE_ZERO(x) (((x) <= 0.) && !CHOLMOD_IS_NAN(x))
02254 
02255 #else
02256 
02257 /* These all work properly, according to the IEEE 754 standard ... except on */
02258 /* a PC with windows.  Works fine in Linux on the same PC... */
02259 #define CHOLMOD_IS_NAN(x) ((x) != (x))
02260 #define CHOLMOD_IS_ZERO(x)  ((x) == 0.)
02261 #define CHOLMOD_IS_NONZERO(x) ((x) != 0.)
02262 #define CHOLMOD_IS_LT_ZERO(x) ((x) < 0.)
02263 #define CHOLMOD_IS_GT_ZERO(x) ((x) > 0.)
02264 #define CHOLMOD_IS_LE_ZERO(x) ((x) <= 0.)
02265 
02266 #endif
02267 
02268 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines