programmer's documentation
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-2016 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 /* Names for coarsening options */
61 
62 extern const char *cs_grid_coarsening_type_name[];
63 
64 /*============================================================================
65  * Semi-private function prototypes
66  *
67  * The following functions are intended to be used by the multigrid layer
68  * (cs_multigrid.c), not directly by the user, so they are no more
69  * documented than private static functions)
70  *============================================================================*/
71 
72 /*----------------------------------------------------------------------------
73  * Create base grid by mapping from shared mesh values.
74  *
75  * Note that as arrays given as arguments are shared by the created grid
76  * (which can only access them, not modify them), the grid should be
77  * destroyed before those arrays.
78  *
79  * parameters:
80  * n_cells <-- Local number of cells
81  * n_cells_ext <-- Local number of cells + ghost cells
82  * n_faces <-- Local number of faces
83  * symmetric <-- True if xam is symmetric, false otherwise
84  * diag_block_size <-- Block sizes for diagonal, or NULL
85  * extra_diag_block_size <-- Block sizes for extra diagonal, or NULL
86  * face_cell <-- Face -> cells connectivity
87  * halo <-- Halo structure associated with this level,
88  * or NULL.
89  * cell_cen <-- Cell center (size: 3.n_cells_ext)
90  * cell_vol <-- Cell volume (size: n_cells_ext)
91  * face_normal <-- Internal face normals (size: 3.n_faces)
92  * a <-- Associated matrix
93  * a_conv <-- Associated matrix (convection)
94  * a_diff <-- Associated matrix (diffusion)
95  *
96  * returns:
97  * base grid structure
98  *----------------------------------------------------------------------------*/
99 
100 cs_grid_t *
102  cs_lnum_t n_cells_ext,
103  cs_lnum_t n_faces,
104  bool symmetric,
105  const int *diag_block_size,
106  const int *extra_diag_block_size,
107  const cs_lnum_2_t *face_cell,
108  const cs_halo_t *halo,
109  const cs_real_t *cell_cen,
110  const cs_real_t *cell_vol,
111  const cs_real_t *face_normal,
112  const cs_matrix_t *a,
113  const cs_matrix_t *a_conv,
114  const cs_matrix_t *a_diff);
115 
116 /*----------------------------------------------------------------------------
117  * Destroy a grid structure.
118  *
119  * parameters:
120  * grid <-> Pointer to grid structure pointer
121  *----------------------------------------------------------------------------*/
122 
123 void
124 cs_grid_destroy(cs_grid_t **grid);
125 
126 /*----------------------------------------------------------------------------
127  * Get grid information.
128  *
129  * parameters:
130  * g <-- Grid structure
131  * level --> Level in multigrid hierarchy (or NULL)
132  * symmetric --> Symmetric matrix coefficients indicator (or NULL)
133  * db_size --> Size of the diagonal block (or NULL)
134  * eb_size --> Size of the extra diagonal block (or NULL)
135  * n_ranks --> number of ranks with data (or NULL)
136  * n_cells --> Number of local cells (or NULL)
137  * n_cells_ext --> Number of cells including ghosts (or NULL)
138  * n_faces --> Number of faces (or NULL)
139  * n_g_cells --> Number of global cells (or NULL)
140  *----------------------------------------------------------------------------*/
141 
142 void
143 cs_grid_get_info(const cs_grid_t *g,
144  int *level,
145  bool *symmetric,
146  int *db_size,
147  int *eb_size,
148  int *n_ranks,
149  cs_lnum_t *n_cells,
150  cs_lnum_t *n_cells_ext,
151  cs_lnum_t *n_faces,
152  cs_gnum_t *n_g_cells);
153 
154 /*----------------------------------------------------------------------------
155  * Get number of cells corresponding to a grid.
156  *
157  * parameters:
158  * g <-- Grid structure
159  *
160  * returns:
161  * number of cells of grid structure
162  *----------------------------------------------------------------------------*/
163 
164 cs_lnum_t
166 
167 /*----------------------------------------------------------------------------
168  * Get number of extended (local + ghost) cells corresponding to a grid.
169  *
170  * parameters:
171  * g <-- Grid structure
172  *
173  * returns:
174  * number of extended cells of grid structure
175  *----------------------------------------------------------------------------*/
176 
177 cs_lnum_t
179 
180 /*----------------------------------------------------------------------------
181  * Get maximum number of extended (local + ghost) cells corresponding to
182  * a grid, both with and without merging between ranks
183  *
184  * parameters:
185  * g <-- Grid structure
186  *
187  * returns:
188  * maximum number of extended cells of grid structure, with or without
189  * merging
190  *----------------------------------------------------------------------------*/
191 
192 cs_lnum_t
194 
195 /*----------------------------------------------------------------------------
196  * Get global number of cells corresponding to a grid.
197  *
198  * parameters:
199  * g <-- Grid structure
200  *
201  * returns:
202  * global number of cells of grid structure
203  *----------------------------------------------------------------------------*/
204 
205 cs_gnum_t
207 
208 /*----------------------------------------------------------------------------
209  * Get grid's associated matrix information.
210  *
211  * parameters:
212  * g <-- Grid structure
213  *
214  * returns:
215  * pointer to matrix structure
216  *----------------------------------------------------------------------------*/
217 
218 const cs_matrix_t *
219 cs_grid_get_matrix(const cs_grid_t *g);
220 
221 #if defined(HAVE_MPI)
222 
223 /*----------------------------------------------------------------------------
224  * Get the MPI subcommunicator for a given grid.
225  *
226  * parameters:
227  * g <-- Grid structure
228  *
229  * returns:
230  * MPI communicator
231  *----------------------------------------------------------------------------*/
232 
233 MPI_Comm
234 cs_grid_get_comm(const cs_grid_t *g);
235 
236 #endif
237 
238 /*----------------------------------------------------------------------------
239  * Create coarse grid from fine grid.
240  *
241  * parameters:
242  * f <-- Fine grid structure
243  * verbosity <-- Verbosity level
244  * coarsening_type <-- Coarsening traversal type:
245  * 0: algebraic with natural face traversal;
246  * 1: algebraic with face traveral by criteria;
247  * 2: algebraic with Hilbert face traversal
248  * aggregation_limit <-- Maximum allowed fine cells per coarse cell
249  * relaxation_parameter <-- P0/P1 relaxation factor
250  *
251  * returns:
252  * coarse grid structure
253  *----------------------------------------------------------------------------*/
254 
255 cs_grid_t *
256 cs_grid_coarsen(const cs_grid_t *f,
257  int verbosity,
258  int coarsening_type,
259  int aggregation_limit,
260  double relaxation_parameter);
261 
262 /*----------------------------------------------------------------------------
263  * Compute coarse cell variable values from fine cell values
264  *
265  * parameters:
266  * f <-- Fine grid structure
267  * c <-- Fine grid structure
268  * f_var <-- Variable defined on fine grid cells
269  * c_var --> Variable defined on coarse grid cells
270  *
271  * returns:
272  * coarse grid structure
273  *----------------------------------------------------------------------------*/
274 
275 void
277  const cs_grid_t *c,
278  const cs_real_t *f_var,
279  cs_real_t *c_var);
280 
281 /*----------------------------------------------------------------------------
282  * Compute fine cell integer values from coarse cell values
283  *
284  * parameters:
285  * c <-- Fine grid structure
286  * f <-- Fine grid structure
287  * c_num --> Variable defined on coarse grid cells
288  * f_num <-- Variable defined on fine grid cells
289  *----------------------------------------------------------------------------*/
290 
291 void
293  const cs_grid_t *f,
294  int *c_num,
295  int *f_num);
296 
297 /*----------------------------------------------------------------------------
298  * Compute fine cell variable values from coarse cell values
299  *
300  * parameters:
301  * c <-- Fine grid structure
302  * f <-- Fine grid structure
303  * c_var --> Variable defined on coarse grid cells
304  * f_var <-- Variable defined on fine grid cells
305  *----------------------------------------------------------------------------*/
306 
307 void
309  const cs_grid_t *f,
310  cs_real_t *c_var,
311  cs_real_t *f_var);
312 
313 /*----------------------------------------------------------------------------
314  * Project coarse grid cell numbers to base grid.
315  *
316  * If a global coarse grid cell number is larger than max_num, its
317  * value modulo max_num is used.
318  *
319  * parameters:
320  * g <-- Grid structure
321  * n_base_cells <-- Number of cells in base grid
322  * max_num <-- Values of c_cell_num = global_num % max_num
323  * c_cell_num --> Global coarse cell number (modulo max_num)
324  *----------------------------------------------------------------------------*/
325 
326 void
328  cs_lnum_t n_base_cells,
329  int max_num,
330  int c_cell_num[]);
331 
332 /*----------------------------------------------------------------------------
333  * Project coarse grid cell rank to base grid.
334  *
335  * parameters:
336  * g <-- Grid structure
337  * n_base_cells <-- Number of cells in base grid
338  * f_cell_rank --> Global coarse cell rank projected to fine cells
339  *----------------------------------------------------------------------------*/
340 
341 void
343  cs_lnum_t n_base_cells,
344  int f_cell_rank[]);
345 
346 /*----------------------------------------------------------------------------
347  * Project variable from coarse grid to base grid
348  *
349  * parameters:
350  * g <-- Grid structure
351  * n_base_cells <-- Number of cells in base grid
352  * c_var <-- Cell variable on coarse grid
353  * f_var --> Cell variable projected to fine grid
354  *----------------------------------------------------------------------------*/
355 
356 void
358  cs_lnum_t n_base_cells,
359  const cs_real_t c_var[],
360  cs_real_t f_var[]);
361 
362 /*----------------------------------------------------------------------------
363  * Compute diagonal dominance metric and project it to base grid
364  *
365  * parameters:
366  * g <-- Grid structure
367  * n_base_cells <-- Number of cells in base grid
368  * diag_dom --> Diagonal dominance metric (on fine grid)
369  *----------------------------------------------------------------------------*/
370 
371 void
373  cs_lnum_t n_base_cells,
374  cs_real_t diag_dom[]);
375 
376 /*----------------------------------------------------------------------------
377  * Return the merge_stride if merging is active.
378  *
379  * returns:
380  * grid merge stride if merging is active, 1 otherwise
381  *----------------------------------------------------------------------------*/
382 
383 int
385 
386 /*----------------------------------------------------------------------------
387  * Finalize global info related to multigrid solvers
388  *----------------------------------------------------------------------------*/
389 
390 void
391 cs_grid_finalize(void);
392 
393 /*----------------------------------------------------------------------------
394  * Dump grid structure
395  *
396  * parameters:
397  * g <-- grid structure that should be dumped
398  *----------------------------------------------------------------------------*/
399 
400 void
401 cs_grid_dump(const cs_grid_t *g);
402 
403 /*=============================================================================
404  * Public function prototypes
405  *============================================================================*/
406 
407 /*----------------------------------------------------------------------------
408  * Query the global multigrid parameters for parallel grid merging.
409  *
410  * parameters:
411  * rank_stride --> number of ranks over which merging
412  * takes place, or NULL
413  * cells_mean_threshold --> mean number of cells under which merging
414  * should be applied, or NULL
415  * cells_glob_threshold --> global number of cells under which merging
416  * should be applied, or NULL
417  * min_ranks --> number of active ranks under which
418  * no merging takes place, or NULL
419  *----------------------------------------------------------------------------*/
420 
421 void
422 cs_grid_get_merge_options(int *rank_stride,
423  int *cells_mean_threshold,
424  cs_gnum_t *cells_glob_threshold,
425  int *min_ranks);
426 
427 /*----------------------------------------------------------------------------
428  * Set global multigrid parameters for parallel grid merging.
429  *
430  * parameters:
431  * rank_stride <-- number of ranks over which merging
432  * takes place
433  * cells_mean_threshold <-- mean number of cells under which merging
434  * should be applied
435  * cells_glob_threshold <-- global number of cells under which merging
436  * should be applied
437  * min_ranks <-- number of active ranks under which
438  * no merging takes place
439  *----------------------------------------------------------------------------*/
440 
441 void
442 cs_grid_set_merge_options(int rank_stride,
443  int cells_mean_threshold,
444  cs_gnum_t cells_glob_threshold,
445  int min_ranks);
446 
447 /*----------------------------------------------------------------------------
448  * Set matrix tuning behavior for multigrid coarse meshes.
449  *
450  * The finest mesh (level 0) is handled by the default tuning options,
451  * so only coarser meshes are considered here.
452  *
453  * parameters:
454  * fill_type <-- associated matrix fill type
455  * max_level <-- maximum level for which tuning is active
456  *----------------------------------------------------------------------------*/
457 
458 void
460  int max_level);
461 
462 /*----------------------------------------------------------------------------
463  * Force matrix variant selection for multigrid coarse meshes.
464  *
465  * The finest mesh (level 0) is handled by the default options,
466  * so only coarser meshes are considered here.
467  *
468  * parameters:
469  * fill_type <-- associated matrix fill type
470  * level <-- level for which variant is assiged
471  * mv <-- matrix variant to assign (NULL to unassign)
472  *----------------------------------------------------------------------------*/
473 
474 void
476  int level,
477  const cs_matrix_variant_t *mv);
478 
479 /*----------------------------------------------------------------------------
480  * Log the current settings for multigrid parallel merging.
481  *----------------------------------------------------------------------------*/
482 
483 void
485 
486 /*----------------------------------------------------------------------------*/
487 
489 
490 #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)
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)
void cs_grid_project_cell_rank(const cs_grid_t *g, cs_lnum_t n_base_cells, int f_cell_rank[])
cs_lnum_t cs_grid_get_n_cells(const cs_grid_t *g)
struct _cs_matrix_variant_t cs_matrix_variant_t
Definition: cs_matrix.h:93
void cs_grid_destroy(cs_grid_t **grid)
#define BEGIN_C_DECLS
Definition: cs_defs.h:448
cs_lnum_t cs_grid_get_n_cells_ext(const cs_grid_t *g)
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)
struct _cs_grid_t cs_grid_t
Definition: cs_grid.h:54
cs_grid_t * cs_grid_coarsen(const cs_grid_t *f, int verbosity, int coarsening_type, int aggregation_limit, double relaxation_parameter)
void cs_grid_dump(const cs_grid_t *g)
Definition: cs_halo.h:70
void cs_grid_set_matrix_tuning(cs_matrix_fill_type_t fill_type, int max_level)
Set matrix tuning behavior for multigrid coarse meshes.
Definition: cs_grid.c:5289
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[])
double cs_real_t
Floating-point value.
Definition: cs_defs.h:296
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:89
const cs_matrix_t * cs_grid_get_matrix(const cs_grid_t *g)
void cs_grid_project_cell_num(const cs_grid_t *g, cs_lnum_t n_base_cells, int max_num, int c_cell_num[])
double precision, save a
Definition: cs_fuel_incl.f90:146
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_2_t *face_cell, const cs_halo_t *halo, const cs_real_t *cell_cen, const cs_real_t *cell_vol, const cs_real_t *face_normal, const cs_matrix_t *a, const cs_matrix_t *a_conv, const cs_matrix_t *a_diff)
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:302
cs_lnum_t cs_grid_get_n_cells_max(const cs_grid_t *g)
void cs_grid_get_merge_options(int *rank_stride, int *cells_mean_threshold, cs_gnum_t *cells_glob_threshold, int *min_ranks)
Query the global multigrid parameters for parallel grid merging.
Definition: cs_grid.c:5219
void cs_grid_finalize(void)
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)
void cs_grid_project_diag_dom(const cs_grid_t *g, cs_lnum_t n_base_cells, cs_real_t diag_dom[])
#define END_C_DECLS
Definition: cs_defs.h:449
void cs_grid_log_merge_options(void)
Log the current settings for multigrid parallel merging.
Definition: cs_grid.c:5372
void cs_grid_set_matrix_variant(cs_matrix_fill_type_t fill_type, int level, const cs_matrix_variant_t *mv)
Force matrix variant selection for multigrid coarse meshes.
Definition: cs_grid.c:5329
const char * cs_grid_coarsening_type_name[]
void cs_grid_set_merge_options(int rank_stride, int cells_mean_threshold, cs_gnum_t cells_glob_threshold, int min_ranks)
Set global multigrid parameters for parallel grid merging behavior.
Definition: cs_grid.c:5261
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)
int cs_grid_get_merge_stride(void)
cs_matrix_fill_type_t
Definition: cs_matrix.h:66