8.3
general documentation
cs_matrix.h
Go to the documentation of this file.
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-2024 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_matrix_assembler.h"
39
40/*----------------------------------------------------------------------------*/
41
43
44/*============================================================================
45 * Macro definitions
46 *============================================================================*/
47
48/*============================================================================
49 * Type definitions
50 *============================================================================*/
51
52/* Matrix structure representation types */
53
54typedef enum {
55
69
70/* Matrix fill types (for tuning) */
71
72typedef enum {
73
74 CS_MATRIX_SCALAR, /* Simple scalar matrix */
75 CS_MATRIX_SCALAR_SYM, /* Simple scalar symmetric matrix */
76 CS_MATRIX_BLOCK_D, /* Matrix with diagonal blocks
77 (and m.I extradiagonal blocks) */
78 CS_MATRIX_BLOCK_D_66, /* Matrix with 6x6 diagonal blocks
79 (and 6.I extradiagonal blocks;
80 subcase of CS_MATRIX_BLOCK_D, allows
81 separate tuning) */
82 CS_MATRIX_BLOCK_D_SYM, /* Symmetric matrix with diagonal blocks
83 (and m.I extradiagonal blocks) */
84 CS_MATRIX_BLOCK, /* Block matrix */
85 CS_MATRIX_N_FILL_TYPES /* Number of possible matrix fill types */
86
88
95typedef enum {
96
103
104/* Structure associated with opaque matrix structure object */
105
106typedef struct _cs_matrix_structure_t cs_matrix_structure_t;
107
108/* Structure associated with opaque matrix object */
109
110typedef struct _cs_matrix_t cs_matrix_t;
111
112/* Structure associated with opaque matrix tuning results object */
113
114typedef struct _cs_matrix_variant_t cs_matrix_variant_t;
115
116/* Information structure for extraction of matrix row */
117
118typedef struct {
119
120 cs_lnum_t row_size; /*< Row size from last call */
121 cs_lnum_t buffer_size; /*< Allocated buffer size */
122 const cs_lnum_t *col_id; /*< Pointer to local column ids */
123 cs_lnum_t *_col_id; /*< Pointer to local column ids copy */
124 const cs_real_t *vals; /*< Pointer to local row values */
125 cs_real_t *_vals; /*< Pointer to local row values copy */
126
128
129/*============================================================================
130 * Global variables
131 *============================================================================*/
132
135extern const char *cs_matrix_fill_type_name[];
136
139extern const char *cs_matrix_spmv_type_name[];
140
141/*=============================================================================
142 * Public function prototypes
143 *============================================================================*/
144
145/*----------------------------------------------------------------------------
146 * Create a matrix structure.
147 *
148 * Note that the structure created usually maps to the given existing
149 * cell global number, face -> cell connectivity arrays, and cell halo
150 * structure, so it must be destroyed before they are freed
151 * (usually along with the code's main face -> cell structure).
152 *
153 * Note that the resulting matrix structure will contain a full main
154 * main diagonal, and that the extra-diagonal structure is always
155 * symmetric (though the coefficients my not be, and we may choose a
156 * matrix format that does not exploit this symmetry). If the edges
157 * connectivity argument is null, the matrix will be purely diagonal.
158 *
159 * parameters:
160 * type <-- type of matrix considered
161 * n_rows <-- local number of rows
162 * n_cols_ext <-- number of columns + ghosts
163 * n_edges <-- local number of (undirected) graph edges
164 * edges <-- edges (symmetric row <-> column) connectivity
165 * halo <-- halo structure associated with cells, or nullptr
166 * numbering <-- vectorization or thread-related numbering info, or nullptr
167 *
168 * returns:
169 * pointer to created matrix structure;
170 *----------------------------------------------------------------------------*/
171
174 cs_lnum_t n_rows,
175 cs_lnum_t n_cols_ext,
176 cs_lnum_t n_edges,
177 const cs_lnum_2_t *edges,
178 const cs_halo_t *halo,
179 const cs_numbering_t *numbering);
180
181/*----------------------------------------------------------------------------
182 * Create a matrix structure based on a MSR connectivity definition.
183 *
184 * Only CSR and MSR formats are handled.
185 *
186 * col_id is sorted row by row during the creation of this structure.
187 *
188 * In case the property of the row index and col_id arrays are transferred
189 * to the structure, the arrays pointers passed as arguments are set to nullptr,
190 * to help ensure the caller does not use the original arrays directly after
191 * this call.
192 *
193 * parameters:
194 * type <-- type of matrix considered
195 * transfer <-- transfer property of row_index and col_id
196 * if true, map them otherwise
197 * ordered <-- indicates if column ids are already ordered
198 * have_diag <-- indicates if the structure includes the
199 * diagonal (should be the same for all rows)
200 * n_rows <-- local number of rows
201 * n_cols_ext <-- local number of columns + ghosts
202 * row_index <-> pointer to index on rows
203 * col_id <-> pointer to array of colum ids related to the row index
204 * halo <-- halo structure for synchronization, or nullptr
205 * numbering <-- vectorization or thread-related numbering info, or nullptr
206 *
207 * returns:
208 * a pointer to a created matrix structure
209 *----------------------------------------------------------------------------*/
210
213 bool transfer,
214 bool have_diag,
215 bool ordered,
216 cs_lnum_t n_rows,
217 cs_lnum_t n_cols_ext,
218 cs_lnum_t **row_index,
219 cs_lnum_t **col_id,
220 const cs_halo_t *halo,
221 const cs_numbering_t *numbering);
222
223/*----------------------------------------------------------------------------
224 * Create an MSR matrix structure sharing an existing connectivity definition.
225 *
226 * Note that as the structure created maps to the given existing
227 * cell global number, face -> cell connectivity arrays, and cell halo
228 * structure, it must be destroyed before they are freed
229 * (usually along with the code's main face -> cell structure).
230 *
231 * parameters:
232 * direct_assembly <-- true if each value corresponds to a unique face
233 * n_rows <-- local number of rows
234 * n_cols_ext <-- local number of columns + ghosts
235 * row_index <-- pointer to index on rows
236 * col_id <-- pointer to array of colum ids related to the row index
237 * halo <-- halo structure for synchronization, or nullptr
238 * numbering <-- vectorization or thread-related numbering
239 * info, or nullptr
240 *
241 * returns:
242 * a pointer to a created matrix structure
243 *----------------------------------------------------------------------------*/
244
246cs_matrix_structure_create_msr_shared(bool direct_assmbly,
247 cs_lnum_t n_rows,
248 cs_lnum_t n_cols_ext,
249 const cs_lnum_t *row_index,
250 const cs_lnum_t *col_id,
251 const cs_halo_t *halo,
252 const cs_numbering_t *numbering);
253
254/*----------------------------------------------------------------------------*/
265/*----------------------------------------------------------------------------*/
266
270
271/*----------------------------------------------------------------------------
272 * Destroy a matrix structure.
273 *
274 * parameters:
275 * ms <-> pointer to matrix structure pointer
276 *----------------------------------------------------------------------------*/
277
278void
280
281/*----------------------------------------------------------------------------
282 * Create a matrix container using a given structure.
283 *
284 * Note that the matrix container maps to the assigned structure,
285 * so it must be destroyed before that structure.
286 *
287 * parameters:
288 * ms <-- associated matrix structure
289 *
290 * returns:
291 * pointer to created matrix structure;
292 *----------------------------------------------------------------------------*/
293
296
297/*----------------------------------------------------------------------------*/
308/*----------------------------------------------------------------------------*/
309
313
314/*----------------------------------------------------------------------------*/
327/*----------------------------------------------------------------------------*/
328
331
332/*----------------------------------------------------------------------------*/
344/*----------------------------------------------------------------------------*/
345
348
349/*----------------------------------------------------------------------------
350 * Destroy a matrix structure.
351 *
352 * In the case of a compoud matrix, sub-matrices are not destroyed.
353 *
354 * parameters:
355 * matrix <-> pointer to matrix structure pointer
356 *----------------------------------------------------------------------------*/
357
358void
360
361/*----------------------------------------------------------------------------
362 * Return type of matrix.
363 *
364 * parameters:
365 * matrix --> pointer to matrix structure
366 *----------------------------------------------------------------------------*/
367
369cs_matrix_get_type(const cs_matrix_t *matrix);
370
371/*----------------------------------------------------------------------------
372 * Return matrix type name.
373 *
374 * parameters:
375 * matrix --> pointer to matrix structure
376 *----------------------------------------------------------------------------*/
377
378const char *
380
381/*----------------------------------------------------------------------------
382 * Return matrix type full name.
383 *
384 * parameters:
385 * matrix --> pointer to matrix structure
386 *----------------------------------------------------------------------------*/
387
388const char *
390
391/*----------------------------------------------------------------------------*/
399/*----------------------------------------------------------------------------*/
400
403
404/*----------------------------------------------------------------------------*/
412/*----------------------------------------------------------------------------*/
413
415cs_matrix_get_n_rows(const cs_matrix_t *matrix);
416
417/*----------------------------------------------------------------------------*/
428/*----------------------------------------------------------------------------*/
429
432
433/*----------------------------------------------------------------------------*/
441/*----------------------------------------------------------------------------*/
442
445
446/*----------------------------------------------------------------------------*/
454/*----------------------------------------------------------------------------*/
455
458
459/*----------------------------------------------------------------------------*/
460/*
461 * \brief Return matrix assembler if present.
462 *
463 * \param[in] matrix pointer to matrix structure
464 */
465/*----------------------------------------------------------------------------*/
466
469
470/*----------------------------------------------------------------------------*/
478/*----------------------------------------------------------------------------*/
479
480const cs_halo_t *
481cs_matrix_get_halo(const cs_matrix_t *matrix);
482
483/*----------------------------------------------------------------------------*/
492/*----------------------------------------------------------------------------*/
493
494const cs_gnum_t *
496
497/*----------------------------------------------------------------------------*/
505/*----------------------------------------------------------------------------*/
506
509
510/*----------------------------------------------------------------------------*/
517/*----------------------------------------------------------------------------*/
518
519void
521 cs_alloc_mode_t alloc_mode);
522
523/*----------------------------------------------------------------------------*/
524/*
525 * \brief Query matrix allocation mode.
526 *
527 * \param[in] matrix pointer to matrix structure
528 *
529 * \return host/device allocation mode
530 */
531/*----------------------------------------------------------------------------*/
532
533bool
535
536/*----------------------------------------------------------------------------*/
537/*
538 *\brief Indicate whether matrix will need xa coefficients.
539 *
540 * \param[in, out] matrix pointer to matrix structure
541 * \param[in] need_xa is thr face-based xa array needed ?
542 */
543/*----------------------------------------------------------------------------*/
544
545void
547 bool need_xa);
548
549/*----------------------------------------------------------------------------
550 * Get matrix fill type, depending on block sizes.
551 *
552 * parameters:
553 * symmetric <-- indicates if matrix coefficients are symmetric
554 * diag_block_size <-- block sizes for diagonal
555 * extra_diag_block_size <-- block sizes for extra diagonal
556 *
557 * returns:
558 * matrix fill type
559 *----------------------------------------------------------------------------*/
560
562cs_matrix_get_fill_type(bool symmetric,
563 cs_lnum_t diag_block_size,
564 cs_lnum_t extra_diag_block_size);
565
566/*----------------------------------------------------------------------------
567 * Set matrix coefficients defined relative to a "native" edge graph,
568 * sharing arrays with the caller when possible.
569 *
570 * With shared arrays, the matrix becomes unusable if the arrays passed as
571 * arguments are not be modified (its coefficients should be unset first
572 * to mark this).
573 *
574 * Depending on current options and initialization, values will be copied
575 * or simply mapped.
576 *
577 * parameters:
578 * matrix <-> pointer to matrix structure
579 * symmetric <-- indicates if matrix coefficients are symmetric
580 * diag_block_size <-- block sizes for diagonal
581 * extra_diag_block_size <-- block sizes for extra diagonal
582 * n_edges <-- local number of graph edges
583 * edges <-- edges (row <-> column) connectivity
584 * da <-- diagonal values (nullptr if zero)
585 * xa <-- extradiagonal values (nullptr if zero)
586 * casts as:
587 * xa[n_edges] if symmetric,
588 * xa[n_edges][2] if non symmetric
589 *----------------------------------------------------------------------------*/
590
591void
593 bool symmetric,
594 cs_lnum_t diag_block_size,
595 cs_lnum_t extra_diag_block_size,
596 const cs_lnum_t n_edges,
597 const cs_lnum_2_t edges[],
598 const cs_real_t *da,
599 const cs_real_t *xa);
600
601/*----------------------------------------------------------------------------
602 * Transfer matrix coefficients defined relative to a "native" edge graph.
603 *
604 * parameters:
605 * matrix <-> pointer to matrix structure
606 * symmetric <-- indicates if matrix coefficients are symmetric
607 * diag_block_size <-- block sizes for diagonal
608 * extra_diag_block_size <-- block sizes for extra diagonal
609 * n_edges <-- local number of graph edges
610 * edges <-- edges (row <-> column) connectivity
611 * da <-- diagonal values (nullptr if zero)
612 * xa <-- extradiagonal values (nullptr if zero)
613 * casts as:
614 * xa[n_edges] if symmetric,
615 * xa[n_edges][2] if non symmetric
616 *----------------------------------------------------------------------------*/
617
618void
620 bool symmetric,
621 cs_lnum_t diag_block_size,
622 cs_lnum_t extra_diag_block_size,
623 const cs_lnum_t n_edges,
624 const cs_lnum_2_t edges[],
625 cs_real_t **d_val,
626 cs_real_t **x_val);
627
628/*----------------------------------------------------------------------------
629 * Set matrix coefficients in an MSR format, transferring the
630 * property of those arrays to the matrix.
631 *
632 * If the matrix is also in MSR format, this avoids an extra copy.
633 * If it is in a different format, values are copied to the structure,
634 * and the original arrays freed. In any case, the arrays pointers passed as
635 * arguments are set to nullptr, to help ensure the caller does not use the
636 * original arrays directly after this call.
637 *
638 * parameters:
639 * matrix <-> pointer to matrix structure
640 * symmetric <-- indicates if matrix coefficients are symmetric
641 * diag_block_size <-- block sizes for diagonal
642 * extra_diag_block_size <-- block sizes for extra diagonal
643 * row_index <-- MSR row index (0 to n-1)
644 * col_id <-- MSR column id (0 to n-1)
645 * d_val <-> diagonal values (nullptr if zero)
646 * x_val <-> extradiagonal values (nullptr if zero)
647 *----------------------------------------------------------------------------*/
648
649void
651 bool symmetric,
652 cs_lnum_t diag_block_size,
653 cs_lnum_t extra_diag_block_size,
654 const cs_lnum_t row_index[],
655 const cs_lnum_t col_id[],
656 cs_real_t **d_val,
657 cs_real_t **x_val);
658
659/*----------------------------------------------------------------------------*/
676/*----------------------------------------------------------------------------*/
677
678void
680 bool symmetric,
681 cs_lnum_t diag_block_size,
682 cs_lnum_t extra_diag_block_size,
683 cs_real_t **d_val,
684 cs_real_t **x_val);
685
686/*----------------------------------------------------------------------------*/
699/*----------------------------------------------------------------------------*/
700
703 cs_lnum_t diag_block_size,
704 cs_lnum_t extra_diag_block_size);
705
706/*----------------------------------------------------------------------------
707 * Release shared matrix coefficients.
708 *
709 * Pointers to mapped coefficients are set to nullptr, while
710 * coefficient copies owned by the matrix are not modified.
711 *
712 * This simply ensures the matrix does not maintain pointers
713 * to nonexistant data.
714 *
715 * parameters:
716 * matrix <-> pointer to matrix structure
717 *----------------------------------------------------------------------------*/
718
719void
721
722/*----------------------------------------------------------------------------
723 * Copy matrix diagonal values.
724 *
725 * In case of matrixes with block diagonal coefficients, only the true
726 * diagonal values are copied.
727 *
728 * parameters:
729 * matrix --> pointer to matrix structure
730 * da --> diagonal (pre-allocated, size: n_rows*block_size
731 *----------------------------------------------------------------------------*/
732
733void
735 cs_real_t *da);
736
737/*----------------------------------------------------------------------------
738 * Query matrix coefficients symmetry
739 *
740 * parameters:
741 * matrix <-- pointer to matrix structure
742 *
743 * returns:
744 * true if coefficients are symmetric, false otherwise
745 *----------------------------------------------------------------------------*/
746
747bool
749
750/*----------------------------------------------------------------------------*/
763/*----------------------------------------------------------------------------*/
764
765bool
767
768/*----------------------------------------------------------------------------
769 * Get matrix diagonal values.
770 *
771 * In case of matrixes with block diagonal coefficients, a pointer to
772 * the complete block diagonal is returned.
773 *
774 * parameters:
775 * matrix --> pointer to matrix structure
776 *
777 * returns:
778 * pointer to matrix diagonal array
779 *----------------------------------------------------------------------------*/
780
781const cs_real_t *
783
784/*----------------------------------------------------------------------------
785 * Get pointer to matrix extra-diagonal values in "native" format
786 *
787 * This function currently only functions if the matrix is in "native"
788 * format or the coefficients were mapped from native coefficients using
789 * cs_matrix_set_coefficients(), in which case the pointer returned is
790 * the same as the one passed to that function.
791 *
792 * parameters:
793 * matrix --> pointer to matrix structure
794 *
795 * returns:
796 * pointer to matrix diagonal array
797 *----------------------------------------------------------------------------*/
798
799const cs_real_t *
801
802/*----------------------------------------------------------------------------
803 * Initialize row info for a given matrix.
804 *
805 * parameters:
806 * r --> row info structure
807 *----------------------------------------------------------------------------*/
808
809void
811
812/*----------------------------------------------------------------------------
813 * Finalize row info for a given matrix.
814 *
815 * parameters:
816 * r <-> row info structure
817 *----------------------------------------------------------------------------*/
818
819void
821
822/*----------------------------------------------------------------------------
823 * Get row values for a given matrix.
824 *
825 * This function may not work for all matrix types.
826 *
827 * In the case of blocked matrixes, the true (non-blocked)
828 * values are returned.
829 *
830 * The row information structure must have been previously initialized
831 * using cs_matrix_row_init(), and should be finalized using
832 * using cs_matrix_row_finalize(), so as to free buffers it may have
833 * built for certain matrix formats.
834 *
835 * parameters:
836 * matrix <-- pointer to matrix structure
837 * row_id <-- id of row to query
838 * r <-> row info structure
839 *----------------------------------------------------------------------------*/
840
841void
842cs_matrix_get_row(const cs_matrix_t *matrix,
843 const cs_lnum_t row_id,
845
846/*----------------------------------------------------------------------------
847 * Get arrays describing a matrix in native format.
848 *
849 * This function works for matrix in native format.
850 *
851 * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
852 * and cs_matrix_get_extra_diag_block_size().
853 *
854 * parameters:
855 * matrix <-- pointer to matrix structure
856 * symmetric --> true if symmetric
857 * n_edges --> number of associated faces
858 * edges --> edges (symmetric row <-> column) connectivity
859 * d_val --> diagonal values
860 * x_val --> extra-diagonal values
861 *----------------------------------------------------------------------------*/
862
863void
865 bool *symmetric,
866 cs_lnum_t *n_edges,
867 const cs_lnum_2_t **edges,
868 const cs_real_t **d_val,
869 const cs_real_t **x_val);
870
871/*----------------------------------------------------------------------------
872 * Get arrays describing a matrix in CSR format.
873 *
874 * This function only works for an CSR matrix (i.e. there is
875 * no automatic conversion from another matrix type).
876 *
877 * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
878 * and cs_matrix_get_extra_diag_block_size().
879 *
880 * parameters:
881 * matrix <-- pointer to matrix structure
882 * row_index --> CSR row index
883 * col_id --> CSR column id
884 * val --> values
885 *----------------------------------------------------------------------------*/
886
887void
889 const cs_lnum_t **row_index,
890 const cs_lnum_t **col_id,
891 const cs_real_t **val);
892
893/*----------------------------------------------------------------------------
894 * Get arrays describing a matrix in MSR format.
895 *
896 * This function only works for an MSR matrix (i.e. there is
897 * no automatic conversion from another matrix type).
898 *
899 * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
900 * and cs_matrix_get_extra_diag_block_size().
901 *
902 * parameters:
903 * matrix <-- pointer to matrix structure
904 * row_index --> MSR row index
905 * col_id --> MSR column id
906 * d_val --> diagonal values
907 * x_val --> extra-diagonal values
908 *----------------------------------------------------------------------------*/
909
910void
912 const cs_lnum_t **row_index,
913 const cs_lnum_t **col_id,
914 const cs_real_t **d_val,
915 const cs_real_t **x_val);
916
917/*----------------------------------------------------------------------------*/
940/*----------------------------------------------------------------------------*/
941
942void
944 const cs_lnum_t *c2f_idx,
945 const cs_lnum_t *c2f,
946 const short int *c2f_sgn,
947 const cs_real_3_t *cell_cen,
948 const cs_real_t *cell_vol,
949 const cs_real_3_t *face_normal);
950
951/*----------------------------------------------------------------------------*/
965/*----------------------------------------------------------------------------*/
966
967void
969 const cs_lnum_t **c2f_idx,
970 const cs_lnum_t **c2f,
971 const short int **c2f_sgn,
972 const cs_real_3_t **cell_cen,
973 const cs_real_t **cell_vol,
974 const cs_real_3_t **face_normal);
975
976/*----------------------------------------------------------------------------
977 * Assign functions based on a variant to a given matrix.
978 *
979 * If the matrix variant is incompatible with the structure, it is ignored,
980 * and defaults for that structure are used instead.
981 *
982 * parameters:
983 * m <-> associated matrix structure
984 * mv <-- associated matrix variant
985 *
986 * returns:
987 * pointer to created matrix structure;
988 *----------------------------------------------------------------------------*/
989
990void
992 const cs_matrix_variant_t *mv);
993
994/*----------------------------------------------------------------------------
995 * Matrix.vector product y = A.x
996 *
997 * This function includes a halo update of x prior to multiplication by A.
998 *
999 * parameters:
1000 * matrix --> pointer to matrix structure
1001 * x <-> multipliying vector values (ghost values updated)
1002 * y --> resulting vector
1003 *----------------------------------------------------------------------------*/
1004
1005void
1007 cs_real_t *x,
1008 cs_real_t *y);
1009
1010#if defined(HAVE_ACCEL)
1011
1012/*----------------------------------------------------------------------------*/
1023/*----------------------------------------------------------------------------*/
1024
1025void
1026cs_matrix_vector_multiply_d(const cs_matrix_t *matrix,
1027 cs_real_t *x,
1028 cs_real_t *y);
1029
1030#endif /* defined(HAVE_ACCEL) */
1031
1032/*----------------------------------------------------------------------------
1033 * Matrix.vector product y = A.x with no prior halo update of x.
1034 *
1035 * This function does not include a halo update of x prior to multiplication
1036 * by A, so it should be called only when the halo of x is known to already
1037 * be up to date (in which case we avoid the performance penalty of a
1038 * redundant update by using this variant of the matrix.vector product).
1039 *
1040 * parameters:
1041 * matrix --> pointer to matrix structure
1042 * x --> multipliying vector values
1043 * y <-- resulting vector
1044 *----------------------------------------------------------------------------*/
1045
1046void
1048 cs_real_t *x,
1049 cs_real_t *y);
1050
1051/*----------------------------------------------------------------------------
1052 * Partial matrix.vector product.
1053 *
1054 * This function includes a halo update of x prior to multiplication,
1055 * except for the CS_MATRIX_SPMV_L operation type, which does not require it,
1056 * as halo adjacencies are only present and useful in the upper-diagonal part..
1057 *
1058 * parameters:
1059 * matrix <-- pointer to matrix structure
1060 * op_type <-- SpMV operation type
1061 * x <-> multipliying vector values (ghost values updated)
1062 * y --> resulting vector
1063 *----------------------------------------------------------------------------*/
1064
1065void
1067 cs_matrix_spmv_type_t op_type,
1068 cs_real_t *x,
1069 cs_real_t *y);
1070
1071#if defined(HAVE_ACCEL)
1072
1073/*----------------------------------------------------------------------------*/
1087/*----------------------------------------------------------------------------*/
1088
1089void
1090cs_matrix_vector_multiply_partial_d(const cs_matrix_t *matrix,
1091 cs_matrix_spmv_type_t op_type,
1092 cs_real_t *x,
1093 cs_real_t *y);
1094
1095#endif /* defined(HAVE_ACCEL) */
1096
1097/*----------------------------------------------------------------------------
1098 * Synchronize ghost values prior to matrix.vector product
1099 *
1100 * parameters:
1101 * matrix <-- pointer to matrix structure
1102 * x <-> multipliying vector values (ghost values updated)
1103 *----------------------------------------------------------------------------*/
1104
1105void
1107 cs_real_t *x);
1108
1109/*----------------------------------------------------------------------------*/
1120/*----------------------------------------------------------------------------*/
1121
1122void
1124 int *n_variants,
1125 cs_matrix_variant_t **m_variant);
1126
1127/*----------------------------------------------------------------------------*/
1136/*----------------------------------------------------------------------------*/
1137
1140
1141/*----------------------------------------------------------------------------
1142 * Destroy a matrix variant structure.
1143 *
1144 * parameters:
1145 * mv <-> Pointer to matrix variant pointer
1146 *----------------------------------------------------------------------------*/
1147
1148void
1150
1151/*----------------------------------------------------------------------------*/
1158/*----------------------------------------------------------------------------*/
1159
1160void
1163
1164/*----------------------------------------------------------------------------*/
1171/*----------------------------------------------------------------------------*/
1172
1173void
1176
1177/*----------------------------------------------------------------------------
1178 * Select the sparse matrix-vector product function to be used by a
1179 * matrix variant for a given fill type.
1180 *
1181 * Currently, possible variant functions are:
1182 *
1183 * CS_MATRIX_NATIVE (all fill types)
1184 * default
1185 * baseline
1186 * omp (for OpenMP with compatible numbering)
1187 * omp_atomic (for OpenMP with atomics)
1188 * vector (For vector machine with compatible numbering)
1189 *
1190 * CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
1191 * default
1192 * mkl (with MKL)
1193 *
1194 * CS_MATRIX_MSR (all fill types)
1195 * default
1196 * mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
1197 * omp_sched (For OpenMP with scheduling)
1198 *
1199 * parameters:
1200 * mv <-> pointer to matrix variant
1201 * numbering <-- mesh numbering info, or nullptr
1202 * fill type <-- matrix fill type to merge from
1203 * spmv_type <-- SpMV operation type (full or sub-matrix)
1204 * (all types if CS_MATRIX_SPMV_N_TYPES)
1205 * func_name <-- function type name
1206 *----------------------------------------------------------------------------*/
1207
1208void
1210 cs_matrix_fill_type_t fill_type,
1211 cs_matrix_spmv_type_t spmv_type,
1212 const cs_numbering_t *numbering,
1213 const char *func_name);
1214
1215/*----------------------------------------------------------------------------*/
1223/*----------------------------------------------------------------------------*/
1224
1227
1228/*----------------------------------------------------------------------------*/
1229
1231
1232#endif /* __CS_MATRIX_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
double cs_real_t
Floating-point value.
Definition: cs_defs.h:342
cs_lnum_t cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:352
cs_real_t cs_real_3_t[3]
vector of 3 floating-point values
Definition: cs_defs.h:359
uint64_t cs_gnum_t
global mesh entity number
Definition: cs_defs.h:325
#define END_C_DECLS
Definition: cs_defs.h:543
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:335
void cs_matrix_row_finalize(cs_matrix_row_info_t *r)
Finalize row info for a given matrix.
Definition: cs_matrix.cpp:5550
void cs_matrix_copy_diagonal(const cs_matrix_t *matrix, cs_real_t *da)
struct _cs_matrix_variant_t cs_matrix_variant_t
Definition: cs_matrix.h:114
bool cs_matrix_is_symmetric(const cs_matrix_t *matrix)
Query matrix coefficients symmetry.
Definition: cs_matrix.cpp:5427
cs_matrix_t * cs_matrix_create_by_copy(cs_matrix_t *src)
Create a matrix container by copying another.
Definition: cs_matrix.cpp:4519
bool cs_matrix_get_need_xa(const cs_matrix_t *matrix)
Query matrix allocation mode.
Definition: cs_matrix.cpp:4937
void cs_matrix_set_coefficients(cs_matrix_t *matrix, bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size, const cs_lnum_t n_edges, const cs_lnum_2_t edges[], const cs_real_t *da, const cs_real_t *xa)
Set matrix coefficients defined relative to a "native" edge graph, sharing arrays with the caller whe...
Definition: cs_matrix.cpp:5041
const cs_real_t * cs_matrix_get_diagonal(const cs_matrix_t *matrix)
Get matrix diagonal values.
Definition: cs_matrix.cpp:5472
cs_matrix_structure_t * cs_matrix_structure_create_msr_shared(bool direct_assmbly, cs_lnum_t n_rows, cs_lnum_t n_cols_ext, const cs_lnum_t *row_index, const cs_lnum_t *col_id, const cs_halo_t *halo, const cs_numbering_t *numbering)
Create an MSR matrix structure sharing an existing connectivity definition.
Definition: cs_matrix.cpp:4319
const char * cs_matrix_spmv_type_name[]
cs_matrix_structure_t * cs_matrix_structure_create_from_assembler(cs_matrix_type_t type, cs_matrix_assembler_t *ma)
Create a matrix structure using a matrix assembler.
Definition: cs_matrix.cpp:4369
const char * cs_matrix_get_type_name(const cs_matrix_t *matrix)
Definition: cs_matrix.cpp:4678
cs_matrix_variant_t * cs_matrix_variant_create(cs_matrix_t *m)
Build matrix variant.
Definition: cs_matrix.cpp:6359
void cs_matrix_set_need_xa(cs_matrix_t *matrix, bool need_xa)
Indicate whether matrix will need xa coefficients.
Definition: cs_matrix.cpp:4957
struct _cs_matrix_structure_t cs_matrix_structure_t
Definition: cs_matrix.h:106
cs_lnum_t cs_matrix_get_extra_diag_block_size(const cs_matrix_t *matrix)
Return the size of the extra-diagonal block for the given matrix.
Definition: cs_matrix.cpp:4826
cs_matrix_spmv_type_t
Definition: cs_matrix.h:95
@ CS_MATRIX_SPMV_N_TYPES
Definition: cs_matrix.h:100
@ CS_MATRIX_SPMV
Definition: cs_matrix.h:97
@ CS_MATRIX_SPMV_E
Definition: cs_matrix.h:98
cs_matrix_type_t cs_matrix_variant_type(const cs_matrix_variant_t *mv)
Get the type associated with a matrix variant.
Definition: cs_matrix.cpp:6780
void cs_matrix_variant_apply_tuned(cs_matrix_t *m, cs_matrix_variant_t *mv)
Apply variants defined by tuning to a given matrix.
Definition: cs_matrix.cpp:6668
void cs_matrix_vector_multiply(const cs_matrix_t *matrix, cs_real_t *x, cs_real_t *y)
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:110
cs_lnum_t cs_matrix_get_n_entries(const cs_matrix_t *matrix)
Return the number of entries in matrix.
Definition: cs_matrix.cpp:4754
void cs_matrix_vector_multiply_nosync(const cs_matrix_t *matrix, cs_real_t *x, cs_real_t *y)
const cs_matrix_assembler_t * cs_matrix_get_assembler(const cs_matrix_t *matrix)
Return matrix assembler if present.
Definition: cs_matrix.cpp:4843
void cs_matrix_transfer_coefficients(cs_matrix_t *matrix, bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size, const cs_lnum_t n_edges, const cs_lnum_2_t edges[], cs_real_t **d_val, cs_real_t **x_val)
Definition: cs_matrix.cpp:5111
void cs_matrix_destroy(cs_matrix_t **matrix)
Definition: cs_matrix.cpp:4629
void cs_matrix_variant_apply(cs_matrix_t *m, cs_matrix_variant_t *mv)
Apply a variant to a given matrix.
Definition: cs_matrix.cpp:6631
const cs_gnum_t * cs_matrix_get_l_range(const cs_matrix_t *matrix)
Return a pointer to local global row range associated with a matrix, if available.
Definition: cs_matrix.cpp:4882
cs_matrix_fill_type_t cs_matrix_get_fill_type(bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size)
Get matrix fill type, depending on block sizes.
Definition: cs_matrix.cpp:4980
cs_matrix_t * cs_matrix_create(const cs_matrix_structure_t *ms)
Create a matrix container using a given structure.
Definition: cs_matrix.cpp:4438
void cs_matrix_variant_set_func(cs_matrix_variant_t *mv, cs_matrix_fill_type_t fill_type, cs_matrix_spmv_type_t spmv_type, const cs_numbering_t *numbering, const char *func_name)
Select the sparse matrix-vector product function to be used by a matrix variant for a given fill type...
Definition: cs_matrix.cpp:6734
void cs_matrix_transfer_coefficients_msr(cs_matrix_t *matrix, bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size, const cs_lnum_t row_index[], const cs_lnum_t col_id[], cs_real_t **d_val, cs_real_t **x_val)
Set matrix coefficients in an MSR format, transferring the property of those arrays to the matrix.
Definition: cs_matrix.cpp:5177
cs_matrix_t * cs_matrix_create_from_assembler(cs_matrix_type_t type, cs_matrix_assembler_t *ma)
Create a matrix directly from assembler.
Definition: cs_matrix.cpp:4472
const char * cs_matrix_get_type_fullname(const cs_matrix_t *matrix)
Definition: cs_matrix.cpp:4694
void cs_matrix_apply_variant(cs_matrix_t *m, const cs_matrix_variant_t *mv)
void cs_matrix_set_alloc_mode(cs_matrix_t *matrix, cs_alloc_mode_t alloc_mode)
Set matrix allocation mode.
Definition: cs_matrix.cpp:4920
void cs_matrix_get_csr_arrays(const cs_matrix_t *matrix, const cs_lnum_t **row_index, const cs_lnum_t **col_id, const cs_real_t **val)
Get arrays describing a matrix in CSR format.
Definition: cs_matrix.cpp:5881
cs_alloc_mode_t cs_matrix_get_alloc_mode(const cs_matrix_t *matrix)
Query matrix allocation mode.
Definition: cs_matrix.cpp:4905
cs_matrix_t * cs_matrix_create_by_local_restrict(const cs_matrix_t *src)
Create a matrix based on the local restriction of a base matrix.
Definition: cs_matrix.cpp:4557
void cs_matrix_set_mesh_association(cs_matrix_t *matrix, const cs_lnum_t *c2f_idx, const cs_lnum_t *c2f, const short int *c2f_sgn, const cs_real_3_t *cell_cen, const cs_real_t *cell_vol, const cs_real_3_t *face_normal)
Associate mesh information with a matrix.
Definition: cs_matrix.cpp:5987
void cs_matrix_get_mesh_association(const cs_matrix_t *matrix, const cs_lnum_t **c2f_idx, const cs_lnum_t **c2f, const short int **c2f_sgn, const cs_real_3_t **cell_cen, const cs_real_t **cell_vol, const cs_real_3_t **face_normal)
Query mesh information that me be associated with a matrix.
Definition: cs_matrix.cpp:6021
void cs_matrix_row_init(cs_matrix_row_info_t *r)
Initialize row info for a given matrix.
Definition: cs_matrix.cpp:5531
void cs_matrix_get_msr_arrays(const cs_matrix_t *matrix, const cs_lnum_t **row_index, const cs_lnum_t **col_id, const cs_real_t **d_val, const cs_real_t **x_val)
Get arrays describing a matrix in MSR format.
Definition: cs_matrix.cpp:5925
cs_matrix_fill_type_t
Definition: cs_matrix.h:72
@ CS_MATRIX_BLOCK_D_66
Definition: cs_matrix.h:78
@ CS_MATRIX_N_FILL_TYPES
Definition: cs_matrix.h:85
@ CS_MATRIX_SCALAR
Definition: cs_matrix.h:74
@ CS_MATRIX_BLOCK_D
Definition: cs_matrix.h:76
@ CS_MATRIX_BLOCK
Definition: cs_matrix.h:84
@ CS_MATRIX_SCALAR_SYM
Definition: cs_matrix.h:75
@ CS_MATRIX_BLOCK_D_SYM
Definition: cs_matrix.h:82
const char * cs_matrix_fill_type_name[]
const cs_halo_t * cs_matrix_get_halo(const cs_matrix_t *matrix)
Return the pointer to the halo structure for the given matrix.
Definition: cs_matrix.cpp:4862
void cs_matrix_vector_multiply_partial(const cs_matrix_t *matrix, cs_matrix_spmv_type_t op_type, cs_real_t *x, cs_real_t *y)
cs_lnum_t cs_matrix_get_diag_block_size(const cs_matrix_t *matrix)
Return the size of the diagonal block for the given matrix.
Definition: cs_matrix.cpp:4807
void cs_matrix_variant_destroy(cs_matrix_variant_t **mv)
Destroy a matrix variant structure.
Definition: cs_matrix.cpp:6615
void cs_matrix_pre_vector_multiply_sync(const cs_matrix_t *matrix, cs_real_t *x)
cs_matrix_assembler_values_t * cs_matrix_assembler_values_init(cs_matrix_t *matrix, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size)
Create and initialize a CSR matrix assembler values structure.
Definition: cs_matrix.cpp:5361
cs_matrix_type_t
Definition: cs_matrix.h:54
@ CS_MATRIX_CSR
Definition: cs_matrix.h:57
@ CS_MATRIX_MSR
Definition: cs_matrix.h:58
@ CS_MATRIX_N_TYPES
Definition: cs_matrix.h:66
@ CS_MATRIX_NATIVE
Definition: cs_matrix.h:56
@ CS_MATRIX_DIST
Definition: cs_matrix.h:60
@ CS_MATRIX_N_BUILTIN_TYPES
Definition: cs_matrix.h:64
void cs_matrix_variant_build_list(const cs_matrix_t *m, int *n_variants, cs_matrix_variant_t **m_variant)
Build list of variants for tuning or testing.
Definition: cs_matrix.cpp:6403
bool cs_matrix_is_mapped_from_native(const cs_matrix_t *matrix)
Indicate whether coefficients were mapped from native face-based arrays.
Definition: cs_matrix.cpp:5448
void cs_matrix_release_coefficients(cs_matrix_t *matrix)
Release shared matrix coefficients.
Definition: cs_matrix.cpp:5317
void cs_matrix_get_row(const cs_matrix_t *matrix, const cs_lnum_t row_id, cs_matrix_row_info_t *r)
Get row values for a given matrix.
Definition: cs_matrix.cpp:5581
cs_matrix_type_t cs_matrix_get_type(const cs_matrix_t *matrix)
Return matrix type.
Definition: cs_matrix.cpp:4663
cs_lnum_t cs_matrix_get_n_rows(const cs_matrix_t *matrix)
Return the number of rows in matrix.
Definition: cs_matrix.cpp:4732
cs_matrix_structure_t * cs_matrix_structure_create_msr(cs_matrix_type_t type, bool transfer, bool have_diag, bool ordered, cs_lnum_t n_rows, cs_lnum_t n_cols_ext, cs_lnum_t **row_index, cs_lnum_t **col_id, const cs_halo_t *halo, const cs_numbering_t *numbering)
Create a matrix structure based on a MSR connectivity definition.
Definition: cs_matrix.cpp:4228
void cs_matrix_structure_destroy(cs_matrix_structure_t **ms)
Destroy a matrix structure.
Definition: cs_matrix.cpp:4410
cs_lnum_t cs_matrix_get_n_columns(const cs_matrix_t *matrix)
Return number of columns in a matrix.
Definition: cs_matrix.cpp:4713
void cs_matrix_get_native_arrays(const cs_matrix_t *matrix, bool *symmetric, cs_lnum_t *n_edges, const cs_lnum_2_t **edges, const cs_real_t **d_val, const cs_real_t **x_val)
Get arrays describing a matrix in native format.
Definition: cs_matrix.cpp:5827
const cs_real_t * cs_matrix_get_extra_diagonal(const cs_matrix_t *matrix)
Get pointer to matrix extra-diagonal values in "native" format.
Definition: cs_matrix.cpp:5507
cs_matrix_structure_t * cs_matrix_structure_create(cs_matrix_type_t type, cs_lnum_t n_rows, cs_lnum_t n_cols_ext, cs_lnum_t n_edges, const cs_lnum_2_t *edges, const cs_halo_t *halo, const cs_numbering_t *numbering)
void cs_matrix_get_coefficients_msr_w(cs_matrix_t *matrix, bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size, cs_real_t **d_val, cs_real_t **x_val)
Directly access matrix coefficients in an MSR format for writing.
Definition: cs_matrix.cpp:5252
struct _cs_matrix_assembler_t cs_matrix_assembler_t
Definition: cs_matrix_assembler.h:61
struct _cs_matrix_assembler_values_t cs_matrix_assembler_values_t
Definition: cs_matrix_assembler.h:65
cs_alloc_mode_t
Definition: cs_mem.h:50
Definition: cs_halo.h:77
Definition: cs_matrix.h:118
cs_lnum_t buffer_size
Definition: cs_matrix.h:121
cs_real_t * _vals
Definition: cs_matrix.h:125
const cs_lnum_t * col_id
Definition: cs_matrix.h:122
cs_lnum_t * _col_id
Definition: cs_matrix.h:123
cs_lnum_t row_size
Definition: cs_matrix.h:120
const cs_real_t * vals
Definition: cs_matrix.h:124
Definition: cs_numbering.h:87