7.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-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  * rotation_mode <-- halo update option for rotational periodicity
329  * precision <-- solver precision
330  * r_norm <-- residue normalization
331  * n_iter --> number of iterations
332  * residue --> residue
333  * rhs <-- right hand side
334  * vx <-> system solution
335  * aux_size <-- number of elements in aux_vectors (in bytes)
336  * aux_vectors --- optional working area (internal allocation if NULL)
337  *
338  * returns:
339  * convergence state
340  *----------------------------------------------------------------------------*/
341 
342 cs_sles_convergence_state_t
343 cs_sles_amgx_solve(void *context,
344  const char *name,
345  const cs_matrix_t *a,
346  int verbosity,
347  cs_halo_rotation_t rotation_mode,
348  double precision,
349  double r_norm,
350  int *n_iter,
351  double *residue,
352  const cs_real_t *rhs,
353  cs_real_t *vx,
354  size_t aux_size,
355  void *aux_vectors);
356 
357 /*----------------------------------------------------------------------------
358  * Free AmgX linear equation solver setup context.
359  *
360  * This function frees resolution-related data, such as
361  * buffers and preconditioning but does not free the whole context,
362  * as info used for logging (especially performance data) is maintained.
363 
364  * parameters:
365  * context <-> pointer to AmgX linear solver info
366  * (actual type: cs_sles_amgx_t *)
367  *----------------------------------------------------------------------------*/
368 
369 void
370 cs_sles_amgx_free(void *context);
371 
372 /*----------------------------------------------------------------------------
373  * Log sparse linear equation solver info.
374  *
375  * parameters:
376  * context <-> pointer to AmgX linear solver info
377  * (actual type: cs_sles_amgx_t *)
378  * log_type <-- log type
379  *----------------------------------------------------------------------------*/
380 
381 void
382 cs_sles_amgx_log(const void *context,
383  cs_log_t log_type);
384 
385 /*----------------------------------------------------------------------------*/
386 
387 END_C_DECLS
388 
389 #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_halo_rotation_t
cs_halo_rotation_t
Definition: cs_halo.h:60
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:1534
BEGIN_C_DECLS
#define BEGIN_C_DECLS
Definition: cs_defs.h:495
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:1566
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:307
cs_matrix_t
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:94
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
END_C_DECLS
#define END_C_DECLS
Definition: cs_defs.h:496
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_solve
cs_sles_convergence_state_t cs_sles_amgx_solve(void *context, const char *name, const cs_matrix_t *a, int verbosity, cs_halo_rotation_t rotation_mode, 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:1338
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