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 */

Generated on Fri Aug 1 22:40:39 2008 for SuperLU by  doxygen 1.4.6