programmer's 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-2015 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 
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 
56  CS_MATRIX_NATIVE, /* Native matrix format */
57  CS_MATRIX_CSR, /* Compressed Sparse Row storage format */
58  CS_MATRIX_CSR_SYM, /* Compressed Symmetric Sparse Row storage format */
59  CS_MATRIX_MSR, /* Modified Compressed Sparse Row storage format */
60  CS_MATRIX_N_TYPES /* Number of known matrix types */
61 
63 
64 /* Matrix fill types (for tuning) */
65 
66 typedef enum {
67 
68  CS_MATRIX_SCALAR, /* Simple scalar matrix */
69  CS_MATRIX_SCALAR_SYM, /* Simple scalar symmetric matrix */
70  CS_MATRIX_33_BLOCK_D, /* Matrix with 3x3 diagonal blocks
71  (and 3.I extradiagonal blocks) */
72  CS_MATRIX_33_BLOCK_D_SYM, /* Symmetric matrix with 3x3 diagonal blocks
73  (and 3.I extradiagonal blocks) */
74  CS_MATRIX_33_BLOCK, /* Matrix with 3x3 blocks
75  (diagonal and extra-diagonal) */
76  CS_MATRIX_N_FILL_TYPES /* Number of possible matrix fill types */
77 
79 
80 /* Structure associated with opaque matrix structure object */
81 
82 typedef struct _cs_matrix_structure_t cs_matrix_structure_t;
83 
84 /* Structure associated with opaque matrix object */
85 
86 typedef struct _cs_matrix_t cs_matrix_t;
87 
88 /* Structure associated with opaque matrix tuning results object */
89 
90 typedef struct _cs_matrix_variant_t cs_matrix_variant_t;
91 
92 /* Information structure for extraction of matrix row */
93 
94 typedef struct {
95 
96  cs_lnum_t row_size; /*< Row size from last call */
97  cs_lnum_t buffer_size; /*< Allocated buffer size */
98  const cs_lnum_t *col_id; /*< Pointer to local column ids */
99  cs_lnum_t *_col_id; /*< Pointer to local column ids copy */
100  const cs_real_t *vals; /*< Pointer to local row values */
101  cs_real_t *_vals; /*< Pointer to local row values copy */
102 
104 
105 /*============================================================================
106  * Global variables
107  *============================================================================*/
108 
109 /* Short names for matrix types */
110 
111 extern const char *cs_matrix_type_name[];
112 
113 /* Full names for matrix types */
114 
115 extern const char *cs_matrix_type_fullname[];
116 
117 /* Fill type names for matrices */
118 
119 extern const char *cs_matrix_fill_type_name[];
120 
121 /*=============================================================================
122  * Public function prototypes
123  *============================================================================*/
124 
125 /*----------------------------------------------------------------------------
126  * Create a matrix structure.
127  *
128  * Note that the structure created usually maps to the given existing
129  * cell global number, face -> cell connectivity arrays, and cell halo
130  * structure, so it must be destroyed before they are freed
131  * (usually along with the code's main face -> cell structure).
132  *
133  * Note that the resulting matrix structure will contain either a full or
134  * an empty main diagonal, and that the extra-diagonal structure is always
135  * symmetric (though the coefficients my not be, and we may choose a
136  * matrix format that does not exploit this symmetry). If the edges
137  * connectivity argument is NULL, the matrix will be purely diagonal.
138  *
139  * parameters:
140  * type <-- type of matrix considered
141  * have_diag <-- indicates if the diagonal structure contains nonzeroes
142  * n_rows <-- local number of rows
143  * n_cols_ext <-- number of columns + ghosts
144  * n_edges <-- local number of (undirected) graph edges
145  * edges <-- edges (symmetric row <-> column) connectivity
146  * halo <-- halo structure associated with cells, or NULL
147  * numbering <-- vectorization or thread-related numbering info, or NULL
148  *
149  * returns:
150  * pointer to created matrix structure;
151  *----------------------------------------------------------------------------*/
152 
155  bool have_diag,
156  cs_lnum_t n_rows,
157  cs_lnum_t n_cols_ext,
158  cs_lnum_t n_edges,
159  const cs_gnum_t *cell_num,
160  const cs_lnum_2_t *edges,
161  const cs_halo_t *halo,
162  const cs_numbering_t *numbering);
163 
164 /*----------------------------------------------------------------------------
165  * Create a matrix structure based on a MSR connectivity definition.
166  *
167  * Only CSR and MSR formats are handled.
168  *
169  * col_id is sorted row by row during the creation of this structure.
170  *
171  * In case the property of the row index and col_id arrays are transferred
172  * to the structure, the arrays pointers passed as arguments are set to NULL,
173  * to help ensure the caller does not use the original arrays directly after
174  * this call.
175  *
176  * parameters:
177  * type <-- type of matrix considered
178  * transfer <-- transfer property of row_index and col_id
179  * if true, map them otherwise
180  * have_diag <-- indicates if the structure includes the
181  * diagonal (should be the same for all rows)
182  * n_rows <-- local number of rows
183  * n_cols_ext <-- local number of columns + ghosts
184  * row_index <-> pointer to index on rows
185  * col_id <-> pointer to array of colum ids related to the row index
186  * halo <-- halo structure for synchronization, or NULL
187  * numbering <-- vectorization or thread-related numbering info, or NULL
188  *
189  * returns:
190  * a pointer to a created CDO matrix structure
191  *----------------------------------------------------------------------------*/
192 
195  bool transfer,
196  bool have_diag,
197  cs_lnum_t n_rows,
198  cs_lnum_t n_cols_ext,
199  cs_lnum_t **row_index,
200  cs_lnum_t **col_id,
201  const cs_halo_t *halo,
202  const cs_numbering_t *numbering);
203 
204 /*----------------------------------------------------------------------------
205  * Destroy a matrix structure.
206  *
207  * parameters:
208  * ms <-> pointer to matrix structure pointer
209  *----------------------------------------------------------------------------*/
210 
211 void
213 
214 /*----------------------------------------------------------------------------
215  * Create a matrix container using a given structure.
216  *
217  * Note that the matrix container maps to the assigned structure,
218  * so it must be destroyed before that structure.
219  *
220  * parameters:
221  * ms <-- associated matrix structure
222  *
223  * returns:
224  * pointer to created matrix structure;
225  *----------------------------------------------------------------------------*/
226 
227 cs_matrix_t *
229 
230 /*----------------------------------------------------------------------------
231  * Create a matrix container using a given variant.
232  *
233  * If the matrix variant is incompatible with the structure, it is ignored,
234  * and defaults for that structure are used instead.
235  *
236  * parameters:
237  * ms <-- associated matrix structure
238  * mv <-- associated matrix variant
239  *
240  * returns:
241  * pointer to created matrix structure;
242  *----------------------------------------------------------------------------*/
243 
244 cs_matrix_t *
246  const cs_matrix_variant_t *mv);
247 
248 /*----------------------------------------------------------------------------
249  * Destroy a matrix structure.
250  *
251  * In the case of a compoud matrix, sub-matrices are not destroyed.
252  *
253  * parameters:
254  * matrix <-> pointer to matrix structure pointer
255  *----------------------------------------------------------------------------*/
256 
257 void
259 
260 /*----------------------------------------------------------------------------
261  * Return type of matrix.
262  *
263  * parameters:
264  * matrix --> pointer to matrix structure
265  *----------------------------------------------------------------------------*/
266 
269 
270 /*----------------------------------------------------------------------------
271  * Return number of columns in matrix.
272  *
273  * parameters:
274  * matrix --> pointer to matrix structure
275  *----------------------------------------------------------------------------*/
276 
277 cs_lnum_t
279 
280 /*----------------------------------------------------------------------------
281  * Return number of rows in matrix.
282  *
283  * parameters:
284  * matrix --> pointer to matrix structure
285  *----------------------------------------------------------------------------*/
286 
287 cs_lnum_t
289 
290 /*----------------------------------------------------------------------------
291  * Return matrix diagonal block sizes.
292  *
293  * Block sizes are defined by a array of 4 values:
294  * 0: useful block size, 1: vector block extents,
295  * 2: matrix line extents, 3: matrix line*column extents
296  *
297  * parameters:
298  * matrix <-- pointer to matrix structure
299  *
300  * returns:
301  * pointer to block sizes
302  *----------------------------------------------------------------------------*/
303 
304 const int *
306 
307 /*----------------------------------------------------------------------------
308  * Return matrix extra-diagonal block sizes.
309  *
310  * Block sizes are defined by a array of 4 values:
311  * 0: useful block size, 1: vector block extents,
312  * 2: matrix line extents, 3: matrix line*column extents
313  *
314  * parameters:
315  * matrix <-- pointer to matrix structure
316  *
317  * returns:
318  * pointer to block sizes
319  *----------------------------------------------------------------------------*/
320 
321 const int *
323 
324 /*----------------------------------------------------------------------------
325  * Return pointer to matrix halo structure.
326  *
327  * parameters:
328  * matrix <-- pointer to matrix structure
329  *
330  * returns:
331  * pointer to halo strucuture
332  *----------------------------------------------------------------------------*/
333 
334 const cs_halo_t *
336 
337 /*----------------------------------------------------------------------------
338  * Get matrix fill type, depending on block sizes.
339  *
340  * Block sizes are defined by an optional array of 4 values:
341  * 0: useful block size, 1: vector block extents,
342  * 2: matrix line extents, 3: matrix line*column extents
343  *
344  * parameters:
345  * symmetric <-- indicates if matrix coefficients are symmetric
346  * diag_block_size <-- block sizes for diagonal, or NULL
347  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
348  *
349  * returns:
350  * matrix fill type
351  *----------------------------------------------------------------------------*/
352 
354 cs_matrix_get_fill_type(bool symmetric,
355  const int *diag_block_size,
356  const int *extra_diag_block_size);
357 
358 /*----------------------------------------------------------------------------
359  * Set matrix coefficients defined relative to a "native" edge graph,
360  * sharing arrays with the caller when possible.
361  *
362  * With shared arrays, the matrix becomes unusable if the arrays passed as
363  * arguments are not be modified (its coefficients should be unset first
364  * to mark this).
365  *
366  * Depending on current options and initialization, values will be copied
367  * or simply mapped.
368  *
369  * Block sizes are defined by an optional array of 4 values:
370  * 0: useful block size, 1: vector block extents,
371  * 2: matrix line extents, 3: matrix line*column extents
372  *
373  * parameters:
374  * matrix <-> pointer to matrix structure
375  * symmetric <-- indicates if matrix coefficients are symmetric
376  * diag_block_size <-- block sizes for diagonal, or NULL
377  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
378  * n_edges <-- local number of graph edges
379  * edges <-- edges (row <-> column) connectivity
380  * da <-- diagonal values (NULL if zero)
381  * xa <-- extradiagonal values (NULL if zero)
382  * casts as:
383  * xa[n_edges] if symmetric,
384  * xa[n_edges][2] if non symmetric
385  *----------------------------------------------------------------------------*/
386 
387 void
389  bool symmetric,
390  const int *diag_block_size,
391  const int *extra_diag_block_size,
392  const cs_lnum_t n_edges,
393  const cs_lnum_2_t edges[],
394  const cs_real_t *da,
395  const cs_real_t *xa);
396 
397 /*----------------------------------------------------------------------------
398  * Set matrix coefficients, copying values to private arrays.
399  *
400  * With private arrays, the matrix becomes independant from the
401  * arrays passed as arguments.
402  *
403  * Block sizes are defined by an optional array of 4 values:
404  * 0: useful block size, 1: vector block extents,
405  * 2: matrix line extents, 3: matrix line*column extents
406  *
407  * parameters:
408  * matrix <-> pointer to matrix structure
409  * symmetric <-- indicates if matrix coefficients are symmetric
410  * diag_block_size <-- block sizes for diagonal, or NULL
411  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
412  * n_edges <-- local number of graph edges
413  * edges <-- edges (row <-> column) connectivity
414  * da <-- diagonal values (NULL if zero)
415  * xa <-- extradiagonal values (NULL if zero)
416  * casts as:
417  * xa[n_edges] if symmetric,
418  * xa[n_edges][2] if non symmetric
419  *----------------------------------------------------------------------------*/
420 
421 void
423  bool symmetric,
424  const int *diag_block_size,
425  const int *extra_diag_block_size,
426  const cs_lnum_t n_edges,
427  const cs_lnum_2_t edges[],
428  const cs_real_t *da,
429  const cs_real_t *xa);
430 
431 /*----------------------------------------------------------------------------
432  * Set matrix coefficients in an MSR format, transferring the
433  * property of those arrays to the matrix.
434  *
435  * If the matrix is also in MSR format, this avoids an extra copy.
436  * If it is in a different format, values are copied to the structure,
437  * and the original arrays freed. In any case, the arrays pointers passed as
438  * arguments are set to NULL, to help ensure the caller does not use the
439  * original arrays directly after this call.
440  *
441  * Block sizes are defined by an optional array of 4 values:
442  * 0: useful block size, 1: vector block extents,
443  * 2: matrix line extents, 3: matrix line*column extents
444  *
445  * parameters:
446  * matrix <-> pointer to matrix structure
447  * symmetric <-- indicates if matrix coefficients are symmetric
448  * diag_block_size <-- block sizes for diagonal, or NULL
449  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
450  * row_index <-- MSR row index (0 to n-1)
451  * col_id <-- MSR column id (0 to n-1)
452  * d_val <-> diagonal values (NULL if zero)
453  * x_val <-> extradiagonal values (NULL if zero)
454  *----------------------------------------------------------------------------*/
455 
456 void
458  bool symmetric,
459  const int *diag_block_size,
460  const int *extra_diag_block_size,
461  const cs_lnum_t row_index[],
462  const cs_lnum_t col_id[],
463  cs_real_t **d_val,
464  cs_real_t **x_val);
465 
466 /*----------------------------------------------------------------------------
467  * Release shared matrix coefficients.
468  *
469  * Pointers to mapped coefficients are set to NULL, while
470  * coefficient copies owned by the matrix are not modified.
471  *
472  * This simply ensures the matrix does not maintain pointers
473  * to nonexistant data.
474  *
475  * parameters:
476  * matrix <-> pointer to matrix structure
477  *----------------------------------------------------------------------------*/
478 
479 void
481 
482 /*----------------------------------------------------------------------------
483  * Copy matrix diagonal values.
484  *
485  * In case of matrixes with block diagonal coefficients, only the true
486  * diagonal values are copied.
487  *
488  * parameters:
489  * matrix --> pointer to matrix structure
490  * da --> diagonal (pre-allocated, size: n_rows*block_size
491  *----------------------------------------------------------------------------*/
492 
493 void
495  cs_real_t *restrict da);
496 
497 /*----------------------------------------------------------------------------
498  * Query matrix coefficients symmetry
499  *
500  * parameters:
501  * matrix <-- pointer to matrix structure
502  *
503  * returns:
504  * true if coefficients are symmetric, false otherwise
505  *----------------------------------------------------------------------------*/
506 
507 bool
509 
510 /*----------------------------------------------------------------------------
511  * Get matrix diagonal values.
512  *
513  * In case of matrixes with block diagonal coefficients, a pointer to
514  * the complete block diagonal is returned.
515  *
516  * parameters:
517  * matrix --> pointer to matrix structure
518  *
519  * returns:
520  * pointer to matrix diagonal array
521  *----------------------------------------------------------------------------*/
522 
523 const cs_real_t *
525 
526 /*----------------------------------------------------------------------------
527  * Get pointer to matrix extra-diagonal values in "native" format
528  *
529  * This function currently only functions if the matrix is in "native"
530  * format or the coefficients were mapped from native coefficients using
531  * cs_matrix_set_coefficients(), in which case the pointer returned is
532  * the same as the one passed to that function.
533  *
534  * parameters:
535  * matrix --> pointer to matrix structure
536  *
537  * returns:
538  * pointer to matrix diagonal array
539  *----------------------------------------------------------------------------*/
540 
541 const cs_real_t *
543 
544 /*----------------------------------------------------------------------------
545  * Initialize row info for a given matrix.
546  *
547  * parameters:
548  * row_info --> row info structure
549  *----------------------------------------------------------------------------*/
550 
551 void
553 
554 /*----------------------------------------------------------------------------
555  * Finalize row info for a given matrix.
556  *
557  * parameters:
558  * row_info <-> row info structure
559  *----------------------------------------------------------------------------*/
560 
561 void
563 
564 /*----------------------------------------------------------------------------
565  * Get row values for a given matrix.
566  *
567  * This function may not work for all matrix types.
568  *
569  * In the case of blocked matrixes, the true (non-blocked)
570  * values are returned.
571  *
572  * The row information structure must have been previously initialized
573  * using cs_matrix_row_init(), and should be finalized using
574  * using cs_matrix_row_finalize(), so as to free buffers it may have
575  * built for certain matrix formats.
576  *
577  * parameters:
578  * matrix <-- pointer to matrix structure
579  * row_id <-- id of row to query
580  * row_info <-> row info structure
581  *----------------------------------------------------------------------------*/
582 
583 void
585  const cs_lnum_t row_id,
587 
588 /*----------------------------------------------------------------------------
589  * Get arrays describing a matrix in native format.
590  *
591  * This function works for matrix in native format.
592  *
593  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
594  * and cs_matrix_get_extra_diag_block_size().
595  *
596  * parameters:
597  * matrix <-- pointer to matrix structure
598  * symmetric --> true if symmetric
599  * n_edges --> number of associated faces
600  * edges --> edges (symmetric row <-> column) connectivity
601  * d_val --> diagonal values
602  * x_val --> extra-diagonal values
603  *----------------------------------------------------------------------------*/
604 
605 void
607  bool *symmetric,
608  cs_lnum_t *n_edges,
609  const cs_lnum_2_t **edges,
610  const cs_real_t **d_val,
611  const cs_real_t **x_val);
612 
613 /*----------------------------------------------------------------------------
614  * Get arrays describing a matrix in CSR format.
615  *
616  * This function only works for an CSR matrix (i.e. there is
617  * no automatic conversion from another matrix type).
618  *
619  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
620  * and cs_matrix_get_extra_diag_block_size().
621  *
622  * parameters:
623  * matrix <-- pointer to matrix structure
624  * row_index --> CSR row index
625  * col_id --> CSR column id
626  * val --> values
627  *----------------------------------------------------------------------------*/
628 
629 void
631  const cs_lnum_t **row_index,
632  const cs_lnum_t **col_id,
633  const cs_real_t **val);
634 
635 /*----------------------------------------------------------------------------
636  * Get arrays describing a matrix in MSR format.
637  *
638  * This function only works for an MSR matrix (i.e. there is
639  * no automatic conversion from another matrix type).
640  *
641  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
642  * and cs_matrix_get_extra_diag_block_size().
643  *
644  * parameters:
645  * matrix <-- pointer to matrix structure
646  * row_index --> MSR row index
647  * col_id --> MSR column id
648  * d_val --> diagonal values
649  * x_val --> extra-diagonal values
650  *----------------------------------------------------------------------------*/
651 
652 void
654  const cs_lnum_t **row_index,
655  const cs_lnum_t **col_id,
656  const cs_real_t **d_val,
657  const cs_real_t **x_val);
658 
659 /*----------------------------------------------------------------------------
660  * Matrix.vector product y = A.x
661  *
662  * This function includes a halo update of x prior to multiplication by A.
663  *
664  * parameters:
665  * rotation_mode --> halo update option for rotational periodicity
666  * matrix --> pointer to matrix structure
667  * x <-> multipliying vector values (ghost values updated)
668  * y --> resulting vector
669  *----------------------------------------------------------------------------*/
670 
671 void
673  const cs_matrix_t *matrix,
674  cs_real_t *restrict x,
675  cs_real_t *restrict y);
676 
677 /*----------------------------------------------------------------------------
678  * Matrix.vector product y = A.x with no prior halo update of x.
679  *
680  * This function does not include a halo update of x prior to multiplication
681  * by A, so it should be called only when the halo of x is known to already
682  * be up to date (in which case we avoid the performance penalty of a
683  * redundant update by using this variant of the matrix.vector product).
684  *
685  * parameters:
686  * matrix --> pointer to matrix structure
687  * x --> multipliying vector values
688  * y --> resulting vector
689  *----------------------------------------------------------------------------*/
690 
691 void
693  const cs_real_t *x,
694  cs_real_t *restrict y);
695 
696 /*----------------------------------------------------------------------------
697  * Matrix.vector product y = (A-D).x
698  *
699  * This function includes a halo update of x prior to multiplication by A.
700  *
701  * parameters:
702  * rotation_mode <-- halo update option for rotational periodicity
703  * matrix <-- pointer to matrix structure
704  * x <-> multipliying vector values (ghost values updated)
705  * y --> resulting vector
706  *----------------------------------------------------------------------------*/
707 
708 void
710  const cs_matrix_t *matrix,
711  cs_real_t *restrict x,
712  cs_real_t *restrict y);
713 
714 /*----------------------------------------------------------------------------
715  * Build list of variants for tuning or testing.
716  *
717  * parameters:
718  * n_fill_types <-- number of fill types tuned for
719  * fill_types <-- array of fill types tuned for
720  * type_filter <-- true for matrix types tuned for, false for others
721  * numbering <-- vectorization or thread-related numbering info,
722  * or NULL
723  * n_variants --> number of variants
724  * m_variant --> array of matrix variants
725  *----------------------------------------------------------------------------*/
726 
727 void
728 cs_matrix_variant_build_list(int n_fill_types,
729  cs_matrix_fill_type_t fill_types[],
730  bool type_filter[],
731  const cs_numbering_t *numbering,
732  int *n_variants,
733  cs_matrix_variant_t **m_variant);
734 
735 /*----------------------------------------------------------------------------
736  * Build matrix variant
737  *
738  * The variant will initially use default matrix-vector functions,
739  * which can be later modified using cs_matrix_variant_set_func().
740  *
741  * parameters:
742  * type <-- type of matrix considered
743  * numbering <-- vectorization or thread-related numbering info,
744  * or NULL
745  *----------------------------------------------------------------------------*/
746 
749  const cs_numbering_t *numbering);
750 
751 /*----------------------------------------------------------------------------
752  * Destroy a matrix variant structure.
753  *
754  * parameters:
755  * mv <-> Pointer to matrix variant pointer
756  *----------------------------------------------------------------------------*/
757 
758 void
760 
761 /*----------------------------------------------------------------------------
762  * Select the sparse matrix-vector product function to be used by a
763  * matrix variant for a given fill type.
764  *
765  * Currently, possible variant functions are:
766  *
767  * CS_MATRIX_NATIVE (all fill types)
768  * standard
769  * 3_3_diag (for CS_MATRIX_33_BLOCK_D or CS_MATRIX_33_BLOCK_D_SYM)
770  * omp (for OpenMP with compatible numbering)
771  * vector (For vector machine with compatible numbering)
772  *
773  * CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
774  * standard
775  * prefetch
776  * mkl (with MKL)
777  *
778  * CS_MATRIX_CSR_SYM (for CS_MATRIX_SCALAR_SYM)
779  * standard
780  * mkl (with MKL)
781  *
782  * CS_MATRIX_MSR (all fill types except CS_MATRIX_33_BLOCK)
783  * standard
784  * prefetch
785  * mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
786  *
787  * parameters:
788  * mv <-> pointer to matrix variant
789  * numbering <-- mesh numbering info, or NULL
790  * fill type <-- matrix fill type to merge from
791  * ed_flag <-- 0: with diagonal only, 1 exclude only; 2; both
792  * func_name <-- function type name
793  *----------------------------------------------------------------------------*/
794 
795 void
797  const cs_numbering_t *numbering,
798  cs_matrix_fill_type_t fill_type,
799  int ed_flag,
800  const char *func_name);
801 
802 /*----------------------------------------------------------------------------
803  * Merge a functions to a matrix variant from another variant sharing
804  * the same structure.
805  *
806  * Functions from the structure to merge for the selected fill type are
807  * assigned to the main variant.
808  *
809  * This can be useful when tuning has been done separately for different fill
810  * types, and the resulting selected structure is identical.
811  *
812  * parameters:
813  * mv <-> pointer to matrix variant
814  * mv_merge <-- pointer to matrix variant to merge
815  * fill type <-- matrix fill type to merge from
816  *----------------------------------------------------------------------------*/
817 
818 void
820  const cs_matrix_variant_t *mv_merge,
821  cs_matrix_fill_type_t fill_type);
822 
823 /*----------------------------------------------------------------------------
824  * Get the type associated with a matrix variant.
825  *
826  * parameters:
827  * mv <-- pointer to matrix variant structure
828  *----------------------------------------------------------------------------*/
829 
832 
833 /*----------------------------------------------------------------------------
834  * Test local matrix.vector product operations.
835  *
836  * parameters:
837  * n_rows <-- number of local rows
838  * n_cols_ext <-- number of columns + ghosts
839  * n_edges <-- local number of (undirected) graph edges
840  * cell_num <-- optional global cell numbers (1 to n), or NULL
841  * edges <-- edges (symmetric row <-> column) connectivity
842  * halo <-- cell halo structure
843  * numbering <-- vectorization or thread-related numbering info, or NULL
844  *----------------------------------------------------------------------------*/
845 
846 void
848  cs_lnum_t n_cols_ext,
849  cs_lnum_t n_edges,
850  const cs_gnum_t *cell_num,
851  const cs_lnum_2_t *edges,
852  const cs_halo_t *halo,
853  const cs_numbering_t *numbering);
854 
855 /*----------------------------------------------------------------------------*/
856 
858 
859 #endif /* __CS_MATRIX_H__ */
cs_lnum_t * _col_id
Definition: cs_matrix.h:99
const int * cs_matrix_get_diag_block_size(const cs_matrix_t *matrix)
Return matrix diagonal block sizes.
Definition: cs_matrix.c:5252
bool cs_matrix_is_symmetric(const cs_matrix_t *matrix)
Query matrix coefficients symmetry.
Definition: cs_matrix.c:5636
void cs_matrix_copy_coefficients(cs_matrix_t *matrix, bool symmetric, const int *diag_block_size, const int *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:5449
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:280
#define restrict
Definition: cs_defs.h:122
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:6066
const cs_halo_t * cs_matrix_get_halo(const cs_matrix_t *matrix)
Return pointer to matrix halo structure.
Definition: cs_matrix.c:5296
void cs_matrix_vector_multiply(cs_halo_rotation_t rotation_mode, 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:6113
void cs_matrix_row_finalize(cs_matrix_row_info_t *r)
Finalize row info for a given matrix.
Definition: cs_matrix.c:5808
void cs_matrix_variant_build_list(int n_fill_types, cs_matrix_fill_type_t fill_types[], bool type_filter[], const cs_numbering_t *numbering, int *n_variants, cs_matrix_variant_t **m_variant)
Build list of variants for tuning or testing.
Definition: cs_matrix.c:6262
cs_halo_rotation_t
Definition: cs_halo.h:59
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:6022
const int * cs_matrix_get_extra_diag_block_size(const cs_matrix_t *matrix)
Return matrix extra-diagonal block sizes.
Definition: cs_matrix.c:5276
Definition: cs_matrix.h:72
void cs_matrix_transfer_coefficients_msr(cs_matrix_t *matrix, bool symmetric, const int *diag_block_size, const int *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, transfering the property of those arrays to the matrix...
Definition: cs_matrix.c:5507
void cs_matrix_row_init(cs_matrix_row_info_t *r)
Initialize row info for a given matrix.
Definition: cs_matrix.c:5789
cs_matrix_t * cs_matrix_create(const cs_matrix_structure_t *ms)
Create a matrix container using a given structure.
Definition: cs_matrix.c:4980
struct _cs_matrix_variant_t cs_matrix_variant_t
Definition: cs_matrix.h:90
#define BEGIN_C_DECLS
Definition: cs_defs.h:419
void cs_matrix_release_coefficients(cs_matrix_t *matrix)
Release shared matrix coefficients.
Definition: cs_matrix.c:5576
Definition: cs_matrix.h:76
Definition: cs_halo.h:70
void cs_matrix_structure_destroy(cs_matrix_structure_t **ms)
Destroy a matrix structure.
Definition: cs_matrix.c:4923
void cs_matrix_copy_diagonal(const cs_matrix_t *matrix, cs_real_t *restrict da)
Copy matrix diagonal values.
Definition: cs_matrix.c:5612
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:5839
void cs_matrix_set_coefficients(cs_matrix_t *matrix, bool symmetric, const int *diag_block_size, const int *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:5388
const char * cs_matrix_type_fullname[]
const char * cs_matrix_fill_type_name[]
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:86
void cs_matrix_variant_merge(cs_matrix_variant_t *mv, const cs_matrix_variant_t *mv_merge, cs_matrix_fill_type_t fill_type)
Merge a functions to a matrix variant from another variant sharing the same structure.
Definition: cs_matrix.c:6600
cs_matrix_fill_type_t cs_matrix_get_fill_type(bool symmetric, const int *diag_block_size, const int *extra_diag_block_size)
Get matrix fill type, depending on block sizes.
Definition: cs_matrix.c:5323
cs_lnum_t row_size
Definition: cs_matrix.h:96
const char * cs_matrix_type_name[]
const cs_lnum_t * col_id
Definition: cs_matrix.h:98
Definition: cs_matrix.h:70
Definition: cs_matrix.h:60
cs_matrix_type_t
Definition: cs_matrix.h:54
cs_matrix_structure_t * cs_matrix_structure_create(cs_matrix_type_t type, bool have_diag, cs_lnum_t n_rows, cs_lnum_t n_cols_ext, cs_lnum_t n_edges, const cs_gnum_t *cell_num, const cs_lnum_2_t *edges, const cs_halo_t *halo, const cs_numbering_t *numbering)
Create a matrix structure.
Definition: cs_matrix.c:4761
void matrix(const cs_int_t *const iconvp, const cs_int_t *const idiffp, const cs_int_t *const ndircp, const cs_int_t *const isym, const cs_real_t *const thetap, const cs_int_t *const 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_matrix_building.c:111
Definition: cs_matrix.h:68
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:5968
Definition: cs_matrix.h:58
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:301
const cs_real_t * vals
Definition: cs_matrix.h:100
cs_real_t * _vals
Definition: cs_matrix.h:101
cs_matrix_variant_t * cs_matrix_variant_create(cs_matrix_type_t type, const cs_numbering_t *numbering)
Build matrix variant.
Definition: cs_matrix.c:6218
void cs_matrix_variant_test(cs_lnum_t n_rows, cs_lnum_t n_cols_ext, cs_lnum_t n_edges, const cs_gnum_t *cell_num, const cs_lnum_2_t *edges, const cs_halo_t *halo, const cs_numbering_t *numbering)
Test local matrix.vector product operations.
Definition: cs_matrix.c:6649
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:4859
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
cs_matrix_type_t cs_matrix_get_type(const cs_matrix_t *matrix)
Return number of columns in matrix.
Definition: cs_matrix.c:5195
cs_lnum_t cs_matrix_get_n_columns(const cs_matrix_t *matrix)
Return number of columns in matrix.
Definition: cs_matrix.c:5212
cs_lnum_t buffer_size
Definition: cs_matrix.h:97
void cs_matrix_destroy(cs_matrix_t **matrix)
Definition: cs_matrix.c:5139
#define END_C_DECLS
Definition: cs_defs.h:420
void cs_matrix_variant_destroy(cs_matrix_variant_t **mv)
Destroy a matrix variant structure.
Definition: cs_matrix.c:6510
Definition: cs_matrix.h:94
double cs_real_t
Definition: cs_defs.h:296
Definition: cs_matrix.h:74
void cs_matrix_exdiag_vector_multiply(cs_halo_rotation_t rotation_mode, const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
Matrix.vector product y = (A-D).x.
Definition: cs_matrix.c:6182
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:5765
Definition: cs_matrix.h:59
cs_matrix_t * cs_matrix_create_by_variant(const cs_matrix_structure_t *ms, const cs_matrix_variant_t *mv)
Create a matrix container using a given variant.
Definition: cs_matrix.c:5108
Definition: cs_matrix.h:57
cs_lnum_t cs_matrix_get_n_rows(const cs_matrix_t *matrix)
Return number of rows in matrix.
Definition: cs_matrix.c:5229
void cs_matrix_variant_set_func(cs_matrix_variant_t *mv, const cs_numbering_t *numbering, cs_matrix_fill_type_t fill_type, int ed_flag, 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:6553
const cs_real_t * cs_matrix_get_diagonal(const cs_matrix_t *matrix)
Get matrix diagonal values.
Definition: cs_matrix.c:5665
Definition: cs_matrix.h:56
Definition: cs_matrix.h:69
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:6626
void cs_matrix_vector_multiply_nosync(const cs_matrix_t *matrix, const cs_real_t *x, cs_real_t *restrict y)
Matrix.vector product y = A.x with no prior halo update of x.
Definition: cs_matrix.c:6151
Definition: cs_numbering.h:78
struct _cs_matrix_structure_t cs_matrix_structure_t
Definition: cs_matrix.h:82
cs_matrix_fill_type_t
Definition: cs_matrix.h:66