programmer's documentation
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-2015 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 a simple accumulation
255  * (i.e. scan) of counts on successive ranks.
256  *
257  * parameters:
258  * n_entities <-- number of entities considered
259  *
260  * returns:
261  * pointer to I/O numbering structure
262  *----------------------------------------------------------------------------*/
263 
264 fvm_io_num_t *
265 fvm_io_num_create_from_scan(size_t n_entities);
266 
267 /*----------------------------------------------------------------------------
268  * Destruction of a I/O numbering structure.
269  *
270  * parameters:
271  * this_io_num <-- pointer to structure that should be destroyed
272  *
273  * returns:
274  * NULL pointer
275  *----------------------------------------------------------------------------*/
276 
277 fvm_io_num_t *
278 fvm_io_num_destroy(fvm_io_num_t * this_io_num);
279 
280 /*----------------------------------------------------------------------------
281  * Transfer ownership of global numbering array from IO numbering structure.
282  *
283  * parameters:
284  * this_io_num <-> pointer to structure transferring array ownership.
285  *
286  * returns:
287  * pointer to transferred array
288  *----------------------------------------------------------------------------*/
289 
290 cs_gnum_t *
292 
293 /*----------------------------------------------------------------------------
294  * Return local number of entities associated with an I/O numbering
295  * structure.
296  *
297  * parameters:
298  * this_io_num <-- pointer to I/O/ numbering structure
299  *
300  * returns:
301  * local number of associated entities
302  *----------------------------------------------------------------------------*/
303 
304 cs_lnum_t
305 fvm_io_num_get_local_count(const fvm_io_num_t *const this_io_num);
306 
307 /*----------------------------------------------------------------------------
308  * Return global number of entities associated with an I/O numbering
309  * structure.
310  *
311  * parameters:
312  * this_io_num <-- pointer to I/O/ numbering structure
313  *
314  * returns:
315  * global number of associated entities
316  *----------------------------------------------------------------------------*/
317 
318 cs_gnum_t
319 fvm_io_num_get_global_count(const fvm_io_num_t *const this_io_num);
320 
321 /*----------------------------------------------------------------------------
322  * Return global numbering associated with an I/O numbering structure.
323  *
324  * parameters:
325  * this_io_num <-- pointer to I/O/ numbering structure
326  *
327  * returns:
328  * pointer to array of global numbers associated with local entities
329  * (1 to n numbering)
330  *----------------------------------------------------------------------------*/
331 
332 const cs_gnum_t *
333 fvm_io_num_get_global_num(const fvm_io_num_t *const this_io_num);
334 
335 /*----------------------------------------------------------------------------
336  * Return the global number of sub-entities associated with an initial
337  * entity whose global numbering is known, given the number of
338  * sub-entities per initial entity.
339  *
340  * parameters:
341  * this_io_num <-- pointer to base io numbering
342  * n_sub_entities <-- number of sub-entities per initial entity
343  * comm <-- associated MPI communicator
344  *
345  * returns:
346  * global number of sub-entities
347  *----------------------------------------------------------------------------*/
348 
349 cs_gnum_t
350 fvm_io_num_global_sub_size(const fvm_io_num_t *this_io_num,
351  const cs_lnum_t n_sub_entities[]);
352 
353 /*----------------------------------------------------------------------------
354  * Dump printout of a I/O numbering structure.
355  *
356  * parameters:
357  * this_io_num <-- pointer to structure that should be dumped
358  *----------------------------------------------------------------------------*/
359 
360 void
361 fvm_io_num_dump(const fvm_io_num_t *const this_io_num);
362 
363 /*----------------------------------------------------------------------------*/
364 
366 
367 #endif /* __FVM_IO_NUM_H__ */
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:280
fvm_io_num_t * fvm_io_num_create_from_scan(size_t n_entities)
Definition: fvm_io_num.c:2501
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:2662
#define BEGIN_C_DECLS
Definition: cs_defs.h:429
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:2048
cs_gnum_t fvm_io_num_get_global_count(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2621
fvm_io_num_sfc_t
Definition: fvm_io_num.h:76
double cs_coord_t
Definition: cs_defs.h:293
void fvm_io_num_dump(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2704
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:2147
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:2245
fvm_io_num_t * fvm_io_num_destroy(fvm_io_num_t *this_io_num)
Definition: fvm_io_num.c:2557
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:2462
Definition: fvm_io_num.h:78
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
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:2182
struct _fvm_io_num_t fvm_io_num_t
Definition: fvm_io_num.h:72
#define END_C_DECLS
Definition: cs_defs.h:430
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:2328
cs_gnum_t * fvm_io_num_transfer_global_num(fvm_io_num_t *this_io_num)
Definition: fvm_io_num.c:2578
const cs_gnum_t * fvm_io_num_get_global_num(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2640
cs_lnum_t fvm_io_num_get_local_count(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.c:2602
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:1947
Definition: fvm_io_num.h:81
Definition: fvm_io_num.h:79