src/base/cs_all_to_all.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_all_to_all.h
Go to the documentation of this file.
1 #ifndef __CS_ALL_TO_ALL_H__
2 #define __CS_ALL_TO_ALL_H__
3
4 /*============================================================================
5 * All-to-all parallel data exchange.
6 *============================================================================*/
7
8 /*
9 This file is part of Code_Saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2013 EDF S.A.
12
13 This program is free software; you can redistribute it and/or modify it under
14 the terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version.
17
18 This program is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21 details.
22
23 You should have received a copy of the GNU General Public License along with
24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25 Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27
28 /*----------------------------------------------------------------------------*/
29
30 #if defined(HAVE_MPI)
31 #include <mpi.h>
32 #endif
33
34 /*----------------------------------------------------------------------------
35 * Local headers
36 *----------------------------------------------------------------------------*/
37
38 #include "cs_defs.h"
39 #include "cs_block_dist.h"
40
41 /*----------------------------------------------------------------------------*/
42
43 BEGIN_C_DECLS
44
45 /*=============================================================================
46 * Macro definitions
47 *============================================================================*/
48
49 /*============================================================================
50 * Type definitions
51 *============================================================================*/
52
53 /* All-to-all algorithm choice */
54
55 typedef enum {
56
57 CS_ALL_TO_ALL_MPI_DEFAULT,
58 CS_ALL_TO_ALL_CRYSTAL_ROUTER
59
60 } cs_all_to_all_type_t;
61
62 /* Opaque all-to-all distribution structure */
63
64 #if defined(HAVE_MPI)
65
66 typedef struct _cs_all_to_all_t cs_all_to_all_t;
67
68 #endif
69
70 /*=============================================================================
71 * Public function prototypes
72 *============================================================================*/
73
74 #if defined(HAVE_MPI)
75
76 /*----------------------------------------------------------------------------
77 * Create an all-to-all distributor for strided data.
78 *
79 * parameters:
80 * n_elts <-- number of elements
81 * stride <-- number of values per entity (interlaced)
82 * datatype <-- type of data considered
83 * elt <-- element values
84 * dest_rank <-- destination rank for each element
85 * comm <-- associated MPI communicator
86 *
87 * returns:
88 * pointer to new all-to-all distributor
89 *---------------------------------------------------------------------------*/
90
91 cs_all_to_all_t *
92 cs_all_to_all_create_s(size_t n_elts,
93 int stride,
94 cs_datatype_t datatype,
95 void *elt,
96 const int dest_rank[],
97 MPI_Comm comm);
98
99 /*----------------------------------------------------------------------------
100 * Create an all-to-all distributor for strided data with additional metadata.
101 *
102 * This variant allows optional tracking of destination ids or global
103 * numbers associated with elements, as well as their source ids.
104 *
105 * In cases where those arrays are required and already available, this
106 * may avoid the need for a specific element values buffer mixing actual
107 * data values and numbering metadata. It also makes extraction of the
108 * metadata easier using cs_all_to_all_get_id_pointers().
109 *
110 * parameters:
111 * n_elts <-- number of elements
112 * stride <-- number of values per entity (interlaced)
113 * datatype <-- type of data considered
114 * dest_id_datatype <-- type of destination id (CS_GNUM_TYPE, CS_LNUM_TYPE
115 * or CS_DATATYPE_NULL depending on elt_id values)
116 * add_src_id <-- add source id metadata (id in elt array)
117 * elt <-- element values
118 * dest_id <-- element destination id, global number, or NULL
119 * dest_rank <-- destination rank for each element
120 * comm <-- associated MPI communicator
121 *
122 * returns:
123 * pointer to new all-to-all distributor
124 *---------------------------------------------------------------------------*/
125
126 cs_all_to_all_t *
127 cs_all_to_all_create_with_ids_s(size_t n_elts,
128 int stride,
129 cs_datatype_t datatype,
130 cs_datatype_t dest_id_datatype,
131 bool add_src_id,
132 void *elt,
133 void *dest_id,
134 const int dest_rank[],
135 MPI_Comm comm);
136
137 /*----------------------------------------------------------------------------
138 * Create an all-to-all distributor for strided data with additional metadata,
139 * with destination rank determined from global numbers and block distribution
140 * information.
141 *
142 * This variant allows optional tracking of destination ids or global
143 * numbers associated with elements, as well as their source ids.
144 *
145 * In cases where those arrays are required and already available, this
146 * may avoid the need for a specific element values buffer mixing actual
147 * data values and numbering metadata. It also makes extraction of the
148 * metadata easier using cs_all_to_all_get_id_pointers().
149 *
150 * parameters:
151 * n_elts <-- number of elements
152 * stride <-- number of values per entity (interlaced)
153 * datatype <-- type of data considered
154 * dest_id_datatype <-- type of destination id (CS_GNUM_TYPE, CS_LNUM_TYPE
155 * or CS_DATATYPE_NULL)
156 * add_src_id <-- add source id metadata (id in elt array)
157 * elt <-- element values
158 * elt_gnum <-- global element numbers
159 * bi <-- destination block distribution info
160 * comm <-- associated MPI communicator
161 *
162 * returns:
163 * pointer to new all-to-all distributor
164 *---------------------------------------------------------------------------*/
165
166 cs_all_to_all_t *
167 cs_all_to_all_create_from_block_s(size_t n_elts,
168 int stride,
169 cs_datatype_t datatype,
170 cs_datatype_t dest_id_datatype,
171 bool add_src_id,
172 void *elt,
173 const cs_gnum_t *elt_gnum,
174 cs_block_dist_info_t bi,
175 MPI_Comm comm);
176
177 /*----------------------------------------------------------------------------
178 * Destroy an all-to-all distributor.
179 *
180 * parameters:
181 * d <-> pointer to associated all-to-all distributor
182 *---------------------------------------------------------------------------*/
183
184 void
185 cs_all_to_all_destroy(cs_all_to_all_t **d);
186
187 /*----------------------------------------------------------------------------
188 * Exchange data with an all-to-all distributor.
189 *
190 * Order of data from a same source rank is preserved.
191 *
192 * parameters:
193 * d <-> pointer to associated all-to-all distributor
194 *---------------------------------------------------------------------------*/
195
196 void
197 cs_all_to_all_exchange(cs_all_to_all_t *d);
198
199 /*----------------------------------------------------------------------------
200 * Sort stride crystal router data by source rank.
201 *
202 * parameters:
203 * d <-> pointer to associated all-to-all distributor
204 *---------------------------------------------------------------------------*/
205
206 void
207 cs_all_to_all_sort_by_source_rank(cs_all_to_all_t *d);
208
209 /*----------------------------------------------------------------------------
210 * Get number of elements associated with all-to-all distributor.
211 *
212 * The number of elements is the number of elements received after exchange.
213 *
214 * parameters:
215 * d <-- pointer to associated all-to-all distributor
216 *---------------------------------------------------------------------------*/
217
218 cs_lnum_t
219 cs_all_to_all_n_elts(const cs_all_to_all_t *d);
220
221 /*----------------------------------------------------------------------------
222 * Swap source and destination ranks of all-to-all distributor.
223 *
224 * parameters:
225 * d <-> associated all-to-all distributor pointer
226 *---------------------------------------------------------------------------*/
227
228 void
229 cs_all_to_all_swap_src_dest(cs_all_to_all_t *d);
230
231 /*----------------------------------------------------------------------------
232 * Get pointer to data elements associated with an all-to-all distributor.
233 *
234 * This allows modification and/or extraction of those elements.
235 *
236 * Note that depending on the distributor type used, the rank metadata
237 * and data may be interleaved, so the corresponding pointers point
238 * to strided, interleaved data.
239 *
240 * parameters:
241 * d <-- pointer to associated all-to-all distributor
242 * data_stride --> stride (in bytes) between data items
243 * data_ptr --> pointer to data items
244 *---------------------------------------------------------------------------*/
245
246 void
247 cs_all_to_all_get_data_pointer(cs_all_to_all_t *d,
248 size_t *data_stride,
249 unsigned char **data);
250
251 /*----------------------------------------------------------------------------
252 * Get pointer to ranks of elements associated with an all-to-all distributor.
253 *
254 * This allows modification and/or extraction of those ranks.
255 *
256 * Note that depending on the distributor type used, the rank metadata
257 * and data may be interleaved, so the corresponding pointers point
258 * to strided, interleaved data.
259 *
260 * parameters:
261 * d <-- pointer to associated all-to-all distributor
262 * rank_stride --> stride (in integers) between rank values
263 * src_rank --> pointer to source rank values (or NULL)
264 * dest_rank --> pointer to destination rank values (or NULL)
265 *---------------------------------------------------------------------------*/
266
267 void
268 cs_all_to_all_get_rank_pointers(cs_all_to_all_t *d,
269 size_t *rank_stride,
270 int **src_rank,
271 int **dest_rank);
272
273 /*----------------------------------------------------------------------------
274 * Get pointer to source or destination rank element ids associated with an
275 * all-to-all distributor.
276 *
277 * If a requested type of id is not available (depending on the all-to-all
278 * distributor creation function and options), the matching pointer will
279 * be set to NULL.
280 *
281 * This allows modification and/or extraction of those ids, though it is
282 * intended primarily for identification.
283 *
284 * Note that depending on the distributor type used, the rank metadata
285 * and data may be interleaved, so the corresponding pointers point
286 * to strided, interleaved data.
287 *
288 * parameters:
289 * d <-- pointer to associated all-to-all distributor
290 * id_stride --> stride (in integers) between id items
291 * dest_id --> pointer to destination ids (or NULL)
292 * dest_id --> pointer to source ids (or NULL)
293 *---------------------------------------------------------------------------*/
294
295 void
296 cs_all_to_all_get_id_pointers(cs_all_to_all_t *d,
297 size_t *id_stride,
298 cs_lnum_t **dest_id,
299 cs_lnum_t **src_id);
300
301 /*----------------------------------------------------------------------------
302 * Get pointer to element global numbers associated with an all-to-all
303 * distributor.
304 *
305 * If this data is not available (depending on the all-to-all distributor
306 * creation function and options), the matching pointer will
307 * be set to NULL.
308 *
309 * This allows modification and/or extraction of those numbers.
310 *
311 * Note that depending on the distributor type used, the rank metadata
312 * and data may be interleaved, so the corresponding pointers point
313 * to strided, interleaved data.
314 *
315 * parameters:
316 * d <-- pointer to associated all-to-all distributor
317 * gnum_stride --> stride (in integers) between element global numbers
318 * gnum --> pointer to global numbers
319 *---------------------------------------------------------------------------*/
320
321 void
322 cs_all_to_all_get_gnum_pointer(cs_all_to_all_t *d,
323 size_t *gnum_stride,
324 cs_gnum_t **gnum);
325
326 /*----------------------------------------------------------------------------
327 * Get current type of all-to-all distributor algorithm choice.
328 *
329 * returns:
330 * current type of all-to-all distributor algorithm choice
331 *---------------------------------------------------------------------------*/
332
333 cs_all_to_all_type_t
334 cs_all_to_all_get_type(void);
335
336 /*----------------------------------------------------------------------------
337 * Set current type of all-to-all distributor algorithm choice.
338 *
339 * parameters:
340 * t <-- type of all-to-all distributor algorithm choice to select
341 *---------------------------------------------------------------------------*/
342
343 void
344 cs_all_to_all_set_type(cs_all_to_all_type_t t);
345
346 #endif /* defined(HAVE_MPI) */
347
348 /*----------------------------------------------------------------------------
349 * Log performance information relative to instrumented all-to-all
350 * distribution.
351 *----------------------------------------------------------------------------*/
352
353 void
354 cs_all_to_all_log_finalize(void);
355
356 /*----------------------------------------------------------------------------*/
357
358 END_C_DECLS
359
360 #endif /* __CS_ALL_TO_ALL_H__ */