7.1
general 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-2021 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 /* Aggregation algorithm */
53 
54 typedef enum {
55 
64 
65 /* Structure associated with opaque grid object */
66 
67 typedef struct _cs_grid_t cs_grid_t;
68 
69 /*============================================================================
70  * Global variables
71  *============================================================================*/
72 
73 /* Names for coarsening options */
74 
75 extern const char *cs_grid_coarsening_type_name[];
76 
77 /*============================================================================
78  * Semi-private function prototypes
79  *
80  * The following functions are intended to be used by the multigrid layer
81  * (cs_multigrid.c), not directly by the user, so they are no more
82  * documented than private static functions)
83  *============================================================================*/
84 
85 /*----------------------------------------------------------------------------
86  * Create base grid by mapping from shared mesh values.
87  *
88  * Note that as arrays given as arguments are shared by the created grid
89  * (which can only access them, not modify them), the grid should be
90  * destroyed before those arrays.
91  *
92  * parameters:
93  * n_faces <-- Local number of faces
94  * diag_block_size <-- Block sizes for diagonal, or NULL
95  * extra_diag_block_size <-- Block sizes for extra diagonal, or NULL
96  * face_cell <-- Face -> cells connectivity
97  * cell_cen <-- Cell center (size: 3.n_cells_ext)
98  * cell_vol <-- Cell volume (size: n_cells_ext)
99  * face_normal <-- Internal face normals (size: 3.n_faces)
100  * a <-- Associated matrix
101  * a_conv <-- Associated matrix (convection)
102  * a_diff <-- Associated matrix (diffusion)
103  *
104  * returns:
105  * base grid structure
106  *----------------------------------------------------------------------------*/
107 
108 cs_grid_t *
110  const cs_lnum_t *diag_block_size,
111  const cs_lnum_t *extra_diag_block_size,
112  const cs_lnum_2_t *face_cell,
113  const cs_real_t *cell_cen,
114  const cs_real_t *cell_vol,
115  const cs_real_t *face_normal,
116  const cs_matrix_t *a,
117  const cs_matrix_t *a_conv,
118  const cs_matrix_t *a_diff);
119 
120 /*----------------------------------------------------------------------------
121  * Create base grid by mapping from parent (possibly shared) matrix.
122  *
123  * Note that as arrays given as arguments are shared by the created grid
124  * (which can only access them, not modify them), the grid should be
125  * destroyed before those arrays.
126  *
127  * parameters:
128  * a <-- associated matrix
129  * n_ranks <-- number of active ranks (<= 1 to restrict to local values)
130  *
131  * returns:
132  * base grid structure
133  *----------------------------------------------------------------------------*/
134 
135 cs_grid_t *
137  int n_ranks);
138 
139 /*----------------------------------------------------------------------------
140  * Destroy a grid structure.
141  *
142  * parameters:
143  * grid <-> Pointer to grid structure pointer
144  *----------------------------------------------------------------------------*/
145 
146 void
147 cs_grid_destroy(cs_grid_t **grid);
148 
149 /*----------------------------------------------------------------------------
150  * Free a grid structure's associated quantities.
151  *
152  * The quantities required to compute a coarser grid with relaxation from a
153  * given grid are not needed after that stage, so may be freed.
154  *
155  * parameters:
156  * g <-> Pointer to grid structure
157  *----------------------------------------------------------------------------*/
158 
159 void
161 
162 /*----------------------------------------------------------------------------
163  * Get grid information.
164  *
165  * parameters:
166  * g <-- Grid structure
167  * level --> Level in multigrid hierarchy (or NULL)
168  * symmetric --> Symmetric matrix coefficients indicator (or NULL)
169  * db_size --> Size of the diagonal block (or NULL)
170  * eb_size --> Size of the extra diagonal block (or NULL)
171  * n_ranks --> number of ranks with data (or NULL)
172  * n_rows --> Number of local rows (or NULL)
173  * n_cols_ext --> Number of columns including ghosts (or NULL)
174  * n_entries --> Number of entries (or NULL)
175  * n_g_rows --> Number of global rows (or NULL)
176  *----------------------------------------------------------------------------*/
177 
178 void
179 cs_grid_get_info(const cs_grid_t *g,
180  int *level,
181  bool *symmetric,
182  cs_lnum_t *db_size,
183  cs_lnum_t *eb_size,
184  int *n_ranks,
185  cs_lnum_t *n_rows,
186  cs_lnum_t *n_cols_ext,
187  cs_lnum_t *n_entries,
188  cs_gnum_t *n_g_rows);
189 
190 /*----------------------------------------------------------------------------
191  * Get number of rows corresponding to a grid.
192  *
193  * parameters:
194  * g <-- Grid structure
195  *
196  * returns:
197  * number of rows of grid structure
198  *----------------------------------------------------------------------------*/
199 
200 cs_lnum_t
201 cs_grid_get_n_rows(const cs_grid_t *g);
202 
203 /*----------------------------------------------------------------------------
204  * Get number of extended (local + ghost) columns corresponding to a grid.
205  *
206  * parameters:
207  * g <-- Grid structure
208  *
209  * returns:
210  * number of extended columns of grid structure
211  *----------------------------------------------------------------------------*/
212 
213 cs_lnum_t
215 
216 /*----------------------------------------------------------------------------
217  * Get maximum number of extended (local + ghost) columns corresponding to
218  * a grid, both with and without merging between ranks
219  *
220  * parameters:
221  * g <-- Grid structure
222  *
223  * returns:
224  * maximum number of extended columns of grid structure, with or without
225  * merging
226  *----------------------------------------------------------------------------*/
227 
228 cs_lnum_t
230 
231 /*----------------------------------------------------------------------------
232  * Get global number of rows corresponding to a grid.
233  *
234  * parameters:
235  * g <-- Grid structure
236  *
237  * returns:
238  * global number of rows of grid structure
239  *----------------------------------------------------------------------------*/
240 
241 cs_gnum_t
243 
244 /*----------------------------------------------------------------------------
245  * Get grid's associated matrix information.
246  *
247  * parameters:
248  * g <-- Grid structure
249  *
250  * returns:
251  * pointer to matrix structure
252  *----------------------------------------------------------------------------*/
253 
254 const cs_matrix_t *
255 cs_grid_get_matrix(const cs_grid_t *g);
256 
257 #if defined(HAVE_MPI)
258 
259 /*----------------------------------------------------------------------------
260  * Get the MPI subcommunicator for a given grid.
261  *
262  * parameters:
263  * g <-- Grid structure
264  *
265  * returns:
266  * MPI communicator
267  *----------------------------------------------------------------------------*/
268 
269 MPI_Comm
270 cs_grid_get_comm(const cs_grid_t *g);
271 
272 /*----------------------------------------------------------------------------
273  * Get the MPI subcommunicator for a given merge stride.
274  *
275  * parameters:
276  * parent <-- parent MPI communicator
277  * merge_stride <-- associated merge stride
278  *
279  * returns:
280  * MPI communicator
281  *----------------------------------------------------------------------------*/
282 
283 MPI_Comm
284 cs_grid_get_comm_merge(MPI_Comm parent,
285  int merge_stride);
286 
287 #endif
288 
289 /*----------------------------------------------------------------------------
290  * Create coarse grid from fine grid.
291  *
292  * parameters:
293  * f <-- Fine grid structure
294  * coarsening_type <-- Coarsening criteria type
295  * aggregation_limit <-- Maximum allowed fine rows per coarse rows
296  * verbosity <-- Verbosity level
297  * merge_stride <-- Associated merge stride
298  * merge_rows_mean_threshold <-- mean number of rows under which
299  * merging should be applied
300  * merge_rows_glob_threshold <-- global number of rows under which
301  * merging should be applied
302  * relaxation_parameter <-- P0/P1 relaxation factor
303  *
304  * returns:
305  * coarse grid structure
306  *----------------------------------------------------------------------------*/
307 
308 cs_grid_t *
309 cs_grid_coarsen(const cs_grid_t *f,
310  int coarsening_type,
311  int aggregation_limit,
312  int verbosity,
313  int merge_stride,
314  int merge_rows_mean_threshold,
315  cs_gnum_t merge_rows_glob_threshold,
316  double relaxation_parameter);
317 
318 /*----------------------------------------------------------------------------
319  * Create coarse grid with only one row per rank from fine grid.
320  *
321  * parameters:
322  * f <-- Fine grid structure
323  * merge_stride <-- Associated merge stride
324  * verbosity <-- Verbosity level
325  *
326  * returns:
327  * coarse grid structure
328  *----------------------------------------------------------------------------*/
329 
330 cs_grid_t *
332  int merge_stride,
333  int verbosity);
334 
335 /*----------------------------------------------------------------------------
336  * Compute coarse row variable values from fine row values
337  *
338  * parameters:
339  * f <-- Fine grid structure
340  * c <-- Fine grid structure
341  * f_var <-- Variable defined on fine grid rows
342  * c_var --> Variable defined on coarse grid rows
343  *
344  * returns:
345  * coarse grid structure
346  *----------------------------------------------------------------------------*/
347 
348 void
350  const cs_grid_t *c,
351  const cs_real_t *f_var,
352  cs_real_t *c_var);
353 
354 /*----------------------------------------------------------------------------
355  * Compute fine row variable values from coarse row values
356  *
357  * parameters:
358  * c <-- Fine grid structure
359  * f <-- Fine grid structure
360  * c_var --> Variable defined on coarse grid rows
361  * f_var <-- Variable defined on fine grid rows
362  *----------------------------------------------------------------------------*/
363 
364 void
366  const cs_grid_t *f,
367  cs_real_t *c_var,
368  cs_real_t *f_var);
369 
370 /*----------------------------------------------------------------------------
371  * Project coarse grid row numbers to base grid.
372  *
373  * If a global coarse grid row number is larger than max_num, its
374  * value modulo max_num is used.
375  *
376  * parameters:
377  * g <-- Grid structure
378  * n_base_rows <-- Number of rows in base grid
379  * max_num <-- Values of c_row_num = global_num % max_num
380  * c_row_num --> Global coarse row number (modulo max_num)
381  *----------------------------------------------------------------------------*/
382 
383 void
385  cs_lnum_t n_base_rows,
386  int max_num,
387  int c_row_num[]);
388 
389 /*----------------------------------------------------------------------------
390  * Project coarse grid row rank to base grid.
391  *
392  * parameters:
393  * g <-- Grid structure
394  * n_base_rows <-- Number of rows in base grid
395  * f_row_rank --> Global coarse row rank projected to fine rows
396  *----------------------------------------------------------------------------*/
397 
398 void
400  cs_lnum_t n_base_rows,
401  int f_row_rank[]);
402 
403 /*----------------------------------------------------------------------------
404  * Project variable from coarse grid to base grid
405  *
406  * parameters:
407  * g <-- Grid structure
408  * n_base_rows <-- Number of rows in base grid
409  * c_var <-- Row variable on coarse grid
410  * f_var --> Row variable projected to fine grid
411  *----------------------------------------------------------------------------*/
412 
413 void
415  cs_lnum_t n_base_rows,
416  const cs_real_t c_var[],
417  cs_real_t f_var[]);
418 
419 /*----------------------------------------------------------------------------
420  * Compute diagonal dominance metric and project it to base grid
421  *
422  * parameters:
423  * g <-- Grid structure
424  * n_base_rows <-- Number of rows in base grid
425  * diag_dom --> Diagonal dominance metric (on fine grid)
426  *----------------------------------------------------------------------------*/
427 
428 void
430  cs_lnum_t n_base_rows,
431  cs_real_t diag_dom[]);
432 
433 /*----------------------------------------------------------------------------
434  * Finalize global info related to multigrid solvers
435  *----------------------------------------------------------------------------*/
436 
437 void
438 cs_grid_finalize(void);
439 
440 /*----------------------------------------------------------------------------
441  * Dump grid structure
442  *
443  * parameters:
444  * g <-- grid structure that should be dumped
445  *----------------------------------------------------------------------------*/
446 
447 void
448 cs_grid_dump(const cs_grid_t *g);
449 
450 /*=============================================================================
451  * Public function prototypes
452  *============================================================================*/
453 
454 /*----------------------------------------------------------------------------
455  * Set matrix tuning behavior for multigrid coarse meshes.
456  *
457  * The finest mesh (level 0) is handled by the default tuning options,
458  * so only coarser meshes are considered here.
459  *
460  * parameters:
461  * fill_type <-- associated matrix fill type
462  * max_level <-- maximum level for which tuning is active
463  *----------------------------------------------------------------------------*/
464 
465 void
467  int max_level);
468 
469 /*----------------------------------------------------------------------------*/
470 
472 
473 #endif /* __CS_GRID_H__ */
Definition: cs_grid.h:59
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:301
void cs_grid_restrict_row_var(const cs_grid_t *f, const cs_grid_t *c, const cs_real_t *f_var, cs_real_t *c_var)
cs_grid_coarsening_t
Definition: cs_grid.h:54
void cs_grid_destroy(cs_grid_t **grid)
#define BEGIN_C_DECLS
Definition: cs_defs.h:510
cs_grid_t * cs_grid_coarsen_to_single(const cs_grid_t *f, int merge_stride, int verbosity)
struct _cs_grid_t cs_grid_t
Definition: cs_grid.h:67
void cs_grid_dump(const cs_grid_t *g)
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:6633
cs_lnum_t cs_grid_get_n_rows(const cs_grid_t *g)
double cs_real_t
Floating-point value.
Definition: cs_defs.h:322
void cs_grid_prolong_row_var(const cs_grid_t *c, const cs_grid_t *f, cs_real_t *c_var, cs_real_t *f_var)
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:93
const cs_matrix_t * cs_grid_get_matrix(const cs_grid_t *g)
void cs_grid_project_var(const cs_grid_t *g, cs_lnum_t n_base_rows, const cs_real_t c_var[], cs_real_t f_var[])
void cs_grid_project_diag_dom(const cs_grid_t *g, cs_lnum_t n_base_rows, cs_real_t diag_dom[])
double precision, save a
Definition: cs_fuel_incl.f90:146
Definition: cs_grid.h:58
cs_lnum_t cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:328
Definition: cs_grid.h:56
void cs_grid_finalize(void)
void cs_grid_get_info(const cs_grid_t *g, int *level, bool *symmetric, cs_lnum_t *db_size, cs_lnum_t *eb_size, int *n_ranks, cs_lnum_t *n_rows, cs_lnum_t *n_cols_ext, cs_lnum_t *n_entries, cs_gnum_t *n_g_rows)
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:316
cs_gnum_t cs_grid_get_n_g_rows(const cs_grid_t *g)
cs_grid_t * cs_grid_create_from_parent(const cs_matrix_t *a, int n_ranks)
cs_lnum_t cs_grid_get_n_cols_max(const cs_grid_t *g)
cs_grid_t * cs_grid_create_from_shared(cs_lnum_t n_faces, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size, const cs_lnum_2_t *face_cell, 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)
#define END_C_DECLS
Definition: cs_defs.h:511
void cs_grid_project_row_num(const cs_grid_t *g, cs_lnum_t n_base_rows, int max_num, int c_row_num[])
cs_lnum_t cs_grid_get_n_cols_ext(const cs_grid_t *g)
cs_grid_t * cs_grid_coarsen(const cs_grid_t *f, int coarsening_type, int aggregation_limit, int verbosity, int merge_stride, int merge_rows_mean_threshold, cs_gnum_t merge_rows_glob_threshold, double relaxation_parameter)
void cs_grid_project_row_rank(const cs_grid_t *g, cs_lnum_t n_base_rows, int f_row_rank[])
const char * cs_grid_coarsening_type_name[]
Definition: cs_grid.h:57
void cs_grid_free_quantities(cs_grid_t *g)
Definition: cs_grid.h:60
cs_matrix_fill_type_t
Definition: cs_matrix.h:70