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