# 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.