System requirements.
Data types for global and local IDs.
Instructions for building the Zoltan library.
Instructions for building applications that use Zoltan.
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;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.
typedef ZOLTAN_ID_TYPE *ZOLTAN_ID_PTR;
#define ZOLTAN_ID_MPI_TYPE MPI_UNSIGNED
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;The system call malloc may be used instead of ZOLTAN_MALLOC.
int num_gids, int num_gid_entries;
gids = (ZOLTAN_ID_PTR) ZOLTAN_MALLOC(num_gids * num_gid_entries * sizeof(ZOLTAN_ID_TYPE);
The command for building Zoltan is shown below:
gmake [options] zoltanwhere 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. |
setenv ZOLTAN_ARCH <platform>or if you are using a Bourne-type shell (e.g., sh or bash), type
ZOLTAN_ARCH = <platform>; export ZOLTAN_ARCHThe resulting library libzoltan.a, object files, and dependency files are stored in the directory Obj_<platform>.
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.
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
-lzoltanin 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.