Zoltan User's Guide  |  Next  |  Previous

Migration Functions

Zoltan's migration functions transfer object data to the processors in a new decomposition. Data to be transferred is specified through the import/export lists returned by Zoltan_LB_Partition. Alternatively, users may specify their own import/export lists.

The migration functions can migrate objects based on their new part assignments and/or their new processor assignments. Behavior is determined by the MIGRATE_ONLY_PROC_CHANGES parameter.

If requested, Zoltan can automatically transfer an application's data between processors to realize a new decomposition. This functionality will be performed as part of the call to Zoltan_LB_Partition if the AUTO_MIGRATE parameter is set to TRUE (nonzero) via a call to Zoltan_Set_Param. This approach is effective for when the data to be moved is relatively simple. For more complicated data movement, the application can leave AUTO_MIGRATE FALSE and call Zoltan_Migrate itself. In either case, routines to pack and unpack object data must be provided by the application. See the Migration Examples for examples with and without auto-migration.

The following functions are the migration interface functions. Their detailed descriptions can be found below.

Zoltan_Invert_Lists
Zoltan_Migrate
The following functions are maintained for backward compatibility with previous versions of Zoltan. 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_Compute_Destinations
Zoltan_Help_Migrate
C: int Zoltan_Invert_Lists (
      struct Zoltan_Struct *zz,
      int num_known,
      ZOLTAN_ID_PTR known_global_ids,
      ZOLTAN_ID_PTR known_local_ids,
      int *known_procs,
      int *known_to_part,
      int *num_found,
      ZOLTAN_ID_PTR *found_global_ids,
      ZOLTAN_ID_PTR *found_local_ids,
      int **found_procs,
      int **found_to_part); 
FORTRAN: FUNCTION Zoltan_Invert_Lists(zz,  num_known, known_global_ids, known_local_ids, known_procs, known_to_part, num_found, found_global_ids, found_local_ids, found_procs, found_to_part) 
INTEGER(Zoltan_INT) :: Zoltan_Invert_Lists
TYPE(Zoltan_Struct),INTENT(IN) :: zz
INTEGER(Zoltan_INT), INTENT(IN) :: num_known
INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_to_part, found_to_part
C++: int Zoltan::Invert_Lists (
      const int & num_known,
      ZOLTAN_ID_PTR const known_global_ids,
      ZOLTAN_ID_PTR const known_local_ids,
      int * const known_procs,
      int * const known_to_part,
      int &num_found,
      ZOLTAN_ID_PTR &found_global_ids,
      ZOLTAN_ID_PTR &found_local_ids,
      int * &found_procs,
      int * &found_to_part); 
Zoltan_Invert_Lists computes inverse communication maps useful for migrating data. It can be used in two ways: For example, if each processor knows which objects it will import from other processors, Zoltan_Invert_Lists computes the list of objects each processor needs to export to other processors. If, instead, each processor knows which objects it will export to other processors, Zoltan_Invert_Lists computes the list of objects each processor will import from other processors. The computed lists are allocated in Zoltan; they should not be allocated by the application before calling Zoltan_Invert_Lists. These lists can be freed through a call to Zoltan_LB_Free_Part.
 
Arguments:
    zz Pointer to the Zoltan structure, created by Zoltan_Create, to be used in this invocation of the migration routine.
    num_known  The number of known objects to be received (sent) by this processor.
    known_global_ids An array of num_known global IDs of known objects to be received (sent) by this processor.
(size = num_known * NUM_GID_ENTRIES)
    known_local_ids An array of num_known local IDs of known objects to be received (sent) by this processor.
(size = num_known * NUM_LID_ENTRIES)
    known_procs An array of size num_known listing the processor IDs of the processors that the known objects will be received from (sent to).
    known_to_part An array of size num_known listing the part numbers of the parts that the known objects will be assigned to.
    num_found Upon return, the number of objects that must be sent to (received from) other processors.
    found_global_ids Upon return, an array of num_found global IDs of objects to be sent (received) by this processor.
(size = num_found * NUM_GID_ENTRIES)
    found_local_ids  Upon return, an array of num_found local IDs of objects to be sent (received) by this processor.
(size = num_found * NUM_LID_ENTRIES)
    found_procs Upon return, an array of size num_found listing the processor IDs of processors that the found objects will be sent to (received from).
    found_to_part An array of size num_found listing the part numbers of the parts that the found objects will be assigned to.
Returned Value:
    int Error code.

Note that the number of global and local ID entries (NUM_GID_ENTRIES and NUM_LID_ENTRIES) should be set using Zoltan_Set_Param before calling Zoltan_Invert_Lists. All processors must have the same values for these two parameters.

C: int Zoltan_Migrate (
      struct Zoltan_Struct *zz,
      int num_import,
      ZOLTAN_ID_PTR import_global_ids,
      ZOLTAN_ID_PTR import_local_ids,
      int *import_procs,
      int *import_to_part,
      int num_export,
      ZOLTAN_ID_PTR export_global_ids,
      ZOLTAN_ID_PTR export_local_ids,
      int *export_procs,
      int *export_to_part); 
FORTRAN: FUNCTION Zoltan_Migrate(zz, num_import, import_global_ids, import_local_ids, import_procs, import_to_part, num_export, export_global_ids, export_local_ids, export_procs, export_to_part)
INTEGER(Zoltan_INT) :: Zoltan_Migrate 
TYPE(Zoltan_Struct),INTENT(IN) :: zz 
INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export 
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids 
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids 
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_to_part, export_to_part
C++: int Zoltan::Migrate (
      const int & num_import,
      ZOLTAN_ID_PTR const import_global_ids,
      ZOLTAN_ID_PTR const import_local_ids,
      int * const import_procs,
      int * const import_to_part,
      const int & num_export,
      ZOLTAN_ID_PTR const export_global_ids,
      ZOLTAN_ID_PTR const export_local_ids,
      int * const export_procs,
      int * const export_to_part); 
Zoltan_Migrate takes lists of objects to be sent to other processors, along with the destinations of those objects, and performs the operations necessary to send the data associated with those objects to their destinations. Zoltan_Migrate performs the following operations using the application-registered functions:

Either export lists or import lists must be specified for Zoltan_Migrate. Both export lists and import lists may be specified, but both are not required.

If export lists are provided, non-NULL values for input arguments import_global_ids, import_local_ids, import_procs, and import_to_part are optional. The values must be non-NULL only if no export lists are provided or if the import lists are used by the application callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN. If all processors pass NULL arguments for the import arrays, the value of num_import should be -1.

Similarly, if import lists are provided, non-NULL values for input arguments export_global_ids, export_local_ids, export_procs, and export_to_part are optional. The values must be non-NULL only if no import lists are provided or if the export lists are used by the application callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN. If all processors pass NULL arguments for the export arrays, the value of num_export should be -1. In this case, Zoltan_Migrate computes the export lists based on the import lists.
 
Arguments:
    zz Pointer to the Zoltan structure, created by Zoltan_Create, to be used in this invocation of the migration routine.
    num_import  The number of objects to be imported to parts on this processor; these objects may be stored on other processors or may be moving to new parts within this processor.
Use num_import=-1 if all processors do not specify import arrays.
    import_global_ids An array of num_import global IDs of objects to be imported to parts on this processor.
(size = num_import * NUM_GID_ENTRIES).
All processors may pass import_global_ids=NULL if export lists are provided and import_global_ids is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN.
    import_local_ids An array of num_import local IDs of objects to be imported to parts on this processor.
(size = num_import * NUM_LID_ENTRIES)
All processors may pass import_local_ids=NULL if export lists are provided and import_local_ids is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN .
    import_procs An array of size num_import listing the processor IDs of objects to be imported to parts on this processor (i.e., the source processors).
All processors may pass import_procs=NULL if export lists are provided and import_procs is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN .
    import_to_part An array of size num_import listing the parts to which imported objects should be assigned.
All processors may pass import_to_part=NULL if export lists are provided and import_to_part is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN .
    num_export The number of objects that were stored on this processor in the previous decomposition that are assigned to other processors or to different parts within this processor in the new decomposition.
Use num_export=-1 if all processors do not specify export arrays.
    export_global_ids An array of num_export global IDs of objects to be exported to new parts.
(size = num_export * NUM_GID_ENTRIES)
All processors may pass export_global_ids=NULL if import lists are provided and export_global_ids is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN .
    export_local_ids An array of num_export local IDs of objects to be exported to new parts.
(size = num_export * NUM_LID_ENTRIES)
All processors may pass export_local_ids=NULL if import lists are provided and export_local_ids is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN .
    export_procs An array of size num_export listing the processor IDs to which exported objects should be assigned (i.e., the destination processors).
All processors may pass export_procs=NULL if import lists are provided and export_procs is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN .
    export_to_part An array of size num_export listing the parts to which exported objects should be assigned.
All processors may pass export_to_part=NULL if import lists are provided and export_to_part is not needed by callback functions ZOLTAN_PRE_MIGRATE_PP_FN, ZOLTAN_MID_MIGRATE_PP_FN, and ZOLTAN_POST_MIGRATE_PP_FN .
Returned Value:
    int Error code.

Note that the number of global and local ID entries (NUM_GID_ENTRIES and NUM_LID_ENTRIES) should be set using Zoltan_Set_Param before calling Zoltan_Migrate. All processors must have the same values for these two parameters.

C: int Zoltan_Compute_Destinations (
      struct Zoltan_Struct *zz,
      int num_known,
      ZOLTAN_ID_PTR known_global_ids,
      ZOLTAN_ID_PTR known_local_ids,
      int *known_procs,
      int *num_found,
      ZOLTAN_ID_PTR *found_global_ids,
      ZOLTAN_ID_PTR *found_local_ids,
      int **found_procs); 
FORTRAN: FUNCTION Zoltan_Compute_Destinations(zz,  num_known, known_global_ids, known_local_ids, known_procs, num_found, found_global_ids, found_local_ids, found_procs) 
INTEGER(Zoltan_INT) :: Zoltan_Compute_Destinations 
TYPE(Zoltan_Struct),INTENT(IN) :: zz
INTEGER(Zoltan_INT), INTENT(IN) :: num_known
INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
Zoltan_Compute_Destinations is a wrapper around Zoltan_Invert_Lists that excludes part assignment arrays. It is maintained for backward compatibility with previous versions of Zoltan.

Zoltan_Compute_Destinations assumes the number of parts is equal to the number of processors. The computed lists are allocated in Zoltan; they should not be allocated by the application before calling Zoltan_Compute_Destinations. These lists can be freed through a call to Zoltan_LB_Free_Data or Zoltan_LB_Free_Part.
 
Arguments:
All arguments are analogous to those in Zoltan_Invert_Lists. Part-assignment arrays known_to_part and found_to_part are not included, as part and processor numbers are assumed to be the same in Zoltan_Compute_Destinations.
Returned Value:
    int Error code.

Note that the number of global and local ID entries (NUM_GID_ENTRIES and NUM_LID_ENTRIES) should be set using Zoltan_Set_Param before calling Zoltan_Compute_Destinations. All processors must have the same values for these two parameters.

C: int Zoltan_Help_Migrate (
      struct Zoltan_Struct *zz,
      int num_import,
      ZOLTAN_ID_PTR import_global_ids,
      ZOLTAN_ID_PTR import_local_ids,
      int *import_procs,
      int num_export,
      ZOLTAN_ID_PTR export_global_ids,
      ZOLTAN_ID_PTR export_local_ids,
      int *export_procs); 
FORTRAN: FUNCTION Zoltan_Help_Migrate(zz, num_import, import_global_ids, import_local_ids, import_procs, num_export, export_global_ids, export_local_ids, export_procs)
INTEGER(Zoltan_INT) :: Zoltan_Help_Migrate 
TYPE(Zoltan_Struct),INTENT(IN) :: zz 
INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export 
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids 
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids 
INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs 
Zoltan_Help_Migrate is a wrapper around Zoltan_Migrate that excludes part assignment arrays. It is maintained for backward compatibility with previous versions of Zoltan.

Zoltan_Help_Migrate assumes the number of parts is equal to the number of processors. It uses migration pre-, mid-, and post-processing routines ZOLTAN_PRE_MIGRATE_FN_TYPE, ZOLTAN_MID_MIGRATE_FN_TYPE, and ZOLTAN_POST_MIGRATE_FN_TYPE, respectively, which also exclude part assignment arrays.
 
Arguments:
All arguments are analogous to those in Zoltan_Migrate. Part-assignment arrays import_to_part and export_to_part are not included, as part and processor numbers are assumed to be the same in Zoltan_Help_Migrate.
Returned Value:
    int Error code.

[Table of Contents  | Next:  Ordering Interface  |  Previous:  Functions for Augmenting a Decomposition  |  Privacy and Security]