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 
109 /*============================================================================
110  * Global variables
111  *============================================================================*/
112 
113 /* Short names for matrix types */
114 
115 extern const char *cs_matrix_type_name[];
116 
117 /* Full names for matrix types */
118 
119 extern const char *cs_matrix_type_fullname[];
120 
121 /* Fill type names for matrices */
122 
123 extern const char *cs_matrix_fill_type_name[];
124 
125 /*=============================================================================
126  * Public function prototypes
127  *============================================================================*/
128 
129 /*----------------------------------------------------------------------------
130  * Create a matrix structure.
131  *
132  * Note that the structure created usually maps to the given existing
133  * cell global number, face -> cell connectivity arrays, and cell halo
134  * structure, so it must be destroyed before they are freed
135  * (usually along with the code's main face -> cell structure).
136  *
137  * Note that the resulting matrix structure will contain either a full or
138  * an empty main diagonal, and that the extra-diagonal structure is always
139  * symmetric (though the coefficients my not be, and we may choose a
140  * matrix format that does not exploit this symmetry). If the edges
141  * connectivity argument is NULL, the matrix will be purely diagonal.
142  *
143  * parameters:
144  * type <-- type of matrix considered
145  * have_diag <-- indicates if the diagonal structure contains nonzeroes
146  * n_rows <-- local number of rows
147  * n_cols_ext <-- number of columns + ghosts
148  * n_edges <-- local number of (undirected) graph edges
149  * edges <-- edges (symmetric row <-> column) connectivity
150  * halo <-- halo structure associated with cells, or NULL
151  * numbering <-- vectorization or thread-related numbering info, or NULL
152  *
153  * returns:
154  * pointer to created matrix structure;
155  *----------------------------------------------------------------------------*/
156 
159  bool have_diag,
160  cs_lnum_t n_rows,
161  cs_lnum_t n_cols_ext,
162  cs_lnum_t n_edges,
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  * row_index <-- pointer to index on rows
223  * col_id <-- pointer to array of colum ids related to the row index
224  * halo <-- halo structure for synchronization, or NULL
225  * numbering <-- vectorization or thread-related numbering
226  * info, or NULL
227  *
228  * returns:
229  * a pointer to a created CDO matrix structure
230  *----------------------------------------------------------------------------*/
231 
234  bool direct_assmbly,
235  cs_lnum_t n_rows,
236  cs_lnum_t n_cols_ext,
237  const cs_lnum_t *row_index,
238  const cs_lnum_t *col_id,
239  const cs_halo_t *halo,
240  const cs_numbering_t *numbering);
241 
242 /*----------------------------------------------------------------------------*/
253 /*----------------------------------------------------------------------------*/
254 
258 
259 /*----------------------------------------------------------------------------
260  * Destroy a matrix structure.
261  *
262  * parameters:
263  * ms <-> pointer to matrix structure pointer
264  *----------------------------------------------------------------------------*/
265 
266 void
268 
269 /*----------------------------------------------------------------------------
270  * Create a matrix container using a given structure.
271  *
272  * Note that the matrix container maps to the assigned structure,
273  * so it must be destroyed before that structure.
274  *
275  * parameters:
276  * ms <-- associated matrix structure
277  *
278  * returns:
279  * pointer to created matrix structure;
280  *----------------------------------------------------------------------------*/
281 
282 cs_matrix_t *
284 
285 /*----------------------------------------------------------------------------
286  * Create a matrix container using a given variant.
287  *
288  * If the matrix variant is incompatible with the structure, it is ignored,
289  * and defaults for that structure are used instead.
290  *
291  * parameters:
292  * ms <-- associated matrix structure
293  * mv <-- associated matrix variant
294  *
295  * returns:
296  * pointer to created matrix structure;
297  *----------------------------------------------------------------------------*/
298 
299 cs_matrix_t *
301  const cs_matrix_variant_t *mv);
302 
303 /*----------------------------------------------------------------------------*/
314 /*----------------------------------------------------------------------------*/
315 
316 cs_matrix_t *
319 
320 /*----------------------------------------------------------------------------*/
333 /*----------------------------------------------------------------------------*/
334 
335 cs_matrix_t *
337 
338 /*----------------------------------------------------------------------------
339  * Destroy a matrix structure.
340  *
341  * In the case of a compoud matrix, sub-matrices are not destroyed.
342  *
343  * parameters:
344  * matrix <-> pointer to matrix structure pointer
345  *----------------------------------------------------------------------------*/
346 
347 void
349 
350 /*----------------------------------------------------------------------------
351  * Return type of matrix.
352  *
353  * parameters:
354  * matrix --> pointer to matrix structure
355  *----------------------------------------------------------------------------*/
356 
359 
360 /*----------------------------------------------------------------------------
361  * Return number of columns in matrix.
362  *
363  * parameters:
364  * matrix --> pointer to matrix structure
365  *----------------------------------------------------------------------------*/
366 
367 cs_lnum_t
369 
370 /*----------------------------------------------------------------------------
371  * Return number of rows in matrix.
372  *
373  * parameters:
374  * matrix --> pointer to matrix structure
375  *----------------------------------------------------------------------------*/
376 
377 cs_lnum_t
379 
380 /*----------------------------------------------------------------------------
381  * Return matrix diagonal block sizes.
382  *
383  * Block sizes are defined by a array of 4 values:
384  * 0: useful block size, 1: vector block extents,
385  * 2: matrix line extents, 3: matrix line*column extents
386  *
387  * parameters:
388  * matrix <-- pointer to matrix structure
389  *
390  * returns:
391  * pointer to block sizes
392  *----------------------------------------------------------------------------*/
393 
394 const cs_lnum_t *
396 
397 /*----------------------------------------------------------------------------
398  * Return matrix extra-diagonal block sizes.
399  *
400  * Block sizes are defined by a array of 4 values:
401  * 0: useful block size, 1: vector block extents,
402  * 2: matrix line extents, 3: matrix line*column extents
403  *
404  * parameters:
405  * matrix <-- pointer to matrix structure
406  *
407  * returns:
408  * pointer to block sizes
409  *----------------------------------------------------------------------------*/
410 
411 const cs_lnum_t *
413 
414 /*----------------------------------------------------------------------------
415  * Return pointer to matrix halo structure.
416  *
417  * parameters:
418  * matrix <-- pointer to matrix structure
419  *
420  * returns:
421  * pointer to halo strucuture
422  *----------------------------------------------------------------------------*/
423 
424 const cs_halo_t *
426 
427 /*----------------------------------------------------------------------------
428  * Get matrix fill type, depending on block sizes.
429  *
430  * Block sizes are defined by an optional array of 4 values:
431  * 0: useful block size, 1: vector block extents,
432  * 2: matrix line extents, 3: matrix line*column extents
433  *
434  * parameters:
435  * symmetric <-- indicates if matrix coefficients are symmetric
436  * diag_block_size <-- block sizes for diagonal, or NULL
437  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
438  *
439  * returns:
440  * matrix fill type
441  *----------------------------------------------------------------------------*/
442 
444 cs_matrix_get_fill_type(bool symmetric,
445  const cs_lnum_t *diag_block_size,
446  const cs_lnum_t *extra_diag_block_size);
447 
448 /*----------------------------------------------------------------------------
449  * Set matrix coefficients defined relative to a "native" edge graph,
450  * sharing arrays with the caller when possible.
451  *
452  * With shared arrays, the matrix becomes unusable if the arrays passed as
453  * arguments are not be modified (its coefficients should be unset first
454  * to mark this).
455  *
456  * Depending on current options and initialization, values will be copied
457  * or simply mapped.
458  *
459  * Block sizes are defined by an optional array of 4 values:
460  * 0: useful block size, 1: vector block extents,
461  * 2: matrix line extents, 3: matrix line*column extents
462  *
463  * parameters:
464  * matrix <-> pointer to matrix structure
465  * symmetric <-- indicates if matrix coefficients are symmetric
466  * diag_block_size <-- block sizes for diagonal, or NULL
467  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
468  * n_edges <-- local number of graph edges
469  * edges <-- edges (row <-> column) connectivity
470  * da <-- diagonal values (NULL if zero)
471  * xa <-- extradiagonal values (NULL if zero)
472  * casts as:
473  * xa[n_edges] if symmetric,
474  * xa[n_edges][2] if non symmetric
475  *----------------------------------------------------------------------------*/
476 
477 void
479  bool symmetric,
480  const cs_lnum_t *diag_block_size,
481  const cs_lnum_t *extra_diag_block_size,
482  const cs_lnum_t n_edges,
483  const cs_lnum_2_t edges[],
484  const cs_real_t *da,
485  const cs_real_t *xa);
486 
487 /*----------------------------------------------------------------------------
488  * Set matrix coefficients, copying values to private arrays.
489  *
490  * With private arrays, the matrix becomes independant from the
491  * arrays passed as arguments.
492  *
493  * Block sizes are defined by an optional array of 4 values:
494  * 0: useful block size, 1: vector block extents,
495  * 2: matrix line extents, 3: matrix line*column extents
496  *
497  * parameters:
498  * matrix <-> pointer to matrix structure
499  * symmetric <-- indicates if matrix coefficients are symmetric
500  * diag_block_size <-- block sizes for diagonal, or NULL
501  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
502  * n_edges <-- local number of graph edges
503  * edges <-- edges (row <-> column) connectivity
504  * da <-- diagonal values (NULL if zero)
505  * xa <-- extradiagonal values (NULL if zero)
506  * casts as:
507  * xa[n_edges] if symmetric,
508  * xa[n_edges][2] if non symmetric
509  *----------------------------------------------------------------------------*/
510 
511 void
513  bool symmetric,
514  const cs_lnum_t *diag_block_size,
515  const cs_lnum_t *extra_diag_block_size,
516  const cs_lnum_t n_edges,
517  const cs_lnum_2_t edges[],
518  const cs_real_t *da,
519  const cs_real_t *xa);
520 
521 /*----------------------------------------------------------------------------
522  * Set matrix coefficients in an MSR format, transferring the
523  * property of those arrays to the matrix.
524  *
525  * If the matrix is also in MSR format, this avoids an extra copy.
526  * If it is in a different format, values are copied to the structure,
527  * and the original arrays freed. In any case, the arrays pointers passed as
528  * arguments are set to NULL, to help ensure the caller does not use the
529  * original arrays directly after this call.
530  *
531  * Block sizes are defined by an optional array of 4 values:
532  * 0: useful block size, 1: vector block extents,
533  * 2: matrix line extents, 3: matrix line*column extents
534  *
535  * parameters:
536  * matrix <-> pointer to matrix structure
537  * symmetric <-- indicates if matrix coefficients are symmetric
538  * diag_block_size <-- block sizes for diagonal, or NULL
539  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
540  * row_index <-- MSR row index (0 to n-1)
541  * col_id <-- MSR column id (0 to n-1)
542  * d_val <-> diagonal values (NULL if zero)
543  * x_val <-> extradiagonal values (NULL if zero)
544  *----------------------------------------------------------------------------*/
545 
546 void
548  bool symmetric,
549  const cs_lnum_t *diag_block_size,
550  const cs_lnum_t *extra_diag_block_size,
551  const cs_lnum_t row_index[],
552  const cs_lnum_t col_id[],
553  cs_real_t **d_val,
554  cs_real_t **x_val);
555 
556 /*----------------------------------------------------------------------------*/
574 /*----------------------------------------------------------------------------*/
575 
578  const cs_lnum_t *diag_block_size,
579  const cs_lnum_t *extra_diag_block_size);
580 
581 /*----------------------------------------------------------------------------
582  * Release shared matrix coefficients.
583  *
584  * Pointers to mapped coefficients are set to NULL, while
585  * coefficient copies owned by the matrix are not modified.
586  *
587  * This simply ensures the matrix does not maintain pointers
588  * to nonexistant data.
589  *
590  * parameters:
591  * matrix <-> pointer to matrix structure
592  *----------------------------------------------------------------------------*/
593 
594 void
596 
597 /*----------------------------------------------------------------------------
598  * Copy matrix diagonal values.
599  *
600  * In case of matrixes with block diagonal coefficients, only the true
601  * diagonal values are copied.
602  *
603  * parameters:
604  * matrix --> pointer to matrix structure
605  * da --> diagonal (pre-allocated, size: n_rows*block_size
606  *----------------------------------------------------------------------------*/
607 
608 void
610  cs_real_t *restrict da);
611 
612 /*----------------------------------------------------------------------------
613  * Query matrix coefficients symmetry
614  *
615  * parameters:
616  * matrix <-- pointer to matrix structure
617  *
618  * returns:
619  * true if coefficients are symmetric, false otherwise
620  *----------------------------------------------------------------------------*/
621 
622 bool
624 
625 /*----------------------------------------------------------------------------
626  * Get matrix diagonal values.
627  *
628  * In case of matrixes with block diagonal coefficients, a pointer to
629  * the complete block diagonal is returned.
630  *
631  * parameters:
632  * matrix --> pointer to matrix structure
633  *
634  * returns:
635  * pointer to matrix diagonal array
636  *----------------------------------------------------------------------------*/
637 
638 const cs_real_t *
640 
641 /*----------------------------------------------------------------------------
642  * Get pointer to matrix extra-diagonal values in "native" format
643  *
644  * This function currently only functions if the matrix is in "native"
645  * format or the coefficients were mapped from native coefficients using
646  * cs_matrix_set_coefficients(), in which case the pointer returned is
647  * the same as the one passed to that function.
648  *
649  * parameters:
650  * matrix --> pointer to matrix structure
651  *
652  * returns:
653  * pointer to matrix diagonal array
654  *----------------------------------------------------------------------------*/
655 
656 const cs_real_t *
658 
659 /*----------------------------------------------------------------------------
660  * Initialize row info for a given matrix.
661  *
662  * parameters:
663  * r --> row info structure
664  *----------------------------------------------------------------------------*/
665 
666 void
668 
669 /*----------------------------------------------------------------------------
670  * Finalize row info for a given matrix.
671  *
672  * parameters:
673  * r <-> row info structure
674  *----------------------------------------------------------------------------*/
675 
676 void
678 
679 /*----------------------------------------------------------------------------
680  * Get row values for a given matrix.
681  *
682  * This function may not work for all matrix types.
683  *
684  * In the case of blocked matrixes, the true (non-blocked)
685  * values are returned.
686  *
687  * The row information structure must have been previously initialized
688  * using cs_matrix_row_init(), and should be finalized using
689  * using cs_matrix_row_finalize(), so as to free buffers it may have
690  * built for certain matrix formats.
691  *
692  * parameters:
693  * matrix <-- pointer to matrix structure
694  * row_id <-- id of row to query
695  * r <-> row info structure
696  *----------------------------------------------------------------------------*/
697 
698 void
700  const cs_lnum_t row_id,
702 
703 /*----------------------------------------------------------------------------
704  * Get arrays describing a matrix in native format.
705  *
706  * This function works for matrix in native format.
707  *
708  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
709  * and cs_matrix_get_extra_diag_block_size().
710  *
711  * parameters:
712  * matrix <-- pointer to matrix structure
713  * symmetric --> true if symmetric
714  * n_edges --> number of associated faces
715  * edges --> edges (symmetric row <-> column) connectivity
716  * d_val --> diagonal values
717  * x_val --> extra-diagonal values
718  *----------------------------------------------------------------------------*/
719 
720 void
722  bool *symmetric,
723  cs_lnum_t *n_edges,
724  const cs_lnum_2_t **edges,
725  const cs_real_t **d_val,
726  const cs_real_t **x_val);
727 
728 /*----------------------------------------------------------------------------
729  * Get arrays describing a matrix in CSR format.
730  *
731  * This function only works for an CSR matrix (i.e. there is
732  * no automatic conversion from another matrix type).
733  *
734  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
735  * and cs_matrix_get_extra_diag_block_size().
736  *
737  * parameters:
738  * matrix <-- pointer to matrix structure
739  * row_index --> CSR row index
740  * col_id --> CSR column id
741  * val --> values
742  *----------------------------------------------------------------------------*/
743 
744 void
746  const cs_lnum_t **row_index,
747  const cs_lnum_t **col_id,
748  const cs_real_t **val);
749 
750 /*----------------------------------------------------------------------------
751  * Get arrays describing a matrix in MSR format.
752  *
753  * This function only works for an MSR matrix (i.e. there is
754  * no automatic conversion from another matrix type).
755  *
756  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
757  * and cs_matrix_get_extra_diag_block_size().
758  *
759  * parameters:
760  * matrix <-- pointer to matrix structure
761  * row_index --> MSR row index
762  * col_id --> MSR column id
763  * d_val --> diagonal values
764  * x_val --> extra-diagonal values
765  *----------------------------------------------------------------------------*/
766 
767 void
769  const cs_lnum_t **row_index,
770  const cs_lnum_t **col_id,
771  const cs_real_t **d_val,
772  const cs_real_t **x_val);
773 
774 /*----------------------------------------------------------------------------
775  * Matrix.vector product y = A.x
776  *
777  * This function includes a halo update of x prior to multiplication by A.
778  *
779  * parameters:
780  * rotation_mode --> halo update option for rotational periodicity
781  * matrix --> pointer to matrix structure
782  * x <-> multipliying vector values (ghost values updated)
783  * y --> resulting vector
784  *----------------------------------------------------------------------------*/
785 
786 void
788  const cs_matrix_t *matrix,
789  cs_real_t *restrict x,
790  cs_real_t *restrict y);
791 
792 /*----------------------------------------------------------------------------
793  * Matrix.vector product y = A.x with no prior halo update of x.
794  *
795  * This function does not include a halo update of x prior to multiplication
796  * by A, so it should be called only when the halo of x is known to already
797  * be up to date (in which case we avoid the performance penalty of a
798  * redundant update by using this variant of the matrix.vector product).
799  *
800  * parameters:
801  * matrix --> pointer to matrix structure
802  * x --> multipliying vector values
803  * y --> resulting vector
804  *----------------------------------------------------------------------------*/
805 
806 void
808  const cs_real_t *x,
809  cs_real_t *restrict y);
810 
811 /*----------------------------------------------------------------------------
812  * Matrix.vector product y = (A-D).x
813  *
814  * This function includes a halo update of x prior to multiplication by A.
815  *
816  * parameters:
817  * rotation_mode <-- halo update option for rotational periodicity
818  * matrix <-- pointer to matrix structure
819  * x <-> multipliying vector values (ghost values updated)
820  * y --> resulting vector
821  *----------------------------------------------------------------------------*/
822 
823 void
825  const cs_matrix_t *matrix,
826  cs_real_t *restrict x,
827  cs_real_t *restrict y);
828 
829 /*----------------------------------------------------------------------------
830  * Synchronize ghost values prior to matrix.vector product
831  *
832  * parameters:
833  * rotation_mode <-- halo update option for rotational periodicity
834  * matrix <-- pointer to matrix structure
835  * x <-> multipliying vector values (ghost values updated)
836  *----------------------------------------------------------------------------*/
837 
838 void
840  const cs_matrix_t *matrix,
841  cs_real_t *x);
842 
843 /*----------------------------------------------------------------------------
844  * Build list of variants for tuning or testing.
845  *
846  * parameters:
847  * n_fill_types <-- number of fill types tuned for
848  * fill_types <-- array of fill types tuned for
849  * type_filter <-- true for matrix types tuned for, false for others
850  * numbering <-- vectorization or thread-related numbering info,
851  * or NULL
852  * n_variants --> number of variants
853  * m_variant --> array of matrix variants
854  *----------------------------------------------------------------------------*/
855 
856 void
857 cs_matrix_variant_build_list(int n_fill_types,
858  cs_matrix_fill_type_t fill_types[],
859  bool type_filter[],
860  const cs_numbering_t *numbering,
861  int *n_variants,
862  cs_matrix_variant_t **m_variant);
863 
864 /*----------------------------------------------------------------------------
865  * Build matrix variant
866  *
867  * The variant will initially use default matrix-vector functions,
868  * which can be later modified using cs_matrix_variant_set_func().
869  *
870  * parameters:
871  * type <-- type of matrix considered
872  * numbering <-- vectorization or thread-related numbering info,
873  * or NULL
874  *----------------------------------------------------------------------------*/
875 
878  const cs_numbering_t *numbering);
879 
880 /*----------------------------------------------------------------------------
881  * Destroy a matrix variant structure.
882  *
883  * parameters:
884  * mv <-> Pointer to matrix variant pointer
885  *----------------------------------------------------------------------------*/
886 
887 void
889 
890 /*----------------------------------------------------------------------------
891  * Select the sparse matrix-vector product function to be used by a
892  * matrix variant for a given fill type.
893  *
894  * Currently, possible variant functions are:
895  *
896  * CS_MATRIX_NATIVE (all fill types)
897  * standard
898  * fixed (for CS_MATRIX_??_BLOCK_D or CS_MATRIX_??_BLOCK_D_SYM)
899  * omp (for OpenMP with compatible numbering)
900  * vector (For vector machine with compatible numbering)
901  *
902  * CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
903  * standard
904  * mkl (with MKL)
905  *
906  * CS_MATRIX_CSR_SYM (for CS_MATRIX_SCALAR_SYM)
907  * standard
908  * mkl (with MKL)
909  *
910  * CS_MATRIX_MSR (all fill types except CS_MATRIX_33_BLOCK)
911  * standard
912  * generic (for CS_MATRIX_??_BLOCK_D or CS_MATRIX_??_BLOCK_D_SYM)
913  * mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
914  *
915  * parameters:
916  * mv <-> pointer to matrix variant
917  * numbering <-- mesh numbering info, or NULL
918  * fill type <-- matrix fill type to merge from
919  * ed_flag <-- 0: with diagonal only, 1 exclude only; 2; both
920  * func_name <-- function type name
921  *----------------------------------------------------------------------------*/
922 
923 void
925  const cs_numbering_t *numbering,
926  cs_matrix_fill_type_t fill_type,
927  int ed_flag,
928  const char *func_name);
929 
930 /*----------------------------------------------------------------------------
931  * Merge a functions to a matrix variant from another variant sharing
932  * the same structure.
933  *
934  * Functions from the structure to merge for the selected fill type are
935  * assigned to the main variant.
936  *
937  * This can be useful when tuning has been done separately for different fill
938  * types, and the resulting selected structure is identical.
939  *
940  * parameters:
941  * mv <-> pointer to matrix variant
942  * mv_merge <-- pointer to matrix variant to merge
943  * fill_type <-- matrix fill type to merge from
944  *----------------------------------------------------------------------------*/
945 
946 void
948  const cs_matrix_variant_t *mv_merge,
949  cs_matrix_fill_type_t fill_type);
950 
951 /*----------------------------------------------------------------------------
952  * Get the type associated with a matrix variant.
953  *
954  * parameters:
955  * mv <-- pointer to matrix variant structure
956  *----------------------------------------------------------------------------*/
957 
960 
961 /*----------------------------------------------------------------------------
962  * Test local matrix.vector product operations.
963  *
964  * parameters:
965  * n_rows <-- number of local rows
966  * n_cols_ext <-- number of columns + ghosts
967  * n_edges <-- local number of (undirected) graph edges
968  * edges <-- edges (symmetric row <-> column) connectivity
969  * halo <-- cell halo structure
970  * numbering <-- vectorization or thread-related numbering info, or NULL
971  *----------------------------------------------------------------------------*/
972 
973 void
975  cs_lnum_t n_cols_ext,
976  cs_lnum_t n_edges,
977  const cs_lnum_2_t *edges,
978  const cs_halo_t *halo,
979  const cs_numbering_t *numbering);
980 
981 /*----------------------------------------------------------------------------*/
982 
984 
985 #endif /* __CS_MATRIX_H__ */
cs_lnum_t * _col_id
Definition: cs_matrix.h:103
const cs_lnum_t * cs_matrix_get_diag_block_size(const cs_matrix_t *matrix)
Return matrix diagonal block sizes.
Definition: cs_matrix.c:6096
cs_matrix_t * cs_matrix_create_by_copy(cs_matrix_t *src)
Create a matrix container by copying another.
Definition: cs_matrix.c:5934
bool cs_matrix_is_symmetric(const cs_matrix_t *matrix)
Query matrix coefficients symmetry.
Definition: cs_matrix.c:6565
#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:6985
const cs_halo_t * cs_matrix_get_halo(const cs_matrix_t *matrix)
Return pointer to matrix halo structure.
Definition: cs_matrix.c:6140
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:7032
void cs_matrix_row_finalize(cs_matrix_row_info_t *r)
Finalize row info for a given matrix.
Definition: cs_matrix.c:6727
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:7201
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:6941
Definition: cs_matrix.h:71
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:6708
void cs_matrix_copy_coefficients(cs_matrix_t *matrix, bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size, const cs_lnum_t n_edges, const cs_lnum_2_t edges[], const cs_real_t *da, const cs_real_t *xa)
Set matrix coefficients, copying values to private arrays.
Definition: cs_matrix.c:6301
cs_matrix_t * cs_matrix_create(const cs_matrix_structure_t *ms)
Create a matrix container using a given structure.
Definition: cs_matrix.c:5819
struct _cs_matrix_variant_t cs_matrix_variant_t
Definition: cs_matrix.h:94
#define BEGIN_C_DECLS
Definition: cs_defs.h:461
void cs_matrix_release_coefficients(cs_matrix_t *matrix)
Release shared matrix coefficients.
Definition: cs_matrix.c:6432
Definition: cs_matrix.h:80
void cs_matrix_transfer_coefficients_msr(cs_matrix_t *matrix, bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size, const cs_lnum_t row_index[], const cs_lnum_t col_id[], cs_real_t **d_val, cs_real_t **x_val)
Set matrix coefficients in an MSR format, transfering the property of those arrays to the matrix...
Definition: cs_matrix.c:6361
Definition: cs_matrix.h:77
cs_matrix_fill_type_t cs_matrix_get_fill_type(bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size)
Get matrix fill type, depending on block sizes.
Definition: cs_matrix.c:6167
Definition: cs_halo.h:71
void cs_matrix_structure_destroy(cs_matrix_structure_t **ms)
Destroy a matrix structure.
Definition: cs_matrix.c:5791
void cs_matrix_copy_diagonal(const cs_matrix_t *matrix, cs_real_t *restrict da)
Copy matrix diagonal values.
Definition: cs_matrix.c:6541
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:6758
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:7522
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_set_coefficients(cs_matrix_t *matrix, bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size, const cs_lnum_t n_edges, const cs_lnum_2_t edges[], const cs_real_t *da, const cs_real_t *xa)
Set matrix coefficients defined relative to a "native" edge graph, sharing arrays with the caller whe...
Definition: cs_matrix.c:6237
const cs_lnum_t * cs_matrix_get_extra_diag_block_size(const cs_matrix_t *matrix)
Return matrix extra-diagonal block sizes.
Definition: cs_matrix.c:6120
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:7570
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:5752
Definition: cs_matrix.h:61
cs_matrix_type_t
Definition: cs_matrix.h:55
cs_matrix_t * cs_matrix_create_from_assembler(cs_matrix_type_t type, cs_matrix_assembler_t *ma)
Create a matrix directly from assembler.
Definition: cs_matrix.c:5887
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:6887
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
void cs_matrix_pre_vector_multiply_sync(cs_halo_rotation_t rotation_mode, const cs_matrix_t *matrix, cs_real_t *x)
Definition: cs_matrix.c:7136
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:7158
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:5617
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 matrix type.
Definition: cs_matrix.c:6039
cs_lnum_t cs_matrix_get_n_columns(const cs_matrix_t *matrix)
Return number of columns in matrix.
Definition: cs_matrix.c:6056
cs_lnum_t buffer_size
Definition: cs_matrix.h:101
void cs_matrix_destroy(cs_matrix_t **matrix)
Definition: cs_matrix.c:5980
#define END_C_DECLS
Definition: cs_defs.h:462
void cs_matrix_variant_destroy(cs_matrix_variant_t **mv)
Destroy a matrix variant structure.
Definition: cs_matrix.c:7434
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:5520
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:7103
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:6684
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:5852
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:6073
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:7476
const cs_real_t * cs_matrix_get_diagonal(const cs_matrix_t *matrix)
Get matrix diagonal values.
Definition: cs_matrix.c:6584
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:5702
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:7548
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:7071
Definition: cs_numbering.h:83
struct _cs_matrix_structure_t cs_matrix_structure_t
Definition: cs_matrix.h:86
cs_matrix_fill_type_t
Definition: cs_matrix.h:67
cs_matrix_assembler_values_t * cs_matrix_assembler_values_init(cs_matrix_t *matrix, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size)
Create and initialize a CSR matrix assembler values structure.
Definition: cs_matrix.c:6476