Mercurial > octave-nkf

comparison liboctave/UMFPACK/UMFPACK/MATLAB/umfpack_details.m @ 5164:57077d0ddc8e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[project @ 2005-02-25 19:55:24 by jwe]
author jwe
date Fri, 25 Feb 2005 19:55:28 +0000
parents
children
comparison
equal deleted inserted replaced
5163:9f3299378193 5164:57077d0ddc8e
1 function [out1, out2, out3, out4, out5] = umfpack (in1, in2, in3, in4, in5)
2 % UMFPACK v4.4: details on each usage.
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 % Usage:
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 20-by-1 vector 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 20-by-1
130 % array. 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 % UMFPACK Version 4.4, Copyright (c) 2005 by Timothy A. Davis.
135 % All Rights Reserved. Type umfpack_details for License.
136 %
137 % UMFPACK License:
138 %
139 % Your use or distribution of UMFPACK or any modified version of
140 % UMFPACK implies that you agree to this License.
141 %
142 % THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY
143 % EXPRESSED OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
144 %
145 % Permission is hereby granted to use or copy this program, provided
146 % that the Copyright, this License, and the Availability of the original
147 % version is retained on all copies. User documentation of any code that
148 % uses UMFPACK or any modified version of UMFPACK code must cite the
149 % Copyright, this License, the Availability note, and "Used by permission."
150 % Permission to modify the code and to distribute modified code is granted,
151 % provided the Copyright, this License, and the Availability note are
152 % retained, and a notice that the code was modified is included. This
153 % software was developed with support from the National Science Foundation,
154 % and is provided to you free of charge.
155 %
156 % Availability: http://www.cise.ufl.edu/research/sparse/umfpack
157 %
158 % See also umfpack, umfpack_make, umfpack_report,
159 % umfpack_demo, and umfpack_simple.
160
161 more on
162 help umfpack_details
163 more off
164