source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sundials/sundials_nvector.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: 16.5 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * $Revision$
4 * $Date$
5 * -----------------------------------------------------------------
6 * Programmer(s): Radu Serban 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 a generic NVECTOR package.
19 * It defines the N_Vector structure (_generic_N_Vector) which
20 * contains the following fields:
21 *   - an implementation-dependent 'content' field which contains
22 *     the description and actual data of the vector
23 *   - an 'ops' filed which contains a structure listing operations
24 *     acting on such vectors
25 *
26 * Part I of this file contains type declarations for the
27 * _generic_N_Vector and _generic_N_Vector_Ops structures, as well
28 * as references to pointers to such structures (N_Vector).
29 *
30 * Part II of this file contains the prototypes for the vector
31 * functions which operate on N_Vector.
32 *
33 * At a minimum, a particular implementation of an NVECTOR must
34 * do the following:
35 *  - specify the 'content' field of N_Vector,
36 *  - implement the operations on those N_Vectors,
37 *  - provide a constructor routine for new vectors
38 *
39 * Additionally, an NVECTOR implementation may provide the following:
40 *  - macros to access the underlying N_Vector data
41 *  - a constructor for an array of N_Vectors
42 *  - a constructor for an empty N_Vector (i.e., a new N_Vector with
43 *    a NULL data pointer).
44 *  - a routine to print the content of an N_Vector
45 * -----------------------------------------------------------------
46 */
47
48#ifndef _NVECTOR_H
49#define _NVECTOR_H
50
51#include <sundials/sundials_types.h>
52
53#ifdef __cplusplus  /* wrapper to enable C++ usage */
54extern "C" {
55#endif
56
57 
58/*
59 * -----------------------------------------------------------------
60 * Implemented N_Vector types
61 * -----------------------------------------------------------------
62 */
63 
64typedef enum {
65  SUNDIALS_NVEC_SERIAL,
66  SUNDIALS_NVEC_PARALLEL,
67  SUNDIALS_NVEC_OPENMP,
68  SUNDIALS_NVEC_PTHREADS,
69  SUNDIALS_NVEC_PARHYP,
70  SUNDIALS_NVEC_PETSC,
71  SUNDIALS_NVEC_CUDA,
72  SUNDIALS_NVEC_RAJA,
73  SUNDIALS_NVEC_CUSTOM
74} N_Vector_ID;
75 
76/*
77 * -----------------------------------------------------------------
78 * Generic definition of N_Vector
79 * -----------------------------------------------------------------
80 */
81
82/* Forward reference for pointer to N_Vector_Ops object */
83typedef struct _generic_N_Vector_Ops *N_Vector_Ops;
84
85/* Forward reference for pointer to N_Vector object */
86typedef struct _generic_N_Vector *N_Vector;
87
88/* Define array of N_Vectors */
89typedef N_Vector *N_Vector_S;
90
91/* Structure containing function pointers to vector operations  */ 
92struct _generic_N_Vector_Ops {
93  N_Vector_ID (*nvgetvectorid)(N_Vector);
94  N_Vector    (*nvclone)(N_Vector);
95  N_Vector    (*nvcloneempty)(N_Vector);
96  void        (*nvdestroy)(N_Vector);
97  void        (*nvspace)(N_Vector, sunindextype *, sunindextype *);
98  realtype*   (*nvgetarraypointer)(N_Vector);
99  void        (*nvsetarraypointer)(realtype *, N_Vector);
100  void        (*nvlinearsum)(realtype, N_Vector, realtype, N_Vector, N_Vector);
101  void        (*nvconst)(realtype, N_Vector);
102  void        (*nvprod)(N_Vector, N_Vector, N_Vector);
103  void        (*nvdiv)(N_Vector, N_Vector, N_Vector);
104  void        (*nvscale)(realtype, N_Vector, N_Vector);
105  void        (*nvabs)(N_Vector, N_Vector);
106  void        (*nvinv)(N_Vector, N_Vector);
107  void        (*nvaddconst)(N_Vector, realtype, N_Vector);
108  realtype    (*nvdotprod)(N_Vector, N_Vector);
109  realtype    (*nvmaxnorm)(N_Vector);
110  realtype    (*nvwrmsnorm)(N_Vector, N_Vector);
111  realtype    (*nvwrmsnormmask)(N_Vector, N_Vector, N_Vector);
112  realtype    (*nvmin)(N_Vector);
113  realtype    (*nvwl2norm)(N_Vector, N_Vector);
114  realtype    (*nvl1norm)(N_Vector);
115  void        (*nvcompare)(realtype, N_Vector, N_Vector);
116  booleantype (*nvinvtest)(N_Vector, N_Vector);
117  booleantype (*nvconstrmask)(N_Vector, N_Vector, N_Vector);
118  realtype    (*nvminquotient)(N_Vector, N_Vector);
119};
120
121/*
122 * -----------------------------------------------------------------
123 * A vector is a structure with an implementation-dependent
124 * 'content' field, and a pointer to a structure of vector
125 * operations corresponding to that implementation.
126 * -----------------------------------------------------------------
127 */
128
129struct _generic_N_Vector {
130  void *content;
131  struct _generic_N_Vector_Ops *ops;
132};
133 
134/*
135 * -----------------------------------------------------------------
136 * Functions exported by NVECTOR module
137 * -----------------------------------------------------------------
138 */
139
140/*
141 * -----------------------------------------------------------------
142 * N_VGetVectorID
143 *   Returns an identifier for the vector type from enumeration
144 *   N_Vector_ID.
145 *
146 * N_VClone
147 *   Creates a new vector of the same type as an existing vector.
148 *   It does not copy the vector, but rather allocates storage for
149 *   the new vector.
150 *
151 * N_VCloneEmpty
152 *   Creates a new vector of the same type as an existing vector,
153 *   but does not allocate storage.
154 *
155 * N_VDestroy
156 *   Destroys a vector created with N_VClone.
157 *
158 * N_VSpace
159 *   Returns space requirements for one N_Vector (type 'realtype' in
160 *   lrw and type 'sunindextype' in liw).
161 *
162 * N_VGetArrayPointer
163 *   Returns a pointer to the data component of the given N_Vector.
164 *   NOTE: This function assumes that the internal data is stored
165 *   as a contiguous 'realtype' array. This routine is only used in
166 *   the solver-specific interfaces to the dense and banded linear
167 *   solvers, as well as the interfaces to  the banded preconditioners
168 *   distributed with SUNDIALS.
169 *   
170 * N_VSetArrayPointer
171 *   Overwrites the data field in the given N_Vector with a user-supplied
172 *   array of type 'realtype'.
173 *   NOTE: This function assumes that the internal data is stored
174 *   as a contiguous 'realtype' array. This routine is only used in
175 *   the interfaces to the dense linear solver.
176 *
177 * N_VLinearSum
178 *   Performs the operation z = a*x + b*y
179 *
180 * N_VConst
181 *   Performs the operation z[i] = c for i = 0, 1, ..., N-1
182 *
183 * N_VProd
184 *   Performs the operation z[i] = x[i]*y[i] for i = 0, 1, ..., N-1
185 *
186 * N_VDiv
187 *   Performs the operation z[i] = x[i]/y[i] for i = 0, 1, ..., N-1
188 *
189 * N_VScale
190 *   Performs the operation z = c*x
191 *
192 * N_VAbs
193 *   Performs the operation z[i] = |x[i]| for i = 0, 1, ..., N-1
194 *
195 * N_VInv
196 *   Performs the operation z[i] = 1/x[i] for i = 0, 1, ..., N-1
197 *   This routine does not check for division by 0. It should be
198 *   called only with an N_Vector x which is guaranteed to have
199 *   all non-zero components.
200 *
201 * N_VAddConst
202 *   Performs the operation z[i] = x[i] + b   for i = 0, 1, ..., N-1
203 *
204 * N_VDotProd
205 *   Returns the dot product of two vectors:
206 *         sum (i = 0 to N-1) {x[i]*y[i]}
207 *
208 * N_VMaxNorm
209 *   Returns the maximum norm of x:
210 *         max (i = 0 to N-1) ABS(x[i])
211 *
212 * N_VWrmsNorm
213 *   Returns the weighted root mean square norm of x with weight
214 *   vector w:
215 *         sqrt [(sum (i = 0 to N-1) {(x[i]*w[i])^2})/N]
216 *
217 * N_VWrmsNormMask
218 *   Returns the weighted root mean square norm of x with weight
219 *   vector w, masked by the elements of id:
220 *         sqrt [(sum (i = 0 to N-1) {(x[i]*w[i]*msk[i])^2})/N]
221 *   where msk[i] = 1.0 if id[i] > 0 and
222 *         msk[i] = 0.0 if id[i] < 0
223 *
224 * N_VMin
225 *   Returns the smallest element of x:
226 *         min (i = 0 to N-1) x[i]
227 *
228 * N_VWL2Norm
229 *   Returns the weighted Euclidean L2 norm of x with weight
230 *   vector w:
231 *         sqrt [(sum (i = 0 to N-1) {(x[i]*w[i])^2})]
232 *
233 * N_VL1Norm
234 *   Returns the L1 norm of x:
235 *         sum (i = 0 to N-1) {ABS(x[i])}
236 *
237 * N_VCompare
238 *   Performs the operation
239 *          z[i] = 1.0 if ABS(x[i]) >= c   i = 0, 1, ..., N-1
240 *                 0.0 otherwise
241 *
242 * N_VInvTest
243 *   Performs the operation z[i] = 1/x[i] with a test for
244 *   x[i] == 0.0 before inverting x[i].
245 *   This routine returns SUNTRUE if all components of x are non-zero
246 *   (successful inversion) and returns SUNFALSE otherwise.
247 *
248 * N_VConstrMask
249 *   Performs the operation :
250 *       m[i] = 1.0 if constraint test fails for x[i]
251 *       m[i] = 0.0 if constraint test passes for x[i]
252 *   where the constraint tests are as follows:
253 *      If c[i] = +2.0, then x[i] must be >  0.0.
254 *      If c[i] = +1.0, then x[i] must be >= 0.0.
255 *      If c[i] = -1.0, then x[i] must be <= 0.0.
256 *      If c[i] = -2.0, then x[i] must be <  0.0.
257 *   This routine returns a boolean SUNFALSE if any element failed
258 *   the constraint test, SUNTRUE if all passed. It also sets a
259 *   mask vector m, with elements equal to 1.0 where the
260 *   corresponding constraint test failed, and equal to 0.0
261 *   where the constraint test passed.
262 *   This routine is specialized in that it is used only for
263 *   constraint checking.
264 *
265 * N_VMinQuotient
266 *   Performs the operation :
267 *       minq  = min ( num[i]/denom[i]) over all i such that   
268 *       denom[i] != 0.
269 *   This routine returns the minimum of the quotients obtained
270 *   by term-wise dividing num[i] by denom[i]. A zero element
271 *   in denom will be skipped. If no such quotients are found,
272 *   then the large value BIG_REAL is returned.
273 *
274 * -----------------------------------------------------------------
275 *
276 * The following table lists the vector functions used by
277 * different modules in SUNDIALS. The symbols in the table
278 * have the following meaning:
279 * S    -  called by the solver;
280 * D    -  called by the dense linear solver module
281 * B    -  called by the band linear solver module
282 * Di   -  called by the diagonal linear solver module
283 * I    -  called by the iterative linear solver module
284 * BP   -  called by the band preconditioner module
285 * BBDP -  called by the band-block diagonal preconditioner module
286 * F    -  called by the Fortran-to-C interface
287 *
288 *                  ------------------------------------------------
289 *                                         MODULES                 
290 * NVECTOR          ------------------------------------------------
291 * FUNCTIONS          CVODE/CVODES          IDA             KINSOL   
292 * -----------------------------------------------------------------
293 * N_VGetVectorID     
294 * -----------------------------------------------------------------
295 * N_VClone           S Di I                S I BBDP        S I BBDP
296 * -----------------------------------------------------------------
297 * N_VCloneEmpty      F                     F               F
298 * -----------------------------------------------------------------
299 * N_VDestroy         S Di I                S I BBDP        S I BBDP
300 * -----------------------------------------------------------------
301 * N_VSpace           S                     S               S         
302 * -----------------------------------------------------------------
303 * N_VGetArrayPointer D B BP BBDP F         D B BBDP        BBDP F     
304 * -----------------------------------------------------------------
305 * N_VSetArrayPointer D F                   D               F
306 * -----------------------------------------------------------------
307 * N_VLinearSum       S D Di I              S D I           S I       
308 * -----------------------------------------------------------------
309 * N_VConst           S I                   S I             I       
310 * -----------------------------------------------------------------
311 * N_VProd            S Di I                S I             S I       
312 * -----------------------------------------------------------------
313 * N_VDiv             S Di I                S I             S I
314 * -----------------------------------------------------------------
315 * N_VScale           S D B Di I BP BBDP    S D B I BBDP    S I BBDP 
316 * -----------------------------------------------------------------
317 * N_VAbs             S                     S               S         
318 * -----------------------------------------------------------------
319 * N_VInv             S Di                  S               S         
320 * -----------------------------------------------------------------
321 * N_VAddConst        S Di                  S                       
322 * -----------------------------------------------------------------
323 * N_VDotProd         I                     I               I         
324 * -----------------------------------------------------------------
325 * N_VMaxNorm         S                     S               S         
326 * -----------------------------------------------------------------
327 * N_VWrmsNorm        S D B I BP BBDP       S                         
328 * -----------------------------------------------------------------
329 * N_VWrmsNormMask                          S                         
330 * -----------------------------------------------------------------
331 * N_VMin             S                     S               S         
332 * -----------------------------------------------------------------
333 * N_VWL2Norm                                               S I       
334 * -----------------------------------------------------------------
335 * N_VL1Norm                                                I
336 * -----------------------------------------------------------------
337 * N_VCompare         Di                    S                         
338 * -----------------------------------------------------------------
339 * N_VInvTest         Di                                             
340 * -----------------------------------------------------------------
341 * N_VConstrMask                            S               S         
342 * -----------------------------------------------------------------
343 * N_VMinQuotient                           S               S         
344 * -----------------------------------------------------------------
345 */
346 
347SUNDIALS_EXPORT N_Vector_ID N_VGetVectorID(N_Vector w);
348SUNDIALS_EXPORT N_Vector N_VClone(N_Vector w);
349SUNDIALS_EXPORT N_Vector N_VCloneEmpty(N_Vector w);
350SUNDIALS_EXPORT void N_VDestroy(N_Vector v);
351SUNDIALS_EXPORT void N_VSpace(N_Vector v, sunindextype *lrw, sunindextype *liw);
352SUNDIALS_EXPORT realtype *N_VGetArrayPointer(N_Vector v);
353SUNDIALS_EXPORT void N_VSetArrayPointer(realtype *v_data, N_Vector v);
354SUNDIALS_EXPORT void N_VLinearSum(realtype a, N_Vector x, realtype b, N_Vector y, N_Vector z);
355SUNDIALS_EXPORT void N_VConst(realtype c, N_Vector z);
356SUNDIALS_EXPORT void N_VProd(N_Vector x, N_Vector y, N_Vector z);
357SUNDIALS_EXPORT void N_VDiv(N_Vector x, N_Vector y, N_Vector z);
358SUNDIALS_EXPORT void N_VScale(realtype c, N_Vector x, N_Vector z);
359SUNDIALS_EXPORT void N_VAbs(N_Vector x, N_Vector z);
360SUNDIALS_EXPORT void N_VInv(N_Vector x, N_Vector z);
361SUNDIALS_EXPORT void N_VAddConst(N_Vector x, realtype b, N_Vector z);
362SUNDIALS_EXPORT realtype N_VDotProd(N_Vector x, N_Vector y);
363SUNDIALS_EXPORT realtype N_VMaxNorm(N_Vector x);
364SUNDIALS_EXPORT realtype N_VWrmsNorm(N_Vector x, N_Vector w);
365SUNDIALS_EXPORT realtype N_VWrmsNormMask(N_Vector x, N_Vector w, N_Vector id);
366SUNDIALS_EXPORT realtype N_VMin(N_Vector x);
367SUNDIALS_EXPORT realtype N_VWL2Norm(N_Vector x, N_Vector w);
368SUNDIALS_EXPORT realtype N_VL1Norm(N_Vector x);
369SUNDIALS_EXPORT void N_VCompare(realtype c, N_Vector x, N_Vector z);
370SUNDIALS_EXPORT booleantype N_VInvTest(N_Vector x, N_Vector z);
371SUNDIALS_EXPORT booleantype N_VConstrMask(N_Vector c, N_Vector x, N_Vector m);
372SUNDIALS_EXPORT realtype N_VMinQuotient(N_Vector num, N_Vector denom);
373
374/*
375 * -----------------------------------------------------------------
376 * Additional functions exported by NVECTOR module
377 * -----------------------------------------------------------------
378 */
379
380/*
381 * -----------------------------------------------------------------
382 * N_VCloneEmptyVectorArray
383 *   Creates (by cloning 'w') an array of 'count' empty N_Vectors
384 *
385 * N_VCloneVectorArray
386 *   Creates (by cloning 'w') an array of 'count' N_Vectors
387 *
388 * N_VDestroyVectorArray
389 *   Frees memory for an array of 'count' N_Vectors that was
390 *   created by a call to N_VCloneVectorArray
391 *
392 * These functions are used by the SPGMR iterative linear solver
393 * module and by the CVODES and IDAS solvers.
394 * -----------------------------------------------------------------
395 */
396
397SUNDIALS_EXPORT N_Vector *N_VCloneEmptyVectorArray(int count, N_Vector w);
398SUNDIALS_EXPORT N_Vector *N_VCloneVectorArray(int count, N_Vector w);
399SUNDIALS_EXPORT void N_VDestroyVectorArray(N_Vector *vs, int count);
400
401#ifdef __cplusplus
402}
403#endif
404
405#endif
Note: See TracBrowser for help on using the repository browser.