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