Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Blame
Revision Log

cvodes.h @ 16222

Visit:

Last change on this file since 16222 was 16222, checked in by gkronber, 4 years ago

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 */
100	extern "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
290	typedef 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
312	typedef 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
337	typedef 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
357	typedef 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
386	typedef 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
415	typedef 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
447	typedef 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
477	typedef 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
499	typedef int (*CVRhsFnB)(realtype t, N_Vector y,
500	N_Vector yB, N_Vector yBdot,
501	void *user_dataB);
502
503	typedef int (CVRhsFnBS)(realtype t, N_Vector y, N_Vector yS,
504	N_Vector yB, N_Vector yBdot,
505	void *user_dataB);
506
507
508	typedef int (*CVQuadRhsFnB)(realtype t, N_Vector y,
509	N_Vector yB, N_Vector qBdot,
510	void *user_dataB);
511
512	typedef 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
547	SUNDIALS_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
589	SUNDIALS_EXPORT int CVodeInit(void *cvode_mem, CVRhsFn f, realtype t0, N_Vector y0);
590	SUNDIALS_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
631	SUNDIALS_EXPORT int CVodeSStolerances(void *cvode_mem, realtype reltol, realtype abstol);
632	SUNDIALS_EXPORT int CVodeSVtolerances(void *cvode_mem, realtype reltol, N_Vector abstol);
633	SUNDIALS_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
664	SUNDIALS_EXPORT int CVodeQuadInit(void *cvode_mem, CVQuadRhsFn fQ, N_Vector yQ0);
665	SUNDIALS_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
692	SUNDIALS_EXPORT int CVodeQuadSStolerances(void *cvode_mem, realtype reltolQ, realtype abstolQ);
693	SUNDIALS_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
743	SUNDIALS_EXPORT int CVodeSensInit(void *cvode_mem, int Ns, int ism,
744	CVSensRhsFn fS, N_Vector *yS0);
745	SUNDIALS_EXPORT int CVodeSensInit1(void *cvode_mem, int Ns, int ism,
746	CVSensRhs1Fn fS1, N_Vector *yS0);
747	SUNDIALS_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
777	SUNDIALS_EXPORT int CVodeSensSStolerances(void cvode_mem, realtype reltolS, realtype abstolS);
778	SUNDIALS_EXPORT int CVodeSensSVtolerances(void cvode_mem, realtype reltolS, N_Vector abstolS);
779	SUNDIALS_EXPORT int CVodeSensEEtolerances(void *cvode_mem);
780
781	/*
782	* -----------------------------------------------------------------
783	* Function : CVodeQuadSensInit and CVodeQuadSensReInit
784	* -----------------------------------------------------------------
785	* -----------------------------------------------------------------
786	*/
787
788	SUNDIALS_EXPORT int CVodeQuadSensInit(void cvode_mem, CVQuadSensRhsFn fQS, N_Vector yQS0);
789	SUNDIALS_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
822	SUNDIALS_EXPORT int CVodeQuadSensSStolerances(void cvode_mem, realtype reltolQS, realtype abstolQS);
823	SUNDIALS_EXPORT int CVodeQuadSensSVtolerances(void cvode_mem, realtype reltolQS, N_Vector abstolQS);
824	SUNDIALS_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
855	SUNDIALS_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
867	SUNDIALS_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
879	SUNDIALS_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
891	SUNDIALS_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
903	SUNDIALS_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
1038	SUNDIALS_EXPORT int CVodeSetErrHandlerFn(void cvode_mem, CVErrHandlerFn ehfun, void eh_data);
1039	SUNDIALS_EXPORT int CVodeSetErrFile(void cvode_mem, FILE errfp);
1040	SUNDIALS_EXPORT int CVodeSetUserData(void cvode_mem, void user_data);
1041	SUNDIALS_EXPORT int CVodeSetMaxOrd(void *cvode_mem, int maxord);
1042	SUNDIALS_EXPORT int CVodeSetMaxNumSteps(void *cvode_mem, long int mxsteps);
1043	SUNDIALS_EXPORT int CVodeSetMaxHnilWarns(void *cvode_mem, int mxhnil);
1044	SUNDIALS_EXPORT int CVodeSetStabLimDet(void *cvode_mem, booleantype stldet);
1045	SUNDIALS_EXPORT int CVodeSetInitStep(void *cvode_mem, realtype hin);
1046	SUNDIALS_EXPORT int CVodeSetMinStep(void *cvode_mem, realtype hmin);
1047	SUNDIALS_EXPORT int CVodeSetMaxStep(void *cvode_mem, realtype hmax);
1048	SUNDIALS_EXPORT int CVodeSetStopTime(void *cvode_mem, realtype tstop);
1049	SUNDIALS_EXPORT int CVodeSetMaxErrTestFails(void *cvode_mem, int maxnef);
1050	SUNDIALS_EXPORT int CVodeSetMaxNonlinIters(void *cvode_mem, int maxcor);
1051	SUNDIALS_EXPORT int CVodeSetMaxConvFails(void *cvode_mem, int maxncf);
1052	SUNDIALS_EXPORT int CVodeSetNonlinConvCoef(void *cvode_mem, realtype nlscoef);
1053	SUNDIALS_EXPORT int CVodeSetConstraints(void *cvode_mem, N_Vector constraints);
1054
1055	SUNDIALS_EXPORT int CVodeSetIterType(void *cvode_mem, int iter);
1056
1057	SUNDIALS_EXPORT int CVodeSetRootDirection(void cvode_mem, int rootdir);
1058	SUNDIALS_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
1084	SUNDIALS_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
1129	SUNDIALS_EXPORT int CVodeSetSensDQMethod(void *cvode_mem, int DQtype, realtype DQrhomax);
1130	SUNDIALS_EXPORT int CVodeSetSensErrCon(void *cvode_mem, booleantype errconS);
1131	SUNDIALS_EXPORT int CVodeSetSensMaxNonlinIters(void *cvode_mem, int maxcorS);
1132	SUNDIALS_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
1157	SUNDIALS_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
1173	SUNDIALS_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
1272	SUNDIALS_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
1323	SUNDIALS_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
1346	SUNDIALS_EXPORT int CVodeGetQuad(void cvode_mem, realtype tret, N_Vector yQout);
1347
1348	SUNDIALS_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
1387	SUNDIALS_EXPORT int CVodeGetSens(void cvode_mem, realtype tret, N_Vector *ySout);
1388	SUNDIALS_EXPORT int CVodeGetSens1(void cvode_mem, realtype tret, int is, N_Vector ySout);
1389
1390	SUNDIALS_EXPORT int CVodeGetSensDky(void cvode_mem, realtype t, int k, N_Vector dkyA);
1391	SUNDIALS_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
1430	SUNDIALS_EXPORT int CVodeGetQuadSens(void cvode_mem, realtype tret, N_Vector *yQSout);
1431	SUNDIALS_EXPORT int CVodeGetQuadSens1(void cvode_mem, realtype tret, int is, N_Vector yQSout);
1432
1433	SUNDIALS_EXPORT int CVodeGetQuadSensDky(void cvode_mem, realtype t, int k, N_Vector dkyQS_all);
1434	SUNDIALS_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
1496	SUNDIALS_EXPORT int CVodeGetWorkSpace(void cvode_mem, long int lenrw, long int *leniw);
1497	SUNDIALS_EXPORT int CVodeGetNumSteps(void cvode_mem, long int nsteps);
1498	SUNDIALS_EXPORT int CVodeGetNumRhsEvals(void cvode_mem, long int nfevals);
1499	SUNDIALS_EXPORT int CVodeGetNumLinSolvSetups(void cvode_mem, long int nlinsetups);
1500	SUNDIALS_EXPORT int CVodeGetNumErrTestFails(void cvode_mem, long int netfails);
1501	SUNDIALS_EXPORT int CVodeGetLastOrder(void cvode_mem, int qlast);
1502	SUNDIALS_EXPORT int CVodeGetCurrentOrder(void cvode_mem, int qcur);
1503	SUNDIALS_EXPORT int CVodeGetNumStabLimOrderReds(void cvode_mem, long int nslred);
1504	SUNDIALS_EXPORT int CVodeGetActualInitStep(void cvode_mem, realtype hinused);
1505	SUNDIALS_EXPORT int CVodeGetLastStep(void cvode_mem, realtype hlast);
1506	SUNDIALS_EXPORT int CVodeGetCurrentStep(void cvode_mem, realtype hcur);
1507	SUNDIALS_EXPORT int CVodeGetCurrentTime(void cvode_mem, realtype tcur);
1508	SUNDIALS_EXPORT int CVodeGetTolScaleFactor(void cvode_mem, realtype tolsfac);
1509	SUNDIALS_EXPORT int CVodeGetErrWeights(void *cvode_mem, N_Vector eweight);
1510	SUNDIALS_EXPORT int CVodeGetEstLocalErrors(void *cvode_mem, N_Vector ele);
1511	SUNDIALS_EXPORT int CVodeGetNumGEvals(void cvode_mem, long int ngevals);
1512	SUNDIALS_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
1521	SUNDIALS_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
1541	SUNDIALS_EXPORT int CVodeGetNumNonlinSolvIters(void cvode_mem, long int nniters);
1542	SUNDIALS_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
1551	SUNDIALS_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
1562	SUNDIALS_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
1582	SUNDIALS_EXPORT int CVodeGetQuadNumRhsEvals(void cvode_mem, long int nfQevals);
1583	SUNDIALS_EXPORT int CVodeGetQuadNumErrTestFails(void cvode_mem, long int nQetfails);
1584	SUNDIALS_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
1593	SUNDIALS_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
1617	SUNDIALS_EXPORT int CVodeGetSensNumRhsEvals(void cvode_mem, long int nfSevals);
1618	SUNDIALS_EXPORT int CVodeGetNumRhsEvalsSens(void cvode_mem, long int nfevalsS);
1619	SUNDIALS_EXPORT int CVodeGetSensNumErrTestFails(void cvode_mem, long int nSetfails);
1620	SUNDIALS_EXPORT int CVodeGetSensNumLinSolvSetups(void cvode_mem, long int nlinsetupsS);
1621	SUNDIALS_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
1630	SUNDIALS_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
1653	SUNDIALS_EXPORT int CVodeGetSensNumNonlinSolvIters(void cvode_mem, long int nSniters);
1654	SUNDIALS_EXPORT int CVodeGetSensNumNonlinSolvConvFails(void cvode_mem, long int nSncfails);
1655	SUNDIALS_EXPORT int CVodeGetStgrSensNumNonlinSolvIters(void cvode_mem, long int nSTGR1niters);
1656	SUNDIALS_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
1666	SUNDIALS_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
1688	SUNDIALS_EXPORT int CVodeGetQuadSensNumRhsEvals(void cvode_mem, long int nfQSevals);
1689	SUNDIALS_EXPORT int CVodeGetQuadSensNumErrTestFails(void cvode_mem, long int nQSetfails);
1690	SUNDIALS_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
1699	SUNDIALS_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
1721	SUNDIALS_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
1741	SUNDIALS_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
1752	SUNDIALS_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
1768	SUNDIALS_EXPORT int CVodeCreateB(void cvode_mem, int lmmB, int iterB, int which);
1769
1770	SUNDIALS_EXPORT int CVodeInitB(void *cvode_mem, int which,
1771	CVRhsFnB fB,
1772	realtype tB0, N_Vector yB0);
1773	SUNDIALS_EXPORT int CVodeInitBS(void *cvode_mem, int which,
1774	CVRhsFnBS fBs,
1775	realtype tB0, N_Vector yB0);
1776	SUNDIALS_EXPORT int CVodeReInitB(void *cvode_mem, int which,
1777	realtype tB0, N_Vector yB0);
1778
1779	SUNDIALS_EXPORT int CVodeSStolerancesB(void *cvode_mem, int which,
1780	realtype reltolB, realtype abstolB);
1781	SUNDIALS_EXPORT int CVodeSVtolerancesB(void *cvode_mem, int which,
1782	realtype reltolB, N_Vector abstolB);
1783
1784	SUNDIALS_EXPORT int CVodeQuadInitB(void *cvode_mem, int which,
1785	CVQuadRhsFnB fQB, N_Vector yQB0);
1786	SUNDIALS_EXPORT int CVodeQuadInitBS(void *cvode_mem, int which,
1787	CVQuadRhsFnBS fQBs, N_Vector yQB0);
1788	SUNDIALS_EXPORT int CVodeQuadReInitB(void *cvode_mem, int which, N_Vector yQB0);
1789
1790	SUNDIALS_EXPORT int CVodeQuadSStolerancesB(void *cvode_mem, int which,
1791	realtype reltolQB, realtype abstolQB);
1792	SUNDIALS_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
1817	SUNDIALS_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
1835	SUNDIALS_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
1851	SUNDIALS_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
1863	SUNDIALS_EXPORT int CVodeSetIterTypeB(void *cvode_mem, int which, int iterB);
1864	SUNDIALS_EXPORT int CVodeSetUserDataB(void cvode_mem, int which, void user_dataB);
1865	SUNDIALS_EXPORT int CVodeSetMaxOrdB(void *cvode_mem, int which, int maxordB);
1866	SUNDIALS_EXPORT int CVodeSetMaxNumStepsB(void *cvode_mem, int which, long int mxstepsB);
1867	SUNDIALS_EXPORT int CVodeSetStabLimDetB(void *cvode_mem, int which, booleantype stldetB);
1868	SUNDIALS_EXPORT int CVodeSetInitStepB(void *cvode_mem, int which, realtype hinB);
1869	SUNDIALS_EXPORT int CVodeSetMinStepB(void *cvode_mem, int which, realtype hminB);
1870	SUNDIALS_EXPORT int CVodeSetMaxStepB(void *cvode_mem, int which, realtype hmaxB);
1871	SUNDIALS_EXPORT int CVodeSetConstraintsB(void *cvode_mem, int which, N_Vector constraintsB);
1872	SUNDIALS_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
1897	SUNDIALS_EXPORT int CVodeGetB(void *cvode_mem, int which,
1898	realtype *tBret, N_Vector yB);
1899	SUNDIALS_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
1923	SUNDIALS_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
1936	SUNDIALS_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
1946	typedef 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
1956	SUNDIALS_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
1973	SUNDIALS_EXPORT int CVodeGetAdjDataPointHermite(void *cvode_mem, int which,
1974	realtype *t, N_Vector y, N_Vector yd);
1975
1976	SUNDIALS_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
1986	SUNDIALS_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.

Context Navigation

source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/cvodes/cvodes.h @ 16222

Download in other formats: