source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/cvodes/cvodes.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: 84.6 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * $Revision$
4 * $Date$
5 * -----------------------------------------------------------------
6 * Programmer(s): Radu Serban @ 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 interface file for the main CVODES integrator.
19 * -----------------------------------------------------------------
20 *
21 * CVODES is used to solve numerically the ordinary initial value   
22 * problem:                                                         
23 *                                                                   
24 *                 y' = f(t,y),                                     
25 *                 y(t0) = y0,                                       
26 *                                                                   
27 * where t0, y0 in R^N, and f: R x R^N -> R^N are given.             
28 *                                                                   
29 * Optionally, CVODES can perform forward or adjoint sensitivity
30 * analysis to find sensitivities of the solution y with respect
31 * to parameters in the right hand side f and/or in the initial         
32 * conditions y0.                                                   
33 *
34 * -----------------------------------------------------------------
35 *
36 *  1: CONSTANTS
37 *     input constants
38 *     return flags
39 *
40 *  2: FUNCTION TYPES
41 *     CVRhsFn CVQuadRhsFn CVSensRhsFn CVSensRhs1Fn CVQuadSensRhsFn
42 *     CVRootFn
43 *     CVEwtFn
44 *     CVErrHandlerFn
45 *     CVRhsFnB     CVRhsFnBS
46 *     CVQuadRhsFnB CVQuadRhsFnBS
47 *     
48 *  3: INITIALIZATION AND DEALLOCATION FUNCTIONS FOR FORWARD PROBLEMS
49 *     CVodeCreate
50 *     CVodeInit        CVodeReInit
51 *     CVodeQuadInit    CVodeQuadReInit
52 *     CVodeSensInit    CVodeSensReInit
53 *     CVodeRootInit
54 *     CVodeFree          CVodeQuadFree      CVodeSensFree
55 *   
56 *  4: OPTIONAL INPUT FUNCTIONS FOR FORWARD PROBLEMS   
57 *   
58 *  5: MAIN SOLVER FUNCTION FOR FORWARD PROBLEMS
59 *     CVode
60 *
61 *  6: EXTRACTION AND DENSE OUTPUT FUNCTIONS FOR FORWARD PROBLEMS
62 *     CVodeGetDky
63 *     CVodeGetQuad
64 *     CVodeGetQuadDky
65 *     CVodeGetSens      CVodeGetSens1
66 *     CVodeGetSensDky   CVodeGetSensDky1
67 *     CVodeGetQuadSens      CVodeGetQuadSens1
68 *     CVodeGetQuadSensDky   CVodeGetQuadSensDky1
69 *   
70 *  7: OPTIONAL OUTPUT FUNCTIONS FOR FORWARD PROBLEMS
71 *   
72 *  8: INITIALIZATION AND DEALLOCATION FUNCTIONS FOR BACKWARD PROBLEMS 
73 *     CVodeAdjInit    CVodeAdjReInit
74 *     CVodeAdjFree
75 *     CVodeInitB      CVodeInitBS       CVodeReInitB
76 *     CVodeQuadInitB  CVodeQuadInitBS   CVodeQuadReInitB
77 *     
78 *  9  MAIN SOLVER FUNCTIONS FOR FORWARD PROBLEMS
79 *     CVodeF
80 *     CVodeB
81 *   
82 * 10: OPTIONAL INPUT FUNCTIONS FOR BACKWARD PROBLEMS 
83 *   
84 * 11: EXTRACTION AND DENSE OUTPUT FUNCTIONS FOR BACKWARD PROBLEMS 
85 *     CVodeGetB
86 *     CVodeGetQuadB
87 *   
88 * 12: OPTIONAL OUTPUT FUNCTIONS FOR BACKWARD PROBLEMS   
89 *
90 * -----------------------------------------------------------------
91 */
92
93#ifndef _CVODES_H
94#define _CVODES_H
95
96#include <stdio.h>
97#include <sundials/sundials_nvector.h>
98
99#ifdef __cplusplus  /* wrapper to enable C++ usage */
100extern "C" {
101#endif
102
103/*
104 * =================================================================
105 *
106 * CVODES CONSTANTS
107 *
108 * =================================================================
109 */
110
111/*
112 * -----------------------------------------------------------------
113 * Enumerations for inputs to:
114 * CVodeCreate (lmm, iter),
115 * CVodeSensInit, CvodeSensinit1, CVodeSensReInit (ism),
116 * CVodeAdjInit (interp),
117 * CVode (itask)
118 * -----------------------------------------------------------------
119 * Symbolic constants for the lmm and iter parameters to CVodeCreate
120 * the input parameter itask to CVode, and the input parameter interp
121 * to CVodeAdjInit, are given below.
122 *
123 * lmm:   The user of the CVODES package specifies whether to use
124 *        the CV_ADAMS or CV_BDF (backward differentiation formula)
125 *        linear multistep method. The BDF method is recommended
126 *        for stiff problems, and the CV_ADAMS method is recommended
127 *        for nonstiff problems.
128 *
129 * iter:  At each internal time step, a nonlinear equation must
130 *        be solved. The user can specify either CV_FUNCTIONAL
131 *        iteration, which does not require linear algebra, or a
132 *        CV_NEWTON iteration, which requires the solution of linear
133 *        systems. In the CV_NEWTON case, the user also specifies a
134 *        CVODE linear solver. CV_NEWTON is recommended in case of
135 *        stiff problems.
136 *
137 * ism:   This parameter specifies the sensitivity corrector type
138 *        to be used. In the CV_SIMULTANEOUS case, the nonlinear
139 *        systems for states and all sensitivities are solved
140 *        simultaneously. In the CV_STAGGERED case, the nonlinear
141 *        system for states is solved first and then, the
142 *        nonlinear systems for all sensitivities are solved
143 *        at the same time. Finally, in the CV_STAGGERED1 approach
144 *        all nonlinear systems are solved in a sequence.
145 *
146 * itask: The itask input parameter to CVode indicates the job
147 *        of the solver for the next user step. The CV_NORMAL
148 *        itask is to have the solver take internal steps until
149 *        it has reached or just passed the user specified tout
150 *        parameter. The solver then interpolates in order to
151 *        return an approximate value of y(tout). The CV_ONE_STEP
152 *        option tells the solver to just take one internal step
153 *        and return the solution at the point reached by that step.
154 *
155 * interp: Specifies the interpolation type used to evaluate the
156 *        forward solution during the backward integration phase.
157 *        CV_HERMITE specifies cubic Hermite interpolation.
158 *        CV_POYNOMIAL specifies the polynomial interpolation
159 * -----------------------------------------------------------------
160 */
161
162/* lmm */
163#define CV_ADAMS          1
164#define CV_BDF            2
165
166/* iter */
167#define CV_FUNCTIONAL     1
168#define CV_NEWTON         2
169
170/* itask */
171#define CV_NORMAL         1
172#define CV_ONE_STEP       2
173
174/* ism */
175#define CV_SIMULTANEOUS   1
176#define CV_STAGGERED      2
177#define CV_STAGGERED1     3
178
179/* DQtype */
180#define CV_CENTERED       1
181#define CV_FORWARD        2
182
183/* interp */
184#define CV_HERMITE        1
185#define CV_POLYNOMIAL     2
186
187/*
188 * ----------------------------------------
189 * CVODES return flags
190 * ----------------------------------------
191 */
192
193#define CV_SUCCESS               0
194#define CV_TSTOP_RETURN          1
195#define CV_ROOT_RETURN           2
196
197#define CV_WARNING              99
198
199#define CV_TOO_MUCH_WORK        -1
200#define CV_TOO_MUCH_ACC         -2
201#define CV_ERR_FAILURE          -3
202#define CV_CONV_FAILURE         -4
203
204#define CV_LINIT_FAIL           -5
205#define CV_LSETUP_FAIL          -6
206#define CV_LSOLVE_FAIL          -7
207#define CV_RHSFUNC_FAIL         -8
208#define CV_FIRST_RHSFUNC_ERR    -9
209#define CV_REPTD_RHSFUNC_ERR    -10
210#define CV_UNREC_RHSFUNC_ERR    -11
211#define CV_RTFUNC_FAIL          -12
212#define CV_CONSTR_FAIL          -13
213
214#define CV_MEM_FAIL             -20
215#define CV_MEM_NULL             -21
216#define CV_ILL_INPUT            -22
217#define CV_NO_MALLOC            -23
218#define CV_BAD_K                -24
219#define CV_BAD_T                -25
220#define CV_BAD_DKY              -26
221#define CV_TOO_CLOSE            -27
222
223#define CV_NO_QUAD              -30
224#define CV_QRHSFUNC_FAIL        -31
225#define CV_FIRST_QRHSFUNC_ERR   -32
226#define CV_REPTD_QRHSFUNC_ERR   -33
227#define CV_UNREC_QRHSFUNC_ERR   -34
228
229#define CV_NO_SENS              -40
230#define CV_SRHSFUNC_FAIL        -41
231#define CV_FIRST_SRHSFUNC_ERR   -42
232#define CV_REPTD_SRHSFUNC_ERR   -43
233#define CV_UNREC_SRHSFUNC_ERR   -44
234
235#define CV_BAD_IS               -45
236
237#define CV_NO_QUADSENS          -50
238#define CV_QSRHSFUNC_FAIL       -51
239#define CV_FIRST_QSRHSFUNC_ERR  -52
240#define CV_REPTD_QSRHSFUNC_ERR  -53
241#define CV_UNREC_QSRHSFUNC_ERR  -54
242
243/*
244 * ----------------------------------------
245 * CVODEA return flags
246 * ----------------------------------------
247 */
248
249#define CV_NO_ADJ              -101
250#define CV_NO_FWD              -102
251#define CV_NO_BCK              -103
252#define CV_BAD_TB0             -104
253#define CV_REIFWD_FAIL         -105
254#define CV_FWD_FAIL            -106
255#define CV_GETY_BADT           -107
256
257/*
258 * =================================================================
259 *
260 * FUNCTION TYPES
261 *
262 * =================================================================
263 */
264
265/*
266 * -----------------------------------------------------------------
267 * Type : CVRhsFn
268 * -----------------------------------------------------------------
269 * The f function which defines the right hand side of the ODE
270 * system y' = f(t,y) must have type CVRhsFn.
271 * f takes as input the independent variable value t, and the
272 * dependent variable vector y.  It stores the result of f(t,y)
273 * in the vector ydot.  The y and ydot arguments are of type
274 * N_Vector.
275 * (Allocation of memory for ydot is handled within CVODES)
276 * The user_data parameter is the same as the user_data
277 * parameter set by the user through the CVodeSetUserData routine.
278 * This user-supplied pointer is passed to the user's f function
279 * every time it is called.
280 *
281 * A CVRhsFn should return 0 if successful, a negative value if
282 * an unrecoverable error occured, and a positive value if a
283 * recoverable error (e.g. invalid y values) occured.
284 * If an unrecoverable occured, the integration is halted.
285 * If a recoverable error occured, then (in most cases) CVODES
286 * will try to correct and retry.
287 * -----------------------------------------------------------------
288 */
289
290typedef int (*CVRhsFn)(realtype t, N_Vector y,
291           N_Vector ydot, void *user_data);
292
293/*
294 * -----------------------------------------------------------------
295 * Type : CVRootFn
296 * -----------------------------------------------------------------
297 * A function g, which defines a set of functions g_i(t,y) whose
298 * roots are sought during the integration, must have type CVRootFn.
299 * The function g takes as input the independent variable value
300 * t, and the dependent variable vector y.  It stores the nrtfn
301 * values g_i(t,y) in the realtype array gout.
302 * (Allocation of memory for gout is handled within CVODE.)
303 * The user_data parameter is the same as that passed by the user
304 * to the CVodeSetUserData routine.  This user-supplied pointer is
305 * passed to the user's g function every time it is called.
306 *
307 * A CVRootFn should return 0 if successful or a non-zero value
308 * if an error occured (in which case the integration will be halted).
309 * -----------------------------------------------------------------
310 */
311
312typedef int (*CVRootFn)(realtype t, N_Vector y, realtype *gout, void *user_data);
313
314/*
315 * -----------------------------------------------------------------
316 * Type : CVEwtFn
317 * -----------------------------------------------------------------
318 * A function e, which sets the error weight vector ewt, must have
319 * type CVEwtFn.
320 * The function e takes as input the current dependent variable y.
321 * It must set the vector of error weights used in the WRMS norm:
322 *
323 *   ||y||_WRMS = sqrt [ 1/N * sum ( ewt_i * y_i)^2 ]
324 *
325 * Typically, the vector ewt has components:
326 *
327 *   ewt_i = 1 / (reltol * |y_i| + abstol_i)
328 *
329 * The user_data parameter is the same as that passed by the user
330 * to the CVodeSetUserData routine.  This user-supplied pointer is
331 * passed to the user's e function every time it is called.
332 * A CVEwtFn e must return 0 if the error weight vector has been
333 * successfuly set and a non-zero value otherwise.
334 * -----------------------------------------------------------------
335 */
336
337typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void *user_data);
338
339
340/*
341 * -----------------------------------------------------------------
342 * Type : CVErrHandlerFn
343 * -----------------------------------------------------------------
344 * A function eh, which handles error messages, must have type
345 * CVErrHandlerFn.
346 * The function eh takes as input the error code, the name of the
347 * module reporting the error, the error message, and a pointer to
348 * user data, the same as that passed to CVodeSetUserData.
349 *
350 * All error codes are negative, except CV_WARNING which indicates
351 * a warning (the solver continues).
352 *
353 * A CVErrHandlerFn has no return value.
354 * -----------------------------------------------------------------
355 */
356 
357typedef void (*CVErrHandlerFn)(int error_code,
358             const char *module, const char *function,
359             char *msg, void *user_data);
360
361/*
362 * -----------------------------------------------------------------
363 * Type : CVQuadRhsFn
364 * -----------------------------------------------------------------
365 * The fQ function which defines the right hand side of the
366 * quadrature equations yQ' = fQ(t,y) must have type CVQuadRhsFn.
367 * fQ takes as input the value of the independent variable t,
368 * the vector of states y and must store the result of fQ in
369 * yQdot. (Allocation of memory for yQdot is handled by CVODES).
370 * The user_data parameter is the same as the user_data parameter
371 * set by the user through the CVodeSetUserData routine and is
372 * passed to the fQ function every time it is called.
373 *
374 * If the quadrature RHS also depends on the sensitivity variables,
375 * i.e., yQ' = fQs(t,y,yS), then fQ must be of type CVodeQuadRhsFnS.
376 *
377 * A CVQuadRhsFn or CVodeQuadRhsFnS should return 0 if successful,
378 * a negative value if an unrecoverable error occured, and a positive
379 * value if a recoverable error (e.g. invalid y values) occured.
380 * If an unrecoverable occured, the integration is halted.
381 * If a recoverable error occured, then (in most cases) CVODES
382 * will try to correct and retry.
383 * -----------------------------------------------------------------
384 */
385
386typedef int (*CVQuadRhsFn)(realtype t, N_Vector y,
387                           N_Vector yQdot,
388         void *user_data);
389
390/*
391 * -----------------------------------------------------------------
392 * Type : CVSensRhsFn
393 * -----------------------------------------------------------------
394 * The fS function which defines the right hand side of the
395 * sensitivity ODE systems s' = f_y * s + f_p must have type
396 * CVSensRhsFn.
397 * fS takes as input the number of sensitivities Ns, the
398 * independent variable value t, the states y and the
399 * corresponding value of f(t,y) in ydot, and the dependent
400 * sensitivity vectors yS. It stores the result of fS in ySdot.
401 * (Allocation of memory for ySdot is handled within CVODES)
402 * The user_data parameter is the same as the user_data parameter
403 * set by the user through the CVodeSetUserData routine and is
404 * passed to the fS function every time it is called.
405 *
406 * A CVSensRhsFn should return 0 if successful, a negative value if
407 * an unrecoverable error occured, and a positive value if a
408 * recoverable error (e.g. invalid y or yS values) occured.
409 * If an unrecoverable occured, the integration is halted.
410 * If a recoverable error occured, then (in most cases) CVODES
411 * will try to correct and retry.
412 * -----------------------------------------------------------------
413 */
414
415typedef int (*CVSensRhsFn)(int Ns, realtype t,
416         N_Vector y, N_Vector ydot,
417         N_Vector *yS, N_Vector *ySdot,
418         void *user_data,
419         N_Vector tmp1, N_Vector tmp2);
420
421/*
422 * -----------------------------------------------------------------
423 * Type : CVSensRhs1Fn
424 * -----------------------------------------------------------------
425 * The fS1 function which defines the right hand side of the i-th
426 * sensitivity ODE system s_i' = f_y * s_i + f_p must have type
427 * CVSensRhs1Fn.
428 * fS1 takes as input the number of sensitivities Ns, the current
429 * sensitivity iS, the independent variable value t, the states y
430 * and the corresponding value of f(t,y) in ydot, and the
431 * dependent sensitivity vector yS. It stores the result of fS in
432 * ySdot.
433 * (Allocation of memory for ySdot is handled within CVODES)
434 * The user_data parameter is the same as the user_data parameter
435 * set by the user through the CVodeSetUserData routine and is
436 * passed to the fS1 function every time it is called.
437 *
438 * A CVSensRhs1Fn should return 0 if successful, a negative value if
439 * an unrecoverable error occured, and a positive value if a
440 * recoverable error (e.g. invalid y or yS values) occured.
441 * If an unrecoverable occured, the integration is halted.
442 * If a recoverable error occured, then (in most cases) CVODES
443 * will try to correct and retry.
444 * -----------------------------------------------------------------
445 */
446
447typedef int (*CVSensRhs1Fn)(int Ns, realtype t,
448          N_Vector y, N_Vector ydot,
449          int iS, N_Vector yS, N_Vector ySdot,
450          void *user_data,
451          N_Vector tmp1, N_Vector tmp2);
452
453/*
454 * -----------------------------------------------------------------
455 * Type : CVQuadSensRhsFn
456 * -----------------------------------------------------------------
457 * The fQS function which defines the right hand side of the
458 * sensitivity ODE systems for quadratures, yQS' = fQ_y * yS + fQ_p
459 * must have type CVQuadSensRhsFn.
460 *
461 * fQS takes as input the number of sensitivities Ns (the same as
462 * that passed to CVodeQuadSensInit), the independent variable
463 * value t, the states y and the dependent sensitivity vectors yS,
464 * as well as the current value of the quadrature RHS yQdot.
465 * It stores the result of fQS in yQSdot.
466 * (Allocation of memory for yQSdot is handled within CVODES)
467 *
468 * A CVQuadSensRhsFn should return 0 if successful, a negative
469 * value if an unrecoverable error occured, and a positive value
470 * if a recoverable error (e.g. invalid y or yS values) occured.
471 * If an unrecoverable occured, the integration is halted.
472 * If a recoverable error occured, then (in most cases) CVODES
473 * will try to correct and retry.
474 * -----------------------------------------------------------------
475 */
476
477typedef int (*CVQuadSensRhsFn)(int Ns, realtype t,
478                               N_Vector y, N_Vector *yS,
479                               N_Vector yQdot, N_Vector *yQSdot,
480                               void *user_data,
481                               N_Vector tmp, N_Vector tmpQ);
482
483/*
484 * -----------------------------------------------------------------
485 * CVRhsFnB and CVRhsFnBS
486 *    The fB function which defines the right hand side of the
487 *    ODE systems to be integrated backwards must have type CVRhsFnB.
488 *    If the backward problem depends on forward sensitivities, its
489 *    RHS function must have type CVRhsFnBS.
490 * -----------------------------------------------------------------
491 * CVQuadRhsFnB and CVQuadRhsFnBS
492 *    The fQB function which defines the quadratures to be integrated
493 *    backwards must have type CVQuadRhsFnB.
494 *    If the backward problem depends on forward sensitivities, its
495 *    quadrature RHS function must have type CVQuadRhsFnBS.
496 * -----------------------------------------------------------------
497 */
498 
499typedef int (*CVRhsFnB)(realtype t, N_Vector y,
500      N_Vector yB, N_Vector yBdot,
501      void *user_dataB);
502
503typedef int (*CVRhsFnBS)(realtype t, N_Vector y, N_Vector *yS,
504                         N_Vector yB, N_Vector yBdot,
505                         void *user_dataB);
506
507 
508typedef int (*CVQuadRhsFnB)(realtype t, N_Vector y,
509          N_Vector yB, N_Vector qBdot,
510          void *user_dataB);
511
512typedef int (*CVQuadRhsFnBS)(realtype t, N_Vector y, N_Vector *yS,
513                             N_Vector yB, N_Vector qBdot,
514                             void *user_dataB);
515
516
517/*
518 * =================================================================
519 *
520 * INITIALIZATION AND DEALLOCATION FUNCTIONS FOR FORWARD PROBLEMS
521 *
522 * =================================================================
523 */
524
525/*
526 * -----------------------------------------------------------------
527 * Function : CVodeCreate
528 * -----------------------------------------------------------------
529 * CVodeCreate creates an internal memory block for a problem to
530 * be solved by CVODES.
531 *
532 * lmm  is the type of linear multistep method to be used.
533 *      The legal values are CV_ADAMS and CV_BDF (see previous
534 *      description).
535 *
536 * iter  is the type of iteration used to solve the nonlinear
537 *       system that arises during each internal time step.
538 *       The legal values are CV_FUNCTIONAL and CV_NEWTON.
539 *
540 * If successful, CVodeCreate returns a pointer to initialized
541 * problem memory. This pointer should be passed to CVodeInit.
542 * If an initialization error occurs, CVodeCreate prints an error
543 * message to standard err and returns NULL.
544 * -----------------------------------------------------------------
545 */
546
547SUNDIALS_EXPORT void *CVodeCreate(int lmm, int iter);
548
549/*
550 * -----------------------------------------------------------------
551 * Functions : CVodeInit and CVodeReInit
552 * -----------------------------------------------------------------
553 * CVodeInit allocates and initializes memory for a problem to
554 * to be solved by CVODE.
555 *
556 * CVodeReInit re-initializes CVode for the solution of a problem,
557 * where a prior call to CVodeInit has been made with the same
558 * problem size N. CVodeReInit performs the same input checking
559 * and initializations that CVodeInit does.
560 * But it does no memory allocation, assuming that the existing
561 * internal memory is sufficient for the new problem.
562 *
563 * The use of CVodeReInit requires that the maximum method order,
564 * maxord, is no larger for the new problem than for the problem
565 * specified in the last call to CVodeInit.  This condition is
566 * automatically fulfilled if the multistep method parameter lmm
567 * is unchanged (or changed from CV_ADAMS to CV_BDF) and the default
568 * value for maxord is specified.
569 *
570 * cvode_mem is pointer to CVODE memory returned by CVodeCreate.
571 *
572 * f       is the name of the C function defining the right-hand
573 *         side function in y' = f(t,y).
574 *
575 * t0      is the initial value of t.
576 *
577 * y0      is the initial condition vector y(t0).
578 *
579 * Return flag:
580 *  CV_SUCCESS   if successful
581 *  CV_MEM_NULL  if the cvode memory was NULL
582 *  CV_MEM_FAIL  if a memory allocation failed
583 *  CV_NO_MALLOC if cvode_mem has not been allocated
584 *               (i.e., CVodeInit has not been called).
585 *  CV_ILL_INPUT if an argument has an illegal value.
586 * -----------------------------------------------------------------
587 */
588
589SUNDIALS_EXPORT int CVodeInit(void *cvode_mem, CVRhsFn f, realtype t0, N_Vector y0);
590SUNDIALS_EXPORT int CVodeReInit(void *cvode_mem, realtype t0, N_Vector y0);
591
592/*
593 * -----------------------------------------------------------------
594 * Functions : CVodeSStolerances
595 *             CVodeSVtolerances
596 *             CVodeWFtolerances
597 * -----------------------------------------------------------------
598 *
599 * These functions specify the integration tolerances. One of them
600 * MUST be called before the first call to CVode.
601 *
602 * CVodeSStolerances specifies scalar relative and absolute tolerances.
603 * CVodeSVtolerances specifies scalar relative tolerance and a vector
604 *   absolute tolerance (a potentially different absolute tolerance
605 *   for each vector component).
606 * CVodeWFtolerances specifies a user-provides function (of type CVEwtFn)
607 *   which will be called to set the error weight vector.
608 *
609 * The tolerances reltol and abstol define a vector of error weights,
610 * ewt, with components
611 *   ewt[i] = 1/(reltol*abs(y[i]) + abstol)      (in the SS case), or
612 *   ewt[i] = 1/(reltol*abs(y[i]) + abstol[i])   (in the SV case).
613 * This vector is used in all error and convergence tests, which
614 * use a weighted RMS norm on all error-like vectors v:
615 *    WRMSnorm(v) = sqrt( (1/N) sum(i=1..N) (v[i]*ewt[i])^2 ),
616 * where N is the problem dimension.
617 *
618 * The return value of these functions is equal to CV_SUCCESS = 0 if
619 * there were no errors; otherwise it is a negative int equal to:
620 *   CV_MEM_NULL      indicating cvode_mem was NULL (i.e.,
621 *                    CVodeCreate has not been called).
622 *   CV_NO_MALLOC     indicating that cvode_mem has not been
623 *                    allocated (i.e., CVodeInit has not been
624 *                    called).
625 *   CV_ILL_INPUT     indicating an input argument was illegal
626 *                    (e.g. a negative tolerance)
627 * In case of an error return, an error message is also printed.
628 * -----------------------------------------------------------------
629 */
630
631SUNDIALS_EXPORT int CVodeSStolerances(void *cvode_mem, realtype reltol, realtype abstol);
632SUNDIALS_EXPORT int CVodeSVtolerances(void *cvode_mem, realtype reltol, N_Vector abstol);
633SUNDIALS_EXPORT int CVodeWFtolerances(void *cvode_mem, CVEwtFn efun);
634
635/*
636 * -----------------------------------------------------------------
637 * Function : CVodeQuadInit and CVodeQuadReInit
638 * -----------------------------------------------------------------
639 * CVodeQuadInit allocates and initializes memory related to
640 * quadrature integration.
641 *
642 * CVodeQuadReInit re-initializes CVODES's quadrature related
643 * memory for a problem, assuming it has already been allocated
644 * in prior calls to CVodeInit and CVodeQuadInit.
645 * The number of quadratures Nq is assumed to be unchanged
646 * since the previous call to CVodeQuadInit.
647 *
648 * cvode_mem is a pointer to CVODES memory returned by CVodeCreate
649 *
650 * fQ    is the user-provided integrand routine.
651 *
652 * yQ0   is an N_Vector with initial values for quadratures
653 *       (typically yQ0 has all zero components).
654 *
655 * Return values:
656 *  CV_SUCCESS if successful
657 *  CV_MEM_NULL if the cvode memory was NULL
658 *  CV_MEM_FAIL if a memory allocation failed
659 *  CV_NO_QUAD  if quadratures were not initialized
660 *              (i.e. CVodeQuadInit has not been called)
661 * -----------------------------------------------------------------
662 */
663
664SUNDIALS_EXPORT int CVodeQuadInit(void *cvode_mem, CVQuadRhsFn fQ, N_Vector yQ0);
665SUNDIALS_EXPORT int CVodeQuadReInit(void *cvode_mem, N_Vector yQ0);
666
667/*
668 * -----------------------------------------------------------------
669 * Functions : CVodeQuadSStolerances
670 *             CVodeQuadSVtolerances
671 * -----------------------------------------------------------------
672 *
673 * These functions specify the integration tolerances for quadrature
674 * variables. One of them MUST be called before the first call to
675 * CVode IF error control on the quadrature variables is enabled
676 * (see CVodeSetQuadErrCon).
677 *
678 * CVodeSStolerances specifies scalar relative and absolute tolerances.
679 * CVodeSVtolerances specifies scalar relative tolerance and a vector
680 *   absolute tolerance (a potentially different absolute tolerance
681 *   for each vector component).
682 *
683 * Return values:
684 *  CV_SUCCESS    if successful
685 *  CV_MEM_NULL   if the cvode memory was NULL
686 *  CV_NO_QUAD    if quadratures were not initialized
687 *  CV_ILL_INPUT  if an input argument was illegal
688 *                (e.g. a negative tolerance)
689 * -----------------------------------------------------------------
690 */
691
692SUNDIALS_EXPORT int CVodeQuadSStolerances(void *cvode_mem, realtype reltolQ, realtype abstolQ);
693SUNDIALS_EXPORT int CVodeQuadSVtolerances(void *cvode_mem, realtype reltolQ, N_Vector abstolQ);
694
695/*
696 * -----------------------------------------------------------------
697 * Function : CVodeSensInit, CVSensInit1, and CVodeSensReInit
698 * -----------------------------------------------------------------
699 * CVodeSensInit and CVSensInit1 allocate and initialize memory
700 * related to sensitivity computations. They only differ in the
701 * type of the sensitivity RHS function: CVodeSensInit specifies
702 * fS of type CVSensRhsFn (i.e. a function that evaluates all
703 * sensitivity RHS simultaneously), while CVodeSensInit1 specifies
704 * fS of type CVSensRhs1Fn (i.e. a function that evaluates one
705 * sensitivity RHS at a time). Recall that ism=CV_STAGGERED1 is
706 * compatible ONLY with a CVSensRhs1Fn. As such, this value for
707 * ism cannot be passed to CVodeSensInit.
708 *
709 * CVodeSensReInit re-initializes CVODES's sensitivity related
710 * memory for a problem, assuming it has already been allocated
711 * in prior calls to CVodeInit and CVodeSensInit.
712 * The number of sensitivities Ns is assumed to be unchanged
713 * since the previous call to CVodeSensInit.
714 * If any error occurs during initialization, it is reported to
715 * the file whose file pointer is errfp.
716 * CVodeSensReInit potentially does some minimal memory allocation
717 * (for the sensitivity absolute tolerance and for arrays of
718 * counters used by the CV_STAGGERED1 method).
719
720 * cvode_mem is pointer to CVODES memory returned by CVodeCreate
721 *
722 * Ns        is the number of sensitivities to be computed.
723 *
724 * ism       is the type of corrector used in sensitivity
725 *           analysis. The legal values are: CV_SIMULTANEOUS,
726 *           CV_STAGGERED, and CV_STAGGERED1.
727 *
728 * fS        is the sensitivity righ-hand side function
729 *           (pass NULL to use the internal DQ approximation)
730 *
731 * yS0       is the array of initial condition vectors for
732 *           sensitivity variables.
733 *
734 * Return values:
735 *   CV_SUCCESS
736 *   CV_MEM_NULL
737 *   CV_ILL_INPUT
738 *   CV_MEM_FAIL
739 *   CV_NO_SENS
740 * -----------------------------------------------------------------
741 */
742
743SUNDIALS_EXPORT int CVodeSensInit(void *cvode_mem, int Ns, int ism,
744                                  CVSensRhsFn fS, N_Vector *yS0);
745SUNDIALS_EXPORT int CVodeSensInit1(void *cvode_mem, int Ns, int ism,
746                                   CVSensRhs1Fn fS1, N_Vector *yS0);
747SUNDIALS_EXPORT int CVodeSensReInit(void *cvode_mem, int ism, N_Vector *yS0);
748
749/*
750 * -----------------------------------------------------------------
751 * Functions : CVodeSensSStolerances
752 *             CVodeSensSVtolerances
753 *             CVodeSensEEtolerances
754 * -----------------------------------------------------------------
755 *
756 * These functions specify the integration tolerances for sensitivity
757 * variables. One of them MUST be called before the first call to CVode.
758 *
759 * CVodeSensSStolerances specifies scalar relative and absolute tolerances.
760 * CVodeSensSVtolerances specifies scalar relative tolerance and a vector
761 *   absolute tolerance for each sensitivity vector (a potentially different
762 *   absolute tolerance for each vector component).
763 * CVodeSensEEtolerances specifies that tolerances for sensitivity variables
764 *   should be estimated from those provided for the state variables.
765 *
766 * The return value is equal to CV_SUCCESS = 0 if there were no
767 * errors; otherwise it is a negative int equal to:
768 *   CV_MEM_NULL  indicating cvode_mem was NULL, or
769 *   CV_NO_SENS   indicating there was not a prior call to
770 *                CVodeSensInit.
771 *   CV_ILL_INPUT indicating an input argument was illegal
772 *                (e.g. negative tolerances)
773 * In case of an error return, an error message is also printed.
774 * -----------------------------------------------------------------
775 */
776
777SUNDIALS_EXPORT int CVodeSensSStolerances(void *cvode_mem, realtype reltolS, realtype *abstolS);
778SUNDIALS_EXPORT int CVodeSensSVtolerances(void *cvode_mem, realtype reltolS, N_Vector *abstolS);
779SUNDIALS_EXPORT int CVodeSensEEtolerances(void *cvode_mem);
780
781/*
782 * -----------------------------------------------------------------
783 * Function : CVodeQuadSensInit and CVodeQuadSensReInit
784 * -----------------------------------------------------------------
785 * -----------------------------------------------------------------
786 */
787
788SUNDIALS_EXPORT int CVodeQuadSensInit(void *cvode_mem, CVQuadSensRhsFn fQS, N_Vector *yQS0);
789SUNDIALS_EXPORT int CVodeQuadSensReInit(void *cvode_mem, N_Vector *yQS0);
790
791/*
792 * -----------------------------------------------------------------
793 * Functions : CVodeQuadSensSStolerances
794 *             CVodeQuadSensSVtolerances
795 *             CVodeQuadSensEEtolerances
796 * -----------------------------------------------------------------
797 *
798 * These functions specify the integration tolerances for quadrature
799 * sensitivity variables. One of them MUST be called before the first
800 * call to CVode IF these variables are included in the error test.
801 *
802 * CVodeQuadSensSStolerances specifies scalar relative and absolute tolerances.
803 * CVodeQuadSensSVtolerances specifies scalar relative tolerance and a vector
804 *   absolute tolerance for each quadrature sensitivity vector (a potentially
805 *   different absolute tolerance for each vector component).
806 * CVodeQuadSensEEtolerances specifies that tolerances for sensitivity variables
807 *   should be estimated from those provided for the quadrature variables.
808 *   In this case, tolerances for the quadrature variables must be
809 *   specified through a call to one of CVodeQuad**tolerances.
810 *
811 * The return value is equal to CV_SUCCESS = 0 if there were no
812 * errors; otherwise it is a negative int equal to:
813 *   CV_MEM_NULL     if cvode_mem was NULL, or
814 *   CV_NO_QuadSENS  if there was not a prior call to
815 *                   CVodeQuadSensInit.
816 *   CV_ILL_INPUT    if an input argument was illegal
817 *                   (e.g. negative tolerances)
818 * In case of an error return, an error message is also printed.
819 * -----------------------------------------------------------------
820 */
821
822SUNDIALS_EXPORT int CVodeQuadSensSStolerances(void *cvode_mem, realtype reltolQS, realtype *abstolQS);
823SUNDIALS_EXPORT int CVodeQuadSensSVtolerances(void *cvode_mem, realtype reltolQS, N_Vector *abstolQS);
824SUNDIALS_EXPORT int CVodeQuadSensEEtolerances(void *cvode_mem);
825
826/*
827 * -----------------------------------------------------------------
828 * Function : CVodeRootInit
829 * -----------------------------------------------------------------
830 * CVodeRootInit initializes a rootfinding problem to be solved
831 * during the integration of the ODE system.  It must be called
832 * after CVodeCreate, and before CVode.  The arguments are:
833 *
834 * cvode_mem = pointer to CVODE memory returned by CVodeCreate.
835 *
836 * nrtfn     = number of functions g_i, an int >= 0.
837 *
838 * g         = name of user-supplied function, of type CVRootFn,
839 *             defining the functions g_i whose roots are sought.
840 *
841 * If a new problem is to be solved with a call to CVodeReInit,
842 * where the new problem has no root functions but the prior one
843 * did, then call CVodeRootInit with nrtfn = 0.
844 *
845 * The return value of CVodeRootInit is CV_SUCCESS = 0 if there were
846 * no errors; otherwise it is a negative int equal to:
847 *   CV_MEM_NULL    indicating cvode_mem was NULL, or
848 *   CV_MEM_FAIL    indicating a memory allocation failed.
849 *                  (including an attempt to increase maxord).
850 *   CV_ILL_INPUT   indicating nrtfn > 0 but g = NULL.
851 * In case of an error return, an error message is also printed.
852 * -----------------------------------------------------------------
853 */
854
855SUNDIALS_EXPORT int CVodeRootInit(void *cvode_mem, int nrtfn, CVRootFn g);
856
857/*
858 * -----------------------------------------------------------------
859 * Function : CVodeFree
860 * -----------------------------------------------------------------
861 * CVodeFree frees the problem memory cvode_mem allocated by
862 * CVodeInit.  Its only argument is the pointer cvode_mem
863 * returned by CVodeCreate.
864 * -----------------------------------------------------------------
865 */
866
867SUNDIALS_EXPORT void CVodeFree(void **cvode_mem);
868
869/*
870 * -----------------------------------------------------------------
871 * Function : CVodeQuadFree
872 * -----------------------------------------------------------------
873 * CVodeQuadFree frees the problem memory in cvode_mem allocated
874 * for quadrature integration. Its only argument is the pointer
875 * cvode_mem returned by CVodeCreate.
876 * -----------------------------------------------------------------
877 */
878
879SUNDIALS_EXPORT void CVodeQuadFree(void *cvode_mem);
880
881/*
882 * -----------------------------------------------------------------
883 * Function : CVodeSensFree
884 * -----------------------------------------------------------------
885 * CVodeSensFree frees the problem memory in cvode_mem allocated
886 * for sensitivity analysis. Its only argument is the pointer
887 * cvode_mem returned by CVodeCreate.
888 * -----------------------------------------------------------------
889 */
890
891SUNDIALS_EXPORT void CVodeSensFree(void *cvode_mem);
892
893/*
894 * -----------------------------------------------------------------
895 * Function : CVodeQuadSensFree
896 * -----------------------------------------------------------------
897 * CVodeQuadSensFree frees the problem memory in cvode_mem allocated
898 * for quadrature sensitivity analysis. Its only argument is the
899 * pointer cvode_mem returned by CVodeCreate.
900 * -----------------------------------------------------------------
901 */
902
903SUNDIALS_EXPORT void CVodeQuadSensFree(void *cvode_mem);
904
905/*
906 * =================================================================
907 *
908 * OPTIONAL INPUT FUNCTIONS FOR FORWARD PROBLEMS
909 *
910 * =================================================================
911 */
912
913/*
914 * -----------------------------------------------------------------
915 * Integrator optional input specification functions
916 * -----------------------------------------------------------------
917 * The following functions can be called to set optional inputs
918 * to values other than the defaults given below:
919 *
920 * Function                |  Optional input / [ default value ]
921 * -----------------------------------------------------------------
922 *                         |
923 * CVodeSetErrHandlerFn    | user-provided ErrHandler function.
924 *                         | [internal]
925 *                         |
926 * CVodeSetErrFile         | the file pointer for an error file
927 *                         | where all CVODE warning and error
928 *                         | messages will be written if the default
929 *                         | internal error handling function is used.
930 *                         | This parameter can be stdout (standard
931 *                         | output), stderr (standard error), or a
932 *                         | file pointer (corresponding to a user
933 *                         | error file opened for writing) returned
934 *                         | by fopen.
935 *                         | If not called, then all messages will
936 *                         | be written to the standard error stream.
937 *                         | [stderr]
938 *                         |
939 * CVodeSetUserData        | a pointer to user data that will be
940 *                         | passed to the user's f function every
941 *                         | time f is called.
942 *                         | [NULL]
943 *                         |
944 * CVodeSetMaxOrd          | maximum lmm order to be used by the
945 *                         | solver.
946 *                         | [12 for Adams , 5 for BDF]
947 *                         |
948 * CVodeSetMaxNumSteps     | maximum number of internal steps to be
949 *                         | taken by the solver in its attempt to
950 *                         | reach tout.
951 *                         | [500]
952 *                         |
953 * CVodeSetMaxHnilWarns    | maximum number of warning messages
954 *                         | issued by the solver that t+h==t on the
955 *                         | next internal step. A value of -1 means
956 *                         | no such messages are issued.
957 *                         | [10]
958 *                         |
959 * CVodeSetStabLimDet      | flag to turn on/off stability limit
960 *                         | detection (SUNTRUE = on, SUNFALSE = off).
961 *                         | When BDF is used and order is 3 or
962 *                         | greater, CVsldet is called to detect
963 *                         | stability limit.  If limit is detected,
964 *                         | the order is reduced.
965 *                         | [SUNFALSE]
966 *                         |
967 * CVodeSetInitStep        | initial step size.
968 *                         | [estimated by CVODES]
969 *                         |
970 * CVodeSetMinStep         | minimum absolute value of step size
971 *                         | allowed.
972 *                         | [0.0]
973 *                         |
974 * CVodeSetMaxStep         | maximum absolute value of step size
975 *                         | allowed.
976 *                         | [infinity]
977 *                         |
978 * CVodeSetStopTime        | the independent variable value past
979 *                         | which the solution is not to proceed.
980 *                         | [infinity]
981 *                         |
982 * CVodeSetMaxErrTestFails | Maximum number of error test failures
983 *                         | in attempting one step.
984 *                         | [7]
985 *                         |
986 * CVodeSetMaxNonlinIters  | Maximum number of nonlinear solver
987 *                         | iterations at one solution.
988 *                         | [3]
989 *                         |
990 * CVodeSetMaxConvFails    | Maximum number of allowable conv.
991 *                         | failures in attempting one step.
992 *                         | [10]
993 *                         |
994 * CVodeSetNonlinConvCoef  | Coeficient in the nonlinear conv.
995 *                         | test.
996 *                         | [0.1]
997 *                         |
998 * CVodeSetConstraints     | an N_vector defining inequality
999 *                         | constraints for each component of the
1000 *                         | solution vector y. If a given element
1001 *                         | of this vector has values +2 or -2,
1002 *                         | then the corresponding component of y
1003 *                         | will be constrained to be > 0.0 or
1004 *                         | < 0.0, respectively, while if it is +1
1005 *                         | or -1, the y component is constrained
1006 *                         | to be >= 0.0 or <= 0.0, respectively.
1007 *                         | If a component of constraints is 0.0,
1008 *                         | then no constraint is imposed on the
1009 *                         | corresponding component of y.
1010 *                         | The presence of a non-NULL constraints
1011 *                         | vector that is not 0.0 (ZERO) in all
1012 *                         | components will cause constraint
1013 *                         | checking to be performed.
1014 *                         |
1015 * -----------------------------------------------------------------
1016 *                         |
1017 * CVodeSetIterType        | Changes the current nonlinear iteration
1018 *                         | type.
1019 *                         | [set by CVodecreate]
1020 *                         |
1021 * -----------------------------------------------------------------
1022 *                            |
1023 * CVodeSetRootDirection      | Specifies the direction of zero
1024 *                            | crossings to be monitored
1025 *                            | [both directions]
1026 *                            |
1027 * CVodeSetNoInactiveRootWarn | disable warning about possible
1028 *                            | g==0 at beginning of integration
1029 *                            |
1030 * -----------------------------------------------------------------
1031 * Return flag:
1032 *   CV_SUCCESS   if successful
1033 *   CV_MEM_NULL  if the cvode memory is NULL
1034 *   CV_ILL_INPUT if an argument has an illegal value
1035 * -----------------------------------------------------------------
1036 */
1037
1038SUNDIALS_EXPORT int CVodeSetErrHandlerFn(void *cvode_mem, CVErrHandlerFn ehfun, void *eh_data);
1039SUNDIALS_EXPORT int CVodeSetErrFile(void *cvode_mem, FILE *errfp);
1040SUNDIALS_EXPORT int CVodeSetUserData(void *cvode_mem, void *user_data);
1041SUNDIALS_EXPORT int CVodeSetMaxOrd(void *cvode_mem, int maxord);
1042SUNDIALS_EXPORT int CVodeSetMaxNumSteps(void *cvode_mem, long int mxsteps);
1043SUNDIALS_EXPORT int CVodeSetMaxHnilWarns(void *cvode_mem, int mxhnil);
1044SUNDIALS_EXPORT int CVodeSetStabLimDet(void *cvode_mem, booleantype stldet);
1045SUNDIALS_EXPORT int CVodeSetInitStep(void *cvode_mem, realtype hin);
1046SUNDIALS_EXPORT int CVodeSetMinStep(void *cvode_mem, realtype hmin);
1047SUNDIALS_EXPORT int CVodeSetMaxStep(void *cvode_mem, realtype hmax);
1048SUNDIALS_EXPORT int CVodeSetStopTime(void *cvode_mem, realtype tstop);
1049SUNDIALS_EXPORT int CVodeSetMaxErrTestFails(void *cvode_mem, int maxnef);
1050SUNDIALS_EXPORT int CVodeSetMaxNonlinIters(void *cvode_mem, int maxcor);
1051SUNDIALS_EXPORT int CVodeSetMaxConvFails(void *cvode_mem, int maxncf);
1052SUNDIALS_EXPORT int CVodeSetNonlinConvCoef(void *cvode_mem, realtype nlscoef);
1053SUNDIALS_EXPORT int CVodeSetConstraints(void *cvode_mem, N_Vector constraints);
1054
1055SUNDIALS_EXPORT int CVodeSetIterType(void *cvode_mem, int iter);
1056
1057SUNDIALS_EXPORT int CVodeSetRootDirection(void *cvode_mem, int *rootdir);
1058SUNDIALS_EXPORT int CVodeSetNoInactiveRootWarn(void *cvode_mem);
1059
1060
1061/*
1062 * -----------------------------------------------------------------
1063 * Quadrature optional input specification functions
1064 * -----------------------------------------------------------------
1065 * The following functions can be called to set optional inputs
1066 * to values other than the defaults given below:
1067 *
1068 * Function             |  Optional input / [ default value ]
1069 * --------------------------------------------------------------
1070 *                      |
1071 * CVodeSetQuadErrCon   | are quadrature variables considered in
1072 *                      | the error control?
1073 *                      | If yes, tolerances for quadrature are
1074 *                      | required (see CVodeQuad**tolerances)
1075 *                      | [errconQ = SUNFALSE]
1076 *                      |
1077 * -----------------------------------------------------------------
1078 * If successful, these functions return CV_SUCCESS. If an argument
1079 * has an illegal value, they return one of the error flags
1080 * defined for the CVodeSet* routines.
1081 * -----------------------------------------------------------------
1082 */
1083
1084SUNDIALS_EXPORT int CVodeSetQuadErrCon(void *cvode_mem, booleantype errconQ);
1085
1086/*
1087 * -----------------------------------------------------------------
1088 * Forward sensitivity optional input specification functions
1089 * -----------------------------------------------------------------
1090 * The following functions can be called to set optional inputs
1091 * to other values than the defaults given below:
1092 *
1093 * Function                   |  Optional input / [ default value ]
1094 * -----------------------------------------------------------------
1095 *                            |
1096 * CVodeSetSensDQMethod       | controls the selection of finite
1097 *                            | difference schemes used in evaluating
1098 *                            | the sensitivity right hand sides:
1099 *                            | (centered vs. forward and
1100 *                            | simultaneous vs. separate)
1101 *                            | [DQtype=CV_CENTERED]
1102 *                            | [DQrhomax=0.0]
1103 *                            |
1104 * CVodeSetSensParams         | parameter information:
1105 *                            | p: pointer to problem parameters
1106 *                            | plist: list of parameters with respect
1107 *                            |        to which sensitivities are to be
1108 *                            |        computed.
1109 *                            | pbar: order of magnitude info.
1110 *                            |       Typically, if p[plist[i]] is nonzero,
1111 *                            |       pbar[i]=p[plist[i]].
1112 *                            | [p=NULL]
1113 *                            | [plist=NULL]
1114 *                            | [pbar=NULL]
1115 *                            |
1116 * CVodeSetSensErrCon         | are sensitivity variables considered in
1117 *                            | the error control?
1118 *                            | [SUNFALSE]
1119 *                            |
1120 * CVodeSetSensMaxNonlinIters | Maximum number of nonlinear solver
1121 *                            | iterations at one solution.
1122 *                            | [3]
1123 *                            |
1124 * -----------------------------------------------------------------
1125 * The return values are the same as for CVodeSet*
1126 * -----------------------------------------------------------------
1127 */
1128
1129SUNDIALS_EXPORT int CVodeSetSensDQMethod(void *cvode_mem, int DQtype, realtype DQrhomax);
1130SUNDIALS_EXPORT int CVodeSetSensErrCon(void *cvode_mem, booleantype errconS);
1131SUNDIALS_EXPORT int CVodeSetSensMaxNonlinIters(void *cvode_mem, int maxcorS);
1132SUNDIALS_EXPORT int CVodeSetSensParams(void *cvode_mem, realtype *p, realtype *pbar, int *plist);
1133
1134/*
1135 * -----------------------------------------------------------------
1136 * Quadrature sensitivity optional input specification functions
1137 * -----------------------------------------------------------------
1138 * The following functions can be called to set optional inputs
1139 * to values other than the defaults given below:
1140 *
1141 * Function               |  Optional input / [ default value ]
1142 * --------------------------------------------------------------
1143 *                        |
1144 * CVodeSetQuadSensErrCon | are quadrature sensitivity variables
1145 *                        | considered in the error control?
1146 *                        | If yes, tolerances for quadrature
1147 *                        | sensitivity variables are required.
1148 *                        | [errconQS = SUNFALSE]
1149 *                        |
1150 * -----------------------------------------------------------------
1151 * If successful, these functions return CV_SUCCESS. If an argument
1152 * has an illegal value, they return one of the error flags
1153 * defined for the CVodeSet* routines.
1154 * -----------------------------------------------------------------
1155 */
1156
1157SUNDIALS_EXPORT int CVodeSetQuadSensErrCon(void *cvode_mem, booleantype errconQS);
1158
1159/*
1160 * -----------------------------------------------------------------
1161 * Function : CVodeSensToggleOff
1162 * -----------------------------------------------------------------
1163 * CVodeSensToggleOff deactivates sensitivity calculations.
1164 * It does NOT deallocate sensitivity-related memory so that
1165 * sensitivity computations can be later toggled ON (through
1166 * CVodeSensReInit).
1167 *
1168 * The return value is equal to CV_SUCCESS = 0 if there were no
1169 * errors or CV_MEM_NULL if cvode_mem was NULL
1170 * -----------------------------------------------------------------
1171 */
1172
1173SUNDIALS_EXPORT int CVodeSensToggleOff(void *cvode_mem);
1174
1175
1176/*
1177 * =================================================================
1178 *
1179 * MAIN SOLVER FUNCTION FOR FORWARD PROBLEMS
1180 *
1181 * =================================================================
1182 */
1183
1184/*
1185 * -----------------------------------------------------------------
1186 * Function : CVode
1187 * -----------------------------------------------------------------
1188 * CVode integrates the ODE over an interval in t.
1189 * If itask is CV_NORMAL, then the solver integrates from its
1190 * current internal t value to a point at or beyond tout, then
1191 * interpolates to t = tout and returns y(tout) in the user-
1192 * allocated vector yout. If itask is CV_ONE_STEP, then the solver
1193 * takes one internal time step and returns in yout the value of
1194 * y at the new internal time. In this case, tout is used only
1195 * during the first call to CVode to determine the direction of
1196 * integration and the rough scale of the problem. If tstop is
1197 * enabled (through a call to CVodeSetStopTime), then CVode returns
1198 * the solution at tstop. Once the integrator returns at a tstop
1199 * time, any future testing for tstop is disabled (and can be
1200 * reenabled only though a new call to CVodeSetStopTime).
1201 * The time reached by the solver is placed in (*tret). The
1202 * user is responsible for allocating the memory for this value.
1203 *
1204 * cvode_mem is the pointer to CVODES memory returned by
1205 *           CVodeCreate.
1206 *
1207 * tout  is the next time at which a computed solution is desired.
1208 *
1209 * yout  is the computed solution vector. In CV_NORMAL mode with no
1210 *       errors and no roots found, yout=y(tout).
1211 *
1212 * tret  is a pointer to a real location. CVode sets (*tret) to
1213 *       the time reached by the solver and returns yout=y(*tret).
1214 *
1215 * itask is CV_NORMAL or CV_ONE_STEP. These two modes are described above.
1216 *
1217 * Here is a brief description of each return value:
1218 *
1219 * CV_SUCCESS:     CVode succeeded and no roots were found.
1220 *
1221 * CV_ROOT_RETURN: CVode succeeded, and found one or more roots.
1222 *                 If nrtfn > 1, call CVodeGetRootInfo to see
1223 *                 which g_i were found to have a root at (*tret).
1224 *
1225 * CV_TSTOP_RETURN: CVode succeded and returned at tstop.
1226 *
1227 * CV_MEM_NULL:    The cvode_mem argument was NULL.
1228 *
1229 * CV_NO_MALLOC:   cvode_mem was not allocated.
1230 *
1231 * CV_ILL_INPUT:   One of the inputs to CVode is illegal. This
1232 *                 includes the situation when a component of the
1233 *                 error weight vectors becomes < 0 during
1234 *                 internal time-stepping. The ILL_INPUT flag
1235 *                 will also be returned if the linear solver
1236 *                 routine CV--- (called by the user after
1237 *                 calling CVodeCreate) failed to set one of the
1238 *                 linear solver-related fields in cvode_mem or
1239 *                 if the linear solver's init routine failed. In
1240 *                 any case, the user should see the printed
1241 *                 error message for more details.
1242 *
1243 * CV_TOO_MUCH_WORK: The solver took mxstep internal steps but
1244 *                 could not reach tout. The default value for
1245 *                 mxstep is MXSTEP_DEFAULT = 500.
1246 *
1247 * CV_TOO_MUCH_ACC: The solver could not satisfy the accuracy
1248 *                 demanded by the user for some internal step.
1249 *
1250 * CV_CONSTR_FAIL: The inequality constraints were violated,
1251 *                 and the solver was unable to recover.
1252 *
1253 * CV_ERR_FAILURE: Error test failures occurred too many times
1254 *                 (= MXNEF = 7) during one internal time step or
1255 *                 occurred with |h| = hmin.
1256 *
1257 * CV_CONV_FAILURE: Convergence test failures occurred too many
1258 *                 times (= MXNCF = 10) during one internal time
1259 *                 step or occurred with |h| = hmin.
1260 *
1261 * CV_LINIT_FAIL:  The linear solver's initialization function
1262 *                 failed.
1263 *
1264 * CV_LSETUP_FAIL: The linear solver's setup routine failed in an
1265 *                 unrecoverable manner.
1266 *
1267 * CV_LSOLVE_FAIL: The linear solver's solve routine failed in an
1268 *                 unrecoverable manner.
1269 * -----------------------------------------------------------------
1270 */
1271
1272SUNDIALS_EXPORT int CVode(void *cvode_mem, realtype tout, N_Vector yout,
1273        realtype *tret, int itask);
1274
1275
1276/*
1277 * =================================================================
1278 *
1279 * EXTRACTION AND DENSE OUTPUT FUNCTIONS FOR FORWARD PROBLEMS
1280 *
1281 * =================================================================
1282 */
1283
1284/*
1285 * -----------------------------------------------------------------
1286 * Function : CVodeGetDky
1287 * -----------------------------------------------------------------
1288 * CVodeGetDky computes the kth derivative of the y function at
1289 * time t, where tn-hu <= t <= tn, tn denotes the current
1290 * internal time reached, and hu is the last internal step size
1291 * successfully used by the solver. The user may request
1292 * k=0, 1, ..., qu, where qu is the current order. The
1293 * derivative vector is returned in dky. This vector must be
1294 * allocated by the caller. It is only legal to call this
1295 * function after a successful return from CVode.
1296 *
1297 * cvode_mem is the pointer to CVODES memory returned by
1298 *           CVodeCreate.
1299 *
1300 * t   is the time at which the kth derivative of y is evaluated.
1301 *     The legal range for t is [tn-hu,tn] as described above.
1302 *
1303 * k   is the order of the derivative of y to be computed. The
1304 *     legal range for k is [0,qu] as described above.
1305 *
1306 * dky is the output derivative vector [(D_k)y](t).
1307 *
1308 * The return values for CVodeGetDky are defined below.
1309 * Here is a brief description of each return value:
1310 *
1311 * CV_SUCCESS: CVodeGetDky succeeded.
1312 *
1313 * CV_BAD_K : k is not in the range 0, 1, ..., qu.
1314 *
1315 * CV_BAD_T : t is not in the interval [tn-hu,tn].
1316 *
1317 * CV_BAD_DKY : The dky argument was NULL.
1318 *
1319 * CV_MEM_NULL : The cvode_mem argument was NULL.
1320 * -----------------------------------------------------------------
1321 */
1322
1323SUNDIALS_EXPORT int CVodeGetDky(void *cvode_mem, realtype t, int k, N_Vector dky);
1324
1325
1326/*
1327 * -----------------------------------------------------------------
1328 * Quadrature integration solution extraction routines
1329 * -----------------------------------------------------------------
1330 * The following functions can be called to obtain the quadrature
1331 * variables after a successful integration step.
1332 * If quadratures were not computed, they return CV_NO_QUAD.
1333 *
1334 * CVodeGetQuad returns the quadrature variables at the same time
1335 *   as that at which CVode returned the solution.
1336 *
1337 * CVodeGetQuadDky returns the quadrature variables (or their
1338 *   derivatives up to the current method order) at any time within
1339 *   the last integration step (dense output). See CVodeGetQuad for
1340 *   more information.
1341 *
1342 * The output vectors yQout and dky must be allocated by the user.
1343 * -----------------------------------------------------------------
1344 */
1345
1346SUNDIALS_EXPORT int CVodeGetQuad(void *cvode_mem, realtype *tret, N_Vector yQout);
1347
1348SUNDIALS_EXPORT int CVodeGetQuadDky(void *cvode_mem, realtype t, int k, N_Vector dky);
1349
1350/*
1351 * -----------------------------------------------------------------
1352 * Forward sensitivity solution extraction routines
1353 * -----------------------------------------------------------------
1354 * The following functions can be called to obtain the sensitivity
1355 * variables after a successful integration step.
1356 *
1357 * CVodeGetSens and CVodeGetSens1 return all the sensitivity vectors
1358 *   or only one of them, respectively, at the same time as that at
1359 *   which CVode returned the solution.
1360 *   The array of output vectors or output vector ySout must be
1361 *   allocated by the user.
1362 *
1363 * CVodeGetSensDky1 computes the kth derivative of the is-th
1364 *   sensitivity (is=1, 2, ..., Ns) of the y function at time t,
1365 *   where tn-hu <= t <= tn, tn denotes the current internal time
1366 *   reached, and hu is the last internal step size successfully
1367 *   used by the solver. The user may request k=0, 1, ..., qu,
1368 *   where qu is the current order.
1369 *   The is-th sensitivity derivative vector is returned in dky.
1370 *   This vector must be allocated by the caller. It is only legal
1371 *   to call this function after a successful return from CVode
1372 *   with sensitivty computations enabled.
1373 *   Arguments have the same meaning as in CVodeDky.
1374 *
1375 * CVodeGetSensDky computes the k-th derivative of all
1376 *   sensitivities of the y function at time t. It repeatedly calls
1377 *   CVodeGetSensDky. The argument dkyA must be a pointer to
1378 *   N_Vector and must be allocated by the user to hold at least Ns
1379 *   vectors.
1380 *
1381 * Return values are similar to those of CVodeDky. Additionally,
1382 * CVodeSensDky can return CV_NO_SENS if sensitivities were
1383 * not computed and CV_BAD_IS if is < 0 or is >= Ns.
1384 * -----------------------------------------------------------------
1385 */
1386
1387SUNDIALS_EXPORT int CVodeGetSens(void *cvode_mem, realtype *tret, N_Vector *ySout);
1388SUNDIALS_EXPORT int CVodeGetSens1(void *cvode_mem, realtype *tret, int is, N_Vector ySout);
1389
1390SUNDIALS_EXPORT int CVodeGetSensDky(void *cvode_mem, realtype t, int k, N_Vector *dkyA);
1391SUNDIALS_EXPORT int CVodeGetSensDky1(void *cvode_mem, realtype t, int k, int is, N_Vector dky);
1392
1393/*
1394 * -----------------------------------------------------------------
1395 * Quadrature sensitivity solution extraction routines
1396 * -----------------------------------------------------------------
1397 * The following functions can be called to obtain the quadrature
1398 * sensitivity variables after a successful integration step.
1399 *
1400 * CVodeGetQuadSens and CVodeGetQuadSens1 return all the quadrature
1401 *   sensitivity vectors or only one of them, respectively, at the
1402 *   same time as that at which CVode returned the solution.
1403 *   The array of output vectors or output vector yQSout must be
1404 *   allocated by the user.
1405 *
1406 * CVodeGetQuadSensDky1 computes the kth derivative of the is-th
1407 *   quadrature sensitivity (is=1, 2, ..., Ns) at time t, where
1408 *   tn-hu <= t <= tn, tn denotes the current internal time
1409 *   reached, and hu is the last internal step size successfully
1410 *   used by the solver. The user may request  k=0, 1, ..., qu,
1411 *   where qu is the current order.
1412 *   The is-th sensitivity derivative vector is returned in dkyQS.
1413 *   This vector must be allocated by the caller. It is only legal
1414 *   to call this function after a successful return from CVode
1415 *   with quadrature sensitivty computations enabled.
1416 *   Arguments have the same meaning as in CVodeDky.
1417 *
1418 * CVodeGetQuadSensDky computes the k-th derivative of all
1419 *   quadrature sensitivities at time t. It repeatedly calls
1420 *   CVodeGetSensDky. The argument dkyQS_all must be a pointer to
1421 *   N_Vector and must be allocated by the user to hold at least Ns
1422 *   vectors.
1423 *
1424 * Return values are similar to those of CVodeDky. Additionally,
1425 * CVodeQuadSensDky can return CV_NO_QUADSENS if quadrature
1426 * sensitivities were not computed and CV_BAD_IS if is < 0 or is >= Ns.
1427 * -----------------------------------------------------------------
1428 */
1429
1430SUNDIALS_EXPORT int CVodeGetQuadSens(void *cvode_mem, realtype *tret, N_Vector *yQSout);
1431SUNDIALS_EXPORT int CVodeGetQuadSens1(void *cvode_mem, realtype *tret, int is, N_Vector yQSout);
1432
1433SUNDIALS_EXPORT int CVodeGetQuadSensDky(void *cvode_mem, realtype t, int k, N_Vector *dkyQS_all);
1434SUNDIALS_EXPORT int CVodeGetQuadSensDky1(void *cvode_mem, realtype t, int k, int is, N_Vector dkyQS);
1435
1436/*
1437 * =================================================================
1438 *
1439 * OPTIONAL OUTPUT FUNCTIONS FOR FORWARD PROBLEMS
1440 *
1441 * =================================================================
1442 */
1443
1444/*
1445 * -----------------------------------------------------------------
1446 * Integrator optional output extraction functions
1447 * -----------------------------------------------------------------
1448 * The following functions can be called to get optional outputs
1449 * and statistics related to the main integrator.
1450 * -----------------------------------------------------------------
1451 * CVodeGetWorkSpace returns the CVODES real and integer workspaces
1452 * CVodeGetNumSteps returns the cumulative number of internal
1453 *                  steps taken by the solver
1454 * CVodeGetNumRhsEvals returns the number of calls to the user's
1455 *                  f function
1456 * CVodeGetNumLinSolvSetups returns the number of calls made to
1457 *                  the linear solver's setup routine
1458 * CVodeGetNumErrTestFails returns the number of local error test
1459 *                  failures that have occured
1460 * CVodeGetLastOrder returns the order used during the last
1461 *                  internal step
1462 * CVodeGetCurrentOrder returns the order to be used on the next
1463 *                  internal step
1464 * CVodeGetNumStabLimOrderReds returns the number of order
1465 *                  reductions due to stability limit detection
1466 * CVodeGetActualInitStep returns the actual initial step size
1467 *                  used by CVODES
1468 * CVodeGetLastStep returns the step size for the last internal
1469 *                  step
1470 * CVodeGetCurrentStep returns the step size to be attempted on
1471 *                  the next internal step
1472 * CVodeGetCurrentTime returns the current internal time reached
1473 *                  by the solver
1474 * CVodeGetTolScaleFactor returns a suggested factor by which the
1475 *                  user's tolerances should be scaled when too
1476 *                  much accuracy has been requested for some
1477 *                  internal step
1478 * CVodeGetErrWeights returns the current error weight vector.
1479 *                    The user must allocate space for eweight.
1480 * CVodeGetEstLocalErrors returns the vector of estimated local
1481 *                  errors. The user must allocate space for ele.
1482 * CVodeGetNumGEvals returns the number of calls to the user's
1483 *                  g function (for rootfinding)
1484 * CVodeGetRootInfo returns the indices for which g_i was found to
1485 *                  have a root. The user must allocate space for
1486 *                  rootsfound. For i = 0 ... nrtfn-1,
1487 *                  rootsfound[i] = 1 if g_i has a root, and = 0 if not.
1488 *
1489 * CVodeGet* return values:
1490 *   CV_SUCCESS   if succesful
1491 *   CV_MEM_NULL  if the cvode memory was NULL
1492 *   CV_NO_SLDET  if stability limit was not turned on
1493 * -----------------------------------------------------------------
1494 */
1495
1496SUNDIALS_EXPORT int CVodeGetWorkSpace(void *cvode_mem, long int *lenrw, long int *leniw);
1497SUNDIALS_EXPORT int CVodeGetNumSteps(void *cvode_mem, long int *nsteps);
1498SUNDIALS_EXPORT int CVodeGetNumRhsEvals(void *cvode_mem, long int *nfevals);
1499SUNDIALS_EXPORT int CVodeGetNumLinSolvSetups(void *cvode_mem, long int *nlinsetups);
1500SUNDIALS_EXPORT int CVodeGetNumErrTestFails(void *cvode_mem, long int *netfails);
1501SUNDIALS_EXPORT int CVodeGetLastOrder(void *cvode_mem, int *qlast);
1502SUNDIALS_EXPORT int CVodeGetCurrentOrder(void *cvode_mem, int *qcur);
1503SUNDIALS_EXPORT int CVodeGetNumStabLimOrderReds(void *cvode_mem, long int *nslred);
1504SUNDIALS_EXPORT int CVodeGetActualInitStep(void *cvode_mem, realtype *hinused);
1505SUNDIALS_EXPORT int CVodeGetLastStep(void *cvode_mem, realtype *hlast);
1506SUNDIALS_EXPORT int CVodeGetCurrentStep(void *cvode_mem, realtype *hcur);
1507SUNDIALS_EXPORT int CVodeGetCurrentTime(void *cvode_mem, realtype *tcur);
1508SUNDIALS_EXPORT int CVodeGetTolScaleFactor(void *cvode_mem, realtype *tolsfac);
1509SUNDIALS_EXPORT int CVodeGetErrWeights(void *cvode_mem, N_Vector eweight);
1510SUNDIALS_EXPORT int CVodeGetEstLocalErrors(void *cvode_mem, N_Vector ele);
1511SUNDIALS_EXPORT int CVodeGetNumGEvals(void *cvode_mem, long int *ngevals);
1512SUNDIALS_EXPORT int CVodeGetRootInfo(void *cvode_mem, int *rootsfound);
1513
1514/*
1515 * -----------------------------------------------------------------
1516 * As a convenience, the following functions provides the
1517 * optional outputs in one group.
1518 * -----------------------------------------------------------------
1519 */
1520
1521SUNDIALS_EXPORT int CVodeGetIntegratorStats(void *cvode_mem, long int *nsteps,
1522              long int *nfevals, long int *nlinsetups,
1523              long int *netfails, int *qlast,
1524              int *qcur, realtype *hinused, realtype *hlast,
1525              realtype *hcur, realtype *tcur);
1526
1527/*
1528 * -----------------------------------------------------------------
1529 * Nonlinear solver optional output extraction functions
1530 * -----------------------------------------------------------------
1531 * The following functions can be called to get optional outputs
1532 * and statistics related to the nonlinear solver.
1533 * -----------------------------------------------------------------
1534 * CVodeGetNumNonlinSolvIters returns the number of nonlinear
1535 *                            solver iterations performed.
1536 * CVodeGetNumNonlinSolvConvFails returns the number of nonlinear
1537 *                                convergence failures.
1538 * -----------------------------------------------------------------
1539 */
1540
1541SUNDIALS_EXPORT int CVodeGetNumNonlinSolvIters(void *cvode_mem, long int *nniters);
1542SUNDIALS_EXPORT int CVodeGetNumNonlinSolvConvFails(void *cvode_mem, long int *nncfails);
1543
1544/*
1545 * -----------------------------------------------------------------
1546 * As a convenience, the following function provides the
1547 * nonlinear solver optional outputs in a group.
1548 * -----------------------------------------------------------------
1549 */
1550
1551SUNDIALS_EXPORT int CVodeGetNonlinSolvStats(void *cvode_mem, long int *nniters,
1552              long int *nncfails);
1553
1554
1555/*
1556 * -----------------------------------------------------------------
1557 * The following function returns the name of the constant
1558 * associated with a CVODES return flag
1559 * -----------------------------------------------------------------
1560 */
1561
1562SUNDIALS_EXPORT char *CVodeGetReturnFlagName(long int flag);
1563
1564/*
1565 * -----------------------------------------------------------------
1566 * Quadrature integration optional output extraction routines
1567 * -----------------------------------------------------------------
1568 * The following functions can be called to get optional outputs
1569 * and statistics related to the integration of quadratures.
1570 * -----------------------------------------------------------------
1571 * CVodeGetQuadNumRhsEvals returns the number of calls to the
1572 *                         user function fQ defining the right hand
1573 *                         side of the quadrature variables.
1574 * CVodeGetQuadNumErrTestFails returns the number of local error
1575 *                             test failures for quadrature variables.
1576 * CVodeGetQuadErrWeights returns the vector of error weights for
1577 *                        the quadrature variables. The user must
1578 *                        allocate space for ewtQ.
1579 * -----------------------------------------------------------------
1580 */
1581
1582SUNDIALS_EXPORT int CVodeGetQuadNumRhsEvals(void *cvode_mem, long int *nfQevals);
1583SUNDIALS_EXPORT int CVodeGetQuadNumErrTestFails(void *cvode_mem, long int *nQetfails);
1584SUNDIALS_EXPORT int CVodeGetQuadErrWeights(void *cvode_mem, N_Vector eQweight);
1585
1586/*
1587 * -----------------------------------------------------------------
1588 * As a convenience, the following function provides the above
1589 * optional outputs in a group.
1590 * -----------------------------------------------------------------
1591 */
1592
1593SUNDIALS_EXPORT int CVodeGetQuadStats(void *cvode_mem, long int *nfQevals,
1594              long int *nQetfails);
1595
1596/*
1597 * -----------------------------------------------------------------
1598 * Forward sensitivity optional output extraction routines
1599 * -----------------------------------------------------------------
1600 * The following functions can be called to get optional outputs
1601 * and statistics related to the integration of sensitivities.
1602 * -----------------------------------------------------------------
1603 * CVodeGetSensNumRhsEvals returns the number of calls to the
1604 *   sensitivity right hand side routine.
1605 * CVodeGetNumRhsEvalsSens returns the number of calls to the
1606 *   user f routine due to finite difference evaluations of the
1607 *   sensitivity equations.
1608 * CVodeGetSensNumErrTestFails returns the number of local error
1609 *   test failures for sensitivity variables.
1610 * CVodeGetSensNumLinSolvSetups returns the number of calls made
1611 *   to the linear solver's setup routine due to sensitivity computations.
1612 * CVodeGetSensErrWeights returns the sensitivity error weight
1613 *   vectors. The user need not allocate space for ewtS.
1614 * -----------------------------------------------------------------
1615 */
1616
1617SUNDIALS_EXPORT int CVodeGetSensNumRhsEvals(void *cvode_mem, long int *nfSevals);
1618SUNDIALS_EXPORT int CVodeGetNumRhsEvalsSens(void *cvode_mem, long int *nfevalsS);
1619SUNDIALS_EXPORT int CVodeGetSensNumErrTestFails(void *cvode_mem, long int *nSetfails);
1620SUNDIALS_EXPORT int CVodeGetSensNumLinSolvSetups(void *cvode_mem, long int *nlinsetupsS);
1621SUNDIALS_EXPORT int CVodeGetSensErrWeights(void *cvode_mem, N_Vector *eSweight);
1622
1623/*
1624 * -----------------------------------------------------------------
1625 * As a convenience, the following function provides the
1626 * optional outputs in a group.
1627 * -----------------------------------------------------------------
1628 */
1629
1630SUNDIALS_EXPORT int CVodeGetSensStats(void *cvode_mem, long int *nfSevals, long int *nfevalsS,
1631              long int *nSetfails, long int *nlinsetupsS);
1632
1633/*
1634 * -----------------------------------------------------------------
1635 * Sensitivity nonlinear solver optional output extraction
1636 * -----------------------------------------------------------------
1637 * The following functions can be called to get optional outputs
1638 * and statistics related to the sensitivity nonlinear solver.
1639 * -----------------------------------------------------------------
1640 * CVodeGetSensNumNonlinSolvIters returns the total number of
1641 *   nonlinear iterations for sensitivity variables.
1642 * CVodeGetSensNumNonlinSolvConvFails returns the total number
1643 *   of nonlinear convergence failures for sensitivity variables
1644 * CVodeGetStgrSensNumNonlinSolvIters returns a vector of Ns
1645 *   nonlinear iteration counters for sensitivity variables in
1646 *   the CV_STAGGERED1 method.
1647 * CVodeGetStgrSensNumNonlinSolvConvFails returns a vector of Ns
1648 *   nonlinear solver convergence failure counters for sensitivity
1649 *   variables in the CV_STAGGERED1 method.
1650 * -----------------------------------------------------------------
1651 */
1652
1653SUNDIALS_EXPORT int CVodeGetSensNumNonlinSolvIters(void *cvode_mem, long int *nSniters);
1654SUNDIALS_EXPORT int CVodeGetSensNumNonlinSolvConvFails(void *cvode_mem, long int *nSncfails);
1655SUNDIALS_EXPORT int CVodeGetStgrSensNumNonlinSolvIters(void *cvode_mem, long int *nSTGR1niters);
1656SUNDIALS_EXPORT int CVodeGetStgrSensNumNonlinSolvConvFails(void *cvode_mem,
1657                 long int *nSTGR1ncfails);
1658
1659/*
1660 * -----------------------------------------------------------------
1661 * As a convenience, the following function provides the     
1662 * optional outputs in groups.                                   
1663 * -----------------------------------------------------------------
1664 */
1665
1666SUNDIALS_EXPORT int CVodeGetSensNonlinSolvStats(void *cvode_mem, long int *nSniters,
1667            long int *nSncfails);
1668
1669
1670/*
1671 * -----------------------------------------------------------------
1672 * Quadrature sensitivity optional output extraction routines
1673 * -----------------------------------------------------------------
1674 * The following functions can be called to get optional outputs and
1675 * statistics related to the integration of quadrature sensitivitiess.
1676 * -----------------------------------------------------------------
1677 * CVodeGetQuadSensNumRhsEvals returns the number of calls to the
1678 *       user function fQS defining the right hand side of the
1679 *       quadrature sensitivity equations.
1680 * CVodeGetQuadSensNumErrTestFails returns the number of local error
1681 *       test failures for quadrature sensitivity variables.
1682 * CVodeGetQuadSensErrWeights returns the vector of error weights
1683 *       for the quadrature sensitivity variables. The user must
1684 *       allocate space for ewtQS.
1685 * -----------------------------------------------------------------
1686 */
1687
1688SUNDIALS_EXPORT int CVodeGetQuadSensNumRhsEvals(void *cvode_mem, long int *nfQSevals);
1689SUNDIALS_EXPORT int CVodeGetQuadSensNumErrTestFails(void *cvode_mem, long int *nQSetfails);
1690SUNDIALS_EXPORT int CVodeGetQuadSensErrWeights(void *cvode_mem, N_Vector *eQSweight);
1691
1692/*
1693 * -----------------------------------------------------------------
1694 * As a convenience, the following function provides the above
1695 * optional outputs in a group.
1696 * -----------------------------------------------------------------
1697 */
1698
1699SUNDIALS_EXPORT int CVodeGetQuadSensStats(void *cvode_mem,
1700                                          long int *nfQSevals,
1701                                          long int *nQSetfails);
1702
1703
1704/*
1705 * =================================================================
1706 *
1707 * INITIALIZATION AND DEALLOCATION FUNCTIONS FOR BACKWARD PROBLEMS
1708 *
1709 * =================================================================
1710 */
1711
1712/*
1713 * -----------------------------------------------------------------
1714 * CVodeAdjInit
1715 * -----------------------------------------------------------------
1716 * CVodeAdjInit specifies some parameters for ASA, initializes ASA
1717 * and allocates space for the adjoint memory structure.
1718 * -----------------------------------------------------------------
1719 */
1720 
1721SUNDIALS_EXPORT int CVodeAdjInit(void *cvode_mem, long int steps, int interp);
1722
1723/*
1724 * -----------------------------------------------------------------
1725 * CVodeAdjReInit
1726 * -----------------------------------------------------------------
1727 * CVodeAdjReInit reinitializes the CVODES memory structure for ASA,
1728 * assuming that the number of steps between check points and the
1729 * type of interpolation remained unchanged. The list of check points
1730 * (and associated memory) is deleted. The list of backward problems
1731 * is kept (however, new backward problems can be added to this list
1732 * by calling CVodeCreateB). The CVODES memory for the forward and
1733 * backward problems can be reinitialized separately by calling
1734 * CVodeReInit and CVodeReInitB, respectively.
1735 * NOTE: if a entirely new list of backward problems is desired,
1736 *   then simply free the adjoint memory (by calling CVodeAdjFree)
1737 *   and reinitialize ASA with CVodeAdjInit.
1738 * -----------------------------------------------------------------
1739 */
1740
1741SUNDIALS_EXPORT int CVodeAdjReInit(void *cvode_mem);
1742
1743/*
1744 * -----------------------------------------------------------------
1745 * CVodeAdjFree
1746 * -----------------------------------------------------------------
1747 * CVodeAdjFree frees the memory allocated by CVodeAdjInit.
1748 * It is typically called by CVodeFree.
1749 * -----------------------------------------------------------------
1750 */
1751 
1752SUNDIALS_EXPORT void CVodeAdjFree(void *cvode_mem);
1753 
1754
1755/*
1756 * -----------------------------------------------------------------
1757 * Interfaces to CVODES functions for setting-up backward problems.
1758 * -----------------------------------------------------------------
1759 * CVodeCreateB,
1760 *
1761 * CVodeInitB, CVodeInitBS, CVodeReInitB
1762 *
1763 * CVodeQuadInitB, CVodeQuadInitBS, CVodeQuadReInitB
1764 *
1765 * -----------------------------------------------------------------
1766 */
1767
1768SUNDIALS_EXPORT int CVodeCreateB(void *cvode_mem, int lmmB, int iterB, int *which);
1769
1770SUNDIALS_EXPORT int CVodeInitB(void *cvode_mem, int which,
1771                               CVRhsFnB fB,
1772                               realtype tB0, N_Vector yB0);
1773SUNDIALS_EXPORT int CVodeInitBS(void *cvode_mem, int which,
1774                                CVRhsFnBS fBs,
1775                                realtype tB0, N_Vector yB0);
1776SUNDIALS_EXPORT int CVodeReInitB(void *cvode_mem, int which,
1777         realtype tB0, N_Vector yB0);
1778
1779SUNDIALS_EXPORT int CVodeSStolerancesB(void *cvode_mem, int which,
1780                                       realtype reltolB, realtype abstolB);
1781SUNDIALS_EXPORT int CVodeSVtolerancesB(void *cvode_mem, int which,
1782                                       realtype reltolB, N_Vector abstolB);
1783
1784SUNDIALS_EXPORT int CVodeQuadInitB(void *cvode_mem, int which,
1785                                     CVQuadRhsFnB fQB, N_Vector yQB0);
1786SUNDIALS_EXPORT int CVodeQuadInitBS(void *cvode_mem, int which,
1787                                      CVQuadRhsFnBS fQBs, N_Vector yQB0);
1788SUNDIALS_EXPORT int CVodeQuadReInitB(void *cvode_mem, int which, N_Vector yQB0);
1789
1790SUNDIALS_EXPORT int CVodeQuadSStolerancesB(void *cvode_mem, int which,
1791                                           realtype reltolQB, realtype abstolQB);
1792SUNDIALS_EXPORT int CVodeQuadSVtolerancesB(void *cvode_mem, int which,
1793                                           realtype reltolQB, N_Vector abstolQB);
1794
1795/*
1796 * =================================================================
1797 *
1798 * MAIN SOLVER FUNCTIONS FOR FORWARD PROBLEMS
1799 *
1800 * =================================================================
1801 */
1802
1803/*
1804 * -----------------------------------------------------------------
1805 * CVodeF
1806 * -----------------------------------------------------------------
1807 * CVodeF integrates towards tout and returns solution into yout.
1808 * In the same time, it stores check point data every 'steps'.
1809 *
1810 * CVodeF can be called repeatedly by the user.
1811 *
1812 * ncheckPtr points to the number of check points stored so far.
1813 *
1814 * -----------------------------------------------------------------
1815 */
1816
1817SUNDIALS_EXPORT int CVodeF(void *cvode_mem, realtype tout, N_Vector yout,
1818         realtype *tret, int itask, int *ncheckPtr);
1819
1820
1821/*
1822 * -----------------------------------------------------------------
1823 * CVodeB
1824 * -----------------------------------------------------------------
1825 * CVodeB performs the integration of all backward problems specified
1826 * through calls to CVodeCreateB through a sequence of forward-backward
1827 * runs in between consecutive check points. CVodeB can be called
1828 * either in CV_NORMAL or CV_ONE_STEP mode. After a successful return
1829 * from CVodeB, the solution and quadrature variables at the current
1830 * return time for any given backward problem can be obtained by
1831 * calling CVodeGetB and CVodeGetQuadB, respectively.
1832 * -----------------------------------------------------------------
1833 */
1834 
1835SUNDIALS_EXPORT int CVodeB(void *cvode_mem, realtype tBout, int itaskB);
1836
1837/*
1838 * =================================================================
1839 *
1840 * OPTIONAL INPUT FUNCTIONS FOR BACKWARD PROBLEMS
1841 *
1842 * =================================================================
1843 */
1844
1845/*
1846 * -----------------------------------------------------------------
1847 * CVodeSetAdjNoSensi
1848 * -----------------------------------------------------------------
1849 */
1850
1851SUNDIALS_EXPORT int CVodeSetAdjNoSensi(void *cvode_mem);
1852
1853/*
1854 * -----------------------------------------------------------------
1855 * Optional input functions for backward problems
1856 * -----------------------------------------------------------------
1857 * These functions are just wrappers around the corresponding
1858 * functions in cvodes.h, with some particularizations for the
1859 * backward integration.
1860 * -----------------------------------------------------------------
1861 */
1862
1863SUNDIALS_EXPORT int CVodeSetIterTypeB(void *cvode_mem, int which, int iterB);
1864SUNDIALS_EXPORT int CVodeSetUserDataB(void *cvode_mem, int which, void *user_dataB);
1865SUNDIALS_EXPORT int CVodeSetMaxOrdB(void *cvode_mem, int which, int maxordB);
1866SUNDIALS_EXPORT int CVodeSetMaxNumStepsB(void *cvode_mem, int which, long int mxstepsB);
1867SUNDIALS_EXPORT int CVodeSetStabLimDetB(void *cvode_mem, int which, booleantype stldetB);
1868SUNDIALS_EXPORT int CVodeSetInitStepB(void *cvode_mem, int which, realtype hinB);
1869SUNDIALS_EXPORT int CVodeSetMinStepB(void *cvode_mem, int which, realtype hminB);
1870SUNDIALS_EXPORT int CVodeSetMaxStepB(void *cvode_mem, int which, realtype hmaxB);
1871SUNDIALS_EXPORT int CVodeSetConstraintsB(void *cvode_mem, int which, N_Vector constraintsB);     
1872SUNDIALS_EXPORT int CVodeSetQuadErrConB(void *cvode_mem, int which, booleantype errconQB);
1873
1874/*
1875 * =================================================================
1876 *
1877 * EXTRACTION AND DENSE OUTPUT FUNCTIONS FOR BACKWARD PROBLEMS
1878 *
1879 * =================================================================
1880 */
1881 
1882/*
1883 * -----------------------------------------------------------------
1884 * CVodeGetB and CVodeGetQuadB
1885 * -----------------------------------------------------------------
1886 * Extraction functions for the solution and quadratures for a given
1887 * backward problem. They return their corresponding output vector
1888 * at the current time reached by the integration of the backward
1889 * problem. To obtain the solution or quadratures associated with
1890 * a given backward problem at some other time within the last
1891 * integration step (dense output), first obtain a pointer to the
1892 * proper CVODES memory by calling CVodeGetAdjCVodeBmem and then use it
1893 * to call CVodeGetDky and CVodeGetQuadDky. 
1894 * -----------------------------------------------------------------
1895 */
1896 
1897SUNDIALS_EXPORT int CVodeGetB(void *cvode_mem, int which,
1898                              realtype *tBret, N_Vector yB);
1899SUNDIALS_EXPORT int CVodeGetQuadB(void *cvode_mem, int which,
1900                                  realtype *tBret, N_Vector qB);
1901
1902
1903/*
1904 * =================================================================
1905 *
1906 * OPTIONAL OUTPUT FUNCTIONS FOR BACKWARD PROBLEMS
1907 *
1908 * =================================================================
1909 */
1910
1911
1912/*
1913 * -----------------------------------------------------------------
1914 * CVodeGetAdjCVodeBmem
1915 * -----------------------------------------------------------------
1916 * CVodeGetAdjCVodeBmem returns a (void *) pointer to the CVODES
1917 * memory allocated for the backward problem. This pointer can
1918 * then be used to call any of the CVodeGet* CVODES routines to
1919 * extract optional output for the backward integration phase.
1920 * -----------------------------------------------------------------
1921 */
1922 
1923SUNDIALS_EXPORT void *CVodeGetAdjCVodeBmem(void *cvode_mem, int which);
1924
1925
1926/*
1927 * -----------------------------------------------------------------
1928 * CVodeGetAdjY
1929 *    Returns the interpolated forward solution at time t. This
1930 *    function is a wrapper around the interpType-dependent internal
1931 *    function.
1932 *    The calling function must allocate space for y.
1933 * -----------------------------------------------------------------
1934 */
1935
1936SUNDIALS_EXPORT int CVodeGetAdjY(void *cvode_mem, realtype t, N_Vector y);
1937
1938/*
1939 * -----------------------------------------------------------------
1940 * CVodeGetAdjCheckPointsInfo
1941 *    Loads an array of nckpnts structures of type CVadjCheckPointRec.
1942 *    The user must allocate space for ckpnt (ncheck+1).
1943 * -----------------------------------------------------------------
1944 */
1945
1946typedef struct {
1947  void *my_addr;
1948  void *next_addr;
1949  realtype t0;
1950  realtype t1;
1951  long int nstep;
1952  int order;
1953  realtype step;
1954} CVadjCheckPointRec;
1955
1956SUNDIALS_EXPORT int CVodeGetAdjCheckPointsInfo(void *cvode_mem, CVadjCheckPointRec *ckpnt);
1957
1958/*
1959 * -----------------------------------------------------------------
1960 * CVodeGetAdjDataPointHermite
1961 *    Returns the 2 vectors stored for cubic Hermite interpolation
1962 *    at the data point 'which'. The user must allocate space for
1963 *    y and yd. Returns CV_MEM_NULL if cvode_mem is NULL.
1964 *    Returns CV_ILL_INPUT if interpType != CV_HERMITE.
1965 * CVodeGetAdjDataPointPolynomial
1966 *    Returns the vector stored for polynomial interpolation
1967 *    at the data point 'which'. The user must allocate space for
1968 *    y. Returns CV_MEM_NULL if cvode_mem is NULL.
1969 *    Returns CV_ILL_INPUT if interpType != CV_POLYNOMIAL.
1970 * -----------------------------------------------------------------
1971 */
1972
1973SUNDIALS_EXPORT int CVodeGetAdjDataPointHermite(void *cvode_mem, int which,
1974                                                realtype *t, N_Vector y, N_Vector yd);
1975 
1976SUNDIALS_EXPORT int CVodeGetAdjDataPointPolynomial(void *cvode_mem, int which,
1977                                                   realtype *t, int *order, N_Vector y);
1978
1979/*
1980 * -----------------------------------------------------------------
1981 * CVodeGetAdjCurrentCheckPoint
1982 *    Returns the address of the 'active' check point.
1983 * -----------------------------------------------------------------
1984 */
1985
1986SUNDIALS_EXPORT int CVodeGetAdjCurrentCheckPoint(void *cvode_mem, void **addr);
1987
1988
1989
1990#ifdef __cplusplus
1991}
1992#endif
1993
1994#endif
Note: See TracBrowser for help on using the repository browser.