- Main Page
- Data Structures
- Files

# SRC/colamd.h

Go to the documentation of this file.

    00001
    00055 #ifndef COLAMD_H
    00056 #define COLAMD_H
    00057
    00058 /* ========================================================================== */
    00059 /* === Include files ======================================================== */
    00060 /* ========================================================================== */
    00061
    00062 #include <stdlib.h>
    00063
    00064 /* ========================================================================== */
    00065 /* === Knob and statistics definitions ====================================== */
    00066 /* ========================================================================== */
    00067
    00068 /* size of the knobs [ ] array.  Only knobs [0..1] are currently used. */
    00069 #define COLAMD_KNOBS 20
    00070
    00071 /* number of output statistics.  Only stats [0..6] are currently used. */
    00072 #define COLAMD_STATS 20
    00073
    00074 /* knobs [0] and stats [0]: dense row knob and output statistic. */
    00075 #define COLAMD_DENSE_ROW 0
    00076
    00077 /* knobs [1] and stats [1]: dense column knob and output statistic. */
    00078 #define COLAMD_DENSE_COL 1
    00079
    00080 /* stats [2]: memory defragmentation count output statistic */
    00081 #define COLAMD_DEFRAG_COUNT 2
    00082
    00083 /* stats [3]: colamd status:  zero OK, > 0 warning or notice, < 0 error */
    00084 #define COLAMD_STATUS 3
    00085
    00086 /* stats [4..6]: error info, or info on jumbled columns */
    00087 #define COLAMD_INFO1 4
    00088 #define COLAMD_INFO2 5
    00089 #define COLAMD_INFO3 6
    00090
    00091 /* error codes returned in stats [3]: */
    00092 #define COLAMD_OK                               (0)
    00093 #define COLAMD_OK_BUT_JUMBLED                   (1)
    00094 #define COLAMD_ERROR_A_not_present              (-1)
    00095 #define COLAMD_ERROR_p_not_present              (-2)
    00096 #define COLAMD_ERROR_nrow_negative              (-3)
    00097 #define COLAMD_ERROR_ncol_negative              (-4)
    00098 #define COLAMD_ERROR_nnz_negative               (-5)
    00099 #define COLAMD_ERROR_p0_nonzero                 (-6)
    00100 #define COLAMD_ERROR_A_too_small                (-7)
    00101 #define COLAMD_ERROR_col_length_negative        (-8)
    00102 #define COLAMD_ERROR_row_index_out_of_bounds    (-9)
    00103 #define COLAMD_ERROR_out_of_memory              (-10)
    00104 #define COLAMD_ERROR_internal_error             (-999)
    00105
    00106 /* ========================================================================== */
    00107 /* === Row and Column structures ============================================ */
    00108 /* ========================================================================== */
    00109
    00110 /* User code that makes use of the colamd/symamd routines need not directly */
    00111 /* reference these structures.  They are used only for the COLAMD_RECOMMENDED */
    00112 /* macro. */
    00113
    00114 typedef struct Colamd_Col_struct
    00115 {
    00116     int start ;         /* index for A of first row in this column, or DEAD */
    00117                         /* if column is dead */
    00118     int length ;        /* number of rows in this column */
    00119     union
    00120     {
    00121         int thickness ; /* number of original columns represented by this */
    00122                         /* col, if the column is alive */
    00123         int parent ;    /* parent in parent tree super-column structure, if */
    00124                         /* the column is dead */
    00125     } shared1 ;
    00126     union
    00127     {
    00128         int score ;     /* the score used to maintain heap, if col is alive */
    00129         int order ;     /* pivot ordering of this column, if col is dead */
    00130     } shared2 ;
    00131     union
    00132     {
    00133         int headhash ;  /* head of a hash bucket, if col is at the head of */
    00134                         /* a degree list */
    00135         int hash ;      /* hash value, if col is not in a degree list */
    00136         int prev ;      /* previous column in degree list, if col is in a */
    00137                         /* degree list (but not at the head of a degree list) */
    00138     } shared3 ;
    00139     union
    00140     {
    00141         int degree_next ;       /* next column, if col is in a degree list */
    00142         int hash_next ;         /* next column, if col is in a hash list */
    00143     } shared4 ;
    00144
    00145 } Colamd_Col ;
    00146
    00147 typedef struct Colamd_Row_struct
    00148 {
    00149     int start ;         /* index for A of first col in this row */
    00150     int length ;        /* number of principal columns in this row */
    00151     union
    00152     {
    00153         int degree ;    /* number of principal & non-principal columns in row */
    00154         int p ;         /* used as a row pointer in init_rows_cols () */
    00155     } shared1 ;
    00156     union
    00157     {
    00158         int mark ;      /* for computing set differences and marking dead rows*/
    00159         int first_column ;/* first column in row (used in garbage collection) */
    00160     } shared2 ;
    00161
    00162 } Colamd_Row ;
    00163
    00164 /* ========================================================================== */
    00165 /* === Colamd recommended memory size ======================================= */
    00166 /* ========================================================================== */
    00167
    00168 /*
    00169     The recommended length Alen of the array A passed to colamd is given by
    00170     the COLAMD_RECOMMENDED (nnz, n_row, n_col) macro.  It returns -1 if any
    00171     argument is negative.  2*nnz space is required for the row and column
    00172     indices of the matrix. COLAMD_C (n_col) + COLAMD_R (n_row) space is
    00173     required for the Col and Row arrays, respectively, which are internal to
    00174     colamd.  An additional n_col space is the minimal amount of "elbow room",
    00175     and nnz/5 more space is recommended for run time efficiency.
    00176
    00177     This macro is not needed when using symamd.
    00178
    00179     Explicit typecast to int added Sept. 23, 2002, COLAMD version 2.2, to avoid
    00180     gcc -pedantic warning messages.
    00181 */
    00182
    00183 #define COLAMD_C(n_col) ((int) (((n_col) + 1) * sizeof (Colamd_Col) / sizeof (int)))
    00184 #define COLAMD_R(n_row) ((int) (((n_row) + 1) * sizeof (Colamd_Row) / sizeof (int)))
    00185
    00186 #define COLAMD_RECOMMENDED(nnz, n_row, n_col)                                 \
    00187 (                                                                             \
    00188 ((nnz) < 0 || (n_row) < 0 || (n_col) < 0)                                     \
    00189 ?                                                                             \
    00190     (-1)                                                                      \
    00191 :                                                                             \
    00192     (2 * (nnz) + COLAMD_C (n_col) + COLAMD_R (n_row) + (n_col) + ((nnz) / 5)) \
    00193 )
    00194
    00195 /* ========================================================================== */
    00196 /* === Prototypes of user-callable routines ================================= */
    00197 /* ========================================================================== */
    00198
    00199 int colamd_recommended          /* returns recommended value of Alen, */
    00200                                 /* or (-1) if input arguments are erroneous */
    00201 (
    00202     int nnz,                    /* nonzeros in A */
    00203     int n_row,                  /* number of rows in A */
    00204     int n_col                   /* number of columns in A */
    00205 ) ;
    00206
    00207 void colamd_set_defaults        /* sets default parameters */
    00208 (                               /* knobs argument is modified on output */
    00209     double knobs [COLAMD_KNOBS] /* parameter settings for colamd */
    00210 ) ;
    00211
    00212 int colamd                      /* returns (1) if successful, (0) otherwise*/
    00213 (                               /* A and p arguments are modified on output */
    00214     int n_row,                  /* number of rows in A */
    00215     int n_col,                  /* number of columns in A */
    00216     int Alen,                   /* size of the array A */
    00217     int A [],                   /* row indices of A, of size Alen */
    00218     int p [],                   /* column pointers of A, of size n_col+1 */
    00219     double knobs [COLAMD_KNOBS],/* parameter settings for colamd */
    00220     int stats [COLAMD_STATS]    /* colamd output statistics and error codes */
    00221 ) ;
    00222
    00223 int symamd                              /* return (1) if OK, (0) otherwise */
    00224 (
    00225     int n,                              /* number of rows and columns of A */
    00226     int A [],                           /* row indices of A */
    00227     int p [],                           /* column pointers of A */
    00228     int perm [],                        /* output permutation, size n_col+1 */
    00229     double knobs [COLAMD_KNOBS],        /* parameters (uses defaults if NULL) */
    00230     int stats [COLAMD_STATS],           /* output statistics and error codes */
    00231     void * (*allocate) (size_t, size_t),
    00232                                         /* pointer to calloc (ANSI C) or */
    00233                                         /* mxCalloc (for MATLAB mexFunction) */
    00234     void (*release) (void *)
    00235                                         /* pointer to free (ANSI C) or */
    00236                                         /* mxFree (for MATLAB mexFunction) */
    00237 ) ;
    00238
    00239 void colamd_report
    00240 (
    00241     int stats [COLAMD_STATS]
    00242 ) ;
    00243
    00244 void symamd_report
    00245 (
    00246     int stats [COLAMD_STATS]
    00247 ) ;
    00248
    00249 #endif /* COLAMD_H */