8.1
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-2023 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 
54 typedef enum {
55 
69 
70 /* Matrix fill types (for tuning) */
71 
72 typedef 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 
95 typedef enum {
96 
103 
104 /* Structure associated with opaque matrix structure object */
105 
106 typedef struct _cs_matrix_structure_t cs_matrix_structure_t;
107 
108 /* Structure associated with opaque matrix object */
109 
110 typedef struct _cs_matrix_t cs_matrix_t;
111 
112 /* Structure associated with opaque matrix tuning results object */
113 
114 typedef struct _cs_matrix_variant_t cs_matrix_variant_t;
115 
116 /* Information structure for extraction of matrix row */
117 
118 typedef 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 
135 extern const char *cs_matrix_fill_type_name[];
136 
139 extern 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 NULL
166  * numbering <-- vectorization or thread-related numbering info, or NULL
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 NULL,
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  * have_diag <-- indicates if the structure includes the
198  * diagonal (should be the same for all rows)
199  * n_rows <-- local number of rows
200  * n_cols_ext <-- local number of columns + ghosts
201  * row_index <-> pointer to index on rows
202  * col_id <-> pointer to array of colum ids related to the row index
203  * halo <-- halo structure for synchronization, or NULL
204  * numbering <-- vectorization or thread-related numbering info, or NULL
205  *
206  * returns:
207  * a pointer to a created matrix structure
208  *----------------------------------------------------------------------------*/
209 
212  bool transfer,
213  bool have_diag,
214  cs_lnum_t n_rows,
215  cs_lnum_t n_cols_ext,
216  cs_lnum_t **row_index,
217  cs_lnum_t **col_id,
218  const cs_halo_t *halo,
219  const cs_numbering_t *numbering);
220 
221 /*----------------------------------------------------------------------------
222  * Create an MSR matrix structure sharing an existing connectivity definition.
223  *
224  * Note that as the structure created maps to the given existing
225  * cell global number, face -> cell connectivity arrays, and cell halo
226  * structure, it must be destroyed before they are freed
227  * (usually along with the code's main face -> cell structure).
228  *
229  * parameters:
230  * direct_assembly <-- true if each value corresponds to a unique face
231  * n_rows <-- local number of rows
232  * n_cols_ext <-- local number of columns + ghosts
233  * row_index <-- pointer to index on rows
234  * col_id <-- pointer to array of colum ids related to the row index
235  * halo <-- halo structure for synchronization, or NULL
236  * numbering <-- vectorization or thread-related numbering
237  * info, or NULL
238  *
239  * returns:
240  * a pointer to a created matrix structure
241  *----------------------------------------------------------------------------*/
242 
244 cs_matrix_structure_create_msr_shared(bool direct_assmbly,
245  cs_lnum_t n_rows,
246  cs_lnum_t n_cols_ext,
247  const cs_lnum_t *row_index,
248  const cs_lnum_t *col_id,
249  const cs_halo_t *halo,
250  const cs_numbering_t *numbering);
251 
252 /*----------------------------------------------------------------------------*/
263 /*----------------------------------------------------------------------------*/
264 
268 
269 /*----------------------------------------------------------------------------
270  * Destroy a matrix structure.
271  *
272  * parameters:
273  * ms <-> pointer to matrix structure pointer
274  *----------------------------------------------------------------------------*/
275 
276 void
278 
279 /*----------------------------------------------------------------------------
280  * Create a matrix container using a given structure.
281  *
282  * Note that the matrix container maps to the assigned structure,
283  * so it must be destroyed before that structure.
284  *
285  * parameters:
286  * ms <-- associated matrix structure
287  *
288  * returns:
289  * pointer to created matrix structure;
290  *----------------------------------------------------------------------------*/
291 
292 cs_matrix_t *
294 
295 /*----------------------------------------------------------------------------*/
306 /*----------------------------------------------------------------------------*/
307 
308 cs_matrix_t *
311 
312 /*----------------------------------------------------------------------------*/
325 /*----------------------------------------------------------------------------*/
326 
327 cs_matrix_t *
329 
330 /*----------------------------------------------------------------------------*/
342 /*----------------------------------------------------------------------------*/
343 
344 cs_matrix_t *
346 
347 /*----------------------------------------------------------------------------
348  * Destroy a matrix structure.
349  *
350  * In the case of a compoud matrix, sub-matrices are not destroyed.
351  *
352  * parameters:
353  * matrix <-> pointer to matrix structure pointer
354  *----------------------------------------------------------------------------*/
355 
356 void
358 
359 /*----------------------------------------------------------------------------
360  * Return type of matrix.
361  *
362  * parameters:
363  * matrix --> pointer to matrix structure
364  *----------------------------------------------------------------------------*/
365 
368 
369 /*----------------------------------------------------------------------------
370  * Return matrix type name.
371  *
372  * parameters:
373  * matrix --> pointer to matrix structure
374  *----------------------------------------------------------------------------*/
375 
376 const char *
378 
379 /*----------------------------------------------------------------------------
380  * Return matrix type full name.
381  *
382  * parameters:
383  * matrix --> pointer to matrix structure
384  *----------------------------------------------------------------------------*/
385 
386 const char *
388 
389 /*----------------------------------------------------------------------------*/
397 /*----------------------------------------------------------------------------*/
398 
399 cs_lnum_t
401 
402 /*----------------------------------------------------------------------------*/
410 /*----------------------------------------------------------------------------*/
411 
412 cs_lnum_t
414 
415 /*----------------------------------------------------------------------------*/
426 /*----------------------------------------------------------------------------*/
427 
428 cs_lnum_t
430 
431 /*----------------------------------------------------------------------------*/
439 /*----------------------------------------------------------------------------*/
440 
441 cs_lnum_t
443 
444 /*----------------------------------------------------------------------------*/
452 /*----------------------------------------------------------------------------*/
453 
454 cs_lnum_t
456 
457 /*----------------------------------------------------------------------------*/
465 /*----------------------------------------------------------------------------*/
466 
467 const cs_halo_t *
469 
470 /*----------------------------------------------------------------------------*/
479 /*----------------------------------------------------------------------------*/
480 
481 const cs_gnum_t *
483 
484 /*----------------------------------------------------------------------------*/
492 /*----------------------------------------------------------------------------*/
493 
496 
497 /*----------------------------------------------------------------------------*/
504 /*----------------------------------------------------------------------------*/
505 
506 void
508  cs_alloc_mode_t alloc_mode);
509 
510 /*----------------------------------------------------------------------------
511  * Get matrix fill type, depending on block sizes.
512  *
513  * parameters:
514  * symmetric <-- indicates if matrix coefficients are symmetric
515  * diag_block_size <-- block sizes for diagonal
516  * extra_diag_block_size <-- block sizes for extra diagonal
517  *
518  * returns:
519  * matrix fill type
520  *----------------------------------------------------------------------------*/
521 
523 cs_matrix_get_fill_type(bool symmetric,
524  cs_lnum_t diag_block_size,
525  cs_lnum_t extra_diag_block_size);
526 
527 /*----------------------------------------------------------------------------
528  * Set matrix coefficients defined relative to a "native" edge graph,
529  * sharing arrays with the caller when possible.
530  *
531  * With shared arrays, the matrix becomes unusable if the arrays passed as
532  * arguments are not be modified (its coefficients should be unset first
533  * to mark this).
534  *
535  * Depending on current options and initialization, values will be copied
536  * or simply mapped.
537  *
538  * parameters:
539  * matrix <-> pointer to matrix structure
540  * symmetric <-- indicates if matrix coefficients are symmetric
541  * diag_block_size <-- block sizes for diagonal
542  * extra_diag_block_size <-- block sizes for extra diagonal
543  * n_edges <-- local number of graph edges
544  * edges <-- edges (row <-> column) connectivity
545  * da <-- diagonal values (NULL if zero)
546  * xa <-- extradiagonal values (NULL if zero)
547  * casts as:
548  * xa[n_edges] if symmetric,
549  * xa[n_edges][2] if non symmetric
550  *----------------------------------------------------------------------------*/
551 
552 void
554  bool symmetric,
555  cs_lnum_t diag_block_size,
556  cs_lnum_t extra_diag_block_size,
557  const cs_lnum_t n_edges,
558  const cs_lnum_2_t edges[],
559  const cs_real_t *da,
560  const cs_real_t *xa);
561 
562 /*----------------------------------------------------------------------------
563  * Set matrix coefficients, copying values to private arrays.
564  *
565  * With private arrays, the matrix becomes independant from the
566  * arrays passed as arguments.
567  *
568  * parameters:
569  * matrix <-> pointer to matrix structure
570  * symmetric <-- indicates if matrix coefficients are symmetric
571  * diag_block_size <-- block sizes for diagonal
572  * extra_diag_block_size <-- block sizes for extra diagonal
573  * n_edges <-- local number of graph edges
574  * edges <-- edges (row <-> column) connectivity
575  * da <-- diagonal values (NULL if zero)
576  * xa <-- extradiagonal values (NULL if zero)
577  * casts as:
578  * xa[n_edges] if symmetric,
579  * xa[n_edges][2] if non symmetric
580  *----------------------------------------------------------------------------*/
581 
582 void
584  bool symmetric,
585  cs_lnum_t diag_block_size,
586  cs_lnum_t extra_diag_block_size,
587  const cs_lnum_t n_edges,
588  const cs_lnum_2_t edges[],
589  const cs_real_t *da,
590  const cs_real_t *xa);
591 
592 /*----------------------------------------------------------------------------
593  * Set matrix coefficients in an MSR format, transferring the
594  * property of those arrays to the matrix.
595  *
596  * If the matrix is also in MSR format, this avoids an extra copy.
597  * If it is in a different format, values are copied to the structure,
598  * and the original arrays freed. In any case, the arrays pointers passed as
599  * arguments are set to NULL, to help ensure the caller does not use the
600  * original arrays directly after this call.
601  *
602  * parameters:
603  * matrix <-> pointer to matrix structure
604  * symmetric <-- indicates if matrix coefficients are symmetric
605  * diag_block_size <-- block sizes for diagonal
606  * extra_diag_block_size <-- block sizes for extra diagonal
607  * row_index <-- MSR row index (0 to n-1)
608  * col_id <-- MSR column id (0 to n-1)
609  * d_val <-> diagonal values (NULL if zero)
610  * x_val <-> extradiagonal values (NULL if zero)
611  *----------------------------------------------------------------------------*/
612 
613 void
615  bool symmetric,
616  cs_lnum_t diag_block_size,
617  cs_lnum_t extra_diag_block_size,
618  const cs_lnum_t row_index[],
619  const cs_lnum_t col_id[],
620  cs_real_t **d_val,
621  cs_real_t **x_val);
622 
623 /*----------------------------------------------------------------------------*/
636 /*----------------------------------------------------------------------------*/
637 
640  cs_lnum_t diag_block_size,
641  cs_lnum_t extra_diag_block_size);
642 
643 /*----------------------------------------------------------------------------
644  * Release shared matrix coefficients.
645  *
646  * Pointers to mapped coefficients are set to NULL, while
647  * coefficient copies owned by the matrix are not modified.
648  *
649  * This simply ensures the matrix does not maintain pointers
650  * to nonexistant data.
651  *
652  * parameters:
653  * matrix <-> pointer to matrix structure
654  *----------------------------------------------------------------------------*/
655 
656 void
658 
659 /*----------------------------------------------------------------------------
660  * Copy matrix diagonal values.
661  *
662  * In case of matrixes with block diagonal coefficients, only the true
663  * diagonal values are copied.
664  *
665  * parameters:
666  * matrix --> pointer to matrix structure
667  * da --> diagonal (pre-allocated, size: n_rows*block_size
668  *----------------------------------------------------------------------------*/
669 
670 void
672  cs_real_t *restrict da);
673 
674 /*----------------------------------------------------------------------------
675  * Query matrix coefficients symmetry
676  *
677  * parameters:
678  * matrix <-- pointer to matrix structure
679  *
680  * returns:
681  * true if coefficients are symmetric, false otherwise
682  *----------------------------------------------------------------------------*/
683 
684 bool
686 
687 /*----------------------------------------------------------------------------*/
700 /*----------------------------------------------------------------------------*/
701 
702 bool
704 
705 /*----------------------------------------------------------------------------
706  * Get matrix diagonal values.
707  *
708  * In case of matrixes with block diagonal coefficients, a pointer to
709  * the complete block diagonal is returned.
710  *
711  * parameters:
712  * matrix --> pointer to matrix structure
713  *
714  * returns:
715  * pointer to matrix diagonal array
716  *----------------------------------------------------------------------------*/
717 
718 const cs_real_t *
720 
721 /*----------------------------------------------------------------------------
722  * Get pointer to matrix extra-diagonal values in "native" format
723  *
724  * This function currently only functions if the matrix is in "native"
725  * format or the coefficients were mapped from native coefficients using
726  * cs_matrix_set_coefficients(), in which case the pointer returned is
727  * the same as the one passed to that function.
728  *
729  * parameters:
730  * matrix --> pointer to matrix structure
731  *
732  * returns:
733  * pointer to matrix diagonal array
734  *----------------------------------------------------------------------------*/
735 
736 const cs_real_t *
738 
739 /*----------------------------------------------------------------------------
740  * Initialize row info for a given matrix.
741  *
742  * parameters:
743  * r --> row info structure
744  *----------------------------------------------------------------------------*/
745 
746 void
748 
749 /*----------------------------------------------------------------------------
750  * Finalize row info for a given matrix.
751  *
752  * parameters:
753  * r <-> row info structure
754  *----------------------------------------------------------------------------*/
755 
756 void
758 
759 /*----------------------------------------------------------------------------
760  * Get row values for a given matrix.
761  *
762  * This function may not work for all matrix types.
763  *
764  * In the case of blocked matrixes, the true (non-blocked)
765  * values are returned.
766  *
767  * The row information structure must have been previously initialized
768  * using cs_matrix_row_init(), and should be finalized using
769  * using cs_matrix_row_finalize(), so as to free buffers it may have
770  * built for certain matrix formats.
771  *
772  * parameters:
773  * matrix <-- pointer to matrix structure
774  * row_id <-- id of row to query
775  * r <-> row info structure
776  *----------------------------------------------------------------------------*/
777 
778 void
780  const cs_lnum_t row_id,
782 
783 /*----------------------------------------------------------------------------
784  * Get arrays describing a matrix in native format.
785  *
786  * This function works for matrix in native format.
787  *
788  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
789  * and cs_matrix_get_extra_diag_block_size().
790  *
791  * parameters:
792  * matrix <-- pointer to matrix structure
793  * symmetric --> true if symmetric
794  * n_edges --> number of associated faces
795  * edges --> edges (symmetric row <-> column) connectivity
796  * d_val --> diagonal values
797  * x_val --> extra-diagonal values
798  *----------------------------------------------------------------------------*/
799 
800 void
802  bool *symmetric,
803  cs_lnum_t *n_edges,
804  const cs_lnum_2_t **edges,
805  const cs_real_t **d_val,
806  const cs_real_t **x_val);
807 
808 /*----------------------------------------------------------------------------
809  * Get arrays describing a matrix in CSR format.
810  *
811  * This function only works for an CSR matrix (i.e. there is
812  * no automatic conversion from another matrix type).
813  *
814  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
815  * and cs_matrix_get_extra_diag_block_size().
816  *
817  * parameters:
818  * matrix <-- pointer to matrix structure
819  * row_index --> CSR row index
820  * col_id --> CSR column id
821  * val --> values
822  *----------------------------------------------------------------------------*/
823 
824 void
826  const cs_lnum_t **row_index,
827  const cs_lnum_t **col_id,
828  const cs_real_t **val);
829 
830 /*----------------------------------------------------------------------------
831  * Get arrays describing a matrix in MSR format.
832  *
833  * This function only works for an MSR matrix (i.e. there is
834  * no automatic conversion from another matrix type).
835  *
836  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
837  * and cs_matrix_get_extra_diag_block_size().
838  *
839  * parameters:
840  * matrix <-- pointer to matrix structure
841  * row_index --> MSR row index
842  * col_id --> MSR column id
843  * d_val --> diagonal values
844  * x_val --> extra-diagonal values
845  *----------------------------------------------------------------------------*/
846 
847 void
849  const cs_lnum_t **row_index,
850  const cs_lnum_t **col_id,
851  const cs_real_t **d_val,
852  const cs_real_t **x_val);
853 
854 /*----------------------------------------------------------------------------
855  * Assign functions based on a variant to a given matrix.
856  *
857  * If the matrix variant is incompatible with the structure, it is ignored,
858  * and defaults for that structure are used instead.
859  *
860  * parameters:
861  * m <-> associated matrix structure
862  * mv <-- associated matrix variant
863  *
864  * returns:
865  * pointer to created matrix structure;
866  *----------------------------------------------------------------------------*/
867 
868 void
870  const cs_matrix_variant_t *mv);
871 
872 /*----------------------------------------------------------------------------
873  * Matrix.vector product y = A.x
874  *
875  * This function includes a halo update of x prior to multiplication by A.
876  *
877  * parameters:
878  * matrix --> pointer to matrix structure
879  * x <-> multipliying vector values (ghost values updated)
880  * y --> resulting vector
881  *----------------------------------------------------------------------------*/
882 
883 void
885  cs_real_t *restrict x,
886  cs_real_t *restrict y);
887 
888 #if defined(HAVE_ACCEL)
889 
890 /*----------------------------------------------------------------------------*/
901 /*----------------------------------------------------------------------------*/
902 
903 void
904 cs_matrix_vector_multiply_d(const cs_matrix_t *matrix,
905  cs_real_t *restrict x,
906  cs_real_t *restrict y);
907 
908 #endif /* defined(HAVE_ACCEL) */
909 
910 /*----------------------------------------------------------------------------
911  * Matrix.vector product y = A.x with no prior halo update of x.
912  *
913  * This function does not include a halo update of x prior to multiplication
914  * by A, so it should be called only when the halo of x is known to already
915  * be up to date (in which case we avoid the performance penalty of a
916  * redundant update by using this variant of the matrix.vector product).
917  *
918  * parameters:
919  * matrix --> pointer to matrix structure
920  * x --> multipliying vector values
921  * y <-- resulting vector
922  *----------------------------------------------------------------------------*/
923 
924 void
926  cs_real_t *restrict x,
927  cs_real_t *restrict y);
928 
929 /*----------------------------------------------------------------------------
930  * Partial matrix.vector product.
931  *
932  * This function includes a halo update of x prior to multiplication,
933  * except for the CS_MATRIX_SPMV_L operation type, which does not require it,
934  * as halo adjacencies are only present and useful in the upper-diagonal part..
935  *
936  * parameters:
937  * matrix <-- pointer to matrix structure
938  * op_type <-- SpMV operation type
939  * x <-> multipliying vector values (ghost values updated)
940  * y --> resulting vector
941  *----------------------------------------------------------------------------*/
942 
943 void
945  cs_matrix_spmv_type_t op_type,
946  cs_real_t *restrict x,
947  cs_real_t *restrict y);
948 
949 #if defined(HAVE_ACCEL)
950 
951 /*----------------------------------------------------------------------------*/
965 /*----------------------------------------------------------------------------*/
966 
967 void
968 cs_matrix_vector_multiply_partial_d(const cs_matrix_t *matrix,
969  cs_matrix_spmv_type_t op_type,
970  cs_real_t *restrict x,
971  cs_real_t *restrict y);
972 
973 #endif /* defined(HAVE_ACCEL) */
974 
975 /*----------------------------------------------------------------------------
976  * Synchronize ghost values prior to matrix.vector product
977  *
978  * parameters:
979  * matrix <-- pointer to matrix structure
980  * x <-> multipliying vector values (ghost values updated)
981  *----------------------------------------------------------------------------*/
982 
983 void
985  cs_real_t *x);
986 
987 /*----------------------------------------------------------------------------*/
998 /*----------------------------------------------------------------------------*/
999 
1000 void
1002  int *n_variants,
1003  cs_matrix_variant_t **m_variant);
1004 
1005 /*----------------------------------------------------------------------------*/
1014 /*----------------------------------------------------------------------------*/
1015 
1018 
1019 /*----------------------------------------------------------------------------
1020  * Destroy a matrix variant structure.
1021  *
1022  * parameters:
1023  * mv <-> Pointer to matrix variant pointer
1024  *----------------------------------------------------------------------------*/
1025 
1026 void
1028 
1029 /*----------------------------------------------------------------------------*/
1036 /*----------------------------------------------------------------------------*/
1037 
1038 void
1040  cs_matrix_variant_t *mv);
1041 
1042 /*----------------------------------------------------------------------------*/
1049 /*----------------------------------------------------------------------------*/
1050 
1051 void
1053  cs_matrix_variant_t *mv);
1054 
1055 /*----------------------------------------------------------------------------
1056  * Select the sparse matrix-vector product function to be used by a
1057  * matrix variant for a given fill type.
1058  *
1059  * Currently, possible variant functions are:
1060  *
1061  * CS_MATRIX_NATIVE (all fill types)
1062  * default
1063  * baseline
1064  * omp (for OpenMP with compatible numbering)
1065  * omp_atomic (for OpenMP with atomics)
1066  * vector (For vector machine with compatible numbering)
1067  *
1068  * CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
1069  * default
1070  * mkl (with MKL)
1071  *
1072  * CS_MATRIX_MSR (all fill types)
1073  * default
1074  * mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
1075  * omp_sched (For OpenMP with scheduling)
1076  *
1077  * parameters:
1078  * mv <-> pointer to matrix variant
1079  * numbering <-- mesh numbering info, or NULL
1080  * fill type <-- matrix fill type to merge from
1081  * spmv_type <-- SpMV operation type (full or sub-matrix)
1082  * (all types if CS_MATRIX_SPMV_N_TYPES)
1083  * func_name <-- function type name
1084  *----------------------------------------------------------------------------*/
1085 
1086 void
1088  cs_matrix_fill_type_t fill_type,
1089  cs_matrix_spmv_type_t spmv_type,
1090  const cs_numbering_t *numbering,
1091  const char *func_name);
1092 
1093 /*----------------------------------------------------------------------------*/
1101 /*----------------------------------------------------------------------------*/
1102 
1105 
1106 /*----------------------------------------------------------------------------*/
1107 
1109 
1110 #endif /* __CS_MATRIX_H__ */
cs_alloc_mode_t
Definition: cs_base_accel.h:142
#define restrict
Definition: cs_defs.h:139
#define BEGIN_C_DECLS
Definition: cs_defs.h:514
double cs_real_t
Floating-point value.
Definition: cs_defs.h:319
cs_lnum_t cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:327
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:298
#define END_C_DECLS
Definition: cs_defs.h:515
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:313
void cs_matrix_row_finalize(cs_matrix_row_info_t *r)
Finalize row info for a given matrix.
Definition: cs_matrix.c:5490
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.c:5367
void cs_matrix_copy_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, copying values to private arrays.
Definition: cs_matrix.c:5135
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.c:5076
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)
Create a matrix structure.
Definition: cs_matrix.c:4218
void cs_matrix_vector_multiply_nosync(const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
Matrix.vector product y = A.x with no prior halo update of x.
Definition: cs_matrix.c:6005
const char * cs_matrix_spmv_type_name[]
cs_matrix_variant_t * cs_matrix_variant_create(cs_matrix_t *m)
Build matrix variant.
Definition: cs_matrix.c:6156
const char * cs_matrix_get_type_fullname(const cs_matrix_t *matrix)
Definition: cs_matrix.c:4786
void cs_matrix_copy_diagonal(const cs_matrix_t *matrix, cs_real_t *restrict da)
Copy matrix diagonal values.
Definition: cs_matrix.c:5344
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.c:4918
const cs_real_t * cs_matrix_get_diagonal(const cs_matrix_t *matrix)
Get matrix diagonal values.
Definition: cs_matrix.c:5412
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
void cs_matrix_vector_multiply_partial(const cs_matrix_t *matrix, cs_matrix_spmv_type_t op_type, cs_real_t *restrict x, cs_real_t *restrict y)
Partial matrix.vector product.
Definition: cs_matrix.c:6061
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.c:6557
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.c:6445
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.c:4846
void cs_matrix_destroy(cs_matrix_t **matrix)
Definition: cs_matrix.c:4724
void cs_matrix_variant_apply(cs_matrix_t *m, cs_matrix_variant_t *mv)
Apply a variant to a given matrix.
Definition: cs_matrix.c:6410
cs_matrix_t * cs_matrix_create_by_copy(cs_matrix_t *src)
Create a matrix container by copying another.
Definition: cs_matrix.c:4604
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.c:5015
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.c:5447
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.c:6511
void cs_matrix_vector_multiply(const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
Matrix.vector product y = A.x.
Definition: cs_matrix.c:5915
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.c:5189
cs_matrix_t * cs_matrix_create(const cs_matrix_structure_t *ms)
Create a matrix container using a given structure.
Definition: cs_matrix.c:4523
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.c:4995
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.c:5821
cs_alloc_mode_t cs_matrix_get_alloc_mode(const cs_matrix_t *matrix)
Query matrix allocation mode.
Definition: cs_matrix.c:4980
void cs_matrix_row_init(cs_matrix_row_info_t *r)
Initialize row info for a given matrix.
Definition: cs_matrix.c:5471
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.c:5865
cs_matrix_structure_t * cs_matrix_structure_create_msr(cs_matrix_type_t type, bool transfer, bool have_diag, 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.c:4316
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[]
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.c:4404
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.c:4937
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.c:4557
const char * cs_matrix_get_type_name(const cs_matrix_t *matrix)
Definition: cs_matrix.c:4770
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.c:4899
void cs_matrix_variant_destroy(cs_matrix_variant_t **mv)
Destroy a matrix variant structure.
Definition: cs_matrix.c:6394
void cs_matrix_pre_vector_multiply_sync(const cs_matrix_t *matrix, cs_real_t *x)
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.c:6201
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.c:5388
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.c:5302
void cs_matrix_release_coefficients(cs_matrix_t *matrix)
Release shared matrix coefficients.
Definition: cs_matrix.c:5259
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.c:5521
cs_matrix_type_t cs_matrix_get_type(const cs_matrix_t *matrix)
Return matrix type.
Definition: cs_matrix.c:4755
cs_lnum_t cs_matrix_get_n_rows(const cs_matrix_t *matrix)
Return the number of rows in matrix.
Definition: cs_matrix.c:4824
void cs_matrix_structure_destroy(cs_matrix_structure_t **ms)
Destroy a matrix structure.
Definition: cs_matrix.c:4495
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.c:4655
cs_lnum_t cs_matrix_get_n_columns(const cs_matrix_t *matrix)
Return number of columns in a matrix.
Definition: cs_matrix.c:4805
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.c:5767
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.c:4957
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.c:4454
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
void matrix(const int *iconvp, const int *idiffp, const int *ndircp, const int *isym, const cs_real_t *thetap, const int *imucpp, const cs_real_t coefbp[], const cs_real_t cofbfp[], const cs_real_t rovsdt[], const cs_real_t i_massflux[], const cs_real_t b_massflux[], const cs_real_t i_visc[], const cs_real_t b_visc[], const cs_real_t xcpp[], cs_real_t da[], cs_real_t xa[])
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