Department of Mathematics - University of Utah

HomeComputingCourse SchedulesCSMECurrent PositionsFAQ (Computing)FormsGraduateHigh SchoolLecture VideosMailbox AccessMath BiologyMath EducationNewsletterPeopleResearchRTG GrantsSeminars

Linking LAPACK and BLAS libraries with Fortran and C/C++ code

Last update: Mon Sep 22 18:34:37 2003

Comments, and reports of errata or bugs, are welcome via e-mail to the author, Nelson H. F. Beebe <beebe@math.utah.edu>. In your report, please supply the full document URL, and the title and Last update time stamp recorded near the top of the document.

Table of contents


Documentation for LAPACK

There is locally-provided online documentation for LAPACK inside the GNU Emacs info system. In emacs, type C-h i to enter the info system, then type MLocal and MLAPACK. You can do the same thing in the standalone xinfo viewer. That documentation is also available in HTML form for Web browsers.

The standard reference manual for LAPACK has appeared in three editions:

@String{pub-SIAM     = "Society for Industrial
                       and Applied Mathematics"}
@String{pub-SIAM:adr = "Philadelphia, PA, USA"}

@Book{Anderson:1992:LUG,
  author =       "E. Anderson and Z. Bai and C. Bischof and 
                 J. Demmel and J. Dongarra and J. {Du Croz} and
                 A. Greenbaum and S. Hammarling and A. McKenney and
                 S. Ostrouchov and D. Sorenson",
  title =        "{LAPACK} Users' Guide",
  publisher =    pub-SIAM,
  address =      pub-SIAM:adr,
  pages =        "xv + 235",
  year =         "1992",
  ISBN =         "0-89871-294-7",
  LCCN =         "QA76.73.F25 L36 1992",
  bibdate =      "Tue Dec 14 22:36:17 1993",
}

@Book{Anderson:1995:LUG,
  author =       "E. Anderson and Z. Bai and C. Bischof and S. Blackford
                 and J. Demmel and J. Dongarra and J. Du Croz and A.
                 Greenbaum and S. Hammarling and A. McKenney and D.
                 Sorensen",
  title =        "{LAPACK} Users' Guide",
  publisher =    pub-SIAM,
  address =      pub-SIAM:adr,
  edition =      "Second",
  pages =        "xix + 325",
  year =         "1995",
  ISBN =         "0-89871-345-5",
  LCCN =         "QA76.73.F25 L36 1995",
  bibdate =      "Thu Sep 19 07:23:11 2002",
  libnote =      "Not yet in my library.",
  xxnote =       "Check authors. Library catalogs only show first.",
}

@Book{Anderson:1999:LUG,
  author =       "E. Anderson and Z. Bai and C. Bischof and S. Blackford
                 and J. Demmel and J. Dongarra and J. Du Croz and A.
                 Greenbaum and S. Hammarling and A. McKenney and D.
                 Sorensen",
  title =        "{LAPACK} Users' Guide",
  publisher =    pub-SIAM,
  address =      pub-SIAM:adr,
  edition =      "Third",
  pages =        "xxi + 407",
  year =         "1999",
  ISBN =         "0-89871-447-8",
  LCCN =         "QA76.73.F25 L36 1999",
  libnote =      "Not yet in my library.",
  bibdate =      "Thu Sep 19 07:23:11 2002",
}

Linking with locally-installed libraries

Because of the problems documented below in using vendor-provided LAPACK libraries, LAPACK and its associated BLAS (Basic Linear Algebra Subroutines) library have been installed separately on all local systems, so that Fortran code can be (almost) uniformly linked like this:

    f77 -o fcode fcode.f -L/usr/local/lib -llapack -lblas

f77 can be replaced by g77, f90, f95, fort, pgf77, pgf90, pghpf, xlf, xlf90, xlf90_r , xlf90_r7, xlf95, xlf95_r, xlf95_r7, xlf_r, or xlf_r7, where available.

The C version of LAPACK, CLAPACK, which is produced automatically from the Fortran sources by the f2c translator, is also available, allowing C code to be linked like this:

    cc -o ccode ccode.c -L/usr/local/lib -lclapack -lcblas -lctmg -lf2c

The -lctmg library may not be needed. Although the code is in C, the internals behave like Fortran with respect to calling conventions, array storage order, and array indexing. Considerable care is therefore needed.

Specific information on use of CLAPACK is available in the Netlib archives, and general information on using C/C++ and Fortran together is available here.

All build logs are preserved in

    /usr/local/math/LAPACK/logs/Typescript.*
    /usr/local/math/LAPACK/CLAPACK/logs/Typescript.*

There are regrettably a few unavoidable exceptions to the above simple recipe that are necessary if the compiler is not f77, or if the memory model is not the default, or if there is more than one version of the libraries:

Caveat: The LAPACK code on all systems has been compiled with -O optimization, and the LAPACK test suites have not yet been run.

Vendor-provided libraries are likely to have been compiled with high optimization levels, and in some cases, may be replaced by assembly-coded routines with even higher performance. They are also likely to have received extensive testing.


Linking with NAG libraries

Using the NAG libraries is documented separately.

Linking with vendor-provided libraries

Most commercial UNIX vendors now provide optimized versions of the LAPACK (and often also LINPACK and EISPACK) libraries, but alas, the library names and locations are vendor dependent.

We also have the commercial NAG libraries installed on all local architectures for which they are available. Those libraries include all of EISPACK, LINPACK, LAPACK, and the BLAS.

On some systems, it is even more complex, because the libraries have been built for Fortran 77 use in one version, and for Fortran 90 in a later version.

Complexity is increased yet again when C code is linked against these libraries, because

The various GNU/Linux distributions for Apple/IBM PowerPC, Compaq/DEC Alpha, Intel x86, and Sun SPARC do not come with LAPACK support.

In a Makefile for C and Fortran code, you might have something like this:

DEFINES         =
INCLUDES        = -I/usr/local/include
OPT             = -O
CFLAGS          = $(OPT) $(INCLUDES) $(DEFINES)
CLIBS           = -lm

# Systems with NAG library:
FLIBS           = -lnag

# GNU/Linux Intel x86 systems with Portland Group compilers (pgcc,
# pgCC, pgf77, pgf90, pghpf):
CLIBS           = -lpgftnrtl -lm -lpgc -lgcc
FLIBS           = -llapack -lblas

# Compaq/DEC Alpha OSF/1 4.0:
FLIBS           = -lsciport -ldxml

# IBM AIX 4.3:
FLIB            = -lessl
FC              = f77

# SGI IRIX 6.5:
FLIBS           = -lcomplib.sgimath
FC              = f77

# Sun Solaris 2.7 with /opt/SUNWspro/SC5.0/lib
FLIBS           = -L/opt/SUNWspro/SC5.0/lib -lsunperf -lF77 -lM77 -lsunmath -lm
FC              = f77

# Sun Solaris 2.[78] with /opt/SUNWspro/WS6U1 (compiled with Fortran 90)
SUNLIB          = -L/opt/SUNWspro/WS6U1/lib -L/opt/SUNWspro/lib
F90LIBS         = $(SUNLIB) -lsunperf -lfui -lfai -lfai2 -lfsumai \
                  -lfprodai -lfminlai -lfmaxlai -lfminvai -lfmaxvai -lfsu
FLIBS           = $(SUNLIB) -lsunperf -lsunmath -lm
FC              = f90

# Sun Solaris 2.[78] with /opt/SUNWspro/WS6U2 (compiled with Fortran 90)
SUNLIB          = -L/opt/SUNWspro/WS6U2/lib -L/opt/SUNWspro/lib
F90LIBS         = $(SUNLIB) -lsunperf -lfui -lfai -lfai2 -lfsumai \
                  -lfprodai -lfminlai -lfmaxlai -lfminvai -lfmaxvai -lfsu
FLIBS           = $(SUNLIB) -lsunperf -lsunmath -lm
FC              = f90

ccode:    ccode.o
        $(CC) $(CFLAGS) -o ccode ccode.o $(FLIBS) $(CLIBS) $(LDFLAGS)

ccode.o:        ccode.c
        $(CC) $(CFLAGS) -c ccode.c

fcode:    fcode.o
        $(FC) -o fcode fcode.o $(FLIBS) $(LDFLAGS)

Shared vendor libraries are a nuisance if gcc, g++, or g77 are used, because those compilers do not know about the location of some vendor-provided libraries, and except on IBM AIX, most UNIX linkers regrettably do not by default record the location of libraries used at link time. This means that even if linking succeeds, your program may fail to run because the run-time loader cannot find the necessary libraries.

One solution is to define the environment variable LD_LIBRARY_PATH (or LPATH on Hewlett-Packad HP-UX) to a colon-separated list of shared-library directory paths. This is hardly satisfactory, since each user who runs that executable must do the same, and, on SGI IRIX 6.x systems, there are three variants of that variable, depending on the memory model chosen.

A better solution to this problem is to supply additional flags that instruct the linker to record the shared-library paths in the executable program. Unfortunately, these flags are highly compiler dependent (and not needed at all on IBM AIX):

### Compaq/DEC compilers:
LDFLAGS         = -Wl,-rpath directory-path
### Gnu compilers:            
LDFLAGS         = -Wl,-rpath directory-path
### SGI compilers:
LDFLAGS         = -YL,directory-path
### Sun compilers:            
LDFLAGS         = -R directory-path

Only one directory can be specified with each option, so you might need to do something like this:

LDFLAGS         = -Wl,-rpath /opt/SUNWspro/WS6U2/lib \
                  -Wl,-rpath /opt/SUNWspro/lib

On some UNIX systems, you can use the ldd command to check whether your executable has recorded the location of all needed libraries (taking care to undefine LD_LIBRARY_PATH for the duration of the command):

% env LD_LIBRARY_PATH= ldd fcode
        libF77.so.4 =>   /opt/SUNWspro/lib/libF77.so.4
        libM77.so.2 =>   /opt/SUNWspro/lib/libM77.so.2
        libsunmath.so.1 =>       /opt/SUNWspro/lib/libsunmath.so.1
        libm.so.1 =>     /opt/SUNWspro/lib/libm.so.1
        libc.so.1 =>     /usr/lib/libc.so.1
        libdl.so.1 =>    /usr/lib/libdl.so.1
        /usr/platform/SUNW,Ultra-Enterprise/lib/libc_psr.so.1

On others, you'll merely be told at run time that a certain library cannot be found, sigh...


Related libraries: LINPACK and EISPACK

Here is some old related mail:

Date: Thu, 12 Apr 2001 08:58:11 -0600 (MDT)
From: "Nelson H. F. Beebe" <beebe@math.utah.edu>
To: Peter Alfeld <alfeld@math.utah.edu>
Subject: Re: linpack

>> do we have a double precision version of LINPACK?

Yes: unlike EISPACK, which used the same names for single and double precision, preventing using both flavors in one program, LINPACK and LAPACK both use a naming convention that identifies the precision:

>From the emacs info path Local -> Linpack -> NAMING-CONVENTIONS:

        NAMING-CONVENTIONS
         A subroutine naming  convention is  employed in  which each  subroutine
         name  is  a  coded  specification  of  the  computation  done  by  that
         subroutine.  All names consist of five  letter in the form TXXYY.   The
         first letter,  T, indicates  the matrix  data type.   Standard  FORTRAN
         allows the use of three such types:

                S       REAL
                D       DOUBLE PRECISION
                C       COMPLEX

         In addition,  some FORTRAN  systems (alas,  NOT the  DEC-20!)  allow  a
         double precision complex type:

                Z       COMPLEX*16

Thus, if you had the source code for sgeco.f, the double-precision version would be dgeco.f.

LINPACK sources are in /usr/local/math/linpack/, and each system has -llinpack available for linking.

I haven't done that for LAPACK, but most vendors have tuned LAPACK implementations available:

    GNU/Linux on Intel IA-32 (Red Hat 8 or later)    -llapack -lblas
    GNU/Linux on DEC Alpha                           -lcxml
    Sun Solaris                                      -lsunmath
    SGI IRIX                                         -lcomplib.sgimath
    Compaq/DEC OSF/1                                 -ldxml and -lsciport
    IBM AIX                                          -lessl

We don't have such a standard library on GNU/Linux systems, but the Portland Group compilers (pgcc, pgCC, pghpf, pgf77, and pgf90) provide -llapack on wasatch.math.utah.edu, a 600MHz dual-CPU Intel x86 Pentium III system. Also, on all systems, we have -lnag, which includes LAPACK. In most cases, we can expect that the vendor implementations of LAPACK include highly-tuned BLAS levels 1, 2, and 3, to produce better performance than a straightforward Fortran LAPACK compilation could produce. IBM's ESSL is a shining example of this: you might enjoy reading this new article which is available in PDF form at the URL cited.

    @String{j-IBM-JRD = "IBM Journal of Research and Development"}

    @Article{Gustavson:2000:MSH,
      author =       "F. G. Gustavson and I. Jonsson",
      title =        "Minimal-storage high-performance {Cholesky}
                     factorization via blocking and recursion",
      journal =      j-IBM-JRD,
      volume =       "44",
      number =       "6",
      pages =        "823--850",
      month =        nov,
      year =         "2000",
      CODEN =        "IBMJAE",
      ISSN =         "0018-8646",
      bibdate =      "Sat Feb 24 09:44:45 MST 2001",
      bibsource =    "http://www.research.ibm.com/journal/",
      URL =          "http://www.research.ibm.com/journal/rd/446/gustavson.html",
      acknowledgement = ack-nhfb,
      ordernumber =  "G322-0224",
    }

You should also look at http://www.math.utah.edu/software


Dept Info Outreach College of Science Newsletter

Department of Mathematics
University of Utah
155 South 1400 East, JWB 233
Salt Lake City, Utah 84112-0090
Tel: 801 581 6851, Fax: 801 581 4148
Webmaster


Entire Web                     Only http://www.math.utah.edu/