8.1
general documentation
cs_iter_algo.h
Go to the documentation of this file.
1 #ifndef __CS_ITER_ALGO_H__
2 #define __CS_ITER_ALGO_H__
3 
4 /*============================================================================
5  * Set of functions to manage high-level iterative algorithms
6  *============================================================================*/
7 
8 /*
9  This file is part of code_saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2023 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  * Local headers
30  *----------------------------------------------------------------------------*/
31 
32 #include "cs_cdo_blas.h"
33 #include "cs_math.h"
34 #include "cs_param_sles.h"
35 #include "cs_param_types.h"
36 #include "cs_sles.h"
37 
38 /*----------------------------------------------------------------------------*/
39 
41 
42 /*============================================================================
43  * Macro definitions
44  *============================================================================*/
45 
46 /*============================================================================
47  * Type definitions
48  *============================================================================*/
49 
50 /* \enum cs_iter_algo_type_bit_t
51  * \brief Bit values for the definition of the type of iterative algorithms
52  *
53  * \var CS_ITER_ALGO_DEFAULT
54  * Iterative algorithms like linear solvers for saddle-point system, fixed
55  * point...
56  *
57  * \var CS_ITER_ALGO_ANDERSON
58  * Iterative algorithms relying on the Anderson acceleration
59  *
60  * \var CS_ITER_ALGO_TWO_LEVEL
61  * Iterative algorithms using an inner/outer iterative loops
62  */
63 
64 typedef enum {
65 
66  CS_ITER_ALGO_DEFAULT = 1 << 0, /* = 1 */
67  CS_ITER_ALGO_ANDERSON = 1 << 1, /* = 2 */
68  CS_ITER_ALGO_TWO_LEVEL = 1 << 2, /* = 4 */
69 
71 
73 
74 /* Structure used as context for the iterative algorithm considered by
75  default */
76 
77 typedef struct {
78 
116  double tol;
117 
118  double prev_res;
119  double res;
120  double res0;
121 
125 
127 
128 /* Structures used when an Anderson acceleration is considered */
129 /* ----------------------------------------------------------- */
130 
137 typedef struct {
138 
160  double max_cond;
161  double beta;
163 
165 
172 typedef struct {
173 
180 
218  double tol;
219 
220  double prev_res;
221  double res;
222  double res0;
223 
227 
260  cs_lnum_t n_elts; /*<! Size of an array for one direction */
261  int n_dir;
262 
267 
269  cs_sdm_t *R;
270 
272 
274 
275 /* ++++++++++++++ */
276 /* Main structure */
277 /* ++++++++++++++ */
278 
289 typedef struct {
290 
310 
311  void *context;
312 
314 
315 /*============================================================================
316  * Public function prototypes
317  *============================================================================*/
318 
319 /*----------------------------------------------------------------------------*/
327 /*----------------------------------------------------------------------------*/
328 
331 
332 /*----------------------------------------------------------------------------*/
343 /*----------------------------------------------------------------------------*/
344 
347  int verbosity,
348  cs_param_sles_cvg_t cvg_param);
349 
350 /*----------------------------------------------------------------------------*/
356 /*----------------------------------------------------------------------------*/
357 
358 void
360 
361 /*----------------------------------------------------------------------------*/
367 /*----------------------------------------------------------------------------*/
368 
369 void
371 
372 /*----------------------------------------------------------------------------*/
378 /*----------------------------------------------------------------------------*/
379 
380 void
382 
383 /*----------------------------------------------------------------------------*/
390 /*----------------------------------------------------------------------------*/
391 
392 void
394  int verbosity);
395 
396 /*----------------------------------------------------------------------------*/
405 /*----------------------------------------------------------------------------*/
406 
407 void
409  cs_param_sles_cvg_t cvg_param);
410 
411 /*----------------------------------------------------------------------------*/
419 /*----------------------------------------------------------------------------*/
420 
421 void
423  double tol);
424 
425 /*----------------------------------------------------------------------------*/
432 /*----------------------------------------------------------------------------*/
433 
434 void
436  double value);
437 
438 /*----------------------------------------------------------------------------*/
446 /*----------------------------------------------------------------------------*/
447 
448 void
450  double value);
451 
452 /*----------------------------------------------------------------------------*/
459 /*----------------------------------------------------------------------------*/
460 
461 void
463  cs_sles_convergence_state_t cvg_status);
464 
465 /*----------------------------------------------------------------------------*/
473 /*----------------------------------------------------------------------------*/
474 
475 void
477  cs_iter_algo_param_aac_t aac_param,
478  cs_lnum_t n_elts);
479 
480 /*----------------------------------------------------------------------------*/
488 /*----------------------------------------------------------------------------*/
489 
490 int
492 
493 /*----------------------------------------------------------------------------*/
501 /*----------------------------------------------------------------------------*/
502 
503 int
505 
506 /*----------------------------------------------------------------------------*/
514 /*----------------------------------------------------------------------------*/
515 
516 double
518 
519 /*----------------------------------------------------------------------------*/
527 /*----------------------------------------------------------------------------*/
528 
531 
532 /*----------------------------------------------------------------------------*/
538 /*----------------------------------------------------------------------------*/
539 
540 double
542 
543 /*----------------------------------------------------------------------------*/
551 /*----------------------------------------------------------------------------*/
552 
555 
556 /*----------------------------------------------------------------------------*/
566 /*----------------------------------------------------------------------------*/
567 
568 void
570  cs_real_t *cur_iterate,
571  const cs_real_t *pre_iterate,
572  cs_cdo_blas_dotprod_t *dotprod,
573  cs_cdo_blas_square_norm_t *sqnorm);
574 
575 /*----------------------------------------------------------------------------*/
582 /*----------------------------------------------------------------------------*/
583 
584 void
586  int n_last_inner_iter);
587 
588 /*----------------------------------------------------------------------------*/
595 /*----------------------------------------------------------------------------*/
596 
597 void
599  double res);
600 
601 /*----------------------------------------------------------------------------*/
612 /*----------------------------------------------------------------------------*/
613 
616  double tol);
617 
618 /*----------------------------------------------------------------------------*/
629 /*----------------------------------------------------------------------------*/
630 
633 
634 /*----------------------------------------------------------------------------*/
641 /*----------------------------------------------------------------------------*/
642 
643 void
645  const char *label);
646 
647 /*----------------------------------------------------------------------------*/
657 /*----------------------------------------------------------------------------*/
658 
659 void
660 cs_iter_algo_check_warning(const char *func_name,
661  const char *eq_name,
662  const char *algo_name,
663  cs_iter_algo_t *algo);
664 
665 /*----------------------------------------------------------------------------*/
666 
668 
669 #endif /* __CS_ITER_ALGO_H__ */
cs_real_t() cs_cdo_blas_square_norm_t(const cs_real_t *array)
Generic function pointer for computing a square norm. Parallel synchronization is performed.
Definition: cs_cdo_blas.h:79
cs_real_t() cs_cdo_blas_dotprod_t(const cs_real_t *a, const cs_real_t *b)
Generic function pointer for computing a dot product. Parallel synchronization is performed.
Definition: cs_cdo_blas.h:64
#define BEGIN_C_DECLS
Definition: cs_defs.h:514
double cs_real_t
Floating-point value.
Definition: cs_defs.h:319
#define END_C_DECLS
Definition: cs_defs.h:515
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:313
unsigned short int cs_flag_t
Definition: cs_defs.h:321
cs_iter_algo_t * cs_iter_algo_create(cs_iter_algo_type_t type)
Create and initialize by default a new cs_iter_algo_t structure.
Definition: cs_iter_algo.c:404
void cs_iter_algo_reset(cs_iter_algo_t *algo)
Reset a cs_iter_algo_t structure.
Definition: cs_iter_algo.c:546
void cs_iter_algo_check_warning(const char *func_name, const char *eq_name, const char *algo_name, cs_iter_algo_t *algo)
Check if something wrong happens during the iterative process after one new iteration.
Definition: cs_iter_algo.c:1472
void cs_iter_algo_set_tolerance(cs_iter_algo_t *algo, double tol)
Set the final tolerance used to check the convergence of the algorithm This tolerance should take int...
Definition: cs_iter_algo.c:643
void cs_iter_algo_log_cvg(cs_iter_algo_t *algo, const char *label)
Log the convergence of the iterative algorithm.
Definition: cs_iter_algo.c:1387
void cs_iter_algo_release_anderson_arrays(cs_iter_algo_aac_t *c)
Reset a cs_iter_algo_t structure.
Definition: cs_iter_algo.c:574
cs_iter_algo_param_aac_t cs_iter_algo_get_anderson_param(cs_iter_algo_t *algo)
Retrieve the set of parameters for an Anderson algorithm.
Definition: cs_iter_algo.c:960
void cs_iter_algo_set_initial_residual(cs_iter_algo_t *algo, double value)
Set the initial residual used to detect a divergence.
Definition: cs_iter_algo.c:673
cs_sles_convergence_state_t cs_iter_algo_get_cvg_status(const cs_iter_algo_t *algo)
Retrieve the last convergence state.
Definition: cs_iter_algo.c:898
cs_iter_algo_type_bit_t
Definition: cs_iter_algo.h:64
@ CS_ITER_ALGO_DEFAULT
Definition: cs_iter_algo.h:66
@ CS_ITER_ALGO_ANDERSON
Definition: cs_iter_algo.h:67
@ CS_ITER_ALGO_TWO_LEVEL
Definition: cs_iter_algo.h:68
cs_sles_convergence_state_t cs_iter_algo_update_cvg_tol_auto(cs_iter_algo_t *algo)
Update the convergence status and the number of iterations. The tolerance threshold is automatically ...
Definition: cs_iter_algo.c:1366
void cs_iter_algo_set_cvg_status(cs_iter_algo_t *algo, cs_sles_convergence_state_t cvg_status)
Set the convergence status of the given structure.
Definition: cs_iter_algo.c:734
int cs_iter_algo_get_n_iter(const cs_iter_algo_t *algo)
Retrieve the current number of iterations done.
Definition: cs_iter_algo.c:798
void cs_iter_algo_set_verbosity(cs_iter_algo_t *algo, int verbosity)
Define the verbosity of the given iterative algorithm.
Definition: cs_iter_algo.c:599
void cs_iter_algo_update_inner_iters(cs_iter_algo_t *algo, int n_last_inner_iter)
Update the counting of inner iterations in two-level algorithms.
Definition: cs_iter_algo.c:1208
cs_iter_algo_t * cs_iter_algo_create_with_settings(cs_iter_algo_type_t type, int verbosity, cs_param_sles_cvg_t cvg_param)
Create a new cs_iter_algo_t structure with the given settings.
Definition: cs_iter_algo.c:483
void cs_iter_algo_update_residual(cs_iter_algo_t *algo, double res)
Update the value of the residual and its associated members.
Definition: cs_iter_algo.c:1244
void cs_iter_algo_set_normalization(cs_iter_algo_t *algo, double value)
Set the normalization to apply when checking the convergence of the algorithm.
Definition: cs_iter_algo.c:704
void cs_iter_algo_free(cs_iter_algo_t **p_algo)
Free a cs_iter_algo_t structure.
Definition: cs_iter_algo.c:507
void cs_iter_algo_update_anderson(cs_iter_algo_t *algo, cs_real_t *cur_iterate, const cs_real_t *pre_iterate, cs_cdo_blas_dotprod_t *dotprod, cs_cdo_blas_square_norm_t *sqnorm)
Apply one more iteration of the Anderson acceleration.
Definition: cs_iter_algo.c:987
double cs_iter_algo_get_normalization(const cs_iter_algo_t *algo)
Get the normalization to apply when computing the tolerance threshold.
Definition: cs_iter_algo.c:928
double cs_iter_algo_get_residual(const cs_iter_algo_t *algo)
Retrieve the last computed residual.
Definition: cs_iter_algo.c:866
void cs_iter_algo_set_cvg_param(cs_iter_algo_t *algo, cs_param_sles_cvg_t cvg_param)
Define the criteria related the convergence of the given iterative algorithm.
Definition: cs_iter_algo.c:620
void cs_iter_algo_set_anderson_param(cs_iter_algo_t *algo, cs_iter_algo_param_aac_t aac_param, cs_lnum_t n_elts)
Create a new cs_iter_algo_aac_t structure for Anderson acceleration.
Definition: cs_iter_algo.c:765
cs_sles_convergence_state_t cs_iter_algo_update_cvg_tol_given(cs_iter_algo_t *algo, double tol)
Update the convergence status and the number of iterations. The tolerance threshold is given so that ...
Definition: cs_iter_algo.c:1291
cs_flag_t cs_iter_algo_type_t
Definition: cs_iter_algo.h:72
int cs_iter_algo_get_n_inner_iter(const cs_iter_algo_t *algo)
Retrieve the cumulated number of inner iterations done.
Definition: cs_iter_algo.c:830
Structure and routines handling the SLES settings stored inside a cs_param_sles_t structure.
cs_param_dotprod_type_t
Definition: cs_param_types.h:1040
cs_sles_convergence_state_t
Definition: cs_sles.h:56
char * label
Definition: keywords.h:58
Context structure for the algorithm called Anderson acceleration.
Definition: cs_iter_algo.h:172
int n_inner_iter
Definition: cs_iter_algo.h:225
cs_real_t * gold
Definition: cs_iter_algo.h:265
double prev_res
Definition: cs_iter_algo.h:220
double tol
Definition: cs_iter_algo.h:218
double res0
Definition: cs_iter_algo.h:222
cs_real_t * dg
Definition: cs_iter_algo.h:266
cs_iter_algo_param_aac_t param
Definition: cs_iter_algo.h:179
cs_real_t * fold
Definition: cs_iter_algo.h:263
cs_real_t * Q
Definition: cs_iter_algo.h:268
cs_lnum_t n_elts
Definition: cs_iter_algo.h:260
cs_sles_convergence_state_t cvg_status
Definition: cs_iter_algo.h:216
cs_real_t * gamma
Definition: cs_iter_algo.h:271
int n_dir
Definition: cs_iter_algo.h:261
double res
Definition: cs_iter_algo.h:221
cs_real_t * df
Definition: cs_iter_algo.h:264
int last_inner_iter
Definition: cs_iter_algo.h:226
cs_sdm_t * R
Definition: cs_iter_algo.h:269
double normalization
Definition: cs_iter_algo.h:217
int n_algo_iter
Definition: cs_iter_algo.h:224
Definition: cs_iter_algo.h:77
int n_inner_iter
Definition: cs_iter_algo.h:123
double prev_res
Definition: cs_iter_algo.h:118
double tol
Definition: cs_iter_algo.h:116
double res0
Definition: cs_iter_algo.h:120
cs_sles_convergence_state_t cvg_status
Definition: cs_iter_algo.h:114
double res
Definition: cs_iter_algo.h:119
int last_inner_iter
Definition: cs_iter_algo.h:124
double normalization
Definition: cs_iter_algo.h:115
int n_algo_iter
Definition: cs_iter_algo.h:122
Structure storing all the parameters to drive the algorithm called Anderson acceleration.
Definition: cs_iter_algo.h:137
cs_param_dotprod_type_t dp_type
Definition: cs_iter_algo.h:162
int n_max_dir
Definition: cs_iter_algo.h:158
double max_cond
Definition: cs_iter_algo.h:160
int starting_iter
Definition: cs_iter_algo.h:159
double beta
Definition: cs_iter_algo.h:161
Structure to handle the convergence of an iterative algorithm.
Definition: cs_iter_algo.h:289
cs_param_sles_cvg_t cvg_param
Definition: cs_iter_algo.h:308
void * context
Definition: cs_iter_algo.h:311
cs_iter_algo_type_t type
Definition: cs_iter_algo.h:307
int verbosity
Definition: cs_iter_algo.h:309
Set of parameters to check the convergence (or the divergence) of an iterative process (tolerances or...
Definition: cs_param_sles.h:61