src/base/cs_halo.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_halo.h
Go to the documentation of this file.
1 #ifndef __CS_HALO_H__
2 #define __CS_HALO_H__
3
4 /*============================================================================
5 * Structure and function headers handling with ghost cells
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 /*----------------------------------------------------------------------------
31 * Local headers
32 *----------------------------------------------------------------------------*/
33
34 #include "cs_base.h"
35 #include "cs_interface.h"
36
37 #include "fvm_periodicity.h"
38
39 /*----------------------------------------------------------------------------*/
40
41 BEGIN_C_DECLS
42
43 /*=============================================================================
44 * Type definitions
45 *============================================================================*/
46
47 /* Halo type */
48
49 typedef enum {
50
51 CS_HALO_STANDARD,
52 CS_HALO_EXTENDED,
53 CS_HALO_N_TYPES
54
55 } cs_halo_type_t;
56
57 /* Options for cs_halo_sync_component(). */
58
59 typedef enum {
60
61 CS_HALO_ROTATION_COPY, /* Copy halo */
62 CS_HALO_ROTATION_ZERO, /* Set rotation halo values to zero */
63 CS_HALO_ROTATION_IGNORE /* Do not modify rotation halo values */
64
65 } cs_halo_rotation_t ;
66
67 /* Structure for halo management */
68 /* ----------------------------- */
69
70 typedef struct {
71
72 int n_c_domains; /* Number of communicating domains. */
73 int n_transforms; /* Number of periodic transformations */
74
75 int *c_domain_rank; /* List of communicating ranks */
76
77 const fvm_periodicity_t * periodicity; /* Pointer to periodicity
78 structure describing transforms */
79
80 int n_rotations; /* Number of periodic transformations
81 involving rotations */
82
83 cs_lnum_t n_local_elts; /* Number of local elements */
84
85 /* send_halo features : send to distant ranks */
86
87 cs_lnum_t n_send_elts[2]; /* Numer of ghost elements in send_list
88 n_elts[0] = standard elements
89 n_elts[1] = extended + standard elements */
90
91 cs_lnum_t *send_list; /* List of local elements in distant halos
92 (0 to n-1 numbering) */
93
94 cs_lnum_t *send_index; /* Index on send_list
95 Size = 2*n_c_domains + 1. For each rank, we
96 have an index for standard halo and one
97 for extended halo. */
98
99 cs_lnum_t *send_perio_lst ; /* For each transformation and for each type of
100 halo on each communicating rank, we store
101 2 values:
102 - start index,
103 - number of elements. */
104
105 /* halo features : receive from distant ranks */
106
107 cs_lnum_t n_elts[2]; /* Numer of ghost elements in halo
108 n_elts[0] = standard elements
109 n_elts[1] = extended + standard elements */
110
111 cs_lnum_t *index; /* Index on halo sections;
112 Size = 2*n_c_domains. For each rank, we
113 have an index for the standard halo and one
114 for the extended halo. */
115
116 cs_lnum_t *perio_lst; /* For each transformation and for each type of halo
117 on each communicating rank, we store 2 values:
118 - start index,
119 - number of elements. */
120
121 /* Organisation of perio_lst:
122
123 -------------------------------------------------
124 T1: | | | | | | | | | | | | |
125 -------------------------------------------------
126 idx n idx n idx n idx n idx n idx n
127 ______ ______ ______ ______ ______ ______
128 std ext std ext std ext
129 ___________ ___________ ___________
130 rank 0 rank 1 rank 2
131
132 -------------------------------------------------
133 T2: | | | | | | | | | | | | |
134 -------------------------------------------------
135 idx n idx n idx n idx n idx n idx n
136 ______ ______ ______ ______ ______ ______
137 std ext std ext std ext
138 ___________ ___________ ___________
139 rank 0 rank 1 rank 2
140
141 -------------------------------------------------
142 T3: | | | | | | | | | | | | |
143 -------------------------------------------------
144 idx n idx n idx n idx n idx n idx n
145 ______ ______ ______ ______ ______ ______
146 std ext std ext std ext
147 ___________ ___________ ___________
148 rank 0 rank 1 rank 2
149
150 etc...
151
152 */
153
154 } cs_halo_t;
155
156 /*=============================================================================
157 * Global static variables
158 *============================================================================*/
159
160 /*============================================================================
161 * Public function header for Fortran API
162 *============================================================================*/
163
164 /*=============================================================================
165 * Public function prototypes
166 *============================================================================*/
167
168 /*----------------------------------------------------------------------------
169 * Create a halo structure.
170 *
171 * parameters:
172 * ifs <-- pointer to a fvm_interface_set structure
173 *
174 * returns:
175 * pointer to created cs_halo_t structure
176 *---------------------------------------------------------------------------*/
177
178 cs_halo_t *
179 cs_halo_create(cs_interface_set_t *ifs);
180
181 /*----------------------------------------------------------------------------
182 * Create a halo structure, using a reference halo
183 *
184 * parameters:
185 * ref <-- pointer to reference halo
186 *
187 * returns:
188 * pointer to created cs_halo_t structure
189 *---------------------------------------------------------------------------*/
190
191 cs_halo_t *
192 cs_halo_create_from_ref(const cs_halo_t *ref);
193
194 /*----------------------------------------------------------------------------
195 * Destroy a halo structure.
196 *
197 * parameters:
198 * this_halo <-- pointer to cs_halo structure to destroy
199 *
200 * returns:
201 * pointer to deleted halo structure (NULL)
202 *---------------------------------------------------------------------------*/
203
204 cs_halo_t *
205 cs_halo_destroy(cs_halo_t *this_halo);
206
207 /*----------------------------------------------------------------------------
208 * Update global buffer sizes so as to be usable with a given halo.
209 *
210 * Calls to halo synchronizations with variable strides up to 3 are
211 * expected. For strides greater than 3, the halo will be resized if
212 * necessary directly by the synchronization function.
213 *
214 * This function should be called at the end of any halo creation,
215 * so that buffer sizes are increased if necessary.
216 *
217 * parameters:
218 * halo <-- pointer to cs_halo_t structure.
219 *---------------------------------------------------------------------------*/
220
221 void
222 cs_halo_update_buffers(const cs_halo_t *halo);
223
224 /*----------------------------------------------------------------------------
225 * Free global halo backup buffer.
226 *---------------------------------------------------------------------------*/
227
228 void
229 cs_halo_free_buffer(void);
230
231 /*----------------------------------------------------------------------------
232 * Apply cell renumbering to a halo
233 *
234 * parameters:
235 * halo <-- pointer to halo structure
236 * new_cell_id <-- array indicating old -> new cell id (0 to n-1)
237 *---------------------------------------------------------------------------*/
238
239 void
240 cs_halo_renumber_cells(cs_halo_t *halo,
241 const cs_lnum_t new_cell_id[]);
242
243 /*----------------------------------------------------------------------------
244 * Update array of any type of halo values in case of parallelism or
245 * periodicity.
246 *
247 * Data is untyped; only its size is given, so this function may also
248 * be used to synchronize interleaved multidimendsional data, using
249 * size = element_size*dim (assuming a homogeneous environment, at least
250 * as far as data encoding goes).
251 *
252 * This function aims at copying main values from local elements
253 * (id between 1 and n_local_elements) to ghost elements on distant ranks
254 * (id between n_local_elements + 1 to n_local_elements_with_halo).
255 *
256 * parameters:
257 * halo <-- pointer to halo structure
258 * sync_mode <-- synchronization mode (standard or extended)
259 * num <-> pointer to local number value array
260 *----------------------------------------------------------------------------*/
261
262 void
263 cs_halo_sync_untyped(const cs_halo_t *halo,
264 cs_halo_type_t sync_mode,
265 size_t size,
266 void *val);
267
268 /*----------------------------------------------------------------------------
269 * Update array of integer halo values in case of parallelism or periodicity.
270 *
271 * This function aims at copying main values from local elements
272 * (id between 1 and n_local_elements) to ghost elements on distant ranks
273 * (id between n_local_elements + 1 to n_local_elements_with_halo).
274 *
275 * parameters:
276 * halo <-- pointer to halo structure
277 * sync_mode <-- synchronization mode (standard or extended)
278 * num <-> pointer to local number value array
279 *----------------------------------------------------------------------------*/
280
281 void
282 cs_halo_sync_num(const cs_halo_t *halo,
283 cs_halo_type_t sync_mode,
284 cs_lnum_t num[]);
285
286 /*----------------------------------------------------------------------------
287 * Update array of variable (floating-point) halo values in case of
288 * parallelism or periodicity.
289 *
290 * This function aims at copying main values from local elements
291 * (id between 1 and n_local_elements) to ghost elements on distant ranks
292 * (id between n_local_elements + 1 to n_local_elements_with_halo).
293 *
294 * parameters:
295 * halo <-- pointer to halo structure
296 * sync_mode <-- synchronization mode (standard or extended)
297 * var <-> pointer to variable value array
298 *----------------------------------------------------------------------------*/
299
300 void
301 cs_halo_sync_var(const cs_halo_t *halo,
302 cs_halo_type_t sync_mode,
303 cs_real_t var[]);
304
305 /*----------------------------------------------------------------------------
306 * Update array of strided variable (floating-point) halo values in case
307 * of parallelism or periodicity.
308 *
309 * This function aims at copying main values from local elements
310 * (id between 1 and n_local_elements) to ghost elements on distant ranks
311 * (id between n_local_elements + 1 to n_local_elements_with_halo).
312 *
313 * parameters:
314 * halo <-- pointer to halo structure
315 * sync_mode <-- synchronization mode (standard or extended)
316 * var <-> pointer to variable value array
317 * stride <-- number of (interlaced) values by entity
318 *----------------------------------------------------------------------------*/
319
320 void
321 cs_halo_sync_var_strided(const cs_halo_t *halo,
322 cs_halo_type_t sync_mode,
323 cs_real_t var[],
324 int stride);
325
326 /*----------------------------------------------------------------------------
327 * Update array of vector variable component (floating-point) halo values
328 * in case of parallelism or periodicity.
329 *
330 * This function aims at copying main values from local elements
331 * (id between 1 and n_local_elements) to ghost elements on distant ranks
332 * (id between n_local_elements + 1 to n_local_elements_with_halo).
333 *
334 * If rotation_op is equal to CS_HALO_ROTATION_IGNORE, halo values
335 * corresponding to periodicity with rotation are left unchanged from their
336 * previous values.
337 *
338 * If rotation_op is equal to CS_HALO_ROTATION_ZERO, halo values
339 * corresponding to periodicity with rotation are set to 0.
340 *
341 * If rotation_op is equal to CS_HALO_ROTATION_COPY, halo values
342 * corresponding to periodicity with rotation are exchanged normally, so
343 * the behavior is the same as that of cs_halo_sync_var().
344 *
345 * parameters:
346 * halo <-- pointer to halo structure
347 * sync_mode <-- synchronization mode (standard or extended)
348 * rotation_op <-- rotation operation
349 * var <-> pointer to variable value array
350 *----------------------------------------------------------------------------*/
351
352 void
353 cs_halo_sync_component(const cs_halo_t *halo,
354 cs_halo_type_t sync_mode,
355 cs_halo_rotation_t rotation_op,
356 cs_real_t var[]);
357
358 /*----------------------------------------------------------------------------
359 * Update array of strided vector variable components (floating-point)
360 * halo values in case of parallelism or periodicity.
361 *
362 * This function aims at copying main values from local elements
363 * (id between 1 and n_local_elements) to ghost elements on distant ranks
364 * (id between n_local_elements + 1 to n_local_elements_with_halo).
365 *
366 * If rotation_op is equal to CS_HALO_ROTATION_IGNORE, halo values
367 * corresponding to periodicity with rotation are left unchanged from their
368 * previous values.
369 *
370 * If rotation_op is equal to CS_HALO_ROTATION_ZERO, halo values
371 * corresponding to periodicity with rotation are set to 0.
372 *
373 * If rotation_op is equal to CS_HALO_ROTATION_COPY, halo values
374 * corresponding to periodicity with rotation are exchanged normally, so
375 * the behavior is the same as that of cs_halo_sync_var_strided().
376 *
377 * parameters:
378 * halo <-- pointer to halo structure
379 * sync_mode <-- synchronization mode (standard or extended)
380 * rotation_op <-- rotation operation
381 * var <-> pointer to variable value array
382 * stride <-- number of (interlaced) values by entity
383 *----------------------------------------------------------------------------*/
384
385 void
386 cs_halo_sync_components_strided(const cs_halo_t *halo,
387 cs_halo_type_t sync_mode,
388 cs_halo_rotation_t rotation_op,
389 cs_real_t var[],
390 int stride);
391
392 /*----------------------------------------------------------------------------
393 * Return MPI_Barrier usage flag.
394 *
395 * returns:
396 * true if MPI barriers are used after posting receives and before posting
397 * sends, false otherwise
398 *---------------------------------------------------------------------------*/
399
400 bool
401 cs_halo_get_use_barrier(void);
402
403 /*----------------------------------------------------------------------------
404 * Set MPI_Barrier usage flag.
405 *
406 * parameters:
407 * use_barrier <-- true if MPI barriers should be used after posting
408 * receives and before posting sends, false otherwise.
409 *---------------------------------------------------------------------------*/
410
411 void
412 cs_halo_set_use_barrier(bool use_barrier);
413
414 /*----------------------------------------------------------------------------
415 * Dump a cs_halo_t structure.
416 *
417 * parameters:
418 * halo <-- pointer to cs_halo_t struture
419 * print_level <-- 0 only dimensions and indexes are printed, else (1)
420 * everything is printed
421 *---------------------------------------------------------------------------*/
422
423 void
424 cs_halo_dump(const cs_halo_t *halo,
425 int print_level);
426
427 /*----------------------------------------------------------------------------*/
428
429 END_C_DECLS
430
431 #endif /* __CS_HALO_H__ */