programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_grid.h
Go to the documentation of this file.
1 #ifndef __CS_GRID_H__
2 #define __CS_GRID_H__
3 
4 /*============================================================================
5  * Grid connectivity and data used for multigrid coarsening
6  * and associated matrix construction.
7  *============================================================================*/
8 
9 /*
10  This file is part of Code_Saturne, a general-purpose CFD tool.
11 
12  Copyright (C) 1998-2014 EDF S.A.
13 
14  This program is free software; you can redistribute it and/or modify it under
15  the terms of the GNU General Public License as published by the Free Software
16  Foundation; either version 2 of the License, or (at your option) any later
17  version.
18 
19  This program is distributed in the hope that it will be useful, but WITHOUT
20  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
21  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
22  details.
23 
24  You should have received a copy of the GNU General Public License along with
25  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
26  Street, Fifth Floor, Boston, MA 02110-1301, USA.
27 */
28 
29 /*----------------------------------------------------------------------------*/
30 
31 /*----------------------------------------------------------------------------
32  * Local headers
33  *----------------------------------------------------------------------------*/
34 
35 #include "cs_base.h"
36 
37 #include "cs_halo.h"
38 #include "cs_matrix.h"
39 
40 /*----------------------------------------------------------------------------*/
41 
43 
44 /*============================================================================
45  * Macro definitions
46  *============================================================================*/
47 
48 /*============================================================================
49  * Type definitions
50  *============================================================================*/
51 
52 /* Structure associated with opaque grid object */
53 
54 typedef struct _cs_grid_t cs_grid_t;
55 
56 /*============================================================================
57  * Global variables
58  *============================================================================*/
59 
60 /*============================================================================
61  * Public function prototypes Fortran API
62  *============================================================================*/
63 
64 /*----------------------------------------------------------------------------
65  * Set the default parameters for multigrid coarsening.
66  *----------------------------------------------------------------------------*/
67 
68 void CS_PROCF(clmopt, CLMOPT)
69 (
70  const cs_int_t *mltmmn, /* <-- Mean number of cells under which merging
71  * should take place */
72  const cs_int_t *mltmgl, /* <-- Global number of cells under which
73  * merging should take place */
74  const cs_int_t *mltmmr, /* <-- Number of active ranks under which no
75  * merging takes place */
76  const cs_int_t *mltmst, /* <-- Number of ranks over which merging
77  * takes place */
78  const cs_int_t *mlttyp /* <-- Coarsening algorithm selection */
79 );
80 
81 /*----------------------------------------------------------------------------
82  * Print the default parameters for multigrid coarsening.
83  *----------------------------------------------------------------------------*/
84 
85 void CS_PROCF(clmimp, CLMIMP)
86 (
87  void
88 );
89 
90 /*----------------------------------------------------------------------------
91  * Order an array of real numbers by increasing value.
92  *----------------------------------------------------------------------------*/
93 
94 void CS_PROCF(clmlgo, CLMLGO)
95 (
96  const cs_int_t *nfac, /* <-- Number of internal faces */
97  const cs_real_t critr[], /* <-- Array to order */
98  cs_int_t iord[] /* <-> ordering */
99 );
100 
101 /*=============================================================================
102  * Public function prototypes
103  *============================================================================*/
104 
105 /*----------------------------------------------------------------------------
106  * Create base grid by mapping from shared mesh values.
107  *
108  * Note that as arrays given as arguments are shared by the created grid
109  * (which can only access them, not modify them), the grid should be
110  * destroyed before those arrays.
111  *
112  * parameters:
113  * n_cells <-- Local number of cells
114  * n_cells_ext <-- Local number of cells + ghost cells
115  * n_faces <-- Local number of faces
116  * symmetric <-- True if xam is symmetric, false otherwise
117  * diag_block_size <-- Block sizes for diagonal, or NULL
118  * extra_diag_block_size <-- Block sizes for extra diagonal, or NULL
119  * face_cell <-- Face -> cells connectivity (1 to n)
120  * halo <-- Halo structure associated with this level,
121  * or NULL.
122  * numbering <-- vectorization or thread-related numbering info,
123  * or NULL.
124  * cell_cen <-- Cell center (size: 3.n_cells_ext)
125  * cell_vol <-- Cell volume (size: n_cells_ext)
126  * face_normal <-- Internal face normals (size: 3.n_faces)
127  * da <-- Matrix diagonal (size: n_cell_ext)
128  * xa <-- Matrix extra-diagonal terms
129  * (size: n_faces if symmetric, 2.n_faces otherwise)
130  *
131  * returns:
132  * base grid structure
133  *----------------------------------------------------------------------------*/
134 
135 cs_grid_t *
137  cs_lnum_t n_cells_ext,
138  cs_lnum_t n_faces,
139  bool symmetric,
140  const int *diag_block_size,
141  const int *extra_diag_block_size,
142  const cs_lnum_t *face_cell,
143  const cs_halo_t *halo,
144  const cs_numbering_t *numbering,
145  const cs_real_t *cell_cen,
146  const cs_real_t *cell_vol,
147  const cs_real_t *face_normal,
148  const cs_real_t *da,
149  const cs_real_t *xa);
150 
151 /*----------------------------------------------------------------------------
152  * Destroy a grid structure.
153  *
154  * parameters:
155  * grid <-> Pointer to grid structure pointer
156  *----------------------------------------------------------------------------*/
157 
158 void
159 cs_grid_destroy(cs_grid_t **grid);
160 
161 /*----------------------------------------------------------------------------
162  * Get grid information.
163  *
164  * parameters:
165  * g <-- Grid structure
166  * level --> Level in multigrid hierarchy (or NULL)
167  * symmetric --> Symmetric matrix coefficients indicator (or NULL)
168  * db_size --> Size of the diagonal block (or NULL)
169  * eb_size --> Size of the extra diagonal block (or NULL)
170  * n_ranks --> number of ranks with data (or NULL)
171  * n_cells --> Number of local cells (or NULL)
172  * n_cells_ext --> Number of cells including ghosts (or NULL)
173  * n_faces --> Number of faces (or NULL)
174  * n_g_cells --> Number of global cells (or NULL)
175  *----------------------------------------------------------------------------*/
176 
177 void
178 cs_grid_get_info(const cs_grid_t *g,
179  int *level,
180  bool *symmetric,
181  int *db_size,
182  int *eb_size,
183  int *n_ranks,
184  cs_lnum_t *n_cells,
185  cs_lnum_t *n_cells_ext,
186  cs_lnum_t *n_faces,
187  cs_gnum_t *n_g_cells);
188 
189 /*----------------------------------------------------------------------------
190  * Get number of cells corresponding to a grid.
191  *
192  * parameters:
193  * g <-- Grid structure
194  *
195  * returns:
196  * number of cells of grid structure
197  *----------------------------------------------------------------------------*/
198 
199 cs_lnum_t
200 cs_grid_get_n_cells(const cs_grid_t *g);
201 
202 /*----------------------------------------------------------------------------
203  * Get number of extended (local + ghost) cells corresponding to a grid.
204  *
205  * parameters:
206  * g <-- Grid structure
207  *
208  * returns:
209  * number of extended cells of grid structure
210  *----------------------------------------------------------------------------*/
211 
212 cs_lnum_t
213 cs_grid_get_n_cells_ext(const cs_grid_t *g);
214 
215 /*----------------------------------------------------------------------------
216  * Get maximum number of extended (local + ghost) cells corresponding to
217  * a grid, both with and without merging between ranks
218  *
219  * parameters:
220  * g <-- Grid structure
221  *
222  * returns:
223  * maximum number of extended cells of grid structure, with or without
224  * merging
225  *----------------------------------------------------------------------------*/
226 
227 cs_lnum_t
228 cs_grid_get_n_cells_max(const cs_grid_t *g);
229 
230 /*----------------------------------------------------------------------------
231  * Get global number of cells corresponding to a grid.
232  *
233  * parameters:
234  * g <-- Grid structure
235  *
236  * returns:
237  * global number of cells of grid structure
238  *----------------------------------------------------------------------------*/
239 
240 cs_gnum_t
241 cs_grid_get_n_g_cells(const cs_grid_t *g);
242 
243 /*----------------------------------------------------------------------------
244  * Get grid's associated matrix information.
245  *
246  * parameters:
247  * g <-- Grid structure
248  *
249  * returns:
250  * pointer to matrix structure
251  *----------------------------------------------------------------------------*/
252 
253 const cs_matrix_t *
254 cs_grid_get_matrix(const cs_grid_t *g);
255 
256 #if defined(HAVE_MPI)
257 
258 /*----------------------------------------------------------------------------
259  * Get the MPI subcommunicator for a given grid.
260  *
261  * parameters:
262  * g <-- Grid structure
263  *
264  * returns:
265  * MPI communicator
266  *----------------------------------------------------------------------------*/
267 
268 MPI_Comm
269 cs_grid_get_comm(const cs_grid_t *g);
270 
271 #endif
272 
273 /*----------------------------------------------------------------------------
274  * Create coarse grid from fine grid.
275  *
276  * parameters:
277  * f <-- Fine grid structure
278  * verbosity <-- Verbosity level
279  * aggregation_limit <-- Maximum allowed fine cells per coarse cell
280  * relaxation_parameter <-- P0/P1 relaxation factor
281  *
282  * returns:
283  * coarse grid structure
284  *----------------------------------------------------------------------------*/
285 
286 cs_grid_t *
287 cs_grid_coarsen(const cs_grid_t *f,
288  int verbosity,
289  int aggregation_limit,
290  double relaxation_parameter);
291 
292 /*----------------------------------------------------------------------------
293  * Compute coarse cell variable values from fine cell values
294  *
295  * parameters:
296  * f <-- Fine grid structure
297  * c <-- Fine grid structure
298  * f_var <-- Variable defined on fine grid cells
299  * c_var --> Variable defined on coarse grid cells
300  *
301  * returns:
302  * coarse grid structure
303  *----------------------------------------------------------------------------*/
304 
305 void
306 cs_grid_restrict_cell_var(const cs_grid_t *f,
307  const cs_grid_t *c,
308  const cs_real_t *f_var,
309  cs_real_t *c_var);
310 
311 /*----------------------------------------------------------------------------
312  * Compute fine cell integer values from coarse cell values
313  *
314  * parameters:
315  * c <-- Fine grid structure
316  * f <-- Fine grid structure
317  * c_num --> Variable defined on coarse grid cells
318  * f_num <-- Variable defined on fine grid cells
319  *----------------------------------------------------------------------------*/
320 
321 void
322 cs_grid_prolong_cell_num(const cs_grid_t *c,
323  const cs_grid_t *f,
324  int *c_num,
325  int *f_num);
326 
327 /*----------------------------------------------------------------------------
328  * Compute fine cell variable values from coarse cell values
329  *
330  * parameters:
331  * c <-- Fine grid structure
332  * f <-- Fine grid structure
333  * c_var --> Variable defined on coarse grid cells
334  * f_var <-- Variable defined on fine grid cells
335  *----------------------------------------------------------------------------*/
336 
337 void
338 cs_grid_prolong_cell_var(const cs_grid_t *c,
339  const cs_grid_t *f,
340  cs_real_t *c_var,
341  cs_real_t *f_var);
342 
343 /*----------------------------------------------------------------------------
344  * Project coarse grid cell numbers to base grid.
345  *
346  * If a global coarse grid cell number is larger than max_num, its
347  * value modulo max_num is used.
348  *
349  * parameters:
350  * g <-- Grid structure
351  * n_base_cells <-- Number of cells in base grid
352  * max_num <-- Values of c_cell_num = global_num % max_num
353  * c_cell_num --> Global coarse cell number (modulo max_num)
354  *----------------------------------------------------------------------------*/
355 
356 void
357 cs_grid_project_cell_num(const cs_grid_t *g,
358  cs_lnum_t n_base_cells,
359  int max_num,
360  int c_cell_num[]);
361 
362 /*----------------------------------------------------------------------------
363  * Project coarse grid cell rank to base grid.
364  *
365  * parameters:
366  * g <-- Grid structure
367  * n_base_cells <-- Number of cells in base grid
368  * f_cell_rank --> Global coarse cell rank projected to fine cells
369  *----------------------------------------------------------------------------*/
370 
371 void
372 cs_grid_project_cell_rank(const cs_grid_t *g,
373  cs_lnum_t n_base_cells,
374  int f_cell_rank[]);
375 
376 /*----------------------------------------------------------------------------
377  * Project variable from coarse grid to base grid
378  *
379  * parameters:
380  * g <-- Grid structure
381  * n_base_cells <-- Number of cells in base grid
382  * c_var <-- Cell variable on coarse grid
383  * f_var --> Cell variable projected to fine grid
384  *----------------------------------------------------------------------------*/
385 
386 void
387 cs_grid_project_var(const cs_grid_t *g,
388  cs_lnum_t n_base_cells,
389  const cs_real_t c_var[],
390  cs_real_t f_var[]);
391 
392 /*----------------------------------------------------------------------------
393  * Compute diagonal dominance metric and project it to base grid
394  *
395  * parameters:
396  * g <-- Grid structure
397  * n_base_cells <-- Number of cells in base grid
398  * diag_dom --> Diagonal dominance metric (on fine grid)
399  *----------------------------------------------------------------------------*/
400 
401 void
402 cs_grid_project_diag_dom(const cs_grid_t *g,
403  cs_lnum_t n_base_cells,
404  cs_real_t diag_dom[]);
405 
406 /*----------------------------------------------------------------------------
407  * Get the default parameters for multigrid coarsening.
408  *
409  * parameters:
410  * merge_mean_threshold --> mean number of cells under which merging
411  * should take place, or NULL
412  * merge_glob_threshold --> global number of cells under which merging
413  * should take place, or NULL
414  * merge_min_ranks --> number of active ranks under which no merging
415  * takes place, or NULL
416  * merge_stride --> number of ranks over which merging takes place,
417  * or NULL
418  * coarsening_type --> coarsening type:
419  * 0: algebraic with natural face traversal;
420  * 1: algebraic with face traveral by criteria;
421  * 2: algebraic with Hilbert face traversal;
422  *----------------------------------------------------------------------------*/
423 
424 void
425 cs_grid_get_defaults(int *merge_mean_threshold,
426  int *merge_glob_threshold,
427  int *merge_min_ranks,
428  int *merge_stride,
429  int *coarsening_type);
430 
431 /*----------------------------------------------------------------------------
432  * Set the default parameters for multigrid coarsening.
433  *
434  * parameters:
435  * merge_mean_threshold <-- mean number of cells under which merging
436  * should take place
437  * merge_glob_threshold <-- global number of cells under which merging
438  * should take place
439  * merge_min_ranks <-- number of active ranks under which no merging
440  * takes place
441  * merge_stride <-- number of ranks over which merging takes place
442  * coarsening_type <-- coarsening type:
443  * 0: algebraic with natural face traversal;
444  * 1: algebraic with face traveral by criterai;
445  * 2: algebraic with Hilbert face traversal;
446  *----------------------------------------------------------------------------*/
447 
448 void
449 cs_grid_set_defaults(int merge_mean_threshold,
450  int merge_glob_threshold,
451  int merge_min_ranks,
452  int merge_stride,
453  int coarsening_type);
454 
455 /*----------------------------------------------------------------------------
456  * Return the merge_stride if merging is active.
457  *
458  * returns:
459  * grid merge stride if merging is active, 1 otherwise
460  *----------------------------------------------------------------------------*/
461 
462 int
464 
465 /*----------------------------------------------------------------------------
466  * Set matrix tuning behavior for multigrid coarse meshes.
467  *
468  * The finest mesh (level 0) is handled by the default tuning options,
469  * so only coarser meshes are considered here.
470  *
471  * parameters:
472  * fill_type <-- associated matrix fill type
473  * max_level <-- maximum leval for which tuning is active
474  *----------------------------------------------------------------------------*/
475 
476 void
478  int max_level);
479 
480 /*----------------------------------------------------------------------------
481  * Set matrix tuning behavior for multigrid coarse meshes.
482  *
483  * The finest mesh (level 0) is handled by the default tuning options,
484  * so only coarser meshes are considered here.
485  *
486  * parameters:
487  * fill_type <-- associated matrix fill type
488  * level <-- level for which variant is assiged
489  * mv <-- matrix variant to assign (NULL to unassign)
490  *----------------------------------------------------------------------------*/
491 
492 void
494  int level,
495  const cs_matrix_variant_t *mv);
496 
497 /*----------------------------------------------------------------------------
498  * Print the default parameters for multigrid coarsening.
499  *----------------------------------------------------------------------------*/
500 
501 void
503 
504 /*----------------------------------------------------------------------------
505  * Finalize global info related to multigrid solvers
506  *----------------------------------------------------------------------------*/
507 
508 void
509 cs_grid_finalize(void);
510 
511 /*----------------------------------------------------------------------------
512  * Dump grid structure
513  *
514  * parameters:
515  * g <-- grid structure that should be dumped
516  *----------------------------------------------------------------------------*/
517 
518 void
519 cs_grid_dump(const cs_grid_t *g);
520 
521 /*----------------------------------------------------------------------------*/
522 
524 
525 #endif /* __CS_GRID_H__ */
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:280
void cs_grid_prolong_cell_num(const cs_grid_t *c, const cs_grid_t *f, int *c_num, int *f_num)
Definition: cs_grid.c:4087
void cs_grid_prolong_cell_var(const cs_grid_t *c, const cs_grid_t *f, cs_real_t *c_var, cs_real_t *f_var)
Definition: cs_grid.c:4128
void cs_grid_project_cell_rank(const cs_grid_t *g, cs_lnum_t n_base_cells, int f_cell_rank[])
Definition: cs_grid.c:4288
cs_lnum_t cs_grid_get_n_cells(const cs_grid_t *g)
Definition: cs_grid.c:3679
struct _cs_matrix_variant_t cs_matrix_variant_t
Definition: cs_matrix.h:90
void cs_grid_destroy(cs_grid_t **grid)
Definition: cs_grid.c:3558
#define BEGIN_C_DECLS
Definition: cs_defs.h:405
int cs_int_t
Fortran-compatible integer.
Definition: cs_defs.h:295
cs_lnum_t cs_grid_get_n_cells_ext(const cs_grid_t *g)
Definition: cs_grid.c:3697
void cs_grid_get_info(const cs_grid_t *g, int *level, bool *symmetric, int *db_size, int *eb_size, int *n_ranks, cs_lnum_t *n_cells, cs_lnum_t *n_cells_ext, cs_lnum_t *n_faces, cs_gnum_t *n_g_cells)
Definition: cs_grid.c:3616
cs_grid_t * cs_grid_create_from_shared(cs_lnum_t n_cells, cs_lnum_t n_cells_ext, cs_lnum_t n_faces, bool symmetric, const int *diag_block_size, const int *extra_diag_block_size, const cs_lnum_t *face_cell, const cs_halo_t *halo, const cs_numbering_t *numbering, const cs_real_t *cell_cen, const cs_real_t *cell_vol, const cs_real_t *face_normal, const cs_real_t *da, const cs_real_t *xa)
Definition: cs_grid.c:3427
void cs_grid_dump(const cs_grid_t *g)
Definition: cs_grid.c:4766
Definition: cs_halo.h:70
void cs_grid_set_matrix_tuning(cs_matrix_fill_type_t fill_type, int max_level)
Definition: cs_grid.c:4626
void cs_grid_set_defaults(int merge_mean_threshold, int merge_glob_threshold, int merge_min_ranks, int merge_stride, int coarsening_type)
Definition: cs_grid.c:4578
void cs_grid_project_var(const cs_grid_t *g, cs_lnum_t n_base_cells, const cs_real_t c_var[], cs_real_t f_var[])
Definition: cs_grid.c:4357
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:86
cs_grid_t * cs_grid_coarsen(const cs_grid_t *f, int verbosity, int aggregation_limit, double relaxation_parameter)
Definition: cs_grid.c:3814
const cs_matrix_t * cs_grid_get_matrix(const cs_grid_t *g)
Definition: cs_grid.c:3756
void cs_grid_log_defaults(void)
Definition: cs_grid.c:4706
void cs_grid_get_defaults(int *merge_mean_threshold, int *merge_glob_threshold, int *merge_min_ranks, int *merge_stride, int *coarsening_type)
Definition: cs_grid.c:4530
void cs_grid_project_cell_num(const cs_grid_t *g, cs_lnum_t n_base_cells, int max_num, int c_cell_num[])
Definition: cs_grid.c:4203
void clmopt(const cs_int_t *mltmmn, const cs_int_t *mltmgl, const cs_int_t *mltmmr, const cs_int_t *mltmst, const cs_int_t *mlttyp)
Definition: cs_grid.c:3350
void clmimp(void)
Definition: cs_grid.c:3370
cs_lnum_t cs_grid_get_n_cells_max(const cs_grid_t *g)
Definition: cs_grid.c:3717
void cs_grid_finalize(void)
Definition: cs_grid.c:4735
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
cs_gnum_t cs_grid_get_n_g_cells(const cs_grid_t *g)
Definition: cs_grid.c:3738
void cs_grid_project_diag_dom(const cs_grid_t *g, cs_lnum_t n_base_cells, cs_real_t diag_dom[])
Definition: cs_grid.c:4429
#define END_C_DECLS
Definition: cs_defs.h:406
double cs_real_t
Definition: cs_defs.h:296
#define CS_PROCF(x, y)
Definition: cs_defs.h:419
void cs_grid_set_matrix_variant(cs_matrix_fill_type_t fill_type, int level, const cs_matrix_variant_t *mv)
Definition: cs_grid.c:4665
void clmlgo(const cs_int_t *nfac, const cs_real_t critr[], cs_int_t iord[])
Definition: cs_grid.c:3382
void cs_grid_restrict_cell_var(const cs_grid_t *f, const cs_grid_t *c, const cs_real_t *f_var, cs_real_t *c_var)
Definition: cs_grid.c:4011
int cs_grid_get_merge_stride(void)
Definition: cs_grid.c:4602
Definition: cs_numbering.h:61
cs_matrix_fill_type_t
Definition: cs_matrix.h:66