zoltanParams: Library for Parsing Zoltan Parameters

Jim Teresco
Department of Computer Science
Williams College
47 Lab Campus Drive
Williamstown, MA 01267


Sandia National Laboratories' Zoltan Toolkit provides partitioning, load balancing, and other services to parallel applications. Zoltan's behavior is, in part, defined by function calls that set a variety of parameters. For example, the call

ierr = Zoltan_Set_Param(zz, "OCT_MAXOBJECTS", "40");

will set the parameter OCT_MAXOBJECTS to 40 in the Zoltan_Struct *zz.

The zoltanParams utility allows applications to specify these parameters in a text file, allowing changes to Zoltan parameters without need to edit source code, recomipile, and relink the applications. A typical situation where this is useful is when trying different partitioning algorithms and parameters to see which works best for a particular application on a particular computer. When using Zoltan's hierarchical balancing procedures (to be included in a future Zoltan release) and when interfacing with the Dynamic Resource Utilization Model (DRUM) to do resource-aware partitioning in heterogeneous and hierarchical parallel computing environments, the number of parameters that may be set makes a tool such as zoltanParams especially useful.

The format of a zoltanParams input file is simple. It contains any number of lines of the format:

which is translated into a call to Zoltan_Set_Param, setting the given parameter to the given value.

When used in conjunction with hierarchical balancing (Zoltan method "HIER"), the file format is slightly more complicated. If the parameter is "LB_METHOD" and its value is set to "HIER", the next part of the file is interpreted as hierarchical balancing parameters:

  level 0 partitions for each proc
  level 0 parameters
  end with LEVEL END
  level 1 partitions for each proc
  level 1 parameters
  end with LEVEL END

  End file with EOF


To make use of the zoltanParams library, it must be compiled, either as a standalone library or by adding the source files to the application's build process. The one C source file zoltanParams_read_file.c requires MPI and Zoltan.

To use zoltanParams, an application should replace part of its Zoltan initialization sequence with a zoltanParams call. A typical Zoltan initialization sequence, such as:

  /* create zoltan lb object */
  lb = Zoltan_Create(MPI_COMM_WORLD);

  /* register callbacks (not shown) */

  /* set zoltan parameters */
  Zoltan_Set_Param(lb, "NUM_GID_ENTRIES", "2");
  Zoltan_Set_Param(lb, "NUM_LID_ENTRIES", "0");
  Zoltan_Set_Param(lb, "OBJ_WEIGHT_DIM", "1");
  Zoltan_Set_Param(lb, "EDGE_WEIGHT_DIM", "0");
  Zoltan_Set_Param(lb, "RETURN_LISTS", "EXPORT");
  Zoltan_Set_Param(lb, "OCT_METHOD", "2");
  Zoltan_Set_Param(lb, "OCT_MAXOBJECTS", "40");
  Zoltan_Set_Param(lb, "OCT_MINOBJECTS", "10");
  Zoltan_Set_Param(lb, "LB_METHOD", "OCTPART");
would be replaced by this code:
  /* create zoltan lb object */
  lb = Zoltan_Create(MPI_COMM_WORLD);

  /* register callbacks (not shown) */

  zoltanParams_read_file(lb, "zoltan.params", MPI_COMM_WORLD);
where the file "zoltan.params" in the working directory contains:
Note: zoltanParams uses static storage to save hierarchical balancing parameters, and such parameters are stored permanently by zoltanParams_read_file and remain available for use by hierarchical balancing until overridden by a subsequent call to zoltanParams_read_file.


zoltanParams is freely available. To get a copy, please contact the developer at terescoj AT cs.williams.edu (replace AT with @). It is written in standard C, and should compile anywhere that has a decent C compiler.


The author was supported by contract 15162 with Sandia National Laboratories, a multiprogram laboratory operation by Sandia Corporation, a Lockheed Martin Company, for the United States Department of Energy under Contract DE-AC04-94AL85000. The library was developed while the author was visiting the Computer Science Research Institute at Sandia National Laboratories.

Jim Teresco - Thu Mar 11 13:33:07 MST 2004