src/fvm/fvm_tesselation.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
fvm_tesselation.h
Go to the documentation of this file.
1 #ifndef __FVM_TESSELATION_H__
2 #define __FVM_TESSELATION_H__
3
4 /*============================================================================
5 * Structure describing a mesh section's subdivision into simpler elements
6 *
7 * This is mostly useful to replace polygons or polyhedra by simpler
8 * elements such as triangles, tetrahedra, and prisms upon data export.
9 *============================================================================*/
10
11 /*
12 This file is part of Code_Saturne, a general-purpose CFD tool.
13
14 Copyright (C) 1998-2013 EDF S.A.
15
16 This program is free software; you can redistribute it and/or modify it under
17 the terms of the GNU General Public License as published by the Free Software
18 Foundation; either version 2 of the License, or (at your option) any later
19 version.
20
21 This program is distributed in the hope that it will be useful, but WITHOUT
22 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
23 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
24 details.
25
26 You should have received a copy of the GNU General Public License along with
27 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
28 Street, Fifth Floor, Boston, MA 02110-1301, USA.
29 */
30
31 /*----------------------------------------------------------------------------*/
32
33 #include "cs_defs.h"
34
35 /*----------------------------------------------------------------------------
36 * Local headers
37 *----------------------------------------------------------------------------*/
38
39 #include "fvm_defs.h"
40 #include "fvm_io_num.h"
41
42 /*----------------------------------------------------------------------------*/
43
44 BEGIN_C_DECLS
45
46 /*=============================================================================
47 * Macro definitions
48 *============================================================================*/
49
50 #define FVM_TESSELATION_N_SUB_TYPES_MAX 2
51
52 /*============================================================================
53 * Type definitions
54 *============================================================================*/
55
56 /*----------------------------------------------------------------------------
57 * Structure defining a tesselation of a mesh section.
58 *----------------------------------------------------------------------------*/
59
60 /*
61 Pointer to tesselation structure. The structure
62 itself is private, and is defined in fvm_tesselation.c
63 */
64
65 typedef struct _fvm_tesselation_t fvm_tesselation_t;
66
67 /*=============================================================================
68 * Public function prototypes
69 *============================================================================*/
70
71 /*----------------------------------------------------------------------------
72 * Creation of a mesh section's subdivision into simpler elements.
73 *
74 * The structure contains pointers to the mesh section's connectivity,
75 * (passed as arguments), which is not copied. This structure should thus
76 * always be destroyed before the mesh section to which it relates.
77 *
78 * Unused connectivity array arguments should be set to NULL (such as
79 * face_index[] and face_num[] for 2D or regular (strided) elements,
80 * and vertex_index[] for strided elements.
81 *
82 * At this stage, the structure does not yet contain tesselation information.
83 *
84 * parameters:
85 * element_type <-- type of elements considered
86 * n_elements <-- number of elements
87 * face_index <-- polyhedron -> faces index (O to n-1)
88 * dimension [n_elements + 1]
89 * face_num <-- element -> face numbers (1 to n, signed,
90 * > 0 for outwards pointing face normal
91 * < 0 for inwards pointing face normal);
92 * dimension: [face_index[n_elements]], or NULL
93 * vertex_index <-- element face -> vertices index (O to n-1);
94 * dimension: [n_cell_faces + 1], [n_elements + 1],
95 * or NULL depending on face_index and vertex_index
96 * vertex_num <-- element -> vertex connectivity (1 to n)
97 * global_element_num <-- global element numbers (NULL in serial mode)
98 *
99 * returns:
100 * pointer to created mesh section tesselation structure
101 *----------------------------------------------------------------------------*/
102
103 fvm_tesselation_t *
104 fvm_tesselation_create(fvm_element_t element_type,
105 cs_lnum_t n_elements,
106 const cs_lnum_t face_index[],
107 const cs_lnum_t face_num[],
108 const cs_lnum_t vertex_index[],
109 const cs_lnum_t vertex_num[],
110 const fvm_io_num_t *global_element_num);
111
112 /*----------------------------------------------------------------------------
113 * Destruction of a mesh section tesselation structure.
114 *
115 * parameters:
116 * this_tesselation <-> pointer to structure that should be destroyed
117 *
118 * returns:
119 * NULL pointer
120 *----------------------------------------------------------------------------*/
121
122 fvm_tesselation_t *
123 fvm_tesselation_destroy(fvm_tesselation_t * this_tesselation);
124
125 /*----------------------------------------------------------------------------
126 * Tesselate a mesh section referred to by an fvm_tesselation_t structure.
127 *
128 * parameters:
129 * this_tesselation <-> partially initialized tesselation structure
130 * dim <-- spatial dimension
131 * vertex_coords <-- associated vertex coordinates array
132 * parent_vertex_num <-- optional indirection to vertex coordinates
133 * error_count --> number of elements with a tesselation error
134 * counter (optional)
135 *----------------------------------------------------------------------------*/
136
137 void
138 fvm_tesselation_init(fvm_tesselation_t *this_tesselation,
139 int dim,
140 const cs_coord_t vertex_coords[],
141 const cs_lnum_t parent_vertex_num[],
142 cs_lnum_t *error_count);
143
144 /*----------------------------------------------------------------------------
145 * Reduction of a nodal mesh polygon splitting representation structure;
146 * only the associations (numberings) necessary to redistribution of fields
147 * for output are conserved, the full connectivity being no longer useful
148 * once it has been output.
149 *
150 * parameters:
151 * this_tesselation <-> pointer to structure that should be reduced
152 *----------------------------------------------------------------------------*/
153
154 void
155 fvm_tesselation_reduce(fvm_tesselation_t * this_tesselation);
156
157 /*----------------------------------------------------------------------------
158 * Return number of parent elements of a tesselation.
159 *
160 * parameters:
161 * this_tesselation <-- tesselation structure
162 *
163 * returns:
164 * number of parent elements
165 *----------------------------------------------------------------------------*/
166
167 cs_lnum_t
168 fvm_tesselation_n_elements(const fvm_tesselation_t *this_tesselation);
169
170 /*----------------------------------------------------------------------------
171 * Return global number of added vertices associated with a tesselation.
172 *
173 * parameters:
174 * this_tesselation <-- tesselation structure
175 *
176 * returns:
177 * global number of added vertices associated with the tesselation
178 *----------------------------------------------------------------------------*/
179
180 cs_gnum_t
181 fvm_tesselation_n_g_vertices_add(const fvm_tesselation_t *this_tesselation);
182
183 /*----------------------------------------------------------------------------
184 * Return (local) number of added vertices associated with a tesselation.
185 *
186 * parameters:
187 * this_tesselation <-- tesselation structure
188 *
189 * returns:
190 * global number of added vertices associated with the tesselation
191 *----------------------------------------------------------------------------*/
192
193 cs_lnum_t
194 fvm_tesselation_n_vertices_add(const fvm_tesselation_t *this_tesselation);
195
196 /*----------------------------------------------------------------------------
197 * Return number of resulting sub-types of a tesselation.
198 *
199 * parameters:
200 * this_tesselation <-- tesselation structure
201 *
202 * returns:
203 * number of resulting sub-types of the tesselation
204 *----------------------------------------------------------------------------*/
205
206 int
207 fvm_tesselation_n_sub_types(const fvm_tesselation_t *this_tesselation);
208
209 /*----------------------------------------------------------------------------
210 * Return given sub-types of a tesselation.
211 *
212 * parameters:
213 * this_tesselation <-- tesselation structure
214 * sub_type_id <-- index of sub-type in tesselation (0 to n-1)
215 *
216 * returns:
217 * sub-types of the tesselation with the given index
218 *----------------------------------------------------------------------------*/
219
220 fvm_element_t
221 fvm_tesselation_sub_type(const fvm_tesselation_t *this_tesselation,
222 int sub_type_id);
223
224 /*----------------------------------------------------------------------------
225 * Return number of elements of a given sub-type of a tesselation.
226 *
227 * parameters:
228 * this_tesselation <-- tesselation structure
229 * sub_type_id <-- index of sub-type in tesselation (0 to n-1)
230 *
231 * returns:
232 * sub-types of the tesselation with the given index
233 *----------------------------------------------------------------------------*/
234
235 cs_lnum_t
236 fvm_tesselation_n_sub_elements(const fvm_tesselation_t *this_tesselation,
237 fvm_element_t sub_type);
238
239 /*----------------------------------------------------------------------------
240 * Obtain the global and maximum number of elements of a given sub-type
241 * of a tesselation.
242 *
243 * parameters:
244 * this_tesselation <-- tesselation structure
245 * sub_type_id <-- index of sub-type in tesselation (0 to n-1)
246 * n_sub_elements_glob --> global number of sub-elements of the given type
247 * n_sub_elements_max --> maximum number of sub-elements per element
248 * of the given type (for all ranks)
249 *----------------------------------------------------------------------------*/
250
251 void
252 fvm_tesselation_get_global_size(const fvm_tesselation_t *this_tesselation,
253 fvm_element_t sub_type,
254 cs_gnum_t *n_sub_elements_glob,
255 cs_lnum_t *n_sub_elements_max);
256
257 /*----------------------------------------------------------------------------
258 * Return global numbering of added vertices associated with a tesselation.
259 *
260 * parameters:
261 * this_tesselation <-- tesselation structure
262 *
263 * returns:
264 * pointer to global numbering of added vertices for this tesselation,
265 * or NULL if no added vertices are present.
266 *----------------------------------------------------------------------------*/
267
268 const fvm_io_num_t *
269 fvm_tesselation_global_vertex_num(const fvm_tesselation_t *this_tesselation);
270
271 /*----------------------------------------------------------------------------
272 * Compute coordinates of added vertices for a tesselation of polyhedra.
273 *
274 * One additional vertex is added near the center of each polyhedra.
275 * For element types other than polyhedra, there is no need for added
276 * vertices, so this function returns immediately.
277 *
278 * parameters:
279 * this_tesselation <-- tesselation structure
280 * vertex_coords --> coordinates of added vertices
281 *----------------------------------------------------------------------------*/
282
283 void
284 fvm_tesselation_vertex_coords(const fvm_tesselation_t *this_tesselation,
285 cs_coord_t vertex_coords[]);
286
287 /*----------------------------------------------------------------------------
288 * Return index of sub-elements associated with each element of a given
289 * sub-type of a tesselation.
290 *
291 * parameters:
292 * this_tesselation <-- tesselation structure
293 * sub_type_id <-- index of sub-type in tesselation (0 to n-1)
294 *
295 * returns:
296 * index of sub-elements associated with each element (0 to n-1 numbering)
297 *----------------------------------------------------------------------------*/
298
299 const cs_lnum_t *
300 fvm_tesselation_sub_elt_index(const fvm_tesselation_t *this_tesselation,
301 fvm_element_t sub_type);
302
303 #if defined(HAVE_MPI)
304
305 /*----------------------------------------------------------------------------
306 * Compute index values corresponding to given range of indices,
307 * for an element -> sub-element value distribution.
308 *
309 * This index is used mainly to gather a decoded tesselation connectivity
310 * or element -> sub-element data distribution, expanding the corresponding
311 * data only on the given range.
312 * Only the index values in the start_id to end_id range are set by
313 * this function, starting with index[start_id] = 0.
314 *
315 * parameters:
316 * this_tesselation <-- tesselation structure
317 * connect_type <-- destination element type
318 * stride <-- number of associated values per sub-element
319 * start_id <-- start index of polyhedra subset in parent section
320 * buffer_limit <-- maximum number of sub-elements of destination
321 * element type allowable for vertex_num[] buffer
322 * global_num_end <-> past the end (maximum + 1) parent element
323 * global number (reduced on return if required
324 * by buffer_size limits)
325 * index --> sub-element index
326 * comm <-- associated MPI communicator
327 *
328 * returns:
329 * polyhedron index end corresponding to decoded range
330 *----------------------------------------------------------------------------*/
331
332 cs_lnum_t
333 fvm_tesselation_range_index_g(const fvm_tesselation_t *this_tesselation,
334 fvm_element_t connect_type,
335 int stride,
336 cs_lnum_t start_id,
337 cs_lnum_t buffer_limit,
338 cs_gnum_t *global_num_end,
339 cs_lnum_t index[],
340 MPI_Comm comm);
341
342 /*----------------------------------------------------------------------------
343 * Decode tesselation to a connectivity buffer.
344 *
345 * To avoid requiring huge buffers and computing unneeded element
346 * connectivities when exporting data in slices, this function may decode
347 * a partial connectivity range, starting at polygon index start_id and ending
348 * either when the indicated buffer size is attained, or the global element
349 * number corresponding to a given polygon exceeds a given value.
350 * It returns the effective polygon index end.
351 *
352 * parameters:
353 * this_tesselation <-- tesselation structure
354 * connect_type <-- destination element type
355 * start_id <-- start index of polygons subset in parent section
356 * buffer_limit <-- maximum number of sub-elements of destination
357 * element type allowable for vertex_num[] buffer
358 * global_num_end <-> past the end (maximum + 1) parent element
359 * global number (reduced on return if required
360 * by buffer_limit)
361 * extra_vertex_base <-- starting number for added vertices
362 * global_vertex_num <-- global vertex numbering
363 * vertex_num --> sub-element (global) vertex connectivity
364 * comm <-- associated MPI communicator
365 *
366 * returns:
367 * polygon index corresponding to end of decoded range
368 *----------------------------------------------------------------------------*/
369
370 cs_lnum_t
371 fvm_tesselation_decode_g(const fvm_tesselation_t *this_tesselation,
372 fvm_element_t connect_type,
373 cs_lnum_t start_id,
374 cs_lnum_t buffer_limit,
375 cs_gnum_t *global_num_end,
376 const fvm_io_num_t *global_vertex_num,
377 cs_gnum_t extra_vertex_base,
378 cs_gnum_t vertex_num[],
379 MPI_Comm comm);
380
381 #endif /* defined(HAVE_MPI) */
382
383 /*----------------------------------------------------------------------------
384 * Decode tesselation to a connectivity buffer.
385 *
386 * To avoid requiring huge buffers and computing unneeded element
387 * connectivities, this function may decode a partial connectivity range,
388 * starting at polygon index start_id and ending either when the indicated
389 * buffer size or the last polygon is attained.
390 * It returns the effective polygon index end.
391 *
392 * parameters:
393 * this_tesselation <-- tesselation structure
394 * connect_type <-- destination element type
395 * start_id <-- start index of polygons subset in parent section
396 * buffer_limit <-- maximum number of sub-elements of destination
397 * element type allowable for vertex_num[] buffer
398 * extra_vertex_base <-- starting number for added vertices
399 * vertex_num --> sub-element (global) vertex connectivity
400 *
401 * returns:
402 * polygon index corresponding to end of decoded range
403 *----------------------------------------------------------------------------*/
404
405 cs_lnum_t
406 fvm_tesselation_decode(const fvm_tesselation_t *this_tesselation,
407 fvm_element_t connect_type,
408 cs_lnum_t start_id,
409 cs_lnum_t buffer_limit,
410 cs_lnum_t extra_vertex_base,
411 cs_lnum_t vertex_num[]);
412
413 /*----------------------------------------------------------------------------
414 * Distribute "per element" data from the base elements to their tesselation.
415 *
416 * The same data array is used for input and output, so as to avoid requiring
417 * excess allocation in typical use cases (extracting data from a parent mesh
418 * to a buffer and distributing it as per its tesselation).
419 * The data array should be at least of size:
420 * [sub_elt_index[end_id] - sub_elt_index[start_id] * size
421 *
422 * parameters:
423 * this_tesselation <-- tesselation structure
424 * connect_type <-- destination element type
425 * start_id <-- start index of elements subset in parent section
426 * end_id <-- end index of elements subset in parent section
427 * size <-- data size for each element (sizeof(type)*stride)
428 * data <-> undistributed data in, distributed data out
429 *----------------------------------------------------------------------------*/
430
431 void
432 fvm_tesselation_distribute(const fvm_tesselation_t *this_tesselation,
433 fvm_element_t connect_type,
434 cs_lnum_t start_id,
435 cs_lnum_t end_id,
436 size_t size,
437 void *data);
438
439 /*----------------------------------------------------------------------------
440 * Compute field values at added vertices for a tesselation of polyhedra.
441 *
442 * One additional vertex is added near the center of each polyhedra.
443 * For element types other than polyhedra, there is no need for added
444 * vertices, so this function returns immediately.
445 *
446 * parameters:
447 * this_tesselation <-- tesselation structure
448 * vertex_coords <-- coordinates of added vertices
449 * src_dim <-- dimension of source data
450 * src_dim_shift <-- source data dimension shift (start index)
451 * dest_dim <-- destination data dimension (1 if non interlaced)
452 * start_id <-- added vertices start index
453 * end_id <-- added vertices past the end index
454 * src_interlace <-- indicates if source data is interlaced
455 * src_datatype <-- source data type (float, double, or int)
456 * dest_datatype <-- destination data type (float, double, or int)
457 * n_parent_lists <-- number of parent lists (if parent_num != NULL)
458 * parent_num_shift <-- parent number to value array index shifts;
459 * size: n_parent_lists
460 * parent_num <-- if n_parent_lists > 0, parent entity numbers
461 * src_data <-- array of source arrays (at least one, with one per
462 * source dimension if non interlaced, times one per
463 * parent list if multiple parent lists, with
464 * x_parent_1, y_parent_1, ..., x_parent_2, ...) order
465 * dest_data --> destination buffer
466 *----------------------------------------------------------------------------*/
467
468 void
469 fvm_tesselation_vertex_values(const fvm_tesselation_t *this_tesselation,
470 int src_dim,
471 int src_dim_shift,
472 int dest_dim,
473 cs_lnum_t start_id,
474 cs_lnum_t end_id,
475 cs_interlace_t src_interlace,
476 cs_datatype_t src_datatype,
477 cs_datatype_t dest_datatype,
478 int n_parent_lists,
479 const cs_lnum_t parent_num_shift[],
480 const cs_lnum_t parent_num[],
481 const void *const src_data[],
482 void *const dest_data);
483
484 /*----------------------------------------------------------------------------
485 * Dump printout of a mesh section tesselation structure.
486 *
487 * parameters:
488 * this_tesselation <-- pointer to structure that should be dumped
489 *----------------------------------------------------------------------------*/
490
491 void
492 fvm_tesselation_dump(const fvm_tesselation_t *this_tesselation);
493
494 /*----------------------------------------------------------------------------*/
495
496 END_C_DECLS
497
498 #endif /* __FVM_TESSELATION_H__ */