8.3
general documentation
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-2024 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
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
65typedef 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
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
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_id <-- optional indirection to vertex coordinates
133 * error_count --> number of elements with a tesselation error
134 * counter (optional)
135 *----------------------------------------------------------------------------*/
136
137void
139 int dim,
140 const cs_coord_t vertex_coords[],
141 const cs_lnum_t parent_vertex_id[],
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
154void
155fvm_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
168fvm_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
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
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
206int
207fvm_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
221fvm_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
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
251void
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
268const fvm_io_num_t *
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
283void
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
299const cs_lnum_t *
301 fvm_element_t sub_type);
302
303#if defined(HAVE_MPI)
304
305/*----------------------------------------------------------------------------
306 * Decode tesselation to a connectivity buffer.
307 *
308 * parameters:
309 * this_tesselation <-- tesselation structure
310 * connect_type <-- destination element type
311 * extra_vertex_base <-- starting number for added vertices
312 * global_vertex_num <-- global vertex numbering
313 * extra_vertex_base <-- starting number for added vertices
314 * vertex_num --> sub-element (global) vertex connectivity
315 *----------------------------------------------------------------------------*/
316
317void
318fvm_tesselation_decode_g(const fvm_tesselation_t *this_tesselation,
319 fvm_element_t connect_type,
320 const fvm_io_num_t *global_vertex_num,
321 cs_gnum_t extra_vertex_base,
322 cs_gnum_t vertex_num[]);
323
324#endif /* defined(HAVE_MPI) */
325
326/*----------------------------------------------------------------------------
327 * Decode tesselation to a connectivity buffer.
328 *
329 * To avoid requiring huge buffers and computing unneeded element
330 * connectivities, this function may decode a partial connectivity range,
331 * starting at polygon index start_id and ending either when the indicated
332 * buffer size or the last polygon is attained.
333 * It returns the effective polygon index end.
334 *
335 * parameters:
336 * this_tesselation <-- tesselation structure
337 * connect_type <-- destination element type
338 * start_id <-- start index of polygons subset in parent section
339 * buffer_limit <-- maximum number of sub-elements of destination
340 * element type allowable for vertex_num[] buffer
341 * extra_vertex_base <-- starting number for added vertices
342 * vertex_num --> sub-element (global) vertex connectivity
343 *
344 * returns:
345 * polygon index corresponding to end of decoded range
346 *----------------------------------------------------------------------------*/
347
349fvm_tesselation_decode(const fvm_tesselation_t *this_tesselation,
350 fvm_element_t connect_type,
351 cs_lnum_t start_id,
352 cs_lnum_t buffer_limit,
353 cs_lnum_t extra_vertex_base,
354 cs_lnum_t vertex_num[]);
355
356/*----------------------------------------------------------------------------
357 * Distribute "per element" data from the base elements to their tesselation.
358 *
359 * The same data array is used for input and output, so as to avoid requiring
360 * excess allocation in typical use cases (extracting data from a parent mesh
361 * to a buffer and distributing it as per its tesselation).
362 * The data array should be at least of size:
363 * [sub_elt_index[end_id] - sub_elt_index[start_id] * size
364 *
365 * parameters:
366 * this_tesselation <-- tesselation structure
367 * connect_type <-- destination element type
368 * start_id <-- start index of elements subset in parent section
369 * end_id <-- end index of elements subset in parent section
370 * size <-- data size for each element (sizeof(type)*stride)
371 * data <-> undistributed data in, distributed data out
372 *----------------------------------------------------------------------------*/
373
374void
375fvm_tesselation_distribute(const fvm_tesselation_t *this_tesselation,
376 fvm_element_t connect_type,
377 cs_lnum_t start_id,
378 cs_lnum_t end_id,
379 size_t size,
380 void *data);
381
382/*----------------------------------------------------------------------------
383 * Compute field values at added vertices for a tesselation of polyhedra.
384 *
385 * One additional vertex is added near the center of each polyhedra.
386 * For element types other than polyhedra, there is no need for added
387 * vertices, so this function returns immediately.
388 *
389 * parameters:
390 * this_tesselation <-- tesselation structure
391 * vertex_coords <-- coordinates of added vertices
392 * src_dim <-- dimension of source data
393 * src_dim_shift <-- source data dimension shift (start index)
394 * dest_dim <-- destination data dimension (1 if non interlaced)
395 * start_id <-- added vertices start index
396 * end_id <-- added vertices past the end index
397 * src_interlace <-- indicates if source data is interlaced
398 * src_datatype <-- source data type (float, double, or int)
399 * dest_datatype <-- destination data type (float, double, or int)
400 * n_parent_lists <-- number of parent lists (if parent_num != NULL)
401 * parent_num_shift <-- parent number to value array index shifts;
402 * size: n_parent_lists
403 * parent_num <-- if n_parent_lists > 0, parent entity numbers
404 * src_data <-- array of source arrays (at least one, with one per
405 * source dimension if non interlaced, times one per
406 * parent list if multiple parent lists, with
407 * x_parent_1, y_parent_1, ..., x_parent_2, ...) order
408 * dest_data --> destination buffer
409 *----------------------------------------------------------------------------*/
410
411void
413 int src_dim,
414 int src_dim_shift,
415 int dest_dim,
416 cs_lnum_t start_id,
417 cs_lnum_t end_id,
418 cs_interlace_t src_interlace,
419 cs_datatype_t src_datatype,
420 cs_datatype_t dest_datatype,
421 int n_parent_lists,
422 const cs_lnum_t parent_num_shift[],
423 const cs_lnum_t parent_num[],
424 const void *const src_data[],
425 void *const dest_data);
426
427/*----------------------------------------------------------------------------
428 * Dump printout of a mesh section tesselation structure.
429 *
430 * parameters:
431 * this_tesselation <-- pointer to structure that should be dumped
432 *----------------------------------------------------------------------------*/
433
434void
435fvm_tesselation_dump(const fvm_tesselation_t *this_tesselation);
436
437/*----------------------------------------------------------------------------*/
438
440
441#endif /* __FVM_TESSELATION_H__ */
cs_datatype_t
Definition: cs_defs.h:300
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
double cs_coord_t
Definition: cs_defs.h:340
uint64_t cs_gnum_t
global mesh entity number
Definition: cs_defs.h:325
cs_interlace_t
Definition: cs_defs.h:514
#define END_C_DECLS
Definition: cs_defs.h:543
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:335
fvm_element_t
Definition: fvm_defs.h:48
struct _fvm_io_num_t fvm_io_num_t
Definition: fvm_io_num.h:72
void fvm_tesselation_distribute(const fvm_tesselation_t *this_tesselation, fvm_element_t connect_type, cs_lnum_t start_id, cs_lnum_t end_id, size_t size, void *data)
Definition: fvm_tesselation.cpp:2631
const fvm_io_num_t * fvm_tesselation_global_vertex_num(const fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2430
cs_lnum_t fvm_tesselation_n_vertices_add(const fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2288
cs_lnum_t fvm_tesselation_n_sub_elements(const fvm_tesselation_t *this_tesselation, fvm_element_t sub_type)
Definition: fvm_tesselation.cpp:2360
void fvm_tesselation_reduce(fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2211
cs_lnum_t fvm_tesselation_n_elements(const fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2238
void fvm_tesselation_dump(const fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2767
fvm_tesselation_t * fvm_tesselation_create(fvm_element_t element_type, cs_lnum_t n_elements, const cs_lnum_t face_index[], const cs_lnum_t face_num[], const cs_lnum_t vertex_index[], const cs_lnum_t vertex_num[], const fvm_io_num_t *global_element_num)
Definition: fvm_tesselation.cpp:2003
struct _fvm_tesselation_t fvm_tesselation_t
Definition: fvm_tesselation.h:65
int fvm_tesselation_n_sub_types(const fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2311
cs_lnum_t fvm_tesselation_decode(const fvm_tesselation_t *this_tesselation, fvm_element_t connect_type, cs_lnum_t start_id, cs_lnum_t buffer_limit, cs_lnum_t extra_vertex_base, cs_lnum_t vertex_num[])
Definition: fvm_tesselation.cpp:2572
void fvm_tesselation_vertex_coords(const fvm_tesselation_t *this_tesselation, cs_coord_t vertex_coords[])
Definition: fvm_tesselation.cpp:2455
fvm_tesselation_t * fvm_tesselation_destroy(fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2127
void fvm_tesselation_get_global_size(const fvm_tesselation_t *this_tesselation, fvm_element_t sub_type, cs_gnum_t *n_sub_elements_glob, cs_lnum_t *n_sub_elements_max)
Definition: fvm_tesselation.cpp:2392
cs_gnum_t fvm_tesselation_n_g_vertices_add(const fvm_tesselation_t *this_tesselation)
Definition: fvm_tesselation.cpp:2259
fvm_element_t fvm_tesselation_sub_type(const fvm_tesselation_t *this_tesselation, int sub_type_id)
Definition: fvm_tesselation.cpp:2333
const cs_lnum_t * fvm_tesselation_sub_elt_index(const fvm_tesselation_t *this_tesselation, fvm_element_t sub_type)
Definition: fvm_tesselation.cpp:2484
void fvm_tesselation_init(fvm_tesselation_t *this_tesselation, int dim, const cs_coord_t vertex_coords[], const cs_lnum_t parent_vertex_id[], cs_lnum_t *error_count)
Definition: fvm_tesselation.cpp:2156
void fvm_tesselation_vertex_values(const fvm_tesselation_t *this_tesselation, int src_dim, int src_dim_shift, int dest_dim, cs_lnum_t start_id, cs_lnum_t end_id, cs_interlace_t src_interlace, cs_datatype_t src_datatype, cs_datatype_t dest_datatype, int n_parent_lists, const cs_lnum_t parent_num_shift[], const cs_lnum_t parent_num[], const void *const src_data[], void *const dest_data)
Definition: fvm_tesselation.cpp:2706