7.0
general documentation
cs_sles_petsc.h
Go to the documentation of this file.
1 #ifndef __CS_SLES_PETSC_H__
2 #define __CS_SLES_PETSC_H__
3 
4 /*============================================================================
5  * Sparse Linear Equation Solvers using PETSc
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2021 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  * PETSc headers
32  *----------------------------------------------------------------------------*/
33 
34 #include <petscversion.h>
35 #include <petscconf.h>
36 #include <petscviewer.h>
37 #include <petscksp.h>
38 
39 /*----------------------------------------------------------------------------
40  * Local headers
41  *----------------------------------------------------------------------------*/
42 
43 #include "cs_base.h"
44 #include "cs_matrix.h"
45 #include "cs_sles.h"
46 
47 /*----------------------------------------------------------------------------*/
48 
50 
51 /*============================================================================
52  * Macro definitions
53  *============================================================================*/
54 
55 /*============================================================================
56  * Type definitions
57  *============================================================================*/
58 
59 /*----------------------------------------------------------------------------
60  * Function pointer for user settings of a PETSc KSP solver setup.
61  *
62  * This function is called at the end of the setup stage for a KSP solver.
63  *
64  * Note that using the advanced KSPSetPostSolve and KSPSetPreSolve functions,
65  * this also allows setting further function pointers for pre and post-solve
66  * operations (see the PETSc documentation).
67  *
68  * Note: if the context pointer is non-NULL, it must point to valid data
69  * when the selection function is called so that value or structure should
70  * not be temporary (i.e. local);
71  *
72  * parameters:
73  * context <-> pointer to optional (untyped) value or structure
74  * ksp <-> pointer to PETSc KSP context
75  *----------------------------------------------------------------------------*/
76 
77 typedef void
78 (cs_sles_petsc_setup_hook_t) (void *context,
79  KSP ksp);
80 
81 /* Iterative linear solver context (opaque) */
82 
83 typedef struct _cs_sles_petsc_t cs_sles_petsc_t;
84 
85 /*============================================================================
86  * Global variables
87  *============================================================================*/
88 
89 /*=============================================================================
90  * User function prototypes
91  *============================================================================*/
92 
93 /*----------------------------------------------------------------------------
94  * Function pointer for user settings of a PETSc KSP solver setup.
95  *
96  * This function is called at the end of the setup stage for a KSP solver.
97  *
98  * Note that using the advanced KSPSetPostSolve and KSPSetPreSolve functions,
99  * this also allows setting further function pointers for pre and post-solve
100  * operations (see the PETSc documentation).
101  *
102  * Note: if the context pointer is non-NULL, it must point to valid data
103  * when the selection function is called so that value or structure should
104  * not be temporary (i.e. local);
105  *
106  * parameters:
107  * context <-> pointer to optional (untyped) value or structure
108  * ksp <-> pointer to PETSc KSP context
109  *----------------------------------------------------------------------------*/
110 
111 void
112 cs_user_sles_petsc_hook(void *context,
113  KSP ksp);
114 
115 /*=============================================================================
116  * Static inline public function prototypes
117  *============================================================================*/
118 
119 /*----------------------------------------------------------------------------
120  * Initialize PETSc if needed
121  *----------------------------------------------------------------------------*/
122 
123 static inline void
124 cs_sles_petsc_init(void)
125 {
126  /* Initialization must be called before setting options;
127  it does not need to be called before calling
128  cs_sles_petsc_define(), as this is handled automatically. */
129 
130  PetscBool is_initialized;
131  PetscInitialized(&is_initialized);
132 
133  if (is_initialized == PETSC_FALSE) {
134 #if defined(HAVE_MPI)
135  PETSC_COMM_WORLD = cs_glob_mpi_comm;
136 #endif
137  PetscInitializeNoArguments();
138  }
139 }
140 
141 /*----------------------------------------------------------------------------
142  * \brief Output the settings of a KSP structure
143  *
144  * \param[in] ksp Krylov SubSpace structure
145  *----------------------------------------------------------------------------*/
146 
147 static inline void
148 cs_sles_petsc_log_setup(KSP ksp)
149 {
150  PetscViewer v;
151 
152  PetscViewerCreate(PETSC_COMM_WORLD, &v);
153  PetscViewerSetType(v, PETSCVIEWERASCII);
154  PetscViewerFileSetMode(v, FILE_MODE_APPEND);
155  PetscViewerFileSetName(v, "petsc_setup.log");
156 
157  KSPView(ksp, v);
158  PetscViewerDestroy(&v);
159 }
160 
161 /*=============================================================================
162  * Public function prototypes
163  *============================================================================*/
164 
165 /*----------------------------------------------------------------------------
166  * Define and associate a PETSc linear system solver
167  * for a given field or equation name.
168  *
169  * If this system did not previously exist, it is added to the list of
170  * "known" systems. Otherwise, its definition is replaced by the one
171  * defined here.
172  *
173  * This is a utility function: if finer control is needed, see
174  * cs_sles_define() and cs_sles_petsc_create().
175  *
176  * In case of rotational periodicity for a block (non-scalar) matrix,
177  * the matrix type will be forced to MATSHELL ("shell") regardless
178  * of the option used.
179  *
180  * Note that this function returns a pointer directly to the iterative solver
181  * management structure. This may be used to set further options.
182  * If needed, cs_sles_find() may be used to obtain a pointer to the matching
183  * cs_sles_t container.
184  *
185  * parameters:
186  * f_id <-- associated field id, or < 0
187  * name <-- associated name if f_id < 0, or NULL
188  * matrix_type <-- PETSc matrix type
189  * setup_hook <-- pointer to optional setup epilogue function
190  * context <-> pointer to optional (untyped) value or structure
191  * for setup_hook, or NULL
192  *
193  * returns:
194  * pointer to newly created iterative solver info object.
195  *----------------------------------------------------------------------------*/
196 
198 cs_sles_petsc_define(int f_id,
199  const char *name,
200  MatType matrix_type,
201  cs_sles_petsc_setup_hook_t *setup_hook,
202  void *context);
203 
204 /*----------------------------------------------------------------------------
205  * Create PETSc linear system solver info and context.
206  *
207  * In case of rotational periodicity for a block (non-scalar) matrix,
208  * the matrix type will be forced to MATSHELL ("shell") regardless
209  * of the option used.
210  *
211  * parameters:
212  * matrix_type <-- PETSc matrix type
213  * setup_hook <-- pointer to optional setup epilogue function
214  * context <-> pointer to optional (untyped) value or structure
215  * for setup_hook, or NULL
216  *
217  * returns:
218  * pointer to newly created solver info object.
219  *----------------------------------------------------------------------------*/
220 
222 cs_sles_petsc_create(MatType matrix_type,
223  cs_sles_petsc_setup_hook_t *setup_hook,
224  void *context);
225 
226 /*----------------------------------------------------------------------------
227  * Create PETSc linear system solver info and context
228  * based on existing info and context.
229  *
230  * parameters:
231  * context <-- pointer to reference info and context
232  * (actual type: cs_sles_petsc_t *)
233  *
234  * returns:
235  * pointer to newly created solver info object
236  * (actual type: cs_sles_petsc_t *)
237  *----------------------------------------------------------------------------*/
238 
239 void *
240 cs_sles_petsc_copy(const void *context);
241 
242 /*----------------------------------------------------------------------------
243  * Destroy PETSc linear system solver info and context.
244  *
245  * parameters:
246  * context <-> pointer to PETSc linear solver info
247  * (actual type: cs_sles_petsc_t **)
248  *----------------------------------------------------------------------------*/
249 
250 void
251 cs_sles_petsc_destroy(void **context);
252 
253 /*----------------------------------------------------------------------------
254  * Setup PETSc linear equation solver.
255  *
256  * parameters:
257  * context <-> pointer to PETSc linear solver info
258  * (actual type: cs_sles_petsc_t *)
259  * name <-- pointer to system name
260  * a <-- associated matrix
261  * verbosity <-- verbosity level
262  *----------------------------------------------------------------------------*/
263 
264 void
265 cs_sles_petsc_setup(void *context,
266  const char *name,
267  const cs_matrix_t *a,
268  int verbosity);
269 
270 /*----------------------------------------------------------------------------
271  * Call PETSc linear equation solver.
272  *
273  * parameters:
274  * context <-> pointer to PETSc linear solver info
275  * (actual type: cs_sles_petsc_t *)
276  * name <-- pointer to system name
277  * a <-- matrix
278  * verbosity <-- verbosity level
279  * rotation_mode <-- halo update option for rotational periodicity
280  * precision <-- solver precision
281  * r_norm <-- residue normalization
282  * n_iter --> number of iterations
283  * residue --> residue
284  * rhs <-- right hand side
285  * vx <-> system solution
286  * aux_size <-- number of elements in aux_vectors (in bytes)
287  * aux_vectors --- optional working area (internal allocation if NULL)
288  *
289  * returns:
290  * convergence state
291  *----------------------------------------------------------------------------*/
292 
294 cs_sles_petsc_solve(void *context,
295  const char *name,
296  const cs_matrix_t *a,
297  int verbosity,
298  cs_halo_rotation_t rotation_mode,
299  double precision,
300  double r_norm,
301  int *n_iter,
302  double *residue,
303  const cs_real_t *rhs,
304  cs_real_t *vx,
305  size_t aux_size,
306  void *aux_vectors);
307 
308 /*----------------------------------------------------------------------------
309  * Free PETSc linear equation solver setup context.
310  *
311  * This function frees resolution-related data, such as
312  * buffers and preconditioning but does not free the whole context,
313  * as info used for logging (especially performance data) is maintained.
314 
315  * parameters:
316  * context <-> pointer to PETSc linear solver info
317  * (actual type: cs_sles_petsc_t *)
318  *----------------------------------------------------------------------------*/
319 
320 void
321 cs_sles_petsc_free(void *context);
322 
323 /*----------------------------------------------------------------------------*/
340 /*----------------------------------------------------------------------------*/
341 
342 bool
345  const cs_matrix_t *a,
346  cs_halo_rotation_t rotation_mode,
347  const cs_real_t *rhs,
348  cs_real_t *vx);
349 
350 /*----------------------------------------------------------------------------
351  * Log sparse linear equation solver info.
352  *
353  * parameters:
354  * context <-> pointer to PETSc linear solver info
355  * (actual type: cs_sles_petsc_t *)
356  * log_type <-- log type
357  *----------------------------------------------------------------------------*/
358 
359 void
360 cs_sles_petsc_log(const void *context,
361  cs_log_t log_type);
362 
363 /*----------------------------------------------------------------------------*/
364 
366 
367 #endif /* __CS_SLES_PETSC_H__ */
bool cs_sles_petsc_error_post_and_abort(cs_sles_t *sles, cs_sles_convergence_state_t state, const cs_matrix_t *a, cs_halo_rotation_t rotation_mode, const cs_real_t *rhs, cs_real_t *vx)
Error handler for PETSc solver.
Definition: cs_sles_petsc.c:1521
struct _cs_sles_petsc_t cs_sles_petsc_t
Definition: cs_sles_petsc.h:83
cs_halo_rotation_t
Definition: cs_halo.h:60
void cs_user_sles_petsc_hook(void *context, KSP ksp)
Definition: cs_sles_petsc.c:489
#define BEGIN_C_DECLS
Definition: cs_defs.h:495
void() cs_sles_petsc_setup_hook_t(void *context, KSP ksp)
Function pointer for user settings of a PETSc KSP solver setup.
Definition: cs_sles_petsc.h:78
cs_sles_petsc_t * cs_sles_petsc_create(MatType matrix_type, cs_sles_petsc_setup_hook_t *setup_hook, void *context)
Create PETSc linear system solver info and context.
Definition: cs_sles_petsc.c:579
double cs_real_t
Floating-point value.
Definition: cs_defs.h:307
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:94
void cs_sles_petsc_setup(void *context, const char *name, const cs_matrix_t *a, int verbosity)
Setup PETSc linear equation solver.
Definition: cs_sles_petsc.c:726
void * cs_sles_petsc_copy(const void *context)
Create PETSc linear system solver info and context based on existing info and context.
Definition: cs_sles_petsc.c:656
cs_sles_convergence_state_t
Convergence status indicator.
Definition: cs_sles.h:56
struct _cs_sles_t cs_sles_t
Definition: cs_sles.h:68
double precision, dimension(:,:,:), allocatable v
Definition: atimbr.f90:114
double precision, save a
Definition: cs_fuel_incl.f90:146
void cs_sles_petsc_free(void *context)
Free PETSc linear equation solver setup context.
Definition: cs_sles_petsc.c:1474
cs_sles_petsc_t * cs_sles_petsc_define(int f_id, const char *name, MatType matrix_type, cs_sles_petsc_setup_hook_t *setup_hook, void *context)
Define and associate a PETSc linear system solver for a given field or equation name.
Definition: cs_sles_petsc.c:533
cs_log_t
Definition: cs_log.h:48
cs_sles_convergence_state_t cs_sles_petsc_solve(void *context, const char *name, const cs_matrix_t *a, int verbosity, cs_halo_rotation_t rotation_mode, 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)
Call PETSc linear equation solver.
Definition: cs_sles_petsc.c:1298
MPI_Comm cs_glob_mpi_comm
Definition: cs_defs.c:179
#define END_C_DECLS
Definition: cs_defs.h:496
void cs_sles_petsc_destroy(void **context)
Destroy PETSc linear system solver info and context.
Definition: cs_sles_petsc.c:680
void cs_sles_petsc_log(const void *context, cs_log_t log_type)
Log sparse linear equation solver info.
Definition: cs_sles_petsc.c:1563