00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.2 $ 00004 * $Date: 2006/11/29 00:05:07 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer(s): Allan Taylor, Alan Hindmarsh, Radu Serban, and 00007 * Aaron Collier @ LLNL 00008 * ----------------------------------------------------------------- 00009 * Copyright (c) 2002, The Regents of the University of California. 00010 * Produced at the Lawrence Livermore National Laboratory. 00011 * All rights reserved. 00012 * For details, see the LICENSE file. 00013 * ----------------------------------------------------------------- 00014 * KINSOL solver module header file 00015 * ----------------------------------------------------------------- 00016 */ 00017 00018 #ifndef _KINSOL_H 00019 #define _KINSOL_H 00020 00021 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00022 extern "C" { 00023 #endif 00024 00025 #include <stdio.h> 00026 00027 #include <sundials/sundials_nvector.h> 00028 00029 /* 00030 * ================================================================= 00031 * K I N S O L C O N S T A N T S 00032 * ================================================================= 00033 */ 00034 00035 /* 00036 * ----------------------------------------------------------------- 00037 * KINSOL return flags 00038 * ----------------------------------------------------------------- 00039 */ 00040 00041 #define KIN_SUCCESS 0 00042 #define KIN_INITIAL_GUESS_OK 1 00043 #define KIN_STEP_LT_STPTOL 2 00044 00045 #define KIN_WARNING 99 00046 00047 #define KIN_MEM_NULL -1 00048 #define KIN_ILL_INPUT -2 00049 #define KIN_NO_MALLOC -3 00050 #define KIN_MEM_FAIL -4 00051 #define KIN_LINESEARCH_NONCONV -5 00052 #define KIN_MAXITER_REACHED -6 00053 #define KIN_MXNEWT_5X_EXCEEDED -7 00054 #define KIN_LINESEARCH_BCFAIL -8 00055 #define KIN_LINSOLV_NO_RECOVERY -9 00056 #define KIN_LINIT_FAIL -10 00057 #define KIN_LSETUP_FAIL -11 00058 #define KIN_LSOLVE_FAIL -12 00059 00060 #define KIN_SYSFUNC_FAIL -13 00061 #define KIN_FIRST_SYSFUNC_ERR -14 00062 #define KIN_REPTD_SYSFUNC_ERR -15 00063 00064 00065 /* 00066 * ----------------------------------------------------------------- 00067 * Enumeration for inputs to KINSetEtaForm (eta choice) 00068 * ----------------------------------------------------------------- 00069 * KIN_ETACONSTANT : use constant value for eta (default value is 00070 * 0.1 but a different value can be specified via 00071 * a call to KINSetEtaConstValue) 00072 * 00073 * KIN_ETACHOICE1 : use choice #1 as given in Eisenstat and Walker's 00074 * paper of SIAM J.Sci.Comput.,17 (1996), pp 16-32, 00075 * wherein eta is defined to be: 00076 * 00077 * eta(k+1) = ABS(||F(u_k+1)||_L2-||F(u_k)+J(u_k)*p_k||_L2) 00078 * --------------------------------------------- 00079 * ||F(u_k)||_L2 00080 * 00081 * 1+sqrt(5) 00082 * eta_safe = eta(k)^ealpha where ealpha = --------- 00083 * 2 00084 * 00085 * KIN_ETACHOICE2 : use choice #2 as given in Eisenstat and Walker's 00086 * paper wherein eta is defined to be: 00087 * 00088 * [ ||F(u_k+1)||_L2 ]^ealpha 00089 * eta(k+1) = egamma * [ --------------- ] 00090 * [ ||F(u_k)||_L2 ] 00091 * 00092 * where egamma = [0,1] and ealpha = (1,2] 00093 * 00094 * eta_safe = egamma*(eta(k)^ealpha) 00095 * 00096 * Note: The default values of the scalar 00097 * coefficients egamma and ealpha (both required) 00098 * are egamma = 0.9 and ealpha = 2.0, but the 00099 * routine KINSetEtaParams can be used to specify 00100 * different values. 00101 * 00102 * When using either KIN_ETACHOICE1 or KIN_ETACHOICE2, if 00103 * eta_safe > 0.1 then the following safeguard is applied: 00104 * 00105 * eta(k+1) = MAX {eta(k+1), eta_safe} 00106 * 00107 * The following safeguards are always applied when using either 00108 * KIN_ETACHOICE1 or KIN_ETACHOICE2 so that eta_min <= eta <= eta_max: 00109 * 00110 * eta(k+1) = MAX {eta(k+1), eta_min} 00111 * eta(k+1) = MIN {eta(k+1), eta_max} 00112 * 00113 * where eta_min = 1.0e-4 and eta_max = 0.9 (see KINForcingTerm). 00114 * ----------------------------------------------------------------- 00115 */ 00116 00117 #define KIN_ETACHOICE1 1 00118 #define KIN_ETACHOICE2 2 00119 #define KIN_ETACONSTANT 3 00120 00121 /* 00122 * ----------------------------------------------------------------- 00123 * Enumeration for global strategy 00124 * ----------------------------------------------------------------- 00125 * Choices are KIN_NONE and KIN_LINESEARCH. 00126 * ----------------------------------------------------------------- 00127 */ 00128 00129 #define KIN_NONE 0 00130 #define KIN_LINESEARCH 1 00131 00132 /* 00133 * ================================================================= 00134 * F U N C T I O N T Y P E S 00135 * ================================================================= 00136 */ 00137 00138 /* 00139 * ----------------------------------------------------------------- 00140 * Type : KINSysFn 00141 * ----------------------------------------------------------------- 00142 * The user-supplied subroutine implementing the nonlinear system 00143 * function (vector-valued function) F must take as input the 00144 * dependent variable vector uu (type N_Vector), and set fval (type 00145 * N_Vector) equal to F(uu) before returning. Additional workspace 00146 * is allocated by the user and referenced by the f_data memory 00147 * pointer. 00148 * 00149 * Note: The user-defined routine (internally referenced by a 00150 * a pointer (type KINSysFn) named func) should have an 'int' return 00151 * value type. However, the return value is currently ignored. 00152 * ----------------------------------------------------------------- 00153 */ 00154 00155 typedef int (*KINSysFn)(N_Vector uu, N_Vector fval, void *f_data ); 00156 00157 00158 /* 00159 * ----------------------------------------------------------------- 00160 * Type : KINErrHandlerFn 00161 * ----------------------------------------------------------------- 00162 * A function eh, which handles error messages, must have type 00163 * KINErrHandlerFn. 00164 * The function eh takes as input the error code, the name of the 00165 * module reporting the error, the error message, and a pointer to 00166 * user data, the same as that passed to KINSetErrHandlerFn. 00167 * 00168 * All error codes are negative, except KIN_WARNING which indicates 00169 * a warning (the solver continues). 00170 * 00171 * A KINErrHandlerFn has no return value. 00172 * ----------------------------------------------------------------- 00173 */ 00174 00175 typedef void (*KINErrHandlerFn)(int error_code, 00176 const char *module, const char *function, 00177 char *msg, void *eh_data); 00178 00179 00180 /* 00181 * ----------------------------------------------------------------- 00182 * Type : KINInfoHandlerFn 00183 * ----------------------------------------------------------------- 00184 * A function ih, which handles info messages, must have type 00185 * KINInfoHandlerFn. 00186 * The function ih takes as input the name of the module and of the 00187 * function reporting the info message and a pointer to 00188 * user data, the same as that passed to KINSetInfoHandlerFn. 00189 * 00190 * A KINInfoHandlerFn has no return value. 00191 * ----------------------------------------------------------------- 00192 */ 00193 00194 typedef void (*KINInfoHandlerFn)(const char *module, const char *function, 00195 char *msg, void *ih_data); 00196 00197 /* 00198 * ================================================================ 00199 * U S E R - C A L L A B L E R O U T I N E S 00200 * ================================================================ 00201 */ 00202 00203 /* 00204 * ----------------------------------------------------------------- 00205 * Function : KINCreate 00206 * ----------------------------------------------------------------- 00207 * KINCreate allocates and initializes an internal memory block for 00208 * the KINSOL solver module. 00209 * 00210 * If successful, KINCreate returns a pointer to the initialized 00211 * memory block which should be passed to KINMalloc. If an 00212 * error occurs, then KINCreate returns a NULL pointer. 00213 * ----------------------------------------------------------------- 00214 */ 00215 00216 SUNDIALS_EXPORT void *KINCreate(void); 00217 00218 /* 00219 * ----------------------------------------------------------------- 00220 * Optional Input Specification Functions (KINSOL) 00221 * ----------------------------------------------------------------- 00222 * The following functions can be called to set optional inputs: 00223 * 00224 * Function Name | Optional Input [Default Value] 00225 * | 00226 * ----------------------------------------------------------------- 00227 * | 00228 * KINSetErrHandlerFn | user-provided ErrHandler function. 00229 * | [internal] 00230 * | 00231 * KINSetErrFile | pointer (type FILE) indicating where all 00232 * | warning/error messages should be sent 00233 * | if the default internal error handler 00234 * | is used 00235 * | [stderr] 00236 * | 00237 * KINSetPrintLevel | level of verbosity of output: 00238 * | 00239 * | 0 no statistical information is 00240 * | displayed (default level) 00241 * | 00242 * | 1 for each nonlinear iteration display 00243 * | the following information: the scaled 00244 * | norm (L2) of the system function 00245 * | evaluated at the current iterate, the 00246 * | scaled norm of the Newton step (only if 00247 * | using KIN_NONE), and the 00248 * | number of function evaluations performed 00249 * | thus far 00250 * | 00251 * | 2 display level 1 output and the 00252 * | following values for each iteration: 00253 * | 00254 * | fnorm (L2) = ||fscale*func(u)||_L2 00255 * | (only for KIN_NONE) 00256 * | 00257 * | scaled fnorm (for stopping) = 00258 * | ||fscale*ABS(func(u))||_L-infinity 00259 * | (for KIN_NONE and 00260 * | KIN_LINESEARCH) 00261 * | 00262 * | 3 display level 2 output plus additional 00263 * | values used by the global strategy 00264 * | (only if using KIN_LINESEARCH), and 00265 * | statistical information for the linear 00266 * | solver 00267 * | [0] 00268 * | 00269 * KINSetInfoHandlerFn | user-provided InfoHandler function. 00270 * | [internal] 00271 * | 00272 * KINSetInfoFile | pointer (type FILE) specifying where 00273 * | informative (non-error) messages should 00274 * | be sent if the default internal info 00275 * | handler is used 00276 * | [stdout] 00277 * | 00278 * KINSetFdata | pointer to user-allocated memory that is 00279 * | passed to the user-supplied subroutine 00280 * | implementing the nonlinear system function 00281 * | F(u) 00282 * | [NULL] 00283 * | 00284 * KINSetNumMaxIters | maximum number of nonlinear iterations 00285 * | [MXITER_DEFAULT] (defined in kinsol_impl.h) 00286 * | 00287 * KINSetNoInitSetup | flag controlling whether or not the 00288 * | KINSol routine makes an initial call 00289 * | to the linear solver setup routine (lsetup) 00290 * | (possible values are TRUE and FALSE) 00291 * | [FALSE] 00292 * | 00293 * KINSetNoResMon | flag controlling whether or not the nonlinear 00294 * | residual monitoring scheme is used to control 00295 * | Jacobian updating (possible values are TRUE 00296 * | and FALSE) 00297 * | [FALSE if using direct linear solver] 00298 * | [TRUE if using inexact linear solver] 00299 * | 00300 * KINSetMaxSetupCalls | mbset, number of nonlinear iteraions, such 00301 * | that a call to the linear solver setup routine 00302 * | (lsetup) is forced every mbset iterations. 00303 * | If mbset=1, lsetup s called at every iteration. 00304 * | [MSBSET_DEFAULT] (defined in kinsol_impl.h) 00305 * | 00306 * KINSetMaxSubSetupCalls | mbsetsub is the number of nonlinear iterations 00307 * | between checks by the nonlinear residual 00308 * | monitoring algorithm (specifies length of 00309 * | subinterval) 00310 * | NOTE: mbset should be a multiple of mbsetsub 00311 * | [MSBSET_SUB_DEFAULT] (defined in kinsol_impl.h) 00312 * | 00313 * KINSetEtaForm | flag indicating which method to use to 00314 * | compute the value of the eta coefficient 00315 * | used in the calculation of the linear 00316 * | solver convergence tolerance: 00317 * | 00318 * | eps = (eta+uround)*||fscale*func(u)||_L2 00319 * | 00320 * | the linear solver tests for convergence by 00321 * | checking if the following inequality has 00322 * | been satisfied: 00323 * | 00324 * | ||fscale*(func(u)+J(u)*p)||_L2 <= eps 00325 * | 00326 * | where J(u) is the system Jacobian 00327 * | evaluated at the current iterate, and p 00328 * | denotes the Newton step 00329 * | 00330 * | choices for computing eta are as follows: 00331 * | 00332 * | KIN_ETACHOICE1 (refer to KINForcingTerm) 00333 * | 00334 * | eta = ABS(||F(u_k+1)||_L2-||F(u_k)+J(u_k)*p_k||_L2) 00335 * | --------------------------------------------- 00336 * | ||F(u_k)||_L2 00337 * | 00338 * | KIN_ETACHOICE2 (refer to KINForcingTerm) 00339 * | 00340 * | [ ||F(u_k+1)||_L2 ]^alpha 00341 * | eta = gamma * [ --------------- ] 00342 * | [ ||F(u_k)||_L2 ] 00343 * | 00344 * | where gamma = [0,1] and alpha = (1,2] 00345 * | 00346 * | KIN_ETACONSTANT use a constant value for eta 00347 * | [KIN_ETACHOICE1] 00348 * | 00349 * KINSetEtaConstValue | constant value of eta - use with 00350 * | KIN_ETACONSTANT option 00351 * | [0.1] 00352 * | 00353 * KINSetEtaParams | values of eta_gamma (egamma) and eta_alpha 00354 * | (ealpha) coefficients - use with KIN_ETACHOICE2 00355 * | option 00356 * | [0.9 and 2.0] 00357 * | 00358 * KINSetResMonParams | values of omega_min and omega_max scalars 00359 * | used by nonlinear residual monitoring 00360 * | algorithm (see KINStop) 00361 * | [0.00001 and 0.9] 00362 * | 00363 * KINSetResMonConstValue | constant value used by residual monitoring 00364 * | algorithm. If omega=0, then it is estimated 00365 * | using omega_min and omega_max. 00366 * | [0.0] 00367 * | 00368 * KINSetNoMinEps | flag controlling whether or not the value 00369 * | of eps is bounded below by 0.01*fnormtol 00370 * | (see KINSetFuncNormTol) 00371 * | 00372 * | FALSE constrain value of eps by setting 00373 * | to the following: 00374 * | 00375 * | eps = MAX{0.01*fnormtol, eps} 00376 * | 00377 * | TRUE do not constrain value of eps 00378 * | [FALSE] 00379 * | 00380 * KINSetMaxNewtonStep | maximum scaled length of Newton step 00381 * | (reset to value of one if user-supplied 00382 * | value is less than one) 00383 * | [1000*||uscale*u_0||_L2] 00384 * | 00385 * KINSetMaxBetaFails | maximum number of beta condition failures 00386 * | in the line search algorithm. 00387 * | [MXNBCF_DEFAULT] (defined in kinsol_impl.h) 00388 * | 00389 * KINSetRelErrFunc | real scalar equal to realative error in 00390 * | computing F(u) (used in difference- 00391 * | quotient approximation of matrix-vector 00392 * | product J(u)*v) 00393 * | [(uround)^1/2] 00394 * | 00395 * KINSetFuncNormTol | real scalar used as stopping tolerance on 00396 * | ||fscale*ABS(func(u))||_L-infinity (see 00397 * | KINStop and KINInitialStop) 00398 * | [(uround)^1/3] 00399 * | 00400 * KINSetScaledStepTol | real scalar used as stopping tolerance on 00401 * | the maximum scaled step length: 00402 * | 00403 * | || u_k+1 - u_k || 00404 * | || ----------------- ||_L-infinity 00405 * | || ABS(u_k+1)+uscale || 00406 * | 00407 * | (see KINStop) 00408 * | [(uround)^2/3] 00409 * | 00410 * KINSetConstraints | pointer to an array (type N_Vector) of 00411 * | constraints on the solution vector u 00412 * | 00413 * | if constraints[i] = 00414 * | 00415 * | 0 u[i] not constrained 00416 * | 00417 * | +1 u[i] constrained to be >= 0 00418 * | -1 u[i] constrained to be <= 0 00419 * | 00420 * | +2 u[i] constrained to be > 0 00421 * | -2 u[i] constrained to be < 0 00422 * | 00423 * | if a NULL pointer is given, then no 00424 * | constraints are applied to vector u 00425 * | [NULL] 00426 * | 00427 * KINSetSysFunc | set the user-provided routine which 00428 * | defines the nonlinear problem to be 00429 * | solved 00430 * | [none] 00431 * ----------------------------------------------------------------- 00432 * The possible return values for the KINSet* subroutines are the 00433 * following: 00434 * 00435 * KIN_SUCCESS : means the associated variable was successfully 00436 * set [0] 00437 * 00438 * KIN_MEM_NULL : means a NULL KINSOL memory block pointer was given 00439 * (must call the KINCreate and KINMalloc memory 00440 * allocation subroutines prior to calling KINSol) [-1] 00441 * 00442 * KIN_ILL_INPUT : means the supplied parameter was invalid (check 00443 * error message) [-2] 00444 * ----------------------------------------------------------------- 00445 * Note: If successful, these functions return KIN_SUCCESS. If an 00446 * argument has an illegal value, then an error message is printed 00447 * to the file specified by errfp and an error code is returned. 00448 * ----------------------------------------------------------------- 00449 */ 00450 00451 SUNDIALS_EXPORT int KINSetErrHandlerFn(void *kinmem, KINErrHandlerFn ehfun, void *eh_data); 00452 SUNDIALS_EXPORT int KINSetErrFile(void *kinmem, FILE *errfp); 00453 SUNDIALS_EXPORT int KINSetInfoHandlerFn(void *kinmem, KINInfoHandlerFn ihfun, void *ih_data); 00454 SUNDIALS_EXPORT int KINSetInfoFile(void *kinmem, FILE *infofp); 00455 SUNDIALS_EXPORT int KINSetFdata(void *kinmem, void *f_data); 00456 SUNDIALS_EXPORT int KINSetPrintLevel(void *kinmemm, int printfl); 00457 SUNDIALS_EXPORT int KINSetNumMaxIters(void *kinmem, long int mxiter); 00458 SUNDIALS_EXPORT int KINSetNoInitSetup(void *kinmem, booleantype noInitSetup); 00459 SUNDIALS_EXPORT int KINSetNoResMon(void *kinmem, booleantype noNNIResMon); 00460 SUNDIALS_EXPORT int KINSetMaxSetupCalls(void *kinmem, long int msbset); 00461 SUNDIALS_EXPORT int KINSetMaxSubSetupCalls(void *kinmem, long int msbsetsub); 00462 SUNDIALS_EXPORT int KINSetEtaForm(void *kinmem, int etachoice); 00463 SUNDIALS_EXPORT int KINSetEtaConstValue(void *kinmem, realtype eta); 00464 SUNDIALS_EXPORT int KINSetEtaParams(void *kinmem, realtype egamma, realtype ealpha); 00465 SUNDIALS_EXPORT int KINSetResMonParams(void *kinmem, realtype omegamin, realtype omegamax); 00466 SUNDIALS_EXPORT int KINSetResMonConstValue(void *kinmem, realtype omegaconst); 00467 SUNDIALS_EXPORT int KINSetNoMinEps(void *kinmem, booleantype noMinEps); 00468 SUNDIALS_EXPORT int KINSetMaxNewtonStep(void *kinmem, realtype mxnewtstep); 00469 SUNDIALS_EXPORT int KINSetMaxBetaFails(void *kinmem, long int mxnbcf); 00470 SUNDIALS_EXPORT int KINSetRelErrFunc(void *kinmem, realtype relfunc); 00471 SUNDIALS_EXPORT int KINSetFuncNormTol(void *kinmem, realtype fnormtol); 00472 SUNDIALS_EXPORT int KINSetScaledStepTol(void *kinmem, realtype scsteptol); 00473 SUNDIALS_EXPORT int KINSetConstraints(void *kinmem, N_Vector constraints); 00474 SUNDIALS_EXPORT int KINSetSysFunc(void *kinmem, KINSysFn func); 00475 00476 /* 00477 * ----------------------------------------------------------------- 00478 * Function : KINMalloc 00479 * ----------------------------------------------------------------- 00480 * KINMalloc allocates additional memory for vector storage and 00481 * sets a couple problem-specific KINSOL variables. 00482 * 00483 * Note: Additional vectors must be initialized by the user and 00484 * passed to the KINSol routine. 00485 * 00486 * kinmem pointer to an internal memory block allocated during a 00487 * prior call to KINCreate 00488 * 00489 * func name of user-supplied subroutine implementing the 00490 * nonlinear function F(u) 00491 * 00492 * tmpl implementation-specific template vector (type N_Vector) 00493 * (created using either N_VNew_Serial or N_VNew_Parallel) 00494 * 00495 * KINMalloc return flags: KIN_SUCCESS, KIN_MEM_NULL, KIN_ILL_INPUT, 00496 * and KIN_MEM_FAIL (see below). If an error occurs, then KINMalloc 00497 * prints an error message. 00498 * 00499 * ----------------------------------------------------------------- 00500 * The possible return values for the KINMalloc subroutine are the 00501 * following: 00502 * 00503 * KIN_SUCCESS : means the necessary system memory was successfully 00504 * allocated [0] 00505 * 00506 * KIN_MEM_NULL : means a NULL KINSOL memory block pointer was given 00507 * (must call the KINCreate routine before calling 00508 * KINMalloc) [-1] 00509 * 00510 * KIN_ILL_INPUT : means the name of a user-supplied subroutine 00511 * implementing the nonlinear system function F(u) 00512 * was not given [-2] 00513 * 00514 * KIN_MEM_FAIL : means an error occurred during memory allocation 00515 * (either insufficient system resources are available 00516 * or the vector kernel has not yet been initialized) 00517 * [-4] 00518 * ----------------------------------------------------------------- 00519 */ 00520 00521 SUNDIALS_EXPORT int KINMalloc(void *kinmem, KINSysFn func, N_Vector tmpl); 00522 00523 /* 00524 * ----------------------------------------------------------------- 00525 * Function : KINSol 00526 * ----------------------------------------------------------------- 00527 * KINSol (main KINSOL driver routine) manages the computational 00528 * process of computing an approximate solution of the nonlinear 00529 * system. If the initial guess (initial value assigned to vector u) 00530 * doesn't violate any user-defined constraints, then the subroutine 00531 * attempts to solve the system F(u) = 0 using a nonlinear Krylov 00532 * subspace projection method. The Newton-Krylov iterations are 00533 * stopped if either of the following conditions is satisfied: 00534 * 00535 * ||F(u)||_L-infinity <= 0.01*fnormtol 00536 * 00537 * ||u[i+1] - u[i]||_L-infinity <= scsteptol 00538 * 00539 * However, if the current iterate satisfies the second stopping 00540 * criterion, it doesn't necessarily mean an approximate solution 00541 * has been found since the algorithm may have stalled, or the 00542 * user-specified step tolerance (scsteptol) may be too large. 00543 * 00544 * kinmem pointer to an internal memory block allocated during a 00545 * prior call to KINCreate 00546 * 00547 * uu vector set to initial guess by user before calling KINSol, 00548 * but which upon return contains an approximate solution of 00549 * the nonlinear system F(u) = 0 00550 * 00551 * strategy global strategy applied to Newton step if unsatisfactory 00552 * (KIN_NONE or KIN_LINESEARCH) 00553 * 00554 * u_scale vector containing diagonal elements of scaling matrix 00555 * for vector u chosen so that the components of 00556 * u_scale*u (as a matrix multiplication) all have 00557 * about the same magnitude when u is close to a root 00558 * of F(u) 00559 * 00560 * f_scale vector containing diagonal elements of scaling matrix 00561 * for F(u) chosen so that the components of 00562 * f_scale*F(u) (as a matrix multiplication) all have 00563 * roughly the same magnitude when u is not too near a 00564 * root of F(u) 00565 * 00566 * Note: The components of vectors u_scale and f_scale should be 00567 * positive. 00568 * 00569 * If successful, KINSol returns a vector uu contains an approximate 00570 * solution of the given nonlinear system. If an error occurs, then 00571 * an error message is printed and an error code is returned. 00572 * 00573 * ----------------------------------------------------------------- 00574 * KINSol Return Values 00575 * ----------------------------------------------------------------- 00576 * 00577 * The possible return values for the KINSol subroutine are the 00578 * following: 00579 * 00580 * KIN_SUCCESS : means ||fscale*ABS(func(u))||_L-infinity <= 0.01*fnormtol 00581 * and the current iterate uu is probably an approximate 00582 * solution of the nonlinear system F(u) = 0 [0] 00583 * 00584 * KIN_INITIAL_GUESS_OK : means the initial user-supplied guess 00585 * already satisfies the stopping criterion 00586 * given above [1] 00587 * 00588 * KIN_STEP_LT_STPTOL : means the following inequality has been 00589 * satisfied (stopping tolerance on scaled 00590 * step length): 00591 * 00592 * || u_k+1 - u_k || 00593 * || ----------------- ||_L-infinity <= scsteptol 00594 * || ABS(u_k+1)+uscale || 00595 * 00596 * so the current iterate (denoted above by u_k+1) 00597 * may be an approximate solution of the given 00598 * nonlinear system, but it is also quite possible 00599 * that the algorithm is "stalled" (making 00600 * insufficient progress) near an invalid solution, 00601 * or the real scalar scsteptol is too large [2] 00602 * 00603 * KIN_LINESEARCH_NONCONV : means the line search algorithm was unable 00604 * to find an iterate sufficiently distinct 00605 * from the current iterate 00606 * 00607 * failure to satisfy the sufficient decrease 00608 * condition could mean the current iterate is 00609 * "close" to an approximate solution of the given 00610 * nonlinear system, the finite-difference 00611 * approximation of the matrix-vector product 00612 * J(u)*v is inaccurate, or the real scalar 00613 * scsteptol is too large [-5] 00614 * 00615 * KIN_MAXITER_REACHED : means the maximum number of nonlinear iterations 00616 * has been reached [-6] 00617 * 00618 * KIN_MXNEWT_5X_EXCEEDED : means five consecutive steps have been taken 00619 * that satisfy the following inequality: 00620 * 00621 * ||uscale*p||_L2 > 0.99*mxnewtstep 00622 * 00623 * where p denotes the current step and 00624 * mxnewtstep is a real scalar upper bound 00625 * on the scaled step length 00626 * 00627 * such a failure may mean ||fscale*func(u)||_L2 00628 * asymptotes from above to a finite value, or 00629 * the real scalar mxnewtstep is too small [-7] 00630 * 00631 * KIN_LINESEARCH_BCFAIL : means the line search algorithm (implemented 00632 * in KINLineSearch) was unable to satisfy the 00633 * beta-condition for MXNBCF + 1 nonlinear 00634 * iterations (not necessarily consecutive), 00635 * which may indicate the algorithm is making 00636 * poor progress [-8] 00637 * 00638 * KIN_LINSOLV_NO_RECOVERY : means the user-supplied routine psolve 00639 * encountered a recoverable error, but 00640 * the preconditioner is already current [-9] 00641 * 00642 * KIN_LINIT_FAIL : means the linear solver initialization routine (linit) 00643 * encountered an error [-10] 00644 * 00645 * KIN_LSETUP_FAIL : means the user-supplied routine pset (used to compute 00646 * the preconditioner) encountered an unrecoverable 00647 * error [-11] 00648 * 00649 * KIN_LSOLVE_FAIL : means either the user-supplied routine psolve (used to 00650 * to solve the preconditioned linear system) encountered 00651 * an unrecoverable error, or the linear solver routine 00652 * (lsolve) encountered an error condition [-12] 00653 * 00654 * KIN_MEM_NULL : means a NULL KINSOL memory block pointer was given 00655 * (must call the KINCreate and KINMalloc memory 00656 * allocation subroutines prior to calling KINSol) [-1] 00657 * 00658 * KIN_NO_MALLOC : means additional system memory has not yet been 00659 * allocated for vector storage (forgot to call the 00660 * KINMalloc routine) [-3] 00661 * 00662 * KIN_ILL_INPUT : means at least one input parameter was invalid 00663 * (check error output) [-2] 00664 * ----------------------------------------------------------------- 00665 */ 00666 00667 SUNDIALS_EXPORT int KINSol(void *kinmem, N_Vector uu, int strategy, 00668 N_Vector u_scale, N_Vector f_scale); 00669 00670 /* 00671 * ----------------------------------------------------------------- 00672 * Optional Output Extraction Functions (KINSOL) 00673 * ----------------------------------------------------------------- 00674 * The following functions can be called to get optional outputs 00675 * and statistical information related to the KINSOL solver: 00676 * 00677 * Function Name | Returned Value 00678 * | 00679 * ----------------------------------------------------------------- 00680 * | 00681 * KINGetWorkSpace | returns both integer workspace size 00682 * | (total number of long int-sized blocks 00683 * | of memory allocated by KINSOL for 00684 * | vector storage) and real workspace 00685 * | size (total number of realtype-sized 00686 * | blocks of memory allocated by KINSOL 00687 * | for vector storage) 00688 * | 00689 * KINGetNumFuncEvals | total number evaluations of the 00690 * | nonlinear system function F(u) 00691 * | (number of direct calls made to the 00692 * | user-supplied subroutine by KINSOL 00693 * | module member functions) 00694 * | 00695 * KINGetNumNonlinSolvIters | total number of nonlinear iterations 00696 * | performed 00697 * | 00698 * KINGetNumBetaCondFails | total number of beta-condition 00699 * | failures (see KINLineSearch) 00700 * | 00701 * | KINSOL halts if the number of such 00702 * | failures exceeds the value of the 00703 * | constant MXNBCF (defined in kinsol.c) 00704 * | 00705 * KINGetNumBacktrackOps | total number of backtrack operations 00706 * | (step length adjustments) performed 00707 * | by the line search algorithm (see 00708 * | KINLineSearch) 00709 * | 00710 * KINGetFuncNorm | scaled norm of the nonlinear system 00711 * | function F(u) evaluated at the 00712 * | current iterate: 00713 * | 00714 * | ||fscale*func(u)||_L2 00715 * | 00716 * KINGetStepLength | scaled norm (or length) of the step 00717 * | used during the previous iteration: 00718 * | 00719 * | ||uscale*p||_L2 00720 * | 00721 * KINGetReturnFlagName | returns the name of the constant 00722 * | associated with a KINSOL return flag 00723 * | 00724 * ----------------------------------------------------------------- 00725 * 00726 * The possible return values for the KINSet* subroutines are the 00727 * following: 00728 * 00729 * KIN_SUCCESS : means the information was successfully retrieved [0] 00730 * 00731 * KIN_MEM_NULL : means a NULL KINSOL memory block pointer was given 00732 * (must call the KINCreate and KINMalloc memory 00733 * allocation subroutines prior to calling KINSol) [-1] 00734 * ----------------------------------------------------------------- 00735 */ 00736 00737 SUNDIALS_EXPORT int KINGetWorkSpace(void *kinmem, long int *lenrw, long int *leniw); 00738 SUNDIALS_EXPORT int KINGetNumNonlinSolvIters(void *kinmem, long int *nniters); 00739 SUNDIALS_EXPORT int KINGetNumFuncEvals(void *kinmem, long int *nfevals); 00740 SUNDIALS_EXPORT int KINGetNumBetaCondFails(void *kinmem, long int *nbcfails); 00741 SUNDIALS_EXPORT int KINGetNumBacktrackOps(void *kinmem, long int *nbacktr); 00742 SUNDIALS_EXPORT int KINGetFuncNorm(void *kinmem, realtype *fnorm); 00743 SUNDIALS_EXPORT int KINGetStepLength(void *kinmem, realtype *steplength); 00744 SUNDIALS_EXPORT char *KINGetReturnFlagName(int flag); 00745 00746 /* 00747 * ----------------------------------------------------------------- 00748 * Function : KINFree 00749 * ----------------------------------------------------------------- 00750 * KINFree frees system memory resources reserved for the KINSOL 00751 * solver module. 00752 * 00753 * kinmem pointer to an internal memory block allocated during 00754 * prior calls to KINCreate and KINMalloc 00755 * ----------------------------------------------------------------- 00756 */ 00757 00758 SUNDIALS_EXPORT void KINFree(void **kinmem); 00759 00760 00761 #ifdef __cplusplus 00762 } 00763 #endif 00764 00765 #endif
1.5.6