Zoltan Developer's Guide | Next | Previous

## Data Structures

The Zoltan_Struct data structure is the main data structure for interfacing between Zoltan and the application. The application creates an Zoltan_Struct data structure through a call to Zoltan_Create. Fields of the data structure are then set through calls from the application to interface routines such as Zoltan_Set_Param and Zoltan_Set_Fn. The fields of the Zoltan_Struct data structure are listed and described in the table below. See the Zoltan User's Guide for descriptions of the function types used in the Zoltan_Struct.

A Zoltan_Struct data structure zz is passed from the application to Zoltan in the call to Zoltan_LB_Partition. This data structure is passed to the individual load-balancing routines. The zz->LB.Data_Structure pointer field should point to the main data structures of the particular load-balancing algorithm so that the data structures may be preserved for future calls to Zoltan_LB_Partition and so that separate instances of the same load-balancing algorithm (with different Zoltan_Struct structures) can be used by the application.

Fields of Zoltan_Struct | Description
--- | ---
MPI_Comm Communicator | The MPI communicator to be used by the Zoltan structure; set by Zoltan_Create.
int Proc | The rank of the processor within Communicator; set in Zoltan_Create.
int Num_Proc | The number of processors in Communicator; set in Zoltan_Create.
int Num_GID | The number of array entries used to represent a global ID. Set via a call to Zoltan_Set_Param for NUM_GID_ENTRIES.
int Num_LID | The number of array entries used to represent a local ID. Set via a call to Zoltan_Set_Param for NUM_LID_ENTRIES.
int Debug_Level | A flag indicating the amount of debugging information that should be printed by Zoltan.
int Fortran | A flag indicating whether or not the structure was created by a call from Fortran.
PARAM_LIST * Params | A linked list of string pairs. The first item in each pair is the name of a modifiable parameter. The second string is the new value the parameter should adopt. These string pairs are read upon invocation of a Zoltan algorithm and the appropriate parameter changes are made. This design allows for different Zoltan structures to have different parameter settings.
int Deterministic | Flag indicating whether algorithms used should be forced to be deterministic; used to obtain completely reproducible results. Set via a call to Zoltan_Set_Param for DETERMINISTIC.
int Obj_Weight_Dim | Number of weights per object. Set via a call to Zoltan_Set_Param for OBJ_WEIGHT_DIM.
int Edge_Weight_Dim | For graph algorithms, number of weights per edge. Set via a call to Zoltan_Set_Param for EDGE_WEIGHT_DIM.
int Timer | Timer type that is currently active. Set via a call to Zoltan_Set_Param for TIMER.
ZOLTAN_NUM_EDGES_FN * Get_Num_Edges | A pointer to an application-registered function that returns the number of edges associated with a given object. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Edges_Fn.
void *Get_Num_Edges_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Num_Edges. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Edges_Fn.
ZOLTAN_EDGE_LIST_FN * Get_Edge_List | A pointer to an application-registered function that returns a given object's neighbors along its edges. Set in Zoltan_Set_Fn or Zoltan_Set_Edge_List_Fn.
void *Get_Edge_List_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Edge_List. Set in Zoltan_Set_Fn or Zoltan_Set_Edge_List_Fn.
ZOLTAN_NUM_GEOM_FN * Get_Num_Geom | A pointer to an application-registered function that returns the number of geometry values needed to describe the positions of objects. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Geom_Fn.
void *Get_Num_Geom_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Num_Geom. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Geom_Fn.
ZOLTAN_GEOM_FN * Get_Geom | A pointer to an application-registered function that returns a given object's geometry information (e.g., coordinates). Set in Zoltan_Set_Fn or Zoltan_Set_Geom_Fn.
void *Get_Geom_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Geom. Set in Zoltan_Set_Fn or Zoltan_Set_Geom_Fn.
ZOLTAN_NUM_OBJ_FN * Get_Num_Obj | A pointer to an application-registered function that returns the number of objects assigned to the processor before load balancing. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Obj_Fn.
void *Get_Num_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Num_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Obj_Fn.
ZOLTAN_OBJ_LIST_FN * Get_Obj_List | A pointer to an application-registered function that returns arrays of objects assigned to the processor before load balancing. Set in Zoltan_Set_Fn or Zoltan_Set_Obj_List_Fn.
void *Get_Obj_List_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Obj_List. Set in Zoltan_Set_Fn or Zoltan_Set_Obj_List_Fn.
ZOLTAN_FIRST_OBJ_FN * Get_First_Obj | A pointer to an application-registered function that returns the first object assigned to the processor before load balancing. Used with Get_Next_Obj as an iterator over all objects. Set in Zoltan_Set_Fn or Zoltan_Set_First_Obj_Fn.
void *Get_First_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_First_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_First_Obj_Fn.
ZOLTAN_NEXT_OBJ_FN * Get_Next_Obj | A pointer to an application-registered function that, given an object assigned to the processor, returns the next object assigned to the processor before load balancing. Used with Get_First_Obj as an iterator over all objects. Set in Zoltan_Set_Fn or Zoltan_Set_Next_Obj_Fn.
void *Get_Next_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Next_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Next_Obj_Fn.
ZOLTAN_NUM_BORDER_OBJ_FN * Get_Num_Border_Obj | A pointer to an application-registered function that returns the number of objects sharing a subdomain border with a given processor. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Border_Obj_Fn.
void *Get_Num_Border_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Num_Border_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Border_Obj_Fn.
ZOLTAN_BORDER_OBJ_LIST_FN * Get_Border_Obj_List | A pointer to an application-registered function that returns arrays of objects that share a subdomain border with a given processor. Set in Zoltan_Set_Fn or Zoltan_Set_Border_Obj_List_Fn.
void *Get_Border_Obj_List_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Border_Obj_List. Set in Zoltan_Set_Fn or Zoltan_Set_Border_Obj_List_Fn.
ZOLTAN_FIRST_BORDER_OBJ_FN * Get_First_Border_Obj | A pointer to an application-registered function that returns the first object sharing a subdomain border with a given processor. Used with Get_Next_Border_Obj as an iterator over objects along borders. Set in Zoltan_Set_Fn or Zoltan_Set_First_Border_Obj_Fn.
void *Get_First_Border_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_First_Border_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_First_Border_Obj_Fn.
ZOLTAN_NEXT_BORDER_OBJ_FN * Get_Next_Border_Obj | A pointer to an application-registered function that, given an object, returns the next object sharing a subdomain border with a given processor. Used with Get_First_Border_Obj as an iterator over objects along borders. Set in Zoltan_Set_Fn or Zoltan_Set_Next_Border_Obj_Fn.
void *Get_Next_Border_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Next_Border_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Next_Border_Obj_Fn.
ZOLTAN_NUM_COARSE_OBJ_FN * Get_Num_Coarse_Obj | A pointer to an application-registered function that returns the number of objects in the initial coarse grid. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Coarse_Obj_Fn.
void *Get_Num_Coarse_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Num_Coarse_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Coarse_Obj_Fn.
ZOLTAN_COARSE_OBJ_LIST_FN * Get_Coarse_Obj_List | A pointer to an application-registered function that returns arrays of objects in the initial coarse grid. Set in Zoltan_Set_Fn or Zoltan_Set_Coarse_Obj_List_Fn.
void *Get_Coarse_Obj_List_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Coarse_Obj_List. Set in Zoltan_Set_Fn or Zoltan_Set_Coarse_Obj_List_Fn.
ZOLTAN_FIRST_COARSE_OBJ_FN * Get_First_Coarse_Obj | A pointer to an application-registered function that returns the first object of the initial coarse grid. Used with Get_Next_Coarse_Obj as an iterator over all objects in the coarse grid. Set in Zoltan_Set_Fn or Zoltan_Set_First_Coarse_Obj_Fn.
void *Get_First_Coarse_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_First_Coarse_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_First_Coarse_Obj_Fn.
ZOLTAN_NEXT_COARSE_OBJ_FN * Get_Next_Coarse_Obj | A pointer to an application-registered function that, given an object in the initial coarse grid, returns the next object in the coarse grid. Used with Get_First_Coarse_Obj as an iterator over all objects in the coarse grid. Set in Zoltan_Set_Fn or Zoltan_Set_Next_Coarse_Obj_Fn.
void *Get_Next_Coarse_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Next_Coarse_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Next_Coarse_Obj_Fn.
ZOLTAN_NUM_CHILD_FN * Get_Num_Child | A pointer to an application-registered function that returns the number of refinement children of an object. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Child_Fn.
void *Get_Num_Child_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Num_Child. Set in Zoltan_Set_Fn or Zoltan_Set_Num_Child_Fn.
ZOLTAN_CHILD_LIST_FN * Get_Child_List | A pointer to an application-registered function that returns arrays of objects that are refinement children of a given object. Set in Zoltan_Set_Fn or Zoltan_Set_Child_List_Fn.
void *Get_Child_List_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Child_List. Set in Zoltan_Set_Fn or Zoltan_Set_Child_List_Fn.
ZOLTAN_CHILD_WEIGHT_FN * Get_Child_Weight | A pointer to an application-registered function that returns the weight of an object. Set in Zoltan_Set_Fn or Zoltan_Set_Child_Weight_Fn.
void *Get_Child_Weight_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Child_Weight. Set in Zoltan_Set_Fn or Zoltan_Set_Child_Weight_Fn.
ZOLTAN_OBJ_SIZE_FN * Get_Obj_Size | A pointer to an application-registered function that returns the size (in bytes) of data objects to be migrated. Called by Zoltan_Migrate. Set in Zoltan_Set_Fn or Zoltan_Set_Obj_Size_Fn.
void *Get_Obj_Size_Data | A pointer to data provided by the user that will be passed to the function pointed to by Get_Obj_Size. Set in Zoltan_Set_Fn or Zoltan_Set_Obj_Size_Fn.
ZOLTAN_PACK_OBJ_FN * Pack_Obj | A pointer to an application-registered function that packs all data for a given object into a communication buffer provided by the migration tools in preparation for data-migration communication. Called by Zoltan_Migrate for each object to be exported. Set in Zoltan_Set_Fn or Zoltan_Set_Pack_Obj_Fn.
void *Pack_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Pack_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Pack_Obj_Fn.
ZOLTAN_UNPACK_OBJ_FN * Unpack_Obj | A pointer to an application-registered function that unpacks all data for a given object from a communication buffer after the communication for data migration is completed. Called by Zoltan_Migrate for each imported object. Set in Zoltan_Set_Fn or Zoltan_Set_Unpack_Obj_Fn.
void *Unpack_Obj_Data | A pointer to data provided by the user that will be passed to the function pointed to by Unpack_Obj. Set in Zoltan_Set_Fn or Zoltan_Set_Unpack_Obj_Fn.
ZOLTAN_LB LB | A structure with data used by the load-balancing tools. See the table below.
ZOLTAN_MIGRATE Migrate | A structure with data used by the migration tools. See the table below.
Fields of the Zoltan_Struct data structure.

Each Zoltan_Struct data structure has a ZOLTAN_LB sub-structure. The ZOLTAN_LB structure contains data used by the load-balancing tools, including pointers to specific load-balancing methods and load-balancing data structures. The fields of the ZOLTAN_LB structure are listed and described in in the following table.

Fields of ZOLTAN_LB | Description
--- | ---
void * Data_Structure | The data structure used by the selected load-balancing algorithm; this pointer is cast by the algorithm to the appropriate data type.
double Imbalance_Tol | The degree of load balance which is considered acceptable. Set via a call to Zoltan_Set_Param for IMBALANCE_TOL.
int Num_Global_Parts | The total number of parts to be generated. Set via a call to Zoltan_Set_Param for NUM_GLOBAL_PARTS or through summation of NUM_LOCAL_PARTS parameters.
int Num_Local_Parts | The number of parts to be generated on this processor. Set via a call to Zoltan_Set_Param for NUM_LOCAL_PARTS or (roughly) through division of the NUM_GLOBAL_PARTS parameter by the number of processors.
int Return_Lists | A flag indicating whether the application wants import and/or export lists returned by Zoltan_LB_Partition. Set via a call to Zoltan_Set_Param for RETURN_LISTS.
ZOLTAN_LB_METHOD Method | An enumerated type designating which load-balancing algorithm should be used with this Zoltan structure; set via a call to Zoltan_Set_Param for LB_METHOD.
LB_FN * LB_Fn | A pointer to the load-balancing function specified by Method.
ZOLTAN_LB_FREE_DATA_FN *Free_Structure | Pointer to a function that frees the Data_Structure memory.
ZOLTAN_LB_POINT_ASSIGN_FN *Point_Assign | Pointer to the function that performs Zoltan_LB_Point_Assign for the particular load-balancing method.
Fields of the ZOLTAN_LB data structure.
ZOLTAN_LB_BOX_ASSIGN_FN *Box_Assign | Pointer to the function that performs Zoltan_LB_Box_Assign for the particular load-balancing method.

Each Zoltan_Struct data structure has a ZOLTAN_MIGRATE sub-structure. The ZOLTAN_MIGRATE structure contains data used by the migration tools, including pointers to pre- and post-processing routines. These pointers are set through the interface routine Zoltan_Set_Fn and are used in Zoltan_Migrate. The fields of the ZOLTAN_MIGRATE structure are listed and described in in the following table.

Fields of ZOLTAN_MIGRATE | Description
--- | ---
int Auto_Migrate | A flag indicating whether Zoltan should perform auto-migration for the application. If true, Zoltan calls Zoltan_Migrate to move objects to their new processors; if false, data migration is left to the user. Set in Zoltan_Set_Param for AUTO_MIGRATE.
ZOLTAN_PRE_MIGRATE_PP_FN * Pre_Migrate_PP | A pointer to an application-registered function that performs pre-processing for data migration. The function is called by Zoltan_Migrate before data migration is performed. Set in Zoltan_Set_Fn or Zoltan_Set_Pre_Migrate_PP_Fn.
void *Pre_Migrate_PP_Data | A pointer to data provided by the user that will be passed to the function pointed to by Pre_Migrate_PP. Set in Zoltan_Set_Fn or Zoltan_Set_Pre_Migrate_PP_Fn.
ZOLTAN_MID_MIGRATE_PP_FN * Mid_Migrate_PP | A pointer to an application-registered function that performs processing between the packing and unpacking operations in Zoltan_Migrate. Set in Zoltan_Set_Fn or Zoltan_Set_Mid_Migrate_PP_Fn.
void *Mid_Migrate_PP_Data | A pointer to data provided by the user that will be passed to the function pointed to by Mid_Migrate_PP. Set in Zoltan_Set_Fn or Zoltan_Set_Mid_Migrate_PP_Fn.
ZOLTAN_POST_MIGRATE_PP_FN *Post_Migrate_PP | A pointer to an application-registered function that performs post-processing for data migration. The function is called by Zoltan_Migrate after data migration is performed. Set in Zoltan_Set_Fn or Zoltan_Set_Post_Migrate_PP_Fn.
void *Post_Migrate_PP_Data | A pointer to data provided by the user that will be passed to the function pointed to by Post_Migrate_PP. Set in Zoltan_Set_Fn or Zoltan_Set_Post_Migrate_PP_Fn.
ZOLTAN_PRE_MIGRATE_FN * Pre_Migrate | A pointer to an application-registered function that performs pre-processing for data migration. The function is called by Zoltan_Help_Migrate before data migration is performed. Set in Zoltan_Set_Fn or Zoltan_Set_Pre_Migrate_Fn. Maintained for backward compatibility with Zoltan v1.3 interface.
void *Pre_Migrate_Data | A pointer to data provided by the user that will be passed to the function pointed to by Pre_Migrate. Set in Zoltan_Set_Fn or Zoltan_Set_Pre_Migrate_Fn.
ZOLTAN_MID_MIGRATE_FN * Mid_Migrate | A pointer to an application-registered function that performs processing between the packing and unpacking operations in Zoltan_Help_Migrate. Set in Zoltan_Set_Fn or Zoltan_Set_Mid_Migrate_Fn. Maintained for backward compatibility with Zoltan v1.3 interface.
void *Mid_Migrate_Data | A pointer to data provided by the user that will be passed to the function pointed to by Mid_Migrate. Set in Zoltan_Set_Fn or Zoltan_Set_Mid_Migrate_Fn.
ZOLTAN_POST_MIGRATE_FN *Post_Migrate | A pointer to an application-registered function that performs post-processing for data migration. The function is called by Zoltan_Help_Migrate after data migration is performed. Set in Zoltan_Set_Fn or Zoltan_Set_Post_Migrate_Fn. Maintained for backward compatibility with Zoltan v1.3 interface.
void *Post_Migrate_Data | A pointer to data provided by the user that will be passed to the function pointed to by Post_Migrate. Set in Zoltan_Set_Fn or Zoltan_Set_Post_Migrate_Fn.
Fields of the ZOLTAN_MIGRATE data structure.

For each pointer to an application registered function in the Zoltan_Struct and ZOLTAN_MIGRATE data structures there is also a pointer to a Fortran application registered function, of the form ZOLTAN_FUNCNAME_FORT_FN *Get_Funcname_Fort. These are for use within the Fortran interface. The Zoltan routines should invoke the usual application registered function regardless of whether the Zoltan structure was created from C or Fortran.

[Table of Contents | Next: Services | Previous: ID Data Types | Privacy and Security]