programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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-2013 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 interleaved,
67  bool copy,
68  const cs_real_t *restrict da,
69  const cs_real_t *restrict xa);
70 
71 typedef void
72 (cs_matrix_release_coeffs_t) (cs_matrix_t *matrix);
73 
74 typedef void
75 (cs_matrix_copy_diagonal_t) (const cs_matrix_t *matrix,
76  cs_real_t *restrict da);
77 
78 typedef void
79 (cs_matrix_vector_product_t) (bool exclude_diag,
80  const cs_matrix_t *matrix,
81  const cs_real_t *restrict x,
82  cs_real_t *restrict y);
83 
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_cells; /* Local number of cells */
100  cs_lnum_t n_cells_ext; /* Local number of participating cells
101  (cells + ghost cells sharing a face) */
102  cs_lnum_t n_faces; /* Local number of faces
103  (for extra-diagonal terms */
104 
105  /* Pointers to shared arrays */
106 
107  const cs_lnum_t *face_cell; /* Face -> cells connectivity (1 to n) */
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; /* Local number of columns
139  (> n_rows in case of ghost cells) */
140  cs_lnum_t n_cols_max; /* Maximum number of nonzero values
141  on a given row */
142 
143  /* Pointers to structure arrays and info (row_index, col_id) */
144 
145  bool have_diag; /* Has non-zero diagonal */
146  bool direct_assembly; /* True if each value corresponds to
147  a unique face ; false if multiple
148  faces contribute to the same
149  value (i.e. we have split faces) */
150 
151  cs_lnum_t *row_index; /* Row index (0 to n-1) */
152  cs_lnum_t *col_id; /* Column id (0 to n-1) */
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  int n_prefetch_rows; /* Number of rows at a time for which
162  the x values in y = Ax should be
163  prefetched (0 if no prefetch) */
164 
165  cs_real_t *val; /* Matrix coefficients */
166 
167  cs_real_t *x_prefetch; /* Prefetch array for x in y = Ax */
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 cells) */
186  cs_lnum_t n_cols_max; /* Maximum number of nonzero values
187  on a given row */
188 
189  /* Pointers to structure arrays and info (row_index, col_id) */
190 
191  bool have_diag; /* Has non-zero diagonal */
192  bool direct_assembly; /* True if each value corresponds to
193  a unique face ; false if multiple
194  faces contribute to the same
195  value (i.e. we have split faces) */
196 
197  cs_lnum_t *row_index; /* Row index (0 to n-1) */
198  cs_lnum_t *col_id; /* Column id (0 to n-1) */
199 
200 } cs_matrix_struct_csr_sym_t;
201 
202 /* symmetric CSR matrix coefficients representation */
203 /*--------------------------------------------------*/
204 
205 typedef struct _cs_matrix_coeff_csr_sym_t {
206 
207  cs_real_t *val; /* Matrix coefficients */
208 
209  /* Pointers to auxiliary arrays used for queries */
210 
211  const cs_real_t *d_val; /* Pointer to diagonal matrix
212  coefficients, if queried */
213  cs_real_t *_d_val; /* Diagonal matrix coefficients,
214  if queried */
215 
216 } cs_matrix_coeff_csr_sym_t;
217 
218 /* MSR matrix coefficients representation */
219 /*----------------------------------------*/
220 
221 typedef struct _cs_matrix_coeff_msr_t {
222 
223  int n_prefetch_rows; /* Number of rows at a time for which
224  the x values in y = Ax should be
225  prefetched (0 if no prefetch) */
226  int max_db_size; /* Current max allocated block size */
227  int max_eb_size; /* Current max allocated extradiag block size */
228 
229  /* Pointers to possibly shared arrays */
230 
231  const cs_real_t *d_val; /* 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_real_t *x_prefetch; /* Prefetch array for x in y = Ax */
239 
240 } cs_matrix_coeff_msr_t;
241 
242 /* Matrix structure (representation-independent part) */
243 /*----------------------------------------------------*/
244 
245 struct _cs_matrix_structure_t {
246 
247  cs_matrix_type_t type; /* Matrix storage and definition type */
248 
249  cs_lnum_t n_cells; /* Local number of cells */
250  cs_lnum_t n_cells_ext; /* Local number of participating cells
251  (cells + ghost cells sharing a face) */
252  cs_lnum_t n_faces; /* Local Number of mesh faces
253  (necessary to affect coefficients) */
254 
255  void *structure; /* Matrix structure */
256 
257  /* Pointers to shared arrays from mesh structure
258  (face->cell connectivity for coefficient assignment,
259  local->local cell numbering for future info or renumbering,
260  and halo) */
261 
262  const cs_lnum_t *face_cell; /* Face -> cells connectivity (1 to n) */
263  const cs_gnum_t *cell_num; /* Global cell numbers */
264  const cs_halo_t *halo; /* Parallel or periodic halo */
265  const cs_numbering_t *numbering; /* Vectorization or thread-related
266  numbering information */
267 };
268 
269 /* Structure associated with Matrix (representation-independent part) */
270 /*--------------------------------------------------------------------*/
271 
272 struct _cs_matrix_t {
273 
274  cs_matrix_type_t type; /* Matrix storage and definition type */
275 
276  cs_lnum_t n_cells; /* Local number of cells */
277  cs_lnum_t n_cells_ext; /* Local number of participating cells
278  (cells + ghost cells sharing a face) */
279  cs_lnum_t n_faces; /* Local Number of mesh faces
280  (necessary to affect coefficients) */
281 
282  cs_matrix_fill_type_t fill_type; /* Matrix fill type */
283 
284  int db_size[4]; /* Diag Block size, including padding:
285  0: useful block size
286  1: vector block extents
287  2: matrix line extents
288  3: matrix line*column extents */
289 
290  int eb_size[4]; /* Extradiag block size, including padding:
291  0: useful block size
292  1: vector block extents
293  2: matrix line extents
294  3: matrix line*column extents */
295 
296  /* Pointer to shared structure */
297 
298  const void *structure; /* Matrix structure */
299 
300  /* Pointers to shared arrays from mesh structure
301  (face->cell connectivity for coefficient assignment,
302  local->local cell numbering for future info or renumbering,
303  and halo) */
304 
305  const cs_lnum_t *face_cell; /* Face -> cells connectivity (1 to n) */
306  const cs_gnum_t *cell_num; /* Global cell numbers */
307  const cs_halo_t *halo; /* Parallel or periodic halo */
308  const cs_numbering_t *numbering; /* Vectorization or thread-related
309  numbering information */
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  /* Loop lenght parameter for some SpMv algorithms */
327 
328  int loop_length;
329 
330 };
331 
332 /* Structure used for tuning variants */
333 /*------------------------------------*/
334 
335 struct _cs_matrix_variant_t {
336 
337  char name[32]; /* Variant name */
338 
339  cs_matrix_type_t type; /* Matrix storage and definition type */
340 
341  /* Loop lenght parameter for some SpMv algorithms */
342 
343  int loop_length;
344 
345  /* Function pointer arrays, with variants:
346  fill_type + exclude_diagonal_flag */
347 
348  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES*2];
349 
350  /* Measured structure creation cost, or -1 otherwise */
351 
352  double matrix_create_cost;
353 
354  /* Measured assignment costs for each available fill type, or -1 otherwise */
355 
356  double matrix_assign_cost[CS_MATRIX_N_FILL_TYPES];
357 
358  /* Measured operation costs for each available operation, or -1 otherwise
359  fill_type*2 + exclude_diagonal_flag */
360 
361  double matrix_vector_cost[CS_MATRIX_N_FILL_TYPES*2];
362 
363 };
364 
367 /*=============================================================================
368  * Semi-private function prototypes
369  *============================================================================*/
370 
371 /*----------------------------------------------------------------------------*/
372 
374 
375 #endif /* __CS_MATRIX_PRIV_H__ */