Code_Saturne
CFD tool
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros 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-2012 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 /*----------------------------------------------------------------------------
53  * Matrix types
54  *----------------------------------------------------------------------------*/
55 
56 typedef enum {
57 
58  CS_MATRIX_NATIVE, /* Native matrix format */
59  CS_MATRIX_CSR, /* Compressed Sparse Row storage format */
60  CS_MATRIX_CSR_SYM, /* Compressed Symmetric Sparse Row storage format */
61  CS_MATRIX_MSR, /* Modified Compressed Sparse Row storage format */
62  CS_MATRIX_N_TYPES /* Number of known matrix types */
63 
65 
66 /* Structure associated with opaque matrix structure object */
67 
69 
70 /* Structure associated with opaque matrix object */
71 
72 typedef struct _cs_matrix_t cs_matrix_t;
73 
74 /* Structure associated with opaque matrix tuning results object */
75 
77 
78 /*============================================================================
79  * Global variables
80  *============================================================================*/
81 
82 /* Short names for matrix types */
83 
84 extern const char *cs_matrix_type_name[];
85 
86 /* Full names for matrix types */
87 
88 extern const char *cs_matrix_type_fullname[];
89 
92 
93 /*=============================================================================
94  * Public function prototypes for Fortran API
95  *============================================================================*/
96 
97 void CS_PROCF(promav, PROMAV)
98 (
99  const cs_int_t *isym, /* <-- Symmetry indicator:
100  1: symmetric; 2: not symmetric */
101  const cs_int_t *ibsize, /* <-- Block size of diagonal element */
102  const cs_int_t *iinvpe, /* <-- Indicator to cancel increments
103  in rotational periodicty (2) or
104  to exchange them as scalars (1) */
105  const cs_real_t *dam, /* <-- Matrix diagonal */
106  const cs_real_t *xam, /* <-- Matrix extra-diagonal terms */
107  cs_real_t *vx, /* <-- A*vx */
108  cs_real_t *vy /* <-> vy = A*vx */
109  );
110 
111 /*=============================================================================
112  * Public function prototypes
113  *============================================================================*/
114 
115 /*----------------------------------------------------------------------------
116  * Initialize sparse matrix API.
117  *----------------------------------------------------------------------------*/
118 
119 void
121 
122 /*----------------------------------------------------------------------------
123  * Finalize sparse matrix API.
124  *----------------------------------------------------------------------------*/
125 
126 void
127 cs_matrix_finalize(void);
128 
129 /*----------------------------------------------------------------------------
130  * Create a matrix Structure.
131  *
132  * Note that the structure created maps to the given existing
133  * cell global number, face -> cell connectivity arrays, and cell halo
134  * structure, so it must be destroyed before they are freed
135  * (usually along with the code's main face -> cell structure).
136  *
137  * Note that the resulting matrix structure will contain either a full or
138  * an empty main diagonal, and that the extra-diagonal structure is always
139  * symmetric (though the coefficients my not be, and we may choose a
140  * matrix format that does not exploit ths symmetry). If the face_cell
141  * connectivity argument is NULL, the matrix will be purely diagonal.
142  *
143  * parameters:
144  * type <-- Type of matrix considered
145  * have_diag <-- Indicates if the diagonal structure contains nonzeroes
146  * n_cells <-- Local number of cells
147  * n_cells_ext <-- Local number of cells + ghost cells sharing a face
148  * n_faces <-- Local number of internal faces
149  * cell_num <-- Optional global cell numbers (1 to n), or NULL
150  * face_cell <-- Face -> cells connectivity (1 to n)
151  * halo <-- Halo structure associated with cells, or NULL
152  * numbering <-- vectorization or thread-related numbering info, or NULL
153  *
154  * returns:
155  * pointer to created matrix structure;
156  *----------------------------------------------------------------------------*/
157 
160  bool have_diag,
161  cs_lnum_t n_cells,
162  cs_lnum_t n_cells_ext,
163  cs_lnum_t n_faces,
164  const cs_gnum_t *cell_num,
165  const cs_lnum_t *face_cell,
166  const cs_halo_t *halo,
167  const cs_numbering_t *numbering);
168 
169 /*----------------------------------------------------------------------------
170  * Create a matrix container using a given structure and tuning info.
171  *
172  * If the matrix variant is incompatible with the structure, it is ignored.
173  *
174  * parameters:
175  * ms <-- Associated matrix structure
176  * mv <-- Associated matrix variant
177  *
178  * returns:
179  * pointer to created matrix structure;
180  *----------------------------------------------------------------------------*/
181 
182 cs_matrix_t *
184  const cs_matrix_variant_t *mv);
185 
186 /*----------------------------------------------------------------------------
187  * Destroy a matrix structure.
188  *
189  * parameters:
190  * ms <-> Pointer to matrix structure pointer
191  *----------------------------------------------------------------------------*/
192 
193 void
195 
196 /*----------------------------------------------------------------------------
197  * Create a matrix container using a given structure.
198  *
199  * Note that the matrix container maps to the assigned structure,
200  * so it must be destroyed before that structure.
201  *
202  * parameters:
203  * ms <-- Associated matrix structure
204  *
205  * returns:
206  * pointer to created matrix structure;
207  *----------------------------------------------------------------------------*/
208 
209 cs_matrix_t *
211 
212 /*----------------------------------------------------------------------------
213  * Destroy a matrix structure.
214  *
215  * parameters:
216  * matrix <-> Pointer to matrix structure pointer
217  *----------------------------------------------------------------------------*/
218 
219 void
221 
222 /*----------------------------------------------------------------------------
223  * Return number of columns in matrix.
224  *
225  * parameters:
226  * matrix --> Pointer to matrix structure
227  *----------------------------------------------------------------------------*/
228 
229 cs_lnum_t
231 
232 /*----------------------------------------------------------------------------
233  * Return number of rows in matrix.
234  *
235  * parameters:
236  * matrix --> Pointer to matrix structure
237  *----------------------------------------------------------------------------*/
238 
239 cs_lnum_t
241 
242 /*----------------------------------------------------------------------------
243  * Return matrix diagonal block sizes.
244  *
245  * Block sizes are defined by a array of 4 values:
246  * 0: useful block size, 1: vector block extents,
247  * 2: matrix line extents, 3: matrix line*column extents
248  *
249  * parameters:
250  * matrix <-- Pointer to matrix structure
251  *
252  * returns:
253  * pointer to block sizes
254  *----------------------------------------------------------------------------*/
255 
256 const int *
258 
259 /*----------------------------------------------------------------------------
260  * Set matrix coefficients, sharing arrays with the caller when possible.
261  *
262  * With shared arrays, the matrix becomes unusable if the arrays passed as
263  * arguments are not be modified (its coefficients should be unset first
264  * to mark this).
265  *
266  * Depending on current options and initialization, values will be copied
267  * or simply mapped.
268  *
269  * Block sizes are defined by an optional array of 4 values:
270  * 0: useful block size, 1: vector block extents,
271  * 2: matrix line extents, 3: matrix line*column extents
272  *
273  * parameters:
274  * matrix <-> Pointer to matrix structure
275  * symmetric <-- Indicates if matrix coefficients are symmetric
276  * diag_block_size <-- Block sizes for diagonal, or NULL
277  * da <-- Diagonal values (NULL if zero)
278  * xa <-- Extradiagonal values (NULL if zero)
279  *----------------------------------------------------------------------------*/
280 
281 void
283  bool symmetric,
284  const int *diag_block_size,
285  const cs_real_t *da,
286  const cs_real_t *xa);
287 
288 /*----------------------------------------------------------------------------
289  * Set matrix coefficients in the non-interleaved case.
290  *
291  * In the symmetric case, there is no difference with the interleaved case.
292  *
293  * Depending on current options and initialization, values will be copied
294  * or simply mapped (non-symmetric values will be copied).
295  *
296  * parameters:
297  * matrix <-> Pointer to matrix structure
298  * symmetric <-- Indicates if matrix coefficients are symmetric
299  * da <-- Diagonal values (NULL if zero)
300  * xa <-- Extradiagonal values (NULL if zero)
301  *----------------------------------------------------------------------------*/
302 
303 void
305  bool symmetric,
306  const cs_real_t *da,
307  const cs_real_t *xa);
308 
309 /*----------------------------------------------------------------------------
310  * Set matrix coefficients, copying values to private arrays.
311  *
312  * With private arrays, the matrix becomes independant from the
313  * arrays passed as arguments.
314  *
315  * Block sizes are defined by an optional array of 4 values:
316  * 0: useful block size, 1: vector block extents,
317  * 2: matrix line extents, 3: matrix line*column extents
318  *
319  * parameters:
320  * matrix <-> Pointer to matrix structure
321  * symmetric <-- Indicates if matrix coefficients are symmetric
322  * diag_block_size <-- Block sizes for diagonal, or NULL
323  * da <-- Diagonal values (NULL if zero)
324  * xa <-- Extradiagonal values (NULL if zero)
325  *----------------------------------------------------------------------------*/
326 
327 void
329  bool symmetric,
330  const int *diag_block_size,
331  const cs_real_t *da,
332  const cs_real_t *xa);
333 
334 /*----------------------------------------------------------------------------
335  * Release shared matrix coefficients.
336  *
337  * Pointers to mapped coefficients are set to NULL, while
338  * coefficient copies owned by the matrix are not modified.
339  *
340  * This simply ensures the matrix does not maintain pointers
341  * to nonexistant data.
342  *
343  * parameters:
344  * matrix <-> Pointer to matrix structure
345  *----------------------------------------------------------------------------*/
346 
347 void
349 
350 /*----------------------------------------------------------------------------
351  * Copy matrix diagonal values.
352  *
353  * In case of matrixes with block diagonal coefficients, only the true
354  * diagonal values are copied.
355  *
356  * parameters:
357  * matrix --> Pointer to matrix structure
358  * da --> Diagonal (pre-allocated, size: n_cells)
359  *----------------------------------------------------------------------------*/
360 
361 void
363  cs_real_t *restrict da);
364 
365 /*----------------------------------------------------------------------------
366  * Get matrix diagonal values.
367  *
368  * In case of matrixes with block diagonal coefficients, a pointer to
369  * the complete block diagonal is returned.
370  *
371  * parameters:
372  * matrix --> Pointer to matrix structure
373  *
374  * returns:
375  * pointer to matrix diagonal array
376  *----------------------------------------------------------------------------*/
377 
378 const cs_real_t *
380 
381 /*----------------------------------------------------------------------------
382  * Matrix.vector product y = A.x
383  *
384  * This function includes a halo update of x prior to multiplication by A.
385  *
386  * parameters:
387  * rotation_mode --> Halo update option for rotational periodicity
388  * matrix --> Pointer to matrix structure
389  * x <-> Multipliying vector values (ghost values updated)
390  * y --> Resulting vector
391  *----------------------------------------------------------------------------*/
392 
393 void
395  const cs_matrix_t *matrix,
396  cs_real_t *restrict x,
397  cs_real_t *restrict y);
398 
399 /*----------------------------------------------------------------------------
400  * Matrix.vector product y = A.x with no prior halo update of x.
401  *
402  * This function does not include a halo update of x prior to multiplication
403  * by A, so it should be called only when the halo of x is known to already
404  * be up to date (in which case we avoid the performance penalty of a
405  * redundant update by using this variant of the matrix.vector product).
406  *
407  * parameters:
408  * matrix --> Pointer to matrix structure
409  * x --> Multipliying vector values
410  * y --> Resulting vector
411  *----------------------------------------------------------------------------*/
412 
413 void
415  const cs_real_t *x,
416  cs_real_t *restrict y);
417 
418 /*----------------------------------------------------------------------------
419  * Matrix.vector product y = (A-D).x
420  *
421  * This function includes a halo update of x prior to multiplication by A.
422  *
423  * parameters:
424  * rotation_mode <-- Halo update option for rotational periodicity
425  * matrix <-- Pointer to matrix structure
426  * x <-> Multipliying vector values (ghost values updated)
427  * y --> Resulting vector
428  *----------------------------------------------------------------------------*/
429 
430 void
432  const cs_matrix_t *matrix,
433  cs_real_t *restrict x,
434  cs_real_t *restrict y);
435 
436 /*----------------------------------------------------------------------------
437  * Tune local matrix.vector product operations.
438  *
439  * parameters:
440  * t_measure <-- minimum time for each measure
441  * sym_weight <-- weight of symmetric case (0 <= weight <= 1)
442  * block_weight <-- weight of block case (0 <= weight <= 1)
443  * n_min_spmv <-- minimum number of SpMv products (to estimate
444  * amortization of coefficients assignment)
445  * n_cells <-- number of local cells
446  * n_cells_ext <-- number of cells including ghost cells (array size)
447  * n_faces <-- local number of internal faces
448  * cell_num <-- Optional global cell numbers (1 to n), or NULL
449  * face_cell <-- face -> cells connectivity (1 to n)
450  * halo <-- cell halo structure
451  * numbering <-- vectorization or thread-related numbering info, or NULL
452  *
453  * returns:
454  * pointer to tuning results structure
455  *----------------------------------------------------------------------------*/
456 
458 cs_matrix_variant_tuned(double t_measure,
459  double sym_weight,
460  double block_weight,
461  int n_min_products,
462  cs_lnum_t n_cells,
463  cs_lnum_t n_cells_ext,
464  cs_lnum_t n_faces,
465  const cs_gnum_t *cell_num,
466  const cs_lnum_t *face_cell,
467  const cs_halo_t *halo,
468  const cs_numbering_t *numbering);
469 
470 /*----------------------------------------------------------------------------
471  * Destroy a matrix variant structure.
472  *
473  * parameters:
474  * mv <-> Pointer to matrix variant pointer
475  *----------------------------------------------------------------------------*/
476 
477 void
479 
480 /*----------------------------------------------------------------------------
481  * Get the type associated with a matrix variant.
482  *
483  * parameters:
484  * mv <-- Pointer to matrix variant structure
485  *----------------------------------------------------------------------------*/
486 
489 
490 /*----------------------------------------------------------------------------
491  * Test local matrix.vector product operations.
492  *
493  * parameters:
494  * n_cells <-- number of local cells
495  * n_cells_ext <-- number of cells including ghost cells (array size)
496  * n_faces <-- local number of internal faces
497  * cell_num <-- Optional global cell numbers (1 to n), or NULL
498  * face_cell <-- face -> cells connectivity (1 to n)
499  * halo <-- cell halo structure
500  * numbering <-- vectorization or thread-related numbering info, or NULL
501  *
502  * returns:
503  * pointer to tuning results structure
504  *----------------------------------------------------------------------------*/
505 
506 void
508  cs_lnum_t n_cells_ext,
509  cs_lnum_t n_faces,
510  const cs_gnum_t *cell_num,
511  const cs_lnum_t *face_cell,
512  const cs_halo_t *halo,
513  const cs_numbering_t *numbering);
514 
515 /*----------------------------------------------------------------------------*/
516 
518 
519 #endif /* __CS_MATRIX_H__ */
const int * cs_matrix_get_diag_block_size(const cs_matrix_t *matrix)
Definition: cs_matrix.c:5040
#define restrict
Definition: cs_defs.h:105
void cs_matrix_vector_multiply(cs_halo_rotation_t rotation_mode, const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
Definition: cs_matrix.c:5333
cs_halo_rotation_t
Definition: cs_halo.h:59
cs_matrix_t * cs_matrix_create(const cs_matrix_structure_t *ms)
Definition: cs_matrix.c:4772
cs_matrix_t * cs_glob_matrix_default
Definition: cs_matrix.c:158
cs_matrix_type_t type
Definition: cs_matrix_priv.h:327
#define BEGIN_C_DECLS
Definition: cs_defs.h:365
void cs_matrix_release_coefficients(cs_matrix_t *matrix)
Definition: cs_matrix.c:5189
cs_matrix_structure_t * cs_matrix_structure_create(cs_matrix_type_t type, bool have_diag, cs_lnum_t n_cells, cs_lnum_t n_cells_ext, cs_lnum_t n_faces, const cs_gnum_t *cell_num, const cs_lnum_t *face_cell, const cs_halo_t *halo, const cs_numbering_t *numbering)
Definition: cs_matrix.c:4639
void cs_matrix_set_coefficients_ni(cs_matrix_t *matrix, bool symmetric, const cs_real_t *da, const cs_real_t *xa)
Definition: cs_matrix.c:5113
void cs_matrix_variant_test(cs_lnum_t n_cells, cs_lnum_t n_cells_ext, cs_lnum_t n_faces, const cs_gnum_t *cell_num, const cs_lnum_t *face_cell, const cs_halo_t *halo, const cs_numbering_t *numbering)
Definition: cs_matrix.c:5838
Definition: cs_halo.h:75
void cs_matrix_structure_destroy(cs_matrix_structure_t **ms)
Definition: cs_matrix.c:4715
void promav(const cs_int_t *isym, const cs_int_t *ibsize, const cs_int_t *iinvpe, const cs_real_t *dam, const cs_real_t *xam, cs_real_t *vx, cs_real_t *vy)
Definition: cs_matrix.c:4525
void cs_matrix_copy_diagonal(const cs_matrix_t *matrix, cs_real_t *restrict da)
Definition: cs_matrix.c:5213
Definition: cs_matrix_priv.h:268
int cs_int_t
Definition: cs_defs.h:263
const char * cs_matrix_type_fullname[]
Definition: cs_matrix.c:139
subroutine matrix
Definition: matrix.f90:85
void cs_matrix_initialize(void)
Definition: cs_matrix.c:4577
cs_matrix_structure_t * cs_glob_matrix_default_struct
Definition: cs_matrix.c:159
const char * cs_matrix_type_name[]
Definition: cs_matrix.c:131
cs_matrix_variant_t * cs_matrix_variant_tuned(double t_measure, double sym_weight, double block_weight, int n_min_products, cs_lnum_t n_cells, cs_lnum_t n_cells_ext, cs_lnum_t n_faces, const cs_gnum_t *cell_num, const cs_lnum_t *face_cell, const cs_halo_t *halo, const cs_numbering_t *numbering)
Definition: cs_matrix.c:5482
int cs_lnum_t
Definition: cs_defs.h:260
Definition: cs_matrix.h:62
cs_matrix_type_t
Definition: cs_matrix.h:56
unsigned cs_gnum_t
Definition: cs_defs.h:255
void cs_matrix_set_coefficients(cs_matrix_t *matrix, bool symmetric, const int *diag_block_size, const cs_real_t *da, const cs_real_t *xa)
Definition: cs_matrix.c:5072
Definition: cs_matrix.h:60
cs_lnum_t cs_matrix_get_n_columns(const cs_matrix_t *matrix)
Definition: cs_matrix.c:5001
void cs_matrix_destroy(cs_matrix_t **matrix)
Definition: cs_matrix.c:4946
#define END_C_DECLS
Definition: cs_defs.h:366
void cs_matrix_variant_destroy(cs_matrix_variant_t **mv)
Definition: cs_matrix.c:5802
Definition: cs_matrix_priv.h:241
double cs_real_t
Definition: cs_defs.h:264
#define CS_PROCF(x, y)
Definition: cs_defs.h:379
void cs_matrix_exdiag_vector_multiply(cs_halo_rotation_t rotation_mode, const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
Definition: cs_matrix.c:5426
Definition: cs_matrix.h:61
cs_matrix_t * cs_matrix_create_tuned(const cs_matrix_structure_t *ms, const cs_matrix_variant_t *mv)
Definition: cs_matrix.c:4919
Definition: cs_matrix_priv.h:323
Definition: cs_matrix.h:59
cs_lnum_t cs_matrix_get_n_rows(const cs_matrix_t *matrix)
Definition: cs_matrix.c:5017
const cs_real_t * cs_matrix_get_diagonal(const cs_matrix_t *matrix)
Definition: cs_matrix.c:5240
void cs_matrix_finalize(void)
Definition: cs_matrix.c:4603
Definition: cs_matrix.h:58
cs_matrix_type_t cs_matrix_variant_type(const cs_matrix_variant_t *mv)
Definition: cs_matrix.c:5816
void cs_matrix_vector_multiply_nosync(const cs_matrix_t *matrix, const cs_real_t *x, cs_real_t *restrict y)
Definition: cs_matrix.c:5382
Definition: cs_numbering.h:66
void cs_matrix_copy_coefficients(cs_matrix_t *matrix, bool symmetric, const int *diag_block_size, const cs_real_t *da, const cs_real_t *xa)
Definition: cs_matrix.c:5150