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:
TYPE(Zoltan_Struct) :: zz
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,
TYPE mesh
! an existing data type with whatever defines a mesh
END TYPE mesh
TYPE Zoltan_User_Data_2
TYPE(mesh), POINTER :: ptr
END TYPE Zoltan_User_Data_2
The application would then set the pointer to the data before calling Zoltan_Set_Fn:
TYPE(mesh) :: meshdata
TYPE(Zoltan_User_Data_2) :: query_data
TYPE(Zoltan_Struct) :: zz
INTEGER(Zoltan_INT), EXTERNAL :: num_obj_func ! not required for module
procedures
query_data%ptr => meshdata
ierr = Zoltan_Set_Fn(zz,ZOLTAN_NUM_OBJ_FN_TYPE,num_obj_func,query_data)
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