1 /* ========================================================================== */ 2 /* === umfpack.h ============================================================ */ 3 /* ========================================================================== */ 4 5 /* -------------------------------------------------------------------------- */ 6 /* Copyright (c) 2005-2012 by Timothy A. Davis, http://www.suitesparse.com. */ 7 /* All Rights Reserved. See ../Doc/License.txt for License. */ 8 /* -------------------------------------------------------------------------- */ 9 10 /* 11 This is the umfpack.h include file, and should be included in all user code 12 that uses UMFPACK. Do not include any of the umf_* header files in user 13 code. All routines in UMFPACK starting with "umfpack_" are user-callable. 14 All other routines are prefixed "umf_XY_", (where X is d or z, and Y is 15 i or l) and are not user-callable. 16 */ 17 18 #ifndef UMFPACK_H 19 #define UMFPACK_H 20 21 /* -------------------------------------------------------------------------- */ 22 /* Make it easy for C++ programs to include UMFPACK */ 23 /* -------------------------------------------------------------------------- */ 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 #include "SuiteSparse_config.h" 30 31 /* -------------------------------------------------------------------------- */ 32 /* size of Info and Control arrays */ 33 /* -------------------------------------------------------------------------- */ 34 35 /* These might be larger in future versions, since there are only 3 unused 36 * entries in Info, and no unused entries in Control. */ 37 38 #define UMFPACK_INFO 90 39 #define UMFPACK_CONTROL 20 40 41 /* -------------------------------------------------------------------------- */ 42 /* User-callable routines */ 43 /* -------------------------------------------------------------------------- */ 44 45 /* Primary routines: */ 46 #include "umfpack_symbolic.h" 47 #include "umfpack_numeric.h" 48 #include "umfpack_solve.h" 49 #include "umfpack_free_symbolic.h" 50 #include "umfpack_free_numeric.h" 51 52 /* Alternative routines: */ 53 #include "umfpack_defaults.h" 54 #include "umfpack_qsymbolic.h" 55 #include "umfpack_wsolve.h" 56 57 /* Matrix manipulation routines: */ 58 #include "umfpack_triplet_to_col.h" 59 #include "umfpack_col_to_triplet.h" 60 #include "umfpack_transpose.h" 61 #include "umfpack_scale.h" 62 63 /* Getting the contents of the Symbolic and Numeric opaque objects: */ 64 #include "umfpack_get_lunz.h" 65 #include "umfpack_get_numeric.h" 66 #include "umfpack_get_symbolic.h" 67 #include "umfpack_save_numeric.h" 68 #include "umfpack_load_numeric.h" 69 #include "umfpack_save_symbolic.h" 70 #include "umfpack_load_symbolic.h" 71 #include "umfpack_get_determinant.h" 72 73 /* Reporting routines (the above 14 routines print nothing): */ 74 #include "umfpack_report_status.h" 75 #include "umfpack_report_info.h" 76 #include "umfpack_report_control.h" 77 #include "umfpack_report_matrix.h" 78 #include "umfpack_report_triplet.h" 79 #include "umfpack_report_vector.h" 80 #include "umfpack_report_symbolic.h" 81 #include "umfpack_report_numeric.h" 82 #include "umfpack_report_perm.h" 83 84 /* Utility routines: */ 85 #include "umfpack_timer.h" 86 #include "umfpack_tictoc.h" 87 88 /* AMD */ 89 #include "amd.h" 90 91 /* global function pointers */ 92 #include "umfpack_global.h" 93 94 /* -------------------------------------------------------------------------- */ 95 /* Version, copyright, and license */ 96 /* -------------------------------------------------------------------------- */ 97 98 #define UMFPACK_VERSION "UMFPACK V5.7.9 (Oct 20, 2019)" 99 100 #define UMFPACK_COPYRIGHT \ 101 "UMFPACK: Copyright (c) 2005-2013 by Timothy A. Davis. All Rights Reserved.\n" 102 103 #define UMFPACK_LICENSE_PART1 \ 104 "\nUMFPACK License: refer to UMFPACK/Doc/License.txt for the license.\n" \ 105 " UMFPACK is available under alternate licenses,\n" \ 106 " contact T. Davis for details.\n" 107 108 #define UMFPACK_LICENSE_PART2 "\n" 109 110 #define UMFPACK_LICENSE_PART3 \ 111 "\n" \ 112 "Availability: http://www.suitesparse.com" \ 113 "\n" 114 115 /* UMFPACK Version 4.5 and later will include the following definitions. 116 * As an example, to test if the version you are using is 4.5 or later: 117 * 118 * #ifdef UMFPACK_VER 119 * if (UMFPACK_VER >= UMFPACK_VER_CODE (4,5)) ... 120 * #endif 121 * 122 * This also works during compile-time: 123 * 124 * #if defined(UMFPACK_VER) && (UMFPACK >= UMFPACK_VER_CODE (4,5)) 125 * printf ("This is version 4.5 or later\n") ; 126 * #else 127 * printf ("This is an early version\n") ; 128 * #endif 129 * 130 * Versions 4.4 and earlier of UMFPACK do not include a #define'd version 131 * number, although they do include the UMFPACK_VERSION string, defined 132 * above. 133 */ 134 135 #define UMFPACK_DATE "Oct 20, 2019" 136 #define UMFPACK_VER_CODE(main,sub) ((main) * 1000 + (sub)) 137 #define UMFPACK_MAIN_VERSION 5 138 #define UMFPACK_SUB_VERSION 7 139 #define UMFPACK_SUBSUB_VERSION 9 140 #define UMFPACK_VER UMFPACK_VER_CODE(UMFPACK_MAIN_VERSION,UMFPACK_SUB_VERSION) 141 142 /* -------------------------------------------------------------------------- */ 143 /* contents of Info */ 144 /* -------------------------------------------------------------------------- */ 145 146 /* Note that umfpack_report.m must coincide with these definitions. S is 147 * the submatrix of A after removing row/col singletons and empty rows/cols. */ 148 149 /* returned by all routines that use Info: */ 150 #define UMFPACK_STATUS 0 /* UMFPACK_OK, or other result */ 151 #define UMFPACK_NROW 1 /* n_row input value */ 152 #define UMFPACK_NCOL 16 /* n_col input value */ 153 #define UMFPACK_NZ 2 /* # of entries in A */ 154 155 /* computed in UMFPACK_*symbolic and UMFPACK_numeric: */ 156 #define UMFPACK_SIZE_OF_UNIT 3 /* sizeof (Unit) */ 157 158 /* computed in UMFPACK_*symbolic: */ 159 #define UMFPACK_SIZE_OF_INT 4 /* sizeof (int) */ 160 #define UMFPACK_SIZE_OF_LONG 5 /* sizeof (SuiteSparse_long) */ 161 #define UMFPACK_SIZE_OF_POINTER 6 /* sizeof (void *) */ 162 #define UMFPACK_SIZE_OF_ENTRY 7 /* sizeof (Entry), real or complex */ 163 #define UMFPACK_NDENSE_ROW 8 /* number of dense rows */ 164 #define UMFPACK_NEMPTY_ROW 9 /* number of empty rows */ 165 #define UMFPACK_NDENSE_COL 10 /* number of dense rows */ 166 #define UMFPACK_NEMPTY_COL 11 /* number of empty rows */ 167 #define UMFPACK_SYMBOLIC_DEFRAG 12 /* # of memory compactions */ 168 #define UMFPACK_SYMBOLIC_PEAK_MEMORY 13 /* memory used by symbolic analysis */ 169 #define UMFPACK_SYMBOLIC_SIZE 14 /* size of Symbolic object, in Units */ 170 #define UMFPACK_SYMBOLIC_TIME 15 /* time (sec.) for symbolic analysis */ 171 #define UMFPACK_SYMBOLIC_WALLTIME 17 /* wall clock time for sym. analysis */ 172 #define UMFPACK_STRATEGY_USED 18 /* strategy used: sym, unsym */ 173 #define UMFPACK_ORDERING_USED 19 /* ordering used: colamd, amd, given */ 174 #define UMFPACK_QFIXED 31 /* whether Q is fixed or refined */ 175 #define UMFPACK_DIAG_PREFERRED 32 /* whether diagonal pivoting attempted*/ 176 #define UMFPACK_PATTERN_SYMMETRY 33 /* symmetry of pattern of S */ 177 #define UMFPACK_NZ_A_PLUS_AT 34 /* nnz (S+S'), excl. diagonal */ 178 #define UMFPACK_NZDIAG 35 /* nnz (diag (S)) */ 179 180 /* AMD statistics, computed in UMFPACK_*symbolic: */ 181 #define UMFPACK_SYMMETRIC_LUNZ 36 /* nz in L+U, if AMD ordering used */ 182 #define UMFPACK_SYMMETRIC_FLOPS 37 /* flops for LU, if AMD ordering used */ 183 #define UMFPACK_SYMMETRIC_NDENSE 38 /* # of "dense" rows/cols in S+S' */ 184 #define UMFPACK_SYMMETRIC_DMAX 39 /* max nz in cols of L, for AMD */ 185 186 /* 51:55 unused */ 187 188 /* statistcs for singleton pruning */ 189 #define UMFPACK_COL_SINGLETONS 56 /* # of column singletons */ 190 #define UMFPACK_ROW_SINGLETONS 57 /* # of row singletons */ 191 #define UMFPACK_N2 58 /* size of S */ 192 #define UMFPACK_S_SYMMETRIC 59 /* 1 if S square and symmetricly perm.*/ 193 194 /* estimates computed in UMFPACK_*symbolic: */ 195 #define UMFPACK_NUMERIC_SIZE_ESTIMATE 20 /* final size of Numeric->Memory */ 196 #define UMFPACK_PEAK_MEMORY_ESTIMATE 21 /* for symbolic & numeric */ 197 #define UMFPACK_FLOPS_ESTIMATE 22 /* flop count */ 198 #define UMFPACK_LNZ_ESTIMATE 23 /* nz in L, incl. diagonal */ 199 #define UMFPACK_UNZ_ESTIMATE 24 /* nz in U, incl. diagonal */ 200 #define UMFPACK_VARIABLE_INIT_ESTIMATE 25 /* initial size of Numeric->Memory*/ 201 #define UMFPACK_VARIABLE_PEAK_ESTIMATE 26 /* peak size of Numeric->Memory */ 202 #define UMFPACK_VARIABLE_FINAL_ESTIMATE 27 /* final size of Numeric->Memory */ 203 #define UMFPACK_MAX_FRONT_SIZE_ESTIMATE 28 /* max frontal matrix size */ 204 #define UMFPACK_MAX_FRONT_NROWS_ESTIMATE 29 /* max # rows in any front */ 205 #define UMFPACK_MAX_FRONT_NCOLS_ESTIMATE 30 /* max # columns in any front */ 206 207 /* exact values, (estimates shown above) computed in UMFPACK_numeric: */ 208 #define UMFPACK_NUMERIC_SIZE 40 /* final size of Numeric->Memory */ 209 #define UMFPACK_PEAK_MEMORY 41 /* for symbolic & numeric */ 210 #define UMFPACK_FLOPS 42 /* flop count */ 211 #define UMFPACK_LNZ 43 /* nz in L, incl. diagonal */ 212 #define UMFPACK_UNZ 44 /* nz in U, incl. diagonal */ 213 #define UMFPACK_VARIABLE_INIT 45 /* initial size of Numeric->Memory*/ 214 #define UMFPACK_VARIABLE_PEAK 46 /* peak size of Numeric->Memory */ 215 #define UMFPACK_VARIABLE_FINAL 47 /* final size of Numeric->Memory */ 216 #define UMFPACK_MAX_FRONT_SIZE 48 /* max frontal matrix size */ 217 #define UMFPACK_MAX_FRONT_NROWS 49 /* max # rows in any front */ 218 #define UMFPACK_MAX_FRONT_NCOLS 50 /* max # columns in any front */ 219 220 /* computed in UMFPACK_numeric: */ 221 #define UMFPACK_NUMERIC_DEFRAG 60 /* # of garbage collections */ 222 #define UMFPACK_NUMERIC_REALLOC 61 /* # of memory reallocations */ 223 #define UMFPACK_NUMERIC_COSTLY_REALLOC 62 /* # of costlly memory realloc's */ 224 #define UMFPACK_COMPRESSED_PATTERN 63 /* # of integers in LU pattern */ 225 #define UMFPACK_LU_ENTRIES 64 /* # of reals in LU factors */ 226 #define UMFPACK_NUMERIC_TIME 65 /* numeric factorization time */ 227 #define UMFPACK_UDIAG_NZ 66 /* nz on diagonal of U */ 228 #define UMFPACK_RCOND 67 /* est. reciprocal condition # */ 229 #define UMFPACK_WAS_SCALED 68 /* none, max row, or sum row */ 230 #define UMFPACK_RSMIN 69 /* min (max row) or min (sum row) */ 231 #define UMFPACK_RSMAX 70 /* max (max row) or max (sum row) */ 232 #define UMFPACK_UMIN 71 /* min abs diagonal entry of U */ 233 #define UMFPACK_UMAX 72 /* max abs diagonal entry of U */ 234 #define UMFPACK_ALLOC_INIT_USED 73 /* alloc_init parameter used */ 235 #define UMFPACK_FORCED_UPDATES 74 /* # of forced updates */ 236 #define UMFPACK_NUMERIC_WALLTIME 75 /* numeric wall clock time */ 237 #define UMFPACK_NOFF_DIAG 76 /* number of off-diagonal pivots */ 238 239 #define UMFPACK_ALL_LNZ 77 /* nz in L, if no dropped entries */ 240 #define UMFPACK_ALL_UNZ 78 /* nz in U, if no dropped entries */ 241 #define UMFPACK_NZDROPPED 79 /* # of dropped small entries */ 242 243 /* computed in UMFPACK_solve: */ 244 #define UMFPACK_IR_TAKEN 80 /* # of iterative refinement steps taken */ 245 #define UMFPACK_IR_ATTEMPTED 81 /* # of iter. refinement steps attempted */ 246 #define UMFPACK_OMEGA1 82 /* omega1, sparse backward error estimate */ 247 #define UMFPACK_OMEGA2 83 /* omega2, sparse backward error estimate */ 248 #define UMFPACK_SOLVE_FLOPS 84 /* flop count for solve */ 249 #define UMFPACK_SOLVE_TIME 85 /* solve time (seconds) */ 250 #define UMFPACK_SOLVE_WALLTIME 86 /* solve time (wall clock, seconds) */ 251 252 /* Info [87, 88, 89] unused */ 253 254 /* Unused parts of Info may be used in future versions of UMFPACK. */ 255 256 /* -------------------------------------------------------------------------- */ 257 /* contents of Control */ 258 /* -------------------------------------------------------------------------- */ 259 260 /* used in all UMFPACK_report_* routines: */ 261 #define UMFPACK_PRL 0 /* print level */ 262 263 /* used in UMFPACK_*symbolic only: */ 264 #define UMFPACK_DENSE_ROW 1 /* dense row parameter */ 265 #define UMFPACK_DENSE_COL 2 /* dense col parameter */ 266 #define UMFPACK_BLOCK_SIZE 4 /* BLAS-3 block size */ 267 #define UMFPACK_STRATEGY 5 /* auto, symmetric, or unsym. */ 268 #define UMFPACK_ORDERING 10 /* ordering method to use */ 269 #define UMFPACK_FIXQ 13 /* -1: no fixQ, 0: default, 1: fixQ */ 270 #define UMFPACK_AMD_DENSE 14 /* for AMD ordering */ 271 #define UMFPACK_AGGRESSIVE 19 /* whether or not to use aggressive */ 272 #define UMFPACK_SINGLETONS 11 /* singleton filter on if true */ 273 274 /* used in UMFPACK_numeric only: */ 275 #define UMFPACK_PIVOT_TOLERANCE 3 /* threshold partial pivoting setting */ 276 #define UMFPACK_ALLOC_INIT 6 /* initial allocation ratio */ 277 #define UMFPACK_SYM_PIVOT_TOLERANCE 15 /* threshold, only for diag. entries */ 278 #define UMFPACK_SCALE 16 /* what row scaling to do */ 279 #define UMFPACK_FRONT_ALLOC_INIT 17 /* frontal matrix allocation ratio */ 280 #define UMFPACK_DROPTOL 18 /* drop tolerance for entries in L,U */ 281 282 /* used in UMFPACK_*solve only: */ 283 #define UMFPACK_IRSTEP 7 /* max # of iterative refinements */ 284 285 /* compile-time settings - Control [8..11] cannot be changed at run time: */ 286 #define UMFPACK_COMPILED_WITH_BLAS 8 /* uses the BLAS */ 287 288 /* 9,12: unused */ 289 290 /* -------------------------------------------------------------------------- */ 291 292 /* Control [UMFPACK_STRATEGY] is one of the following: */ 293 #define UMFPACK_STRATEGY_AUTO 0 /* use sym. or unsym. strategy */ 294 #define UMFPACK_STRATEGY_UNSYMMETRIC 1 /* COLAMD(A), coletree postorder, 295 not prefer diag*/ 296 #define UMFPACK_STRATEGY_OBSOLETE 2 /* 2-by-2 is no longer available */ 297 #define UMFPACK_STRATEGY_SYMMETRIC 3 /* AMD(A+A'), no coletree postorder, 298 prefer diagonal */ 299 300 /* Control [UMFPACK_SCALE] is one of the following: */ 301 #define UMFPACK_SCALE_NONE 0 /* no scaling */ 302 #define UMFPACK_SCALE_SUM 1 /* default: divide each row by sum (abs (row))*/ 303 #define UMFPACK_SCALE_MAX 2 /* divide each row by max (abs (row)) */ 304 305 /* Control [UMFPACK_ORDERING] and Info [UMFPACK_ORDERING_USED] are one of: */ 306 #define UMFPACK_ORDERING_CHOLMOD 0 /* use CHOLMOD (AMD/COLAMD then METIS)*/ 307 #define UMFPACK_ORDERING_AMD 1 /* use AMD/COLAMD */ 308 #define UMFPACK_ORDERING_GIVEN 2 /* user-provided Qinit */ 309 #define UMFPACK_ORDERING_METIS 3 /* use METIS */ 310 #define UMFPACK_ORDERING_BEST 4 /* try many orderings, pick best */ 311 #define UMFPACK_ORDERING_NONE 5 /* natural ordering */ 312 #define UMFPACK_ORDERING_USER 6 /* user-provided function */ 313 /* AMD/COLAMD means: use AMD for symmetric strategy, COLAMD for unsymmetric */ 314 315 /* -------------------------------------------------------------------------- */ 316 /* default values of Control: */ 317 /* -------------------------------------------------------------------------- */ 318 319 #define UMFPACK_DEFAULT_PRL 1 320 #define UMFPACK_DEFAULT_DENSE_ROW 0.2 321 #define UMFPACK_DEFAULT_DENSE_COL 0.2 322 #define UMFPACK_DEFAULT_PIVOT_TOLERANCE 0.1 323 #define UMFPACK_DEFAULT_SYM_PIVOT_TOLERANCE 0.001 324 #define UMFPACK_DEFAULT_BLOCK_SIZE 32 325 #define UMFPACK_DEFAULT_ALLOC_INIT 0.7 326 #define UMFPACK_DEFAULT_FRONT_ALLOC_INIT 0.5 327 #define UMFPACK_DEFAULT_IRSTEP 2 328 #define UMFPACK_DEFAULT_SCALE UMFPACK_SCALE_SUM 329 #define UMFPACK_DEFAULT_STRATEGY UMFPACK_STRATEGY_AUTO 330 #define UMFPACK_DEFAULT_AMD_DENSE AMD_DEFAULT_DENSE 331 #define UMFPACK_DEFAULT_FIXQ 0 332 #define UMFPACK_DEFAULT_AGGRESSIVE 1 333 #define UMFPACK_DEFAULT_DROPTOL 0 334 #define UMFPACK_DEFAULT_ORDERING UMFPACK_ORDERING_AMD 335 #define UMFPACK_DEFAULT_SINGLETONS TRUE 336 337 /* default values of Control may change in future versions of UMFPACK. */ 338 339 /* -------------------------------------------------------------------------- */ 340 /* status codes */ 341 /* -------------------------------------------------------------------------- */ 342 343 #define UMFPACK_OK (0) 344 345 /* status > 0 means a warning, but the method was successful anyway. */ 346 /* A Symbolic or Numeric object was still created. */ 347 #define UMFPACK_WARNING_singular_matrix (1) 348 349 /* The following warnings were added in umfpack_*_get_determinant */ 350 #define UMFPACK_WARNING_determinant_underflow (2) 351 #define UMFPACK_WARNING_determinant_overflow (3) 352 353 /* status < 0 means an error, and the method was not successful. */ 354 /* No Symbolic of Numeric object was created. */ 355 #define UMFPACK_ERROR_out_of_memory (-1) 356 #define UMFPACK_ERROR_invalid_Numeric_object (-3) 357 #define UMFPACK_ERROR_invalid_Symbolic_object (-4) 358 #define UMFPACK_ERROR_argument_missing (-5) 359 #define UMFPACK_ERROR_n_nonpositive (-6) 360 #define UMFPACK_ERROR_invalid_matrix (-8) 361 #define UMFPACK_ERROR_different_pattern (-11) 362 #define UMFPACK_ERROR_invalid_system (-13) 363 #define UMFPACK_ERROR_invalid_permutation (-15) 364 #define UMFPACK_ERROR_internal_error (-911) /* yes, call me if you get this! */ 365 #define UMFPACK_ERROR_file_IO (-17) 366 367 #define UMFPACK_ERROR_ordering_failed (-18) 368 369 /* -------------------------------------------------------------------------- */ 370 /* solve codes */ 371 /* -------------------------------------------------------------------------- */ 372 373 /* Solve the system ( )x=b, where ( ) is defined below. "t" refers to the */ 374 /* linear algebraic transpose (complex conjugate if A is complex), or the (') */ 375 /* operator in MATLAB. "at" refers to the array transpose, or the (.') */ 376 /* operator in MATLAB. */ 377 378 #define UMFPACK_A (0) /* Ax=b */ 379 #define UMFPACK_At (1) /* A'x=b */ 380 #define UMFPACK_Aat (2) /* A.'x=b */ 381 382 #define UMFPACK_Pt_L (3) /* P'Lx=b */ 383 #define UMFPACK_L (4) /* Lx=b */ 384 #define UMFPACK_Lt_P (5) /* L'Px=b */ 385 #define UMFPACK_Lat_P (6) /* L.'Px=b */ 386 #define UMFPACK_Lt (7) /* L'x=b */ 387 #define UMFPACK_Lat (8) /* L.'x=b */ 388 389 #define UMFPACK_U_Qt (9) /* UQ'x=b */ 390 #define UMFPACK_U (10) /* Ux=b */ 391 #define UMFPACK_Q_Ut (11) /* QU'x=b */ 392 #define UMFPACK_Q_Uat (12) /* QU.'x=b */ 393 #define UMFPACK_Ut (13) /* U'x=b */ 394 #define UMFPACK_Uat (14) /* U.'x=b */ 395 396 /* -------------------------------------------------------------------------- */ 397 398 /* Integer constants are used for status and solve codes instead of enum */ 399 /* to make it easier for a Fortran code to call UMFPACK. */ 400 401 #ifdef __cplusplus 402 } 403 #endif 404 405 #endif /* UMFPACK_H */ 406