Zoltan Developer's Guide  |  Next  |  Previous

FORTRAN Interface

With any change to the user API of Zoltan, the Fortran interface should be modified to reflect the change. This section contains information about the implementation of the Fortran interface which should cover most situations. If you have questions or need assistance, contact william.mitchell@nist.gov.

If changes are made to functions that are called by zdrive, then the changes should also be made to zfdrive. Changes to the Fortran interface can be tested by building and running zfdrive, if the changes are in functions called by zfdrive. The zfdrive program works the same way as zdrive except that it is restricted to the Chaco examples and simpler input files.

Any changes in the interface should also be reflected in the Fortran API definitions in the Zoltan User's Guide.


All structures in the API have a corresponding user-defined type in the Fortran interface. If a new structure is added, then modifications will be required to fort/fwrap.fpp and fort/cwrap.c. In these files, search for Zoltan_Struct and "do like it does."

An explanation of how structures are handled may help. The Fortran user-defined type for the structure simply contains the address of the structure, i.e., the C pointer returned by a call to create the structure. Note that the user does not have access to the components of the structure, and can only pass the structure to functions. Within the Fortran structure, the address is stored in a variable of type(Zoltan_PTR), which is a character string containing one character for each byte of the address. This gives the best guarantee of portability under the Fortran and C standards. Also, to insure portability of passing character strings, the character string is converted to an array of integers before passing it between Fortran and C. The process of doing this is most easily seen by looking at Zoltan_Destroy, which has little else to clutter the code.

Modifications to an existing Zoltan interface function

If the argument list or return type of a user-callable function in Zoltan changes, the same changes must be made in the Fortran interface routines. This involves changes in two files: fort/fwrap.fpp and fort/cwrap.c. In these files, search for the function name with the prefix Zoltan_ omitted, and modify the argument list, argument declarations, return type, and call to the C library function as appropriate. When adding a new argument, if there is not already an argument of the same type,  look at another function that does have an argument of that type for guidance.

Removing a Zoltan interface function

If a user callable function is removed from the Zoltan library, edit fort/fwrap.fpp and fort/cwrap.c to remove all references to that function.

Adding a new Zoltan interface function

Adding a new function involves changes to the two files fort/fwrap.fpp and fort/cwrap.c. Perhaps the easiest way to add a new function to these files is to pick some existing function, search for all occurrences of it, and use that code as a guide for the implementation of the interface for the new function. Zoltan_LB_Point_Assign is a nice minimal function to use as an example. Use a case insensitive search on the name of the function without the Zoltan_LB_ prefix, for example point_assign.

Here are the items in fwrap.fpp:

Here are the items in cwrap.c:

Query functions

If a query function is added, deleted or changed, modifications must be made to fort/fwrap.fpp and fort/cwrap.c, similar to the modifications for interface functions, and possibly also include/zoltan.h and zz/zz_const.h.

Here are the places query functions appear in fwrap.fpp:

Here are the places query functions appear in cwrap.c: In zz/zz_const.h, if a new field is added to the structures for a new query function, it should be added in both C and Fortran forms. In include/zoltan.h, if a new typedef for a query function is added, it should be added in both C and Fortran forms. See these files for examples.

Enumerated types and defined constants

Enumerated types and defined constants that the application uses as the value for an arguments must be placed in fwrap.fpp with the same value. See ZOLTAN_OK for an example. 

[Table of Contents  |  Next:  C++ Interface  |  Previous:  Migration Tools  |  Privacy and Security]