2.5 ACML FORTRAN and C interfaces

All routines in ACML come with both FORTRAN and C interfaces. The FORTRAN interfaces typically follow the relevant standard (e.g. LAPACK, BLAS). Here we document how a C programmer should call ACML routines.

In C code that uses ACML routines, be sure to include the header file <acml.h>, which contains function prototypes for all ACML C interfaces. The header file also contains C prototypes for FORTRAN interfaces, thus the C programmer could call the FORTRAN interfaces from C, though there is little reason to do so.

C interfaces to ACML routines differ from FORTRAN interfaces in the following major respects:

• The FORTRAN interface names are appended by an underscore (except for the Windows 32-bit Microsoft C/Intel Fortran version of ACML, where FORTRAN interface names are distinguished from C by being upper case rather than lower case - this is the default for the Intel Fortran compiler)
• The C interfaces contain no workspace arguments; all workspace memory is allocated internally.
• Scalar input arguments are passed by value in C interfaces. FORTRAN interfaces pass all arguments (except for character string length arguments that are normally hidden from FORTRAN programmers) by reference.
• Most arguments that are passed as character string pointers to FORTRAN interfaces are passed by value as single characters to C interfaces. The character string length arguments of FORTRAN interfaces are not required in the C interfaces.
• Unlike FORTRAN, C has no native complex data type. ACML C routines which operate on complex data use the types complex and doublecomplex defined in <acml.h> for single and double precision computations respectively. Some of the programs in the ACML examples directory (see Examples) make use of these types.

It is important to note that in both the FORTRAN and C interfaces, 2-dimensional arrays are assumed to be stored in column-major order. e.g. the matrix

             A = ( 1.0 2.0 )
                 ( 3.0 4.0 )

would be stored in memory as 1.0, 3.0, 2.0, 4.0. This storage order corresponds to a FORTRAN-style 2-D array declaration A(2,2), but not to an array declared as a[2][2] in C which would be stored in row-major order as 1.0, 2.0, 3.0, 4.0.

As an example, compare the FORTRAN and C interfaces of LAPACK routine dsytrf as implemented in ACML.

FORTRAN:

       void dsytrf_(char *uplo, int *n, double *a, int *lda, int *ipiv,
                    double *work, int *lwork, int *info, int uplo_len);

C:

       void dsytrf(char uplo, int n, double *a, int lda, int *ipiv,
                   int *info);

C code calling both the above variants might look like this:

       double *a;
       int *ipiv;
       double *work;
       int n, lda, lwork, info;
     
       /* Assume that all arrays and variables are allocated and
          initialized as required by dsytrf. */
     
       /* Call the FORTRAN version of dsytrf. The first argument
          is a character string, and the last argument is the
          length of that string. The input scalar arguments n, lda
          and lwork, as well as the output scalar argument info,
          are all passed by reference. */
       dsytrf_("Upper", &n, a, &lda, ipiv, work, &lwork, &info, 5);
     
       /* Call the C version of dsytrf. The first argument is a
          character, workspace is not required, and input scalar
          arguments n and lda are passed by value. Output scalar
          argument info is passed by reference. */
       dsytrf('U', n, a, lda, ipiv, &info);