programmer's documentation
 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 
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 *
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 
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 
497 
498 #endif /* __FVM_TESSELATION_H__ */