programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups 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-2013 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  * parameters:
101  * parent_entity_number <-- pointer to list of selected entitie's parent's
102  * numbers, or NULL if all first nb_ent entities
103  * are used
104  * parent_global_number <-- pointer to list of global (i.e. domain splitting
105  * independent) parent entity numbers
106  * n_entities <-- number of entities considered
107  * share_parent_global <-- if non zero, try to share parent_global_number
108  * instead of using a local copy
109  *
110  * returns:
111  * pointer to I/O numbering structure
112  *----------------------------------------------------------------------------*/
113 
114 fvm_io_num_t *
115 fvm_io_num_create(const cs_lnum_t parent_entity_number[],
116  const cs_gnum_t parent_global_number[],
117  const size_t n_entities,
118  const int share_parent_global);
119 
120 /*----------------------------------------------------------------------------
121  * Creation of an I/O numbering structure,
122  * sharing a given global numbering array.
123  *
124  * The corresponding entities must be locally ordered.
125  *
126  * parameters:
127  * global_number <-- pointer to list of global (i.e. domain splitting
128  * independent) entity numbers
129  * global_count <-- global number of entities
130  * n_entities <-- number of local entities considered
131  *
132  * returns:
133  * pointer to I/O numbering structure
134  *----------------------------------------------------------------------------*/
135 
136 fvm_io_num_t *
137 fvm_io_num_create_shared(const cs_gnum_t global_number[],
138  cs_gnum_t global_count,
139  size_t n_entities);
140 
141 /*----------------------------------------------------------------------------
142  * Creation of an I/O numbering structure based on an an initial
143  * I/O numbering and a number of new entities per base entity.
144  *
145  * This is useful for example to create an I/O numbering for
146  * triangles based on split polygons, whose I/O numbering is defined.
147  *
148  * parameters:
149  * base_io_num <-- pointer to base I/O numbering structure
150  * n_sub_entities <-- number of new entities per base entity
151  *
152  * returns:
153  * pointer to I/O numbering structure
154  *----------------------------------------------------------------------------*/
155 
156 fvm_io_num_t *
157 fvm_io_num_create_from_sub(const fvm_io_num_t *base_io_num,
158  const cs_lnum_t n_sub_entities[]);
159 
160 /*----------------------------------------------------------------------------
161  * Creation of an I/O numbering structure based on a strided adjacency.
162  *
163  * The corresponding entities must be locally ordered.
164  *
165  * parameters:
166  * parent_entity_number <-- pointer to list of selected entitie's parent's
167  * numbers, or NULL if all first n_ent entities
168  * are used
169  * adjacency <-- entity adjacency (1 to n global numbering)
170  * n_entities <-- number of entities considered
171  * stride <-- values per entity
172  *
173  * returns:
174  * pointer to I/O numbering structure
175  *----------------------------------------------------------------------------*/
176 
177 fvm_io_num_t *
178 fvm_io_num_create_from_adj_s(const cs_lnum_t parent_entity_number[],
179  const cs_gnum_t adjacency[],
180  size_t n_entities,
181  size_t stride);
182 
183 /*----------------------------------------------------------------------------
184  * Creation of an I/O numbering structure based on an indexed adjacency.
185  *
186  * The corresponding entities do not need to be locally ordered.
187  *
188  * parameters:
189  * parent_entity_number <-- pointer to list of selected entitie's parent's
190  * numbers, or NULL if all first n_ent entities
191  * are used
192  * index <-- index on entities for adjacency
193  * adjacency <-- entity adjacency (1 to n global numbering)
194  * n_entities <-- number of entities considered
195  *
196  * returns:
197  * pointer to I/O numbering structure
198  *----------------------------------------------------------------------------*/
199 
200 fvm_io_num_t *
201 fvm_io_num_create_from_adj_i(const cs_lnum_t parent_entity_number[],
202  const cs_lnum_t index[],
203  const cs_gnum_t adjacency[],
204  cs_lnum_t n_entities);
205 
206 /*----------------------------------------------------------------------------
207  * Creation of an I/O numbering structure based on a space-filling curve.
208  *
209  * It is expected that entities are unique (i.e. not duplicated on 2 or
210  * more ranks). If 2 entities have a same Morton codeor Hilbert, their global
211  * number will be determined by lexicographical ordering of coordinates.
212  *
213  * parameters:
214  * coords <-- pointer to entity coordinates (interlaced)
215  * dim <-- spatial dimension
216  * n_entities <-- number of entities considered
217  * sfc_type <-- type of space-filling curve (Morton or Hilbert)
218  *
219  * returns:
220  * pointer to I/O numbering structure
221  *----------------------------------------------------------------------------*/
222 
223 fvm_io_num_t *
225  int dim,
226  size_t n_entities,
227  fvm_io_num_sfc_t sfc_type);
228 
229 /*----------------------------------------------------------------------------
230  * Creation of an I/O numbering structure based on a simple accumulation
231  * (i.e. scan) of counts on successive ranks.
232  *
233  * parameters:
234  * n_entities <-- number of entities considered
235  *
236  * returns:
237  * pointer to I/O numbering structure
238  *----------------------------------------------------------------------------*/
239 
240 fvm_io_num_t *
241 fvm_io_num_create_from_scan(size_t n_entities);
242 
243 /*----------------------------------------------------------------------------
244  * Destruction of a I/O numbering structure.
245  *
246  * parameters:
247  * this_io_num <-- pointer to structure that should be destroyed
248  *
249  * returns:
250  * NULL pointer
251  *----------------------------------------------------------------------------*/
252 
253 fvm_io_num_t *
254 fvm_io_num_destroy(fvm_io_num_t * this_io_num);
255 
256 /*----------------------------------------------------------------------------
257  * Transfer ownership of global numbering array from IO numbering structure.
258  *
259  * parameters:
260  * this_io_num <-> pointer to structure transferring array ownership.
261  *
262  * returns:
263  * pointer to transferred array
264  *----------------------------------------------------------------------------*/
265 
266 cs_gnum_t *
267 fvm_io_num_transfer_global_num(fvm_io_num_t * this_io_num);
268 
269 /*----------------------------------------------------------------------------
270  * Return local number of entities associated with an I/O numbering
271  * structure.
272  *
273  * parameters:
274  * this_io_num <-- pointer to I/O/ numbering structure
275  *
276  * returns:
277  * local number of associated entities
278  *----------------------------------------------------------------------------*/
279 
280 cs_lnum_t
281 fvm_io_num_get_local_count(const fvm_io_num_t *const this_io_num);
282 
283 /*----------------------------------------------------------------------------
284  * Return global number of entities associated with an I/O numbering
285  * structure.
286  *
287  * parameters:
288  * this_io_num <-- pointer to I/O/ numbering structure
289  *
290  * returns:
291  * global number of associated entities
292  *----------------------------------------------------------------------------*/
293 
294 cs_gnum_t
295 fvm_io_num_get_global_count(const fvm_io_num_t *const this_io_num);
296 
297 /*----------------------------------------------------------------------------
298  * Return global numbering associated with an I/O numbering structure.
299  *
300  * parameters:
301  * this_io_num <-- pointer to I/O/ numbering structure
302  *
303  * returns:
304  * pointer to array of global numbers associated with local entities
305  * (1 to n numbering)
306  *----------------------------------------------------------------------------*/
307 
308 const cs_gnum_t *
309 fvm_io_num_get_global_num(const fvm_io_num_t *const this_io_num);
310 
311 /*----------------------------------------------------------------------------
312  * Return the global number of sub-entities associated with an initial
313  * entity whose global numbering is known, given the number of
314  * sub-entities per initial entity.
315  *
316  * parameters:
317  * this_io_num <-- pointer to base io numbering
318  * n_sub_entities <-- number of sub-entities per initial entity
319  * comm <-- associated MPI communicator
320  *
321  * returns:
322  * global number of sub-entities
323  *----------------------------------------------------------------------------*/
324 
325 cs_gnum_t
326 fvm_io_num_global_sub_size(const fvm_io_num_t *this_io_num,
327  const cs_lnum_t n_sub_entities[]);
328 
329 /*----------------------------------------------------------------------------
330  * Dump printout of a I/O numbering structure.
331  *
332  * parameters:
333  * this_io_num <-- pointer to structure that should be dumped
334  *----------------------------------------------------------------------------*/
335 
336 void
337 fvm_io_num_dump(const fvm_io_num_t *const this_io_num);
338 
339 /*----------------------------------------------------------------------------*/
340 
342 
343 #endif /* __FVM_IO_NUM_H__ */