programmer's documentation
 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 
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 *
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 *
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
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
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
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
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
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 
430 
431 #endif /* __CS_HALO_H__ */