16 Convert From Global Map To Global Segment Map

16.1 Module m_ConvertMaps - Conversion Between MCT Domain Decomposition Descriptors (Source File: m_ConvertMaps.F90)

This module contains routines to convert between the GlobalMap and GlobalSegMap types. Since the GlobalMap is a 1-D decomposition with one contiguous segment per process, it is always possible to create a GlobalSegMap containing the same decomposition information. In the unusual case that a GlobalSegMap contains at most one segment per process, and no two segments overlap, it is possible to create a GlobalMap describing the same decomposition.

INTERFACE:

 
  module m_ConvertMaps

USES:

       use m_GlobalMap,    only : GlobalMap
       use m_GlobalSegMap, only : GlobalSegMap
 
       implicit none
 
       private   ! except

PUBLIC MEMBER FUNCTIONS:

 
       public :: GlobalMapToGlobalSegMap
       public :: GlobalSegMapToGlobalMap
 
 
     interface GlobalMapToGlobalSegMap ; module procedure &
         GlobalMapToGlobalSegMap_
     end interface
     interface GlobalSegMapToGlobalMap ; module procedure &
         GlobalSegMapToGlobalMap_
     end interface

REVISION HISTORY:

   12Feb01 - J.W. Larson <larson@mcs.anl.gov> - initial module

16.1.1 GlobalMapToGlobalSegMap_ - Convert GlobalMap to GlobalSegMap

This routine takes an input GlobalMap argument GMap, and converts its decomposition information into the output GlobalSegMap argument GSMap. Since the GlobalMap is a very special case of the more general GlobalSegMap decomposition, this conversion is always possible.

The motivation of this routine is the fact that the majority of the APIs for MCT services require the user to supply a GlobalSegMap as a domain decomposition descriptor argument. This routine is the means by which the user can enjoy the convenience and simplicity of the GlobalMap datatype (where it is appropriate), but still access all of the MCT's functionality.

N.B.: This routine creates an allocated structure GSMap. The user is responsible for deleting this structure using the clean() method for the GlobalSegMap when GSMap is no longer needed. Failure to do so will create a memory leak.

INTERFACE:

 
  subroutine GlobalMapToGlobalSegMap_(GMap, GSMap)

USES:

       use m_stdio, only : stderr
       use m_die,   only : MP_perr_die, die, warn
 
       use m_GlobalMap,    only : GlobalMap
 
       use m_GlobalSegMap, only : GlobalSegMap
       use m_GlobalSegMap, only : GlobalSegMap_init => init
 
       use m_MCTWorld, only : ThisMCTWorld
       use m_MCTWorld, only : MCTWorld_ComponentNumProcs => ComponentNumProcs
 
       implicit none

INPUT PARAMETERS:

 
       type(GlobalMap),    intent(in)  :: GMap

OUTPUT PARAMETERS:

 
       type(GlobalSegMap), intent(out) :: GSMap

REVISION HISTORY:

   12Feb01 - J.W. Larson <larson@mcs.anl.gov> - Prototype code.
   24Feb01 - J.W. Larson <larson@mcs.anl.gov> - Finished code.

16.1.2 GlobalSegMapToGlobalMap_ - Convert GlobalSegMap to GlobalMap

This routine takes an input GlobalSegMap argument GSMap, and examines it to determine whether or not it may be expressed in GlobalMap form. A GlobalSegMap can be converted to a GlobalMap if and only if:

1. Each process on the communicator covered by the GlobalSegMap contains at most one segment;
2. The GlobalSegMap is not haloed (that is, none of the segments overlap); and
3. The start indices of the segments are in the same order as their respective process ID numbers.

If these conditions are satisfied, GlobalSegMapToGlobalMap_() creates an output GlobalMap argument GMap describing the same decomposition as GSMap. If these conditions are not satisfied, map conversion can not occur, and GlobalSegMapToGlobalMap_() has one of two outcomes:

1. If the optional output INTEGER argument status is provided, GlobalSegMapToGlobalMap_() returns without creating GMap, and returns a non-zero value for status.
2. If the optional output INTEGER argument status is not provided, execution will terminate with an error message.

The optional output INTEGER argument status, if provided will be returned from GlobalSegMapToGlobalMap_() with a value explained by the table below:

Value of status	Significance
0	Map Conversion Successful
1	Unsuccessful-more than one segment per process,
	or a negative numer of segments (ERROR)
2	Unsuccessful-GSMap haloed
3	Unsuccessful-GSMap segments out-of-order
	with respect to resident process ID ranks

N.B.: This routine creates an allocated structure GMap. The user is responsible for deleting this structure using the clean() method for the GlobalMap when GMap is no longer needed. Failure to do so will create a memory leak.

INTERFACE:

 
  subroutine GlobalSegMapToGlobalMap_(GSMap, GMap, status)

USES:

       use m_stdio, only : stderr
       use m_die,   only : MP_perr_die, die
 
       use m_SortingTools , only : IndexSet
       use m_SortingTools , only : IndexSort
       use m_SortingTools , only : Permute
 
       use m_MCTWorld, only : MCTWorld
       use m_MCTWorld, only : ThisMCTWorld
       use m_MCTWorld, only : ComponentNumProcs
 
       use m_GlobalSegMap, only : GlobalSegMap
       use m_GlobalSegMap, only : GlobalSegMap_comp_id => comp_id
       use m_GlobalSegMap, only : GlobalSegMap_gsize => gsize
       use m_GlobalSegMap, only : GlobalSegMap_haloed => haloed
       use m_GlobalSegMap, only : GlobalSegMap_ngseg => ngseg
       use m_GlobalSegMap, only : GlobalSegMap_nlseg => nlseg
       use m_GlobalSegMap, only : GlobalSegMap_active_pes => active_pes
 
       use m_GlobalMap,    only : GlobalMap
 
       implicit none

INPUT PARAMETERS:

 
       type(GlobalSegMap),           intent(in)  :: GSMap

OUTPUT PARAMETERS:

 
       type(GlobalMap),              intent(out) :: GMap
       integer,            optional, intent(out) :: status

REVISION HISTORY:

   12Feb01 - J.W. Larson <larson@mcs.anl.gov> - API / first prototype.
   21Sep02 - J.W. Larson <larson@mcs.anl.gov> - Near-complete Implementation,
             still, do not call!