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:

- Given a list of known off-processor objects to be received by a processor,
  compute a list of local objects to be sent by the processor to other processors; or
- Given a list of known local objects to be sent by a processor to other processors,
  compute a list of off-processor objects to be received by the processor.

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:

- Call ZOLTAN_PRE_MIGRATE_PP_FN_TYPE (if registered)
- For each export object, call ZOLTAN_OBJ_SIZE_FN_TYPE to get object sizes.
- For each export object, call ZOLTAN_PACK_OBJ_FN_TYPE to load communication buffers.
- Communicate buffers to destination processors.
- Call ZOLTAN_MID_MIGRATE_PP_FN_TYPE (if registered).
- For each imported object, call ZOLTAN_UNPACK_OBJ_FN_TYPE to move data from the buffer into the new processor's data structures.
- Call ZOLTAN_POST_MIGRATE_PP_FN_TYPE (if registered).

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]