8.0
general documentation
cs_join_set.h
Go to the documentation of this file.
1 #ifndef __CS_JOIN_SET_H__
2 #define __CS_JOIN_SET_H__
3 
4 /*============================================================================
5  * Subroutines useful to manage list structures
6  *===========================================================================*/
7 
8 /*
9  This file is part of code_saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2023 EDF S.A.
12 
13  This program is free software; you can redistribute it and/or modify it under
14  the terms of the GNU General Public License as published by the Free Software
15  Foundation; either version 2 of the License, or (at your option) any later
16  version.
17 
18  This program is distributed in the hope that it will be useful, but WITHOUT
19  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21  details.
22 
23  You should have received a copy of the GNU General Public License along with
24  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25  Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27 
28 /*----------------------------------------------------------------------------*/
29 
30 /*----------------------------------------------------------------------------
31  * Standard C library headers
32  *---------------------------------------------------------------------------*/
33 
34 #include <stdio.h>
35 
36 /*----------------------------------------------------------------------------
37  * Local headers
38  *---------------------------------------------------------------------------*/
39 
40 #include "cs_base.h"
41 
42 /*---------------------------------------------------------------------------*/
43 
45 
46 /*============================================================================
47  * Macro and type definitions
48  *===========================================================================*/
49 
52 typedef struct { /* Definition of a global indexed list of global elements */
53 
54  cs_lnum_t n_elts;
55  cs_gnum_t n_g_elts;
56 
57  cs_gnum_t *g_elts; /* Global numbering of elements */
58 
59  cs_lnum_t *index; /* Index on elements from */
60  cs_gnum_t *g_list; /* Global numbering of entities linked with g_elts */
61 
62 } cs_join_gset_t;
63 
64 typedef struct { /* Resizable array structure */
65 
66  cs_lnum_t n_max_elts;
67  cs_lnum_t n_elts;
68  cs_lnum_t *array;
69 
70 } cs_join_rset_t;
71 
72 /* ------------------------------------------------------------------ *
73  * Definition of a structure defining a set of equivalence between
74  * vertices for instance
75  * ------------------------------------------------------------------ */
76 
77 typedef struct {
78 
79  cs_lnum_t n_max_equiv; /* max. number of equiv. allocated */
80  cs_lnum_t n_equiv; /* number of equivalences */
81  cs_lnum_t *equiv_couple; /* ids of the two equivalent entities.
82  size = 2 * n_equiv */
83 } cs_join_eset_t;
84 
87 /*============================================================================
88  * Public function prototypes
89  *===========================================================================*/
90 
91 /*----------------------------------------------------------------------------
92  * Allocate a resizable array.
93  *
94  * parameters:
95  * max_size <-- initial number of elements to allocate
96  *
97  * returns:
98  * pointer to a new alloacted resizable array
99  *---------------------------------------------------------------------------*/
100 
101 cs_join_rset_t *
103 
104 /*----------------------------------------------------------------------------
105  * Destroy a cs_join_rset_t structure.
106  *
107  * parameter:
108  * set <-- pointer to pointer to the cs_join_rset_t structure to destroy
109  *---------------------------------------------------------------------------*/
110 
111 void
112 cs_join_rset_destroy(cs_join_rset_t **set);
113 
114 /*----------------------------------------------------------------------------
115  * Check if we need to resize the current cs_join_rset_t structure and do
116  * it if necessary.
117  *
118  * parameters:
119  * set <-- pointer to pointer to the cs_join_rset_t structure to test
120  * test_size <-- target size
121  *---------------------------------------------------------------------------*/
122 
123 void
124 cs_join_rset_resize(cs_join_rset_t **set,
125  cs_lnum_t test_size);
126 
127 /*----------------------------------------------------------------------------
128  * Create a new cs_join_eset_t structure.
129  *
130  * parameters:
131  * init_size <-- number of initial equivalences to allocate
132  *
133  * returns:
134  * a pointer to a new cs_join_eset_t structure
135  *---------------------------------------------------------------------------*/
136 
137 cs_join_eset_t *
138 cs_join_eset_create(cs_lnum_t init_size);
139 
140 /*----------------------------------------------------------------------------
141  * Check if the requested size if allocated in the structure.
142  *
143  * Reallocate cs_join_eset_t structure if necessary.
144  *
145  * parameters:
146  * request_size <-- necessary size
147  * equiv_set <-> pointer to pointer to the cs_join_eset_t struct.
148  *---------------------------------------------------------------------------*/
149 
150 void
152  cs_join_eset_t **equiv_set);
153 
154 /*----------------------------------------------------------------------------
155  * Destroy a cs_join_eset_t structure.
156  *
157  * parameter:
158  * equiv_set <-- pointer to pointer to the structure to destroy
159  *---------------------------------------------------------------------------*/
160 
161 void
162 cs_join_eset_destroy(cs_join_eset_t **equiv_set);
163 
164 /*----------------------------------------------------------------------------
165  * Clean a cs_join_eset_t structure.
166  *
167  * If necessary, create a new cs_join_eset_t structure with no redundancy.
168  *
169  * parameters:
170  * eset <-- pointer to pointer to the cs_join_eset_t structure to clean
171  *---------------------------------------------------------------------------*/
172 
173 void
174 cs_join_eset_clean(cs_join_eset_t **eset);
175 
176 /*----------------------------------------------------------------------------
177  * Create a cs_join_gset_t structure (indexed list on global numbering)
178  *
179  * parameters:
180  * n_elts <-- number of elements composing the list
181  *
182  * returns:
183  * a new allocated pointer to a cs_join_gset_t structure.
184  *---------------------------------------------------------------------------*/
185 
186 cs_join_gset_t *
188 
189 /*----------------------------------------------------------------------------
190  * Build a cs_join_gset_t structure to store all the potential groups
191  * between elements.
192  *
193  * Values in g_elts are the tag values and values in g_list
194  * are position in tag array.
195  *
196  * parameters:
197  * n_elts <-- number of elements in tag array
198  * tag <-- tag array used to define a new cs_join_gset_t
199  *
200  * returns:
201  * a new allocated cs_join_gset_t structure
202  *---------------------------------------------------------------------------*/
203 
204 cs_join_gset_t *
206  const cs_gnum_t tag[]);
207 
208 /*----------------------------------------------------------------------------
209  * Create a new cs_join_gset_t which holds equivalences between elements of
210  * g_list in cs_join_gset_t.
211  *
212  * For a subset of equivalences, we store their initial value in the return
213  * cs_join_gset_t structure. A subset is defined if at least two elements
214  * are equivalent.
215  *
216  * The behavior of this function is near from cs_join_gset_create_from_tag
217  * but we don't store the position in init_array but its value in init_array.
218  *
219  * parameters:
220  * set <-- pointer to a cs_join_gset_t structure
221  * init_array <-- initial values of set->g_list
222  *
223  * returns:
224  * a new allocated cs_join_gset_t structure, or NULL if it would be empty
225  *---------------------------------------------------------------------------*/
226 
227 cs_join_gset_t *
228 cs_join_gset_create_by_equiv(const cs_join_gset_t *set,
229  const cs_gnum_t init_array[]);
230 
231 /*----------------------------------------------------------------------------
232  * Copy a cs_join_gset_t structure.
233  *
234  * parameters:
235  * src <-- pointer to the cs_join_gset_t structure to copy
236  *
237  * returns:
238  * a new allocated cs_join_gset_t structure.
239  *---------------------------------------------------------------------------*/
240 
241 cs_join_gset_t *
242 cs_join_gset_copy(const cs_join_gset_t *src);
243 
244 /*----------------------------------------------------------------------------
245  * Destroy a cs_join_gset_t structure.
246  *
247  * parameters:
248  * set <-- pointer to pointer to the cs_join_gset_t structure to destroy
249  *---------------------------------------------------------------------------*/
250 
251 void
252 cs_join_gset_destroy(cs_join_gset_t **set);
253 
254 /*----------------------------------------------------------------------------
255  * Sort a cs_join_gset_t structure according to the global numbering of
256  * the g_elts in cs_join_gset_t structure.
257  *
258  * parameters:
259  * set <-> pointer to the structure to order
260  *---------------------------------------------------------------------------*/
261 
262 void
263 cs_join_gset_sort_elts(cs_join_gset_t *set);
264 
265 /*----------------------------------------------------------------------------
266  * Sort each sub-list of the g_list array in a cs_join_gset_t structure.
267  *
268  * parameters:
269  * p_set <-> pointer to the structure to sort
270  *---------------------------------------------------------------------------*/
271 
272 void
273 cs_join_gset_sort_sublist(cs_join_gset_t *set);
274 
275 /*----------------------------------------------------------------------------
276  * Invert a cs_join_gset_t structure.
277  *
278  * parameters:
279  * set <-- pointer to the cs_join_gset_t structure to work with
280  *
281  * returns:
282  * the new allocated and inverted set structure
283  *---------------------------------------------------------------------------*/
284 
285 cs_join_gset_t *
286 cs_join_gset_invert(const cs_join_gset_t *set);
287 
288 /*----------------------------------------------------------------------------
289  * Delete redudancies in a cs_join_gset_t structure.
290  *
291  * The output set has an ordered sub-list for each element in the set.
292  *
293  * parameters:
294  * set <-> pointer to the structure to clean
295  *---------------------------------------------------------------------------*/
296 
297 void
298 cs_join_gset_clean(cs_join_gset_t *set);
299 
300 /*----------------------------------------------------------------------------
301  * Delete redudancies in g_list array of a cs_join_gset_t structure.
302  *
303  * parameters:
304  * set <-> pointer to the structure to clean
305  * linked_array <-> array for which redundancies are scanned
306  *---------------------------------------------------------------------------*/
307 
308 void
309 cs_join_gset_clean_from_array(cs_join_gset_t *set,
310  cs_gnum_t linked_array[]);
311 
312 /*----------------------------------------------------------------------------
313  * Concatenate the two g_elts and g_list arrays.
314  *
315  * Order the new concatenated array and delete redundant elements.
316  * We get a single ordered array.
317  *
318  * parameters:
319  * set <-- pointer to the structure to work with
320  * n_elts --> number of elements in the new set
321  * new_array --> pointer to the new created array
322  *---------------------------------------------------------------------------*/
323 
324 void
325 cs_join_gset_single_order(const cs_join_gset_t *set,
326  cs_lnum_t *n_elts,
327  cs_gnum_t *new_array[]);
328 
329 /*----------------------------------------------------------------------------
330  * Compress a g_list such as for each element "e" in g_elts:
331  * - there is no redundancy for the linked elements of set->g_list
332  * - there is no element in set->g_list < e except if this element is not
333  * present in g_elts
334  *
335  * g_list and g_elts need to be ordered before calling this function.
336  *
337  * parameters:
338  * set <-> pointer to the structure to work with
339  *---------------------------------------------------------------------------*/
340 
341 void
342 cs_join_gset_compress(cs_join_gset_t *set);
343 
344 /*----------------------------------------------------------------------------
345  * Delete redundancies in set->g_elts.
346  *
347  * Merge sub-arrays associated to a common set->g_elts[i].
348  *
349  * parameters:
350  * set <-- pointer to the structure to work with
351  * order_tag <-- 0: set->g_elts is not ordered, 1: ordered
352  *---------------------------------------------------------------------------*/
353 
354 void
355 cs_join_gset_merge_elts(cs_join_gset_t *set,
356  int order_tag);
357 
358 #if defined(HAVE_MPI)
359 
360 /*----------------------------------------------------------------------------
361  * Synchronize a cs_join_gset_t structure and distribute the resulting set
362  * over the rank by block
363  *
364  * parameters:
365  * max_gnum <-- max global number in global element numbering
366  * loc_set <-> pointer to the local structure to work with
367  * comm <-- mpi_comm on which synchro. and distribution take place
368  *
369  * returns:
370  * a synchronized and distributed cs_join_gset_t structure.
371  *---------------------------------------------------------------------------*/
372 
373 cs_join_gset_t *
374 cs_join_gset_block_sync(cs_gnum_t max_gnum,
375  cs_join_gset_t *loc_set,
376  MPI_Comm comm);
377 
378 /*----------------------------------------------------------------------------
379  * Update a local cs_join_gset_t structure from a distributed and
380  * synchronized cs_join_gset_t structure.
381  *
382  * loc_set should not have redundant elements.
383  *
384  * parameters:
385  * max_gnum <-- max global number in global element numbering
386  * sync_set <-- pointer to the structure which holds a synchronized block
387  * loc_set <-> pointer to a local structure holding elements to update
388  * comm <-- comm on which synchronization and distribution take place
389  *---------------------------------------------------------------------------*/
390 
391 void
392 cs_join_gset_block_update(cs_gnum_t max_gnum,
393  const cs_join_gset_t *sync_set,
394  cs_join_gset_t *loc_set,
395  MPI_Comm comm);
396 
397 #endif /* HAVE_MPI */
398 
399 /*----------------------------------------------------------------------------
400  * Dump an array (int or double).
401  *
402  * This function is called according to the verbosity.
403  *
404  * parameters:
405  * f <-- handle to output file
406  * type <-- type of the array to display
407  * header <-- header to display in front of the array
408  * n_elts <-- number of elements to display
409  * array <-- array to display
410  *---------------------------------------------------------------------------*/
411 
412 void
413 cs_join_dump_array(FILE *f,
414  const char *type,
415  const char *header,
416  int n_elts,
417  const void *array);
418 
419 /*----------------------------------------------------------------------------
420  * Dump a cs_join_gset_t structure.
421  *
422  * parameters:
423  * f <-- handle to output file
424  * set <-- pointer to the cs_join_gset_t structure to dump
425  *---------------------------------------------------------------------------*/
426 
427 void
428 cs_join_gset_dump(FILE *f,
429  const cs_join_gset_t *set);
430 
431 /*---------------------------------------------------------------------------*/
432 
434 
435 #endif /* __CS_JOIN_SET_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:509
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:298
#define END_C_DECLS
Definition: cs_defs.h:510
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:313
void cs_join_rset_resize(cs_join_rset_t **set, cs_lnum_t test_size)
Definition: cs_join_set.c:326
cs_join_gset_t * cs_join_gset_create_by_equiv(const cs_join_gset_t *set, const cs_gnum_t init_array[])
Definition: cs_join_set.c:728
cs_join_gset_t * cs_join_gset_copy(const cs_join_gset_t *src)
Definition: cs_join_set.c:879
void cs_join_gset_sort_elts(cs_join_gset_t *set)
Definition: cs_join_set.c:931
cs_join_eset_t * cs_join_eset_create(cs_lnum_t init_size)
Definition: cs_join_set.c:366
void cs_join_gset_single_order(const cs_join_gset_t *set, cs_lnum_t *n_elts, cs_gnum_t *new_array[])
Definition: cs_join_set.c:1295
void cs_join_gset_sort_sublist(cs_join_gset_t *set)
Definition: cs_join_set.c:1010
void cs_join_rset_destroy(cs_join_rset_t **set)
Definition: cs_join_set.c:308
void cs_join_dump_array(FILE *f, const char *type, const char *header, int n_elts, const void *array)
Definition: cs_join_set.c:1822
void cs_join_eset_check_size(cs_lnum_t request_size, cs_join_eset_t **equiv_set)
Definition: cs_join_set.c:391
void cs_join_eset_destroy(cs_join_eset_t **equiv_set)
Definition: cs_join_set.c:425
cs_join_gset_t * cs_join_gset_invert(const cs_join_gset_t *set)
Definition: cs_join_set.c:1034
cs_join_gset_t * cs_join_gset_create_from_tag(cs_lnum_t n_elts, const cs_gnum_t tag[])
Definition: cs_join_set.c:593
cs_join_gset_t * cs_join_gset_create(cs_lnum_t n_elts)
Definition: cs_join_set.c:553
void cs_join_gset_compress(cs_join_gset_t *set)
Definition: cs_join_set.c:1384
void cs_join_gset_destroy(cs_join_gset_t **set)
Definition: cs_join_set.c:912
cs_join_rset_t * cs_join_rset_create(cs_lnum_t max_size)
Definition: cs_join_set.c:282
void cs_join_gset_merge_elts(cs_join_gset_t *set, int order_tag)
Definition: cs_join_set.c:1470
void cs_join_gset_dump(FILE *f, const cs_join_gset_t *set)
Definition: cs_join_set.c:1885
void cs_join_gset_clean_from_array(cs_join_gset_t *set, cs_gnum_t linked_array[])
Definition: cs_join_set.c:1211
void cs_join_gset_clean(cs_join_gset_t *set)
Definition: cs_join_set.c:1160
void cs_join_eset_clean(cs_join_eset_t **eset)
Definition: cs_join_set.c:443