programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules 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-2017 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 #include "cs_rank_neighbors.h"
37 
38 #include "fvm_periodicity.h"
39 
40 /*----------------------------------------------------------------------------*/
41 
43 
44 /*=============================================================================
45  * Type definitions
46  *============================================================================*/
47 
48 /* Halo type */
49 
50 typedef enum {
51 
55 
57 
58 /* Options for cs_halo_sync_component(). */
59 
60 typedef enum {
61 
62  CS_HALO_ROTATION_COPY, /* Copy halo */
63  CS_HALO_ROTATION_ZERO, /* Set rotation halo values to zero */
64  CS_HALO_ROTATION_IGNORE /* Do not modify rotation halo values */
65 
67 
68 /* Structure for halo management */
69 /* ----------------------------- */
70 
71 typedef struct {
72 
73  int n_c_domains; /* Number of communicating domains. */
74  int n_transforms; /* Number of periodic transformations */
75 
76  int *c_domain_rank; /* List of communicating ranks */
77 
78  const fvm_periodicity_t * periodicity; /* Pointer to periodicity
79  structure describing transforms */
80 
81  int n_rotations; /* Number of periodic transformations
82  involving rotations */
83 
84  cs_lnum_t n_local_elts; /* Number of local elements */
85 
86  /* send_halo features : send to distant ranks */
87 
88  cs_lnum_t n_send_elts[2]; /* Numer of ghost elements in send_list
89  n_elts[0] = standard elements
90  n_elts[1] = extended + standard elements */
91 
92  cs_lnum_t *send_list; /* List of local elements in distant halos
93  (0 to n-1 numbering) */
94 
95  cs_lnum_t *send_index; /* Index on send_list
96  Size = 2*n_c_domains + 1. For each rank, we
97  have an index for standard halo and one
98  for extended halo. */
99 
100  cs_lnum_t *send_perio_lst ; /* For each transformation and for each type of
101  halo on each communicating rank, we store
102  2 values:
103  - start index,
104  - number of elements. */
105 
106  /* halo features : receive from distant ranks */
107 
108  cs_lnum_t n_elts[2]; /* Numer of ghost elements in halo
109  n_elts[0] = standard elements
110  n_elts[1] = extended + standard elements */
111 
112  cs_lnum_t *index; /* Index on halo sections;
113  Size = 2*n_c_domains. For each rank, we
114  have an index for the standard halo and one
115  for the extended halo. */
116 
117  cs_lnum_t *perio_lst; /* For each transformation and for each type of halo
118  on each communicating rank, we store 2 values:
119  - start index,
120  - number of elements. */
121 
122  /* Organisation of perio_lst:
123 
124  -------------------------------------------------
125  T1: | | | | | | | | | | | | |
126  -------------------------------------------------
127  idx n idx n idx n idx n idx n idx n
128  ______ ______ ______ ______ ______ ______
129  std ext std ext std ext
130  ___________ ___________ ___________
131  rank 0 rank 1 rank 2
132 
133  -------------------------------------------------
134  T2: | | | | | | | | | | | | |
135  -------------------------------------------------
136  idx n idx n idx n idx n idx n idx n
137  ______ ______ ______ ______ ______ ______
138  std ext std ext std ext
139  ___________ ___________ ___________
140  rank 0 rank 1 rank 2
141 
142  -------------------------------------------------
143  T3: | | | | | | | | | | | | |
144  -------------------------------------------------
145  idx n idx n idx n idx n idx n idx n
146  ______ ______ ______ ______ ______ ______
147  std ext std ext std ext
148  ___________ ___________ ___________
149  rank 0 rank 1 rank 2
150 
151  etc...
152 
153  */
154 
155 } cs_halo_t;
156 
157 /*=============================================================================
158  * Global static variables
159  *============================================================================*/
160 
161 /*============================================================================
162  * Public function header for Fortran API
163  *============================================================================*/
164 
165 /*=============================================================================
166  * Public function prototypes
167  *============================================================================*/
168 
169 /*----------------------------------------------------------------------------*/
177 /*----------------------------------------------------------------------------*/
178 
179 cs_halo_t *
181 
182 /*----------------------------------------------------------------------------*/
190 /*----------------------------------------------------------------------------*/
191 
192 cs_halo_t *
194 
195 #if defined(HAVE_MPI)
196 
197 /*----------------------------------------------------------------------------*/
221 /*----------------------------------------------------------------------------*/
222 
223 cs_halo_t *
225  cs_lnum_t n_local_elts,
226  cs_lnum_t n_distant_elts,
227  const int elt_rank_id[],
228  const cs_lnum_t elt_id[]);
229 
230 #endif /* HAVE_MPI */
231 
232 /*----------------------------------------------------------------------------*/
238 /*----------------------------------------------------------------------------*/
239 
240 void
241 cs_halo_destroy(cs_halo_t **halo);
242 
243 /*----------------------------------------------------------------------------
244  * Update global buffer sizes so as to be usable with a given halo.
245  *
246  * Calls to halo synchronizations with variable strides up to 3 are
247  * expected. For strides greater than 3, the halo will be resized if
248  * necessary directly by the synchronization function.
249  *
250  * This function should be called at the end of any halo creation,
251  * so that buffer sizes are increased if necessary.
252  *
253  * parameters:
254  * halo <-- pointer to cs_halo_t structure.
255  *---------------------------------------------------------------------------*/
256 
257 void
258 cs_halo_update_buffers(const cs_halo_t *halo);
259 
260 /*----------------------------------------------------------------------------
261  * Free global halo backup buffer.
262  *---------------------------------------------------------------------------*/
263 
264 void
265 cs_halo_free_buffer(void);
266 
267 /*----------------------------------------------------------------------------
268  * Apply local cells renumbering to a halo
269  *
270  * parameters:
271  * halo <-- pointer to halo structure
272  * new_cell_id <-- array indicating old -> new cell id (0 to n-1)
273  *---------------------------------------------------------------------------*/
274 
275 void
277  const cs_lnum_t new_cell_id[]);
278 
279 /*----------------------------------------------------------------------------
280  * Apply ghost cells renumbering to a halo
281  *
282  * parameters:
283  * halo <-- pointer to halo structure
284  * old_cell_id <-- array indicating new -> old cell id (0 to n-1)
285  *---------------------------------------------------------------------------*/
286 
287 void
289  const cs_lnum_t old_cell_id[]);
290 
291 /*----------------------------------------------------------------------------
292  * Update array of any type of halo values in case of parallelism or
293  * periodicity.
294  *
295  * Data is untyped; only its size is given, so this function may also
296  * be used to synchronize interleaved multidimendsional data, using
297  * size = element_size*dim (assuming a homogeneous environment, at least
298  * as far as data encoding goes).
299  *
300  * This function aims at copying main values from local elements
301  * (id between 1 and n_local_elements) to ghost elements on distant ranks
302  * (id between n_local_elements + 1 to n_local_elements_with_halo).
303  *
304  * parameters:
305  * halo <-- pointer to halo structure
306  * sync_mode <-- synchronization mode (standard or extended)
307  * num <-> pointer to local number value array
308  *----------------------------------------------------------------------------*/
309 
310 void
311 cs_halo_sync_untyped(const cs_halo_t *halo,
312  cs_halo_type_t sync_mode,
313  size_t size,
314  void *val);
315 
316 /*----------------------------------------------------------------------------
317  * Update array of integer halo values in case of parallelism or periodicity.
318  *
319  * This function aims at copying main values from local elements
320  * (id between 1 and n_local_elements) to ghost elements on distant ranks
321  * (id between n_local_elements + 1 to n_local_elements_with_halo).
322  *
323  * parameters:
324  * halo <-- pointer to halo structure
325  * sync_mode <-- synchronization mode (standard or extended)
326  * num <-> pointer to local number value array
327  *----------------------------------------------------------------------------*/
328 
329 void
330 cs_halo_sync_num(const cs_halo_t *halo,
331  cs_halo_type_t sync_mode,
332  cs_lnum_t num[]);
333 
334 /*----------------------------------------------------------------------------
335  * Update array of variable (floating-point) halo values in case of
336  * parallelism or periodicity.
337  *
338  * This function aims at copying main values from local elements
339  * (id between 1 and n_local_elements) to ghost elements on distant ranks
340  * (id between n_local_elements + 1 to n_local_elements_with_halo).
341  *
342  * parameters:
343  * halo <-- pointer to halo structure
344  * sync_mode <-- synchronization mode (standard or extended)
345  * var <-> pointer to variable value array
346  *----------------------------------------------------------------------------*/
347 
348 void
349 cs_halo_sync_var(const cs_halo_t *halo,
350  cs_halo_type_t sync_mode,
351  cs_real_t var[]);
352 
353 /*----------------------------------------------------------------------------
354  * Update array of strided variable (floating-point) halo values in case
355  * of parallelism or periodicity.
356  *
357  * This function aims at copying main values from local elements
358  * (id between 1 and n_local_elements) to ghost elements on distant ranks
359  * (id between n_local_elements + 1 to n_local_elements_with_halo).
360  *
361  * parameters:
362  * halo <-- pointer to halo structure
363  * sync_mode <-- synchronization mode (standard or extended)
364  * var <-> pointer to variable value array
365  * stride <-- number of (interlaced) values by entity
366  *----------------------------------------------------------------------------*/
367 
368 void
370  cs_halo_type_t sync_mode,
371  cs_real_t var[],
372  int stride);
373 
374 /*----------------------------------------------------------------------------
375  * Update array of vector variable component (floating-point) halo values
376  * in case of parallelism or periodicity.
377  *
378  * This function aims at copying main values from local elements
379  * (id between 1 and n_local_elements) to ghost elements on distant ranks
380  * (id between n_local_elements + 1 to n_local_elements_with_halo).
381  *
382  * If rotation_op is equal to CS_HALO_ROTATION_IGNORE, halo values
383  * corresponding to periodicity with rotation are left unchanged from their
384  * previous values.
385  *
386  * If rotation_op is equal to CS_HALO_ROTATION_ZERO, halo values
387  * corresponding to periodicity with rotation are set to 0.
388  *
389  * If rotation_op is equal to CS_HALO_ROTATION_COPY, halo values
390  * corresponding to periodicity with rotation are exchanged normally, so
391  * the behavior is the same as that of cs_halo_sync_var().
392  *
393  * parameters:
394  * halo <-- pointer to halo structure
395  * sync_mode <-- synchronization mode (standard or extended)
396  * rotation_op <-- rotation operation
397  * var <-> pointer to variable value array
398  *----------------------------------------------------------------------------*/
399 
400 void
402  cs_halo_type_t sync_mode,
403  cs_halo_rotation_t rotation_op,
404  cs_real_t var[]);
405 
406 /*----------------------------------------------------------------------------
407  * Update array of strided vector variable components (floating-point)
408  * halo values in case of parallelism or periodicity.
409  *
410  * This function aims at copying main values from local elements
411  * (id between 1 and n_local_elements) to ghost elements on distant ranks
412  * (id between n_local_elements + 1 to n_local_elements_with_halo).
413  *
414  * If rotation_op is equal to CS_HALO_ROTATION_IGNORE, halo values
415  * corresponding to periodicity with rotation are left unchanged from their
416  * previous values.
417  *
418  * If rotation_op is equal to CS_HALO_ROTATION_ZERO, halo values
419  * corresponding to periodicity with rotation are set to 0.
420  *
421  * If rotation_op is equal to CS_HALO_ROTATION_COPY, halo values
422  * corresponding to periodicity with rotation are exchanged normally, so
423  * the behavior is the same as that of cs_halo_sync_var_strided().
424  *
425  * parameters:
426  * halo <-- pointer to halo structure
427  * sync_mode <-- synchronization mode (standard or extended)
428  * rotation_op <-- rotation operation
429  * var <-> pointer to variable value array
430  * stride <-- number of (interlaced) values by entity
431  *----------------------------------------------------------------------------*/
432 
433 void
435  cs_halo_type_t sync_mode,
436  cs_halo_rotation_t rotation_op,
437  cs_real_t var[],
438  int stride);
439 
440 /*----------------------------------------------------------------------------
441  * Return MPI_Barrier usage flag.
442  *
443  * returns:
444  * true if MPI barriers are used after posting receives and before posting
445  * sends, false otherwise
446  *---------------------------------------------------------------------------*/
447 
448 bool
450 
451 /*----------------------------------------------------------------------------
452  * Set MPI_Barrier usage flag.
453  *
454  * parameters:
455  * use_barrier <-- true if MPI barriers should be used after posting
456  * receives and before posting sends, false otherwise.
457  *---------------------------------------------------------------------------*/
458 
459 void
460 cs_halo_set_use_barrier(bool use_barrier);
461 
462 /*----------------------------------------------------------------------------
463  * Dump a cs_halo_t structure.
464  *
465  * parameters:
466  * halo <-- pointer to cs_halo_t struture
467  * print_level <-- 0 only dimensions and indexes are printed, else (1)
468  * everything is printed
469  *---------------------------------------------------------------------------*/
470 
471 void
472 cs_halo_dump(const cs_halo_t *halo,
473  int print_level);
474 
475 /*----------------------------------------------------------------------------*/
476 
478 
479 #endif /* __CS_HALO_H__ */
void cs_halo_free_buffer(void)
Definition: cs_halo.c:900
cs_halo_rotation_t
Definition: cs_halo.h:60
void cs_halo_destroy(cs_halo_t **halo)
Definition: cs_halo.c:760
cs_lnum_t * index
Definition: cs_halo.h:112
void cs_halo_sync_component(const cs_halo_t *halo, cs_halo_type_t sync_mode, cs_halo_rotation_t rotation_op, cs_real_t var[])
Definition: cs_halo.c:1719
void cs_halo_set_use_barrier(bool use_barrier)
Definition: cs_halo.c:1810
#define BEGIN_C_DECLS
Definition: cs_defs.h:453
void cs_halo_sync_var(const cs_halo_t *halo, cs_halo_type_t sync_mode, cs_real_t var[])
Definition: cs_halo.c:1399
cs_lnum_t * perio_lst
Definition: cs_halo.h:117
Definition: cs_halo.h:53
Definition: cs_halo.h:71
bool cs_halo_get_use_barrier(void)
Definition: cs_halo.c:1796
cs_halo_t * cs_halo_create_from_ref(const cs_halo_t *ref)
Create a halo structure, given a reference halo.
Definition: cs_halo.c:463
int * c_domain_rank
Definition: cs_halo.h:76
double cs_real_t
Floating-point value.
Definition: cs_defs.h:297
cs_lnum_t n_local_elts
Definition: cs_halo.h:84
void cs_halo_update_buffers(const cs_halo_t *halo)
Definition: cs_halo.c:820
Definition: cs_halo.h:63
void cs_halo_sync_var_strided(const cs_halo_t *halo, cs_halo_type_t sync_mode, cs_real_t var[], int stride)
Definition: cs_halo.c:1530
Definition: cs_halo.h:62
int n_transforms
Definition: cs_halo.h:74
Definition: cs_rank_neighbors.h:67
cs_lnum_t * send_perio_lst
Definition: cs_halo.h:100
int n_rotations
Definition: cs_halo.h:81
cs_halo_type_t
Definition: cs_halo.h:50
cs_halo_t * cs_halo_create(const cs_interface_set_t *ifs)
Create a halo structure given an interface set.
Definition: cs_halo.c:331
struct _cs_interface_set_t cs_interface_set_t
Definition: cs_interface.h:61
void cs_halo_renumber_ghost_cells(cs_halo_t *halo, const cs_lnum_t old_cell_id[])
Definition: cs_halo.c:939
int n_c_domains
Definition: cs_halo.h:73
void cs_halo_sync_components_strided(const cs_halo_t *halo, cs_halo_type_t sync_mode, cs_halo_rotation_t rotation_op, cs_real_t var[], int stride)
Definition: cs_halo.c:1766
struct _fvm_periodicity_t fvm_periodicity_t
Definition: fvm_periodicity.h:67
void cs_halo_sync_untyped(const cs_halo_t *halo, cs_halo_type_t sync_mode, size_t size, void *val)
Definition: cs_halo.c:1089
void cs_halo_sync_num(const cs_halo_t *halo, cs_halo_type_t sync_mode, cs_lnum_t num[])
Definition: cs_halo.c:1260
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:293
Definition: cs_halo.h:52
const fvm_periodicity_t * periodicity
Definition: cs_halo.h:78
#define END_C_DECLS
Definition: cs_defs.h:454
void cs_halo_renumber_cells(cs_halo_t *halo, const cs_lnum_t new_cell_id[])
Definition: cs_halo.c:917
cs_lnum_t * send_index
Definition: cs_halo.h:95
Definition: cs_halo.h:64
cs_halo_t * cs_halo_create_from_rank_neighbors(const cs_rank_neighbors_t *rn, cs_lnum_t n_local_elts, cs_lnum_t n_distant_elts, const int elt_rank_id[], const cs_lnum_t elt_id[])
Create a halo structure from distant element distant ranks and ids.
Definition: cs_halo.c:545
void cs_halo_dump(const cs_halo_t *halo, int print_level)
Definition: cs_halo.c:1825
cs_lnum_t * send_list
Definition: cs_halo.h:92
Definition: cs_halo.h:54