Zoltan User's Guide  |  Next  |  Previous

General Interface Functions

Functions used to initialize and manipulate Zoltan's data structures are described below:
C and C++: int Zoltan_Initialize (
      int argc,
      char **argv,
      float *ver);
FORTRAN: FUNCTION Zoltan_Initialize( argc, argv, ver) 
INTEGER(Zoltan_INT) :: Zoltan_Initialize 
INTEGER(Zoltan_INT), INTENT(IN), OPTIONAL :: argc 
CHARACTER(LEN=*), DIMENSION(*), INTENT(IN), OPTIONAL :: argv 
REAL(Zoltan_FLOAT), INTENT(OUT) :: ver 
The Zoltan_Initialize function initializes MPI for Zoltan. If the application uses MPI, this function should be called after calling MPI_Init. If the application does not use MPI, this function calls MPI_Init for use by Zoltan. This function is called with the argc and argv command-line arguments from the main program, which are used if Zoltan_Initialize calls MPI_Init. From C,  if MPI_Init has already been called, the argc and argv arguments may have any value because their values will be ignored.  From Fortran, if one of argc or argv is omitted, they must both be omitted. If they are omitted, ver does NOT have to be passed as a keyword argument.

Zoltan_Initialize returns the Zoltan version number so that users can verify which version of the library their application is linked to.

C++ applications should call the C Zoltan_Initialize function before using the C++ interface to the Zoltan library.
 
Arguments:  
    argc The number of command-line arguments to the application.
    argv An array of strings containing the command-line arguments to the application.
    ver Upon return, the version number of the library.
Returned Value:
    int Error code.

C: struct Zoltan_Struct *Zoltan_Create (
      MPI_Comm communicator);
FORTRAN: FUNCTION Zoltan_Create(communicator) 
TYPE(Zoltan_Struct), pointer :: Zoltan_Create 
INTEGER, INTENT(IN) :: communicator 
C++: Zoltan (
     const MPI_Comm &communicator = MPI_COMM_WORLD);
The Zoltan_Create function allocates memory for storage of information to be used by Zoltan and sets the default values for the information. The pointer returned by this function is passed to many subsequent functions. An application may allocate more than one Zoltan_Struct data structure; for example, an application may use several Zoltan_Struct structures if, say, it uses different decompositions with different load-balancing techniques.

In the C++ interface to Zoltan, the Zoltan class represents a Zoltan load balancing data structure and the functions that operate on it. It is the constructor which allocates an instance of a Zoltan object. It has no return value.
 
Arguments:
    communicator The MPI communicator to be used for this Zoltan structure. Only those processors included in the communicator participate in Zoltan functions. If all processors are to participate, communicator should be MPI_COMM_WORLD .
Returned Value: 
    struct Zoltan_Struct * Pointer to memory for storage of Zoltan information. If an error occurs, NULL will be returned in C, or the result will be a nullified pointer in Fortran. Any error that occurs in this function is assumed to be fatal.

C: struct Zoltan_Struct *Zoltan_Copy (
      Zoltan_Struct *from);
FORTRAN: FUNCTION Zoltan_Copy(from) 
TYPE(Zoltan_Struct), pointer :: Zoltan_Copy 
TYPE(Zoltan_Struct), INTENT(IN) :: from  
C++: Zoltan (
     const Zoltan &zz);
The Zoltan_Copy function creates a new Zoltan_Struct and copies the state of the existing Zoltan_Struct, which it has been passed, to the new structure. It returns the new Zoltan_Struct.

There is no direct interface to Zoltan_Copy from C++. Rather, the Zoltan copy constructor invokes the C library Zoltan_Copy program.
 
Arguments:
    from A pointer to the Zoltan_Struct that is to be copied.
Returned Value: 
    struct Zoltan_Struct * Pointer to a new Zoltan_Struct, which is now a copy of from.

C: int Zoltan_Copy_To (
      Zoltan_Struct *to,
      Zoltan_Struct *from);
FORTRAN: FUNCTION Zoltan_Copy_To(to, from) 
INTEGER(Zoltan_INT) :: Zoltan_Copy_To 
TYPE(Zoltan_Struct), INTENT(IN) :: to  
TYPE(Zoltan_Struct), INTENT(IN) :: from  
C++: Zoltan & operator= (
     const Zoltan &zz);
The Zoltan_Copy_To function copies one Zoltan_Struct to another, after first freeing any memory used by the target Zoltan_Struct and re-initializing it.

The C++ interface to the Zoltan_Copy_To function is through the Zoltan copy operator, which invokes the C library Zoltan_Copy_To program.
 
Arguments:
    to A pointer to an existing Zoltan_Struct, the target of the copy.
    from A pointer to an existing Zoltan_Struct, the source of the copy.
Returned Value: 
    int 0 on success and 1 on failure.

C: int Zoltan_Set_Param (
      struct Zoltan_Struct *zz,
      char *param_name,
      char *new_val);
FORTRAN: FUNCTION Zoltan_Set_Param(zz, param_name, new_val) 
INTEGER(Zoltan_INT) :: Zoltan_Set_Param 
TYPE(Zoltan_Struct), INTENT(IN) :: zz 
CHARACTER(LEN=*), INTENT(IN) :: param_name, new_value 
C++: int Zoltan::Set_Param (
      const std::string &param_name,
      const std::string &new_value);
Zoltan_Set_Param is used to alter the value of one of the parameters used by Zoltan.  All Zoltan parameters have reasonable default values, but this routine allows a user to provide alternative values if desired.
 
Arguments:
    zz Pointer to the Zoltan structure created by Zoltan_Create.
   param_name A string containing the name of the parameter to be altered.  Note that the string is case-insensitive.  Also, different Zoltan structures can have different parameter values. 
   new_val A string containing the new value for the parameter.  Example strings include "3.154", "True", "7" or anything appropriate for the parameter being set. As above, the string is case-insensitive. 
Returned Value:
    int Error code.
C: int Zoltan_Set_Param_Vec (
      struct Zoltan_Struct *zz,
      char *param_name,
      char *new_val,
      int index);
FORTRAN: FUNCTION Zoltan_Set_Param_Vec(zz, param_name, new_val, index)
INTEGER(Zoltan_INT) :: Zoltan_Set_Param_Vec
TYPE(Zoltan_Struct), INTENT(IN) :: zz
CHARACTER(LEN=*), INTENT(IN) :: param_name, new_value
INTEGER(Zoltan_INT), INTENT(IN) :: index
C++: int Zoltan::Set_Param_Vec (
      const std::string &param_name,
      const std::string &new_val,
      const int &index);
Zoltan_Set_Param_Vec is used to alter the value of a vector parameter in Zoltan. A vector parameter is a parameter that has one name but contains multiple values. These values are referenced by their indices, usually starting at 0. Each entry (component) may have a different value. This routine sets a single entry (component) of a vector parameter. If you want all entries (components) of a vector parameter to have the same value, set the parameter using Zoltan_Set_Param as if it were a scalar parameter. If one only sets the values of a subset of the indices for a vector parameter, the remaining entries will have the default value for that particular parameter.
 
Arguments:
    zz Pointer to the Zoltan structure created by Zoltan_Create.
   param_name A string containing the name of the parameter to be altered.  Note that the string is case-insensitive.  Also, different Zoltan structures can have different parameter values. 
   new_val A string containing the new value for the parameter.  Example strings include "3.154", "True", "7" or anything appropriate for the parameter being set. As above, the string is case-insensitive. 
   index The index of the entry of the vector parameter to be set. The default in Zoltan is that the first entry in a vector has index 0 (C-style indexing).
Returned Value:
    int Error code.
C: int Zoltan_Set_Fn (
      struct Zoltan_Struct *zz,
      ZOLTAN_FN_TYPE fn_type,
      void (*fn_ptr)(),
      void *data);
FORTRAN: FUNCTION Zoltan_Set_Fn(zz, fn_type, fn_ptr, data) 
INTEGER(Zoltan_INT) :: Zoltan_Set_Fn 
TYPE(Zoltan_Struct), INTENT(IN) :: zz 
TYPE(ZOLTAN_FN_TYPE), INTENT(IN) :: fn_type 
EXTERNAL :: fn_ptr 
<type-data>, OPTIONAL :: data 

<type-data> can be any of INTEGER(Zoltan_INT), DIMENSION(*) or REAL(Zoltan_FLOAT), DIMENSION(*) or REAL(Zoltan_DOUBLE), DIMENSION(*) or TYPE(Zoltan_User_Data_x) where x is 1, 2, 3 or 4. See the section on Fortran query functions for an explanation. 
C++: int Zoltan::Set_Fn (
      const ZOLTAN_FN_TYPE &fn_type,
      void (*fn_ptr)(),
      void *data = 0);
Zoltan_Set_Fn registers an application-supplied query function in the Zoltan structure. All types of query functions can be registered through calls to Zoltan_Set_Fn.  To register functions while maintaining strict type-checking of the fn_ptr argument, use Zoltan_Set_<zoltan_fn_type>_Fn.
 
Arguments:
    zz Pointer to the Zoltan structure created by Zoltan_Create.
    fn_type The type of function being registered; see Application-Registered Query Functions for possible function types.
    fn_ptr A pointer to the application-supplied query function being registered.
    data A pointer to user defined data that will be passed, as an argument, to the function pointed to by fn_ptr. In C it may be NULL. In Fortran it may be omitted.
Returned Value:
    int Error code.
C: int Zoltan_Set_<zoltan_fn_type>_Fn (
      struct Zoltan_Struct *zz,
      <zoltan_fn_type> (*fn_ptr)(), 
      void *data);
FORTRAN: FUNCTION Zoltan_Set_<zoltan_fn_type>_Fn(zz, fn_ptr, data) 
INTEGER(Zoltan_INT) :: Zoltan_Set_<zoltan_fn_type>_Fn 
TYPE(Zoltan_Struct), INTENT(IN) :: zz 
EXTERNAL :: fn_ptr 
<type-data>, OPTIONAL :: data 

An interface block for fn_ptr is included in the FUNCTION definition so that strict type-checking of the registered query function can be done.

<type-data> can be any of INTEGER(Zoltan_INT), DIMENSION(*) or REAL(Zoltan_FLOAT), DIMENSION(*) or REAL(Zoltan_DOUBLE), DIMENSION(*) or TYPE(Zoltan_User_Data_x) where x is 1, 2, 3 or 4. See the section on Fortran query functions for an explanation. 
C++: int Zoltan::Set_<zoltan_fn_type>_Fn (
      <zoltan_fn_type> (*fn_ptr)(), 
      void *data = 0);
The interface functions Zoltan_Set_<zoltan_fn_type>_Fn, where <zoltan_fn_type> is one of the query function types, register specific types of application-supplied query functions in the Zoltan structure. One interface function exists for each type of query function.  For example, Zoltan_Set_Num_Geom_Fn registers a query function of type ZOLTAN_NUM_GEOM_FN.  Each query function has an associated Zoltan_Set_<zoltan_fn_type>_Fn.  A complete list of these functions is included in include/zoltan.h.

Query functions can be registered using either Zoltan_Set_Fn or Zoltan_Set_<zoltan_fn_type>_Fn.
Zoltan_Set_<zoltan_fn_type>_Fn provides strict type checking of the fn_ptr argument; the argument's type is specified for each Zoltan_Set_<zoltan_fn_type>_Fn. Zoltan_Set_Fn does not provide this strict type checking, as the pointer to the registered function is cast to a void pointer.
Arguments:
    zz Pointer to the Zoltan structure created by Zoltan_Create.
    fn_ptr A pointer to the application-supplied query function being registered.  The type of the pointer matches <zoltan_fn_type> in the name Zoltan_Set_<zoltan_fn_type>_Fn.
    data A pointer to user defined data that will be passed, as an argument, to the function pointed to by fn_ptr. In C it may be NULL. In Fortran it may be omitted.
Returned Value:
    int Error code.
Example:
The interface function
    int Zoltan_Set_Geom_Fn(struct Zoltan_Struct *zz, ZOLTAN_GEOM_FN (*fn_ptr)(),
                                                 void *data);
registers an ZOLTAN_GEOM_FN query function.

C: void Zoltan_Destroy (
      struct Zoltan_Struct **zz);
FORTRAN: SUBROUTINE Zoltan_Destroy(zz) 
TYPE(Zoltan_Struct), POINTER :: zz 
C++: ~Zoltan ();
Zoltan_Destroy frees the memory associated with a Zoltan structure and sets the structure to NULL in C or nullifies the structure in Fortran. Note that Zoltan_Destroy does not deallocate the import and export arrays returned from Zoltan (e.g., the arrays returned from Zoltan_LB_Partition); these arrays can be deallocated through a separate call to Zoltan_LB_Free_Part.

There is no explicit Destroy method in the C++ interface. The Zoltan object is destroyed when the destructor executes.

As a side effect, Zoltan_Destroy (and the C++ Zoltan destructor) frees the MPI communicator that had been allocated for the structure. So it is important that the application does not call MPI_Finalize before it calls Zoltan_Destroy or before the destructor executes.
 
Arguments:
    zz A pointer to the address of the Zoltan structure, created by Zoltan_Create, to be destroyed. 

[Table of Contents  | Next:  Load-Balancing Functions  |  Previous:  Zoltan Interface Functions  |  Privacy and Security]