PetscSFCreateByMatchingIndices#

Create PetscSF 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 Parameters#

  • 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 PetscSF

  [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 PetscSF

  [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 PetscSF

  [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#

PetscSF, PetscSFCreate()

Level#

advanced

Location#

src/vec/is/sf/utils/sfutils.c

Index of all PetscSF routines
Table of Contents for all manual pages
Index of all manual pages