1 #ifndef __CS_MATRIX_H__ 2 #define __CS_MATRIX_H__ 3 4 /*============================================================================ 5 * Sparse Matrix Representation and Operations 6 *============================================================================*/ 7 8 /* 9 This file is part of Code_Saturne, a general-purpose CFD tool. 10 11 Copyright (C) 1998-2021 EDF S.A. 12 13 This program is free software; you can redistribute it and/or modify it under 14 the terms of the GNU General Public License as published by the Free Software 15 Foundation; either version 2 of the License, or (at your option) any later 16 version. 17 18 This program is distributed in the hope that it will be useful, but WITHOUT 19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 21 details. 22 23 You should have received a copy of the GNU General Public License along with 24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin 25 Street, Fifth Floor, Boston, MA 02110-1301, USA. 26 */ 27 28 /*----------------------------------------------------------------------------*/ 29 30 /*---------------------------------------------------------------------------- 31 * Local headers 32 *----------------------------------------------------------------------------*/ 33 34 #include "cs_defs.h" 35 36 #include "cs_halo.h" 37 #include "cs_numbering.h" 38 #include "cs_halo_perio.h" 39 #include "cs_matrix_assembler.h" 40 41 /*----------------------------------------------------------------------------*/ 42 43 BEGIN_C_DECLS 44 45 /*============================================================================ 46 * Macro definitions 47 *============================================================================*/ 48 49 /*============================================================================ 50 * Type definitions 51 *============================================================================*/ 52 53 /* Matrix structure representation types */ 54 55 typedef enum { 56 57 CS_MATRIX_NATIVE, /*!< Native (edge-based) matrix storage */ 58 CS_MATRIX_CSR, /*!< Compressed Sparse Row storage */ 59 CS_MATRIX_MSR, /*!< Modified Compressed Sparse Row storage 60 (separate diagonal) */ 61 62 CS_MATRIX_N_BUILTIN_TYPES, /*!< Number of known and built-in matrix types */ 63 64 CS_MATRIX_N_TYPES /*!< Number of known matrix types */ 65 66 } cs_matrix_type_t; 67 68 /* Matrix fill types (for tuning) */ 69 70 typedef enum { 71 72 CS_MATRIX_SCALAR, /* Simple scalar matrix */ 73 CS_MATRIX_SCALAR_SYM, /* Simple scalar symmetric matrix */ 74 CS_MATRIX_BLOCK_D, /* Matrix with diagonal blocks 75 (and m.I extradiagonal blocks) */ 76 CS_MATRIX_BLOCK_D_66, /* Matrix with 6x6 diagonal blocks 77 (and 6.I extradiagonal blocks; 78 subcase of CS_MATRIX_BLOCK_D, allows 79 separate tuning) */ 80 CS_MATRIX_BLOCK_D_SYM, /* Symmetric matrix with diagonal blocks 81 (and m.I extradiagonal blocks) */ 82 CS_MATRIX_BLOCK, /* Block matrix */ 83 CS_MATRIX_N_FILL_TYPES /* Number of possible matrix fill types */ 84 85 } cs_matrix_fill_type_t; 86 87 /* Structure associated with opaque matrix structure object */ 88 89 typedef struct _cs_matrix_structure_t cs_matrix_structure_t; 90 91 /* Structure associated with opaque matrix object */ 92 93 typedef struct _cs_matrix_t cs_matrix_t; 94 95 /* Structure associated with opaque matrix tuning results object */ 96 97 typedef struct _cs_matrix_variant_t cs_matrix_variant_t; 98 99 /* Information structure for extraction of matrix row */ 100 101 typedef struct { 102 103 cs_lnum_t row_size; /*< Row size from last call */ 104 cs_lnum_t buffer_size; /*< Allocated buffer size */ 105 const cs_lnum_t *col_id; /*< Pointer to local column ids */ 106 cs_lnum_t *_col_id; /*< Pointer to local column ids copy */ 107 const cs_real_t *vals; /*< Pointer to local row values */ 108 cs_real_t *_vals; /*< Pointer to local row values copy */ 109 110 } cs_matrix_row_info_t; 111 112 /*============================================================================ 113 * Global variables 114 *============================================================================*/ 115 116 /* Fill type names for matrices */ 117 118 extern const char *cs_matrix_fill_type_name[]; 119 120 /*============================================================================= 121 * Public function prototypes 122 *============================================================================*/ 123 124 /*---------------------------------------------------------------------------- 125 * Create a matrix structure. 126 * 127 * Note that the structure created usually maps to the given existing 128 * cell global number, face -> cell connectivity arrays, and cell halo 129 * structure, so it must be destroyed before they are freed 130 * (usually along with the code's main face -> cell structure). 131 * 132 * Note that the resulting matrix structure will contain either a full or 133 * an empty main diagonal, and that the extra-diagonal structure is always 134 * symmetric (though the coefficients my not be, and we may choose a 135 * matrix format that does not exploit this symmetry). If the edges 136 * connectivity argument is NULL, the matrix will be purely diagonal. 137 * 138 * parameters: 139 * type <-- type of matrix considered 140 * have_diag <-- indicates if the diagonal structure contains nonzeroes 141 * n_rows <-- local number of rows 142 * n_cols_ext <-- number of columns + ghosts 143 * n_edges <-- local number of (undirected) graph edges 144 * edges <-- edges (symmetric row <-> column) connectivity 145 * halo <-- halo structure associated with cells, or NULL 146 * numbering <-- vectorization or thread-related numbering info, or NULL 147 * 148 * returns: 149 * pointer to created matrix structure; 150 *----------------------------------------------------------------------------*/ 151 152 cs_matrix_structure_t * 153 cs_matrix_structure_create(cs_matrix_type_t type, 154 bool have_diag, 155 cs_lnum_t n_rows, 156 cs_lnum_t n_cols_ext, 157 cs_lnum_t n_edges, 158 const cs_lnum_2_t *edges, 159 const cs_halo_t *halo, 160 const cs_numbering_t *numbering); 161 162 /*---------------------------------------------------------------------------- 163 * Create a matrix structure based on a MSR connectivity definition. 164 * 165 * Only CSR and MSR formats are handled. 166 * 167 * col_id is sorted row by row during the creation of this structure. 168 * 169 * In case the property of the row index and col_id arrays are transferred 170 * to the structure, the arrays pointers passed as arguments are set to NULL, 171 * to help ensure the caller does not use the original arrays directly after 172 * this call. 173 * 174 * parameters: 175 * type <-- type of matrix considered 176 * transfer <-- transfer property of row_index and col_id 177 * if true, map them otherwise 178 * have_diag <-- indicates if the structure includes the 179 * diagonal (should be the same for all rows) 180 * n_rows <-- local number of rows 181 * n_cols_ext <-- local number of columns + ghosts 182 * row_index <-> pointer to index on rows 183 * col_id <-> pointer to array of colum ids related to the row index 184 * halo <-- halo structure for synchronization, or NULL 185 * numbering <-- vectorization or thread-related numbering info, or NULL 186 * 187 * returns: 188 * a pointer to a created matrix structure 189 *----------------------------------------------------------------------------*/ 190 191 cs_matrix_structure_t * 192 cs_matrix_structure_create_msr(cs_matrix_type_t type, 193 bool transfer, 194 bool have_diag, 195 cs_lnum_t n_rows, 196 cs_lnum_t n_cols_ext, 197 cs_lnum_t **row_index, 198 cs_lnum_t **col_id, 199 const cs_halo_t *halo, 200 const cs_numbering_t *numbering); 201 202 /*---------------------------------------------------------------------------- 203 * Create an MSR matrix structure sharing an existing connectivity definition. 204 * 205 * Note that as the structure created maps to the given existing 206 * cell global number, face -> cell connectivity arrays, and cell halo 207 * structure, it must be destroyed before they are freed 208 * (usually along with the code's main face -> cell structure). 209 * 210 * parameters: 211 * have_diag <-- indicates if the structure includes the 212 * diagonal (should be the same for all rows) 213 * direct_assembly <-- true if each value corresponds to a unique face 214 * n_rows <-- local number of rows 215 * n_cols_ext <-- local number of columns + ghosts 216 * row_index <-- pointer to index on rows 217 * col_id <-- pointer to array of colum ids related to the row index 218 * halo <-- halo structure for synchronization, or NULL 219 * numbering <-- vectorization or thread-related numbering 220 * info, or NULL 221 * 222 * returns: 223 * a pointer to a created matrix structure 224 *----------------------------------------------------------------------------*/ 225 226 cs_matrix_structure_t * 227 cs_matrix_structure_create_msr_shared(bool have_diag, 228 bool direct_assmbly, 229 cs_lnum_t n_rows, 230 cs_lnum_t n_cols_ext, 231 const cs_lnum_t *row_index, 232 const cs_lnum_t *col_id, 233 const cs_halo_t *halo, 234 const cs_numbering_t *numbering); 235 236 /*----------------------------------------------------------------------------*/ 237 /*! 238 * \brief Create a matrix structure using a matrix assembler. 239 * 240 * Only CSR and MSR formats are handled. 241 * 242 * \param[in] type type of matrix considered 243 * \param[in] ma pointer to matrix assembler structure 244 * 245 * \return a pointer to a created matrix structure 246 */ 247 /*----------------------------------------------------------------------------*/ 248 249 cs_matrix_structure_t * 250 cs_matrix_structure_create_from_assembler(cs_matrix_type_t type, 251 cs_matrix_assembler_t *ma); 252 253 /*---------------------------------------------------------------------------- 254 * Destroy a matrix structure. 255 * 256 * parameters: 257 * ms <-> pointer to matrix structure pointer 258 *----------------------------------------------------------------------------*/ 259 260 void 261 cs_matrix_structure_destroy(cs_matrix_structure_t **ms); 262 263 /*---------------------------------------------------------------------------- 264 * Create a matrix container using a given structure. 265 * 266 * Note that the matrix container maps to the assigned structure, 267 * so it must be destroyed before that structure. 268 * 269 * parameters: 270 * ms <-- associated matrix structure 271 * 272 * returns: 273 * pointer to created matrix structure; 274 *----------------------------------------------------------------------------*/ 275 276 cs_matrix_t * 277 cs_matrix_create(const cs_matrix_structure_t *ms); 278 279 /*----------------------------------------------------------------------------*/ 280 /*! 281 * \brief Create a matrix directly from assembler. 282 * 283 * Only CSR and MSR formats are handled. 284 * 285 * \param[in] type type of matrix considered 286 * \param[in] ma pointer to matrix assembler structure 287 * 288 * \return a pointer to a created matrix structure 289 */ 290 /*----------------------------------------------------------------------------*/ 291 292 cs_matrix_t * 293 cs_matrix_create_from_assembler(cs_matrix_type_t type, 294 cs_matrix_assembler_t *ma); 295 296 /*----------------------------------------------------------------------------*/ 297 /*! 298 * \brief Create a matrix container by copying another 299 * 300 * Note that the matrix containers share the same assigned structure, 301 * so they must be both destroyed before that structure. 302 * 303 * If assigned, coefficients are not copied. 304 * 305 * \param[in] src reference matrix structure 306 * 307 * \return pointer to created matrix structure; 308 */ 309 /*----------------------------------------------------------------------------*/ 310 311 cs_matrix_t * 312 cs_matrix_create_by_copy(cs_matrix_t *src); 313 314 /*----------------------------------------------------------------------------*/ 315 /*! 316 * \brief Create a matrix based on the local restriction of a base matrix. 317 * 318 * Coefficients are copied. Some coefficients may be shared with the 319 * parent matrix, so the base matrix must not be destroyed before the 320 * restriction matrix. 321 * 322 * \param[in] src reference matrix structure 323 * 324 * \return pointer to created matrix structure; 325 */ 326 /*----------------------------------------------------------------------------*/ 327 328 cs_matrix_t * 329 cs_matrix_create_by_local_restrict(const cs_matrix_t *src); 330 331 /*---------------------------------------------------------------------------- 332 * Destroy a matrix structure. 333 * 334 * In the case of a compoud matrix, sub-matrices are not destroyed. 335 * 336 * parameters: 337 * matrix <-> pointer to matrix structure pointer 338 *----------------------------------------------------------------------------*/ 339 340 void 341 cs_matrix_destroy(cs_matrix_t **matrix); 342 343 /*---------------------------------------------------------------------------- 344 * Return type of matrix. 345 * 346 * parameters: 347 * matrix --> pointer to matrix structure 348 *----------------------------------------------------------------------------*/ 349 350 cs_matrix_type_t 351 cs_matrix_get_type(const cs_matrix_t *matrix); 352 353 /*---------------------------------------------------------------------------- 354 * Return matrix type name. 355 * 356 * parameters: 357 * matrix --> pointer to matrix structure 358 *----------------------------------------------------------------------------*/ 359 360 const char * 361 cs_matrix_get_type_name(const cs_matrix_t *matrix); 362 363 /*---------------------------------------------------------------------------- 364 * Return matrix type full name. 365 * 366 * parameters: 367 * matrix --> pointer to matrix structure 368 *----------------------------------------------------------------------------*/ 369 370 const char * 371 cs_matrix_get_type_fullname(const cs_matrix_t *matrix); 372 373 /*---------------------------------------------------------------------------- 374 * Return number of columns in matrix. 375 * 376 * parameters: 377 * matrix --> pointer to matrix structure 378 *----------------------------------------------------------------------------*/ 379 380 cs_lnum_t 381 cs_matrix_get_n_columns(const cs_matrix_t *matrix); 382 383 /*---------------------------------------------------------------------------- 384 * Return number of rows in matrix. 385 * 386 * parameters: 387 * matrix --> pointer to matrix structure 388 *----------------------------------------------------------------------------*/ 389 390 cs_lnum_t 391 cs_matrix_get_n_rows(const cs_matrix_t *matrix); 392 393 /*---------------------------------------------------------------------------- 394 * Return number of entries in matrix. 395 * 396 * When the block size is > 1, the number reported is the number of 397 * entry blocks, not individual entries. 398 * 399 * parameters: 400 * matrix --> pointer to matrix structure 401 *----------------------------------------------------------------------------*/ 402 403 cs_lnum_t 404 cs_matrix_get_n_entries(const cs_matrix_t *matrix); 405 406 /*---------------------------------------------------------------------------- 407 * Return matrix diagonal block sizes. 408 * 409 * Block sizes are defined by a array of 4 values: 410 * 0: useful block size, 1: vector block extents, 411 * 2: matrix line extents, 3: matrix line*column extents 412 * 413 * parameters: 414 * matrix <-- pointer to matrix structure 415 * 416 * returns: 417 * pointer to block sizes 418 *----------------------------------------------------------------------------*/ 419 420 const cs_lnum_t * 421 cs_matrix_get_diag_block_size(const cs_matrix_t *matrix); 422 423 /*---------------------------------------------------------------------------- 424 * Return matrix extra-diagonal block sizes. 425 * 426 * Block sizes are defined by a array of 4 values: 427 * 0: useful block size, 1: vector block extents, 428 * 2: matrix line extents, 3: matrix line*column extents 429 * 430 * parameters: 431 * matrix <-- pointer to matrix structure 432 * 433 * returns: 434 * pointer to block sizes 435 *----------------------------------------------------------------------------*/ 436 437 const cs_lnum_t * 438 cs_matrix_get_extra_diag_block_size(const cs_matrix_t *matrix); 439 440 /*---------------------------------------------------------------------------- 441 * Return pointer to matrix halo structure. 442 * 443 * parameters: 444 * matrix <-- pointer to matrix structure 445 * 446 * returns: 447 * pointer to halo strucuture 448 *----------------------------------------------------------------------------*/ 449 450 const cs_halo_t * 451 cs_matrix_get_halo(const cs_matrix_t *matrix); 452 453 /*---------------------------------------------------------------------------- 454 * Get matrix fill type, depending on block sizes. 455 * 456 * Block sizes are defined by an optional array of 4 values: 457 * 0: useful block size, 1: vector block extents, 458 * 2: matrix line extents, 3: matrix line*column extents 459 * 460 * parameters: 461 * symmetric <-- indicates if matrix coefficients are symmetric 462 * diag_block_size <-- block sizes for diagonal, or NULL 463 * extra_diag_block_size <-- block sizes for extra diagonal, or NULL 464 * 465 * returns: 466 * matrix fill type 467 *----------------------------------------------------------------------------*/ 468 469 cs_matrix_fill_type_t 470 cs_matrix_get_fill_type(bool symmetric, 471 const cs_lnum_t *diag_block_size, 472 const cs_lnum_t *extra_diag_block_size); 473 474 /*---------------------------------------------------------------------------- 475 * Set matrix coefficients defined relative to a "native" edge graph, 476 * sharing arrays with the caller when possible. 477 * 478 * With shared arrays, the matrix becomes unusable if the arrays passed as 479 * arguments are not be modified (its coefficients should be unset first 480 * to mark this). 481 * 482 * Depending on current options and initialization, values will be copied 483 * or simply mapped. 484 * 485 * Block sizes are defined by an optional array of 4 values: 486 * 0: useful block size, 1: vector block extents, 487 * 2: matrix line extents, 3: matrix line*column extents 488 * 489 * parameters: 490 * matrix <-> pointer to matrix structure 491 * symmetric <-- indicates if matrix coefficients are symmetric 492 * diag_block_size <-- block sizes for diagonal, or NULL 493 * extra_diag_block_size <-- block sizes for extra diagonal, or NULL 494 * n_edges <-- local number of graph edges 495 * edges <-- edges (row <-> column) connectivity 496 * da <-- diagonal values (NULL if zero) 497 * xa <-- extradiagonal values (NULL if zero) 498 * casts as: 499 * xa[n_edges] if symmetric, 500 * xa[n_edges][2] if non symmetric 501 *----------------------------------------------------------------------------*/ 502 503 void 504 cs_matrix_set_coefficients(cs_matrix_t *matrix, 505 bool symmetric, 506 const cs_lnum_t *diag_block_size, 507 const cs_lnum_t *extra_diag_block_size, 508 const cs_lnum_t n_edges, 509 const cs_lnum_2_t edges[], 510 const cs_real_t *da, 511 const cs_real_t *xa); 512 513 /*---------------------------------------------------------------------------- 514 * Set matrix coefficients, copying values to private arrays. 515 * 516 * With private arrays, the matrix becomes independant from the 517 * arrays passed as arguments. 518 * 519 * Block sizes are defined by an optional array of 4 values: 520 * 0: useful block size, 1: vector block extents, 521 * 2: matrix line extents, 3: matrix line*column extents 522 * 523 * parameters: 524 * matrix <-> pointer to matrix structure 525 * symmetric <-- indicates if matrix coefficients are symmetric 526 * diag_block_size <-- block sizes for diagonal, or NULL 527 * extra_diag_block_size <-- block sizes for extra diagonal, or NULL 528 * n_edges <-- local number of graph edges 529 * edges <-- edges (row <-> column) connectivity 530 * da <-- diagonal values (NULL if zero) 531 * xa <-- extradiagonal values (NULL if zero) 532 * casts as: 533 * xa[n_edges] if symmetric, 534 * xa[n_edges][2] if non symmetric 535 *----------------------------------------------------------------------------*/ 536 537 void 538 cs_matrix_copy_coefficients(cs_matrix_t *matrix, 539 bool symmetric, 540 const cs_lnum_t *diag_block_size, 541 const cs_lnum_t *extra_diag_block_size, 542 const cs_lnum_t n_edges, 543 const cs_lnum_2_t edges[], 544 const cs_real_t *da, 545 const cs_real_t *xa); 546 547 /*---------------------------------------------------------------------------- 548 * Set matrix coefficients in an MSR format, transferring the 549 * property of those arrays to the matrix. 550 * 551 * If the matrix is also in MSR format, this avoids an extra copy. 552 * If it is in a different format, values are copied to the structure, 553 * and the original arrays freed. In any case, the arrays pointers passed as 554 * arguments are set to NULL, to help ensure the caller does not use the 555 * original arrays directly after this call. 556 * 557 * Block sizes are defined by an optional array of 4 values: 558 * 0: useful block size, 1: vector block extents, 559 * 2: matrix line extents, 3: matrix line*column extents 560 * 561 * parameters: 562 * matrix <-> pointer to matrix structure 563 * symmetric <-- indicates if matrix coefficients are symmetric 564 * diag_block_size <-- block sizes for diagonal, or NULL 565 * extra_diag_block_size <-- block sizes for extra diagonal, or NULL 566 * row_index <-- MSR row index (0 to n-1) 567 * col_id <-- MSR column id (0 to n-1) 568 * d_val <-> diagonal values (NULL if zero) 569 * x_val <-> extradiagonal values (NULL if zero) 570 *----------------------------------------------------------------------------*/ 571 572 void 573 cs_matrix_transfer_coefficients_msr(cs_matrix_t *matrix, 574 bool symmetric, 575 const cs_lnum_t *diag_block_size, 576 const cs_lnum_t *extra_diag_block_size, 577 const cs_lnum_t row_index[], 578 const cs_lnum_t col_id[], 579 cs_real_t **d_val, 580 cs_real_t **x_val); 581 582 /*----------------------------------------------------------------------------*/ 583 /*! 584 * \brief Create and initialize a CSR matrix assembler values structure. 585 * 586 * The associated matrix's structure must have been created using 587 * \ref cs_matrix_structure_create_from_assembler. 588 * 589 * Block sizes are defined by an optional array of 4 values: 590 * 0: useful block size, 1: vector block extents, 591 * 2: matrix line extents, 3: matrix line*column extents 592 * 593 * \param[in, out] matrix pointer to matrix structure 594 * \param[in] diag_block_size block sizes for diagonal, or NULL 595 * \param[in] extra_diag_block_size block sizes for extra diagonal, 596 * or NULL 597 * 598 * \return pointer to initialized matrix assembler values structure; 599 */ 600 /*----------------------------------------------------------------------------*/ 601 602 cs_matrix_assembler_values_t * 603 cs_matrix_assembler_values_init(cs_matrix_t *matrix, 604 const cs_lnum_t *diag_block_size, 605 const cs_lnum_t *extra_diag_block_size); 606 607 /*---------------------------------------------------------------------------- 608 * Release shared matrix coefficients. 609 * 610 * Pointers to mapped coefficients are set to NULL, while 611 * coefficient copies owned by the matrix are not modified. 612 * 613 * This simply ensures the matrix does not maintain pointers 614 * to nonexistant data. 615 * 616 * parameters: 617 * matrix <-> pointer to matrix structure 618 *----------------------------------------------------------------------------*/ 619 620 void 621 cs_matrix_release_coefficients(cs_matrix_t *matrix); 622 623 /*---------------------------------------------------------------------------- 624 * Copy matrix diagonal values. 625 * 626 * In case of matrixes with block diagonal coefficients, only the true 627 * diagonal values are copied. 628 * 629 * parameters: 630 * matrix --> pointer to matrix structure 631 * da --> diagonal (pre-allocated, size: n_rows*block_size 632 *----------------------------------------------------------------------------*/ 633 634 void 635 cs_matrix_copy_diagonal(const cs_matrix_t *matrix, 636 cs_real_t *restrict da); 637 638 /*---------------------------------------------------------------------------- 639 * Query matrix coefficients symmetry 640 * 641 * parameters: 642 * matrix <-- pointer to matrix structure 643 * 644 * returns: 645 * true if coefficients are symmetric, false otherwise 646 *----------------------------------------------------------------------------*/ 647 648 bool 649 cs_matrix_is_symmetric(const cs_matrix_t *matrix); 650 651 /*----------------------------------------------------------------------------*/ 652 /*! 653 * \brief Indicate whether coefficients were mapped from native face-based 654 * arrays. 655 * 656 * It is used in the current multgrid code, but should be removed as soon 657 * as the dependency to the native format is removed. 658 * 659 * \param[in] matrix pointer to matrix structure 660 * 661 * \return true if coefficients were mapped from native face-based arrays, 662 * false otherwise 663 */ 664 /*----------------------------------------------------------------------------*/ 665 666 bool 667 cs_matrix_is_mapped_from_native(const cs_matrix_t *matrix); 668 669 /*---------------------------------------------------------------------------- 670 * Get matrix diagonal values. 671 * 672 * In case of matrixes with block diagonal coefficients, a pointer to 673 * the complete block diagonal is returned. 674 * 675 * parameters: 676 * matrix --> pointer to matrix structure 677 * 678 * returns: 679 * pointer to matrix diagonal array 680 *----------------------------------------------------------------------------*/ 681 682 const cs_real_t * 683 cs_matrix_get_diagonal(const cs_matrix_t *matrix); 684 685 /*---------------------------------------------------------------------------- 686 * Get pointer to matrix extra-diagonal values in "native" format 687 * 688 * This function currently only functions if the matrix is in "native" 689 * format or the coefficients were mapped from native coefficients using 690 * cs_matrix_set_coefficients(), in which case the pointer returned is 691 * the same as the one passed to that function. 692 * 693 * parameters: 694 * matrix --> pointer to matrix structure 695 * 696 * returns: 697 * pointer to matrix diagonal array 698 *----------------------------------------------------------------------------*/ 699 700 const cs_real_t * 701 cs_matrix_get_extra_diagonal(const cs_matrix_t *matrix); 702 703 /*---------------------------------------------------------------------------- 704 * Initialize row info for a given matrix. 705 * 706 * parameters: 707 * r --> row info structure 708 *----------------------------------------------------------------------------*/ 709 710 void 711 cs_matrix_row_init(cs_matrix_row_info_t *r); 712 713 /*---------------------------------------------------------------------------- 714 * Finalize row info for a given matrix. 715 * 716 * parameters: 717 * r <-> row info structure 718 *----------------------------------------------------------------------------*/ 719 720 void 721 cs_matrix_row_finalize(cs_matrix_row_info_t *r); 722 723 /*---------------------------------------------------------------------------- 724 * Get row values for a given matrix. 725 * 726 * This function may not work for all matrix types. 727 * 728 * In the case of blocked matrixes, the true (non-blocked) 729 * values are returned. 730 * 731 * The row information structure must have been previously initialized 732 * using cs_matrix_row_init(), and should be finalized using 733 * using cs_matrix_row_finalize(), so as to free buffers it may have 734 * built for certain matrix formats. 735 * 736 * parameters: 737 * matrix <-- pointer to matrix structure 738 * row_id <-- id of row to query 739 * r <-> row info structure 740 *----------------------------------------------------------------------------*/ 741 742 void 743 cs_matrix_get_row(const cs_matrix_t *matrix, 744 const cs_lnum_t row_id, 745 cs_matrix_row_info_t *r); 746 747 /*---------------------------------------------------------------------------- 748 * Get arrays describing a matrix in native format. 749 * 750 * This function works for matrix in native format. 751 * 752 * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size() 753 * and cs_matrix_get_extra_diag_block_size(). 754 * 755 * parameters: 756 * matrix <-- pointer to matrix structure 757 * symmetric --> true if symmetric 758 * n_edges --> number of associated faces 759 * edges --> edges (symmetric row <-> column) connectivity 760 * d_val --> diagonal values 761 * x_val --> extra-diagonal values 762 *----------------------------------------------------------------------------*/ 763 764 void 765 cs_matrix_get_native_arrays(const cs_matrix_t *matrix, 766 bool *symmetric, 767 cs_lnum_t *n_edges, 768 const cs_lnum_2_t **edges, 769 const cs_real_t **d_val, 770 const cs_real_t **x_val); 771 772 /*---------------------------------------------------------------------------- 773 * Get arrays describing a matrix in CSR format. 774 * 775 * This function only works for an CSR matrix (i.e. there is 776 * no automatic conversion from another matrix type). 777 * 778 * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size() 779 * and cs_matrix_get_extra_diag_block_size(). 780 * 781 * parameters: 782 * matrix <-- pointer to matrix structure 783 * row_index --> CSR row index 784 * col_id --> CSR column id 785 * val --> values 786 *----------------------------------------------------------------------------*/ 787 788 void 789 cs_matrix_get_csr_arrays(const cs_matrix_t *matrix, 790 const cs_lnum_t **row_index, 791 const cs_lnum_t **col_id, 792 const cs_real_t **val); 793 794 /*---------------------------------------------------------------------------- 795 * Get arrays describing a matrix in MSR format. 796 * 797 * This function only works for an MSR matrix (i.e. there is 798 * no automatic conversion from another matrix type). 799 * 800 * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size() 801 * and cs_matrix_get_extra_diag_block_size(). 802 * 803 * parameters: 804 * matrix <-- pointer to matrix structure 805 * row_index --> MSR row index 806 * col_id --> MSR column id 807 * d_val --> diagonal values 808 * x_val --> extra-diagonal values 809 *----------------------------------------------------------------------------*/ 810 811 void 812 cs_matrix_get_msr_arrays(const cs_matrix_t *matrix, 813 const cs_lnum_t **row_index, 814 const cs_lnum_t **col_id, 815 const cs_real_t **d_val, 816 const cs_real_t **x_val); 817 818 /*---------------------------------------------------------------------------- 819 * Assign functions based on a variant to a given matrix. 820 * 821 * If the matrix variant is incompatible with the structure, it is ignored, 822 * and defaults for that structure are used instead. 823 * 824 * parameters: 825 * m <-> associated matrix structure 826 * mv <-- associated matrix variant 827 * 828 * returns: 829 * pointer to created matrix structure; 830 *----------------------------------------------------------------------------*/ 831 832 void 833 cs_matrix_apply_variant(cs_matrix_t *m, 834 const cs_matrix_variant_t *mv); 835 836 /*---------------------------------------------------------------------------- 837 * Matrix.vector product y = A.x 838 * 839 * This function includes a halo update of x prior to multiplication by A. 840 * 841 * parameters: 842 * matrix --> pointer to matrix structure 843 * x <-> multipliying vector values (ghost values updated) 844 * y --> resulting vector 845 *----------------------------------------------------------------------------*/ 846 847 void 848 cs_matrix_vector_multiply(const cs_matrix_t *matrix, 849 cs_real_t *restrict x, 850 cs_real_t *restrict y); 851 852 /*---------------------------------------------------------------------------- 853 * Matrix.vector product y = A.x with no prior halo update of x. 854 * 855 * This function does not include a halo update of x prior to multiplication 856 * by A, so it should be called only when the halo of x is known to already 857 * be up to date (in which case we avoid the performance penalty of a 858 * redundant update by using this variant of the matrix.vector product). 859 * 860 * parameters: 861 * matrix --> pointer to matrix structure 862 * x --> multipliying vector values 863 * y <-- resulting vector 864 *----------------------------------------------------------------------------*/ 865 866 void 867 cs_matrix_vector_multiply_nosync(const cs_matrix_t *matrix, 868 cs_real_t *restrict x, 869 cs_real_t *restrict y); 870 871 /*---------------------------------------------------------------------------- 872 * Matrix.vector product y = (A-D).x 873 * 874 * This function includes a halo update of x prior to multiplication by A. 875 * 876 * parameters: 877 * matrix <-- pointer to matrix structure 878 * x <-> multipliying vector values (ghost values updated) 879 * y --> resulting vector 880 *----------------------------------------------------------------------------*/ 881 882 void 883 cs_matrix_exdiag_vector_multiply(const cs_matrix_t *matrix, 884 cs_real_t *restrict x, 885 cs_real_t *restrict y); 886 887 /*---------------------------------------------------------------------------- 888 * Synchronize ghost values prior to matrix.vector product 889 * 890 * parameters: 891 * matrix <-- pointer to matrix structure 892 * x <-> multipliying vector values (ghost values updated) 893 *----------------------------------------------------------------------------*/ 894 895 void 896 cs_matrix_pre_vector_multiply_sync(const cs_matrix_t *matrix, 897 cs_real_t *x); 898 899 /*----------------------------------------------------------------------------*/ 900 /*! 901 * \brief Build list of variants for tuning or testing. 902 * 903 * The matrix coefficients should be assigned, so the fill type can 904 * be determined. 905 * 906 * \param[in] m associated matrix 907 * \param[out] n_variants number of variants 908 * \param[out] m_variant array of matrix variants 909 */ 910 /*----------------------------------------------------------------------------*/ 911 912 void 913 cs_matrix_variant_build_list(const cs_matrix_t *m, 914 int *n_variants, 915 cs_matrix_variant_t **m_variant); 916 917 /*----------------------------------------------------------------------------*/ 918 /*! 919 * \brief Build matrix variant 920 * 921 * The variant will initially use default matrix-vector functions, 922 * which can be later modified using cs_matrix_variant_set_func(). 923 * 924 * \param[in] m pointer to matrix 925 */ 926 /*----------------------------------------------------------------------------*/ 927 928 cs_matrix_variant_t * 929 cs_matrix_variant_create(cs_matrix_t *m); 930 931 /*---------------------------------------------------------------------------- 932 * Destroy a matrix variant structure. 933 * 934 * parameters: 935 * mv <-> Pointer to matrix variant pointer 936 *----------------------------------------------------------------------------*/ 937 938 void 939 cs_matrix_variant_destroy(cs_matrix_variant_t **mv); 940 941 /*----------------------------------------------------------------------------*/ 942 /*! 943 * \brief Apply a variant to a given matrix 944 * 945 * \param[in, out] m pointer to matrix 946 * \param[in] mv pointer to matrix variant pointer 947 */ 948 /*----------------------------------------------------------------------------*/ 949 950 void 951 cs_matrix_variant_apply(cs_matrix_t *m, 952 cs_matrix_variant_t *mv); 953 954 /*---------------------------------------------------------------------------- 955 * Select the sparse matrix-vector product function to be used by a 956 * matrix variant for a given fill type. 957 * 958 * Currently, possible variant functions are: 959 * 960 * CS_MATRIX_NATIVE (all fill types) 961 * default 962 * standard 963 * omp (for OpenMP with compatible numbering) 964 * vector (For vector machine with compatible numbering) 965 * 966 * CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM) 967 * default 968 * standard 969 * mkl (with MKL) 970 * 971 * CS_MATRIX_MSR (all fill types except CS_MATRIX_33_BLOCK) 972 * default 973 * standard 974 * mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM) 975 * omp_sched (For OpenMP with scheduling) 976 * 977 * parameters: 978 * mv <-> pointer to matrix variant 979 * numbering <-- mesh numbering info, or NULL 980 * fill type <-- matrix fill type to merge from 981 * ed_flag <-- 0: with diagonal only, 1 exclude only; 2; both 982 * func_name <-- function type name 983 *----------------------------------------------------------------------------*/ 984 985 void 986 cs_matrix_variant_set_func(cs_matrix_variant_t *mv, 987 const cs_numbering_t *numbering, 988 cs_matrix_fill_type_t fill_type, 989 int ed_flag, 990 const char *func_name); 991 992 /*---------------------------------------------------------------------------- 993 * Get the type associated with a matrix variant. 994 * 995 * parameters: 996 * mv <-- pointer to matrix variant structure 997 *----------------------------------------------------------------------------*/ 998 999 cs_matrix_type_t 1000 cs_matrix_variant_type(const cs_matrix_variant_t *mv); 1001 1002 /*----------------------------------------------------------------------------*/ 1003 1004 END_C_DECLS 1005 1006 #endif /* __CS_MATRIX_H__ */ 1007