Module zoltan: A Python wrapper for Zoltan¶

Definitions for the Zoltan wrapper

This module defines the main wrapper for the Zoltan library. Users can use derived classes of PyZoltan to perform a domain decomposition on their data. Currently, the following partitioners are available:

ZoltanGeometricPartitioner : Dynamic load balancing using RCB, RIB, HSFC

Zoltan works by calling user defined call back functions that have to be registered with Zoltan. These functions query a user defined data structure and provide the requisite information for Zoltan to proceed with the load balancing. The user defined data structures are defined as structs in the accompanying header (.pxd) file.

The user is responsible to populate this struct appropriately with application specific data and register the right query functions with Zoltan for the chosen algorithm.

Refer to the Zoltan reference manual for a complete list of available query functions, load balancing algorithms and auxiliary functions.

class pyzoltan.core.zoltan.PyZoltan¶

Base class for the Python wrapper for Zoltan

All Zoltan partitioners are derived from PyZoltan. This class sets up the basic arrays used (import/export lists) for load balancing, methods to set Zoltan parameters and the actual load balancing method itself.

The specific Zoltan interface functions that are exposed through this class are:

Zoltan_LB_Balance : The main load balancing routine. Upon return, a list of indices (local, global) to be imported and exported are available.

Zoltan_Invert_Lists : Invert import/export lists. Upon return, a given set of lists is inverted.

Zoltan_Set_Param : Set the value of a Zoltan parameter

Initialize the Zoltan wrapper

Parameters

comm (MPI communicator) – MPI communicator to be used
obj_weight_dim (str, default "0") – Number of weights accociated with an object. The default value implies all objects have the same weight.
edge_weight_dim (str, default "0") – Number of weights associated with an edge. The default value implies all edges have the same weight.
debug_level (str, default "0") – Zoltan debug level. Values in the range [0, 10] are accepted
return_lists (str, default "ALL") – Kind of lists to be returned by Zoltan. Valid values are “IMPORT”, “EXPORT”, “ALL”, “PART”, “NONE”. For explanation see notes section below.

Notes

Valid values of the return_lists argument are:

“IMPORT”: return only lists for objects to be imported,

“EXPORT”: return only lists for objects to be exported,

“ALL”: return both import and export lists,

“PART”: return the processor and partition assignment for all local objects,

“NONE”: don’t return anything

Instantiation of the PyZoltan object initializes the Zoltan library, creates the Zoltan struct ubiquitous in Zoltan calls and also sets up the import/export lists that will be used for the data exchange. It also sets up some reasonable default values.

In general though, any parameter can be set using the Zoltan_Set_Param function wrapper

Zoltan_Create()¶: Create the Zoltan struct

Zoltan_Destroy()¶: Destroy the Zoltan struct

Zoltan_Invert_Lists()¶

Invert export lists to get import lists

At times, we know which particles to export without any information aobut import requirements. Two situations in which this arises is in computing neighbors for geometric partitioners and load balancing using cell lists.

Zoltan_LB_Balance()¶

Call the Zoltan load balancing function.

After a call to this function, the import/export lists required for load balancing are available as data attributes.

The method returns an integer (1:True, 0:False) indicating whether a change in the assignment of the objects is necessary.

Zoltan_Set_Param()¶: Set a general Zoltan Parameter

comm¶

debug_level¶

dim¶

edge_weight_dim¶

exportGlobalids¶

exportLocalids¶

exportProcs¶

importGlobalids¶

importLocalids¶

importProcs¶

lb_method¶

numExport¶

numImport¶

obj_weight_dim¶

parts¶

procs¶

rank¶

reset_zoltan_lists()¶: Reset all Zoltan Import/Export lists

return_lists¶

set_lb_method()¶: Set the Zoltan load balancing method

set_num_global_objects()¶: Set the number of global objects

set_num_local_objects()¶: Set the number of local objects

size¶

version¶

weights¶

class pyzoltan.core.zoltan.ZoltanGeometricPartitioner¶

Concrete implementation of PyZoltan using the geometric algorithms.

Use the ZoltanGeometricPartitioner to load balance/partition a set of objects defined by their coordinates (x, y & z) and an array of unique global indices. Additionally, each object can also have a weight associated with it.

Constructor

Parameters

dim (int) – Problem dimensionality
comm (mpi4py.MPI.Comm) – MPI communicator (typically COMM_WORLD)
x (DoubleArray) – Coordinate arrays for the objects to be partitioned
y (DoubleArray) – Coordinate arrays for the objects to be partitioned
z (DoubleArray) – Coordinate arrays for the objects to be partitioned
gid (UIntArray) – Global indices for the objects to be partitioned
obj_weight_dim (str) – Optional weights for the objects (this should be 1 at most)
return_lists (str) – Specify lists requested from Zoltan (Import/Export)
lb_method (str) – String specifying the load balancing method to use
keep_cuts (str) – Parameter used for adding items to a decomposition

Zoltan_Box_PP_Assign()¶

Find the processors that intersect with a box

For Zoltan, given a domain decomposition using a geometric algorithm, we can use Zoltan_Box_PP_Assign to find processors that intersect with a rectilinear box defined by the values xmin, …. zmax

Zoltan_Point_PP_Assign()¶

Find to which processor a given point must be sent to

For Zoltan, given a domain decomposition using a geometric algorithm, we can use Zoltan_Point_PP_Assign to find a processor in the decomposition to which a given point (x, y, z) belongs to

gid¶

keep_cuts¶

num_global_objects¶

num_local_objects¶

set_rcb_directions()¶

Flag to group the cuts along a given direction

Legal values (refer to the Zoltan User Guide):

‘0’ = don’t order cuts; ‘1’ = xyz ‘2’ = xzy ‘3’ = yzx ‘4’ = yxz ‘5’ = zxy ‘6’ = zyx

set_rcb_lock_directions()¶

Flag to fix the directions of the RCB cuts

Legal values are:

0 : don’t fix directions (default when using RCB) 1 : fix directions

Notes:

This option is only valid for the RCB based geometric partitioner. Setting this option to True (1) will mean the direction of the cuts used at the beginning is re-used for the duration of the simulation.

set_rcb_rectilinear_blocks()¶

Flag controlling the shape of the RCB regions

This option will avoid any unwanted projections of the different partitions at the cost of a slight imbalance.

set_rcb_reuse()¶

Flag to use the previous cut direction as a guess

Legal values are:

0 : don’t reuse 1 : reuse

x¶

y¶

z¶

pyzoltan.core.zoltan.Zoltan_Initialize()¶: Initialize Zoltan

pyzoltan.core.zoltan.get_zoltan_id_type_max()¶