 Abstract 
 Table of Contents 
 Main 
 Reference 

Full Citation 
Material Information 

Title: 
UMFPACK version 4.3 user guide 

Series Title: 
Department of Computer and Information Science and Engineering Technical Reports 

Physical Description: 
Book 

Language: 
English 

Creator: 
Davis, Timothy A. 

Publisher: 
Department of Computer and Information Science and Engineering, University of Florida 

Place of Publication: 
Gainesville, Fla. 

Publication Date: 
January 16, 2004 

Copyright Date: 
2004 
Record Information 

Bibliographic ID: 
UF00095603 

Volume ID: 
VID00001 

Source Institution: 
University of Florida 

Holding Location: 
University of Florida 

Rights Management: 
All rights reserved by the source institution and holding location. 

Downloads 

Table of Contents 
Abstract
Page 1
Table of Contents
Page 2
Page 3
Main
Page 4
Page 5
Page 6
Page 7
Page 8
Page 9
Page 10
Page 11
Page 12
Page 13
Page 14
Page 15
Page 16
Page 17
Page 18
Page 19
Page 20
Page 21
Page 22
Page 23
Page 24
Page 25
Page 26
Page 27
Page 28
Page 29
Page 30
Page 31
Page 32
Page 33
Page 34
Page 35
Page 36
Page 37
Page 38
Page 39
Page 40
Page 41
Page 42
Page 43
Page 44
Page 45
Page 46
Page 47
Page 48
Page 49
Page 50
Page 51
Page 52
Page 53
Page 54
Page 55
Page 56
Page 57
Page 58
Page 59
Page 60
Page 61
Page 62
Page 63
Page 64
Page 65
Page 66
Page 67
Page 68
Page 69
Page 70
Page 71
Page 72
Page 73
Page 74
Page 75
Page 76
Page 77
Page 78
Page 79
Page 80
Page 81
Page 82
Page 83
Page 84
Page 85
Page 86
Page 87
Page 88
Page 89
Page 90
Page 91
Page 92
Page 93
Page 94
Page 95
Page 96
Page 97
Page 98
Page 99
Page 100
Page 101
Page 102
Page 103
Page 104
Page 105
Page 106
Page 107
Page 108
Page 109
Page 110
Page 111
Page 112
Page 113
Page 114
Page 115
Page 116
Page 117
Page 118
Page 119
Page 120
Page 121
Page 122
Page 123
Page 124
Page 125
Reference
Page 126
Page 127

Full Text 
UMFPACK Version 4.3 User Guide
Timothy A. Davis
Dept. of Computer and Information Science and Engineering
Univ. of Florida, Gainesville, FL
Jan. 16, 2004
Abstract
UMFPACK is a set of routines for solving unsymmetric sparse linear systems, Ax = b,
using the Unsymmetric MultiFrontal method and direct sparse LU factorization. It is written in
ANSI/ISO C, with a MATLAB interface. UMFPACK relies on the Level3 Basic Linear Algebra
Subprograms (dense matrix multiply) for its performance. This code works on Windows and
many versions of Unix (Sun Solaris, Red Hat Linux, IBM AIX, SGI IRIX, and Compaq Alpha).
Technical Report TR04003.
UMFPACK Version 4.3 (Jan. 16, 2004), Copyright@2004 by Timothy A. Davis. All Rights
Reserved.
UMFPACK License: Your use or distribution of UMFPACK or any modified version of
UMFPACK implies that you agree to this License.
THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
Permission is hereby granted to use or copy this program, provided that the Copl,riht. this
License, and the Availability of the original version is retained on all copies. User documentation of
any code that uses UMFPACK or any modified version of UMFPACK code must cite the Copvriit.
this License, the Availability note, and "Used by permission." Permission to modify the code and
to distribute modified code is granted, provided the Copyright, this License, and the Availability
note are retained, and a notice that the code was modified is included. This software was developed
with support from the National Science Foundation, and is provided to you free of charge.
Availability: http://www.cise.ufl.edu/research/sparse/umfpack
Acknowledgments:
This work was supported by the National Science Foundation, under grants DMS9504974,
DMS' 1;',''I, and CCR0203270. The upgrade to Version 4.1 and the inclusion of the symmetric
and 2by2 pivoting strategies were done while the author was on sabbatical at Stanford University
and Lawrence Berkeley National Laboratory.
Contents
1 Overview
2 Availability
3 Primary changes since Version 4.1
4 Primary changes in Version 4.1 (since Version 4.0)
5 Using UMFPACK in MATLAB
6 Using UMFPACK in a C program
6.1 The size of an integer ..........
6.2 Real and complex floatingpoint .....
6.3 Primary routines, and a simple example
6.4 A note about zerosized ii , ....
6.5 Alternative routines ...........
6.6 Matrix manipulation routines ......
6.7 Getting the contents of opaque objects .
6.8 Reporting routines .. ..........
6.9 Utility routines .. ...........
6.10 Control parameters .. ..........
6.11 Error codes .. .............
6.12 Larger examples .. ..........
7 Synopsis of Ccallable routines
7.1 Primary routines: real/int .......
7.2 Alternative routines: real/int ......
7.3 Matrix manipulation routines: real/int
7.4
7.5
7.6
7.7
7.8
7.9
7.10
Getting the contents of opaque objects: real/int .
Reporting routines: real/int .. ...........
Primary routines: complex/int .. ..........
Alternative routines: complex/int .. ........
Matrix manipulation routines: complex/int .....
Getting the contents of opaque objects: complex/int
Reporting routines: complex/int .. .........
8 Synopsis of utility routines
9 Synopsis of AMD ordering routines
10 Using UMFPACK in a Fortran program
11 Installing the C library
12 Installing the MATLAB interface
13 Installing the Fortran interface
 : : :
14 Known Issues
15 Future work 30
16 The primary UMFPACK routines 32
16.1 umfpack_*_symbolic .................. ................. .. 32
16.2 umfpack_*_numeric .................. .................. .. 42
16.3 umfpack_*_solve .................. ................... .. 52
16.4 umfpack_*_frc, _, il. . ..i.................... ............... . 57
16.5 umfpack_*_free_numeric .................. ............... .. 58
17 Alternative routines 59
17.1 umfpack_*_defaults.... . .. ........ ................. .. 59
17.2 umfpack_*_qsymbolic .................. ................. .. 61
17.3 umfpack_*_wsolve . . .............. .................. .. 64
18 Matrix manipulation routines 67
18.1 umfpack_*_col_to_triplet .................. ............... .. 67
18.2 umfpack_*_triplet_to_col .................. .............. 69
18.3 umfpack_*_transpose .................. ................. .. 74
18.4 umfpack_*_scale .................. ................... .. 78
19 Getting the contents of opaque objects 80
19.1 umfpack_*_get_lunz... ....... ....... ................. .. 80
19.2 umfpack_*_get_numeric .................. ................ .. 83
19.3 umfpack_*_get_symbolic .................. ............... .. 88
19.4 umfpack_*_save_numeric .................. ............... .. 94
19.5 umfpack_*_loadnumeric .................. ............. .. .. 96
19.6 umfpack_*_save _,l1. .......... . . . .. ............... .. 98
19.7 umfpack_*_l...1. ,il.. . . . .. .................. .............. ..100
20 Reporting routines 102
20.1 umfpack_*_report_status ................... . . . . ... 102
20.2 umfpack_*_report_control .................. . . . . . ... 104
20.3 umfpack_*_report_info ................... . . . . . ... 106
20.4 umfpack_*_report_matrix ................... . . . . ... 108
20.5 umfpack_*_report_numeric .................. . . . . ... 112
20.6 umfpack_*_report_perm ................... . . . . ... 114
20.7 umfpack_*_report _, ili . . ................... .............. 116
20.8 umfpack_*_report_triplet ................... . . . . ... 118
20.9 umfpack_*_report_vector ................... . . . . . 121
21 Utility routines 124
21.1 umfpack_timer .................. ................ . 124
21.2 umfpack_tic and umfpack_toc .................. ............ 125
1 Overview
UMFPACK1 Version 4.3 is a set of routines for solving systems of linear equations, Ax = b, when
A is sparse and unsymmetric. It is based on the Unsymmetricpattern MultiFrontal method [5, 6].
UMFPACK factorizes PAQ, PRAQ, or PR1AQ into the product LU, where L and U are lower
and upper triangular, respectively, P and Q are permutation matrices, and R is a diagonal matrix
of row scaling factors (or R = I if rowscaling is not used). Both P and Q are chosen to reduce
fillin (new nonzeros in L and U that are not present in A). The permutation P has the dual
role of reducing fillin and maintaining numerical accuracy (via relaxed partial pivoting and row
interchanges).
The sparse matrix A can be square or rectangular, singular or nonsingular, and real or complex
(or any combination). Only square matrices A can be used to solve Ax = b or related systems.
Rectangular matrices can only be factorized.
UMFPACK first finds a column preordering that reduces fillin, without regard to numerical
values. It scales and .,!1 '!,.. the matrix, and then automatically selects one of three strategies
for preordering the rows and columns: unsymmetric, 2by2, and symmetric. These strategies are
described below.
First, all pivots with zero Markowitz cost are eliminated and placed in the LU factors. The
remaining submatrix S is then i I1,,.. .1 The following rules are applied, and the first one that
matches defines the strategy.
Rule 1: A rectangular  unsymmetric.
Rule 2: If the zeroMarkowitz elimination results in a rectangular S, or an S whose diagonal
has not been preserved, the unsymmetric strategy is used.
The symmetry a1 of S is computed. It is defined as the number of matched offdiagonal
entries, divided by the total number of offdiagonal entries. An entry sij is matched if sji is
also an entry. They need not be numerically equal. An /iil, is a value in A which is present
in the input data structure. All nonzeros are entries, but some entries may be numerically
zero. Rule 3: a1 < 0.1  unsymmetric. The matrix is very unsymmetric.
Let d be the number of nonzero entries on the diagonal of S. Let S be vbyv. Rule 4:
(a( > 0.7) A (d = v)  symmetric. The matrix has a nearly symmetric nonzero pattern, and
a zerofree diagonal.
If the strategy has not yet been determined, the 2by2 strategy is attempted. A row permuta
tion P2 is found which attempts to reduce the number of small diagonal entries of P2S. An entry
sij is determined to be small if Isij < 0.01 max Is*j, or large otherwise. If sij is numerically small,
the method attempts to swap two rows i and j, such that both sij and sji are large. Once these
rows are swapped, they remain in place. Let (2 be the symmetry of P2S, and let d2 be the number
of nonzero entries (either small or large) on the diagonal of P2S.
Rule 5: (a2 > 1.la) A (d2 > 0.9v)  2by2. The 2by2 permutation has made the matrix
significantly more symmetric.
Rule 6: (2 < 0.7ao  unsymmetric. The 2by2 strategy has significantly deteriorated the
symmetry,
'Pronounced with two syllables: umphpack
* Rule 7: a2 < 0.25  unsymmetric. The matrix is still very unsymmetric.
Rule 8: a2 > 0.51  2by2. The matrix is roughly symmetric.
Rule 9: (2 > 0.999(7 2by2. The 2by2 permutation has preserved symmetry, or made
it only slightly worse.
Rule 10: if no rule has yet triggered, use the unsymmetric strategy.
Each strategy is described below:
,,,,r,,... li,.:. The column preordering of S is computed by a modified version of COLAMD
[7, 8, 26]. The method finds a symmetric permutation Q of the matrix STS (without forming
STS explicitly). This is a good choice for Q, since the C'l._. l:a factors of (SQ)T(SQ) are
an upper bound (in terms of nonzero pattern) of the factor U for the unsymmetric LU
factorization (PSQ = LU) regardless of the choice of P [18, 19, 21]. This modified version
of COLAMD also computes the column elimination tree and postorders the tree. It finds
the upper bound on the number of nonzeros in L and U. It also has a different threshold for
determining dense rows and columns. During factorization, the column preordering can be
modified. Columns within a single supercolumn can be reshuffled, to reduce fillin. Threshold
partial pivoting is used with no preference given to the diagonal entry. Within a given pivot
column j, an entry aij can be chosen if aiy > 0.1 max laj. Among those numerically
acceptable entries, the sparsest row i is chosen as the pivot row.
2by2: The symmetric strategy (see below) is applied to the matrix P2S, rather than S.
,.. ,,... I, :. The column ordering is computed from AMD [1, 2], applied to the pattern of S+
ST followed by a postordering of the supernodal elimination tree of S + ST. No modification
of the column preordering is made during numerical factorization. Threshold partial pivoting
is used, with a strong preference given to the diagonal entry. The diagonal entry is chosen
if ajj > 0.001 max la,jl. Otherwise, a sparse row is selected, using the same method used by
the unsymmetric strategy.
The symmetric and 2by2 strategies, and their automatic selection, are new to Version 4.1.
Version 4.0 only used the unsymmetric strategy.
Once the strategy is selected, the factorization of the matrix A is broken down into the fac
torization of a sequence of dense rectangular frontal matrices. The frontal matrices are related
to each other by a supernodal column elimination tree, in which each node in the tree represents
one frontal matrix. This .,11 1, ,i phase also determines upper bounds on the memory usage, the
floatingpoint operation count, and the number of nonzeros in the LU factors.
UMFPACK factorizes each chain of frontal matrices in a single working array, similar to how
the unifrontal method [17] factorizes the whole matrix. A chain of frontal matrices is a sequence
of fronts where the parent of front i is i+1 in the supernodal column elimination tree. For the
nonsingular matrices factorized with the unsymmetric strategy, there are exactly the same number
of chains as there are leaves in the supernodal column elimination tree. UMFPACK is an outer
product based, rightlooking method. At the kth step of Gaussian elimination, it represents the
updated submatrix Ak as an implicit summation of a set of dense submatrices (referred to as
elements, borrowing a phrase from finiteelement methods) that arise when the frontal matrices are
factorized and their pivot rows and columns eliminated.
Each frontal matrix represents the elimination of one or more columns; each column of A will
be eliminated in a specific frontal matrix, and which frontal matrix will be used for which column
is determined by the pre ii i 1, i, phase. The pre i 1', i, phase also determines the worstcase size
of each frontal matrix so that they can hold any candidate pivot column and any candidate pivot
row. From the perspective of the .11i1 i1, i, phase, any candidate pivot column in the frontal matrix
is identical (in terms of nonzero pattern), and so is any row. However, the numeric factorization
phase has more information than the .11i1 i1, i phase. It uses this information to reorder the columns
within each frontal matrix to reduce fillin. Similarly, since the number of nonzeros in each row and
column are maintained (more precisely, COLMMD , 1., approximate degrees [20]), a pivot row can
be selected based on sparsitypreserving criteria (low degree) as well as numerical considerations
(relaxed threshold partial pivoting).
When the symmetric or 2by2 strategies are used, the column preordering is not refined during
numeric factorization. Row pivoting for sparsity and numerical accuracy is performed if the diagonal
entry is too small.
More details of the method, including experimental results, are described in [4, 4], available at
http://www.cise.ufl.edu/techreports.
2 Availability
In addition to appearing as a Collected Algorithm of the ACM, UMFPACK Version 4.3 is available
at http://www.cise.ufl.edu/research/sparse. An earlier version (Version 4.0) is included as a built
in routine in MATLAB 6.5. Version 4.0 does not have the symmetric or 2by2 strategies and it
takes less advantage of the level3 BLAS [10, 11, 27, 24]. Version 4.3 (and v4.2 and v4.1) tend to be
much faster than Version 4.0, particularly on unsymmetric matrices with mostly symmetric nonzero
pattern (such as finite element and circuit simulation matrices). Version 3.0 and following make use
of a modified version of COLAMD V2.0 by Timothy A. Davis, Stefan Larimore, John Gilbert, and
Esmond Ng. The original COLAMD V2.1 is available in as a builtin routine in MATLAB V6.0
(or later), and at http://www.cise.ufl.edu/research/sparse. These codes are also available in Netlib
[12] at http://www.netlib.org. UMFPACK Versions 2.2.1 and earlier, coauthored with Iain Duff,
are available at http://www.cise.ufl.edu/research/sparse and as MA38 (functionally equivalent to
Version 2.2.1) in the Harwell Subroutine Library.
3 Primary changes since Version 4.1
No changes are visible to the C or MATLAB user, except the presence of one new control parameter
in the Control in i', and three new statistics in the Info array. The primary change is the addition
of an (optional) drop tolerance.
4 Primary changes in Version 4.1 (since Version 4.0)
A detailed list of changes is in the ChangeLog file. The following is a summary of the main changes
that are visible to the C or MATLAB user:
1. New ordering strategies added. No changes are required in user code (either C or MATLAB) to
use the new default strategy, which is an automatic selection of the unsymmetric, symmetric,
or 2by2 strategies.
2. Row scaling added. This is only visible to the MATLAB caller when using the form [L,U,P, Q,R]
= umfpack (A), to retrieve the LU factors. Likewise, it is only visible to the C caller when
the LU factors are retrieved, or when solving systems with just L or U. New Ccallable and
MATLABcallable routines are included to get and to apply the scale factors computed by
UMFPACK. Row scaling is enabled by default, but can be disabled. Row scaling usually
leads to a better factorization, particularly when the symmetric strategy is used.
3. Error code UMFPACKERROR_problem_to_large removed. Version 4.0 would generate this error
when the upper bound memory usage exceeded 2GB (for the int version), even when the
actual memory usage was less than this. The new version properly handles this case, and can
successfully factorize the matrix if sufficient memory is available.
4. New control parameters and statistics provided.
5. The AMD symmetric approximate minimum degree ordering routine added [1, 2]. It is used
by UMFPACK, and can also be called independently from C or MATLAB.
6. The umfpack mexFunction now returns permutation matrices, not permutation vectors, when
using the form [L,U,P,Q] = umfpack (A) or the new form [L,U,P,Q,R] = umfpack (A).
7. New arguments added to the usercallable routines umfpack_*_symbolic, umfpack_*_qsymbolic,
umfpack_*_get_numeric, and umfpack_*_get_symbolic. The ',nilli i :. i1, now makes
use of the numerical values of the matrix A, to guide the 2by2 strategy. The subsequent
matrix passed to the numeric factorization step does not have to have the same numerical
values. All of the new arguments are optional. If you do not wish to include them, simply
pass NULL pointers instead. The 2by2 strategy will assume all entries are numerically large,
for example.
8. New routines added to save and load the Numeric and Symbolic objects to and from a binary
file.
9. A Fortran interface added. It provides access to a subset of UMFPACK's features.
10. You can compute an incomplete LU factorization, by dropping small entries from L and U.
By default, no nonzero entry is dropped, no matter how small in absolute value. This feature
is new to Version 4.3.
5 Using UMFPACK in MATLAB
The easiest way to use UMFPACK is within MATLAB. Version 4.0 is a builtin routine in MATLAB
6.5, and is used in x = A\b when A is sparse, square, unsymmetric (or symmetric but not positive
definite), and with nonzero entries that are not confined in a narrow band. It is also used for the
[L,U,P,Q] = lu (A) usage of lu. Type help lu in MATLAB 6.5 or later for more details.
To use the UMFPACK mexFunction, you must download and compile it, since the mexFunction
itself is not part of MATLAB. The following discussion assumes that you have MATLAB Version 6.0
or later (which includes the BLAS, and the colamd ordering routine). To compile both the UMF
PACK and AMD mexFunctions, just type make in the Unix system shell, while in the UMFPACK
directory. You can also type umfpack_make in MATLAB, if you are in the UMFPACK/MATLAB direc
tory, or if that directory is in your MATLAB path. This works on any system with MATLAB,
including Windows. See Section 11 for more details on how to install UMFPACK. Once installed,
the UMFPACK mexFunction can mI1 i,.. factor, and solve linear systems. Table 1 summarizes
some of the more common uses of the UMFPACK mexFunction within MATLAB.
Table 1: Using UMFPACK's MATLAB interface
Function Using UMFPACK MATLAB 6.0 equivalent
Solve Ax = b. x = umfpack (A,'\',b) ;x = A \ b ;
Solve Ax b using S = spones (A) ; spparms ('autommd',0) ;
a different column pre Q = symamd (S+S') ; S = spones (A) ;
ordering, x = umfpack (A,Q,'\',b) ; Q = symamd (S+S')
x = A (:,Q) \ b
x (Q) = x ;
spparms ('autommd',1) ;
Solve ATxT bT. x = umfpack (b,'/',A) ;x = b / A ;
Scale and factorize A, then [L,U,P,Q,R] = umfpack (A) ; [m n] = size (A)
solve Ax= b. c = P (R \ b); r = full (sum (abs (A), 2));
x = Q (U \ (L \ c)) ;r (find (r == 0)) = 1 ;
R = spdiags (r, 0, m, m)
I = speye (n) ;
Q = I (:, colamd (A))
[L,U,P] = lu ((R\A)*Q)
c = P*(R \ b) ;
x = Q (U \ (L \ c))
An optional input argument can be used to modify the control parameters for UMFPACK,
and an optional output argument provides statistics on the factorization. UMFPACK will print
these statistics if you turn on the sparse matrix monitor flag with spparms ('spumoni', 1). The
UMFPACK printing level parameter described in Section 6.8 is set to spumoni plus 1. Type help
umfpack for more information.
Refer to the AMD User Guide for more details about the AMD mexFunction.
Note: in MATLAB 6.5, use spparms ('autoamd',0) in addition to spparms ('autommd',0),
in Table 1, to turn off MATLAB's default reordering.
UMFPACK requires b to be a dense vector (real or complex) of the appropriate dimension.
This is more restrictive than what you can do with MATLAB's backlash or forward slash. See
umfpack_solve for an Mfile that removes this restriction. This restriction does not apply to the
builtin backlash operator in MATLAB 6.5, which uses UMFPACK v4.0 to factorize the matrix.
You can do this yourself in MATLAB:
[L,U,P,Q,R] = umfpack (A) ;
x = Q (U \ (L \ (P (R \ b))))
or, with no row scaling:
[L,U,P,Q] = umfpack (A)
x = Q (U \ (L \ (P b)))
The above examples do not make use of the iterative refinement that is built into x = umfpack
(A, '\',b) however.
MATLAB's [L,U,P] = lu(A) returns a lower triangular L, an upper triangular U, and a per
mutation matrix P such that P*A is equal to L*U. UMFPACK behaves differently. By default, it
scales the rows of A and reorders the columns of A prior to factorization, so that L*U is equal to
P* (R\A)*Q, where R is a diagonal sparse matrix of scale factors for the rows of A. The scale factors
R are applied to A via the MATLAB expression R\A to avoid multiplying by the reciprocal, which
can be numerically inaccurate.
There are more options; you can provide your own column preordering (in which case UMF
PACK does not call COLAMD or AMD), you can modify other control settings (similar to the
spparms in MATLAB), and you can get various statistics on the ,ii1 I, i. factorization, and solution
of the linear , I. 1i1 Type umfpack_details and umfpack_report in MATLAB for more informa
tion. Two demo Mfiles are provided. Just type umfpack_simple and umfpack_demo to run them.
The output of these two programs should be about the same as the files umfpack_simple.m.out
and umfpack_demo.m.out that are provided.
Factorizing A' (or A. ') and using the transposed factors can sometimes be faster than factorizing
A. It can also be preferable to factorize A' if A is rectangular. UMFPACK preorders the columns
to maintain sparsity; the row ordering is not determined until the matrix is factorized. Thus, if A
is m by n with rank m and m < n, then umfpack might not find a factor U with a zerofree diagonal.
Unless the matrix illconditioned or poorly scaled, factorizing A' in this case will guarantee that
both factors will have zerofree diagonals. Here's how you can factorize A' and get the factors of A
instead:
[l,u,p,q] = umfpack (A')
L =u'
U = ;
P= q;
Q=p;
clear 1 u p q
This is an alternative to [L,U,P,Q]=umfpack(A).
A simple Mfile (umfpack_btf) is provided that first permutes the matrix to upper block trian
gular form, using MATLAB's dmperm routine, and then solves each block. The LU factors are not
returned. Its usage is simple: x = umfpack_btf(A,b). Type help umfpack_btf for more options.
An estimate of the 1norm of L*UP*A*Q can be computed in MATLAB as lu_normest (P*A*Q,L,U),
using the lu_normest.m Mfile by Hager and Davis [9] that is included with the UMFPACK dis
tribution. With row scaling enabled, use lu_normest(P*(R\A)*Q, L,U) instead.
One issue you may encounter is how UMFPACK allocates its memory when being used in
a mexFunction. One part of its working space is of variable size. The , il..lib ;.i1 I1, i phase
determines an upper bound on the size of this memory, but not all of this memory will typically
be used in the numerical factorization. UMFPACK tries to allocate a decent amount of working
space. This is 711' of the upper bound, by default, for the unsymmetric strategy. For the symmetric
strategy, the fraction of the upper bound is computed automatically (assuming a bestcase scenario
with no numerical pivoting required during numeric factorization). If this initial allocation fails, it
reduces its request and uses less memory. If the space is not large enough during factorization, it
is increased via mxRealloc.
However, mxMalloc and mxRealloc abort the umfpack mexFunction if they fail, so this strategy
does not work in MATLAB. The strategy works fine when malloc or the internal memory allocator
utMalloc are used instead, since those routines return NULL on failure, and do not terminate
the mexFunction. The umfpack mexFunction can be compiled to use utMalloc, but this is an
internal undocumented utility routine in MATLAB, and thus using utMalloc might not i', , be
successful. To use the documented mxMalloc routine instead, compile the mexFunction with the
DNUTIL flag enabled.
6 Using UMFPACK in a C program
The Ccallable UMFPACK library consists of 31 usercallable routines and one include file. Twenty
seven of the routines come in four versions, with different sizes of integers and for real or complex
floatingpoint numbers:
1. umfpack_di_*: real double precision, int integers.
2. umfpack_dl_*: real double precision, long integers.
3. umfpackzi_*: complex double precision, int integers.
4. umfpackzl_*: complex double precision, long integers.
where denotes the specific name of one of the 27 routines. Routine names beginning with umf
are internal to the package, and should not be called by the user. The include file umfpack.h must
be included in any C program that uses UMFPACK. The other three routines are the same for all
four versions.
In addition, the Ccallable AMD library distributed with UMFPACK includes 4 usercallable
routines (in two versions with int and long integers) and one include file. Refer to the AMD
documentation for more details.
Use only one version for any one problem; do not attempt to use one version to .111 I,. the
matrix and another version to factorize the matrix, for example.
The notation umfpack_di_* refers to all 27 usercallable routines for the real double preci
sion and int integer case. The notation umfpack_*_numeric, for example, refers all four versions
(real/complex, int/long) of a single operation (in this case numeric factorization).
6.1 The size of an integer
The umfpack_di_* and umfpackzi_* routines use int integer arguments; those starting with
umfpack_dl_ or umfpack_zl_ use long integer arguments. If you compile UMFPACK in the stan
dard ILP32 mode (32bit into's, long's, and pointers) then the versions are essentially identical.
You will be able to solve problems using up to 2GB of memory. If you compile UMFPACK in the
standard LP64 mode, the size of an int remains 32bits, but the size of a long and a pointer both
get promoted to 64bits. In the LP64 mode, the umfpack_dl_* and umfpack_zl_* routines can solve
huge problems (not limited to 2GB), limited of course by the amount of available memory. The
only drawback to the 64bit mode is that not all BLAS libraries support 64bit integers. This limits
the performance you will obtain. Those that do support 64bit integers are specific to particular
architectures, and are not portable. UMFPACK and AMD should be compiled in the same mode.
If you compile UMFPACK and AMD in the LP64 mode, be sure to add DLP64 to the compilation
command. See the examples in Make. alpha, Make.sgi, and Make. solaris.
6.2 Real and complex floatingpoint
The umfpack_di_* and umfpack_dl_* routines take (real) double precision arguments, and return
double precision arguments. In the umfpackzi_* and umfpack_zl_* routines, these same arguments
hold the real part of the matrices; and second double precision ii hold the imaginary part of
the input and output matrices. Internally, complex numbers are stored in arrays with their real
and imaginary parts interleaved, as required by the BLAS.
6.3 Primary routines, and a simple example
Five primary UMFPACK routines are required to factorize A or solve Ax = b. They are fully
described in Section 16:
umfpack_*_symbolic:
Preorders the columns of A to reduce fillin. Returns an opaque Symbolic object as a
void pointer. The object contains the symbolic .111 i1, i, and is needed for the numeric
factorization. This routine requires only O(A) space, where IAI is the number of nonzero
entries in the matrix. It computes upper bounds on the nonzeros in L and U, the floating
point operations required, and the memory usage of umfpack_*_numeric. The Symbolic
object is small; it contains just the column preordering, the supernodal column elimination
tree, and information about each frontal matrix. It is no larger than about 13n integers if A
is nb, ,,
umfpack_*_numeric:
Numerically scales and then factorizes a sparse matrix into PAQ, PRAQ, or PR1AQ into
the product LU, where P and Q are permutation matrices, R is a diagonal matrix of scale
factors, L is lower triangular with unit diagonal, and U is upper triangular. Requires the
, ,l .i ordering and .1i i, i, computed by umfpack_*_symbolic or umfpack_*_qsymbolic.
Returns an opaque Numeric object as a void pointer. The object contains the numeri
cal factorization and is used by umfpack_*_solve. You can factorize a new matrix with a
different values (but identical pattern) as the matrix .,,_ !,...1 by umfpack_*_symbolic or
umfpack_*_qsymbolic by reusing the Symbolic object (this feature is available when using
UMFPACK in a C or Fortran program, but not in MATLAB). The matrix U will have zeros
on the diagonal if A is singular; this produces a warning, but the factorization is still valid.
umfpack_*_solve:
Solves a sparse linear , I. 111 (Ax = b, ATx = b, or systems involving just L or U), using
the numeric factorization computed by umfpack_*_numeric. Iterative refinement with sparse
backward error [3] is used by default. The matrix A must be square. If it is singular,
then a dividebyzero will occur, and your solution with contain IEEE Inf's or NaN's in the
appropriate places.
umfpack_*_free_symbolic:
Frees the Symbolic object created by umfpack_*_symbolic or umfpack_*_qsymbolic.
umfpack_*_free_numeric:
Frees the Numeric object created by umfpack_*_numeric.
Be careful not to free a Symbolic object with umfpack_*_freenumeric. Nor should you attempt
to free a Numeric object with umfpack_*_free_symbolic. Failure to free these objects will lead to
memory leaks.
The matrix A is represented in compressed column form, which is identical to the sparse matrix
representation used by MATLAB. It consists of three or four arrays, where the matrix is mbyn,
with nz entries. For the int version of UMFPACK:
int Ap [n+] ;
int Ai [nz] ;
double Ax [nz] ;
For the long version of UMFPACK:
long Ap [n+] ;
long Ai [nz] ;
double Ax [nz] ;
The complex versions add another array for the imaginary part:
double Az [nz] ;
All nonzeros are entries, but an entry may be numerically zero. The row indices of entries in
column j are stored in Ai [Ap[j] ... Ap[j+1]1]. The corresponding numerical values are stored
in Ax [Ap[j] ... Ap[j+1]1]. The imaginary part, for the complex versions, is stored in Az[Ap[j]
...Ap[j+1]1].
No duplicate row indices may be present, and the row indices in any given column must be
sorted in ascending order. The first entry Ap [0] must be zero. The total number of entries in the
matrix is thus nz = Ap [n]. Except for the fact that extra zero entries can be included, there is thus
a unique compressed column representation of any given matrix A. For a more flexible method for
providing an input matrix to UMFPACK, see Section 6.6.
Here is a simple main program, umfpack_simple.c, that illustrates the basic usage of UMF
PACK. See Section 7 for a short description of each calling sequence, including a list of options for
the first argument of umfpack_di_solve.
#include
#include "umfpack.h"
int n = 5 ;
int Ap [ ] = {0, 2, 5, 9, 10, 12} ;
int Ai [ ] = { 0, 1, 0, 2, 4, 1, 2, 3, 4, 2, 1, 4} ;
double Ax [ ] = {2., 3., 3., 1., 4., 4., 3., 1., 2., 2., 6., 1.} ;
double b [ ] = {8., 45., 3., 3., 19.} ;
double x [5] ;
int main (void)
{
double *null = (double *) NULL ;
int i ;
void *Symbolic, *Numeric ;
(void) umfpack_di_symbolic (n, n, Ap, Ai, Ax, &Symbolic, null, null)
(void) umfpackdinumeric (Ap, Ai, Ax, Symbolic, &Numeric, null, null)
umfpack_di_free_symbolic (&Symbolic) ;
(void) umfpackdisolve (UMFPACK_A, Ap, Ai, Ax, x, b, Numeric, null, null)
umfpack_di_free_numeric (&Numeric) ;
for (i = 0 ; i < n ; i++) printf ("x [%d] = %g\n", i, x [i]) ;
return (0) ;
1
The Ap, Ai, and Ax arrays represent the matrix
2 3 0 0 0
3 0 406
A 0 1 3 2 0
0 0 1 0 0
0 4 2 0 1
and the solution to Ax = b is x = [12 3 4 5]T. The program uses default control settings and
does not return any statistics about the ordering, factorization, or solution (Control and Info are
both (double *) NULL). It also ignores the status value returned by most usercallable UMFPACK
routines.
6.4 A note about zerosized arrays
UMFPACK uses many userprovided arrays of size m or n (the order of the matrix), and of size
nz (the number of nonzeros in a matrix). UMFPACK does not handle zerodimensioned arrays; it
returns an error code if m or n are zero. However, nz can be zero, since all singular matrices are
handled correctly. If you attempt to malloc an array of size nz = 0, however, malloc will return
a null pointer which UMFPACK will report as a missing argument. If you malloc an array of size
nz to pass to UMFPACK, make sure that you handle the nz = 0 case correctly (use a size equal to
the maximum of nz and 1, or use a size of nz+l).
6.5 Alternative routines
Three alternative routines are provided that modify UMFPACK's default behavior. They are fully
described in Section 17:
*umfpack_*_defaults:
Sets the default control parameters in the Control array. These can then be modified as
desired before passing the array to the other UMFPACK routines. Control parameters are
summarized in Section 6.10. Three particular parameters deserve special notice. UMFPACK
uses relaxed partial pivoting, where a candidate pivot entry is numerically acceptable if its
magnitude is greater than or equal to a tolerance parameter times the magnitude of the
largest entry in the same column. The parameter Control [UMFPACK_PIVOT_TOLERANCE]
has a default value of 0.1, and is used for the unsymmetric strategy. For complex matrices,
a cheap approximation of the absolute value is used for the threshold pivoting test (lal
'1, .1 + aimagDl)
For the symmetric strategy, a second tolerance is used for diagonal entries:
Control [UMFPACK_SYM_PIVOT_TOLERANCE], with a default value of 0.001. The first parame
ter (with a default of 0.1) is used for any offdiagonal candidate pivot entries.
These two parameters may be too small for some matrices, particularly for illconditioned or
poorly scaled ones. With the default pivot tolerances and default iterative refinement, x =
umfpack (A, '\',b) is just as accurate as (or more accurate) than x = A\b in MATLAB 6.1
for nearly all matrices.
If Control [UMFPACKPIVOT_TOLERANCE] is zero, than any nonzero entry is acceptable as a
pivot (this is changed from Version 4.0, which treated a value of 0.0 the same as 1.0). If the
symmetric strategy is used, and Control [UMFPACK_SYM_PIVOT_TOLERANCE] is zero, then any
nonzero entry on the diagonal is accepted as a pivot. Offdiagonal pivoting will still occur if the
diagonal entry is exactly zero. The Control [UMFPACK_SYMPIVOT_TOLERANCE] parameter is
new to Version 4.1. It is similar in function to the pivot tolerance for leftlooking methods (the
MATLAB THRESH option in [L,U,P] = lu (A, THRESH), and the pivot tolerance parameter
in SuperLU).
The parameter Control [UMFPACK_STRATEGY] can be used to bypass UMFPACK's automatic
strategy selection. The automatic strategy nearly i'. ,, selects the best method. When it
does not, the different methods nearly ,'. i,, give about the same quality of results. There
may be cases where the automatic strategy fails to pick a good strategy. Also, you can save
some computing time if you know the right strategy for your set of matrix problems.
umfpack_*_qsymbolic:
An alternative to umfpack_*_symbolic. Allows the user to specify his or her own column
preordering, rather than using the default COLAMD or AMD preorderings. For example,
a graph partitioningbased order of ATA would be suitable for UMFPACK's unsymmetric
strategy. A partitioning of A + AT would be suitable for UMFPACK's symmetric or 2by2
strategies.
umfpack_*_wsolve:
An alternative to umfpack_*_solve which does not dynamically allocate any memory. Re
quires the user to pass two additional work arrays.
6.6 Matrix manipulation routines
The compressed column data structure is compact, and simplifies the UMFPACK routines that
operate on the sparse matrix A. However, it can be inconvenient for the user to generate. Section 18
presents the details of routines for manipulating sparse matrices in triplet form, compressed column
form, and compressed row form (the transpose of the compressed column form). The triplet form
of a matrix consists of three or four arrays. For the int version of UMFPACK:
int Ti [nz] ;
int Tj [nz] ;
double Tx [nz] ;
For the long version:
long Ti [nz] ;
long Tj [nz] ;
double Tx [nz] ;
The complex versions use another array to hold the imaginary part:
double Tz [nz] ;
The kth triplet is (i, j, aij), where i = Ti[k], j = Tj [k], and aij = Tx[k]. For the complex
versions, Tx [k] is the real part of aij and Tz [k] is the imaginary part. The triplets can be in any
order in the Ti, Tj, and Tx arrays (and Tz for the complex versions), and duplicate entries may
exist. Any duplicate entries are summed when the triplet form is converted to compressed column
form. This is a convenient way to create a matrix arising in finiteelement methods, for example.
Four routines are provided for manipulating sparse matrices:
umfpack_*_triplet_to_col:
Converts a triplet form of a matrix to compressed column form (ready for input to
umfpack_*_symbolic, umfpack_*_qsymbolic, and umfpack_*_numeric). Identical to A =
spconvert (i, x) in MATLAB, except that zero entries are not removed, so that the pattern
of entries in the compressed column form of A are fully under user control. This is important
if you want to factorize a new matrix with the Symbolic object from a prior matrix with the
same pattern as the new one.
umfpack_*_col_to_triplet:
The opposite of umfpack_*_triplet_to_col. Identical to [i,j,x] = find(A) in MATLAB,
except that numerically zero entries may be included.
umfpack_*_transpose:
Transposes and optionally permutes a column form matrix [25]. Identical to R = A(P,Q)'
(linear algebraic transpose, using the complex <,.iiin: ,.I!) or R = A(P,Q). (the array trans
pose) in MATLAB, except for the presence of numerically zero entries.
Factorizing AT and then solving Ax = b with the transposed factors can sometimes be much
faster or much slower than factorizing A. It is highly dependent on your particular matrix.
umfpack_*_scale:
Applies the row scale factors to a userprovided vector. This is not required to solve the
sparse linear system Ax b or ATx b, since umfpack_*_solve applies the scale factors
for those systems. This routine is new to Version 4.1.
It is quite easy to add matrices in triplet form, subtract them, transpose them, permute them,
construct a submatrix, and multiply a tripletform matrix times a vector. UMFPACK does not pro
vide code for these basic operations, however. Refer to the discussion of umfpack_*_triplet_to_col
in Section 18 for more details on how to compute these operations in your own code. The only
primary matrix operation not provided by UMFPACK is the multiplication of two sparse matrices
[25].
6.7 Getting the contents of opaque objects
There are cases where you may wish to do more with the LU factorization of a matrix than solve a
linear , I, i1, The opaque Symbolic and Numeric objects are just that opaque. You cannot do
anything with them except to pass them back to subsequent calls to UMFPACK. Three routines are
provided for c. .i, in: their contents into userprovided arrays using simpler data structures. Four
routines are provided for saving and loading the Numeric and Symbolic objects to/from binary
files. They are fully described in Section 19:
umfpack_*_get_lunz:
Returns the number of nonzeros in L and U.
umfpack_*_get_numeric:
Copies L, U, P, Q, and R from the Numeric object into arrays provided by the user. The
matrix L is returned in compressed row form (with the column indices in each row sorted
in ascending order). The matrix U is returned in compressed column form (with sorted
columns). There are no explicit zero entries in L and U, but such entries may exist in the
Numeric object. The permutations P and Q are represented as permutation vectors, where
P [k] = i means that row i of the original matrix is the the kth row of PAQ, and where
Q [k] = j means that column j of the original matrix is the kth column of PAQ. This is
identical to how MATLAB uses permutation vectors (type help colamd in MATLAB 6.1 or
later).
umfpack_*_get_symbolic:
Copies the contents of the Symbolic object (the initial row and column ip. ..1i. ,:_. supern
odal column elimination tree, and information about each frontal matrix) into 11 1, provided
by the user.
umfpack_*_save_numeric:
Saves a copy of the Numeric object to a file, in binary format.
umfpack_*_load_numeric:
Creates a Numeric object by loading it from a file created by umfpack_*_save_numeric.
umfpack_*_save_symbolic:
Saves a copy of the Symbolic object to a file, in binary format.
umfpack_*_load_symbolic:
Creates a Symbolic object by loading it from a file created by umfpack_*_save_symbolic.
UMFPACK itself does not make use of these routines; they are provided solely for returning
the contents of the opaque Symbolic and Numeric objects to the user, and saving/loading them
to/from a binary file.
6.8 Reporting routines
None of the UMFPACK routines discussed so far prints anything, even when an error occurs.
UMFPACK provides you with nine routines for printing the input and output arguments (including
the Control settings and Info statistics) of UMFPACK routines discussed above. They are fully
described in Section 20:
umfpack_*_report_status:
Prints the status (return value) of other umfpack_* routines.
umfpack_*_report_info:
Prints the statistics returned in the Info i i , by umfpack_*_*symbolic, umfpack_*_numeric,
and umfpack_*_*solve.
umfpack_*_report_control:
Prints the Control settings.
umfpack_* _reportmat rix:
Verifies and prints a compressed columnform or compressed rowform sparse matrix.
umfpack_*_report _triplet:
Verifies and prints a matrix in triplet form.
umfpack_*_report_symbolic:
Verifies and prints a Symbolic object.
umfpack_*_report _numeric:
Verifies and prints a Numeric object.
umfpack_*_report_perm:
Verifies and prints a permutation vector.
umfpack_*_report _vector:
Verifies and prints a real or complex vector.
The umfpack_*_report_* routines behave slightly differently when compiled into the Ccallable
UMFPACK library than when used in the MATLAB mexFunction. MATLAB stores its sparse
matrices using the same compressed column data structure discussed above, where row and column
indices of an mb, , matrix are in the range 0 to m 1 or n 1, respectively. It prints them as if
they are in the range 1 to m or n. The UMFPACK mexFunction behaves the same way.
You can control how much the umfpack_*_report_* routines print by modifying the Control
[UMFPACKPRL] parameter. Its default value is 1. Here is a summary of how the routines use this
print level parameter:
umfpack_*_report _status:
No output if the print level is 0 or less, even when an error occurs. If 1, then error messages
are printed, and nothing is printed if the status is UMFPACKOK. A warning message is printed
if the matrix is singular. If 2 or more, then the status is i' , printed. If 4 or more, then
the UMFPACK Copyright is printed. If 6 or more, then the UMFPACK License is printed.
See also the first page of this User Guide for the Copi,riht and License.
umfpack_*_report_control:
No output if the print level is 1 or less. If 2 or more, all of Control is printed.
umfpack_*_report_info:
No output if the print level is 1 or less. If 2 or more, all of Info is printed.
all other umfpack_*_report_* routines:
If the print level is 2 or less, then these routines return silently without checking their inputs.
If 3 or more, the inputs are fully verified and a short status summary is printed. If 4, then
the first few entries of the input arguments are printed. If 5, then all of the input arguments
are printed.
This print level parameter has an additional effect on the MATLAB mexFunction. If zero, then
no warnings of singular or nearly singular matrices are printed (similar to the MATLAB commands
warning off MATLAB: singularMatrix and warning off MATLAB:nearlySingularMatrix).
Table 2: UMFPACK Control parameters
ANSI C default description
Control [UMFPACKPRL] 1 printing level
Control [UMFPACKDENSEROW] 0.2 dense row parameter
Control [UMFPACKDENSE_COL] 0.2 dense column parameter
Control [UMFPACKPIVOT_TOLERANCE] 0.1 partial pivoting tolerance
Control [UMFPACKBLOCK_SIZE] 32 BLAS block size
Control [UMFPACKSTRATEGY] 0 (auto) select strategy
Control [UMFPACKALLOC_INIT] 0.7 initial memory allocation
Control [UMFPACK_IRSTEP] 2 max iter. refinement steps
Control [UMFPACK_2BY2_TOLERANCE] 0.01 defines "large" entries
Control [UMFPACKFIXQ] 0 (auto) fix or i... .. 1;. Q
Control [UMFPACKAMDDENSE] 10 AMD dense row/column parameter
Control [UMFPACK_SYMPIVOT_TOLERANCE] 0.001 for diagonal entries
Control [UMFPACK_SCALE] 1 (sum) row scaling (none, sum, or max)
Control [UMFPACKFRONTALLOC_INIT] 0.5 frontal matrix allocation ratio
Control [UMFPACKDROPTOL] 0 drop tolerance
Control [UMFPACKAGGRESSIVE] 1 (yes) aggressive absorption
in AMD and COLAMD
Can only be changed at compile time:
Control(9) Control [UMFPACK_COMPILED_WITH_BLAS]
Control(10) Control [UMFPACK_COMPILEDFORATLAB]
Control(11) Control [UMFPACK_COMPILED_WITH_GETRUSAGE]
Control(12) Control [UMFPACK_COMPILED_INDEBUG_MODE]
true if BLAS is used
true for mexFunction
1 if getrusage used
true if debug mode enabled
6.9 Utility routines
UMFPACK v4.0 included a routine that returns the time used by the process, umfpack_timer.
The routine uses either getrusage (which is preferred), or the ANSI C clock routine if that is not
available. It is fully described in Section 21. It is still available in UMFPACK v4.1 and following, but
not used internally. Two new timing routines are provided in UMFPACK Version 4.1 and following,
umfpack_tic and umfpack_toc. They use POSIXcompliant sysconf and times routines to find
both the CPU time and wallclock time. These three routines are the only usercallable routine that
is identical in all four int/long, real/complex versions (there is no umfpack_di_timer routine, for
example).
6.10 Control parameters
UMFPACK uses an optional double array (currently of size 20) to modify its control parameters.
If you pass (double *) NULL instead of a Control array, then defaults are used. This array will
almost certainly grow in size in future releases, so be sure to dimension your Control array to be
of size UMFPACK_CONTROL. That constant is currently defined to be 20, but will increase in future
versions.
The contents of this array may be modified by the user (see umfpack_*_defaults). Each user
callable routine includes a complete description of how each control setting modifies its behavior.
Table 2 summarizes the entire contents of the Control array. Note that ANSI C uses 0based
indexing, while MATLAB uses 1based indexing. Thus, Control(1) in MATLAB is the same as
Control [0] or Control [UMFPACKPRL] in ANSI C.
Let aOr Control [UMFPACKDENSE_ROW], ac Control [UMFPACK_DENSE_COL], and a =Control
[UMFPACK_AMD_DENSE]. Suppose the submatrix S, obtained after eliminating pivots with zero Markowitz
cost, is mb, ,, Then a row is considered .I i , if it has more than max(16, 16ar/ni) entries. A
column is considered I ii, if it has more than max(16, 16ac/m) entries. These rows and columns
MATLAB
Control(1)
Control(2)
Control(3)
Control(4)
Control(5)
Control(6)
Control(7)
Control(8)
Control(13)
Control(14)
Control(15)
Control(16)
Control(17)
Control(18)
Control(19)
Control(20)
are treated different in COLAMD and during numerical factorization. In COLAMD, dense columns
are placed last in their natural order, and dense rows are ignored. During numerical factorization,
dense rows are stored differently. In AMD, a row/column of the square matrix S + ST is consid
ered .I ii, if it has more than max(16, aqn) entries. These rows/columns are placed last in
AMD's output ordering. For more details on the control parameters, refer to the documentation of
umfpack_*_qsymbolic, umfpack_*_numeric, umfpack_*_solve, and the umfpack_*_report_* rou
tines, in Sections 16 through 20, below.
6.11 Error codes
M i,', of the routines return a status value. This is also returned as the first entry in the Info
array, for those routines with that argument. The following list summarizes all of the error codes
in UMFPACK v4.3. Each error code is given a specific name in the umfpack.h include file, so you
can use those constants instead of hardcoded values in your program. Future versions may report
additional error codes.
A value of zero means everything was successful, and the matrix is nonsingular. A value greater
than zero means the routine was successful, but a warning occurred. Currently, the only warning
code is when the matrix is singular. A negative value means the routine was not successful. In this
case, no Symbolic or Numeric object was created.
UMFPACKOK, (0): UMFPACK was successful.
UMFPACK_WARNING_singular_matrix, (1): Matrix is singular. There are exact zeros on the
diagonal of U.
UMFPACKERROR_out_ofmemory, (1): Not enough memory. The ANSI C malloc or realloc
routine failed.
UMFPACKERROR_invalid_Numeric_obj ect, (3): Routines that take a Numeric object as input
(or load it from a file) check this object and return this error code if it is invalid. This can
be caused by a memory leak or overrun in your program, which can overwrite part of the
Numeric object. It can also be caused by passing a Symbolic object by mistake, or some
other pointer. If you try to factorize a matrix using one version of UMFPACK and then
use the factors in another version, this error code will trigger as well. You cannot factor
your matrix using version 4.0 and then solve with version 4.1. You cannot use different
precisions of the same version (real and complex, for example). It is possible for the Numeric
object to be corrupted by your program in subtle ways that are not detectable by this quick
check. In this case, you may see an UMFPACK_ERROR_dif f erent_pattern error code, or even
an UMFPACKERROR_internal_error.
UMFPACKERROR_invalid_Symbolic_object, (4): Routines that take a Symbolic object as
input (or load it from a file) check this object and return this error code if it is invalid.
The causes of this error are analogous to the UMFPACK_ERROR_invalid_Numeric_object error
described above.
UMFPACKERROR_argument_missing, (5): Some arguments of some are optional (you can pass
a NULL pointer instead of an oii ',). This error code occurs if you pass a NULL pointer when
that argument is required to be present.
UMFPACKERROR_n_nonpositive (6): The number of rows or columns of the matrix must be
greater than zero.
UMFPACKERROR_invalid_matrix (8): The matrix is invalid. For the columnoriented input,
this error code will occur if the contents of Ap and/or Ai are invalid.
Ap is an integer array of size n_col+l. On input, it holds the i." i..l i s" for the column form of
the sparse matrix A. Column j of the matrix A is held in Ai [(Ap [j]) ... (Ap [j+1]1)].
The first entry, Ap [0], must be zero, and Ap [j] < Ap [j+1] must hold for all j in the
range 0 to n_col1. The value nz = Ap [n_col] is thus the total number of entries in the
pattern of the matrix A. nz must be greater than or equal to zero.
The nonzero pattern (row indices) for column j is stored in Ai [(Ap [j]) ... (Ap [j+] 1)].
The row indices in a given column j must be in ascending order, and no duplicate row indices
may be present. Row indices must be in the range 0 to n_row1 (the matrix is 0based).
Some routines take a tripletform input, with arguments nz, Ti, and Tj. This error code is
returned if nz is less than zero, if any row index in Ti is outside the range 0 to n_col1, or
if any column index in Tj is outside the range 0 to n_row1.
UMFPACKERROR_different_pattern, (11): The most common cause of this error is that the
pattern of the matrix has changed between the , i_,l..11. and numeric factorization. It can
also occur if the Numeric or Symbolic object has been subtly corrupted by your program.
UMFPACKERROR_invalid_system, (13): The sys argument provided to one of the solve rou
tines is invalid.
UMFPACKERROR_invalid_permutation, (15): The permutation vector provided as input is
invalid.
UMFPACKERROR_file_IO, (17): This error code is returned by the routines that save and
load the Numeric or Symbolic objects to/from a file, if a file I/O error has occurred. The file
may not exist or may not be readable, you may be trying to create a file that you don't have
permission to create, or you may be out of disk space. The file you are trying to read might
be the wrong one, and an earlier endoffile condition would then result in this error.
UMFPACKERROR_internal_error, (911): An internal error has occurred, of unknown cause.
This is either a bug in UMFPACK, or the result of a memory overrun from your program. Try
modifying the file AMD/Source/amd_internal.h and adding the statement #undef NDEBUG,
to enable the debu:_:_in:; mode. Recompile UMFPACK and rerun your program. A failed
assertion might occur which can give you a better indication as to what is going wrong. Be
aware that UMFPACK will be extraordinarily slow when running in debug mode. If all else
fails, contact the developer (davis@cise.ufl.edu) with as many details as possible.
6.12 Larger examples
Full examples of all usercallable UMFPACK routines are available in four standalone C main
programs, umfpack_*_demo.c. Another example is the UMFPACK mexFunction, umfpackmex.c.
The mexFunction accesses only the usercallable C interface to UMFPACK. The only features
that it does not use are the support for the triplet form (MATLAB's sparse arrays are already
in the compressed column form) and the ability to reuse the Symbolic object to numerically
factorize a matrix whose pattern is the same as a prior matrix .11 i1,. 1 .1 by umfpack_*_symbolic or
umfpack_*_qsymbolic. The latter is an important feature, but the mexFunction does not return its
opaque Symbolic and Numeric objects to MATLAB. Instead, it gets the contents of these objects
Table 3: UMFPACK sys parameter
Value system
UMFPACKA (0) Ax = b
UMFPACKAt (1) AHX = b
UMFPACKAat (2) ATx = b
UMFPACKt_L (3) P Lx = b
UMFPACKIL (4) Lx b
UMFPACKILtP (5) LHPx b
UMFPACKLatP (6) LTPx = b
UMFPACKLt (7) LHX = b
UMFPACKLat (8) LTx b
UMFPACK_U_Qt (9) UQ'x b
UMFPACKU (10) Ux b
UMFPACK_Q_Ut (11) QUHx b
UMFPACK_Q_Uat (12) QUTx b
UMFPACKUt (13) UHX b
UMFPACK_Uat (14) UTx = b
after extracting them via the umfpack_*_get_* routines, and returns them as MATLAB sparse
matrices.
The umf4.c program for reading matrices in Harwell/Boeing format [14] is provided. It re
quires three Fortran 77 programs (readhb.f, readhbnozeros.f, and readhb_size.f) for reading
in the sample Harwell/Boeing files in the UMFPACK/Demo/HB directory. More matrices are avail
able at http://www.cise.ufl.edu/research/sparse/matrices. Type make hb in the UMFPACK/Demo/HB
directory to compile and run this demo. This program was used for the experimental results in [4].
7 Synopsis of Ccallable routines
Each subsection, below, summarizes the input variables, output variables, return values, and calling
sequences of the routines in one category. Variables with the same name as those already listed in
a prior category have the same size and type.
The real, long integer umfpack_dl_* routines are identical to the real, int routines, except that
_di_ is replaced with _dl_ in the name, and all int arguments become long. Similarly, the complex,
long integer umfpackzl_* routines are identical to the complex, int routines, except that _zi_ is
replaced with _zl_ in the name, and all int arguments become long. Only the real and complex
int versions are listed in the , n liI below.
The matrix A is mbyn with nz entries.
The sys argument of umfpack_*_solve is an integer in the range 0 to 14 which defines which
linear system is to be solved. Valid values are listed in Table 3. The notation AH refers to the
matrix transpose, which is the complex conjugate transpose for complex matrices (A' in MATLAB).
The ii , transpose is AT, which is A.' in MATLAB.
7.1 Primary routines: real/int
#include "umfpack.h"
int status, sys, n, m, nz, Ap [n+1], Ai [nz] ;
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], Ax [nz], X [n], B [n]
void *Symbolic, *Numeric ;
status = umfpack_di_symbolic (m, n, Ap, Ai, Ax, &Symbolic, Control, Info) ;
status = umfpack_di_numeric (Ap, Ai, Ax, Symbolic, &Numeric, Control, Info)
status = umfpack_di_solve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info)
umfpackdifree_symbolic (&Symbolic)
umfpackdifree_numeric (&Numeric) ;
7.2 Alternative routines: real/int
int Qinit [n], Wi [n]
double W [5*n] ;
umfpackdidefaults (Control)
status = umfpack_di_qsymbolic (m, n, Ap, Ai, Ax, Qinit, &Symbolic, Control, Info)
status = umfpack_di_wsolve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info, Wi, W)
7.3 Matrix manipulation routines: real/int
int Ti [nz], Tj [nz], P [m], Q [n], Rp [m+1], Ri [nz], Map [nz]
double Tx [nz], Rx [nz], Y [m], Z [m] ;
status = umfpack_di_col_to_triplet (n, Ap, Tj)
status = umfpackditriplettocol (m, n, nz, Ti, Tj, Tx, Ap, Ai, Ax, Map) ;
status = umfpack_di_transpose (m, n, Ap, Ai, Ax, P, Q, Rp, Ri, Rx)
status = umfpack_di_scale (Y, Z, Numeric) ;
7.4 Getting the contents of opaque objects: real/int
The filename string should be large enough to hold the name of a file.
int Inz, unz, Lp [m+1], Lj [lnz], Up [n+1], Ui [unz], do_recip ;
double Lx [lnz], Ux [unz], D [min (m,n)], Rs [m] ;
int nfr, nchains, P1 [m], Q1 [n], Front_npivcol En+1], Frontparent En+1], Front_lstrow En+1],
Front_leftmostdesc En+1], Chain_start En+1], Chain_maxrows En+1], Chain_maxcols En+1] ;
char filename [100] ;
status = umfpack_di_get_lunz (&lnz, &unz, &m, &n, &nz_udiag, Numeric)
status = umfpack_di_get_numeric (Lp, Lj, Lx, Up, Ui, Ux, P, Q, D, &do_recip, Rs, Numeric)
status = umfpack_di_get_symbolic (&m, &n, &nl, &nz, &nfr, &nchains, P1, Q1,
Front_npivcol, Front_parent, Front_lstrow, Front_leftmostdesc,
Chain_start, Chain_maxrows, Chain_maxcols, Symbolic)
status = umfpack_di_load_numeric (&Numeric, filename)
status = umfpack_di_save_numeric (Numeric, filename)
status = umfpack_di_load_symbolic (&Symbolic, filename)
status = umfpack_di_save_symbolic (Symbolic, filename)
7.5 Reporting routines: real/int
umfpack_di_report_status (Control, status)
umfpack_di_report_control (Control) ;
umfpack_di_report_info (Control, Info)
status = umfpack_di_report_matrix (m, n, Ap, Ai, Ax, 1, Control) ;
status = umfpack_di_report_matrix (m, n, Rp, Ri, Rx, 0, Control)
status = umfpack_di_report_numeric (Numeric, Control)
status = umfpack_di_report_perm (m, P, Control)
status = umfpack_di_report_perm (n, Q, Control)
status = umfpack_di_report_symbolic (Symbolic, Control)
status = umfpack_di_report_triplet (m, n, nz, Ti, Tj, Tx, Control)
status = umfpack_di_report_vector (n, X, Control)
7.6 Primary routines: complex/int
double Az [nz], Xx [n], Xz [n], Bx [n], Bz [n]
status = umfpack_zi_symbolic (m, n, Ap, Ai, Ax, Az, &Symbolic, Control, Info)
status = umfpack_zi_numeric (Ap, Ai, Ax, Az, Symbolic, &Numeric, Control, Info)
status = umfpack_zi_solve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric, Control, Info)
umfpackzifree_symbolic (&Symbolic)
umfpackzifree_numeric (&Numeric) ;
7.7 Alternative routines: complex/int
double Wz [10*n] ;
umfpackzidefaults (Control)
status = umfpack_zi_qsymbolic (m, n, Ap, Ai, Ax, Az, Qinit, &Symbolic, Control, Info)
status = umfpack_zi_wsolve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric, Control, Info, Wi, Wz)
7.8 Matrix manipulation routines: complex/int
double Tz [nz], Rz [nz], Yx [m], Yz [m], Zx [m], Zz [m]
status = umfpack_zi_col_to_triplet (n, Ap, Tj) ;
status = umfpack_zi_triplet_to_col (m, n, nz, Ti, Tj, Tx, Tz, Ap, Ai, Ax, Az, Map)
status = umfpack_zi_transpose (m, n, Ap, Ai, Ax, Az, P, Q, Rp, Ri, Rx, Rz, 1) ;
status = umfpack_zi_transpose (m, n, Ap, Ai, Ax, Az, P, Q, Rp, Ri, Rx, Rz, 0)
status = umfpack_zi_scale (Yx, Yz, Zx, Zz, Numeric) ;
7.9 Getting the contents of opaque objects: complex/int
double Lz [lnz], Uz [unz], Dx [min (m,n)], Dz [min (m,n)] ;
status = umfpack_zi_get_lunz (&lnz, &unz, &m, &n, &nz_udiag, Numeric)
status = umfpack_zi_get_numeric (Lp, Lj, Lx, Lz, Up, Ui, Ux, Uz, P, Q, Dx, Dz,
&do_recip, Rs, Numeric) ;
status = umfpack_zi_get_symbolic (&m, &n, &nl, &nz, &nfr, &nchains, PI, QI,
Front_npivcol, Front_parent, Front_1strow, Front_leftmostdesc,
Chain_start, Chain_maxrows, Chain_maxcols, Symbolic)
status = umfpack_zi_load_numeric (&Numeric, filename)
status = umfpack_zi_save_numeric (Numeric, filename)
status = umfpack_zi_load_symbolic (&Symbolic, filename)
status = umfpack_zi_save_symbolic (Symbolic, filename)
7.10 Reporting routines: complex/int
umfpack_zi_report_status (Control, status)
umfpack_zi_report_control (Control) ;
umfpack_zi_report_info (Control, Info)
status = umfpack_zi_report_matrix (m, n, Ap, Ai, Ax, Az, 1, Control) ;
status = umfpack_zi_report_matrix (m, n, Rp, Ri, Rx, Rz, 0, Control)
status = umfpack_zi_report_numeric (Numeric, Control)
status = umfpack_zi_report_perm (m, P, Control)
status = umfpack_zi_report_perm (n, Q, Control)
status = umfpack_zi_report_symbolic (Symbolic, Control) ;
status = umfpack_zi_report_triplet (m, n, nz, Ti, Tj, Tx, Tz, Control)
status = umfpack_zi_report_vector (n, Xx, Xz, Control)
8 Synopsis of utility routines
These routines are the same in all four versions of UMFPACK.
double t, s [2] ;
t = umfpack_timer ( ) ;
umfpack_tic (s)
umfpack_toc (s)
9 Synopsis of AMD ordering routines
UMFPACK makes use of the AMD ordering package for its symmetric ordering strategy. You may
also use these four usercallable routines in your own C programs. You need to include the amd.h
file only if you make direct calls to the AMD routines themselves. The int versions are summarized
below; long versions are also available. Refer to the AMD User Guide for more information, or to
the file amd.h which documents these routines.
#include "amd.h"
double amd_control [AMD_CONTROL], amd_info [AMD_INFO]
amd_defaults (amd_control) ;
status = amd_order (n, Ap, Ai, P, amd_control, amd_info)
amd_control (amd_control)
amd_info (amd_info) ;
10 Using UMFPACK in a Fortran program
UMFPACK v4.3 includes a basic Fortran 77 interface to some of the Ccallable UMFPACK routines.
Since interfacing C and Fortran programs is not portable, this interface might not work with all
C and Fortran compilers. Refer to Section 11 for more details. The following Fortran routines are
provided. The list includes the Ccallable routines that the Fortran interface routine calls. Refer
to the corresponding C routines in Section 6 for more details on what the Fortran routine does.
umf4def: sets the default control parameters (umfpack_di_defaults).
umf4sym: preordering and symbolic factorization (umfpack_di_symbolic).
umf4num: numeric factorization (umfpack_di_numeric).
umf4solr: solve a linear ,. ii with iterative refinement (umfpack_di_solve).
umf4sol: solve a linear system without iterative refinement (umfpack_di_solve). Sets Control
[UMFPACK_IRSTEP] to zero, and does not require the matrix A.
umf4scal: scales a vector using UMFPACK's scale factors (umfpack_di_scale).
* umf4fnum: free the Numeric object (umfpack_di_free_numeric).
umf4fsym: free the Symbolic object (umfpack_di_free_symbolic).
umf4pcon: prints the control parameters (umfpack_di_report_control).
umf4pinf: print statistics (umfpack_di_report_info).
umf4snum: save the Numeric object to a file (umfpack_di_save_numeric).
umf4ssym: save the Symbolic object to a file (umfpack_di_save_symbolic).
umf41num: load the Numeric object from a file (umfpack_di_load_numeric).
umf41sym: load the Symbolic object from a file (umfpack_di_load_symbolic).
The matrix A is passed to UMFPACK in compressed column form, with 0based indices. In
Fortran, for an mbyn matrix A with nz entries, the row indices of the first column (column 1) are
in Ai (Ap(1)+1 .. .Ap(2)), with values in Ax (Ap(1)+l .. .Ap(2)). The last column (column n) is
in Ai (Ap(n)+1 ...Ap(n+l)) and Ax (Ap(n)+1 ...Ap(n+l)). The number of entries in the matrix
is thus nz = Ap (n+1). The row indices in Ai are in the range 0 to m1. They must be sorted, with
no duplicate entries allowed. None of the UMFPACK routines modify the input matrix A. The
following definitions apply for the Fortran routines:
integer m, n, Ap (n+1), Ai (nz), symbolic, numeric, filenum, status
double precision Ax (nz), control (20), info (90), x (n), b (n)
UMFPACK's status is returned in either a status argument, or in info (1). It is zero if
UMFPACK was successful, 1 if the matrix is singular (this is a wiriiiOn:_. not an error), and negative
if an error occurred. Section 6.11 summarizes the possible values of status and info (1). See
Table 3 for a list of the values of the sys argument. See Table 2 for a list of the control parameters
(the Fortran usage is the same as the MATLAB usage for this array).
For the Numeric and Symbolic handles, it is probably safe to assume that a Fortran integer
is sufficient to store a C pointer. If that does not work, try defining numeric and symbolic in
your Fortran program as integer arrays of size 2. You will need to define them as integer*8 if you
compile UMFPACK in the 64bit mode.
To avoid passing strings between C and Fortran in the load/save routines, a file number is
passed instead, and the C interface constructs a file name (if filenum is 42, the Numeric file name
is n42.umf, and the Symbolic file name is s42.umf).
The following is a summary of the calling sequence of each Fortran interface routine. An example
of their use is in the Demo/umf4hb. f file. That routine also includes an example of how to convert a
1based sparse matrix into 0based form. For more details on the arguments of each routine, refer to
the arguments of the same name in the corresponding Ccallable routine, in Sections 16 through 21.
The only exception is the control argument of umf4sol, which sets control (8) to zero to disable
iterative refinement. Note that the solve routines do not overwrite b with the solution, but return
their solution in a different array, x.
call umf4def (control)
call umf4sym (m, n, Ap, Ai, Ax, symbolic, control, info)
call umf4num (Ap, Ai, Ax, symbolic, numeric, control, info)
call umf4solr (sys, Ap, Ai, Ax, x, b, numeric, control, info)
call umf4sol (sys, x, b, numeric, control, info)
call umf4scal (x, b, numeric, status)
call umf4fnum (numeric)
call umf4fsym (symbolic)
call umf4pcon (control)
call umf4pinf (control)
call umf4snum (numeric, filenum, status)
call umf4ssym (symbolic, filenum, status)
call umf41num (numeric, filenum, status)
call umf41sym (symbolic, filenum, status)
Access to the complex routines in UMFPACK is provided by the interface routines in umf4_f77zwrapper. c.
The following is a , li of each routine. All the arguments are the same as the real versions,
except Az, xz, and bz are the imaginary parts of the matrix, solution, and righthandside, respec
tively. The Ax, x, and b are the real parts.
call umf4zdef (control)
call umf4zsym (m, n, Ap, Ai, Ax, Az, symbolic, control, info)
call umf4znum (Ap, Ai, Ax, Az, symbolic, numeric, control, info)
call umf4zsolr (sys, Ap, Ai, Ax, Az, x, xz, b, bz, numeric, control, info)
call umf4zsol (sys, x, xz, b, bz, numeric, control, info)
call umf4zscal (x, xz, b, bz, numeric, status)
call umf4zfnum (numeric)
call umf4zfsym (symbolic)
call umf4zpcon (control)
call umf4zpinf (control)
call umf4zsnum (numeric, filenum, status)
call umf4zssym (symbolic, filenum, status)
call umf4zlnum (numeric, filenum, status)
call umf4zlsym (symbolic, filenum, status)
11 Installing the C library
The following discussion assumes you have the make program, either in Unix, or in Windows with
Cygwin2. You can skip this section and go to next one if all you want to use is the UMFPACK
and AMD mexFunctions in MATLAB.
You will need to install both UMFPACK v4.3 and AMD vl.1 (or AMD vl.0) to use UMFPACK.
The UMFPACK and AMD subdirectories must be placed sidebyside within the same directory. AMD
is a standalone package that is required by UMFPACK. UMFPACK can be compiled without the
BLAS [10, 11, 27, 24], but your performance will be much less than what it should be.
Systemdependent configurations are in the AMD/Make and UMFPACK/Make directories (the
UMFPACK/Make directory is actually just a symbolic link to AMD/Make3). You can edit the Make. include
files in either of those directories to customize the compilation. The default settings will work on
most systems, except that UMFPACK will be compiled so that it does not use the BLAS. Sample
configuration files are provided for Linux, Sun Solaris, SGI IRIX, IBM AIX, and the DEC/Compaq
Alpha.
To compile and install both packages, go to the UMFPACK directory and type make. This will
compile the libraries (AMD/Lib/libamd.a and UMFPACK/Lib/libumfpack.a). A demo of the AMD
ordering routine will be compiled and tested in the AMD/Demo directory, and five demo programs will
then be compiled and tested in the UMFPACK/Demo directory. The outputs of these demo programs
2www.cygwin.com
3Windows might not extract the symbolic link UMFPACK/Make correctly. If it doesn't, simply create the
UMFPACK/Make folder by copying it from AMD/Make.
will then be compared with output files in the distribution. Expect to see a few differences, such as
residual norms, compiletime control settings, and perhaps memory usage differences. The AMD
and UMFPACK mexFunctions for use in MATLAB will also be compiled. If you do not have
MATLAB 6.0 or later, type make lib instead.
If you have the GNU version of make, the Source/GNUmakefile and MATLAB/GNUmakefile files
are used. These are much more concise than what the "old" version of make can handle. If you
do not have GNU make, the Source/Makefile and MATLAB/Makefile files are used instead. Each
UMFPACK source file is compiled into four versions (double / complex, and int / long). A proper
oldI, ., Makefile is cumbersome in this case, so these two Makefile's have been constructed by
brute force. They ignore dependencies, and simply compile everything. I highly recommend using
GNU make if you wish to modify UMFPACK.
If you compile UMFPACK and AMD and then later change the Make. include file or your
systemspecific configuration file such as Make.linux, then you should type make purge and then
make to recompile.
Here are the various parameters that you can control in your Make. include file:
CC = your C compiler, such as cc.
RANLIB = your ,1I. i's ranlib program, if needed.
CFLAGS = optimization flags, such as 0. Add DLP64 if you are compiling in 64bit mode
(32 bit into's, 64 bit long's, and 64 bit pointers).
CONFIG = configuration settings for the BLAS, memory allocation routines, and timing rou
tines.
LIB = your libraries, such as lm or lblas.
RM = the command to delete a file.
MV = the command to rename a file.
MEX = the command to compile a MATLAB mexFunction. If you are using MATLAB 5,
you need to add DNBLAS and DNUTIL to this command. An example is provided in the
Make/Make.include file.
F77 = the command to compile a Fortran program (optional).
F77FLAGS = the Fortran compiler flags (optional).
F77LIB = the Fortran libraries (optional).
The CONFIG string can include combinations of the f .11, . in. most deal with how the BLAS
are called:
DNBLAS if you do not have any BLAS at all.
DCBLAS if you have the CBLAS [27].
DNSUNPERF if you are on Solaris but do not have the Sun Performance Library (for the
BLAS).
DNSCSL if you on SGI IRIX but do not have the SCSL BLAS library.
DLONGBLAS if your BLAS can take long integer input arguments. If not defined, then the
umfpack_*l_* versions of UMFPACK that use long integers do not call the BLAS. This flag
is set internally when using the Sun Performance BLAS or SGI's SCSL BLAS (both have
64bit versions of the BLAS).
Options for controlling how C calls the Fortran BLAS: DBLAS_BY_VALUE, DBLASNO_UNDERSCORE,
and DBLAS_CHAR_ARG. These are set automatically for Windows, Sun Solaris, SGI Irix, Red
Hat Linux, Compaq Alpha, and AIX (the IBM RS 6000). They are ignored if you are using
the CBLAS interface to the BLAS.
DGETRUSAGE if you have the getrusage function.
DNUTIL if you wish to compile the MATLABcallable UMFPACK mexFunction with the
mxMalloc, mxRealloc and mxFree routines, instead of the undocumented (but superior)
utMalloc, utRealloc, and utFree routines. The default is to use the ut* routines on Unix,
and the mx* routines on Windows.
DNPOSIX if you do not have the POSIXcompliant sysconf and times routines used by
umfpack_tic and umfpack_toc.
DNRECIPROCAL controls a tradeoff between speed and accuracy. If defined (or if the pivot
value itself is less than 1012), then the pivot column is divided by the pivot value during
numeric factorization. Otherwise, it is multiplied by the reciprocal of the pivot, which is faster
but can be less accurate. The default is to multiply by the reciprocal unless the pivot value is
small. This option also modifies how the rows of the matrix A are scaled. If DNRECIPROCAL
is defined (or if any scale factor is less than 1012), entries in the rows of A are divided by the
scale factors. Otherwise, they are multiplied by the reciprocal. When compiling the complex
routines with the GNU gcc compiler, the pivot column is I'. ,, divided by the pivot entry,
because of a numerical accuracy issue encountered with gcc version 3.2 with a few complex
matrices on a Pentium I \l (running Linux). You can still use DNRECIPROCAL to control how
the scale factors for the rows of A are applied.
DNODIVIDE_BY_ZERO controls how UMFPACK treats zeros on the diagonal of U, for a singu
lar matrix A. If defined, then no division by zero is performed (a zero entry on the diagonal
of U is treated as if it were equal to one). By default, UMFPACK will divide by zero.
DNO_TIMER controls whether or not timing routines are to be called. If defined, no timers are
used. Timers are included by default.
If a Fortran BLAS package is used you may see compiler warnings. The BLAS routines dgemm,
dgemv, dger, dtrsm, dtrsv, dscal and their corresponding complex versions are used. Header files
are not provided for the Fortran BLAS. You may safely ignore all of these warnings.
I highly recommend the recent BLAS by Goto and van de Geijn [24]. Using this BLAS increased
the performance of UMFPACK by up to 50% on a Dell Latitude C840 laptop (2GHz Pentium 4M,
512K L2 cache, 1GB main memory). The peak performance of umfpack_di_numeric with Goto
and van de Geijn's BLAS is 1.6 Gflops on this computer. In MATLAB, the peak performance of
UMFPACK on a dense matrix (stored in sparse format) is 900 Mflops, as compared to 1 Gflop for
x = A\b when A is stored as a regular full matrix.
When you compile your program that uses the Ccallable UMFPACK library, you need to link
your program with both libraries (UMFPACK/Lib/libumfpack.a and AMD/Lib/libamd.a) and you
need to tell your compiler to look in the directories UMFPACK/Include and AMD/Include for include
files. See UMFPACK/Demo/Makefile for an example. You do not need to directly include any AMD
include files in your program, unless you directly call AMD routines. You only need the
#include "umfpack.h"
statement, as described in Section 7.
If you would like to compile both 32bit and 64bit versions of the libraries, you will need to
do it in two steps. Modify your Make/Make. file, and select the 32bit option. Type make
in the UMFPACK directory, which creates the UMFPACK/Lib/libumfpack. a and AMD/Lib/libamd.a
libraries. Rename those two files. Edit your Make/Make. and select the 64bit option.
Type make purge, and then make, and you will create the 64bit libraries. You can use the same
umfpack.h include file for both 32bit and 64bit versions. Simply link your program with the
appropriate 32bit or 64bit compiled version of the UMFPACK and AMD libraries.
Type make hb in the UMFPACK/Demo/HB directory to compile and run a C program that reads
in and factorizes Harwell/Boeing matrices. Note that this uses a standalone Fortran program to
read in the Fortranformatted Harwell/Boeing matrices and write them to a file which can be read
by a C program.
12 Installing the MATLAB interface
If all you want to do is use the UMFPACK mexFunction in MATLAB, you can skip the use
of the make command described above. Simply type umfpack_make in MATLAB while in the
UMFPACK/MATLAB directory. You can also type amd_make in the AMD/MATLAB directory to compile
the standalone AMD mexFunction (this is not required to compile the UMFPACK mexFunction).
This works on any computer with MATLAB, including Windows. This method of creating the
UMFPACK mexFunction has been tested with MATLAB 5.3, 6.1, and 6.5.
You will be prompted to select several configuration options, including whether or not to use the
BLAS. MATLAB 5.3 (or earlier) does not include the BLAS, so you either have to compile UMF
PACK without the BLAS (UMFPACK will be slow), or modify your /bin/mexopts. sh by
adding your BLAS library to the CLIBS i,:_. where is the directory in which MATLAB
is installed.
If you are using Windows and the Icc compiler bundled with MATLAB 6.1, then you may need
to copy the UMFPACK\MATLAB\lcc_lib\libmwlapack. lib file into the \extern\lib\win32\lcc\
directory. Next, type mex setup at the MATLAB prompt, and ask MATLAB to select the icc
compiler. MATLAB 6.1 has builtin BLAS, but in that version of MATLAB the BLAS cannot be
accessed by a mexFunction compiled by Icc without first copying this file to the location listed
above. If you have MATLAB 6.5 or later, you can probably skip this step.
13 Installing the Fortran interface
Once the 32bit Ccallable UMFPACK library is compiled, you can also compile the Fortran in
terface, by typing make fortran. This will create the umf4hb program, test it, and compare the
output with the file umf4hb. out in the distribution. If you compiled UMFPACK in 64bit mode,
you need to use make fortran64 instead, which compiles the umf4hb64 program and compares its
output with the file umf4hb64. out. Refer to the comments in the Demo/umf4_f77wrapper.c file
for more details.
This interface is highly nonportable, since it depends on how C and Fortran are inter
faced. Because of this issue, the interface is included in the Demo directory, and not as a pri
mary part of the UMFPACK library. The interface routines are not included in the compiled
UMFPACK/Lib/libumfpack.a library, but left as standalone compiled files (umf4_f77wrapper.o
and umf4_f77wrapper64.o in the Demo directory). You may need to modify the interface routines
in the file umf4_f77wrapper.c if you are using compilers for which this interface has not been
tested.
14 Known Issues
The Microsoft C or C++ compilers on a Pentium badly break the IEEE 754 standard, and do not
treat NaN's properly. According to IEEE 754, the expression (x != x) is supposed to be true if
and only if x is NaN. For noncompliant compilers in Windows that expression is I'. i, false, and
another test must be used: (x < x) is true if and only if x is NaN. For compliant compilers, (x
< x) is ', ,, false, for any value of x (including NaN). To cover both cases, UMFPACK when
running under Microsoft Windows defines the following macro, which is true if and only if x is NaN,
regardless of whether your compiler is compliant or not:
#define SCALAR_IS_NAN(x) (((x) != (x))  ((x) < (x)))
If your compiler breaks this test, then UMFPACK will fail catastrophically if it encounters a
NaN. You will not just see NaN's in your output; UMFPACK will probably crash with a segmen
tation fault. In that case, you might try to see if the common (but nonANSI C) routine isnan is
available, and modify the macro SCALAR_IS_NAN in umf_version.h accordingly. The simpler (and
IEEE 754compliant) test (x != x) is I, true with Linux on a PC, and on every Unix compiler
I have tested.
Some compilers will complain about the Fortran BLAS being defined implicitly. C prototypes
for the BLAS are not used, except the CBLAS. Some compilers will complain about unrecognized
#pragma's. You may safely ignore all of these warnings.
15 Future work
Here are a few features that are not in UMFPACK Version 4.3, in no particular order. They may
appear in a future release of UMFPACK. If you are interested, let me know and I could consider
including them:
1. Future versions may have different default Control parameters. Future versions may return
more statistics in the Info ii ,, and they may use more entries in the Control array.
These two Ii ,, will probably become larger, since there are very few unused entries. If
they change in size, the constants UMFPACK_CONTROL and UMFPACK_INFO defined in umfpack.h
will be changed to reflect their new size. Your C program should use these constants when
declaring the size of these two I ii, Do not define them as Control [20] and Info [90].
2. Forward/back solvers for the conventional row or columnform data structure for L and U
(the output of umfpack_*_di_get_numeric). This would enable a separate solver that could be
used to write a MATLAB mexFunction x = lu_refine (A, b, L, U, P, Q, R) that gives
MATLAB access to the iterative refinement algorithm with sparse backward error .,!11 i, i
It would also be easier to handle sparse righthandsides in this data structure, and end up
with good asymptotic runtime in this case (particularly for Lx = b; see [23]).
3. Complex absolute value computations could be based on FDLIBM (see
http://www.netlib.org/fdlibm), using the hypot (x,y) routine.
4. When using iterative refinement, the residual Ax b could be returned by umfpack_solve.
5. The solve routines could handle multiple righthand sides, and sparse righthand sides. See
umfpack_solve for the MATLAB version of this feature.
6. An option to redirect the error and diagnostic output.
7. Permutation to blocktriangularform [16] for the Ccallable interface. There are two routines
in the AC'il Collected Algorithms (529 and 575) [13, 15] that could be translated from Fortran
to C and included in UMFPACK. This would result in better performance for matrices from
circuit simulation and chemical process engineering. See umfpack_btf.m for the MATLAB
version of this feature.
8. The ability to use userprovided malloc, free, and realloc memory allocation routines. Note
that UMFPACK makes very few calls to these routines. You can do this at compiletime by
modifying the definitions of ALLOCATE, FREE, and REALLOCATE in the file umf_internal.h. Be
sure to document your changes carefully when you change UMFPACK source code.
9. The ability to use userprovided work ini ',. so that malloc, free, and realloc realloc are
not called. The umfpack_*_wsolve routine is one example.
10. A method that takes time proportional to the number of nonzeros in A to compute the
', il.1i. factorization [22]. This would improve the performance of the symmetric and 2by
2 strategies, and the unsymmetric strategy when dense rows are present. The current method
takes time proportional to the number of nonzeros in the upper bound of U. The method
used in UMFPACK exploits supercolumns, however, so this bound is rarely reached.
11. The complex versions could use ANSI C99 double _Complex arguments, and support the use
of interleaved real/imaginary parts as input and output arguments. The
umfpack_*_report_vector routine is one example.
12. Other basic sparse matrix operations, such as sparse matrix multiplication, could be included.
13. A more complete Fortran interface.
14. A C++ interface.
15. A parallel version using MPI. This would require a large amount of effort.
16 The primary UMFPACK routines
The include files are the same for all four versions of UMFPACK. The generic integer type is Int,
which is an int or long, depending on which version of UMFPACK you are using.
16.1 umfpack_*_symbolic
umfpack_di_symbolic
int n_row,
int n_col,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
void **Symbolic,
const double Control
double Info [UMFPACK_
long umfpack_dl_symbolic
(
long n_row,
long n_col,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
void **Symbolic,
const double Control
double Info [UMFPACK_
[UMFPACK_CONTROL],
INFO]
[UMFPACK_CONTROL],
INFO]
umfpack_zi_symbolic
int n_row,
int n_col,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
void **Symbolic,
const double Control
double Info [UMFPACK_
long umfpack_zl_symbolic
(
long n_row,
long n_col,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
void **Symbolic,
const double Control
double Info [UMFPACK_
const double Az [ ],
[UMFPACK_CONTROL],
INFO]
const double Az [ ],
[UMFPACK_CONTROL],
INFO]
double int Syntax:
#include "umfpack.h"
void *Symbolic ;
int n_row, n_col, *Ap, *Ai, status ;
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], *Ax ;
status = umfpack_di_symbolic (n_row, n_col, Ap, Ai, Ax,
&Symbolic, Control, Info)
double long Syntax:
#include "umfpack.h"
void *Symbolic ;
long nrow, ncol, *Ap, *Ai, status
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], *Ax ;
status = umfpack_dl_symbolic (n_row, n_col, Ap, Ai, Ax,
&Symbolic, Control, Info)
complex int Syntax:
#include "umfpack.h"
void *Symbolic ;
int n_row, n_col, *Ap, *Ai, status ;
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], *Ax, *Az ;
status = umfpack_zi_symbolic (n_row, n_col, Ap, Ai, Ax, Az,
&Symbolic, Control, Info)
complex long Syntax:
#include "umfpack.h"
void *Symbolic ;
long nrow, ncol, *Ap, *Ai, status
double Control [UMFPACK_CONTROL], Info
status = umfpack_zl_symbolic (n_row, n_
&Symbolic, Control, Info) ;
[UMFPACK_INFO], *Ax, *Az
col, Ap, Ai, Ax, Az,
Purpose:
Given nonzero pattern of a sparse matrix A in column
umfpack_*_symbolic performs a column preordering to
(using COLAMD or AMD) and a symbolic factorization.
before the matrix can be numerically factorized with
If you wish to bypass the COLAMD or AMD preordering
ordering, use umfpack_*_qsymbolic instead.
oriented form,
reduce fillin
This is required
umfpack_*_numeric.
and provide your own
Since umfpack_*_symbolic and umfpack_*_qsymbolic are very similar, options
for both routines are discussed below.
For the following discussion, let S be the submatrix of A obtained after
eliminating all pivots of zero Markowitz cost. S has dimension
(n_rownlnempty_row) by (n_colnlnempty_col), where
nl = Info [UMFPACK_COL_SINGLETONS] + Info [UMFPACK_ROW_SINGLETONS],
nempty_row = Info [UMFPACK_NEMPTY_ROW] and
nempty_col = Info [UMFPACK_NEMPTY_COL].
Returns:
The status code is returned. See Info [UMFPACK_STATUS], below.
Arguments:
Int n_row ; Input argument, not modified.
Int n_col ; Input argument, not modified.
A is an n_rowbyn_col matrix. Restriction: n_row > 0 and n_col > 0.
Int Ap En_col+1] ; Input argument, not modified.
Ap is an integer array of size n_col+l. On input, it holds the
"pointers" for the column form of the sparse matrix A. Column j of
the matrix A is held in Ai [(Ap [j]) ... (Ap [j+1]1)]. The first
entry, Ap [0], must be zero, and Ap [j] <= Ap [j+1] must hold for all
j in the range 0 to n_coll. The value nz = Ap En_col] is thus the
total number of entries in the pattern of the matrix A. nz must be
greater than or equal to zero.
Int Ai [nz] ; Input argument, not modified, of size nz = Ap En_col].
The nonzero pattern (row indices) for column j is stored in
Ai [(Ap [j]) ... (Ap [j+1]1)]. The row indices in a given column j
must be in ascending order, and no duplicate row indices may be present.
Row indices must be in the range 0 to n_row1 (the matrix is Obased).
See umfpack_*_triplettocol for how to sort the columns of a matrix
and sum up the duplicate entries. See umfpack_*_report_matrix for how
to print the matrix A.
double Ax [nz] ; Optional input argument, not modified.
The numerical values of the sparse matrix A. The nonzero pattern (row
indices) for column j is stored in Ai [(Ap [j]) ... (Ap [j+l]1)], and
the corresponding numerical values are stored in
Ax [(Ap [j]) ... (Ap [j+1]1)]. Used only by the 2by2 strategy to
determine whether entries are "large" or "small". You do not have to
pass the same numerical values to umfpack_*_numeric. If Ax is not
present (a (double *) NULL pointer), then any entry in A is assumed to
be "large".
double Az [nz] ; Optional input argument, not modified, for complex
versions.
For the complex versions, this holds the imaginary part of A. The
imaginary part of column j is held in Az [(Ap [j]) ... (Ap [j+1]1)].
Future complex version: if Ax is present and Az is NULL, then both real
and imaginary parts will be contained in Ax[0..2*nzl], with Ax[2*k]
and Ax[2*k+l] being the real and imaginary part of the kth entry.
Used by the 2by2 strategy only. See the description of Ax, above.
void **Symbolic ; Output argument.
**Symbolic is the address of a (void *) pointer variable in the user's
calling routine (see Syntax, above). On input, the contents of this
variable are not defined. On output, this variable holds a (void *)
pointer to the Symbolic object (if successful), or (void *) NULL if
a failure occurred.
double Control [UMFPACK_CONTROL] ; Input argument, not modified.
If a (double *) NULL pointer is passed, then the default control
settings are used (the defaults are suitable for all matrices,
ranging from those with highly unsymmetric nonzero pattern, to
symmetric matrices). Otherwise, the settings are determined from the
Control array. See umfpack_*_defaults on how to fill the Control
array with the default settings. If Control contains NaN's, the
defaults are used. The following Control parameters are used:
Control [UMFPACK_STRATEGY]: This is the most important control
parameter. It determines what kind of ordering and pivoting
strategy that UMFPACK should use. It is new to Version 4.1
There are 4 options:
UMFPACK_STRATEGY_AUTO: This is the default. The input matrix is
analyzed to determine how symmetric the nonzero pattern is, and
how many entries there are on the diagonal. It then selects one
of the following strategies. Refer to the User Guide for a
description of how the strategy is automatically selected.
UMFPACK_STRATEGY_UNSYMMETRIC: Use the unsymmetric strategy. COLAMD
is used to order the columns of A, followed by a postorder of
the column elimination tree. No attempt is made to perform
diagonal pivoting. The column ordering is refined during
factorization. This strategy was the only one provided with
UMFPACK V4.0.
In the numerical factorization, the
Control [UMFPACK_SYM_PIVOT_TOLERANCE] parameter is ignored. A
pivot is selected if its magnitude is >=
Control [UMFPACK_PIVOT_TOLERANCE] (default 0.1) times the
largest entry in its column.
UMFPACK_STRATEGY_SYMMETRIC: Use the symmetric strategy (new to
Version 4.1). In this method, the approximate minimum degree
ordering (AMD) is applied to A+A', followed by a postorder of
the elimination tree of A+A'. UMFPACK attempts to perform
diagonal pivoting during numerical factorization. No refinement
of the column preordering is performed during factorization.
In the numerical factorization, a nonzero entry on the diagonal
is selected as the pivot if its magnitude is >= Control
[UMFPACK_SYM_PIVOT_TOLERANCE] (default 0.001) times the largest
entry in its column. If this is not acceptable, then an
offdiagonal pivot is selected with magnitude >= Control
[UMFPACK_PIVOT_TOLERANCE] (default 0.1) times the largest entry
in its column.
UMFPACK_STRATEGY_2BY2: a row permutation P2 is found that places
large entries on the diagonal. The matrix P2*A is then
factorized using the symmetric strategy, described above.
Refer to the User Guide for more information.
Control [UMFPACK_DENSE_COL]:
If COLAMD is used, columns with more than
max (16, Control [UMFPACK_DENSE_COL] 16 sqrt (n_row)) entries
are placed placed last in the column preordering. Default: 0.2.
Control [UMFPACK_DENSE_ROW]:
Rows with more than max (16, Control [UMFPACK_DENSE_ROW] 16 *
sqrt (n_col)) entries are treated differently in the COLAMD
preordering, and in the internal data structures during the
subsequent numeric factorization. Default: 0.2.
Control [UMFPACK_AMD_DENSE]: rows/columns in A+A' with more than
max (16, Control [UMFPACK_AMD_DENSE] sqrt (n)) entries
(where n = n_row = n_col) are ignored in the AMD preordering.
Default: 10.
Control [UMFPACK_BLOCK_SIZE]: the block size to use for Level3 BLAS
in the subsequent numerical factorization (umfpack_*_numeric).
A value less than 1 is treated as 1. Default: 32. Modifying this
parameter affects when updates are applied to the working frontal
matrix, and can indirectly affect fillin and operation count.
As long as the block size is large enough (8 or so), this parameter
has a modest effect on performance.
Control [UMFPACK_2BY2_TOLERANCE]: a diagonal entry S (k,k) is
considered "small" if it is < tol max (abs (S (:,k))), where S a
submatrix of the scaled input matrix, with pivots of zero Markowitz
cost removed.
Control [UMFPACK_SCALE]: This parameter is new to V4.1. See
umfpack_numeric.h for a description. Only affects the 2by2
strategy. Default: UMFPACK_SCALE_SUM.
Control [UMFPACK_FIXQ]: If > 0, then the preordering Q is not modified
during numeric factorization. If < 0, then Q may be modified. If
zero, then this is controlled automatically (the unsymmetric
strategy modifies Q, the others do not). Default: 0.
Control [UMFPACK_AGGRESSIVE]: If nonzero, aggressive absorption is used
in COLAMD and AMD. Default: 1.
double Info [UMFPACK_INFO] ; Output argument, not defined on input.
Contains statistics about the symbolic analysis. If a (double *) NULL
pointer is passed, then no statistics are returned in Info (this is not
an error condition). The entire Info array is cleared (all entries set
to 1) and then the following statistics are computed:
Info [UMFPACK_STATUS]: status code. This is also the return value,
whether or not Info is present.
UMFPACK OK
Each column of the input matrix contained row indices
in increasing order, with no duplicates. Only in this case
does umfpack_*_symbolic compute a valid symbolic factorization.
For the other cases below, no Symbolic object is created
(*Symbolic is (void *) NULL).
UMFPACK_ERROR_n_nonpositive
n is less than or equal to zero.
UMFPACK ERROR invalid matrix
Number of entries in the matrix is negative, Ap [0] is nonzero,
a column has a negative number of entries, a row index is out of
bounds, or the columns of input matrix were jumbled (unsorted
columns or duplicate entries).
UMFPACK_ERRORout of memory
Insufficient memory to perform the symbolic analysis. If the
analysis requires more than 2GB of memory and you are using
the 32bit ("int") version of UMFPACK, then you are guaranteed
to run out of memory. Try using the 64bit version of UMFPACK.
UMFPACKERRORargument missing
One or more required arguments is missing.
UMFPACK ERROR internal error
Something very serious went wrong. This is a bug.
Please contact the author (davis@cise.ufl.edu).
Note that the UMFPACK_ERROR_problem_too_large error code is no
longer returned (it was in Version 4.0).
Info [UMFPACK_NROW]: the value of the input argument n_row.
Info [UMFPACKNCOL]: the value of the input argument ncol.
Info [UMFPACKNZ]: the number of entries in the input matrix
(Ap [n_col]).
Info [UMFPACK_SIZEOFUNIT]: the number of bytes in a Unit,
for memory usage statistics below.
Info [UMFPACK_SIZEOFINT]: the number of bytes in an int.
Info [UMFPACK_SIZEOFLONG]: the number of bytes in a long.
Info [UMFPACK_SIZEOFPOINTER]: the number of bytes in a void *
pointer.
Info [UMFPACK_SIZEOFENTRY]: the number of bytes in a numerical entry.
Info [UMFPACK_NDENSE_ROW]: number of "dense" rows in A. These rows are
ignored when the column preordering is computed in COLAMD. They
are also treated differently during numeric factorization. If > 0,
then the matrix had to be reanalyzed by UMF_analyze, which does
not ignore these rows.
Info [UMFPACK_NEMPTY_ROW]: number of "empty" rows in A, as determined
These are rows that either have no entries, or whose entries are
all in pivot columns of zeroMarkowitzcost pivots.
Info [UMFPACK_NDENSE_COL]: number of "dense" columns in A. COLAMD
orders these columns are ordered last in the factorization, but
before "empty" columns.
Info [UMFPACK_NEMPTY_COL]: number of "empty" columns in A. These are
columns that either have no entries, or whose entries are all in
pivot rows of zeroMarkowitzcost pivots. These columns are
ordered last in the factorization, to the right of "dense" columns.
Info [UMFPACK_SYMBOLIC_DEFRAG]: number of garbage collections
performed during ordering and symbolic preanalysis.
Info [UMFPACK_SYMBOLIC_PEAK_MEMORY]: the amount of memory (in Units)
required for umfpack_*_symbolic to complete. This count includes
the size of the Symbolic object itself, which is also reported in
Info [UMFPACK_SYMBOLIC_SIZE].
Info [UMFPACK_SYMBOLIC_SIZE]: the final size of the Symbolic object (in
Units). This is fairly small, roughly 2*n to 13*n integers,
depending on the matrix.
Info [UMFPACK_VARIABLE_INIT_ESTIMATE]: the Numeric object contains two
parts. The first is fixed in size (0 (n_row+n_col)). The
second part holds the sparse LU factors and the contribution blocks
from factorized frontal matrices. This part changes in size during
factorization. Info [UMFPACK_VARIABLE_INIT_ESTIMATE] is the exact
size (in Units) required for this second variablesized part in
order for the numerical factorization to start.
Info [UMFPACK_VARIABLE_PEAK_ESTIMATE]: the estimated peak size (in
Units) of the variablesized part of the Numeric object. This is
usually an upper bound, but that is not guaranteed.
Info [UMFPACK_VARIABLE_FINAL_ESTIMATE]: the estimated final size (in
Units) of the variablesized part of the Numeric object. This is
usually an upper bound, but that is not guaranteed. It holds just
the sparse LU factors.
Info [UMFPACK_NUMERIC_SIZE_ESTIMATE]: an estimate of the final size (in
Units) of the entire Numeric object (both fixedsize and variable
sized parts), which holds the LU factorization (including the L, U,
P and Q matrices).
Info [UMFPACK_PEAK_MEMORY_ESTIMATE]: an estimate of the total amount of
memory (in Units) required by umfpack_*_symbolic and
umfpack_*_numeric to perform both the symbolic and numeric
factorization. This is the larger of the amount of memory needed
in umfpack_*_numeric itself, and the amount of memory needed in
umfpack_*_symbolic (Info [UMFPACK_SYMBOLIC_PEAK_MEMORY]). The
count includes the size of both the Symbolic and Numeric objects
themselves. It can be a very loose upper bound, particularly when
the symmetric or 2by2 strategies are used.
Info [UMFPACK_FLOPS_ESTIMATE]: an estimate of the total floatingpoint
operations required to factorize the matrix. This is a "true"
theoretical estimate of the number of flops that would be performed
by a flopparsimonious sparse LU algorithm. It assumes that no
extra flops are performed except for what is strictly required to
compute the LU factorization. It ignores, for example, the flops
performed by umfpackdinumeric to add contribution blocks of
frontal matrices together. If L and U are the upper bound on the
pattern of the factors, then this flop count estimate can be
represented in MATLAB (for real matrices, not complex) as:
Lnz = full (sum (spones (L))) 1 ; % nz in each col of L
Unz = full (sum (spones (U')))' 1 ; % nz in each row of U
flops = 2*Lnz*Unz + sum (Lnz) ;
The actual "true flop" count found by umfpack_*_numeric will be
less than this estimate.
For the real version, only (+ /) are counted. For the complex
version, the following counts are used:
operation flops
c = 1/b 6
c = a*b 6
c = a*b 8
Info [UMFPACK_LNZ_ESTIMATE]: an estimate of the number of nonzeros in
L, including the diagonal. Since L is unitdiagonal, the diagonal
of L is not stored. This estimate is a strict upper bound on the
actual nonzeros in L to be computed by umfpack_*_numeric.
Info [UMFPACK_UNZ_ESTIMATE]: an estimate of the number of nonzeros in
U, including the diagonal. This estimate is a strict upper bound on
the actual nonzeros in U to be computed by umfpack_*_numeric.
Info [UMFPACK_MAX_FRONT_SIZE_ESTIMATE]: estimate of the size of the
largest frontal matrix (# of entries), for arbitrary partial
pivoting during numerical factorization.
Info [UMFPACK_SYMBOLIC_TIME]: The CPU time taken, in seconds.
The rest of the statistics are new to Version 4.1:
Info [UMFPACKSYMBOLICWALLTIME]: The wallclock time taken, in seconds.
Info [UMFPACKSTRATEGYUSED]: The ordering strategy used:
UMFPACKSTRATEGYSYMMETRIC, UMFPACKSTRATEGY_UNSYMMETRIC, or
UMFPACK STRATEGY 2BY2.
Info [UMFPACK_ORDERING_USED]: The ordering method used:
UMFPACK ORDERING COLAMD or UMFPACK ORDERING AMD. It can be
UMFPACK_ORDERING_GIVEN for umfpack_*_qsymbolic.
Info [UMFPACK_QFIXED]: 1 if the column preordering will be refined
during numerical factorization, 0 if not.
Info [UMFPACK_DIAG_PREFERED]: 1 if diagonal pivoting will be attempted,
0 if not.
Info [UMFPACK_COL_SINGLETONS]: the matrix A is analyzed by first
eliminating all pivots with zero Markowitz cost. This count is the
number of these pivots with exactly one nonzero in their pivot
column.
Info [UMFPACK_ROW_SINGLETONS]: the number of zeroMarkowitzcost
pivots with exactly one nonzero in their pivot row.
Info [UMFPACK_PATTERN_SYMMETRY]: the symmetry of the pattern of S.
Info [UMFPACKNZ_A_PLUS_AT]: the number of offdiagonal entries in S+S'.
Info [UMFPACK_NZDIAG]: the number of entries on the diagonal of S.
Info [UMFPACK_N2]: if S is square, and nempty_row = nempty_col, this
is equal to n_row ni nempty_row.
Info [UMFPACK_S_SYMMETRIC]: 1 if S is square and its diagonal has been
preserved, 0 otherwise.
Info [UMFPACK_MAX_FRONT_NROWS_ESTIMATE]: estimate of the max number of
rows in any frontal matrix, for arbitrary partial pivoting.
Info [UMFPACK_MAX_FRONT_NCOLS_ESTIMATE]: estimate of the max number of
columns in any frontal matrix, for arbitrary partial pivoting.
The next four statistics are computed only if AMD is used:
Info [UMFPACK_SYMMETRIC_LUNZ]: The number of nonzeros in L and U,
assuming no pivoting during numerical factorization, and assuming a
zerofree diagonal of U. Excludes the entries on the diagonal of
L. If the matrix has a purely symmetric nonzero pattern, this is
often a lower bound on the nonzeros in the actual L and U computed
in the numerical factorization, for matrices that fit the criteria
for the "symmetric" strategy.
Info [UMFPACK_SYMMETRIC_FLOPS]: The floatingpoint operation count in
the numerical factorization phase, assuming no pivoting. If the
pattern of the matrix is symmetric, this is normally a lower bound
on the floatingpoint operation count in the actual numerical
factorization, for matrices that fit the criteria for the symmetric
or 2by2 strategies
Info [UMFPACK_SYMMETRIC_NDENSE]: The number of "dense" rows/columns of
S+S' that were ignored during the AMD ordering. These are placed
last in the output order. If > 0, then the
Info [UMFPACK_SYMMETRIC_*] statistics, above are rough upper bounds.
Info [UMFPACK_SYMMETRIC_DMAX]: The maximum number of nonzeros in any
column of L, if no pivoting is performed during numerical
factorization. Excludes the part of the LU factorization for
pivots with zero Markowitz cost.
The following statistics are computed only if the 2by2 strategy is
used or attempted:
Info [UMFPACK_2BY2_NWEAK]: the number of small diagonal entries in S.
Info [UMFPACK_2BY2_UNMATCHED]: the number of small diagonal entries
in P2*S.
Info [UMFPACK_2BY2_PATTERN_SYMMETRY]: the symmetry of P2*S.
Info [UMFPACK_2BY2_NZ_PA_PLUS_AT]: the number of offdiagonal entries
in (P2*S)+(P2*S)'.
Info [UMFPACK_2BY2_NZDIAG]: the number of nonzero entries on the
diagonal of P2*S.
At the start of umfpack_*_symbolic, all of Info is set of 1, and then
after that only the above listed Info [...] entries are accessed.
Future versions might modify different parts of Info.
16.2 umfpack_*_numeric
umfpack_di_numeric
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
void *Symbolic,
void **Numeric,
const double Control
double Info [UMFPACK_
long umfpackdlnumeric
(
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
void *Symbolic,
void **Numeric,
const double Control
double Info [UMFPACK_
int umfpack_zi_numeric
(
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
void *Symbolic,
void **Numeric,
const double Control
double Info [UMFPACK_
long umfpackzlnumeric
(
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
void *Symbolic,
void **Numeric,
const double Control
double Info [UMFPACK_
double int Syntax:
[UMFPACK_CONTROL],
INFO]
[UMFPACK_CONTROL],
INFO]
const double Az [ ],
[UMFPACK_CONTROL],
INFO]
const double Az [ ],
[UMFPACK_CONTROL],
INFO]
#include "umfpack.h"
void *Symbolic, *Numeric ;
int *Ap, *Ai, status ;
double *Ax, Control [UMFPACK_CONTROL], Info [UMFPACK_INFO] ;
status = umfpack_di_numeric (Ap, Ai, Ax, Symbolic, &Numeric, Control, Info);
double long Syntax:
#include "umfpack.h"
void *Symbolic, *Numeric ;
long *Ap, *Ai, status ;
double *Ax, Control [UMFPACK_CONTROL], Info [UMFPACK_INFO] ;
status = umfpack_dl_numeric (Ap, Ai, Ax, Symbolic, &Numeric, Control, Info);
complex int Syntax:
#include "umfpack.h"
void *Symbolic, *Numeric ;
int *Ap, *Ai, status ;
double *Ax, *Az, Control [UMFPACK_CONTROL], Info [UMFPACK_INFO]
status = umfpack_zi_numeric (Ap, Ai, Ax, Az, Symbolic, &Numeric,
Control, Info)
complex long Syntax:
#include "umfpack.h"
void *Symbolic, *Numeric ;
long *Ap, *Ai, status ;
double *Ax, *Az, Control [UMFPACK_CONTROL], Info [UMFPACK_INFO]
status = umfpack_zl_numeric (Ap, Ai, Ax, Symbolic, &Numeric,
Control, Info)
Purpose:
Given a sparse matrix A in columnoriented form, and a symbolic analysis
computed by umfpack_*_*symbolic, the umfpack_*_numeric routine performs the
numerical factorization, PAQ=LU, PRAQ=LU, or P(R\A)Q=LU, where P and Q are
permutation matrices (represented as permutation vectors), R is the row
scaling, L is unitlower triangular, and U is upper triangular. This is
required before the system Ax=b (or other related linear systems) can be
solved. umfpack_*_numeric can be called multiple times for each call to
umfpack_*_*symbolic, to factorize a sequence of matrices with identical
nonzero pattern. Simply compute the Symbolic object once, with
umfpack_*_*symbolic, and reuse it for subsequent matrices. This routine
safely detects if the pattern changes, and sets an appropriate error code.
Returns:
The status code is returned. See Info [UMFPACK_STATUS], below.
Arguments:
Int Ap En_col+l] ; Input argument, not modified.
This must be identical to the Ap array passed to umfpack_*_*symbolic.
The value of ncol is what was passed to umfpack_*_*symbolic (this is
held in the Symbolic object).
Int Ai [nz] ; Input argument, not modified, of size nz = Ap En_col].
This must be identical to the Ai array passed to umfpack_*_*symbolic.
double Ax [nz] ; Input argument, not modified, of size nz = Ap En_col].
The numerical values of the sparse matrix A. The nonzero pattern (row
indices) for column j is stored in Ai [(Ap [j]) ... (Ap [j+l]1)], and
the corresponding numerical values are stored in
Ax [(Ap [j]) ... (Ap [j+1]1)].
Input argument, not modified, for complex versions.
For the complex versions, this holds the imaginary part of A. The
imaginary part of column j is held in Az [(Ap [j]) ... (Ap [j+1]1)].
Future complex version: if Ax is present and Az is NULL, then both real
and imaginary parts will be contained in Ax[0..2*nzl], with Ax[2*k]
and Ax[2*k+l] being the real and imaginary part of the kth entry.
void *Symbolic ; Input argument, not modified.
The Symbolic object, which holds the symbolic factorization computed by
umfpack_*_*symbolic. The Symbolic object is not modified by
umfpack_*_numeric.
void **Numeric ; Output argument.
**Numeric is the address of a (void *) pointer variable in the user's
calling routine (see Syntax, above). On input, the contents of this
variable are not defined. On output, this variable holds a (void *)
pointer to the Numeric object (if successful), or (void *) NULL if
a failure occurred.
double Control [UMFPACK_CONTROL] ; Input argument, not modified.
If a (double *) NULL pointer is passed, then the default control
settings are used. Otherwise, the settings are determined from the
Control array. See umfpack_*_defaults on how to fill the Control
array with the default settings. If Control contains NaN's, the
defaults are used. The following Control parameters are used:
Control [UMFPACK_PIVOT_TOLERANCE]: relative pivot tolerance for
threshold partial pivoting with row interchanges. In any given
column, an entry is numerically acceptable if its absolute value is
greater than or equal to Control [UMFPACK_PIVOT_TOLERANCE] times
the largest absolute value in the column. A value of 1.0 gives true
partial pivoting. If less than or equal to zero, then any nonzero
entry is numerically acceptable as a pivot (this is changed from
Version 4.0). Default: 0.1.
Smaller values tend to lead to sparser LU factors, but the solution
to the linear system can become inaccurate. Larger values can lead
to a more accurate solution (but not always), and usually an
increase in the total work.
For complex matrices, a cheap approximate of the absolute value
is used for the threshold partial pivoting test (la_reall + la_imagl
instead of the more expensivetocompute exact absolute value
sqrt (a_real^2 + a_imag^2)).
Control [UMFPACK_SYM_PIVOT_TOLERANCE]: This parameter is new to V4.1.
If diagonal pivoting is attempted (the symmetric or symmetric2by2
strategies are used) then this parameter is used to control when the
diagonal entry is selected in a given pivot column. The absolute
value of the entry must be >= Control [UMFPACK_SYM_PIVOT_TOLERANCE]
times the largest absolute value in the column. A value of zero
will ensure that no offdiagonal pivoting is performed, except that
zero diagonal entries are not selected if there are any offdiagonal
double Az Enz]
nonzero entries.
If an offdiagonal pivot is selected, an attempt is made to restore
symmetry later on. Suppose A (i,j) is selected, where i != j.
If column i has not yet been selected as a pivot column, then
the entry A (j,i) is redefined as a "diagonal" entry, except that
the tighter tolerance (Control [UMFPACK_PIVOT_TOLERANCE]) is
applied. This strategy has an effect similar to 2by2 pivoting
for symmetric indefinite matrices. If a 2by2 block pivot with
nonzero structure
ij
i: 0 x
j: x 0
is selected in a symmetric indefinite factorization method, the
2by2 block is inverted and a rank2 update is applied. In
UMFPACK, this 2by2 block would be reordered as
ji
i: x 0
j: 0 x
In both cases, the symmetry of the Schur complement is preserved.
Control [UMFPACKSCALE]: This parameter is new to V4.1. Version 4.0
did not scale the matrix. Note that the user's input matrix is
never modified, only an internal copy is scaled.
There are three valid settings for this parameter. If any other
value is provided, the default is used.
UMFPACK_SCALE_NONE: no scaling is performed.
UMFPACK_SCALE_SUM: each row of the input matrix A is divided by
the sum of the absolute values of the entries in that row.
The scaled matrix has an infinity norm of 1.
UMFPACK_SCALE_MAX: each row of the input matrix A is divided by
the maximum the absolute values of the entries in that row.
In the scaled matrix the largest entry in each row has
a magnitude exactly equal to 1.
Note that for complex matrices, a cheap approximate absolute value
is used, la_reall + la_imagl, instead of the exact absolute value
sqrt ((a_real)^2 + (a_imag)^2).
Scaling is very important for the "symmetric" strategy when
diagonal pivoting is attempted. It also improves the performance
of the "unsymmetric" strategy.
Default: UMFPACK SCALE SUM.
Control [UMFPACK_ALLOC_INIT]: This parameter has changed in V4.1.
When umfpack_*_numeric starts, it allocates memory for the Numeric
object. Part of this is of fixed size (approximately n double's +
12*n integers). The remainder is of variable size, which grows to
hold the LU factors and the frontal matrices created during
factorization. A estimate of the upper bound is computed by
umfpack_*_*symbolic, and returned by umfpack_*_*symbolic in
Info [UMFPACK_VARIABLE_PEAK_ESTIMATE] (in Units).
If Control [UMFPACK_ALLOC_INIT] is >= 0, umfpack_*_numeric initially
allocates space for the variablesized part equal to this estimate
times Control [UMFPACK_ALLOC_INIT]. Typically, for matrices for
which the "unsymmetric" strategy applies, umfpack_*_numeric needs
only about half the estimated memory space, so a setting of 0.5 or
0.6 often provides enough memory for umfpack_*_numeric to factorize
the matrix with no subsequent increases in the size of this block.
If the matrix is ordered via AMD, then this nonnegative parameter
is ignored. The initial allocation ratio computed automatically,
as 1.2 (nz + Info [UMFPACK_SYMMETRIC_LUNZ]) /
(Info [UMFPACK_LNZ_ESTIMATE] + Info [UMFPACK_UNZ_ESTIMATE] 
min (n_row, n_col)).
If Control [UMFPACK_ALLOC_INIT] is negative, then umfpack_*_numeric
allocates a space with initial size (in Units) equal to
(Control [UMFPACK_ALLOC_INIT]).
Regardless of the value of this parameter, a space equal to or
greater than the the bare minimum amount of memory needed to start
the factorization is always initially allocated. The bare initial
memory required is returned by umfpack_*_*symbolic in
Info [UMFPACK_VARIABLE_INIT_ESTIMATE] (an exact value, not an
estimate).
If the variablesize part of the Numeric object is found to be too
small sometime after numerical factorization has started, the memory
is increased in size by a factor of 1.2. If this fails, the
request is reduced by a factor of 0.95 until it succeeds, or until
it determines that no increase in size is possible. Garbage
collection then occurs.
The strategy of attempting to "malloc" a working space, and
retrying with a smaller space, may not work under MATLAB, since
mxMalloc aborts the mexFunction if it fails. The builtin umfpack
routine (version 4.0) in MATLAB 6.5 uses utMalloc instead, which
avoids this problem. As a mexFunction, utMalloc is used unless
DNUTIL is defined at compile time. The utMalloc routine, and
utFree and utRealloc, are not documented. If the mexFunction
doesn't work, then compile it with DNUTIL instead.
If you are using the umfpack mexFunction, decrease the magnitude of
Control [UMFPACK_ALLOC_INIT] if you run out of memory in MATLAB.
Default initial allocation size: 0.7. Thus, with the default
control settings and the "unsymmetric" strategy, the upperbound is
reached after two reallocations (0.7 1.2 1.2 = 1.008).
Changing this parameter has little effect on fillin or operation
count. It has a small impact on runtime (the extra time required
to do the garbage collection and memory reallocation).
Control [UMFPACK_FRONT_ALLOC_INIT]: This parameter is new to V4.1.
When UMFPACK starts the factorization of each "chain" of frontal
matrices, it allocates a working array to hold the frontal matrices
as they are factorized. The symbolic factorization computes the
size of the largest possible frontal matrix that could occur during
the factorization of each chain.
If Control [UMFPACK_FRONT_ALLOC_INIT] is >= 0, the following
strategy is used. If the AMD ordering was used, this nonnegative
parameter is ignored. A front of size (d+2)*(d+2) is allocated,
where d = Info [UMFPACK_SYMMETRIC_DMAX]. Otherwise, a front of
size Control [UMFPACK_FRONT_ALLOC_INIT] times the largest front
possible for this chain is allocated.
If Control [UMFPACK_FRONT_ALLOC_INIT] is negative, then a front of
size (Control [UMFPACK_FRONT_ALLOC_INIT]) is allocated (where the
size is in terms of the number of numerical entries). This is done
regardless of the ordering method or ordering strategy used.
Default: 0.5.
Control [UMFPACK_DROPTOL]: This parameter is new to V4.2.
Entries in L and U with absolute value less than or equal to the
drop tolerance are removed from the data structures (unless leaving
them there reduces memory usage by reducing the space required
for the nonzero pattern of L and U).
Default: 0.0.
double Info [UMFPACK_INFO] ; Output argument.
Contains statistics about the numeric factorization. If a
(double *) NULL pointer is passed, then no statistics are returned in
Info (this is not an error condition). The following statistics are
computed in umfpack_*_numeric:
Info [UMFPACK_STATUS]: status code. This is also the return value,
whether or not Info is present.
UMFPACK OK
Numeric factorization was successful. umfpack_*_numeric
computed a valid numeric factorization.
UMFPACK_WARNING_singular_matrix
Numeric factorization was successful, but the matrix is
singular. umfpack_*_numeric computed a valid numeric
factorization, but you will get a divide by zero in
umfpack_*_*solve. For the other cases below, no Numeric object
is created (*Numeric is (void *) NULL).
UMFPACK_ERRORout of memory
Insufficient memory to complete the numeric factorization.
UMFPACK_ERROR_argument_missing
One or more required arguments are missing.
UMFPACK_ERROR_invalid_Symbolic_object
Symbolic object provided as input is invalid.
UMFPACK_ERROR_different_pattern
The pattern (Ap and/or Ai) has changed since the call to
umfpack_*_*symbolic which produced the Symbolic object.
Info [UMFPACK_NROW]: the value of n_row stored in the Symbolic object.
Info [UMFPACK_NCOL]: the value of n_col stored in the Symbolic object.
Info [UMFPACK_NZ]: the number of entries in the input matrix.
This value is obtained from the Symbolic object.
Info [UMFPACK_SIZEOFUNIT]: the number of bytes in a Unit, for memory
usage statistics below.
Info [UMFPACK_VARIABLE_INIT]: the initial size (in Units) of the
variablesized part of the Numeric object. If this differs from
Info [UMFPACK_VARIABLE_INIT_ESTIMATE], then the pattern (Ap and/or
Ai) has changed since the last call to umfpack_*_*symbolic, which is
an error condition.
Info [UMFPACK_VARIABLE_PEAK]: the peak size (in Units) of the
variablesized part of the Numeric object. This size is the amount
of space actually used inside the block of memory, not the space
allocated via UMF_malloc. You can reduce UMFPACK's memory
requirements by setting Control [UMFPACK_ALLOC_INIT] to the ratio
Info [UMFPACK_VARIABLE_PEAK] / Info[UMFPACK_VARIABLE_PEAKESTIMATE].
This will ensure that no memory reallocations occur (you may want to
add 0.001 to make sure that integer roundoff does not lead to a
memory size that is 1 Unit too small; otherwise, garbage collection
and reallocation will occur).
Info [UMFPACK_VARIABLE_FINAL]: the final size (in Units) of the
variablesized part of the Numeric object. It holds just the
sparse LU factors.
Info [UMFPACK_NUMERIC_SIZE]: the actual final size (in Units) of the
entire Numeric object, including the final size of the variable
part of the object. Info [UMFPACK_NUMERIC_SIZE_ESTIMATE],
an estimate, was computed by umfpack_*_*symbolic. The estimate is
normally an upper bound on the actual final size, but this is not
guaranteed.
Info [UMFPACK_PEAK_MEMORY]: the actual peak memory usage (in Units) of
both umfpack_*_*symbolic and umfpack_*_numeric. An estimate,
Info [UMFPACK_PEAK_MEMORY_ESTIMATE], was computed by
umfpack_*_*symbolic. The estimate is normally an upper bound on the
actual peak usage, but this is not guaranteed. With testing on
hundreds of matrix arising in real applications, I have never
observed a matrix where this estimate or the Numeric size estimate
was less than the actual result, but this is theoretically possible.
Please send me one if you find such a matrix.
Info [UMFPACK_FLOPS]: the actual count of the (useful) floatingpoint
operations performed. An estimate, Info [UMFPACK_FLOPS_ESTIMATE],
was computed by umfpack_*_*symbolic. The estimate is guaranteed to
be an upper bound on this flop count. The flop count excludes
"useless" flops on zero values, flops performed during the pivot
search (for tentative updates and assembly of candidate columns),
and flops performed to add frontal matrices together.
For the real version, only (+ /) are counted. For the complex
version, the following counts are used:
operation flops
c = 1/b 6
c = a*b 6
c = a*b 8
Info [UMFPACK_LNZ]: the actual nonzero entries in final factor L,
including the diagonal. This excludes any zero entries in L,
although some of these are stored in the Numeric object. The
Info [UMFPACK_LU_ENTRIES] statistic does account for all
explicitly stored zeros, however. Info [UMFPACK_LNZ_ESTIMATE],
an estimate, was computed by umfpack_*_*symbolic. The estimate is
guaranteed to be an upper bound on Info [UMFPACK_LNZ].
Info [UMFPACK_UNZ]: the actual nonzero entries in final factor U,
including the diagonal. This excludes any zero entries in U,
although some of these are stored in the Numeric object. The
Info [UMFPACK_LU_ENTRIES] statistic does account for all
explicitly stored zeros, however. Info [UMFPACK_UNZ_ESTIMATE],
an estimate, was computed by umfpack_*_*symbolic. The estimate is
guaranteed to be an upper bound on Info [UMFPACK_UNZ].
Info [UMFPACK_NUMERIC_DEFRAG]: The number of garbage collections
performed during umfpack_*_numeric, to compact the contents of the
variablesized workspace used by umfpack_*_numeric. No estimate was
computed by umfpack_*_*symbolic. In the current version of UMFPACK,
garbage collection is performed and then the memory is reallocated,
so this statistic is the same as Info [UMFPACK_NUMERIC_REALLOC],
below. It may differ in future releases.
Info [UMFPACK_NUMERIC_REALLOC]: The number of times that the Numeric
object was increased in size from its initial size. A rough upper
bound on the peak size of the Numeric object was computed by
umfpack_*_*symbolic, so reallocations should be rare. However, if
umfpack_*_numeric is unable to allocate that much storage, it
reduces its request until either the allocation succeeds, or until
it gets too small to do anything with. If the memory that it
finally got was small, but usable, then the reallocation count
could be high. No estimate of this count was computed by
umfpack_*_*symbolic.
Info [UMFPACK_NUMERIC_COSTLY_REALLOC]: The number of times that the
system realloc library routine (or mxRealloc for the mexFunction)
had to move the workspace. Realloc can sometimes increase the size
of a block of memory without moving it, which is much faster. This
statistic will always be <= Info [UMFPACK_NUMERIC_REALLOC]. If your
memory space is fragmented, then the number of "costly" realloc's
will be equal to Info [UMFPACK_NUMERIC_REALLOC].
Info [UMFPACK_COMPRESSED_PATTERN]: The number of integers used to
represent the pattern of L and U.
Info [UMFPACKLUENTRIES]: The total number of numerical values that
are stored for the LU factors. Some of the values may be explicitly
zero in order to save space (allowing for a smaller compressed
pattern).
Info [UMFPACK_NUMERIC_TIME]: The CPU time taken, in seconds.
Info [UMFPACK_RCOND]: A rough estimate of the condition number, equal
to min (abs (diag (U))) / max (abs (diag (U))), or zero if the
diagonal of U is all zero.
Info [UMFPACK_UDIAG_NZ]: The number of numerically nonzero values on
the diagonal of U.
Info [UMFPACK_UMIN]: the smallest absolute value on the diagonal of U.
Info [UMFPACK_UMAX]: the smallest absolute value on the diagonal of U.
Info [UMFPACK_MAX_FRONT_SIZE]: the size of the
largest frontal matrix (number of entries).
The following statistics were added to Version 4.1:
Info [UMFPACK_NUMERIC_WALLTIME]: The wallclock time taken, in seconds.
Info [UMFPACK_MAX_FRONT_NROWS]: the max number of
rows in any frontal matrix.
Info [UMFPACK_MAX_FRONT_NCOLS]: the max number of
columns in any frontal matrix.
Info [UMFPACK_WAS_SCALED]: the scaling used, either UMFPACK_SCALE_NONE,
UMFPACK_SCALE_SUM, or UMFPACK_SCALE_MAX.
Info [UMFPACK_RSMIN]: if scaling is performed, the smallest scale factor
for any row (either the smallest sum of absolute entries, or the
smallest maximum of absolute entries).
Info [UMFPACK_RSMAX]: if scaling is performed, the largest scale factor
for any row (either the largest sum of absolute entries, or the
largest maximum of absolute entries).
Info [UMFPACK_ALLOC_INIT_USED]: the initial allocation parameter used.
Info [UMFPACK_FORCED_UPDATES]: the number of BLAS3 updates to the
frontal matrices that were required because the frontal matrix
grew larger than its current working array.
Info [UMFPACK_NOFF_DIAG]: number of offdiagonal pivots selected, if the
symmetric or 2by2 strategies are used.
The following statistics were added to Version 4.2:
Info [UMFPACK_NZDROPPED]: the number of entries smaller in absolute
value than Control [UMFPACK_DROPTOL] that were dropped from L and U.
Note that entries on the diagonal of U are never dropped.
Info [UMFPACK_ALL_LNZ]: the number of entries in L, including the
diagonal, if no small entries are dropped.
Info [UMFPACK_ALL_UNZ]: the number of entries in U, including the
diagonal, if no small entries are dropped.
Only the above listed Info [...] entries are accessed. The remaining
entries of Info are not accessed or modified by umfpack_*_numeric.
Future versions might modify different parts of Info.
16.3 umfpack_*_solve
umfpack_di_solve
int sys,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
double X [ ],
const double B [ ],
void *Numeric,
const double Control
double Info [UMFPACK_
long umfpackdlsolve
(
long sys,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
double X [ ],
const double B [ ],
void *Numeric,
const double Control
double Info [UMFPACK_
int umfpack_zi_solve
(
int sys,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
double Xx [ ],
const double Bx [ ],
void *Numeric,
const double Control
double Info [UMFPACK_
long umfpackzlsolve
(
long sys,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
double Xx [ ],
const double Bx [ ],
void *Numeric,
const double Control
double Info [UMFPACK_
double int Syntax:
#include "umfpack.h"
[UMFPACK_CONTROL],
INFO]
[UMFPACK_CONTROL],
INFO]
const double Az [ ],
double Xz [ ],
const double Bz [ ],
[UMFPACK_CONTROL],
INFO]
const double Az [ ],
double Xz [ ],
const double Bz [ ],
[UMFPACK_CONTROL],
INFO]
void *Numeric ;
int status, *Ap, *Ai, sys ;
double *B, *X, *Ax, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ;
status = umfpack_di_solve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info)
double long Syntax:
#include "umfpack.h"
void *Numeric ;
long status, *Ap, *Ai, sys ;
double *B, *X, *Ax, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ;
status = umfpack_dl_solve (sys, Ap, Ai, Ax, X, B, Numeric, Control, Info)
complex int Syntax:
#include "umfpack.h"
void *Numeric ;
int status, *Ap, *Ai, sys ;
double *Bx, *Bz, *Xx, *Xz, *Ax, *Az, Info [UMFPACK_INFO],
Control [UMFPACK_CONTROL] ;
status = umfpack_zi_solve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric,
Control, Info)
complex long Syntax:
#include "umfpack.h"
void *Numeric ;
long status, *Ap, *Ai, sys ;
double *Bx, *Bz, *Xx, *Xz, *Ax,
Control [UMFPACK_CONTROL] ;
status = umfpack_zl_solve (sys,
Control, Info) ;
*Az, Info [UMFPACK_INFO],
Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric,
Purpose:
Given LU factors computed by umfpack_*_numeric (PAQ=LU, PRAQ=LU, or
P(R\A)Q=LU) and the righthandside, B, solve a linear system for the
solution X. Iterative refinement is optionally performed. Only square
systems are handled. Singular matrices result in a dividebyzero for all
systems except those involving just the matrix L. Iterative refinement is
not performed for singular matrices. In the discussion below, n is equal
to n_row and n_col, because only square systems are handled.
Returns:
The status code is returned. See Info [UMFPACK_STATUS], below.
Arguments:
Int sys ; Input argument, not modified.
Defines which system to solve. (') is the linear algebraic transpose
(complex conjugate if A is complex), and (.') is the array transpose.
sys value
UMFPACK A
UMFPACK At
UMFPACK Aat
UMFPACK Pt L
system solved
Ax=b
A'x=b
A.'x=b
P'Lx=b
UMFPACK_
UMFPACK
UMFPACK_
UMFPACK_
UMFPACK_
UMFPACK_
UMFPACK
UMFPACK
UMFPACK
UMFPACK
L
Lt P
Lat P
Lt
U_Qt
U
Q_Ut
Q_Uat
Ut
Uat
Lx=b
L'Px=b
L.'Px=b
L'x=b
UQ'x=b
Ux=b
QU'x=b
QU.'x=b
U'x=b
U.'x=b
Iterative refinement can be
the following:
UMFPACK A
UMFPACK At
UMFPACK Aat
optionally performed when sys is any of
Ax=b
A'x=b
A.'x=b
For the other values of the sys argument, iterative refinement is not
performed (Control [UMFPACK_IRSTEP], Ap, Ai, Ax, and Az are ignored).
Earlier versions used a string argument for sys. It was changed to an
integer to make it easier for a Fortran code to call UMFPACK.
Int Ap [n+1] ;
Int Ai [nz] ;
double Ax [nz]
double Az [nz]
Input argument, not modified.
Input argument, not modified.
Input argument, not modified.
Input argument, not modified, for complex versions.
If iterative refinement is requested (Control [UMFPACK_IRSTEP] >= 1,
Ax=b, A'x=b, or A.'x=b is being solved, and A is nonsingular), then
these arrays must be identical to the same ones passed to
umfpack_*_numeric. The umfpack_*_solve routine does not check the
contents of these arguments, so the results are undefined if Ap, Ai, Ax,
and/or Az are modified between the calls the umfpack_*_numeric and
umfpack_*_solve. These three arrays do not need to be present (NULL
pointers can be passed) if Control [UMFPACK_IRSTEP] is zero, or if a
system other than Ax=b, A'x=b, or A.'x=b is being solved, or if A is
singular, since in each of these cases A is not accessed.
Future complex version: if Ax is present and Az is NULL, then both real
and imaginary parts will be contained in Ax[O..2*nzl], with Ax[2*k]
and Ax[2*k+l] being the real and imaginary part of the kth entry.
double X [n]
or:
double Xx [n]
double Xz n] ;
Output argument.
Output argument, real part.
Output argument, imaginary part.
The solution to the linear system, where n = n_row
dimension of the matrices A, L, and U.
Future complex version: if Xx is present and Xz is NULL, then both real
and imaginary parts will be returned in Xx[0..2*nl], with Xx[2*k] and
Xx[2*k+l] being the real and imaginary part of the kth entry.
double B [n]
or:
double Bx [n]
Input argument, not modified.
Input argument, not modified, real part.
n_col is the
Input argument, not modified, imaginary part.
The righthand side vector, b, stored as a conventional array of size n
(or two arrays of size n for complex versions). This routine does not
solve for multiple righthandsides, nor does it allow b to be stored in
a sparsecolumn form.
Future complex version: if Bx is present and Bz is NULL, then both real
and imaginary parts will be contained in Bx[O..2*nl], with Bx[2*k]
and Bx[2*k+l] being the real and imaginary part of the kth entry.
void *Numeric ;
Input argument, not modified.
Numeric must point to a valid Numeric object, computed by
umfpack_*_numeric.
double Control [UMFPACK_CONTROL] ; Input argument, not modified.
If a (double *) NULL pointer is passed, then the default control
settings are used. Otherwise, the settings are determined from the
Control array. See umfpack_*_defaults on how to fill the Control
array with the default settings. If Control contains NaN's, the
defaults are used. The following Control parameters are used:
Control [UMFPACK_IRSTEP]: The maximum number of iterative refinement
steps to attempt. A value less than zero is treated as zero. If
less than 1, or if Ax=b, A'x=b, or A.'x=b is not being solved, or
if A is singular, then the Ap, Ai, Ax, and Az arguments are not
accessed. Default: 2.
double Info [UMFPACK_INFO] ;
Output argument.
Contains statistics about the solution factorization.
(double *) NULL pointer is passed, then no statistics
Info (this is not an error condition). The following
computed in umfpack_*_solve:
Info [UMFPACK_STATUS]: status code. This is also the
whether or not Info is present.
UMFPACK OK
The linear system was successfully solved.
If a
are returned in
statistics are
return value,
UMFPACK_WARNING_singular_matrix
A dividebyzero occurred. Your solution will
and/or NaN's. Some parts of the solution may
example, solving Ax=b with
A = [2 0] b = [ I ] returns x
[0 0] [ 0 ]
contain Inf's
be valid. For
[ 0.5 ]
[ Inf ]
UMFPACK_ERRORout of memory
Insufficient memory to solve the linear system.
UMFPACK_ERROR_argument_missing
double Bz [n] ;
One or more required arguments are missing. The B, X, (or
Bx, Bz, Xx and Xz for the complex versions) arguments
are always required. Info and Control are not required. Ap,
Ai, Ax (and Az for complex versions) are required if Ax=b,
A'x=b, A.'x=b is to be solved, the (default) iterative
refinement is requested, and the matrix A is nonsingular.
UMFPACK_ERROR_invalid_system
The sys argument is not valid, or the matrix A is not square.
UMFPACK_ERROR_invalid_Numeric_object
The Numeric object is not valid.
Info [UMFPACK_NROW], Info [UMFPACK_NCOL]:
The dimensions of the matrix A (L is n_rowbyn_inner and
U is n_innerbyn_col, with n_inner = min(n_row,n_col)).
Info [UMFPACK_NZ]: the number of entries in the input matrix, Ap [n],
if iterative refinement is requested (Ax=b, A'x=b, or A.'x=b is
being solved, Control [UMFPACK_IRSTEP] >= 1, and A is nonsingular).
Info [UMFPACKIRTAKEN]: The number of iterative refinement steps
effectively taken. The number of steps attempted may be one more
than this; the refinement algorithm backtracks if the last
refinement step worsens the solution.
Info [UMFPACKIRATTEMPTED]: The number of iterative refinement steps
attempted. The number of times a linear system was solved is one
more than this (once for the initial Ax=b, and once for each Ay=r
solved for each iterative refinement step attempted).
Info [UMFPACK_OMEGA1]: sparse backward error estimate, omegal, if
iterative refinement was performed, or 1 if iterative refinement
not performed.
Info [UMFPACK_OMEGA2]: sparse backward error estimate, omega2, if
iterative refinement was performed, or 1 if iterative refinement
not performed.
Info [UMFPACK_SOLVE_FLOPS]: the number of floating point operations
performed to solve the linear system. This includes the work
taken for all iterative refinement steps, including the backtrack
(if any).
Info [UMFPACK_SOLVE_TIME]: The time taken, in seconds.
The following statistic was added to Version 4.1:
Info [UMFPACK_SOLVE_WALLTIME]: The wallclock time taken, in seconds.
Only the above listed Info [...] entries are accessed. The remaining
entries of Info are not accessed or modified by umfpack_*_solve.
Future versions might modify different parts of Info.
16.4 umfpack_*_free_symbolic
void umfpackdifree_symbolic
void **Symbolic
void umfpackdlfree_symbolic
void **Symbolic
void umfpackzifree_symbolic
void **Symbolic
void umfpackzlfree_symbolic
void **Symbolic
double int Syntax:
#include "umfpack.h"
void *Symbolic ;
umfpack_di_free_symbolic
(&Symbolic) ;
double long Syntax:
#include "umfpack.h"
void *Symbolic ;
umfpack_dl_free_symbolic
(&Symbolic) ;
complex int Syntax:
#include "umfpack.h"
void *Symbolic ;
umfpack_zi_free_symbolic
(&Symbolic) ;
complex long Syntax:
#include "umfpack.h"
void *Symbolic ;
umfpack_zl_free_symbolic
(&Symbolic) ;
Purpose:
Deallocates the Symbolic object and sets the Symbolic handle to NULL. This
routine is the only valid way of destroying the Symbolic object.
Arguments:
void **Symbolic ;
Input argument, set to (void *) NULL on output.
Points to a valid Symbolic object computed by umfpack_*_symbolic.
No action is taken if Symbolic is a (void *) NULL pointer.
16.5 umfpack_*_freenumeric
void umfpackdifree_numeric
(
void **Numeric
void umfpackdlfree_numeric
(
void **Numeric
void umfpackzifree_numeric
(
void **Numeric
void umfpackzlfree_numeric
void **Numeric
void **Numeric
double int Syntax:
#include "umfpack.h"
void *Numeric ;
umfpack_di_free_numeric
(&Numeric) ;
double long Syntax:
#include "umfpack.h"
void *Numeric ;
umfpack_dl_free_numeric
(&Numeric) ;
complex int Syntax:
#include "umfpack.h"
void *Numeric ;
umfpack_zi_free_numeric
(&Numeric) ;
complex long Syntax:
#include "umfpack.h"
void *Numeric ;
umfpack_zl_free_numeric
(&Numeric) ;
Purpose:
Deallocates the Numeric object and sets the Numeric handle to NULL. This
routine is the only valid way of destroying the Numeric object.
Arguments:
void **Numeric ;
Input argument, set to (void *) NULL on output.
Numeric points to a valid Numeric object, computed by umfpack_*_numeric.
No action is taken if Numeric is a (void *) NULL pointer.
17 Alternative routines
17.1 umfpack_*_defaults
void umfpackdidefaults
(
double Control [UMFPACK_CONTROL]
void umfpackdldefaults
(
double Control [UMFPACK_CONTROL]
void umfpackzidefaults
(
double Control [UMFPACK_CONTROL]
void umfpackzldefaults
(
double Control [UMFPACK_CONTROL]
double int Syntax:
#include "umfpack.h"
double Control [UMFPACK_CONTROL]
umfpack_di_defaults (Control)
double long Syntax:
#include "umfpack.h"
double Control [UMFPACK_CONTROL]
umfpack_dl_defaults (Control)
complex int Syntax:
#include "umfpack.h"
double Control [UMFPACK_CONTROL]
umfpack_zi_defaults (Control)
complex long Syntax:
#include "umfpack.h"
double Control [UMFPACK_CONTROL]
umfpack_zl_defaults (Control)
Purpose:
Sets the default control parameter settings.
NOTE: new control parameters have been added to the Control array for
Version 4.1. These entries were unused in Version 4.0. The default block
size for the BLAS has increased from 24 to 32. Some rarely used control
parameters have been removed (those that controlled relaxed amalgamation).
Arguments:
double Control [UMFPACK_CONTROL] ; Output argument.
Control is set to the default control parameter settings. You can
then modify individual settings by changing specific entries in the
Control array. If Control is a (double *) NULL pointer, then
umfpack_*_defaults returns silently (no error is generated, since
passing a NULL pointer for Control to any UMFPACK routine is valid).
17.2 umfpack_*_qsymbolic
umfpack_di_qsymbolic
int n_row,
int n_col,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
const int Qinit [ ],
void **Symbolic,
const double Control
double Info [UMFPACK_
[UMFPACK_CONTROL],
INFO]
long umfpack_dl_qsymbolic
long n_row,
long n_col,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
const long Qinit [ ],
void **Symbolic,
const double Control [UMFPACK_CONTROL],
double Info [UMFPACK_INFO]
int umfpack_zi_qsymbolic
(
int n_row,
int n_col,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
const int Qinit [ ],
void **Symbolic,
const double Control
double Info [UMFPACK_
const double Az [ ],
[UMFPACK_CONTROL],
INFO]
long umfpack_zl_qsymbolic
(
long n_row,
long n_col,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ], const double Az [ ],
const long Qinit [ ],
void **Symbolic,
const double Control [UMFPACK_CONTROL],
double Info [UMFPACK_INFO]
) ;
double int Syntax:
#include "umfpack.h"
void *Symbolic ;
int n_row, n_col, *Ap, *Ai, *Qinit, status ;
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], *Ax ;
status = umfpack_di_qsymbolic (n_row, n_col, Ap, Ai, Ax, Qinit,
&Symbolic, Control, Info)
double long Syntax:
#include "umfpack.h"
void *Symbolic ;
long n_row, n_col, *Ap, *Ai, *Qinit, status ;
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], *Ax ;
status = umfpack_dl_qsymbolic (n_row, n_col, Ap, Ai, Ax, Qinit,
&Symbolic, Control, Info)
complex int Syntax:
#include "umfpack.h"
void *Symbolic ;
int n_row, n_col, *Ap, *Ai, *Qinit, status ;
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], *Ax, *Az ;
status = umfpack_zi_qsymbolic (n_row, n_col, Ap, Ai, Ax, Az, Qinit,
&Symbolic, Control, Info)
complex long Syntax:
#include "umfpack.h"
void *Symbolic ;
long n_row, n_col, *Ap, *Ai, *Qinit, status ;
double Control [UMFPACK_CONTROL], Info [UMFPACK_INFO], *Ax, *Az ;
status = umfpack_zl_qsymbolic (n_row, n_col, Ap, Ai, Ax, Az, Qinit,
&Symbolic, Control, Info)
Purpose:
Given the nonzero pattern of a sparse matrix A in columnoriented form, and
a sparsity preserving column preordering Qinit, umfpack_*_qsymbolic
performs the symbolic factorization of A*Qinit (or A (:,Qinit) in MATLAB
notation). This is identical to umfpack_*_symbolic, except that neither
COLAMD nor AMD are called and the user input column order Qinit is used
instead. Note that in general, the Qinit passed to umfpack_*_qsymbolic
can differ from the final Q found in umfpack_*_numeric. The unsymmetric
strategy will perform a column etree postordering done in
umfpack_*_qsymbolic and sparsitypreserving modifications are made within
each frontal matrix during umfpack_*_numeric. The symmetric and 2by2
strategies will preserve Qinit, unless the matrix is structurally singular.
See umfpack_*_symbolic for more information.
*** WARNING *** A poor choice of Qinit can easily cause umfpack_*_numeric
to use a huge amount of memory and do a lot of work. The "default" symbolic
analysis method is umfpack_*_symbolic, not this routine. If you use this
routine, the performance of UMFPACK is your responsibility; UMFPACK will
not try to secondguess a poor choice of Qinit.
Returns:
The value of Info [UMFPACK_STATUS]; see umfpack_*_symbolic.
Also returns UMFPACK_ERROR_invalid_permuation if Qinit is not a valid
permutation vector.
Arguments:
All arguments are the same as umfpack_*_symbolic, except for the following:
Int Qinit [n_col] ; Input argument, not modified.
The user's fillreducing initial column preordering. This must be a
permutation of O..n_coll. If Qinit [k] = j, then column j is the kth
column of the matrix A (:,Qinit) to be factorized. If Qinit is an
(Int *) NULL pointer, then COLAMD or AMD are called instead.
17.3 umfpack_*_wsolve
int umfpack_di_wsolve
(
int sys,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
double X [ ],
const double B [ ],
void *Numeric,
const double Control
double Info [UMFPACK_
int Wi [ ],
double W [ ]
long umfpackdlwsolve
(
long sys,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
double X [ ],
const double B [ ],
void *Numeric,
const double Control
double Info [UMFPACK_
long Wi [ ],
double W [ ]
int umfpack_zi_wsolve
(
int sys,
const int Ap [ ],
const int Ai [ ],
const double Ax [ ],
double Xx [ ],
const double Bx [ ],
void *Numeric,
const double Control
double Info [UMFPACK_
int Wi [ ],
double W [ ]
[UMFPACK_CONTROL],
INFO],
[UMFPACK_CONTROL],
INFO],
const double Az [ ],
double Xz [ ],
const double Bz [ ],
[UMFPACK_CONTROL],
INFO],
long umfpackzlwsolve
(
long sys,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ], const double Az [ ],
double Xx [ ], double Xz [ ],
const double Bx [ ], const double Bz [ ],
void *Numeric,
const double Control [UMFPACKCONTROL],
double Info [UMFPACK_INFO],
long Wi [ ],
double W [ ]
double int Syntax:
#include "umfpack.h"
void *Numeric ;
int status, *Ap, *Ai, *Wi, sys ;
double *B, *X, *Ax, *W, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL]
status = umfpack_di_wsolve (sys, Ap, Ai, Ax, X, B, Numeric,
Control, Info, Wi, W)
double long Syntax:
#include "umfpack.h"
void *Numeric ;
long status, *Ap, *Ai, *Wi, sys ;
double *B, *X, *Ax, *W, Info [UMFPACK_INFO], Control [UMFPACK_CONTROL]
status = umfpack_dl_wsolve (sys, Ap, Ai, Ax, X, B, Numeric,
Control, Info, Wi, W)
complex int Syntax:
#include "umfpack.h"
void *Numeric ;
int status, *Ap, *Ai, *Wi, sys ;
double *Bx, *Bz, *Xx, *Xz, *Ax, *Az, *W,
Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ;
status = umfpack_zi_wsolve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric,
Control, Info, Wi, W)
complex long Syntax:
#include "umfpack.h"
void *Numeric ;
long status, *Ap, *Ai, *Wi, sys ;
double *Bx, *Bz, *Xx, *Xz, *Ax, *Az, *W,
Info [UMFPACK_INFO], Control [UMFPACK_CONTROL] ;
status = umfpack_zl_wsolve (sys, Ap, Ai, Ax, Az, Xx, Xz, Bx, Bz, Numeric,
Control, Info, Wi, W)
Purpose:
Given LU factors computed by umfpack_*_numeric (PAQ=LU) and the
righthandside, B, solve a linear system for the solution X. Iterative
refinement is optionally performed. This routine is identical to
umfpack_*_solve, except that it does not dynamically allocate any workspace.
When you have many linear systems to solve, this routine is faster than
umfpack_*_solve, since the workspace (Wi, W) needs to be allocated only
once, prior to calling umfpack_*_wsolve.
Returns:
The status code is returned. See Info [UMFPACK_STATUS], below.
Arguments:
Int sys ; Input argument,
Int Ap [n+1] ; Input argument,
Int Ai [nz] ; Input argument,
double Ax [nz] ; Input argument,
double X [n] ; Output argument
double B [n] ; Input argument,
void *Numeric ; Input argument,
double Control [UMFPACK_CONTROL] ;
double Info [UMFPACK_INFO] ;
modified.
modified.
modified.
modified.
not modified.
not modified.
Input argument, not modified.
Output argument.
for complex versions:
double Az [nz] ; Input argument, not modified, imaginary part
double Xx [n] ; Output argument, real part.
double Xz [n] ; Output argument, imaginary part
double Bx [n] ; Input argument, not modified, real part
double Bz [n] ; Input argument, not modified, imaginary part
The above arguments are identical to umfpack_*_solve, except that the
error code UMFPACK_ERROR_out_of_memory will not be returned in
Info [UMFPACK_STATUS], since umfpack_*_wsolve does not allocate any
memory.
Int Wi [n] ;
double W c*n] ;
Workspace.
Workspace, where c is defined below.
The Wi and W arguments are workspace used by umfpack_*_wsolve. They
need not be initialized on input, and their contents are undefined on
output. The size of W depends on whether or not iterative refinement is
used, and which version (real or complex) is called. Iterative
refinement is performed if Ax=b, A'x=b, or A.'x=b is being solved,
Control [UMFPACK_IRSTEP] > 0, and A is nonsingular. The size of W is
given below:
no iter.
refinement
umfpackdiwsolve
umfpackdlwsolve
umfpackziwsolve
umfpackzlwsolve
with iter.
refinement
5*n
5*n
10*n
10*n
18 Matrix manipulation routines
18.1 umfpack_*_col_to_triplet
int umfpackdicoltotriplet
int n_col,
const int Ap [ ],
int Tj [ ]
long umfpackdlcoltotriplet
long n_col,
const long Ap [ ],
long Tj [ ]
int umfpackzicoltotriplet
int n_col,
const int Ap [ ],
int Tj [ ]
long umfpackzlcoltotriplet
long n_col,
const long Ap [ ],
long Tj [ ]
double int Syntax:
#include "umfpack.h"
int n_col, *Tj, *Ap, status
status = umfpackdicoltotriplet (ncol, Ap, Tj)
double long Syntax:
#include "umfpack.h"
long n_col, *Tj, *Ap, status ;
status = umfpack_dl_col_to_triplet (n_col, Ap, Tj)
complex int Syntax:
#include "umfpack.h"
int n_col, *Tj, *Ap, status
status = umfpackzicoltotriplet (ncol, Ap, Tj)
complex long Syntax:
#include "umfpack.h"
long n_col, *Tj, *Ap, status ;
status = umfpack_zl_col_to_triplet (n_col, Ap, Tj)
Purpose:
Converts a columnoriented matrix to a triplet form. Only the column
pointers, Ap, are required, and only the column indices of the triplet form
are constructed. This routine is the opposite of umfpack_*_triplettocol.
The matrix may be singular and/or rectangular. Analogous to [i, Tj, x] =
find (A) in MATLAB, except that zero entries present in the columnform of
A are present in the output, and i and x are not created (those are just Ai
and Ax+Az*li, respectively, for a columnform matrix A).
Returns:
UMFPACK OK if successful
UMFPACK_ERROR_argument_missing if Ap or Tj is missing
UMFPACK_ERROR_n_nonpositive if n_col <= 0
UMFPACK_ERROR_invalid_matrix if Ap [n_col] < 0, Ap [0] != 0, or
Ap [j] > Ap [j+1] for any j in the range 0 to n1.
Unsorted columns and duplicate entries do not cause an error (these would
only be evident by examining Ai). Empty rows and columns are OK.
Arguments:
Int n_col ; Input argument, not modified.
A is an n_rowbyn_col matrix. Restriction: n_col > 0.
(n_row is not required)
Int Ap [n_col+I] ; Input argument, not modified.
The column pointers of the columnoriented form of the matrix. See
umfpack_*_*symbolic for a description. The number of entries in
the matrix is nz = Ap [n_col]. Restrictions on Ap are the same as those
for umfpack_*_transpose. Ap [0] must be zero, nz must be >= 0, and
Ap [j] <= Ap [j+1] and Ap [j] <= Ap [n_col] must be true for all j in
the range 0 to n_coll. Empty columns are OK (that is, Ap [j] may equal
Ap [j+1] for any j in the range 0 to n_coll).
Int Tj [nz] ; Output argument.
Tj is an integer array of size nz on input, where nz = Ap [n_col].
Suppose the columnform of the matrix is held in Ap, Ai, Ax, and Az
(see umfpack_*_*symbolic for a description). Then on output, the
triplet form of the same matrix is held in Ai (row indices), Tj (column
indices), and Ax (numerical values). Note, however, that this routine
does not require Ai and Ax (or Az for the complex version) in order to
do the conversion.
18.2 umfpack_*_triplet_tocol
umfpack_di_triplet_to_col
int n_row,
int n_col,
int nz,
const int Ti [ ],
const int Tj [ ],
const double Tx [ ],
int Ap [ ],
int Ai [ ],
double Ax [ ],
int Map [ ]
long umfpackdl
(
triplet_to_col
long n_row,
long n_col,
long nz,
const long Ti [ ],
const long Tj [ ],
const double Tx [ ],
long Ap [ ],
long Ai [ ],
double Ax [ ],
long Map [ ]
int umfpack_zi_triplet_to_col
int n_row,
int n_col,
int nz,
const int Ti [ ],
const int Tj [ ],
const double Tx [ ], const double Tz [ ],
int Ap [ ],
int Ai [ ],
double Ax [ ], double Az [ ],
int Map [ ]
) ;
long umfpackzltriplet_to_col
(
long n_row,
long n_col,
long nz,
const long Ti [ ],
const long Tj [ ],
const double Tx [ ], const double Tz [ ],
long Ap [ ],
long Ai [ ],
double Ax [ ], double Az [ ],
long Map [ ]
double int Syntax:
#include "umfpack.h"
int n_row, n_col, nz, *Ti, *Tj, *Ap, *Ai, status, *Map ;
double *Tx, *Ax ;
status = umfpack_di_triplet_to_col (n_row, n_col, nz, Ti, Tj, Tx,
Ap, Ai, Ax, Map)
double long Syntax:
#include "umfpack.h"
long n_row, n_col, nz, *Ti, *Tj, *Ap, *Ai, status, *Map ;
double *Tx, *Ax ;
status = umfpack_dl_triplet_to_col (n_row, n_col, nz, Ti, Tj, Tx,
Ap, Ai, Ax, Map)
complex int Syntax:
#include "umfpack.h"
int n_row, n_col, nz, *Ti, *Tj, *Ap, *Ai, status, *Map ;
double *Tx, *Tz, *Ax, *Az ;
status = umfpack_zi_triplet_to_col (n_row, n_col, nz, Ti, Tj, Tx, Tz,
Ap, Ai, Ax, Az, Map)
long Syntax:
#include "umfpack.h"
long n_row, n_col, nz, *Ti, *Tj, *Ap, *Ai, status, *Map ;
double *Tx, *Tz, *Ax, *Az ;
status = umfpack_zl_triplet_to_col (n_row, n_col, nz, Ti, Tj, Tx, Tz,
Ap, Ai, Ax, Az, Map)
Purpose:
Converts a sparse matrix from "triplet" form to compressedcolumn form.
Analogous to A = spconvert (Ti, Tj, Tx + Tx*li) in MATLAB, except that
zero entries present in the triplet form are present in A.
The triplet form of a matrix is a very simple data structure for basic
sparse matrix operations. For example, suppose you wish to factorize a
matrix A coming from a finite element method, in which A is a sum of
dense submatrices, A = El + E2 + E3 + ... The entries in each element
matrix Ei can be concatenated together in the three triplet arrays, and
any overlap between the elements will be correctly summed by
umfpack_*_triplettocol.
Transposing a matrix in triplet form is simple; just interchange the
use of Ti and Tj. You can construct the complex conjugate transpose by
negating Tz, for the complex versions.
Permuting a matrix in triplet form is also simple. If you want the matrix
PAQ, or A (P,Q) in MATLAB notation, where P [k] = i means that row i of
A is the kth row of PAQ and Q [k] = j means that column j of A is the kth
column of PAQ, then do the following. First, create inverse permutations
Pinv and Qinv such that Pinv [i] = k if P [k] = i and Qinv [j] = k if
Q [k] = j. Next, for the mth triplet (Ti [m], Tj [m], Tx [m], Tz [m]),
replace Ti [m] with Pinv [Ti [m]] and replace Tj [m] with Qinv [Tj [m]].
If you have a columnform matrix with duplicate entries or unsorted
columns, you can sort it and sum up the duplicates by first converting it
to triplet form with umfpack_*_col_to_triplet, and then converting it back
with umfpack_*_triplettocol.
Constructing a submatrix is also easy. Just scan the triplets and remove
those entries outside the desired subset of 0...n_row1 and 0...n_coll,
and renumber the indices according to their position in the subset.
You can do all these operations on a columnform matrix by first
converting it to triplet form with umfpack_*_coltotriplet, doing the
operation on the triplet form, and then converting it back with
umfpack_*_triplettocol.
The only operation not supported easily in the triplet form is the
multiplication of two sparse matrices (UMFPACK does not provide this
operation).
You can print the input triplet form with umfpack_*_report_triplet, and
the output matrix with umfpack_*_report_matrix.
The matrix may be singular (nz can be zero, and empty rows and/or columns
may exist). It may also be rectangular and/or complex.
Returns:
UMFPACK OK if successful.
UMFPACK_ERROR_argument_missing if Ap, Ai, Ti, and/or Tj are missing.
UMFPACK_ERROR_n_nonpositive if n_row <= 0 or n_col <= 0.
UMFPACK_ERROR_invalid_matrix if nz < 0, or if for any k, Ti [k] and/or
Tj [k] are not in the range 0 to n_row1 or 0 to n_coll, respectively.
UMFPACK_ERRORoutof memory if unable to allocate sufficient workspace.
Arguments:
Int n_row ; Input argument, not modified.
Int n_col ; Input argument, not modified.
A is an n_rowbyn_col matrix. Restriction: n_row > 0 and n_col > 0.
All row and column indices in the triplet form must be in the range
0 to n_row1 and 0 to n_coll, respectively.
Int nz ; Input argument, not modified.
The number of entries in the triplet form of the matrix. Restriction:
nz >= 0.
Int Ti [nz] ; Input argument, not modified.
Int Tj [nz] ; Input argument, not modified.
double Tx [nz] ; Input argument, not modified.
double Tz [nz] ; Input argument, not modified, for complex versions.
Ti, Tj, Tx, and Tz hold the "triplet" form of a sparse matrix. The kth
nonzero entry is in row i = Ti [k], column j = Tj [k], and the real part
of a_ij is Tx [k]. The imaginary part of a_ij is Tz [k], for complex
versions. The row and column indices i and j must be in the range 0 to
n_row1 and 0 to n_coll, respectively. Duplicate entries may be
present; they are summed in the output matrix. This is not an error
condition. The "triplets" may be in any order. Tx, Tz, Ax, and Az
are optional. For the real version, Ax is computed only if both Ax
and Tx are present (not (double *) NULL). For the complex version, Ax
and Az are computed only if Tx, Tz, Ax, and Az are all present. These
are not error conditions; the routine can create just the pattern of
the output matrix from the pattern of the triplets.
Future complex version: if Tx is present and Tz is NULL, then both real
and imaginary parts will be contained in Tx[0..2*nzl], with Tx[2*k]
and Tx[2*k+l] being the real and imaginary part of the kth entry.
Int Ap [n_col+1] ; Output argument.
Ap is an integer array of size n_col+1 on input. On output, Ap holds
the "pointers" for the column form of the sparse matrix A. Column j of
the matrix A is held in Ai [(Ap [j]) ... (Ap [j+1]1)]. The first
entry, Ap [0], is zero, and Ap [j] <= Ap [j+1] holds for all j in the
range 0 to n_coll. The value nz2 = Ap [n_col] is thus the total
number of entries in the pattern of the matrix A. Equivalently, the
number of duplicate triplets is nz Ap [n_col].
Int Ai [nz] ; Output argument.
Ai is an integer array of size nz on input. Note that only the first
Ap [n_col] entries are used.
The nonzero pattern (row indices) for column j is stored in
Ai [(Ap [j]) ... (Ap [j+1]1)]. The row indices in a given column j
are in ascending order, and no duplicate row indices are present.
Row indices are in the range 0 to n_col1 (the matrix is Obased).
double Ax [nz] ; Output argument.
double Az [nz] ; Output argument for complex versions.
Ax and Az (for the complex versions) are double arrays of size nz on
input. Note that only the first Ap [n_col] entries are used
in both arrays.
Ax is optional; if Tx and/or Ax are not present (a (double *) NULL
pointer), then Ax is not computed. Az is also optional; if Tz and/or
Az are not present, then Az is not computed. If present, Ax holds the
numerical values of the the real part of the sparse matrix A and Az
holds the imaginary parts. The nonzero pattern (row indices) for
column j is stored in Ai [(Ap [j]) ... (Ap [j+1]1)], and the
corresponding numerical values are stored in
Ax [(Ap [j]) ... (Ap [j+1]1)]. The imaginary parts are stored in
Az [(Ap [j]) ... (Ap [j+1]1)], for the complex versions.
Future complex version: if Ax is present and Az is NULL, then both real
and imaginary parts will be returned in Ax[0..2*nz21], with Ax[2*k]
and Ax[2*k+l] being the real and imaginary part of the kth entry.
int Map [nz] ; Optional output argument.
If Map is present (a nonNULL pointer to an Int array of size nz), then
on output it holds the position of the triplets in the columnform
matrix. That is, suppose p = Map [k], and the kth triplet is i=Ti[k],
j=Tj[k], and aij=Tx[k]. Then i=Ai[p], and aij will have been summed
into Ax[p] (or simply aij=Ax[p] if there were no duplicate entries also
in row i and column j). Also, Ap[j] <= p < Ap[j+1]. The Map array is
not computed if it is (Int *) NULL. The Map array is useful for
converting a subsequent triplet form matrix with the same pattern as the
first one, without calling this routine. If Ti and Tj do not change,
then Ap, and Ai can be reused from the prior call to
umfpack_*_triplet_to_col. You only need to recompute Ax (and Az for the
complex version). This code excerpt properly sums up all duplicate
values (for the real version):
for (p = 0 ; p < Ap [n_col] ; p++) Ax [p] = 0 ;
for (k = 0 ; k < nz ; k++) Ax [Map [k]] += Tx [k] ;
This feature is useful (along with the reuse of the Symbolic object) if
you need to factorize a sequence of triplet matrices with identical
nonzero pattern (the order of the triplets in the Ti,Tj,Tx arrays must
also remain unchanged). It is faster than calling this routine for
each matrix, and requires no workspace.
18.3 umfpack_*_transpose
umfpack_di_transpose
int n_
int n_
const
const
const
const
const
int Rp
int Ri
double
row,
col,
int Ap
int Ai
double
int P [
int Q [
[ ],
Rx [ ],
Rx [1
[ ],
[ ],
Ax [ ],
] ,
] ,
long umfpackdltranspose
long n_row,
long n_col,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ],
const long P [ ],
const long Q [ ],
long Rp [ ],
long Ri [ ],
double Rx [ ]
umfpack_zi_transpose
row,
col,
int Ap [ ],
int Ai [ ],
double Ax [ ], const doi
int P [ ],
int Q [ ],
[ ] ,
[],
Rx [ ], double Rz [ ],
_conjugate
uble Az [ ],
long umfpackzltranspose
(
long n_row,
long n_col,
const long Ap [ ],
const long Ai [ ],
const double Ax [ ], const double Az [ ],
const long P [ ],
const long Q [ ],
long Rp [ ],
long Ri [ ],
double Rx [ ], double Rz [ ],
int n_
int n_
const
const
const
const
const
int Rp
int Ri
double
int do
long do_conjugate
double int Syntax:
#include "umfpack.h"
int n_row, n_col, status, *Ap, *Ai, *P, *Q, *Rp, *Ri ;
double *Ax, *Rx ;
status = umfpack_di_transpose (nrow, ncol, Ap, Ai, Ax,
P, Q, Rp, Ri, Rx)
double long Syntax:
#include "umfpack.h"
long n_row, n_col, status, *Ap, *Ai, *P, *Q, *Rp, *Ri ;
double *Ax, *Rx ;
status = umfpack_dl_transpose (nrow, ncol, Ap, Ai, Ax,
P, Q, Rp, Ri, Rx)
complex int Syntax:
#include "umfpack.h"
int n_row, n_col, status, *Ap, *Ai, *P, *Q, *Rp, *Ri, do_conjugate ;
double *Ax, *Az, *Rx, *Rz ;
status = umfpack_zi_transpose (n_row, n_col, Ap, Ai, Ax, Az, P, Q,
Rp, Ri, Rx, Rz, do_conjugate)
complex long Syntax:
#include "umfpack.h"
long n_row, n_col, status, *Ap, *Ai, *P, *Q,
double *Ax, *Az, *Rx, *Rz ;
status = umfpack_zl_transpose (n_row, n_col,
Rp, Ri, Rx, Rz, do_conjugate) ;
*Rp, *Ri, do_conjugate
Ap, Ai, Ax, Az, P, Q,
Purpose:
Transposes and optionally permutes a sparse matrix in row or columnform,
R = (PAQ)'. In MATLAB notation, R = (A (P,Q))' or R = (A (P,Q)).' doing
either the linear algebraic transpose or the array transpose. Alternatively,
this routine can be viewed as converting A (P,Q) from columnform to
rowform, or visa versa (for the array transpose). Empty rows and columns
may exist. The matrix A may be singular and/or rectangular.
umfpack_*_transpose is useful if you want to factorize A' or A.' instead of
A. Factorizing A' or A.' instead of A can be much better, particularly if
AA' is much sparser than A'A. You can still solve Ax=b if you factorize
A' or A.', by solving with the sys argument UMFPACK_At or UMFPACK_Aat,
respectively, in umfpack_*_*solve. The umfpack mexFunction (umfpackmex.c)
is one example. To compute x = A/b, it computes x = (A.'\b.').' instead,
by factorizing A.'. It then uses the regular solve, since b.' and x.' are
stored identically as b and x, respectively (both b.' and b are dense
vectors). If b and x were arrays, the umfpack mexFunction would need to
first compute b.' and then transpose the resulting solution.
Returns:
UMFPACK OK if successful.
UMFPACK_ERRORoutofmemory if umfpack_*_transpose fails to allocate a
sizemax (n_row,n_col) workspace.
UMFPACK_ERROR_argument_missing if Ai, Ap, Ri, and/or Rp are missing.
UMFPACK_ERROR_n_nonpositive if n_row <= 0 or n_col <= 0
UMFPACK_ERROR_invalid_permutation if P and/or Q are invalid.
UMFPACK_ERROR_invalid_matrix if Ap En_col] < 0, if Ap [0] != 0,
if Ap [j] > Ap [j+1] for any j in the range 0 to n_coll,
if any row index i is < 0 or >= n_row, or if the row indices
in any column are not in ascending order.
Arguments:
Int n_row ; Input argument, not modified.
Int n_col ; Input argument, not modified.
A is an n_rowbyn_col matrix. Restriction: n_row > 0 and n_col > 0.
Int Ap En_col+l] ; Input argument, not modified.
The column pointers of the columnoriented form of the matrix A. See
umfpack_*_symbolic for a description. The number of entries in
the matrix is nz = Ap En_coll. Ap [0] must be zero, Ap En_col] must be
=> 0, and Ap [j] <= Ap [j+1] and Ap [j] <= Ap [n_col] must be true for
all j in the range 0 to n_coll. Empty columns are OK (that is, Ap [j]
may equal Ap [j+1] for any j in the range 0 to n_coll).
Int Ai [nz] ; Input argument, not modified, of size nz = Ap En_coll.
The nonzero pattern (row indices) for column j is stored in
Ai [(Ap [j]) ... (Ap [j+1]1)]. The row indices in a given column j
must be in ascending order, and no duplicate row indices may be present.
Row indices must be in the range 0 to n_row1 (the matrix is Obased).
double Ax [nz] ; Input argument, not modified, of size nz = Ap En_coll.
double Az [nz] ; Input argument, not modified, for complex versions.
If present, these are the numerical values of the sparse matrix A.
The nonzero pattern (row indices) for column j is stored in
Ai [(Ap [j]) ... (Ap [j+l]1)], and the corresponding real numerical
values are stored in Ax [(Ap [j]) ... (Ap [j+1]1)]. The imaginary
values are stored in Az [(Ap [j]) ... (Ap [j+1]1)]. The values are
transposed only if Ax and Rx are present (for the real version), and
only if all four (Ax, Az, Rx, and Rz) are present for the complex
version. These are not an error conditions; you are able to transpose
and permute just the pattern of a matrix.
Future complex version: if Ax is present and Az is NULL, then both real
and imaginary parts will be contained in Ax[0..2*nz1], with Ax[2*k]
and Ax[2*k+l] being the real and imaginary part of the kth entry.
Int P [n_row] ; Input argument, not modified.
The permutation vector P is defined as P [k] = i, where the original
row i of A is the kth row of PAQ. If you want to use the identity
permutation for P, simply pass (Int *) NULL for P. This is not an error
condition. P is a complete permutation of all the rows of A; this
routine does not support the creation of a transposed submatrix of A
(R = A (1:3,:)' where A has more than 3 rows, for example, cannot be
done; a future version might support this operation).
Int Q [n_col] ; Input argument, not modified.
The permutation vector Q is defined as Q [k] = j, where the original
column j of A is the kth column of PAQ. If you want to use the identity
permutation for Q, simply pass (Int *) NULL for Q. This is not an error
condition. Q is a complete permutation of all the columns of A; this
routine does not support the creation of a transposed submatrix of A.
Int Rp [n_row+1] ; Output argument.
The column pointers of the matrix R = (A (P,Q))' or (A (P,Q)).', in the
same form as the column pointers Ap for the matrix A.
Int Ri [nz] ; Output argument.
The row indices of the matrix R = (A (P,Q))' or (A (P,Q)).' in the
same form as the row indices Ai for the matrix A.
double Rx [nz] ; Output argument.
double Rz [nz] ; Output argument, imaginary part for complex versions.
If present, these are the numerical values of the sparse matrix R,
in the same form as the values Ax and Az of the matrix A.
Future complex version: if Rx is present and Rz is NULL, then both real
and imaginary parts will be contained in Rx[0..2*nzl], with Rx[2*k]
and Rx[2*k+l] being the real and imaginary part of the kth entry.
Int do_conjugate ; Input argument for complex versions only.
If true, and if Ax, Az, Rx, and Rz are all present, then the linear
algebraic transpose is computed (complex conjugate). If false, the
array transpose is computed instead.
18.4 umfpack_*_scale
int umfpack_di_scale
(
double X [ ],
const double B [ ],
void *Numeric
long umfpackdlscale
(
double X [ ],
const double B [ ],
void *Numeric
int umfpack_zi_scale
double Xx [ ],
const double Bx [
void *Numeric
long umfpackzlscale
(
double Xx [ ],
const double Bx [
void *Numeric
double int Syntax:
#include "umfpack.h"
void *Numeric ;
double *B, *X ;
status = umfpack_di_
double Xz [ ],
], const double Bz [ ],
double Xz [ ],
], const double Bz [ ],
scale (X, B, Numeric)
double long Syntax:
#include "umfpack.h"
void *Numeric ;
double *B, *X ;
status = umfpack_dl_
scale (X, B, Numeric)
complex int Syntax:
#include "umfpack.h"
void *Numeric ;
double *Bx, *Bz, *Xx, *Xz
status = umfpackziscale (Xx, Xz, Bx, Bz, Numeric)
complex long Syntax:
#include "umfpack.h"
void *Numeric ;
double *Bx, *Bz, *Xx, *Xz
status = umfpackzlscale (Xx, Xz, Bx, Bz, Numeric)
Purpose:
Given LU factors computed by umfpack_*_numeric (PAQ=LU, PRAQ=LU, or
P(R\A)Q=LU), and a vector B, this routine computes X = B, X = R*B, or
X = R\B, as appropriate. X and B must be vectors equal in length to the
number of rows of A.
Returns:
The status code is returned. UMFPACK OK is returned if successful.
UMFPACK_ERROR_invalid_Numeric_object is returned in the Numeric
object is invalid. UMFPACK_ERROR_argument_missing is returned if
any of the input vectors are missing (X and B for the real version,
and Xx, Xz, Bx, and Bz for the complex version).
Arguments:
double X En_row] ; Output argument.
or:
double Xx En_row] ; Output argument, real part.
double Xz En_row] ; Output argument, imaginary part.
The output vector X.
double B En_row] ; Input argument, not modified.
or:
double Bx En_row] ; Input argument, not modified, real part.
double Bz En_row] ; Input argument, not modified, imaginary part.
The input vector B.
void *Numeric ;
Numeric must point to
umfpack_*_numeric.
Input argument, not modified.
a valid Numeric object, computed by
19 Getting the contents of opaque objects
19.1 umfpack_*_getlunz
int umfpack_di_get_lunz
int nz,
int *lnz,
int *unz,
int *n_row,
int *n_col,
int *nz_udiag,
void *Numeric
long umfpackdlgetlunz
(
long
long
long
long
long
void
*lnz,
*unz,
*n_row,
*n_col,
*nz_udiag,
*Numeric
int umfpack_zi_get_lunz
int nz,
int *unz,
int *unz,
int *n_row,
int *n_col,
int *nz_udiag,
void *Numeric
long umfpackzlgetlunz
long
long
long
long
long
void
*lnz,
*unz,
*n_row,
*n_col,
*nz_udiag,
*Numeric
double int Syntax:
#include "umfpack.h"
void *Numeric ;
int status, Inz, unz, n_row, n_col
status = umfpack_di_get_lunz (&lnz, &unz, &n_row, &n_col, Numeric)
double long Syntax:
#include "umfpack.h"
void *Numeric ;
long status, Inz, unz, n_row, n_col ;
status = umfpack_dl_get_lunz (&lnz, &unz, &n_row, &n_col, Numeric)
complex int Syntax:
#include "umfpack.h"
void *Numeric ;
int status, Inz, unz, n_row, n_col
status = umfpack_zi_get_lunz (&lnz, &unz, &n_row, &n_col, Numeric)
complex long Syntax:
#include "umfpack.h"
void *Numeric ;
long status, Inz, unz, n_row, n_col ;
status = umfpack_zl_get_lunz (&lnz, &unz, &n_row, &n_col, Numeric)
Purpose:
Determines the size and number of nonzeros in the LU factors held by the
Numeric object. These are also the sizes of the output arrays required
by umfpack_*_get_numeric.
The matrix L is n_row by min(n_row,n_col), with Inz nonzeros, including
the entries on the unit diagonal of L.
The matrix U is min(n_row,n_col) by n_col, with unz nonzeros, including
nonzeros on the diagonal of U.
Returns:
UMFPACK OK if successful.
UMFPACK_ERROR_invalid_Numeric_object if Numeric is not a valid object.
UMFPACK_ERROR_argument_missing if any other argument is (Int *) NULL.
Arguments:
Int *lnz ; Output argument.
The number of nonzeros in L, including the diagonal (which is all
one's). This value is the required size of the Lj and Lx arrays as
computed by umfpack_*_get_numeric. The value of Inz is identical to
Info [UMFPACK_LNZ], if that value was returned by umfpack_*_numeric.
Int *unz ; Output argument.
The number of nonzeros in U, including the diagonal. This value is the
required size of the Ui and Ux arrays as computed by
umfpack_*_get_numeric. The value of unz is identical to
Info [UMFPACK_UNZ], if that value was returned by umfpack_*_numeric.
Int *n_row ; Output argument.
Int *n_col ; Output argument.
The order of the L and U matrices. L is n_row by min(n_row,n_col)
and U is min(n_row,n_col) by n_col.
Int *nz_udiag ; Output argument.
The number of numerically nonzero values on the diagonal of U. The
matrix is singular if nz_diag < min(n_row,n_col). A dividebyzero
will occur if nz_diag < n_row == n_col when solving a sparse system
involving the matrix U in umfpack_*_*solve. The value of nz_udiag is
identical to Info [UMFPACK_UDIAG_NZ] if that value was returned by
umfpack_*_numeric.
void *Numeric ; Input argument, not modified.
Numeric must point to a valid Numeric object, computed by
umfpack_*_numeric.
19.2 umfpack_*_getnumeric
int umfpack_di_get_numeric
int Lp [ ],
int Lj [ ],
double Lx [ ],
int Up [ ],
int Ui [ ],
double Ux [ ],
int P [ ],
int [ ],
double Dx [ ],
int *do_recip,
double Rs [ ],
void *Numeric
long umfpack_dl_get_numeric
long Lp [ ],
long Lj [ ],
double Lx [ ],
long Up [ ],
long Ui [ ],
double Ux [ ],
long P [ ],
long Q [ ],
double Dx [ ],
long *do_recip,
double Rs [ ],
void *Numeric
int umfpack_zi_get_numeric
int Lp [ ],
int Lj [ ],
double Lx [ ],
int Up [ ],
int Ui [ ],
double Ux [ ],
int P [ ],
int [ ],
double Dx [ ],
int *do_recip,
double Rs [ ],
void *Numeric
double Lz [ ],
double Uz [ ],
double Dz [ ],
long umfpack_zl_get_numeric
(
long Lp [ ],
long Lj [ ],
double Lx [ ],
long Up [ ],
long Ui [ ],
double Lz [ ],
double Ux [ ], double Uz [ ],
long P [ ],
long Q [ ],
double Dx [ ], double Dz [ ],
long *do_recip,
double Rs [ ],
void *Numeric
);
double int Syntax:
#include "umfpack.h"
void *Numeric ;
int *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ;
double *Lx, *Ux, *Dx, *Rs ;
status = umfpack_di_get_numeric (Lp, Lj, Lx, Up, Ui, Ux, P, Q, Dx,
&do_recip, Rs, Numeric)
double long Syntax:
#include "umfpack.h"
void *Numeric ;
long *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ;
double *Lx, *Ux, *Dx, *Rs ;
status = umfpack_dl_get_numeric (Lp, Lj, Lx, Up, Ui, Ux, P, Q, Dx,
&do_recip, Rs, Numeric)
complex int Syntax:
#include "umfpack.h"
void *Numeric ;
int *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ;
double *Lx, *Lz, *Ux, *Uz, *Dx, *Dz, *Rs ;
status = umfpack_zi_get_numeric (Lp, Lj, Lx, Lz, Up, Ui, Ux, Uz, P, Q,
Dx, Dz, &do_recip, Rs, Numeric)
complex long Syntax:
#include "umfpack.h"
void *Numeric ;
long *Lp, *Lj, *Up, *Ui, *P, *Q, status, do_recip ;
double *Lx, *Lz, *Ux, *Uz, *Dx, *Dz, *Rs ;
status = umfpack_zl_get_numeric (Lp, Lj, Lx, Lz, Up, Ui, Ux, Uz, P, Q,
Dx, Dz, &do_recip, Rs, Numeric)
Purpose:
This routine copies the LU factors and permutation vectors from the Numeric
object into useraccessible arrays. This routine is not needed to solve a
linear system. Note that the output arrays Lp, Lj, Lx, Up, Ui, Ux, P, Q,
Dx, and Rs are not allocated by umfpack_*_get_numeric; they must exist on
input. Similarly, Lz, Uz and Dz must exist on input for the complex
versions.
All output arguments are optional. If any of them are NULL
on input, then that part of the LU factorization is not copied. You can
use this routine to extract just the parts of the LU factorization that
you want. For example, to retrieve just the column permutation Q, use:
#define noD (double *) NULL
#define nol (int *) NULL
status = umfpack_di_get_numeric (noI, nol, noD, nol, nol, noD, nol,
Q, noD, nol, noD, Numeric)
Returns:
Returns UMFPACK_OK if successful. Returns UMFPACK_ERROR_out_ofmemory
if insufficient memory is available for the 2*max(n_row,n_col) integer
workspace that umfpack_*_get_numeric allocates to construct L and/or U.
Returns UMFPACK_ERROR_invalid_Numeric_object if the Numeric object provided
as input is invalid.
Arguments:
Int Lp [n_row+1] ; Output argument.
Int Lj [inz] ; Output argument.
double Lx [inz] ; Output argument.
double Lz [inz] ; Output argument for complex versions.
The n_rowbymin(n_row,n_col) matrix L is returned in compressedrow
form. The column indices of row i and corresponding numerical values
are in:
Lj [Lp [i] ... Lp [i+l]1]
Lx [Lp [i] ... Lp [i+l]1] real part
Lz [Lp [i] ... Lp [i+l]1] imaginary part (complex versions)
respectively. Each row is stored in sorted order, from low column
indices to higher. The last entry in each row is the diagonal, which
is numerically equal to one. The sizes of Lp, Lj, Lx, and Lz are
returned by umfpack_*_get_lunz. If Lp, Lj, or Ux (or Uz for the
complex version) are not present, then the matrix L is not returned.
This is not an error condition. The L matrix can be printed if n_row,
Lp, Lj, Lx (and Lz for the complex versions) are passed to
umfpack_*_report_matrix (using the "row" form).
Future complex version: if Lx is present and Lz is NULL, then both real
and imaginary parts will be returned in Lx[O..2*lnzl], with Lx[2*k]
and Lx[2*k+l] being the real and imaginary part of the kth entry.
Int Up [n_col+1] ; Output argument.
Int Ui [unz] ; Output argument.
double Ux [unz] ; Output argument.
double Uz [unz] ; Output argument for complex versions.
The min(n_row,n_col)byn_col matrix U is returned in compressedcolumn
form. The row indices of column j and corresponding numerical values
are in
Ui [Up [j] ... Up [j+1]1]
Ux [Up [j] ... Up [j+1]1] real part
Uz [Up [j] ... Up [j+1]1] imaginary part (complex versions)
respectively. Each column is stored in sorted order, from low row
indices to higher. The last entry in each column is the diagonal
(assuming that it is nonzero). The sizes of Up, Ui, Ux, and Uz are
returned by umfpack_*_get_lunz. If Up, Ui, or Ux (or Uz for the complex
version) are not present, then the matrix U is not returned. This is
not an error condition. The U matrix can be printed if n_col, Up, Ui,
Ux (and Uz for the complex versions) are passed to
umfpack_*_report_matrix (using the "column" form).
Future complex version: if Ux is present and Uz is NULL, then both real
and imaginary parts will be returned in Ux[0..2*unzl], with Ux[2*k]
and Ux[2*k+l] being the real and imaginary part of the kth entry.
Int P En_row] ; Output argument.
The permutation vector P is defined as P [k] = i, where the original
row i of A is the kth pivot row in PAQ. If you do not want the P vector
to be returned, simply pass (Int *) NULL for P. This is not an error
condition. You can print P and Q with umfpack_*_report_perm.
Int Q En_col] ; Output argument.
The permutation vector Q is defined as Q [k] = j, where the original
column j of A is the kth pivot column in PAQ. If you not want the Q
vector to be returned, simply pass (Int *) NULL for Q. This is not
an error condition. Note that Q is not necessarily identical to
Qtree, the column preordering held in the Symbolic object. Refer to
the description of Qtree and Front_npivcol in umfpack_*_get_symbolic for
details.
double Dx [min(n_row,n_col)] ; Output argument.
double Dz [min(n_row,n_col)] ; Output argument for complex versions.
The diagonal of U is also returned in Dx and Dz. You can extract the
diagonal of U without getting all of U by passing a nonNULL Dx (and
Dz for the complex version) and passing Up, Ui, and Ux as NULL. Dx is
the real part of the diagonal, and Dz is the imaginary part.
Future complex version: if Dx is present and Dz is NULL, then both real
and imaginary parts will be returned in Dx[O..2*min(n_row,n_col)1],
with Dx[2*k] and Dx[2*k+l] being the real and imaginary part of the kth
entry.
Int *do_recip ; Output argument.
If do_recip is returned as zero (false), then the scale factors Rs [i]
are to be used by multiplying row i by Rs [i]. Otherwise, the entries
in row i are to be divided by Rs [i].
If UMFPACK has been compiled with gcc, or for MATLAB as either a
builtin routine or as a mexFunction, then the NRECIPROCAL flag is
set, and do_recip will always be zero (false).
NOTE: this argument is new to version 4.1.
double Rs [n_row] ; Output argument.
The row scale factors are returned in Rs [O..n_row1]. Row i of A is
scaled by dividing or multiplying its values by Rs [i]. If default
scaling is in use, Rs [i] is the sum of the absolute values of row i
(or its reciprocal). If max row scaling is in use, then Rs [i] is the
maximum absolute value in row i (or its reciprocal).
Otherwise, Rs [i] = 1. If row i is all zero, Rs [i] = 1 as well. For
the complex version, an approximate absolute value is used
(Ix_reall+Ix_imagl).
NOTE: this argument is new to version 4.1.
void *Numeric ; Input argument, not modified.
Numeric must point to a valid Numeric object, computed by
umfpack_*_numeric.
19.3 umfpack_*_getsymbolic
int umfpack_di_get_symbolic
int *n_row,
int *n_col,
int *nl,
int *nz,
int *nfr,
int *nchains,
int P [ ],
int Q [ ],
int Front_npivcol [ ],
int Front_parent [ ],
int Front_1strow [ ],
int Front_leftmostdesc [ ],
int Chain_start [ ],
int Chain_maxrows [ ],
int Chain_maxcols [ ],
void *Symbolic
long umfpack_dl_get_symbolic
long *n_row,
long *n_col,
long *nl,
long *nz,
long *nfr,
long *nchains,
long P [ ],
long Q [ ],
long Front_npivcol [ ],
long Front_parent [ ],
long Front_1strow [ ],
long Front_leftmostdesc [ ],
long Chain_start [ ],
long Chain_maxrows [ ],
long Chain_maxcols [ ],
void *Symbolic
umfpack_zi_get_symbolic
int *n_row,
int *n_col,
int *nl,
int *nz,
int *nfr,
int *nchains,
int P [ ],
int Q [ ],
int Front_npivcol [ ],
int Front_parent [ ],
int Front_1strow [ ],
int Front_leftmostdesc [ ],
int Chainstart [ ],
int Chain_maxrows [ ],
int Chain_maxcols [ ],
void *Symbolic
long umfpack_zl_get_symbolic
long *n_row,
long *n_col,
long *nl,
long *nz,
long *nfr,
long *nchains,
long P [ ],
long Q [ ],
long Front_npivcol [ ],
long Front_parent [ ],
long Front_1strow [ ],
long Front_leftmostdesc [ ],
long Chain_start [ ],
long Chain_maxrows [ ],
long Chain_maxcols [ ],
void *Symbolic
double int Syntax:
#include "umfpack.h"
int status, n_row, n_col, nz, nfr, nchains, *P, *Q,
*Front_npivcol, *Front_parent, *Front_1strow, *Front_leftmostdesc,
*Chain_start, *Chain_maxrows, *Chain_maxcols ;
void *Symbolic ;
status = umfpack_di_get_symbolic (&n_row, &n_col, &nz, &nfr, &nchains,
P, Q, Front_npivcol, Front_parent, Front_1strow,
Front_leftmostdesc, Chain_start, Chain_maxrows, Chain_maxcols,
Symbolic) ;
double long Syntax:
#include "umfpack.h"
long status, n_row, n_col, nz, nfr, nchains, *P, *Q,
*Front_npivcol, *Front_parent, *Front_1strow, *Front_leftmostdesc,
*Chain_start, *Chain_maxrows, *Chain_maxcols ;
void *Symbolic ;
status = umfpack_dl_get_symbolic (&n_row, &n_col, &nz, &nfr, &nchains,
P, Q, Front_npivcol, Front_parent, Front_1strow,
Front_leftmostdesc, Chain_start, Chain_maxrows, Chain_maxcols,
Symbolic) ;
complex int Syntax:
#include "umfpack.h"
int status, n_row, n_col, nz, nfr, nchains, *P, *Q,
*Front_npivcol, *Front_parent, *Front_1strow, *Front_leftmostdesc,
*Chain_start, *Chain_maxrows, *Chain_maxcols ;
void *Symbolic ;
status = umfpack_zi_get_symbolic (&n_row, &n_col, &nz, &nfr, &nchains,
P, Q, Front_npivcol, Front_parent, Front_1strow,
Front_leftmostdesc, Chain_start, Chain_maxrows, Chain_maxcols,
Symbolic) ;
complex long Syntax:
#include "umfpack.h"
long status, n_row, n_col, nz, nfr, nchains, *P, *Q,
*Front_npivcol, *Front_parent, *Front_1strow, *Front_leftmostdesc,
*Chain_start, *Chain_maxrows, *Chain_maxcols ;
void *Symbolic ;
status = umfpack_zl_get_symbolic (&n_row, &n_col, &nz, &nfr, &nchains,
P, Q, Front_npivcol, Front_parent, Front_1strow,
Front_leftmostdesc, Chain_start, Chain_maxrows, Chain_maxcols,
Symbolic)
Purpose:
Copies the contents of the Symbolic object into simple integer arrays
accessible to the user. This routine is not needed to factorize and/or
solve a sparse linear system using UMFPACK. Note that the output arrays
P, Q, Front_npivcol, Front_parent, Front_1strow, Front_leftmostdesc,
Chain_start, Chain_maxrows, and Chain_maxcols are not allocated by
umfpack_*_get_symbolic; they must exist on input.
All output arguments are optional. If any of them are NULL
on input, then that part of the symbolic analysis is not copied. You can
use this routine to extract just the parts of the symbolic analysis that
you want. For example, to retrieve just the column permutation Q, use:
#define nol (int *) NULL
status = umfpack_di_get_symbolic (nol, nol, nol, nol, nol, nol, nol,
Q, nol, nol, nol, nol, nol, nol, nol, Symbolic) ;
The only required argument the last one, the pointer to the Symbolic object.
The Symbolic object is small. Its size for an nbyn square matrix varies
from 4*n to 13*n, depending on the matrix. The object holds the initial
column permutation, the supernodal column elimination tree, and information
about each frontal matrix. You can print it with umfpack_*_report_symbolic.
Returns:
Returns UMFPACK_OK if successful, UMFPACK_ERROR_invalid_Symbolic_object
if Symbolic is an invalid object.
Arguments:
Int *n_row ; Output argument.
Int *n_col ; Output argument.
The dimensions of the matrix A analyzed by the call to
umfpack_*_symbolic that generated the Symbolic object.
Int *nl ; Output argument.
The number of pivots with zero Markowitz cost (they have just one entry
in the pivot row, or the pivot column, or both). These appear first in
the output permutations P and Q.
NOTE: this argument is new to version 4.1.
Int *nz ; Output argument.
The number of nonzeros in A.
Int *nfr ; Output argument.
The number of frontal matrices that will be used by umfpack_*_numeric
to factorize the matrix A. It is in the range 0 to n_col.
Int *nchains ; Output argument.
The frontal matrices are related to one another by the supernodal
column elimination tree. Each node in this tree is one frontal matrix.
The tree is partitioned into a set of disjoint paths, and a frontal
matrix chain is one path in this tree. Each chain is factorized using
a unifrontal technique, with a single working array that holds each
frontal matrix in the chain, one at a time. nchains is in the range
0 to nfr.
Int P [n_row] ; Output argument.
The initial row permutation. If P [k] = i, then this means that
row i is the kth row in the preordered matrix. In general, this P is
not the same as the final row permutation computed by umfpack_*_numeric.
For the unsymmetric strategy, P defines the rowmerge order. Let j be
the column index of the leftmost nonzero entry in row i of A*Q. Then
P defines a sort of the rows according to this value. A row can appear
earlier in this ordering if it is aggressively absorbed before it can
become a pivot row. If P [k] = i, row i typically will not be the kth
pivot row.
For the symmetric strategy, P = Q. For the 2by2 strategy, P is the
row permutation that places large entries on the diagonal of P*A*Q.
If no pivoting occurs during numerical factorization, P [k] = i also
defines the final permutation of umfpack_*_numeric, for either the
symmetric or 2by2 strategies.
Int Q [n_col] ; Output argument.
The initial column permutation. If Q [k] = j, then this means that
column j is the kth pivot column in the preordered matrix. Q is
not necessarily the same as the final column permutation Q, computed by
umfpack_*_numeric. The numeric factorization may reorder the pivot
columns within each frontal matrix to reduce fillin. If the matrix is
structurally singular, and if the symmetric or 2by2 strategies or
used (or if Control [UMFPACK_FIXQ] > 0), then this Q will be the same
as the final column permutation computed in umfpack_*_numeric.
Int Front_npivcol [n_col+1] ; Output argument.
This array should be of size at least n_col+1, in order to guarantee
that it will be large enough to hold the output. Only the first nfr+1
entries are used, however.
The kth frontal matrix holds Front_npivcol [k] pivot columns. Thus, the
first frontal matrix, front 0, is used to factorize the first
Front_npivcol [0] columns; these correspond to the original columns
Q [0] through Q [Front_npivcol [0]1]. The next frontal matrix
is used to factorize the next Front_npivcol [1] columns, which are thus
the original columns Q [Front_npivcol [0]] through
Q [Front_npivcol [0] + Front_npivcol [1] 1], and so on. Columns
with no entries at all are put in a placeholder "front",
Front_npivcol [nfr]. The sum of Front_npivcol [0..nfr] is equal to
n col.
Any modifications that umfpack_*_numeric makes to the initial column
permutation are constrained to within each frontal matrix. Thus, for
the first frontal matrix, Q [01 through Q [Front_npivcol [0]1] is some
permutation of the columns Q [0] through
Q [Front_npivcol [0]1]. For second frontal matrix,
Q [Front_npivcol [0]] through Q [Front_npivcol [0] + Front_npivcol[1]1]
is some permutation of the same portion of Q, and so on. All pivot
columns are numerically factorized within the frontal matrix originally
determined by the symbolic factorization; there is no delayed pivoting
across frontal matrices.
Int Front_parent [n_col+l] ; Output argument.
This array should be of size at least n_col+l, in order to guarantee
that it will be large enough to hold the output. Only the first nfr+l
entries are used, however.
Front_parent [0..nfr] holds the supernodal column elimination tree
(including the placeholder front nfr, which may be empty). Each node in
the tree corresponds to a single frontal matrix. The parent of node f
is Front_parent [f].
Int Front_1strow [n_col+l] ; Output argument.
This array should be of size at least n_col+l, in order to guarantee
that it will be large enough to hold the output. Only the first nfr+l
entries are used, however.
Front_1strow [k] is the row index of the first row in A (P,Q)
whose leftmost entry is in a pivot column for the kth front. This is
necessary only to properly factorize singular matrices. It is new to
Version 4.0. Rows in the range Front_1strow [k] to
Front_1strow [k+l]l first become pivot row candidates at the kth front.
Any rows not eliminated in the kth front may be selected as pivot rows
in the parent of k (Front_parent [k]) and so on up the tree.
Int Front_leftmostdesc [n_col+l] ; Output argument.
This array should be of size at least n_col+l, in order to guarantee
that it will be large enough to hold the output. Only the first nfr+l
entries are used, however.
Front_leftmostdesc [k] is the leftmost descendant of front k, or k
if the front has no children in the tree. Since the rows and columns
(P and Q) have been postordered via a depthfirstsearch of
the tree, rows in the range Front_1strow [Front_leftmostdesc [k]] to
Front_1strow [k+l]l form the entire set of candidate pivot rows for
the kth front (some of these will typically have already been selected
by fronts in the range Front_leftmostdesc [k] to front k1, before
the factorization reaches front k).
Chain_start [n_col+1] ;
This array should be of size at least n_col+l, in order to guarantee
that it will be large enough to hold the output. Only the first
nchains+1 entries are used, however.
The kth frontal matrix chain consists of frontal matrices Chain_start[k]
through Chain_start [k+l]1. Thus, Chain_start [0] is always 0, and
Chain_start [nchains] is the total number of frontal matrices, nfr. For
two adjacent fronts f and f+1 within a single chain, f+1 is always the
parent of f (that is, Front_parent [f] = f+1).
Int Chain_maxrows En_col+l] ; Output argument.
Int Chain_maxcols En_col+1] ; Output argument.
These arrays should be of size at least n_col+l, in order to guarantee
that they will be large enough to hold the output. Only the first
nchains entries are used, however.
The kth frontal matrix chain requires a single working array of
dimension Chain_maxrows [k] by Chain_maxcols [k], for the unifrontal
technique that factorizes the frontal matrix chain. Since the symbolic
factorization only provides an upper bound on the size of each frontal
matrix, not all of the working array is necessarily used during the
numerical factorization.
Note that the upper bound on the number of rows and columns of each
frontal matrix is computed by umfpack_*_symbolic, but all that is
required by umfpack_*_numeric is the maximum of these two sets of
values for each frontal matrix chain. Thus, the size of each
individual frontal matrix is not preserved in the Symbolic object.
void *Symbolic ; Input argument, not modified.
The Symbolic object, which holds the symbolic factorization computed by
umfpack_*_symbolic. The Symbolic object is not modified by
umfpack_*_get_symbolic.
Output argument.
19.4 umfpack_*_savenumeric
int umfpack_di_save_numeric
(
void *Numeric,
char *filename
long umfpackdlsave_numeric
(
void *Numeric,
char *filename
int umfpack_zi_save_numeric
(
void *Numeric,
char *filename
long umfpackzlsave_numeric
(
void *Numeric,
char *filename
double int Syntax:
#include "umfpack.h"
int status ;
char *filename
void *Numeric
status = umfpack_di_save
numeric (Numeric, filename)
double long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Numeric ;
status = umfpack_dl_save.
numeric (Numeric, filename)
complex int Syntax:
#include "umfpack.h"
int status ;
char *filename ;
void *Numeric
status = umfpack_zi_save.
numeric (Numeric, filename)
complex long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Numeric
status = umfpack_zl_save
numeric (Numeric, filename)
Purpose:
Saves a Numeric object to a file, which can later be read by
umfpack_*_load_numeric. The Numeric object is not modified. You need
to call umfpack_*_free_numeric if you to delete the Numeric object after
saving it to a file.
Returns:
UMFPACK OK if successful.
UMFPACK_ERROR_invalid_Numeric_object if Numeric is not valid.
UMFPACK_ERROR_file_IO if an I/O error occurred.
Arguments:
void *Numeric ;
Input argument, not modified.
Numeric must point to a valid Numeric object, computed by
umfpack_*_numeric or loaded by umfpack_*_load_numeric.
char *filename ;
Input argument, not modified.
A string that contains the filename to which the Numeric
object is written.
19.5 umfpack_*_loadnumeric
int umfpack_di_load_numeric
(
void **Numeric,
char *filename
long umfpackdlload_numeric
(
void **Numeric,
char *filename
int umfpack_zi_load_numeric
(
void **Numeric,
char *filename
long umfpackzlload_numeric
(
void **Numeric,
char *filename
double int Syntax:
#include "umfpack.h"
int status ;
char *filename
void *Numeric
status = umfpackdiloadnumeric (&Numeric, filename)
double long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Numeric ;
status = umfpackdlloadnumeric (&Numeric, filename)
complex int Syntax:
#include "umfpack.h"
int status ;
char *filename ;
void *Numeric
status = umfpackziloadnumeric (&Numeric, filename)
complex long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Numeric
status = umfpackzlloadnumeric (&Numeric, filename)
Purpose:
Loads a Numeric object from a file created by umfpack_ save_numeric. The
Numeric handle passed to this routine is overwritten with the new object.
If that object exists prior to calling this routine, a memory leak will
occur. The contents of Numeric are ignored on input.
Returns:
UMFPACK OK if successful.
UMFPACK_ERRORoutofmemory if not enough memory is available.
UMFPACK_ERROR_file_IO if an I/O error occurred.
Arguments:
void **Numeric ; Output argument.
**Numeric is the address of a (void *) pointer variable in the user's
calling routine (see Syntax, above). On input, the contents of this
variable are not defined. On output, this variable holds a (void *)
pointer to the Numeric object (if successful), or (void *) NULL if
a failure occurred.
char *filename ; Input argument, not modified.
A string that contains the filename from which to read the Numeric
object.
19.6 umfpack_*_savesymbolic
int umfpack_di_save_symbolic
void *Symbolic,
char *filename
long umfpackdlsave_symbolic
void *Symbolic,
char *filename
int umfpack_zi_save_symbolic
void *Symbolic,
char *filename
long umfpackzlsave_symbolic
void *Symbolic,
char *filename
double int Syntax:
#include "umfpack.h"
int status ;
char *filename
void *Symbolic ;
status = umfpack_di_save_
symbolic (Symbolic, filename)
double long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Symbolic ;
status = umfpack_dl_save
symbolic (Symbolic, filename)
complex int Syntax:
#include "umfpack.h"
int status ;
char *filename ;
void *Symbolic ;
status = umfpack_zi_save_
symbolic (Symbolic, filename)
complex long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Symbolic ;
status = umfpack_zl_save
symbolic (Symbolic, filename)
Purpose:
Saves a Symbolic object to a file, which can later be read by
umfpack_*_load_symbolic. The Symbolic object is not modified. You need
to call umfpack_*_free_symbolic if you to delete the Symbolic object after
saving it to a file.
Returns:
UMFPACK OK if successful.
UMFPACK_ERROR_invalid_Symbolic_object if Symbolic is not valid.
UMFPACK_ERROR_file_IO if an I/O error occurred.
Arguments:
void *Symbolic ;
Input argument, not modified.
Symbolic must point to a valid Symbolic object, computed by
umfpack_*_symbolic or loaded by umfpack_*_load_symbolic.
char *filename ;
Input argument, not modified.
A string that contains the filename to which the Symbolic
object is written.
19.7 umfpack_*_loadsymbolic
int umfpack_di_load_symbolic
(
void **Symbolic,
char *filename
);
long umfpackdlload_symbolic
(
void **Symbolic,
char *filename
);
int umfpack_zi_load_symbolic
(
void **Symbolic,
char *filename
);
long umfpackzlload_symbolic
(
void **Symbolic,
char *filename
);
double int Syntax:
#include "umfpack.h"
int status ;
char *filename
void *Symbolic ;
status = umfpack_di_load_symbolic (&Symbolic, filename)
double long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Symbolic ;
status = umfpack_dl_load_symbolic (&Symbolic, filename)
complex int Syntax:
#include "umfpack.h"
int status ;
char *filename ;
void *Symbolic ;
status = umfpack_zi_load_symbolic (&Symbolic, filename)
complex long Syntax:
#include "umfpack.h"
long status ;
char *filename
void *Symbolic ;
status = umfpack_zl_load_symbolic (&Symbolic, filename)

