7.1
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-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_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 
55 typedef enum {
56 
61 
63 
64 /* General linear solver context (opaque) */
65 
66 typedef 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 
83 typedef 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  * verbosity <-- associated verbosity
97  *----------------------------------------------------------------------------*/
98 
99 typedef void
100 (cs_sles_pc_setup_t) (void *context,
101  const char *name,
102  const cs_matrix_t *a,
103  int verbosity);
104 
105 /*----------------------------------------------------------------------------
106  * Function pointer for setting of the required tolerance for preconditioners
107  * involving an iterative solver.
108  *
109  * This will usually not be relevant to non-iterative preconditioners,
110  * for which this type of function does not need to be defined.
111  *
112  * The preconditioner is considered to have converged when
113  * residue/r_norm <= precision, residue being the L2 norm of a.vx-rhs.
114  *
115  * parameters:
116  * context <-> pointer to preconditioner context
117  * precision <-- preconditioner precision
118  * r_norm <-- residue normalization
119  *----------------------------------------------------------------------------*/
120 
121 typedef void
122 (cs_sles_pc_tolerance_t) (void *context,
123  double precision,
124  double r_norm);
125 
126 /*----------------------------------------------------------------------------
127  * Function pointer for application of a preconditioner.
128  *
129  * In cases where it is desired that the preconditioner modify a vector
130  * "in place", x_in should be set to NULL, and x_out contain the vector to
131  * be modified (\f$x_{out} \leftarrow M^{-1}x_{out})\f$).
132  *
133  * parameters:
134  * context <-> pointer to preconditioner context
135  * x_in <-- input vector
136  * x_out <-> input/output vector
137  *
138  * returns:
139  * preconditioner application status
140  *----------------------------------------------------------------------------*/
141 
142 typedef cs_sles_pc_state_t
143 (cs_sles_pc_apply_t) (void *context,
144  const cs_real_t *x_in,
145  cs_real_t *x_out);
146 
147 /*----------------------------------------------------------------------------
148  * Function pointer for freeing of a preconditioner's context data.
149  *
150  * Note that this function should free resolution-related data, such as
151  * multigrid hierarchy and any other temporary arrays or
152  * objects required for application, but should not free the whole context,
153  * as info used for logging (especially performance data) should be
154  * maintained.
155  *
156  * parameters:
157  * context <-> pointer to preconditioner context
158  *----------------------------------------------------------------------------*/
159 
160 typedef void
161 (cs_sles_pc_free_t) (void *context);
162 
163 /*----------------------------------------------------------------------------
164  * Function pointer for logging of linear preconditioner setup,
165  * history and performance data.
166  *
167  * This function will indirectly be called for each preconditioner when
168  * cs_sles_finalize() is called.
169  *
170  * parameters:
171  * context <-- pointer to preconditioner context
172  * log_type <-- log type
173  *----------------------------------------------------------------------------*/
174 
175 typedef void
176 (cs_sles_pc_log_t) (const void *context,
177  cs_log_t log_type);
178 
179 /*----------------------------------------------------------------------------
180  * Function pointer for creation of a preconditioner context based on the
181  * copy of another.
182  *
183  * The new context copies the settings of the copied context, but not
184  * its setup data and logged info, such as performance data.
185  *
186  * This type of function is optional, but enables associating different
187  * preconditioners to related systems (to differentiate logging) while using
188  * the same settings by default.
189  *
190  * parameters:
191  * context <-- context to clone
192  *
193  * returns:
194  * pointer to newly created context
195  *----------------------------------------------------------------------------*/
196 
197 typedef void *
198 (cs_sles_pc_clone_t) (const void *context);
199 
200 /*----------------------------------------------------------------------------
201  * Function pointer for destruction of a preconditioner context.
202  *
203  * This function should free all context data.
204  *
205  * parameters:
206  * context <-> pointer to preconditioner context
207  *----------------------------------------------------------------------------*/
208 
209 typedef void
210 (cs_sles_pc_destroy_t) (void **context);
211 
212 /*============================================================================
213  * Global variables
214  *============================================================================*/
215 
216 /*=============================================================================
217  * Public function prototypes for Fortran API
218  *============================================================================*/
219 
220 /*=============================================================================
221  * Public function prototypes
222  *============================================================================*/
223 
224 /*----------------------------------------------------------------------------*/
236 /*----------------------------------------------------------------------------*/
237 
238 void
240  cs_log_t log_type);
241 
242 /*----------------------------------------------------------------------------*/
267 /*----------------------------------------------------------------------------*/
268 
269 cs_sles_pc_t *
270 cs_sles_pc_define(void *context,
271  cs_sles_pc_get_type_t *get_type_func,
272  cs_sles_pc_setup_t *setup_func,
273  cs_sles_pc_tolerance_t *tolerance_func,
274  cs_sles_pc_apply_t *apply_func,
275  cs_sles_pc_free_t *free_func,
276  cs_sles_pc_log_t *log_func,
277  cs_sles_pc_clone_t *clone_func,
278  cs_sles_pc_destroy_t *destroy_func);
279 
280 /*----------------------------------------------------------------------------*/
287 /*----------------------------------------------------------------------------*/
288 
289 void
291 
292 /*----------------------------------------------------------------------------*/
306 /*----------------------------------------------------------------------------*/
307 
308 cs_sles_pc_t *
309 cs_sles_pc_clone(const cs_sles_pc_t *src);
310 
311 /*----------------------------------------------------------------------------*/
324 /*----------------------------------------------------------------------------*/
325 
326 const char *
328 
329 /*----------------------------------------------------------------------------*/
337 /*----------------------------------------------------------------------------*/
338 
339 const char *
341 
342 /*----------------------------------------------------------------------------*/
354 /*----------------------------------------------------------------------------*/
355 
356 void *
358 
359 /*----------------------------------------------------------------------------*/
369 /*----------------------------------------------------------------------------*/
370 
373 
374 /*----------------------------------------------------------------------------*/
392 /*----------------------------------------------------------------------------*/
393 
394 void
396  double precision,
397  double r_norm);
398 
399 /*----------------------------------------------------------------------------*/
415 /*----------------------------------------------------------------------------*/
416 
417 void
419  const char *name,
420  const cs_matrix_t *a,
421  int verbosity);
422 
423 /*----------------------------------------------------------------------------*/
440 /*----------------------------------------------------------------------------*/
441 
444  cs_real_t *x_in,
445  cs_real_t *x_out);
446 
447 /*----------------------------------------------------------------------------*/
458 /*----------------------------------------------------------------------------*/
459 
460 void
462 
463 /*----------------------------------------------------------------------------*/
469 /*----------------------------------------------------------------------------*/
470 
471 cs_sles_pc_t *
473 
474 /*----------------------------------------------------------------------------*/
480 /*----------------------------------------------------------------------------*/
481 
482 cs_sles_pc_t *
484 
485 /*----------------------------------------------------------------------------*/
491 /*----------------------------------------------------------------------------*/
492 
493 cs_sles_pc_t *
495 
496 /*----------------------------------------------------------------------------*/
502 /*----------------------------------------------------------------------------*/
503 
504 cs_sles_pc_t *
506 
507 /*----------------------------------------------------------------------------*/
508 
510 
511 #endif /* __CS_SLES_PC_H__ */
cs_sles_pc_t * cs_sles_pc_poly_1_create(void)
Create a polynomial preconditioner of degree 1.
Definition: cs_sles_pc.c:1066
void() cs_sles_pc_free_t(void *context)
Function pointer for freeing of a preconditioner&#39;s context data.
Definition: cs_sles_pc.h:161
cs_sles_pc_state_t
Convergence status indicator.
Definition: cs_sles_pc.h:55
cs_sles_pc_t * cs_sles_pc_poly_2_create(void)
Create a polynomial preconditioner of degree 2.
Definition: cs_sles_pc.c:1094
const char * cs_sles_pc_get_type(cs_sles_pc_t *pc)
Return type name of preconditioner context.
Definition: cs_sles_pc.c:793
void cs_sles_pc_destroy(cs_sles_pc_t **pc)
Destroy a sparse linear equation preconditioner.
Definition: cs_sles_pc.c:725
Definition: cs_sles_pc.h:60
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.c:687
#define BEGIN_C_DECLS
Definition: cs_defs.h:510
void() cs_sles_pc_setup_t(void *context, const char *name, const cs_matrix_t *a, int verbosity)
Function pointer for pre-resolution setup of a preconditioner context.
Definition: cs_sles_pc.h:100
void cs_sles_pc_setup(cs_sles_pc_t *pc, const char *name, const cs_matrix_t *a, int verbosity)
Setup sparse linear equation preconditioner.
Definition: cs_sles_pc.c:918
struct _cs_sles_pc_t cs_sles_pc_t
Definition: cs_sles_pc.h:66
Definition: cs_sles_pc.h:58
cs_sles_pc_t * cs_sles_pc_none_create(void)
Create an "identity" (or null) preconditioner.
Definition: cs_sles_pc.c:1010
double cs_real_t
Floating-point value.
Definition: cs_defs.h:322
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:143
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:93
void * cs_sles_pc_get_context(cs_sles_pc_t *pc)
Return pointer to preconditioner context structure pointer.
Definition: cs_sles_pc.c:839
double precision, save a
Definition: cs_fuel_incl.f90:146
cs_sles_pc_t * cs_sles_pc_jacobi_create(void)
Create a Jacobi preconditioner.
Definition: cs_sles_pc.c:1038
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:198
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.c:950
cs_log_t
Definition: cs_log.h:48
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.c:888
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.c:862
void cs_sles_pc_free(cs_sles_pc_t *pc)
Free preconditioner setup.
Definition: cs_sles_pc.c:971
void() cs_sles_pc_destroy_t(void **context)
Definition: cs_sles_pc.h:210
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:176
#define END_C_DECLS
Definition: cs_defs.h:511
Definition: cs_sles_pc.h:59
Definition: cs_sles_pc.h:57
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:122
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.c:994
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.c:753
const char * cs_sles_pc_get_type_name(cs_sles_pc_t *pc)
Return type name of preconditioner context.
Definition: cs_sles_pc.c:814