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-2016 EDF S.A.
12 
13  This program is free software; you can redistribute it and/or modify it under
14  the terms of the GNU General Public License as published by the Free Software
15  Foundation; either version 2 of the License, or (at your option) any later
16  version.
17 
18  This program is distributed in the hope that it will be useful, but WITHOUT
19  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21  details.
22 
23  You should have received a copy of the GNU General Public License along with
24  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25  Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27 
28 /*----------------------------------------------------------------------------*/
29 
30 /*----------------------------------------------------------------------------
31  * Local headers
32  *----------------------------------------------------------------------------*/
33 
34 #include "cs_defs.h"
35 
36 #include "cs_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  * - Symmetric Compressed Sparse Row (CSR_SYM)
57  */
58 
59 /*----------------------------------------------------------------------------
60  * Function pointer types
61  *----------------------------------------------------------------------------*/
62 
63 typedef void
64 (cs_matrix_set_coeffs_t) (cs_matrix_t *matrix,
65  bool symmetric,
66  bool copy,
67  cs_lnum_t n_edges,
68  const cs_lnum_2_t *restrict edges,
69  const cs_real_t *restrict da,
70  const cs_real_t *restrict xa);
71 
72 typedef void
73 (cs_matrix_release_coeffs_t) (cs_matrix_t *matrix);
74 
75 typedef void
76 (cs_matrix_copy_diagonal_t) (const cs_matrix_t *matrix,
77  cs_real_t *restrict da);
78 
79 typedef void
80 (cs_matrix_vector_product_t) (bool exclude_diag,
81  const cs_matrix_t *matrix,
82  const cs_real_t *restrict x,
83  cs_real_t *restrict y);
84 
85 /*----------------------------------------------------------------------------
86  * Matrix types
87  *----------------------------------------------------------------------------*/
88 
89 /* Native matrix structure representation */
90 /*----------------------------------------*/
91 
92 /* Note: the members of this structure are already available through the top
93  * matrix structure, but are replicated here in case of future removal
94  * from the top structure (which would require computation/assignment of
95  * matrix coefficients in another form) */
96 
97 typedef struct _cs_matrix_struct_native_t {
98 
99  cs_lnum_t n_rows; /* Local number of rows */
100  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
101  cs_lnum_t n_edges; /* Local number of graph edges
102  (for extra-diagonal terms) */
103 
104  /* Pointers to shared arrays */
105 
106  const cs_lnum_2_t *edges; /* Edges (symmetric row <-> column)
107  connectivity */
108 
109 } cs_matrix_struct_native_t;
110 
111 /* Native matrix coefficients */
112 /*----------------------------*/
113 
114 typedef struct _cs_matrix_coeff_native_t {
115 
116  bool symmetric; /* Symmetry indicator */
117  int max_db_size; /* Current max allocated diag block size */
118  int max_eb_size; /* Current max allocated extradiag block size */
119 
120  /* Pointers to possibly shared arrays */
121 
122  const cs_real_t *da; /* Diagonal terms */
123  const cs_real_t *xa; /* Extra-diagonal terms */
124 
125  /* Pointers to private arrays (NULL if shared) */
126 
127  cs_real_t *_da; /* Diagonal terms */
128  cs_real_t *_xa; /* Extra-diagonal terms */
129 
130 } cs_matrix_coeff_native_t;
131 
132 /* CSR (Compressed Sparse Row) matrix structure representation */
133 /*-------------------------------------------------------------*/
134 
135 typedef struct _cs_matrix_struct_csr_t {
136 
137  cs_lnum_t n_rows; /* Local number of rows */
138  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
139 
140  /* Pointers to structure arrays and info (row_index, col_id) */
141 
142  bool have_diag; /* Has non-zero diagonal */
143  bool direct_assembly; /* True if each value corresponds to
144  a unique face ; false if multiple
145  faces contribute to the same
146  value (i.e. we have split faces) */
147 
148  const cs_lnum_t *row_index; /* Pointer to row index (0 to n-1) */
149  const cs_lnum_t *col_id; /* Pointer to column id (0 to n-1) */
150 
151  cs_lnum_t *_row_index; /* Row index (0 to n-1), if owner */
152  cs_lnum_t *_col_id; /* Column id (0 to n-1), if owner */
153 
154 } cs_matrix_struct_csr_t;
155 
156 /* CSR matrix coefficients representation */
157 /*----------------------------------------*/
158 
159 typedef struct _cs_matrix_coeff_csr_t {
160 
161  /* Pointers to possibly shared arrays */
162 
163  const cs_real_t *val; /* Matrix coefficients */
164 
165  /* Pointers to private arrays (NULL if shared) */
166 
167  cs_real_t *_val; /* Diagonal matrix coefficients */
168 
169  /* Pointers to auxiliary arrays used for queries */
170 
171  const cs_real_t *d_val; /* Pointer to diagonal matrix
172  coefficients, if queried */
173  cs_real_t *_d_val; /* Diagonal matrix coefficients,
174  if queried */
175 
176 } cs_matrix_coeff_csr_t;
177 
178 /* CSR_SYM (Symmetric Compressed Sparse Row) matrix structure representation */
179 /*---------------------------------------------------------------------------*/
180 
181 typedef struct _cs_matrix_struct_csr_sym_t {
182 
183  cs_lnum_t n_rows; /* Local number of rows */
184  cs_lnum_t n_cols; /* Local number of columns
185  (> n_rows in case of ghost columns) */
186 
187  /* Pointers to structure arrays and info (row_index, col_id) */
188 
189  bool have_diag; /* Has non-zero diagonal */
190  bool direct_assembly; /* True if each value corresponds to
191  a unique face ; false if multiple
192  faces contribute to the same
193  value (i.e. we have split faces) */
194 
195  cs_lnum_t *row_index; /* Row index (0 to n-1) */
196  cs_lnum_t *col_id; /* Column id (0 to n-1) */
197 
198 } cs_matrix_struct_csr_sym_t;
199 
200 /* symmetric CSR matrix coefficients representation */
201 /*--------------------------------------------------*/
202 
203 typedef struct _cs_matrix_coeff_csr_sym_t {
204 
205  cs_real_t *val; /* Matrix coefficients */
206 
207  /* Pointers to auxiliary arrays used for queries */
208 
209  const cs_real_t *d_val; /* Pointer to diagonal matrix
210  coefficients, if queried */
211  cs_real_t *_d_val; /* Diagonal matrix coefficients,
212  if queried */
213 
214 } cs_matrix_coeff_csr_sym_t;
215 
216 /* MSR matrix coefficients representation */
217 /*----------------------------------------*/
218 
219 typedef struct _cs_matrix_coeff_msr_t {
220 
221  int max_db_size; /* Current max allocated block size */
222  int max_eb_size; /* Current max allocated extradiag block size */
223 
224  /* Pointers to possibly shared arrays */
225 
226  const cs_real_t *d_val; /* Diagonal matrix coefficients */
227  const cs_real_t *x_val; /* Extra-diagonal matrix coefficients */
228 
229  /* Pointers to private arrays (NULL if shared) */
230 
231  cs_real_t *_d_val; /* Diagonal matrix coefficients */
232  cs_real_t *_x_val; /* Extra-diagonal matrix coefficients */
233 
234 } cs_matrix_coeff_msr_t;
235 
236 /* Matrix structure (representation-independent part) */
237 /*----------------------------------------------------*/
238 
239 struct _cs_matrix_structure_t {
240 
241  cs_matrix_type_t type; /* Matrix storage and definition type */
242 
243  cs_lnum_t n_rows; /* Local number of rows */
244  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
245 
246  void *structure; /* Matrix structure */
247 
248  /* Pointers to shared arrays from mesh structure
249  (face->cell connectivity for coefficient assignment,
250  local->local cell numbering for future info or renumbering,
251  and halo) */
252 
253  const cs_gnum_t *row_num; /* Global row numbers */
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 
259 /* Structure associated with Matrix (representation-independent part) */
260 /*--------------------------------------------------------------------*/
261 
262 struct _cs_matrix_t {
263 
264  cs_matrix_type_t type; /* Matrix storage and definition type */
265 
266  cs_lnum_t n_rows; /* Local number of rows */
267  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
268 
269  cs_matrix_fill_type_t fill_type; /* Matrix fill type */
270 
271  bool symmetric; /* true if coefficients are symmetric */
272 
273  int db_size[4]; /* Diag Block size, including padding:
274  0: useful block size
275  1: vector block extents
276  2: matrix line extents
277  3: matrix line*column extents */
278 
279  int eb_size[4]; /* Extradiag block size, including padding:
280  0: useful block size
281  1: vector block extents
282  2: matrix line extents
283  3: matrix line*column extents */
284 
285  /* Pointer to shared structure */
286 
287  const void *structure; /* Matrix structure */
288 
289  /* Pointers to arrays possibly shared from mesh structure
290  (graph edges: face->cell connectivity for coefficient assignment,
291  rows: local->local cell numbering for future info or renumbering,
292  and halo) */
293 
294  const cs_halo_t *halo; /* Parallel or periodic halo */
295  const cs_numbering_t *numbering; /* Vectorization or thread-related
296  numbering information */
297 
298  /* Pointer to shared arrays from coefficient assignment from
299  "native" type. This should be removed in the future, but requires
300  removing the dependency to the native structure in the multigrid
301  code first. */
302 
303  const cs_real_t *xa; /* Extra-diagonal terms */
304 
305  /* Pointer to private data */
306 
307  void *coeffs; /* Matrix coefficients */
308 
309  /* Function pointers */
310 
311  cs_matrix_set_coeffs_t *set_coefficients;
312  cs_matrix_release_coeffs_t *release_coefficients;
313  cs_matrix_copy_diagonal_t *copy_diagonal;
314 
315  /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants:
316  fill_type*2 + exclude_diagonal_flag */
317 
318  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
319 
320 };
321 
322 /* Structure used for tuning variants */
323 /*------------------------------------*/
324 
325 struct _cs_matrix_variant_t {
326 
327  char name[32]; /* Variant name */
328 
329  cs_matrix_type_t type; /* Matrix storage and definition type */
330 
331  /* Function pointer arrays, with variants:
332  fill_type + exclude_diagonal_flag */
333 
334  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
335 
336  /* Measured structure creation cost, or -1 otherwise */
337 
338  double matrix_create_cost;
339 
340  /* Measured assignment costs for each available fill type, or -1 otherwise */
341 
342  double matrix_assign_cost[CS_MATRIX_N_FILL_TYPES];
343 
344  /* Measured operation costs for each available operation, or -1 otherwise
345  fill_type*2 + exclude_diagonal_flag */
346 
347  double matrix_vector_cost[CS_MATRIX_N_FILL_TYPES][2][2];
348 
349 };
350 
353 /*=============================================================================
354  * Semi-private function prototypes
355  *============================================================================*/
356 
357 /*----------------------------------------------------------------------------
358  * Create CSR matrix coefficients.
359  *
360  * returns:
361  * pointer to allocated CSR coefficients structure.
362  *----------------------------------------------------------------------------*/
363 
364 cs_matrix_coeff_csr_t *
366 
367 /*----------------------------------------------------------------------------
368  * Destroy CSR matrix coefficients.
369  *
370  * parameters:
371  * coeff <-> Pointer to CSR matrix coefficients pointer
372  *----------------------------------------------------------------------------*/
373 
374 void
375 cs_matrix_destroy_coeff_csr(cs_matrix_coeff_csr_t **coeff);
376 
377 /*----------------------------------------------------------------------------
378  * Release shared CSR matrix coefficients.
379  *
380  * parameters:
381  * matrix <-- Pointer to matrix structure
382  *----------------------------------------------------------------------------*/
383 
384 void
386 
387 /*----------------------------------------------------------------------------
388  * Copy diagonal of CSR matrix.
389  *
390  * parameters:
391  * matrix <-- Pointer to matrix structure
392  * da --> Diagonal (pre-allocated, size: n_rows)
393  *----------------------------------------------------------------------------*/
394 
395 void
397  cs_real_t *restrict da);
398 
399 /*----------------------------------------------------------------------------
400  * Destroy CSR matrix structure.
401  *
402  * parameters:
403  * matrix <-> Pointer to CSR matrix structure pointer
404  *----------------------------------------------------------------------------*/
405 
406 void
407 cs_matrix_destroy_struct_csr(cs_matrix_struct_csr_t **matrix);
408 
409 /*----------------------------------------------------------------------------
410  * Local matrix.vector product y = A.x with CSR matrix.
411  *
412  * parameters:
413  * exclude_diag <-- exclude diagonal if true
414  * matrix <-- Pointer to matrix structure
415  * x <-- Multipliying vector values
416  * y --> Resulting vector
417  *----------------------------------------------------------------------------*/
418 
419 void
420 cs_matrix_vec_p_l_csr(bool exclude_diag,
421  const cs_matrix_t *matrix,
422  const cs_real_t *restrict x,
423  cs_real_t *restrict y);
424 
425 #if defined (HAVE_MKL)
426 /*----------------------------------------------------------------------------
427  * Local matrix.vector product y = A.x with MSR matrix, using MKL
428  *
429  * parameters:
430  * exclude_diag <-- exclude diagonal if true
431  * matrix <-- Pointer to matrix structure
432  * x <-- Multipliying vector values
433  * y --> Resulting vector
434  *----------------------------------------------------------------------------*/
435 
436 void
437 cs_matrix_vec_p_l_csr_mkl(bool exclude_diag,
438  const cs_matrix_t *matrix,
439  const cs_real_t *restrict x,
440  cs_real_t *restrict y);
441 
442 #endif /* defined (HAVE_MKL) */
443 
444 /*----------------------------------------------------------------------------
445  * Copy diagonal of native or MSR matrix.
446  *
447  * parameters:
448  * matrix <-- Pointer to matrix structure
449  * da --> Diagonal (pre-allocated, size: n_cols)
450  *----------------------------------------------------------------------------*/
451 
452 void
454  cs_real_t *restrict da);
455 
456 /*----------------------------------------------------------------------------
457  * Create MSR matrix coefficients.
458  *
459  * returns:
460  * pointer to allocated MSR coefficients structure.
461  *----------------------------------------------------------------------------*/
462 
463 cs_matrix_coeff_msr_t *
465 
466 /*----------------------------------------------------------------------------
467  * Release shared MSR matrix coefficients.
468  *
469  * parameters:
470  * matrix <-- Pointer to matrix structure
471  *----------------------------------------------------------------------------*/
472 
473 void
475 
476 /*----------------------------------------------------------------------------
477  * Local matrix.vector product y = A.x with MSR matrix.
478  *
479  * parameters:
480  * exclude_diag <-- exclude diagonal if true
481  * matrix <-- Pointer to matrix structure
482  * x <-- Multipliying vector values
483  * y --> Resulting vector
484  *----------------------------------------------------------------------------*/
485 
486 void
487 cs_matrix_vec_p_l_msr(bool exclude_diag,
488  const cs_matrix_t *matrix,
489  const cs_real_t *restrict x,
490  cs_real_t *restrict y);
491 
492 #if defined (HAVE_MKL)
493 /*----------------------------------------------------------------------------
494  * Local matrix.vector product y = A.x with MSR matrix, using MKL
495  *
496  * parameters:
497  * exclude_diag <-- exclude diagonal if true
498  * matrix <-- Pointer to matrix structure
499  * x <-- Multipliying vector values
500  * y --> Resulting vector
501  *----------------------------------------------------------------------------*/
502 
503 void
504 cs_matrix_vec_p_l_msr_mkl(bool exclude_diag,
505  const cs_matrix_t *matrix,
506  const cs_real_t *restrict x,
507  cs_real_t *restrict y);
508 #endif /* defined (HAVE_MKL) */
509 
510 /*----------------------------------------------------------------------------*/
511 
513 
514 #endif /* __CS_MATRIX_PRIV_H__ */
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:280
#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:448
Definition: cs_matrix.h:79
Definition: cs_halo.h:70
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:296
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:89
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:54
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:302
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
#define END_C_DECLS
Definition: cs_defs.h:449
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:66