1 /* ----------------------------------------------------------------- 2 * Programmer(s): Allan Taylor, Alan Hindmarsh, Radu Serban, and 3 * 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 KINSOL solver. 16 * -----------------------------------------------------------------*/ 17 18 #ifndef _KINSOL_H 19 #define _KINSOL_H 20 21 #include <stdio.h> 22 #include <sundials/sundials_nvector.h> 23 #include <kinsol/kinsol_ls.h> 24 25 #ifdef __cplusplus /* wrapper to enable C++ usage */ 26 extern "C" { 27 #endif 28 29 /* ----------------- 30 * KINSOL Constants 31 * ----------------- */ 32 33 /* return values */ 34 35 #define KIN_SUCCESS 0 36 #define KIN_INITIAL_GUESS_OK 1 37 #define KIN_STEP_LT_STPTOL 2 38 39 #define KIN_WARNING 99 40 41 #define KIN_MEM_NULL -1 42 #define KIN_ILL_INPUT -2 43 #define KIN_NO_MALLOC -3 44 #define KIN_MEM_FAIL -4 45 #define KIN_LINESEARCH_NONCONV -5 46 #define KIN_MAXITER_REACHED -6 47 #define KIN_MXNEWT_5X_EXCEEDED -7 48 #define KIN_LINESEARCH_BCFAIL -8 49 #define KIN_LINSOLV_NO_RECOVERY -9 50 #define KIN_LINIT_FAIL -10 51 #define KIN_LSETUP_FAIL -11 52 #define KIN_LSOLVE_FAIL -12 53 54 #define KIN_SYSFUNC_FAIL -13 55 #define KIN_FIRST_SYSFUNC_ERR -14 56 #define KIN_REPTD_SYSFUNC_ERR -15 57 58 #define KIN_VECTOROP_ERR -16 59 60 /* Enumeration for eta choice */ 61 #define KIN_ETACHOICE1 1 62 #define KIN_ETACHOICE2 2 63 #define KIN_ETACONSTANT 3 64 65 /* Enumeration for global strategy */ 66 #define KIN_NONE 0 67 #define KIN_LINESEARCH 1 68 #define KIN_PICARD 2 69 #define KIN_FP 3 70 71 /* ------------------------------ 72 * User-Supplied Function Types 73 * ------------------------------ */ 74 75 typedef int (*KINSysFn)(N_Vector uu, N_Vector fval, void *user_data); 76 77 typedef void (*KINErrHandlerFn)(int error_code, 78 const char *module, const char *function, 79 char *msg, void *user_data); 80 81 typedef void (*KINInfoHandlerFn)(const char *module, const char *function, 82 char *msg, void *user_data); 83 84 /* ------------------- 85 * Exported Functions 86 * ------------------- */ 87 88 /* Creation function */ 89 SUNDIALS_EXPORT void *KINCreate(void); 90 91 /* Initialization function */ 92 SUNDIALS_EXPORT int KINInit(void *kinmem, KINSysFn func, N_Vector tmpl); 93 94 /* Solver function */ 95 SUNDIALS_EXPORT int KINSol(void *kinmem, N_Vector uu, int strategy, 96 N_Vector u_scale, N_Vector f_scale); 97 98 /* Optional input functions */ 99 SUNDIALS_EXPORT int KINSetErrHandlerFn(void *kinmem, KINErrHandlerFn ehfun, 100 void *eh_data); 101 SUNDIALS_EXPORT int KINSetErrFile(void *kinmem, FILE *errfp); 102 SUNDIALS_EXPORT int KINSetInfoHandlerFn(void *kinmem, KINInfoHandlerFn ihfun, 103 void *ih_data); 104 SUNDIALS_EXPORT int KINSetInfoFile(void *kinmem, FILE *infofp); 105 SUNDIALS_EXPORT int KINSetUserData(void *kinmem, void *user_data); 106 SUNDIALS_EXPORT int KINSetPrintLevel(void *kinmemm, int printfl); 107 SUNDIALS_EXPORT int KINSetMAA(void *kinmem, long int maa); 108 SUNDIALS_EXPORT int KINSetDampingAA(void *kinmem, realtype beta); 109 SUNDIALS_EXPORT int KINSetNumMaxIters(void *kinmem, long int mxiter); 110 SUNDIALS_EXPORT int KINSetNoInitSetup(void *kinmem, booleantype noInitSetup); 111 SUNDIALS_EXPORT int KINSetNoResMon(void *kinmem, booleantype noNNIResMon); 112 SUNDIALS_EXPORT int KINSetMaxSetupCalls(void *kinmem, long int msbset); 113 SUNDIALS_EXPORT int KINSetMaxSubSetupCalls(void *kinmem, long int msbsetsub); 114 SUNDIALS_EXPORT int KINSetEtaForm(void *kinmem, int etachoice); 115 SUNDIALS_EXPORT int KINSetEtaConstValue(void *kinmem, realtype eta); 116 SUNDIALS_EXPORT int KINSetEtaParams(void *kinmem, realtype egamma, 117 realtype ealpha); 118 SUNDIALS_EXPORT int KINSetResMonParams(void *kinmem, realtype omegamin, 119 realtype omegamax); 120 SUNDIALS_EXPORT int KINSetResMonConstValue(void *kinmem, realtype omegaconst); 121 SUNDIALS_EXPORT int KINSetNoMinEps(void *kinmem, booleantype noMinEps); 122 SUNDIALS_EXPORT int KINSetMaxNewtonStep(void *kinmem, realtype mxnewtstep); 123 SUNDIALS_EXPORT int KINSetMaxBetaFails(void *kinmem, long int mxnbcf); 124 SUNDIALS_EXPORT int KINSetRelErrFunc(void *kinmem, realtype relfunc); 125 SUNDIALS_EXPORT int KINSetFuncNormTol(void *kinmem, realtype fnormtol); 126 SUNDIALS_EXPORT int KINSetScaledStepTol(void *kinmem, realtype scsteptol); 127 SUNDIALS_EXPORT int KINSetConstraints(void *kinmem, N_Vector constraints); 128 SUNDIALS_EXPORT int KINSetSysFunc(void *kinmem, KINSysFn func); 129 130 131 /* Optional output functions */ 132 SUNDIALS_EXPORT int KINGetWorkSpace(void *kinmem, long int *lenrw, 133 long int *leniw); 134 SUNDIALS_EXPORT int KINGetNumNonlinSolvIters(void *kinmem, long int *nniters); 135 SUNDIALS_EXPORT int KINGetNumFuncEvals(void *kinmem, long int *nfevals); 136 SUNDIALS_EXPORT int KINGetNumBetaCondFails(void *kinmem, long int *nbcfails); 137 SUNDIALS_EXPORT int KINGetNumBacktrackOps(void *kinmem, long int *nbacktr); 138 SUNDIALS_EXPORT int KINGetFuncNorm(void *kinmem, realtype *fnorm); 139 SUNDIALS_EXPORT int KINGetStepLength(void *kinmem, realtype *steplength); 140 SUNDIALS_EXPORT char *KINGetReturnFlagName(long int flag); 141 142 /* Free function */ 143 SUNDIALS_EXPORT void KINFree(void **kinmem); 144 145 /* KINLS interface function that depends on KINSysFn */ 146 SUNDIALS_EXPORT int KINSetJacTimesVecSysFn(void *kinmem, KINSysFn jtimesSysFn); 147 148 #ifdef __cplusplus 149 } 150 #endif 151 152 #endif 153