Zoltan User's Guide  |  Next  |  Previous

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.



[Table of Contents  |  Next:  FORTRAN 77  |  Previous:  FORTRAN--Compiling Applications