8.3
general documentation
cs_matrix_default.h
Go to the documentation of this file.
1#ifndef __CS_MATRIX_DEFAULT_H__
2#define __CS_MATRIX_DEFAULT_H__
3
4/*============================================================================
5 * Default Sparse Matrix structure and Tuning.
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_field.h"
37#include "cs_halo.h"
38#include "cs_matrix.h"
39#include "cs_numbering.h"
40#include "cs_halo_perio.h"
41
42/*----------------------------------------------------------------------------*/
43
45
46/*============================================================================
47 * Macro definitions
48 *============================================================================*/
49
50/*============================================================================
51 * Type definitions
52 *============================================================================*/
53
54/*============================================================================
55 * Global variables
56 *============================================================================*/
57
58/*=============================================================================
59 * Public function prototypes
60 *============================================================================*/
61
62/*----------------------------------------------------------------------------
63 * Matrix (native format) vector product
64 *
65 * parameters:
66 * symmetric <-- Symmetry indicator:
67 * db_size <-- block sizes for diagonal
68 * eb_size <-- block sizes for extra diagonal
69 * f_id <-- associated field id, or < 0
70 * dam <-- Matrix diagonal
71 * xam <-- Matrix extra-diagonal terms
72 * vx <-- A*vx
73 * vy <-> vy = A*vx
74 *----------------------------------------------------------------------------*/
75
76void
78 cs_lnum_t db_size,
79 cs_lnum_t eb_size,
80 int f_id,
81 const cs_real_t *dam,
82 const cs_real_t *xam,
83 cs_real_t *vx,
84 cs_real_t *vy);
85
86/*----------------------------------------------------------------------------
87 * Initialize sparse matrix API.
88 *----------------------------------------------------------------------------*/
89
90void
92
93/*----------------------------------------------------------------------------
94 * Finalize sparse matrix API.
95 *----------------------------------------------------------------------------*/
96
97void
99
100/*----------------------------------------------------------------------------
101 * Update sparse matrix API in case of mesh modification.
102 *----------------------------------------------------------------------------*/
103
104void
106
107/*----------------------------------------------------------------------------
108 * Return default matrix for a given fill type
109 *
110 * parameters:
111 * symmetric <-- Indicates if matrix coefficients are symmetric
112 * diag_block_size <-- Block sizes for diagonal
113 * extra_diag_block_size <-- Block sizes for extra diagonal
114 *
115 * returns:
116 * pointer to default matrix structure adapted to fill type
117 *----------------------------------------------------------------------------*/
118
120cs_matrix_default(bool symmetric,
121 cs_lnum_t diag_block_size,
122 cs_lnum_t extra_diag_block_size);
123
124/*----------------------------------------------------------------------------
125 * Return MSR matrix
126 *
127 * returns:
128 * pointer to MSR matrix
129 *----------------------------------------------------------------------------*/
130
132cs_matrix_msr(void);
133
134/*----------------------------------------------------------------------------
135 * Return native matrix
136 *
137 * returns:
138 * pointer to native matrix
139 *----------------------------------------------------------------------------*/
140
142cs_matrix_native(void);
143
144/*----------------------------------------------------------------------------*/
145/*
146 * \brief Return matrix wrapper for external library for a given fill type.
147 *
148 * \param[in] type_name Matrix type name
149 * \param[in] symmetric Indicates if coefficients are symmetric
150 * \param[in] diag_block_size Block sizes for diagonal
151 * \param[in] extra_diag_block_size Block sizes for extra diagonal
152 *
153 * \return Pointer to matrix matching requested type
154 */
155/*----------------------------------------------------------------------------*/
156
158cs_matrix_external(const char *type_name,
159 bool symmetric,
160 cs_lnum_t diag_block_size,
161 cs_lnum_t extra_diag_block_size);
162
163/*----------------------------------------------------------------------------*/
164/*
165 * \brief Copy base matrix to external library matrix type for given fill type.
166 *
167 * Note that the matrix containers share the same assigned structure,
168 * so they must be both destroyed before that structure.
169 *
170 * Coefficients and matching structures are not copied or created.
171 *
172 * This function is intended to allow sharing of a base structure or assembler
173 * with an external library matrix wrapper, so as to allow efficient
174 * coefficient assignment, but with external coefficient handling.
175 *
176 * The matrix shoud be converted to the desired external type after calling
177 * this function, so that it can the be accessed using \ref cs_matrix_external.
178 *
179 * \param[in] symmetric Indicates if matrix coefficients are symmetric
180 * \param[in] diag_block_size Block sizes for diagonal
181 * \param[in] extra_diag_block_size Block sizes for extra diagonal
182 *
183 * \return pointer to native matrix adapted to fill type
184 */
185/*----------------------------------------------------------------------------*/
186
189 bool symmetric,
190 cs_lnum_t diag_block_size,
191 cs_lnum_t extra_diag_block_size);
192
193/*----------------------------------------------------------------------------
194 * Determine or apply default tuning for a given matrix type
195 *
196 * Information from the variant used fo this definition is copied,
197 * so it may be freed after calling this function.
198 *
199 * parameters:
200 * fill type <-- Fill type for which tuning behavior is set
201 * mv <-- Matrix variant to use for this type
202 *----------------------------------------------------------------------------*/
203
204void
206
207/*----------------------------------------------------------------------------
208 * Set number of matrix computation runs for tuning.
209 *
210 * If this function is not called, defaults are:
211 * - minimum of 10 runs
212 *
213 * parameters:
214 * n_min_products <-- minimum number of SpM.V products for tuning.
215 *----------------------------------------------------------------------------*/
216
217void
218cs_matrix_set_tuning_runs(int n_min_products);
219
220/*----------------------------------------------------------------------------
221 * Get number of matrix computation runs for tuning.
222 *
223 * return:
224 * minimum number of SpM.V calls for tuning
225 *----------------------------------------------------------------------------*/
226
227int
229
230/*----------------------------------------------------------------------------*/
231/*
232 * \brief Set default matrix type for a given fill type.
233 *
234 * \param[in] fill type Fill type for which tuning behavior is set
235 * \param[in] type Matrix type to use
236 */
237/*----------------------------------------------------------------------------*/
238
239void
241 cs_matrix_type_t type);
242
243/*----------------------------------------------------------------------------*/
244/*
245 * \brief Return a (0-based) global block row numbering for a given matrix.
246 *
247 * The numbering is built or updated if not previously used, or if the
248 * previous call considered a different matrix or halo, and is simply
249 * returned otherwise.
250 * In other words, this works as a matrix global numbering cache.
251 *
252 * The matrix's halo is used for the update.
253 *
254 * \param[in] m associated matrix
255 *
256 * \return pointer to requested global numbering
257 */
258/*----------------------------------------------------------------------------*/
259
260const cs_gnum_t *
262
264#ifdef __cplusplus
265
266/*----------------------------------------------------------------------------*/
267/*
268 * \brief Return a (0-based) global block row numbering for a given matrix.
269 *
270 * The numbering is built or updated if not previously used, or if the
271 * previous call considered a different matrix or halo, and is simply
272 * returned otherwise.
273 * In other words, this works as a matrix global numbering cache.
274 *
275 * \param[in] m associated matrix
276 * \param[in] halo associated halo
277 *
278 * \return pointer to requested global numbering
279 */
280/*----------------------------------------------------------------------------*/
281
282const cs_gnum_t *
284 const cs_halo_t *halo);
285
286#endif /* cplusplus */
288
289/*----------------------------------------------------------------------------*/
290/*
291 * \brief Return matrix associated wiht a matrix assembler.
292 *
293 * Coefficients are not assigned at this stage.
294 *
295 * \param[in] f pointer to associated field
296 * \param[in] type matrix type
297 *
298 * \return pointer to associated matrix structure
299 */
300/*----------------------------------------------------------------------------*/
301
304 cs_matrix_type_t type);
305
306/*----------------------------------------------------------------------------*/
307/*
308 * \brief Assign coefficients to a matrix using a matrix assembler.
309 *
310 * \param[in] f pointer to associated field
311 * \param[in] type matrix type
312 * \param[in] symmetric is matrix symmetric ?
313 * \param[in] diag_block_size block sizes for diagonal, or nullptr
314 * \param[in] extra_diag_block_size block sizes for extra diagonal, or nullptr
315 * \param[in] da diagonal values (nullptr if zero)
316 * \param[in] xa extradiagonal values (nullptr if zero)
317 * casts as:
318 * xa[n_edges] if symmetric,
319 * xa[n_edges][2] if non symmetric
320 *
321 * \return pointer to associated matrix structure
322 */
323/*----------------------------------------------------------------------------*/
324
327 cs_matrix_type_t type,
328 bool symmetric,
329 cs_lnum_t diag_block_size,
330 cs_lnum_t extra_diag_block_size,
331 const cs_real_t *da,
332 const cs_real_t *xa);
333
334/*----------------------------------------------------------------------------
335 * Release of destroy matrix depending on whether is is cached or not.
336 *
337 * Matrices built by assembler are destroyed.
338 *
339 * parameters:
340 * matrix <-> pointer to matrix structure pointer
341 *----------------------------------------------------------------------------*/
342
343void
345
346/*----------------------------------------------------------------------------*/
347
349
350#endif /* __CS_MATRIX_DEFAULT_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
double cs_real_t
Floating-point value.
Definition: cs_defs.h:342
uint64_t cs_gnum_t
global mesh entity number
Definition: cs_defs.h:325
#define END_C_DECLS
Definition: cs_defs.h:543
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:335
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:110
cs_matrix_fill_type_t
Definition: cs_matrix.h:72
cs_matrix_type_t
Definition: cs_matrix.h:54
cs_matrix_t * cs_matrix_by_assembler(const cs_field_t *f, cs_matrix_type_t type)
Return matrix associated wiht a matrix assembler.
Definition: cs_matrix_default.cpp:936
int cs_matrix_get_tuning_runs(void)
Definition: cs_matrix_default.cpp:832
cs_matrix_t * cs_matrix_external(const char *type_name, bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size)
Return matrix wrapper for external library for a given fill type.
Definition: cs_matrix_default.cpp:636
const cs_gnum_t * cs_matrix_get_block_row_g_id(const cs_matrix_t *m)
Return a (0-based) global block row numbering for a given matrix.
Definition: cs_matrix_default.cpp:874
cs_matrix_t * cs_matrix_msr(void)
Definition: cs_matrix_default.cpp:604
cs_matrix_t * cs_matrix_copy_to_external(cs_matrix_t *src, bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size)
Copy base matrix to external library matrix type for given fill type.
Definition: cs_matrix_default.cpp:738
void cs_matrix_finalize(void)
Definition: cs_matrix_default.cpp:485
void cs_matrix_update_mesh(void)
Definition: cs_matrix_default.cpp:535
void cs_matrix_vector_native_multiply(bool symmetric, cs_lnum_t db_size, cs_lnum_t eb_size, int f_id, const cs_real_t *dam, const cs_real_t *xam, cs_real_t *vx, cs_real_t *vy)
Definition: cs_matrix_default.cpp:418
cs_matrix_t * cs_matrix_set_coefficients_by_assembler(const cs_field_t *f, cs_matrix_type_t type, bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size, const cs_real_t *da, const cs_real_t *xa)
Assign coefficients to a matrix using a matrix assembler.
Definition: cs_matrix_default.cpp:982
void cs_matrix_release(cs_matrix_t **m)
Definition: cs_matrix_default.cpp:1117
void cs_matrix_initialize(void)
Definition: cs_matrix_default.cpp:464
void cs_matrix_default_set_type(cs_matrix_fill_type_t fill_type, cs_matrix_type_t type)
Set default matrix type for a given fill type.
Definition: cs_matrix_default.cpp:850
void cs_matrix_default_set_tuned(cs_matrix_t *m)
Definition: cs_matrix_default.cpp:775
cs_matrix_t * cs_matrix_default(bool symmetric, cs_lnum_t diag_block_size, cs_lnum_t extra_diag_block_size)
Definition: cs_matrix_default.cpp:577
cs_matrix_t * cs_matrix_native(void)
Definition: cs_matrix_default.cpp:617
void cs_matrix_set_tuning_runs(int n_min_products)
Definition: cs_matrix_default.cpp:816
Field descriptor.
Definition: cs_field.h:131
Definition: cs_halo.h:77