1 /* -----------------------------------------------------------------
2  * Programmer(s): Allan G. Taylor, Alan C. Hindmarsh, Radu Serban,
3  *                and Aaron Collier @ LLNL
4  * -----------------------------------------------------------------
5  * SUNDIALS Copyright Start
6  * Copyright (c) 2002-2021, 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 IDA solver.
16  * -----------------------------------------------------------------*/
17 
18 #ifndef _IDA_H
19 #define _IDA_H
20 
21 #include <stdio.h>
22 #include <sundials/sundials_nvector.h>
23 #include <sundials/sundials_nonlinearsolver.h>
24 #include <ida/ida_ls.h>
25 
26 #ifdef __cplusplus  /* wrapper to enable C++ usage */
27 extern "C" {
28 #endif
29 
30 /* -----------------
31  * IDA Constants
32  * ----------------- */
33 
34 /* itask */
35 #define IDA_NORMAL           1
36 #define IDA_ONE_STEP         2
37 
38 /* icopt */
39 #define IDA_YA_YDP_INIT      1
40 #define IDA_Y_INIT           2
41 
42 /* return values */
43 
44 #define IDA_SUCCESS          0
45 #define IDA_TSTOP_RETURN     1
46 #define IDA_ROOT_RETURN      2
47 
48 #define IDA_WARNING          99
49 
50 #define IDA_TOO_MUCH_WORK   -1
51 #define IDA_TOO_MUCH_ACC    -2
52 #define IDA_ERR_FAIL        -3
53 #define IDA_CONV_FAIL       -4
54 
55 #define IDA_LINIT_FAIL      -5
56 #define IDA_LSETUP_FAIL     -6
57 #define IDA_LSOLVE_FAIL     -7
58 #define IDA_RES_FAIL        -8
59 #define IDA_REP_RES_ERR     -9
60 #define IDA_RTFUNC_FAIL     -10
61 #define IDA_CONSTR_FAIL     -11
62 
63 #define IDA_FIRST_RES_FAIL  -12
64 #define IDA_LINESEARCH_FAIL -13
65 #define IDA_NO_RECOVERY     -14
66 #define IDA_NLS_INIT_FAIL   -15
67 #define IDA_NLS_SETUP_FAIL  -16
68 #define IDA_NLS_FAIL        -17
69 
70 #define IDA_MEM_NULL        -20
71 #define IDA_MEM_FAIL        -21
72 #define IDA_ILL_INPUT       -22
73 #define IDA_NO_MALLOC       -23
74 #define IDA_BAD_EWT         -24
75 #define IDA_BAD_K           -25
76 #define IDA_BAD_T           -26
77 #define IDA_BAD_DKY         -27
78 #define IDA_VECTOROP_ERR    -28
79 
80 #define IDA_UNRECOGNIZED_ERROR -99
81 
82 
83 /* ------------------------------
84  * User-Supplied Function Types
85  * ------------------------------ */
86 
87 typedef int (*IDAResFn)(realtype tt, N_Vector yy, N_Vector yp,
88                         N_Vector rr, void *user_data);
89 
90 typedef int (*IDARootFn)(realtype t, N_Vector y, N_Vector yp,
91                          realtype *gout, void *user_data);
92 
93 typedef int (*IDAEwtFn)(N_Vector y, N_Vector ewt, void *user_data);
94 
95 typedef void (*IDAErrHandlerFn)(int error_code,
96                                 const char *module, const char *function,
97                                 char *msg, void *user_data);
98 
99 /* -------------------
100  * Exported Functions
101  * ------------------- */
102 
103 /* Initialization functions */
104 SUNDIALS_EXPORT void *IDACreate(void);
105 
106 SUNDIALS_EXPORT int IDAInit(void *ida_mem, IDAResFn res, realtype t0,
107                             N_Vector yy0, N_Vector yp0);
108 SUNDIALS_EXPORT int IDAReInit(void *ida_mem, realtype t0, N_Vector yy0,
109                               N_Vector yp0);
110 
111 /* Tolerance input functions */
112 SUNDIALS_EXPORT int IDASStolerances(void *ida_mem, realtype reltol,
113                                     realtype abstol);
114 SUNDIALS_EXPORT int IDASVtolerances(void *ida_mem, realtype reltol,
115                                     N_Vector abstol);
116 SUNDIALS_EXPORT int IDAWFtolerances(void *ida_mem, IDAEwtFn efun);
117 
118 /* Initial condition calculation function */
119 SUNDIALS_EXPORT int IDACalcIC(void *ida_mem, int icopt, realtype tout1);
120 
121 /* Initial condition calculation optional input functions */
122 SUNDIALS_EXPORT int IDASetNonlinConvCoefIC(void *ida_mem, realtype epiccon);
123 SUNDIALS_EXPORT int IDASetMaxNumStepsIC(void *ida_mem, int maxnh);
124 SUNDIALS_EXPORT int IDASetMaxNumJacsIC(void *ida_mem, int maxnj);
125 SUNDIALS_EXPORT int IDASetMaxNumItersIC(void *ida_mem, int maxnit);
126 SUNDIALS_EXPORT int IDASetLineSearchOffIC(void *ida_mem, booleantype lsoff);
127 SUNDIALS_EXPORT int IDASetStepToleranceIC(void *ida_mem, realtype steptol);
128 SUNDIALS_EXPORT int IDASetMaxBacksIC(void *ida_mem, int maxbacks);
129 
130 /* Optional input functions */
131 SUNDIALS_EXPORT int IDASetErrHandlerFn(void *ida_mem, IDAErrHandlerFn ehfun,
132                                        void *eh_data);
133 SUNDIALS_EXPORT int IDASetErrFile(void *ida_mem, FILE *errfp);
134 SUNDIALS_EXPORT int IDASetUserData(void *ida_mem, void *user_data);
135 SUNDIALS_EXPORT int IDASetMaxOrd(void *ida_mem, int maxord);
136 SUNDIALS_EXPORT int IDASetMaxNumSteps(void *ida_mem, long int mxsteps);
137 SUNDIALS_EXPORT int IDASetInitStep(void *ida_mem, realtype hin);
138 SUNDIALS_EXPORT int IDASetMaxStep(void *ida_mem, realtype hmax);
139 SUNDIALS_EXPORT int IDASetStopTime(void *ida_mem, realtype tstop);
140 SUNDIALS_EXPORT int IDASetNonlinConvCoef(void *ida_mem, realtype epcon);
141 SUNDIALS_EXPORT int IDASetMaxErrTestFails(void *ida_mem, int maxnef);
142 SUNDIALS_EXPORT int IDASetMaxNonlinIters(void *ida_mem, int maxcor);
143 SUNDIALS_EXPORT int IDASetMaxConvFails(void *ida_mem, int maxncf);
144 SUNDIALS_EXPORT int IDASetSuppressAlg(void *ida_mem, booleantype suppressalg);
145 SUNDIALS_EXPORT int IDASetId(void *ida_mem, N_Vector id);
146 SUNDIALS_EXPORT int IDASetConstraints(void *ida_mem, N_Vector constraints);
147 
148 SUNDIALS_EXPORT int IDASetNonlinearSolver(void *ida_mem,
149                                           SUNNonlinearSolver NLS);
150 
151 /* Rootfinding initialization function */
152 SUNDIALS_EXPORT int IDARootInit(void *ida_mem, int nrtfn, IDARootFn g);
153 
154 /* Rootfinding optional input functions */
155 SUNDIALS_EXPORT int IDASetRootDirection(void *ida_mem, int *rootdir);
156 SUNDIALS_EXPORT int IDASetNoInactiveRootWarn(void *ida_mem);
157 
158 /* Solver function */
159 SUNDIALS_EXPORT int IDASolve(void *ida_mem, realtype tout, realtype *tret,
160                              N_Vector yret, N_Vector ypret, int itask);
161 
162 /* Utility functions to update/compute y and yp based on ycor */
163 SUNDIALS_EXPORT int IDAComputeY(void *ida_mem, N_Vector ycor, N_Vector y);
164 SUNDIALS_EXPORT int IDAComputeYp(void *ida_mem, N_Vector ycor, N_Vector yp);
165 
166 /* Dense output function */
167 SUNDIALS_EXPORT int IDAGetDky(void *ida_mem, realtype t, int k, N_Vector dky);
168 
169 /* Optional output functions */
170 SUNDIALS_EXPORT int IDAGetWorkSpace(void *ida_mem, long int *lenrw,
171                                     long int *leniw);
172 SUNDIALS_EXPORT int IDAGetNumSteps(void *ida_mem, long int *nsteps);
173 SUNDIALS_EXPORT int IDAGetNumResEvals(void *ida_mem, long int *nrevals);
174 SUNDIALS_EXPORT int IDAGetNumLinSolvSetups(void *ida_mem, long int *nlinsetups);
175 SUNDIALS_EXPORT int IDAGetNumErrTestFails(void *ida_mem, long int *netfails);
176 SUNDIALS_EXPORT int IDAGetNumBacktrackOps(void *ida_mem, long int *nbacktr);
177 SUNDIALS_EXPORT int IDAGetConsistentIC(void *ida_mem, N_Vector yy0_mod,
178                                        N_Vector yp0_mod);
179 SUNDIALS_EXPORT int IDAGetLastOrder(void *ida_mem, int *klast);
180 SUNDIALS_EXPORT int IDAGetCurrentOrder(void *ida_mem, int *kcur);
181 SUNDIALS_EXPORT int IDAGetCurrentCj(void *ida_mem, realtype *cj);
182 SUNDIALS_EXPORT int IDAGetCurrentY(void *ida_mem, N_Vector *ycur);
183 SUNDIALS_EXPORT int IDAGetCurrentYp(void *ida_mem, N_Vector *ypcur);
184 SUNDIALS_EXPORT int IDAGetActualInitStep(void *ida_mem, realtype *hinused);
185 SUNDIALS_EXPORT int IDAGetLastStep(void *ida_mem, realtype *hlast);
186 SUNDIALS_EXPORT int IDAGetCurrentStep(void *ida_mem, realtype *hcur);
187 SUNDIALS_EXPORT int IDAGetCurrentTime(void *ida_mem, realtype *tcur);
188 SUNDIALS_EXPORT int IDAGetTolScaleFactor(void *ida_mem, realtype *tolsfact);
189 SUNDIALS_EXPORT int IDAGetErrWeights(void *ida_mem, N_Vector eweight);
190 SUNDIALS_EXPORT int IDAGetEstLocalErrors(void *ida_mem, N_Vector ele);
191 SUNDIALS_EXPORT int IDAGetNumGEvals(void *ida_mem, long int *ngevals);
192 SUNDIALS_EXPORT int IDAGetRootInfo(void *ida_mem, int *rootsfound);
193 SUNDIALS_EXPORT int IDAGetIntegratorStats(void *ida_mem, long int *nsteps,
194                                           long int *nrevals,
195                                           long int *nlinsetups,
196                                           long int *netfails,
197                                           int *qlast, int *qcur,
198                                           realtype *hinused, realtype *hlast,
199                                           realtype *hcur, realtype *tcur);
200 SUNDIALS_EXPORT int IDAGetNonlinearSystemData(void *ida_mem, realtype *tcur,
201                                               N_Vector *yypred,
202                                               N_Vector *yppred,
203                                               N_Vector *yyn, N_Vector *ypn,
204                                               N_Vector *res, realtype *cj,
205                                               void **user_data);
206 SUNDIALS_EXPORT int IDAGetNumNonlinSolvIters(void *ida_mem, long int *nniters);
207 SUNDIALS_EXPORT int IDAGetNumNonlinSolvConvFails(void *ida_mem,
208                                                  long int *nncfails);
209 SUNDIALS_EXPORT int IDAGetNonlinSolvStats(void *ida_mem, long int *nniters,
210                                           long int *nncfails);
211 SUNDIALS_EXPORT char *IDAGetReturnFlagName(long int flag);
212 
213 /* Free function */
214 SUNDIALS_EXPORT void IDAFree(void **ida_mem);
215 
216 /* IDALS interface function that depends on IDAResFn */
217 SUNDIALS_EXPORT int IDASetJacTimesResFn(void *ida_mem,
218                                         IDAResFn jtimesResFn);
219 
220 
221 #ifdef __cplusplus
222 }
223 #endif
224 
225 #endif
226