← Back to branch summary

~ubuntu-branches/ubuntu/saucy/python-scipy/saucy

« back to all changes in this revision

Viewing changes to Lib/sandbox/pysparse/umfpack/umfpack_solve.h

  • Committer: Bazaar Package Importer
  • Author(s): Ondrej Certik
  • Date: 2008-06-16 22:58:01 UTC
  • mfrom: (2.1.24 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080616225801-irdhrpcwiocfbcmt
Tags: 0.6.0-12
http://bugs.debian.org/489149
* The description updated to match the current SciPy (Closes: #489149).
* Standards-Version bumped to 3.8.0 (no action needed)
* Build-Depends: netcdf-dev changed to libnetcdf-dev

Show diffs side-by-side

added added

removed removed

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