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-2016 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_BLOCK_D, /* Matrix with diagonal blocks
71  (and m.I extradiagonal blocks) */
72  CS_MATRIX_BLOCK_D_66, /* Matrix with 6x6 diagonal blocks
73  (and 6.I extradiagonal blocks;
74  subcase of CS_MATRIX_BLOCK_D, allows
75  separate tuning) */
76  CS_MATRIX_BLOCK_D_SYM, /* Symmetric matrix with diagonal blocks
77  (and m.I extradiagonal blocks) */
78  CS_MATRIX_BLOCK, /* Block matrix */
79  CS_MATRIX_N_FILL_TYPES /* Number of possible matrix fill types */
80 
82 
83 /* Structure associated with opaque matrix structure object */
84 
85 typedef struct _cs_matrix_structure_t cs_matrix_structure_t;
86 
87 /* Structure associated with opaque matrix object */
88 
89 typedef struct _cs_matrix_t cs_matrix_t;
90 
91 /* Structure associated with opaque matrix tuning results object */
92 
93 typedef struct _cs_matrix_variant_t cs_matrix_variant_t;
94 
95 /* Information structure for extraction of matrix row */
96 
97 typedef struct {
98 
99  cs_lnum_t row_size; /*< Row size from last call */
100  cs_lnum_t buffer_size; /*< Allocated buffer size */
101  const cs_lnum_t *col_id; /*< Pointer to local column ids */
102  cs_lnum_t *_col_id; /*< Pointer to local column ids copy */
103  const cs_real_t *vals; /*< Pointer to local row values */
104  cs_real_t *_vals; /*< Pointer to local row values copy */
105 
107 
108 /*============================================================================
109  * Global variables
110  *============================================================================*/
111 
112 /* Short names for matrix types */
113 
114 extern const char *cs_matrix_type_name[];
115 
116 /* Full names for matrix types */
117 
118 extern const char *cs_matrix_type_fullname[];
119 
120 /* Fill type names for matrices */
121 
122 extern const char *cs_matrix_fill_type_name[];
123 
124 /*=============================================================================
125  * Public function prototypes
126  *============================================================================*/
127 
128 /*----------------------------------------------------------------------------
129  * Create a matrix structure.
130  *
131  * Note that the structure created usually maps to the given existing
132  * cell global number, face -> cell connectivity arrays, and cell halo
133  * structure, so it must be destroyed before they are freed
134  * (usually along with the code's main face -> cell structure).
135  *
136  * Note that the resulting matrix structure will contain either a full or
137  * an empty main diagonal, and that the extra-diagonal structure is always
138  * symmetric (though the coefficients my not be, and we may choose a
139  * matrix format that does not exploit this symmetry). If the edges
140  * connectivity argument is NULL, the matrix will be purely diagonal.
141  *
142  * parameters:
143  * type <-- type of matrix considered
144  * have_diag <-- indicates if the diagonal structure contains nonzeroes
145  * n_rows <-- local number of rows
146  * n_cols_ext <-- number of columns + ghosts
147  * n_edges <-- local number of (undirected) graph edges
148  * edges <-- edges (symmetric row <-> column) connectivity
149  * halo <-- halo structure associated with cells, or NULL
150  * numbering <-- vectorization or thread-related numbering info, or NULL
151  *
152  * returns:
153  * pointer to created matrix structure;
154  *----------------------------------------------------------------------------*/
155 
158  bool have_diag,
159  cs_lnum_t n_rows,
160  cs_lnum_t n_cols_ext,
161  cs_lnum_t n_edges,
162  const cs_gnum_t *cell_num,
163  const cs_lnum_2_t *edges,
164  const cs_halo_t *halo,
165  const cs_numbering_t *numbering);
166 
167 /*----------------------------------------------------------------------------
168  * Create a matrix structure based on a MSR connectivity definition.
169  *
170  * Only CSR and MSR formats are handled.
171  *
172  * col_id is sorted row by row during the creation of this structure.
173  *
174  * In case the property of the row index and col_id arrays are transferred
175  * to the structure, the arrays pointers passed as arguments are set to NULL,
176  * to help ensure the caller does not use the original arrays directly after
177  * this call.
178  *
179  * parameters:
180  * type <-- type of matrix considered
181  * transfer <-- transfer property of row_index and col_id
182  * if true, map them otherwise
183  * have_diag <-- indicates if the structure includes the
184  * diagonal (should be the same for all rows)
185  * n_rows <-- local number of rows
186  * n_cols_ext <-- local number of columns + ghosts
187  * row_index <-> pointer to index on rows
188  * col_id <-> pointer to array of colum ids related to the row index
189  * halo <-- halo structure for synchronization, or NULL
190  * numbering <-- vectorization or thread-related numbering info, or NULL
191  *
192  * returns:
193  * a pointer to a created matrix structure
194  *----------------------------------------------------------------------------*/
195 
198  bool transfer,
199  bool have_diag,
200  cs_lnum_t n_rows,
201  cs_lnum_t n_cols_ext,
202  cs_lnum_t **row_index,
203  cs_lnum_t **col_id,
204  const cs_halo_t *halo,
205  const cs_numbering_t *numbering);
206 
207 /*----------------------------------------------------------------------------
208  * Create an MSR matrix structure sharing an existing connectivity definition
209  * as well as an optional edge-based definition.
210  *
211  * Note that as the structure created maps to the given existing
212  * cell global number, face -> cell connectivity arrays, and cell halo
213  * structure, it must be destroyed before they are freed
214  * (usually along with the code's main face -> cell structure).
215  *
216  * parameters:
217  * have_diag <-- indicates if the structure includes the
218  * diagonal (should be the same for all rows)
219  * direct_assembly <-- true if each value corresponds to a unique face
220  * n_rows <-- local number of rows
221  * n_cols_ext <-- local number of columns + ghosts
222  * cell_num <-- global cell numbers, or NULL
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
227  * info, or NULL
228  *
229  * returns:
230  * a pointer to a created CDO matrix structure
231  *----------------------------------------------------------------------------*/
232 
235  bool direct_assmbly,
236  cs_lnum_t n_rows,
237  cs_lnum_t n_cols_ext,
238  const cs_gnum_t *cell_num,
239  const cs_lnum_t *row_index,
240  const cs_lnum_t *col_id,
241  const cs_halo_t *halo,
242  const cs_numbering_t *numbering);
243 
244 /*----------------------------------------------------------------------------
245  * Destroy a matrix structure.
246  *
247  * parameters:
248  * ms <-> pointer to matrix structure pointer
249  *----------------------------------------------------------------------------*/
250 
251 void
253 
254 /*----------------------------------------------------------------------------
255  * Create a matrix container using a given structure.
256  *
257  * Note that the matrix container maps to the assigned structure,
258  * so it must be destroyed before that structure.
259  *
260  * parameters:
261  * ms <-- associated matrix structure
262  *
263  * returns:
264  * pointer to created matrix structure;
265  *----------------------------------------------------------------------------*/
266 
267 cs_matrix_t *
269 
270 /*----------------------------------------------------------------------------
271  * Create a matrix container using a given variant.
272  *
273  * If the matrix variant is incompatible with the structure, it is ignored,
274  * and defaults for that structure are used instead.
275  *
276  * parameters:
277  * ms <-- associated matrix structure
278  * mv <-- associated matrix variant
279  *
280  * returns:
281  * pointer to created matrix structure;
282  *----------------------------------------------------------------------------*/
283 
284 cs_matrix_t *
286  const cs_matrix_variant_t *mv);
287 
288 /*----------------------------------------------------------------------------*/
301 /*----------------------------------------------------------------------------*/
302 
303 cs_matrix_t *
305 
306 /*----------------------------------------------------------------------------
307  * Destroy a matrix structure.
308  *
309  * In the case of a compoud matrix, sub-matrices are not destroyed.
310  *
311  * parameters:
312  * matrix <-> pointer to matrix structure pointer
313  *----------------------------------------------------------------------------*/
314 
315 void
317 
318 /*----------------------------------------------------------------------------
319  * Return type of matrix.
320  *
321  * parameters:
322  * matrix --> pointer to matrix structure
323  *----------------------------------------------------------------------------*/
324 
327 
328 /*----------------------------------------------------------------------------
329  * Return number of columns in matrix.
330  *
331  * parameters:
332  * matrix --> pointer to matrix structure
333  *----------------------------------------------------------------------------*/
334 
335 cs_lnum_t
337 
338 /*----------------------------------------------------------------------------
339  * Return number of rows in matrix.
340  *
341  * parameters:
342  * matrix --> pointer to matrix structure
343  *----------------------------------------------------------------------------*/
344 
345 cs_lnum_t
347 
348 /*----------------------------------------------------------------------------
349  * Return matrix diagonal block sizes.
350  *
351  * Block sizes are defined by a array of 4 values:
352  * 0: useful block size, 1: vector block extents,
353  * 2: matrix line extents, 3: matrix line*column extents
354  *
355  * parameters:
356  * matrix <-- pointer to matrix structure
357  *
358  * returns:
359  * pointer to block sizes
360  *----------------------------------------------------------------------------*/
361 
362 const int *
364 
365 /*----------------------------------------------------------------------------
366  * Return matrix extra-diagonal block sizes.
367  *
368  * Block sizes are defined by a array of 4 values:
369  * 0: useful block size, 1: vector block extents,
370  * 2: matrix line extents, 3: matrix line*column extents
371  *
372  * parameters:
373  * matrix <-- pointer to matrix structure
374  *
375  * returns:
376  * pointer to block sizes
377  *----------------------------------------------------------------------------*/
378 
379 const int *
381 
382 /*----------------------------------------------------------------------------
383  * Return pointer to matrix halo structure.
384  *
385  * parameters:
386  * matrix <-- pointer to matrix structure
387  *
388  * returns:
389  * pointer to halo strucuture
390  *----------------------------------------------------------------------------*/
391 
392 const cs_halo_t *
394 
395 /*----------------------------------------------------------------------------
396  * Get matrix fill type, depending on block sizes.
397  *
398  * Block sizes are defined by an optional array of 4 values:
399  * 0: useful block size, 1: vector block extents,
400  * 2: matrix line extents, 3: matrix line*column extents
401  *
402  * parameters:
403  * symmetric <-- indicates if matrix coefficients are symmetric
404  * diag_block_size <-- block sizes for diagonal, or NULL
405  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
406  *
407  * returns:
408  * matrix fill type
409  *----------------------------------------------------------------------------*/
410 
412 cs_matrix_get_fill_type(bool symmetric,
413  const int *diag_block_size,
414  const int *extra_diag_block_size);
415 
416 /*----------------------------------------------------------------------------
417  * Set matrix coefficients defined relative to a "native" edge graph,
418  * sharing arrays with the caller when possible.
419  *
420  * With shared arrays, the matrix becomes unusable if the arrays passed as
421  * arguments are not be modified (its coefficients should be unset first
422  * to mark this).
423  *
424  * Depending on current options and initialization, values will be copied
425  * or simply mapped.
426  *
427  * Block sizes are defined by an optional array of 4 values:
428  * 0: useful block size, 1: vector block extents,
429  * 2: matrix line extents, 3: matrix line*column extents
430  *
431  * parameters:
432  * matrix <-> pointer to matrix structure
433  * symmetric <-- indicates if matrix coefficients are symmetric
434  * diag_block_size <-- block sizes for diagonal, or NULL
435  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
436  * n_edges <-- local number of graph edges
437  * edges <-- edges (row <-> column) connectivity
438  * da <-- diagonal values (NULL if zero)
439  * xa <-- extradiagonal values (NULL if zero)
440  * casts as:
441  * xa[n_edges] if symmetric,
442  * xa[n_edges][2] if non symmetric
443  *----------------------------------------------------------------------------*/
444 
445 void
447  bool symmetric,
448  const int *diag_block_size,
449  const int *extra_diag_block_size,
450  const cs_lnum_t n_edges,
451  const cs_lnum_2_t edges[],
452  const cs_real_t *da,
453  const cs_real_t *xa);
454 
455 /*----------------------------------------------------------------------------
456  * Set matrix coefficients, copying values to private arrays.
457  *
458  * With private arrays, the matrix becomes independant from the
459  * arrays passed as arguments.
460  *
461  * Block sizes are defined by an optional array of 4 values:
462  * 0: useful block size, 1: vector block extents,
463  * 2: matrix line extents, 3: matrix line*column extents
464  *
465  * parameters:
466  * matrix <-> pointer to matrix structure
467  * symmetric <-- indicates if matrix coefficients are symmetric
468  * diag_block_size <-- block sizes for diagonal, or NULL
469  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
470  * n_edges <-- local number of graph edges
471  * edges <-- edges (row <-> column) connectivity
472  * da <-- diagonal values (NULL if zero)
473  * xa <-- extradiagonal values (NULL if zero)
474  * casts as:
475  * xa[n_edges] if symmetric,
476  * xa[n_edges][2] if non symmetric
477  *----------------------------------------------------------------------------*/
478 
479 void
481  bool symmetric,
482  const int *diag_block_size,
483  const int *extra_diag_block_size,
484  const cs_lnum_t n_edges,
485  const cs_lnum_2_t edges[],
486  const cs_real_t *da,
487  const cs_real_t *xa);
488 
489 /*----------------------------------------------------------------------------
490  * Set matrix coefficients in an MSR format, transferring the
491  * property of those arrays to the matrix.
492  *
493  * If the matrix is also in MSR format, this avoids an extra copy.
494  * If it is in a different format, values are copied to the structure,
495  * and the original arrays freed. In any case, the arrays pointers passed as
496  * arguments are set to NULL, to help ensure the caller does not use the
497  * original arrays directly after this call.
498  *
499  * Block sizes are defined by an optional array of 4 values:
500  * 0: useful block size, 1: vector block extents,
501  * 2: matrix line extents, 3: matrix line*column extents
502  *
503  * parameters:
504  * matrix <-> pointer to matrix structure
505  * symmetric <-- indicates if matrix coefficients are symmetric
506  * diag_block_size <-- block sizes for diagonal, or NULL
507  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
508  * row_index <-- MSR row index (0 to n-1)
509  * col_id <-- MSR column id (0 to n-1)
510  * d_val <-> diagonal values (NULL if zero)
511  * x_val <-> extradiagonal values (NULL if zero)
512  *----------------------------------------------------------------------------*/
513 
514 void
516  bool symmetric,
517  const int *diag_block_size,
518  const int *extra_diag_block_size,
519  const cs_lnum_t row_index[],
520  const cs_lnum_t col_id[],
521  cs_real_t **d_val,
522  cs_real_t **x_val);
523 
524 /*----------------------------------------------------------------------------
525  * Release shared matrix coefficients.
526  *
527  * Pointers to mapped coefficients are set to NULL, while
528  * coefficient copies owned by the matrix are not modified.
529  *
530  * This simply ensures the matrix does not maintain pointers
531  * to nonexistant data.
532  *
533  * parameters:
534  * matrix <-> pointer to matrix structure
535  *----------------------------------------------------------------------------*/
536 
537 void
539 
540 /*----------------------------------------------------------------------------
541  * Copy matrix diagonal values.
542  *
543  * In case of matrixes with block diagonal coefficients, only the true
544  * diagonal values are copied.
545  *
546  * parameters:
547  * matrix --> pointer to matrix structure
548  * da --> diagonal (pre-allocated, size: n_rows*block_size
549  *----------------------------------------------------------------------------*/
550 
551 void
553  cs_real_t *restrict da);
554 
555 /*----------------------------------------------------------------------------
556  * Query matrix coefficients symmetry
557  *
558  * parameters:
559  * matrix <-- pointer to matrix structure
560  *
561  * returns:
562  * true if coefficients are symmetric, false otherwise
563  *----------------------------------------------------------------------------*/
564 
565 bool
567 
568 /*----------------------------------------------------------------------------
569  * Get matrix diagonal values.
570  *
571  * In case of matrixes with block diagonal coefficients, a pointer to
572  * the complete block diagonal is returned.
573  *
574  * parameters:
575  * matrix --> pointer to matrix structure
576  *
577  * returns:
578  * pointer to matrix diagonal array
579  *----------------------------------------------------------------------------*/
580 
581 const cs_real_t *
583 
584 /*----------------------------------------------------------------------------
585  * Get pointer to matrix extra-diagonal values in "native" format
586  *
587  * This function currently only functions if the matrix is in "native"
588  * format or the coefficients were mapped from native coefficients using
589  * cs_matrix_set_coefficients(), in which case the pointer returned is
590  * the same as the one passed to that function.
591  *
592  * parameters:
593  * matrix --> pointer to matrix structure
594  *
595  * returns:
596  * pointer to matrix diagonal array
597  *----------------------------------------------------------------------------*/
598 
599 const cs_real_t *
601 
602 /*----------------------------------------------------------------------------
603  * Initialize row info for a given matrix.
604  *
605  * parameters:
606  * r --> row info structure
607  *----------------------------------------------------------------------------*/
608 
609 void
611 
612 /*----------------------------------------------------------------------------
613  * Finalize row info for a given matrix.
614  *
615  * parameters:
616  * r <-> row info structure
617  *----------------------------------------------------------------------------*/
618 
619 void
621 
622 /*----------------------------------------------------------------------------
623  * Get row values for a given matrix.
624  *
625  * This function may not work for all matrix types.
626  *
627  * In the case of blocked matrixes, the true (non-blocked)
628  * values are returned.
629  *
630  * The row information structure must have been previously initialized
631  * using cs_matrix_row_init(), and should be finalized using
632  * using cs_matrix_row_finalize(), so as to free buffers it may have
633  * built for certain matrix formats.
634  *
635  * parameters:
636  * matrix <-- pointer to matrix structure
637  * row_id <-- id of row to query
638  * r <-> row info structure
639  *----------------------------------------------------------------------------*/
640 
641 void
643  const cs_lnum_t row_id,
645 
646 /*----------------------------------------------------------------------------
647  * Get arrays describing a matrix in native format.
648  *
649  * This function works for matrix in native format.
650  *
651  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
652  * and cs_matrix_get_extra_diag_block_size().
653  *
654  * parameters:
655  * matrix <-- pointer to matrix structure
656  * symmetric --> true if symmetric
657  * n_edges --> number of associated faces
658  * edges --> edges (symmetric row <-> column) connectivity
659  * d_val --> diagonal values
660  * x_val --> extra-diagonal values
661  *----------------------------------------------------------------------------*/
662 
663 void
665  bool *symmetric,
666  cs_lnum_t *n_edges,
667  const cs_lnum_2_t **edges,
668  const cs_real_t **d_val,
669  const cs_real_t **x_val);
670 
671 /*----------------------------------------------------------------------------
672  * Get arrays describing a matrix in CSR format.
673  *
674  * This function only works for an CSR matrix (i.e. there is
675  * no automatic conversion from another matrix type).
676  *
677  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
678  * and cs_matrix_get_extra_diag_block_size().
679  *
680  * parameters:
681  * matrix <-- pointer to matrix structure
682  * row_index --> CSR row index
683  * col_id --> CSR column id
684  * val --> values
685  *----------------------------------------------------------------------------*/
686 
687 void
689  const cs_lnum_t **row_index,
690  const cs_lnum_t **col_id,
691  const cs_real_t **val);
692 
693 /*----------------------------------------------------------------------------
694  * Get arrays describing a matrix in MSR format.
695  *
696  * This function only works for an MSR matrix (i.e. there is
697  * no automatic conversion from another matrix type).
698  *
699  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
700  * and cs_matrix_get_extra_diag_block_size().
701  *
702  * parameters:
703  * matrix <-- pointer to matrix structure
704  * row_index --> MSR row index
705  * col_id --> MSR column id
706  * d_val --> diagonal values
707  * x_val --> extra-diagonal values
708  *----------------------------------------------------------------------------*/
709 
710 void
712  const cs_lnum_t **row_index,
713  const cs_lnum_t **col_id,
714  const cs_real_t **d_val,
715  const cs_real_t **x_val);
716 
717 /*----------------------------------------------------------------------------
718  * Matrix.vector product y = A.x
719  *
720  * This function includes a halo update of x prior to multiplication by A.
721  *
722  * parameters:
723  * rotation_mode --> halo update option for rotational periodicity
724  * matrix --> pointer to matrix structure
725  * x <-> multipliying vector values (ghost values updated)
726  * y --> resulting vector
727  *----------------------------------------------------------------------------*/
728 
729 void
731  const cs_matrix_t *matrix,
732  cs_real_t *restrict x,
733  cs_real_t *restrict y);
734 
735 /*----------------------------------------------------------------------------
736  * Matrix.vector product y = A.x with no prior halo update of x.
737  *
738  * This function does not include a halo update of x prior to multiplication
739  * by A, so it should be called only when the halo of x is known to already
740  * be up to date (in which case we avoid the performance penalty of a
741  * redundant update by using this variant of the matrix.vector product).
742  *
743  * parameters:
744  * matrix --> pointer to matrix structure
745  * x --> multipliying vector values
746  * y --> resulting vector
747  *----------------------------------------------------------------------------*/
748 
749 void
751  const cs_real_t *x,
752  cs_real_t *restrict y);
753 
754 /*----------------------------------------------------------------------------
755  * Matrix.vector product y = (A-D).x
756  *
757  * This function includes a halo update of x prior to multiplication by A.
758  *
759  * parameters:
760  * rotation_mode <-- halo update option for rotational periodicity
761  * matrix <-- pointer to matrix structure
762  * x <-> multipliying vector values (ghost values updated)
763  * y --> resulting vector
764  *----------------------------------------------------------------------------*/
765 
766 void
768  const cs_matrix_t *matrix,
769  cs_real_t *restrict x,
770  cs_real_t *restrict y);
771 
772 /*----------------------------------------------------------------------------
773  * Build list of variants for tuning or testing.
774  *
775  * parameters:
776  * n_fill_types <-- number of fill types tuned for
777  * fill_types <-- array of fill types tuned for
778  * type_filter <-- true for matrix types tuned for, false for others
779  * numbering <-- vectorization or thread-related numbering info,
780  * or NULL
781  * n_variants --> number of variants
782  * m_variant --> array of matrix variants
783  *----------------------------------------------------------------------------*/
784 
785 void
786 cs_matrix_variant_build_list(int n_fill_types,
787  cs_matrix_fill_type_t fill_types[],
788  bool type_filter[],
789  const cs_numbering_t *numbering,
790  int *n_variants,
791  cs_matrix_variant_t **m_variant);
792 
793 /*----------------------------------------------------------------------------
794  * Build matrix variant
795  *
796  * The variant will initially use default matrix-vector functions,
797  * which can be later modified using cs_matrix_variant_set_func().
798  *
799  * parameters:
800  * type <-- type of matrix considered
801  * numbering <-- vectorization or thread-related numbering info,
802  * or NULL
803  *----------------------------------------------------------------------------*/
804 
807  const cs_numbering_t *numbering);
808 
809 /*----------------------------------------------------------------------------
810  * Destroy a matrix variant structure.
811  *
812  * parameters:
813  * mv <-> Pointer to matrix variant pointer
814  *----------------------------------------------------------------------------*/
815 
816 void
818 
819 /*----------------------------------------------------------------------------
820  * Select the sparse matrix-vector product function to be used by a
821  * matrix variant for a given fill type.
822  *
823  * Currently, possible variant functions are:
824  *
825  * CS_MATRIX_NATIVE (all fill types)
826  * standard
827  * fixed (for CS_MATRIX_??_BLOCK_D or CS_MATRIX_??_BLOCK_D_SYM)
828  * omp (for OpenMP with compatible numbering)
829  * vector (For vector machine with compatible numbering)
830  *
831  * CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
832  * standard
833  * mkl (with MKL)
834  *
835  * CS_MATRIX_CSR_SYM (for CS_MATRIX_SCALAR_SYM)
836  * standard
837  * mkl (with MKL)
838  *
839  * CS_MATRIX_MSR (all fill types except CS_MATRIX_33_BLOCK)
840  * standard
841  * generic (for CS_MATRIX_??_BLOCK_D or CS_MATRIX_??_BLOCK_D_SYM)
842  * mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
843  *
844  * parameters:
845  * mv <-> pointer to matrix variant
846  * numbering <-- mesh numbering info, or NULL
847  * fill type <-- matrix fill type to merge from
848  * ed_flag <-- 0: with diagonal only, 1 exclude only; 2; both
849  * func_name <-- function type name
850  *----------------------------------------------------------------------------*/
851 
852 void
854  const cs_numbering_t *numbering,
855  cs_matrix_fill_type_t fill_type,
856  int ed_flag,
857  const char *func_name);
858 
859 /*----------------------------------------------------------------------------
860  * Merge a functions to a matrix variant from another variant sharing
861  * the same structure.
862  *
863  * Functions from the structure to merge for the selected fill type are
864  * assigned to the main variant.
865  *
866  * This can be useful when tuning has been done separately for different fill
867  * types, and the resulting selected structure is identical.
868  *
869  * parameters:
870  * mv <-> pointer to matrix variant
871  * mv_merge <-- pointer to matrix variant to merge
872  * fill_type <-- matrix fill type to merge from
873  *----------------------------------------------------------------------------*/
874 
875 void
877  const cs_matrix_variant_t *mv_merge,
878  cs_matrix_fill_type_t fill_type);
879 
880 /*----------------------------------------------------------------------------
881  * Get the type associated with a matrix variant.
882  *
883  * parameters:
884  * mv <-- pointer to matrix variant structure
885  *----------------------------------------------------------------------------*/
886 
889 
890 /*----------------------------------------------------------------------------
891  * Test local matrix.vector product operations.
892  *
893  * parameters:
894  * n_rows <-- number of local rows
895  * n_cols_ext <-- number of columns + ghosts
896  * n_edges <-- local number of (undirected) graph edges
897  * cell_num <-- optional global cell numbers (1 to n), or NULL
898  * edges <-- edges (symmetric row <-> column) connectivity
899  * halo <-- cell halo structure
900  * numbering <-- vectorization or thread-related numbering info, or NULL
901  *----------------------------------------------------------------------------*/
902 
903 void
905  cs_lnum_t n_cols_ext,
906  cs_lnum_t n_edges,
907  const cs_gnum_t *cell_num,
908  const cs_lnum_2_t *edges,
909  const cs_halo_t *halo,
910  const cs_numbering_t *numbering);
911 
912 /*----------------------------------------------------------------------------*/
913 
915 
916 #endif /* __CS_MATRIX_H__ */
cs_lnum_t * _col_id
Definition: cs_matrix.h:102
cs_matrix_t * cs_matrix_create_by_copy(cs_matrix_t *src)
Create a matrix container by copying another.
Definition: cs_matrix.c:5397
const int * cs_matrix_get_diag_block_size(const cs_matrix_t *matrix)
Return matrix diagonal block sizes.
Definition: cs_matrix.c:5556
bool cs_matrix_is_symmetric(const cs_matrix_t *matrix)
Query matrix coefficients symmetry.
Definition: cs_matrix.c:5953
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:5762
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:6373
const cs_halo_t * cs_matrix_get_halo(const cs_matrix_t *matrix)
Return pointer to matrix halo structure.
Definition: cs_matrix.c:5600
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:6420
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_gnum_t *cell_num, 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:5129
void cs_matrix_row_finalize(cs_matrix_row_info_t *r)
Finalize row info for a given matrix.
Definition: cs_matrix.c:6115
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:6568
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:6329
Definition: cs_matrix.h:70
const int * cs_matrix_get_extra_diag_block_size(const cs_matrix_t *matrix)
Return matrix extra-diagonal block sizes.
Definition: cs_matrix.c:5580
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:5822
void cs_matrix_row_init(cs_matrix_row_info_t *r)
Initialize row info for a given matrix.
Definition: cs_matrix.c:6096
cs_matrix_t * cs_matrix_create(const cs_matrix_structure_t *ms)
Create a matrix container using a given structure.
Definition: cs_matrix.c:5232
struct _cs_matrix_variant_t cs_matrix_variant_t
Definition: cs_matrix.h:93
#define BEGIN_C_DECLS
Definition: cs_defs.h:448
void cs_matrix_release_coefficients(cs_matrix_t *matrix)
Release shared matrix coefficients.
Definition: cs_matrix.c:5893
Definition: cs_matrix.h:79
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:5175
void cs_matrix_copy_diagonal(const cs_matrix_t *matrix, cs_real_t *restrict da)
Copy matrix diagonal values.
Definition: cs_matrix.c:5929
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:6146
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:5697
const char * cs_matrix_type_fullname[]
const char * cs_matrix_fill_type_name[]
double cs_real_t
Floating-point value.
Definition: cs_defs.h:296
Definition: cs_matrix.h:78
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:89
Definition: cs_matrix.h:72
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:6891
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:5627
cs_lnum_t row_size
Definition: cs_matrix.h:99
const char * cs_matrix_type_name[]
const cs_lnum_t * col_id
Definition: cs_matrix.h:101
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:4948
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:6275
Definition: cs_matrix.h:58
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:302
const cs_real_t * vals
Definition: cs_matrix.h:103
cs_real_t * _vals
Definition: cs_matrix.h:104
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:6525
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:6940
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:5046
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:5499
cs_lnum_t cs_matrix_get_n_columns(const cs_matrix_t *matrix)
Return number of columns in matrix.
Definition: cs_matrix.c:5516
cs_lnum_t buffer_size
Definition: cs_matrix.h:100
void cs_matrix_destroy(cs_matrix_t **matrix)
Definition: cs_matrix.c:5443
#define END_C_DECLS
Definition: cs_defs.h:449
void cs_matrix_variant_destroy(cs_matrix_variant_t **mv)
Destroy a matrix variant structure.
Definition: cs_matrix.c:6803
Definition: cs_matrix.h:97
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:6489
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:6072
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:5362
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:5533
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:6845
const cs_real_t * cs_matrix_get_diagonal(const cs_matrix_t *matrix)
Get matrix diagonal values.
Definition: cs_matrix.c:5972
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:6917
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:6458
Definition: cs_numbering.h:78
struct _cs_matrix_structure_t cs_matrix_structure_t
Definition: cs_matrix.h:85
cs_matrix_fill_type_t
Definition: cs_matrix.h:66