cs_sles_hypre.h

Go to the documentation of this file.

#ifndef __CS_SLES_HYPRE_H__
#define __CS_SLES_HYPRE_H__

/*============================================================================
 * Sparse Linear Equation Solvers using HYPRE
 *============================================================================*/

/*
  This file is part of Code_Saturne, a general-purpose CFD tool.

  Copyright (C) 1998-2021 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.
*/

/*----------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------
 * HYPRE headers
 *----------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------
 *  Local headers
 *----------------------------------------------------------------------------*/

#include "cs_base.h"
#include "cs_matrix.h"
#include "cs_sles.h"

/*----------------------------------------------------------------------------*/

BEGIN_C_DECLS

/*============================================================================
 * Macro definitions
 *============================================================================*/

/*============================================================================
 * Type definitions
 *============================================================================*/

/*----------------------------------------------------------------------------
 * Solver and preconditioner types
 *----------------------------------------------------------------------------*/

typedef enum {

  /* Solver or preconditioner */

  CS_SLES_HYPRE_BOOMERAMG,     
  CS_SLES_HYPRE_HYBRID,        
  CS_SLES_HYPRE_ILU,           
  CS_SLES_HYPRE_BICGSTAB,      
  CS_SLES_HYPRE_GMRES,         
  CS_SLES_HYPRE_FLEXGMRES,     
  CS_SLES_HYPRE_LGMRES,        
  CS_SLES_HYPRE_PCG,           
  /* Preconditioner only */

  CS_SLES_HYPRE_EUCLID,        
  CS_SLES_HYPRE_PARASAILS,     
  /* End  of allowable solvers */

  CS_SLES_HYPRE_NONE           
} cs_sles_hypre_type_t;

/*----------------------------------------------------------------------------
 * Function pointer for user settings of a HYPRE solver setup.
 *
 * This function is called during the setup stage for a HYPRE solver.
 *
 * When first called, the solver argument is NULL, and must be created
 * using HYPRE functions.
 *
 * Note: if the context pointer is non-NULL, it must point to valid data
 * when the selection function is called so that value or structure should
 * not be temporary (i.e. local);
 *
 * parameters:
 *   verbosity <-- verbosity level
 *   context   <-> pointer to optional (untyped) value or structure
 *   solver    <-> handle to HYPRE solver (to be cast as HYPRE_Solver)
 *----------------------------------------------------------------------------*/

typedef void
(cs_sles_hypre_setup_hook_t) (int   verbosity,
                              void  *context,
                              void  *solver);

/* HYPRE linear solver context (opaque) */

typedef struct _cs_sles_hypre_t  cs_sles_hypre_t;

/*============================================================================
 *  Global variables
 *============================================================================*/

/*=============================================================================
 * Public function prototypes
 *============================================================================*/

/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/

cs_sles_hypre_t *
cs_sles_hypre_define(int                          f_id,
                     const char                  *name,
                     cs_sles_hypre_type_t         solver_type,
                     cs_sles_hypre_type_t         precond_type,
                     cs_sles_hypre_setup_hook_t  *setup_hook,
                     void                        *context);

/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/

cs_sles_hypre_t *
cs_sles_hypre_create(cs_sles_hypre_type_t         solver_type,
                     cs_sles_hypre_type_t         precond_type,
                     cs_sles_hypre_setup_hook_t  *setup_hook,
                     void                        *context);

/*----------------------------------------------------------------------------
 * Destroy HYPRE linear system solver info and context.
 *
 * parameters:
 *   context  <-> pointer to HYPRE linear solver info
 *                (actual type: cs_sles_hypre_t  **)
 *----------------------------------------------------------------------------*/

void
cs_sles_hypre_destroy(void  **context);

/*----------------------------------------------------------------------------
 * Create HYPRE linear system solver info and context
 * based on existing info and context.
 *
 * parameters:
 *   context <-- pointer to reference info and context
 *               (actual type: cs_sles_hypre_t  *)
 *
 * returns:
 *   pointer to newly created solver info object
 *   (actual type: cs_sles_hypre_t  *)
 *----------------------------------------------------------------------------*/

void *
cs_sles_hypre_copy(const void  *context);

/*----------------------------------------------------------------------------
 * Setup HYPRE linear equation solver.
 *
 * parameters:
 *   context   <-> pointer to HYPRE linear solver info
 *                 (actual type: cs_sles_hypre_t  *)
 *   name      <-- pointer to system name
 *   a         <-- associated matrix
 *   verbosity <-- verbosity level
 *----------------------------------------------------------------------------*/

void
cs_sles_hypre_setup(void               *context,
                    const char         *name,
                    const cs_matrix_t  *a,
                    int                 verbosity);

/*----------------------------------------------------------------------------
 * Call HYPRE linear equation solver.
 *
 * parameters:
 *   context       <-> pointer to HYPRE linear solver info
 *                     (actual type: cs_sles_hypre_t  *)
 *   name          <-- pointer to system name
 *   a             <-- matrix
 *   verbosity     <-- verbosity level
 *   precision     <-- solver precision
 *   r_norm        <-- residue normalization
 *   n_iter        --> number of iterations
 *   residue       --> residue
 *   rhs           <-- right hand side
 *   vx            <-> system solution
 *   aux_size      <-- number of elements in aux_vectors (in bytes)
 *   aux_vectors   --- optional working area (internal allocation if NULL)
 *
 * returns:
 *   convergence state
 *----------------------------------------------------------------------------*/

cs_sles_convergence_state_t
cs_sles_hypre_solve(void                *context,
                    const char          *name,
                    const cs_matrix_t   *a,
                    int                  verbosity,
                    double               precision,
                    double               r_norm,
                    int                 *n_iter,
                    double              *residue,
                    const cs_real_t     *rhs,
                    cs_real_t           *vx,
                    size_t               aux_size,
                    void                *aux_vectors);

/*----------------------------------------------------------------------------
 * Free HYPRE linear equation solver setup context.
 *
 * This function frees resolution-related data, such as
 * buffers and preconditioning but does not free the whole context,
 * as info used for logging (especially performance data) is maintained.

 * parameters:
 *   context <-> pointer to HYPRE linear solver info
 *               (actual type: cs_sles_hypre_t  *)
 *----------------------------------------------------------------------------*/

void
cs_sles_hypre_free(void  *context);

/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/

bool
cs_sles_hypre_error_post_and_abort(cs_sles_t                    *sles,
                                   cs_sles_convergence_state_t   state,
                                   const cs_matrix_t            *a,
                                   const cs_real_t              *rhs,
                                   cs_real_t                    *vx);

/*----------------------------------------------------------------------------
 * Log sparse linear equation solver info.
 *
 * parameters:
 *   context  <-> pointer to HYPRE linear solver info
 *                (actual type: cs_sles_hypre_t  *)
 *   log_type <-- log type
 *----------------------------------------------------------------------------*/

void
cs_sles_hypre_log(const void  *context,
                  cs_log_t     log_type);

/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/

void
cs_sles_hypre_set_host_device(cs_sles_hypre_t   *context,
                              int                use_device);

/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/

int
cs_sles_hypre_get_host_device(const cs_sles_hypre_t   *context);

/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/

void
cs_sles_hypre_library_info(cs_log_t  log_type);

/*----------------------------------------------------------------------------*/

END_C_DECLS

#endif /* __CS_SLES_HYPRE_H__ */