1 SuperLU (Version 5.2.x) 2 ======================= 3 4SuperLU contains a set of subroutines to solve a sparse linear system 5A*X=B. It uses Gaussian elimination with partial pivoting (GEPP). 6The columns of A may be preordered before factorization; the 7preordering for sparsity is completely separate from the factorization. 8 9SuperLU is implemented in ANSI C, and must be compiled with standard 10ANSI C compilers. It provides functionality for both real and complex 11matrices, in both single and double precision. The file names for the 12single-precision real version start with letter "s" (such as sgstrf.c); 13the file names for the double-precision real version start with letter "d" 14(such as dgstrf.c); the file names for the single-precision complex 15version start with letter "c" (such as cgstrf.c); the file names 16for the double-precision complex version start with letter "z" 17(such as zgstrf.c). 18 19 20SuperLU contains the following directory structure: 21 22 SuperLU/README instructions on installation 23 SuperLU/CBLAS/ needed BLAS routines in C, not necessarily fast 24 SuperLU/DOC/ Users' Guide and documentation of source code 25 SuperLU/EXAMPLE/ example programs 26 SuperLU/FORTRAN/ Fortran interface 27 SuperLU/INSTALL/ test machine dependent parameters; the Users' Guide. 28 SuperLU/MAKE_INC/ sample machine-specific make.inc files 29 SuperLU/MATLAB/ Matlab mex-file interface 30 SuperLU/SRC/ C source code, to be compiled into the superlu.a library 31 SuperLU/TESTING/ driver routines to test correctness 32 SuperLU/Makefile top level Makefile that does installation and testing 33 SuperLU/make.inc compiler, compile flags, library definitions and C 34 preprocessor definitions, included in all Makefiles. 35 (You may need to edit it to be suitable for your system 36 before compiling the whole package.) 37 38There are two ways to install the package. One uses CMake build system, 39the other requires users to edit makefile manually. The procedures 40are described below. 41 421. Manual installation with makefile. 43 Before installing the package, please examine the three things dependent 44 on your system setup: 45 46 1.1 Edit the make.inc include file. 47 This make include file is referenced inside each of the Makefiles 48 in the various subdirectories. As a result, there is no need to 49 edit the Makefiles in the subdirectories. All information that is 50 machine specific has been defined in this include file. 51 52 Example machine-specific make.inc include files are provided 53 in the MAKE_INC/ directory for several systems, such as Linux, 54 MacX, Cray, IBM, SunOS 5.x (Solaris), and HP-PA. 55 When you have selected the machine to which you wish 56 to install SuperLU, copy the appropriate sample include file (if one 57 is present) into make.inc. For example, if you wish to run 58 SuperLU on an linux, you can do 59 60 cp MAKE_INC/make.linux make.inc 61 62 For the systems other than listed above, slight modifications to the 63 make.inc file will need to be made. 64 65 1.2. The BLAS library. 66 If there is BLAS library available on your machine, you may define 67 the following in the file SuperLU/make.inc: 68 BLASDEF = -DUSE_VENDOR_BLAS 69 BLASLIB = <BLAS library you wish to link with> 70 71 The CBLAS/ subdirectory contains the part of the C BLAS needed by 72 SuperLU package. However, these codes are intended for use only if 73 there is no faster implementation of the BLAS already available 74 on your machine. In this case, you should do the following: 75 76 1) In SuperLU/make.inc, undefine (comment out) BLASDEF, and define: 77 BLASLIB = ../lib/blas$(PLAT).a 78 79 2) Go to the SuperLU/ directory, type: 80 make blaslib 81 to make the BLAS library from the routines in the 82 CBLAS/ subdirectory. 83 84 1.3. C preprocessor definition CDEFS. 85 In the header file SRC/slu_Cnames.h, we use macros to determine how 86 C routines should be named so that they are callable by Fortran. 87 (Some vendor-supplied BLAS libraries do not have C interface. So the 88 re-naming is needed in order for the SuperLU BLAS calls (in C) to 89 interface with the Fortran-style BLAS.) 90 The possible options for CDEFS are: 91 92 o -DAdd_: Fortran expects a C routine to have an underscore 93 postfixed to the name; 94 o -DNoChange: Fortran expects a C routine name to be identical to 95 that compiled by C; 96 o -DUpCase: Fortran expects a C routine name to be all uppercase. 97 98 1.4. The Matlab MEX-file interface. 99 The MATLAB/ subdirectory includes Matlab C MEX-files, so that 100 our factor and solve routines can be called as alternatives to those 101 built into Matlab. In the file SuperLU/make.inc, define MATLAB to be 102 the directory in which Matlab is installed on your system, for example: 103 104 MATLAB = /usr/local/matlab 105 106 At the SuperLU/ directory, type "make matlabmex" to build the MEX-file 107 interface. After you have built the interface, you may go to the 108 MATLAB/ directory to test the correctness by typing (in Matlab): 109 trysuperlu 110 trylusolve 111 112 A Makefile is provided in each subdirectory. The installation can be done 113 completely automatically by simply typing "make" at the top level. 114 The test results are in the files below: 115 INSTALL/install.out 116 TESTING/stest.out # single precision, real 117 TESTING/dtest.out # double precision, real 118 TESTING/ctest.out # single precision, complex 119 TESTING/ztest.out # double precision, complex 120 121 1222. Using CMake build system. 123 You will need to create a build tree from which to invoke CMake. 124 125 From the top level directory, do: 126 mkdir build ; cd build 127 cmake .. 128 129 or with more options, e.g., 130 cmake .. \ 131 -DCMAKE_INSTALL_PREFIX=../build 132 -DCMAKE_INSTALL_INCLUDEDIR=/my/custom/path 133 134 To actually build, type: 135 make 136 137 To install the library, type: 138 make install 139 140 To run the installation test, type: 141 make test (or: ctest) 142 143 The test results are in the files below: 144 build/TESTING/s_test.out # single precision, real 145 build/TESTING/d_test.out # double precision, real 146 build/TESTING/c_test.out # single precision, complex 147 build/TESTING/z_test.out # double precision, complex 148 149 150-------------------- 151| RELEASE VERSIONS | 152-------------------- 153 February 4, 1997 Version 1.0 154 November 15, 1997 Version 1.1 155 September 1, 1999 Version 2.0 156 October 15, 2003 Version 3.0 157 August 1, 2008 Version 3.1 158 June 30, 2009 Version 4.0 159 November 23, 2010 Version 4.1 160 August 25, 2011 Version 4.2 161 October 27, 2011 Version 4.3 162 July 26, 2015 Version 5.0 163 December 3, 2015 Version 5.1 164 April 8, 2016 Version 5.2.0 165