Zoltan User's Guide  |  Next  |  Previous

Functions for Augmenting a Decomposition

The following functions support the addition of new items to an existing decomposition. Given a decomposition, they determine to which processor(s) a new item should be assigned. Currently, they work in conjunction with only the RCB, RIB, and HSFC algorithms.
Zoltan_LB_Point_PP_Assign
Zoltan_LB_Box_PP_Assign
For backward compatibility with previous versions of Zoltan, the following functions are also maintained. These functions are applicable only when the number of parts to be generated is equal to the number of processors on which the parts are computed. That is, these functions assume "parts" and "processors" are synonymous.
Zoltan_LB_Point_Assign
Zoltan_LB_Box_Assign
C: int Zoltan_LB_Point_PP_Assign (
      struct Zoltan_Struct * zz,
      double * coords,
      int * proc,
      int * part ); 
FORTRAN: FUNCTION Zoltan_LB_Point_PP_Assign(zz, coords, proc, part)
INTEGER(Zoltan_INT) :: Zoltan_LB_Point_PP_Assign 
TYPE(Zoltan_Struct), INTENT(IN) :: zz 
REAL(Zoltan_DOUBLE), DIMENSION(*), INTENT(IN) :: coords 
INTEGER(Zoltan_INT), INTENT(OUT) :: proc 
INTEGER(Zoltan_INT), INTENT(OUT) :: part 
C++: int Zoltan::LB_Point_PP_Assign (
      double * const coords,
      int & proc,
      int & part ); 
Zoltan_LB_Point_PP_Assign is used to determine to which processor and parts a new point should be assigned. It is applicable only to geometrically generated decompositions (RCB, RIB, and HSFC). If the parameter KEEP_CUTS is set to TRUE, then the sequence of cuts that define the decomposition is saved. Given a new geometric point, the processor and parts which own it can be determined.
 
Arguments:
    zz Pointer to the Zoltan structure created by Zoltan_Create.
    coords The (x,y) or (x,y,z) coordinates of the point being assigned.
    proc Upon return, the ID of the processor to which the point should belong.
    part Upon return, the ID of the parts to which the point should belong.
Returned Value:
    int Error code.
C: int Zoltan_LB_Box_PP_Assign (
      struct Zoltan_Struct * zz,
      double xmin,
      double ymin,
      double zmin,
      double xmax,
      double ymax,
      double zmax,
      int *procs,
      int *numprocs,
      int *parts,
      int *numparts);
FORTRAN: FUNCTION Zoltan_LB_Box_PP_Assign(zz, xmin, ymin, zmin, xmax, ymax, zmax, procs, numprocs, parts, numparts) 
INTEGER(Zoltan_INT) :: Zoltan_LB_Box_PP_Assign 
TYPE(Zoltan_Struct), INTENT(IN) :: zz 
REAL(Zoltan_DOUBLE), INTENT(IN) :: xmin, ymin, zmin, xmax, ymax, zmax 
INTEGER(Zoltan_INT), DIMENSION(*), INTENT(OUT) ::procs 
INTEGER(Zoltan_INT), INTENT(OUT) :: numprocs 
INTEGER(Zoltan_INT), DIMENSION(*), INTENT(OUT) ::parts 
INTEGER(Zoltan_INT), INTENT(OUT) :: numparts 
C++: int Zoltan::LB_Box_PP_Assign (
      const double & xmin,
      const double & ymin,
      const double & zmin,
      const double & xmax,
      const double & ymax,
      const double & zmax,
      int * const procs,
      int & numprocs,
      int * const parts,
      int & numparts);
In many settings, it is useful to know which processors and parts might need to know about an extended geometric object. Zoltan_LB_Box_PP_Assign addresses this problem. Given a geometric decomposition of space (currently only RCB, RIB, and HSFC are supported), and given an axis-aligned box around the geometric object, Zoltan_LB_Box_PP_Assign determines which processors and parts own geometry that intersects the box. To use this routine, the parameter KEEP_CUTS must be set to TRUE when the decomposition is generated. This parameter will cause the sequence of geometric cuts to be saved, which is necessary for Zoltan_LB_Box_PP_Assign to do its job.

Note that if the parameter REDUCE_DIMENSIONS was set to TRUE and the geometry was determined to be degenerate when decomposition was calculated, then the calculation was performed on transformed coordinates. This means that Zoltan_LB_Box_PP_Assign must transform the supplied bounding box accordingly. The transformed vertices are bounded again, and the parts intersections are calculated in the transformed space on this new bounding box. The impact of this is that Zoltan_LB_Box_PP_Assign may return parts not actually intersecting the original bounding box, but it will not omit any parts intersecting the original bounding box.
 

 
Arguments:
    zz Pointer to the Zoltan structure created by Zoltan_Create.
   xmin, ymin, zmin The coordinates of the lower extent of the bounding box around the object.  If the geometry is two-dimensional, the z value is ignored. 
   xmax, ymax, zmax The coordinates of the upper extent of the bounding box around the object.  If the geometry is two-dimensional, the z value is ignored. 
   procs The list of processors intersecting the box are returned starting at this address. Note that it is the responsibility of the calling routine to ensure that there is sufficient space for the return list. 
   numprocs Upon return, this value contains the number of processors that intersect the box (i.e. the number of entries placed in the procs list). 
   parts The list of parts intersecting the box are returned starting at this address. Note that it is the responsibility of the calling routine to ensure that there is sufficient space for the return list. 
   numparts Upon return, this value contains the number of parts that intersect the box (i.e. the number of entries placed in the parts list). 
Returned Value:
    int Error code.

C: int Zoltan_LB_Point_Assign (
      struct Zoltan_Struct * zz,
      double * coords,
      int * proc); 
FORTRAN: FUNCTION Zoltan_LB_Point_Assign(zz, coords, proc) 
INTEGER(Zoltan_INT) :: Zoltan_LB_Point_Assign 
TYPE(Zoltan_Struct), INTENT(IN) :: zz 
REAL(Zoltan_DOUBLE), DIMENSION(*), INTENT(IN) :: coords 
INTEGER(Zoltan_INT), INTENT(OUT) :: proc 
Zoltan_LB_Point_Assign is is a wrapper around Zoltan_LB_Point_PP_Assign that excludes the parts assignment results. Zoltan_LB_Point_Assign assumes the number of parts is equal to the number of processors; thus, the parts assignment is equivalent to the processor assignment.
 
Arguments:
All arguments are analogous to those in Zoltan_LB_Point_PP_Assign. Parts-assignment argument part is not included, as processor and parts numbers are considered to be the same in Zoltan_LB_Point_Assign.
Returned Value:
    int Error code.
C: int Zoltan_LB_Box_Assign (
      struct Zoltan_Struct * zz,
      double xmin,
      double ymin,
      double zmin,
      double xmax,
      double ymax,
      double zmax,
      int *procs,
      int *numprocs);
FORTRAN: FUNCTION Zoltan_LB_Box_Assign(zz, xmin, ymin, zmin, xmax, ymax, zmax, procs, numprocs) 
INTEGER(Zoltan_INT) :: Zoltan_LB_Box_Assign 
TYPE(Zoltan_Struct), INTENT(IN) :: zz 
REAL(Zoltan_DOUBLE), INTENT(IN) :: xmin, ymin, zmin, xmax, ymax, zmax 
INTEGER(Zoltan_INT), DIMENSION(*), INTENT(OUT) ::procs 
INTEGER(Zoltan_INT), INTENT(OUT) :: numprocs 
Zoltan_LB_Box_Assign is a wrapper around Zoltan_LB_Box_PP_Assign that excludes the parts assignment results. Zoltan_LB_Box_Assign assumes the number of parts is equal to the number of processors; thus, the parts assignment is equivalent to the processor assignment.

 
Arguments:
All arguments are analogous to those in Zoltan_LB_Box_PP_Assign. Parts-assignment arguments parts and numparts are not included, as processor and parts numbers are considered to be the same in Zoltan_LB_Box_Assign.
Returned Value:
    int Error code.

[Table of Contents  |  Next:  Migration Functions  |  Previous:  Load-Balancing Functions  |  Privacy and Security]