src/alge/cs_matrix.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

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
42 BEGIN_C_DECLS
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
62 } cs_matrix_type_t;
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
78 } cs_matrix_fill_type_t;
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
104 extern cs_matrix_t *cs_glob_matrix_default;
105 extern cs_matrix_structure_t *cs_glob_matrix_default_struct;
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
135 cs_matrix_initialize(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
149 cs_matrix_update_mesh(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
180 cs_matrix_structure_t *
181 cs_matrix_structure_create(cs_matrix_type_t type,
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 *
205 cs_matrix_create_tuned(const cs_matrix_structure_t *ms,
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
216 cs_matrix_structure_destroy(cs_matrix_structure_t **ms);
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 *
232 cs_matrix_create(const cs_matrix_structure_t *ms);
233
234 /*----------------------------------------------------------------------------
235 * Destroy a matrix structure.
236 *
237 * parameters:
238 * matrix <-> Pointer to matrix structure pointer
239 *----------------------------------------------------------------------------*/
240
241 void
242 cs_matrix_destroy(cs_matrix_t **matrix);
243
244 /*----------------------------------------------------------------------------
245 * Return number of columns in matrix.
246 *
247 * parameters:
248 * matrix --> Pointer to matrix structure
249 *----------------------------------------------------------------------------*/
250
251 cs_lnum_t
252 cs_matrix_get_n_columns(const cs_matrix_t *matrix);
253
254 /*----------------------------------------------------------------------------
255 * Return number of rows in matrix.
256 *
257 * parameters:
258 * matrix --> Pointer to matrix structure
259 *----------------------------------------------------------------------------*/
260
261 cs_lnum_t
262 cs_matrix_get_n_rows(const cs_matrix_t *matrix);
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 *
279 cs_matrix_get_diag_block_size(const cs_matrix_t *matrix);
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
305 cs_matrix_set_coefficients(cs_matrix_t *matrix,
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
328 cs_matrix_set_coefficients_ni(cs_matrix_t *matrix,
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
353 cs_matrix_copy_coefficients(cs_matrix_t *matrix,
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
374 cs_matrix_release_coefficients(cs_matrix_t *matrix);
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
388 cs_matrix_copy_diagonal(const cs_matrix_t *matrix,
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 *
405 cs_matrix_get_diagonal(const cs_matrix_t *matrix);
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
420 cs_matrix_vector_multiply(cs_halo_rotation_t rotation_mode,
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
440 cs_matrix_vector_multiply_nosync(const cs_matrix_t *matrix,
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
457 cs_matrix_exdiag_vector_multiply(cs_halo_rotation_t rotation_mode,
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
494 cs_matrix_variant_t *
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
516 cs_matrix_variant_destroy(cs_matrix_variant_t **mv);
517
518 /*----------------------------------------------------------------------------
519 * Get the type associated with a matrix variant.
520 *
521 * parameters:
522 * mv <-- Pointer to matrix variant structure
523 *----------------------------------------------------------------------------*/
524
525 cs_matrix_type_t
526 cs_matrix_variant_type(const cs_matrix_variant_t *mv);
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
545 cs_matrix_variant_test(cs_lnum_t n_cells,
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
555 END_C_DECLS
556
557 #endif /* __CS_MATRIX_H__ */