8.3
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-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_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
60typedef 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
95cs_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
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
125void *
126cs_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
136void
137cs_sles_amgx_destroy(void **context);
138
139/*----------------------------------------------------------------------------*/
149/*----------------------------------------------------------------------------*/
150
151const char *
152cs_sles_amgx_get_config(void *context);
153
154/*----------------------------------------------------------------------------*/
165/*----------------------------------------------------------------------------*/
166
167void
168cs_sles_amgx_set_config(void *context,
169 const char *config);
170
171/*----------------------------------------------------------------------------*/
181/*----------------------------------------------------------------------------*/
182
183const char *
184cs_sles_amgx_get_config_file(void *context);
185
186/*----------------------------------------------------------------------------*/
197/*----------------------------------------------------------------------------*/
198
199void
200cs_sles_amgx_set_config_file(void *context,
201 const char *path);
202
203/*----------------------------------------------------------------------------*/
214/*----------------------------------------------------------------------------*/
215
216bool
217cs_sles_amgx_get_use_device(void *context);
218
219/*----------------------------------------------------------------------------*/
229/*----------------------------------------------------------------------------*/
230
231void
232cs_sles_amgx_set_use_device(void *context,
233 bool use_device);
234
235/*----------------------------------------------------------------------------*/
245/*----------------------------------------------------------------------------*/
246
247void
248cs_sles_amgx_set_flags(void *context,
249 int flags);
250
251/*----------------------------------------------------------------------------*/
259/*----------------------------------------------------------------------------*/
260
261int
262cs_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
275void
276cs_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 <-- residual normalization
297 * n_iter --> number of iterations
298 * residual --> residual
299 * rhs <-- right hand side
300 * vx_ini <-- initial system solution
301 * (vx if nonzero, nullptr if zero)
302 * vx <-> system solution
303 * aux_size <-- number of elements in aux_vectors (in bytes)
304 * aux_vectors --- optional working area (internal allocation if NULL)
305 *
306 * returns:
307 * convergence state
308 *----------------------------------------------------------------------------*/
309
311cs_sles_amgx_solve(void *context,
312 const char *name,
313 const cs_matrix_t *a,
314 int verbosity,
315 double precision,
316 double r_norm,
317 int *n_iter,
318 double *residual,
319 const cs_real_t *rhs,
320 cs_real_t *vx_ini,
321 cs_real_t *vx,
322 size_t aux_size,
323 void *aux_vectors);
324
325/*----------------------------------------------------------------------------
326 * Free AmgX linear equation solver setup context.
327 *
328 * This function frees resolution-related data, such as
329 * buffers and preconditioning but does not free the whole context,
330 * as info used for logging (especially performance data) is maintained.
331
332 * parameters:
333 * context <-> pointer to AmgX linear solver info
334 * (actual type: cs_sles_amgx_t *)
335 *----------------------------------------------------------------------------*/
336
337void
338cs_sles_amgx_free(void *context);
339
340/*----------------------------------------------------------------------------
341 * Log sparse linear equation solver info.
342 *
343 * parameters:
344 * context <-> pointer to AmgX linear solver info
345 * (actual type: cs_sles_amgx_t *)
346 * log_type <-- log type
347 *----------------------------------------------------------------------------*/
348
349void
350cs_sles_amgx_log(const void *context,
351 cs_log_t log_type);
352
353/*----------------------------------------------------------------------------*/
359/*----------------------------------------------------------------------------*/
360
361void
363
364/*----------------------------------------------------------------------------*/
365
367
368#endif /* __CS_SLES_AMGX_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
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.cpp:1670
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 *residual, const cs_real_t *rhs, cs_real_t *vx_ini, cs_real_t *vx, size_t aux_size, void *aux_vectors)
Call AmgX linear equation solver.
Definition: cs_sles_amgx.cpp:1384
void cs_sles_amgx_destroy(void **context)
Destroy AmgX linear system solver info and context.
Definition: cs_sles_amgx.cpp:882
void cs_sles_amgx_set_flags(void *context, int flags)
Define additional AmgX solver usage flags.
Definition: cs_sles_amgx.cpp:1142
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.cpp: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.cpp:1162
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.cpp:844
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.cpp:1022
void cs_sles_amgx_log(const void *context, cs_log_t log_type)
Log sparse linear equation solver info.
Definition: cs_sles_amgx.cpp:1616
cs_sles_amgx_t * cs_sles_amgx_create(void)
Create AmgX linear system solver info and context.
Definition: cs_sles_amgx.cpp:795
const char * cs_sles_amgx_get_config(void *context)
return the solver configuration for an AmgX solver.
Definition: cs_sles_amgx.cpp:938
void cs_sles_amgx_set_config(void *context, const char *config)
Define the configuration for an AmgX solver.
Definition: cs_sles_amgx.cpp: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.cpp:1123
void cs_sles_amgx_free(void *context)
Free AmgX linear equation solver setup context.
Definition: cs_sles_amgx.cpp:1584
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.cpp: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.cpp:1066
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.cpp:761