source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sunlinsol/sunlinsol_spbcgs.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: 9.5 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * Programmer(s): Daniel Reynolds @ SMU
4 * Based on code sundials_spbcgs.h by: Peter Brown and
5 *     Aaron Collier @ LLNL
6 * -----------------------------------------------------------------
7 * LLNS/SMU Copyright Start
8 * Copyright (c) 2017, Southern Methodist University and
9 * Lawrence Livermore National Security
10 *
11 * This work was performed under the auspices of the U.S. Department
12 * of Energy by Southern Methodist University and Lawrence Livermore
13 * National Laboratory under Contract DE-AC52-07NA27344.
14 * Produced at Southern Methodist University and the Lawrence
15 * Livermore National Laboratory.
16 *
17 * All rights reserved.
18 * For details, see the LICENSE file.
19 * LLNS/SMU Copyright End
20 * -----------------------------------------------------------------
21 * This is the header file for the SPBCGS implementation of the
22 * SUNLINSOL module.  The SPBCGS algorithm is based on the
23 * Scaled Preconditioned Bi-CG-Stabilized method.
24 *
25 * The SPBCGS algorithm solves a linear system A x = b.
26 * Preconditioning is allowed on the left, right, or both.
27 * Scaling is allowed on both sides.  We denote the preconditioner
28 * and scaling matrices as follows:
29 *   P1 = left preconditioner
30 *   P2 = right preconditioner
31 *   S1 = diagonal matrix of scale factors for P1-inverse b
32 *   S2 = diagonal matrix of scale factors for P2 x
33 * The matrices A, P1, and P2 are not required explicitly; only
34 * routines that provide A, P1-inverse, and P2-inverse as
35 * operators are required.
36 *
37 * In this notation, SPBCGS applies the underlying GMRES method to
38 * the equivalent transformed system
39 *   Abar xbar = bbar , where
40 *   Abar = S1 (P1-inverse) A (P2-inverse) (S2-inverse) ,
41 *   bbar = S1 (P1-inverse) b , and   xbar = S2 P2 x .
42 *
43 * The scaling matrices must be chosen so that vectors S1
44 * P1-inverse b and S2 P2 x have dimensionless components.
45 * If preconditioning is done on the left only (P2 = I), by a
46 * matrix P, then S2 must be a scaling for x, while S1 is a
47 * scaling for P-inverse b, and so may also be taken as a scaling
48 * for x.  Similarly, if preconditioning is done on the right only
49 * (P1 = I, P2 = P), then S1 must be a scaling for b, while S2 is
50 * a scaling for P x, and may also be taken as a scaling for b.
51 *
52 * The stopping test for the SPBCGS iterations is on the L2 norm of
53 * the scaled preconditioned residual:
54 *      || bbar - Abar xbar ||_2  <  delta
55 * with an input test constant delta.
56 *
57 * The usage of this SPBCGS solver involves supplying up to three
58 * routines and making a variety of calls.  The user-supplied
59 * routines are
60 *    atimes (A_data, x, y) to compute y = A x, given x,
61 *    psolve (P_data, y, x, lr) to solve P1 x = y or P2 x = y for
62 *           x, given y,
63 *    psetup (P_data) to perform any 'setup' operations in
64 *           preparation for calling psolve.
65 * The user calls are:
66 *    SUNLinearSolver LS = SUNSPBCGS(y, pretype, maxl);
67 *           to create the linear solver structure,
68 *    flag = SUNLinSolSetATimes(LS, A_data, atimes);
69 *           to set the matrix-vector product setup/apply routines,
70 *    flag = SUNLinSolSetPreconditioner(LS, P_data, psetup, psolve);
71 *           to *optionally* set the preconditioner setup/apply routines,
72 *    flag = SUNLinSolSetScalingVectors(LS, s1, s2);
73 *           to *optionally* set the diagonals of the scaling matrices.
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 SPBCGS implementation
95 * of the supplied SUNLINSOL module.
96 *
97 * Part II contains the prototype for the constructor
98 * SUNSPBCGS as well as implementation-specific prototypes
99 * for various useful solver 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_SPBCGS_H
110#define _SUNLINSOL_SPBCGS_H
111
112#include <sundials/sundials_linearsolver.h>
113#include <sundials/sundials_matrix.h>
114#include <sundials/sundials_nvector.h>
115#include <sundials/sundials_spbcgs.h>
116
117#ifdef __cplusplus  /* wrapper to enable C++ usage */
118extern "C" {
119#endif
120
121/* Default SPBCGS solver parameters */
122#define SUNSPBCGS_MAXL_DEFAULT 5
123
124/*
125 * -----------------------------------------------------------------
126 * PART I: SPBCGS implementation of SUNLinearSolver
127 *
128 * The SPBCGS implementation of the SUNLinearSolver 'content'
129 * structure contains:
130 *     maxl -- number of BiCGStab iterations to allow
131 *     pretype -- flag for type of preconditioning to employ
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 *     s1,s2 -- vectors (type N_Vector) which holds the diagonals
141 *         of the scaling matrices S1 and S2, respectively
142 *     r -- a vector (type N_Vector) which holds the scaled,
143 *         preconditioned linear system residual
144 *     r_star -- a vector (type N_Vector) which holds the initial
145 *         scaled, preconditioned linear system residual
146 *     p, q, u and Ap -- vectors (type N_Vector) used for workspace
147 *         by the SPBCG algorithm.
148 *     vtemp -- a vector (type N_Vector) used as temporary vector
149 *         storage during calculations.
150 * -----------------------------------------------------------------
151 */
152 
153struct _SUNLinearSolverContent_SPBCGS {
154  int maxl;
155  int pretype;
156  int numiters;
157  realtype resnorm;
158  long int last_flag;
159
160  ATimesFn ATimes;
161  void* ATData;
162  PSetupFn Psetup;
163  PSolveFn Psolve;
164  void* PData;
165
166  N_Vector s1;
167  N_Vector s2;
168  N_Vector r;
169  N_Vector r_star;
170  N_Vector p;
171  N_Vector q;
172  N_Vector u;
173  N_Vector Ap;
174  N_Vector vtemp;
175};
176
177typedef struct _SUNLinearSolverContent_SPBCGS *SUNLinearSolverContent_SPBCGS;
178
179 
180/*
181 * -----------------------------------------------------------------
182 * PART II: functions exported by sunlinsol_spbcgs
183 *
184 * CONSTRUCTOR:
185 *    SUNSPBCGS creates and allocates memory for a SPBCGS solver
186 *
187 * "SET" ROUTINES:
188 *    SUNSPBCGSSetPrecType updates the type of preconditioning to
189 *       use.  Supported values are PREC_NONE, PREC_LEFT, PREC_RIGHT
190 *       and PREC_BOTH.
191 *    SUNSPBCGSSetMaxl updates the maximum number of iterations to
192 *       allow in the solver.
193 * -----------------------------------------------------------------
194 */
195
196SUNDIALS_EXPORT SUNLinearSolver SUNSPBCGS(N_Vector y, int pretype, int maxl);
197SUNDIALS_EXPORT int SUNSPBCGSSetPrecType(SUNLinearSolver S, int pretype);
198SUNDIALS_EXPORT int SUNSPBCGSSetMaxl(SUNLinearSolver S, int maxl);
199
200/*
201 * -----------------------------------------------------------------
202 * SPBCGS implementations of various useful linear solver operations
203 * -----------------------------------------------------------------
204 */
205
206SUNDIALS_EXPORT SUNLinearSolver_Type SUNLinSolGetType_SPBCGS(SUNLinearSolver S);
207SUNDIALS_EXPORT int SUNLinSolInitialize_SPBCGS(SUNLinearSolver S);
208SUNDIALS_EXPORT int SUNLinSolSetATimes_SPBCGS(SUNLinearSolver S, void* A_data,
209                                              ATimesFn ATimes);
210SUNDIALS_EXPORT int SUNLinSolSetPreconditioner_SPBCGS(SUNLinearSolver S,
211                                                      void* P_data,
212                                                      PSetupFn Pset,
213                                                      PSolveFn Psol);
214SUNDIALS_EXPORT int SUNLinSolSetScalingVectors_SPBCGS(SUNLinearSolver S,
215                                                      N_Vector s1,
216                                                      N_Vector s2);
217SUNDIALS_EXPORT int SUNLinSolSetup_SPBCGS(SUNLinearSolver S, SUNMatrix A);
218SUNDIALS_EXPORT int SUNLinSolSolve_SPBCGS(SUNLinearSolver S, SUNMatrix A,
219                                          N_Vector x, N_Vector b, realtype tol);
220SUNDIALS_EXPORT int SUNLinSolNumIters_SPBCGS(SUNLinearSolver S);
221SUNDIALS_EXPORT realtype SUNLinSolResNorm_SPBCGS(SUNLinearSolver S);
222SUNDIALS_EXPORT N_Vector SUNLinSolResid_SPBCGS(SUNLinearSolver S);
223SUNDIALS_EXPORT long int SUNLinSolLastFlag_SPBCGS(SUNLinearSolver S);
224SUNDIALS_EXPORT int SUNLinSolSpace_SPBCGS(SUNLinearSolver S,
225                                          long int *lenrwLS,
226                                          long int *leniwLS);
227SUNDIALS_EXPORT int SUNLinSolFree_SPBCGS(SUNLinearSolver S);
228
229
230#ifdef __cplusplus
231}
232#endif
233
234#endif
Note: See TracBrowser for help on using the repository browser.