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 42 BEGIN_C_DECLS 43 44 /*============================================================================ 45 * Macro definitions 46 *============================================================================*/ 47 48 /*============================================================================ 49 * Type definitions 50 *============================================================================*/ 51 52 /* Aggregation algorithm */ 53 54 typedef enum { 55 56 CS_GRID_COARSENING_DEFAULT, /*!< default among following choices */ 57 CS_GRID_COARSENING_SPD_DX, /*!< SPD, diag/extradiag ratio based */ 58 CS_GRID_COARSENING_SPD_MX, /*!< SPD, max extradiag ratio based */ 59 CS_GRID_COARSENING_SPD_PW, /*!< SPD, pairwise aggregation */ 60 CS_GRID_COARSENING_CONV_DIFF_DX /*!< convection+diffusion, 61 diag/extradiag ratio based */ 62 63 } cs_grid_coarsening_t; 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 * 109 cs_grid_create_from_shared(cs_lnum_t n_faces, 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 * 136 cs_grid_create_from_parent(const cs_matrix_t *a, 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 160 cs_grid_free_quantities(cs_grid_t *g); 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 214 cs_grid_get_n_cols_ext(const cs_grid_t *g); 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 229 cs_grid_get_n_cols_max(const cs_grid_t *g); 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 242 cs_grid_get_n_g_rows(const cs_grid_t *g); 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 * 331 cs_grid_coarsen_to_single(const cs_grid_t *f, 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 349 cs_grid_restrict_row_var(const cs_grid_t *f, 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 365 cs_grid_prolong_row_var(const cs_grid_t *c, 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 384 cs_grid_project_row_num(const cs_grid_t *g, 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 399 cs_grid_project_row_rank(const cs_grid_t *g, 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 414 cs_grid_project_var(const cs_grid_t *g, 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 429 cs_grid_project_diag_dom(const cs_grid_t *g, 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 466 cs_grid_set_matrix_tuning(cs_matrix_fill_type_t fill_type, 467 int max_level); 468 469 /*----------------------------------------------------------------------------*/ 470 471 END_C_DECLS 472 473 #endif /* __CS_GRID_H__ */ 474