programmer's documentation
cs_matrix_priv.h
Go to the documentation of this file.
1 #ifndef __CS_MATRIX_PRIV_H__
2 #define __CS_MATRIX_PRIV_H__
3 
4 /*============================================================================
5  * Private types for 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_matrix.h"
37 
38 /*----------------------------------------------------------------------------*/
39 
41 
44 /*=============================================================================
45  * Macro definitions
46  *============================================================================*/
47 
48 /*============================================================================
49  * Type definitions
50  *============================================================================*/
51 
52 /* Formats currently supported:
53  *
54  * - Native
55  * - Compressed Sparse Row (CSR)
56  * - Modified Compressed Sparse Row (MSR), with separate diagonal
57  * - Symmetric Compressed Sparse Row (CSR_SYM)
58  */
59 
60 /*----------------------------------------------------------------------------
61  * Function pointer types
62  *----------------------------------------------------------------------------*/
63 
64 typedef void
65 (cs_matrix_set_coeffs_t) (cs_matrix_t *matrix,
66  bool symmetric,
67  bool copy,
68  cs_lnum_t n_edges,
69  const cs_lnum_2_t *restrict edges,
70  const cs_real_t *restrict da,
71  const cs_real_t *restrict xa);
72 
73 typedef void
74 (cs_matrix_release_coeffs_t) (cs_matrix_t *matrix);
75 
76 typedef void
77 (cs_matrix_copy_diagonal_t) (const cs_matrix_t *matrix,
78  cs_real_t *restrict da);
79 
80 typedef void
81 (cs_matrix_vector_product_t) (bool exclude_diag,
82  const cs_matrix_t *matrix,
83  const cs_real_t *restrict x,
84  cs_real_t *restrict y);
85 
86 /*----------------------------------------------------------------------------
87  * Matrix types
88  *----------------------------------------------------------------------------*/
89 
90 /* Native matrix structure representation */
91 /*----------------------------------------*/
92 
93 /* Note: the members of this structure are already available through the top
94  * matrix structure, but are replicated here in case of future removal
95  * from the top structure (which would require computation/assignment of
96  * matrix coefficients in another form) */
97 
98 typedef struct _cs_matrix_struct_native_t {
99 
100  cs_lnum_t n_rows; /* Local number of rows */
101  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
102  cs_lnum_t n_edges; /* Local number of graph edges
103  (for extra-diagonal terms) */
104 
105  /* Pointers to shared arrays */
106 
107  const cs_lnum_2_t *edges; /* Edges (symmetric row <-> column)
108  connectivity */
109 
110 } cs_matrix_struct_native_t;
111 
112 /* Native matrix coefficients */
113 /*----------------------------*/
114 
115 typedef struct _cs_matrix_coeff_native_t {
116 
117  bool symmetric; /* Symmetry indicator */
118  int max_db_size; /* Current max allocated diag block size */
119  int max_eb_size; /* Current max allocated extradiag block size */
120 
121  /* Pointers to possibly shared arrays */
122 
123  const cs_real_t *da; /* Diagonal terms */
124  const cs_real_t *xa; /* Extra-diagonal terms */
125 
126  /* Pointers to private arrays (NULL if shared) */
127 
128  cs_real_t *_da; /* Diagonal terms */
129  cs_real_t *_xa; /* Extra-diagonal terms */
130 
131 } cs_matrix_coeff_native_t;
132 
133 /* CSR (Compressed Sparse Row) matrix structure representation */
134 /*-------------------------------------------------------------*/
135 
136 typedef struct _cs_matrix_struct_csr_t {
137 
138  cs_lnum_t n_rows; /* Local number of rows */
139  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
140 
141  /* Pointers to structure arrays and info (row_index, col_id) */
142 
143  bool have_diag; /* Has non-zero diagonal */
144  bool direct_assembly; /* True if each value corresponds to
145  a unique face ; false if multiple
146  faces contribute to the same
147  value (i.e. we have split faces) */
148 
149  const cs_lnum_t *row_index; /* Pointer to row index (0 to n-1) */
150  const cs_lnum_t *col_id; /* Pointer to column id (0 to n-1) */
151 
152  cs_lnum_t *_row_index; /* Row index (0 to n-1), if owner */
153  cs_lnum_t *_col_id; /* Column id (0 to n-1), if owner */
154 
155 } cs_matrix_struct_csr_t;
156 
157 /* CSR matrix coefficients representation */
158 /*----------------------------------------*/
159 
160 typedef struct _cs_matrix_coeff_csr_t {
161 
162  /* Pointers to possibly shared arrays */
163 
164  const cs_real_t *val; /* Matrix coefficients */
165 
166  /* Pointers to private arrays (NULL if shared) */
167 
168  cs_real_t *_val; /* Diagonal matrix coefficients */
169 
170  /* Pointers to auxiliary arrays used for queries */
171 
172  const cs_real_t *d_val; /* Pointer to diagonal matrix
173  coefficients, if queried */
174  cs_real_t *_d_val; /* Diagonal matrix coefficients,
175  if queried */
176 
177 } cs_matrix_coeff_csr_t;
178 
179 /* CSR_SYM (Symmetric Compressed Sparse Row) matrix structure representation */
180 /*---------------------------------------------------------------------------*/
181 
182 typedef struct _cs_matrix_struct_csr_sym_t {
183 
184  cs_lnum_t n_rows; /* Local number of rows */
185  cs_lnum_t n_cols; /* Local number of columns
186  (> n_rows in case of ghost columns) */
187 
188  /* Pointers to structure arrays and info (row_index, col_id) */
189 
190  bool have_diag; /* Has non-zero diagonal */
191  bool direct_assembly; /* True if each value corresponds to
192  a unique face ; false if multiple
193  faces contribute to the same
194  value (i.e. we have split faces) */
195 
196  cs_lnum_t *row_index; /* Row index (0 to n-1) */
197  cs_lnum_t *col_id; /* Column id (0 to n-1) */
198 
199 } cs_matrix_struct_csr_sym_t;
200 
201 /* symmetric CSR matrix coefficients representation */
202 /*--------------------------------------------------*/
203 
204 typedef struct _cs_matrix_coeff_csr_sym_t {
205 
206  cs_real_t *val; /* Matrix coefficients */
207 
208  /* Pointers to auxiliary arrays used for queries */
209 
210  const cs_real_t *d_val; /* Pointer to diagonal matrix
211  coefficients, if queried */
212  cs_real_t *_d_val; /* Diagonal matrix coefficients,
213  if queried */
214 
215 } cs_matrix_coeff_csr_sym_t;
216 
217 /* MSR matrix coefficients representation */
218 /*----------------------------------------*/
219 
220 typedef struct _cs_matrix_coeff_msr_t {
221 
222  int max_db_size; /* Current max allocated block size */
223  int max_eb_size; /* Current max allocated extradiag block size */
224 
225  /* Pointers to possibly shared arrays */
226 
227  const cs_real_t *d_val; /* Diagonal matrix coefficients */
228  const cs_real_t *x_val; /* Extra-diagonal matrix coefficients */
229 
230  /* Pointers to private arrays (NULL if shared) */
231 
232  cs_real_t *_d_val; /* Diagonal matrix coefficients */
233  cs_real_t *_x_val; /* Extra-diagonal matrix coefficients */
234 
235 } cs_matrix_coeff_msr_t;
236 
237 /* Matrix structure (representation-independent part) */
238 /*----------------------------------------------------*/
239 
240 struct _cs_matrix_structure_t {
241 
242  cs_matrix_type_t type; /* Matrix storage and definition type */
243 
244  cs_lnum_t n_rows; /* Local number of rows */
245  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
246 
247  void *structure; /* Matrix structure */
248 
249  /* Pointers to shared arrays from mesh structure
250  (face->cell connectivity for coefficient assignment,
251  local->local cell numbering for future info or renumbering,
252  and halo) */
253 
254  const cs_halo_t *halo; /* Parallel or periodic halo */
255  const cs_numbering_t *numbering; /* Vectorization or thread-related
256  numbering information */
257 
258  const cs_matrix_assembler_t *assembler; /* Associated matrix assembler */
259 };
260 
261 /* Structure associated with Matrix (representation-independent part) */
262 /*--------------------------------------------------------------------*/
263 
264 struct _cs_matrix_t {
265 
266  cs_matrix_type_t type; /* Matrix storage and definition type */
267 
268  cs_lnum_t n_rows; /* Local number of rows */
269  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
270 
271  cs_matrix_fill_type_t fill_type; /* Matrix fill type */
272 
273  bool symmetric; /* true if coefficients are symmetric */
274 
275  int db_size[4]; /* Diag Block size, including padding:
276  0: useful block size
277  1: vector block extents
278  2: matrix line extents
279  3: matrix line*column extents */
280 
281  int eb_size[4]; /* Extradiag block size, including padding:
282  0: useful block size
283  1: vector block extents
284  2: matrix line extents
285  3: matrix line*column extents */
286 
287  /* Pointer to shared structure */
288 
289  const void *structure; /* Matrix structure */
290 
291  /* Pointers to arrays possibly shared from mesh structure
292  (graph edges: face->cell connectivity for coefficient assignment,
293  rows: local->local cell numbering for future info or renumbering,
294  and halo) */
295 
296  const cs_halo_t *halo; /* Parallel or periodic halo */
297  const cs_numbering_t *numbering; /* Vectorization or thread-related
298  numbering information */
299  const cs_matrix_assembler_t *assembler; /* Associated matrix assembler */
300 
301  /* Pointer to shared arrays from coefficient assignment from
302  "native" type. This should be removed in the future, but requires
303  removing the dependency to the native structure in the multigrid
304  code first. */
305 
306  const cs_real_t *xa; /* Extra-diagonal terms */
307 
308  /* Pointer to private data */
309 
310  void *coeffs; /* Matrix coefficients */
311 
312  /* Function pointers */
313 
314  cs_matrix_set_coeffs_t *set_coefficients;
315  cs_matrix_release_coeffs_t *release_coefficients;
316  cs_matrix_copy_diagonal_t *copy_diagonal;
317 
318  /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants:
319  fill_type*2 + exclude_diagonal_flag */
320 
321  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
322 
323  /* Additional contributions */
324 
325  cs_matrix_vector_product_extend_t *vector_multiply_extend; /* SpMV add */
326  cs_matrix_preconditioner_extend_t *preconditioner_extend; /* Diag add */
327  void *input_extend; /* Associated
328  data */
329 };
330 
331 /* Structure used for tuning variants */
332 /*------------------------------------*/
333 
334 struct _cs_matrix_variant_t {
335 
336  char name[32]; /* Variant name */
337 
338  cs_matrix_type_t type; /* Matrix storage and definition type */
339 
340  /* Function pointer arrays, with variants:
341  fill_type + exclude_diagonal_flag */
342 
343  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
344 
345  /* Measured structure creation cost, or -1 otherwise */
346 
347  double matrix_create_cost;
348 
349  /* Measured assignment costs for each available fill type, or -1 otherwise */
350 
351  double matrix_assign_cost[CS_MATRIX_N_FILL_TYPES];
352 
353  /* Measured operation costs for each available operation, or -1 otherwise
354  fill_type*2 + exclude_diagonal_flag */
355 
356  double matrix_vector_cost[CS_MATRIX_N_FILL_TYPES][2][2];
357 
358 };
359 
362 /*=============================================================================
363  * Semi-private function prototypes
364  *============================================================================*/
365 
366 /*----------------------------------------------------------------------------
367  * Create CSR matrix coefficients.
368  *
369  * returns:
370  * pointer to allocated CSR coefficients structure.
371  *----------------------------------------------------------------------------*/
372 
373 cs_matrix_coeff_csr_t *
375 
376 /*----------------------------------------------------------------------------
377  * Destroy CSR matrix coefficients.
378  *
379  * parameters:
380  * coeff <-> Pointer to CSR matrix coefficients pointer
381  *----------------------------------------------------------------------------*/
382 
383 void
384 cs_matrix_destroy_coeff_csr(cs_matrix_coeff_csr_t **coeff);
385 
386 /*----------------------------------------------------------------------------
387  * Release shared CSR matrix coefficients.
388  *
389  * parameters:
390  * matrix <-- Pointer to matrix structure
391  *----------------------------------------------------------------------------*/
392 
393 void
395 
396 /*----------------------------------------------------------------------------
397  * Copy diagonal of CSR matrix.
398  *
399  * parameters:
400  * matrix <-- Pointer to matrix structure
401  * da --> Diagonal (pre-allocated, size: n_rows)
402  *----------------------------------------------------------------------------*/
403 
404 void
406  cs_real_t *restrict da);
407 
408 /*----------------------------------------------------------------------------
409  * Destroy CSR matrix structure.
410  *
411  * parameters:
412  * matrix <-> Pointer to CSR matrix structure pointer
413  *----------------------------------------------------------------------------*/
414 
415 void
416 cs_matrix_destroy_struct_csr(cs_matrix_struct_csr_t **matrix);
417 
418 /*----------------------------------------------------------------------------
419  * Local matrix.vector product y = A.x with CSR matrix.
420  *
421  * parameters:
422  * exclude_diag <-- exclude diagonal if true
423  * matrix <-- Pointer to matrix structure
424  * x <-- Multipliying vector values
425  * y --> Resulting vector
426  *----------------------------------------------------------------------------*/
427 
428 void
429 cs_matrix_vec_p_l_csr(bool exclude_diag,
430  const cs_matrix_t *matrix,
431  const cs_real_t *restrict x,
432  cs_real_t *restrict y);
433 
434 #if defined (HAVE_MKL)
435 /*----------------------------------------------------------------------------
436  * Local matrix.vector product y = A.x with MSR matrix, using MKL
437  *
438  * parameters:
439  * exclude_diag <-- exclude diagonal if true
440  * matrix <-- Pointer to matrix structure
441  * x <-- Multipliying vector values
442  * y --> Resulting vector
443  *----------------------------------------------------------------------------*/
444 
445 void
446 cs_matrix_vec_p_l_csr_mkl(bool exclude_diag,
447  const cs_matrix_t *matrix,
448  const cs_real_t *restrict x,
449  cs_real_t *restrict y);
450 
451 #endif /* defined (HAVE_MKL) */
452 
453 /*----------------------------------------------------------------------------
454  * Copy diagonal of native or MSR matrix.
455  *
456  * parameters:
457  * matrix <-- Pointer to matrix structure
458  * da --> Diagonal (pre-allocated, size: n_cols)
459  *----------------------------------------------------------------------------*/
460 
461 void
463  cs_real_t *restrict da);
464 
465 /*----------------------------------------------------------------------------
466  * Create MSR matrix coefficients.
467  *
468  * returns:
469  * pointer to allocated MSR coefficients structure.
470  *----------------------------------------------------------------------------*/
471 
472 cs_matrix_coeff_msr_t *
474 
475 /*----------------------------------------------------------------------------
476  * Release shared MSR matrix coefficients.
477  *
478  * parameters:
479  * matrix <-- Pointer to matrix structure
480  *----------------------------------------------------------------------------*/
481 
482 void
484 
485 /*----------------------------------------------------------------------------
486  * Local matrix.vector product y = A.x with MSR matrix.
487  *
488  * parameters:
489  * exclude_diag <-- exclude diagonal if true
490  * matrix <-- Pointer to matrix structure
491  * x <-- Multipliying vector values
492  * y --> Resulting vector
493  *----------------------------------------------------------------------------*/
494 
495 void
496 cs_matrix_vec_p_l_msr(bool exclude_diag,
497  const cs_matrix_t *matrix,
498  const cs_real_t *restrict x,
499  cs_real_t *restrict y);
500 
501 #if defined (HAVE_MKL)
502 /*----------------------------------------------------------------------------
503  * Local matrix.vector product y = A.x with MSR matrix, using MKL
504  *
505  * parameters:
506  * exclude_diag <-- exclude diagonal if true
507  * matrix <-- Pointer to matrix structure
508  * x <-- Multipliying vector values
509  * y --> Resulting vector
510  *----------------------------------------------------------------------------*/
511 
512 void
513 cs_matrix_vec_p_l_msr_mkl(bool exclude_diag,
514  const cs_matrix_t *matrix,
515  const cs_real_t *restrict x,
516  cs_real_t *restrict y);
517 #endif /* defined (HAVE_MKL) */
518 
519 /*----------------------------------------------------------------------------*/
520 
522 
523 #endif /* __CS_MATRIX_PRIV_H__ */
#define restrict
Definition: cs_defs.h:122
void cs_matrix_copy_diagonal_separate(const cs_matrix_t *matrix, cs_real_t *restrict da)
cs_matrix_coeff_csr_t * cs_matrix_create_coeff_csr(void)
#define BEGIN_C_DECLS
Definition: cs_defs.h:453
Definition: cs_matrix.h:80
Definition: cs_halo.h:71
void cs_matrix_copy_diagonal_csr(const cs_matrix_t *matrix, cs_real_t *restrict da)
void cs_matrix_release_coeffs_csr(cs_matrix_t *matrix)
double cs_real_t
Floating-point value.
Definition: cs_defs.h:297
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
void cs_matrix_release_coeffs_msr(cs_matrix_t *matrix)
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:90
void cs_matrix_destroy_coeff_csr(cs_matrix_coeff_csr_t **coeff)
cs_matrix_coeff_msr_t * cs_matrix_create_coeff_msr(void)
void cs_matrix_vec_p_l_msr(bool exclude_diag, const cs_matrix_t *matrix, const cs_real_t *restrict x, cs_real_t *restrict y)
void cs_matrix_vec_p_l_csr(bool exclude_diag, const cs_matrix_t *matrix, const cs_real_t *restrict x, cs_real_t *restrict y)
cs_matrix_type_t
Definition: cs_matrix.h:55
void() cs_matrix_vector_product_extend_t(bool exclude_diag, void *input, const cs_real_t *restrict x, cs_real_t *restrict y)
Definition: cs_matrix.h:128
void() cs_matrix_preconditioner_extend_t(void *input, cs_real_t *restrict ad)
Definition: cs_matrix.h:142
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:303
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:293
#define END_C_DECLS
Definition: cs_defs.h:454
struct _cs_matrix_assembler_t cs_matrix_assembler_t
Definition: cs_matrix_assembler.h:62
Definition: cs_numbering.h:78
void cs_matrix_destroy_struct_csr(cs_matrix_struct_csr_t **matrix)
cs_matrix_fill_type_t
Definition: cs_matrix.h:67