programmer's 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-2015 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 <petscksp.h>
35 
36 /*----------------------------------------------------------------------------
37  * Local headers
38  *----------------------------------------------------------------------------*/
39 
40 #include "cs_base.h"
41 #include "cs_halo_perio.h"
42 #include "cs_matrix.h"
43 #include "cs_time_plot.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 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 furthur 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  * Public function prototypes
89  *============================================================================*/
90 
91 /*----------------------------------------------------------------------------
92  * Define and associate a PETSc linear system solver
93  * for a given field or equation name.
94  *
95  * If this system did not previously exist, it is added to the list of
96  * "known" systems. Otherwise, its definition is replaced by the one
97  * defined here.
98  *
99  * This is a utility function: if finer control is needed, see
100  * cs_sles_define() and cs_sles_petsc_create().
101  *
102  * In case of rotational periodicity for a block (non-scalar) matrix,
103  * the matrix type will be forced to MATSHELL ("shell") regardless
104  * of the option used.
105  *
106  * Note that this function returns a pointer directly to the iterative solver
107  * management structure. This may be used to set further options.
108  * If needed, cs_sles_find() may be used to obtain a pointer to the matching
109  * cs_sles_t container.
110  *
111  * parameters:
112  * f_id <-- associated field id, or < 0
113  * name <-- associated name if f_id < 0, or NULL
114  * matrix_type <-- PETSc matrix type
115  * setup_hook <-- pointer to optional setup epilogue function
116  * context <-> pointer to optional (untyped) value or structure
117  * for setup_hook, or NULL
118  *
119  * returns:
120  * pointer to newly created iterative solver info object.
121  *----------------------------------------------------------------------------*/
122 
124 cs_sles_petsc_define(int f_id,
125  const char *name,
126  MatType matrix_type,
127  cs_sles_petsc_setup_hook_t *setup_hook,
128  void *context);
129 
130 /*----------------------------------------------------------------------------
131  * Create PETSc linear system solver info and context.
132  *
133  * In case of rotational periodicity for a block (non-scalar) matrix,
134  * the matrix type will be forced to MATSHELL ("shell") regardless
135  * of the option used.
136  *
137  * parameters:
138  * matrix_type <-- PETSc matrix type
139  * setup_hook <-- pointer to optional setup epilogue function
140  * context <-> pointer to optional (untyped) value or structure
141  * for setup_hook, or NULL
142  *
143  * returns:
144  * pointer to newly created solver info object.
145  *----------------------------------------------------------------------------*/
146 
148 cs_sles_petsc_create(MatType matrix_type,
149  cs_sles_petsc_setup_hook_t *setup_hook,
150  void *context);
151 
152 /*----------------------------------------------------------------------------
153  * Create PETSc linear system solver info and context
154  * based on existing info and context.
155  *
156  * parameters:
157  * context <-- pointer to reference info and context
158  * (actual type: cs_sles_petsc_t *)
159  *
160  * returns:
161  * pointer to newly created solver info object
162  * (actual type: cs_sles_petsc_t *)
163  *----------------------------------------------------------------------------*/
164 
165 void *
166 cs_sles_petsc_copy(const void *context);
167 
168 /*----------------------------------------------------------------------------
169  * Destroy PETSc linear system solver info and context.
170  *
171  * parameters:
172  * context <-> pointer to PETSc linear solver info
173  * (actual type: cs_sles_petsc_t **)
174  *----------------------------------------------------------------------------*/
175 
176 void
177 cs_sles_petsc_destroy(void **context);
178 
179 /*----------------------------------------------------------------------------
180  * Setup PETSc linear equation solver.
181  *
182  * parameters:
183  * context <-> pointer to PETSc linear solver info
184  * (actual type: cs_sles_petsc_t *)
185  * name <-- pointer to system name
186  * a <-- associated matrix
187  * verbosity <-- verbosity level
188  *----------------------------------------------------------------------------*/
189 
190 void
191 cs_sles_petsc_setup(void *context,
192  const char *name,
193  const cs_matrix_t *a,
194  int verbosity);
195 
196 /*----------------------------------------------------------------------------
197  * Call PETSc linear equation solver.
198  *
199  * parameters:
200  * context <-> pointer to PETSc linear solver info
201  * (actual type: cs_sles_petsc_t *)
202  * name <-- pointer to system name
203  * a <-- matrix
204  * verbosity <-- verbosity level
205  * rotation_mode <-- halo update option for rotational periodicity
206  * precision <-- solver precision
207  * r_norm <-- residue normalization
208  * n_iter --> number of iterations
209  * residue --> residue
210  * rhs <-- right hand side
211  * vx <-> system solution
212  * aux_size <-- number of elements in aux_vectors (in bytes)
213  * aux_vectors --- optional working area (internal allocation if NULL)
214  *
215  * returns:
216  * convergence state
217  *----------------------------------------------------------------------------*/
218 
220 cs_sles_petsc_solve(void *context,
221  const char *name,
222  const cs_matrix_t *a,
223  int verbosity,
224  cs_halo_rotation_t rotation_mode,
225  double precision,
226  double r_norm,
227  int *n_iter,
228  double *residue,
229  const cs_real_t *rhs,
230  cs_real_t *vx,
231  size_t aux_size,
232  void *aux_vectors);
233 
234 /*----------------------------------------------------------------------------
235  * Free PETSc linear equation solver setup context.
236  *
237  * This function frees resolution-related data, such as
238  * buffers and preconditioning but does not free the whole context,
239  * as info used for logging (especially performance data) is maintained.
240 
241  * parameters:
242  * context <-> pointer to PETSc linear solver info
243  * (actual type: cs_sles_petsc_t *)
244  *----------------------------------------------------------------------------*/
245 
246 void
247 cs_sles_petsc_free(void *context);
248 
249 /*----------------------------------------------------------------------------
250  * Log sparse linear equation solver info.
251  *
252  * parameters:
253  * context <-> pointer to PETSc linear solver info
254  * (actual type: cs_sles_petsc_t *)
255  * log_type <-- log type
256  *----------------------------------------------------------------------------*/
257 
258 void
259 cs_sles_petsc_log(const void *context,
260  cs_log_t log_type);
261 
262 /*----------------------------------------------------------------------------*/
263 
265 
266 #endif /* __CS_SLES_PETSC_H__ */
struct _cs_sles_petsc_t cs_sles_petsc_t
Definition: cs_sles_petsc.h:81
cs_halo_rotation_t
Definition: cs_halo.h:59
#define BEGIN_C_DECLS
Definition: cs_defs.h:429
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_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:457
struct _cs_matrix_t cs_matrix_t
Definition: cs_matrix.h:89
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:600
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:530
cs_sles_convergence_state_t
Convergence status indicator.
Definition: cs_sles.h:55
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:1337
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:409
cs_log_t
Definition: cs_log.h:47
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:1172
#define END_C_DECLS
Definition: cs_defs.h:430
double cs_real_t
Definition: cs_defs.h:296
void cs_sles_petsc_destroy(void **context)
Destroy PETSc linear system solver info and context.
Definition: cs_sles_petsc.c:554
void cs_sles_petsc_log(const void *context, cs_log_t log_type)
Log sparse linear equation solver info.
Definition: cs_sles_petsc.c:1375