# readme for CLAPACK # ================== # This directory contains the C version of LAPACK. # Individual routines, as well as a tar file of the complete # package, are available. # # The information below describes how CLAPACK was created and how # it may be used. # # ====================================================================== # # The CLAPACK library was built using a Fortran to C conversion utility # called f2c. The entire Fortran 77 LAPACK library is run through f2c to # obtain C code, and then modified to improve readability. CLAPACK's goal # is to provide LAPACK for someone who does not have access to a Fortran # compiler. # # However, f2c is designed to create C code that is still callable from # Fortran, so all arguments must be passed using Fortran calling # conventions and data structures. This requirement has several # repercussions. The first is that since many compilers require distinct # Fortran and C routine namespaces, an underscore (_) is appended to C # routine names which will be called from Fortran. Therefore, f2c has added # this underscore to all the names in CLAPACK. So, a call that in Fortran # would look like: # # call dgetrf(...) # # becomes in C: # # dgetrf_(...); # # Second, the user must pass ALL arguments by reference, i.e. as pointers, # since this is how Fortran works. This includes all scalar arguments # like M and N. This restriction means that you cannot make a # call with numbers directly in the parameter sequence. For example, # consider the LU factorization of a 5-by-5 matrix. If the matrix to # be factored is called A, the Fortran call # # call dgetrf(5, 5, A, 5, ipiv, info) # # becomes in C: # # M = N = LDA = 5; # dgetrf_(&M, &N, A, &LDA, ipiv, &info); # # # Some LAPACK routines take character string arguments. In all but the # testing and timing code, only the first character of the string is # signficant. Therefore, the CLAPACK driver, computational, and auxiliary # routines only expect single character arguments. For example, the Fortran # call # # call dpotrf( 'Upper', n, a, lda, info ) # # becomes in C: # # char s = 'U'; # dpotrf_(&s, &n, a, &lda, &info); # # In a future release we hope to provide ``wrapper'' routines that will # remove the need for these unnecessary pointers, and automatically # allocate (``malloc'') any workspace that is required. # # As a final point, we must stress that there is a difference in the definition # of a two-dimensional array in Fortran and C. # A two-dimensional Fortran array declared as # # DOUBLE PRECISION A(LDA, N) # # is a contiguous piece of LDA X N double-words of memory, stored in # column-major order: elements in a column are contiguous, and elements # within a row are separated by a stride of LDA double-words. # # In C, however, a two-dimensional array is in row-major order. Further, the # rows of a two-dimensional C array need not be contiguous. The array # # double A[LDA][N]; # # actually has LDA pointers to rows of length N. # These pointers can in principle be anywhere in memory. Passing such a # two-dimensional C array to a CLAPACK routine will almost surely give # erroneous results. # # Instead, you must use a one-dimensional C array of size LDA X N # double-words (or else malloc the same amount of space). # We recommend using the following code to get the array CLAPACK will be # expecting: # # double *A; # A = malloc( LDA*N*sizeof(double) ); # # Note that for best memory utilization, you would set LDA=M, the # actual number of rows of A. If you now wish to operate on the # matrix A, remember that A is in column-major order. As an example of # accessing Fortran-style arrays in C, the following code fragments show # how to initialize the array A declared above so that # all of column j has the value j: # # double *ptr; # ptr = A; # for(j=0; j < N; j++) # { # for (i=0; i < M; i++) *ptr++ = j; # ptr += (LDA - M); # } # # or, you can use: # # for(j=0; j < N; j++) # { # for (i=0; i < M; i++) A[j*LDA+i] = j; # } # # Note that the loop over the row index i is the inner loop, since column # entries are contiguous.