Zoltan Developer's Guide  |  Next  |  Previous

Parameter Setting Routines

Zoltan allows applications to change a number of parameter settings at runtime. This facility supports debugging by, for instance, allowing control over the type and quantity of output. It also allows users to modify some of the parameters that characterize the partitioning algorithms. The design of the parameter setting routines was driven by several considerations. First, we wanted to keep the user interface as simple as possible. Second, we wanted to allow different Zoltan structures to have different parameter settings associated with them. This second consideration precluded the use of C's static global variables (except in a few special places). The parameter routines described below allow developers to provide runtime access to any appropriate variables. In some cases, it is appropriate to allow developers to tinker with parameters that will never be documented for users.

Our solution to parameter setting is to have a single interface routine Zoltan_Set_Param. This function calls a set of more domain-specific parameter setting routines, each of which is responsible for a domain-specific set of parameters. Assuming there are no errors, the parameter name and new value are placed in a linked list of new parameters which is maintained by the Zoltan structure. When a partitioning method is invoked on a Zoltan structure, it scans through this linked list using the Zoltan_Assign_Param_Vals function, resetting parameter values that are appropriate to the method.

In addition to the method-specific parameters, Zoltan also has a set of so-called key parameters. These are normally stored in the Zoltan structure and may be accessed by any part of the Zoltan code (including all the methods). A list of the key parameters currently used in Zoltan can be found in the User's Guide.

The routines that control parameter setting are listed below. Note that these routines have been written to be as independent of Zoltan as possible. Only a few minor changes would be required to use these routines as a separate library.

Zoltan_Set_Param:  User interface function that calls a set of method-specific routines.
Zoltan_Set_Param_Vec:  Same as Zoltan_Set_Param, but for vector parameters.
Zoltan_Check_Param:  Routine to check if parameter name and value are OK.
Zoltan_Bind_Param: Routine to associate a parameter name with a variable.
Zoltan_Bind_Param_Vec: Same as Zoltan_Bind_Param, but for vector parameters.
Zoltan_Assign_Param_Vals:  Scans list of parameter names & values, setting relevant parameters accordingly.
Zoltan_Free_Params: Frees a parameter list.
See also:  Adding new parameters in Zoltan.

int Zoltan_Set_Param(struct Zoltan_Struct *zz, char *param_name, char *new_val);

The Zoltan_Set_Param function is the user interface for parameter setting. Its principle purpose is to call a sequence of more domain-specific routines for setting domain-specific parameters (e.g., Zoltan_RCB_Set_Param). If you are adding algorithms to Zoltan, you must write one of these domain-specific parameter routines and modify Zoltan_Set_Param to call it. Zoltan_RCB_Set_Param can serve as a template for this task. The arguments to this routine are two strings param_name and new_val. The domain-specific routines return an integer value with the following meaning.

0 - The parameter name was found, and the value passed all error checks.
1 - The parameter name was not found among the parameters known by the domain-specific routine.
2 - The parameter name was found, but the value failed the error checking.
3 - Same as 0, but do not add parameter and value to linked list.
Other - More serious error; value is an error code.
If one of the domain-specific parameter routines returns with a 0, Zoltan_Set_Param adds the parameter and the value (both strings) to a linked list of such pairs that is pointed to by the Params field of the zz structure.
Arguments:
   zz The Zoltan structure whose parameter value is being modified.
   param_name A string containing the name of the parameter being modified. It is automatically converted to all upper-case letters.
   new_val The new value desired for the parameter, expressed as a string.
Returned Value:
   int Error code.
int Zoltan_Set_Param_Vec(struct Zoltan_Struct *zz, char *param_name, char *new_val, int index);

This routine works the same way as Zoltan_Set_Param, but is used for vector parameters. A vector parameter is a parameter that in addition to a name also has a set of 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.

int Zoltan_Check_Param( char *param_name, char *new_val, PARAM_VARS *params, PARAM_UTYPE *result, int *matched_index);
The Zoltan_Check_Param routine simplifies the task of writing your own domain-specific parameter setting function. Zoltan_Check_Param compares the param_name string against a list of strings that you provide, and if a match is found it extracts the new value from the new_val string. See Zoltan_RCB_Set_Param for an example of how to use this routine.
Arguments:
   param_name A capitalized string containing the name of the parameter being modified.
   new_val The new value desired for the parameter, expressed as a string.
   params The data structure (defined in params/params_const.h) describing the domain-specific parameters to be matched against. The data structure is an array of items, each of which consists of four fields. The first field is a string that is a capitalized name of a parameter. The second field is an address that is unused in Zoltan_Check_Param, but is used in Zoltan_Assign_Param_Vals. The third field is another capitalized string that indicates the type of the parameter from the first field. Currently supported types are "INT", "INTEGER", "FLOAT", "REAL", "DOUBLE", "LONG", "STRING" and "CHAR". It is easy to add additional types by simple modifications to Zoltan_Check_Param and Zoltan_Assign_Param_Vals. The fourth field is an integer that gives the dimension (length) of the parameter, if it is a vector parameter. Scalar parameters have dimension 0. The array is terminated by an item consisting of four NULL fields. See Zoltan_RCB_Set_Param for an example of how to set up this data structure. 
   result Structure of information returned by Zoltan_Check_Param (defined in params/params_const.h).  If param_name matches any of the parameter names from the first field of the params data structure, Zoltan_Check_Param attempts to decode the value in new_val. The type of the value is determined by the third field in the params data structure. If the value decodes properly, it is returned in result. 
   matched_index If param_name matches, then matched_index returns the index into the params array that corresponds to the matched parameter name. The matched_index and result values allow the developer to check that values being assigned to parameters are valid. 
Returned Value:
   int 0 - param_name found in params data structure and new_val decodes OK. 
1 - param_name not found in params data structure. 
2 - param_name found in params data structure but new_val doesn't decode properly. 
int Zoltan_Bind_Param (PARAM_VARS *params, char *name, void *var);

This routine is used to associate the name of a parameter in the parameter array params with a variable pointed to by var.
Note that since the variable to be bound can be of an arbitrary type, the pointer should be cast to a void pointer. Zoltan_Bind_Param must be called before Zoltan_Assign_Param_Vals, where the actual assignment of values takes place.
Arguments:
   params The data structure describing the domain-specific parameters to be matched against. The data structure is an array of items, each of which consists of four fields. The first field is a string that is a capitalized name of a parameter. The second field is an address that is unused in Zoltan_Check_Param, but is used in Zoltan_Assign_Param_Vals. The third field is another capitalized string that indicates the type of the parameter from the first field. Currently supported types are "INT", "INTEGER", "FLOAT", "REAL", "DOUBLE", "LONG", "STRING" and "CHAR". It is easy to add additional types by simple modifications to Zoltan_Check_Param and Zoltan_Assign_Param_Vals. The fourth field is an integer that gives the dimension (length) of the parameter, if it is a vector parameter. Scalar parameters have dimension 0. The array is terminated by an item consisting of four NULL fields.
   name A capitalized string containing the name of the parameter being modified.
   var A pointer to the variable  you wish to associate with the parameter name name.  The pointer should be type cast to a void pointer. The user is responsible for ensuring that the pointer really points to a variable of appropriate type.  A NULL pointer may be used to "unbind" a variable such that it will not be assigned a value upon future calls to Zoltan_Assign_Param_Vals.
Returned Value:
   int Error code.

int Zoltan_Bind_Param_Vec(PARAM_VARS *params, char *name, void *var, int dim);

Same as Zoltan_Bind_Param, but for vector parameters. The additional parameter dim gives the dimension or length of the vector parameter.

int Zoltan_Assign_Param_Vals(PARAM_LIST *change_list, PARAM_VARS *params, int debug_level, int my_proc, int debug_proc);
This routine changes parameter values as specified by the list of names and new values which is associated with a Zoltan structure. To use this routine, parameter values should first be set to their defaults, and then Zoltan_Assign_Param_Vals should be called to alter the values as appropriate. See Zoltan_RCB for a template.
Arguments:
   change_list The linked list of parameter names and values which is constructed by Zoltan_Set_Param and is a field of an Zoltan_Struct data structure (defined in params/param_const.h). 
   params The data structure (defined in params/params_const.h) describing the domain-specific parameters to be matched against. The data structure is an array of items, each of which consists of three fields. The first field is a string which is a capitalized name of a parameter. The second field is an address of the parameter which should be altered. The third field is another capitalized string which indicates the type of the parameter being altered. Currently supported types are "INT", "INTEGER", "FLOAT", "REAL", "DOUBLE", "LONG", "STRING" and "CHAR". It is easy to add additional types by simple modifications to Zoltan_Check_Param and Zoltan_Assign_Param_Vals. The array is terminated by an item consisting of three NULL fields. 
   debug_level Zoltan debug level. (Normally this is zz->Debug_Level.)
   my_proc Processor number. (Normally this is zz->Proc.)
   debug_proc Processor number for debugging. (Normally this is zz->Debug_Proc.)
Returned Value:
    int Error code.
The last three input parameters may seem strange. They are present to support Zoltan's debugging features. If the parameter utility code is used outside of Zoltan, these  parameters may be removed or simply set these input values to zero in the function call.

void Zoltan_Free_Params (PARAM_LIST **param_list );

This routine frees the parameters in the list pointed to by param_list.
 
Arguments:
   param_list A pointer to a list (array) of parameters to be freed.  PARAM_LIST is defined in params/param_const.h.


[Table of Contents  |  Next:  Parallel Computing Routines  |  Previous:  Services  |  Privacy and Security]