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