Zoltan Developer's Guide  |  Next  |  Previous

Common Functions for Querying Applications

Many Zoltan algorithms need to query applications for similar data. The following functions provide simple, uniform query functionality for algorithm developers:
Zoltan_Get_Obj_List
Zoltan_Get_Coordinates
These functions provide a uniform method of calling the query functions registered by an application. Their use simplifies new algorithm development and code maintenance. Usage examples are in rcb/shared.c.

Zoltan_Get_Obj_List can be called from any Zoltan algorithm to obtain a list of object IDs, weights, and part assignments.

Given a list of object IDs, Zoltan_Get_Coordinates can be called from any Zoltan algorithm to obtain a list of coordinates for those IDs.

Note that, contrary to most Zoltan functions, these functions allocate memory for their return lists.

int Zoltan_Get_Obj_List(
    struct Zoltan_Struct *zz,
    int *num_obj,
    ZOLTAN_ID_PTR *global_ids,
    ZOLTAN_ID_PTR *local_ids,
    int wdim,
    float **objwgts,
    int **parts);
Zoltan_Get_Obj_List returns arrays of global and local IDs, part assignments, and object weights (if OBJ_WEIGHT_DIM is not zero) for all objects on a processor. It is a convenient function that frees algorithm developers from calling ZOLTAN_OBJ_LIST_FN, ZOLTAN_FIRST_OBJ_FN, ZOLTAN_NEXT_OBJ_FN, and ZOLTAN_PART_FN query functions directly.
 
Arguments:
    zz A pointer to the Zoltan structure created by Zoltan_Create.
    num_obj Upon return,  the number of objects.
    global_ids Upon return, an array of global IDs of objects on the current processor.
    local_ids Upon return, an array of local IDs of objects on the current processor. NULL is returned when NUM_LID_ENTRIES is zero.
    wdim The number of weights associated with an object (typically 1), or 0 if weights are not requested.
    objwgts Upon return, an array of object weights. Weights for object i are stored in objwgts[i*wdim:(i+1)*wdim-1], for i=0,1,...,num_obj-1. If wdim is zero, the return value of objwgts is undefined and may be NULL.
    parts Upon return, an array of part assignments. Object i is currently in part parts[i].
Returned value:
Error code.
Required Query Functions:
ZOLTAN_NUM_OBJ_FN
ZOLTAN_OBJ_LIST_FN or ZOLTAN_FIRST_OBJ_FN/ZOLTAN_NEXT_OBJ_FN pair
Optional Query Functions:
ZOLTAN_PART_FN

int Zoltan_Get_Coordinates(
    struct Zoltan_Struct *zz,
    int num_obj,
    ZOLTAN_ID_PTR global_ids,
    ZOLTAN_ID_PTR local_ids,
    int *num_dim,
    double **coords);
Given lists of object IDs, Zoltan_Get_Coordinates returns the dimensionality of the problem and an array of coordinates of the objects. It is a convenient function that frees algorithm developers from calling ZOLTAN_NUM_GEOM_FN, ZOLTAN_GEOM_MULTI_FN, and ZOLTAN_GEOM_FN query functions directly.
 
Arguments:
    zz A pointer to the Zoltan structure created by Zoltan_Create.
    num_obj The number of objects.
    global_ids An array of global IDs of objects on the current processor.
    local_ids An array of local IDs of objects on the current processor. local_ids is NULL when NUM_LID_ENTRIES is zero.
    num_dim Upon return, the number of coordinates for each object (typically 1, 2 or 3).
    coords Upon return, an array of coordinates for the objects. Coordinates for object i are stored in coords[i*num_dim:(i+1)*num_dim-1], for i=0,1,...,num_obj-1.
Returned value:
Error code.
Required Query Functions:
ZOLTAN_NUM_GEOM_FN
ZOLTAN_GEOM_MULTI_FN or ZOLTAN_GEOM_FN


[Table of Contents  |  Next:  Hash Function  |  Previous:  Parallel Routines  |  Privacy and Security]