Mercurial > octave-nkf

comparison liboctave/UMFPACK/UMFPACK/Include/umfpack_solve.h @ 5164:57077d0ddc8e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[project @ 2005-02-25 19:55:24 by jwe]
author jwe
date Fri, 25 Feb 2005 19:55:28 +0000
parents
children
comparison
equal deleted inserted replaced
5163:9f3299378193 5164:57077d0ddc8e
1 /* ========================================================================== */
2 /* === umfpack_solve ======================================================== */
3 /* ========================================================================== */
4
5 /* -------------------------------------------------------------------------- */
6 /* UMFPACK Version 4.4, Copyright (c) 2005 by Timothy A. Davis. CISE Dept, */
7 /* Univ. of Florida. All Rights Reserved. See ../Doc/License for License. */
8 /* web: http://www.cise.ufl.edu/research/sparse/umfpack */
9 /* -------------------------------------------------------------------------- */
10
11 int umfpack_di_solve
12 (
13 int sys,
14 const int Ap [ ],
15 const int Ai [ ],
16 const double Ax [ ],
17 double X [ ],
18 const double B [ ],
19 void *Numeric,
20 const double Control [UMFPACK_CONTROL],
21 double Info [UMFPACK_INFO]
22 ) ;
23
24 long umfpack_dl_solve
25 (
26 long sys,
27 const long Ap [ ],
28 const long Ai [ ],
29 const double Ax [ ],
30 double X [ ],
31 const double B [ ],
32 void *Numeric,
33 const double Control [UMFPACK_CONTROL],
34 double Info [UMFPACK_INFO]
35 ) ;
36
37 int umfpack_zi_solve
38 (
39 int sys,
40 const int Ap [ ],
41 const int Ai [ ],
42 const double Ax [ ], const double Az [ ],
43 double Xx [ ], double Xz [ ],
44 const double Bx [ ], const double Bz [ ],
45 void *Numeric,
46 const double Control [UMFPACK_CONTROL],
47 double Info [UMFPACK_INFO]
48 ) ;
49
50 long umfpack_zl_solve
51 (
52 long sys,
53 const long Ap [ ],
54 const long Ai [ ],
55 const double Ax [ ], const double Az [ ],
56 double Xx [ ], double Xz [ ],
57 const double Bx [ ], const double Bz [ ],
58 void *Numeric,
59 const double Control [UMFPACK_CONTROL],
60 double Info [UMFPACK_INFO]
61 ) ;
62
63 /*
64 double int Syntax:
65
66 #include "umfpack.h"
67 void *Numeric ;
68 int status, *Ap, *Ai, sys ;
69 double *B, *X, *Ax, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ;
70 status = umfpack_di_solve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info) ;
71
72 double long Syntax:
73
74 #include "umfpack.h"
75 void *Numeric ;
76 long status, *Ap, *Ai, sys ;
77 double *B, *X, *Ax, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ;
78 status = umfpack_dl_solve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info) ;
79
80 complex int Syntax:
81
82 #include "umfpack.h"
83 void *Numeric ;
84 int status, *Ap, *Ai, sys ;
85 double *Bx, *Bz, *Xx, *Xz, *Ax, *Az, Info [UMFPACK_INFO],
86 Control [UMFPACK_CONTROL] ;
87 status = umfpack_zi_solve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric,
88 Control, Info) ;
89
90 complex long Syntax:
91
92 #include "umfpack.h"
93 void *Numeric ;
94 long status, *Ap, *Ai, sys ;
95 double *Bx, *Bz, *Xx, *Xz, *Ax, *Az, Info [UMFPACK_INFO],
96 Control [UMFPACK_CONTROL] ;
97 status = umfpack_zl_solve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric,
98 Control, Info) ;
99
100 packed complex Syntax:
101
102 Same as above, Xz, Bz, and Az are NULL.
103
104 Purpose:
105
106 Given LU factors computed by umfpack_*_numeric (PAQ=LU, PRAQ=LU, or
107 P(R\A)Q=LU) and the right-hand-side, B, solve a linear system for the
108 solution X. Iterative refinement is optionally performed. Only square
109 systems are handled. Singular matrices result in a divide-by-zero for all
110 systems except those involving just the matrix L. Iterative refinement is
111 not performed for singular matrices. In the discussion below, n is equal
112 to n_row and n_col, because only square systems are handled.
113
114 Returns:
115
116 The status code is returned. See Info [UMFPACK_STATUS], below.
117
118 Arguments:
119
120 Int sys ; Input argument, not modified.
121
122 Defines which system to solve. (') is the linear algebraic transpose
123 (complex conjugate if A is complex), and (.') is the array transpose.
124
125 sys value system solved
126 UMFPACK_A Ax=b
127 UMFPACK_At A'x=b
128 UMFPACK_Aat A.'x=b
129 UMFPACK_Pt_L P'Lx=b
130 UMFPACK_L Lx=b
131 UMFPACK_Lt_P L'Px=b
132 UMFPACK_Lat_P L.'Px=b
133 UMFPACK_Lt L'x=b
134 UMFPACK_U_Qt UQ'x=b
135 UMFPACK_U Ux=b
136 UMFPACK_Q_Ut QU'x=b
137 UMFPACK_Q_Uat QU.'x=b
138 UMFPACK_Ut U'x=b
139 UMFPACK_Uat U.'x=b
140
141 Iterative refinement can be optionally performed when sys is any of
142 the following:
143
144 UMFPACK_A Ax=b
145 UMFPACK_At A'x=b
146 UMFPACK_Aat A.'x=b
147
148 For the other values of the sys argument, iterative refinement is not
149 performed (Control [UMFPACK_IRSTEP], Ap, Ai, Ax, and Az are ignored).
150
151 Int Ap [n+1] ; Input argument, not modified.
152 Int Ai [nz] ; Input argument, not modified.
153 double Ax [nz] ; Input argument, not modified.
154 Size 2*nz for packed complex case.
155 double Az [nz] ; Input argument, not modified, for complex versions.
156
157 If iterative refinement is requested (Control [UMFPACK_IRSTEP] >= 1,
158 Ax=b, A'x=b, or A.'x=b is being solved, and A is nonsingular), then
159 these arrays must be identical to the same ones passed to
160 umfpack_*_numeric. The umfpack_*_solve routine does not check the
161 contents of these arguments, so the results are undefined if Ap, Ai, Ax,
162 and/or Az are modified between the calls the umfpack_*_numeric and
163 umfpack_*_solve. These three arrays do not need to be present (NULL
164 pointers can be passed) if Control [UMFPACK_IRSTEP] is zero, or if a
165 system other than Ax=b, A'x=b, or A.'x=b is being solved, or if A is
166 singular, since in each of these cases A is not accessed.
167
168 If Az, Xz, or Bz are NULL, then both real
169 and imaginary parts are contained in Ax[0..2*nz-1], with Ax[2*k]
170 and Ax[2*k+1] being the real and imaginary part of the kth entry.
171
172 double X [n] ; Output argument.
173 or:
174 double Xx [n] ; Output argument, real part
175 Size 2*n for packed complex case.
176 double Xz [n] ; Output argument, imaginary part.
177
178 The solution to the linear system, where n = n_row = n_col is the
179 dimension of the matrices A, L, and U.
180
181 If Az, Xz, or Bz are NULL, then both real
182 and imaginary parts are returned in Xx[0..2*n-1], with Xx[2*k] and
183 Xx[2*k+1] being the real and imaginary part of the kth entry.
184
185 double B [n] ; Input argument, not modified.
186 or:
187 double Bx [n] ; Input argument, not modified, real part.
188 Size 2*n for packed complex case.
189 double Bz [n] ; Input argument, not modified, imaginary part.
190
191 The right-hand side vector, b, stored as a conventional array of size n
192 (or two arrays of size n for complex versions). This routine does not
193 solve for multiple right-hand-sides, nor does it allow b to be stored in
194 a sparse-column form.
195
196 If Az, Xz, or Bz are NULL, then both real
197 and imaginary parts are contained in Bx[0..2*n-1], with Bx[2*k]
198 and Bx[2*k+1] being the real and imaginary part of the kth entry.
199
200 void *Numeric ; Input argument, not modified.
201
202 Numeric must point to a valid Numeric object, computed by
203 umfpack_*_numeric.
204
205 double Control [UMFPACK_CONTROL] ; Input argument, not modified.
206
207 If a (double *) NULL pointer is passed, then the default control
208 settings are used. Otherwise, the settings are determined from the
209 Control array. See umfpack_*_defaults on how to fill the Control
210 array with the default settings. If Control contains NaN's, the
211 defaults are used. The following Control parameters are used:
212
213 Control [UMFPACK_IRSTEP]: The maximum number of iterative refinement
214 steps to attempt. A value less than zero is treated as zero. If
215 less than 1, or if Ax=b, A'x=b, or A.'x=b is not being solved, or
216 if A is singular, then the Ap, Ai, Ax, and Az arguments are not
217 accessed. Default: 2.
218
219 double Info [UMFPACK_INFO] ; Output argument.
220
221 Contains statistics about the solution factorization. If a
222 (double *) NULL pointer is passed, then no statistics are returned in
223 Info (this is not an error condition). The following statistics are
224 computed in umfpack_*_solve:
225
226 Info [UMFPACK_STATUS]: status code. This is also the return value,
227 whether or not Info is present.
228
229 UMFPACK_OK
230
231 The linear system was successfully solved.
232
233 UMFPACK_WARNING_singular_matrix
234
235 A divide-by-zero occurred. Your solution will contain Inf's
236 and/or NaN's. Some parts of the solution may be valid. For
237 example, solving Ax=b with
238
239 A = [2 0] b = [ 1 ] returns x = [ 0.5 ]
240 [0 0] [ 0 ] [ Inf ]
241
242 UMFPACK_ERROR_out_of_memory
243
244 Insufficient memory to solve the linear system.
245
246 UMFPACK_ERROR_argument_missing
247
248 One or more required arguments are missing. The B, X, (or
249 Bx and Xx for the complex versions) arguments
250 are always required. Info and Control are not required. Ap,
251 Ai, Ax are required if Ax=b,
252 A'x=b, A.'x=b is to be solved, the (default) iterative
253 refinement is requested, and the matrix A is nonsingular.
254
255 UMFPACK_ERROR_invalid_system
256
257 The sys argument is not valid, or the matrix A is not square.
258
259 UMFPACK_ERROR_invalid_Numeric_object
260
261 The Numeric object is not valid.
262
263 Info [UMFPACK_NROW], Info [UMFPACK_NCOL]:
264 The dimensions of the matrix A (L is n_row-by-n_inner and
265 U is n_inner-by-n_col, with n_inner = min(n_row,n_col)).
266
267 Info [UMFPACK_NZ]: the number of entries in the input matrix, Ap [n],
268 if iterative refinement is requested (Ax=b, A'x=b, or A.'x=b is
269 being solved, Control [UMFPACK_IRSTEP] >= 1, and A is nonsingular).
270
271 Info [UMFPACK_IR_TAKEN]: The number of iterative refinement steps
272 effectively taken. The number of steps attempted may be one more
273 than this; the refinement algorithm backtracks if the last
274 refinement step worsens the solution.
275
276 Info [UMFPACK_IR_ATTEMPTED]: The number of iterative refinement steps
277 attempted. The number of times a linear system was solved is one
278 more than this (once for the initial Ax=b, and once for each Ay=r
279 solved for each iterative refinement step attempted).
280
281 Info [UMFPACK_OMEGA1]: sparse backward error estimate, omega1, if
282 iterative refinement was performed, or -1 if iterative refinement
283 not performed.
284
285 Info [UMFPACK_OMEGA2]: sparse backward error estimate, omega2, if
286 iterative refinement was performed, or -1 if iterative refinement
287 not performed.
288
289 Info [UMFPACK_SOLVE_FLOPS]: the number of floating point operations
290 performed to solve the linear system. This includes the work
291 taken for all iterative refinement steps, including the backtrack
292 (if any).
293
294 Info [UMFPACK_SOLVE_TIME]: The time taken, in seconds.
295
296 Info [UMFPACK_SOLVE_WALLTIME]: The wallclock time taken, in seconds.
297
298 Only the above listed Info [...] entries are accessed. The remaining
299 entries of Info are not accessed or modified by umfpack_*_solve.
300 Future versions might modify different parts of Info.
301 */