1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
<center><a href="https://gitlab.com/petsc/petsc/-/blob/2cd11c936b2c10bfd58f60105eda30ca65946a12/include/petscsftypes.h">Actual source code: petscsftypes.h</a></center><br>
<html>
<head>
<title></title>
<meta name="generator" content="c2html 0.9.6">
<meta name="date" content="2026-01-01T23:31:07+00:00">
</head>
<body bgcolor="#FFFFFF">
<pre width=80>
<a name="line1"> 1: </a><font color="#A020F0">#pragma once</font>
<a name="line3"> 3: </a><font color="#B22222">/* MANSEC = <a href="../manualpages/Vec/Vec.html">Vec</a> */</font>
<a name="line4"> 4: </a><font color="#B22222">/* SUBMANSEC = <a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a> */</font>
<a name="line6"> 6: </a><font color="#B22222">/*S</font>
<a name="line7"> 7: </a><font color="#B22222"> <a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a> - PETSc object for managing the communication of certain entries of arrays and `<a href="../manualpages/Vec/Vec.html">Vec</a>` between MPI processes.</font>
<a name="line9"> 9: </a><font color="#B22222"> Level: intermediate</font>
<a name="line11"> 11: </a><font color="#B22222"> `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>` uses the concept of star forests to indicate and determine the communication patterns concisely and efficiently.</font>
<a name="line12"> 12: </a><font color="#B22222"> A star <https://en.wikipedia.org/wiki/Star_(graph_theory)> forest is simply a collection of trees of height 1. The leave nodes represent</font>
<a name="line13"> 13: </a><font color="#B22222"> "ghost locations" for the root nodes.</font>
<a name="line15"> 15: </a><font color="#B22222"> The standard usage paradigm for `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>` is to provide the communication pattern with `<a href="../manualpages/PetscSF/PetscSFSetGraph.html">PetscSFSetGraph</a>()` or `<a href="../manualpages/PetscSF/PetscSFSetGraphWithPattern.html">PetscSFSetGraphWithPattern</a>()` and</font>
<a name="line16"> 16: </a><font color="#B22222"> then perform the communication using `<a href="../manualpages/PetscSF/PetscSFBcastBegin.html">PetscSFBcastBegin</a>()` and `<a href="../manualpages/PetscSF/PetscSFBcastEnd.html">PetscSFBcastEnd</a>()`, `<a href="../manualpages/PetscSF/PetscSFReduceBegin.html">PetscSFReduceBegin</a>()` and `<a href="../manualpages/PetscSF/PetscSFReduceEnd.html">PetscSFReduceEnd</a>()`.</font>
<a name="line18"> 18: </a><font color="#B22222">.seealso: [](sec_petscsf), `<a href="../manualpages/PetscSF/PetscSFCreate.html">PetscSFCreate</a>()`, `<a href="../manualpages/PetscSF/PetscSFSetGraph.html">PetscSFSetGraph</a>()`, `<a href="../manualpages/PetscSF/PetscSFSetGraphWithPattern.html">PetscSFSetGraphWithPattern</a>()`, `<a href="../manualpages/PetscSF/PetscSFBcastBegin.html">PetscSFBcastBegin</a>()`, `<a href="../manualpages/PetscSF/PetscSFBcastEnd.html">PetscSFBcastEnd</a>()`,</font>
<a name="line19"> 19: </a><font color="#B22222"> `<a href="../manualpages/PetscSF/PetscSFReduceBegin.html">PetscSFReduceBegin</a>()`, `<a href="../manualpages/PetscSF/PetscSFReduceEnd.html">PetscSFReduceEnd</a>()`, `<a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a>`, `<a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a>()`</font>
<a name="line20"> 20: </a><font color="#B22222">S*/</font>
<a name="line21"> 21: </a><font color="#4169E1">typedef struct _p_PetscSF *<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>;</font>
<a name="line23"> 23: </a><font color="#B22222">/*J</font>
<a name="line24"> 24: </a><font color="#B22222"> <a href="../manualpages/PetscSF/PetscSFType.html">PetscSFType</a> - String with the name of a `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>` type. Each `<a href="../manualpages/PetscSF/PetscSFType.html">PetscSFType</a>` uses different mechanisms to perform the communication.</font>
<a name="line26"> 26: </a><font color="#B22222"> Level: beginner</font>
<a name="line28"> 28: </a><font color="#B22222"> Available Types:</font>
<a name="line29"> 29: </a><font color="#B22222">+ `PETSCSFBASIC` - use MPI sends and receives</font>
<a name="line30"> 30: </a><font color="#B22222">. `PETSCSFNEIGHBOR` - use MPI_Neighbor operations</font>
<a name="line31"> 31: </a><font color="#B22222">. `PETSCSFALLGATHERV` - use <a href="http://www.mpich.org/static/docs/latest/www3/MPI_Allgatherv.html#MPI_Allgatherv">MPI_Allgatherv</a> operations</font>
<a name="line32"> 32: </a><font color="#B22222">. `PETSCSFALLGATHER` - use <a href="http://www.mpich.org/static/docs/latest/www3/MPI_Allgather.html#MPI_Allgather">MPI_Allgather</a> operations</font>
<a name="line33"> 33: </a><font color="#B22222">. `PETSCSFGATHERV` - use <a href="http://www.mpich.org/static/docs/latest/www3/MPI_Igatherv.html#MPI_Igatherv">MPI_Igatherv</a> and <a href="http://www.mpich.org/static/docs/latest/www3/MPI_Iscatterv.html#MPI_Iscatterv">MPI_Iscatterv</a> operations</font>
<a name="line34"> 34: </a><font color="#B22222">. `PETSCSFGATHER` - use <a href="http://www.mpich.org/static/docs/latest/www3/MPI_Igather.html#MPI_Igather">MPI_Igather</a> and <a href="http://www.mpich.org/static/docs/latest/www3/MPI_Iscatter.html#MPI_Iscatter">MPI_Iscatter</a> operations</font>
<a name="line35"> 35: </a><font color="#B22222">. `PETSCSFALLTOALL` - use <a href="http://www.mpich.org/static/docs/latest/www3/MPI_Ialltoall.html#MPI_Ialltoall">MPI_Ialltoall</a> operations</font>
<a name="line36"> 36: </a><font color="#B22222">- `PETSCSFWINDOW` - use MPI_Win operations</font>
<a name="line38"> 38: </a><font color="#B22222"> Note:</font>
<a name="line39"> 39: </a><font color="#B22222"> Some `<a href="../manualpages/PetscSF/PetscSFType.html">PetscSFType</a>` only provide specialized code for a subset of the `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>` operations and use `PETSCSFBASIC` for the others.</font>
<a name="line41"> 41: </a><font color="#B22222">.seealso: [](sec_petscsf), `<a href="../manualpages/PetscSF/PetscSFSetType.html">PetscSFSetType</a>()`, `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>`</font>
<a name="line42"> 42: </a><font color="#B22222">J*/</font>
<a name="line43"> 43: </a><font color="#4169E1">typedef const char *<a href="../manualpages/PetscSF/PetscSFType.html">PetscSFType</a>;</font>
<a name="line44"> 44: </a><strong><font color="#228B22">#define PETSCSFBASIC </font><font color="#666666">"basic"</font><font color="#228B22"></font></strong>
<a name="line45"> 45: </a><strong><font color="#228B22">#define PETSCSFNEIGHBOR </font><font color="#666666">"neighbor"</font><font color="#228B22"></font></strong>
<a name="line46"> 46: </a><strong><font color="#228B22">#define PETSCSFALLGATHERV </font><font color="#666666">"allgatherv"</font><font color="#228B22"></font></strong>
<a name="line47"> 47: </a><strong><font color="#228B22">#define PETSCSFALLGATHER </font><font color="#666666">"allgather"</font><font color="#228B22"></font></strong>
<a name="line48"> 48: </a><strong><font color="#228B22">#define PETSCSFGATHERV </font><font color="#666666">"gatherv"</font><font color="#228B22"></font></strong>
<a name="line49"> 49: </a><strong><font color="#228B22">#define PETSCSFGATHER </font><font color="#666666">"gather"</font><font color="#228B22"></font></strong>
<a name="line50"> 50: </a><strong><font color="#228B22">#define PETSCSFALLTOALL </font><font color="#666666">"alltoall"</font><font color="#228B22"></font></strong>
<a name="line51"> 51: </a><strong><font color="#228B22">#define PETSCSFWINDOW </font><font color="#666666">"window"</font><font color="#228B22"></font></strong>
<a name="line53"> 53: </a><font color="#B22222">/*S</font>
<a name="line54"> 54: </a><font color="#B22222"> <a href="../manualpages/PetscSF/PetscSFNode.html">PetscSFNode</a> - specifier of MPI rank owner and local index for array or `<a href="../manualpages/Vec/Vec.html">Vec</a>` entry locations that are to be communicated with a `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>`</font>
<a name="line56"> 56: </a><font color="#B22222"> Level: beginner</font>
<a name="line58"> 58: </a><font color="#B22222"> Sample Usage:</font>
<a name="line59"> 59: </a><font color="#B22222">.vb</font>
<a name="line60"> 60: </a><font color="#B22222"> <a href="../manualpages/PetscSF/PetscSFNode.html">PetscSFNode</a> *remote;</font>
<a name="line61"> 61: </a><font color="#B22222"> <a href="../manualpages/Sys/PetscCall.html">PetscCall</a>(<a href="../manualpages/Sys/PetscMalloc1.html">PetscMalloc1</a>(nleaves,&remote));</font>
<a name="line62"> 62: </a><font color="#B22222"> for (i=0; i<size; i++) {</font>
<a name="line63"> 63: </a><font color="#B22222"> remote[i].rank = i;</font>
<a name="line64"> 64: </a><font color="#B22222"> remote[i].index = rank;</font>
<a name="line65"> 65: </a><font color="#B22222"> }</font>
<a name="line66"> 66: </a><font color="#B22222">.ve</font>
<a name="line68"> 68: </a><font color="#B22222"> Sample Fortran Usage:</font>
<a name="line69"> 69: </a><font color="#B22222">.vb</font>
<a name="line70"> 70: </a><font color="#B22222"> type(<a href="../manualpages/PetscSF/PetscSFNode.html">PetscSFNode</a>) remote(6)</font>
<a name="line71"> 71: </a><font color="#B22222"> remote(1)%rank = modulo(rank+size-1,size)</font>
<a name="line72"> 72: </a><font color="#B22222"> remote(1)%index = 1 * stride</font>
<a name="line73"> 73: </a><font color="#B22222">.ve</font>
<a name="line75"> 75: </a><font color="#B22222"> Notes:</font>
<a name="line76"> 76: </a><font color="#B22222"> Use `MPIU_SF_NODE` when performing MPI operations on arrays of `<a href="../manualpages/PetscSF/PetscSFNode.html">PetscSFNode</a>`</font>
<a name="line78"> 78: </a><font color="#B22222"> 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.</font>
<a name="line80"> 80: </a><font color="#B22222">.seealso: [](sec_petscsf), `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>`, `<a href="../manualpages/PetscSF/PetscSFSetGraph.html">PetscSFSetGraph</a>()`</font>
<a name="line81"> 81: </a><font color="#B22222">S*/</font>
<a name="line82"> 82: </a><font color="#4169E1">typedef</font> <font color="#4169E1">struct</font> {
<a name="line83"> 83: </a> <a href="../manualpages/Sys/PetscInt.html">PetscInt</a> rank; <font color="#B22222">/* MPI rank of owner */</font>
<a name="line84"> 84: </a> <a href="../manualpages/Sys/PetscInt.html">PetscInt</a> index; <font color="#B22222">/* Index of node on rank */</font>
<a name="line85"> 85: </a>} <a href="../manualpages/PetscSF/PetscSFNode.html">PetscSFNode</a>;
<a name="line87"> 87: </a><strong><font color="#228B22">#define MPIU_SF_NODE MPIU_2INT</font></strong>
<a name="line89"> 89: </a><font color="#4169E1">typedef</font> <font color="#4169E1">enum</font> {
<a name="line90"> 90: </a> PETSCSF_ROOT2LEAF = 0,
<a name="line91"> 91: </a> PETSCSF_LEAF2ROOT = 1
<a name="line92"> 92: </a>} PetscSFDirection;
<a name="line93"> 93: </a><font color="#4169E1">typedef</font> <font color="#4169E1">enum</font> {
<a name="line94"> 94: </a> PETSCSF_BCAST = 0,
<a name="line95"> 95: </a> PETSCSF_REDUCE = 1,
<a name="line96"> 96: </a> PETSCSF_FETCH = 2
<a name="line97"> 97: </a>} PetscSFOperation;
<a name="line98"> 98: </a><font color="#B22222">/* When doing device-aware MPI, a backend refers to the SF/device interface */</font>
<a name="line99"> 99: </a><font color="#4169E1">typedef</font> <font color="#4169E1">enum</font> {
<a name="line100">100: </a> PETSCSF_BACKEND_INVALID = 0,
<a name="line101">101: </a> PETSCSF_BACKEND_CUDA = 1,
<a name="line102">102: </a> PETSCSF_BACKEND_HIP = 2,
<a name="line103">103: </a> PETSCSF_BACKEND_KOKKOS = 3
<a name="line104">104: </a>} PetscSFBackend;
<a name="line105">105: </a><font color="#4169E1">typedef struct _n_PetscSFLink *PetscSFLink;</font>
<a name="line107">107: </a><font color="#B22222">/*S</font>
<a name="line108">108: </a><font color="#B22222"> <a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a> - Object used to manage communication of data</font>
<a name="line109">109: </a><font color="#B22222"> between vectors in parallel or between parallel and sequential vectors. Manages both scatters and gathers</font>
<a name="line111">111: </a><font color="#B22222"> Level: beginner</font>
<a name="line113">113: </a><font color="#B22222"> Note:</font>
<a name="line114">114: </a><font color="#B22222"> This is an alias for `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>`.</font>
<a name="line116">116: </a><font color="#B22222">.seealso: [](sec_petscsf), `<a href="../manualpages/Vec/Vec.html">Vec</a>`, `<a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a>`, `<a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a>()`, `<a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a>()`, `<a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a>()`</font>
<a name="line117">117: </a><font color="#B22222">S*/</font>
<a name="line118">118: </a><font color="#4169E1">typedef <a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a> <a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a>;</font>
<a name="line120">120: </a><font color="#B22222">/*J</font>
<a name="line121">121: </a><font color="#B22222"> <a href="../manualpages/PetscSF/VecScatterType.html">VecScatterType</a> - String with the name of a PETSc vector scatter type</font>
<a name="line123">123: </a><font color="#B22222"> Level: beginner</font>
<a name="line125">125: </a><font color="#B22222"> Note:</font>
<a name="line126">126: </a><font color="#B22222"> This is an alias for `<a href="../manualpages/PetscSF/PetscSFType.html">PetscSFType</a>`</font>
<a name="line128">128: </a><font color="#B22222">.seealso: [](sec_petscsf), `<a href="../manualpages/PetscSF/PetscSFType.html">PetscSFType</a>`, `<a href="../manualpages/Vec/VecScatterSetType.html">VecScatterSetType</a>()`, `<a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a>`, `<a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a>()`, `<a href="../manualpages/Vec/VecScatterDestroy.html">VecScatterDestroy</a>()`</font>
<a name="line129">129: </a><font color="#B22222">J*/</font>
<a name="line130">130: </a><font color="#4169E1">typedef <a href="../manualpages/PetscSF/PetscSFType.html">PetscSFType</a> <a href="../manualpages/PetscSF/VecScatterType.html">VecScatterType</a>;</font>
</pre>
</body>
</html>
|
