double precision
and integer
types can be used
without any modification. For single precision, a conversion is necessary
for vector and matrix types, because PROFIL uses double precision for the
REAL
type internally. This can be changed in the configuration file.
See section Basic Operations and Types, for details.
The conversion between single and double precision types is beyond the scope of this short documentation and because of this left out here. It is assumed that the reader is familiar with building and using own libraries.
The general steps to use FORTRAN library functions with PROFIL are:
Throughout this description we use the computation of the eigenvalues of
a symmetric real matrix as an example (the FORTRAN routine is RSM
from EISPACK). We assume that all FORTRAN routines belonging to RSM
are converted to C and a library called libRSM.a has been built from
this set of routines.
The parameter description of the FORTRAN RSM
subroutine is given
below (taken from the EISPACK rsm.f file).
subroutine rsm(nm,n,a,w,m,z,fwork,iwork,ierr) c integer n,nm,m,iwork(n),ierr integer k1,k2,k3,k4,k5,k6,k7 double precision a(nm,n),w(n),z(nm,m),fwork(1) c c this subroutine calls the recommended sequence of c subroutines from the eigensystem subroutine package (eispack) c to find all of the eigenvalues and some of the eigenvectors c of a real symmetric matrix. c c on input c c nm must be set to the row dimension of the two-dimensional c array parameters as declared in the calling program c dimension statement. c c n is the order of the matrix a. c c a contains the real symmetric matrix. c c m the eigenvectors corresponding to the first m eigenvalues c are to be computed. c if m = 0 then no eigenvectors are computed. c if m = n then all of the eigenvectors are computed. c c on output c c w contains all n eigenvalues in ascending order. c c z contains the orthonormal eigenvectors associated with c the first m eigenvalues. c c ierr is an integer output variable set equal to an error c completion code described in the documentation for tqlrat, c imtqlv and tinvit. the normal completion code is zero. c c fwork is a temporary storage array of dimension 8*n. c c iwork is an integer temporary storage array of dimension n. c
This header is converted by f2c into the following C header, which can be used by PROFIL routines:
extern "C" { int rsm_(PINT nm, PINT n, PREAL a, PREAL w, PINT m, PREAL z, PREAL fwork, PINT iwork, PINT ierr); }
The leading P of the types denotes a pointer to the appropriate type, because FORTRAN always uses reference parameters.
Assuming that we want to create a PROFIL subroutine which returns a vector containing the eigenvalues of its matrix argument, the header would be
VECTOR Eigenvalues (MATRIX & A)
To use the PROFIL vectors and matrices as FORTRAN subroutine parameters, the
extension theElements must be appended with a separating dot to the vector or
matrix name. Additionally, all vector and matrix types must be correctly
sized before calling the converted FORTRAN routine. For the small example discussed
here, the complete implementation of the subroutine Eigenvalues
might look like:
VECTOR Eigenvalues (MATRIX & A) // Computes and returns all eigenvalues of the symmetric matrix A { INT nm = RowDimension (A); INT n = ColDimension (A); VECTOR e(n); VECTOR fwork(8 * n); INTEGER_VECTOR iwork(n); INT ierr, m = 0;// No symmetry check is performed!! rsm_ (& nm, & n, A.theElements, e.theElements, & m, NULL, fwork.theElements, iwork.theElements, & ierr); if (ierr) Error ("Something is wrong in eigenvalue computation", ierr, ErrorHandler::SevereError); return e; }