8.3
general documentation
cs_sles_pc.h
Go to the documentation of this file.
1#ifndef __CS_SLES_PC_H__
2#define __CS_SLES_PC_H__
3
4/*============================================================================
5 * Sparse Linear Equation Solver Preconditioner driver
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_log.h"
36#include "cs_halo_perio.h"
37#include "cs_matrix.h"
38
39/*----------------------------------------------------------------------------*/
40
42
43/*============================================================================
44 * Macro definitions
45 *============================================================================*/
46
47/*============================================================================
48 * Type definitions
49 *============================================================================*/
50
51/*----------------------------------------------------------------------------
52 * Convergence status
53 *----------------------------------------------------------------------------*/
54
55typedef enum {
56
61
63
64/* General linear solver context (opaque) */
65
66typedef struct _cs_sles_pc_t cs_sles_pc_t;
67
68/*----------------------------------------------------------------------------
69 * Function pointer returning the type name of a preconditioner context.
70 *
71 * The context structure depends on the type of preconditioner used,
72 * which may in turn be determined by the string returned by
73 * cs_sles_pc_get_type() and cs_sles_pc_get_type_name().
74 * If may be used by appropriate functions specific to that type.
75 *
76 * parameters:
77 * context <-- pointer to preconditioner-specific context
78 * logging <-- if true, a name appropritate to logging
79 * (possibly translated) is returned; if false,
80 * a canonical name is returned.
81 *----------------------------------------------------------------------------*/
82
83typedef const char *
84(cs_sles_pc_get_type_t) (const void *context,
85 bool logging);
86
87/*----------------------------------------------------------------------------
88 * Function pointer for pre-resolution setup of a preconditioner context.
89 *
90 * This setup may include building a multigrid hierarchy, for example.
91 *
92 * parameters:
93 * context <-> pointer to preconditioner context
94 * name <-- pointer to name of associated linear system
95 * a <-- matrix
96 * accel <-- use accelerator version ?
97 * verbosity <-- associated verbosity
98 *----------------------------------------------------------------------------*/
99
100typedef void
101(cs_sles_pc_setup_t) (void *context,
102 const char *name,
103 const cs_matrix_t *a,
104 bool accel,
105 int verbosity);
106
107/*----------------------------------------------------------------------------
108 * Function pointer for setting of the required tolerance for preconditioners
109 * involving an iterative solver.
110 *
111 * This will usually not be relevant to non-iterative preconditioners,
112 * for which this type of function does not need to be defined.
113 *
114 * The preconditioner is considered to have converged when
115 * residual/r_norm <= precision, residual being the L2 norm of a.vx-rhs.
116 *
117 * parameters:
118 * context <-> pointer to preconditioner context
119 * precision <-- preconditioner precision
120 * r_norm <-- residual normalization
121 *----------------------------------------------------------------------------*/
122
123typedef void
124(cs_sles_pc_tolerance_t) (void *context,
125 double precision,
126 double r_norm);
127
128/*----------------------------------------------------------------------------
129 * Function pointer for application of a preconditioner.
130 *
131 * In cases where it is desired that the preconditioner modify a vector
132 * "in place", x_in should be set to NULL, and x_out contain the vector to
133 * be modified (\f$x_{out} \leftarrow M^{-1}x_{out})\f$).
134 *
135 * parameters:
136 * context <-> pointer to preconditioner context
137 * x_in <-- input vector
138 * x_out <-> input/output vector
139 *
140 * returns:
141 * preconditioner application status
142 *----------------------------------------------------------------------------*/
143
145(cs_sles_pc_apply_t) (void *context,
146 const cs_real_t *x_in,
147 cs_real_t *x_out);
148
149/*----------------------------------------------------------------------------
150 * Function pointer for freeing of a preconditioner's context data.
151 *
152 * Note that this function should free resolution-related data, such as
153 * multigrid hierarchy and any other temporary arrays or
154 * objects required for application, but should not free the whole context,
155 * as info used for logging (especially performance data) should be
156 * maintained.
157 *
158 * parameters:
159 * context <-> pointer to preconditioner context
160 *----------------------------------------------------------------------------*/
161
162typedef void
163(cs_sles_pc_free_t) (void *context);
164
165/*----------------------------------------------------------------------------
166 * Function pointer for logging of linear preconditioner setup,
167 * history and performance data.
168 *
169 * This function will indirectly be called for each preconditioner when
170 * cs_sles_finalize() is called.
171 *
172 * parameters:
173 * context <-- pointer to preconditioner context
174 * log_type <-- log type
175 *----------------------------------------------------------------------------*/
176
177typedef void
178(cs_sles_pc_log_t) (const void *context,
179 cs_log_t log_type);
180
181/*----------------------------------------------------------------------------
182 * Function pointer for creation of a preconditioner context based on the
183 * copy of another.
184 *
185 * The new context copies the settings of the copied context, but not
186 * its setup data and logged info, such as performance data.
187 *
188 * This type of function is optional, but enables associating different
189 * preconditioners to related systems (to differentiate logging) while using
190 * the same settings by default.
191 *
192 * parameters:
193 * context <-- context to clone
194 *
195 * returns:
196 * pointer to newly created context
197 *----------------------------------------------------------------------------*/
198
199typedef void *
200(cs_sles_pc_clone_t) (const void *context);
201
202/*----------------------------------------------------------------------------
203 * Function pointer for destruction of a preconditioner context.
204 *
205 * This function should free all context data.
206 *
207 * parameters:
208 * context <-> pointer to preconditioner context
209 *----------------------------------------------------------------------------*/
210
211typedef void
212(cs_sles_pc_destroy_t) (void **context);
213
214/*============================================================================
215 * Global variables
216 *============================================================================*/
217
218/*=============================================================================
219 * Public function prototypes for Fortran API
220 *============================================================================*/
221
222/*=============================================================================
223 * Public function prototypes
224 *============================================================================*/
225
226/*----------------------------------------------------------------------------*/
238/*----------------------------------------------------------------------------*/
239
240void
242 cs_log_t log_type);
243
244/*----------------------------------------------------------------------------*/
269/*----------------------------------------------------------------------------*/
270
272cs_sles_pc_define(void *context,
273 cs_sles_pc_get_type_t *get_type_func,
274 cs_sles_pc_setup_t *setup_func,
275 cs_sles_pc_tolerance_t *tolerance_func,
276 cs_sles_pc_apply_t *apply_func,
277 cs_sles_pc_free_t *free_func,
278 cs_sles_pc_log_t *log_func,
279 cs_sles_pc_clone_t *clone_func,
280 cs_sles_pc_destroy_t *destroy_func);
281
282/*----------------------------------------------------------------------------*/
289/*----------------------------------------------------------------------------*/
290
291void
293
294/*----------------------------------------------------------------------------*/
308/*----------------------------------------------------------------------------*/
309
312
313/*----------------------------------------------------------------------------*/
326/*----------------------------------------------------------------------------*/
327
328const char *
330
331/*----------------------------------------------------------------------------*/
339/*----------------------------------------------------------------------------*/
340
341const char *
343
344/*----------------------------------------------------------------------------*/
356/*----------------------------------------------------------------------------*/
357
358void *
360
361/*----------------------------------------------------------------------------*/
371/*----------------------------------------------------------------------------*/
372
375
376/*----------------------------------------------------------------------------*/
394/*----------------------------------------------------------------------------*/
395
396void
398 double precision,
399 double r_norm);
400
401/*----------------------------------------------------------------------------*/
418/*----------------------------------------------------------------------------*/
419
420void
422 const char *name,
423 const cs_matrix_t *a,
424 bool accel,
425 int verbosity);
426
427/*----------------------------------------------------------------------------*/
444/*----------------------------------------------------------------------------*/
445
448 cs_real_t *x_in,
449 cs_real_t *x_out);
450
451/*----------------------------------------------------------------------------*/
462/*----------------------------------------------------------------------------*/
463
464void
466
467/*----------------------------------------------------------------------------*/
473/*----------------------------------------------------------------------------*/
474
477
478/*----------------------------------------------------------------------------*/
484/*----------------------------------------------------------------------------*/
485
488
489/*----------------------------------------------------------------------------*/
495/*----------------------------------------------------------------------------*/
496
499
500/*----------------------------------------------------------------------------*/
506/*----------------------------------------------------------------------------*/
507
510
511/*----------------------------------------------------------------------------*/
512
514
515#endif /* __CS_SLES_PC_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_pc_state_t() cs_sles_pc_apply_t(void *context, const cs_real_t *x_in, cs_real_t *x_out)
Function pointer for application of a preconditioner.
Definition: cs_sles_pc.h:145
cs_sles_pc_t * cs_sles_pc_jacobi_create(void)
Create a Jacobi preconditioner.
Definition: cs_sles_pc.cpp:1078
void() cs_sles_pc_free_t(void *context)
Function pointer for freeing of a preconditioner's context data.
Definition: cs_sles_pc.h:163
const char * cs_sles_pc_get_type_name(cs_sles_pc_t *pc)
Return type name of preconditioner context.
Definition: cs_sles_pc.cpp:853
void() cs_sles_pc_tolerance_t(void *context, double precision, double r_norm)
Function pointer for setting of the required tolerance for preconditioners involving an iterative sol...
Definition: cs_sles_pc.h:124
cs_sles_pc_state_t
Definition: cs_sles_pc.h:55
@ CS_SLES_PC_CONVERGED
Definition: cs_sles_pc.h:60
@ CS_SLES_PC_DIVERGED
Definition: cs_sles_pc.h:57
@ CS_SLES_PC_BREAKDOWN
Definition: cs_sles_pc.h:58
@ CS_SLES_PC_MAX_ITERATION
Definition: cs_sles_pc.h:59
struct _cs_sles_pc_t cs_sles_pc_t
Definition: cs_sles_pc.h:66
cs_sles_pc_t * cs_sles_pc_poly_2_create(void)
Create a polynomial preconditioner of degree 2.
Definition: cs_sles_pc.cpp:1134
void cs_sles_pc_setup(cs_sles_pc_t *pc, const char *name, const cs_matrix_t *a, bool accel, int verbosity)
Setup sparse linear equation preconditioner.
Definition: cs_sles_pc.cpp:958
cs_sles_pc_t * cs_sles_pc_none_create(void)
Create an "identity" (or null) preconditioner.
Definition: cs_sles_pc.cpp:1050
void() cs_sles_pc_destroy_t(void **context)
Definition: cs_sles_pc.h:212
const char * cs_sles_pc_get_type(cs_sles_pc_t *pc)
Return type name of preconditioner context.
Definition: cs_sles_pc.cpp:832
void cs_sles_pc_log(cs_sles_pc_t *pc, cs_log_t log_type)
Log preconditioner setup, history and performance data.
Definition: cs_sles_pc.cpp:1034
const char *() cs_sles_pc_get_type_t(const void *context, bool logging)
Function pointer returning the type name of a preconditioner context.
Definition: cs_sles_pc.h:84
void *() cs_sles_pc_clone_t(const void *context)
Function pointer for creation of a preconditioner context based on the copy of another.
Definition: cs_sles_pc.h:200
cs_sles_pc_apply_t * cs_sles_pc_get_apply_func(const cs_sles_pc_t *pc)
Return a pointer to the function used to apply a preconditioner.
Definition: cs_sles_pc.cpp:901
cs_sles_pc_t * cs_sles_pc_define(void *context, cs_sles_pc_get_type_t *get_type_func, cs_sles_pc_setup_t *setup_func, cs_sles_pc_tolerance_t *tolerance_func, cs_sles_pc_apply_t *apply_func, cs_sles_pc_free_t *free_func, cs_sles_pc_log_t *log_func, cs_sles_pc_clone_t *clone_func, cs_sles_pc_destroy_t *destroy_func)
Define sparse linear equation preconditioner.
Definition: cs_sles_pc.cpp:726
cs_sles_pc_t * cs_sles_pc_clone(const cs_sles_pc_t *src)
Create a new preconditioner context based on the copy of another.
Definition: cs_sles_pc.cpp:792
cs_sles_pc_state_t cs_sles_pc_apply(cs_sles_pc_t *pc, cs_real_t *x_in, cs_real_t *x_out)
Apply a preconditioner.
Definition: cs_sles_pc.cpp:990
cs_sles_pc_t * cs_sles_pc_poly_1_create(void)
Create a polynomial preconditioner of degree 1.
Definition: cs_sles_pc.cpp:1106
void cs_sles_pc_free(cs_sles_pc_t *pc)
Free preconditioner setup.
Definition: cs_sles_pc.cpp:1011
void * cs_sles_pc_get_context(cs_sles_pc_t *pc)
Return pointer to preconditioner context structure pointer.
Definition: cs_sles_pc.cpp:878
void() cs_sles_pc_log_t(const void *context, cs_log_t log_type)
Function pointer for logging of preconditioner history and performance data.
Definition: cs_sles_pc.h:178
void() cs_sles_pc_setup_t(void *context, const char *name, const cs_matrix_t *a, bool accel, int verbosity)
Function pointer for pre-resolution setup of a preconditioner context.
Definition: cs_sles_pc.h:101
void cs_sles_pc_set_tolerance(cs_sles_pc_t *pc, double precision, double r_norm)
Set the required tolerance for preconditioners involving an iterative solver.
Definition: cs_sles_pc.cpp:927
void cs_sles_pc_destroy(cs_sles_pc_t **pc)
Destroy a sparse linear equation preconditioner.
Definition: cs_sles_pc.cpp:764