1 /* -----------------------------------------------------------------
2  * Programmer(s): Scott D. Cohen, Alan C. Hindmarsh, Radu Serban,
3  *                and Dan Shumaker @ LLNL
4  * -----------------------------------------------------------------
5  * SUNDIALS Copyright Start
6  * Copyright (c) 2002-2020, Lawrence Livermore National Security
7  * and Southern Methodist University.
8  * All rights reserved.
9  *
10  * See the top-level LICENSE and NOTICE files for details.
11  *
12  * SPDX-License-Identifier: BSD-3-Clause
13  * SUNDIALS Copyright End
14  * -----------------------------------------------------------------
15  * This is the header file for the main CVODE integrator.
16  * -----------------------------------------------------------------*/
17 
18 #ifndef _CVODE_H
19 #define _CVODE_H
20 
21 #include <stdio.h>
22 #include <sundials/sundials_nvector.h>
23 #include <sundials/sundials_nonlinearsolver.h>
24 #include <cvode/cvode_ls.h>
25 #include <cvode/cvode_proj.h>
26 
27 #ifdef __cplusplus  /* wrapper to enable C++ usage */
28 extern "C" {
29 #endif
30 
31 /* -----------------
32  * CVODE Constants
33  * ----------------- */
34 
35 /* lmm */
36 #define CV_ADAMS          1
37 #define CV_BDF            2
38 
39 /* itask */
40 #define CV_NORMAL         1
41 #define CV_ONE_STEP       2
42 
43 
44 /* return values */
45 
46 #define CV_SUCCESS               0
47 #define CV_TSTOP_RETURN          1
48 #define CV_ROOT_RETURN           2
49 
50 #define CV_WARNING              99
51 
52 #define CV_TOO_MUCH_WORK        -1
53 #define CV_TOO_MUCH_ACC         -2
54 #define CV_ERR_FAILURE          -3
55 #define CV_CONV_FAILURE         -4
56 
57 #define CV_LINIT_FAIL           -5
58 #define CV_LSETUP_FAIL          -6
59 #define CV_LSOLVE_FAIL          -7
60 #define CV_RHSFUNC_FAIL         -8
61 #define CV_FIRST_RHSFUNC_ERR    -9
62 #define CV_REPTD_RHSFUNC_ERR    -10
63 #define CV_UNREC_RHSFUNC_ERR    -11
64 #define CV_RTFUNC_FAIL          -12
65 #define CV_NLS_INIT_FAIL        -13
66 #define CV_NLS_SETUP_FAIL       -14
67 #define CV_CONSTR_FAIL          -15
68 #define CV_NLS_FAIL             -16
69 
70 #define CV_MEM_FAIL             -20
71 #define CV_MEM_NULL             -21
72 #define CV_ILL_INPUT            -22
73 #define CV_NO_MALLOC            -23
74 #define CV_BAD_K                -24
75 #define CV_BAD_T                -25
76 #define CV_BAD_DKY              -26
77 #define CV_TOO_CLOSE            -27
78 #define CV_VECTOROP_ERR         -28
79 
80 #define CV_PROJ_MEM_NULL        -29
81 #define CV_PROJFUNC_FAIL        -30
82 #define CV_REPTD_PROJFUNC_ERR   -31
83 
84 #define CV_UNRECOGNIZED_ERR     -99
85 
86 
87 /* ------------------------------
88  * User-Supplied Function Types
89  * ------------------------------ */
90 
91 typedef int (*CVRhsFn)(realtype t, N_Vector y,
92                        N_Vector ydot, void *user_data);
93 
94 typedef int (*CVRootFn)(realtype t, N_Vector y, realtype *gout,
95                         void *user_data);
96 
97 typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void *user_data);
98 
99 typedef void (*CVErrHandlerFn)(int error_code,
100                                const char *module, const char *function,
101                                char *msg, void *user_data);
102 
103 typedef int (*CVMonitorFn)(void *cvode_mem, void *user_data);
104 
105 /* -------------------
106  * Exported Functions
107  * ------------------- */
108 
109 /* Initialization functions */
110 SUNDIALS_EXPORT void *CVodeCreate(int lmm);
111 
112 SUNDIALS_EXPORT int CVodeInit(void *cvode_mem, CVRhsFn f, realtype t0,
113                               N_Vector y0);
114 SUNDIALS_EXPORT int CVodeReInit(void *cvode_mem, realtype t0, N_Vector y0);
115 
116 /* Tolerance input functions */
117 SUNDIALS_EXPORT int CVodeSStolerances(void *cvode_mem, realtype reltol,
118                                       realtype abstol);
119 SUNDIALS_EXPORT int CVodeSVtolerances(void *cvode_mem, realtype reltol,
120                                       N_Vector abstol);
121 SUNDIALS_EXPORT int CVodeWFtolerances(void *cvode_mem, CVEwtFn efun);
122 
123 /* Optional input functions */
124 SUNDIALS_EXPORT int CVodeSetErrHandlerFn(void *cvode_mem, CVErrHandlerFn ehfun,
125                                          void *eh_data);
126 SUNDIALS_EXPORT int CVodeSetErrFile(void *cvode_mem, FILE *errfp);
127 SUNDIALS_EXPORT int CVodeSetUserData(void *cvode_mem, void *user_data);
128 SUNDIALS_EXPORT int CVodeSetMonitorFn(void *cvode_mem, CVMonitorFn fn);
129 SUNDIALS_EXPORT int CVodeSetMonitorFrequency(void *cvode_mem, long int nst);
130 SUNDIALS_EXPORT int CVodeSetMaxOrd(void *cvode_mem, int maxord);
131 SUNDIALS_EXPORT int CVodeSetMaxNumSteps(void *cvode_mem, long int mxsteps);
132 SUNDIALS_EXPORT int CVodeSetMaxHnilWarns(void *cvode_mem, int mxhnil);
133 SUNDIALS_EXPORT int CVodeSetStabLimDet(void *cvode_mem, booleantype stldet);
134 SUNDIALS_EXPORT int CVodeSetInitStep(void *cvode_mem, realtype hin);
135 SUNDIALS_EXPORT int CVodeSetMinStep(void *cvode_mem, realtype hmin);
136 SUNDIALS_EXPORT int CVodeSetMaxStep(void *cvode_mem, realtype hmax);
137 SUNDIALS_EXPORT int CVodeSetStopTime(void *cvode_mem, realtype tstop);
138 SUNDIALS_EXPORT int CVodeSetMaxErrTestFails(void *cvode_mem, int maxnef);
139 SUNDIALS_EXPORT int CVodeSetMaxNonlinIters(void *cvode_mem, int maxcor);
140 SUNDIALS_EXPORT int CVodeSetMaxConvFails(void *cvode_mem, int maxncf);
141 SUNDIALS_EXPORT int CVodeSetNonlinConvCoef(void *cvode_mem, realtype nlscoef);
142 SUNDIALS_EXPORT int CVodeSetConstraints(void *cvode_mem, N_Vector constraints);
143 SUNDIALS_EXPORT int CVodeSetNonlinearSolver(void *cvode_mem,
144                                             SUNNonlinearSolver NLS);
145 SUNDIALS_EXPORT int CVodeSetUseIntegratorFusedKernels(void *cvode_mem, booleantype onoff);
146 
147 /* Rootfinding initialization function */
148 SUNDIALS_EXPORT int CVodeRootInit(void *cvode_mem, int nrtfn, CVRootFn g);
149 
150 /* Rootfinding optional input functions */
151 SUNDIALS_EXPORT int CVodeSetRootDirection(void *cvode_mem, int *rootdir);
152 SUNDIALS_EXPORT int CVodeSetNoInactiveRootWarn(void *cvode_mem);
153 
154 /* Solver function */
155 SUNDIALS_EXPORT int CVode(void *cvode_mem, realtype tout, N_Vector yout,
156                           realtype *tret, int itask);
157 
158 /* Dense output function */
159 SUNDIALS_EXPORT int CVodeGetDky(void *cvode_mem, realtype t, int k,
160                                 N_Vector dky);
161 
162 /* Optional output functions */
163 SUNDIALS_EXPORT int CVodeGetWorkSpace(void *cvode_mem, long int *lenrw,
164                                       long int *leniw);
165 SUNDIALS_EXPORT int CVodeGetNumSteps(void *cvode_mem, long int *nsteps);
166 SUNDIALS_EXPORT int CVodeGetNumRhsEvals(void *cvode_mem, long int *nfevals);
167 SUNDIALS_EXPORT int CVodeGetNumLinSolvSetups(void *cvode_mem,
168                                              long int *nlinsetups);
169 SUNDIALS_EXPORT int CVodeGetNumErrTestFails(void *cvode_mem,
170                                             long int *netfails);
171 SUNDIALS_EXPORT int CVodeGetLastOrder(void *cvode_mem, int *qlast);
172 SUNDIALS_EXPORT int CVodeGetCurrentOrder(void *cvode_mem, int *qcur);
173 SUNDIALS_EXPORT int CVodeGetCurrentGamma(void *cvode_mem, realtype *gamma);
174 SUNDIALS_EXPORT int CVodeGetNumStabLimOrderReds(void *cvode_mem,
175                                                 long int *nslred);
176 SUNDIALS_EXPORT int CVodeGetActualInitStep(void *cvode_mem, realtype *hinused);
177 SUNDIALS_EXPORT int CVodeGetLastStep(void *cvode_mem, realtype *hlast);
178 SUNDIALS_EXPORT int CVodeGetCurrentStep(void *cvode_mem, realtype *hcur);
179 SUNDIALS_EXPORT int CVodeGetCurrentState(void *cvode_mem, N_Vector *y);
180 SUNDIALS_EXPORT int CVodeGetCurrentTime(void *cvode_mem, realtype *tcur);
181 SUNDIALS_EXPORT int CVodeGetTolScaleFactor(void *cvode_mem, realtype *tolsfac);
182 SUNDIALS_EXPORT int CVodeGetErrWeights(void *cvode_mem, N_Vector eweight);
183 SUNDIALS_EXPORT int CVodeGetEstLocalErrors(void *cvode_mem, N_Vector ele);
184 SUNDIALS_EXPORT int CVodeGetNumGEvals(void *cvode_mem, long int *ngevals);
185 SUNDIALS_EXPORT int CVodeGetRootInfo(void *cvode_mem, int *rootsfound);
186 SUNDIALS_EXPORT int CVodeGetIntegratorStats(void *cvode_mem, long int *nsteps,
187                                             long int *nfevals,
188                                             long int *nlinsetups,
189                                             long int *netfails,
190                                             int *qlast, int *qcur,
191                                             realtype *hinused, realtype *hlast,
192                                             realtype *hcur, realtype *tcur);
193 SUNDIALS_EXPORT int CVodeGetNumNonlinSolvIters(void *cvode_mem,
194                                                long int *nniters);
195 SUNDIALS_EXPORT int CVodeGetNumNonlinSolvConvFails(void *cvode_mem,
196                                                    long int *nncfails);
197 SUNDIALS_EXPORT int CVodeGetNonlinSolvStats(void *cvode_mem, long int *nniters,
198                                             long int *nncfails);
199 SUNDIALS_EXPORT char *CVodeGetReturnFlagName(long int flag);
200 
201 /* Free function */
202 SUNDIALS_EXPORT void CVodeFree(void **cvode_mem);
203 
204 /* CVLS interface function that depends on CVRhsFn */
205 SUNDIALS_EXPORT int CVodeSetJacTimesRhsFn(void *cvode_mem,
206                                           CVRhsFn jtimesRhsFn);
207 
208 #ifdef __cplusplus
209 }
210 #endif
211 
212 #endif
213