8.3
general 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-2024 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
72typedef struct _fvm_io_num_t fvm_io_num_t;
73
74/* Space-filling curve types */
75
76typedef 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
91extern 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
118fvm_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
141fvm_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 * parameters:
151 * global_number <-- pointer to list of global (i.e. domain splitting
152 * independent) entity numbers
153 * global_count <-- global number of entities
154 * n_entities <-- number of local entities considered
155 *
156 * returns:
157 * pointer to I/O numbering structure
158 *----------------------------------------------------------------------------*/
159
161fvm_io_num_create_shared(const cs_gnum_t global_number[],
162 cs_gnum_t global_count,
163 size_t n_entities);
164
165/*----------------------------------------------------------------------------
166 * Creation of an I/O numbering structure based on an an initial
167 * I/O numbering and a number of new entities per base entity.
168 *
169 * This is useful for example to create an I/O numbering for
170 * triangles based on split polygons, whose I/O numbering is defined.
171 *
172 * parameters:
173 * base_io_num <-- pointer to base I/O numbering structure
174 * n_sub_entities <-- number of new entities per base entity
175 *
176 * returns:
177 * pointer to I/O numbering structure
178 *----------------------------------------------------------------------------*/
179
182 const cs_lnum_t n_sub_entities[]);
183
184/*----------------------------------------------------------------------------
185 * Creation of an I/O numbering structure based on a strided adjacency.
186 *
187 * The corresponding entities must be locally ordered.
188 *
189 * parameters:
190 * parent_entity_id <-- pointer to list of selected entitie's parent's ids,
191 * or NULL if all first n_ent entities are used
192 * adjacency <-- entity adjacency (1 to n global numbering)
193 * n_entities <-- number of entities considered
194 * stride <-- values per entity
195 *
196 * returns:
197 * pointer to I/O numbering structure
198 *----------------------------------------------------------------------------*/
199
201fvm_io_num_create_from_adj_s(const cs_lnum_t parent_entity_id[],
202 const cs_gnum_t adjacency[],
203 size_t n_entities,
204 size_t stride);
205
206/*----------------------------------------------------------------------------
207 * Creation of an I/O numbering structure based on an indexed adjacency.
208 *
209 * The corresponding entities do not need to be locally ordered.
210 *
211 * parameters:
212 * parent_entity_id <-- pointer to list of selected entitie's parent's ids,
213 * or NULL if all first n_ent entities are used
214 * index <-- index on entities for adjacency
215 * adjacency <-- entity adjacency (1 to n global numbering)
216 * n_entities <-- number of entities considered
217 *
218 * returns:
219 * pointer to I/O numbering structure
220 *----------------------------------------------------------------------------*/
221
223fvm_io_num_create_from_adj_i(const cs_lnum_t parent_entity_id[],
224 const cs_lnum_t index[],
225 const cs_gnum_t adjacency[],
226 cs_lnum_t n_entities);
227
228/*----------------------------------------------------------------------------
229 * Creation of an I/O numbering structure based on a space-filling curve.
230 *
231 * It is expected that entities are unique (i.e. not duplicated on 2 or
232 * more ranks). If 2 entities have a same Morton codeor Hilbert, their global
233 * number will be determined by lexicographical ordering of coordinates.
234 *
235 * parameters:
236 * coords <-- pointer to entity coordinates (interlaced)
237 * dim <-- spatial dimension
238 * n_entities <-- number of entities considered
239 * sfc_type <-- type of space-filling curve (Morton or Hilbert)
240 *
241 * returns:
242 * pointer to I/O numbering structure
243 *----------------------------------------------------------------------------*/
244
247 int dim,
248 size_t n_entities,
249 fvm_io_num_sfc_t sfc_type);
250
251/*----------------------------------------------------------------------------
252 * Creation of an I/O numbering structure based on real values, assuming
253 * ordering by increasing values.
254 *
255 * It is expected that entities are unique (i.e. not duplicated on 2 or
256 * more ranks). If 2 entities have a same value, their global
257 * number will be determined by their initial order.
258 *
259 * parameters:
260 * val <-- pointer to real values
261 * n_entities <-- number of entities considered
262 *
263 * returns:
264 * pointer to I/O numbering structure
265 *----------------------------------------------------------------------------*/
266
269 size_t n_entities);
270
271/*----------------------------------------------------------------------------
272 * Creation of an I/O numbering structure based on a simple accumulation
273 * (i.e. scan) of counts on successive ranks.
274 *
275 * parameters:
276 * n_entities <-- number of entities considered
277 *
278 * returns:
279 * pointer to I/O numbering structure
280 *----------------------------------------------------------------------------*/
281
283fvm_io_num_create_from_scan(size_t n_entities);
284
285/*----------------------------------------------------------------------------
286 * Destruction of a I/O numbering structure.
287 *
288 * parameters:
289 * this_io_num <-- pointer to structure that should be destroyed
290 *
291 * returns:
292 * null pointer
293 *----------------------------------------------------------------------------*/
294
296fvm_io_num_destroy(fvm_io_num_t * this_io_num);
297
298/*----------------------------------------------------------------------------
299 * Transfer ownership of global numbering array from IO numbering structure.
300 *
301 * parameters:
302 * this_io_num <-> pointer to structure transferring array ownership.
303 *
304 * returns:
305 * pointer to transferred array
306 *----------------------------------------------------------------------------*/
307
308cs_gnum_t *
310
311/*----------------------------------------------------------------------------
312 * Return local number of entities associated with an I/O numbering
313 * structure.
314 *
315 * parameters:
316 * this_io_num <-- pointer to I/O/ numbering structure
317 *
318 * returns:
319 * local number of associated entities
320 *----------------------------------------------------------------------------*/
321
323fvm_io_num_get_local_count(const fvm_io_num_t *const this_io_num);
324
325/*----------------------------------------------------------------------------
326 * Return global number of entities associated with an I/O numbering
327 * structure.
328 *
329 * parameters:
330 * this_io_num <-- pointer to I/O/ numbering structure
331 *
332 * returns:
333 * global number of associated entities
334 *----------------------------------------------------------------------------*/
335
337fvm_io_num_get_global_count(const fvm_io_num_t *const this_io_num);
338
339/*----------------------------------------------------------------------------
340 * Return global numbering associated with an I/O numbering structure.
341 *
342 * parameters:
343 * this_io_num <-- pointer to I/O/ numbering structure
344 *
345 * returns:
346 * pointer to array of global numbers associated with local entities
347 * (1 to n numbering)
348 *----------------------------------------------------------------------------*/
349
350const cs_gnum_t *
351fvm_io_num_get_global_num(const fvm_io_num_t *const this_io_num);
352
353/*----------------------------------------------------------------------------
354 * Return the global number of sub-entities associated with an initial
355 * entity whose global numbering is known, given the number of
356 * sub-entities per initial entity.
357 *
358 * parameters:
359 * this_io_num <-- pointer to base io numbering
360 * n_sub_entities <-- number of sub-entities per initial entity
361 * comm <-- associated MPI communicator
362 *
363 * returns:
364 * global number of sub-entities
365 *----------------------------------------------------------------------------*/
366
369 const cs_lnum_t n_sub_entities[]);
370
371/*----------------------------------------------------------------------------
372 * Dump printout of a I/O numbering structure.
373 *
374 * parameters:
375 * this_io_num <-- pointer to structure that should be dumped
376 *----------------------------------------------------------------------------*/
377
378void
379fvm_io_num_dump(const fvm_io_num_t *const this_io_num);
380
381/*----------------------------------------------------------------------------*/
382
384
385#endif /* __FVM_IO_NUM_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
double cs_real_t
Floating-point value.
Definition: cs_defs.h:342
double cs_coord_t
Definition: cs_defs.h:340
uint64_t cs_gnum_t
global mesh entity number
Definition: cs_defs.h:325
#define END_C_DECLS
Definition: cs_defs.h:543
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:335
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.cpp:2228
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.cpp:2362
fvm_io_num_t * fvm_io_num_create_from_scan(size_t n_entities)
Definition: fvm_io_num.cpp:2598
const cs_gnum_t * fvm_io_num_get_global_num(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.cpp:2738
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.cpp:2080
fvm_io_num_t * fvm_io_num_create_from_real(const cs_real_t val[], size_t n_entities)
Definition: fvm_io_num.cpp:2406
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.cpp:2145
cs_lnum_t fvm_io_num_get_local_count(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.cpp:2700
fvm_io_num_sfc_t
Definition: fvm_io_num.h:76
@ FVM_IO_NUM_SFC_HILBERT_BOX
Definition: fvm_io_num.h:80
@ FVM_IO_NUM_SFC_HILBERT_CUBE
Definition: fvm_io_num.h:81
@ FVM_IO_NUM_SFC_MORTON_BOX
Definition: fvm_io_num.h:78
@ FVM_IO_NUM_SFC_MORTON_CUBE
Definition: fvm_io_num.h:79
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.cpp:1942
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.cpp:1900
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.cpp:2045
struct _fvm_io_num_t fvm_io_num_t
Definition: fvm_io_num.h:72
const char * fvm_io_num_sfc_type_name[]
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.cpp:2760
void fvm_io_num_dump(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.cpp:2805
cs_gnum_t * fvm_io_num_transfer_global_num(fvm_io_num_t *this_io_num)
Definition: fvm_io_num.cpp:2676
cs_gnum_t fvm_io_num_get_global_count(const fvm_io_num_t *const this_io_num)
Definition: fvm_io_num.cpp:2719
fvm_io_num_t * fvm_io_num_destroy(fvm_io_num_t *this_io_num)
Definition: fvm_io_num.cpp:2655