Mercurial > octave-nkf

comparison liboctave/UMFPACK/UMFPACK/README.txt @ 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 UMFPACK Version 4.4: a set of routines solving sparse linear systems via LU
2 factorization. Requires two other packages: the BLAS (dense matrix
3 operations) and AMD (sparse matrix minimum degree ordering). Includes
4 a C-callable and MATLAB interface, and a basic FORTRAN 77 interface to
5 a subset of the C-callable routines.
6
7 Quick start (Unix, or Windows with Cygwin):
8
9 To compile, test, and install both UMFPACK and AMD, the UMFPACK and AMD
10 directories must be in the same parent directory. To configure, edit
11 UMFPACK/Make/Make.include and AMD/Make/Make.include (otherwise the BLAS
12 will not be used, and UMFPACK will be slow). cd to this directory (UMFPACK)
13 and type "make" (or "make lib" if you do not have MATLAB). To compile and
14 run a demo program for Harwell/Boeing matrices, type "make hb". To compile
15 a FORTRAN main program that calls the 32-bit C-callable UMFPACK library,
16 type "make fortran". When done, type "make clean" to remove unused *.o
17 files (keeps the compiled libraries and demo programs). See the User Guide
18 (Doc/UserGuide.pdf), or UMFPACK/Make/Make.include, for more details
19 (including options for compiling 64-bit mode).
20
21 Quick start (for MATLAB users):
22
23 To compile, test, and install the UMFPACK mexFunction, cd to the
24 UMFPACK/MATLAB directory and type umfpack_make at the MATLAB prompt.
25 This works on any system supported by MATLAB.
26
27 --------------------------------------------------------------------------------
28
29 UMFPACK Version 4.4 (Jan. 28, 2005), Copyright (c) 2005 by Timothy A.
30 Davis. All Rights Reserved.
31
32 UMFPACK License:
33
34 Your use or distribution of UMFPACK or any modified version of
35 UMFPACK implies that you agree to this License.
36
37 THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY
38 EXPRESSED OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
39
40 Permission is hereby granted to use or copy this program, provided
41 that the Copyright, this License, and the Availability of the original
42 version is retained on all copies. User documentation of any code that
43 uses UMFPACK or any modified version of UMFPACK code must cite the
44 Copyright, this License, the Availability note, and "Used by permission."
45 Permission to modify the code and to distribute modified code is granted,
46 provided the Copyright, this License, and the Availability note are
47 retained, and a notice that the code was modified is included. This
48 software was developed with support from the National Science Foundation,
49 and is provided to you free of charge.
50
51 Availability:
52
53 http://www.cise.ufl.edu/research/sparse/umfpack
54
55 UMFPACK (including versions 2.2.1 and earlier, in Fortran) is available at
56 http://www.cise.ufl.edu/research/sparse. MA38 is available in the Harwell
57 Subroutine Library. This version of UMFPACK includes a modified form of
58 COLAMD Version 2.0, originally released on Jan. 31, 2000, also available at
59 http://www.cise.ufl.edu/research/sparse. COLAMD V2.0 is also incorporated
60 as a built-in function in MATLAB version 6.1, by The MathWorks, Inc.
61 (http://www.mathworks.com). COLAMD V1.0 appears as a column-preordering
62 in SuperLU (SuperLU is available at http://www.netlib.org).
63 UMFPACK v4.0 is a built-in routine in MATLAB 6.5.
64 UMFPACK v4.3 is a built-in routine in MATLAB 7.1.
65
66 --------------------------------------------------------------------------------
67
68 Refer to ../AMD/README for the License for AMD, which is a separate
69 package for ordering sparse matrices that is required by UMFPACK.
70 UMFPACK v4.4 can use either AMD v1.0 or v1.1.
71
72 --------------------------------------------------------------------------------
73
74 This is the UMFPACK README.txt file. It is a terse overview of UMFPACK.
75 Refer to the User Guide (Doc/UserGuide.pdf) for how to install and use UMFPACK,
76 or to the Quick Start Guide, QuickStart.pdf.
77
78 Description:
79
80 UMFPACK is a set of routines for solving unsymmetric sparse linear systems,
81 Ax=b, using the Unsymmetric MultiFrontal method. Written in ANSI/ISO C,
82 with a MATLAB (Version 6.0 or later) interface.
83
84 For best performance, UMFPACK requires an optimized BLAS library. It can
85 also be compiled without any BLAS at all. UMFPACK requires AMD Version 1.0
86 or Version 1.1
87
88 Authors:
89
90 Timothy A. Davis (davis@cise.ufl.edu), University of Florida.
91
92 Includes a modified version of COLAMD V2.0, by Stefan I. Larimore and
93 Timothy A. Davis, University of Florida. The COLAMD algorithm was developed
94 in collaboration with John Gilbert, Xerox Palo Alto Research Center, and
95 Esmond Ng, Lawrence Berkeley National Laboratory.
96
97 Includes AMD, by Timothy A. Davis, Patrick R. Amestoy, and Iain S. Duff.
98
99 UMFPACK Version 2.2.1 (MA38 in the Harwell Subroutine Library) is
100 co-authored with Iain S. Duff, Rutherford Appleton Laboratory.
101
102 Acknowledgements:
103
104 This work was supported by the National Science Foundation, under
105 grants DMS-9504974, DMS-9803599, and CCR-0203270.
106
107 Portions of this work were done while on sabbatical at Stanford University
108 and Lawrence Berkeley National Laboratory (with funding from the SciDAC
109 program). I would like to thank Gene Golub, Esmond Ng, and Horst Simon
110 for making this sabbatical possible.
111
112 I would also like to thank the many researchers who provided sparse
113 matrices from a wide range of domains and used earlier versions of UMFPACK/
114 MA38 in their applications, and thus assisted in the practical development
115 of the algorithm (see http://www.cise.ufl.edu/research/sparse, future
116 contributions of matrices are always welcome).
117
118 The MathWorks, Inc., provided a pre-release of MATLAB V6 which allowed me
119 to release the first umfpack mexFunction (v3.0) about 6 months earlier than
120 I had originally planned. They also supported the extension of UMFPACK to
121 complex, singular, and rectangular matrices (UMFPACK v4.0).
122
123 Penny Anderson (The MathWorks, Inc.), Anshul Gupta (IBM), and Friedrich
124 Grund (WAIS) assisted in porting UMFPACK to different platforms. Penny
125 Anderson also incorporated UMFPACK v4.0 into MATLAB, for lu, backslash (\),
126 and forward slash (/).
127
128 David Bateman (Motorola) wrote the initial version of the packed complex
129 input option, and umfpack_get_determinant.
130
131 --------------------------------------------------------------------------------
132 Files and directories in the UMFPACK distribution:
133 --------------------------------------------------------------------------------
134
135 ----------------------------------------------------------------------------
136 Subdirectories of the UMFPACK directory:
137 ----------------------------------------------------------------------------
138
139 Doc documentation
140 Make for compiling UMFPACK (a symbolic link to ../AMD/Make)
141 Source primary source code
142 Include include files for use in your code that calls UMFPACK
143 Demo demo programs. also serves as test of the UMFPACK installation.
144 MATLAB UMFPACK mexFunction for MATLAB, and supporting m-files
145 Lib where the compiled C-callable UMFPACK library is placed.
146
147 ----------------------------------------------------------------------------
148 Files in the UMFPACK directory:
149 ----------------------------------------------------------------------------
150
151 Makefile top-level Makefile for GNU make or original make.
152 Windows users would require Cygwin to use "make"
153
154 README.txt this file
155
156 ----------------------------------------------------------------------------
157 Doc directory: documentation
158 ----------------------------------------------------------------------------
159
160 ChangeLog change log
161 License the UMFPACK License
162 Makefile for creating the documentation
163 QuickStart.tex Quick Start guide (source)
164 QuickStart.pdf Quick Start guide (PDF)
165 UserGuide.bib User Guide (references)
166 UserGuide.sed1 sed script for processing UserGuide.stex
167 UserGuide.sed2 sed script for processing UserGuide.stex
168 UserGuide.stex User Guide (LaTeX)
169 UserGuide.pdf User Guide (PDF)
170
171 ----------------------------------------------------------------------------
172 Make directory: for compiling the UMFPACK library (Lib/libumfpack.a)
173 ----------------------------------------------------------------------------
174
175 This is a symbolic link to the ../AMD/Make directory. Refer to the
176 ../AMD/README file for a list of its contents.
177
178 ----------------------------------------------------------------------------
179 Source directory:
180 ----------------------------------------------------------------------------
181
182 GNUmakefile a nice Makefile, for GNU make
183 Makefile an ugly Unix Makefile (for older make's)
184
185 umfpack_col_to_triplet.c convert col form to triplet
186 umfpack_defaults.c set Control defaults
187 umfpack_free_numeric.c free Numeric object
188 umfpack_free_symbolic.c free Symbolic object
189 umfpack_get_determinant.c compute determinant from Numeric object
190 umfpack_get_lunz.c get nz's in L and U
191 umfpack_get_numeric.c get Numeric object
192 umfpack_get_symbolic.c get Symbolic object
193 umfpack_load_numeric.c load Numeric object from file
194 umfpack_load_symbolic.c load Symbolic object from file
195 umfpack_numeric.c numeric factorization
196 umfpack_qsymbolic.c symbolic factorization, user Q
197 umfpack_report_control.c print Control settings
198 umfpack_report_info.c print Info statistics
199 umfpack_report_matrix.c print col or row-form sparse matrix
200 umfpack_report_numeric.c print Numeric object
201 umfpack_report_perm.c print permutation
202 umfpack_report_status.c print return status
203 umfpack_report_symbolic.c print Symbolic object
204 umfpack_report_triplet.c print triplet matrix
205 umfpack_report_vector.c print dense vector
206 umfpack_save_numeric.c save Numeric object to file
207 umfpack_save_symbolic.c save Symbolic object to file
208 umfpack_scale.c scale a vector
209 umfpack_solve.c solve a linear system
210 umfpack_symbolic.c symbolic factorization
211 umfpack_tictoc.c timer
212 umfpack_timer.c timer
213 umfpack_transpose.c transpose a matrix
214 umfpack_triplet_to_col.c convert triplet to col form
215
216 umf_config.h configuration file (BLAS, memory, timer)
217 umf_internal.h definitions internal to UMFPACK
218 umf_version.h version definitions (int/long, real/complex)
219
220 umf_2by2.[ch]
221 umf_analyze.[ch] symbolic factorization of A'*A
222 umf_apply_order.[ch] apply column etree postorder
223 umf_assemble.[ch] assemble elements into current front
224 umf_blas3_update.[ch] rank-k update. Uses level-3 BLAS
225 umf_build_tuples.[ch] construct tuples for elements
226 umf_colamd.[ch] COLAMD pre-ordering, modified for UMFPACK
227 umf_create_element.[ch] create a new element
228 umf_dump.[ch] debugging routines, not normally active
229 umf_extend_front.[ch] extend the current frontal matrix
230 umf_free.[ch] free memory
231 umf_fsize.[ch] determine largest front in each subtree
232 umf_garbage_collection.[ch] compact Numeric->Memory
233 umf_get_memory.[ch] make Numeric->Memory bigger
234 umf_grow_front.[ch] make current frontal matrix bigger
235 umf_init_front.[ch] initialize a new frontal matrix
236 umf_is_permutation.[ch] checks the validity of a permutation vector
237 umf_kernel.[ch] the main numeric factorization kernel
238 umf_kernel_init.[ch] initializations for umf_kernel
239 umf_kernel_wrapup.[ch] wrapup for umf_kernel
240 umf_local_search.[ch] local row and column pivot search
241 umf_lsolve.[ch] solve Lx=b
242 umf_ltsolve.[ch] solve L'x=b and L.'x=b
243 umf_malloc.[ch] malloc some memory
244 umf_mem_alloc_element.[ch] allocate element in Numeric->Memory
245 umf_mem_alloc_head_block.[ch] alloc. block at head of Numeric->Memory
246 umf_mem_alloc_tail_block.[ch] alloc. block at tail of Numeric->Memory
247 umf_mem_free_tail_block.[ch] free block at tail of Numeric->Memory
248 umf_mem_init_memoryspace.[ch] initialize Numeric->Memory
249 umf_realloc.[ch] realloc memory
250 umf_report_perm.[ch] print a permutation vector
251 umf_report_vector.[ch] print a double vector
252 umf_row_search.[ch] look for a pivot row
253 umf_scale.[ch] scale the pivot column
254 umf_scale_column.[ch] move pivot row & column into place, log P and Q
255 umf_set_stats.[ch] set statistics (final or estimates)
256 umf_singletons.[ch] find all zero-cost pivots
257 umf_solve.[ch] solve a linear system
258 umf_start_front.[ch] start a new frontal matrix for one frontal chain
259 umf_store_lu.[ch] store LU factors of current front
260 umf_symbolic_usage.[ch] determine memory usage for Symbolic object
261 umf_transpose.[ch] transpose a matrix in row or col form
262 umf_triplet.[ch] convert triplet to column form
263 umf_tuple_lengths.[ch] determine the tuple list lengths
264 umf_usolve.[ch] solve Ux=b
265 umf_utsolve.[ch] solve U'x=b and U.'x=b
266 umf_valid_numeric.[ch] checks the validity of a Numeric object
267 umf_valid_symbolic.[ch] check the validity of a Symbolic object
268
269 ----------------------------------------------------------------------------
270 Include directory:
271 ----------------------------------------------------------------------------
272
273 umfpack.h include file for user programs. Includes all of
274 the following files. This serves are source-
275 code level documenation. These files are also
276 used to construct the User Guide.
277
278 umfpack_col_to_triplet.h
279 umfpack_defaults.h
280 umfpack_free_numeric.h
281 umfpack_free_symbolic.h
282 umfpack_get_determinant.h
283 umfpack_get_lunz.h
284 umfpack_get_numeric.h
285 umfpack_get_symbolic.h
286 umfpack_load_numeric.h
287 umfpack_load_symbolic.h
288 umfpack_numeric.h
289 umfpack_qsymbolic.h
290 umfpack_report_control.h
291 umfpack_report_info.h
292 umfpack_report_matrix.h
293 umfpack_report_numeric.h
294 umfpack_report_perm.h
295 umfpack_report_status.h
296 umfpack_report_symbolic.h
297 umfpack_report_triplet.h
298 umfpack_report_vector.h
299 umfpack_save_numeric.h
300 umfpack_save_symbolic.h
301 umfpack_scale.h
302 umfpack_solve.h
303 umfpack_symbolic.h
304 umfpack_tictoc.h
305 umfpack_timer.h
306 umfpack_transpose.h
307 umfpack_triplet_to_col.h
308
309 umfpack_wsolve.h note that there is no umfpack_wsolve.c. The
310 umfpack_*_wsolve routines are created from the
311 umfpack_solve.c file.
312
313 ----------------------------------------------------------------------------
314 Demo directory:
315 ----------------------------------------------------------------------------
316
317 Makefile for GNU make or original make
318
319 umfpack_simple.c a simple demo
320 umpack_xx_demo.c template to create the demo codes below
321
322 umfpack_di_demo.sed for creating umfpack_di_demo.c
323 umfpack_dl_demo.sed for creating umfpack_dl_demo.c
324 umfpack_zi_demo.sed for creating umfpack_zi_demo.c
325 umfpack_zl_demo.sed for creating umfpack_zl_demo.c
326
327 umfpack_di_demo.c a full demo (real/int version)
328 umfpack_dl_demo.c a full demo (real/long version)
329 umfpack_zi_demo.c a full demo (complex/int version)
330 umfpack_zl_demo.c a full demo (complex/long version)
331
332 umfpack_di_demo.out umfpack_di_demo output, unmodified Make.include
333 umfpack_dl_demo.out umfpack_dl_demo output, unmodified Make.include
334 umfpack_zi_demo.out umfpack_zi_demo output, unmodified Make.include
335 umfpack_zl_demo.out umfpack_zl_demo output, unmodified Make.include
336
337 umf4.c a demo (real/int) for Harwell/Boeing matrices
338 umf4.out output of "make hb", unmodified Make.include
339 HB directory of sample Harwell/Boeing matrices
340 readhb.f reads HB matrices, keeps zero entries
341 readhb_nozeros.f reads HB matrices, removes zero entries
342 readhb_size.f reads HB matrix dimension, nnz
343 tmp empty directory for umf4.c demo
344
345 umf4_f77wrapper.c a simple FORTRAN interface for UMFPACK.
346 compile with "make fortran"
347 umf4hb.f a demo of the FORTRAN interface
348 umf4hb.out output of "make fortran"
349
350 umf4_f77zwrapper.c a simple FORTRAN interface for the complex
351 UMFPACK routines. compile with "make fortran"
352 umf4zhb.f a demo of the FORTRAN interface (complex)
353 umf4zhb.out output of umf4zhb with HB/qc324.cua
354
355 umf4hb64.f 64-bit version of umf4hb.f
356
357 simple_compile a single command that compiles the double/int
358 version of UMFPACK (useful prototype for
359 Microsoft Visual Studio project)
360
361 ----------------------------------------------------------------------------
362 MATLAB directory:
363 ----------------------------------------------------------------------------
364
365 Contents.m for "help umfpack" listing of toolbox contents
366 GNUmakefile a nice Makefile, for GNU make
367 Makefile an ugly Unix Makefile (for older make's)
368
369 lu_normest.m 1-norm estimate of A-L*U (by Hager & Davis).
370 luflop.m for "help luflop"
371 luflopmex.c luflop mexFunction, for computing LU flop count
372 umfpack.m for "help umfpack"
373 umfpack_btf.m solve Ax=b using umfpack and dmperm
374 umfpack_demo.m a full umfpack demo
375 umfpack_details.m the details of how to use umfpack
376 umfpack_make.m compile the umfpack mexFunction within MATLAB
377 umfpack_report.m report statistics
378 umfpack_simple.m a simple umfpack demo
379 umfpack_solve.m x=A\b or b/A for arbitrary b
380 umfpack_test.m extensive test, requires UF sparse matrices
381 umfpackmex.c the umfpack mexFunction
382 west0067.mat sparse matrix for umfpack_demo.m
383
384 umfpack_demo.m.out output of umfpack_demo.m
385 umfpack_simple.m.out output of umfpack_simple
386
387 lcc_lib/lapacksyms.def LAPACK definitions for lcc compiler (Windows)
388 lcc_lib/libmwlapack.lib LAPACK definitions for lcc compiler (Windows)
389
390 ----------------------------------------------------------------------------
391 Lib directory: libumfpack.a library placed here
392 ----------------------------------------------------------------------------
393
394 libumfpack.def UMPFACK definitions for Windows