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