|
kusano |
7d535a |
SuperLU (Version 4.1)
|
|
kusano |
7d535a |
=====================
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
Copyright (c) 2003, The Regents of the University of California, through
|
|
kusano |
7d535a |
Lawrence Berkeley National Laboratory (subject to receipt of any required
|
|
kusano |
7d535a |
approvals from U.S. Dept. of Energy)
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
All rights reserved.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
Redistribution and use in source and binary forms, with or without
|
|
kusano |
7d535a |
modification, are permitted provided that the following conditions are met:
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
(1) Redistributions of source code must retain the above copyright notice,
|
|
kusano |
7d535a |
this list of conditions and the following disclaimer.
|
|
kusano |
7d535a |
(2) Redistributions in binary form must reproduce the above copyright notice,
|
|
kusano |
7d535a |
this list of conditions and the following disclaimer in the documentation
|
|
kusano |
7d535a |
and/or other materials provided with the distribution.
|
|
kusano |
7d535a |
(3) Neither the name of Lawrence Berkeley National Laboratory, U.S. Dept. of
|
|
kusano |
7d535a |
Energy nor the names of its contributors may be used to endorse or promote
|
|
kusano |
7d535a |
products derived from this software without specific prior written permission.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
|
kusano |
7d535a |
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
|
|
kusano |
7d535a |
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
kusano |
7d535a |
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
|
|
kusano |
7d535a |
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
kusano |
7d535a |
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
kusano |
7d535a |
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
kusano |
7d535a |
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
kusano |
7d535a |
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
kusano |
7d535a |
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
kusano |
7d535a |
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
SuperLU contains a set of subroutines to solve a sparse linear system
|
|
kusano |
7d535a |
A*X=B. It uses Gaussian elimination with partial pivoting (GEPP).
|
|
kusano |
7d535a |
The columns of A may be preordered before factorization; the
|
|
kusano |
7d535a |
preordering for sparsity is completely separate from the factorization.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
SuperLU is implemented in ANSI C, and must be compiled with standard
|
|
kusano |
7d535a |
ANSI C compilers. It provides functionality for both real and complex
|
|
kusano |
7d535a |
matrices, in both single and double precision. The file names for the
|
|
kusano |
7d535a |
single-precision real version start with letter "s" (such as sgstrf.c);
|
|
kusano |
7d535a |
the file names for the double-precision real version start with letter "d"
|
|
kusano |
7d535a |
(such as dgstrf.c); the file names for the single-precision complex
|
|
kusano |
7d535a |
version start with letter "c" (such as cgstrf.c); the file names
|
|
kusano |
7d535a |
for the double-precision complex version start with letter "z"
|
|
kusano |
7d535a |
(such as zgstrf.c).
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
SuperLU contains the following directory structure:
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
SuperLU/README instructions on installation
|
|
kusano |
7d535a |
SuperLU/CBLAS/ needed BLAS routines in C, not necessarily fast
|
|
kusano |
7d535a |
SuperLU/DOC/ Users' Guide and documentation of source code
|
|
kusano |
7d535a |
SuperLU/EXAMPLE/ example programs
|
|
kusano |
7d535a |
SuperLU/FORTRAN/ Fortran interface
|
|
kusano |
7d535a |
SuperLU/INSTALL/ test machine dependent parameters; the Users' Guide.
|
|
kusano |
7d535a |
SuperLU/MAKE_INC/ sample machine-specific make.inc files
|
|
kusano |
7d535a |
SuperLU/MATLAB/ Matlab mex-file interface
|
|
kusano |
7d535a |
SuperLU/SRC/ C source code, to be compiled into the superlu.a library
|
|
kusano |
7d535a |
SuperLU/TESTING/ driver routines to test correctness
|
|
kusano |
7d535a |
SuperLU/Makefile top level Makefile that does installation and testing
|
|
kusano |
7d535a |
SuperLU/make.inc compiler, compile flags, library definitions and C
|
|
kusano |
7d535a |
preprocessor definitions, included in all Makefiles.
|
|
kusano |
7d535a |
(You may need to edit it to be suitable for your system
|
|
kusano |
7d535a |
before compiling the whole package.)
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
Before installing the package, please examine the three things dependent
|
|
kusano |
7d535a |
on your system setup:
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
1. Edit the make.inc include file.
|
|
kusano |
7d535a |
This make include file is referenced inside each of the Makefiles
|
|
kusano |
7d535a |
in the various subdirectories. As a result, there is no need to
|
|
kusano |
7d535a |
edit the Makefiles in the subdirectories. All information that is
|
|
kusano |
7d535a |
machine specific has been defined in this include file.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
Example machine-specific make.inc include files are provided
|
|
kusano |
7d535a |
in the MAKE_INC/ directory for several systems, such as Linux,
|
|
kusano |
7d535a |
IBM RS/6000, SunOS 5.x (Solaris), HP-PA and MacX.
|
|
kusano |
7d535a |
When you have selected the machine to which you wish
|
|
kusano |
7d535a |
to install SuperLU, copy the appropriate sample include file (if one
|
|
kusano |
7d535a |
is present) into make.inc. For example, if you wish to run
|
|
kusano |
7d535a |
SuperLU on an linux, you can do
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
cp MAKE_INC/make.linux make.inc
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
For the systems other than listed above, slight modifications to the
|
|
kusano |
7d535a |
make.inc file will need to be made.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
2. The BLAS library.
|
|
kusano |
7d535a |
If there is BLAS library available on your machine, you may define
|
|
kusano |
7d535a |
the following in the file SuperLU/make.inc:
|
|
kusano |
7d535a |
BLASDEF = -DUSE_VENDOR_BLAS
|
|
kusano |
7d535a |
BLASLIB = <blas library="" link="" to="" wish="" with="" you=""></blas>
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
The CBLAS/ subdirectory contains the part of the C BLAS needed by
|
|
kusano |
7d535a |
SuperLU package. However, these codes are intended for use only if there
|
|
kusano |
7d535a |
is no faster implementation of the BLAS already available on your machine.
|
|
kusano |
7d535a |
In this case, you should do the following:
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
1) In SuperLU/make.inc, undefine (comment out) BLASDEF, and define:
|
|
kusano |
7d535a |
BLASLIB = ../lib/blas$(PLAT).a
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
2) Go to the SuperLU/ directory, type:
|
|
kusano |
7d535a |
make blaslib
|
|
kusano |
7d535a |
to make the BLAS library from the routines in the CBLAS/ subdirectory.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
3. C preprocessor definition CDEFS.
|
|
kusano |
7d535a |
In the header file SRC/slu_Cnames.h, we use macros to determine how
|
|
kusano |
7d535a |
C routines should be named so that they are callable by Fortran.
|
|
kusano |
7d535a |
(Some vendor-supplied BLAS libraries do not have C interface. So the
|
|
kusano |
7d535a |
re-naming is needed in order for the SuperLU BLAS calls (in C) to
|
|
kusano |
7d535a |
interface with the Fortran-style BLAS.)
|
|
kusano |
7d535a |
The possible options for CDEFS are:
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
o -DAdd_: Fortran expects a C routine to have an underscore
|
|
kusano |
7d535a |
postfixed to the name;
|
|
kusano |
7d535a |
o -DNoChange: Fortran expects a C routine name to be identical to
|
|
kusano |
7d535a |
that compiled by C;
|
|
kusano |
7d535a |
o -DUpCase: Fortran expects a C routine name to be all uppercase.
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
4. The Matlab MEX-file interface.
|
|
kusano |
7d535a |
The MATLAB/ subdirectory includes Matlab C MEX-files, so that
|
|
kusano |
7d535a |
our factor and solve routines can be called as alternatives to those
|
|
kusano |
7d535a |
built into Matlab. In the file SuperLU/make.inc, define MATLAB to be the
|
|
kusano |
7d535a |
directory in which Matlab is installed on your system, for example:
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
MATLAB = /usr/local/matlab
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
At the SuperLU/ directory, type "make matlabmex" to build the MEX-file
|
|
kusano |
7d535a |
interface. After you have built the interface, you may go to the MATLAB/
|
|
kusano |
7d535a |
directory to test the correctness by typing (in Matlab):
|
|
kusano |
7d535a |
trysuperlu
|
|
kusano |
7d535a |
trylusolve
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
A Makefile is provided in each subdirectory. The installation can be done
|
|
kusano |
7d535a |
completely automatically by simply typing "make" at the top level.
|
|
kusano |
7d535a |
The test results are in the files below:
|
|
kusano |
7d535a |
INSTALL/install.out
|
|
kusano |
7d535a |
TESTING/stest.out
|
|
kusano |
7d535a |
TESTING/dtest.out
|
|
kusano |
7d535a |
TESTING/ctest.out
|
|
kusano |
7d535a |
TESTING/ztest.out
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
|
|
kusano |
7d535a |
--------------------
|
|
kusano |
7d535a |
| RELEASE VERSIONS |
|
|
kusano |
7d535a |
--------------------
|
|
kusano |
7d535a |
February 4, 1997 Version 1.0
|
|
kusano |
7d535a |
November 15, 1997 Version 1.1
|
|
kusano |
7d535a |
September 1, 1999 Version 2.0
|
|
kusano |
7d535a |
October 15, 2003 Version 3.0
|
|
kusano |
7d535a |
August 1, 2008 Version 3.1
|
|
kusano |
7d535a |
June 30, 2009 Version 4.0
|
|
kusano |
7d535a |
November 23, 2010 Version 4.1
|