1 /* ---------------------------------------------------------------- 2 * Programmer(s): Daniel R. Reynolds @ SMU 3 * Radu Serban @ 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 IDAS' linear solver interface. 16 * ----------------------------------------------------------------*/ 17 18 #ifndef _IDASLS_H 19 #define _IDASLS_H 20 21 #include <sundials/sundials_direct.h> 22 #include <sundials/sundials_iterative.h> 23 #include <sundials/sundials_linearsolver.h> 24 #include <sundials/sundials_matrix.h> 25 #include <sundials/sundials_nvector.h> 26 27 #ifdef __cplusplus /* wrapper to enable C++ usage */ 28 extern "C" { 29 #endif 30 31 32 /*================================================================= 33 IDALS Constants 34 =================================================================*/ 35 36 #define IDALS_SUCCESS 0 37 #define IDALS_MEM_NULL -1 38 #define IDALS_LMEM_NULL -2 39 #define IDALS_ILL_INPUT -3 40 #define IDALS_MEM_FAIL -4 41 #define IDALS_PMEM_NULL -5 42 #define IDALS_JACFUNC_UNRECVR -6 43 #define IDALS_JACFUNC_RECVR -7 44 #define IDALS_SUNMAT_FAIL -8 45 #define IDALS_SUNLS_FAIL -9 46 47 /* Return values for the adjoint module */ 48 #define IDALS_NO_ADJ -101 49 #define IDALS_LMEMB_NULL -102 50 51 52 /*================================================================= 53 Forward problems 54 =================================================================*/ 55 56 /*================================================================= 57 IDALS user-supplied function prototypes 58 =================================================================*/ 59 60 typedef int (*IDALsJacFn)(realtype t, realtype c_j, N_Vector y, 61 N_Vector yp, N_Vector r, SUNMatrix Jac, 62 void *user_data, N_Vector tmp1, 63 N_Vector tmp2, N_Vector tmp3); 64 65 typedef int (*IDALsPrecSetupFn)(realtype tt, N_Vector yy, 66 N_Vector yp, N_Vector rr, 67 realtype c_j, void *user_data); 68 69 typedef int (*IDALsPrecSolveFn)(realtype tt, N_Vector yy, 70 N_Vector yp, N_Vector rr, 71 N_Vector rvec, N_Vector zvec, 72 realtype c_j, realtype delta, 73 void *user_data); 74 75 typedef int (*IDALsJacTimesSetupFn)(realtype tt, N_Vector yy, 76 N_Vector yp, N_Vector rr, 77 realtype c_j, void *user_data); 78 79 typedef int (*IDALsJacTimesVecFn)(realtype tt, N_Vector yy, 80 N_Vector yp, N_Vector rr, 81 N_Vector v, N_Vector Jv, 82 realtype c_j, void *user_data, 83 N_Vector tmp1, N_Vector tmp2); 84 85 86 /*================================================================= 87 IDALS Exported functions 88 =================================================================*/ 89 90 SUNDIALS_EXPORT int IDASetLinearSolver(void *ida_mem, 91 SUNLinearSolver LS, 92 SUNMatrix A); 93 94 95 /*----------------------------------------------------------------- 96 Optional inputs to the IDALS linear solver interface 97 -----------------------------------------------------------------*/ 98 99 SUNDIALS_EXPORT int IDASetJacFn(void *ida_mem, IDALsJacFn jac); 100 SUNDIALS_EXPORT int IDASetPreconditioner(void *ida_mem, 101 IDALsPrecSetupFn pset, 102 IDALsPrecSolveFn psolve); 103 SUNDIALS_EXPORT int IDASetJacTimes(void *ida_mem, 104 IDALsJacTimesSetupFn jtsetup, 105 IDALsJacTimesVecFn jtimes); 106 SUNDIALS_EXPORT int IDASetEpsLin(void *ida_mem, realtype eplifac); 107 SUNDIALS_EXPORT int IDASetLSNormFactor(void *ida_mem, 108 realtype nrmfac); 109 SUNDIALS_EXPORT int IDASetLinearSolutionScaling(void *ida_mem, 110 booleantype onoff); 111 SUNDIALS_EXPORT int IDASetIncrementFactor(void *ida_mem, 112 realtype dqincfac); 113 114 /*----------------------------------------------------------------- 115 Optional outputs from the IDALS linear solver interface 116 -----------------------------------------------------------------*/ 117 118 SUNDIALS_EXPORT int IDAGetLinWorkSpace(void *ida_mem, 119 long int *lenrwLS, 120 long int *leniwLS); 121 SUNDIALS_EXPORT int IDAGetNumJacEvals(void *ida_mem, 122 long int *njevals); 123 SUNDIALS_EXPORT int IDAGetNumPrecEvals(void *ida_mem, 124 long int *npevals); 125 SUNDIALS_EXPORT int IDAGetNumPrecSolves(void *ida_mem, 126 long int *npsolves); 127 SUNDIALS_EXPORT int IDAGetNumLinIters(void *ida_mem, 128 long int *nliters); 129 SUNDIALS_EXPORT int IDAGetNumLinConvFails(void *ida_mem, 130 long int *nlcfails); 131 SUNDIALS_EXPORT int IDAGetNumJTSetupEvals(void *ida_mem, 132 long int *njtsetups); 133 SUNDIALS_EXPORT int IDAGetNumJtimesEvals(void *ida_mem, 134 long int *njvevals); 135 SUNDIALS_EXPORT int IDAGetNumLinResEvals(void *ida_mem, 136 long int *nrevalsLS); 137 SUNDIALS_EXPORT int IDAGetLastLinFlag(void *ida_mem, 138 long int *flag); 139 SUNDIALS_EXPORT char *IDAGetLinReturnFlagName(long int flag); 140 141 142 /*================================================================= 143 Backward problems 144 =================================================================*/ 145 146 /*================================================================= 147 IDALS user-supplied function prototypes 148 =================================================================*/ 149 150 typedef int (*IDALsJacFnB)(realtype tt, realtype c_jB, N_Vector yy, 151 N_Vector yp, N_Vector yyB, N_Vector ypB, 152 N_Vector rrB, SUNMatrix JacB, 153 void *user_dataB, N_Vector tmp1B, 154 N_Vector tmp2B, N_Vector tmp3B); 155 156 typedef int (*IDALsJacFnBS)(realtype tt, realtype c_jB, N_Vector yy, 157 N_Vector yp, N_Vector *yS, N_Vector *ypS, 158 N_Vector yyB, N_Vector ypB, N_Vector rrB, 159 SUNMatrix JacB, void *user_dataB, 160 N_Vector tmp1B, N_Vector tmp2B, 161 N_Vector tmp3B); 162 163 typedef int (*IDALsPrecSetupFnB)(realtype tt, N_Vector yy, 164 N_Vector yp, N_Vector yyB, 165 N_Vector ypB, N_Vector rrB, 166 realtype c_jB, void *user_dataB); 167 168 typedef int (*IDALsPrecSetupFnBS)(realtype tt, N_Vector yy, 169 N_Vector yp, N_Vector *yyS, 170 N_Vector *ypS, N_Vector yyB, 171 N_Vector ypB, N_Vector rrB, 172 realtype c_jB, void *user_dataB); 173 174 typedef int (*IDALsPrecSolveFnB)(realtype tt, N_Vector yy, 175 N_Vector yp, N_Vector yyB, 176 N_Vector ypB, N_Vector rrB, 177 N_Vector rvecB, N_Vector zvecB, 178 realtype c_jB, realtype deltaB, 179 void *user_dataB); 180 181 typedef int (*IDALsPrecSolveFnBS)(realtype tt, N_Vector yy, 182 N_Vector yp, N_Vector *yyS, 183 N_Vector *ypS, N_Vector yyB, 184 N_Vector ypB, N_Vector rrB, 185 N_Vector rvecB, N_Vector zvecB, 186 realtype c_jB, realtype deltaB, 187 void *user_dataB); 188 189 typedef int (*IDALsJacTimesSetupFnB)(realtype t, N_Vector yy, 190 N_Vector yp, N_Vector yyB, 191 N_Vector ypB, N_Vector rrB, 192 realtype c_jB, void *user_dataB); 193 194 typedef int (*IDALsJacTimesSetupFnBS)(realtype t, N_Vector yy, 195 N_Vector yp, N_Vector *yyS, 196 N_Vector *ypS, N_Vector yyB, 197 N_Vector ypB, N_Vector rrB, 198 realtype c_jB, void *user_dataB); 199 200 typedef int (*IDALsJacTimesVecFnB)(realtype t, N_Vector yy, 201 N_Vector yp, N_Vector yyB, 202 N_Vector ypB, N_Vector rrB, 203 N_Vector vB, N_Vector JvB, 204 realtype c_jB, void *user_dataB, 205 N_Vector tmp1B, N_Vector tmp2B); 206 207 typedef int (*IDALsJacTimesVecFnBS)(realtype t, N_Vector yy, 208 N_Vector yp, N_Vector *yyS, 209 N_Vector *ypS, N_Vector yyB, 210 N_Vector ypB, N_Vector rrB, 211 N_Vector vB, N_Vector JvB, 212 realtype c_jB, void *user_dataB, 213 N_Vector tmp1B, N_Vector tmp2B); 214 215 216 /*================================================================= 217 IDALS Exported functions 218 =================================================================*/ 219 220 SUNDIALS_EXPORT int IDASetLinearSolverB(void *ida_mem, 221 int which, 222 SUNLinearSolver LS, 223 SUNMatrix A); 224 225 /*----------------------------------------------------------------- 226 Each IDASet***B or IDASet***BS function below links the 227 main IDAS integrator with the corresponding IDALS 228 optional input function for the backward integration. 229 The 'which' argument is the int returned by IDACreateB. 230 -----------------------------------------------------------------*/ 231 232 SUNDIALS_EXPORT int IDASetJacFnB(void *ida_mem, int which, 233 IDALsJacFnB jacB); 234 SUNDIALS_EXPORT int IDASetJacFnBS(void *ida_mem, int which, 235 IDALsJacFnBS jacBS); 236 237 SUNDIALS_EXPORT int IDASetEpsLinB(void *ida_mem, int which, 238 realtype eplifacB); 239 SUNDIALS_EXPORT int IDASetLSNormFactorB(void *ida_mem, int which, 240 realtype nrmfacB); 241 SUNDIALS_EXPORT int IDASetLinearSolutionScalingB(void *ida_mem, int which, 242 booleantype onoffB); 243 SUNDIALS_EXPORT int IDASetIncrementFactorB(void *ida_mem, int which, 244 realtype dqincfacB); 245 SUNDIALS_EXPORT int IDASetPreconditionerB(void *ida_mem, int which, 246 IDALsPrecSetupFnB psetB, 247 IDALsPrecSolveFnB psolveB); 248 SUNDIALS_EXPORT int IDASetPreconditionerBS(void *ida_mem, int which, 249 IDALsPrecSetupFnBS psetBS, 250 IDALsPrecSolveFnBS psolveBS); 251 SUNDIALS_EXPORT int IDASetJacTimesB(void *ida_mem, int which, 252 IDALsJacTimesSetupFnB jtsetupB, 253 IDALsJacTimesVecFnB jtimesB); 254 SUNDIALS_EXPORT int IDASetJacTimesBS(void *ida_mem, int which, 255 IDALsJacTimesSetupFnBS jtsetupBS, 256 IDALsJacTimesVecFnBS jtimesBS); 257 258 259 #ifdef __cplusplus 260 } 261 #endif 262 263 #endif 264