petsc-3.15.0 2021-04-05
Report Typos and Errors

PetscSFCreateByMatchingIndices

Create SF by matching root and leaf indices

Synopsis

#include "petscsf.h"   
PetscErrorCode PetscSFCreateByMatchingIndices(PetscLayout layout, PetscInt numRootIndices, const PetscInt *rootIndices, const PetscInt *rootLocalIndices, PetscInt rootLocalOffset, PetscInt numLeafIndices, const PetscInt *leafIndices, const PetscInt *leafLocalIndices, PetscInt leafLocalOffset, PetscSF *sfA, PetscSF *sf)
Collective

Input Parameters

layout - PetscLayout defining the global index space and the rank that brokers each index
numRootIndices - size of rootIndices
rootIndices - PetscInt array of global indices of which this process requests ownership
rootLocalIndices - root local index permutation (NULL if no permutation)
rootLocalOffset - offset to be added to root local indices
numLeafIndices - size of leafIndices
leafIndices - PetscInt array of global indices with which this process requires data associated
leafLocalIndices - leaf local index permutation (NULL if no permutation)
leafLocalOffset - offset to be added to leaf local indices

Output Parameter

sfA - star forest representing the communication pattern from the layout space to the leaf space (NULL if not needed)
sf - star forest representing the communication pattern from the root space to the leaf space

Example 1


 rank             : 0            1            2
 rootIndices      : [1 0 2]      [3]          [3]
 rootLocalOffset  : 100          200          300
 layout           : [0 1]        [2]          [3]
 leafIndices      : [0]          [2]          [0 3]
 leafLocalOffset  : 400          500          600

would build the following SF


 [0] 400 <- (0,101)
 [1] 500 <- (0,102)
 [2] 600 <- (0,101)
 [2] 601 <- (2,300)

Example 2


 rank             : 0               1               2
 rootIndices      : [1 0 2]         [3]             [3]
 rootLocalOffset  : 100             200             300
 layout           : [0 1]           [2]             [3]
 leafIndices      : rootIndices     rootIndices     rootIndices
 leafLocalOffset  : rootLocalOffset rootLocalOffset rootLocalOffset

would build the following SF


 [1] 200 <- (2,300)

Example 3


 No process requests ownership of global index 1, but no process needs it.

 rank             : 0            1            2
 numRootIndices   : 2            1            1
 rootIndices      : [0 2]        [3]          [3]
 rootLocalOffset  : 100          200          300
 layout           : [0 1]        [2]          [3]
 numLeafIndices   : 1            1            2
 leafIndices      : [0]          [2]          [0 3]
 leafLocalOffset  : 400          500          600

would build the following SF


 [0] 400 <- (0,100)
 [1] 500 <- (0,101)
 [2] 600 <- (0,100)
 [2] 601 <- (2,300)

Notes

The layout parameter represents any partitioning of [0, N), where N is the total number of global indices, and its local size can be set to PETSC_DECIDE. If a global index x lies in the partition owned by process i, each process whose rootIndices contains x requests ownership of x and sends its own rank and the local index of x to process i. If multiple processes request ownership of x, the one with the highest rank is to own x. Process i then broadcasts the ownership information, so that each process whose leafIndices contains x knows the ownership information of x. The output sf is constructed by associating each leaf point to a root point in this way.

Suppose there is point data ordered according to the global indices and partitioned according to the given layout. The optional output PetscSF object sfA can be used to push such data to leaf points.

All indices in rootIndices and leafIndices must lie in the layout range. The union (over all processes) of rootIndices must cover that of leafIndices, but need not cover the entire layout.

If (leafIndices, leafLocalIndices, leafLocalOffset) == (rootIndices, rootLocalIndices, rootLocalOffset), the output star forest is almost identity, so will only include non-trivial part of the map.

Developer Notes

Current approach of a process of the highest rank gaining the ownership may cause load imbalance; consider using hash(rank, root_local_index) as the bid for the ownership determination.

See Also

PetscSFCreate()

Level

advanced

Location

src/vec/is/sf/utils/sfutils.c
Index of all SF routines
Table of Contents for all manual pages
Index of all manual pages