SUPERLU
Sparse Linear Equation Solver

SUPERLU, FORTRAN77 programs which illustrate the use of the SUPERLU library for the fast direct solution of large sparse systems of linear equations.

Although SUPERLU is written in C, these examples show how, by using an interface function, a FORTRAN77 program can pass data to SUPERLU and receive results computed by it.

SUPERLU contains a set of subroutines to solve a sparse linear system A*X=B. It uses Gaussian elimination with partial pivoting (GEPP). The columns of A may be preordered before factorization; the preordering for sparsity is completely separate from the factorization.

SUPERLU is implemented in ANSI C, and must be compiled with an ANSI C compiler. It provides functionality for both real and complex matrices, in both single and double precision. The initial letter of a routine name indicates the arithmetic type and precision:

• C, such as cgstrf, is for single precision complex arithmetic;
• D, such as dgstrf, is for double precision real arithmetic;
• S, such as sgstrf, is for single precision real arithmetic;
• Z, such as zgstrf, is for double precision complex arithmetic.

SUPERLU includes functions to read a sparse matrix from a file in the Harwell-Boeing sparse matrix format.

Licensing:

Copyright (c) 2003, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from U.S. Dept. of Energy)

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of Lawrence Berkeley National Laboratory, U.S. Dept. of Energy nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Languages:

SUPERLU is available in a C version and a C++ version and a FORTRAN77 version and a FORTRAN90 version.

Related Data and Programs:

CC, a data directory which contains a description and examples of the CC format, ("compressed column") for storing a sparse matrix, including a way to write the matrix as a set of three files.

CG_RC, a FORTRAN77 library which implements the conjugate gradient method for solving a positive definite sparse linear system A*x=b, using reverse communication.

HB, a data directory which contains examples of Harwell Boeing (HB) files, a sparse matrix file format;

HB_READ, a FORTRAN77 library which reads files in the Harwell Boeing (HB) sparse matrix format; This is a simplified interface intended to handle only the most common format, complex unsymmetric assembled (CUA) or real unsymmetric assembled (RUA).

MGMRES, a FORTRAN77 library which applies the restarted GMRES algorithm to solve a sparse linear system, by Lili Ju.

SUPERLU_OPENMP, FORTRAN77 programs which illustrate how to use the SUPERLU library with the OpenMP parallel programming interface, which applies a fast direct solution method to solve sparse linear systems, by James Demmel, John Gilbert, and Xiaoye Li.

Reference:

1. http://crd.lbl.gov/~xiaoye/SuperLU/ the SuperLU web site.
2. James Demmel, John Gilbert, Xiaoye Li,
   SuperLU Users's Guide.
3. James Demmel, Stanley Eisenstat, John Gilbert, Xiaoye Li, Joseph Liu
   A Supernodal Approach to Sparse Partial Pivoting,
   SIAM Journal on Matrix Analysis and Applications,
   Volume 20, Number 3, pages 720-755, 1999.

Examples and Tests:

Depending on the arithmetic precision involved, the user must compile one of the following C functions and link it with the FORTRAN77 program and SUPERLU:

• c_fortran_cgssv.c, the C/FORTRAN interface function for calling CGSSV, single precision complex arithmetic.
• c_fortran_dgssv.c, the C/FORTRAN interface function for calling DGSSV, double precision real arithmetic.
• c_fortran_sgssv.c, the C/FORTRAN interface function for calling SGSSV, single precision real arithmetic.
• c_fortran_zgssv.c, the C/FORTRAN interface function for calling ZGSSV, double precision complex arithmetic.

Many of the examples read the matrix from a file, which uses the Harwell-Boeing sparse matrix format. These matrices include:

• sample_cua.txt, a complex 5x5 matrix in Harwell Boeing (HB) CUA format;
• sample_rua.txt, a real 5x5 matrix in Harwell Boeing (HB) RUA format;

C_SAMPLE uses CGSSV to solve a 5x5 system. Single precision complex arithmetic is used.

• c_sample.f, the calling program;
• c_sample.sh, commands to compile, link and run the calling program;
• c_sample_output.txt, the sample output.

C_SAMPLE_HB reads a 5x5 matrix from a file in Harwell-Boeing (HB) format, into compressed column (CC) format, and then uses CGSSV to solve the linear system. Single precision complex arithmetic is used.

• c_sample_hb.f, the calling program;
• c_sample_hb.sh, commands to compile, link and run the calling program;
• c_sample_hb_output.txt, the sample output.

C_SAMPLE_ST reads a 5x5 matrix from a file in Sparse Triplet (ST) format, into compressed column (CC) format, and then uses CGSSV to solve the linear system. Single precision complex arithmetic is used.

• c_sample_st.f, the calling program;
• c_sample_st.sh, commands to compile, link and run the calling program;
• c_sample_st_output.txt, the sample output.

D_SAMPLE uses DGSSV to solve a 5x5 system. Double precision real arithmetic is used.

• d_sample.f, the calling program;
• d_sample.sh, commands to compile, link and run the calling program;
• d_sample_output.txt, the sample output.

D_SAMPLE_HB reads a 5x5 matrix from a file in Harwell-Boeing (HB) format, into compressed column (CC) format, and then uses DGSSV to solve the linear system. Double precision real arithmetic is used.

• d_sample_hb.f, the calling program;
• d_sample_hb.sh, commands to compile, link and run the calling program;
• d_sample_hb_output.txt, the sample output.

D_SAMPLE_ST reads a 5x5 matrix from a file in Sparse Triplet (ST) format, into compressed column (CC) format, and then uses DGSSV to solve the linear system. Double precision real arithmetic is used.

• d_sample_st.f, the calling program;
• d_sample_st.sh, commands to compile, link and run the calling program;
• d_sample_st_output.txt, the sample output.

S_SAMPLE uses SGSSV to solve a 5x5 system. Single precision real arithmetic is used.

• s_sample.f, the calling program;
• s_sample.sh, commands to compile, link and run the calling program;
• s_sample_output.txt, the sample output.

S_SAMPLE_HB reads a 5x5 matrix from a file in Harwell-Boeing (HB) format, into compressed column (CC) format, and then uses SGSSV to solve the linear system. Single precision real arithmetic is used.

• s_sample_hb.f, the calling program;
• s_sample_hb.sh, commands to compile, link and run the calling program;
• s_sample_hb_output.txt, the sample output.

S_SAMPLE_ST reads a 5x5 matrix from a file in Sparse Triplet (ST) format, into compressed column (CC) format, and then uses SGSSV to solve the linear system. Single precision real arithmetic is used.

• s_sample_st.f, the calling program;
• s_sample_st.sh, commands to compile, link and run the calling program;
• s_sample_st_output.txt, the sample output.

Z_SAMPLE uses ZGSSV to solve a 5x5 system. Double precision complex arithmetic is used.

• z_sample.f, the calling program;
• z_sample.sh, commands to compile, link and run the calling program;
• z_sample_output.txt, the sample output.

Z_SAMPLE_HB reads a 5x5 matrix from a file in Harwell-Boeing (HB) format, into compressed column (CC) format, and then uses ZGSSV to solve the linear system. Double precision complex arithmetic is used.

• z_sample_hb.f, the calling program;
• z_sample_hb.sh, commands to compile, link and run the calling program;
• z_sample_hb_output.txt, the sample output.

Z_SAMPLE_ST reads a 5x5 matrix from a file in Sparse Triplet (ST) format, into compressed column (CC) format, and then uses ZGSSV to solve the linear system. Double precision complex arithmetic is used.

• z_sample_st.f, the calling program;
• z_sample_st.sh, commands to compile, link and run the calling program;
• z_sample_st_output.txt, the sample output.

You can go up one level to the FORTRAN77 source codes.