programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
fvm_io_num.h
Go to the documentation of this file.
1 #ifndef __FVM_IO_NUM_H__
2 #define __FVM_IO_NUM_H__
3 
4 /*============================================================================
5  * Main structure for an I/O numbering scheme associated with mesh entities
6  * (such as cells, faces, and vertices);
7  *
8  * In parallel mode, such a scheme is important so as to redistribute
9  * locally numbered entities on n processes to files written by p
10  * processes, with p <= n.
11  *
12  * Only the case where p = 1 is presently implemented, so the numbering
13  * scheme is simply based on entity's global labels.
14  *
15  * For p > 1, it would probably be necessary to extend the numbering
16  * schemes so as to account for the fact that a given entity may have
17  * a main index on its main associated domain, but may be present
18  * as a ghost entity with another index on neighboring domains.
19  *============================================================================*/
20 
21 /*
22  This file is part of Code_Saturne, a general-purpose CFD tool.
23 
24  Copyright (C) 1998-2018 EDF S.A.
25 
26  This program is free software; you can redistribute it and/or modify it under
27  the terms of the GNU General Public License as published by the Free Software
28  Foundation; either version 2 of the License, or (at your option) any later
29  version.
30 
31  This program is distributed in the hope that it will be useful, but WITHOUT
32  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
33  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
34  details.
35 
36  You should have received a copy of the GNU General Public License along with
37  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
38  Street, Fifth Floor, Boston, MA 02110-1301, USA.
39 */
40 
41 /*----------------------------------------------------------------------------*/
42 
43 #include "cs_defs.h"
44 
45 /*----------------------------------------------------------------------------
46  * Local headers
47  *----------------------------------------------------------------------------*/
48 
49 #include "fvm_defs.h"
50 
51 /*----------------------------------------------------------------------------*/
52 
54 
55 /*=============================================================================
56  * Macro definitions
57  *============================================================================*/
58 
59 /*============================================================================
60  * Type definitions
61  *============================================================================*/
62 
63 /*----------------------------------------------------------------------------
64  * Structure defining an I/O numbering scheme
65  *----------------------------------------------------------------------------*/
66 
67 /*
68  Pointer to an I/O numbering scheme structure. The structure
69  itself is private, and is defined in fvm_io_num.c
70 */
71 
72 typedef struct _fvm_io_num_t fvm_io_num_t;
73 
74 /* Space-filling curve types */
75 
76 typedef enum {
77 
78  FVM_IO_NUM_SFC_MORTON_BOX, /* Morton (Z) curve in bounding box */
79  FVM_IO_NUM_SFC_MORTON_CUBE, /* Morton (Z) curve in bounding cube */
80  FVM_IO_NUM_SFC_HILBERT_BOX, /* Peano-Hilbert curve in bounding box */
81  FVM_IO_NUM_SFC_HILBERT_CUBE, /* Peano-Hilbert curve in bounding cube */
82 
84 
85 /*=============================================================================
86  * Static global variables
87  *============================================================================*/
88 
89 /* Names of space-filling curve types */
90 
91 extern const char *fvm_io_num_sfc_type_name[];
92 
93 /*=============================================================================
94  * Public function prototypes
95  *============================================================================*/
96 
97 /*----------------------------------------------------------------------------
98  * Creation of an I/O numbering structure.
99  *
100  * This function is similar to fvm_io_num_create_from_select, albeit
101  * using parent entity numbers (1 to n) instead of ids (0 to n-1).
102  *
103  * parameters:
104  * parent_entity_number <-- pointer to list of selected entitie's parent's
105  * numbers, or NULL if all first nb_ent entities
106  * are used
107  * parent_global_number <-- pointer to list of global (i.e. domain splitting
108  * independent) parent entity numbers
109  * n_entities <-- number of entities considered
110  * share_parent_global <-- if non zero, try to share parent_global_number
111  * instead of using a local copy
112  *
113  * returns:
114  * pointer to I/O numbering structure
115  *----------------------------------------------------------------------------*/
116 
117 fvm_io_num_t *
118 fvm_io_num_create(const cs_lnum_t parent_entity_number[],
119  const cs_gnum_t parent_global_number[],
120  const size_t n_entities,
121  const int share_parent_global);
122 
123 /*----------------------------------------------------------------------------
124  * Creation of an I/O numbering structure based on a selection of entities.
125  *
126  * parameters:
127  * parent_entity_id <-- pointer to list of selected entitie's parent's
128  * ids, or NULL if all first n_ent entities
129  * are used
130  * parent_global_number <-- pointer to list of global (i.e. domain splitting
131  * independent) parent entity numbers
132  * n_entities <-- number of entities considered
133  * share_parent_global <-- if non zero, try to share parent_global_number
134  * instead of using a local copy
135  *
136  * returns:
137  * pointer to I/O numbering structure
138  *----------------------------------------------------------------------------*/
139 
140 fvm_io_num_t *
141 fvm_io_num_create_from_select(const cs_lnum_t parent_entity_id[],
142  const cs_gnum_t parent_global_number[],
143  size_t n_entities,
144  int share_parent_global);
145 
146 /*----------------------------------------------------------------------------
147  * Creation of an I/O numbering structure,
148  * sharing a given global numbering array.
149  *
150  * The corresponding entities must be locally ordered.
151  *
152  * parameters:
153  * global_number <-- pointer to list of global (i.e. domain splitting
154  * independent) entity numbers
155  * global_count <-- global number of entities
156  * n_entities <-- number of local entities considered
157  *
158  * returns:
159  * pointer to I/O numbering structure
160  *----------------------------------------------------------------------------*/
161 
162 fvm_io_num_t *
163 fvm_io_num_create_shared(const cs_gnum_t global_number[],
164  cs_gnum_t global_count,
165  size_t n_entities);
166 
167 /*----------------------------------------------------------------------------
168  * Creation of an I/O numbering structure based on an an initial
169  * I/O numbering and a number of new entities per base entity.
170  *
171  * This is useful for example to create an I/O numbering for
172  * triangles based on split polygons, whose I/O numbering is defined.
173  *
174  * parameters:
175  * base_io_num <-- pointer to base I/O numbering structure
176  * n_sub_entities <-- number of new entities per base entity
177  *
178  * returns:
179  * pointer to I/O numbering structure
180  *----------------------------------------------------------------------------*/
181 
182 fvm_io_num_t *
183 fvm_io_num_create_from_sub(const fvm_io_num_t *base_io_num,
184  const cs_lnum_t n_sub_entities[]);
185 
186 /*----------------------------------------------------------------------------
187  * Creation of an I/O numbering structure based on a strided adjacency.
188  *
189  * The corresponding entities must be locally ordered.
190  *
191  * parameters:
192  * parent_entity_id <-- pointer to list of selected entitie's parent's ids,
193  * or NULL if all first n_ent entities are used
194  * adjacency <-- entity adjacency (1 to n global numbering)
195  * n_entities <-- number of entities considered
196  * stride <-- values per entity
197  *
198  * returns:
199  * pointer to I/O numbering structure
200  *----------------------------------------------------------------------------*/
201 
202 fvm_io_num_t *
203 fvm_io_num_create_from_adj_s(const cs_lnum_t parent_entity_id[],
204  const cs_gnum_t adjacency[],
205  size_t n_entities,
206  size_t stride);
207 
208 /*----------------------------------------------------------------------------
209  * Creation of an I/O numbering structure based on an indexed adjacency.
210  *
211  * The corresponding entities do not need to be locally ordered.
212  *
213  * parameters:
214  * parent_entity_id <-- pointer to list of selected entitie's parent's ids,
215  * or NULL if all first n_ent entities are used
216  * index <-- index on entities for adjacency
217  * adjacency <-- entity adjacency (1 to n global numbering)
218  * n_entities <-- number of entities considered
219  *
220  * returns:
221  * pointer to I/O numbering structure
222  *----------------------------------------------------------------------------*/
223 
224 fvm_io_num_t *
225 fvm_io_num_create_from_adj_i(const cs_lnum_t parent_entity_id[],
226  const cs_lnum_t index[],
227  const cs_gnum_t adjacency[],
228  cs_lnum_t n_entities);
229 
230 /*----------------------------------------------------------------------------
231  * Creation of an I/O numbering structure based on a space-filling curve.
232  *
233  * It is expected that entities are unique (i.e. not duplicated on 2 or
234  * more ranks). If 2 entities have a same Morton codeor Hilbert, their global
235  * number will be determined by lexicographical ordering of coordinates.
236  *
237  * parameters:
238  * coords <-- pointer to entity coordinates (interlaced)
239  * dim <-- spatial dimension
240  * n_entities <-- number of entities considered
241  * sfc_type <-- type of space-filling curve (Morton or Hilbert)
242  *
243  * returns:
244  * pointer to I/O numbering structure
245  *----------------------------------------------------------------------------*/
246 
247 fvm_io_num_t *
249  int dim,
250  size_t n_entities,
251  fvm_io_num_sfc_t sfc_type);
252 
253 /*----------------------------------------------------------------------------
254  * Creation of an I/O numbering structure based on real values, assuming
255  * ordering by increasing values.
256  *
257  * It is expected that entities are unique (i.e. not duplicated on 2 or
258  * more ranks). If 2 entities have a same value, their global
259  * number will be determined by their initial order.
260  *
261  * parameters:
262  * val <-- pointer to real values
263  * n_entities <-- number of entities considered
264  *
265  * returns:
266  * pointer to I/O numbering structure
267  *----------------------------------------------------------------------------*/
268 
269 fvm_io_num_t *
271  size_t n_entities);
272 
273 /*----------------------------------------------------------------------------
274  * Creation of an I/O numbering structure based on a simple accumulation
275  * (i.e. scan) of counts on successive ranks.
276  *
277  * parameters:
278  * n_entities <-- number of entities considered
279  *
280  * returns:
281  * pointer to I/O numbering structure
282  *----------------------------------------------------------------------------*/
283 
284 fvm_io_num_t *
285 fvm_io_num_create_from_scan(size_t n_entities);
286 
287 /*----------------------------------------------------------------------------
288  * Destruction of a I/O numbering structure.
289  *
290  * parameters:
291  * this_io_num <-- pointer to structure that should be destroyed
292  *
293  * returns:
294  * NULL pointer
295  *----------------------------------------------------------------------------*/
296 
297 fvm_io_num_t *
298 fvm_io_num_destroy(fvm_io_num_t * this_io_num);
299 
300 /*----------------------------------------------------------------------------
301  * Transfer ownership of global numbering array from IO numbering structure.
302  *
303  * parameters:
304  * this_io_num <-> pointer to structure transferring array ownership.
305  *
306  * returns:
307  * pointer to transferred array
308  *----------------------------------------------------------------------------*/
309 
310 cs_gnum_t *
312 
313 /*----------------------------------------------------------------------------
314  * Return local number of entities associated with an I/O numbering
315  * structure.
316  *
317  * parameters:
318  * this_io_num <-- pointer to I/O/ numbering structure
319  *
320  * returns:
321  * local number of associated entities
322  *----------------------------------------------------------------------------*/
323 
324 cs_lnum_t
325 fvm_io_num_get_local_count(const fvm_io_num_t *const this_io_num);
326 
327 /*----------------------------------------------------------------------------
328  * Return global number of entities associated with an I/O numbering
329  * structure.
330  *
331  * parameters:
332  * this_io_num <-- pointer to I/O/ numbering structure
333  *
334  * returns:
335  * global number of associated entities
336  *----------------------------------------------------------------------------*/
337 
338 cs_gnum_t
339 fvm_io_num_get_global_count(const fvm_io_num_t *const this_io_num);
340 
341 /*----------------------------------------------------------------------------
342  * Return global numbering associated with an I/O numbering structure.
343  *
344  * parameters:
345  * this_io_num <-- pointer to I/O/ numbering structure
346  *
347  * returns:
348  * pointer to array of global numbers associated with local entities
349  * (1 to n numbering)
350  *----------------------------------------------------------------------------*/
351 
352 const cs_gnum_t *
353 fvm_io_num_get_global_num(const fvm_io_num_t *const this_io_num);
354 
355 /*----------------------------------------------------------------------------
356  * Return the global number of sub-entities associated with an initial
357  * entity whose global numbering is known, given the number of
358  * sub-entities per initial entity.
359  *
360  * parameters:
361  * this_io_num <-- pointer to base io numbering
362  * n_sub_entities <-- number of sub-entities per initial entity
363  * comm <-- associated MPI communicator
364  *
365  * returns:
366  * global number of sub-entities
367  *----------------------------------------------------------------------------*/
368 
369 cs_gnum_t
370 fvm_io_num_global_sub_size(const fvm_io_num_t *this_io_num,
371  const cs_lnum_t n_sub_entities[]);
372 
373 /*----------------------------------------------------------------------------
374  * Dump printout of a I/O numbering structure.
375  *
376  * parameters:
377  * this_io_num <-- pointer to structure that should be dumped
378  *----------------------------------------------------------------------------*/
379 
380 void
381 fvm_io_num_dump(const fvm_io_num_t *const this_io_num);
382 
383 /*----------------------------------------------------------------------------*/
384 
386 
387 #endif /* __FVM_IO_NUM_H__ */
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:281
fvm_io_num_t * fvm_io_num_create_from_scan(size_t n_entities)
Definition: fvm_io_num.c:2715
cs_gnum_t fvm_io_num_global_sub_size(const fvm_io_num_t *this_io_num, const cs_lnum_t n_sub_entities[])
Definition: fvm_io_num.c:2876
#define BEGIN_C_DECLS
Definition: cs_defs.h:453
fvm_io_num_t * fvm_io_num_create_from_select(const cs_lnum_t parent_entity_id[], const cs_gnum_t parent_global_number[], size_t n_entities, int share_parent_global)
Definition: fvm_io_num.c:2061
cs_gnum_t fvm_io_num_get_global_count(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2835
fvm_io_num_sfc_t
Definition: fvm_io_num.h:76
double cs_coord_t
Definition: cs_defs.h:294
double cs_real_t
Floating-point value.
Definition: cs_defs.h:297
void fvm_io_num_dump(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2921
fvm_io_num_t * fvm_io_num_create_shared(const cs_gnum_t global_number[], cs_gnum_t global_count, size_t n_entities)
Definition: fvm_io_num.c:2166
fvm_io_num_t * fvm_io_num_create_from_adj_s(const cs_lnum_t parent_entity_id[], const cs_gnum_t adjacency[], size_t n_entities, size_t stride)
Definition: fvm_io_num.c:2266
fvm_io_num_t * fvm_io_num_create_from_real(const cs_real_t val[], size_t n_entities)
Definition: fvm_io_num.c:2527
fvm_io_num_t * fvm_io_num_destroy(fvm_io_num_t *this_io_num)
Definition: fvm_io_num.c:2771
const char * fvm_io_num_sfc_type_name[]
Definition: fvm_io_num.h:80
fvm_io_num_t * fvm_io_num_create_from_sfc(const cs_coord_t coords[], int dim, size_t n_entities, fvm_io_num_sfc_t sfc_type)
Definition: fvm_io_num.c:2483
Definition: fvm_io_num.h:78
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:293
fvm_io_num_t * fvm_io_num_create_from_sub(const fvm_io_num_t *base_io_num, const cs_lnum_t n_sub_entities[])
Definition: fvm_io_num.c:2201
struct _fvm_io_num_t fvm_io_num_t
Definition: fvm_io_num.h:72
#define END_C_DECLS
Definition: cs_defs.h:454
fvm_io_num_t * fvm_io_num_create_from_adj_i(const cs_lnum_t parent_entity_id[], const cs_lnum_t index[], const cs_gnum_t adjacency[], cs_lnum_t n_entities)
Definition: fvm_io_num.c:2349
cs_gnum_t * fvm_io_num_transfer_global_num(fvm_io_num_t *this_io_num)
Definition: fvm_io_num.c:2792
const cs_gnum_t * fvm_io_num_get_global_num(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2854
cs_lnum_t fvm_io_num_get_local_count(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2816
fvm_io_num_t * fvm_io_num_create(const cs_lnum_t parent_entity_number[], const cs_gnum_t parent_global_number[], const size_t n_entities, const int share_parent_global)
Definition: fvm_io_num.c:2019
Definition: fvm_io_num.h:81
Definition: fvm_io_num.h:79