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