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-2015 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  * numbering <-- vectorization or thread-related numbering info,
90  * or NULL.
91  * cell_cen <-- Cell center (size: 3.n_cells_ext)
92  * cell_vol <-- Cell volume (size: n_cells_ext)
93  * face_normal <-- Internal face normals (size: 3.n_faces)
94  * a <-- Associated matrix
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_numbering_t *numbering,
110  const cs_real_t *cell_cen,
111  const cs_real_t *cell_vol,
112  const cs_real_t *face_normal,
113  const cs_matrix_t *a);
114 
115 /*----------------------------------------------------------------------------
116  * Destroy a grid structure.
117  *
118  * parameters:
119  * grid <-> Pointer to grid structure pointer
120  *----------------------------------------------------------------------------*/
121 
122 void
123 cs_grid_destroy(cs_grid_t **grid);
124 
125 /*----------------------------------------------------------------------------
126  * Get grid information.
127  *
128  * parameters:
129  * g <-- Grid structure
130  * level --> Level in multigrid hierarchy (or NULL)
131  * symmetric --> Symmetric matrix coefficients indicator (or NULL)
132  * db_size --> Size of the diagonal block (or NULL)
133  * eb_size --> Size of the extra diagonal block (or NULL)
134  * n_ranks --> number of ranks with data (or NULL)
135  * n_cells --> Number of local cells (or NULL)
136  * n_cells_ext --> Number of cells including ghosts (or NULL)
137  * n_faces --> Number of faces (or NULL)
138  * n_g_cells --> Number of global cells (or NULL)
139  *----------------------------------------------------------------------------*/
140 
141 void
142 cs_grid_get_info(const cs_grid_t *g,
143  int *level,
144  bool *symmetric,
145  int *db_size,
146  int *eb_size,
147  int *n_ranks,
148  cs_lnum_t *n_cells,
149  cs_lnum_t *n_cells_ext,
150  cs_lnum_t *n_faces,
151  cs_gnum_t *n_g_cells);
152 
153 /*----------------------------------------------------------------------------
154  * Get number of cells corresponding to a grid.
155  *
156  * parameters:
157  * g <-- Grid structure
158  *
159  * returns:
160  * number of cells of grid structure
161  *----------------------------------------------------------------------------*/
162 
163 cs_lnum_t
165 
166 /*----------------------------------------------------------------------------
167  * Get number of extended (local + ghost) cells corresponding to a grid.
168  *
169  * parameters:
170  * g <-- Grid structure
171  *
172  * returns:
173  * number of extended cells of grid structure
174  *----------------------------------------------------------------------------*/
175 
176 cs_lnum_t
178 
179 /*----------------------------------------------------------------------------
180  * Get maximum number of extended (local + ghost) cells corresponding to
181  * a grid, both with and without merging between ranks
182  *
183  * parameters:
184  * g <-- Grid structure
185  *
186  * returns:
187  * maximum number of extended cells of grid structure, with or without
188  * merging
189  *----------------------------------------------------------------------------*/
190 
191 cs_lnum_t
193 
194 /*----------------------------------------------------------------------------
195  * Get global number of cells corresponding to a grid.
196  *
197  * parameters:
198  * g <-- Grid structure
199  *
200  * returns:
201  * global number of cells of grid structure
202  *----------------------------------------------------------------------------*/
203 
204 cs_gnum_t
206 
207 /*----------------------------------------------------------------------------
208  * Get grid's associated matrix information.
209  *
210  * parameters:
211  * g <-- Grid structure
212  *
213  * returns:
214  * pointer to matrix structure
215  *----------------------------------------------------------------------------*/
216 
217 const cs_matrix_t *
218 cs_grid_get_matrix(const cs_grid_t *g);
219 
220 #if defined(HAVE_MPI)
221 
222 /*----------------------------------------------------------------------------
223  * Get the MPI subcommunicator for a given grid.
224  *
225  * parameters:
226  * g <-- Grid structure
227  *
228  * returns:
229  * MPI communicator
230  *----------------------------------------------------------------------------*/
231 
232 MPI_Comm
233 cs_grid_get_comm(const cs_grid_t *g);
234 
235 #endif
236 
237 /*----------------------------------------------------------------------------
238  * Create coarse grid from fine grid.
239  *
240  * parameters:
241  * f <-- Fine grid structure
242  * verbosity <-- Verbosity level
243  * coarsening_type <-- Coarsening traversal type:
244  * 0: algebraic with natural face traversal;
245  * 1: algebraic with face traveral by criteria;
246  * 2: algebraic with Hilbert face traversal
247  * aggregation_limit <-- Maximum allowed fine cells per coarse cell
248  * relaxation_parameter <-- P0/P1 relaxation factor
249  *
250  * returns:
251  * coarse grid structure
252  *----------------------------------------------------------------------------*/
253 
254 cs_grid_t *
255 cs_grid_coarsen(const cs_grid_t *f,
256  int verbosity,
257  int coarsening_type,
258  int aggregation_limit,
259  double relaxation_parameter);
260 
261 /*----------------------------------------------------------------------------
262  * Compute coarse cell variable values from fine cell values
263  *
264  * parameters:
265  * f <-- Fine grid structure
266  * c <-- Fine grid structure
267  * f_var <-- Variable defined on fine grid cells
268  * c_var --> Variable defined on coarse grid cells
269  *
270  * returns:
271  * coarse grid structure
272  *----------------------------------------------------------------------------*/
273 
274 void
276  const cs_grid_t *c,
277  const cs_real_t *f_var,
278  cs_real_t *c_var);
279 
280 /*----------------------------------------------------------------------------
281  * Compute fine cell integer values from coarse cell values
282  *
283  * parameters:
284  * c <-- Fine grid structure
285  * f <-- Fine grid structure
286  * c_num --> Variable defined on coarse grid cells
287  * f_num <-- Variable defined on fine grid cells
288  *----------------------------------------------------------------------------*/
289 
290 void
292  const cs_grid_t *f,
293  int *c_num,
294  int *f_num);
295 
296 /*----------------------------------------------------------------------------
297  * Compute fine cell variable values from coarse cell values
298  *
299  * parameters:
300  * c <-- Fine grid structure
301  * f <-- Fine grid structure
302  * c_var --> Variable defined on coarse grid cells
303  * f_var <-- Variable defined on fine grid cells
304  *----------------------------------------------------------------------------*/
305 
306 void
308  const cs_grid_t *f,
309  cs_real_t *c_var,
310  cs_real_t *f_var);
311 
312 /*----------------------------------------------------------------------------
313  * Project coarse grid cell numbers to base grid.
314  *
315  * If a global coarse grid cell number is larger than max_num, its
316  * value modulo max_num is used.
317  *
318  * parameters:
319  * g <-- Grid structure
320  * n_base_cells <-- Number of cells in base grid
321  * max_num <-- Values of c_cell_num = global_num % max_num
322  * c_cell_num --> Global coarse cell number (modulo max_num)
323  *----------------------------------------------------------------------------*/
324 
325 void
327  cs_lnum_t n_base_cells,
328  int max_num,
329  int c_cell_num[]);
330 
331 /*----------------------------------------------------------------------------
332  * Project coarse grid cell rank to base grid.
333  *
334  * parameters:
335  * g <-- Grid structure
336  * n_base_cells <-- Number of cells in base grid
337  * f_cell_rank --> Global coarse cell rank projected to fine cells
338  *----------------------------------------------------------------------------*/
339 
340 void
342  cs_lnum_t n_base_cells,
343  int f_cell_rank[]);
344 
345 /*----------------------------------------------------------------------------
346  * Project variable from coarse grid to base grid
347  *
348  * parameters:
349  * g <-- Grid structure
350  * n_base_cells <-- Number of cells in base grid
351  * c_var <-- Cell variable on coarse grid
352  * f_var --> Cell variable projected to fine grid
353  *----------------------------------------------------------------------------*/
354 
355 void
357  cs_lnum_t n_base_cells,
358  const cs_real_t c_var[],
359  cs_real_t f_var[]);
360 
361 /*----------------------------------------------------------------------------
362  * Compute diagonal dominance metric and project it to base grid
363  *
364  * parameters:
365  * g <-- Grid structure
366  * n_base_cells <-- Number of cells in base grid
367  * diag_dom --> Diagonal dominance metric (on fine grid)
368  *----------------------------------------------------------------------------*/
369 
370 void
372  cs_lnum_t n_base_cells,
373  cs_real_t diag_dom[]);
374 
375 /*----------------------------------------------------------------------------
376  * Return the merge_stride if merging is active.
377  *
378  * returns:
379  * grid merge stride if merging is active, 1 otherwise
380  *----------------------------------------------------------------------------*/
381 
382 int
384 
385 /*----------------------------------------------------------------------------
386  * Finalize global info related to multigrid solvers
387  *----------------------------------------------------------------------------*/
388 
389 void
390 cs_grid_finalize(void);
391 
392 /*----------------------------------------------------------------------------
393  * Dump grid structure
394  *
395  * parameters:
396  * g <-- grid structure that should be dumped
397  *----------------------------------------------------------------------------*/
398 
399 void
400 cs_grid_dump(const cs_grid_t *g);
401 
402 /*=============================================================================
403  * Public function prototypes
404  *============================================================================*/
405 
406 /*----------------------------------------------------------------------------
407  * Query the global multigrid parameters for parallel grid merging.
408  *
409  * parameters:
410  * rank_stride --> number of ranks over which merging
411  * takes place, or NULL
412  * cells_mean_threshold --> mean number of cells under which merging
413  * should be applied, or NULL
414  * cells_glob_threshold --> global number of cells under which merging
415  * should be applied, or NULL
416  * min_ranks --> number of active ranks under which
417  * no merging takes place, or NULL
418  *----------------------------------------------------------------------------*/
419 
420 void
421 cs_grid_get_merge_options(int *rank_stride,
422  int *cells_mean_threshold,
423  cs_gnum_t *cells_glob_threshold,
424  int *min_ranks);
425 
426 /*----------------------------------------------------------------------------
427  * Set global multigrid parameters for parallel grid merging.
428  *
429  * parameters:
430  * rank_stride <-- number of ranks over which merging
431  * takes place
432  * cells_mean_threshold <-- mean number of cells under which merging
433  * should be applied
434  * cells_glob_threshold <-- global number of cells under which merging
435  * should be applied
436  * min_ranks <-- number of active ranks under which
437  * no merging takes place
438  *----------------------------------------------------------------------------*/
439 
440 void
441 cs_grid_set_merge_options(int rank_stride,
442  int cells_mean_threshold,
443  cs_gnum_t cells_glob_threshold,
444  int min_ranks);
445 
446 /*----------------------------------------------------------------------------
447  * Set matrix tuning behavior for multigrid coarse meshes.
448  *
449  * The finest mesh (level 0) is handled by the default tuning options,
450  * so only coarser meshes are considered here.
451  *
452  * parameters:
453  * fill_type <-- associated matrix fill type
454  * max_level <-- maximum level for which tuning is active
455  *----------------------------------------------------------------------------*/
456 
457 void
459  int max_level);
460 
461 /*----------------------------------------------------------------------------
462  * Force matrix variant selection for multigrid coarse meshes.
463  *
464  * The finest mesh (level 0) is handled by the default options,
465  * so only coarser meshes are considered here.
466  *
467  * parameters:
468  * fill_type <-- associated matrix fill type
469  * level <-- level for which variant is assiged
470  * mv <-- matrix variant to assign (NULL to unassign)
471  *----------------------------------------------------------------------------*/
472 
473 void
475  int level,
476  const cs_matrix_variant_t *mv);
477 
478 /*----------------------------------------------------------------------------
479  * Log the current settings for multigrid parallel merging.
480  *----------------------------------------------------------------------------*/
481 
482 void
484 
485 /*----------------------------------------------------------------------------*/
486 
488 
489 #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:429
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:4763
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_numbering_t *numbering, const cs_real_t *cell_cen, const cs_real_t *cell_vol, const cs_real_t *face_normal, const cs_matrix_t *a)
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[])
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
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:301
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:4693
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:430
void cs_grid_log_merge_options(void)
Log the current settings for multigrid parallel merging.
Definition: cs_grid.c:4846
double cs_real_t
Definition: cs_defs.h:296
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:4803
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:4735
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)
Definition: cs_numbering.h:78
cs_matrix_fill_type_t
Definition: cs_matrix.h:66