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