1function umfpack_details
2%UMFPACK_DETAILS details on all the options for using umfpack in MATLAB
3%
4% Factor or solve a sparse linear system, returning either the solution x to
5% Ax=b or A'x'=b', the factorization LU=PAQ, or LU=P(R\A)Q.  A must be sparse.
6% For the solve, A must be square and b must be a dense n-by-1 vector.  For LU
7% factorization, A can be rectangular.  In both cases, A and/or b can be real
8% or complex.
9%
10% UMFPACK analyzes the matrix and selects one of three strategies to factorize
11% the matrix.  It first finds a set of k initial pivot entries of zero Markowitz
12% cost.  This forms the first k rows and columns of L and U.  The remaining
13% submatrix S is then analyzed, based on the symmetry of the nonzero pattern of
14% the submatrix and the values on the diagaonal.  The strategies include:
15%
16%       (1) unsymmetric:  use a COLAMD pre-ordering, a column elimination tree
17%           post-ordering, refine the column ordering during factorization,
18%           and make no effort at selecting pivots on the diagonal.
19%       (2) 2-by-2:  like the symmetric strategy (see below), except that local
20%           row permutations are first made to attempt to place large entries
21%           on the diagonal.
22%       (3) symmetric:  use an AMD pre-ordering on the matrix S+S', an
23%           elimination tree post-ordering, do not refine the column ordering
24%           during factorization, and attempt to select pivots on the diagonal.
25%
26% Each of the following uses of umfpack (except for "Control = umfpack") is
27% stand-alone.  That is, no call to umfpack is required for any subsequent
28% call.  In each usage, the Info output argument is optional.
29%
30% Example:
31%
32% [x, Info] = umfpack (A, '\', b) ;
33% [x, Info] = umfpack (A, '\', b, Control) ;
34% [x, Info] = umfpack (A, Qinit, '\', b, Control) ;
35% [x, Info] = umfpack (A, Qinit, '\', b) ;
36%
37%       Solves Ax=b (similar to x = A\b in MATLAB).
38%
39% [x, Info] = umfpack (b, '/', A) ;
40% [x, Info] = umfpack (b, '/', A, Control) ;
41% [x, Info] = umfpack (b, '/', A, Qinit) ;
42% [x, Info] = umfpack (b, '/', A, Qinit, Control) ;
43%
44%       Solves A'x'=b' (similar to x = b/A in MATLAB).
45%
46% [L, U, P, Q, R, Info] = umfpack (A) ;
47% [L, U, P, Q, R, Info] = umfpack (A, Control) ;
48% [L, U, P, Q, R, Info] = umfpack (A, Qinit) ;
49% [L, U, P, Q, R, Info] = umfpack (A, Qinit, Control) ;
50%
51%       Returns the LU factorization of A.  P and Q are returned as permutation
52%       matrices.  R is a diagonal sparse matrix of scale factors for the rows
53%       of A, L is lower triangular, and U is upper triangular.  The
54%       factorization is L*U = P*(R\A)*Q.  You can turn off scaling by setting
55%       Control (17) to zero (in which case R = speye (m)), or by using the
56%       following syntaxes (in which case Control (17) is ignored):
57%
58% [L, U, P, Q] = umfpack (A) ;
59% [L, U, P, Q] = umfpack (A, Control) ;
60% [L, U, P, Q] = umfpack (A, Qinit) ;
61% [L, U, P, Q] = umfpack (A, Qinit, Control) ;
62%
63%       Same as above, except that no row scaling is performed.  The Info array
64%       is not returned, either.
65%
66% [P1, Q1, Fr, Ch, Info] = umfpack (A, 'symbolic') ;
67% [P1, Q1, Fr, Ch, Info] = umfpack (A, 'symbolic', Control) ;
68% [P1, Q1, Fr, Ch, Info] = umfpack (A, Qinit, 'symbolic') ;
69% [P1, Q1, Fr, Ch, Info] = umfpack (A, Qinit, 'symbolic', Control);
70%
71%       Performs only the fill-reducing column pre-ordering (including the
72%       elimination tree post-ordering) and symbolic factorization.  Q1 is the
73%       initial column permutation (either from colamd, amd, or the input
74%       ordering Qinit), possibly followed by a column elimination tree post-
75%       ordering or a symmetric elimination tree post-ordering, depending on
76%       the strategy used.
77%
78%       For the unsymmetric strategy, P1 is the row ordering induced by Q1
79%       (row-merge order). For the 2-by-2 strategy, P1 is the row ordering that
80%       places large entries on the diagonal of P1*A*Q1.  For the symmetric
81%       strategy, P1 = Q1.
82%
83%       Fr is a (nfr+1)-by-4 array containing information about each frontal
84%       matrix, where nfr <= n is the number of frontal matrices.  Fr (:,1) is
85%       the number of pivot columns in each front, and Fr (:,2) is the parent
86%       of each front in the supercolumn elimination tree.  Fr (k,2) is zero if
87%       k is a root.  The first Fr (1,1) columns of P1*A*Q1 are the pivot
88%       columns for the first front, the next Fr (2,1) columns of P1*A*Q1
89%       are the pivot columns for the second front, and so on.
90%
91%       For the unsymmetric strategy, Fr (:,3) is the row index of the first
92%       row in P1*A*Q1 whose leftmost nonzero entry is in a pivot column for
93%       the kth front.  Fr (:,4) is the leftmost descendent of the kth front.
94%       Rows in the range Fr (Fr (k,4),3) to Fr (k+1,3)-1 form the entire set
95%       of candidate pivot rows for the kth front (some of these will typically
96%       have been selected as pivot rows of fronts Fr (k,3) to k-1, before the
97%       factorization reaches the kth front.  If front k is a leaf node, then
98%       Fr (k,4) is k.
99%
100%       Ch is a (nchains+1)-by-3 array containing information about each "chain"
101%       (unifrontal sequence) of frontal matrices, and where nchains <= nfr
102%       is the number of chains.  The ith chain consists of frontal matrices.
103%       Chain (i,1) to Chain (i+1,1)-1, and the largest front in chain i is
104%       Chain (i,2)-by-Chain (i,3).
105%
106%       This use of umfpack is not required to factor or solve a linear system
107%       in MATLAB.  It analyzes the matrix A and provides information only.
108%       The MATLAB statement "treeplot (Fr (:,2)')" plots the column elimination
109%       tree.
110%
111% Control = umfpack ;
112%
113%       Returns a struct of default parameter settings for umfpack.
114%
115% umfpack_report (Control, Info) ;
116%
117%       Prints the current Control settings, and Info
118%
119% det = umfpack (A, 'det') ;
120% [det dexp] = umfpack (A, 'det') ;
121%
122%       Computes the determinant of A.  The 2nd form returns the determinant
123%       in the form det*10^dexp, where det is in the range +/- 1 to 10,
124%       which helps to avoid overflow/underflow when dexp is out of range of
125%       normal floating-point numbers.
126%
127% If present, Qinit is a user-supplied 1-by-n permutation vector.  It is an
128% initial fill-reducing column pre-ordering for A; if not present, then colamd
129% or amd are used instead.  If present, Control is a user-supplied struct.
130% Control and Info are optional; if Control is not present, defaults
131% are used.  If a Control entry is NaN, then the default is used for that entry.
132%
133%
134% Copyright 1995-2012 by Timothy A. Davis, http://www.suitesparse.com
135% All Rights Reserved.
136% UMFPACK is available under alternate licenses, contact T. Davis for details.
137%
138% UMFPACK License: see UMFPACK/Doc/License.txt for the license.
139%
140% Availability: http://www.suitesparse.com
141%
142% See also umfpack, umfpack_make, umfpack_report,
143%    umfpack_demo, and umfpack_simple.
144
145more on
146help umfpack_details
147more off
148
149