7.1
general documentation
cs_matrix.h
Go to the documentation of this file.
1 #ifndef __CS_MATRIX_H__
2 #define __CS_MATRIX_H__
3 
4 /*============================================================================
5  * Sparse Matrix Representation and Operations
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2021 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 
67 
68 /* Matrix fill types (for tuning) */
69 
70 typedef enum {
71 
72  CS_MATRIX_SCALAR, /* Simple scalar matrix */
73  CS_MATRIX_SCALAR_SYM, /* Simple scalar symmetric matrix */
74  CS_MATRIX_BLOCK_D, /* Matrix with diagonal blocks
75  (and m.I extradiagonal blocks) */
76  CS_MATRIX_BLOCK_D_66, /* Matrix with 6x6 diagonal blocks
77  (and 6.I extradiagonal blocks;
78  subcase of CS_MATRIX_BLOCK_D, allows
79  separate tuning) */
80  CS_MATRIX_BLOCK_D_SYM, /* Symmetric matrix with diagonal blocks
81  (and m.I extradiagonal blocks) */
82  CS_MATRIX_BLOCK, /* Block matrix */
83  CS_MATRIX_N_FILL_TYPES /* Number of possible matrix fill types */
84 
86 
87 /* Structure associated with opaque matrix structure object */
88 
89 typedef struct _cs_matrix_structure_t cs_matrix_structure_t;
90 
91 /* Structure associated with opaque matrix object */
92 
93 typedef struct _cs_matrix_t cs_matrix_t;
94 
95 /* Structure associated with opaque matrix tuning results object */
96 
97 typedef struct _cs_matrix_variant_t cs_matrix_variant_t;
98 
99 /* Information structure for extraction of matrix row */
100 
101 typedef struct {
102 
103  cs_lnum_t row_size; /*< Row size from last call */
104  cs_lnum_t buffer_size; /*< Allocated buffer size */
105  const cs_lnum_t *col_id; /*< Pointer to local column ids */
106  cs_lnum_t *_col_id; /*< Pointer to local column ids copy */
107  const cs_real_t *vals; /*< Pointer to local row values */
108  cs_real_t *_vals; /*< Pointer to local row values copy */
109 
111 
112 /*============================================================================
113  * Global variables
114  *============================================================================*/
115 
116 /* Fill type names for matrices */
117 
118 extern const char *cs_matrix_fill_type_name[];
119 
120 /*=============================================================================
121  * Public function prototypes
122  *============================================================================*/
123 
124 /*----------------------------------------------------------------------------
125  * Create a matrix structure.
126  *
127  * Note that the structure created usually maps to the given existing
128  * cell global number, face -> cell connectivity arrays, and cell halo
129  * structure, so it must be destroyed before they are freed
130  * (usually along with the code's main face -> cell structure).
131  *
132  * Note that the resulting matrix structure will contain either a full or
133  * an empty main diagonal, and that the extra-diagonal structure is always
134  * symmetric (though the coefficients my not be, and we may choose a
135  * matrix format that does not exploit this symmetry). If the edges
136  * connectivity argument is NULL, the matrix will be purely diagonal.
137  *
138  * parameters:
139  * type <-- type of matrix considered
140  * have_diag <-- indicates if the diagonal structure contains nonzeroes
141  * n_rows <-- local number of rows
142  * n_cols_ext <-- number of columns + ghosts
143  * n_edges <-- local number of (undirected) graph edges
144  * edges <-- edges (symmetric row <-> column) connectivity
145  * halo <-- halo structure associated with cells, or NULL
146  * numbering <-- vectorization or thread-related numbering info, or NULL
147  *
148  * returns:
149  * pointer to created matrix structure;
150  *----------------------------------------------------------------------------*/
151 
154  bool have_diag,
155  cs_lnum_t n_rows,
156  cs_lnum_t n_cols_ext,
157  cs_lnum_t n_edges,
158  const cs_lnum_2_t *edges,
159  const cs_halo_t *halo,
160  const cs_numbering_t *numbering);
161 
162 /*----------------------------------------------------------------------------
163  * Create a matrix structure based on a MSR connectivity definition.
164  *
165  * Only CSR and MSR formats are handled.
166  *
167  * col_id is sorted row by row during the creation of this structure.
168  *
169  * In case the property of the row index and col_id arrays are transferred
170  * to the structure, the arrays pointers passed as arguments are set to NULL,
171  * to help ensure the caller does not use the original arrays directly after
172  * this call.
173  *
174  * parameters:
175  * type <-- type of matrix considered
176  * transfer <-- transfer property of row_index and col_id
177  * if true, map them otherwise
178  * have_diag <-- indicates if the structure includes the
179  * diagonal (should be the same for all rows)
180  * n_rows <-- local number of rows
181  * n_cols_ext <-- local number of columns + ghosts
182  * row_index <-> pointer to index on rows
183  * col_id <-> pointer to array of colum ids related to the row index
184  * halo <-- halo structure for synchronization, or NULL
185  * numbering <-- vectorization or thread-related numbering info, or NULL
186  *
187  * returns:
188  * a pointer to a created matrix structure
189  *----------------------------------------------------------------------------*/
190 
193  bool transfer,
194  bool have_diag,
195  cs_lnum_t n_rows,
196  cs_lnum_t n_cols_ext,
197  cs_lnum_t **row_index,
198  cs_lnum_t **col_id,
199  const cs_halo_t *halo,
200  const cs_numbering_t *numbering);
201 
202 /*----------------------------------------------------------------------------
203  * Create an MSR matrix structure sharing an existing connectivity definition.
204  *
205  * Note that as the structure created maps to the given existing
206  * cell global number, face -> cell connectivity arrays, and cell halo
207  * structure, it must be destroyed before they are freed
208  * (usually along with the code's main face -> cell structure).
209  *
210  * parameters:
211  * have_diag <-- indicates if the structure includes the
212  * diagonal (should be the same for all rows)
213  * direct_assembly <-- true if each value corresponds to a unique face
214  * n_rows <-- local number of rows
215  * n_cols_ext <-- local number of columns + ghosts
216  * row_index <-- pointer to index on rows
217  * col_id <-- pointer to array of colum ids related to the row index
218  * halo <-- halo structure for synchronization, or NULL
219  * numbering <-- vectorization or thread-related numbering
220  * info, or NULL
221  *
222  * returns:
223  * a pointer to a created matrix structure
224  *----------------------------------------------------------------------------*/
225 
228  bool direct_assmbly,
229  cs_lnum_t n_rows,
230  cs_lnum_t n_cols_ext,
231  const cs_lnum_t *row_index,
232  const cs_lnum_t *col_id,
233  const cs_halo_t *halo,
234  const cs_numbering_t *numbering);
235 
236 /*----------------------------------------------------------------------------*/
247 /*----------------------------------------------------------------------------*/
248 
252 
253 /*----------------------------------------------------------------------------
254  * Destroy a matrix structure.
255  *
256  * parameters:
257  * ms <-> pointer to matrix structure pointer
258  *----------------------------------------------------------------------------*/
259 
260 void
262 
263 /*----------------------------------------------------------------------------
264  * Create a matrix container using a given structure.
265  *
266  * Note that the matrix container maps to the assigned structure,
267  * so it must be destroyed before that structure.
268  *
269  * parameters:
270  * ms <-- associated matrix structure
271  *
272  * returns:
273  * pointer to created matrix structure;
274  *----------------------------------------------------------------------------*/
275 
276 cs_matrix_t *
278 
279 /*----------------------------------------------------------------------------*/
290 /*----------------------------------------------------------------------------*/
291 
292 cs_matrix_t *
295 
296 /*----------------------------------------------------------------------------*/
309 /*----------------------------------------------------------------------------*/
310 
311 cs_matrix_t *
313 
314 /*----------------------------------------------------------------------------*/
326 /*----------------------------------------------------------------------------*/
327 
328 cs_matrix_t *
330 
331 /*----------------------------------------------------------------------------
332  * Destroy a matrix structure.
333  *
334  * In the case of a compoud matrix, sub-matrices are not destroyed.
335  *
336  * parameters:
337  * matrix <-> pointer to matrix structure pointer
338  *----------------------------------------------------------------------------*/
339 
340 void
342 
343 /*----------------------------------------------------------------------------
344  * Return type of matrix.
345  *
346  * parameters:
347  * matrix --> pointer to matrix structure
348  *----------------------------------------------------------------------------*/
349 
352 
353 /*----------------------------------------------------------------------------
354  * Return matrix type name.
355  *
356  * parameters:
357  * matrix --> pointer to matrix structure
358  *----------------------------------------------------------------------------*/
359 
360 const char *
362 
363 /*----------------------------------------------------------------------------
364  * Return matrix type full name.
365  *
366  * parameters:
367  * matrix --> pointer to matrix structure
368  *----------------------------------------------------------------------------*/
369 
370 const char *
372 
373 /*----------------------------------------------------------------------------
374  * Return number of columns in matrix.
375  *
376  * parameters:
377  * matrix --> pointer to matrix structure
378  *----------------------------------------------------------------------------*/
379 
380 cs_lnum_t
382 
383 /*----------------------------------------------------------------------------
384  * Return number of rows in matrix.
385  *
386  * parameters:
387  * matrix --> pointer to matrix structure
388  *----------------------------------------------------------------------------*/
389 
390 cs_lnum_t
392 
393 /*----------------------------------------------------------------------------
394  * Return number of entries in matrix.
395  *
396  * When the block size is > 1, the number reported is the number of
397  * entry blocks, not individual entries.
398  *
399  * parameters:
400  * matrix --> pointer to matrix structure
401  *----------------------------------------------------------------------------*/
402 
403 cs_lnum_t
405 
406 /*----------------------------------------------------------------------------
407  * Return matrix diagonal block sizes.
408  *
409  * Block sizes are defined by a array of 4 values:
410  * 0: useful block size, 1: vector block extents,
411  * 2: matrix line extents, 3: matrix line*column extents
412  *
413  * parameters:
414  * matrix <-- pointer to matrix structure
415  *
416  * returns:
417  * pointer to block sizes
418  *----------------------------------------------------------------------------*/
419 
420 const cs_lnum_t *
422 
423 /*----------------------------------------------------------------------------
424  * Return matrix extra-diagonal block sizes.
425  *
426  * Block sizes are defined by a array of 4 values:
427  * 0: useful block size, 1: vector block extents,
428  * 2: matrix line extents, 3: matrix line*column extents
429  *
430  * parameters:
431  * matrix <-- pointer to matrix structure
432  *
433  * returns:
434  * pointer to block sizes
435  *----------------------------------------------------------------------------*/
436 
437 const cs_lnum_t *
439 
440 /*----------------------------------------------------------------------------
441  * Return pointer to matrix halo structure.
442  *
443  * parameters:
444  * matrix <-- pointer to matrix structure
445  *
446  * returns:
447  * pointer to halo strucuture
448  *----------------------------------------------------------------------------*/
449 
450 const cs_halo_t *
452 
453 /*----------------------------------------------------------------------------
454  * Get matrix fill type, depending on block sizes.
455  *
456  * Block sizes are defined by an optional array of 4 values:
457  * 0: useful block size, 1: vector block extents,
458  * 2: matrix line extents, 3: matrix line*column extents
459  *
460  * parameters:
461  * symmetric <-- indicates if matrix coefficients are symmetric
462  * diag_block_size <-- block sizes for diagonal, or NULL
463  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
464  *
465  * returns:
466  * matrix fill type
467  *----------------------------------------------------------------------------*/
468 
470 cs_matrix_get_fill_type(bool symmetric,
471  const cs_lnum_t *diag_block_size,
472  const cs_lnum_t *extra_diag_block_size);
473 
474 /*----------------------------------------------------------------------------
475  * Set matrix coefficients defined relative to a "native" edge graph,
476  * sharing arrays with the caller when possible.
477  *
478  * With shared arrays, the matrix becomes unusable if the arrays passed as
479  * arguments are not be modified (its coefficients should be unset first
480  * to mark this).
481  *
482  * Depending on current options and initialization, values will be copied
483  * or simply mapped.
484  *
485  * Block sizes are defined by an optional array of 4 values:
486  * 0: useful block size, 1: vector block extents,
487  * 2: matrix line extents, 3: matrix line*column extents
488  *
489  * parameters:
490  * matrix <-> pointer to matrix structure
491  * symmetric <-- indicates if matrix coefficients are symmetric
492  * diag_block_size <-- block sizes for diagonal, or NULL
493  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
494  * n_edges <-- local number of graph edges
495  * edges <-- edges (row <-> column) connectivity
496  * da <-- diagonal values (NULL if zero)
497  * xa <-- extradiagonal values (NULL if zero)
498  * casts as:
499  * xa[n_edges] if symmetric,
500  * xa[n_edges][2] if non symmetric
501  *----------------------------------------------------------------------------*/
502 
503 void
505  bool symmetric,
506  const cs_lnum_t *diag_block_size,
507  const cs_lnum_t *extra_diag_block_size,
508  const cs_lnum_t n_edges,
509  const cs_lnum_2_t edges[],
510  const cs_real_t *da,
511  const cs_real_t *xa);
512 
513 /*----------------------------------------------------------------------------
514  * Set matrix coefficients, copying values to private arrays.
515  *
516  * With private arrays, the matrix becomes independant from the
517  * arrays passed as arguments.
518  *
519  * Block sizes are defined by an optional array of 4 values:
520  * 0: useful block size, 1: vector block extents,
521  * 2: matrix line extents, 3: matrix line*column extents
522  *
523  * parameters:
524  * matrix <-> pointer to matrix structure
525  * symmetric <-- indicates if matrix coefficients are symmetric
526  * diag_block_size <-- block sizes for diagonal, or NULL
527  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
528  * n_edges <-- local number of graph edges
529  * edges <-- edges (row <-> column) connectivity
530  * da <-- diagonal values (NULL if zero)
531  * xa <-- extradiagonal values (NULL if zero)
532  * casts as:
533  * xa[n_edges] if symmetric,
534  * xa[n_edges][2] if non symmetric
535  *----------------------------------------------------------------------------*/
536 
537 void
539  bool symmetric,
540  const cs_lnum_t *diag_block_size,
541  const cs_lnum_t *extra_diag_block_size,
542  const cs_lnum_t n_edges,
543  const cs_lnum_2_t edges[],
544  const cs_real_t *da,
545  const cs_real_t *xa);
546 
547 /*----------------------------------------------------------------------------
548  * Set matrix coefficients in an MSR format, transferring the
549  * property of those arrays to the matrix.
550  *
551  * If the matrix is also in MSR format, this avoids an extra copy.
552  * If it is in a different format, values are copied to the structure,
553  * and the original arrays freed. In any case, the arrays pointers passed as
554  * arguments are set to NULL, to help ensure the caller does not use the
555  * original arrays directly after this call.
556  *
557  * Block sizes are defined by an optional array of 4 values:
558  * 0: useful block size, 1: vector block extents,
559  * 2: matrix line extents, 3: matrix line*column extents
560  *
561  * parameters:
562  * matrix <-> pointer to matrix structure
563  * symmetric <-- indicates if matrix coefficients are symmetric
564  * diag_block_size <-- block sizes for diagonal, or NULL
565  * extra_diag_block_size <-- block sizes for extra diagonal, or NULL
566  * row_index <-- MSR row index (0 to n-1)
567  * col_id <-- MSR column id (0 to n-1)
568  * d_val <-> diagonal values (NULL if zero)
569  * x_val <-> extradiagonal values (NULL if zero)
570  *----------------------------------------------------------------------------*/
571 
572 void
574  bool symmetric,
575  const cs_lnum_t *diag_block_size,
576  const cs_lnum_t *extra_diag_block_size,
577  const cs_lnum_t row_index[],
578  const cs_lnum_t col_id[],
579  cs_real_t **d_val,
580  cs_real_t **x_val);
581 
582 /*----------------------------------------------------------------------------*/
600 /*----------------------------------------------------------------------------*/
601 
604  const cs_lnum_t *diag_block_size,
605  const cs_lnum_t *extra_diag_block_size);
606 
607 /*----------------------------------------------------------------------------
608  * Release shared matrix coefficients.
609  *
610  * Pointers to mapped coefficients are set to NULL, while
611  * coefficient copies owned by the matrix are not modified.
612  *
613  * This simply ensures the matrix does not maintain pointers
614  * to nonexistant data.
615  *
616  * parameters:
617  * matrix <-> pointer to matrix structure
618  *----------------------------------------------------------------------------*/
619 
620 void
622 
623 /*----------------------------------------------------------------------------
624  * Copy matrix diagonal values.
625  *
626  * In case of matrixes with block diagonal coefficients, only the true
627  * diagonal values are copied.
628  *
629  * parameters:
630  * matrix --> pointer to matrix structure
631  * da --> diagonal (pre-allocated, size: n_rows*block_size
632  *----------------------------------------------------------------------------*/
633 
634 void
636  cs_real_t *restrict da);
637 
638 /*----------------------------------------------------------------------------
639  * Query matrix coefficients symmetry
640  *
641  * parameters:
642  * matrix <-- pointer to matrix structure
643  *
644  * returns:
645  * true if coefficients are symmetric, false otherwise
646  *----------------------------------------------------------------------------*/
647 
648 bool
650 
651 /*----------------------------------------------------------------------------*/
664 /*----------------------------------------------------------------------------*/
665 
666 bool
668 
669 /*----------------------------------------------------------------------------
670  * Get matrix diagonal values.
671  *
672  * In case of matrixes with block diagonal coefficients, a pointer to
673  * the complete block diagonal is returned.
674  *
675  * parameters:
676  * matrix --> pointer to matrix structure
677  *
678  * returns:
679  * pointer to matrix diagonal array
680  *----------------------------------------------------------------------------*/
681 
682 const cs_real_t *
684 
685 /*----------------------------------------------------------------------------
686  * Get pointer to matrix extra-diagonal values in "native" format
687  *
688  * This function currently only functions if the matrix is in "native"
689  * format or the coefficients were mapped from native coefficients using
690  * cs_matrix_set_coefficients(), in which case the pointer returned is
691  * the same as the one passed to that function.
692  *
693  * parameters:
694  * matrix --> pointer to matrix structure
695  *
696  * returns:
697  * pointer to matrix diagonal array
698  *----------------------------------------------------------------------------*/
699 
700 const cs_real_t *
702 
703 /*----------------------------------------------------------------------------
704  * Initialize row info for a given matrix.
705  *
706  * parameters:
707  * r --> row info structure
708  *----------------------------------------------------------------------------*/
709 
710 void
712 
713 /*----------------------------------------------------------------------------
714  * Finalize row info for a given matrix.
715  *
716  * parameters:
717  * r <-> row info structure
718  *----------------------------------------------------------------------------*/
719 
720 void
722 
723 /*----------------------------------------------------------------------------
724  * Get row values for a given matrix.
725  *
726  * This function may not work for all matrix types.
727  *
728  * In the case of blocked matrixes, the true (non-blocked)
729  * values are returned.
730  *
731  * The row information structure must have been previously initialized
732  * using cs_matrix_row_init(), and should be finalized using
733  * using cs_matrix_row_finalize(), so as to free buffers it may have
734  * built for certain matrix formats.
735  *
736  * parameters:
737  * matrix <-- pointer to matrix structure
738  * row_id <-- id of row to query
739  * r <-> row info structure
740  *----------------------------------------------------------------------------*/
741 
742 void
744  const cs_lnum_t row_id,
746 
747 /*----------------------------------------------------------------------------
748  * Get arrays describing a matrix in native format.
749  *
750  * This function works for matrix in native format.
751  *
752  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
753  * and cs_matrix_get_extra_diag_block_size().
754  *
755  * parameters:
756  * matrix <-- pointer to matrix structure
757  * symmetric --> true if symmetric
758  * n_edges --> number of associated faces
759  * edges --> edges (symmetric row <-> column) connectivity
760  * d_val --> diagonal values
761  * x_val --> extra-diagonal values
762  *----------------------------------------------------------------------------*/
763 
764 void
766  bool *symmetric,
767  cs_lnum_t *n_edges,
768  const cs_lnum_2_t **edges,
769  const cs_real_t **d_val,
770  const cs_real_t **x_val);
771 
772 /*----------------------------------------------------------------------------
773  * Get arrays describing a matrix in CSR format.
774  *
775  * This function only works for an CSR matrix (i.e. there is
776  * no automatic conversion from another matrix type).
777  *
778  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
779  * and cs_matrix_get_extra_diag_block_size().
780  *
781  * parameters:
782  * matrix <-- pointer to matrix structure
783  * row_index --> CSR row index
784  * col_id --> CSR column id
785  * val --> values
786  *----------------------------------------------------------------------------*/
787 
788 void
790  const cs_lnum_t **row_index,
791  const cs_lnum_t **col_id,
792  const cs_real_t **val);
793 
794 /*----------------------------------------------------------------------------
795  * Get arrays describing a matrix in MSR format.
796  *
797  * This function only works for an MSR matrix (i.e. there is
798  * no automatic conversion from another matrix type).
799  *
800  * Matrix block sizes can be obtained by cs_matrix_get_diag_block_size()
801  * and cs_matrix_get_extra_diag_block_size().
802  *
803  * parameters:
804  * matrix <-- pointer to matrix structure
805  * row_index --> MSR row index
806  * col_id --> MSR column id
807  * d_val --> diagonal values
808  * x_val --> extra-diagonal values
809  *----------------------------------------------------------------------------*/
810 
811 void
813  const cs_lnum_t **row_index,
814  const cs_lnum_t **col_id,
815  const cs_real_t **d_val,
816  const cs_real_t **x_val);
817 
818 /*----------------------------------------------------------------------------
819  * Assign functions based on a variant to a given matrix.
820  *
821  * If the matrix variant is incompatible with the structure, it is ignored,
822  * and defaults for that structure are used instead.
823  *
824  * parameters:
825  * m <-> associated matrix structure
826  * mv <-- associated matrix variant
827  *
828  * returns:
829  * pointer to created matrix structure;
830  *----------------------------------------------------------------------------*/
831 
832 void
834  const cs_matrix_variant_t *mv);
835 
836 /*----------------------------------------------------------------------------
837  * Matrix.vector product y = A.x
838  *
839  * This function includes a halo update of x prior to multiplication by A.
840  *
841  * parameters:
842  * matrix --> pointer to matrix structure
843  * x <-> multipliying vector values (ghost values updated)
844  * y --> resulting vector
845  *----------------------------------------------------------------------------*/
846 
847 void
849  cs_real_t *restrict x,
850  cs_real_t *restrict y);
851 
852 /*----------------------------------------------------------------------------
853  * Matrix.vector product y = A.x with no prior halo update of x.
854  *
855  * This function does not include a halo update of x prior to multiplication
856  * by A, so it should be called only when the halo of x is known to already
857  * be up to date (in which case we avoid the performance penalty of a
858  * redundant update by using this variant of the matrix.vector product).
859  *
860  * parameters:
861  * matrix --> pointer to matrix structure
862  * x --> multipliying vector values
863  * y <-- resulting vector
864  *----------------------------------------------------------------------------*/
865 
866 void
868  cs_real_t *restrict x,
869  cs_real_t *restrict y);
870 
871 /*----------------------------------------------------------------------------
872  * Matrix.vector product y = (A-D).x
873  *
874  * This function includes a halo update of x prior to multiplication by A.
875  *
876  * parameters:
877  * matrix <-- pointer to matrix structure
878  * x <-> multipliying vector values (ghost values updated)
879  * y --> resulting vector
880  *----------------------------------------------------------------------------*/
881 
882 void
884  cs_real_t *restrict x,
885  cs_real_t *restrict y);
886 
887 /*----------------------------------------------------------------------------
888  * Synchronize ghost values prior to matrix.vector product
889  *
890  * parameters:
891  * matrix <-- pointer to matrix structure
892  * x <-> multipliying vector values (ghost values updated)
893  *----------------------------------------------------------------------------*/
894 
895 void
897  cs_real_t *x);
898 
899 /*----------------------------------------------------------------------------*/
910 /*----------------------------------------------------------------------------*/
911 
912 void
914  int *n_variants,
915  cs_matrix_variant_t **m_variant);
916 
917 /*----------------------------------------------------------------------------*/
926 /*----------------------------------------------------------------------------*/
927 
930 
931 /*----------------------------------------------------------------------------
932  * Destroy a matrix variant structure.
933  *
934  * parameters:
935  * mv <-> Pointer to matrix variant pointer
936  *----------------------------------------------------------------------------*/
937 
938 void
940 
941 /*----------------------------------------------------------------------------*/
948 /*----------------------------------------------------------------------------*/
949 
950 void
952  cs_matrix_variant_t *mv);
953 
954 /*----------------------------------------------------------------------------
955  * Select the sparse matrix-vector product function to be used by a
956  * matrix variant for a given fill type.
957  *
958  * Currently, possible variant functions are:
959  *
960  * CS_MATRIX_NATIVE (all fill types)
961  * default
962  * standard
963  * omp (for OpenMP with compatible numbering)
964  * vector (For vector machine with compatible numbering)
965  *
966  * CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
967  * default
968  * standard
969  * mkl (with MKL)
970  *
971  * CS_MATRIX_MSR (all fill types except CS_MATRIX_33_BLOCK)
972  * default
973  * standard
974  * mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)
975  * omp_sched (For OpenMP with scheduling)
976  *
977  * parameters:
978  * mv <-> pointer to matrix variant
979  * numbering <-- mesh numbering info, or NULL
980  * fill type <-- matrix fill type to merge from
981  * ed_flag <-- 0: with diagonal only, 1 exclude only; 2; both
982  * func_name <-- function type name
983  *----------------------------------------------------------------------------*/
984 
985 void
987  const cs_numbering_t *numbering,
988  cs_matrix_fill_type_t fill_type,
989  int ed_flag,
990  const char *func_name);
991 
992 /*----------------------------------------------------------------------------
993  * Get the type associated with a matrix variant.
994  *
995  * parameters:
996  * mv <-- pointer to matrix variant structure
997  *----------------------------------------------------------------------------*/
998 
1001 
1002 /*----------------------------------------------------------------------------*/
1003 
1005 
1006 #endif /* __CS_MATRIX_H__ */
cs_lnum_t * _col_id
Definition: cs_matrix.h:106
const cs_lnum_t * cs_matrix_get_diag_block_size(const cs_matrix_t *matrix)
Return matrix diagonal block sizes.
Definition: cs_matrix.c:6098
cs_matrix_t * cs_matrix_create_by_copy(cs_matrix_t *src)
Create a matrix container by copying another.
Definition: cs_matrix.c:5816
bool cs_matrix_is_symmetric(const cs_matrix_t *matrix)
Query matrix coefficients symmetry.
Definition: cs_matrix.c:6545
#define restrict
Definition: cs_defs.h:142
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:6926
const cs_halo_t * cs_matrix_get_halo(const cs_matrix_t *matrix)
Return pointer to matrix halo structure.
Definition: cs_matrix.c:6142
void cs_matrix_row_finalize(cs_matrix_row_info_t *r)
Finalize row info for a given matrix.
Definition: cs_matrix.c:6668
void cs_matrix_vector_multiply_nosync(const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
Matrix.vector product y = A.x with no prior halo update of x.
Definition: cs_matrix.c:7010
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:6882
void cs_matrix_exdiag_vector_multiply(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:7041
const char * cs_matrix_get_type_name(const cs_matrix_t *matrix)
Definition: cs_matrix.c:5977
Definition: cs_matrix.h:74
cs_matrix_variant_t * cs_matrix_variant_create(cs_matrix_t *m)
Build matrix variant.
Definition: cs_matrix.c:7070
struct _cs_matrix_assembler_values_t cs_matrix_assembler_values_t
Definition: cs_matrix_assembler.h:65
void cs_matrix_row_init(cs_matrix_row_info_t *r)
Initialize row info for a given matrix.
Definition: cs_matrix.c:6649
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:6303
cs_matrix_t * cs_matrix_create(const cs_matrix_structure_t *ms)
Create a matrix container using a given structure.
Definition: cs_matrix.c:5735
struct _cs_matrix_variant_t cs_matrix_variant_t
Definition: cs_matrix.h:97
#define BEGIN_C_DECLS
Definition: cs_defs.h:510
void cs_matrix_release_coefficients(cs_matrix_t *matrix)
Release shared matrix coefficients.
Definition: cs_matrix.c:6434
Definition: cs_matrix.h:83
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:6363
Definition: cs_matrix.h:80
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:6169
Definition: cs_halo.h:77
void cs_matrix_structure_destroy(cs_matrix_structure_t **ms)
Destroy a matrix structure.
Definition: cs_matrix.c:5707
void cs_matrix_pre_vector_multiply_sync(const cs_matrix_t *matrix, cs_real_t *x)
void cs_matrix_copy_diagonal(const cs_matrix_t *matrix, cs_real_t *restrict da)
Copy matrix diagonal values.
Definition: cs_matrix.c:6521
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:6699
const char * cs_matrix_fill_type_name[]
double cs_real_t
Floating-point value.
Definition: cs_defs.h:322
Definition: cs_matrix.h:82
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:93
Definition: cs_matrix.h:76
cs_lnum_t row_size
Definition: cs_matrix.h:103
void cs_matrix_variant_build_list(const cs_matrix_t *m, int *n_variants, cs_matrix_variant_t **m_variant)
Build list of variants for tuning or testing.
Definition: cs_matrix.c:7109
const cs_lnum_t * col_id
Definition: cs_matrix.h:105
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:6239
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:6122
const char * cs_matrix_get_type_fullname(const cs_matrix_t *matrix)
Definition: cs_matrix.c:5994
bool cs_matrix_is_mapped_from_native(const cs_matrix_t *matrix)
Indicate whether coefficients were mapped from native face-based arrays.
Definition: cs_matrix.c:6566
void cs_matrix_vector_multiply(const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
Matrix.vector product y = A.x.
Definition: cs_matrix.c:6977
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:5668
Definition: cs_matrix.h:62
Definition: cs_matrix.h:64
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:5769
Definition: cs_matrix.h:72
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:6828
cs_matrix_t * cs_matrix_create_by_local_restrict(const cs_matrix_t *src)
Create a matrix based on the local restriction of a base matrix.
Definition: cs_matrix.c:5864
cs_lnum_t cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:328
const cs_real_t * vals
Definition: cs_matrix.h:107
cs_real_t * _vals
Definition: cs_matrix.h:108
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:5527
void cs_matrix_apply_variant(cs_matrix_t *m, const cs_matrix_variant_t *mv)
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:316
cs_matrix_type_t cs_matrix_get_type(const cs_matrix_t *matrix)
Return matrix type.
Definition: cs_matrix.c:5961
cs_lnum_t cs_matrix_get_n_columns(const cs_matrix_t *matrix)
Return number of columns in a matrix.
Definition: cs_matrix.c:6012
cs_lnum_t buffer_size
Definition: cs_matrix.h:104
void cs_matrix_destroy(cs_matrix_t **matrix)
Definition: cs_matrix.c:5933
#define END_C_DECLS
Definition: cs_defs.h:511
void cs_matrix_variant_destroy(cs_matrix_variant_t **mv)
Destroy a matrix variant structure.
Definition: cs_matrix.c:7364
Definition: cs_matrix.h:101
struct _cs_matrix_assembler_t cs_matrix_assembler_t
Definition: cs_matrix_assembler.h:61
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:5437
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:6625
Definition: cs_matrix.h:59
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:6029
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:7429
cs_lnum_t cs_matrix_get_n_entries(const cs_matrix_t *matrix)
Return number of entries in matrix.
Definition: cs_matrix.c:6049
const cs_real_t * cs_matrix_get_diagonal(const cs_matrix_t *matrix)
Get matrix diagonal values.
Definition: cs_matrix.c:6590
Definition: cs_matrix.h:57
Definition: cs_matrix.h:73
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.
Definition: cs_matrix.c:5618
void cs_matrix_variant_apply(cs_matrix_t *m, cs_matrix_variant_t *mv)
Apply a variant to a given matrix.
Definition: cs_matrix.c:7380
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:7472
Definition: cs_numbering.h:83
struct _cs_matrix_structure_t cs_matrix_structure_t
Definition: cs_matrix.h:89
cs_matrix_fill_type_t
Definition: cs_matrix.h:70
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:6479