8.3
general documentation
cs_sles_default.h
Go to the documentation of this file.
1#ifndef __CS_SLES_DEFAULT_H__
2#define __CS_SLES_DEFAULT_H__
3
4/*============================================================================
5 * Sparse Linear Equation Solvers
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_base.h"
35#include "cs_halo_perio.h"
36#include "cs_matrix.h"
37#include "cs_sles.h"
38
39/*----------------------------------------------------------------------------*/
40
42
43/*============================================================================
44 * Macro definitions
45 *============================================================================*/
46
47/*============================================================================
48 * Type definitions
49 *============================================================================*/
50
51/*============================================================================
52 * Global variables
53 *============================================================================*/
54
55/*=============================================================================
56 * Public function prototypes
57 *============================================================================*/
58
59/*----------------------------------------------------------------------------
60 * Default initializations for sparse linear equation solver API.
61 *----------------------------------------------------------------------------*/
62
63void
65
66/*----------------------------------------------------------------------------
67 * Default definition of a sparse linear equation solver
68 *
69 * parameters:
70 * f_id <-- associated field id, or < 0
71 * name <-- associated name if f_id < 0, or NULL
72 * a <-- matrix
73 *----------------------------------------------------------------------------*/
74
75void
76cs_sles_default(int f_id,
77 const char *name,
78 const cs_matrix_t *a);
79
80/*----------------------------------------------------------------------------
81 * Default setup setup for sparse linear equation solver API.
82 *
83 * This includes setup logging.
84 *----------------------------------------------------------------------------*/
85
86void
88
89/*----------------------------------------------------------------------------
90 * Return default verbosity associated to a field id, name couple.
91 *
92 * parameters:
93 * f_id <-- associated field id, or < 0
94 * name <-- associated name if f_id < 0, or NULL
95 *
96 * returns:
97 * verbosity associated with field or name
98 *----------------------------------------------------------------------------*/
99
100int
102 const char *name);
103
104/*----------------------------------------------------------------------------*/
105/*
106 * \brief Return pointer to matrix structure matching equation solve.
107 *
108 * Some matrix properties (such as assembly options and geometric
109 * association) are set immediately, but coefficients are not
110 * assigned at this stage.
111 *
112 * \param[in] f_id associated field id, or < 0
113 * \param[in] name associated name if f_id < 0, or nullptr
114 * \param[in] db_size block sizes for diagonal
115 * \param[in] eb_size block sizes for extra diagonal
116 * \param[in] symmetric indicate if matrix is symmetric
117 *
118 * \return pointer to matrix structure
119 */
120/*----------------------------------------------------------------------------*/
121
124 const char *name,
125 cs_lnum_t db_size,
126 cs_lnum_t eb_size,
127 bool symmetric);
128
129/*----------------------------------------------------------------------------
130 * Release of destroy matrix depending on whether is is cached or not.
131 *
132 * Matrices built by assembler are destroyed.
133 *
134 * parameters:
135 * matrix <-> pointer to matrix structure
136 *----------------------------------------------------------------------------*/
137
138void
140
141/*----------------------------------------------------------------------------
142 * Default finalization for sparse linear equation solver API.
143 *
144 * This includes performance data logging output.
145 *----------------------------------------------------------------------------*/
146
147void
149
150/*----------------------------------------------------------------------------
151 * Call sparse linear equation solver setup for convection-diffusion
152 * systems
153 *
154 * parameters:
155 * f_id associated field id, or < 0
156 * name associated name if f_id < 0, or NULL
157 * diag_block_size block sizes for diagonal
158 * extra_diag_block_size block sizes for extra diagonal
159 * da diagonal values (NULL if zero)
160 * xa extradiagonal values (NULL if zero)
161 * conv_diff convection-diffusion mode
162 */
163/*----------------------------------------------------------------------------*/
164
165void
167 const char *name,
168 const cs_lnum_t diag_block_size,
169 const cs_lnum_t extra_diag_block_size,
170 const cs_real_t *da,
171 const cs_real_t *xa,
172 bool conv_diff);
173
174/*----------------------------------------------------------------------------*/
175/*
176 * \brief Call sparse linear equation solver for general colocated
177 * cell-centered finite volume scheme.
178 *
179 * The initial solution is assumed to be 0 (and does not need to
180 * be initialized before calling this function).
181 *
182 * \param[in] sc solver context
183 * \param[in] a matrix
184 * \param[in] precision solver precision
185 * \param[in] r_norm residual normalization
186 * \param[out] n_iter number of "equivalent" iterations
187 * \param[out] residual residual
188 * \param[in] rhs right hand side
189 * \param[out] vx system solution
190 *
191 * \return convergence state
192 */
193/*----------------------------------------------------------------------------*/
194
197 cs_matrix_t *a,
198 double precision,
199 double r_norm,
200 int *n_iter,
201 double *residual,
202 const cs_real_t *rhs,
203 cs_real_t *vx);
204
205/*----------------------------------------------------------------------------
206 * Call sparse linear equation solver using native matrix arrays.
207 *
208 * parameters:
209 * f_id <-- associated field id, or < 0
210 * name <-- associated name if f_id < 0, or NULL
211 * symmetric <-- indicates if matrix coefficients are symmetric
212 * diag_block_size <-- block sizes for diagonal
213 * extra_diag_block_size <-- block sizes for extra diagonal
214 * da <-- diagonal values (NULL if zero)
215 * xa <-- extradiagonal values (NULL if zero)
216 * r_epsilon <-- precision
217 * r_norm <-- residual normalization
218 * n_iter --> number of iterations
219 * residual --> residual
220 * rhs <-- right hand side
221 * vx <-> system solution
222 *
223 * returns:
224 * convergence state
225 *----------------------------------------------------------------------------*/
226
228cs_sles_solve_native(int f_id,
229 const char *name,
230 bool symmetric,
231 cs_lnum_t diag_block_size,
232 cs_lnum_t extra_diag_block_size,
233 const cs_real_t *da,
234 const cs_real_t *xa,
235 double precision,
236 double r_norm,
237 int *n_iter,
238 double *residual,
239 const cs_real_t *rhs,
240 cs_real_t *vx);
241
242/*----------------------------------------------------------------------------
243 * Free sparse linear equation solver setup using native matrix arrays.
244 *
245 * parameters:
246 * f_id <-- associated field id, or < 0
247 * name <-- associated name if f_id < 0, or NULL
248 *----------------------------------------------------------------------------*/
249
250void
251cs_sles_free_native(int f_id,
252 const char *name);
253
254/*----------------------------------------------------------------------------
255 * Error handler attempting fallback to alternative solution procedure for
256 * sparse linear equation solver.
257 *
258 * In case of divergence with an iterative solver, this error handler
259 * switches to a default preconditioner, then resets the solution vector.
260 *
261 * The default error for the solver type handler is then set, in case
262 * the solution fails again.
263 *
264 * Note that this error handler may rebuild solver contexts, so should not
265 * be used in conjunction with shared contexts (such as multigrid
266 * ascent/descent contexts), but only for "outer" solvers.
267 *
268 * parameters:
269 * sles <-> pointer to solver object
270 * state <-- convergence status
271 * a <-- matrix
272 * rhs <-- right hand side
273 * vx <-> system solution
274 *
275 * returns:
276 * true if fallback solution is possible, false otherwise
277 *----------------------------------------------------------------------------*/
278
279bool
282 const cs_matrix_t *a,
283 const cs_real_t rhs[],
284 cs_real_t vx[]);
285
286/*----------------------------------------------------------------------------*/
287
289
290#endif /* __CS_SLES_DEFAULT_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
double cs_real_t
Floating-point value.
Definition: cs_defs.h:342
#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_sles_convergence_state_t
Definition: cs_sles.h:56
struct _cs_sles_t cs_sles_t
Definition: cs_sles.h:68
void cs_sles_free_native(int f_id, const char *name)
Free sparse linear equation solver setup using native matrix arrays.
Definition: cs_sles_default.cpp:1235
void cs_sles_setup_native_conv_diff(int f_id, const char *name, const cs_lnum_t diag_block_size, const cs_lnum_t extra_diag_block_size, const cs_real_t *da, const cs_real_t *xa, bool conv_diff)
Call sparse linear equation solver setup for convection-diffusion systems.
Definition: cs_sles_default.cpp:867
cs_matrix_t * cs_sles_default_get_matrix(int f_id, const char *name, cs_lnum_t db_size, cs_lnum_t eb_size, bool symmetric)
Return pointer to matrix structure matching equation solve.
Definition: cs_sles_default.cpp:664
int cs_sles_default_get_verbosity(int f_id, const char *name)
Return default verbosity associated to a field id, name couple.
Definition: cs_sles_default.cpp:621
cs_sles_convergence_state_t cs_sles_solve_native(int f_id, const char *name, 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, double precision, double r_norm, int *n_iter, double *residual, const cs_real_t *rhs, cs_real_t *vx)
Call sparse linear equation solver using native matrix arrays.
Definition: cs_sles_default.cpp:1085
void cs_sles_default_setup(void)
Default setup for sparse linear equation solver API.
Definition: cs_sles_default.cpp:543
cs_sles_convergence_state_t cs_sles_solve_ccc_fv(cs_sles_t *sc, cs_matrix_t *a, double precision, double r_norm, int *n_iter, double *residual, const cs_real_t *rhs, cs_real_t *vx)
Call sparse linear equation solver for general colocated cell-centered finite volume scheme.
Definition: cs_sles_default.cpp:977
void cs_sles_default_log_setup(void)
void cs_sles_default_finalize(void)
Default finalization for sparse linear equation solver API.
Definition: cs_sles_default.cpp:601
bool cs_sles_default_error(cs_sles_t *sles, cs_sles_convergence_state_t state, const cs_matrix_t *a, const cs_real_t rhs[], cs_real_t vx[])
Error handler attempting fallback to alternative solution procedure for sparse linear equation solver...
Definition: cs_sles_default.cpp:1294
void cs_sles_default(int f_id, const char *name, const cs_matrix_t *a)
Default definition of a sparse linear equation solver.
Definition: cs_sles_default.cpp:524
void cs_sles_default_release_matrix(cs_matrix_t **m)
Definition: cs_sles_default.cpp:845