00001 /* ========================================================================== */ 00002 /* === umfpack_solve ======================================================== */ 00003 /* ========================================================================== */ 00004 00005 /* -------------------------------------------------------------------------- */ 00006 /* UMFPACK Version 4.3 (Jan. 16, 2004), Copyright (c) 2004 by Timothy A. */ 00007 /* Davis. All Rights Reserved. See ../README for License. */ 00008 /* email: davis@cise.ufl.edu CISE Department, Univ. of Florida. */ 00009 /* web: http://www.cise.ufl.edu/research/sparse/umfpack */ 00010 /* -------------------------------------------------------------------------- */ 00011 00012 int umfpack_di_solve 00013 ( 00014 int sys, 00015 const int Ap [ ], 00016 const int Ai [ ], 00017 const double Ax [ ], 00018 double X [ ], 00019 const double B [ ], 00020 void *Numeric, 00021 const double Control [UMFPACK_CONTROL], 00022 double Info [UMFPACK_INFO] 00023 ) ; 00024 00025 long umfpack_dl_solve 00026 ( 00027 long sys, 00028 const long Ap [ ], 00029 const long Ai [ ], 00030 const double Ax [ ], 00031 double X [ ], 00032 const double B [ ], 00033 void *Numeric, 00034 const double Control [UMFPACK_CONTROL], 00035 double Info [UMFPACK_INFO] 00036 ) ; 00037 00038 int umfpack_zi_solve 00039 ( 00040 int sys, 00041 const int Ap [ ], 00042 const int Ai [ ], 00043 const double Ax [ ], const double Az [ ], 00044 double Xx [ ], double Xz [ ], 00045 const double Bx [ ], const double Bz [ ], 00046 void *Numeric, 00047 const double Control [UMFPACK_CONTROL], 00048 double Info [UMFPACK_INFO] 00049 ) ; 00050 00051 long umfpack_zl_solve 00052 ( 00053 long sys, 00054 const long Ap [ ], 00055 const long Ai [ ], 00056 const double Ax [ ], const double Az [ ], 00057 double Xx [ ], double Xz [ ], 00058 const double Bx [ ], const double Bz [ ], 00059 void *Numeric, 00060 const double Control [UMFPACK_CONTROL], 00061 double Info [UMFPACK_INFO] 00062 ) ; 00063 00064 /* 00065 double int Syntax: 00066 00067 #include "umfpack.h" 00068 void *Numeric ; 00069 int status, *Ap, *Ai, sys ; 00070 double *B, *X, *Ax, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ; 00071 status = umfpack_di_solve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info) ; 00072 00073 double long Syntax: 00074 00075 #include "umfpack.h" 00076 void *Numeric ; 00077 long status, *Ap, *Ai, sys ; 00078 double *B, *X, *Ax, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ; 00079 status = umfpack_dl_solve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info) ; 00080 00081 complex int Syntax: 00082 00083 #include "umfpack.h" 00084 void *Numeric ; 00085 int status, *Ap, *Ai, sys ; 00086 double *Bx, *Bz, *Xx, *Xz, *Ax, *Az, Info [UMFPACK_INFO], 00087 Control [UMFPACK_CONTROL] ; 00088 status = umfpack_zi_solve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric, 00089 Control, Info) ; 00090 00091 complex long Syntax: 00092 00093 #include "umfpack.h" 00094 void *Numeric ; 00095 long status, *Ap, *Ai, sys ; 00096 double *Bx, *Bz, *Xx, *Xz, *Ax, *Az, Info [UMFPACK_INFO], 00097 Control [UMFPACK_CONTROL] ; 00098 status = umfpack_zl_solve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric, 00099 Control, Info) ; 00100 00101 Purpose: 00102 00103 Given LU factors computed by umfpack_*_numeric (PAQ=LU, PRAQ=LU, or 00104 P(R\A)Q=LU) and the right-hand-side, B, solve a linear system for the 00105 solution X. Iterative refinement is optionally performed. Only square 00106 systems are handled. Singular matrices result in a divide-by-zero for all 00107 systems except those involving just the matrix L. Iterative refinement is 00108 not performed for singular matrices. In the discussion below, n is equal 00109 to n_row and n_col, because only square systems are handled. 00110 00111 Returns: 00112 00113 The status code is returned. See Info [UMFPACK_STATUS], below. 00114 00115 Arguments: 00116 00117 Int sys ; Input argument, not modified. 00118 00119 Defines which system to solve. (') is the linear algebraic transpose 00120 (complex conjugate if A is complex), and (.') is the array transpose. 00121 00122 sys value system solved 00123 UMFPACK_A Ax=b 00124 UMFPACK_At A'x=b 00125 UMFPACK_Aat A.'x=b 00126 UMFPACK_Pt_L P'Lx=b 00127 UMFPACK_L Lx=b 00128 UMFPACK_Lt_P L'Px=b 00129 UMFPACK_Lat_P L.'Px=b 00130 UMFPACK_Lt L'x=b 00131 UMFPACK_U_Qt UQ'x=b 00132 UMFPACK_U Ux=b 00133 UMFPACK_Q_Ut QU'x=b 00134 UMFPACK_Q_Uat QU.'x=b 00135 UMFPACK_Ut U'x=b 00136 UMFPACK_Uat U.'x=b 00137 00138 Iterative refinement can be optionally performed when sys is any of 00139 the following: 00140 00141 UMFPACK_A Ax=b 00142 UMFPACK_At A'x=b 00143 UMFPACK_Aat A.'x=b 00144 00145 For the other values of the sys argument, iterative refinement is not 00146 performed (Control [UMFPACK_IRSTEP], Ap, Ai, Ax, and Az are ignored). 00147 00148 Earlier versions used a string argument for sys. It was changed to an 00149 integer to make it easier for a Fortran code to call UMFPACK. 00150 00151 Int Ap [n+1] ; Input argument, not modified. 00152 Int Ai [nz] ; Input argument, not modified. 00153 double Ax [nz] ; Input argument, not modified. 00154 double Az [nz] ; Input argument, not modified, for complex versions. 00155 00156 If iterative refinement is requested (Control [UMFPACK_IRSTEP] >= 1, 00157 Ax=b, A'x=b, or A.'x=b is being solved, and A is nonsingular), then 00158 these arrays must be identical to the same ones passed to 00159 umfpack_*_numeric. The umfpack_*_solve routine does not check the 00160 contents of these arguments, so the results are undefined if Ap, Ai, Ax, 00161 and/or Az are modified between the calls the umfpack_*_numeric and 00162 umfpack_*_solve. These three arrays do not need to be present (NULL 00163 pointers can be passed) if Control [UMFPACK_IRSTEP] is zero, or if a 00164 system other than Ax=b, A'x=b, or A.'x=b is being solved, or if A is 00165 singular, since in each of these cases A is not accessed. 00166 00167 Future complex version: if Ax is present and Az is NULL, then both real 00168 and imaginary parts will be contained in Ax[0..2*nz-1], with Ax[2*k] 00169 and Ax[2*k+1] being the real and imaginary part of the kth entry. 00170 00171 double X [n] ; Output argument. 00172 or: 00173 double Xx [n] ; Output argument, real part. 00174 double Xz [n] ; Output argument, imaginary part. 00175 00176 The solution to the linear system, where n = n_row = n_col is the 00177 dimension of the matrices A, L, and U. 00178 00179 Future complex version: if Xx is present and Xz is NULL, then both real 00180 and imaginary parts will be returned in Xx[0..2*n-1], with Xx[2*k] and 00181 Xx[2*k+1] being the real and imaginary part of the kth entry. 00182 00183 double B [n] ; Input argument, not modified. 00184 or: 00185 double Bx [n] ; Input argument, not modified, real part. 00186 double Bz [n] ; Input argument, not modified, imaginary part. 00187 00188 The right-hand side vector, b, stored as a conventional array of size n 00189 (or two arrays of size n for complex versions). This routine does not 00190 solve for multiple right-hand-sides, nor does it allow b to be stored in 00191 a sparse-column form. 00192 00193 Future complex version: if Bx is present and Bz is NULL, then both real 00194 and imaginary parts will be contained in Bx[0..2*n-1], with Bx[2*k] 00195 and Bx[2*k+1] being the real and imaginary part of the kth entry. 00196 00197 void *Numeric ; Input argument, not modified. 00198 00199 Numeric must point to a valid Numeric object, computed by 00200 umfpack_*_numeric. 00201 00202 double Control [UMFPACK_CONTROL] ; Input argument, not modified. 00203 00204 If a (double *) NULL pointer is passed, then the default control 00205 settings are used. Otherwise, the settings are determined from the 00206 Control array. See umfpack_*_defaults on how to fill the Control 00207 array with the default settings. If Control contains NaN's, the 00208 defaults are used. The following Control parameters are used: 00209 00210 Control [UMFPACK_IRSTEP]: The maximum number of iterative refinement 00211 steps to attempt. A value less than zero is treated as zero. If 00212 less than 1, or if Ax=b, A'x=b, or A.'x=b is not being solved, or 00213 if A is singular, then the Ap, Ai, Ax, and Az arguments are not 00214 accessed. Default: 2. 00215 00216 double Info [UMFPACK_INFO] ; Output argument. 00217 00218 Contains statistics about the solution factorization. If a 00219 (double *) NULL pointer is passed, then no statistics are returned in 00220 Info (this is not an error condition). The following statistics are 00221 computed in umfpack_*_solve: 00222 00223 Info [UMFPACK_STATUS]: status code. This is also the return value, 00224 whether or not Info is present. 00225 00226 UMFPACK_OK 00227 00228 The linear system was successfully solved. 00229 00230 UMFPACK_WARNING_singular_matrix 00231 00232 A divide-by-zero occured. Your solution will contain Inf's 00233 and/or NaN's. Some parts of the solution may be valid. For 00234 example, solving Ax=b with 00235 00236 A = [2 0] b = [ 1 ] returns x = [ 0.5 ] 00237 [0 0] [ 0 ] [ Inf ] 00238 00239 UMFPACK_ERROR_out_of_memory 00240 00241 Insufficient memory to solve the linear system. 00242 00243 UMFPACK_ERROR_argument_missing 00244 00245 One or more required arguments are missing. The B, X, (or 00246 Bx, Bz, Xx and Xz for the complex versions) arguments 00247 are always required. Info and Control are not required. Ap, 00248 Ai, Ax (and Az for complex versions) are required if Ax=b, 00249 A'x=b, A.'x=b is to be solved, the (default) iterative 00250 refinement is requested, and the matrix A is nonsingular. 00251 00252 UMFPACK_ERROR_invalid_system 00253 00254 The sys argument is not valid, or the matrix A is not square. 00255 00256 UMFPACK_ERROR_invalid_Numeric_object 00257 00258 The Numeric object is not valid. 00259 00260 Info [UMFPACK_NROW], Info [UMFPACK_NCOL]: 00261 The dimensions of the matrix A (L is n_row-by-n_inner and 00262 U is n_inner-by-n_col, with n_inner = min(n_row,n_col)). 00263 00264 Info [UMFPACK_NZ]: the number of entries in the input matrix, Ap [n], 00265 if iterative refinement is requested (Ax=b, A'x=b, or A.'x=b is 00266 being solved, Control [UMFPACK_IRSTEP] >= 1, and A is nonsingular). 00267 00268 Info [UMFPACK_IR_TAKEN]: The number of iterative refinement steps 00269 effectively taken. The number of steps attempted may be one more 00270 than this; the refinement algorithm backtracks if the last 00271 refinement step worsens the solution. 00272 00273 Info [UMFPACK_IR_ATTEMPTED]: The number of iterative refinement steps 00274 attempted. The number of times a linear system was solved is one 00275 more than this (once for the initial Ax=b, and once for each Ay=r 00276 solved for each iterative refinement step attempted). 00277 00278 Info [UMFPACK_OMEGA1]: sparse backward error estimate, omega1, if 00279 iterative refinement was performed, or -1 if iterative refinement 00280 not performed. 00281 00282 Info [UMFPACK_OMEGA2]: sparse backward error estimate, omega2, if 00283 iterative refinement was performed, or -1 if iterative refinement 00284 not performed. 00285 00286 Info [UMFPACK_SOLVE_FLOPS]: the number of floating point operations 00287 performed to solve the linear system. This includes the work 00288 taken for all iterative refinement steps, including the backtrack 00289 (if any). 00290 00291 Info [UMFPACK_SOLVE_TIME]: The time taken, in seconds. 00292 00293 ------------------------------------------------------------------------ 00294 The following statistic was added to Version 4.1: 00295 ------------------------------------------------------------------------ 00296 00297 Info [UMFPACK_SOLVE_WALLTIME]: The wallclock time taken, in seconds. 00298 00299 Only the above listed Info [...] entries are accessed. The remaining 00300 entries of Info are not accessed or modified by umfpack_*_solve. 00301 Future versions might modify different parts of Info. 00302 */
1.4.6