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.

Structures
Modifications to an existing Zoltan interface function
Removing a Zoltan interface function
Adding a new Zoltan interface function
Query functions
Enumerated types and defined constants

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.

### Structures

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:

- public statement: The name of the function should be included in the list of public entities.
- interface for the C wrapper: Copy one of these and modify the function name, argument list and declarations for the new function. The name is of the form Zfw_LB_Point_Assign (fw stands for Fortran wrapper).
- generic interface: This assigns the function name to be a generic name for one or more module procedures.
- module procedure(s): These are the Fortran-side wrapper functions. Usually there is one module procedure of the form Zf90_LB_Point_Assign. If one argument can have more than one type passed to it (for example, it is type void in the C interface), then there must be one module procedure for each type that can be passed. These are distinguished by appending a digit to the end of the module procedure name. If n arguments can have more than one type, then n digits are appended. See Zoltan_LB_Free_Part for example. Generally the module procedure just calls the C-side wrapper function, but in some cases it may need to coerce data to a different type (e.g., Zoltan_Struct), or may actually do real work (e.g., Zoltan_LB_Free_Part).

Here are the items in cwrap.c:

- name mangling: These are macros to convert the function name from the case sensitive C name (for example, Zfw_LB_Point_Assign) to the mangled name produced by the Fortran compiler. There are four of these for each function:

- lowercase (zfw_lb_point_assign),
- uppercase (ZFW_LB_POINT_ASSIGN),
- lowercase with underscore (zfw_lb_point_assign_), and
- lower case with double underscore (zfw_point_assign__ but the second underscore is appended only if the name already contains an underscore, which will always be the case for names starting with Zfw_).

- C-side wrapper function: Usually this just calls the Zoltan library function after coercing the form of the data (for example, constructing the pointer to Zoltan_Struct and call-by-reference to call-by-value conversions).

### 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:

- public statement for the ZOLTAN_FN_TYPE argument: These are identical to the C enumerated type.
- definition of the ZOLTAN_FN_TYPE arguments: There are two groups of these, one containing subroutines (void functions) and one containing functions (int functions). Put the new symbol in the right category. The value assigned to the new symbol must agree exactly with where the symbol appears in the order of the enumerated type.

Here are the places query functions appear in cwrap.c:

- reverse wrappers: These are the query functions that are actually called by the Zoltan library routines when the query function was registered from Fortran. They are just wrappers to call the registered Fortran routine, coercing argument types as necessary. Look at Zoltan_Num_Edges_Fort_Wrapper for an example.
- Zfw_Set_Fn: This has a switch based on the value of the ZOLTAN_FN_TYPE argument to set the Fortran query function and wrapper in the Zoltan_Struct.

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]