SAMappingSetSizes

Sets the local and global sizes for the domain and range, and checks to determine compatibility

Synopsis

#include "petscsa.h"  
PetscErrorCode  SAMappingSetSizes(SAMapping map, PetscInt m, PetscInt n, PetscInt M, PetscInt N)
Collective on SAMapping

Input Parameters

map - the mapping
m - number of local domain indices (or PETSC_DETERMINE)
n - number of local range columns (or PETSC_DETERMINE)
M - number of global domain indices (or PETSC_DETERMINE or PETSC_IGNORE)
N - number of global range indices (or PETSC_DETERMINE or PETSC_IGNORE)

Notes

The sizes specify (i) what the domain and range for the graph underlying SAMapping is, and (b) what the parallel layout of the domain and range are. The local and global sizes m and M (and n and N) are not independent. Two situations are possible the domain

(and,analogously, for the range)

(P) Parallel layout for the domain demands that the local values of m on all ranks of the communicator add up to M (see more at MatSetSizes, for example). Thus, m and M must be specified in this compatible way. One way to ensure this is to specify m and leave M as PETSC_DETERMINE -- then M is computed by summing the local m across the ranks. The other option is to specify M (the same on all ranks, which will be checked) and leave m as PETSC_DETERMINE. In this case the local m is determined by dividing M as equally as possible among the ranks (m might end up being 0). If both m and M are specified, their compatibility is verified by summing the m across the ranks. If m or M are PETSC_DETERMINE on one rank, they must be PETSC_DETERMINE on all of the ranks, or the program might hang. Finally, both m and M cannot be PETSC_DETERMINE at once.

In any case, domain indices can have any value 0 <= i < M on every rank (with the same M). However, domain indices are split up among the ranks: each rank will "own" m indices with the indices owned by rank 0 numbered [0,m), followed by the indices on rank 1, and so on.

(S) Sequential layout for the domain makes it essentially into a disjoint union of local domains of local size m. This is signalled by specifying M as PETSC_IGNORE.

In this case, domain indices can have any value 0 <= i < m on every rank (with its own m).

Assembly/Mapping

Whether the domain is laid out in parallel (P) or not (S), determines the behavior of SAMapping during assembly. In case (P), the edges of the underlying graph are migrated to the rank that owns the corresponding domain indices. SAMapping can map indices lying in its local range, which is a subset of its local domain. This means that due to parallel assembly edges inserted by different ranks might be used during the mapping. This is completely analogous to matrix assembly.

When the domain is not laid out in parallel, no migration takes place and the mapping of indices is done purely locally.

Support/Image

Observe that the support and image of the graph may be strictly smaller than its domain and range, if no edges from some domain points (or to some range points) are added to SAMapping.

Operator

Observe also that the linear operator defined by SAMapping will behave essentially as a VecScatter (i) between MPI vectors with sizes (m,M) and (n,N), if both the domain and the range are (P), (ii) between an MPI Vec with size (m,M) and a collection of SEQ Vecs (one per rank) of local size (n), if the domain is (P) and the range is (S), (iii) between a collection of SEQ Vecs (one per rank) of local size (m) and an MPI Vec of size (n,N), if the domain is (S) and the range is (P), (iv) between collections of SEQ Vecs (one per rank) or local sizes (m) and (n), if both the domain and the range are (S).

See Also

SAMappingGetSizes(), SAMappingGetSupportSize(), SAMappingGetImageSize(), SAMappingMapIndicesLocal()

Level:beginner
Location:
src/dm/sa/interface/sa.c
Index of all DM routines
Table of Contents for all manual pages
Index of all manual pages