1 /* ========================================================================== */ 2 /* === umfpack_get_numeric ================================================== */ 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 int umfpack_di_get_numeric 11 ( 12 int Lp [ ], 13 int Lj [ ], 14 double Lx [ ], 15 int Up [ ], 16 int Ui [ ], 17 double Ux [ ], 18 int P [ ], 19 int Q [ ], 20 double Dx [ ], 21 int *do_recip, 22 double Rs [ ], 23 void *Numeric 24 ) ; 25 26 SuiteSparse_long umfpack_dl_get_numeric 27 ( 28 SuiteSparse_long Lp [ ], 29 SuiteSparse_long Lj [ ], 30 double Lx [ ], 31 SuiteSparse_long Up [ ], 32 SuiteSparse_long Ui [ ], 33 double Ux [ ], 34 SuiteSparse_long P [ ], 35 SuiteSparse_long Q [ ], 36 double Dx [ ], 37 SuiteSparse_long *do_recip, 38 double Rs [ ], 39 void *Numeric 40 ) ; 41 42 int umfpack_zi_get_numeric 43 ( 44 int Lp [ ], 45 int Lj [ ], 46 double Lx [ ], double Lz [ ], 47 int Up [ ], 48 int Ui [ ], 49 double Ux [ ], double Uz [ ], 50 int P [ ], 51 int Q [ ], 52 double Dx [ ], double Dz [ ], 53 int *do_recip, 54 double Rs [ ], 55 void *Numeric 56 ) ; 57 58 SuiteSparse_long umfpack_zl_get_numeric 59 ( 60 SuiteSparse_long Lp [ ], 61 SuiteSparse_long Lj [ ], 62 double Lx [ ], double Lz [ ], 63 SuiteSparse_long Up [ ], 64 SuiteSparse_long Ui [ ], 65 double Ux [ ], double Uz [ ], 66 SuiteSparse_long P [ ], 67 SuiteSparse_long Q [ ], 68 double Dx [ ], double Dz [ ], 69 SuiteSparse_long *do_recip, 70 double Rs [ ], 71 void *Numeric 72 ) ; 73 74 /* 75 double int Syntax: 76 77 #include "umfpack.h" 78 void *Numeric ; 79 int *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ; 80 double *Lx, *Ux, *Dx, *Rs ; 81 status = umfpack_di_get_numeric (Lp, Lj, Lx, Up, Ui, Ux, P, Q, Dx, 82 &do_recip, Rs, Numeric) ; 83 84 double SuiteSparse_long Syntax: 85 86 #include "umfpack.h" 87 void *Numeric ; 88 SuiteSparse_long *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ; 89 double *Lx, *Ux, *Dx, *Rs ; 90 status = umfpack_dl_get_numeric (Lp, Lj, Lx, Up, Ui, Ux, P, Q, Dx, 91 &do_recip, Rs, Numeric) ; 92 93 complex int Syntax: 94 95 #include "umfpack.h" 96 void *Numeric ; 97 int *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ; 98 double *Lx, *Lz, *Ux, *Uz, *Dx, *Dz, *Rs ; 99 status = umfpack_zi_get_numeric (Lp, Lj, Lx, Lz, Up, Ui, Ux, Uz, P, Q, 100 Dx, Dz, &do_recip, Rs, Numeric) ; 101 102 complex SuiteSparse_long Syntax: 103 104 #include "umfpack.h" 105 void *Numeric ; 106 SuiteSparse_long *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ; 107 double *Lx, *Lz, *Ux, *Uz, *Dx, *Dz, *Rs ; 108 status = umfpack_zl_get_numeric (Lp, Lj, Lx, Lz, Up, Ui, Ux, Uz, P, Q, 109 Dx, Dz, &do_recip, Rs, Numeric) ; 110 111 packed complex int/SuiteSparse_long Syntax: 112 113 Same as above, except Lz, Uz, and Dz are all NULL. 114 115 Purpose: 116 117 This routine copies the LU factors and permutation vectors from the Numeric 118 object into user-accessible arrays. This routine is not needed to solve a 119 linear system. Note that the output arrays Lp, Lj, Lx, Up, Ui, Ux, P, Q, 120 Dx, and Rs are not allocated by umfpack_*_get_numeric; they must exist on 121 input. 122 123 All output arguments are optional. If any of them are NULL 124 on input, then that part of the LU factorization is not copied. You can 125 use this routine to extract just the parts of the LU factorization that 126 you want. For example, to retrieve just the column permutation Q, use: 127 128 #define noD (double *) NULL 129 #define noI (int *) NULL 130 status = umfpack_di_get_numeric (noI, noI, noD, noI, noI, noD, noI, 131 Q, noD, noI, noD, Numeric) ; 132 133 Returns: 134 135 Returns UMFPACK_OK if successful. Returns UMFPACK_ERROR_out_of_memory 136 if insufficient memory is available for the 2*max(n_row,n_col) integer 137 workspace that umfpack_*_get_numeric allocates to construct L and/or U. 138 Returns UMFPACK_ERROR_invalid_Numeric_object if the Numeric object provided 139 as input is invalid. 140 141 Arguments: 142 143 Int Lp [n_row+1] ; Output argument. 144 Int Lj [lnz] ; Output argument. 145 double Lx [lnz] ; Output argument. Size 2*lnz for packed complex case. 146 double Lz [lnz] ; Output argument for complex versions. 147 148 The n_row-by-min(n_row,n_col) matrix L is returned in compressed-row 149 form. The column indices of row i and corresponding numerical values 150 are in: 151 152 Lj [Lp [i] ... Lp [i+1]-1] 153 Lx [Lp [i] ... Lp [i+1]-1] real part 154 Lz [Lp [i] ... Lp [i+1]-1] imaginary part (complex versions) 155 156 respectively. Each row is stored in sorted order, from low column 157 indices to higher. The last entry in each row is the diagonal, which 158 is numerically equal to one. The sizes of Lp, Lj, Lx, and Lz are 159 returned by umfpack_*_get_lunz. If Lp, Lj, or Lx are not present, 160 then the matrix L is not returned. This is not an error condition. 161 The L matrix can be printed if n_row, Lp, Lj, Lx (and Lz for the split 162 complex case) are passed to umfpack_*_report_matrix (using the 163 "row" form). 164 165 If Lx is present and Lz is NULL, then both real 166 and imaginary parts are returned in Lx[0..2*lnz-1], with Lx[2*k] 167 and Lx[2*k+1] being the real and imaginary part of the kth entry. 168 169 Int Up [n_col+1] ; Output argument. 170 Int Ui [unz] ; Output argument. 171 double Ux [unz] ; Output argument. Size 2*unz for packed complex case. 172 double Uz [unz] ; Output argument for complex versions. 173 174 The min(n_row,n_col)-by-n_col matrix U is returned in compressed-column 175 form. The row indices of column j and corresponding numerical values 176 are in 177 178 Ui [Up [j] ... Up [j+1]-1] 179 Ux [Up [j] ... Up [j+1]-1] real part 180 Uz [Up [j] ... Up [j+1]-1] imaginary part (complex versions) 181 182 respectively. Each column is stored in sorted order, from low row 183 indices to higher. The last entry in each column is the diagonal 184 (assuming that it is nonzero). The sizes of Up, Ui, Ux, and Uz are 185 returned by umfpack_*_get_lunz. If Up, Ui, or Ux are not present, 186 then the matrix U is not returned. This is not an error condition. 187 The U matrix can be printed if n_col, Up, Ui, Ux (and Uz for the 188 split complex case) are passed to umfpack_*_report_matrix (using the 189 "column" form). 190 191 If Ux is present and Uz is NULL, then both real 192 and imaginary parts are returned in Ux[0..2*unz-1], with Ux[2*k] 193 and Ux[2*k+1] being the real and imaginary part of the kth entry. 194 195 Int P [n_row] ; Output argument. 196 197 The permutation vector P is defined as P [k] = i, where the original 198 row i of A is the kth pivot row in PAQ. If you do not want the P vector 199 to be returned, simply pass (Int *) NULL for P. This is not an error 200 condition. You can print P and Q with umfpack_*_report_perm. 201 202 Int Q [n_col] ; Output argument. 203 204 The permutation vector Q is defined as Q [k] = j, where the original 205 column j of A is the kth pivot column in PAQ. If you not want the Q 206 vector to be returned, simply pass (Int *) NULL for Q. This is not 207 an error condition. Note that Q is not necessarily identical to 208 Qtree, the column pre-ordering held in the Symbolic object. Refer to 209 the description of Qtree and Front_npivcol in umfpack_*_get_symbolic for 210 details. 211 212 double Dx [min(n_row,n_col)] ; Output argument. Size 2*n for 213 the packed complex case. 214 double Dz [min(n_row,n_col)] ; Output argument for complex versions. 215 216 The diagonal of U is also returned in Dx and Dz. You can extract the 217 diagonal of U without getting all of U by passing a non-NULL Dx (and 218 Dz for the complex version) and passing Up, Ui, and Ux as NULL. Dx is 219 the real part of the diagonal, and Dz is the imaginary part. 220 221 If Dx is present and Dz is NULL, then both real 222 and imaginary parts are returned in Dx[0..2*min(n_row,n_col)-1], 223 with Dx[2*k] and Dx[2*k+1] being the real and imaginary part of the kth 224 entry. 225 226 Int *do_recip ; Output argument. 227 228 This argument defines how the scale factors Rs are to be interpretted. 229 230 If do_recip is TRUE (one), then the scale factors Rs [i] are to be used 231 by multiplying row i by Rs [i]. Otherwise, the entries in row i are to 232 be divided by Rs [i]. 233 234 If UMFPACK has been compiled with gcc, or for MATLAB as either a 235 built-in routine or as a mexFunction, then the NRECIPROCAL flag is 236 set, and do_recip will always be FALSE (zero). 237 238 double Rs [n_row] ; Output argument. 239 240 The row scale factors are returned in Rs [0..n_row-1]. Row i of A is 241 scaled by dividing or multiplying its values by Rs [i]. If default 242 scaling is in use, Rs [i] is the sum of the absolute values of row i 243 (or its reciprocal). If max row scaling is in use, then Rs [i] is the 244 maximum absolute value in row i (or its reciprocal). 245 Otherwise, Rs [i] = 1. If row i is all zero, Rs [i] = 1 as well. For 246 the complex version, an approximate absolute value is used 247 (|x_real|+|x_imag|). 248 249 void *Numeric ; Input argument, not modified. 250 251 Numeric must point to a valid Numeric object, computed by 252 umfpack_*_numeric. 253 */ 254