cs_iter_algo.h

Go to the documentation of this file.

#ifndef __CS_ITER_ALGO_H__
#define __CS_ITER_ALGO_H__
 
/*============================================================================
 * Set of functions to manage high-level iterative algorithms
 *============================================================================*/
 
/*
  This file is part of code_saturne, a general-purpose CFD tool.
 
  Copyright (C) 1998-2024 EDF S.A.
 
  This program is free software; you can redistribute it and/or modify it under
  the terms of the GNU General Public License as published by the Free Software
  Foundation; either version 2 of the License, or (at your option) any later
  version.
 
  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  details.
 
  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
  Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
 
/*----------------------------------------------------------------------------
 *  Local headers
 *----------------------------------------------------------------------------*/
 
#include "cs_cdo_blas.h"
#include "cs_math.h"
#include "cs_param_sles.h"
#include "cs_param_types.h"
#include "cs_sles.h"
 
/*----------------------------------------------------------------------------*/
 
BEGIN_C_DECLS
 
/*============================================================================
 * Macro definitions
 *============================================================================*/
 
/*============================================================================
 * Type definitions
 *============================================================================*/
 
/* \enum cs_iter_algo_type_bit_t
 * \brief Bit values for the definition of the type of iterative algorithms
 *
 * \var CS_ITER_ALGO_DEFAULT
 * Iterative algorithms like linear solvers for saddle-point system, fixed
 * point...
 *
 * \var CS_ITER_ALGO_ANDERSON
 * Iterative algorithms relying on the Anderson acceleration
 *
 * \var CS_ITER_ALGO_TWO_LEVEL
 * Iterative algorithms using an inner/outer iterative loops
 */
 
typedef enum {
 
  CS_ITER_ALGO_DEFAULT             = 1 << 0, /* =  1 */
  CS_ITER_ALGO_ANDERSON            = 1 << 1, /* =  2 */
  CS_ITER_ALGO_TWO_LEVEL           = 1 << 2, /* =  4 */
 
} cs_iter_algo_type_bit_t;
 
typedef cs_flag_t  cs_iter_algo_type_t;
 
/* Structure used as context for the iterative algorithm considered by
   default */
 
typedef struct {
 
  cs_sles_convergence_state_t      cvg_status;
  double                           normalization;
  double                           tol;
 
  double                           prev_res;
  double                           res;
  double                           res0;
 
  int                              n_algo_iter;
  int                              n_inner_iter;
  int                              last_inner_iter;
 
} cs_iter_algo_default_t;
 
/* Structures used when an Anderson acceleration is considered */
/* ----------------------------------------------------------- */
 
typedef struct {
 
  int                        n_max_dir;
  int                        starting_iter;
  double                     max_cond;
  double                     beta;
  cs_param_dotprod_type_t    dp_type;
 
} cs_iter_algo_param_aac_t;
 
typedef struct {
 
  cs_iter_algo_param_aac_t        param;
 
  cs_sles_convergence_state_t    cvg_status;
  double                         normalization;
  double                         tol;
 
  double                         prev_res;
  double                         res;
  double                         res0;
 
  int                            n_algo_iter;
  int                            n_inner_iter;
  int                            last_inner_iter;
 
  cs_lnum_t       n_elts; /*<! Size of an array for one direction */
  int             n_dir;
 
  cs_real_t      *fold;
  cs_real_t      *df;
  cs_real_t      *gold;
  cs_real_t      *dg;
 
  cs_real_t      *Q;
  cs_sdm_t       *R;
 
  cs_real_t      *gamma;
 
} cs_iter_algo_aac_t;
 
/* ++++++++++++++ */
/* Main structure */
/* ++++++++++++++ */
 
typedef struct {
 
  cs_iter_algo_type_t              type;
  cs_param_convergence_t           cvg_param;
  int                              verbosity;
 
  void                            *context;
 
} cs_iter_algo_t;
 
/*============================================================================
 * Public function prototypes
 *============================================================================*/
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_iter_algo_t *
cs_iter_algo_create(cs_iter_algo_type_t    type);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_iter_algo_t *
cs_iter_algo_create_with_settings(cs_iter_algo_type_t     type,
                                  int                     verbosity,
                                  cs_param_convergence_t  cvg_param);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_free(cs_iter_algo_t   **p_algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_reset(cs_iter_algo_t      *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_release_anderson_arrays(cs_iter_algo_aac_t      *c);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_set_verbosity(cs_iter_algo_t     *algo,
                           int                 verbosity);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_set_cvg_param(cs_iter_algo_t         *algo,
                           cs_param_convergence_t  cvg_param);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_set_tolerance(cs_iter_algo_t   *algo,
                           double            tol);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_set_initial_residual(cs_iter_algo_t   *algo,
                                  double            value);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_set_normalization(cs_iter_algo_t   *algo,
                               double            value);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_set_cvg_status(cs_iter_algo_t                  *algo,
                            cs_sles_convergence_state_t      cvg_status);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
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);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
int
cs_iter_algo_get_n_iter(const cs_iter_algo_t        *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
int
cs_iter_algo_get_n_inner_iter(const cs_iter_algo_t        *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
double
cs_iter_algo_get_residual(const cs_iter_algo_t        *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_sles_convergence_state_t
cs_iter_algo_get_cvg_status(const cs_iter_algo_t        *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
double
cs_iter_algo_get_normalization(const cs_iter_algo_t    *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_iter_algo_param_aac_t
cs_iter_algo_get_anderson_param(cs_iter_algo_t         *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
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);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_update_inner_iters(cs_iter_algo_t   *algo,
                                int               n_last_inner_iter);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_update_residual(cs_iter_algo_t      *algo,
                             double               res);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_sles_convergence_state_t
cs_iter_algo_update_cvg_tol_given(cs_iter_algo_t         *algo,
                                  double                  tol);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
cs_sles_convergence_state_t
cs_iter_algo_update_cvg_tol_auto(cs_iter_algo_t         *algo);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_log_cvg(cs_iter_algo_t      *algo,
                     const char          *label);
 
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
 
void
cs_iter_algo_check_warning(const char            *func_name,
                           const char            *eq_name,
                           const char            *algo_name,
                           cs_iter_algo_t        *algo);
 
/*----------------------------------------------------------------------------*/
 
END_C_DECLS
 
#endif /* __CS_ITER_ALGO_H__ */