1a4963045SJacob Faibussowitsch #pragma once 20c312b8eSJed Brown 3ac09b921SBarry Smith /* SUBMANSEC = PetscSF */ 4ac09b921SBarry Smith 50c312b8eSJed Brown /*S 687497f52SBarry Smith PetscSF - PETSc object for setting up and managing the communication of certain entries of arrays and `Vec` between MPI ranks. 70c312b8eSJed Brown 80c312b8eSJed Brown Level: intermediate 90c312b8eSJed Brown 1087497f52SBarry Smith `PetscSF` uses the concept of star forests to indicate and determine the communication patterns concisely and efficiently. 11af27ebaaSBarry Smith A star <https://en.wikipedia.org/wiki/Star_(graph_theory)> forest is simply a collection of trees of height 1. The leave nodes represent 120c312b8eSJed Brown "ghost locations" for the root nodes. 130c312b8eSJed Brown 14db781477SPatrick Sanan .seealso: `PetscSFCreate()`, `VecScatter`, `VecScatterCreate()` 150c312b8eSJed Brown S*/ 160c312b8eSJed Brown typedef struct _p_PetscSF *PetscSF; 170c312b8eSJed Brown 1897929ea7SJunchao Zhang /*J 1987497f52SBarry Smith PetscSFType - String with the name of a `PetscSF` type 2097929ea7SJunchao Zhang 2197929ea7SJunchao Zhang Level: beginner 2297929ea7SJunchao Zhang 23db781477SPatrick Sanan .seealso: `PetscSFSetType()`, `PetscSF` 2497929ea7SJunchao Zhang J*/ 2597929ea7SJunchao Zhang typedef const char *PetscSFType; 2620662ed9SBarry Smith #define PETSCSFBASIC "basic" 2720662ed9SBarry Smith #define PETSCSFNEIGHBOR "neighbor" 2820662ed9SBarry Smith #define PETSCSFALLGATHERV "allgatherv" 2920662ed9SBarry Smith #define PETSCSFALLGATHER "allgather" 3020662ed9SBarry Smith #define PETSCSFGATHERV "gatherv" 3120662ed9SBarry Smith #define PETSCSFGATHER "gather" 3220662ed9SBarry Smith #define PETSCSFALLTOALL "alltoall" 3320662ed9SBarry Smith #define PETSCSFWINDOW "window" 3497929ea7SJunchao Zhang 35799f573fSMatthew G. Knepley /*S 36799f573fSMatthew G. Knepley PetscSFNode - specifier of owner and index 37799f573fSMatthew G. Knepley 38799f573fSMatthew G. Knepley Level: beginner 39799f573fSMatthew G. Knepley 4038ab3f8aSBarry Smith Sample Usage: 4116a05f60SBarry Smith .vb 4216a05f60SBarry Smith PetscSFNode *remote; 4316a05f60SBarry Smith PetscCall(PetscMalloc1(nleaves,&remote)); 4416a05f60SBarry Smith for (i=0; i<size; i++) { 4516a05f60SBarry Smith remote[i].rank = i; 4616a05f60SBarry Smith remote[i].index = rank; 4716a05f60SBarry Smith } 4816a05f60SBarry Smith .ve 4938ab3f8aSBarry Smith 5038ab3f8aSBarry Smith Sample Fortran Usage: 5116a05f60SBarry Smith .vb 5216a05f60SBarry Smith type(PetscSFNode) remote(6) 5316a05f60SBarry Smith remote(1)%rank = modulo(rank+size-1,size) 5416a05f60SBarry Smith remote(1)%index = 1 * stride 5516a05f60SBarry Smith .ve 5638ab3f8aSBarry Smith 576497c311SBarry Smith Notes: 586497c311SBarry Smith Use `MPIU_SF_NODE` when performing MPI operations on arrays of `PetscSFNode` 596497c311SBarry Smith 606497c311SBarry Smith 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. 616497c311SBarry Smith 6216a05f60SBarry Smith .seealso: `PetscSF`, `PetscSFSetGraph()` 63799f573fSMatthew G. Knepley S*/ 64799f573fSMatthew G. Knepley typedef struct { 65799f573fSMatthew G. Knepley PetscInt rank; /* Rank of owner */ 66799f573fSMatthew G. Knepley PetscInt index; /* Index of node on rank */ 67799f573fSMatthew G. Knepley } PetscSFNode; 68799f573fSMatthew G. Knepley 696497c311SBarry Smith #define MPIU_SF_NODE MPIU_2INT 706497c311SBarry Smith 7197929ea7SJunchao Zhang /*S 7297929ea7SJunchao Zhang VecScatter - Object used to manage communication of data 73*0b4b7b1cSBarry Smith between vectors in parallel or between parallel and sequential vectors. Manages both scatters and gathers 7497929ea7SJunchao Zhang 7597929ea7SJunchao Zhang Level: beginner 7697929ea7SJunchao Zhang 7787497f52SBarry Smith .seealso: `Vec`, `PetscSF`, `VecScatterCreate()`, `VecScatterBegin()`, `VecScatterEnd()` 7897929ea7SJunchao Zhang S*/ 7997929ea7SJunchao Zhang typedef PetscSF VecScatter; 8097929ea7SJunchao Zhang 8197929ea7SJunchao Zhang /*J 8297929ea7SJunchao Zhang VecScatterType - String with the name of a PETSc vector scatter type 8397929ea7SJunchao Zhang 8497929ea7SJunchao Zhang Level: beginner 8597929ea7SJunchao Zhang 8687497f52SBarry Smith .seealso: `PetscSFType`, `VecScatterSetType()`, `VecScatter`, `VecScatterCreate()`, `VecScatterDestroy()` 8797929ea7SJunchao Zhang J*/ 8897929ea7SJunchao Zhang typedef PetscSFType VecScatterType; 89