Calling Fortran functions from C++ by means of shared libraries

Refer to: http://collaboration.cmc.ec.gc.ca/science/rpn/biblio/ddj/Website/articles/CUJ/2004/0401/0401weiguo/0401weiguo.htm

        Even though C++ is the programming language of choice for systems and business applications, Fortran still has a strong presence in scientific and engineering computation. In practice, programming in C++ and Fortran lets you make use of existing Fortran code bases, which are valuable resources and may significantly accelerate development.

        While it is possible to call Fortran functions from C++, C++ (unlike C) provides features that support passing by reference as arguments, complex data types, and the like. By using proper definitions of Fortran data types and functions in C++, you can compile and link Fortran functions with C++ code using C++ compilers. This technique has been discussed by Carsten Arnholm (http://home.online.no/~arnholm/cppf77.htm).

        In this article, I present another way to call Fortran functions in C++. This approach is to compile Fortran functions separately into shared libraries, then explicitly call them in C++ from the shared libraries. Of course, this method is not 100-percent portable — shared libraries compiled on one platform may not be used in another one. However, it is still portable because Linux and other operating systems support shared libraries, and there are system API functions available to make use of the shared libraries. The major advantage of this method is that Fortran code can be separated from C++ code, letting C++ developers use native C++ data types to call Fortran functions. And since there is no need for you to include additional header files, development and maintenance can also be separated. This increases the code modularity and reusability. Source code that implements this technique for both Windows and Linux is available at http://www.cuj.com/code/.

About the Data Types

        Fortran has a long history in scientific computation. Hitherto now, there exist several Fortran standards, known as Fortran 66/77/90/95/2000. Since most of the existing Fortran codes comply with Fortran 77 (F77) Standard, I'll only address calling of the F77 functions in C++ via shared libraries.

        Basically, there are six data types in F77 Standard, namely, INTEGER,REAL,DOUBLE PRECISION,COMPLEX,LOGICAL,CHARACTER [*n], wheren is the optional string length (in the range 1 to 32767). Most of these data types have their direct counterparts in basic C++ data types, except forCOMPLEX andCHARACTER.

        In C++, complex numbers are supported in the Standard Library rather than the core language. C++'s complex number class can be directly passed to F77 functions. Returning complex values from F77 functions may be different, since this is compiler-dependent behavior. (Here, I use GNU g77 as the F77 compiler.) However, C++'s complex class can also be directly used to hold the returned complex values from F77 functions.

        Because of the different ways of handling string lengths in F77 and C++, as well as the different ways of passing strings as function parameters,CHARACTER is another special data type. The C++CHARACTER class can also be directly passed to F77 functions. However, returningCHARACTER values from F77 functions is not supported by the method I present here.

        Fortran supports multidimensional arrays. Passing one-dimensional arrays is easy, and C++ pointers can be directly passed to Fortran functions. Multidimensional arrays, however, need special attention because Fortran stores array elements in a "column-first" fashion, while C++ uses "row-first" convention. Carsten Arnholm refers to a class calledFMATRIX, which can be used to convert a C++ matrix (two-dimensional array) to an F77 matrix. However, it also does not work in the method I present here. Instead, I treat multidimensional arrays as one-dimensional arrays; that is, one-dimensional C++ arrays are used and data of multidimensional arrays are rearranged to conform with the column-first rule. Then, the corresponding C++ pointers to the one-dimensional arrays are passed to call the F77 functions.

        Function pointers are another useful type of function arguments. This is particularly important in scientific and engineering computations. For instance, a function pointer is useful in the numerical integration routines where the algorithm can be implemented in a function, which takes the integrand and boundaries as the arguments. This is better than hard-coding the function with the algorithm. In F77, a function or subroutine can take another external function's name as an argument, and call that external function inside of itself. In C++, this can be done by using function pointers. It has been found that C++ function pointers can be directly passed to F77 functions.

DLLs and Shared Libraries

        Libraries are collections of object files, which can be statically or dynamically linked with the executable files. Dynamically linked libraries (DLLs) are one of the most important aspects of Windows. Shared libraries (or shared objects), on the other hand, are used in Linux and other UNIX-like operating systems. Neither DLLs nor shared libraries are native to C++ or F77--they are system-dependent techniques.

        There are basically two ways to link DLLs or shared libraries with executable files — implicit and explicit linking. Implicit linking is like static linking of libraries, except that implicit linking of shared libraries loads code upon startup. Explicit linking loads code while the program is running.

With explicit linking, programs do not need to know the name of the library upon startup, giving the program more flexibility. In this article, I'll show how to explicitly link F77 shared libraries in C++ programs.

        Explicit linking of DLLs on Windows can be performed by using the Windows API functionsLoadLibrary(),GetProcAddress(), andCloseLibrary{}. On Linux or Solaris (or perhaps other UNIX systems), explicit linking can be done via the API functionsdlopen(),dlsym(), anddlclose().

        In the following examples, I use the GNU Fortran g77 compiler to compile F77 files into shared libraries. On Windows XP Pro, I use g77 in MingW 2.0. The DLLfoo.dll is created fromfoo.for using the commands:

g77 -fno-f2c -shared -s -o foo.dll foo.for

        On Red Hat Linux 8.0, I use g77 in GCC 3.2 to create the shared libraries by using the same command options:

g77 -fno-f2c -shared -s -o foo.so foo.for

        C++ programs can then dynamically load the shared libraries. In the following examples, I use the freely available Borland command-line C++ compiler and g++ to compile the C++ programs on Windows and Linux, respectively.

Examples

        My first example illustrates how to pass a single argument to an F77 function.Listing 1 (ex1.for) is F77 code that defines a function with a REAL type input (x) and returns the value of2*x.Listing 2 is the C++ test file on Windows. The LoadLibrary() function dynamically loads ex1.dll, which was compiled from the F77 code. ex1.dll can be in the same directory as the C++ program, or any directory defined by thePATH environmental variable. Then GetProcAddress() finds the function to be run in the ex1.dll. Because of "name decoration," g77 adds an underscore after the name of the function in the shared library. Also, F77 function arguments are passed by reference; therefore, in ex1win.cpp (Listing 2) the float type argument is passed by reference to the function foo_(). After getting the address of the function, one can call the function as you would a normal function. Finally,FreeLibrary() unloads the DLL from the address space of the calling process.

         Listing 3 (ex1lnx.cpp) is the C++ file inListing 2 on Linux. You can create a shared library ex1.so from the F77 file ex1.for and put ex1.so in the same path as the C++ file (ex1.so can also be in a path defined byLD_LIBRARY_PATH). On Linux, you use the different API functions to dynamically load the function. The functions I use here are defined in dlfcn.h file. In this program,dlopen() opens ex1.so.dlsym() retrieves function's address, anddlclose() unloads the library. When ex1lnx.cpp (Listing 3) is compiled, it should be linked with DLL; for example:

g++ -o ex1lnx ex1lnx.cpp -ldl

        Otherwise, there will be undefined references errors.

        The second example is about complex numbers. Listing 4 shows the F77 function, which takes one COMPLEX input,x, and returns aCOMPLEX result of2*x. The DLL and shared library are ex2.dll on Windows and ex2.so on Linux.Listing 5 (ex2win.cpp) is the C++ file of Listing 2 on Windows, and Listing 6 (ex2lnx.cpp) is the C++ file on Linux. You can see that in C++, the complex class can be used almost as easily as other data types such asdouble orfloat. Just like the first example, the C++ complex variable should also be passed by reference into the F77 function.

        Listing 7 is the F77 subroutine, which calculates the dot product of two arrays, and saves the result in another array. The shared libraries are ex3.dll on Windows and ex3.so on Linux.Listing 8 (ex3win.cpp) is the C++ file on Windows, and Listing 9 (ex3lnx.cpp) is the C++ file on Linux. In this case, C++ pointers are passed for F77 arrays.

        The fourth example deals with function pointers that are useful in scientific computations. The F77 function inListing 10 has two arguments: one is an external function name, the other a REAL type. The function evaluates the external function at the given argument and returns the result.

        The shared libraries are ex4.dll on Windows and ex4.so on Linux. Listings 11 (ex4win.cpp) and 12 (ex4lnx.cpp) are the C++ files on Windows and Linux, respectively. In this case, a C++ function pointer can be directly passed for an F77 function name. The C++ function to be evaluated in the F77 function should be defined in such a way that it takes references of data.

        The last example is about Muller's method and demonstrates this calling method. This method can be used to find any number of roots (real and/or complex) of an arbitrary function. The source code was written in F77 and can be found athttp://www.netlib.org/. The definition of the functionmuller() is:

subroutine muller (f,eps,nsig,kn,nguess,n,x,itmax,infer,ier)
implicit double precision (a-h,o-z)
dimension x(1),infer(1)

        In the argument list, f is an external function whose roots will be saved inx.

        The shared libraries are muller.dll on Windows and muller.so on Linux.Listings 13 (ex5win.cpp) and 14 (ex5lnx.cpp) show the C++ files on Windows and Linux, respectively. In C++ files, the same functionmyFunc() is defined, which is simply a polynomial inx, made by the tenth power of(x-1). Therefore, the actual roots of this functions are ten 1s. Don't be surprised if the results differ from the analytical ones — it is a tough numerical problem to find roots of such a polynomial. In fact, Muller's method does a good job. To call themuller_() function in the shared libraries, a function pointer should be defined in the C++ files, just like the previous examples. In C++ files, pointers can be passed to F77 arrays, and single variables must be passed by references.

Conclusion

        The technique I've presented here for calling Fortran functions from C++ via shared libraries is not completely portable on different operating systems. The major advantage of this method is that the source codes of Fortran and C++ can be separated. As demonstrated in the examples, you can use the native data types in C++ when dynamically calling the F77 functions, giving you much more flexibility.