Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Calling PDE Support Routines from Fortran

The calling interface for all the Intel® oneAPI Math Kernel Library (oneMKL) TT and Poisson Solver routines is designed to be easily used in C. However, you can invoke each TT or Poisson Solver routine directly from Fortran 90 or higher if you are familiar with the inter-language calling conventions of your platform.

The TT or Poisson Solver interface cannot be invoked from FORTRAN 77 due to restrictions imposed by the use of the Intel® oneAPI Math Kernel Library (oneMKL) FFT interface.

The inter-language calling conventions include, but are not limited to, the argument passing mechanisms for the language, the data type mappings from C to Fortran, and how C external names are decorated on the platform.

To promote portability and relieve you of dealing with the calling conventions specifics, the Fortran header file mkl_trig_transforms.f90 for TT routines and mkl_poisson.f90 for Poisson Solver routines, used together with mkl_dfti.f90, declare a set of macros and introduce type definitions intended to hide the inter-language calling conventions and provide an interface to the routines that looks natural in Fortran.

For example, consider a hypothetical library routine, foo, which takes a double-precision vector of length n. C users access such a function as follows:

MKL_INT n; 
  double *x; 
  … 
  foo(x, &n);

As noted above, to invoke foo, Fortran users would need to know what Fortran data types correspond to C types MKL_INT and double (or float for single-precision), what argument-passing mechanism the C compiler uses and what, if any, name decoration is performed by the C compiler when generating the external symbol foo. However, with the Fortran header files mkl_trig_transforms.f90 / mkl_poisson.f90 and mkl_dfti.f90 included, the invocation of foo within a Fortran program will look as follows for the LP64 interface (for the ILP64 interface, INTEGER*8 type will be used instead of INTEGER*4):

  • For TT interface,
    use mkl_dfti 
    use mkl_trig_transforms 
    INTEGER*4 n 
    DOUBLE PRECISION, ALLOCATABLE :: x 
    … 
    CALL FOO(x,n)
          
  • For Poisson Solver interface,
    use mkl_dfti 
    use mkl_poisson 
    INTEGER*4 n 
    DOUBLE PRECISION, ALLOCATABLE :: x 
    … 
    CALL FOO(x,n) 
        

Note that in the above example, the header files mkl_trig_transforms.f90 / mkl_poisson.f90 and mkl_dfti.f90 provide a definition for the subroutine FOO. To ease the use of Poisson Solver or TT routines in Fortran, the general approach of providing Fortran definitions of names is used throughout the libraries. Specifically, if a name from a Poisson Solver or TT interface is documented as having the C-specific name foo, then the Fortran header files provide an appropriate Fortran language type definition FOO.

One of the key differences between Fortran and C is the language argument-passing mechanism: C programs use pass-by-value semantics and Fortran programs use pass-by-reference semantics. The Fortran headers ensure proper treatment of this difference. In particular, in the above example, the header files mkl_trig_transforms.f90 / mkl_poisson.f90 and mkl_dfti.f90 hide the difference by defining a macro FOO that takes the address of the appropriate arguments.