7.1
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-2021 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 
40 BEGIN_C_DECLS
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 
94 cs_sles_amgx_t *
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 
109 cs_sles_amgx_t *
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_pin_memory(void *context);
218 
219 /*----------------------------------------------------------------------------*/
230 /*----------------------------------------------------------------------------*/
231 
232 void
233 cs_sles_amgx_set_pin_memory(void *context,
234  bool pin_memory);
235 
236 /*----------------------------------------------------------------------------*/
247 /*----------------------------------------------------------------------------*/
248 
249 bool
250 cs_sles_amgx_get_use_device(void *context);
251 
252 /*----------------------------------------------------------------------------*/
262 /*----------------------------------------------------------------------------*/
263 
264 void
265 cs_sles_amgx_set_use_device(void *context,
266  bool use_device);
267 
268 /*----------------------------------------------------------------------------*/
278 /*----------------------------------------------------------------------------*/
279 
280 void
281 cs_sles_amgx_set_flags(void *context,
282  int flags);
283 
284 /*----------------------------------------------------------------------------*/
292 /*----------------------------------------------------------------------------*/
293 
294 int
295 cs_sles_amgx_get_flags(void *context);
296 
297 /*----------------------------------------------------------------------------
298  * Setup AmgX linear equation solver.
299  *
300  * parameters:
301  * context <-> pointer to AmgX linear solver info
302  * (actual type: cs_sles_amgx_t *)
303  * name <-- pointer to system name
304  * a <-- associated matrix
305  * verbosity <-- verbosity level
306  *----------------------------------------------------------------------------*/
307 
308 void
309 cs_sles_amgx_setup(void *context,
310  const char *name,
311  const cs_matrix_t *a,
312  int verbosity);
313 
314 /*----------------------------------------------------------------------------
315  * Call AmgX linear equation solver.
316  *
317  * \warn The precision, r_norm, and n_iter parameters are ignored here.
318  * the matching configuration options should be set earlier, using
319  * the \ref cs_sles_amgx_set_config function
320  *
321  *
322  * parameters:
323  * context <-> pointer to AmgX linear solver info
324  * (actual type: cs_sles_amgx_t *)
325  * name <-- pointer to system name
326  * a <-- matrix
327  * verbosity <-- verbosity level
328  * precision <-- solver precision
329  * r_norm <-- residue normalization
330  * n_iter --> number of iterations
331  * residue --> residue
332  * rhs <-- right hand side
333  * vx <-> system solution
334  * aux_size <-- number of elements in aux_vectors (in bytes)
335  * aux_vectors --- optional working area (internal allocation if NULL)
336  *
337  * returns:
338  * convergence state
339  *----------------------------------------------------------------------------*/
340 
341 cs_sles_convergence_state_t
342 cs_sles_amgx_solve(void *context,
343  const char *name,
344  const cs_matrix_t *a,
345  int verbosity,
346  double precision,
347  double r_norm,
348  int *n_iter,
349  double *residue,
350  const cs_real_t *rhs,
351  cs_real_t *vx,
352  size_t aux_size,
353  void *aux_vectors);
354 
355 /*----------------------------------------------------------------------------
356  * Free AmgX linear equation solver setup context.
357  *
358  * This function frees resolution-related data, such as
359  * buffers and preconditioning but does not free the whole context,
360  * as info used for logging (especially performance data) is maintained.
361 
362  * parameters:
363  * context <-> pointer to AmgX linear solver info
364  * (actual type: cs_sles_amgx_t *)
365  *----------------------------------------------------------------------------*/
366 
367 void
368 cs_sles_amgx_free(void *context);
369 
370 /*----------------------------------------------------------------------------
371  * Log sparse linear equation solver info.
372  *
373  * parameters:
374  * context <-> pointer to AmgX linear solver info
375  * (actual type: cs_sles_amgx_t *)
376  * log_type <-- log type
377  *----------------------------------------------------------------------------*/
378 
379 void
380 cs_sles_amgx_log(const void *context,
381  cs_log_t log_type);
382 
383 /*----------------------------------------------------------------------------*/
389 /*----------------------------------------------------------------------------*/
390 
391 void
392 cs_sles_amgx_library_info(cs_log_t log_type);
393 
394 /*----------------------------------------------------------------------------*/
395 
396 END_C_DECLS
397 
398 #endif /* __CS_SLES_AMGX_H__ */
cs_sles_amgx_set_pin_memory
void cs_sles_amgx_set_pin_memory(void *context, bool pin_memory)
Define whether an AmgX solver should pin host memory.
Definition: cs_sles_amgx.c:1071
cs_sles_amgx_define
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:740
cs_base.h
cs_sles.h
cs_sles_amgx_free
void cs_sles_amgx_free(void *context)
Free AmgX linear equation solver setup context.
Definition: cs_sles_amgx.c:1524
BEGIN_C_DECLS
#define BEGIN_C_DECLS
Definition: cs_defs.h:510
cs_sles_amgx_log
void cs_sles_amgx_log(const void *context, cs_log_t log_type)
Log sparse linear equation solver info.
Definition: cs_sles_amgx.c:1556
cs_sles_amgx_set_use_device
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:1116
cs_sles_amgx_setup
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:1186
cs_matrix.h
cs_real_t
double cs_real_t
Floating-point value.
Definition: cs_defs.h:322
cs_matrix_t
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:93
cs_sles_convergence_state_t
cs_sles_convergence_state_t
Convergence status indicator.
Definition: cs_sles.h:56
cs_fuel_incl::a
double precision, save a
Definition: cs_fuel_incl.f90:146
cs_sles_amgx_get_config
const char * cs_sles_amgx_get_config(void *context)
return the solver configuration for an AmgX solver.
Definition: cs_sles_amgx.c:919
cs_log_t
cs_log_t
Definition: cs_log.h:48
cs_sles_amgx_set_config_file
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:1024
cs_sles_amgx_get_use_device
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:1090
cs_sles_amgx_destroy
void cs_sles_amgx_destroy(void **context)
Destroy AmgX linear system solver info and context.
Definition: cs_sles_amgx.c:863
cs_sles_amgx_get_config_file
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:1003
cs_sles_amgx_get_flags
int cs_sles_amgx_get_flags(void *context)
Query additional AmgX solver usage flags.
Definition: cs_sles_amgx.c:1147
cs_sles_amgx_solve
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:1337
END_C_DECLS
#define END_C_DECLS
Definition: cs_defs.h:511
cs_sles_amgx_t
struct _cs_sles_amgx_t cs_sles_amgx_t
Definition: cs_sles_amgx.h:60
cs_sles_amgx_copy
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:824
cs_sles_amgx_get_pin_memory
bool cs_sles_amgx_get_pin_memory(void *context)
Indicate whether an AmgX solver should pin host memory.
Definition: cs_sles_amgx.c:1050
cs_sles_amgx_set_config
void cs_sles_amgx_set_config(void *context, const char *config)
Define the configuration for an AmgX solver.
Definition: cs_sles_amgx.c:978
cs_sles_amgx_library_info
void cs_sles_amgx_library_info(cs_log_t log_type)
Print information on AmgX library.
Definition: cs_sles_amgx.c:1610
cs_sles_amgx_set_flags
void cs_sles_amgx_set_flags(void *context, int flags)
Define additional AmgX solver usage flags.
Definition: cs_sles_amgx.c:1166
cs_sles_amgx_create
cs_sles_amgx_t * cs_sles_amgx_create(void)
Create AmgX linear system solver info and context.
Definition: cs_sles_amgx.c:774