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]