1 #pragma once 2 3 /* SUBMANSEC = PetscSF */ 4 5 /*S 6 PetscSF - PETSc object for setting up and managing the communication of certain entries of arrays and `Vec` between MPI ranks. 7 8 Level: intermediate 9 10 `PetscSF` uses the concept of star forests to indicate and determine the communication patterns concisely and efficiently. 11 A star <https://en.wikipedia.org/wiki/Star_(graph_theory)> forest is simply a collection of trees of height 1. The leave nodes represent 12 "ghost locations" for the root nodes. 13 14 .seealso: `PetscSFCreate()`, `VecScatter`, `VecScatterCreate()` 15 S*/ 16 typedef struct _p_PetscSF *PetscSF; 17 18 /*J 19 PetscSFType - String with the name of a `PetscSF` type 20 21 Level: beginner 22 23 .seealso: `PetscSFSetType()`, `PetscSF` 24 J*/ 25 typedef const char *PetscSFType; 26 #define PETSCSFBASIC "basic" 27 #define PETSCSFNEIGHBOR "neighbor" 28 #define PETSCSFALLGATHERV "allgatherv" 29 #define PETSCSFALLGATHER "allgather" 30 #define PETSCSFGATHERV "gatherv" 31 #define PETSCSFGATHER "gather" 32 #define PETSCSFALLTOALL "alltoall" 33 #define PETSCSFWINDOW "window" 34 35 /*S 36 PetscSFNode - specifier of owner and index 37 38 Level: beginner 39 40 Sample Usage: 41 .vb 42 PetscSFNode *remote; 43 PetscCall(PetscMalloc1(nleaves,&remote)); 44 for (i=0; i<size; i++) { 45 remote[i].rank = i; 46 remote[i].index = rank; 47 } 48 .ve 49 50 Sample Fortran Usage: 51 .vb 52 type(PetscSFNode) remote(6) 53 remote(1)%rank = modulo(rank+size-1,size) 54 remote(1)%index = 1 * stride 55 .ve 56 57 Notes: 58 Use `MPIU_SF_NODE` when performing MPI operations on arrays of `PetscSFNode` 59 60 Generally the values of `rank` should be in $[ 0,size)$ and the value of `index` greater than or equal to 0, but there are some situations that violate this. 61 62 .seealso: `PetscSF`, `PetscSFSetGraph()` 63 S*/ 64 typedef struct { 65 PetscInt rank; /* Rank of owner */ 66 PetscInt index; /* Index of node on rank */ 67 } PetscSFNode; 68 69 #define MPIU_SF_NODE MPIU_2INT 70 71 /*S 72 VecScatter - Object used to manage communication of data 73 between vectors in parallel or between parallel and sequential vectors. Manages both scatters and gathers 74 75 Level: beginner 76 77 .seealso: `Vec`, `PetscSF`, `VecScatterCreate()`, `VecScatterBegin()`, `VecScatterEnd()` 78 S*/ 79 typedef PetscSF VecScatter; 80 81 /*J 82 VecScatterType - String with the name of a PETSc vector scatter type 83 84 Level: beginner 85 86 .seealso: `PetscSFType`, `VecScatterSetType()`, `VecScatter`, `VecScatterCreate()`, `VecScatterDestroy()` 87 J*/ 88 typedef PetscSFType VecScatterType; 89