programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_matrix.h
Go to the documentation of this file.
1 #ifndef __CS_MATRIX_H__
2 #define __CS_MATRIX_H__
3 
4 /*============================================================================
5  * 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_halo.h"
37 #include "cs_numbering.h"
38 #include "cs_halo_perio.h"
39 
40 /*----------------------------------------------------------------------------*/
41 
43 
44 /*============================================================================
45  * Macro definitions
46  *============================================================================*/
47 
48 /*============================================================================
49  * Type definitions
50  *============================================================================*/
51 
52 /* Matrix structure representation types */
53 
54 typedef enum {
55 
56  CS_MATRIX_NATIVE, /* Native matrix format */
57  CS_MATRIX_CSR, /* Compressed Sparse Row storage format */
58  CS_MATRIX_CSR_SYM, /* Compressed Symmetric Sparse Row storage format */
59  CS_MATRIX_MSR, /* Modified Compressed Sparse Row storage format */
60  CS_MATRIX_N_TYPES /* Number of known matrix types */
61 
63 
64 /* Matrix fill types (for tuning) */
65 
66 typedef enum {
67 
68  CS_MATRIX_SCALAR, /* Simple calar matrix */
69  CS_MATRIX_SCALAR_SYM, /* Simple scalar symmetric matrix */
70  CS_MATRIX_33_BLOCK_D, /* Matrix with 3x3 diagonal blocks
71  (and 3.I extradiagonal blocks) */
72  CS_MATRIX_33_BLOCK_D_SYM, /* Symmetric matrix with 3x3 diagonal blocks
73  (and 3.I extradiagonal blocks) */
74  CS_MATRIX_33_BLOCK, /* Matrix with 3x3 blocks
75  (diagonal and extra-diagonal) */
76  CS_MATRIX_N_FILL_TYPES /* Number of possible matrix fill types */
77 
79 
80 /* Structure associated with opaque matrix structure object */
81 
82 typedef struct _cs_matrix_structure_t cs_matrix_structure_t;
83 
84 /* Structure associated with opaque matrix object */
85 
86 typedef struct _cs_matrix_t cs_matrix_t;
87 
88 /* Structure associated with opaque matrix tuning results object */
89 
90 typedef struct _cs_matrix_variant_t cs_matrix_variant_t;
91 
92 /*============================================================================
93  * Global variables
94  *============================================================================*/
95 
96 /* Short names for matrix types */
97 
98 extern const char *cs_matrix_type_name[];
99 
100 /* Full names for matrix types */
101 
102 extern const char *cs_matrix_type_fullname[];
103 
106 
107 /*=============================================================================
108  * Public function prototypes for Fortran API
109  *============================================================================*/
110 
111 void CS_PROCF(promav, PROMAV)
112 (
113  const cs_int_t *isym, /* <-- Symmetry indicator:
114  1: symmetric; 2: not symmetric */
115  const cs_int_t *ibsize, /* <-- Block size of diagonal element */
116  const cs_int_t *iesize, /* <-- Block size of element ij */
117  const cs_int_t *iinvpe, /* <-- Indicator to cancel increments
118  in rotational periodicty (2) or
119  to exchange them as scalars (1) */
120  const cs_real_t *dam, /* <-- Matrix diagonal */
121  const cs_real_t *xam, /* <-- Matrix extra-diagonal terms */
122  cs_real_t *vx, /* <-- A*vx */
123  cs_real_t *vy /* <-> vy = A*vx */
124  );
125 
126 /*=============================================================================
127  * Public function prototypes
128  *============================================================================*/
129 
130 /*----------------------------------------------------------------------------
131  * Initialize sparse matrix API.
132  *----------------------------------------------------------------------------*/
133 
134 void
136 
137 /*----------------------------------------------------------------------------
138  * Finalize sparse matrix API.
139  *----------------------------------------------------------------------------*/
140 
141 void
142 cs_matrix_finalize(void);
143 
144 /*----------------------------------------------------------------------------
145  * Update sparse matrix API in case of mesh modification.
146  *----------------------------------------------------------------------------*/
147 
148 void
150 
151 /*----------------------------------------------------------------------------
152  * Create a matrix Structure.
153  *
154  * Note that the structure created maps to the given existing
155  * cell global number, face -> cell connectivity arrays, and cell halo
156  * structure, so it must be destroyed before they are freed
157  * (usually along with the code's main face -> cell structure).
158  *
159  * Note that the resulting matrix structure will contain either a full or
160  * an empty main diagonal, and that the extra-diagonal structure is always
161  * symmetric (though the coefficients my not be, and we may choose a
162  * matrix format that does not exploit ths symmetry). If the face_cell
163  * connectivity argument is NULL, the matrix will be purely diagonal.
164  *
165  * parameters:
166  * type <-- Type of matrix considered
167  * have_diag <-- Indicates if the diagonal structure contains nonzeroes
168  * n_cells <-- Local number of cells
169  * n_cells_ext <-- Local number of cells + ghost cells sharing a face
170  * n_faces <-- Local number of internal faces
171  * cell_num <-- Optional global cell numbers (1 to n), or NULL
172  * face_cell <-- Face -> cells connectivity (1 to n)
173  * halo <-- Halo structure associated with cells, or NULL
174  * numbering <-- vectorization or thread-related numbering info, or NULL
175  *
176  * returns:
177  * pointer to created matrix structure;
178  *----------------------------------------------------------------------------*/
179 
182  bool have_diag,
183  cs_lnum_t n_cells,
184  cs_lnum_t n_cells_ext,
185  cs_lnum_t n_faces,
186  const cs_gnum_t *cell_num,
187  const cs_lnum_t *face_cell,
188  const cs_halo_t *halo,
189  const cs_numbering_t *numbering);
190 
191 /*----------------------------------------------------------------------------
192  * Create a matrix container using a given structure and tuning info.
193  *
194  * If the matrix variant is incompatible with the structure, it is ignored.
195  *
196  * parameters:
197  * ms <-- Associated matrix structure
198  * mv <-- Associated matrix variant
199  *
200  * returns:
201  * pointer to created matrix structure;
202  *----------------------------------------------------------------------------*/
203 
204 cs_matrix_t *
206  const cs_matrix_variant_t *mv);
207 
208 /*----------------------------------------------------------------------------
209  * Destroy a matrix structure.
210  *
211  * parameters:
212  * ms <-> Pointer to matrix structure pointer
213  *----------------------------------------------------------------------------*/
214 
215 void
217 
218 /*----------------------------------------------------------------------------
219  * Create a matrix container using a given structure.
220  *
221  * Note that the matrix container maps to the assigned structure,
222  * so it must be destroyed before that structure.
223  *
224  * parameters:
225  * ms <-- Associated matrix structure
226  *
227  * returns:
228  * pointer to created matrix structure;
229  *----------------------------------------------------------------------------*/
230 
231 cs_matrix_t *
233 
234 /*----------------------------------------------------------------------------
235  * Destroy a matrix structure.
236  *
237  * parameters:
238  * matrix <-> Pointer to matrix structure pointer
239  *----------------------------------------------------------------------------*/
240 
241 void
243 
244 /*----------------------------------------------------------------------------
245  * Return number of columns in matrix.
246  *
247  * parameters:
248  * matrix --> Pointer to matrix structure
249  *----------------------------------------------------------------------------*/
250 
251 cs_lnum_t
253 
254 /*----------------------------------------------------------------------------
255  * Return number of rows in matrix.
256  *
257  * parameters:
258  * matrix --> Pointer to matrix structure
259  *----------------------------------------------------------------------------*/
260 
261 cs_lnum_t
263 
264 /*----------------------------------------------------------------------------
265  * Return matrix diagonal block sizes.
266  *
267  * Block sizes are defined by a array of 4 values:
268  * 0: useful block size, 1: vector block extents,
269  * 2: matrix line extents, 3: matrix line*column extents
270  *
271  * parameters:
272  * matrix <-- Pointer to matrix structure
273  *
274  * returns:
275  * pointer to block sizes
276  *----------------------------------------------------------------------------*/
277 
278 const int *
280 
281 /*----------------------------------------------------------------------------
282  * Set matrix coefficients, sharing arrays with the caller when possible.
283  *
284  * With shared arrays, the matrix becomes unusable if the arrays passed as
285  * arguments are not be modified (its coefficients should be unset first
286  * to mark this).
287  *
288  * Depending on current options and initialization, values will be copied
289  * or simply mapped.
290  *
291  * Block sizes are defined by an optional array of 4 values:
292  * 0: useful block size, 1: vector block extents,
293  * 2: matrix line extents, 3: matrix line*column extents
294  *
295  * parameters:
296  * matrix <-> Pointer to matrix structure
297  * symmetric <-- Indicates if matrix coefficients are symmetric
298  * diag_block_size <-- Block sizes for diagonal, or NULL
299  * extra_diag_block_size <-- Block sizes for extra diagonal, or NULL
300  * da <-- Diagonal values (NULL if zero)
301  * xa <-- Extradiagonal values (NULL if zero)
302  *----------------------------------------------------------------------------*/
303 
304 void
306  bool symmetric,
307  const int *diag_block_size,
308  const int *extra_diag_block_size,
309  const cs_real_t *da,
310  const cs_real_t *xa);
311 
312 /*----------------------------------------------------------------------------
313  * Set matrix coefficients in the non-interleaved case.
314  *
315  * In the symmetric case, there is no difference with the interleaved case.
316  *
317  * Depending on current options and initialization, values will be copied
318  * or simply mapped (non-symmetric values will be copied).
319  *
320  * parameters:
321  * matrix <-> Pointer to matrix structure
322  * symmetric <-- Indicates if matrix coefficients are symmetric
323  * da <-- Diagonal values (NULL if zero)
324  * xa <-- Extradiagonal values (NULL if zero)
325  *----------------------------------------------------------------------------*/
326 
327 void
329  bool symmetric,
330  const cs_real_t *da,
331  const cs_real_t *xa);
332 
333 /*----------------------------------------------------------------------------
334  * Set matrix coefficients, copying values to private arrays.
335  *
336  * With private arrays, the matrix becomes independant from the
337  * arrays passed as arguments.
338  *
339  * Block sizes are defined by an optional array of 4 values:
340  * 0: useful block size, 1: vector block extents,
341  * 2: matrix line extents, 3: matrix line*column extents
342  *
343  * parameters:
344  * matrix <-> Pointer to matrix structure
345  * symmetric <-- Indicates if matrix coefficients are symmetric
346  * diag_block_size <-- Block sizes for diagonal, or NULL
347  * extra_diag_block_size <-- Block sizes for extra diagonal, or NULL
348  * da <-- Diagonal values (NULL if zero)
349  * xa <-- Extradiagonal values (NULL if zero)
350  *----------------------------------------------------------------------------*/
351 
352 void
354  bool symmetric,
355  const int *diag_block_size,
356  const int *extra_diag_block_size,
357  const cs_real_t *da,
358  const cs_real_t *xa);
359 
360 /*----------------------------------------------------------------------------
361  * Release shared matrix coefficients.
362  *
363  * Pointers to mapped coefficients are set to NULL, while
364  * coefficient copies owned by the matrix are not modified.
365  *
366  * This simply ensures the matrix does not maintain pointers
367  * to nonexistant data.
368  *
369  * parameters:
370  * matrix <-> Pointer to matrix structure
371  *----------------------------------------------------------------------------*/
372 
373 void
375 
376 /*----------------------------------------------------------------------------
377  * Copy matrix diagonal values.
378  *
379  * In case of matrixes with block diagonal coefficients, only the true
380  * diagonal values are copied.
381  *
382  * parameters:
383  * matrix --> Pointer to matrix structure
384  * da --> Diagonal (pre-allocated, size: n_cells)
385  *----------------------------------------------------------------------------*/
386 
387 void
389  cs_real_t *restrict da);
390 
391 /*----------------------------------------------------------------------------
392  * Get matrix diagonal values.
393  *
394  * In case of matrixes with block diagonal coefficients, a pointer to
395  * the complete block diagonal is returned.
396  *
397  * parameters:
398  * matrix --> Pointer to matrix structure
399  *
400  * returns:
401  * pointer to matrix diagonal array
402  *----------------------------------------------------------------------------*/
403 
404 const cs_real_t *
406 
407 /*----------------------------------------------------------------------------
408  * Matrix.vector product y = A.x
409  *
410  * This function includes a halo update of x prior to multiplication by A.
411  *
412  * parameters:
413  * rotation_mode --> Halo update option for rotational periodicity
414  * matrix --> Pointer to matrix structure
415  * x <-> Multipliying vector values (ghost values updated)
416  * y --> Resulting vector
417  *----------------------------------------------------------------------------*/
418 
419 void
421  const cs_matrix_t *matrix,
422  cs_real_t *restrict x,
423  cs_real_t *restrict y);
424 
425 /*----------------------------------------------------------------------------
426  * Matrix.vector product y = A.x with no prior halo update of x.
427  *
428  * This function does not include a halo update of x prior to multiplication
429  * by A, so it should be called only when the halo of x is known to already
430  * be up to date (in which case we avoid the performance penalty of a
431  * redundant update by using this variant of the matrix.vector product).
432  *
433  * parameters:
434  * matrix --> Pointer to matrix structure
435  * x --> Multipliying vector values
436  * y --> Resulting vector
437  *----------------------------------------------------------------------------*/
438 
439 void
441  const cs_real_t *x,
442  cs_real_t *restrict y);
443 
444 /*----------------------------------------------------------------------------
445  * Matrix.vector product y = (A-D).x
446  *
447  * This function includes a halo update of x prior to multiplication by A.
448  *
449  * parameters:
450  * rotation_mode <-- Halo update option for rotational periodicity
451  * matrix <-- Pointer to matrix structure
452  * x <-> Multipliying vector values (ghost values updated)
453  * y --> Resulting vector
454  *----------------------------------------------------------------------------*/
455 
456 void
458  const cs_matrix_t *matrix,
459  cs_real_t *restrict x,
460  cs_real_t *restrict y);
461 
462 /*----------------------------------------------------------------------------
463  * Tune local matrix.vector product operations.
464  *
465  * To avoid multiplying structures for multiple matrix fill-ins,
466  * an array of tuning types may be provided, and weights may be
467  * associated to each type based on the expected usage of each fill-in
468  * type. If n_fill_types is set to 0, these arrays are ignored, and their
469  * following default is used:
470  *
471  * CS_MATRIX_SCALAR 0.5
472  * CS_MATRIX_SCALAR_SYM 0.25
473  * CS_MATRIX_33_BLOCK_D 0.25
474  *
475  * parameters:
476  * t_measure <-- minimum time for each measure
477  * n_fill_types <-- number of fill types tuned for, or 0
478  * fill_types <-- array of fill types tuned for, or NULL
479  * fill_weights <-- weight of fill types tuned for, or NULL
480  * n_min_spmv <-- minimum number of SpMv products (to estimate
481  * amortization of coefficients assignment)
482  * n_cells <-- number of local cells
483  * n_cells_ext <-- number of cells including ghost cells (array size)
484  * n_faces <-- local number of internal faces
485  * cell_num <-- Optional global cell numbers (1 to n), or NULL
486  * face_cell <-- face -> cells connectivity (1 to n)
487  * halo <-- cell halo structure
488  * numbering <-- vectorization or thread-related numbering info, or NULL
489  *
490  * returns:
491  * pointer to tuning results structure
492  *----------------------------------------------------------------------------*/
493 
495 cs_matrix_variant_tuned(double t_measure,
496  int n_fill_types,
497  cs_matrix_fill_type_t fill_types[],
498  double fill_weights[],
499  int n_min_products,
500  cs_lnum_t n_cells,
501  cs_lnum_t n_cells_ext,
502  cs_lnum_t n_faces,
503  const cs_gnum_t *cell_num,
504  const cs_lnum_t *face_cell,
505  const cs_halo_t *halo,
506  const cs_numbering_t *numbering);
507 
508 /*----------------------------------------------------------------------------
509  * Destroy a matrix variant structure.
510  *
511  * parameters:
512  * mv <-> Pointer to matrix variant pointer
513  *----------------------------------------------------------------------------*/
514 
515 void
517 
518 /*----------------------------------------------------------------------------
519  * Get the type associated with a matrix variant.
520  *
521  * parameters:
522  * mv <-- Pointer to matrix variant structure
523  *----------------------------------------------------------------------------*/
524 
527 
528 /*----------------------------------------------------------------------------
529  * Test local matrix.vector product operations.
530  *
531  * parameters:
532  * n_cells <-- number of local cells
533  * n_cells_ext <-- number of cells including ghost cells (array size)
534  * n_faces <-- local number of internal faces
535  * cell_num <-- Optional global cell numbers (1 to n), or NULL
536  * face_cell <-- face -> cells connectivity (1 to n)
537  * halo <-- cell halo structure
538  * numbering <-- vectorization or thread-related numbering info, or NULL
539  *
540  * returns:
541  * pointer to tuning results structure
542  *----------------------------------------------------------------------------*/
543 
544 void
546  cs_lnum_t n_cells_ext,
547  cs_lnum_t n_faces,
548  const cs_gnum_t *cell_num,
549  const cs_lnum_t *face_cell,
550  const cs_halo_t *halo,
551  const cs_numbering_t *numbering);
552 
553 /*----------------------------------------------------------------------------*/
554 
556 
557 #endif /* __CS_MATRIX_H__ */