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
Autotools option: --enable-f90interface
Before compiling the library, make sure that the application's
has been placed in the zoltan/src/fort/ directory, if needed.
CMake option: -D Zoltan_ENABLE_F90INTERFACE:BOOL=ON
FORTRAN: Compiling Applications
To compile a Fortran application using the Zoltan library, the module
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
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
f90 -I<path to the installation include directory>
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.
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).
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
near the beginning.
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:
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.
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
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
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
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:
! an existing data type with whatever defines a mesh
END TYPE mesh
TYPE(mesh), POINTER :: ptr
END TYPE Zoltan_User_Data_2
TYPE(mesh) :: meshdata
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,
TYPE(Zoltan_User_Data_2) :: query_data
TYPE(Zoltan_Struct) :: zz
INTEGER(Zoltan_INT), EXTERNAL :: num_obj_func ! not required for module
query_data%ptr => meshdata
ierr = Zoltan_Set_Fn(zz,ZOLTAN_NUM_OBJ_FN_TYPE,num_obj_func,query_data)
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
TYPE(ZOLTAN_STRUCT), POINTER :: ZZ
(you can use a name other than ZZ if you wish).
To create the structure, use a pointer assignment statement with the call
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
INTEGER, POINTER :: IMPORT_GLOBAL_IDS(:)
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,
SUBROUTINE GET_OBJ_LIST(DATA, GLOBAL_IDS, LOCAL_IDS, WGT_DIM, OBJ_WGTS,
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.
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 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.
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]