source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sundials/sundials_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: 7.8 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * $Revision$
4 * $Date$
5 * -----------------------------------------------------------------
6 * Programmer(s): Peter Brown and Aaron Collier @ LLNL
7 * -----------------------------------------------------------------
8 * LLNS Copyright Start
9 * Copyright (c) 2014, Lawrence Livermore National Security
10 * This work was performed under the auspices of the U.S. Department
11 * of Energy by Lawrence Livermore National Laboratory in part under
12 * Contract W-7405-Eng-48 and in part under Contract DE-AC52-07NA27344.
13 * Produced at the Lawrence Livermore National Laboratory.
14 * All rights reserved.
15 * For details, see the LICENSE file.
16 * LLNS Copyright End
17 * -----------------------------------------------------------------
18 * This is the header file for the implementation of the scaled,
19 * preconditioned Bi-CGSTAB (SPBCG) iterative linear solver.
20 * -----------------------------------------------------------------
21 */
22
23#ifndef _SPBCG_H
24#define _SPBCG_H
25
26#include <sundials/sundials_iterative.h>
27
28#ifdef __cplusplus  /* wrapper to enable C++ usage */
29extern "C" {
30#endif
31
32/*
33 * -----------------------------------------------------------------
34 * Types: struct SpbcgMemRec and struct *SpbcgMem
35 * -----------------------------------------------------------------
36 * A variable declaration of type struct *SpbcgMem denotes a pointer
37 * to a data structure of type struct SpbcgMemRec. The SpbcgMemRec
38 * structure contains numerous fields that must be accessed by the
39 * SPBCG linear solver module.
40 *
41 *  l_max  maximum Krylov subspace dimension that SpbcgSolve will
42 *         be permitted to use
43 *
44 *  r  vector (type N_Vector) which holds the scaled, preconditioned
45 *     linear system residual
46 *
47 *  r_star  vector (type N_Vector) which holds the initial scaled,
48 *          preconditioned linear system residual
49 *
50 *  p, q, u and Ap  vectors (type N_Vector) used for workspace by
51 *                  the SPBCG algorithm
52 *
53 *  vtemp  scratch vector (type N_Vector) used as temporary vector
54 *         storage
55 * -----------------------------------------------------------------
56 */
57
58typedef struct {
59
60  int l_max;
61
62  N_Vector r_star;
63  N_Vector r;
64  N_Vector p;
65  N_Vector q;
66  N_Vector u;
67  N_Vector Ap;
68  N_Vector vtemp;
69
70} SpbcgMemRec, *SpbcgMem;
71
72/*
73 * -----------------------------------------------------------------
74 * Function : SpbcgMalloc
75 * -----------------------------------------------------------------
76 * SpbcgMalloc allocates additional memory needed by the SPBCG
77 * linear solver module.
78 *
79 *  l_max  maximum Krylov subspace dimension that SpbcgSolve will
80 *         be permitted to use
81 *
82 *  vec_tmpl  implementation-specific template vector (type N_Vector)
83 *            (created using either N_VNew_Serial or N_VNew_Parallel)
84 *
85 * If successful, SpbcgMalloc returns a non-NULL memory pointer. If
86 * an error occurs, then a NULL pointer is returned.
87 * -----------------------------------------------------------------
88 */
89
90SUNDIALS_EXPORT SpbcgMem SpbcgMalloc(int l_max, N_Vector vec_tmpl);
91
92/*
93 * -----------------------------------------------------------------
94 * Function : SpbcgSolve
95 * -----------------------------------------------------------------
96 * SpbcgSolve solves the linear system Ax = b by means of a scaled
97 * preconditioned Bi-CGSTAB (SPBCG) iterative method.
98 *
99 *  mem  pointer to an internal memory block allocated during a
100 *       prior call to SpbcgMalloc
101 *
102 *  A_data  pointer to a data structure containing information
103 *          about the coefficient matrix A (passed to user-supplied
104 *          function referenced by atimes (function pointer))
105 *
106 *  x  vector (type N_Vector) containing initial guess x_0 upon
107 *     entry, but which upon return contains an approximate solution
108 *     of the linear system Ax = b (solution only valid if return
109 *     value is either SPBCG_SUCCESS or SPBCG_RES_REDUCED)
110 *
111 *  b  vector (type N_Vector) set to the right-hand side vector b
112 *     of the linear system (undisturbed by function)
113 *
114 *  pretype  variable (type int) indicating the type of
115 *           preconditioning to be used (see sundials_iterative.h)
116 *
117 *  delta  tolerance on the L2 norm of the scaled, preconditioned
118 *         residual (if return value == SPBCG_SUCCESS, then
119 *         ||sb*P1_inv*(b-Ax)||_L2 <= delta)
120 *
121 *  P_data  pointer to a data structure containing preconditioner
122 *          information (passed to user-supplied function referenced
123 *          by psolve (function pointer))
124 *
125 *  sx  vector (type N_Vector) containing positive scaling factors
126 *      for x (pass sx == NULL if scaling NOT required)
127 *
128 *  sb  vector (type N_Vector) containing positive scaling factors
129 *      for b (pass sb == NULL if scaling NOT required)
130 *
131 *  atimes  user-supplied routine responsible for computing the
132 *          matrix-vector product Ax (see sundials_iterative.h)
133 *
134 *  psolve  user-supplied routine responsible for solving the
135 *          preconditioned linear system Pz = r (ignored if
136 *          pretype == PREC_NONE) (see sundials_iterative.h)
137 *
138 *  res_norm  pointer (type realtype*) to the L2 norm of the
139 *            scaled, preconditioned residual (if return value
140 *            is either SPBCG_SUCCESS or SPBCG_RES_REDUCED, then
141 *            *res_norm = ||sb*P1_inv*(b-Ax)||_L2, where x is
142 *            the computed approximate solution, sb is the diagonal
143 *            scaling matrix for the right-hand side b, and P1_inv
144 *            is the inverse of the left-preconditioner matrix)
145 *
146 *  nli  pointer (type int*) to the total number of linear
147 *       iterations performed
148 *
149 *  nps  pointer (type int*) to the total number of calls made
150 *       to the psolve routine
151 * -----------------------------------------------------------------
152 */
153
154SUNDIALS_EXPORT int SpbcgSolve(SpbcgMem mem, void *A_data, N_Vector x, N_Vector b,
155             int pretype, realtype delta, void *P_data, N_Vector sx,
156             N_Vector sb, ATimesFn atimes, PSolveFn psolve,
157             realtype *res_norm, int *nli, int *nps);
158
159/* Return values for SpbcgSolve */
160
161#define SPBCG_SUCCESS            0  /* SPBCG algorithm converged          */
162#define SPBCG_RES_REDUCED        1  /* SPBCG did NOT converge, but the
163               residual was reduced               */
164#define SPBCG_CONV_FAIL          2  /* SPBCG algorithm failed to converge */
165#define SPBCG_PSOLVE_FAIL_REC    3  /* psolve failed recoverably          */
166#define SPBCG_ATIMES_FAIL_REC    4  /* atimes failed recoverably          */
167#define SPBCG_PSET_FAIL_REC      5  /* pset faild recoverably             */
168
169#define SPBCG_MEM_NULL          -1  /* mem argument is NULL               */
170#define SPBCG_ATIMES_FAIL_UNREC -2  /* atimes returned failure flag       */
171#define SPBCG_PSOLVE_FAIL_UNREC -3  /* psolve failed unrecoverably        */
172#define SPBCG_PSET_FAIL_UNREC   -4  /* pset failed unrecoverably          */
173
174/*
175 * -----------------------------------------------------------------
176 * Function : SpbcgFree
177 * -----------------------------------------------------------------
178 * SpbcgFree frees the memory allocated by a call to SpbcgMalloc.
179 * It is illegal to use the pointer mem after a call to SpbcgFree.
180 * -----------------------------------------------------------------
181 */
182
183SUNDIALS_EXPORT void SpbcgFree(SpbcgMem mem);
184
185/*
186 * -----------------------------------------------------------------
187 * Macro : SPBCG_VTEMP
188 * -----------------------------------------------------------------
189 * This macro provides access to the vector r in the
190 * memory block of the SPBCG module. The argument mem is the
191 * memory pointer returned by SpbcgMalloc, of type SpbcgMem,
192 * and the macro value is of type N_Vector.
193 *
194 * Note: Only used by IDA (r contains P_inverse F if nli_inc == 0).
195 * -----------------------------------------------------------------
196 */
197
198#define SPBCG_VTEMP(mem) (mem->r)
199
200#ifdef __cplusplus
201}
202#endif
203
204#endif
Note: See TracBrowser for help on using the repository browser.