programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_sles.h
Go to the documentation of this file.
1 #ifndef __CS_SLES_H__
2 #define __CS_SLES_H__
3 
4 /*============================================================================
5  * Sparse Linear Equation Solvers
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2014 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_halo_perio.h"
36 #include "cs_matrix.h"
37 
38 /*----------------------------------------------------------------------------*/
39 
41 
42 /*============================================================================
43  * Macro definitions
44  *============================================================================*/
45 
46 /*============================================================================
47  * Type definitions
48  *============================================================================*/
49 
50 /*----------------------------------------------------------------------------
51  * Solver types
52  *----------------------------------------------------------------------------*/
53 
54 typedef enum {
55 
56  CS_SLES_PCG, /* Preconditionned conjugate gradient */
57  CS_SLES_PCG_SR, /* Preconditionned conjugate gradient, single reduction*/
58  CS_SLES_JACOBI, /* Jacobi */
59  CS_SLES_BICGSTAB, /* Bi-conjugate gradient stabilized */
60  CS_SLES_GMRES, /* Generalized minimal residual */
61  CS_SLES_N_TYPES /* Number of resolution algorithms */
62 
64 
65 /*============================================================================
66  * Global variables
67  *============================================================================*/
68 
69 /* Short names for matrix types */
70 
71 extern const char *cs_sles_type_name[];
72 
73 /*=============================================================================
74  * Public function prototypes for Fortran API
75  *============================================================================*/
76 
77 /*----------------------------------------------------------------------------
78  * General sparse linear system resolution
79  *----------------------------------------------------------------------------*/
80 
81 void CS_PROCF(reslin, RESLIN)
82 (
83  const char *cname, /* <-- variable name */
84  const cs_int_t *lname, /* <-- variable name length */
85  const cs_int_t *ncelet, /* <-- Number of cells, halo included */
86  const cs_int_t *ncel, /* <-- Number of local cells */
87  const cs_int_t *nfac, /* <-- Number of faces */
88  const cs_int_t *isym, /* <-- Symmetry indicator:
89  1: symmetric; 2: not symmetric */
90  const cs_int_t *ibsize, /* <-- Block size of element ii,ii */
91  const cs_int_t *iesize, /* <-- Block size of element ij */
92  const cs_int_t *ireslp, /* <-- Resolution type:
93  0: pcg; 1: Jacobi; 2: cg-stab, 3: gmres,
94  200: pcg_sr */
95  const cs_int_t *ipol, /* <-- Preconditioning polynomial degree
96  (0: diagonal; -1: non-preconditionned) */
97  const cs_int_t *nitmap, /* <-- Number of max iterations */
98  const cs_int_t *iinvpe, /* <-- Indicator to cancel increments
99  in rotational periodicty (2) or
100  to exchange them as scalars (1) */
101  const cs_int_t *iwarnp, /* <-- Verbosity level */
102  cs_int_t *niterf, /* --> Number of iterations done */
103  const cs_real_t *epsilp, /* <-- Precision for iterative resolution */
104  const cs_real_t *rnorm, /* <-- Residue normalization */
105  cs_real_t *residu, /* --> Final non normalized residue */
106  const cs_int_t *ifacel, /* <-- Face -> cell connectivity */
107  const cs_real_t *dam, /* <-- Matrix diagonal */
108  const cs_real_t *xam, /* <-- Matrix extra-diagonal terms */
109  const cs_real_t *smbrp, /* <-- System right-hand side */
110  cs_real_t *vx /* <-> System solution */
111 );
112 
113 /*=============================================================================
114  * Public function prototypes
115  *============================================================================*/
116 
117 /*----------------------------------------------------------------------------
118  * Initialize sparse linear equation solver API.
119  *----------------------------------------------------------------------------*/
120 
121 void
122 cs_sles_initialize(void);
123 
124 /*----------------------------------------------------------------------------
125  * Finalize sparse linear equation solver API.
126  *----------------------------------------------------------------------------*/
127 
128 void
129 cs_sles_finalize(void);
130 
131 #if defined(HAVE_MPI)
132 
133 /*----------------------------------------------------------------------------
134  * Set MPI communicator for dot products.
135  *----------------------------------------------------------------------------*/
136 
137 void
138 cs_sles_set_mpi_reduce_comm(MPI_Comm comm);
139 
140 #endif /* defined(HAVE_MPI) */
141 
142 /*----------------------------------------------------------------------------
143  * Test if a general sparse linear system needs solving or if the right-hand
144  * side is already zero within convergence criteria.
145  *
146  * The computed residue is also updated;
147  *
148  * parameters:
149  * var_name <-- Variable name
150  * solver_name <-- Name of solver
151  * n_rows <-- Number of (non ghost) rows in rhs
152  * verbosity <-- Verbosity level
153  * r_norm <-- Residue normalization
154  * residue <-> Residue
155  * rhs <-- Right hand side
156  *
157  * returns:
158  * 1 if solving is required, 0 if the rhs is already zero within tolerance
159  * criteria (precision of residue normalization)
160  *----------------------------------------------------------------------------*/
161 
162 int
163 cs_sles_needs_solving(const char *var_name,
164  const char *solver_name,
165  cs_int_t n_rows,
166  int verbosity,
167  double r_norm,
168  double *residue,
169  const cs_real_t *rhs);
170 
171 /*----------------------------------------------------------------------------
172  * General sparse linear system resolution.
173  *
174  * parameters:
175  * var_name <-- Variable name
176  * solver_type <-- Type of solver (PCG, Jacobi, ...)
177  * update_stats <-- Automatic solver statistics indicator
178  * symmetric <-- Symmetric coefficients indicator
179  * a <-- Matrix
180  * poly_degree <-- Preconditioning polynomial degree
181  * (0: diagonal; -1: non-preconditioned)
182  * rotation_mode <-- Halo update option for rotational periodicity
183  * verbosity <-- Verbosity level
184  * n_max_iter <-- Maximum number of iterations
185  * precision <-- Precision limit
186  * r_norm <-- Residue normalization
187  * n_iter --> Number of iterations
188  * residue <-> Residue
189  * rhs <-- Right hand side
190  * vx --> System solution
191  * aux_size <-- Number of elements in aux_vectors
192  * aux_vectors --- Optional working area (allocation otherwise)
193  *
194  * returns:
195  * 1 if converged, 0 if not converged, -1 if not converged and maximum
196  * iteration number reached, -2 if divergence is detected.
197  *----------------------------------------------------------------------------*/
198 
199 int
200 cs_sles_solve(const char *var_name,
201  cs_sles_type_t solver_type,
202  bool update_stats,
203  const cs_matrix_t *a,
204  int poly_degree,
205  cs_halo_rotation_t rotation_mode,
206  int verbosity,
207  int n_max_iter,
208  double precision,
209  double r_norm,
210  int *n_iter,
211  double *residue,
212  const cs_real_t *rhs,
213  cs_real_t *vx,
214  size_t aux_size,
215  void *aux_vectors);
216 
217 /*----------------------------------------------------------------------------
218  * Output default post-processing data for failed system convergence.
219  *
220  * parameters:
221  * var_name <-- Variable name
222  * mesh_id <-- id of error output mesh, or 0 if none
223  * rotation_mode <-- Halo update option for rotational periodicity
224  * a <-- Linear equation matrix
225  * rhs <-- Right hand side
226  * vx <-> Current system solution
227  *----------------------------------------------------------------------------*/
228 
229 void
230 cs_sles_post_error_output_def(const char *var_name,
231  int mesh_id,
232  cs_halo_rotation_t rotation_mode,
233  const cs_matrix_t *a,
234  const cs_real_t *rhs,
235  cs_real_t *vx);
236 
237 /*----------------------------------------------------------------------------
238  * Output post-processing variable for failed system convergence.
239  *
240  * parameters:
241  * var_name <-- Variable name
242  * diag_block_size <-- Block size for diagonal
243  * mesh_id <-- id of error output mesh, or 0 if none
244  * var <-- Variable values
245  *----------------------------------------------------------------------------*/
246 
247 void
248 cs_sles_post_error_output_var(const char *var_name,
249  int mesh_id,
250  int diag_block_size,
251  cs_real_t *var);
252 
253 /*----------------------------------------------------------------------------*/
254 
256 
257 #endif /* __CS_SLES_H__ */
Definition: cs_sles.h:61
cs_halo_rotation_t
Definition: cs_halo.h:59
const char * cs_sles_type_name[]
Definition: cs_sles.c:151
void cs_sles_initialize(void)
Definition: cs_sles.c:2995
void cs_sles_post_error_output_var(const char *var_name, int mesh_id, int diag_block_size, cs_real_t *var)
Definition: cs_sles.c:3471
#define BEGIN_C_DECLS
Definition: cs_defs.h:405
int cs_int_t
Fortran-compatible integer.
Definition: cs_defs.h:295
Definition: cs_sles.h:57
Definition: cs_sles.h:56
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:86
void cs_sles_finalize(void)
Definition: cs_sles.c:3010
Definition: cs_sles.h:59
void reslin(const char *cname, const cs_int_t *lname, const cs_int_t *ncelet, const cs_int_t *ncel, const cs_int_t *nfac, const cs_int_t *isym, const cs_int_t *ibsize, const cs_int_t *iesize, const cs_int_t *ireslp, const cs_int_t *ipol, const cs_int_t *nitmap, const cs_int_t *iinvpe, const cs_int_t *iwarnp, cs_int_t *niterf, const cs_real_t *epsilp, const cs_real_t *rnorm, cs_real_t *residu, const cs_int_t *ifacel, const cs_real_t *dam, const cs_real_t *xam, const cs_real_t *smbrp, cs_real_t *vx)
Definition: cs_sles.c:2822
void cs_sles_post_error_output_def(const char *var_name, int mesh_id, cs_halo_rotation_t rotation_mode, const cs_matrix_t *a, const cs_real_t *rhs, cs_real_t *vx)
Definition: cs_sles.c:3381
Definition: cs_sles.h:58
int cs_sles_solve(const char *var_name, cs_sles_type_t solver_type, bool update_stats, const cs_matrix_t *a, int poly_degree, cs_halo_rotation_t rotation_mode, int verbosity, int n_max_iter, 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)
Definition: cs_sles.c:3142
#define END_C_DECLS
Definition: cs_defs.h:406
double cs_real_t
Definition: cs_defs.h:296
#define CS_PROCF(x, y)
Definition: cs_defs.h:419
cs_sles_type_t
Definition: cs_sles.h:54
int cs_sles_needs_solving(const char *var_name, const char *solver_name, cs_int_t n_rows, int verbosity, double r_norm, double *residue, const cs_real_t *rhs)
Definition: cs_sles.c:3078
Definition: cs_sles.h:60