reorganize scicos_sundials as std lib
[scilab.git] / scilab / modules / scicos / src / scicos_sundials / include / cvode / cvode.h
1 /*
2  * -----------------------------------------------------------------
3  * $Revision: 1.3 $
4  * $Date: 2006/10/17 21:00:00 $
5  * ----------------------------------------------------------------- 
6  * Programmer(s): Scott D. Cohen, Alan C. Hindmarsh, Radu Serban
7  *                and Dan Shumaker @ LLNL
8  * -----------------------------------------------------------------
9  * Copyright (c) 2002, The Regents of the University of California.
10  * Produced at the Lawrence Livermore National Laboratory.
11  * All rights reserved.
12  * For details, see the LICENSE file.
13  * -----------------------------------------------------------------
14  * This is the interface file for the main CVODE integrator.
15  * -----------------------------------------------------------------
16  *
17  * CVODE is used to solve numerically the ordinary initial value
18  * problem:
19  *
20  *                 y' = f(t,y),
21  *                 y(t0) = y0,
22  *
23  * where t0, y0 in R^N, and f: R x R^N -> R^N are given.
24  *
25  * -----------------------------------------------------------------
26  */
27
28 #ifndef _CVODE_H
29 #define _CVODE_H
30
31 #ifdef __cplusplus  /* wrapper to enable C++ usage */
32 extern "C" {
33 #endif
34
35 #include <stdio.h>
36
37 #include <sundials/sundials_nvector.h>
38
39   /*
40    * =================================================================
41    *              C V O D E     C O N S T A N T S
42    * =================================================================
43    */
44
45   /*
46    * -----------------------------------------------------------------
47    * Enumerations for inputs to CVodeCreate, CVodeMalloc,
48    * CVodeReInit, and CVode.
49    * -----------------------------------------------------------------
50    * Symbolic constants for the lmm, iter, and itol input
51    * parameters to CVodeMalloc and CVodeReInit, as well as the
52    * input parameter itask to CVode, are given below.
53    *
54    * lmm:   The user of the CVODE package specifies whether to use the
55    *        CV_ADAMS (Adams-Moulton) or CV_BDF (Backward Differentiation
56    *        Formula) linear multistep method. The BDF method is
57    *        recommended for stiff problems, and the CV_ADAMS method is
58    *        recommended for nonstiff problems.
59    *
60    * iter:  At each internal time step, a nonlinear equation must
61    *        be solved. The user can specify either CV_FUNCTIONAL
62    *        iteration, which does not require linear algebra, or a
63    *        CV_NEWTON iteration, which requires the solution of linear
64    *        systems. In the CV_NEWTON case, the user also specifies a
65    *        CVODE linear solver. CV_NEWTON is recommended in case of
66    *        stiff problems.
67    *
68    * itol:  This parameter specifies the relative and absolute
69    *        tolerance types to be used. The CV_SS tolerance type means
70    *        a scalar relative and absolute tolerance. The CV_SV
71    *        tolerance type means a scalar relative tolerance and a
72    *        vector absolute tolerance (a potentially different
73    *        absolute tolerance for each vector component). The CV_WF
74    *        tolerance type means that the user provides a function
75    *        (of type CVEwtFn) to set the error weight vector.
76    *
77    * itask: The itask input parameter to CVode indicates the job
78    *        of the solver for the next user step. The CV_NORMAL
79    *        itask is to have the solver take internal steps until
80    *        it has reached or just passed the user specified tout
81    *        parameter. The solver then interpolates in order to
82    *        return an approximate value of y(tout). The CV_ONE_STEP
83    *        option tells the solver to just take one internal step
84    *        and return the solution at the point reached by that
85    *        step. The CV_NORMAL_TSTOP and CV_ONE_STEP_TSTOP modes are
86    *        similar to CV_NORMAL and CV_ONE_STEP, respectively, except
87    *        that the integration never proceeds past the value
88    *        tstop (specified through the routine CVodeSetStopTime).
89    * -----------------------------------------------------------------
90    */
91
92   /* lmm */
93 #define CV_ADAMS 1
94 #define CV_BDF   2
95
96   /* iter */
97 #define CV_FUNCTIONAL 1
98 #define CV_NEWTON     2
99
100   /* itol */
101 #define CV_SS 1
102 #define CV_SV 2
103 #define CV_WF 3
104
105   /* itask */
106 #define CV_NORMAL         1
107 #define CV_ONE_STEP       2
108 #define CV_NORMAL_TSTOP   3
109 #define CV_ONE_STEP_TSTOP 4
110
111   /*
112    * ----------------------------------------
113    * CVODE return flags
114    * ----------------------------------------
115    */
116 /* SUNDIALS EXTENSION */
117 #define CV_ZERO_DETACH_RETURN    3
118
119 #define CV_SUCCESS               0
120 #define CV_TSTOP_RETURN          1
121 #define CV_ROOT_RETURN           2
122
123 #define CV_WARNING              99
124
125 #define CV_TOO_MUCH_WORK        -1
126 #define CV_TOO_MUCH_ACC         -2
127 #define CV_ERR_FAILURE          -3
128 #define CV_CONV_FAILURE         -4
129
130 #define CV_LINIT_FAIL           -5
131 #define CV_LSETUP_FAIL          -6
132 #define CV_LSOLVE_FAIL          -7
133 #define CV_RHSFUNC_FAIL         -8
134 #define CV_FIRST_RHSFUNC_ERR    -9
135 #define CV_REPTD_RHSFUNC_ERR    -10
136 #define CV_UNREC_RHSFUNC_ERR    -11
137 #define CV_RTFUNC_FAIL          -12
138
139 #define CV_MEM_FAIL             -20
140 #define CV_MEM_NULL             -21
141 #define CV_ILL_INPUT            -22
142 #define CV_NO_MALLOC            -23
143 #define CV_BAD_K                -24
144 #define CV_BAD_T                -25
145 #define CV_BAD_DKY              -26
146 #define CV_TOO_CLOSE            -27
147
148 /* SUNDIALS EXTENSION */
149 #define CV_YOUT_NULL            -28
150 #define CV_TRET_NULL            -29
151 #define CV_BAD_ITASK            -30
152 #define CV_NO_TSTOP             -31
153 #define CV_BAD_H0               -32
154 #define CV_BAD_TSTOP            -33
155 #define CV_BAD_INIT_ROOT        -34
156 #define CV_NO_EFUN              -35
157 #define CV_EWT_FAIL             -36
158 #define CV_BAD_EWT              -37
159 #define CV_LSOLVE_NULL          -38
160 #define CV_NULL_Y0              -39
161 #define CV_BAD_ITOL             -40
162 #define CV_NULL_F               -41
163 #define CV_BAD_NVECTOR          -42
164 #define CV_NULL_ABSTOL          -43
165 #define CV_BAD_RELTOL           -44
166 #define CV_BAD_ABSTOL           -45
167 #define CV_NULL_G               -46
168 #define CV_BAD_TOUT             -47
169 #define CV_CLOSE_ROOTS          -48
170
171   /*
172    * =================================================================
173    *              F U N C T I O N   T Y P E S
174    * =================================================================
175    */
176
177   /*
178    * -----------------------------------------------------------------
179    * Type : CVRhsFn
180    * -----------------------------------------------------------------
181    * The f function which defines the right hand side of the ODE
182    * system y' = f(t,y) must have type CVRhsFn.
183    * f takes as input the independent variable value t, and the
184    * dependent variable vector y.  It stores the result of f(t,y)
185    * in the vector ydot.  The y and ydot arguments are of type
186    * N_Vector.
187    * (Allocation of memory for ydot is handled within CVODE)
188    * The f_data parameter is the same as the f_data
189    * parameter set by the user through the CVodeSetFdata routine.
190    * This user-supplied pointer is passed to the user's f function
191    * every time it is called.
192    *
193    * A CVRhsFn should return 0 if successful, a negative value if
194    * an unrecoverable error occured, and a positive value if a 
195    * recoverable error (e.g. invalid y values) occured. 
196    * If an unrecoverable occured, the integration is halted. 
197    * If a recoverable error occured, then (in most cases) CVODE
198    * will try to correct and retry.
199    * -----------------------------------------------------------------
200    */
201
202   typedef int (*CVRhsFn)(realtype t, N_Vector y,
203                          N_Vector ydot, void *f_data);
204
205   /*
206    * -----------------------------------------------------------------
207    * Type : CVRootFn
208    * -----------------------------------------------------------------
209    * A function g, which defines a set of functions g_i(t,y) whose
210    * roots are sought during the integration, must have type CVRootFn.
211    * The function g takes as input the independent variable value
212    * t, and the dependent variable vector y.  It stores the nrtfn
213    * values g_i(t,y) in the realtype array gout.
214    * (Allocation of memory for gout is handled within CVODE.)
215    * The g_data parameter is the same as that passed by the user
216    * to the CVodeRootInit routine.  This user-supplied pointer is
217    * passed to the user's g function every time it is called.
218    *
219    * A CVRootFn should return 0 if successful or a non-zero value
220    * if an error occured (in which case the integration will be halted).
221    * -----------------------------------------------------------------
222    */
223
224   typedef int (*CVRootFn)(realtype t, N_Vector y, realtype *gout,
225                           void *g_data);
226
227   /*
228    * -----------------------------------------------------------------
229    * Type : CVEwtFn
230    * -----------------------------------------------------------------
231    * A function e, which sets the error weight vector ewt, must have
232    * type CVEwtFn.
233    * The function e takes as input the current dependent variable y.
234    * It must set the vector of error weights used in the WRMS norm:
235    * 
236    *   ||y||_WRMS = sqrt [ 1/N * sum ( ewt_i * y_i)^2 ]
237    *
238    * Typically, the vector ewt has components:
239    * 
240    *   ewt_i = 1 / (reltol * |y_i| + abstol_i)
241    *
242    * The e_data parameter is the same as that passed by the user
243    * to the CVodeSetEwtFn routine.  This user-supplied pointer is
244    * passed to the user's e function every time it is called.
245    * A CVEwtFn e must return 0 if the error weight vector has been
246    * successfuly set and a non-zero value otherwise.
247    * -----------------------------------------------------------------
248    */
249
250   typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void *e_data);
251
252   /*
253    * -----------------------------------------------------------------
254    * Type : CVErrHandlerFn
255    * -----------------------------------------------------------------
256    * A function eh, which handles error messages, must have type
257    * CVErrHandlerFn.
258    * The function eh takes as input the error code, the name of the
259    * module reporting the error, the error message, and a pointer to
260    * user data, the same as that passed to CVodeSetErrHandlerFn.
261    * 
262    * All error codes are negative, except CV_WARNING which indicates 
263    * a warning (the solver continues).
264    *
265    * A CVErrHandlerFn has no return value.
266    * -----------------------------------------------------------------
267    */
268
269   typedef void (*CVErrHandlerFn)(int error_code, 
270                                  const char *module, const char *function, 
271                                  char *msg, void *eh_data); 
272
273   /*
274    * =================================================================
275    *          U S E R - C A L L A B L E   R O U T I N E S
276    * =================================================================
277    */
278
279   /*
280    * -----------------------------------------------------------------
281    * Function : CVodeCreate
282    * -----------------------------------------------------------------
283    * CVodeCreate creates an internal memory block for a problem to
284    * be solved by CVODE.
285    *
286    * lmm   is the type of linear multistep method to be used.
287    *       The legal values are CV_ADAMS and CV_BDF (see previous
288    *       description).
289    *
290    * iter  is the type of iteration used to solve the nonlinear
291    *       system that arises during each internal time step.
292    *       The legal values are CV_FUNCTIONAL and CV_NEWTON.
293    *
294    * If successful, CVodeCreate returns a pointer to initialized
295    * problem memory. This pointer should be passed to CVodeMalloc.
296    * If an initialization error occurs, CVodeCreate prints an error
297    * message to standard err and returns NULL.
298    * -----------------------------------------------------------------
299    */
300
301   void *CVodeCreate(int lmm, int iter);
302
303   /*
304    * -----------------------------------------------------------------
305    * Integrator optional input specification functions
306    * -----------------------------------------------------------------
307    * The following functions can be called to set optional inputs
308    * to values other than the defaults given below:
309    *
310    * Function                |  Optional input / [ default value ]
311    * -----------------------------------------------------------------
312    *                         |
313    * CVodeSetErrHandlerFn    | user-provided ErrHandler function.
314    *                         | [internal]
315    *                         |
316    * CVodeSetErrFile         | the file pointer for an error file
317    *                         | where all CVODE warning and error
318    *                         | messages will be written if the default
319    *                         | internal error handling function is used. 
320    *                         | This parameter can be stdout (standard 
321    *                         | output), stderr (standard error), or a 
322    *                         | file pointer (corresponding to a user 
323    *                         | error file opened for writing) returned 
324    *                         | by fopen.
325    *                         | If not called, then all messages will
326    *                         | be written to the standard error stream.
327    *                         | [stderr]
328    *                         |
329    * CVodeSetFdata           | a pointer to user data that will be
330    *                         | passed to the user's f function every
331    *                         | time f is called.
332    *                         | [NULL]
333    *                         |
334    * CVodeSetEwtFn           | user-provide EwtSet function e and 
335    *                         | a pointer to user data that will be
336    *                         | passed to the user's e function every
337    *                         | time e is called.
338    *                         | [NULL]
339    *                         | [NULL]
340    *                         |
341    * CVodeSetMaxOrd          | maximum lmm order to be used by the
342    *                         | solver.
343    *                         | [12 for Adams , 5 for BDF]
344    *                         |
345    * CVodeSetMaxNumSteps     | maximum number of internal steps to be
346    *                         | taken by the solver in its attempt to
347    *                         | reach tout.
348    *                         | [500]
349    *                         |
350    * CVodeSetMaxHnilWarns    | maximum number of warning messages
351    *                         | issued by the solver that t+h==t on the
352    *                         | next internal step. A value of -1 means
353    *                         | no such messages are issued.
354    *                         | [10]
355    *                         |
356    * CVodeSetStabLimDet      | flag to turn on/off stability limit
357    *                         | detection (TRUE = on, FALSE = off).
358    *                         | When BDF is used and order is 3 or
359    *                         | greater, CVsldet is called to detect
360    *                         | stability limit.  If limit is detected,
361    *                         | the order is reduced.
362    *                         | [FALSE]
363    *                         |
364    * CVodeSetInitStep        | initial step size.
365    *                         | [estimated by CVODE]
366    *                         |
367    * CVodeSetMinStep         | minimum absolute value of step size
368    *                         | allowed.
369    *                         | [0.0]
370    *                         |
371    * CVodeSetMaxStep         | maximum absolute value of step size
372    *                         | allowed.
373    *                         | [infinity]
374    *                         |
375    * CVodeSetStopTime        | the independent variable value past
376    *                         | which the solution is not to proceed.
377    *                         | [infinity]
378    *                         |
379    * CVodeSetMaxErrTestFails | Maximum number of error test failures
380    *                         | in attempting one step.
381    *                         | [7]
382    *                         |
383    * CVodeSetMaxNonlinIters  | Maximum number of nonlinear solver
384    *                         | iterations at one solution.
385    *                         | [3]
386    *                         |
387    * CVodeSetMaxConvFails    | Maximum number of convergence failures
388    *                         | allowed in attempting one step.
389    *                         | [10]
390    *                         |
391    * CVodeSetNonlinConvCoef  | Coefficient in the nonlinear
392    *                         | convergence test.
393    *                         | [0.1]
394    *                         |
395    * -----------------------------------------------------------------
396    *                         |
397    * CVodeSetIterType        | Changes the current nonlinear iteration
398    *                         | type.
399    *                         | [set by CVodecreate]
400    *                         |
401    * CVodeSetTolerances      | Changes the integration tolerances
402    *                         | between calls to CVode().
403    *                         | [set by CVodeMalloc/CVodeReInit]
404    *                         |
405    * -----------------------------------------------------------------
406    * Return flag:
407    *   CV_SUCCESS   if successful
408    *   CV_MEM_NULL  if the cvode memory is NULL
409    *   CV_ILL_INPUT if an argument has an illegal value
410    * -----------------------------------------------------------------
411    */
412
413   int CVodeSetErrHandlerFn(void *cvode_mem, CVErrHandlerFn ehfun, void *eh_data);
414   int CVodeSetErrFile(void *cvode_mem, FILE *errfp);
415   int CVodeSetFdata(void *cvode_mem, void *f_data);
416   int CVodeSetEwtFn(void *cvode_mem, CVEwtFn efun, void *e_data);
417   int CVodeSetMaxOrd(void *cvode_mem, int maxord);
418   int CVodeSetMaxNumSteps(void *cvode_mem, long int mxsteps);
419   int CVodeSetMaxHnilWarns(void *cvode_mem, int mxhnil);
420   int CVodeSetStabLimDet(void *cvode_mem, booleantype stldet);
421   int CVodeSetInitStep(void *cvode_mem, realtype hin);
422   int CVodeSetMinStep(void *cvode_mem, realtype hmin);
423   int CVodeSetMaxStep(void *cvode_mem, realtype hmax);
424   int CVodeSetStopTime(void *cvode_mem, realtype tstop);
425   int CVodeSetMaxErrTestFails(void *cvode_mem, int maxnef);
426   int CVodeSetMaxNonlinIters(void *cvode_mem, int maxcor);
427   int CVodeSetMaxConvFails(void *cvode_mem, int maxncf);
428   int CVodeSetNonlinConvCoef(void *cvode_mem, realtype nlscoef);
429
430   int CVodeSetIterType(void *cvode_mem, int iter);
431   int CVodeSetTolerances(void *cvode_mem,
432                          int itol, realtype reltol, void *abstol);
433
434   /*
435    * -----------------------------------------------------------------
436    * Function : CVodeMalloc
437    * -----------------------------------------------------------------
438    * CVodeMalloc allocates and initializes memory for a problem to
439    * to be solved by CVODE.
440    *
441    * cvode_mem is pointer to CVODE memory returned by CVodeCreate.
442    *
443    * f       is the name of the C function defining the right-hand
444    *         side function in y' = f(t,y).
445    *
446    * t0      is the initial value of t.
447    *
448    * y0      is the initial condition vector y(t0).
449    *
450    * itol    is the type of tolerances to be used.
451    *         The legal values are:
452    *            CV_SS (scalar relative and absolute tolerances),
453    *            CV_SV (scalar relative tolerance and vector
454    *                absolute tolerance).
455    *            CV_WF (indicates that the user will provide a
456    *                function to evaluate the error weights.
457    *                In this case, reltol and abstol are ignored.)
458    *
459    * reltol  is the relative tolerance scalar.
460    *
461    * abstol  is a pointer to the absolute tolerance scalar or
462    *         an N_Vector of absolute tolerances.
463    *
464    * The parameters itol, reltol, and abstol define a vector of
465    * error weights, ewt, with components
466    *   ewt[i] = 1/(reltol*abs(y[i]) + abstol)   (if itol = CV_SS), or
467    *   ewt[i] = 1/(reltol*abs(y[i]) + abstol[i])   (if itol = CV_SV).
468    * This vector is used in all error and convergence tests, which
469    * use a weighted RMS norm on all error-like vectors v:
470    *    WRMSnorm(v) = sqrt( (1/N) sum(i=1..N) (v[i]*ewt[i])^2 ),
471    * where N is the problem dimension.
472    *
473    * Return flag:
474    *  CV_SUCCESS if successful
475    *  CV_MEM_NULL if the cvode memory was NULL
476    *  CV_MEM_FAIL if a memory allocation failed
477    *  CV_ILL_INPUT f an argument has an illegal value.
478    * -----------------------------------------------------------------
479    */
480
481   int CVodeMalloc(void *cvode_mem, CVRhsFn f, realtype t0, N_Vector y0,
482                   int itol, realtype reltol, void *abstol);
483
484   /*
485    * -----------------------------------------------------------------
486    * Function : CVodeReInit
487    * -----------------------------------------------------------------
488    * CVodeReInit re-initializes CVode for the solution of a problem,
489    * where a prior call to CVodeMalloc has been made with the same
490    * problem size N. CVodeReInit performs the same input checking
491    * and initializations that CVodeMalloc does.
492    * But it does no memory allocation, assuming that the existing
493    * internal memory is sufficient for the new problem.
494    *
495    * The use of CVodeReInit requires that the maximum method order,
496    * maxord, is no larger for the new problem than for the problem
497    * specified in the last call to CVodeMalloc.  This condition is
498    * automatically fulfilled if the multistep method parameter lmm
499    * is unchanged (or changed from CV_ADAMS to CV_BDF) and the default
500    * value for maxord is specified.
501    *
502    * All of the arguments to CVodeReInit have names and meanings
503    * identical to those of CVodeMalloc.
504    *
505    * The return value of CVodeReInit is equal to CV_SUCCESS = 0 if
506    * there were no errors; otherwise it is a negative int equal to:
507    *   CV_MEM_NULL      indicating cvode_mem was NULL (i.e.,
508    *                    CVodeCreate has not been called).
509    *   CV_NO_MALLOC     indicating that cvode_mem has not been
510    *                    allocated (i.e., CVodeMalloc has not been
511    *                    called).
512    *   CV_ILL_INPUT     indicating an input argument was illegal
513    *                    (including an attempt to increase maxord).
514    * In case of an error return, an error message is also printed.
515    * -----------------------------------------------------------------
516    */
517
518   int CVodeReInit(void *cvode_mem, CVRhsFn f, realtype t0, N_Vector y0,
519                   int itol, realtype reltol, void *abstol);
520
521   /*
522    * -----------------------------------------------------------------
523    * Function : CVodeRootInit
524    * -----------------------------------------------------------------
525    * CVodeRootInit initializes a rootfinding problem to be solved
526    * during the integration of the ODE system.  It must be called
527    * after CVodeCreate, and before CVode.  The arguments are:
528    *
529    * cvode_mem = pointer to CVODE memory returned by CVodeCreate.
530    *
531    * nrtfn     = number of functions g_i, an int >= 0.
532    *
533    * g         = name of user-supplied function, of type CVRootFn,
534    *             defining the functions g_i whose roots are sought.
535    *
536    * g_data    = a pointer to user data that will be passed to the 
537    *             user's g function every time g is called.
538    *
539    * If a new problem is to be solved with a call to CVodeReInit,
540    * where the new problem has no root functions but the prior one
541    * did, then call CVodeRootInit with nrtfn = 0.
542    *
543    * The return value of CVodeRootInit is CV_SUCCESS = 0 if there were
544    * no errors; otherwise it is a negative int equal to:
545    *   CV_MEM_NULL     indicating cvode_mem was NULL, or
546    *   CV_MEM_FAIL     indicating a memory allocation failed.
547    *                    (including an attempt to increase maxord).
548    *   CV_ILL_INPUT   indicating nrtfn > 0 but g = NULL.
549    * In case of an error return, an error message is also printed.
550    * -----------------------------------------------------------------
551    */
552
553   int CVodeRootInit(void *cvode_mem, int nrtfn, CVRootFn g, void *g_data);
554
555   /*
556    * -----------------------------------------------------------------
557    * Function : CVode
558    * -----------------------------------------------------------------
559    * CVode integrates the ODE over an interval in t.
560    * If itask is CV_NORMAL, then the solver integrates from its
561    * current internal t value to a point at or beyond tout, then
562    * interpolates to t = tout and returns y(tout) in the user-
563    * allocated vector yout. If itask is CV_ONE_STEP, then the solver
564    * takes one internal time step and returns in yout the value of
565    * y at the new internal time. In this case, tout is used only
566    * during the first call to CVode to determine the direction of
567    * integration and the rough scale of the t variable.  If itask is
568    * CV_NORMAL_TSTOP or CV_ONE_STEP_TSTOP, then CVode returns the
569    * solution at tstop if that comes sooner than tout or the end of
570    * the next internal step, respectively.  In any case,
571    * the time reached by the solver is placed in (*tret). The
572    * user is responsible for allocating the memory for this value.
573    *
574    * cvode_mem is the pointer to CVODE memory returned by
575    *           CVodeCreate.
576    *
577    * tout  is the next time at which a computed solution is desired.
578    *
579    * yout  is the computed solution vector. In CV_NORMAL mode with no
580    *       errors and no roots found, yout=y(tout).
581    *
582    * tret  is a pointer to a real location. CVode sets (*tret) to
583    *       the time reached by the solver and returns
584    *       yout=y(*tret).
585    *
586    * itask is CV_NORMAL, CV_ONE_STEP, CV_NORMAL_TSTOP, or CV_ONE_STEP_TSTOP.
587    *       These four modes are described above.
588    *
589    * Here is a brief description of each return value:
590    *
591    * CV_SUCCESS:      CVode succeeded and no roots were found.
592    *
593    * CV_ROOT_RETURN:  CVode succeeded, and found one or more roots.
594    *                  If nrtfn > 1, call CVodeGetRootInfo to see
595    *                  which g_i were found to have a root at (*tret).
596    *
597    * CV_TSTOP_RETURN: CVode succeeded and returned at tstop.
598    *
599    * CV_MEM_NULL:     The cvode_mem argument was NULL.
600    *
601    * CV_NO_MALLOC:    cvode_mem was not allocated.
602    *
603    * CV_ILL_INPUT:    One of the inputs to CVode is illegal. This
604    *                  includes the situation when a component of the
605    *                  error weight vectors becomes < 0 during
606    *                  internal time-stepping.  It also includes the
607    *                  situation where a root of one of the root
608    *                  functions was found both at t0 and very near t0.
609    *                  The ILL_INPUT flag will also be returned if the
610    *                  linear solver routine CV--- (called by the user
611    *                  after calling CVodeCreate) failed to set one of
612    *                  the linear solver-related fields in cvode_mem or
613    *                  if the linear solver's init routine failed. In
614    *                  any case, the user should see the printed
615    *                  error message for more details.
616    *
617    * CV_TOO_MUCH_WORK: The solver took mxstep internal steps but
618    *                  could not reach tout. The default value for
619    *                  mxstep is MXSTEP_DEFAULT = 500.
620    *
621    * CV_TOO_MUCH_ACC: The solver could not satisfy the accuracy
622    *                  demanded by the user for some internal step.
623    *
624    * CV_ERR_FAILURE:  Error test failures occurred too many times
625    *                  (= MXNEF = 7) during one internal time step or
626    *                  occurred with |h| = hmin.
627    *
628    * CV_CONV_FAILURE: Convergence test failures occurred too many
629    *                  times (= MXNCF = 10) during one internal time
630    *                  step or occurred with |h| = hmin.
631    *
632    * CV_LINIT_FAIL:   The linear solver's initialization function 
633    *                  failed.
634    *
635    * CV_LSETUP_FAIL:  The linear solver's setup routine failed in an
636    *                  unrecoverable manner.
637    *
638    * CV_LSOLVE_FAIL:  The linear solver's solve routine failed in an
639    *                  unrecoverable manner.
640    * -----------------------------------------------------------------
641    */
642
643   int CVode(void *cvode_mem, realtype tout, N_Vector yout,
644             realtype *tret, int itask);
645
646   /*
647    * -----------------------------------------------------------------
648    * Function : CVodeGetDky
649    * -----------------------------------------------------------------
650    * CVodeGetDky computes the kth derivative of the y function at
651    * time t, where tn-hu <= t <= tn, tn denotes the current
652    * internal time reached, and hu is the last internal step size
653    * successfully used by the solver. The user may request
654    * k=0, 1, ..., qu, where qu is the order last used. The
655    * derivative vector is returned in dky. This vector must be
656    * allocated by the caller. It is only legal to call this
657    * function after a successful return from CVode.
658    *
659    * cvode_mem is the pointer to CVODE memory returned by
660    *           CVodeCreate.
661    *
662    * t   is the time at which the kth derivative of y is evaluated.
663    *     The legal range for t is [tn-hu,tn] as described above.
664    *
665    * k   is the order of the derivative of y to be computed. The
666    *     legal range for k is [0,qu] as described above.
667    *
668    * dky is the output derivative vector [((d/dy)^k)y](t).
669    *
670    * The return value for CVodeGetDky is one of:
671    *
672    *   CV_SUCCESS:  CVodeGetDky succeeded.
673    *
674    *   CV_BAD_K:    k is not in the range 0, 1, ..., qu.
675    *
676    *   CV_BAD_T:    t is not in the interval [tn-hu,tn].
677    *
678    *   CV_BAD_DKY:  The dky argument was NULL.
679    *
680    *   CV_MEM_NULL: The cvode_mem argument was NULL.
681    * -----------------------------------------------------------------
682    */
683
684   int CVodeGetDky(void *cvode_mem, realtype t, int k, N_Vector dky);
685
686   /*
687    * -----------------------------------------------------------------
688    * Integrator optional output extraction functions
689    * -----------------------------------------------------------------
690    * The following functions can be called to get optional outputs
691    * and statistics related to the main integrator.
692    * -----------------------------------------------------------------
693    * CVodeGetWorkSpace returns the CVODE real and integer workspaces
694    * CVodeGetNumSteps returns the cumulative number of internal
695    *                  steps taken by the solver
696    * CVodeGetNumRhsEvals returns the number of calls to the user's
697    *                     f function
698    * CVodeGetNumLinSolvSetups returns the number of calls made to
699    *                          the linear solver's setup routine
700    * CVodeGetNumErrTestFails returns the number of local error test
701    *                         failures that have occured
702    * CVodeGetLastOrder returns the order used during the last
703    *                   internal step
704    * CVodeGetCurrentOrder returns the order to be used on the next
705    *                      internal step
706    * CVodeGetNumStabLimOrderReds returns the number of order
707    *                             reductions due to stability limit
708    *                             detection
709    * CVodeGetActualInitStep returns the actual initial step size
710    *                        used by CVODE
711    * CVodeGetLastStep returns the step size for the last internal
712    *                  step
713    * CVodeGetCurrentStep returns the step size to be attempted on
714    *                     the next internal step
715    * CVodeGetCurrentTime returns the current internal time reached
716    *                     by the solver
717    * CVodeGetTolScaleFactor returns a suggested factor by which the
718    *                        user's tolerances should be scaled when
719    *                        too much accuracy has been requested for
720    *                        some internal step
721    * CVodeGetErrWeights returns the current error weight vector.
722    *                    The user must allocate space for eweight.
723    * CVodeGetEstLocalErrors returns the vector of estimated local
724    *                        errors. The user must allocate space
725    *                        for ele.
726    * CVodeGetNumGEvals returns the number of calls to the user's
727    *                   g function (for rootfinding)
728    * CVodeGetRootInfo returns the indices for which g_i was found to 
729    *                  have a root. The user must allocate space for 
730    *                  rootsfound. For i = 0 ... nrtfn-1, 
731    *                  rootsfound[i] = 1 if g_i has a root, and = 0 if not.
732    *
733    * CVodeGet* return values:
734    *   CV_SUCCESS   if succesful
735    *   CV_MEM_NULL  if the cvode memory was NULL
736    *   CV_NO_SLDET  if stability limit was not turned on
737    * -----------------------------------------------------------------
738    */
739
740   int CVodeGetWorkSpace(void *cvode_mem, long int *lenrw, long int *leniw);
741   int CVodeGetNumSteps(void *cvode_mem, long int *nsteps);
742   int CVodeGetNumRhsEvals(void *cvode_mem, long int *nfevals);
743   int CVodeGetNumLinSolvSetups(void *cvode_mem, long int *nlinsetups);
744   int CVodeGetNumErrTestFails(void *cvode_mem, long int *netfails);
745   int CVodeGetLastOrder(void *cvode_mem, int *qlast);
746   int CVodeGetCurrentOrder(void *cvode_mem, int *qcur);
747   int CVodeGetNumStabLimOrderReds(void *cvode_mem, long int *nslred);
748   int CVodeGetActualInitStep(void *cvode_mem, realtype *hinused);
749   int CVodeGetLastStep(void *cvode_mem, realtype *hlast);
750   int CVodeGetCurrentStep(void *cvode_mem, realtype *hcur);
751   int CVodeGetCurrentTime(void *cvode_mem, realtype *tcur);
752   int CVodeGetTolScaleFactor(void *cvode_mem, realtype *tolsfac);
753   int CVodeGetErrWeights(void *cvode_mem, N_Vector eweight);
754   int CVodeGetEstLocalErrors(void *cvode_mem, N_Vector ele);
755   int CVodeGetNumGEvals(void *cvode_mem, long int *ngevals);
756   int CVodeGetRootInfo(void *cvode_mem, int *rootsfound);
757
758   /*
759    * -----------------------------------------------------------------
760    * As a convenience, the following functions provides the
761    * optional outputs in one group.
762    * -----------------------------------------------------------------
763    */
764
765   int CVodeGetIntegratorStats(void *cvode_mem, long int *nsteps,
766                               long int *nfevals, long int *nlinsetups,
767                               long int *netfails, int *qlast,
768                               int *qcur, realtype *hinused, realtype *hlast,
769                               realtype *hcur, realtype *tcur);
770
771   /*
772    * -----------------------------------------------------------------
773    * Nonlinear solver optional output extraction functions
774    * -----------------------------------------------------------------
775    * The following functions can be called to get optional outputs
776    * and statistics related to the nonlinear solver.
777    * -----------------------------------------------------------------
778    * CVodeGetNumNonlinSolvIters returns the number of nonlinear
779    *                            solver iterations performed.
780    * CVodeGetNumNonlinSolvConvFails returns the number of nonlinear
781    *                                convergence failures.
782    * -----------------------------------------------------------------
783    */
784
785   int CVodeGetNumNonlinSolvIters(void *cvode_mem, long int *nniters);
786   int CVodeGetNumNonlinSolvConvFails(void *cvode_mem, long int *nncfails);
787
788   /*
789    * -----------------------------------------------------------------
790    * As a convenience, the following function provides the
791    * nonlinear solver optional outputs in a group.
792    * -----------------------------------------------------------------
793    */
794
795   int CVodeGetNonlinSolvStats(void *cvode_mem, long int *nniters,
796                               long int *nncfails);
797
798   /*
799    * -----------------------------------------------------------------
800    * The following function returns the name of the constant 
801    * associated with a CVODE return flag
802    * -----------------------------------------------------------------
803    */
804
805   char *CVodeGetReturnFlagName(int flag);
806
807   /*
808    * -----------------------------------------------------------------
809    * Function : CVodeFree
810    * -----------------------------------------------------------------
811    * CVodeFree frees the problem memory cvode_mem allocated by
812    * CVodeCreate and CVodeMalloc.  Its only argument is the pointer
813    * cvode_mem returned by CVodeCreate.
814    * -----------------------------------------------------------------
815    */
816
817   void CVodeFree(void **cvode_mem);
818
819 #ifdef __cplusplus
820 }
821 #endif
822
823 #endif