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-2015 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  cs_lnum_t n_cols_max; /* Maximum number of nonzero values
140  on a given row */
141 
142  /* Pointers to structure arrays and info (row_index, col_id) */
143 
144  bool have_diag; /* Has non-zero diagonal */
145  bool direct_assembly; /* True if each value corresponds to
146  a unique face ; false if multiple
147  faces contribute to the same
148  value (i.e. we have split faces) */
149 
150  const cs_lnum_t *row_index; /* Pointer to row index (0 to n-1) */
151  const cs_lnum_t *col_id; /* Pointer to column id (0 to n-1) */
152 
153  cs_lnum_t *_row_index; /* Row index (0 to n-1), if owner */
154  cs_lnum_t *_col_id; /* Column id (0 to n-1), if owner */
155 
156 } cs_matrix_struct_csr_t;
157 
158 /* CSR matrix coefficients representation */
159 /*----------------------------------------*/
160 
161 typedef struct _cs_matrix_coeff_csr_t {
162 
163  /* Pointers to possibly shared arrays */
164 
165  const cs_real_t *val; /* Matrix coefficients */
166 
167  /* Pointers to private arrays (NULL if shared) */
168 
169  cs_real_t *_val; /* Diagonal matrix coefficients */
170 
171  /* Pointers to auxiliary arrays used for queries */
172 
173  const cs_real_t *d_val; /* Pointer to diagonal matrix
174  coefficients, if queried */
175  cs_real_t *_d_val; /* Diagonal matrix coefficients,
176  if queried */
177 
178 } cs_matrix_coeff_csr_t;
179 
180 /* CSR_SYM (Symmetric Compressed Sparse Row) matrix structure representation */
181 /*---------------------------------------------------------------------------*/
182 
183 typedef struct _cs_matrix_struct_csr_sym_t {
184 
185  cs_lnum_t n_rows; /* Local number of rows */
186  cs_lnum_t n_cols; /* Local number of columns
187  (> n_rows in case of ghost columns) */
188  cs_lnum_t n_cols_max; /* Maximum number of nonzero values
189  on a given row */
190 
191  /* Pointers to structure arrays and info (row_index, col_id) */
192 
193  bool have_diag; /* Has non-zero diagonal */
194  bool direct_assembly; /* True if each value corresponds to
195  a unique face ; false if multiple
196  faces contribute to the same
197  value (i.e. we have split faces) */
198 
199  cs_lnum_t *row_index; /* Row index (0 to n-1) */
200  cs_lnum_t *col_id; /* Column id (0 to n-1) */
201 
202 } cs_matrix_struct_csr_sym_t;
203 
204 /* symmetric CSR matrix coefficients representation */
205 /*--------------------------------------------------*/
206 
207 typedef struct _cs_matrix_coeff_csr_sym_t {
208 
209  cs_real_t *val; /* Matrix coefficients */
210 
211  /* Pointers to auxiliary arrays used for queries */
212 
213  const cs_real_t *d_val; /* Pointer to diagonal matrix
214  coefficients, if queried */
215  cs_real_t *_d_val; /* Diagonal matrix coefficients,
216  if queried */
217 
218 } cs_matrix_coeff_csr_sym_t;
219 
220 /* MSR matrix coefficients representation */
221 /*----------------------------------------*/
222 
223 typedef struct _cs_matrix_coeff_msr_t {
224 
225  int max_db_size; /* Current max allocated block size */
226  int max_eb_size; /* Current max allocated extradiag block size */
227 
228  /* Pointers to possibly shared arrays */
229 
230  const cs_real_t *d_val; /* Diagonal matrix coefficients */
231  const cs_real_t *x_val; /* Extra-diagonal matrix coefficients */
232 
233  /* Pointers to private arrays (NULL if shared) */
234 
235  cs_real_t *_d_val; /* Diagonal matrix coefficients */
236  cs_real_t *_x_val; /* Extra-diagonal matrix coefficients */
237 
238 } cs_matrix_coeff_msr_t;
239 
240 /* Matrix structure (representation-independent part) */
241 /*----------------------------------------------------*/
242 
243 struct _cs_matrix_structure_t {
244 
245  cs_matrix_type_t type; /* Matrix storage and definition type */
246 
247  cs_lnum_t n_rows; /* Local number of rows */
248  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
249 
250  void *structure; /* Matrix structure */
251 
252  /* Pointers to shared arrays from mesh structure
253  (face->cell connectivity for coefficient assignment,
254  local->local cell numbering for future info or renumbering,
255  and halo) */
256 
257  const cs_gnum_t *row_num; /* Global row numbers */
258  const cs_halo_t *halo; /* Parallel or periodic halo */
259  const cs_numbering_t *numbering; /* Vectorization or thread-related
260  numbering information */
261 };
262 
263 /* Structure associated with Matrix (representation-independent part) */
264 /*--------------------------------------------------------------------*/
265 
266 struct _cs_matrix_t {
267 
268  cs_matrix_type_t type; /* Matrix storage and definition type */
269 
270  cs_lnum_t n_rows; /* Local number of rows */
271  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
272 
273  cs_matrix_fill_type_t fill_type; /* Matrix fill type */
274 
275  bool symmetric; /* true if coefficients are symmetric */
276 
277  int db_size[4]; /* Diag Block size, including padding:
278  0: useful block size
279  1: vector block extents
280  2: matrix line extents
281  3: matrix line*column extents */
282 
283  int eb_size[4]; /* Extradiag block size, including padding:
284  0: useful block size
285  1: vector block extents
286  2: matrix line extents
287  3: matrix line*column extents */
288 
289  /* Pointer to shared structure */
290 
291  const void *structure; /* Matrix structure */
292 
293  /* Pointers to arrays possibly shared from mesh structure
294  (graph edges: face->cell connectivity for coefficient assignment,
295  rows: local->local cell numbering for future info or renumbering,
296  and halo) */
297 
298  const cs_halo_t *halo; /* Parallel or periodic halo */
299  const cs_numbering_t *numbering; /* Vectorization or thread-related
300  numbering information */
301 
302  /* Pointer to shared arrays from coefficient assignment from
303  "native" type. This should be removed in the future, but requires
304  removing the dependency to the native structure in the multigrid
305  code first. */
306 
307  const cs_real_t *xa; /* Extra-diagonal terms */
308 
309  /* Pointer to private data */
310 
311  void *coeffs; /* Matrix coefficients */
312 
313  /* Function pointers */
314 
315  cs_matrix_set_coeffs_t *set_coefficients;
316  cs_matrix_release_coeffs_t *release_coefficients;
317  cs_matrix_copy_diagonal_t *copy_diagonal;
318 
319  /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants:
320  fill_type*2 + exclude_diagonal_flag */
321 
322  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
323 
324 };
325 
326 /* Structure used for tuning variants */
327 /*------------------------------------*/
328 
329 struct _cs_matrix_variant_t {
330 
331  char name[32]; /* Variant name */
332 
333  cs_matrix_type_t type; /* Matrix storage and definition type */
334 
335  /* Function pointer arrays, with variants:
336  fill_type + exclude_diagonal_flag */
337 
338  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
339 
340  /* Measured structure creation cost, or -1 otherwise */
341 
342  double matrix_create_cost;
343 
344  /* Measured assignment costs for each available fill type, or -1 otherwise */
345 
346  double matrix_assign_cost[CS_MATRIX_N_FILL_TYPES];
347 
348  /* Measured operation costs for each available operation, or -1 otherwise
349  fill_type*2 + exclude_diagonal_flag */
350 
351  double matrix_vector_cost[CS_MATRIX_N_FILL_TYPES][2][2];
352 
353 };
354 
357 /*=============================================================================
358  * Semi-private function prototypes
359  *============================================================================*/
360 
361 /*----------------------------------------------------------------------------
362  * Create CSR matrix coefficients.
363  *
364  * returns:
365  * pointer to allocated CSR coefficients structure.
366  *----------------------------------------------------------------------------*/
367 
368 cs_matrix_coeff_csr_t *
370 
371 /*----------------------------------------------------------------------------
372  * Destroy CSR matrix coefficients.
373  *
374  * parameters:
375  * coeff <-> Pointer to CSR matrix coefficients pointer
376  *----------------------------------------------------------------------------*/
377 
378 void
379 cs_matrix_destroy_coeff_csr(cs_matrix_coeff_csr_t **coeff);
380 
381 /*----------------------------------------------------------------------------
382  * Release shared CSR matrix coefficients.
383  *
384  * parameters:
385  * matrix <-- Pointer to matrix structure
386  *----------------------------------------------------------------------------*/
387 
388 void
390 
391 /*----------------------------------------------------------------------------
392  * Copy diagonal of CSR matrix.
393  *
394  * parameters:
395  * matrix <-- Pointer to matrix structure
396  * da --> Diagonal (pre-allocated, size: n_rows)
397  *----------------------------------------------------------------------------*/
398 
399 void
401  cs_real_t *restrict da);
402 
403 /*----------------------------------------------------------------------------
404  * Destroy CSR matrix structure.
405  *
406  * parameters:
407  * matrix <-> Pointer to CSR matrix structure pointer
408  *----------------------------------------------------------------------------*/
409 
410 void
411 cs_matrix_destroy_struct_csr(cs_matrix_struct_csr_t **matrix);
412 
413 /*----------------------------------------------------------------------------
414  * Local matrix.vector product y = A.x with CSR matrix.
415  *
416  * parameters:
417  * exclude_diag <-- exclude diagonal if true
418  * matrix <-- Pointer to matrix structure
419  * x <-- Multipliying vector values
420  * y --> Resulting vector
421  *----------------------------------------------------------------------------*/
422 
423 void
424 cs_matrix_vec_p_l_csr(bool exclude_diag,
425  const cs_matrix_t *matrix,
426  const cs_real_t *restrict x,
427  cs_real_t *restrict y);
428 
429 #if defined (HAVE_MKL)
430 /*----------------------------------------------------------------------------
431  * Local matrix.vector product y = A.x with MSR matrix, using MKL
432  *
433  * parameters:
434  * exclude_diag <-- exclude diagonal if true
435  * matrix <-- Pointer to matrix structure
436  * x <-- Multipliying vector values
437  * y --> Resulting vector
438  *----------------------------------------------------------------------------*/
439 
440 void
441 cs_matrix_vec_p_l_csr_mkl(bool exclude_diag,
442  const cs_matrix_t *matrix,
443  const cs_real_t *restrict x,
444  cs_real_t *restrict y);
445 
446 #endif /* defined (HAVE_MKL) */
447 
448 /*----------------------------------------------------------------------------
449  * Copy diagonal of native or MSR matrix.
450  *
451  * parameters:
452  * matrix <-- Pointer to matrix structure
453  * da --> Diagonal (pre-allocated, size: n_cols)
454  *----------------------------------------------------------------------------*/
455 
456 void
458  cs_real_t *restrict da);
459 
460 /*----------------------------------------------------------------------------
461  * Create MSR matrix coefficients.
462  *
463  * returns:
464  * pointer to allocated MSR coefficients structure.
465  *----------------------------------------------------------------------------*/
466 
467 cs_matrix_coeff_msr_t *
469 
470 /*----------------------------------------------------------------------------
471  * Release shared MSR matrix coefficients.
472  *
473  * parameters:
474  * matrix <-- Pointer to matrix structure
475  *----------------------------------------------------------------------------*/
476 
477 void
479 
480 /*----------------------------------------------------------------------------
481  * Local matrix.vector product y = A.x with MSR matrix.
482  *
483  * parameters:
484  * exclude_diag <-- exclude diagonal if true
485  * matrix <-- Pointer to matrix structure
486  * x <-- Multipliying vector values
487  * y --> Resulting vector
488  *----------------------------------------------------------------------------*/
489 
490 void
491 cs_matrix_vec_p_l_msr(bool exclude_diag,
492  const cs_matrix_t *matrix,
493  const cs_real_t *restrict x,
494  cs_real_t *restrict y);
495 
496 #if defined (HAVE_MKL)
497 /*----------------------------------------------------------------------------
498  * Local matrix.vector product y = A.x with MSR matrix, using MKL
499  *
500  * parameters:
501  * exclude_diag <-- exclude diagonal if true
502  * matrix <-- Pointer to matrix structure
503  * x <-- Multipliying vector values
504  * y --> Resulting vector
505  *----------------------------------------------------------------------------*/
506 
507 void
508 cs_matrix_vec_p_l_msr_mkl(bool exclude_diag,
509  const cs_matrix_t *matrix,
510  const cs_real_t *restrict x,
511  cs_real_t *restrict y);
512 #endif /* defined (HAVE_MKL) */
513 
514 /*----------------------------------------------------------------------------*/
515 
517 
518 #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:429
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)
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
void matrix(const cs_int_t *const iconvp, const cs_int_t *const idiffp, const cs_int_t *const ndircp, const cs_int_t *const isym, const cs_real_t *const thetap, const cs_int_t *const 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
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:301
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
#define END_C_DECLS
Definition: cs_defs.h:430
double cs_real_t
Definition: cs_defs.h:296
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