src/base/cs_interface.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

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
41 BEGIN_C_DECLS
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
94 cs_lnum_t
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 *
211 cs_interface_set_create(cs_lnum_t n_elts,
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
490 END_C_DECLS
491
492 #endif /* __CS_INTERFACE_H__ */