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