You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
790 lines
32 KiB
790 lines
32 KiB
<!-------- @HEADER
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
|
|
! Copyright 2012 Sandia Corporation
|
|
!
|
|
! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
|
|
! the U.S. Government retains certain rights in this software.
|
|
!
|
|
! Redistribution and use in source and binary forms, with or without
|
|
! modification, are permitted provided that the following conditions are
|
|
! met:
|
|
!
|
|
! 1. Redistributions of source code must retain the above copyright
|
|
! notice, this list of conditions and the following disclaimer.
|
|
!
|
|
! 2. Redistributions in binary form must reproduce the above copyright
|
|
! notice, this list of conditions and the following disclaimer in the
|
|
! documentation and/or other materials provided with the distribution.
|
|
!
|
|
! 3. Neither the name of the Corporation nor the names of the
|
|
! contributors may be used to endorse or promote products derived from
|
|
! this software without specific prior written permission.
|
|
!
|
|
! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
|
|
! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
|
|
! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
!
|
|
! Questions? Contact Karen Devine kddevin@sandia.gov
|
|
! Erik Boman egboman@sandia.gov
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! @HEADER
|
|
------->
|
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
|
|
<meta name="sandia.approval_type" content="formal">
|
|
<meta name="sandia.approved" content="SAND2007-4748W">
|
|
<meta name="author" content="Zoltan PI">
|
|
|
|
<title>Zoltan User's Guide: Migration Interface</title>
|
|
|
|
</head>
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<div align=right><b><i><a href="ug.html"> Zoltan User's Guide</a>
|
|
| <a href="ug_interface_order.html">Next</a> | <a href="ug_interface_augment.html">Previous</a></i></b></div>
|
|
|
|
<h2>
|
|
<a NAME="Migration Functions"></a>Migration Functions</h2>
|
|
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
|
|
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
|
|
Alternatively, users may specify their own import/export lists.
|
|
<p>
|
|
The
|
|
migration functions can migrate objects based on their new part assignments
|
|
and/or their new processor assignments. Behavior is determined by the
|
|
<a href="ug_alg.html#MIGRATE_ONLY_PROC_CHANGES"><B>MIGRATE_ONLY_PROC_CHANGES</b></a>
|
|
parameter.
|
|
<p>
|
|
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
|
|
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
|
|
if the <b><a href="ug_alg.html#LB Parameters">AUTO_MIGRATE</a></b>
|
|
parameter is set to TRUE (nonzero) via a call to <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
|
|
This approach is effective for when the data to be moved is relatively
|
|
simple. For more complicated data movement, the application can leave <b><a href="ug_alg.html#LB Parameters">AUTO_MIGRATE</a></b>
|
|
FALSE and call <b><a href="#Zoltan_Migrate">Zoltan_Migrate</a></b>
|
|
itself.
|
|
In either case, <a href="ug_query_mig.html#Migration Query Functions">routines
|
|
to pack and unpack object data</a> must be provided by the application.
|
|
See the <a href="ug_examples_mig.html#Migration Example">Migration Examples</a>
|
|
for examples with and without auto-migration.
|
|
<p>The following functions are the migration interface functions. Their
|
|
detailed descriptions can be found below.
|
|
<blockquote>
|
|
<b><a href="#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>
|
|
<br><b><a href="#Zoltan_Migrate">Zoltan_Migrate</a></b>
|
|
</blockquote>
|
|
|
|
The following functions are maintained for <a href="ug_backward.html">backward compatibility</a> 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.
|
|
<blockquote>
|
|
<b><a href="#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a></b>
|
|
<br><b><a href="#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a></b>
|
|
</blockquote>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr WIDTH="100%">
|
|
<a NAME="Zoltan_Invert_Lists"></a>
|
|
<hr WIDTH="100%">
|
|
<table WIDTH="100%" NOSAVE >
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C:</td>
|
|
|
|
<td WIDTH="85%">
|
|
int <b>Zoltan_Invert_Lists</b>
|
|
(
|
|
<br> struct <b>Zoltan_Struct</b> *<i>zz</i>,
|
|
<br> int <i>num_known</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_local_ids</i>,
|
|
<br> int *<i>known_procs</i>,
|
|
<br> int *<i>known_to_part</i>,
|
|
<br> int *<i>num_found</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_local_ids</i>,
|
|
<br> int **<i>found_procs</i>,
|
|
<br> int **<i>found_to_part</i>); </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
|
|
|
|
<td>FUNCTION <b>Zoltan_Invert_Lists</b>(<i>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</i>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Invert_Lists
|
|
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
|
|
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_known
|
|
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_to_part, found_to_part
|
|
</td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C++:</td>
|
|
|
|
<td WIDTH="85%">
|
|
int <b>Zoltan::Invert_Lists</b>
|
|
(
|
|
<br> const int & <i>num_known</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>known_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>known_local_ids</i>,
|
|
<br> int * const <i>known_procs</i>,
|
|
<br> int * const <i>known_to_part</i>,
|
|
<br> int &<i>num_found</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> &<i>found_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> &<i>found_local_ids</i>,
|
|
<br> int * &<i>found_procs</i>,
|
|
<br> int * &<i>found_to_part</i>); </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr WIDTH="100%"><b>Zoltan_Invert_Lists</b> computes inverse communication
|
|
maps useful for migrating data. It can be used in two ways:
|
|
<ul>
|
|
<li> Given a list of known off-processor objects to be received by a processor,<br>
|
|
compute a list of local objects to be sent by the processor to other
|
|
processors; or
|
|
</li>
|
|
<li> Given a list of known local objects to be sent by a processor to other processors, <br>
|
|
compute a list of off-processor objects to be received by the processor.
|
|
</li>
|
|
</ul>
|
|
|
|
For example, if each processor knows which objects it will import from other
|
|
processors, <b>Zoltan_Invert_Lists</b> 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,
|
|
<b>Zoltan_Invert_Lists</b> 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 <b>Zoltan_Invert_Lists</b>. These lists can be freed through a
|
|
call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> zz</i></td>
|
|
|
|
<td>Pointer to the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
|
|
to be used in this invocation of the migration routine.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> num_known </i></td>
|
|
|
|
<td>The number of known objects to be received (sent) by
|
|
this processor.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> known_global_ids</i></td>
|
|
|
|
<td>An array of <i>num_known</i> global IDs of known objects to be received (sent)
|
|
by this processor.
|
|
<br>(size = <i>num_known</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> known_local_ids</i></td>
|
|
|
|
<td>An array of <i>num_known</i> local IDs of known objects to be received (sent)
|
|
by this processor.
|
|
<br>(size = <i>num_known</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> known_procs</i></td>
|
|
|
|
<td>An array of size <i>num_known</i> listing the processor IDs of the
|
|
processors that the known objects will be received from (sent to).
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> known_to_part</i></td>
|
|
|
|
<td>An array of size <i>num_known</i> listing the part numbers of the
|
|
parts that the known objects will be assigned to.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> num_found</i></td>
|
|
|
|
<td>Upon return, the number of objects that must be sent to (received from) other processors.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> found_global_ids</i></td>
|
|
|
|
<td>Upon return, an array of <i>num_found</i> global IDs of objects to be
|
|
sent (received) by this processor.
|
|
<br>(size = <i>num_found</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> found_local_ids</i></td>
|
|
|
|
<td> Upon return, an array of <i>num_found</i> local IDs of objects
|
|
to be sent (received) by this processor.
|
|
<br>(size = <i>num_found</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> found_procs</i></td>
|
|
|
|
<td>Upon return, an array of size <i>num_found</i> listing the processor
|
|
IDs of processors that the found objects will be sent to (received from).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> found_to_part</i></td>
|
|
|
|
<td>An array of size <i>num_found</i> listing the part numbers of the
|
|
parts that the found objects will be assigned to.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
|
|
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
|
|
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
|
|
before calling <b>Zoltan_Invert_Lists</b>. All processors must have
|
|
the same values for these two parameters.
|
|
<p>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr WIDTH="100%">
|
|
<a NAME="Zoltan_Migrate"></a>
|
|
<hr WIDTH="100%">
|
|
<table WIDTH="100%" NOSAVE >
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C:</td>
|
|
|
|
<td WIDTH="85%">
|
|
int <b>Zoltan_Migrate</b> (
|
|
<br> struct <b>Zoltan_Struct</b> *<i>zz</i>,
|
|
<br> int <i>num_import</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_local_ids</i>,
|
|
<br> int *<i>import_procs</i>,
|
|
<br> int *<i>import_to_part</i>,
|
|
<br> int <i>num_export</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_local_ids</i>,
|
|
<br> int *<i>export_procs</i>,
|
|
<br> int *<i>export_to_part</i>); </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
|
|
|
|
<td>FUNCTION <b>Zoltan_Migrate</b>(<i>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</i>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Migrate
|
|
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
|
|
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_to_part, export_to_part
|
|
</td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C++:</td>
|
|
|
|
<td WIDTH="85%">
|
|
int <b>Zoltan::Migrate</b> (
|
|
<br> const int & <i>num_import</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>import_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>import_local_ids</i>,
|
|
<br> int * const <i>import_procs</i>,
|
|
<br> int * const <i>import_to_part</i>,
|
|
<br> const int & <i>num_export</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>export_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>export_local_ids</i>,
|
|
<br> int * const <i>export_procs</i>,
|
|
<br> int * const <i>export_to_part</i>); </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr WIDTH="100%"><b>Zoltan_Migrate</b> 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. <b>Zoltan_Migrate</b> performs the following
|
|
operations using the application-registered functions:
|
|
<ul>
|
|
<li>
|
|
Call <b><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN">ZOLTAN_PRE_MIGRATE_PP_FN_TYPE</a></b> (if registered)
|
|
</li>
|
|
<li>
|
|
For each export object, call <b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN_TYPE</a></b> to get object sizes.
|
|
</li>
|
|
<li>
|
|
For each export object, call
|
|
<b><a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN_TYPE</a></b> to load communication buffers.
|
|
</li>
|
|
<li>
|
|
Communicate buffers to destination processors.
|
|
</li>
|
|
<li>
|
|
Call <b><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN">ZOLTAN_MID_MIGRATE_PP_FN_TYPE</a></b> (if registered).
|
|
</li>
|
|
<li>
|
|
For each imported object, call
|
|
<b><a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN_TYPE</a></b> to move data from the buffer into the new processor's data structures.
|
|
</li>
|
|
<li>
|
|
Call <b><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN">ZOLTAN_POST_MIGRATE_PP_FN_TYPE</a></b> (if registered).
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Either export lists or import lists must be specified for <b>Zoltan_Migrate</b>.
|
|
Both export lists and import lists may be specified, but both are not required.
|
|
<p>
|
|
If export lists are provided,
|
|
non-NULL values for input arguments <i>import_global_ids</i>, <i>import_local_ids</i>, <i>import_procs</i>, and <i>import_to_part</i> 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
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
|
|
If all processors pass NULL arguments for the import arrays, the value of <i>num_import</i> should be -1.
|
|
<p>
|
|
Similarly, if import lists are provided,
|
|
non-NULL values for input arguments <i>export_global_ids</i>, <i>export_local_ids</i>, <i>export_procs</i>, and <i>export_to_part</i> 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
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
|
|
If all processors pass NULL arguments for the export arrays, the value of <i>num_export</i> should be -1.
|
|
In this case, <b>Zoltan_Migrate</b> computes the export lists based on the
|
|
import lists.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> zz</i></td>
|
|
|
|
<td>Pointer to the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
|
|
to be used in this invocation of the migration routine.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> num_import </i></td>
|
|
|
|
<td>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.
|
|
<br> Use <i>num_import</i>=-1 if all processors do not specify import arrays.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> import_global_ids</i></td>
|
|
|
|
<td>An array of <i>num_import</i> global IDs of objects
|
|
to be imported to parts on this processor.
|
|
<br>(size = <i>num_import</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>).
|
|
<br>All processors may pass <i>import_global_ids</i>=NULL if
|
|
export lists are provided and
|
|
<i>import_global_ids</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> import_local_ids</i></td>
|
|
|
|
<td>An array of <i>num_import</i> local IDs of objects to be imported
|
|
to parts on this processor.
|
|
<br>(size = <i>num_import</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)
|
|
<br>All processors may pass <i>import_local_ids</i>=NULL if
|
|
export lists are provided and
|
|
<i>import_local_ids</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
|
|
a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
|
|
a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
|
|
</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> import_procs</i></td>
|
|
|
|
<td>An array of size <i>num_import</i> listing the processor IDs of
|
|
objects to be imported to parts on this processor (i.e., the source
|
|
processors).
|
|
<br>All processors may pass <i>import_procs</i>=NULL if
|
|
export lists are provided and
|
|
<i>import_procs</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
|
|
a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
|
|
a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
|
|
</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> import_to_part</i></td>
|
|
|
|
<td>An array of size <i>num_import</i> listing the parts to which
|
|
imported objects should be assigned.
|
|
<br>All processors may pass <i>import_to_part</i>=NULL if
|
|
export lists are provided and
|
|
<i>import_to_part</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
|
|
a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
|
|
a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
|
|
</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> num_export</i></td>
|
|
|
|
<td>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.
|
|
<br> Use <i>num_export</i>=-1 if all processors do not specify export arrays.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> export_global_ids</i></td>
|
|
|
|
<td>An array of <i>num_export</i> global IDs of objects to be exported
|
|
to new parts.
|
|
<br>(size = <i>num_export</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)
|
|
<br>All processors may pass <i>export_global_ids</i>=NULL if
|
|
import lists are provided and
|
|
<i>export_global_ids</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
|
|
a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
|
|
a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
|
|
</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> export_local_ids</i></td>
|
|
|
|
<td>An array of <i>num_export</i> local IDs of objects to be exported to
|
|
new parts.
|
|
<br>(size = <i>num_export</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)
|
|
<br>All processors may pass <i>export_local_ids</i>=NULL if
|
|
import lists are provided and
|
|
<i>export_local_ids</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
|
|
a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
|
|
a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
|
|
</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> export_procs</i></td>
|
|
|
|
<td>An array of size <i>num_export</i> listing the processor IDs to which
|
|
exported objects should be assigned (i.e., the destination processors).
|
|
<br>All processors may pass <i>export_procs</i>=NULL if
|
|
import lists are provided and
|
|
<i>export_procs</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
|
|
a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
|
|
a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
|
|
</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> export_to_part</i></td>
|
|
|
|
<td>An array of size <i>num_export</i> listing the parts to which
|
|
exported objects should be assigned.
|
|
<br>All processors may pass <i>export_to_part</i>=NULL if
|
|
import lists are provided and
|
|
<i>export_to_part</i> is not
|
|
needed by callback functions
|
|
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
|
|
a>,
|
|
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
|
|
a>, and
|
|
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
|
|
</a>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
|
|
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
|
|
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
|
|
before calling <b>Zoltan_Migrate</b>. All processors must have the same
|
|
values for these two parameters.
|
|
<br>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr WIDTH="100%">
|
|
<a NAME="Zoltan_Compute_Destinations"></a>
|
|
<hr WIDTH="100%">
|
|
<table WIDTH="100%" NOSAVE >
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C:</td>
|
|
|
|
<td WIDTH="85%">
|
|
int <b>Zoltan_Compute_Destinations</b>
|
|
(
|
|
<br> struct <b>Zoltan_Struct</b> *<i>zz</i>,
|
|
<br> int <i>num_known</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_local_ids</i>,
|
|
<br> int *<i>known_procs</i>,
|
|
<br> int *<i>num_found</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_local_ids</i>,
|
|
<br> int **<i>found_procs</i>); </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
|
|
|
|
<td>FUNCTION <b>Zoltan_Compute_Destinations</b>(<i>zz, num_known, known_global_ids,
|
|
known_local_ids, known_procs, num_found, found_global_ids, found_local_ids,
|
|
found_procs</i>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Compute_Destinations
|
|
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
|
|
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_known
|
|
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<hr WIDTH="100%"><b>Zoltan_Compute_Destinations</b> is a wrapper around
|
|
<a href="#Zoltan_Invert_Lists"><b>Zoltan_Invert_Lists</b></a> that excludes
|
|
part assignment arrays. It is maintained for backward compatibility with
|
|
previous versions of Zoltan.
|
|
<p>
|
|
<b>Zoltan_Compute_Destinations</b> 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 <b>Zoltan_Compute_Destinations</b>. These lists can be freed through a
|
|
call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Data">Zoltan_LB_Free_Data</a></b> or
|
|
<b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP></td>
|
|
|
|
<td>
|
|
All arguments are analogous to those in
|
|
<a href="#Zoltan_Invert_Lists"><b>Zoltan_Invert_Lists</b></a>.
|
|
Part-assignment arrays <i>known_to_part</i> and <i>found_to_part</i> are
|
|
not included, as part and processor numbers are assumed to be the same in
|
|
<b>Zoltan_Compute_Destinations</b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
|
|
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
|
|
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
|
|
before calling <b>Zoltan_Compute_Destinations</b>. All processors must have
|
|
the same values for these two parameters.
|
|
<p>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr WIDTH="100%">
|
|
<a NAME="Zoltan_Help_Migrate"></a>
|
|
<hr WIDTH="100%">
|
|
<table WIDTH="100%" NOSAVE >
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP NOSAVE>C:</td>
|
|
|
|
<td WIDTH="85%">
|
|
int <b>Zoltan_Help_Migrate</b> (
|
|
<br> struct <b>Zoltan_Struct</b> *<i>zz</i>,
|
|
<br> int <i>num_import</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_local_ids</i>,
|
|
<br> int *<i>import_procs</i>,
|
|
<br> int <i>num_export</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_global_ids</i>,
|
|
<br> <a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_local_ids</i>,
|
|
<br> int *<i>export_procs</i>); </td>
|
|
</tr>
|
|
|
|
<tr NOSAVE>
|
|
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>
|
|
|
|
<td>FUNCTION <b>Zoltan_Help_Migrate</b>(<i>zz, num_import, import_global_ids,
|
|
import_local_ids, import_procs, num_export, export_global_ids, export_local_ids,
|
|
export_procs</i>)
|
|
<br>INTEGER(Zoltan_INT) :: Zoltan_Help_Migrate
|
|
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
|
|
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids
|
|
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs </td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<hr WIDTH="100%"><b>Zoltan_Help_Migrate</b>
|
|
is a wrapper around <a href="#Zoltan_Migrate"><b>Zoltan_Migrate</b></a>
|
|
that excludes part assignment arrays. It is maintained for backward
|
|
compatibility with previous versions of Zoltan.
|
|
<p>
|
|
<b>Zoltan_Help_Migrate</b> assumes the number of parts is equal to the
|
|
number of processors. It uses migration pre-, mid-, and post-processing
|
|
routines
|
|
<b><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_FN">ZOLTAN_PRE_MIGRATE_FN_TYPE</a></b>,
|
|
<b><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_FN">ZOLTAN_MID_MIGRATE_FN_TYPE</a></b>, and
|
|
<b><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_FN">ZOLTAN_POST_MIGRATE_FN_TYPE</a></b>, respectively, which also exclude part assignment arrays.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP></td>
|
|
|
|
<td>
|
|
All arguments are analogous to those in
|
|
<a href="#Zoltan_Migrate"><b>Zoltan_Migrate</b></a>.
|
|
Part-assignment arrays <i>import_to_part</i> and <i>export_to_part</i> are
|
|
not included, as part and processor numbers are assumed to be the same in
|
|
<b>Zoltan_Help_Migrate</b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<!------------------------------------------------------------------------->
|
|
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a> | <a href="ug_interface_order.html">Next:
|
|
Ordering Interface</a> | <a href="ug_interface_augment.html">Previous:
|
|
Functions for Augmenting a Decomposition</a> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
|
</body>
|
|
</html>
|
|
|