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

