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  const cs_real_t *restrict da,
68  const cs_real_t *restrict xa);
69 
70 typedef void
71 (cs_matrix_release_coeffs_t) (cs_matrix_t *matrix);
72 
73 typedef void
74 (cs_matrix_copy_diagonal_t) (const cs_matrix_t *matrix,
75  cs_real_t *restrict da);
76 
77 typedef void
78 (cs_matrix_vector_product_t) (bool exclude_diag,
79  const cs_matrix_t *matrix,
80  const cs_real_t *restrict x,
81  cs_real_t *restrict y);
82 
83 /*----------------------------------------------------------------------------
84  * Matrix types
85  *----------------------------------------------------------------------------*/
86 
87 /* Native matrix structure representation */
88 /*----------------------------------------*/
89 
90 /* Note: the members of this structure are already available through the top
91  * matrix structure, but are replicated here in case of future removal
92  * from the top structure (which would require computation/assignment of
93  * matrix coefficients in another form) */
94 
95 typedef struct _cs_matrix_struct_native_t {
96 
97  cs_lnum_t n_cells; /* Local number of cells */
98  cs_lnum_t n_cells_ext; /* Local number of participating cells
99  (cells + ghost cells sharing a face) */
100  cs_lnum_t n_faces; /* Local number of faces
101  (for extra-diagonal terms */
102 
103  /* Pointers to shared arrays */
104 
105  const cs_lnum_2_t *face_cell; /* Face -> cells connectivity (0 to n-1) */
106 
107 } cs_matrix_struct_native_t;
108 
109 /* Native matrix coefficients */
110 /*----------------------------*/
111 
112 typedef struct _cs_matrix_coeff_native_t {
113 
114  bool symmetric; /* Symmetry indicator */
115  int max_db_size; /* Current max allocated diag block size */
116  int max_eb_size; /* Current max allocated extradiag block size */
117 
118  /* Pointers to possibly shared arrays */
119 
120  const cs_real_t *da; /* Diagonal terms */
121  const cs_real_t *xa; /* Extra-diagonal terms */
122 
123  /* Pointers to private arrays (NULL if shared) */
124 
125  cs_real_t *_da; /* Diagonal terms */
126  cs_real_t *_xa; /* Extra-diagonal terms */
127 
128 } cs_matrix_coeff_native_t;
129 
130 /* CSR (Compressed Sparse Row) matrix structure representation */
131 /*-------------------------------------------------------------*/
132 
133 typedef struct _cs_matrix_struct_csr_t {
134 
135  cs_lnum_t n_rows; /* Local number of rows */
136  cs_lnum_t n_cols; /* Local number of columns
137  (> n_rows in case of ghost cells) */
138  cs_lnum_t n_cols_max; /* Maximum number of nonzero values
139  on a given row */
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  cs_lnum_t *row_index; /* Row index (0 to n-1) */
150  cs_lnum_t *col_id; /* Column id (0 to n-1) */
151 
152 } cs_matrix_struct_csr_t;
153 
154 /* CSR matrix coefficients representation */
155 /*----------------------------------------*/
156 
157 typedef struct _cs_matrix_coeff_csr_t {
158 
159  int n_prefetch_rows; /* Number of rows at a time for which
160  the x values in y = Ax should be
161  prefetched (0 if no prefetch) */
162 
163  cs_real_t *val; /* Matrix coefficients */
164 
165  cs_real_t *x_prefetch; /* Prefetch array for x in y = Ax */
166 
167  /* Pointers to auxiliary arrays used for queries */
168 
169  const cs_real_t *d_val; /* Pointer to diagonal matrix
170  coefficients, if queried */
171  cs_real_t *_d_val; /* Diagonal matrix coefficients,
172  if queried */
173 
174 } cs_matrix_coeff_csr_t;
175 
176 /* CSR_SYM (Symmetric Compressed Sparse Row) matrix structure representation */
177 /*---------------------------------------------------------------------------*/
178 
179 typedef struct _cs_matrix_struct_csr_sym_t {
180 
181  cs_lnum_t n_rows; /* Local number of rows */
182  cs_lnum_t n_cols; /* Local number of columns
183  (> n_rows in case of ghost cells) */
184  cs_lnum_t n_cols_max; /* Maximum number of nonzero values
185  on a given row */
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 n_prefetch_rows; /* Number of rows at a time for which
222  the x values in y = Ax should be
223  prefetched (0 if no prefetch) */
224  int max_db_size; /* Current max allocated block size */
225  int max_eb_size; /* Current max allocated extradiag block size */
226 
227  /* Pointers to possibly shared arrays */
228 
229  const cs_real_t *d_val; /* 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_real_t *x_prefetch; /* Prefetch array for x in y = Ax */
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_cells; /* Local number of cells */
248  cs_lnum_t n_cells_ext; /* Local number of participating cells
249  (cells + ghost cells sharing a face) */
250  cs_lnum_t n_faces; /* Local Number of mesh faces
251  (necessary to affect coefficients) */
252 
253  void *structure; /* Matrix structure */
254 
255  /* Pointers to shared arrays from mesh structure
256  (face->cell connectivity for coefficient assignment,
257  local->local cell numbering for future info or renumbering,
258  and halo) */
259 
260  const cs_lnum_2_t *face_cell; /* Face -> cells connectivity */
261  const cs_gnum_t *cell_num; /* Global cell numbers */
262  const cs_halo_t *halo; /* Parallel or periodic halo */
263  const cs_numbering_t *numbering; /* Vectorization or thread-related
264  numbering information */
265 };
266 
267 /* Structure associated with Matrix (representation-independent part) */
268 /*--------------------------------------------------------------------*/
269 
270 struct _cs_matrix_t {
271 
272  cs_matrix_type_t type; /* Matrix storage and definition type */
273 
274  cs_lnum_t n_cells; /* Local number of cells */
275  cs_lnum_t n_cells_ext; /* Local number of participating cells
276  (cells + ghost cells sharing a face) */
277  cs_lnum_t n_faces; /* Local Number of mesh faces
278  (necessary to affect coefficients) */
279 
280  cs_matrix_fill_type_t fill_type; /* Matrix fill type */
281 
282  int db_size[4]; /* Diag 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  int eb_size[4]; /* Extradiag block size, including padding:
289  0: useful block size
290  1: vector block extents
291  2: matrix line extents
292  3: matrix line*column extents */
293 
294  /* Pointer to shared structure */
295 
296  const void *structure; /* Matrix structure */
297 
298  /* Pointers to shared arrays from mesh structure
299  (face->cell connectivity for coefficient assignment,
300  local->local cell numbering for future info or renumbering,
301  and halo) */
302 
303  const cs_lnum_2_t *face_cell; /* Face -> cells connectivity */
304  const cs_gnum_t *cell_num; /* Global cell numbers */
305  const cs_halo_t *halo; /* Parallel or periodic halo */
306  const cs_numbering_t *numbering; /* Vectorization or thread-related
307  numbering information */
308 
309  /* Pointers to shared arrays from coefficient assignment
310  these may become NULL in the future if coefficients are passed
311  directly from non "native" types, so precautions may need to be
312  taken when accessing those */
313 
314  const cs_real_t *xa; /* Extra-diagonal terms */
315 
316  /* Pointer to private data */
317 
318  void *coeffs; /* Matrix coefficients */
319 
320  /* Function pointers */
321 
322  cs_matrix_set_coeffs_t *set_coefficients;
323  cs_matrix_release_coeffs_t *release_coefficients;
324  cs_matrix_copy_diagonal_t *copy_diagonal;
325 
326  /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants:
327  fill_type*2 + exclude_diagonal_flag */
328 
329  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
330 
331  /* Loop length parameter for some SpMv algorithms */
332 
333  int loop_length[CS_MATRIX_N_FILL_TYPES][2];
334 
335 };
336 
337 /* Structure used for tuning variants */
338 /*------------------------------------*/
339 
340 struct _cs_matrix_variant_t {
341 
342  char name[32]; /* Variant name */
343 
344  cs_matrix_type_t type; /* Matrix storage and definition type */
345 
346  /* Loop length parameter for some SpMv algorithms */
347 
348  int loop_length[CS_MATRIX_N_FILL_TYPES][2];
349 
350  /* Function pointer arrays, with variants:
351  fill_type + exclude_diagonal_flag */
352 
353  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES][2];
354 
355  /* Measured structure creation cost, or -1 otherwise */
356 
357  double matrix_create_cost;
358 
359  /* Measured assignment costs for each available fill type, or -1 otherwise */
360 
361  double matrix_assign_cost[CS_MATRIX_N_FILL_TYPES];
362 
363  /* Measured operation costs for each available operation, or -1 otherwise
364  fill_type*2 + exclude_diagonal_flag */
365 
366  double matrix_vector_cost[CS_MATRIX_N_FILL_TYPES][2];
367 
368 };
369 
372 /*=============================================================================
373  * Semi-private function prototypes
374  *============================================================================*/
375 
376 /*----------------------------------------------------------------------------*/
377 
379 
380 #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
#define BEGIN_C_DECLS
Definition: cs_defs.h:419
Definition: cs_matrix.h:76
Definition: cs_halo.h:70
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:86
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:420
double cs_real_t
Definition: cs_defs.h:296
Definition: cs_numbering.h:78
cs_matrix_fill_type_t
Definition: cs_matrix.h:66