System requirements.
Building the Zoltan library.
Testing the Zoltan library.
Reporting bugs in Zoltan.
Incorporating Zoltan into Applications
Building applications that use Zoltan.
Data types for global and local IDs.
C++ interface.
F90 interface.
The command for building Zoltan is shown below:
cd zoltan/srcwhere the options that may be specified are listed below.
gmake [options] zoltan
ZOLTAN_ARCH=<platform> | Specify the target architecture for the Zoltan library. A corresponding file, zoltan/src/Utilities/Config/Config.<platform>, containing environment definitions for <platform>, must be created in the zoltan/src/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. Currently, the Fortran 90 interface can be built only with the native Zoltan build environment. |
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>.
./configure --helpIMPORTANT! To comply with Trilinos practices, the default autotools configuration produces a serial build of Zoltan -- that is, a version of Zoltan that runs on only one processor. In most cases, Zoltan users prefer a parallel build that runs on multiple processors; users must link with MPI and may choose to compile with the MPI compilers. To enable the parallel build, users must use the --enable-mpi option; they can also require that MPI compilers (e.g., mpicc, mpic++) be used by specifying the --with-mpi-compiler option.
The following script is an example of configuration and build commands using Autotools. It specifies that Zoltan should be built with both the ParMETIS and PT-Scotch interfaces. Paths to both ParMETIS and PT-Scotch are given. The prefix option states where Zoltan should be installed; in this example, Zoltan's include files will be installed in /homes/username/zoltan_v3.1/OBJ_LINUX/include, and the libraries will be installed in /homes/username/zoltan_v3.1/OBJ_LINUX/lib. This examples assumes the script is run from /homes/username/zoltan_v3.1/OBJ_LINUX.
#
../configure \
--prefix=/homes/username/zoltan_v3.1/OBJ_LINUX \
--enable-mpi --with-mpi-compilers \
--enable-zoltan \
--with-gnumake \
--with-scotch \
--with-scotch-incdir="/Net/local/proj/zoltan/arch/all/src/Scotch5" \
--with-scotch-libdir="/Net/local/proj/zoltan/arch/linux64/lib/openmpi/Scotch5" \
--with-parmetis \
--with-parmetis-incdir="/Net/local/proj/zoltan/arch/all/src/ParMETIS3" \
--with-parmetis-libdir="/Net/local/proj/zoltan/arch/linux64/lib/openmpi/ParMETIS3"
make everything
make install
More examples are in the directory zoltan/SampleConfigurationScripts.
Note: Building Zoltan's Fortran 90 interface is not yet available with Autotools; use the native Zoltan build environment to build the Fortran 90 interface.
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, PT-Scotch and PaToH, 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. PaToH must be obtained directly from http://bmi.osu.edu/~umit/software.html. PT-Scotch is available at http://www.labri.fr/perso/pelegrin/scotch/.)
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.
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);