<!-------- @HEADER ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring ! Copyright 2012 Sandia Corporation ! ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, ! the U.S. Government retains certain rights in this software. ! ! Redistribution and use in source and binary forms, with or without ! modification, are permitted provided that the following conditions are ! met: ! ! 1. Redistributions of source code must retain the above copyright ! notice, this list of conditions and the following disclaimer. ! ! 2. Redistributions in binary form must reproduce the above copyright ! notice, this list of conditions and the following disclaimer in the ! documentation and/or other materials provided with the distribution. ! ! 3. Neither the name of the Corporation nor the names of the ! contributors may be used to endorse or promote products derived from ! this software without specific prior written permission. ! ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ! ! Questions? Contact Karen Devine kddevin@sandia.gov ! Erik Boman egboman@sandia.gov ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! @HEADER -------> <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]"> <meta name="sandia.approved" content="SAND99-1376"> <meta name="author" content="karen devine, kddevin@sandia.gov"> <title> Zoltan Developer's Guide: Parameter Setting Routines</title> </head> <body bgcolor="#FFFFFF"> <div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a> | <a href="dev_services_parallel.html">Next</a> | <a href="dev_services.html">Previous</a></i></b></div> <!-------------------------------------------------------------------------> <h2> <a NAME="Parameters"></a>Parameter Setting Routines</h2> 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. <p>Our solution to parameter setting is to have a single interface routine <b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>. 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 <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b> function, resetting parameter values that are appropriate to the method. <p>In addition to the method-specific parameters, Zoltan also has a set of so-called <a NAME="key_params"></a><b>key parameters</b>. 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 <a href="../ug_html/ug_param.html#General_Parameters">key parameters currently used in Zoltan</a> can be found in the User's Guide. <p>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. <blockquote> <b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b>: User interface function that calls a set of method-specific routines. <br><b><a href="#Zoltan_Set_Param_Vec">Zoltan_Set_Param_Vec</a></b>: Same as Zoltan_Set_Param, but for vector parameters. <br><b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>: Routine to check if parameter name and value are OK. <br><b><a href="#Zoltan_Bind_Param">Zoltan_Bind_Param</a></b>: Routine to associate a parameter name with a variable. <br><b><a href="#Zoltan_Bind_Param_Vec">Zoltan_Bind_Param_Vec</a></b>: Same as Zoltan_Bind_Param, but for vector parameters. <br><b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>: Scans list of parameter names & values, setting relevant parameters accordingly. <br><b><a href="#Zoltan_Free_Params">Zoltan_Free_Params</a></b>: Frees a parameter list.</blockquote> See also: <a href="dev_add_params.html">Adding new parameters in Zoltan</a>. <p> <!-------------------------------------------------------------------------> <hr> <a NAME="Zoltan_Set_Param"></a> <hr> int <b>Zoltan_Set_Param</b>(struct <b><a href="dev_lb_structs.html">Zoltan_Struct</a></b> *<i>zz</i>, char *<i>param_name</i>, char *<i>new_val</i>); <br> <hr> <p>The <b>Zoltan_Set_Param</b> function is the <a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">user interface for parameter setting</a>. Its principle purpose is to call a sequence of more domain-specific routines for setting domain-specific parameters (e.g., <b>Zoltan_RCB_Set_Param</b>). If you are adding algorithms to Zoltan, you must write one of these domain-specific parameter routines and modify <b>Zoltan_Set_Param</b> to call it. <b>Zoltan_RCB_Set_Param</b> can serve as a template for this task. The arguments to this routine are two strings <i>param_name</i> and <i>new_val</i>. The domain-specific routines return an integer value with the following meaning. <blockquote>0 - The parameter name was found, and the value passed all error checks. <br>1 - The parameter name was not found among the parameters known by the domain-specific routine. <br>2 - The parameter name was found, but the value failed the error checking. <br>3 - Same as 0, but do not add parameter and value to linked list. <br>Other - More serious error; value is an <a href="../ug_html/ug_interface.html#Error Codes">error code</a>.</blockquote> If one of the domain-specific parameter routines returns with a 0, <b>Zoltan_Set_Param</b> adds the parameter and the value (both strings) to a linked list of such pairs that is pointed to by the <i>Params</i> field of the <i>zz</i> structure. <table WIDTH="100%" > <tr VALIGN=TOP> <td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td> <td WIDTH="80%"></td> </tr> <tr> <td VALIGN=TOP> <i>zz</i></td> <td>The Zoltan structure whose parameter value is being modified.</td> </tr> <tr> <td VALIGN=TOP> <i>param_name</i></td> <td>A string containing the name of the parameter being modified. It is automatically converted to all upper-case letters.</td> </tr> <tr> <td VALIGN=TOP> <i>new_val</i></td> <td>The new value desired for the parameter, expressed as a string.</td> </tr> <tr> <td><b>Returned Value:</b></td> <td></td> </tr> <tr> <td VALIGN=TOP> int</td> <td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td> </tr> </table> <!-------------------------------------------------------------------------> <hr> <a NAME="Zoltan_Set_Param_Vec"></a> <hr> int <b>Zoltan_Set_Param_Vec</b>(struct <b><a href="dev_lb_structs.html">Zoltan_Struct</a></b> *<i>zz</i>, char *<i>param_name</i>, char *<i>new_val</i>, int <i>index</i>); <br> <hr> <p> This routine works the same way as <a href="#Zoltan_Set_Param"> Zoltan_Set_Param</a>, 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 <a href="#Zoltan_Set_Param"> Zoltan_Set_Param</a> as if it were a scalar parameter. <!-------------------------------------------------------------------------> <hr> <a NAME="Zoltan_Check_Param"></a> <hr> int <b>Zoltan_Check_Param</b>( char *<i>param_name</i>, char *<i>new_val</i>, <b>PARAM_VARS</b> *<i>params</i>, <b>PARAM_UTYPE </b>*<i>result</i>, int *<i>matched_index</i>); <br> <hr>The <b>Zoltan_Check_Param</b> routine simplifies the task of writing your own domain-specific parameter setting function. <b>Zoltan_Check_Param</b> compares the <i>param_name</i> string against a list of strings that you provide, and if a match is found it extracts the new value from the <i>new_val</i> string. See <b>Zoltan_RCB_Set_Param</b> for an example of how to use this routine. <table WIDTH="100%" > <tr VALIGN=TOP> <td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td> <td WIDTH="80%"></td> </tr> <tr> <td VALIGN=TOP> <i>param_name</i></td> <td>A capitalized string containing the name of the parameter being modified.</td> </tr> <tr> <td VALIGN=TOP> <i>new_val</i></td> <td>The new value desired for the parameter, expressed as a string.</td> </tr> <tr> <td VALIGN=TOP> <i>params</i></td> <td>The data structure (defined in <i>params/params_const.h</i>) 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 <b>Zoltan_Check_Param</b>, but is used in <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>. 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 <b>Zoltan_Check_Param</b> and <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>. 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 <b>Zoltan_RCB_Set_Param</b> for an example of how to set up this data structure. </td> </tr> <tr> <td VALIGN=TOP> <i>result</i></td> <td>Structure of information returned by <b>Zoltan_Check_Param</b> (defined in <i>params/params_const.h</i>). If <i>param_name</i> matches any of the parameter names from the first field of the <i>params</i> data structure, <b>Zoltan_Check_Param</b> attempts to decode the value in <i>new_val</i>. The type of the value is determined by the third field in the <i>params</i> data structure. If the value decodes properly, it is returned in <i>result</i>. </td> </tr> <tr> <td VALIGN=TOP> <i>matched_index</i></td> <td>If <i>param_name</i> matches, then <i>matched_index</i> returns the index into the <i>params</i> array that corresponds to the matched parameter name. The <i>matched_index</i> and <i>result</i> values allow the developer to check that values being assigned to parameters are valid. </td> </tr> <tr> <td><b>Returned Value:</b></td> <td></td> </tr> <tr> <td VALIGN=TOP> int</td> <td>0 - <i>param_name</i> found in <i>params</i> data structure and <i>new_val</i> decodes OK. <br>1 - <i>param_name</i> not found in <i>params</i> data structure. <br>2 - <i>param_name</i> found in <i>params</i> data structure but <i>new_val</i> doesn't decode properly. </td> </tr> </table> <!-------------------------------------------------------------------------> <hr> <a NAME="Zoltan_Bind_Param"></a> <hr WIDTH="100%"> int <b>Zoltan_Bind_Param </b>(<b>PARAM_VARS</b> *<i>params,</i> char *<i>name,</i> void *<i>var</i>); <br> <hr WIDTH="100%"> <br>This routine is used to associate the name of a parameter in the parameter array <i>params</i> with a variable pointed to by <i>var</i>. <br>Note that since the variable to be bound can be of an arbitrary type, the pointer should be cast to a void pointer. <b>Zoltan_Bind_Param</b> must be called before <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>, where the actual assignment of values takes place. <table WIDTH="100%" NOSAVE > <tr VALIGN=TOP> <td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td> <td WIDTH="80%"></td> </tr> <tr> <td VALIGN=TOP> <i>params</i></td> <td>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 <b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b>, but is used in <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>. 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 <b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b> and <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a></b>. 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.</td> </tr> <tr> <td> <i>name</i></td> <td>A capitalized string containing the name of the parameter being modified.</td> </tr> <tr VALIGN=TOP NOSAVE> <td> <i>var</i></td> <td NOSAVE>A pointer to the variable you wish to associate with the parameter name <i>name.</i> 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 <b><a href="#Zoltan_Assign_Param_Vals">Zoltan_Assign_Param_Vals</a>.</b></td> </tr> <tr> <td><b>Returned Value:</b></td> <td></td> </tr> <tr VALIGN=TOP NOSAVE> <td> int</td> <td NOSAVE><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td> </tr> </table> <p> <!-------------------------------------------------------------------------> <hr> <a NAME="Zoltan_Bind_Param_Vec"></a> <hr WIDTH="100%"> int <b>Zoltan_Bind_Param_Vec</b>(<b>PARAM_VARS</b> *<i>params,</i> char *<i>name,</i> void *<i>var</i>, int <i>dim</i>); <br> <hr WIDTH="100%"> <p> Same as Zoltan_Bind_Param, but for vector parameters. The additional parameter <i>dim</i> gives the dimension or length of the vector parameter. </p> <!-------------------------------------------------------------------------> <hr> <a NAME="Zoltan_Assign_Param_Vals"></a> <hr> int <b>Zoltan_Assign_Param_Vals</b>(<b>PARAM_LIST</b> *<i>change_list</i>, <b>PARAM_VARS</b> *<i>params, </i>int<i> debug_level,</i> int <i>my_proc,</i> int <i>debug_proc</i>); <br> <hr>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 <b>Zoltan_Assign_Param_Vals</b> should be called to alter the values as appropriate. See <b>Zoltan_RCB</b> for a template. <table WIDTH="100%" > <tr VALIGN=TOP> <td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td> <td WIDTH="80%"></td> </tr> <tr> <td VALIGN=TOP> <i>change_list</i></td> <td>The linked list of parameter names and values which is constructed by <b><a href="#Zoltan_Set_Param">Zoltan_Set_Param</a></b> and is a field of an <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b> data structure (defined in <i>params/param_const.h</i>). </td> </tr> <tr> <td VALIGN=TOP> <i>params</i></td> <td>The data structure (defined in <i>params/params_const.h</i>) 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 <b><a href="#Zoltan_Check_Param">Zoltan_Check_Param</a></b> and <b>Zoltan_Assign_Param_Vals</b>. The array is terminated by an item consisting of three NULL fields. </td> </tr> <tr> <td> <i>debug_level</i></td> <td>Zoltan debug level. (Normally this is <i>zz->Debug_Level</i>.)</td> </tr> <tr> <td> <i>my_proc</i></td> <td>Processor number. (Normally this is<i> zz->Proc</i>.)</td> </tr> <tr> <td> <i>debug_proc</i></td> <td>Processor number for debugging. (Normally this is <i>zz->Debug_Proc</i>.)</td> </tr> <tr> <td></td> <td></td> </tr> <tr> <td><b>Returned Value:</b></td> </tr> <tr> <td> int</td> <td><a href="../ug_html/ug_interface.html#Error Codes">Error code</a>.</td> </tr> <tr> <td></td> <td></td> </tr> </table> 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. <p> <!-------------------------------------------------------------------------> <hr WIDTH="100%"> <a NAME="Zoltan_Free_Params"></a> <hr> void <b>Zoltan_Free_Params </b>(<b>PARAM_LIST</b> **<i>param_list</i> ); <hr WIDTH="100%"> <br>This routine frees the parameters in the list pointed to by <i>param_list</i>. <br> <table WIDTH="100%" > <tr VALIGN=TOP> <td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td> <td WIDTH="80%"></td> </tr> <tr> <td VALIGN=TOP> <i>param_list</i></td> <td>A pointer to a list (array) of parameters to be freed. <b>PARAM_LIST</b> is defined in <i>params/param_const.h</i>.</td> </tr> </table> <p> <!-------------------------------------------------------------------------> <hr WIDTH="100%"> <br>[<a href="dev.html">Table of Contents</a> | <a href="dev_services_parallel.html">Next: Parallel Computing Routines</a> | <a href="dev_services.html">Previous: Services</a> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>] </body> </html>