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