My Project
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-2019 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 
40 BEGIN_C_DECLS
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
224  block size */
225 
226  /* Pointers to possibly shared arrays */
227 
228  const cs_real_t *d_val; /* Diagonal matrix coefficients */
229  const cs_real_t *x_val; /* Extra-diagonal matrix coefficients */
230 
231  /* Pointers to private arrays (NULL if shared) */
232 
233  cs_real_t *_d_val; /* Diagonal matrix coefficients */
234  cs_real_t *_x_val; /* Extra-diagonal matrix coefficients */
235 
236 } cs_matrix_coeff_msr_t;
237 
238 /* Matrix structure (representation-independent part) */
239 /*----------------------------------------------------*/
240 
241 struct _cs_matrix_structure_t {
242 
243  cs_matrix_type_t type; /* Matrix storage and definition type */
244 
245  cs_lnum_t n_rows; /* Local number of rows */
246  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
247 
248  void *structure; /* Matrix structure */
249 
250  /* Pointers to shared arrays from mesh structure
251  (face->cell connectivity for coefficient assignment,
252  local->local cell numbering for future info or renumbering,
253  and halo) */
254 
255  const cs_halo_t *halo; /* Parallel or periodic halo */
256  const cs_numbering_t *numbering; /* Vectorization or thread-related
257  numbering information */
258 
259  const cs_matrix_assembler_t *assembler; /* Associated matrix assembler */
260 };
261 
262 /* Structure associated with Matrix (representation-independent part) */
263 /*--------------------------------------------------------------------*/
264 
265 struct _cs_matrix_t {
266 
267  cs_matrix_type_t type; /* Matrix storage and definition type */
268 
269  cs_lnum_t n_rows; /* Local number of rows */
270  cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
271 
272  cs_matrix_fill_type_t fill_type; /* Matrix fill type */
273 
274  bool symmetric; /* true if coefficients are symmetric */
275 
276  cs_lnum_t db_size[4]; /* Diag Block size, including padding:
277  0: useful block size
278  1: vector block extents
279  2: matrix line extents
280  3: matrix line*column extents */
281 
282  cs_lnum_t eb_size[4]; /* Extradiag block size, including padding:
283  0: useful block size
284  1: vector block extents
285  2: matrix line extents
286  3: matrix line*column extents */
287 
288  /* Pointer to shared structure */
289 
290  const void *structure; /* Possibly shared matrix structure */
291  void *_structure; /* Private 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  const cs_matrix_assembler_t *assembler; /* Associated matrix assembler */
303 
304  /* Pointer to shared arrays from coefficient assignment from
305  "native" type. This should be removed in the future, but requires
306  removing the dependency to the native structure in the multigrid
307  code first. */
308 
309  const cs_real_t *xa; /* Extra-diagonal terms */
310 
311  /* Pointer to private data */
312 
313  void *coeffs; /* Matrix coefficients */
314 
315  /* Function pointers */
316 
317  cs_matrix_set_coeffs_t *set_coefficients;
318  cs_matrix_release_coeffs_t *release_coefficients;
319  cs_matrix_copy_diagonal_t *copy_diagonal;
320 
321  /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants:
322  fill_type*2 + exclude_diagonal_flag */
323 
324  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
325 
326 };
327 
328 /* Structure used for tuning variants */
329 /*------------------------------------*/
330 
331 struct _cs_matrix_variant_t {
332 
333  char name[32]; /* Variant name */
334 
335  cs_matrix_type_t type; /* Matrix storage and definition type */
336 
337  /* Function pointer arrays, with variants:
338  fill_type + exclude_diagonal_flag */
339 
340  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
341 
342  /* Measured structure creation cost, or -1 otherwise */
343 
344  double matrix_create_cost;
345 
346  /* Measured assignment costs for each available fill type, or -1 otherwise */
347 
348  double matrix_assign_cost[CS_MATRIX_N_FILL_TYPES];
349 
350  /* Measured operation costs for each available operation, or -1 otherwise
351  fill_type*2 + exclude_diagonal_flag */
352 
353  double matrix_vector_cost[CS_MATRIX_N_FILL_TYPES][2][2];
354 
355 };
356 
359 /*=============================================================================
360  * Semi-private function prototypes
361  *============================================================================*/
362 
363 /*----------------------------------------------------------------------------
364  * Create CSR matrix coefficients.
365  *
366  * returns:
367  * pointer to allocated CSR coefficients structure.
368  *----------------------------------------------------------------------------*/
369 
370 cs_matrix_coeff_csr_t *
371 cs_matrix_create_coeff_csr(void);
372 
373 /*----------------------------------------------------------------------------
374  * Destroy CSR matrix coefficients.
375  *
376  * parameters:
377  * coeff <-> Pointer to CSR matrix coefficients pointer
378  *----------------------------------------------------------------------------*/
379 
380 void
381 cs_matrix_destroy_coeff_csr(cs_matrix_coeff_csr_t **coeff);
382 
383 /*----------------------------------------------------------------------------
384  * Release shared CSR matrix coefficients.
385  *
386  * parameters:
387  * matrix <-- Pointer to matrix structure
388  *----------------------------------------------------------------------------*/
389 
390 void
391 cs_matrix_release_coeffs_csr(cs_matrix_t *matrix);
392 
393 /*----------------------------------------------------------------------------
394  * Copy diagonal of CSR matrix.
395  *
396  * parameters:
397  * matrix <-- Pointer to matrix structure
398  * da --> Diagonal (pre-allocated, size: n_rows)
399  *----------------------------------------------------------------------------*/
400 
401 void
402 cs_matrix_copy_diagonal_csr(const cs_matrix_t *matrix,
403  cs_real_t *restrict da);
404 
405 /*----------------------------------------------------------------------------
406  * Destroy CSR matrix structure.
407  *
408  * parameters:
409  * matrix <-> Pointer to CSR matrix structure pointer
410  *----------------------------------------------------------------------------*/
411 
412 void
413 cs_matrix_destroy_struct_csr(cs_matrix_struct_csr_t **matrix);
414 
415 /*----------------------------------------------------------------------------
416  * Local matrix.vector product y = A.x with CSR matrix.
417  *
418  * parameters:
419  * exclude_diag <-- exclude diagonal if true
420  * matrix <-- Pointer to matrix structure
421  * x <-- Multipliying vector values
422  * y --> Resulting vector
423  *----------------------------------------------------------------------------*/
424 
425 void
426 cs_matrix_vec_p_l_csr(bool exclude_diag,
427  const cs_matrix_t *matrix,
428  const cs_real_t *restrict x,
429  cs_real_t *restrict y);
430 
431 #if defined (HAVE_MKL)
432 /*----------------------------------------------------------------------------
433  * Local matrix.vector product y = A.x with MSR matrix, using MKL
434  *
435  * parameters:
436  * exclude_diag <-- exclude diagonal if true
437  * matrix <-- Pointer to matrix structure
438  * x <-- Multipliying vector values
439  * y --> Resulting vector
440  *----------------------------------------------------------------------------*/
441 
442 void
443 cs_matrix_vec_p_l_csr_mkl(bool exclude_diag,
444  const cs_matrix_t *matrix,
445  const cs_real_t *restrict x,
446  cs_real_t *restrict y);
447 
448 #endif /* defined (HAVE_MKL) */
449 
450 /*----------------------------------------------------------------------------
451  * Copy diagonal of native or MSR matrix.
452  *
453  * parameters:
454  * matrix <-- Pointer to matrix structure
455  * da --> Diagonal (pre-allocated, size: n_cols)
456  *----------------------------------------------------------------------------*/
457 
458 void
459 cs_matrix_copy_diagonal_separate(const cs_matrix_t *matrix,
460  cs_real_t *restrict da);
461 
462 /*----------------------------------------------------------------------------
463  * Create MSR matrix coefficients.
464  *
465  * returns:
466  * pointer to allocated MSR coefficients structure.
467  *----------------------------------------------------------------------------*/
468 
469 cs_matrix_coeff_msr_t *
470 cs_matrix_create_coeff_msr(void);
471 
472 /*----------------------------------------------------------------------------
473  * Release shared MSR matrix coefficients.
474  *
475  * parameters:
476  * matrix <-- Pointer to matrix structure
477  *----------------------------------------------------------------------------*/
478 
479 void
480 cs_matrix_release_coeffs_msr(cs_matrix_t *matrix);
481 
482 /*----------------------------------------------------------------------------
483  * Local matrix.vector product y = A.x with MSR matrix.
484  *
485  * parameters:
486  * exclude_diag <-- exclude diagonal if true
487  * matrix <-- Pointer to matrix structure
488  * x <-- Multipliying vector values
489  * y --> Resulting vector
490  *----------------------------------------------------------------------------*/
491 
492 void
493 cs_matrix_vec_p_l_msr(bool exclude_diag,
494  const cs_matrix_t *matrix,
495  const cs_real_t *restrict x,
496  cs_real_t *restrict y);
497 
498 #if defined (HAVE_MKL)
499 /*----------------------------------------------------------------------------
500  * Local matrix.vector product y = A.x with MSR matrix, using MKL
501  *
502  * parameters:
503  * exclude_diag <-- exclude diagonal if true
504  * matrix <-- Pointer to matrix structure
505  * x <-- Multipliying vector values
506  * y --> Resulting vector
507  *----------------------------------------------------------------------------*/
508 
509 void
510 cs_matrix_vec_p_l_msr_mkl(bool exclude_diag,
511  const cs_matrix_t *matrix,
512  const cs_real_t *restrict x,
513  cs_real_t *restrict y);
514 #endif /* defined (HAVE_MKL) */
515 
516 /*----------------------------------------------------------------------------*/
517 
518 END_C_DECLS
519 
520 #endif /* __CS_MATRIX_PRIV_H__ */
cs_matrix_destroy_struct_csr
void cs_matrix_destroy_struct_csr(cs_matrix_struct_csr_t **matrix)
cs_defs.h
CS_MATRIX_N_FILL_TYPES
Definition: cs_matrix.h:80
cs_matrix_vec_p_l_msr
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)
restrict
#define restrict
Definition: cs_defs.h:127
END_C_DECLS
#define END_C_DECLS
Definition: cs_defs.h:468
cs_real_t
double cs_real_t
Floating-point value.
Definition: cs_defs.h:302
BEGIN_C_DECLS
#define BEGIN_C_DECLS
Definition: cs_defs.h:467
cs_matrix_t
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:90
cs_matrix_create_coeff_csr
cs_matrix_coeff_csr_t * cs_matrix_create_coeff_csr(void)
cs_numbering_t
Definition: cs_numbering.h:83
da
void const int const int const int const cs_real_t const int const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t cs_real_t da[]
Definition: cs_matrix_building.h:65
y
void const cs_lnum_t *const const cs_real_t *const const cs_real_t *const const cs_real_t *const const cs_real_t *const y
Definition: cs_wall_functions.h:1147
cs_matrix_copy_diagonal_csr
void cs_matrix_copy_diagonal_csr(const cs_matrix_t *matrix, cs_real_t *restrict da)
cs_lnum_t
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:298
cs_halo_t
Definition: cs_halo.h:71
cs_matrix_assembler_t
struct _cs_matrix_assembler_t cs_matrix_assembler_t
Definition: cs_matrix_assembler.h:61
cs_matrix_create_coeff_msr
cs_matrix_coeff_msr_t * cs_matrix_create_coeff_msr(void)
cs_lnum_2_t
int cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:308
cs_matrix_fill_type_t
cs_matrix_fill_type_t
Definition: cs_matrix.h:67
cs_matrix_type_t
cs_matrix_type_t
Definition: cs_matrix.h:55
cs_matrix_release_coeffs_msr
void cs_matrix_release_coeffs_msr(cs_matrix_t *matrix)
cs_matrix_release_coeffs_csr
void cs_matrix_release_coeffs_csr(cs_matrix_t *matrix)
cs_matrix.h
cs_matrix_destroy_coeff_csr
void cs_matrix_destroy_coeff_csr(cs_matrix_coeff_csr_t **coeff)
cs_matrix_vec_p_l_csr
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)
type
void const cs_int_t * type
Definition: cs_measures_util.h:425
xa
void const int const int const int const cs_real_t const int const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t const cs_real_t cs_real_t cs_real_t xa[]
Definition: cs_matrix_building.h:65
cs_matrix_copy_diagonal_separate
void cs_matrix_copy_diagonal_separate(const cs_matrix_t *matrix, cs_real_t *restrict da)
Generated on Thu Apr 9 2020 17:26:56 for My Project by   doxygen 1.8.16