source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sunlinsol/sunlinsol_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: 8.7 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * Programmer(s): Daniel Reynolds, Ashley Crawford @ SMU
4 * -----------------------------------------------------------------
5 * LLNS/SMU Copyright Start
6 * Copyright (c) 2017, Southern Methodist University and
7 * Lawrence Livermore National Security
8 *
9 * This work was performed under the auspices of the U.S. Department
10 * of Energy by Southern Methodist University and Lawrence Livermore
11 * National Laboratory under Contract DE-AC52-07NA27344.
12 * Produced at Southern Methodist University and the Lawrence
13 * Livermore National Laboratory.
14 *
15 * All rights reserved.
16 * For details, see the LICENSE file.
17 * LLNS/SMU Copyright End
18 * -----------------------------------------------------------------
19 * This is the header file for the PCG implementation of the
20 * SUNLINSOL module.  The PCG algorithm is based on the
21 * Preconditioned Conjugate Gradient.
22 *
23 * The PCG algorithm solves a linear system A x = b where
24 * A is a symmetric, real-valued matrix, i.e. A = A' (Matlab
25 * notation for the transpose of A).  Preconditioning is allowed,
26 * and is applied in a symmetric fashion on both the right and left. 
27 * Scaling is also allowed and is applied symmetrically.  We denote
28 * the preconditioner and scaling matrices as follows:
29 *   P = preconditioner (assumed symmetric)
30 *   S = diagonal matrix of scale factors
31 * The matrices A and P are not required explicitly; only routines
32 * that provide A and P-inverse as operators are required.  The
33 * diagonal of the matrix S is held in a single N_Vector, supplied
34 * by the user of this module.
35 *
36 * In this notation, PCG applies the underlying algorithm to
37 * the equivalent transformed system
38 *   Abar xbar = bbar , where
39 *   Abar = S (P-inverse) A (P-inverse) S ,
40 *   bbar = S (P-inverse) b , and   xbar = (S-inverse) P x .
41 *
42 * The scaling matrix must be chosen so that the vectors
43 * (S P-inverse b) and (S-inverse P x) have dimensionless
44 * components.
45 *
46 * The stopping test for the PCG iterations is on the L2 norm of
47 * the scaled preconditioned residual:
48 *      || bbar - Abar xbar ||_2  <  delta
49 *  <=>
50 *      || S (P-inverse) b - S (P-inverse) A x ||_2  <  delta
51 *  <=>
52 *      || P-inverse b - (P-inverse) A x ||_S  <  delta
53 * where || v ||_S =  sqrt(v' S' S v) with an input test constant
54 * delta.
55 *
56 * The usage of this PCG solver involves supplying up to three
57 * routines and making a variety of calls.  The user-supplied
58 * routines are
59 *    atimes (A_data, x, y) to compute y = A x, given x,
60 *    psolve (P_data, y, x, lr) to solve P1 x = y or P2 x = y for
61 *           x, given y,
62 *    psetup (P_data) to perform any 'setup' operations in
63 *           preparation for calling psolve.
64 * The user calls are:
65 *    SUNLinearSolver LS = SUNPCG(y, pretype, maxl);
66 *           to create the linear solver structure,
67 *    flag = SUNLinSolSetATimes(LS, A_data, atimes);
68 *           to set the matrix-vector product setup/apply routines,
69 *    flag = SUNLinSolSetPreconditioner(LS, P_data, psetup, psolve);
70 *           to *optionally* set the preconditioner setup/apply routines,
71 *    flag = SUNLinSolSetScalingVectors(LS, s, NULL);
72 *           to *optionally* set the diagonal of the scaling matrix
73 *           (for PCG, only the first of the two scaling vectors is used)
74 *    flag = SUNLinSolInitialize(LS);
75 *           to perform internal solver memory allocations,
76 *    flag = SUNLinSolSetup(LS, NULL);
77 *           to call the psetup routine (if non-NULL);
78 *    flag = SUNLinSolSolve(LS, NULL, x, b, w, tol);
79 *           to solve the linear system to the tolerance 'tol'
80 *    long int nli = SUNLinSolNumIters(LS);
81 *           to *optionally* retrieve the number of linear iterations
82 *           performed by the solver,
83 *    long int lastflag = SUNLinSolLastFlag(LS);
84 *           to *optionally* retrieve the last internal solver error flag,
85 *    realtype resnorm = SUNLinSolResNorm(LS);
86 *           to *optionally* retrieve the final linear residual norm,
87 *    flag = SUNLinSolFree(LS);
88 *           to free the solver memory.
89 * Complete details for specifying atimes, psetup and psolve
90 * and for the usage calls are given below.
91 *
92 * -----------------------------------------------------------------
93 *
94 * Part I contains declarations specific to the PCG implementation
95 * of the supplied SUNLINSOL module.
96 *
97 * Part II contains the prototype for the constructor SUNPCG as well
98 * as implementation-specific prototypes for various useful solver
99 * operations.
100 *
101 * Notes:
102 *
103 *   - The definition of the generic SUNLinearSolver structure can
104 *     be found in the header file sundials_linearsolver.h.
105 *
106 * -----------------------------------------------------------------
107 */
108
109#ifndef _SUNLINSOL_PCG_H
110#define _SUNLINSOL_PCG_H
111
112#include <sundials/sundials_linearsolver.h>
113#include <sundials/sundials_matrix.h>
114#include <sundials/sundials_nvector.h>
115#include <sundials/sundials_pcg.h>
116
117#ifdef __cplusplus  /* wrapper to enable C++ usage */
118extern "C" {
119#endif
120
121/* Default PCG solver parameters */
122#define SUNPCG_MAXL_DEFAULT    5
123
124/*
125 * -----------------------------------------------------------------
126 * PART I: PCG implementation of SUNLinearSolver
127 *
128 * The PCG implementation of the SUNLinearSolver 'content'
129 * structure contains:
130 *     maxl -- number of PCG iterations to use
131 *     pretype -- flag for use of preconditioning
132 *     numiters -- number of iterations from most-recent solve
133 *     resnorm -- final linear residual norm from most-recent solve
134 *     last_flag -- last error return flag from internal setup/solve
135 *     ATimes -- function pointer to ATimes routine
136 *     ATData -- pointer to structure for ATimes
137 *     Psetup -- function pointer to preconditioner setup routine
138 *     Psolve -- function pointer to preconditioner solve routine
139 *     PData -- pointer to structure for Psetup/Psolve
140 *     s -- vector (type N_Vector) which holds the diagonal of the
141 *         scaling matrix S
142 *     r -- vector (type N_Vector) which holds the preconditioned
143 *         linear system residual
144 *     p, z and Ap -- vectors (type N_Vector) used for workspace by
145 *         the PCG algorithm
146 * -----------------------------------------------------------------
147 */
148 
149struct _SUNLinearSolverContent_PCG {
150  int maxl;
151  int pretype;
152  int numiters;
153  realtype resnorm;
154  long int last_flag;
155
156  ATimesFn ATimes;
157  void* ATData;
158  PSetupFn Psetup;
159  PSolveFn Psolve;
160  void* PData;
161
162  N_Vector s;
163  N_Vector r;
164  N_Vector p;
165  N_Vector z;
166  N_Vector Ap;
167};
168
169typedef struct _SUNLinearSolverContent_PCG *SUNLinearSolverContent_PCG;
170
171 
172/*
173 * -----------------------------------------------------------------
174 * PART III: functions exported by sunlinsol_pcg
175 *
176 * CONSTRUCTOR:
177 *    SUNPCG creates and allocates memory for a PCG solver
178 * -----------------------------------------------------------------
179 */
180
181SUNDIALS_EXPORT SUNLinearSolver SUNPCG(N_Vector y, int pretype, int maxl);
182SUNDIALS_EXPORT int SUNPCGSetPrecType(SUNLinearSolver S, int pretype);
183SUNDIALS_EXPORT int SUNPCGSetMaxl(SUNLinearSolver S, int maxl);
184
185/*
186 * -----------------------------------------------------------------
187 * PCG implementations of various useful linear solver operations
188 * -----------------------------------------------------------------
189 */
190
191SUNDIALS_EXPORT SUNLinearSolver_Type SUNLinSolGetType_PCG(SUNLinearSolver S);
192SUNDIALS_EXPORT int SUNLinSolInitialize_PCG(SUNLinearSolver S);
193SUNDIALS_EXPORT int SUNLinSolSetATimes_PCG(SUNLinearSolver S, void* A_data,
194                                           ATimesFn ATimes);
195SUNDIALS_EXPORT int SUNLinSolSetPreconditioner_PCG(SUNLinearSolver S,
196                                                   void* P_data,
197                                                   PSetupFn Pset,
198                                                   PSolveFn Psol);
199SUNDIALS_EXPORT int SUNLinSolSetScalingVectors_PCG(SUNLinearSolver S,
200                                                   N_Vector s,
201                                                   N_Vector nul);
202SUNDIALS_EXPORT int SUNLinSolSetup_PCG(SUNLinearSolver S, SUNMatrix nul);
203SUNDIALS_EXPORT int SUNLinSolSolve_PCG(SUNLinearSolver S, SUNMatrix nul,
204                                       N_Vector x, N_Vector b, realtype tol);
205SUNDIALS_EXPORT int SUNLinSolNumIters_PCG(SUNLinearSolver S);
206SUNDIALS_EXPORT realtype SUNLinSolResNorm_PCG(SUNLinearSolver S);
207SUNDIALS_EXPORT N_Vector SUNLinSolResid_PCG(SUNLinearSolver S);
208SUNDIALS_EXPORT long int SUNLinSolLastFlag_PCG(SUNLinearSolver S);
209SUNDIALS_EXPORT int SUNLinSolSpace_PCG(SUNLinearSolver S,
210                                       long int *lenrwLS,
211                                       long int *leniwLS);
212SUNDIALS_EXPORT int SUNLinSolFree_PCG(SUNLinearSolver S);
213
214#ifdef __cplusplus
215}
216#endif
217
218#endif
Note: See TracBrowser for help on using the repository browser.