programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_interface.h
Go to the documentation of this file.
1 #ifndef __CS_INTERFACE_H__
2 #define __CS_INTERFACE_H__
3 
4 /*============================================================================
5  * Main structure for handling of interfaces associating mesh elements
6  * (such as inter-processor or periodic connectivity between cells, faces,
7  * or vertices);
8  *============================================================================*/
9 
10 /*
11  This file is part of Code_Saturne, a general-purpose CFD tool.
12 
13  Copyright (C) 1998-2013 EDF S.A.
14 
15  This program is free software; you can redistribute it and/or modify it under
16  the terms of the GNU General Public License as published by the Free Software
17  Foundation; either version 2 of the License, or (at your option) any later
18  version.
19 
20  This program is distributed in the hope that it will be useful, but WITHOUT
21  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
22  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
23  details.
24 
25  You should have received a copy of the GNU General Public License along with
26  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
27  Street, Fifth Floor, Boston, MA 02110-1301, USA.
28 */
29 
30 /*----------------------------------------------------------------------------*/
31 
32 /*----------------------------------------------------------------------------
33  * Local headers
34  *----------------------------------------------------------------------------*/
35 
36 #include "fvm_defs.h"
37 #include "fvm_periodicity.h"
38 
39 /*----------------------------------------------------------------------------*/
40 
42 
43 /*=============================================================================
44  * Macro definitions
45  *============================================================================*/
46 
47 /*============================================================================
48  * Type definitions
49  *============================================================================*/
50 
51 /*----------------------------------------------------------------------------
52  * Structure defining an I/O numbering scheme
53  *----------------------------------------------------------------------------*/
54 
55 /*
56  Pointer to structures representing an interface and a list of interfaces.
57  The structures themselves are private, and is defined in cs_interface.c
58 */
59 
60 typedef struct _cs_interface_t cs_interface_t;
61 typedef struct _cs_interface_set_t cs_interface_set_t;
62 
63 /*=============================================================================
64  * Static global variables
65  *============================================================================*/
66 
67 /*=============================================================================
68  * Public function prototypes
69  *============================================================================*/
70 
71 /*----------------------------------------------------------------------------
72  * Return process rank associated with an interface's distant elements.
73  *
74  * parameters:
75  * itf <-- pointer to interface structure
76  *
77  * returns:
78  * process rank associated with the interface's distant elements
79  *----------------------------------------------------------------------------*/
80 
81 int
82 cs_interface_rank(const cs_interface_t *itf);
83 
84 /*----------------------------------------------------------------------------
85  * Return number of local and distant elements defining an interface.
86  *
87  * parameters:
88  * itf <-- pointer to interface structure
89  *
90  * returns:
91  * number of local and distant elements defining the interface
92  *----------------------------------------------------------------------------*/
93 
95 cs_interface_size(const cs_interface_t *itf);
96 
97 /*----------------------------------------------------------------------------
98  * Return pointer to array of local element ids defining an interface.
99  *
100  * The size of the array may be obtained by cs_interface_size().
101  * The array is owned by the interface structure, and is not copied
102  * (hence the constant qualifier for the return value).
103  *
104  * parameters:
105  * itf <-- pointer to interface structure
106  *
107  * returns:
108  * pointer to array of local element ids (0 to n-1) defining the interface
109  *----------------------------------------------------------------------------*/
110 
111 const cs_lnum_t *
112 cs_interface_get_elt_ids(const cs_interface_t *itf);
113 
114 /*----------------------------------------------------------------------------
115  * Return pointer to array of matching element ids defining an interface.
116  *
117  * This array is only available if cs_interface_set_add_match_ids() has
118  * been called for the containing interface set.
119  *
120  * The size of the array may be obtained by cs_interface_size().
121  * The array is owned by the interface structure, and is not copied
122  * (hence the constant qualifier for the return value).
123  *
124  * parameters:
125  * itf <-- pointer to interface structure
126  *
127  * returns:
128  * pointer to array of local element ids (0 to n-1) defining the interface
129  *----------------------------------------------------------------------------*/
130 
131 const cs_lnum_t *
132 cs_interface_get_match_ids(const cs_interface_t *itf);
133 
134 /*----------------------------------------------------------------------------
135  * Return size of index of sub-sections for different transformations.
136  *
137  * The index is applicable to both local_num and distant_num arrays,
138  * with purely parallel equivalences appearing at position 0, and
139  * equivalences through periodic transform i at position i+1;
140  * Its size should thus be equal to 1 + number of periodic transforms + 1,
141  * In absence of periodicity, it may be 0, as the index is not needed.
142  *
143  * parameters:
144  * itf <-- pointer to interface structure
145  *
146  * returns:
147  * transform index size for the interface
148  *----------------------------------------------------------------------------*/
149 
150 cs_lnum_t
151 cs_interface_get_tr_index_size(const cs_interface_t *itf);
152 
153 /*----------------------------------------------------------------------------
154  * Return pointer to index of sub-sections for different transformations.
155  *
156  * The index is applicable to both local_num and distant_num arrays,
157  * with purely parallel equivalences appearing at position 0, and
158  * equivalences through periodic transform i at position i+1;
159  * In absence of periodicity, it may be NULL, as it is not needed.
160  *
161  * parameters:
162  * itf <-- pointer to interface structure
163  *
164  * returns:
165  * pointer to transform index for the interface
166  *----------------------------------------------------------------------------*/
167 
168 const cs_lnum_t *
169 cs_interface_get_tr_index(const cs_interface_t *itf);
170 
171 /*----------------------------------------------------------------------------
172  * Creation of a list of interfaces between elements of a same type.
173  *
174  * These interfaces may be used to identify equivalent vertices or faces using
175  * domain splitting, as well as periodic elements (on the same or on
176  * distant ranks).
177  *
178  * Note that periodicity information will be completed and made consistent
179  * based on the input, so that if a periodic couple is defined on a given rank,
180  * the reverse couple wil be defined, whether it is also defined on the same
181  * or a different rank.
182  *
183  * In addition, multiple periodicity interfaces will be built automatically
184  * if the periodicity structure provides for composed periodicities, so they
185  * need not be defined prior to this function.
186  *
187  * The corresponding elements must be locally ordered.
188  *
189  * parameters:
190  * n_elts <-- number of local elements considered
191  * (size of parent_element_number[]
192  * parent_element_id <-- pointer to list of selected elements local
193  * numbers (0 to n-1), or NULL if all first n_elts
194  * elements are used
195  * global_number <-- pointer to list of global (i.e. domain splitting
196  * independent) element numbers
197  * periodicity <-- periodicity information (NULL if none)
198  * n_periodic_lists <-- number of periodic lists (may be local)
199  * periodicity_num <-- periodicity number (1 to n) associated with
200  * each periodic list (primary periodicities only)
201  * n_periodic_couples <-- number of periodic couples associated with
202  * each periodic list
203  * periodic_couples <-- array indicating periodic couples (using
204  * global numberings) for each list
205  *
206  * returns:
207  * pointer to list of interfaces (possibly NULL in serial mode)
208  *----------------------------------------------------------------------------*/
209 
210 cs_interface_set_t *
212  const cs_lnum_t parent_element_id[],
213  const cs_gnum_t global_number[],
214  const fvm_periodicity_t *periodicity,
215  int n_periodic_lists,
216  const int periodicity_num[],
217  const cs_lnum_t n_periodic_couples[],
218  const cs_gnum_t *const periodic_couples[]);
219 
220 /*----------------------------------------------------------------------------
221  * Destruction of an interface set.
222  *
223  * parameters:
224  * ifs <-> pointer to pointer to structure to destroy
225  *----------------------------------------------------------------------------*/
226 
227 void
228 cs_interface_set_destroy(cs_interface_set_t **ifs);
229 
230 /*----------------------------------------------------------------------------
231  * Return number of interfaces associated with an interface set.
232  *
233  * parameters:
234  * ifs <-- pointer to interface set structure
235  *
236  * returns:
237  * number of interfaces in set
238  *----------------------------------------------------------------------------*/
239 
240 int
241 cs_interface_set_size(const cs_interface_set_t *ifs);
242 
243 /*----------------------------------------------------------------------------
244  * Return total number of elements in interface set.
245  *
246  * This is equal to the sum of cs_interface_size() on the cs_interface_size()
247  * interfaces of a set.
248  *
249  * parameters:
250  * ifs <-- pointer to interface set structure
251  *
252  * returns:
253  * number of interfaces in set
254  *----------------------------------------------------------------------------*/
255 
256 cs_lnum_t
257 cs_interface_set_n_elts(const cs_interface_set_t *ifs);
258 
259 /*----------------------------------------------------------------------------
260  * Return pointer to a given interface in an interface set.
261  *
262  * parameters:
263  * ifs <-- pointer to interface set structure
264  * interface_id <-- index of interface in set (0 to n-1)
265  *
266  * returns:
267  * pointer to interface structure
268  *----------------------------------------------------------------------------*/
269 
270 const cs_interface_t *
271 cs_interface_set_get(const cs_interface_set_t *ifs,
272  int interface_id);
273 
274 /*----------------------------------------------------------------------------
275  * Return pointer to the periocicity structure associated of an interface set.
276  *
277  * parameters:
278  * ifs <-- pointer to interface set structure
279  *
280  * returns:
281  * pointer to periodicity structure, or NULL
282  *----------------------------------------------------------------------------*/
283 
284 const fvm_periodicity_t *
285 cs_interface_set_periodicity(const cs_interface_set_t *ifs);
286 
287 /*----------------------------------------------------------------------------
288  * Apply renumbering of elements referenced by an interface set.
289  *
290  * For any given element i, a negative old_to_new[i] value means that that
291  * element does not appear anymore in the new numbering.
292  *
293  * parameters:
294  * ifs <-> pointer to interface set structure
295  * old_to_new <-- renumbering array (0 to n-1 numbering)
296  *----------------------------------------------------------------------------*/
297 
298 void
299 cs_interface_set_renumber(cs_interface_set_t *ifs,
300  const cs_lnum_t old_to_new[]);
301 
302 /*----------------------------------------------------------------------------
303  * Add matching element id information to an interface set.
304  *
305  * This information is required by calls to cs_interface_get_dist_ids(),
306  * and may be freed using cs_interface_set_free_match_ids().
307  *
308  * parameters:
309  * ifs <-> pointer to interface set structure
310  *----------------------------------------------------------------------------*/
311 
312 void
313 cs_interface_set_add_match_ids(cs_interface_set_t *ifs);
314 
315 /*----------------------------------------------------------------------------
316  * Free matching element id information of an interface set.
317  *
318  * This information is used by calls to cs_interface_get_dist_ids(),
319  * and may be defined using cs_interface_set_add_match_ids().
320  *
321  * parameters:
322  * ifs <-> pointer to interface set structure
323  *----------------------------------------------------------------------------*/
324 
325 void
326 cs_interface_set_free_match_ids(cs_interface_set_t *ifs);
327 
328 /*----------------------------------------------------------------------------
329  * Copy array from distant or matching interface elements to local elements.
330  *
331  * Source and destination arrays define values for all elements in the
332  * interface set (i.e. all elements listed by cs_interface_get_elt_ids()
333  * when looping over interfaces of a set,
334  *
335  * parameters:
336  * ifs <-- pointer to interface set structure
337  * datatype <-- type of data considered
338  * stride <-- number of values per entity (interlaced)
339  * src_on_parent <-- true if source array is defined on the elements
340  * defined by ifs->elt_ids, false if source array
341  * defined directly on cs_interface_set_n_elts(ifs)
342  * src <-- source array (size: cs_interface_set_n_elts(ifs)*stride
343  * or parent array size * stride)
344  * dest <-- destination array
345  * (size: cs_interface_set_n_elts(ifs)*stride)
346  *----------------------------------------------------------------------------*/
347 
348 void
349 cs_interface_set_copy_array(const cs_interface_set_t *ifs,
350  cs_datatype_t datatype,
351  int stride,
352  bool src_on_parent,
353  const void *src,
354  void *dest);
355 
356 /*----------------------------------------------------------------------------
357  * Copy indexed array from distant or matching interface elements to
358  * local elements.
359  *
360  * Source and destination arrays define values for all elements in the
361  * interface set (i.e. all elements listed by cs_interface_get_elt_ids()
362  * when looping over interfaces of a set,
363  *
364  * Note that when copying the same type of data to all matching elements,
365  * the source and destination index may be the same, if src_on_parent is true.
366  * To avoid requiring a separate destination index, the dest_index argument
367  * may be set to NULL, in which case it is assumed that source and destination
368  * are symmetric, and src_index is sufficient to determine sizes (whether
369  * src_on_parent is true or not).
370  *
371  * In some use cases, for example when copying values only in one, the
372  * copying is not symmetric, so both a source and destination buffer must
373  * be provided.
374  *
375  * parameters:
376  * ifs <-- pointer to interface set structure
377  * datatype <-- type of data considered
378  * src_on_parent <-- true if source array is defined on the elements
379  * defined by ifs->elt_ids, false if source array
380  * defined directly on cs_interface_set_n_elts(ifs)
381  * src_index <-- index for source array
382  * dest_index <-- index for destination array, or NULL
383  * src <-- source array (size:
384  * src_index[cs_interface_set_n_elts(ifs)]
385  * or parent array size * stride)
386  * dest <-- destination array (size:
387  * src_index[cs_interface_set_n_elts(ifs)] or
388  * dest_index[cs_interface_set_n_elts(ifs)])
389  *----------------------------------------------------------------------------*/
390 
391 void
392 cs_interface_set_copy_indexed(const cs_interface_set_t *ifs,
393  cs_datatype_t datatype,
394  bool src_on_parent,
395  const cs_lnum_t src_index[],
396  const cs_lnum_t dest_index[],
397  const void *src,
398  void *dest);
399 
400 /*----------------------------------------------------------------------------
401  * Update the sum of values for elements associated with an interface set.
402  *
403  * On input, the variable array should contain local contributions. On output,
404  * contributions from matching elements on parallel or periodic boundaries
405  * have been added.
406  *
407  * Only the values of elements belonging to the interfaces are modified.
408  *
409  * parameters:
410  * ifs <-- pointer to a fvm_interface_set_t structure
411  * n_elts <-- number of elements in var buffer
412  * stride <-- number of values (non interlaced) by entity
413  * interlace <-- true if variable is interlaced (for stride > 1)
414  * datatype <-- type of data considered
415  * var <-> variable buffer
416  *----------------------------------------------------------------------------*/
417 
418 void
419 cs_interface_set_sum(cs_interface_set_t *ifs,
420  cs_lnum_t n_elts,
421  cs_lnum_t stride,
422  bool interlace,
423  cs_datatype_t datatype,
424  void *var);
425 
426 /*----------------------------------------------------------------------------
427  * Update to maximum value for elements associated with an interface set.
428  *
429  * On input, the variable array should contain local contributions. On output,
430  * contributions from matching elements on parallel or periodic boundaries
431  * have been added.
432  *
433  * Only the values of elements belonging to the interfaces are modified.
434  *
435  * parameters:
436  * ifs <-- pointer to a fvm_interface_set_t structure
437  * n_elts <-- number of elements in var buffer
438  * stride <-- number of values (non interlaced) by entity
439  * interlace <-- true if variable is interlaced (for stride > 1)
440  * datatype <-- type of data considered
441  * var <-> variable buffer
442  *----------------------------------------------------------------------------*/
443 
444 void
445 cs_interface_set_max(cs_interface_set_t *ifs,
446  cs_lnum_t n_elts,
447  cs_lnum_t stride,
448  bool interlace,
449  cs_datatype_t datatype,
450  void *var);
451 
452 /*----------------------------------------------------------------------------
453  * Update to maximum value for elements associated with an interface set.
454  *
455  * On input, the variable array should contain local contributions. On output,
456  * contributions from matching elements on parallel or periodic boundaries
457  * have been added.
458  *
459  * Only the values of elements belonging to the interfaces are modified.
460  *
461  * parameters:
462  * ifs <-- pointer to a fvm_interface_set_t structure
463  * n_elts <-- number of elements in var buffer
464  * stride <-- number of values (non interlaced) by entity
465  * interlace <-- true if variable is interlaced (for stride > 1)
466  * datatype <-- type of data considered
467  * var <-> variable buffer
468  *----------------------------------------------------------------------------*/
469 
470 void
471 cs_interface_set_max(cs_interface_set_t *ifs,
472  cs_lnum_t n_elts,
473  cs_lnum_t stride,
474  bool interlace,
475  cs_datatype_t datatype,
476  void *var);
477 
478 /*----------------------------------------------------------------------------
479  * Dump printout of an interface list.
480  *
481  * parameters:
482  * ifs <-- pointer to structure that should be dumped
483  *----------------------------------------------------------------------------*/
484 
485 void
486 cs_interface_set_dump(const cs_interface_set_t *ifs);
487 
488 /*----------------------------------------------------------------------------*/
489 
491 
492 #endif /* __CS_INTERFACE_H__ */