8.0
general documentation
cs_sles_amgx.h
Go to the documentation of this file.
1 #ifndef __CS_SLES_AMGX_H__
2 #define __CS_SLES_AMGX_H__
3 
4 /*============================================================================
5  * Sparse Linear Equation Solvers using AmgX
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_base.h"
35 #include "cs_matrix.h"
36 #include "cs_sles.h"
37 
38 /*----------------------------------------------------------------------------*/
39 
41 
42 /*============================================================================
43  * Macro definitions
44  *============================================================================*/
45 
52 #define CS_SLES_AMGX_PREFER_COMM_FROM_MAPS (1 << 0)
53 
54 /*============================================================================
55  * Type definitions
56  *============================================================================*/
57 
58 /* AmgX linear solver context (opaque) */
59 
60 typedef struct _cs_sles_amgx_t cs_sles_amgx_t;
61 
62 /*============================================================================
63  * Global variables
64  *============================================================================*/
65 
66 /*=============================================================================
67  * Public function prototypes
68  *============================================================================*/
69 
70 /*----------------------------------------------------------------------------
71  * Define and associate an AmgX linear system solver
72  * for a given field or equation name.
73  *
74  * If this system did not previously exist, it is added to the list of
75  * "known" systems. Otherwise, its definition is replaced by the one
76  * defined here.
77  *
78  * This is a utility function: if finer control is needed, see
79  * cs_sles_define() and cs_sles_amgx_create().
80  *
81  * Note that this function returns a pointer directly to the AmgX solver
82  * management structure. This may be used to set further options.
83  * If needed, cs_sles_find() may be used to obtain a pointer to the matching
84  * cs_sles_t container.
85  *
86  * parameters:
87  * f_id <-- associated field id, or < 0
88  * name <-- associated name if f_id < 0, or NULL
89  *
90  * returns:
91  * pointer to newly created AmgX solver info object.
92  *----------------------------------------------------------------------------*/
93 
95 cs_sles_amgx_define(int f_id,
96  const char *name);
97 
98 /*----------------------------------------------------------------------------
99  * Create AmgX linear system solver info and context.
100  *
101  * In case of rotational periodicity for a block (non-scalar) matrix,
102  * the matrix type will be forced to MATSHELL ("shell") regardless
103  * of the option used.
104  *
105  * returns:
106  * pointer to newly created solver info object.
107  *----------------------------------------------------------------------------*/
108 
110 cs_sles_amgx_create(void);
111 
112 /*----------------------------------------------------------------------------
113  * Create AmgX linear system solver info and context
114  * based on existing info and context.
115  *
116  * parameters:
117  * context <-- pointer to reference info and context
118  * (actual type: cs_sles_amgx_t *)
119  *
120  * returns:
121  * pointer to newly created solver info object
122  * (actual type: cs_sles_amgx_t *)
123  *----------------------------------------------------------------------------*/
124 
125 void *
126 cs_sles_amgx_copy(const void *context);
127 
128 /*----------------------------------------------------------------------------
129  * Destroy AmgX linear system solver info and context.
130  *
131  * parameters:
132  * context <-> pointer to AmgX linear solver info
133  * (actual type: cs_sles_amgx_t **)
134  *----------------------------------------------------------------------------*/
135 
136 void
137 cs_sles_amgx_destroy(void **context);
138 
139 /*----------------------------------------------------------------------------*/
149 /*----------------------------------------------------------------------------*/
150 
151 const char *
152 cs_sles_amgx_get_config(void *context);
153 
154 /*----------------------------------------------------------------------------*/
165 /*----------------------------------------------------------------------------*/
166 
167 void
168 cs_sles_amgx_set_config(void *context,
169  const char *config);
170 
171 /*----------------------------------------------------------------------------*/
181 /*----------------------------------------------------------------------------*/
182 
183 const char *
184 cs_sles_amgx_get_config_file(void *context);
185 
186 /*----------------------------------------------------------------------------*/
197 /*----------------------------------------------------------------------------*/
198 
199 void
200 cs_sles_amgx_set_config_file(void *context,
201  const char *path);
202 
203 /*----------------------------------------------------------------------------*/
214 /*----------------------------------------------------------------------------*/
215 
216 bool
217 cs_sles_amgx_get_use_device(void *context);
218 
219 /*----------------------------------------------------------------------------*/
229 /*----------------------------------------------------------------------------*/
230 
231 void
232 cs_sles_amgx_set_use_device(void *context,
233  bool use_device);
234 
235 /*----------------------------------------------------------------------------*/
245 /*----------------------------------------------------------------------------*/
246 
247 void
248 cs_sles_amgx_set_flags(void *context,
249  int flags);
250 
251 /*----------------------------------------------------------------------------*/
259 /*----------------------------------------------------------------------------*/
260 
261 int
262 cs_sles_amgx_get_flags(void *context);
263 
264 /*----------------------------------------------------------------------------
265  * Setup AmgX linear equation solver.
266  *
267  * parameters:
268  * context <-> pointer to AmgX linear solver info
269  * (actual type: cs_sles_amgx_t *)
270  * name <-- pointer to system name
271  * a <-- associated matrix
272  * verbosity <-- verbosity level
273  *----------------------------------------------------------------------------*/
274 
275 void
276 cs_sles_amgx_setup(void *context,
277  const char *name,
278  const cs_matrix_t *a,
279  int verbosity);
280 
281 /*----------------------------------------------------------------------------
282  * Call AmgX linear equation solver.
283  *
284  * \warn The precision, r_norm, and n_iter parameters are ignored here.
285  * the matching configuration options should be set earlier, using
286  * the \ref cs_sles_amgx_set_config function
287  *
288  *
289  * parameters:
290  * context <-> pointer to AmgX linear solver info
291  * (actual type: cs_sles_amgx_t *)
292  * name <-- pointer to system name
293  * a <-- matrix
294  * verbosity <-- verbosity level
295  * precision <-- solver precision
296  * r_norm <-- residue normalization
297  * n_iter --> number of iterations
298  * residue --> residue
299  * rhs <-- right hand side
300  * vx <-> system solution
301  * aux_size <-- number of elements in aux_vectors (in bytes)
302  * aux_vectors --- optional working area (internal allocation if NULL)
303  *
304  * returns:
305  * convergence state
306  *----------------------------------------------------------------------------*/
307 
309 cs_sles_amgx_solve(void *context,
310  const char *name,
311  const cs_matrix_t *a,
312  int verbosity,
313  double precision,
314  double r_norm,
315  int *n_iter,
316  double *residue,
317  const cs_real_t *rhs,
318  cs_real_t *vx,
319  size_t aux_size,
320  void *aux_vectors);
321 
322 /*----------------------------------------------------------------------------
323  * Free AmgX linear equation solver setup context.
324  *
325  * This function frees resolution-related data, such as
326  * buffers and preconditioning but does not free the whole context,
327  * as info used for logging (especially performance data) is maintained.
328 
329  * parameters:
330  * context <-> pointer to AmgX linear solver info
331  * (actual type: cs_sles_amgx_t *)
332  *----------------------------------------------------------------------------*/
333 
334 void
335 cs_sles_amgx_free(void *context);
336 
337 /*----------------------------------------------------------------------------
338  * Log sparse linear equation solver info.
339  *
340  * parameters:
341  * context <-> pointer to AmgX linear solver info
342  * (actual type: cs_sles_amgx_t *)
343  * log_type <-- log type
344  *----------------------------------------------------------------------------*/
345 
346 void
347 cs_sles_amgx_log(const void *context,
348  cs_log_t log_type);
349 
350 /*----------------------------------------------------------------------------*/
356 /*----------------------------------------------------------------------------*/
357 
358 void
360 
361 /*----------------------------------------------------------------------------*/
362 
364 
365 #endif /* __CS_SLES_AMGX_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:509
double cs_real_t
Floating-point value.
Definition: cs_defs.h:319
#define END_C_DECLS
Definition: cs_defs.h:510
cs_log_t
Definition: cs_log.h:48
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:110
cs_sles_convergence_state_t
Definition: cs_sles.h:56
void cs_sles_amgx_library_info(cs_log_t log_type)
Print information on AmgX library.
Definition: cs_sles_amgx.c:1657
void cs_sles_amgx_destroy(void **context)
Destroy AmgX linear system solver info and context.
Definition: cs_sles_amgx.c:882
const char * cs_sles_amgx_get_config_file(void *context)
return the name of the solver configuration file for an AmgX solver.
Definition: cs_sles_amgx.c:1022
void cs_sles_amgx_set_flags(void *context, int flags)
Define additional AmgX solver usage flags.
Definition: cs_sles_amgx.c:1142
cs_sles_amgx_t * cs_sles_amgx_define(int f_id, const char *name)
Define and associate an AmgX linear system solver for a given field or equation name.
Definition: cs_sles_amgx.c:761
void * cs_sles_amgx_copy(const void *context)
Create AmgX linear system solver info and context based on existing info and context.
Definition: cs_sles_amgx.c:844
void cs_sles_amgx_set_config_file(void *context, const char *path)
Set the solver configuration file for an AmgX solver.
Definition: cs_sles_amgx.c:1043
void cs_sles_amgx_setup(void *context, const char *name, const cs_matrix_t *a, int verbosity)
Setup AmgX linear equation solver.
Definition: cs_sles_amgx.c:1162
void cs_sles_amgx_log(const void *context, cs_log_t log_type)
Log sparse linear equation solver info.
Definition: cs_sles_amgx.c:1603
const char * cs_sles_amgx_get_config(void *context)
return the solver configuration for an AmgX solver.
Definition: cs_sles_amgx.c:938
void cs_sles_amgx_set_config(void *context, const char *config)
Define the configuration for an AmgX solver.
Definition: cs_sles_amgx.c:997
struct _cs_sles_amgx_t cs_sles_amgx_t
Definition: cs_sles_amgx.h:60
int cs_sles_amgx_get_flags(void *context)
Query additional AmgX solver usage flags.
Definition: cs_sles_amgx.c:1123
void cs_sles_amgx_free(void *context)
Free AmgX linear equation solver setup context.
Definition: cs_sles_amgx.c:1571
cs_sles_convergence_state_t cs_sles_amgx_solve(void *context, const char *name, const cs_matrix_t *a, int verbosity, double precision, double r_norm, int *n_iter, double *residue, const cs_real_t *rhs, cs_real_t *vx, size_t aux_size, void *aux_vectors)
Call AmgX linear equation solver.
Definition: cs_sles_amgx.c:1382
void cs_sles_amgx_set_use_device(void *context, bool use_device)
Define whether an AmgX solver should use the device or host.
Definition: cs_sles_amgx.c:1092
bool cs_sles_amgx_get_use_device(void *context)
Define whether an AmgX solver should use the device or host.
Definition: cs_sles_amgx.c:1066
cs_sles_amgx_t * cs_sles_amgx_create(void)
Create AmgX linear system solver info and context.
Definition: cs_sles_amgx.c:795
double precision, save a
Definition: cs_fuel_incl.f90:148