My Project
programmer's 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-2019 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 
41 BEGIN_C_DECLS
42 
43 /*============================================================================
44  * Macro definitions
45  *============================================================================*/
46 
47 /*============================================================================
48  * Type definitions
49  *============================================================================*/
50 
51 /*----------------------------------------------------------------------------
52  * Convergence status
53  *----------------------------------------------------------------------------*/
54 
55 typedef enum {
56 
57  CS_SLES_PC_DIVERGED = -2,
58  CS_SLES_PC_BREAKDOWN = -1,
59  CS_SLES_PC_MAX_ITERATION = 0,
60  CS_SLES_PC_CONVERGED = 1
61 
62 } cs_sles_pc_state_t;
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  * rotation_mode <-- halo update option for rotational periodicity
136  * x_in <-- input vector
137  * x_out <-> input/output vector
138  *
139  * returns:
140  * preconditioner application status
141  *----------------------------------------------------------------------------*/
142 
143 typedef cs_sles_pc_state_t
144 (cs_sles_pc_apply_t) (void *context,
145  cs_halo_rotation_t rotation_mode,
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 
162 typedef 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 
177 typedef 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 
199 typedef 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 
211 typedef 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 
240 void
241 cs_sles_pc_log(cs_sles_pc_t *pc,
242  cs_log_t log_type);
243 
244 /*----------------------------------------------------------------------------*/
269 /*----------------------------------------------------------------------------*/
270 
271 cs_sles_pc_t *
272 cs_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 
291 void
292 cs_sles_pc_destroy(cs_sles_pc_t **pc);
293 
294 /*----------------------------------------------------------------------------*/
308 /*----------------------------------------------------------------------------*/
309 
310 cs_sles_pc_t *
311 cs_sles_pc_clone(const cs_sles_pc_t *src);
312 
313 /*----------------------------------------------------------------------------*/
326 /*----------------------------------------------------------------------------*/
327 
328 const char *
329 cs_sles_pc_get_type(cs_sles_pc_t *pc);
330 
331 /*----------------------------------------------------------------------------*/
339 /*----------------------------------------------------------------------------*/
340 
341 const char *
342 cs_sles_pc_get_type_name(cs_sles_pc_t *pc);
343 
344 /*----------------------------------------------------------------------------*/
356 /*----------------------------------------------------------------------------*/
357 
358 void *
359 cs_sles_pc_get_context(cs_sles_pc_t *pc);
360 
361 /*----------------------------------------------------------------------------*/
371 /*----------------------------------------------------------------------------*/
372 
373 cs_sles_pc_apply_t *
374 cs_sles_pc_get_apply_func(const cs_sles_pc_t *pc);
375 
376 /*----------------------------------------------------------------------------*/
394 /*----------------------------------------------------------------------------*/
395 
396 void
397 cs_sles_pc_set_tolerance(cs_sles_pc_t *pc,
398  double precision,
399  double r_norm);
400 
401 /*----------------------------------------------------------------------------*/
417 /*----------------------------------------------------------------------------*/
418 
419 void
420 cs_sles_pc_setup(cs_sles_pc_t *pc,
421  const char *name,
422  const cs_matrix_t *a,
423  int verbosity);
424 
425 /*----------------------------------------------------------------------------*/
443 /*----------------------------------------------------------------------------*/
444 
445 cs_sles_pc_state_t
446 cs_sles_pc_apply(cs_sles_pc_t *pc,
447  cs_halo_rotation_t rotation_mode,
448  cs_real_t *x_in,
449  cs_real_t *x_out);
450 
451 /*----------------------------------------------------------------------------*/
462 /*----------------------------------------------------------------------------*/
463 
464 void
465 cs_sles_pc_free(cs_sles_pc_t *pc);
466 
467 /*----------------------------------------------------------------------------*/
473 /*----------------------------------------------------------------------------*/
474 
475 cs_sles_pc_t *
476 cs_sles_pc_none_create(void);
477 
478 /*----------------------------------------------------------------------------*/
484 /*----------------------------------------------------------------------------*/
485 
486 cs_sles_pc_t *
487 cs_sles_pc_jacobi_create(void);
488 
489 /*----------------------------------------------------------------------------*/
495 /*----------------------------------------------------------------------------*/
496 
497 cs_sles_pc_t *
498 cs_sles_pc_poly_1_create(void);
499 
500 /*----------------------------------------------------------------------------*/
506 /*----------------------------------------------------------------------------*/
507 
508 cs_sles_pc_t *
509 cs_sles_pc_poly_2_create(void);
510 
511 /*----------------------------------------------------------------------------*/
512 
513 END_C_DECLS
514 
515 #endif /* __CS_SLES_PC_H__ */
cs_sles_pc_apply
cs_sles_pc_state_t cs_sles_pc_apply(cs_sles_pc_t *pc, cs_halo_rotation_t rotation_mode, cs_real_t *x_in, cs_real_t *x_out)
Apply a preconditioner.
Definition: cs_sles_pc.c:962
cs_sles_pc_get_context
void * cs_sles_pc_get_context(cs_sles_pc_t *pc)
Return pointer to preconditioner context structure pointer.
Definition: cs_sles_pc.c:850
cs_fuel_incl::a
double precision, save a
Definition: cs_fuel_incl.f90:146
cs_sles_pc_poly_2_create
cs_sles_pc_t * cs_sles_pc_poly_2_create(void)
Create a polynomial preconditioner of degree 2.
Definition: cs_sles_pc.c:1107
cs_log.h
cs_sles_pc_t
struct _cs_sles_pc_t cs_sles_pc_t
Definition: cs_sles_pc.h:66
cs_sles_pc_setup
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:929
cs_sles_pc_define
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:698
END_C_DECLS
#define END_C_DECLS
Definition: cs_defs.h:468
cs_sles_pc_apply_t
cs_sles_pc_state_t() cs_sles_pc_apply_t(void *context, cs_halo_rotation_t rotation_mode, const cs_real_t *x_in, cs_real_t *x_out)
Function pointer for application of a preconditioner.
Definition: cs_sles_pc.h:144
cs_sles_pc_free_t
void() cs_sles_pc_free_t(void *context)
Function pointer for freeing of a preconditioner's context data.
Definition: cs_sles_pc.h:163
cs_real_t
double cs_real_t
Floating-point value.
Definition: cs_defs.h:302
cs_sles_pc_log
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:1007
cs_sles_pc_clone
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:764
BEGIN_C_DECLS
#define BEGIN_C_DECLS
Definition: cs_defs.h:467
cs_matrix_t
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:90
cs_sles_pc_setup_t
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
cs_sles_pc_set_tolerance
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:899
cs_sles_pc_none_create
cs_sles_pc_t * cs_sles_pc_none_create(void)
Create an "identity" (or null) preconditioner.
Definition: cs_sles_pc.c:1023
CS_SLES_PC_MAX_ITERATION
Definition: cs_sles_pc.h:59
cs_sles_pc_state_t
cs_sles_pc_state_t
Convergence status indicator.
Definition: cs_sles_pc.h:55
CS_SLES_PC_CONVERGED
Definition: cs_sles_pc.h:60
cs_sles_pc_destroy
void cs_sles_pc_destroy(cs_sles_pc_t **pc)
Destroy a sparse linear equation preconditioner.
Definition: cs_sles_pc.c:736
CS_SLES_PC_DIVERGED
Definition: cs_sles_pc.h:57
cs_sles_pc_get_type_t
const typedef char *() cs_sles_pc_get_type_t(const void *context, bool logging)
cs_sles_pc_get_apply_func
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:873
cs_halo_perio.h
CS_SLES_PC_BREAKDOWN
Definition: cs_sles_pc.h:58
cs_log_t
cs_log_t
Definition: cs_log.h:48
cs_sles_pc_get_type
const char * cs_sles_pc_get_type(cs_sles_pc_t *pc)
Return type name of preconditioner context.
Definition: cs_sles_pc.c:804
cs_sles_pc_get_type_name
const char * cs_sles_pc_get_type_name(cs_sles_pc_t *pc)
Return type name of preconditioner context.
Definition: cs_sles_pc.c:825
cs_sles_pc_free
void cs_sles_pc_free(cs_sles_pc_t *pc)
Free preconditioner setup.
Definition: cs_sles_pc.c:984
cs_sles_pc_tolerance_t
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
cs_sles_pc_log_t
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
cs_matrix.h
cs_sles_pc_clone_t
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_destroy_t
void() cs_sles_pc_destroy_t(void **context)
Definition: cs_sles_pc.h:212
cs_halo_rotation_t
cs_halo_rotation_t
Definition: cs_halo.h:60
cs_sles_pc_jacobi_create
cs_sles_pc_t * cs_sles_pc_jacobi_create(void)
Create a Jacobi preconditioner.
Definition: cs_sles_pc.c:1051
cs_base.h
cs_sles_pc_poly_1_create
cs_sles_pc_t * cs_sles_pc_poly_1_create(void)
Create a polynomial preconditioner of degree 1.
Definition: cs_sles_pc.c:1079
Generated on Thu Apr 9 2020 17:26:56 for My Project by   doxygen 1.8.16