8.0
general documentation
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-2023 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 
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 
63 typedef 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 
72 typedef void
73 (cs_matrix_release_coeffs_t) (cs_matrix_t *matrix);
74 
75 typedef void
76 (cs_matrix_destroy_struct_t) (void **ms);
77 
78 typedef void
79 (cs_matrix_destroy_coeffs_t) (cs_matrix_t *matrix);
80 
81 typedef void
82 (cs_matrix_destroy_adaptor_t) (cs_matrix_t *matrix);
83 
84 typedef void
85 (cs_matrix_copy_diagonal_t) (const cs_matrix_t *matrix,
86  cs_real_t *restrict da);
87 
88 typedef 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 
107 typedef void
108 (cs_matrix_vector_product_t) (const cs_matrix_t *matrix,
109  bool exclude_diag,
110  bool sync,
111  cs_real_t *restrict x,
112  cs_real_t *restrict y);
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 
126 typedef 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 
143 typedef 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 
188 typedef 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 
206 typedef 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 
230 typedef 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 
265 struct _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 
291 struct _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 private data */
336 
337  void *coeffs; /* Matrix coefficients */
338 
339  void *ext_lib_map; /* Mapping of structure and
340  coefficients to external
341  library, if needed */
342 
343  /* Function pointers */
344 
345  cs_matrix_set_coeffs_t *set_coefficients;
346  cs_matrix_release_coeffs_t *release_coefficients;
347  cs_matrix_copy_diagonal_t *copy_diagonal;
348  cs_matrix_get_diagonal_t *get_diagonal;
349 
350  cs_matrix_destroy_struct_t *destroy_structure;
351  cs_matrix_destroy_coeffs_t *destroy_coefficients;
352  cs_matrix_destroy_adaptor_t *destroy_adaptor;
353 
354  cs_matrix_assembler_values_create_t *assembler_values_create;
355 
356  /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants:
357  fill_type*4 + full, extra-diagonal, lower, upper parts */
358 
359  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_N_FILL_TYPES]
361 
362 #if defined(HAVE_ACCEL)
363 
364  /* Function pointer arrays, with CS_MATRIX_N_FILL_TYPES variants, for host
365  or device only: fill_type*4 + full, extra-diagonal, lower, upper parts */
366 
367  cs_matrix_vector_product_t *vector_multiply_h[CS_MATRIX_N_FILL_TYPES]
369  cs_matrix_vector_product_t *vector_multiply_d[CS_MATRIX_N_FILL_TYPES]
371 
372 #endif /* defined(HAVE_ACCEL) */
373 
374 };
375 
376 /* Structure used for tuning variants */
377 /*------------------------------------*/
378 
379 struct _cs_matrix_variant_t {
380 
381  char name[2][32]; /* Variant names */
382 
383  cs_matrix_type_t type; /* Matrix storage and definition type */
384  cs_matrix_fill_type_t fill_type; /* Matrix storage and definition type */
385 
386  /* Function pointer arrays */
387 
388  cs_matrix_vector_product_t *vector_multiply[CS_MATRIX_SPMV_N_TYPES];
389 
390  /* Associated vector host/device locations */
391 
392  char vector_multiply_xy_hd[CS_MATRIX_SPMV_N_TYPES];
393 };
394 
397 /*=============================================================================
398  * Semi-private function prototypes
399  *============================================================================*/
400 
401 /*----------------------------------------------------------------------------*/
402 
404 
405 #endif /* __CS_MATRIX_PRIV_H__ */
cs_alloc_mode_t
Definition: cs_base_accel.h:142
#define restrict
Definition: cs_defs.h:139
#define BEGIN_C_DECLS
Definition: cs_defs.h:509
double cs_real_t
Floating-point value.
Definition: cs_defs.h:319
cs_lnum_t cs_lnum_2_t[2]
vector of 2 local mesh-entity ids
Definition: cs_defs.h:325
#define END_C_DECLS
Definition: cs_defs.h:510
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:313
@ 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[])
Definition: cs_matrix_building.c:111
Definition: cs_halo.h:77
Definition: cs_numbering.h:87