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
src
alge
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__ */
Generated on Thu Feb 27 2014 19:21:34 by
1.8.3.1