00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.5 $ 00004 * $Date: 2006/12/01 22:48:55 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer(s): Scott D. Cohen, Alan C. Hindmarsh, Radu Serban 00007 * and Dan Shumaker @ 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 * This is the interface file for the main CVODE integrator. 00015 * ----------------------------------------------------------------- 00016 * 00017 * CVODE is used to solve numerically the ordinary initial value 00018 * problem: 00019 * 00020 * y' = f(t,y), 00021 * y(t0) = y0, 00022 * 00023 * where t0, y0 in R^N, and f: R x R^N -> R^N are given. 00024 * 00025 * ----------------------------------------------------------------- 00026 */ 00027 00028 #ifndef _CVODE_H 00029 #define _CVODE_H 00030 00031 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00032 extern "C" { 00033 #endif 00034 00035 #include <stdio.h> 00036 00037 #include <sundials/sundials_nvector.h> 00038 00039 /* 00040 * ================================================================= 00041 * C V O D E C O N S T A N T S 00042 * ================================================================= 00043 */ 00044 00045 /* 00046 * ----------------------------------------------------------------- 00047 * Enumerations for inputs to CVodeCreate, CVodeMalloc, 00048 * CVodeReInit, and CVode. 00049 * ----------------------------------------------------------------- 00050 * Symbolic constants for the lmm, iter, and itol input 00051 * parameters to CVodeMalloc and CVodeReInit, as well as the 00052 * input parameter itask to CVode, are given below. 00053 * 00054 * lmm: The user of the CVODE package specifies whether to use the 00055 * CV_ADAMS (Adams-Moulton) or CV_BDF (Backward Differentiation 00056 * Formula) linear multistep method. The BDF method is 00057 * recommended for stiff problems, and the CV_ADAMS method is 00058 * recommended for nonstiff problems. 00059 * 00060 * iter: At each internal time step, a nonlinear equation must 00061 * be solved. The user can specify either CV_FUNCTIONAL 00062 * iteration, which does not require linear algebra, or a 00063 * CV_NEWTON iteration, which requires the solution of linear 00064 * systems. In the CV_NEWTON case, the user also specifies a 00065 * CVODE linear solver. CV_NEWTON is recommended in case of 00066 * stiff problems. 00067 * 00068 * itol: This parameter specifies the relative and absolute 00069 * tolerance types to be used. The CV_SS tolerance type means 00070 * a scalar relative and absolute tolerance. The CV_SV 00071 * tolerance type means a scalar relative tolerance and a 00072 * vector absolute tolerance (a potentially different 00073 * absolute tolerance for each vector component). The CV_WF 00074 * tolerance type means that the user provides a function 00075 * (of type CVEwtFn) to set the error weight vector. 00076 * 00077 * itask: The itask input parameter to CVode indicates the job 00078 * of the solver for the next user step. The CV_NORMAL 00079 * itask is to have the solver take internal steps until 00080 * it has reached or just passed the user specified tout 00081 * parameter. The solver then interpolates in order to 00082 * return an approximate value of y(tout). The CV_ONE_STEP 00083 * option tells the solver to just take one internal step 00084 * and return the solution at the point reached by that 00085 * step. The CV_NORMAL_TSTOP and CV_ONE_STEP_TSTOP modes are 00086 * similar to CV_NORMAL and CV_ONE_STEP, respectively, except 00087 * that the integration never proceeds past the value 00088 * tstop (specified through the routine CVodeSetStopTime). 00089 * ----------------------------------------------------------------- 00090 */ 00091 00092 /* lmm */ 00093 #define CV_ADAMS 1 00094 #define CV_BDF 2 00095 00096 /* iter */ 00097 #define CV_FUNCTIONAL 1 00098 #define CV_NEWTON 2 00099 00100 /* itol */ 00101 #define CV_SS 1 00102 #define CV_SV 2 00103 #define CV_WF 3 00104 00105 /* itask */ 00106 #define CV_NORMAL 1 00107 #define CV_ONE_STEP 2 00108 #define CV_NORMAL_TSTOP 3 00109 #define CV_ONE_STEP_TSTOP 4 00110 00111 /* 00112 * ---------------------------------------- 00113 * CVODE return flags 00114 * ---------------------------------------- 00115 */ 00116 00117 #define CV_SUCCESS 0 00118 #define CV_TSTOP_RETURN 1 00119 #define CV_ROOT_RETURN 2 00120 00121 #define CV_WARNING 99 00122 00123 #define CV_TOO_MUCH_WORK -1 00124 #define CV_TOO_MUCH_ACC -2 00125 #define CV_ERR_FAILURE -3 00126 #define CV_CONV_FAILURE -4 00127 00128 #define CV_LINIT_FAIL -5 00129 #define CV_LSETUP_FAIL -6 00130 #define CV_LSOLVE_FAIL -7 00131 #define CV_RHSFUNC_FAIL -8 00132 #define CV_FIRST_RHSFUNC_ERR -9 00133 #define CV_REPTD_RHSFUNC_ERR -10 00134 #define CV_UNREC_RHSFUNC_ERR -11 00135 #define CV_RTFUNC_FAIL -12 00136 00137 #define CV_MEM_FAIL -20 00138 #define CV_MEM_NULL -21 00139 #define CV_ILL_INPUT -22 00140 #define CV_NO_MALLOC -23 00141 #define CV_BAD_K -24 00142 #define CV_BAD_T -25 00143 #define CV_BAD_DKY -26 00144 #define CV_TOO_CLOSE -27 00145 00146 /* 00147 * ================================================================= 00148 * F U N C T I O N T Y P E S 00149 * ================================================================= 00150 */ 00151 00152 /* 00153 * ----------------------------------------------------------------- 00154 * Type : CVRhsFn 00155 * ----------------------------------------------------------------- 00156 * The f function which defines the right hand side of the ODE 00157 * system y' = f(t,y) must have type CVRhsFn. 00158 * f takes as input the independent variable value t, and the 00159 * dependent variable vector y. It stores the result of f(t,y) 00160 * in the vector ydot. The y and ydot arguments are of type 00161 * N_Vector. 00162 * (Allocation of memory for ydot is handled within CVODE) 00163 * The f_data parameter is the same as the f_data 00164 * parameter set by the user through the CVodeSetFdata routine. 00165 * This user-supplied pointer is passed to the user's f function 00166 * every time it is called. 00167 * 00168 * A CVRhsFn should return 0 if successful, a negative value if 00169 * an unrecoverable error occured, and a positive value if a 00170 * recoverable error (e.g. invalid y values) occured. 00171 * If an unrecoverable occured, the integration is halted. 00172 * If a recoverable error occured, then (in most cases) CVODE 00173 * will try to correct and retry. 00174 * ----------------------------------------------------------------- 00175 */ 00176 00177 typedef int (*CVRhsFn)(realtype t, N_Vector y, 00178 N_Vector ydot, void *f_data); 00179 00180 /* 00181 * ----------------------------------------------------------------- 00182 * Type : CVRootFn 00183 * ----------------------------------------------------------------- 00184 * A function g, which defines a set of functions g_i(t,y) whose 00185 * roots are sought during the integration, must have type CVRootFn. 00186 * The function g takes as input the independent variable value 00187 * t, and the dependent variable vector y. It stores the nrtfn 00188 * values g_i(t,y) in the realtype array gout. 00189 * (Allocation of memory for gout is handled within CVODE.) 00190 * The g_data parameter is the same as that passed by the user 00191 * to the CVodeRootInit routine. This user-supplied pointer is 00192 * passed to the user's g function every time it is called. 00193 * 00194 * A CVRootFn should return 0 if successful or a non-zero value 00195 * if an error occured (in which case the integration will be halted). 00196 * ----------------------------------------------------------------- 00197 */ 00198 00199 typedef int (*CVRootFn)(realtype t, N_Vector y, realtype *gout, 00200 void *g_data); 00201 00202 /* 00203 * ----------------------------------------------------------------- 00204 * Type : CVEwtFn 00205 * ----------------------------------------------------------------- 00206 * A function e, which sets the error weight vector ewt, must have 00207 * type CVEwtFn. 00208 * The function e takes as input the current dependent variable y. 00209 * It must set the vector of error weights used in the WRMS norm: 00210 * 00211 * ||y||_WRMS = sqrt [ 1/N * sum ( ewt_i * y_i)^2 ] 00212 * 00213 * Typically, the vector ewt has components: 00214 * 00215 * ewt_i = 1 / (reltol * |y_i| + abstol_i) 00216 * 00217 * The e_data parameter is the same as that passed by the user 00218 * to the CVodeSetEwtFn routine. This user-supplied pointer is 00219 * passed to the user's e function every time it is called. 00220 * A CVEwtFn e must return 0 if the error weight vector has been 00221 * successfuly set and a non-zero value otherwise. 00222 * ----------------------------------------------------------------- 00223 */ 00224 00225 typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void *e_data); 00226 00227 /* 00228 * ----------------------------------------------------------------- 00229 * Type : CVErrHandlerFn 00230 * ----------------------------------------------------------------- 00231 * A function eh, which handles error messages, must have type 00232 * CVErrHandlerFn. 00233 * The function eh takes as input the error code, the name of the 00234 * module reporting the error, the error message, and a pointer to 00235 * user data, the same as that passed to CVodeSetErrHandlerFn. 00236 * 00237 * All error codes are negative, except CV_WARNING which indicates 00238 * a warning (the solver continues). 00239 * 00240 * A CVErrHandlerFn has no return value. 00241 * ----------------------------------------------------------------- 00242 */ 00243 00244 typedef void (*CVErrHandlerFn)(int error_code, 00245 const char *module, const char *function, 00246 char *msg, void *eh_data); 00247 00248 /* 00249 * ================================================================= 00250 * U S E R - C A L L A B L E R O U T I N E S 00251 * ================================================================= 00252 */ 00253 00254 /* 00255 * ----------------------------------------------------------------- 00256 * Function : CVodeCreate 00257 * ----------------------------------------------------------------- 00258 * CVodeCreate creates an internal memory block for a problem to 00259 * be solved by CVODE. 00260 * 00261 * lmm is the type of linear multistep method to be used. 00262 * The legal values are CV_ADAMS and CV_BDF (see previous 00263 * description). 00264 * 00265 * iter is the type of iteration used to solve the nonlinear 00266 * system that arises during each internal time step. 00267 * The legal values are CV_FUNCTIONAL and CV_NEWTON. 00268 * 00269 * If successful, CVodeCreate returns a pointer to initialized 00270 * problem memory. This pointer should be passed to CVodeMalloc. 00271 * If an initialization error occurs, CVodeCreate prints an error 00272 * message to standard err and returns NULL. 00273 * ----------------------------------------------------------------- 00274 */ 00275 00276 SUNDIALS_EXPORT void *CVodeCreate(int lmm, int iter); 00277 00278 /* 00279 * ----------------------------------------------------------------- 00280 * Integrator optional input specification functions 00281 * ----------------------------------------------------------------- 00282 * The following functions can be called to set optional inputs 00283 * to values other than the defaults given below: 00284 * 00285 * Function | Optional input / [ default value ] 00286 * ----------------------------------------------------------------- 00287 * | 00288 * CVodeSetErrHandlerFn | user-provided ErrHandler function. 00289 * | [internal] 00290 * | 00291 * CVodeSetErrFile | the file pointer for an error file 00292 * | where all CVODE warning and error 00293 * | messages will be written if the default 00294 * | internal error handling function is used. 00295 * | This parameter can be stdout (standard 00296 * | output), stderr (standard error), or a 00297 * | file pointer (corresponding to a user 00298 * | error file opened for writing) returned 00299 * | by fopen. 00300 * | If not called, then all messages will 00301 * | be written to the standard error stream. 00302 * | [stderr] 00303 * | 00304 * CVodeSetFdata | a pointer to user data that will be 00305 * | passed to the user's f function every 00306 * | time f is called. 00307 * | [NULL] 00308 * | 00309 * CVodeSetEwtFn | user-provide EwtSet function e and 00310 * | a pointer to user data that will be 00311 * | passed to the user's e function every 00312 * | time e is called. 00313 * | [NULL] 00314 * | [NULL] 00315 * | 00316 * CVodeSetMaxOrd | maximum lmm order to be used by the 00317 * | solver. 00318 * | [12 for Adams , 5 for BDF] 00319 * | 00320 * CVodeSetMaxNumSteps | maximum number of internal steps to be 00321 * | taken by the solver in its attempt to 00322 * | reach tout. 00323 * | [500] 00324 * | 00325 * CVodeSetMaxHnilWarns | maximum number of warning messages 00326 * | issued by the solver that t+h==t on the 00327 * | next internal step. A value of -1 means 00328 * | no such messages are issued. 00329 * | [10] 00330 * | 00331 * CVodeSetStabLimDet | flag to turn on/off stability limit 00332 * | detection (TRUE = on, FALSE = off). 00333 * | When BDF is used and order is 3 or 00334 * | greater, CVsldet is called to detect 00335 * | stability limit. If limit is detected, 00336 * | the order is reduced. 00337 * | [FALSE] 00338 * | 00339 * CVodeSetInitStep | initial step size. 00340 * | [estimated by CVODE] 00341 * | 00342 * CVodeSetMinStep | minimum absolute value of step size 00343 * | allowed. 00344 * | [0.0] 00345 * | 00346 * CVodeSetMaxStep | maximum absolute value of step size 00347 * | allowed. 00348 * | [infinity] 00349 * | 00350 * CVodeSetStopTime | the independent variable value past 00351 * | which the solution is not to proceed. 00352 * | [infinity] 00353 * | 00354 * CVodeSetMaxErrTestFails | Maximum number of error test failures 00355 * | in attempting one step. 00356 * | [7] 00357 * | 00358 * CVodeSetMaxNonlinIters | Maximum number of nonlinear solver 00359 * | iterations at one solution. 00360 * | [3] 00361 * | 00362 * CVodeSetMaxConvFails | Maximum number of convergence failures 00363 * | allowed in attempting one step. 00364 * | [10] 00365 * | 00366 * CVodeSetNonlinConvCoef | Coefficient in the nonlinear 00367 * | convergence test. 00368 * | [0.1] 00369 * | 00370 * ----------------------------------------------------------------- 00371 * | 00372 * CVodeSetIterType | Changes the current nonlinear iteration 00373 * | type. 00374 * | [set by CVodecreate] 00375 * | 00376 * CVodeSetTolerances | Changes the integration tolerances 00377 * | between calls to CVode(). 00378 * | [set by CVodeMalloc/CVodeReInit] 00379 * | 00380 * ----------------------------------------------------------------- 00381 * Return flag: 00382 * CV_SUCCESS if successful 00383 * CV_MEM_NULL if the cvode memory is NULL 00384 * CV_ILL_INPUT if an argument has an illegal value 00385 * ----------------------------------------------------------------- 00386 */ 00387 00388 SUNDIALS_EXPORT int CVodeSetErrHandlerFn(void *cvode_mem, CVErrHandlerFn ehfun, void *eh_data); 00389 SUNDIALS_EXPORT int CVodeSetErrFile(void *cvode_mem, FILE *errfp); 00390 SUNDIALS_EXPORT int CVodeSetFdata(void *cvode_mem, void *f_data); 00391 SUNDIALS_EXPORT int CVodeSetEwtFn(void *cvode_mem, CVEwtFn efun, void *e_data); 00392 SUNDIALS_EXPORT int CVodeSetMaxOrd(void *cvode_mem, int maxord); 00393 SUNDIALS_EXPORT int CVodeSetMaxNumSteps(void *cvode_mem, long int mxsteps); 00394 SUNDIALS_EXPORT int CVodeSetMaxHnilWarns(void *cvode_mem, int mxhnil); 00395 SUNDIALS_EXPORT int CVodeSetStabLimDet(void *cvode_mem, booleantype stldet); 00396 SUNDIALS_EXPORT int CVodeSetInitStep(void *cvode_mem, realtype hin); 00397 SUNDIALS_EXPORT int CVodeSetMinStep(void *cvode_mem, realtype hmin); 00398 SUNDIALS_EXPORT int CVodeSetMaxStep(void *cvode_mem, realtype hmax); 00399 SUNDIALS_EXPORT int CVodeSetStopTime(void *cvode_mem, realtype tstop); 00400 SUNDIALS_EXPORT int CVodeSetMaxErrTestFails(void *cvode_mem, int maxnef); 00401 SUNDIALS_EXPORT int CVodeSetMaxNonlinIters(void *cvode_mem, int maxcor); 00402 SUNDIALS_EXPORT int CVodeSetMaxConvFails(void *cvode_mem, int maxncf); 00403 SUNDIALS_EXPORT int CVodeSetNonlinConvCoef(void *cvode_mem, realtype nlscoef); 00404 00405 SUNDIALS_EXPORT int CVodeSetIterType(void *cvode_mem, int iter); 00406 SUNDIALS_EXPORT int CVodeSetTolerances(void *cvode_mem, 00407 int itol, realtype reltol, void *abstol); 00408 00409 /* 00410 * ----------------------------------------------------------------- 00411 * Function : CVodeMalloc 00412 * ----------------------------------------------------------------- 00413 * CVodeMalloc allocates and initializes memory for a problem to 00414 * to be solved by CVODE. 00415 * 00416 * cvode_mem is pointer to CVODE memory returned by CVodeCreate. 00417 * 00418 * f is the name of the C function defining the right-hand 00419 * side function in y' = f(t,y). 00420 * 00421 * t0 is the initial value of t. 00422 * 00423 * y0 is the initial condition vector y(t0). 00424 * 00425 * itol is the type of tolerances to be used. 00426 * The legal values are: 00427 * CV_SS (scalar relative and absolute tolerances), 00428 * CV_SV (scalar relative tolerance and vector 00429 * absolute tolerance). 00430 * CV_WF (indicates that the user will provide a 00431 * function to evaluate the error weights. 00432 * In this case, reltol and abstol are ignored.) 00433 * 00434 * reltol is the relative tolerance scalar. 00435 * 00436 * abstol is a pointer to the absolute tolerance scalar or 00437 * an N_Vector of absolute tolerances. 00438 * 00439 * The parameters itol, reltol, and abstol define a vector of 00440 * error weights, ewt, with components 00441 * ewt[i] = 1/(reltol*abs(y[i]) + abstol) (if itol = CV_SS), or 00442 * ewt[i] = 1/(reltol*abs(y[i]) + abstol[i]) (if itol = CV_SV). 00443 * This vector is used in all error and convergence tests, which 00444 * use a weighted RMS norm on all error-like vectors v: 00445 * WRMSnorm(v) = sqrt( (1/N) sum(i=1..N) (v[i]*ewt[i])^2 ), 00446 * where N is the problem dimension. 00447 * 00448 * Return flag: 00449 * CV_SUCCESS if successful 00450 * CV_MEM_NULL if the cvode memory was NULL 00451 * CV_MEM_FAIL if a memory allocation failed 00452 * CV_ILL_INPUT f an argument has an illegal value. 00453 * ----------------------------------------------------------------- 00454 */ 00455 00456 SUNDIALS_EXPORT int CVodeMalloc(void *cvode_mem, CVRhsFn f, realtype t0, N_Vector y0, 00457 int itol, realtype reltol, void *abstol); 00458 00459 /* 00460 * ----------------------------------------------------------------- 00461 * Function : CVodeReInit 00462 * ----------------------------------------------------------------- 00463 * CVodeReInit re-initializes CVode for the solution of a problem, 00464 * where a prior call to CVodeMalloc has been made with the same 00465 * problem size N. CVodeReInit performs the same input checking 00466 * and initializations that CVodeMalloc does. 00467 * But it does no memory allocation, assuming that the existing 00468 * internal memory is sufficient for the new problem. 00469 * 00470 * The use of CVodeReInit requires that the maximum method order, 00471 * maxord, is no larger for the new problem than for the problem 00472 * specified in the last call to CVodeMalloc. This condition is 00473 * automatically fulfilled if the multistep method parameter lmm 00474 * is unchanged (or changed from CV_ADAMS to CV_BDF) and the default 00475 * value for maxord is specified. 00476 * 00477 * All of the arguments to CVodeReInit have names and meanings 00478 * identical to those of CVodeMalloc. 00479 * 00480 * The return value of CVodeReInit is equal to CV_SUCCESS = 0 if 00481 * there were no errors; otherwise it is a negative int equal to: 00482 * CV_MEM_NULL indicating cvode_mem was NULL (i.e., 00483 * CVodeCreate has not been called). 00484 * CV_NO_MALLOC indicating that cvode_mem has not been 00485 * allocated (i.e., CVodeMalloc has not been 00486 * called). 00487 * CV_ILL_INPUT indicating an input argument was illegal 00488 * (including an attempt to increase maxord). 00489 * In case of an error return, an error message is also printed. 00490 * ----------------------------------------------------------------- 00491 */ 00492 00493 SUNDIALS_EXPORT int CVodeReInit(void *cvode_mem, CVRhsFn f, realtype t0, N_Vector y0, 00494 int itol, realtype reltol, void *abstol); 00495 00496 /* 00497 * ----------------------------------------------------------------- 00498 * Function : CVodeRootInit 00499 * ----------------------------------------------------------------- 00500 * CVodeRootInit initializes a rootfinding problem to be solved 00501 * during the integration of the ODE system. It must be called 00502 * after CVodeCreate, and before CVode. The arguments are: 00503 * 00504 * cvode_mem = pointer to CVODE memory returned by CVodeCreate. 00505 * 00506 * nrtfn = number of functions g_i, an int >= 0. 00507 * 00508 * g = name of user-supplied function, of type CVRootFn, 00509 * defining the functions g_i whose roots are sought. 00510 * 00511 * g_data = a pointer to user data that will be passed to the 00512 * user's g function every time g is called. 00513 * 00514 * If a new problem is to be solved with a call to CVodeReInit, 00515 * where the new problem has no root functions but the prior one 00516 * did, then call CVodeRootInit with nrtfn = 0. 00517 * 00518 * The return value of CVodeRootInit is CV_SUCCESS = 0 if there were 00519 * no errors; otherwise it is a negative int equal to: 00520 * CV_MEM_NULL indicating cvode_mem was NULL, or 00521 * CV_MEM_FAIL indicating a memory allocation failed. 00522 * (including an attempt to increase maxord). 00523 * CV_ILL_INPUT indicating nrtfn > 0 but g = NULL. 00524 * In case of an error return, an error message is also printed. 00525 * ----------------------------------------------------------------- 00526 */ 00527 00528 SUNDIALS_EXPORT int CVodeRootInit(void *cvode_mem, int nrtfn, CVRootFn g, void *g_data); 00529 00530 /* 00531 * ----------------------------------------------------------------- 00532 * Function : CVode 00533 * ----------------------------------------------------------------- 00534 * CVode integrates the ODE over an interval in t. 00535 * If itask is CV_NORMAL, then the solver integrates from its 00536 * current internal t value to a point at or beyond tout, then 00537 * interpolates to t = tout and returns y(tout) in the user- 00538 * allocated vector yout. If itask is CV_ONE_STEP, then the solver 00539 * takes one internal time step and returns in yout the value of 00540 * y at the new internal time. In this case, tout is used only 00541 * during the first call to CVode to determine the direction of 00542 * integration and the rough scale of the t variable. If itask is 00543 * CV_NORMAL_TSTOP or CV_ONE_STEP_TSTOP, then CVode returns the 00544 * solution at tstop if that comes sooner than tout or the end of 00545 * the next internal step, respectively. In any case, 00546 * the time reached by the solver is placed in (*tret). The 00547 * user is responsible for allocating the memory for this value. 00548 * 00549 * cvode_mem is the pointer to CVODE memory returned by 00550 * CVodeCreate. 00551 * 00552 * tout is the next time at which a computed solution is desired. 00553 * 00554 * yout is the computed solution vector. In CV_NORMAL mode with no 00555 * errors and no roots found, yout=y(tout). 00556 * 00557 * tret is a pointer to a real location. CVode sets (*tret) to 00558 * the time reached by the solver and returns 00559 * yout=y(*tret). 00560 * 00561 * itask is CV_NORMAL, CV_ONE_STEP, CV_NORMAL_TSTOP, or CV_ONE_STEP_TSTOP. 00562 * These four modes are described above. 00563 * 00564 * Here is a brief description of each return value: 00565 * 00566 * CV_SUCCESS: CVode succeeded and no roots were found. 00567 * 00568 * CV_ROOT_RETURN: CVode succeeded, and found one or more roots. 00569 * If nrtfn > 1, call CVodeGetRootInfo to see 00570 * which g_i were found to have a root at (*tret). 00571 * 00572 * CV_TSTOP_RETURN: CVode succeeded and returned at tstop. 00573 * 00574 * CV_MEM_NULL: The cvode_mem argument was NULL. 00575 * 00576 * CV_NO_MALLOC: cvode_mem was not allocated. 00577 * 00578 * CV_ILL_INPUT: One of the inputs to CVode is illegal. This 00579 * includes the situation when a component of the 00580 * error weight vectors becomes < 0 during 00581 * internal time-stepping. It also includes the 00582 * situation where a root of one of the root 00583 * functions was found both at t0 and very near t0. 00584 * The ILL_INPUT flag will also be returned if the 00585 * linear solver routine CV--- (called by the user 00586 * after calling CVodeCreate) failed to set one of 00587 * the linear solver-related fields in cvode_mem or 00588 * if the linear solver's init routine failed. In 00589 * any case, the user should see the printed 00590 * error message for more details. 00591 * 00592 * CV_TOO_MUCH_WORK: The solver took mxstep internal steps but 00593 * could not reach tout. The default value for 00594 * mxstep is MXSTEP_DEFAULT = 500. 00595 * 00596 * CV_TOO_MUCH_ACC: The solver could not satisfy the accuracy 00597 * demanded by the user for some internal step. 00598 * 00599 * CV_ERR_FAILURE: Error test failures occurred too many times 00600 * (= MXNEF = 7) during one internal time step or 00601 * occurred with |h| = hmin. 00602 * 00603 * CV_CONV_FAILURE: Convergence test failures occurred too many 00604 * times (= MXNCF = 10) during one internal time 00605 * step or occurred with |h| = hmin. 00606 * 00607 * CV_LINIT_FAIL: The linear solver's initialization function 00608 * failed. 00609 * 00610 * CV_LSETUP_FAIL: The linear solver's setup routine failed in an 00611 * unrecoverable manner. 00612 * 00613 * CV_LSOLVE_FAIL: The linear solver's solve routine failed in an 00614 * unrecoverable manner. 00615 * ----------------------------------------------------------------- 00616 */ 00617 00618 SUNDIALS_EXPORT int CVode(void *cvode_mem, realtype tout, N_Vector yout, 00619 realtype *tret, int itask); 00620 00621 /* 00622 * ----------------------------------------------------------------- 00623 * Function : CVodeGetDky 00624 * ----------------------------------------------------------------- 00625 * CVodeGetDky computes the kth derivative of the y function at 00626 * time t, where tn-hu <= t <= tn, tn denotes the current 00627 * internal time reached, and hu is the last internal step size 00628 * successfully used by the solver. The user may request 00629 * k=0, 1, ..., qu, where qu is the order last used. The 00630 * derivative vector is returned in dky. This vector must be 00631 * allocated by the caller. It is only legal to call this 00632 * function after a successful return from CVode. 00633 * 00634 * cvode_mem is the pointer to CVODE memory returned by 00635 * CVodeCreate. 00636 * 00637 * t is the time at which the kth derivative of y is evaluated. 00638 * The legal range for t is [tn-hu,tn] as described above. 00639 * 00640 * k is the order of the derivative of y to be computed. The 00641 * legal range for k is [0,qu] as described above. 00642 * 00643 * dky is the output derivative vector [((d/dy)^k)y](t). 00644 * 00645 * The return value for CVodeGetDky is one of: 00646 * 00647 * CV_SUCCESS: CVodeGetDky succeeded. 00648 * 00649 * CV_BAD_K: k is not in the range 0, 1, ..., qu. 00650 * 00651 * CV_BAD_T: t is not in the interval [tn-hu,tn]. 00652 * 00653 * CV_BAD_DKY: The dky argument was NULL. 00654 * 00655 * CV_MEM_NULL: The cvode_mem argument was NULL. 00656 * ----------------------------------------------------------------- 00657 */ 00658 00659 SUNDIALS_EXPORT int CVodeGetDky(void *cvode_mem, realtype t, int k, N_Vector dky); 00660 00661 /* 00662 * ----------------------------------------------------------------- 00663 * Integrator optional output extraction functions 00664 * ----------------------------------------------------------------- 00665 * The following functions can be called to get optional outputs 00666 * and statistics related to the main integrator. 00667 * ----------------------------------------------------------------- 00668 * CVodeGetWorkSpace returns the CVODE real and integer workspaces 00669 * CVodeGetNumSteps returns the cumulative number of internal 00670 * steps taken by the solver 00671 * CVodeGetNumRhsEvals returns the number of calls to the user's 00672 * f function 00673 * CVodeGetNumLinSolvSetups returns the number of calls made to 00674 * the linear solver's setup routine 00675 * CVodeGetNumErrTestFails returns the number of local error test 00676 * failures that have occured 00677 * CVodeGetLastOrder returns the order used during the last 00678 * internal step 00679 * CVodeGetCurrentOrder returns the order to be used on the next 00680 * internal step 00681 * CVodeGetNumStabLimOrderReds returns the number of order 00682 * reductions due to stability limit 00683 * detection 00684 * CVodeGetActualInitStep returns the actual initial step size 00685 * used by CVODE 00686 * CVodeGetLastStep returns the step size for the last internal 00687 * step 00688 * CVodeGetCurrentStep returns the step size to be attempted on 00689 * the next internal step 00690 * CVodeGetCurrentTime returns the current internal time reached 00691 * by the solver 00692 * CVodeGetTolScaleFactor returns a suggested factor by which the 00693 * user's tolerances should be scaled when 00694 * too much accuracy has been requested for 00695 * some internal step 00696 * CVodeGetErrWeights returns the current error weight vector. 00697 * The user must allocate space for eweight. 00698 * CVodeGetEstLocalErrors returns the vector of estimated local 00699 * errors. The user must allocate space 00700 * for ele. 00701 * CVodeGetNumGEvals returns the number of calls to the user's 00702 * g function (for rootfinding) 00703 * CVodeGetRootInfo returns the indices for which g_i was found to 00704 * have a root. The user must allocate space for 00705 * rootsfound. For i = 0 ... nrtfn-1, 00706 * rootsfound[i] = 1 if g_i has a root, and = 0 if not. 00707 * 00708 * CVodeGet* return values: 00709 * CV_SUCCESS if succesful 00710 * CV_MEM_NULL if the cvode memory was NULL 00711 * CV_NO_SLDET if stability limit was not turned on 00712 * ----------------------------------------------------------------- 00713 */ 00714 00715 SUNDIALS_EXPORT int CVodeGetWorkSpace(void *cvode_mem, long int *lenrw, long int *leniw); 00716 SUNDIALS_EXPORT int CVodeGetNumSteps(void *cvode_mem, long int *nsteps); 00717 SUNDIALS_EXPORT int CVodeGetNumRhsEvals(void *cvode_mem, long int *nfevals); 00718 SUNDIALS_EXPORT int CVodeGetNumLinSolvSetups(void *cvode_mem, long int *nlinsetups); 00719 SUNDIALS_EXPORT int CVodeGetNumErrTestFails(void *cvode_mem, long int *netfails); 00720 SUNDIALS_EXPORT int CVodeGetLastOrder(void *cvode_mem, int *qlast); 00721 SUNDIALS_EXPORT int CVodeGetCurrentOrder(void *cvode_mem, int *qcur); 00722 SUNDIALS_EXPORT int CVodeGetNumStabLimOrderReds(void *cvode_mem, long int *nslred); 00723 SUNDIALS_EXPORT int CVodeGetActualInitStep(void *cvode_mem, realtype *hinused); 00724 SUNDIALS_EXPORT int CVodeGetLastStep(void *cvode_mem, realtype *hlast); 00725 SUNDIALS_EXPORT int CVodeGetCurrentStep(void *cvode_mem, realtype *hcur); 00726 SUNDIALS_EXPORT int CVodeGetCurrentTime(void *cvode_mem, realtype *tcur); 00727 SUNDIALS_EXPORT int CVodeGetTolScaleFactor(void *cvode_mem, realtype *tolsfac); 00728 SUNDIALS_EXPORT int CVodeGetErrWeights(void *cvode_mem, N_Vector eweight); 00729 SUNDIALS_EXPORT int CVodeGetEstLocalErrors(void *cvode_mem, N_Vector ele); 00730 SUNDIALS_EXPORT int CVodeGetNumGEvals(void *cvode_mem, long int *ngevals); 00731 SUNDIALS_EXPORT int CVodeGetRootInfo(void *cvode_mem, int *rootsfound); 00732 00733 /* 00734 * ----------------------------------------------------------------- 00735 * As a convenience, the following functions provides the 00736 * optional outputs in one group. 00737 * ----------------------------------------------------------------- 00738 */ 00739 00740 SUNDIALS_EXPORT int CVodeGetIntegratorStats(void *cvode_mem, long int *nsteps, 00741 long int *nfevals, long int *nlinsetups, 00742 long int *netfails, int *qlast, 00743 int *qcur, realtype *hinused, realtype *hlast, 00744 realtype *hcur, realtype *tcur); 00745 00746 /* 00747 * ----------------------------------------------------------------- 00748 * Nonlinear solver optional output extraction functions 00749 * ----------------------------------------------------------------- 00750 * The following functions can be called to get optional outputs 00751 * and statistics related to the nonlinear solver. 00752 * ----------------------------------------------------------------- 00753 * CVodeGetNumNonlinSolvIters returns the number of nonlinear 00754 * solver iterations performed. 00755 * CVodeGetNumNonlinSolvConvFails returns the number of nonlinear 00756 * convergence failures. 00757 * ----------------------------------------------------------------- 00758 */ 00759 00760 SUNDIALS_EXPORT int CVodeGetNumNonlinSolvIters(void *cvode_mem, long int *nniters); 00761 SUNDIALS_EXPORT int CVodeGetNumNonlinSolvConvFails(void *cvode_mem, long int *nncfails); 00762 00763 /* 00764 * ----------------------------------------------------------------- 00765 * As a convenience, the following function provides the 00766 * nonlinear solver optional outputs in a group. 00767 * ----------------------------------------------------------------- 00768 */ 00769 00770 SUNDIALS_EXPORT int CVodeGetNonlinSolvStats(void *cvode_mem, long int *nniters, 00771 long int *nncfails); 00772 00773 /* 00774 * ----------------------------------------------------------------- 00775 * The following function returns the name of the constant 00776 * associated with a CVODE return flag 00777 * ----------------------------------------------------------------- 00778 */ 00779 00780 SUNDIALS_EXPORT char *CVodeGetReturnFlagName(int flag); 00781 00782 /* 00783 * ----------------------------------------------------------------- 00784 * Function : CVodeFree 00785 * ----------------------------------------------------------------- 00786 * CVodeFree frees the problem memory cvode_mem allocated by 00787 * CVodeCreate and CVodeMalloc. Its only argument is the pointer 00788 * cvode_mem returned by CVodeCreate. 00789 * ----------------------------------------------------------------- 00790 */ 00791 00792 SUNDIALS_EXPORT void CVodeFree(void **cvode_mem); 00793 00794 #ifdef __cplusplus 00795 } 00796 #endif 00797 00798 #endif
1.5.6