programmer's documentation
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-2015 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 
42 
43 /*=============================================================================
44  * Type definitions
45  *============================================================================*/
46 
47 /* Halo type */
48 
49 typedef enum {
50 
54 
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 
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 *
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 *
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 local cells 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
241  const cs_lnum_t new_cell_id[]);
242 
243 /*----------------------------------------------------------------------------
244  * Apply ghost cells renumbering to a halo
245  *
246  * parameters:
247  * halo <-- pointer to halo structure
248  * old_cell_id <-- array indicating new -> old cell id (0 to n-1)
249  *---------------------------------------------------------------------------*/
250 
251 void
253  const cs_lnum_t old_cell_id[]);
254 
255 /*----------------------------------------------------------------------------
256  * Update array of any type of halo values in case of parallelism or
257  * periodicity.
258  *
259  * Data is untyped; only its size is given, so this function may also
260  * be used to synchronize interleaved multidimendsional data, using
261  * size = element_size*dim (assuming a homogeneous environment, at least
262  * as far as data encoding goes).
263  *
264  * This function aims at copying main values from local elements
265  * (id between 1 and n_local_elements) to ghost elements on distant ranks
266  * (id between n_local_elements + 1 to n_local_elements_with_halo).
267  *
268  * parameters:
269  * halo <-- pointer to halo structure
270  * sync_mode <-- synchronization mode (standard or extended)
271  * num <-> pointer to local number value array
272  *----------------------------------------------------------------------------*/
273 
274 void
275 cs_halo_sync_untyped(const cs_halo_t *halo,
276  cs_halo_type_t sync_mode,
277  size_t size,
278  void *val);
279 
280 /*----------------------------------------------------------------------------
281  * Update array of integer halo values in case of parallelism or periodicity.
282  *
283  * This function aims at copying main values from local elements
284  * (id between 1 and n_local_elements) to ghost elements on distant ranks
285  * (id between n_local_elements + 1 to n_local_elements_with_halo).
286  *
287  * parameters:
288  * halo <-- pointer to halo structure
289  * sync_mode <-- synchronization mode (standard or extended)
290  * num <-> pointer to local number value array
291  *----------------------------------------------------------------------------*/
292 
293 void
294 cs_halo_sync_num(const cs_halo_t *halo,
295  cs_halo_type_t sync_mode,
296  cs_lnum_t num[]);
297 
298 /*----------------------------------------------------------------------------
299  * Update array of variable (floating-point) halo values in case of
300  * parallelism or periodicity.
301  *
302  * This function aims at copying main values from local elements
303  * (id between 1 and n_local_elements) to ghost elements on distant ranks
304  * (id between n_local_elements + 1 to n_local_elements_with_halo).
305  *
306  * parameters:
307  * halo <-- pointer to halo structure
308  * sync_mode <-- synchronization mode (standard or extended)
309  * var <-> pointer to variable value array
310  *----------------------------------------------------------------------------*/
311 
312 void
313 cs_halo_sync_var(const cs_halo_t *halo,
314  cs_halo_type_t sync_mode,
315  cs_real_t var[]);
316 
317 /*----------------------------------------------------------------------------
318  * Update array of strided variable (floating-point) halo values in case
319  * of parallelism or periodicity.
320  *
321  * This function aims at copying main values from local elements
322  * (id between 1 and n_local_elements) to ghost elements on distant ranks
323  * (id between n_local_elements + 1 to n_local_elements_with_halo).
324  *
325  * parameters:
326  * halo <-- pointer to halo structure
327  * sync_mode <-- synchronization mode (standard or extended)
328  * var <-> pointer to variable value array
329  * stride <-- number of (interlaced) values by entity
330  *----------------------------------------------------------------------------*/
331 
332 void
334  cs_halo_type_t sync_mode,
335  cs_real_t var[],
336  int stride);
337 
338 /*----------------------------------------------------------------------------
339  * Update array of vector variable component (floating-point) halo values
340  * in case of parallelism or periodicity.
341  *
342  * This function aims at copying main values from local elements
343  * (id between 1 and n_local_elements) to ghost elements on distant ranks
344  * (id between n_local_elements + 1 to n_local_elements_with_halo).
345  *
346  * If rotation_op is equal to CS_HALO_ROTATION_IGNORE, halo values
347  * corresponding to periodicity with rotation are left unchanged from their
348  * previous values.
349  *
350  * If rotation_op is equal to CS_HALO_ROTATION_ZERO, halo values
351  * corresponding to periodicity with rotation are set to 0.
352  *
353  * If rotation_op is equal to CS_HALO_ROTATION_COPY, halo values
354  * corresponding to periodicity with rotation are exchanged normally, so
355  * the behavior is the same as that of cs_halo_sync_var().
356  *
357  * parameters:
358  * halo <-- pointer to halo structure
359  * sync_mode <-- synchronization mode (standard or extended)
360  * rotation_op <-- rotation operation
361  * var <-> pointer to variable value array
362  *----------------------------------------------------------------------------*/
363 
364 void
366  cs_halo_type_t sync_mode,
367  cs_halo_rotation_t rotation_op,
368  cs_real_t var[]);
369 
370 /*----------------------------------------------------------------------------
371  * Update array of strided vector variable components (floating-point)
372  * halo values in case of parallelism or periodicity.
373  *
374  * This function aims at copying main values from local elements
375  * (id between 1 and n_local_elements) to ghost elements on distant ranks
376  * (id between n_local_elements + 1 to n_local_elements_with_halo).
377  *
378  * If rotation_op is equal to CS_HALO_ROTATION_IGNORE, halo values
379  * corresponding to periodicity with rotation are left unchanged from their
380  * previous values.
381  *
382  * If rotation_op is equal to CS_HALO_ROTATION_ZERO, halo values
383  * corresponding to periodicity with rotation are set to 0.
384  *
385  * If rotation_op is equal to CS_HALO_ROTATION_COPY, halo values
386  * corresponding to periodicity with rotation are exchanged normally, so
387  * the behavior is the same as that of cs_halo_sync_var_strided().
388  *
389  * parameters:
390  * halo <-- pointer to halo structure
391  * sync_mode <-- synchronization mode (standard or extended)
392  * rotation_op <-- rotation operation
393  * var <-> pointer to variable value array
394  * stride <-- number of (interlaced) values by entity
395  *----------------------------------------------------------------------------*/
396 
397 void
399  cs_halo_type_t sync_mode,
400  cs_halo_rotation_t rotation_op,
401  cs_real_t var[],
402  int stride);
403 
404 /*----------------------------------------------------------------------------
405  * Return MPI_Barrier usage flag.
406  *
407  * returns:
408  * true if MPI barriers are used after posting receives and before posting
409  * sends, false otherwise
410  *---------------------------------------------------------------------------*/
411 
412 bool
414 
415 /*----------------------------------------------------------------------------
416  * Set MPI_Barrier usage flag.
417  *
418  * parameters:
419  * use_barrier <-- true if MPI barriers should be used after posting
420  * receives and before posting sends, false otherwise.
421  *---------------------------------------------------------------------------*/
422 
423 void
424 cs_halo_set_use_barrier(bool use_barrier);
425 
426 /*----------------------------------------------------------------------------
427  * Dump a cs_halo_t structure.
428  *
429  * parameters:
430  * halo <-- pointer to cs_halo_t struture
431  * print_level <-- 0 only dimensions and indexes are printed, else (1)
432  * everything is printed
433  *---------------------------------------------------------------------------*/
434 
435 void
436 cs_halo_dump(const cs_halo_t *halo,
437  int print_level);
438 
439 /*----------------------------------------------------------------------------*/
440 
442 
443 #endif /* __CS_HALO_H__ */
void cs_halo_free_buffer(void)
Definition: cs_halo.c:664
cs_halo_rotation_t
Definition: cs_halo.h:59
cs_lnum_t * index
Definition: cs_halo.h:111
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:1477
void cs_halo_set_use_barrier(bool use_barrier)
Definition: cs_halo.c:1568
#define BEGIN_C_DECLS
Definition: cs_defs.h:429
void cs_halo_sync_var(const cs_halo_t *halo, cs_halo_type_t sync_mode, cs_real_t var[])
Definition: cs_halo.c:1157
cs_lnum_t * perio_lst
Definition: cs_halo.h:116
Definition: cs_halo.h:52
Definition: cs_halo.h:70
bool cs_halo_get_use_barrier(void)
Definition: cs_halo.c:1554
cs_halo_t * cs_halo_create_from_ref(const cs_halo_t *ref)
Definition: cs_halo.c:461
int * c_domain_rank
Definition: cs_halo.h:75
cs_lnum_t n_local_elts
Definition: cs_halo.h:83
void cs_halo_update_buffers(const cs_halo_t *halo)
Definition: cs_halo.c:584
Definition: cs_halo.h:62
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:1288
Definition: cs_halo.h:61
int n_transforms
Definition: cs_halo.h:73
cs_lnum_t * send_perio_lst
Definition: cs_halo.h:99
int n_rotations
Definition: cs_halo.h:80
cs_halo_type_t
Definition: cs_halo.h:49
cs_halo_t * cs_halo_create(cs_interface_set_t *ifs)
Definition: cs_halo.c:329
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:703
int n_c_domains
Definition: cs_halo.h:72
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:1524
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:849
void cs_halo_sync_num(const cs_halo_t *halo, cs_halo_type_t sync_mode, cs_lnum_t num[])
Definition: cs_halo.c:1019
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
Definition: cs_halo.h:51
const fvm_periodicity_t * periodicity
Definition: cs_halo.h:77
#define END_C_DECLS
Definition: cs_defs.h:430
double cs_real_t
Definition: cs_defs.h:296
void cs_halo_renumber_cells(cs_halo_t *halo, const cs_lnum_t new_cell_id[])
Definition: cs_halo.c:681
cs_halo_t * cs_halo_destroy(cs_halo_t *this_halo)
Definition: cs_halo.c:525
cs_lnum_t * send_index
Definition: cs_halo.h:94
Definition: cs_halo.h:63
void cs_halo_dump(const cs_halo_t *halo, int print_level)
Definition: cs_halo.c:1583
cs_lnum_t * send_list
Definition: cs_halo.h:91
Definition: cs_halo.h:53