8.0
general documentation
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-2023 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 are 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
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 
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 *
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 *
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
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 *
170 
171 /*----------------------------------------------------------------------------*/
186 /*----------------------------------------------------------------------------*/
187 
188 void
190  const fvm_periodicity_t *periodicity,
191  int tr_ignore,
192  cs_gnum_t tag_value,
193  cs_gnum_t *tag);
194 
195 /*----------------------------------------------------------------------------
196  * Creation of a list of interfaces between elements of a same type.
197  *
198  * These interfaces may be used to identify equivalent vertices or faces using
199  * domain splitting, as well as periodic elements (on the same or on
200  * distant ranks).
201  *
202  * Note that periodicity information will be completed and made consistent
203  * based on the input, so that if a periodic couple is defined on a given rank,
204  * the reverse couple wil be defined, whether it is also defined on the same
205  * or a different rank.
206  *
207  * In addition, multiple periodicity interfaces will be built automatically
208  * if the periodicity structure provides for composed periodicities, so they
209  * need not be defined prior to this function.
210  *
211  * parameters:
212  * n_elts <-- number of local elements considered
213  * (size of parent_element_id[]
214  * parent_element_id <-- pointer to list of selected elements local
215  * numbers (0 to n-1), or NULL if all first n_elts
216  * elements are used
217  * global_number <-- pointer to list of global (i.e. domain splitting
218  * independent) element numbers
219  * periodicity <-- periodicity information (NULL if none)
220  * n_periodic_lists <-- number of periodic lists (may be local)
221  * periodicity_num <-- periodicity number (1 to n) associated with
222  * each periodic list (primary periodicities only)
223  * n_periodic_couples <-- number of periodic couples associated with
224  * each periodic list
225  * periodic_couples <-- array indicating periodic couples (using
226  * global numberings) for each list
227  *
228  * returns:
229  * pointer to list of interfaces (possibly NULL in serial mode)
230  *----------------------------------------------------------------------------*/
231 
234  const cs_lnum_t parent_element_id[],
235  const cs_gnum_t global_number[],
236  const fvm_periodicity_t *periodicity,
237  int n_periodic_lists,
238  const int periodicity_num[],
239  const cs_lnum_t n_periodic_couples[],
240  const cs_gnum_t *const periodic_couples[]);
241 
242 /*----------------------------------------------------------------------------
243  * Destruction of an interface set.
244  *
245  * parameters:
246  * ifs <-> pointer to pointer to structure to destroy
247  *----------------------------------------------------------------------------*/
248 
249 void
251 
252 /*----------------------------------------------------------------------------*/
261 /*----------------------------------------------------------------------------*/
262 
265  cs_lnum_t stride);
266 
267 /*----------------------------------------------------------------------------*/
277 /*----------------------------------------------------------------------------*/
278 
281  cs_lnum_t block_size,
282  cs_lnum_t n_blocks);
283 
284 /*----------------------------------------------------------------------------
285  * Return number of interfaces associated with an interface set.
286  *
287  * parameters:
288  * ifs <-- pointer to interface set structure
289  *
290  * returns:
291  * number of interfaces in set
292  *----------------------------------------------------------------------------*/
293 
294 int
296 
297 /*----------------------------------------------------------------------------
298  * Return total number of elements in interface set.
299  *
300  * This is equal to the sum of cs_interface_size() on the cs_interface_size()
301  * interfaces of a set.
302  *
303  * parameters:
304  * ifs <-- pointer to interface set structure
305  *
306  * returns:
307  * number of interfaces in set
308  *----------------------------------------------------------------------------*/
309 
310 cs_lnum_t
312 
313 /*----------------------------------------------------------------------------
314  * Return pointer to a given interface in an interface set.
315  *
316  * parameters:
317  * ifs <-- pointer to interface set structure
318  * interface_id <-- index of interface in set (0 to n-1)
319  *
320  * returns:
321  * pointer to interface structure
322  *----------------------------------------------------------------------------*/
323 
324 const cs_interface_t *
326  int interface_id);
327 
328 /*----------------------------------------------------------------------------
329  * Return pointer to the periocicity structure associated of an interface set.
330  *
331  * parameters:
332  * ifs <-- pointer to interface set structure
333  *
334  * returns:
335  * pointer to periodicity structure, or NULL
336  *----------------------------------------------------------------------------*/
337 
338 const fvm_periodicity_t *
340 
341 /*----------------------------------------------------------------------------
342  * Apply renumbering of elements referenced by an interface set.
343  *
344  * For any given element i, a negative old_to_new[i] value means that that
345  * element does not appear anymore in the new numbering.
346  *
347  * parameters:
348  * ifs <-> pointer to interface set structure
349  * old_to_new <-- renumbering array (0 to n-1 numbering)
350  *----------------------------------------------------------------------------*/
351 
352 void
354  const cs_lnum_t old_to_new[]);
355 
356 /*----------------------------------------------------------------------------
357  * Add matching element id information to an interface set.
358  *
359  * This information is required by calls to cs_interface_get_match_ids(),
360  * and may be freed using cs_interface_set_free_match_ids().
361  *
362  * parameters:
363  * ifs <-> pointer to interface set structure
364  *----------------------------------------------------------------------------*/
365 
366 void
368 
369 /*----------------------------------------------------------------------------
370  * Free matching element id information of an interface set.
371  *
372  * This information is used by calls to cs_interface_get_match_ids(),
373  * and may be defined using cs_interface_set_add_match_ids().
374  *
375  * parameters:
376  * ifs <-> pointer to interface set structure
377  *----------------------------------------------------------------------------*/
378 
379 void
381 
382 /*----------------------------------------------------------------------------
383  * Copy array from distant or matching interface elements to local elements.
384  *
385  * Source and destination arrays define values for all elements in the
386  * interface set (i.e. all elements listed by cs_interface_get_elt_ids()
387  * when looping over interfaces of a set,
388  *
389  * parameters:
390  * ifs <-- pointer to interface set structure
391  * datatype <-- type of data considered
392  * stride <-- number of values per entity (interlaced)
393  * src_on_parent <-- true if source array is defined on the elements
394  * defined by ifs->elt_ids, false if source array
395  * defined directly on cs_interface_set_n_elts(ifs)
396  * src <-- source array (size: cs_interface_set_n_elts(ifs)*stride
397  * or parent array size * stride)
398  * dest <-- destination array
399  * (size: cs_interface_set_n_elts(ifs)*stride)
400  *----------------------------------------------------------------------------*/
401 
402 void
404  cs_datatype_t datatype,
405  int stride,
406  bool src_on_parent,
407  const void *src,
408  void *dest);
409 
410 /*----------------------------------------------------------------------------
411  * Copy indexed array from distant or matching interface elements to
412  * local elements.
413  *
414  * Source and destination arrays define values for all elements in the
415  * interface set (i.e. all elements listed by cs_interface_get_elt_ids()
416  * when looping over interfaces of a set,
417  *
418  * Note that when copying the same type of data to all matching elements,
419  * the source and destination index may be the same, if src_on_parent is true.
420  * To avoid requiring a separate destination index, the dest_index argument
421  * may be set to NULL, in which case it is assumed that source and destination
422  * are symmetric, and src_index is sufficient to determine sizes (whether
423  * src_on_parent is true or not).
424  *
425  * In some use cases, for example when copying values only in one direction,
426  * the copying is not symmetric, so both a source and destination buffer must
427  * be provided.
428  *
429  * parameters:
430  * ifs <-- pointer to interface set structure
431  * datatype <-- type of data considered
432  * src_on_parent <-- true if source array is defined on the elements
433  * defined by ifs->elt_ids, false if source array
434  * defined directly on cs_interface_set_n_elts(ifs)
435  * src_index <-- index for source array
436  * dest_index <-- index for destination array, or NULL
437  * src <-- source array (size:
438  * src_index[cs_interface_set_n_elts(ifs)]
439  * or parent array size * stride)
440  * dest <-- destination array (size:
441  * src_index[cs_interface_set_n_elts(ifs)] or
442  * dest_index[cs_interface_set_n_elts(ifs)])
443  *----------------------------------------------------------------------------*/
444 
445 void
447  cs_datatype_t datatype,
448  bool src_on_parent,
449  const cs_lnum_t src_index[],
450  const cs_lnum_t dest_index[],
451  const void *src,
452  void *dest);
453 
454 /*----------------------------------------------------------------------------*/
472 /*----------------------------------------------------------------------------*/
473 
474 void
476  cs_lnum_t n_elts,
477  cs_lnum_t stride,
478  bool interlace,
479  cs_datatype_t datatype,
480  void *var);
481 
482 /*----------------------------------------------------------------------------
483  * Update the sum of values for elements associated with an interface set.
484  *
485  * On input, the variable array should contain local contributions. On output,
486  * contributions from matching elements on parallel or periodic boundaries
487  * have been added.
488  *
489  * Only the values of elements belonging to the interfaces are modified.
490  *
491  * parameters:
492  * ifs <-- pointer to a fvm_interface_set_t structure
493  * n_elts <-- number of elements in var buffer
494  * stride <-- number of values (non interlaced) by entity
495  * interlace <-- true if variable is interlaced (for stride > 1)
496  * datatype <-- type of data considered
497  * var <-> variable buffer
498  *----------------------------------------------------------------------------*/
499 
500 void
502  cs_lnum_t n_elts,
503  cs_lnum_t stride,
504  bool interlace,
505  cs_datatype_t datatype,
506  void *var);
507 
508 /*----------------------------------------------------------------------------*/
528 /*----------------------------------------------------------------------------*/
529 
530 void
532  cs_lnum_t n_elts,
533  cs_lnum_t stride,
534  bool interlace,
535  cs_datatype_t datatype,
536  int tr_ignore,
537  void *var);
538 
539 /*----------------------------------------------------------------------------
540  * Update to minimum value for elements associated with an interface set.
541  *
542  * On input, the variable array should contain local contributions. On output,
543  * contributions from matching elements on parallel or periodic boundaries
544  * have been added.
545  *
546  * Only the values of elements belonging to the interfaces are modified.
547  *
548  * parameters:
549  * ifs <-- pointer to a fvm_interface_set_t structure
550  * n_elts <-- number of elements in var buffer
551  * stride <-- number of values (non interlaced) by entity
552  * interlace <-- true if variable is interlaced (for stride > 1)
553  * datatype <-- type of data considered
554  * var <-> variable buffer
555  *----------------------------------------------------------------------------*/
556 
557 void
559  cs_lnum_t n_elts,
560  cs_lnum_t stride,
561  bool interlace,
562  cs_datatype_t datatype,
563  void *var);
564 
565 /*----------------------------------------------------------------------------
566  * Update to maximum value for elements associated with an interface set.
567  *
568  * On input, the variable array should contain local contributions. On output,
569  * contributions from matching elements on parallel or periodic boundaries
570  * have been added.
571  *
572  * Only the values of elements belonging to the interfaces are modified.
573  *
574  * parameters:
575  * ifs <-- pointer to a fvm_interface_set_t structure
576  * n_elts <-- number of elements in var buffer
577  * stride <-- number of values (non interlaced) by entity
578  * interlace <-- true if variable is interlaced (for stride > 1)
579  * datatype <-- type of data considered
580  * var <-> variable buffer
581  *----------------------------------------------------------------------------*/
582 
583 void
585  cs_lnum_t n_elts,
586  cs_lnum_t stride,
587  bool interlace,
588  cs_datatype_t datatype,
589  void *var);
590 
591 /*----------------------------------------------------------------------------*/
611 /*----------------------------------------------------------------------------*/
612 
613 void
615  cs_lnum_t n_elts,
616  cs_lnum_t stride,
617  bool interlace,
618  cs_datatype_t datatype,
619  int tr_ignore,
620  void *var);
621 
622 /*----------------------------------------------------------------------------
623  * Dump printout of an interface list.
624  *
625  * parameters:
626  * ifs <-- pointer to structure that should be dumped
627  *----------------------------------------------------------------------------*/
628 
629 void
631 
632 /*----------------------------------------------------------------------------*/
633 
635 
636 #endif /* __CS_INTERFACE_H__ */
cs_datatype_t
Definition: cs_defs.h:272
#define BEGIN_C_DECLS
Definition: cs_defs.h:509
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:298
#define END_C_DECLS
Definition: cs_defs.h:510
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:313
void cs_interface_tag_local_matches(const cs_interface_t *itf, const fvm_periodicity_t *periodicity, int tr_ignore, cs_gnum_t tag_value, cs_gnum_t *tag)
Tag mutiple elements of local interface with a given values.
Definition: cs_interface.c:6039
void cs_interface_set_copy_indexed(const cs_interface_set_t *ifs, cs_datatype_t datatype, bool src_on_parent, const cs_lnum_t src_index[], const cs_lnum_t dest_index[], const void *src, void *dest)
Copy indexed array from distant or matching interface elements to local elements.
Definition: cs_interface.c:4217
int cs_interface_set_size(const cs_interface_set_t *ifs)
Return number of interfaces associated with an interface set.
Definition: cs_interface.c:3849
void cs_interface_set_renumber(cs_interface_set_t *ifs, const cs_lnum_t old_to_new[])
Apply renumbering of elements referenced by an interface set.
Definition: cs_interface.c:3945
void cs_interface_set_sum(const cs_interface_set_t *ifs, cs_lnum_t n_elts, cs_lnum_t stride, bool interlace, cs_datatype_t datatype, void *var)
Update the sum of values for elements associated with an interface set.
Definition: cs_interface.c:4616
void cs_interface_set_max_tr(const cs_interface_set_t *ifs, cs_lnum_t n_elts, cs_lnum_t stride, bool interlace, cs_datatype_t datatype, int tr_ignore, void *var)
Update the maximum of values for elements associated with an interface set, allowing control over per...
Definition: cs_interface.c:5588
const fvm_periodicity_t * cs_interface_set_periodicity(const cs_interface_set_t *ifs)
Return pointer to the periocicity structure associated of an interface set.
Definition: cs_interface.c:3922
void cs_interface_set_inclusive_or(const cs_interface_set_t *ifs, cs_lnum_t n_elts, cs_lnum_t stride, bool interlace, cs_datatype_t datatype, void *var)
Update values using the bitwise inclusive or operation for elements associated with an interface set.
Definition: cs_interface.c:4414
const cs_lnum_t * cs_interface_get_elt_ids(const cs_interface_t *itf)
Return pointer to array of local element ids defining an interface.
Definition: cs_interface.c:3388
cs_interface_set_t * cs_interface_set_create(cs_lnum_t n_elts, const cs_lnum_t parent_element_id[], const cs_gnum_t global_number[], const fvm_periodicity_t *periodicity, int n_periodic_lists, const int periodicity_num[], const cs_lnum_t n_periodic_couples[], const cs_gnum_t *const periodic_couples[])
Creation of a list of interfaces between elements of a same type.
Definition: cs_interface.c:3520
void cs_interface_set_dump(const cs_interface_set_t *ifs)
Dump printout of an interface list.
Definition: cs_interface.c:6099
cs_lnum_t cs_interface_size(const cs_interface_t *itf)
Return number of local and distant elements defining an interface.
Definition: cs_interface.c:3362
cs_interface_set_t * cs_interface_set_dup_blocks(cs_interface_set_t *ifs, cs_lnum_t block_size, cs_lnum_t n_blocks)
Duplicate an interface set for coupled variable blocks.
Definition: cs_interface.c:3717
void cs_interface_set_destroy(cs_interface_set_t **ifs)
Destruction of an interface set.
Definition: cs_interface.c:3624
int cs_interface_rank(const cs_interface_t *itf)
Return process rank associated with an interface's distant elements.
Definition: cs_interface.c:3341
void cs_interface_set_free_match_ids(cs_interface_set_t *ifs)
Free matching element id information of an interface set.
Definition: cs_interface.c:6004
const cs_interface_t * cs_interface_set_get(const cs_interface_set_t *ifs, int interface_id)
Return pointer to a given interface in an interface set.
Definition: cs_interface.c:3897
void cs_interface_set_copy_array(const cs_interface_set_t *ifs, cs_datatype_t datatype, int stride, bool src_on_parent, const void *src, void *dest)
Copy array from distant or matching interface elements to local elements.
Definition: cs_interface.c:4050
struct _cs_interface_set_t cs_interface_set_t
Definition: cs_interface.h:61
void cs_interface_set_min(const cs_interface_set_t *ifs, cs_lnum_t n_elts, cs_lnum_t stride, bool interlace, cs_datatype_t datatype, void *var)
Update to minimum value for elements associated with an interface set.
Definition: cs_interface.c:5058
void cs_interface_set_add_match_ids(cs_interface_set_t *ifs)
Add matching element id information to an interface set.
Definition: cs_interface.c:5879
struct _cs_interface_t cs_interface_t
Definition: cs_interface.h:60
cs_lnum_t cs_interface_set_n_elts(const cs_interface_set_t *ifs)
Return total number of elements in interface set.
Definition: cs_interface.c:3873
const cs_lnum_t * cs_interface_get_tr_index(const cs_interface_t *itf)
Return pointer to index of sub-sections for different transformations.
Definition: cs_interface.c:3470
cs_interface_set_t * cs_interface_set_dup(const cs_interface_set_t *ifs, cs_lnum_t stride)
Duplicate an interface set, applying an optional constant stride.
Definition: cs_interface.c:3651
cs_lnum_t cs_interface_get_tr_index_size(const cs_interface_t *itf)
Return size of index of sub-sections for different transformations.
Definition: cs_interface.c:3444
void cs_interface_set_sum_tr(const cs_interface_set_t *ifs, cs_lnum_t n_elts, cs_lnum_t stride, bool interlace, cs_datatype_t datatype, int tr_ignore, void *var)
Update the sum of values for elements associated with an interface set, allowing control over periodi...
Definition: cs_interface.c:4866
void cs_interface_set_max(const cs_interface_set_t *ifs, cs_lnum_t n_elts, cs_lnum_t stride, bool interlace, cs_datatype_t datatype, void *var)
Update to maximum value for elements associated with an interface set.
Definition: cs_interface.c:5322
const cs_lnum_t * cs_interface_get_match_ids(const cs_interface_t *itf)
Return pointer to array of matching element ids defining an interface.
Definition: cs_interface.c:3417
struct _fvm_periodicity_t fvm_periodicity_t
Definition: fvm_periodicity.h:67