Zoltan User's Guide  |  Next  |  Previous

Using the Zoltan library

This section contains information needed to use the Zoltan library with applications:
System requirements.
Data types for global and local IDs.
Instructions for building the Zoltan library.
Instructions for building applications that use Zoltan.

System Requirements

Zoltan was designed to run on parallel computers and clusters of workstations. In order to build and use Zoltan, you will need: Zoltan has been tested on a variety of platforms, including Linux, Solaris, Irix, and the ASCI Red Teraflop machine. If you wish to use Zoltan on a non-Unix operating system, for example Windows NT or 2000, you will have to port Zoltan yourself.

Data Types for Object IDs

Application query functions and application callable library functions use global and local identifiers (IDs) for objects. All objects to be used in load balancing must have unique global IDs. Zoltan stores an ID as an array of unsigned integers. The number of entries in these arrays can be set using the NUM_GID_ENTRIES and NUM_LID_ENTRIES parameters; by default, one unsigned integer represents an ID. Applications may use whatever format is most convenient to store their IDs; the IDs can then be converted to and from Zoltan's ID format in the application-registered query functions.

The following type definitions are defined in include/zoltan_types.h; they can be used by an application for memory allocation, MPI communication, and as arguments to load-balancing interface functions and application-registered query functions.

typedef unsigned int ZOLTAN_ID_TYPE;
typedef ZOLTAN_ID_TYPE *ZOLTAN_ID_PTR;
#define ZOLTAN_ID_MPI_TYPE MPI_UNSIGNED
In the Fortran interface, IDs are passed as arrays of integers since unsigned integers are not supported in Fortran. See the description of the Fortran interface for more details.

The local IDs passed to Zoltan are not used by the library; they are provided for the convenience of the application and can contain any information desired by the application. For instance, local array indices for objects may be passed as local IDs, enabling direct access to object data in the query function routines. See the application-registered query functions for more details. The source code distribution contains an example application zdrive in which global IDs are integers and local IDs are local array indices. One may choose not to use local ids at all, in which case NUM_LID_ENTRIES may be set to zero.

Some Zoltan routines (e.g., Zoltan_LB_Partition and Zoltan_Invert_Lists) allocate arrays of type ZOLTAN_ID_PTR and return them to the application. Others (e.g., Zoltan_Order and Zoltan_DD_Find) require the application to allocate memory for IDs. Memory for IDs can be allocated as follows:

ZOLTAN_ID_PTR gids;
int num_gids, int num_gid_entries;
gids = (ZOLTAN_ID_PTR) ZOLTAN_MALLOC(num_gids * num_gid_entries * sizeof(ZOLTAN_ID_TYPE);
The system call malloc may be used instead of ZOLTAN_MALLOC.

Building the Zoltan Library

The Zoltan library is implemented in ANSI C and can be compiled with any ANSI C compiler.  Makefiles are included with the source code; these makefiles require the GNU Make (gmake) utility. The top-level Makefile defines targets for the Zoltan library, test driver programs in C, C++ and Fortran90, and two graphical utilities useful for visualization of geometric partitions. (The test drivers and utilities are primarily intended for use by developers.)  This Makefile need not be edited to build Zoltan.  Instead, environment-specific definitions are specified in the configuration file, Utilities/Config/Config.<platform>, where <platform> specifies the particular platform for which Zoltan is being built.  Paths to compilers, include files, and libraries are defined in this file and are then read by the top-level Makefile.  Examples of configuration files for Solaris, Sandia's ASCI Red (tflop) computer, SGI workstations, and PCs running Linux are included in the Utilities/Config subdirectory.   A well-commented version of the configuration file, Utilities/Config/Config.generic, is also included; this file can be used as a template for new environment-specific files.  The variables in these files should be edited to reflect the new system's environment.

The command for building Zoltan is shown below:

gmake [options] zoltan
where the options that may be specified are listed below.
Options to gmake:  
    ZOLTAN_ARCH=<platform> Specify the target architecture for the Zoltan library.  A corresponding file, Utilities/Config/Config.<platform>, containing environment definitions for <platform>, must be created in the Utilities/Config directory.
    YES_FORTRAN=1 Include Fortran support in the Zoltan library.  By default, the Zoltan library is built without the interface that allows use from Fortran applications.  If this option is specified, the Fortran interface is compiled and included in the library.  Use of this option requires that a Fortran 90 (or 95, or later) compiler is available.
As an alternative to typing the options on the gmake command line, they may be set as environment variables; e.g., if you are using a C-shell (csh or tcsh), type
setenv ZOLTAN_ARCH <platform>
or if you are using a Bourne-type shell (e.g., sh or bash), type
ZOLTAN_ARCH = <platform>; export ZOLTAN_ARCH
The resulting library libzoltan.a, object files, and dependency files are stored in the directory Obj_<platform>.

Testing the Zoltan Library

The examples directory contains simple C and C++ examples which use the Zoltan library. The Makefile in this directory has three targets:
gmake ZOLTAN_ARCH=<platform> C_Examples
This builds simple C language examples that use the Zoltan library to perform load balancing.
gmake ZOLTAN_ARCH=<platform> CPP_Examples
This builds simple C++ language examples that use the Zoltan library to perform load balancing. To build C++ applications, define CPPC to point to your C++ compiler in the Config.<platform> file.
gmake ZOLTAN_ARCH=<platform> all
Build both C and C++ examples. Don't forget to define CPPC in your Config.<platform> file.

Some of these examples make use of a small library of support routines found in the examples/lib directory. These routines create simple test meshes of varying sizes, perform error checking across the parallel application, and define Zoltan call backs.

The "right" answer for these tests depends on the number of processes with which you run the tests. In general, if they compile successfully, run quickly (in seconds), and produce reasonable looking output, then you have been successful in building Zoltan.

Building Applications that use Zoltan

The C library interface is described in the include file include/zoltan.h; this file should be included in all C application source files that call Zoltan library routines.

The C++ interface to Zoltan is implemented in header files which define classes that wrap the Zoltan C library. The file include/zoltan_cpp.h defines the Zoltan class which encapsulates a load balancing data structure and the Zoltan load balancing functions which operate upon it. Include this header file instead in your C++ application. Note that C++ applications should call the C function Zoltan_Initialize before creating a Zoltan object.

Fortran applications must USE module zoltan and specify Zoltan/Obj_<platform> as a directory to be searched for module information files.

The C, C++ or Fortran application should then be linked with the Zoltan library (built with Fortran support in the Fortran case) and its utility libraries by including

-lzoltan
in the linking command for the application. Communication within Zoltan is performed through MPI, so appropriate MPI libraries must be linked with the application. Third-party libraries, such as ParMETIS and Jostle, must be also be linked with the application if they were included in compilation of the Zoltan library.  (A courtesy copy of ParMETIS is included with the Zoltan distribution; Jostle must be obtained directly from http://www.gre.ac.uk/~jjg01/.)
 

For applications that used versions of Zoltan before Zoltan v.1.3, only minor updates to the application build process are needed; see the section on backward compatibility of Zoltan.


[Table of Contents  | Next:  Zoltan Interface Functions  |  Previous: Zoltan Release Notes]