source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sundials/sundials_pcg.h @ 16222

Last change on this file since 16222 was 16222, checked in by gkronber, 4 years ago

#2925:

  • added comments about parameter identification for differential equation models
  • added source code of cvodes library (part of sundials) which provides functionality to calculate gradients for the parameters of partial differential equation models efficiently using the 'adjoint state method'.
  • added compiled version of cvodes
File size: 6.1 KB
Line 
1/*---------------------------------------------------------------
2 Programmer(s): Daniel R. Reynolds @ SMU
3 ----------------------------------------------------------------
4 Copyright (c) 2013, Southern Methodist University.
5 All rights reserved.
6 For details, see the LICENSE file.
7 ----------------------------------------------------------------
8 This is the header for the preconditioned conjugate gradient
9 solver in SUNDIALS.
10 ---------------------------------------------------------------*/
11
12#ifndef _PCG_H
13#define _PCG_H
14
15#include <sundials/sundials_iterative.h>
16
17#ifdef __cplusplus  /* wrapper to enable C++ usage */
18extern "C" {
19#endif
20
21/*---------------------------------------------------------------
22 Types: struct PcgMemRec and struct *PcgMem
23 ----------------------------------------------------------------
24 A variable declaration of type struct *PcgMem denotes a pointer
25 to a data structure of type struct PcgMemRec. The PcgMemRec
26 structure contains numerous fields that must be accessed by the
27 PCG linear solver module.
28  * l_max  maximum Krylov subspace dimension that PcgSolve will
29       be permitted to use
30  * r  vector (type N_Vector) which holds the preconditioned
31       linear system residual
32  * p, z and Ap vectors (type N_Vector) used for workspace by
33       the PCG algorithm
34  * vtemp  scratch vector (type N_Vector) used as temporary
35       vector storage
36 --------------------------------------------------------------*/
37typedef struct {
38  int l_max;
39  N_Vector r;
40  N_Vector p;
41  N_Vector z;
42  N_Vector Ap;
43} PcgMemRec, *PcgMem;
44
45/*---------------------------------------------------------------
46 Function : PcgMalloc
47 ----------------------------------------------------------------
48 PcgMalloc allocates additional memory needed by the PCG linear
49 solver module.
50
51   l_max  maximum Krylov subspace dimension that PcgSolve will
52          be permitted to use
53
54   vec_tmpl implementation-specific template vector (of type
55          N_Vector)
56
57 If successful, PcgMalloc returns a non-NULL memory pointer. If
58 an error occurs, then a NULL pointer is returned.
59 --------------------------------------------------------------*/
60
61SUNDIALS_EXPORT PcgMem PcgMalloc(int l_max, N_Vector vec_tmpl);
62
63/*---------------------------------------------------------------
64 Function : PcgSolve
65 ----------------------------------------------------------------
66 PcgSolve solves the linear system Ax = b by means of a
67 preconditioned Conjugate-Gradient (PCG) iterative method.
68
69  mem  pointer to an internal memory block allocated during a
70       prior call to PcgMalloc
71
72  A_data  pointer to a data structure containing information
73       about the coefficient matrix A (passed to user-supplied
74       function referenced by atimes (function pointer))
75
76  x  vector (type N_Vector) containing initial guess x_0 upon
77       entry, but which upon return contains an approximate
78       solution of the linear system Ax = b (solution only
79       valid if return value is either PCG_SUCCESS or
80       PCG_RES_REDUCED)
81
82  b  vector (type N_Vector) set to the right-hand side vector b
83       of the linear system (unchanged by function)
84
85  pretype  variable (type int) indicating the type of
86       preconditioning to be used (see sundials_iterative.h);
87       Note: since CG is for symmetric problems, preconditioning
88       is applied symmetrically by default, so any nonzero flag
89       will indicate to use the preconditioner.
90
91  delta  tolerance on the L2 norm of the residual (if the
92       return value == PCG_SUCCESS, then ||b-Ax||_L2 <= delta)
93
94  P_data  pointer to a data structure containing preconditioner
95       information (passed to user-supplied function referenced
96       by psolve (function pointer))
97
98  w  vector (type N_Vector) used in computing the residual norm
99       for stopping solver (unchanged by function).  This is
100       needed since PCG cannot utilize the same scaling vectors
101       as used in the other SUNDIALS solvers, due to
102       symmetry-breaking nature of scaling operators.
103
104  atimes  user-supplied routine responsible for computing the
105       matrix-vector product Ax (see sundials_iterative.h)
106
107  psolve  user-supplied routine responsible for solving the
108       preconditioned linear system Pz = r (ignored if
109       pretype == PREC_NONE) (see sundials_iterative.h)
110
111  res_norm  pointer (type realtype*) to the L2 norm of the
112       residual (if return value is either PCG_SUCCESS or
113       PCG_RES_REDUCED, then
114            *res_norm = ||b-Ax||_L2, where x is
115       the computed approximate solution)
116
117  nli  pointer (type int*) to the total number of linear
118       iterations performed
119
120  nps  pointer (type int*) to the total number of calls made
121       to the psolve routine
122 --------------------------------------------------------------*/
123
124SUNDIALS_EXPORT int PcgSolve(PcgMem mem, void *A_data, N_Vector x, N_Vector b,
125           int pretype, realtype delta, void *P_data,
126           N_Vector w, ATimesFn atimes, PSolveFn psolve,
127           realtype *res_norm, int *nli, int *nps);
128
129/* Return values for PcgSolve */
130#define PCG_SUCCESS            0  /* PCG algorithm converged          */
131#define PCG_RES_REDUCED        1  /* PCG did NOT converge, but the
132               residual was reduced           */
133#define PCG_CONV_FAIL          2  /* PCG algorithm failed to converge */
134#define PCG_PSOLVE_FAIL_REC    3  /* psolve failed recoverably        */
135#define PCG_ATIMES_FAIL_REC    4  /* atimes failed recoverably        */
136#define PCG_PSET_FAIL_REC      5  /* pset faild recoverably           */
137
138#define PCG_MEM_NULL          -1  /* mem argument is NULL             */
139#define PCG_ATIMES_FAIL_UNREC -2  /* atimes returned failure flag     */
140#define PCG_PSOLVE_FAIL_UNREC -3  /* psolve failed unrecoverably      */
141#define PCG_PSET_FAIL_UNREC   -4  /* pset failed unrecoverably        */
142
143/*---------------------------------------------------------------
144 Function : PcgFree
145 ----------------------------------------------------------------
146 PcgFree frees the memory allocated by a call to PcgMalloc.
147 It is illegal to use the pointer mem after a call to PcgFree.
148 ---------------------------------------------------------------*/
149
150SUNDIALS_EXPORT void PcgFree(PcgMem mem);
151
152#ifdef __cplusplus
153}
154#endif
155
156#endif
Note: See TracBrowser for help on using the repository browser.