The first two routines provide high-level functionalities and free the user from the burden of calling in sequence several of the low-level routines described afterward.
6.5.1 SCOTCH dgraphPart Synopsis
int SCOTCH dgraphPart (const SCOTCH Dgraph * grafptr, const SCOTCH Num partnbr, const SCOTCH Strat * straptr, SCOTCH Num * partloctab)
scotchfdgraphpart (doubleprecision (*) grafdat,
integer partnbr,
doubleprecision (*) stradat, integer (*) partloctab,
integer ierr)
Description
The SCOTCH dgraphPart routine computes a partition into partnbr parts of the distributed source graph structure pointed to by grafptr, using the graph partitioning strategy pointed to bystratptr, and returns distributed fragments of the partition data in the array pointed to bypartloctab.
Thepartloctabarray should have been previously allocated, of a size suffi- cient to hold as manySCOTCH Num integers as there are local vertices of the source graph on each of the processes.
On return, every array cell holds the number of the part to which the corre- sponding vertex is mapped. Parts are numbered from 0 topartnbr−1.
Return values
SCOTCH dgraphPartreturns 0 if the partition of the graph has been success- fully computed, and 1 else. In this latter case, the partloctab array may however have been partially or completely filled, but its content is not signif- icant.
6.5.2 SCOTCH dgraphMap Synopsis
int SCOTCH dgraphMap (const SCOTCH Dgraph * grafptr, const SCOTCH Arch * archptr, const SCOTCH Strat * straptr, SCOTCH Num * partloctab) scotchfdgraphmap (doubleprecision (*) grafdat,
doubleprecision (*) archdat, doubleprecision (*) stradat, integer (*) partloctab,
integer ierr)
Description
TheSCOTCH dgraphMaproutine computes a mapping of the distributed source graph structure pointed to bygrafptr onto the target architecture pointed to by archptr, using the mapping strategy pointed to by straptr, and re- turns distributed fragments of the partition data in the array pointed to by partloctab.
Thepartloctabarray should have been previously allocated, of a size suffi- cient to hold as manySCOTCH Num integers as there are local vertices of the source graph on each of the processes.
On return, every cell of the mapping array holds the number of the target vertex to which the corresponding source vertex is mapped. The numbering of target values is not based: target vertices are numbered from 0 to the number of target vertices minus 1.
Attention: version 5.1 of Scotch does not allow yet to map distributed graphs onto target architectures which are not complete graphs. This restric- tion will be removed in the next release.
Return values
SCOTCH dgraphMapreturns 0 if the partition of the graph has been successfully computed, and 1 else. In this last case, the partloctabarrays may however have been partially or completely filled, but their contents is not significant.
6.5.3 SCOTCH dgraphMapInit Synopsis
int SCOTCH dgraphMapInit (const SCOTCH Dgraph * grafptr, SCOTCH Dmapping * mappptr, const SCOTCH Arch * archptr, SCOTCH Num * partloctab) scotchfdgraphmapinit (doubleprecision (*) grafdat,
doubleprecision (*) mappdat, doubleprecision (*) archdat, integer (*) partloctab,
integer ierr)
Description
The SCOTCH dgraphMapInit routine fills the distributed mapping structure pointed to bymappptrwith all of the data that is passed to it. Thus, all sub- sequent calls to ordering routines such as SCOTCH dgraphMapCompute, using this mapping structure as parameter, will place mapping results in fieldpart loctab.
partloctabis the pointer to an array of as many SCOTCH Nums as there are local vertices in each local fragment of the distributed graph pointed to by grafptr, and which will receive the indices of the vertices of the target archi- tecture pointed to byarchptr.
It should be the first function to be called upon aSCOTCH Dmappingstructure.
When the distributed mapping structure is no longer of use, call function SCOTCH dgraphMapExitto free its internal structures.
Return values
SCOTCH dgraphMapInit returns 0 if the distributed mapping structure has been successfully initialized, and 1 else.
6.5.4 SCOTCH dgraphMapExit Synopsis
void SCOTCH dgraphMapExit (const SCOTCH Dgraph * grafptr, SCOTCH Dmapping * mappptr) scotchfdgraphmapexit (doubleprecision (*) grafdat,
doubleprecision (*) mappdat) Description
TheSCOTCH dgraphMapExitfunction frees the contents of aSCOTCH Dmapping structure previously initialized by SCOTCH dgraphMapInit. All subsequent calls toSCOTCH dgraphMap*routines other thanSCOTCH dgraphMapInit, us- ing this structure as parameter, may yield unpredictable results.
6.5.5 SCOTCH dgraphMapSave Synopsis
int SCOTCH dgraphMapSave (const SCOTCH Dgraph * grafptr, const SCOTCH Dmapping * mappptr,
FILE * stream)
scotchfdgraphmapsave (doubleprecision (*) grafdat, doubleprecision (*) mappdat,
integer fildes,
integer ierr)
Description
The SCOTCH dgraphMapSave routine saves the contents of the SCOTCH Dmappingstructure pointed to bymappptrto streamstream, in theScotch mapping format. Please refer to the Scotch User’s Guide [35] for more information about this format.
Since the mapping format is centralized, only one process should provide a valid output stream; other processes must pass a null pointer.
Fortran users must use theFNUMfunction to obtain the number of the Unix file descriptorfildesassociated with the logical unit of the mapping file.
Return values
SCOTCH dgraphMapSavereturns 0 if the mapping structure has been success- fully written tostream, and 1 else.
6.5.6 SCOTCH dgraphMapCompute Synopsis
int SCOTCH dgraphMapCompute (const SCOTCH Dgraph * grafptr, SCOTCH Dmapping * mappptr, const SCOTCH Strat * straptr) scotchfdgraphmapcompute (doubleprecision (*) grafdat,
doubleprecision (*) mappdat, doubleprecision (*) stradat,
integer ierr)
Description
The SCOTCH dgraphMapCompute routine computes a mapping on the given SCOTCH Dmappingstructure pointed to bymappptrusing the parallel mapping strategy pointed to bystratptr.
On return, every cell of the distributed mapping array (see section 6.5.3) holds the number of the target vertex to which the corresponding source vertex is mapped. The numbering of target values is not based: target vertices are numbered from 0 to the number of target vertices, minus 1.
Attention: version 5.1 of Scotch does not allow yet to map distributed graphs onto target architectures which are not complete graphs. This restric- tion will be removed in the next release.
Return values
SCOTCH dgraphMapCompute returns 0 if the mapping has been successfully computed, and 1 else. In this latter case, the local mapping arrays may however have been partially or completely filled, but their contents is not significant.