Load-Balancing Functions

Zoltan_LB_Partition
Zoltan_LB_Set_Part_Sizes
Zoltan_LB_Eval
Zoltan_LB_Free_Part

Zoltan_LB_Balance
Zoltan_LB_Free_Data

Zoltan_RCB_Box

Returned arrays are allocated in Zoltan; applications should not allocate these arrays before calling Zoltan_LB_Partition. The arrays are later freed through calls to Zoltan_LB_Free_Part.
 

Arguments:
zz	Pointer to the Zoltan structure, created by Zoltan_Create, to be used in this invocation of the load-balancing routine.
changes	Set to 1 or .TRUE. if the decomposition was changed by the load-balancing method; 0 or .FALSE. otherwise.
num_gid_entries	Upon return, the number of array entries used to describe a single global ID.  This value is the maximum value over all processors of the parameter NUM_GID_ENTRIES.
num_lid_entries	Upon return, the number of array entries used to describe a single local ID.  This value is the maximum value over all processors of the parameter NUM_LID_ENTRIES.
num_import	Upon return, the number of objects that are newly assigned to this processor or to parts on this processor (i.e., the number of objects being imported from different parts to parts on this processor). If the value returned is -1, no import information has been returned and all import arrays below are NULL. (The RETURN_LISTS parameter determines whether import lists are returned).
import_global_ids	Upon return, an array of num_import global IDs of objects to be imported to parts on this processor. (size = num_import * num_gid_entries)
import_local_ids	Upon return, an array of  num_import local IDs of objects to be imported to parts on this processor. (size = num_import * num_lid_entries)
import_procs	Upon return, an array of size num_import listing the processor IDs of the processors that owned the imported objects in the previous decomposition (i.e., the source processors).
import_to_part	Upon return, an array of size num_import listing the parts to which the imported objects are being imported.
num_export	Upon return, this value of this count and the following lists depends on the value of the RETURN_LISTS parameter: It is the count of objects on this processor that are newly assigned to other processors or to other parts on this processor, if RETURN_LISTS is "EXPORT" or "EXPORT AND IMPORT". It is the count of all objects on this processor, if RETURN_LISTS is "PARTS" (or "PART ASSIGNMENTS"). It is -1 if the value of RETURN_LISTS indicates that either no lists are to be returned, or only import lists are to be returned. If the value returned is -1, no export information has been returned and all export arrays below are NULL .
export_global_ids	Upon return, an array of num_export global IDs of objects to be exported from parts on this processor (if RETURN_LISTS is equal to "EXPORT" or "EXPORT AND IMPORT"), or an array of num_export global IDs for every object on this processor (if RETURN_LISTS is equal to "PARTS" or "PART ASSIGNMENTS"), .  (size = num_export * num_gid_entries)
export_local_ids	Upon return, an array of num_export local IDs associated with the global IDs returned in export_global_ids (size = num_export * num_lid_entries)
export_procs	Upon return, an array of size num_export listing the processor ID of the processor to which each object is now assigned (i.e., the destination processor). If RETURN_LISTS is equal to "PARTS" or "PART ASSIGNMENTS", this list includes all objects, otherwise it only includes the objects which are moving to a new part and/or process.
export_to_part	Upon return, an array of size num_export listing the parts to which the objects are assigned under the new partition.
Returned Value:
int	Error code.

Arguments:
zz	Pointer to the Zoltan structure.
print_stats	If print_stats>0 (.TRUE. in Fortran), print the quality metrics to stdout.
obj_info	If obj_infois non-NULL, write object balance values to the ZOLTAN_BALANCE_EVAL structure.
graph_info	If graph_infois non-NULL, write graph partition metrics to the ZOLTAN_GRAPH_EVAL structure.
hg_info	If hg_infois non-NULL, write hypergraph partition metrics to the ZOLTAN_HG_EVAL structure.
Returned Value:
int	Error code.

The EVAL structures are defined in zoltan/src/include/zoltan_eval.h. Several of the fields in the EVAL structures are arrays of values. The arrays contain values for

1. the total for the local process
2. the total across all parts
3. the minimum across all parts
4. the maximum across all parts
5. the average across all parts

in that order. The corresponding macros that refer to these fields are:

#define EVAL_LOCAL_SUM 0
#define EVAL_GLOBAL_SUM 1
#define EVAL_GLOBAL_MIN 2
#define EVAL_GLOBAL_MAX 3
#define EVAL_GLOBAL_AVG 4


The ZOLTAN_BALANCE_EVAL structure contains the following fields, and would be of interest if you are doing geometric partitioning:

• obj_imbalance: imbalance in count of objects across parts, scaled by requested part sizes.
• imbalance: imbalance in weight of objects across parts, scaled by requested part sizes.
• nobj: an array containing the number of objects on the local process, the total number of objects, the minimum number of objects in a part, the maximum number in a partitition, and the average number of objects across the parts.
• obj_wgt: an array containing the sum of the weight of objects on the local process, the total weight across all processes, the minimum weight in a part, the maximum weight in a partitition, and the average weight of objects across the parts.
• xtra_imbalance: if the OBJ_WEIGHT_DIM exceeds one, the obj_imbalance value for the extra weights is in this array.
• xtra_obj_wgt: if the OBJ_WEIGHT_DIM exceeds one, the obj_wgt array for the extra weights is in this array.

The ZOLTAN_GRAPH_EVAL structure contains the following fields, and would be of interest if you are doing graph partitioning:

• cutl: an array containing what is known at the CUTL or the ConCut measure of the graph, the first element is not set (this is the local process total, which has no meaning), the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
• cutn: an array containing what is known at the CUTN or the NetCut measure of the graph, the first element is not set, the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
• cuts: an array counting the number of cut edges (the first element again is not set) across all parts, the minimum across parts of cut edges, the maximum, and then the average
• cut_weight: an array summing the weight of cut edges (the first element again is not set) across all parts, the minimum across parts, the maximum, and then the average
• nnborparts: an array which counts the number of neighboring parts that each part has, the first element again is not set, the next is the sum across all parts, the minimum across parts, the maximum, and then the average
• obj_imbalance: imbalance in count of objects across parts, scaled by requested part sizes.
• imbalance: imbalance in weight of objects across parts, scaled by requested part sizes.
• nobj: an array containing the number of objects on the local process, the total number of objects, the minimum number of objects in a part, the maximum number in a partitition, and the average number of objects across the parts.
• obj_wgt: an array containing the sum of the weight of objects on the local process, the total weight across all processes, the minimum weight in a part, the maximum weight in a partitition, and the average weight of objects across the parts.
• num_boundary: an array which counts the number of objects in a part that have at least one remote neighbor, the first element is not set, the next is the sum across parts, the next is the minimum count in any part, the next is the maximum, and then the average for all parts
• xtra_imbalance: if the OBJ_WEIGHT_DIM exceeds one, the obj_imbalance value for the extra weights is in this array.
• xtra_obj_wgt: if the OBJ_WEIGHT_DIM exceeds one, the obj_wgt array for the extra weights is in this array.
• xtra_cut_wgt: if the EDGE_WEIGHT_DIM exceeds one, the cut_wgt array for the each extra weight is in this array.

The ZOLTAN_HG_EVAL structure contains the following fields, and would be of interest if you are doing hypergraph partitioning:

• obj_imbalance: imbalance in count of objects across parts, scaled by requested part sizes.
• imbalance: imbalance in weight of objects across parts, scaled by requested part sizes.
• cutl: an array containing what is known at the CUTL or the ConCut measure of the hypergraph, the first element is not set (this is the local process total, which has no meaning), the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
• cutn: an array containing what is known at the CUTN or the NetCut measure of the hypergraph, the first element is not set, the next is the sum of the CUTL across parts, then the minimum CUTL across parts, then the maximum CUTL across parts, finally the average CUTL across parts.
• nobj: an array containing the number of objects on the local process, t he total number of objects, the minimum number of objects in a part, the maximum number in a partitition, and the average number of objects across the parts.
• obj_wgt: an array containing the sum of the weight of objects on the local p rocess, the total weight across all processes, the minimum weight in a part, the m aximum weight in a part, and the average weight of objects across the parts.
• xtra_imbalance: if the OBJ_WEIGHT_DIM exceeds one, the obj_imbalance value for the extra weights is in this array.
• xtra_obj_wgt: if the OBJ_WEIGHT_DIM e xceeds one, the obj_wgt array for the extra weights is in this array.

Query functions:
Required:	ZOLTAN_NUM_OBJ_FN and ZOLTAN_OBJ_LIST_FN
Optional:	Graph-Based functions are required for writing the ZOLTAN_GRAPH_EVAL structure. Hypergraph-Based functions will be used for writing the ZOLTAN_HG_EVAL if they are available, otherwise Zoltan will create a hypergraph from the graph-Based functions. If Zoltan_LB_Set_Part_Sizes has been called, the part sizes set by the Zoltan_LB_Set_Part_Sizes will be used in calculating imbalances.

Note that the sum of ncuts over all processors is actually twice the number of edges cut in the graph (because each edge is counted twice). The same principle holds for cut_wgt.

There are a few improvements in Zoltan_LB_Eval  in Zoltan version 1.5 (or higher). First, the balance data are computed with respect to both processors and parts (if applicable). Second, the desired part sizes (as set by Zoltan_LB_Set_Part_Sizes)  are taken into account when computing the imbalance.

Known bug: If a part is spread across several processors, the computed cut information (ncuts and cut_wgt) may be incorrect (too high).