8.2
general documentation
Loading...
Searching...
No Matches
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-2024 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
43
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 * - Modified Compressed Sparse Row (MSR), with separate diagonal
57 */
58
59/*----------------------------------------------------------------------------
60 * Function pointer types
61 *----------------------------------------------------------------------------*/
62
63typedef void
64(cs_matrix_set_coeffs_t) (cs_matrix_t *matrix,
65 bool symmetric,
66 bool copy,
67 cs_lnum_t n_edges,
68 const cs_lnum_2_t *restrict edges,
69 const cs_real_t *restrict da,
70 const cs_real_t *restrict xa);
71
72typedef void
73(cs_matrix_release_coeffs_t) (cs_matrix_t *matrix);
74
75typedef void
76(cs_matrix_destroy_struct_t) (void **ms);
77
78typedef void
79(cs_matrix_destroy_coeffs_t) (cs_matrix_t *matrix);
80
81typedef void
82(cs_matrix_destroy_adaptor_t) (cs_matrix_t *matrix);
83
84typedef void
85(cs_matrix_copy_diagonal_t) (const cs_matrix_t *matrix,
87
88typedef const cs_real_t *
89(cs_matrix_get_diagonal_t)(const cs_matrix_t *matrix);
90
92(cs_matrix_assembler_values_create_t) (cs_matrix_t *matrix,
93 cs_lnum_t diag_block_size,
94 cs_lnum_t extra_diag_block_size);
95
96/*----------------------------------------------------------------------------
97 * Function pointer for matrix-veector product (y = A.x).
98 *
99 * parameters:
100 * matrix <-> pointer to matrix structure
101 * exclude_diag <-- if true, compute (A-D).x instead of A.x
102 * sync <-- if true, synchronize ghost values
103 * x <-- x input vector (may be synchronized by this function)
104 * y <-- y output vector
105 *----------------------------------------------------------------------------*/
106
107typedef void
108(cs_matrix_vector_product_t) (cs_matrix_t *matrix,
109 bool exclude_diag,
110 bool sync,
113
114/*----------------------------------------------------------------------------
115 * Matrix types
116 *----------------------------------------------------------------------------*/
117
118/* Native matrix structure representation */
119/*----------------------------------------*/
120
121/* Note: the members of this structure are already available through the top
122 * matrix structure, but are replicated here in case of future removal
123 * from the top structure (which would require computation/assignment of
124 * matrix coefficients in another form) */
125
126typedef struct _cs_matrix_struct_native_t {
127
128 cs_lnum_t n_rows; /* Local number of rows */
129 cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
130 cs_lnum_t n_edges; /* Local number of graph edges
131 (for extra-diagonal terms) */
132
133 /* Pointers to shared arrays */
134
135 const cs_lnum_2_t *edges; /* Edges (symmetric row <-> column)
136 connectivity */
137
138} cs_matrix_struct_native_t;
139
140/* CSR (Compressed Sparse Row) matrix structure representation */
141/*-------------------------------------------------------------*/
142
143typedef struct _cs_matrix_struct_csr_t {
144
145 cs_lnum_t n_rows; /* Local number of rows */
146 cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
147
148 /* Pointers to structure arrays and info (row_index, col_id) */
149
150 bool have_diag; /* Has non-zero diagonal */
151 bool direct_assembly; /* True if each value corresponds to
152 a unique face; false if multiple
153 faces contribute to the same
154 value (i.e. we have split faces) */
155
156 const cs_lnum_t *row_index; /* Pointer to row index (0 to n-1) */
157 const cs_lnum_t *col_id; /* Pointer to column id (0 to n-1) */
158
159 cs_lnum_t *_row_index; /* Row index (0 to n-1), if owner */
160 cs_lnum_t *_col_id; /* Column id (0 to n-1), if owner */
161
162} cs_matrix_struct_csr_t;
163
164/* Distributed matrix structure representation */
165/*---------------------------------------------*/
166
167/* This storage assumes a representation in the following form:
168
169 - D+E+H
170
171 Where D is the diagonal, E the local extra-diagonal, and H is the part
172 of the matrix referencing halo values (only the upper-part of the
173 coefficients are needed on a given rank).
174
175 In cases where a partial block structure is used for the diagonal
176 (usually at boundary cells), the diagonal values may be indexed.
177
178 Sub-matrices are stored in CSR format, to allow easy indexing
179 or access to a given row's elements (which is useful for multigrid
180 coarsening).
181
182 Since the H portion of the matrix may be very sparse, with most rows
183 empty, the matching row ids can be stored in addition to the column ids,
184 defining a simple coordinate-type structure as a COO-type SpMv product
185 can be expected to be cheaper than a CSR-based one in this case.
186 */
187
188typedef struct _cs_matrix_struct_dist_t {
189
190 cs_lnum_t n_rows; /* Local number of rows */
191 cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
192
193 /* Pointers to structure arrays and info */
194
195 cs_matrix_struct_csr_t e; /* E (local off-diagonal) CSR structure */
196 cs_matrix_struct_csr_t h; /* H (halo) CSR structure */
197
198 cs_lnum_t *h_row_id; /* Optional row id for coordinates
199 format (col_id in h structure) */
200
201} cs_matrix_struct_dist_t;
202
203/* CSR matrix coefficients representation */
204/*----------------------------------------*/
205
206typedef struct _cs_matrix_coeff_csr_t {
207
208 /* Pointers to possibly shared arrays */
209
210 const cs_real_t *val; /* Matrix coefficients */
211
212 /* Pointers to private arrays (NULL if shared) */
213
214 cs_real_t *_val; /* Matrix coefficients */
215
216 /* Pointers to auxiliary arrays used for queries */
217
218 const cs_real_t *d_val; /* Pointer to diagonal matrix
219 coefficients, if queried */
220 cs_real_t *_d_val; /* Diagonal matrix coefficients,
221 if queried */
222
223} cs_matrix_coeff_csr_t;
224
225/* Distributed matrix coefficients representation */
226/*------------------------------------------------*/
227
228/* Used for native, MSR, and distributed matrices */
229
230typedef struct _cs_matrix_coeff_dist_t {
231
232 bool symmetric; /* Symmetry indicator */
233
234 int db_size; /* Diagonal block size */
235 int eb_size; /* Extra-diagonal block size */
236
237 /* Pointers to possibly shared arrays */
238
239 const cs_real_t *d_val; /* D (diagonal-only) coefficients */
240 const cs_real_t *e_val; /* E (extra-diagonal) coefficients */
241 const cs_real_t *h_val; /* H (halo-only) coefficients */
242
243 /* Pointers to private arrays.
244 NULL if shared:
245 * If non-NULL, d_val, e_val, and h_val should point
246 to matching private array.
247 * In the case of CSR storage, where diagonal values can be stored in
248 the e_val array, d_val will be NULL but _d_val may be used to store
249 (cache) diagonal values. */
250
251 cs_real_t *_d_val; /* D (diagonal) coefficients */
252 cs_real_t *_e_val; /* E (local extra-diagonal) coefficients */
253 cs_real_t *_h_val; /* H (halo) coefficients */
254
255 /* Pointers to auxiliary matrix structure elements */
256
257 cs_lnum_t *d_idx; /* Index for diagonal matrix coefficients
258 in case of multiple block sizes */
259
260} cs_matrix_coeff_dist_t;
261
262/* Matrix structure (representation-independent part) */
263/*----------------------------------------------------*/
264
265struct _cs_matrix_structure_t {
266
267 cs_matrix_type_t type; /* Matrix storage and definition type */
268
269 cs_lnum_t n_rows; /* Local number of rows */
270 cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
271
272 cs_alloc_mode_t alloc_mode; /* Preferred allocation mode */
273
274 void *structure; /* Matrix structure */
275
276 /* Pointers to shared arrays from mesh structure
277 (face->cell connectivity for coefficient assignment,
278 local->local cell numbering for future info or renumbering,
279 and halo) */
280
281 const cs_halo_t *halo; /* Parallel or periodic halo */
282 const cs_numbering_t *numbering; /* Vectorization or thread-related
283 numbering information */
284
285 const cs_matrix_assembler_t *assembler; /* Associated matrix assembler */
286};
287
288/* Structure associated with Matrix (representation-independent part) */
289/*--------------------------------------------------------------------*/
290
291struct _cs_matrix_t {
292
293 cs_matrix_type_t type; /* Matrix storage and definition type */
294
295 const char *type_name; /* Pointer to matrix type name string */
296 const char *type_fname; /* Pointer to matrix type
297 full name string */
298
299 cs_lnum_t n_rows; /* Local number of rows */
300 cs_lnum_t n_cols_ext; /* Local number of columns + ghosts */
301
302 cs_matrix_fill_type_t fill_type; /* Matrix fill type */
303
304 bool symmetric; /* true if coefficients are symmetric */
305
306 cs_lnum_t db_size; /* Diagonal block size */
307
308 cs_lnum_t eb_size; /* Extradiag block size */
309
310 cs_alloc_mode_t alloc_mode; /* Preferred allocation mode */
311
312 /* Pointer to shared structure */
313
314 const void *structure; /* Possibly shared matrix structure */
315 void *_structure; /* Private matrix structure */
316
317 /* Pointers to arrays possibly shared from mesh structure
318 (graph edges: face->cell connectivity for coefficient assignment,
319 rows: local->local cell numbering for future info or renumbering,
320 and halo) */
321
322 const cs_halo_t *halo; /* Parallel or periodic halo */
323 const cs_numbering_t *numbering; /* Vectorization or thread-related
324 numbering information */
325
326 const cs_matrix_assembler_t *assembler; /* Associated matrix assembler */
327
328 /* Pointer to shared arrays from coefficient assignment from
329 "native" type. This should be removed in the future, but requires
330 removing the dependency to the native structure in the multigrid
331 code first. */
332
333 const cs_real_t *xa; /* Extra-diagonal terms */
334
335 /* Pointer to associated connectivity and geometric data needed by
336 multigrid smoothing. At least cell centers and volumes are needed for
337 relaxation, and face normals are needed for the "classical" option.
338 Cells and faces here do not need to be primary mesh elements,
339 but could be dual mesh elements of some sort */
340
341 const cs_lnum_t *c2f_idx; /* Cell to faces index (shared) */
342 const cs_lnum_t *c2f; /* Cell to faces adjacency (shared) */
343 const short int *c2f_sgn; /* Cell to faces orientation (shared) */
344
345 const cs_real_3_t *cell_cen; /* Cell center (shared) */
346 const cs_real_t *cell_vol; /* Cell volume (shared) */
347 const cs_real_3_t *face_normal; /* Face normal (shared) */
348
349 /* Pointer to private data */
350
351 void *coeffs; /* Matrix coefficients */
352
353 void *ext_lib_map; /* Mapping of structure and
354 coefficients to external
355 library, if needed */
356
357 /* Function pointers */
358
359 cs_matrix_set_coeffs_t *set_coefficients;
360 cs_matrix_release_coeffs_t *release_coefficients;
361 cs_matrix_copy_diagonal_t *copy_diagonal;
362 cs_matrix_get_diagonal_t *get_diagonal;
363
364 cs_matrix_destroy_struct_t *destroy_structure;
365 cs_matrix_destroy_coeffs_t *destroy_coefficients;
366 cs_matrix_destroy_adaptor_t *destroy_adaptor;
367
368 cs_matrix_assembler_values_create_t *assembler_values_create;
369
370 /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants:
371 fill_type*4 + full, extra-diagonal, lower, upper parts */
372
373 cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES]
375
376#if defined(HAVE_ACCEL)
377
378 /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants, for host
379 or device only: fill_type*4 + full, extra-diagonal, lower, upper parts */
380
381 cs_matrix_vector_product_t *vector_multiply_h[CS_MATRIX_N_FILL_TYPES]
383 cs_matrix_vector_product_t *vector_multiply_d[CS_MATRIX_N_FILL_TYPES]
385
386#endif /* defined(HAVE_ACCEL) */
387
388};
389
390/* Structure used for tuning variants */
391/*------------------------------------*/
392
393struct _cs_matrix_variant_t {
394
395 char name[2][32]; /* Variant names */
396
397 cs_matrix_type_t type; /* Matrix storage and definition type */
398 cs_matrix_fill_type_t fill_type; /* Matrix storage and definition type */
399
400 /* Function pointer arrays */
401
402 cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_SPMV_N_TYPES];
403
404 /* Associated vector host/device locations (h/d/g for host/device/both) */
405
406 char vector_multiply_xy_hd[CS_MATRIX_SPMV_N_TYPES];
407};
408
410
411/*=============================================================================
412 * Semi-private function prototypes
413 *============================================================================*/
414
415/*----------------------------------------------------------------------------*/
416
418
419#endif /* __CS_MATRIX_PRIV_H__ */
cs_alloc_mode_t
Definition bft_mem.h:50
#define restrict
Definition cs_defs.h:141
#define BEGIN_C_DECLS
Definition cs_defs.h:528
double cs_real_t
Floating-point value.
Definition cs_defs.h:332
cs_lnum_t cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition cs_defs.h:340
#define END_C_DECLS
Definition cs_defs.h:529
int cs_lnum_t
local mesh entity id
Definition cs_defs.h:325
cs_real_t cs_real_3_t[3]
vector of 3 floating-point values
Definition cs_defs.h:347
@ h
Definition cs_field_pointer.h:91
@ CS_MATRIX_SPMV_N_TYPES
Definition cs_matrix.h:100
struct _cs_matrix_t cs_matrix_t
Definition cs_matrix.h:110
cs_matrix_fill_type_t
Definition cs_matrix.h:72
@ CS_MATRIX_N_FILL_TYPES
Definition cs_matrix.h:85
cs_matrix_type_t
Definition cs_matrix.h:54
struct _cs_matrix_assembler_t cs_matrix_assembler_t
Definition cs_matrix_assembler.h:61
struct _cs_matrix_assembler_values_t cs_matrix_assembler_values_t
Definition cs_matrix_assembler.h:65
void matrix(const int *iconvp, const int *idiffp, const int *ndircp, const int *isym, const cs_real_t *thetap, const int *imucpp, const cs_real_t coefbp[], const cs_real_t cofbfp[], const cs_real_t rovsdt[], const cs_real_t i_massflux[], const cs_real_t b_massflux[], const cs_real_t i_visc[], const cs_real_t b_visc[], const cs_real_t xcpp[], cs_real_t da[], cs_real_t xa[])