Zoltan User's Guide  |  Next  |  Previous

General Usage Example

An example of general Zoltan usage is included below. This is a C language example. Similar C++ examples may be found in the examples directory.

In this example, Zoltan_Initialize is called using the argc and argv arguments to the main program. Then a pointer to a Zoltan structure is returned by the call to Zoltan_Create. In this example, all processors will be used by Zoltan, as MPI_COMM_WORLD is passed to Zoltan_Create as the communicator.

Several application query functions are then registered with Zoltan through calls to Zoltan_Set_Fn. Parameters are set through calls to Zoltan_Set_Param. The application then performs in computations, including making calls to Zoltan functions and utilities.

Before its execution ends, the application frees memory used by Zoltan by calling Zoltan_Destroy.
 

/* Initialize the Zoltan library */ 
struct Zoltan_Struct *zz; 
float version; 
... 
Zoltan_Initialize(argc, argv, &version);  
zz = Zoltan_Create(MPI_COMM_WORLD);

/* Register query functions. */
Zoltan_Set_Fn(zz, ZOLTAN_NUM_GEOM_FN_TYPE,
          (void (*)()) user_return_dimension, NULL);
Zoltan_Set_Fn(zz, ZOLTAN_GEOM_FN_TYPE,
          (void (*)()) user_return_coords, NULL);
Zoltan_Set_Fn(zz, ZOLTAN_NUM_OBJ_FN_TYPE,
          (void (*)()) user_return_num_node, NULL);
Zoltan_Set_Fn(zz, ZOLTAN_OBJ_LIST_FN_TYPE,
          (void (*)()) user_return_owned_nodes, NULL);

/* Set some Zoltan parameters. */
Zoltan_Set_Param(zz, "debug_level", "4");

/* Perform application computations, call Zoltan, etc. */
...

/* Free Zoltan data structure before ending application. */
Zoltan_Destroy (&zz); 

Typical calling sequence for general usage of the Zoltan library.
 
! Initialize the Zoltan library 
type(Zoltan_Struct), pointer :: zz 
real(Zoltan_FLOAT) version 
integer(Zoltan_INT) ierr 
... 
ierr = Zoltan_Initialize(version) ! without argc and argv  
zz => Zoltan_Create(MPI_COMM_WORLD)

! Register load-balancing query functions.
! omit data = C NULL
ierr = Zoltan_Set_Fn(zz, ZOLTAN_NUM_GEOM_FN_TYPE, user_return_dimension)
ierr = Zoltan_Set_Fn(zz, ZOLTAN_GEOM_FN_TYPE, user_return_coords)
ierr = Zoltan_Set_Fn(zz, ZOLTAN_NUM_OBJ_FN_TYPE, user_return_num_node)
ierr = Zoltan_Set_Fn(zz, ZOLTAN_OBJ_LIST_FN_TYPE, user_return_owned_nodes)

! Set some Zoltan parameters.
ierr = Zoltan_Set_Param(zz, "debug_level", "4")

! Perform application computations, call Zoltan, etc.
...

! Free Zoltan data structure before ending application.
call Zoltan_Destroy(zz) 

Fortran version of general usage example.
 

[Table of Contents  |  Next:  Load-Balancing Example  |  Previous:  Examples of Library Usage  |  Privacy and Security]