Zoltan User's Guide  |  Next  |  Previous

FORTRAN Interface

The Fortran interface for Zoltan is a Fortran 90 interface designed similar to the Fortran 90 Bindings for OpenGL [Mitchell]. There is no FORTRAN 77 interface; however, FORTRAN 77 applications can use Zoltan by adding only a few Fortran 90 statements, which are fully explained in the section on FORTRAN 77, provided that vendor-specific extensions are not heavily used in the application. This section describes how to build the Fortran interface into the Zoltan library, how to call Zoltan from Fortran applications, and how to compile Fortran applications that use Zoltan. Note that the capitalization used in this section is for clarity and need not be adhered to in the application code, since Fortran is case insensitive.

FORTRAN: Compiling Zoltan

Including the Fortran interface in the Zoltan library requires an additional option on the autotools configure or CMake command:
Autotools option: --enable-f90interface
CMake option: -D Zoltan_ENABLE_F90INTERFACE:BOOL=ON
Before compiling the library, make sure that the application's zoltan_user_data.f90 has been placed in the zoltan/src/fort/ directory, if needed.

FORTRAN: Compiling Applications

To compile a Fortran application using the Zoltan library, the module information files must be made available to most compilers during the compilation phase. Module information files are files generated by the compiler to provide module information to program units that USE the module. They usually have suffixes like .mod or .M. The module information files for the modules in the Zoltan library are located in the include directory generated during Zoltan installation. Most Fortran 90 compilers have a compile line flag to specify directories to be searched for module information files, typically "-I"; check the documentation for your compiler. If your compiler does not have such a flag, you will have to copy the module information files to the directory of the application (or use symbolic links).

The Fortran interface is built into the same library file as the rest of Zoltan, which is found during the compiler link phase with -lzoltan. Thus an example compilation line would be

FORTRAN API

The Fortran interface for each Zoltan Interface Function and Application-Registered Query Function is given along with the C interface. This section contains some general information about the design and use of the Fortran interface.

Names

All procedure, variable, defined constant and structure names are identical to those in the C interface, except that in Fortran they are case insensitive (either upper or lower case letters can be used).
 

Zoltan module

MODULE zoltan provides access to all entities in Zoltan that are of use to the application, including kind type parameters, named constants, procedures, and derived types. Any program unit (e.g., main program, module, external subroutine) that needs access to an entity from Zoltan must contain the statement near the beginning.

Numeric types

The correspondence between Fortran and C numeric types is achieved through the use of kind type parameters. In most cases, the default kind for a Fortran type will match the corresponding C type, but this is not guaranteed. To insure portability of the application code, it is highly recommended that the following kind type parameters be used in the declaration of all variables and constants that will be passed to a Zoltan procedure:
 
C Fortran
int INTEGER(KIND=Zoltan_INT)
float REAL(KIND=Zoltan_FLOAT)
double REAL(KIND=Zoltan_DOUBLE) 

Note that "KIND=" is optional in declaration statements. The kind number for constants can be attached to the constant, e.g., 1.0_Zoltan_DOUBLE.
 

Structures

For any struct in the C interface to Zoltan, e.g. Zoltan_Struct, there is a corresponding derived type in the Fortran interface. Variables of this type are declared as demonstrated below: In the Fortran interface, the internal components of the derived type are PRIVATE and not accessible to the application. However, the application simply passes these variables around, and never needs to access the internal components.

Global and local IDs

While the C implementation uses arrays of unsigned integers to represent global and local IDs,  the Fortran interface uses arrays of integers, as unsigned integers are not available in Fortran.  Thus, each ID is represented as an array (possibly of size 1) of integers.  Applications that use other data types for their IDs can convert between their data types and Zoltan's in the application-registered query functions.

Query function data

Zoltan_Set_Fn allows the application to pass a pointer to data that will subsequently be passed to the query function being registered. From Fortran this is an optional argument, or can be one of several types. In the simplest cases, an intrinsic array containing the data will be sufficient. For these cases, data can be an assumed size array of type INTEGER(Zoltan_INT), REAL(Zoltan_FLOAT) or REAL(Zoltan_DOUBLE). When the argument is omitted in the call to the registration function, a data argument will still be passed to the query function. This should be declared as an assumed size array of type INTEGER(Zoltan_INT) and never used.

For more complicated situations, the application may need to pass data in a user-defined type. The strong type checking of Fortran does not allow passing an arbitrary type without modifying the Fortran interface for each desired type. So the Fortran interface provides a type to be used for this purpose, Zoltan_User_Data_1. Since different types of data may need to be passed to different query functions, four such types are provided, using the numerals 1, 2, 3 and 4 as the last character in the name of the type. These types are defined by the application in zoltan_user_data.f90. If not needed, they must be defined, but can be almost empty as in fort/zoltan_user_data.f90.

The application may use these types in any appropriate way. If desired, it can define these types to contain the application's data and use the type throughout the application. But it is anticipated that in most cases, the desired type already exists in the application, and the Zoltan_User_Data_x types will be used as "wrapper types," containing one or more pointers to the existing types. For example,

The application would then set the pointer to the data before calling Zoltan_Set_Fn: Note that the existing data type must be available when Zoltan_User_Data_x is defined. Therefore it must be defined either in zoltan_user_data.f90 or in a module that is compiled before zoltan_user_data.f90 and USEd by MODULE zoltan_user_data. For an example that uses a wrapper type, see fdriver/zoltan_user_data.f90.

FORTRAN 77

There is no FORTRAN 77 interface for Zoltan; however, an existing FORTRAN 77 application can be compiled by a Fortran 90 compiler provided it does not use vendor specific extensions (unless the same extensions are supported by the Fortran 90 compiler), and the application can use Zoltan's Fortran 90 interface with a minimal amount of Fortran 90 additions. This section provides details of the Fortran 90 code that must be added.

When building the Zoltan library, use the file fort/zoltan_user_data.f90 for zoltan_user_data.f90. This assumes that DATA in a call to ZOLTAN_SET_FN is either omitted (you can omit arguments that are labeled OPTIONAL in the Fortran API) or an array of type INTEGER, REAL or DOUBLE PRECISION (REAL*4 and REAL*8 might be acceptable). If a more complicated set of data is required (for example, two arrays), then it should be made available to the query functions through COMMON blocks.

To get access to the interface, each program unit (main program, subroutine or function) that calls a Zoltan routine must begin with the statement

and this should be the first statement after the program, subroutine or function statement (before the declarations).

The pointer to the Zoltan structure returned by ZOLTAN_CREATE should be declared as

(you can use a name other than ZZ if you wish).

To create the structure, use a pointer assignment statement with the call to ZOLTAN_CREATE:

Note that the assignment operator is "=>". If ZZ is used in more than one procedure, then put it in a COMMON block. It cannot be passed as an argument unless the procedure interfaces are made "explicit." (Let's not go there.)

The eight import and export arrays passed to ZOLTAN_LB_PARTITION (and other procedures) must be pointers. They should be declared as, for example,

Note that the double colon after POINTER is required, and the dimension must be declared as "(:)" with a colon. Like ZZ, if they are used in more than one procedure, pass them through a COMMON block, not as an argument.

Except in the unlikely event that the default kinds of intrinsic types do not match the C intrinsic types, you do not have to use the kind type parameters Zoltan_INT, etc. It is also not necessary to include the INTENT attribute in the declarations of the query functions, so they can be simplified to, for example,

to be more consistent with a FORTRAN 77 style.

FORTRAN: System-Specific Remarks

System-specific details of the FORTRAN interface are included below.

The mention of specific products, trademarks, or brand names is for purposes of identification only. Such mention is not to be interpreted in any way as an endoresement or certification of such products or brands by the National Institute of Standards and Technology or Sandia National Laboratories. All trademarks mentioned herein belong to their respective owners.

MPICH

As of version 1.1.2, the MPICH implementation of MPI is not completely "Fortran 90 friendly." Only one problem was encountered during our tests:  the reliance on command line arguments. MPICH uses command line arguments during the start-up process, even if the application does not. Command line arguments are not standard in Fortran, so although most compilers offer it as an extension, each compiler has its own method of handling them. The problem arises when one Fortran compiler is specified during the build of MPICH and another Fortran compiler is used for the application. This should not be a problem on systems where there is only one Fortran compiler, or where multiple Fortran compilers are compatible (for example, FORTRAN 77 and Fortran 90 compilers from the same vendor). If your program can get past the call to MPI_Init, then you do not have this problem.

To solve this problem, build MPICH in such a way that it does not include the routines for iargc and getarg (I have been able to do this by using the -f95nag flag when configuring MPICH), and then provide your own versions of them when you link the application. Some versions of these routines are provided in fdriver/farg_*.

Pacific Sierra

Pacific Sierra Research (PSR) Vastf90 is not currently supported due to bugs in the compiler with no known workarounds. It is not known when or if this compiler will be supported.

NASoftware

N.A.Software FortranPlus is not currently supported due to problems with the query functions. We anticipate that this problem can be overcome, and support will be added soon.

[Table of Contents  |  Next:  Zoltan Interface Functions  |  Previous:  C++ Interface  |  Privacy and Security]