00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.6 $ 00004 * $Date: 2007/03/20 14:33:17 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer: Radu Serban @ LLNL 00007 * ----------------------------------------------------------------- 00008 * Copyright (c) 2006, The Regents of the University of California. 00009 * Produced at the Lawrence Livermore National Laboratory. 00010 * All rights reserved. 00011 * For details, see the LICENSE file. 00012 * ----------------------------------------------------------------- 00013 * This is the interface file for the main CPODES integrator. 00014 * ----------------------------------------------------------------- 00015 * 00016 * CPODES is used to solve numerically the ordinary initial value 00017 * problem with invariants: 00018 * 00019 * y' = f(t,y) or F(t,y,y') = 0 00020 * c(t,y) = 0 c(t,y) = 0 00021 * y(t0) = y0 y(t0) = y0; y'(t0) = yp0 00022 * 00023 * where t0, y0, yp0 in R^N, f: R x R^N -> R^N, F: R x R^N x R^N -> R^N 00024 * and c: R x R^N -> R^M. 00025 * 00026 * ----------------------------------------------------------------- 00027 */ 00028 00029 #ifndef _CPODES_H 00030 #define _CPODES_H 00031 00032 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00033 extern "C" { 00034 #endif 00035 00036 #include <stdio.h> 00037 #include <sundials/sundials_nvector.h> 00038 00039 /* 00040 * ================================================================= 00041 * C P O D E C O N S T A N T S 00042 * ================================================================= 00043 */ 00044 00045 /* 00046 * ----------------------------------------------------------------- 00047 * Inputs to CPodeCreate, CPodeInit, CPodeReInit, and CPode. 00048 * ----------------------------------------------------------------- 00049 * Symbolic constants for the lmm_type and nls_type inputs to 00050 * CPodeCreate, the ode_type and tol_type inputs to CPodeInit and 00051 * CPodeReInit, the cnstr_type input to CPodeProjInit, as well as 00052 * the input mode to CPode, are given below. 00053 * 00054 * lmm_type: The user of the CPODES package specifies whether to use 00055 * the CP_ADAMS (Adams-Moulton) or CP_BDF (Backward Differentiation 00056 * Formula) linear multistep method. The BDF method is recommended 00057 * for stiff problems, and the CP_ADAMS method is recommended for 00058 * nonstiff problems. 00059 * 00060 * nls_type: At each internal time step, a nonlinear equation must 00061 * be solved. The user can specify either CP_FUNCTIONAL iteration, 00062 * which does not require linear algebra, or a CP_NEWTON iteration, 00063 * which requires the solution of linear systems. In the CP_NEWTON 00064 * case, the user also specifies a CPODES linear solver. 00065 * CP_NEWTON is recommended in case of stiff problems. 00066 * 00067 * ode_type: The ODE system can be given either in explicit form, 00068 * y' = f(t,y) (in which case ode = CP_EXPL) or in implicit form 00069 * (in which case ode = CP_IMPL). 00070 * 00071 * tol_type: This parameter specifies the relative and absolute 00072 * tolerance types to be used. The CP_SS tolerance type means a 00073 * scalar relative and absolute tolerance. The CP_SV tolerance type 00074 * means a scalar relative tolerance and a vector absolute tolerance 00075 * (a potentially different absolute tolerance for each vector 00076 * component). The CP_WF tolerance type means that the user provides 00077 * a function (of type CPEwtFn) to set the error weight vector. 00078 * 00079 * proj_type: If performing projection on the invariant manifold, 00080 * this parameter specifies whether to use the internal algorithm 00081 * or a user-provided projection function. The valid values are 00082 * CP_PROJ_USER and CP_PROJ_INERNAL. 00083 * A value proj_type = CP_PROJ_USER indicates that a function to 00084 * perform the projection is supplied by the user. 00085 * A value proj_type = CP_PROJ_INTERNAL indicates that the internal 00086 * CPODES projection algorithm is to be used. In this case, the 00087 * user must specify the constraint function and a linear solver 00088 * to be used. 00089 * 00090 * proj_norm: Type of the norm in which projection is to be performed. 00091 * The valid values are CP_PROJ_L2NORM (in which case projection 00092 * is done in Euclidian norm) and CP_PROJ_ERRNORM (in which case 00093 * the projection is done in WRMS norm). 00094 * 00095 * cnstr_type: If the internal projection algorithm is used, then 00096 * cnstr_type specifies the type of constraints. 00097 * If the constraints are linear (cnstr_type = CP_CNSTR_LIN), 00098 * then an improved error estimate for the projected method 00099 * (obtained by projecting the error estimate for the original 00100 * method) is available at no additional cost and will always be used. 00101 * If the constraints are nonlinear (cnstr_type = CP_CNSTR_NONLIN), 00102 * obtaining the global projection operator requires an additional 00103 * evaluation of the constraint Jacobian and constructing its 00104 * More-Penrose pseudo-inverse. In this case, the default is 00105 * to use the error estimate of the unprojected method (unless 00106 * indicated otherwise by the user). 00107 * 00108 * mode: The mode input parameter to CPode indicates the job of the 00109 * solver for the next user step. The CP_NORMAL mode is to have 00110 * the solver take internal steps until it has reached or just 00111 * passed the user specified tout parameter. The solver then 00112 * interpolates in order to return an approximate value of y(tout). 00113 * The CP_ONE_STEP option tells the solver to just take one internal 00114 * step and return the solution at the point reached by that step. 00115 * The CP_NORMAL_TSTOP and CP_ONE_STEP_TSTOP modes are similar to 00116 * CP_NORMAL and CP_ONE_STEP, respectively, except that the 00117 * integration never proceeds past the value tstop (specified 00118 * through the routine CPodeSetStopTime). 00119 * ----------------------------------------------------------------- 00120 */ 00121 00122 /* lmm_type */ 00123 #define CP_ADAMS 1 00124 #define CP_BDF 2 00125 00126 /* nls_type */ 00127 #define CP_FUNCTIONAL 1 00128 #define CP_NEWTON 2 00129 00130 /* ode_type */ 00131 #define CP_EXPL 1 00132 #define CP_IMPL 2 00133 00134 /* tol_type */ 00135 #define CP_SS 1 00136 #define CP_SV 2 00137 #define CP_WF 3 00138 00139 /* proj_type */ 00140 #define CP_PROJ_USER 1 00141 #define CP_PROJ_INTERNAL 2 00142 00143 /* proj_norm */ 00144 #define CP_PROJ_L2NORM 1 00145 #define CP_PROJ_ERRNORM 2 00146 00147 /* cnstr_type */ 00148 #define CP_CNSTR_LIN 1 00149 #define CP_CNSTR_NONLIN 2 00150 00151 /* mode */ 00152 #define CP_NORMAL 1 00153 #define CP_ONE_STEP 2 00154 #define CP_NORMAL_TSTOP 3 00155 #define CP_ONE_STEP_TSTOP 4 00156 00157 /* 00158 * ---------------------------------------- 00159 * CPODES return flags 00160 * ---------------------------------------- 00161 */ 00162 00163 #define CP_SUCCESS 0 00164 #define CP_TSTOP_RETURN 1 00165 #define CP_ROOT_RETURN 2 00166 00167 #define CP_WARNING 99 00168 00169 #define CP_TOO_MUCH_WORK -1 00170 #define CP_TOO_MUCH_ACC -2 00171 #define CP_ERR_FAILURE -3 00172 #define CP_CONV_FAILURE -4 00173 00174 #define CP_LINIT_FAIL -5 00175 #define CP_LSETUP_FAIL -6 00176 #define CP_LSOLVE_FAIL -7 00177 #define CP_ODEFUNC_FAIL -8 00178 #define CP_FIRST_ODEFUNC_ERR -9 00179 #define CP_REPTD_ODEFUNC_ERR -10 00180 #define CP_UNREC_ODEFUNC_ERR -11 00181 #define CP_RTFUNC_FAIL -12 00182 00183 #define CP_MEM_FAIL -20 00184 #define CP_MEM_NULL -21 00185 #define CP_ILL_INPUT -22 00186 #define CP_NO_MALLOC -23 00187 #define CP_BAD_K -24 00188 #define CP_BAD_T -25 00189 #define CP_BAD_DKY -26 00190 #define CP_TOO_CLOSE -27 00191 00192 #define CP_NO_QUAD -30 00193 #define CP_QUADFUNC_FAIL -31 00194 #define CP_FIRST_QUADFUNC_ERR -32 00195 #define CP_REPTD_QUADFUNC_ERR -33 00196 #define CP_UNREC_QUADFUNC_ERR -34 00197 00198 #define CP_BAD_IS -40 00199 #define CP_NO_SENS -41 00200 #define CP_SENSFUNC_FAIL -42 00201 #define CP_FIRST_SENSFUNC_ERR -43 00202 #define CP_REPTD_SENSFUNC_ERR -44 00203 #define CP_UNREC_SENSFUNC_ERR -45 00204 00205 #define CP_PLINIT_FAIL -50 00206 #define CP_PLSETUP_FAIL -51 00207 #define CP_PLSOLVE_FAIL -52 00208 #define CP_CNSTRFUNC_FAIL -53 00209 #define CP_PROJFUNC_FAIL -54 00210 #define CP_PROJ_FAILURE -55 00211 #define CP_REPTD_CNSTRFUNC_ERR -56 00212 #define CP_REPTD_PROJFUNC_ERR -57 00213 00214 #define CP_FIRST_CNSTRFUNC_ERR -60 00215 #define CP_NO_RECOVERY -61 00216 #define CP_LINESEARCH_FAIL -62 00217 00218 /* 00219 * ================================================================= 00220 * F U N C T I O N T Y P E S 00221 * ================================================================= 00222 */ 00223 00224 /* 00225 * ----------------------------------------------------------------- 00226 * Type : CPRhsFn 00227 * ----------------------------------------------------------------- 00228 * If the ODE is given in explicit form, the function which defines 00229 * the right-hand side of the ODE system y'=f(t,y) must have type 00230 * CPRhsFn. 00231 * Such a function takes as input the independent variable value t, 00232 * and the dependent variable vector y. It stores the result of 00233 * f(t,y) in the vector fout. The y and fout arguments are of type 00234 * N_Vector. (Allocation of memory for ydot is handled within CODES) 00235 * The f_data parameter is the same as the f_data parameter set by 00236 * the user through the CPodeInit or CPodeReInit functions. This 00237 * user-supplied pointer is passed to the user's fun function every 00238 * time it is called. 00239 * 00240 * A CPRhsFn should return 0 if successful, a negative value if 00241 * an unrecoverable error occured, and a positive value if a 00242 * recoverable error (e.g. invalid y values) occured. 00243 * If an unrecoverable occured, the integration is halted. 00244 * If a recoverable error occured, then (in most cases) CPODES 00245 * will try to correct and retry. 00246 * ----------------------------------------------------------------- 00247 */ 00248 00249 typedef int (*CPRhsFn)(realtype t, N_Vector y, 00250 N_Vector fout, void *f_data); 00251 00252 /* 00253 * ---------------------------------------------------------------- 00254 * Type : CPResFn 00255 * ---------------------------------------------------------------- 00256 * If the ODE is given in implicit form, the function which 00257 * defines the ODE system F(t,y,y')=0 must have type CPResFn. 00258 * 00259 * A CPResFn takes as input the independent variable value t, 00260 * the dependent variable vector y, and the derivative (with 00261 * respect to t) of the y vector, yp. It stores the result of 00262 * F(t,y,y') in the vector fout. The y, yp, and fout arguments are 00263 * of type N_Vector. The f_data parameter is the pointer f_data 00264 * passed by the user to the CPodeInit or CPodeReInit functions. 00265 * This user-supplied pointer is passed to the user's fun function 00266 * every time it is called. 00267 * 00268 * A CPResFn function should return a value of 0 if successful, a 00269 * positive value if a recoverable error occured (e.g. y has an 00270 * illegal value), or a negative value if a nonrecoverable error 00271 * occured. In the latter case, the program halts. If a recoverable 00272 * error occured, then (in most cases) the integrator will attempt 00273 * to correct and retry. 00274 * ---------------------------------------------------------------- 00275 */ 00276 00277 typedef int (*CPResFn)(realtype t, N_Vector y, N_Vector yp, 00278 N_Vector fout, void *f_data); 00279 00280 /* 00281 * ----------------------------------------------------------------- 00282 * Type : CPCnstrFn 00283 * ----------------------------------------------------------------- 00284 * The function cfun defining the invariant constraints c(t,y) = 0 00285 * must have type CPCnstrFn. 00286 * 00287 * A CPCnstrFn takes as input the independent variable value t and 00288 * the dependent variable vector y. It stores the result of c(t,y) 00289 * in the vector cout. The y and cout arguments are of type 00290 * N_Vector. (Allocation of memory for cout is handled within CPODES) 00291 * The c_data parameter is the same as the c_data parameter set by 00292 * the user through the CPodeProjDefineConstraints routine. 00293 * This user-supplied pointer is passed to the user's cfun function 00294 * every time it is called. 00295 * 00296 * A CPCnstrFn should return 0 if successful, a negative value if 00297 * an unrecoverable error occured, and a positive value if a 00298 * recoverable error (e.g. invalid y values) occured. 00299 * If an unrecoverable occured, the integration is halted. 00300 * If a recoverable error occured, then (in most cases) CPODES 00301 * will try to correct and retry. 00302 * ----------------------------------------------------------------- 00303 */ 00304 00305 typedef int (*CPCnstrFn)(realtype t, N_Vector y, 00306 N_Vector cout, void *c_data); 00307 00308 /* 00309 * ----------------------------------------------------------------- 00310 * Type : CPProjFn 00311 * ----------------------------------------------------------------- 00312 * A user-supplied function to performs the projection onto the 00313 * invariant manifold c(t,y)=0, must have type CPProjFn. 00314 * 00315 * A CPProjFn takes as input the independent variable t and the 00316 * current (corrected) variable vector ycur. 00317 * It must compute a correction vector corr such that 00318 * y = ycurr + corr lies on the manifold (i.e. c(t,y)=0). 00319 * The value epsProj is provided to be used in the stopping test 00320 * of a nonlinear solver iteration (the iterations should be 00321 * terminated when the WRMS norm of the current iterate update 00322 * is below epsProj). 00323 * 00324 * Note that, if the projection is orthogonal then it can be written as 00325 * y = P * ycur + alpha(t), with P^2 = P, 00326 * then the projected error estimate is 00327 * errP = P * err 00328 * and ||errP|| <= ||err||. 00329 * The vector err contains a (scaled) version of the current error 00330 * estimate. CPProjFn may also compute the projected error estimate 00331 * and overwrite the vector err with errP. Otherwise, it should leave 00332 * err unchanged. 00333 * 00334 * If err is NULL, a CPProjFn function should attempt NO projection 00335 * of the error estimate (in this case, it was called from within 00336 * the computation of consistent initial conditions). 00337 * 00338 * A CPProjFn should return 0 if successful, a negative value if 00339 * an unrecoverable error occured, and a positive value if a 00340 * recoverable error (e.g. invalid y values) occured. 00341 * If an unrecoverable occured, the integration is halted. 00342 * If a recoverable error occured, then (in most cases) CPODES 00343 * will try to correct and retry. 00344 * ----------------------------------------------------------------- 00345 * NOTE: If the user's projection routine needs other quantities, 00346 * they are accessible as follows: the error weight vector 00347 * can be obtained by calling CPodeGetErrWeights. The unit 00348 * roundoff is available as UNIT_ROUNDOFF defined in 00349 * sundials_types.h. 00350 * ----------------------------------------------------------------- 00351 */ 00352 00353 typedef int (*CPProjFn)(realtype t, N_Vector ycur, N_Vector corr, 00354 realtype epsProj, N_Vector err, void *pdata); 00355 00356 /* 00357 * ----------------------------------------------------------------- 00358 * Type : CPQuadFn 00359 * ----------------------------------------------------------------- 00360 * The qfun function which defines the right hand side of the 00361 * quadrature equations q' = fQ(t,y) must have type CPQuadFn. 00362 * It takes as input the value of the independent variable t and 00363 * the vector of states y and must store the result of fQ in qout. 00364 * (Allocation of memory for qout is handled by CPODES). 00365 * The q_data parameter is the same as the q_data parameter 00366 * set by the user through the CPodeQuadInit function and is 00367 * passed to the qfun function every time it is called. 00368 * 00369 * A CPQuadFn should return 0 if successful, a negative value if 00370 * an unrecoverable error occured, and a positive value if a 00371 * recoverable error (e.g. invalid y values) occured. 00372 * If an unrecoverable occured, the integration is halted. 00373 * If a recoverable error occured, then (in most cases) CPODES 00374 * will try to correct and retry. 00375 * ----------------------------------------------------------------- 00376 */ 00377 00378 typedef int (*CPQuadFn)(realtype t, N_Vector y, 00379 N_Vector qout, void *q_data); 00380 00381 /* 00382 * ----------------------------------------------------------------- 00383 * Type : CPRootFn 00384 * ----------------------------------------------------------------- 00385 * A function g, which defines a set of functions g_i(t,y,y') whose 00386 * roots are sought during the integration, must have type CPRootFn. 00387 * The function g takes as input the independent variable value 00388 * t, the dependent variable vector y, and its derivative yp=y'. 00389 * It stores the nrtfn values g_i(t,y,y') in the realtype array gout. 00390 * (Allocation of memory for gout is handled within CPODES.) 00391 * The g_data parameter is the same as that passed by the user 00392 * to the CPodeRootInit routine. This user-supplied pointer is 00393 * passed to the user's g function every time it is called. 00394 * 00395 * A CPRootFn should return 0 if successful or a non-zero value 00396 * if an error occured (in which case the integration will be halted). 00397 * ----------------------------------------------------------------- 00398 */ 00399 00400 typedef int (*CPRootFn)(realtype t, N_Vector y, N_Vector yp, 00401 realtype *gout, void *g_data); 00402 00403 /* 00404 * ----------------------------------------------------------------- 00405 * Type : CPEwtFn 00406 * ----------------------------------------------------------------- 00407 * A function e, which sets the error weight vector ewt, must have 00408 * type CPEwtFn. 00409 * The function e takes as input the current dependent variable y. 00410 * It must set the vector of error weights used in the WRMS norm: 00411 * 00412 * ||y||_WRMS = sqrt [ 1/N * sum ( ewt_i * y_i)^2 ] 00413 * 00414 * Typically, the vector ewt has components: 00415 * 00416 * ewt_i = 1 / (reltol * |y_i| + abstol_i) 00417 * 00418 * The e_data parameter is the same as that passed by the user 00419 * to the CPodeSetEwtFn routine. This user-supplied pointer is 00420 * passed to the user's e function every time it is called. 00421 * A CPEwtFn e must return 0 if the error weight vector has been 00422 * successfuly set and a non-zero value otherwise. 00423 * ----------------------------------------------------------------- 00424 */ 00425 00426 typedef int (*CPEwtFn)(N_Vector y, N_Vector ewt, void *e_data); 00427 00428 /* 00429 * ----------------------------------------------------------------- 00430 * Type : CPErrHandlerFn 00431 * ----------------------------------------------------------------- 00432 * A function eh, which handles error messages, must have type 00433 * CPErrHandlerFn. 00434 * The function eh takes as input the error code, the name of the 00435 * module reporting the error, the error message, and a pointer to 00436 * user data, the same as that passed to CPodeSetErrHandlerFn. 00437 * 00438 * All error codes are negative, except CP_WARNING which indicates 00439 * a warning (the solver continues). 00440 * 00441 * A CPErrHandlerFn has no return value. 00442 * ----------------------------------------------------------------- 00443 */ 00444 00445 typedef void (*CPErrHandlerFn)(int error_code, 00446 const char *module, const char *function, 00447 char *msg, void *eh_data); 00448 00449 /* 00450 * ================================================================= 00451 * U S E R - C A L L A B L E F U N C T I O N S 00452 * ================================================================= 00453 */ 00454 00455 /* 00456 * ----------------------------------------------------------------- 00457 * Function : CPodeCreate 00458 * ----------------------------------------------------------------- 00459 * CPodeCreate creates an internal memory block for a problem to 00460 * be solved by CPODES. 00461 * 00462 * ode_type - form in which the ODE system is provided. 00463 * The legal values are CP_EXPL or CP_IMPL (see above). 00464 * 00465 * lmm_type - type of linear multistep method to be used. 00466 * The legal values are CP_ADAMS and CP_BDF (see above). 00467 * 00468 * nls_type - type of iteration used to solve the nonlinear 00469 * system that arises during each internal time step. 00470 * The legal values are CP_FUNCTIONAL and CP_NEWTON 00471 * for ode_type = CP_EXPL and only CP_NEWTON for 00472 * ode_type = CP_IMPL. 00473 * 00474 * If successful, CPodeCreate returns a pointer to initialized 00475 * problem memory. This pointer should be passed to CPodeInit. 00476 * If an initialization error occurs, CPodeCreate prints an error 00477 * message to standard err and returns NULL. 00478 * ----------------------------------------------------------------- 00479 */ 00480 00481 SUNDIALS_EXPORT void *CPodeCreate(int ode_type, int lmm_type, int nls_type); 00482 00483 /* 00484 * ----------------------------------------------------------------- 00485 * Function : CPodeInit 00486 * ----------------------------------------------------------------- 00487 * CPodeInit allocates and initializes memory for a problem to be 00488 * solved by CPODES. 00489 * 00490 * cpode_mem - pointer to CPODES memory returned by CPodeCreate. 00491 * 00492 * fun - name of the C function defining the ODE system. 00493 * Depending on the ODE type (see CPodeCreate), fun 00494 * should be of type CPRhsFn (ode_type=CP_EXPL) or of 00495 * type CPResFn (ode_type=CP_IMPL). 00496 * 00497 * f_data - pointer to user data that will be passed to the 00498 * fun function every time it is called. 00499 * 00500 * t0 - initial value of t. 00501 * 00502 * y0 - initial condition vector y(t0). 00503 * 00504 * yp0 - initial condition vector y'(t0). 00505 * 00506 * tol_type - type of tolerances to be used. The legal values are: 00507 * CP_SS (scalar relative and absolute tolerances), 00508 * CP_SV (scalar relative tolerance and vector 00509 * absolute tolerance). 00510 * CP_WF (indicates that the user will provide a 00511 * function to evaluate the error weights. 00512 * In this case, reltol and abstol are ignored.) 00513 * 00514 * reltol - scalar relative tolerance scalar. 00515 * 00516 * abstol - pointer to the absolute tolerance scalar or 00517 * an N_Vector of absolute tolerances. 00518 * 00519 * The parameters tol_type, reltol, and abstol define a vector of 00520 * error weights, ewt, with components 00521 * ewt[i] = 1/(reltol*abs(y[i]) + abstol) if tol_type = CP_SS 00522 * ewt[i] = 1/(reltol*abs(y[i]) + abstol[i]) if tol_type = CP_SV. 00523 * This vector is used in all error and convergence tests, which 00524 * use a weighted RMS norm on all error-like vectors v: 00525 * WRMSnorm(v) = sqrt( (1/N) sum(i=1..N) (v[i]*ewt[i])^2 ), 00526 * where N is the problem dimension. 00527 * 00528 * Return flag: 00529 * CP_SUCCESS if successful 00530 * CP_MEM_NULL if the CPODES memory was NULL 00531 * CP_MEM_FAIL if a memory allocation failed 00532 * CP_ILL_INPUT f an argument has an illegal value. 00533 * ----------------------------------------------------------------- 00534 */ 00535 00536 SUNDIALS_EXPORT int CPodeInit(void *cpode_mem, 00537 void *fun, void *f_data, 00538 realtype t0, N_Vector y0, N_Vector yp0, 00539 int tol_type, realtype reltol, void *abstol); 00540 00541 /* 00542 * ----------------------------------------------------------------- 00543 * Function : CPodeReInit 00544 * ----------------------------------------------------------------- 00545 * CPodeReInit re-initializes CPODES for the solution of a problem, 00546 * where a prior call to CPodeInit has been made with the same 00547 * problem size N. CPodeReInit performs the same input checking 00548 * and initializations that CPodeInit does. 00549 * But it does no memory allocation, assuming that the existing 00550 * internal memory is sufficient for the new problem. 00551 * 00552 * The use of CPodeReInit requires that the maximum method order, 00553 * maxord, is no larger for the new problem than for the problem 00554 * specified in the last call to CPodeInit. This condition is 00555 * automatically fulfilled if the multistep method parameter lmm_type 00556 * is unchanged (or changed from CP_ADAMS to CP_BDF) and the default 00557 * value for maxord is specified. 00558 * 00559 * All of the arguments to CPodeReInit have names and meanings 00560 * identical to those of CPodeInit. 00561 * 00562 * The return value of CPodeReInit is equal to CP_SUCCESS = 0 if 00563 * there were no errors; otherwise it is a negative int equal to: 00564 * CP_MEM_NULL indicating cpode_mem was NULL (i.e., 00565 * CPodeCreate has not been called). 00566 * CP_NO_MALLOC indicating that cpode_mem has not been 00567 * allocated (i.e., CPodeInit has not been 00568 * called). 00569 * CP_ILL_INPUT indicating an input argument was illegal 00570 * (including an attempt to increase maxord). 00571 * In case of an error return, an error message is also printed. 00572 * ----------------------------------------------------------------- 00573 */ 00574 00575 SUNDIALS_EXPORT int CPodeReInit(void *cpode_mem, 00576 void *fun, void *f_data, 00577 realtype t0, N_Vector y0, N_Vector yp0, 00578 int tol_type, realtype reltol, void *abstol); 00579 00580 /* 00581 * ----------------------------------------------------------------- 00582 * Function : CPodeProjInit 00583 * ----------------------------------------------------------------- 00584 * CPodeProjInit initializes the internal CPODES coordinate 00585 * projection algorithm. It must be called after CPodeCreate and 00586 * CPodeInit. 00587 * 00588 * The arguments are as follows: 00589 * 00590 * cpode_mem - pointer to CPODES memory returned by CPodeCreate. 00591 * 00592 * proj_norm - the norm in which projection is to be done. Legal 00593 * values are CP_PROJ_L2NORM and CP_PROJ_ERRNORM. 00594 * 00595 * cnstr_type - the type of constraints. 00596 * CP_CNSTR_LIN : linear constraints. 00597 * CP_CNSTR_NONLIN: nonlinear constraints. 00598 * 00599 * cfun - name of the user-supplied function (type CPCnstrFn) 00600 * defining the invariant manifold. 00601 * 00602 * c_data - pointer to user data that will be passed to the 00603 * cfun function every time it is called. 00604 * 00605 * ctol - a vector of "absolute tolerances" for the constraints. 00606 * In default operation, this vector is only used as 00607 * a template for cloning other vectors. However, if 00608 * enabled through CPodeSetProjTestCnstr, these values, 00609 * together with reltol, are used to compute the 00610 * constraint WL2 norm and a projection will be 00611 * perfomed only if ||c(t)|_WL2 >= 1.0 00612 * 00613 * The return value of CPodeProjInit is equal to CP_SUCCESS = 0 if 00614 * there were no errors; otherwise it is a negative int equal to: 00615 * CP_MEM_NULL - cpode_mem was NULL 00616 * (i.e., CPodeCreate has not been called). 00617 * CP_NO_MALLOC - cpode_mem has not been allocated 00618 * (i.e., CPodeInit has not been called). 00619 * CP_MEM_FAIL - a memory allocation failed. 00620 * CP_ILL_INPUT - an input argument was illegal. 00621 * In case of an error return, an error message is also printed. 00622 * ----------------------------------------------------------------- 00623 */ 00624 00625 SUNDIALS_EXPORT int CPodeProjInit(void *cpode_mem, int proj_norm, 00626 int cnstr_type, CPCnstrFn cfun, void *c_data, 00627 N_Vector ctol); 00628 00629 /* 00630 * ----------------------------------------------------------------- 00631 * Function : CPodeProjDefine 00632 * ----------------------------------------------------------------- 00633 * CPodeProjDefine initializes coordinate projection using a funciton 00634 * provided by the user. It must be called after CPodeInit. 00635 * 00636 * The arguments are as follows: 00637 * 00638 * cpode_mem - pointer to CPODES memory returned by CPodeCreate. 00639 * 00640 * pfun - name of the user-supplied function (type CPProjFn) 00641 * which will perform the projection. 00642 * 00643 * p_data - pointer to user data that will be passed to the 00644 * pfun function every time it is called. 00645 * 00646 * The return value of CPodeProjDefine is CP_SUCCESS if there were 00647 * no errors, or CP_MEM_NULL if the cpode_mem argument was NULL 00648 * (i.e., CPodeCreate has not been called). 00649 * In case of an error return, an error message is also printed. 00650 * ----------------------------------------------------------------- 00651 */ 00652 00653 SUNDIALS_EXPORT int CPodeProjDefine(void *cpode_mem, CPProjFn pfun, void *p_data); 00654 00655 /* 00656 * ----------------------------------------------------------------- 00657 * Function : CPodeQuadInit and CPodeQuadReInit 00658 * ----------------------------------------------------------------- 00659 * CVodeQuadInit allocates and initializes memory related to 00660 * quadrature integration. 00661 * 00662 * cpode_mem - pointer to CPODES memory returned by CPodeCreate 00663 * 00664 * qfun - the user-provided integrand routine. 00665 * 00666 * q_data - pointer to user data that will be passed to the 00667 * qfun function every time it is called. 00668 * 00669 * q0 - N_Vector with initial values for quadratures 00670 * (typically q0 has all zero components). 00671 * 00672 * CPodeQuadReInit re-initializes CPODES's quadrature related memory 00673 * for a problem, assuming it has already been allocated in prior calls 00674 * to CPodeInit and CPodeQuadInit. All problem specification inputs 00675 * are checked for errors. The number of quadratures Nq is assumed to 00676 * be unchanged since the previous call to CPodeQuadInit. 00677 * 00678 * Return values: 00679 * CP_SUCCESS if successful 00680 * CP_MEM_NULL if the CPODES memory was NULL 00681 * CP_MEM_FAIL if a memory allocation failed 00682 * ----------------------------------------------------------------- 00683 */ 00684 00685 SUNDIALS_EXPORT int CPodeQuadInit(void *cpode_mem, CPQuadFn qfun, void *q_data, N_Vector q0); 00686 SUNDIALS_EXPORT int CPodeQuadReInit(void *cpode_mem, CPQuadFn qfun, void *q_data, N_Vector q0); 00687 00688 /* 00689 * ----------------------------------------------------------------- 00690 * Function : CPodeRootInit 00691 * ----------------------------------------------------------------- 00692 * CPodeRootInit initializes a rootfinding problem to be solved 00693 * during the integration of the ODE system. It must be called 00694 * after CPodeCreate, and before CPode. The arguments are: 00695 * 00696 * cpode_mem - pointer to CPODES memory returned by CPodeCreate. 00697 * 00698 * nrtfn - number of functions g_i, an int >= 0. 00699 * 00700 * gfun - name of user-supplied function, of type CPRootFn, 00701 * defining the functions g_i whose roots are sought. 00702 * 00703 * g_data - pointer to user data that will be passed to the 00704 * gfun function every time it is called. 00705 * 00706 * If a new problem is to be solved with a call to CPodeReInit, 00707 * where the new problem has no root functions but the prior one 00708 * did, then call CPodeRootInit with nrtfn = 0. 00709 * 00710 * The return value of CPodeRootInit is CP_SUCCESS = 0 if there were 00711 * no errors; otherwise it is a negative int equal to: 00712 * CP_MEM_NULL - indicating cpode_mem was NULL. 00713 * CP_MEM_FAIL - indicating a memory allocation failed. 00714 * CP_ILL_INPUT - indicating nrtfn > 0 but gfun = NULL. 00715 * In case of an error return, an error message is also printed. 00716 * ----------------------------------------------------------------- 00717 */ 00718 00719 SUNDIALS_EXPORT int CPodeRootInit(void *cpode_mem, int nrtfn, CPRootFn gfun, void *g_data); 00720 00721 /* 00722 * ----------------------------------------------------------------- 00723 * Function : CPodeCalcIC 00724 * ----------------------------------------------------------------- 00725 * CPodeCalcIC calculates corrected initial conditions that are 00726 * consistent with the invariant constraints and (for implicit-form 00727 * ODEs) with the ODE system itself. It first projects the initial 00728 * guess for the state vector (given by the user through CPodeInit 00729 * or CPodeReInit) and then, if necessary, computes a state derivative 00730 * vector as solution of F(t0, y0, y0') = 0. 00731 * 00732 * Note: If the initial conditions satisfy both the constraints and 00733 * (for implicit-form ODEs) the ODE itself, a call to CPodeCalcIC 00734 * is NOT necessary. 00735 * 00736 * A call to CpodeCalcIC must be preceded by a successful call to 00737 * CPodeInit or CPodeReInit for the given ODE problem, and by a 00738 * successful call to the linear system solver specification 00739 * routine. 00740 * 00741 * A call to CPodeCalcIC should precede the call(s) to CPode for 00742 * the given problem. 00743 * 00744 * If successful, CPodeCalcIC stores internally the corrected 00745 * initial conditions which will be used to start the integration 00746 * at the first call to CPode. 00747 * 00748 * The only argument to CPodeCalcIC is the pointer to the CPODE 00749 * memory block returned by CPodeCreate. 00750 * 00751 * The return value of CPodeCalcIC is one of the following: 00752 * 00753 * CP_SUCCESS 00754 * CP_MEM_NULL 00755 * CP_NO_MALLOC 00756 * CP_ILL_INPUT 00757 * CP_LINIT_FAIL 00758 * CP_PLINIT_FAIL 00759 * CP_FIRST_CNSTRFUNC_ERR 00760 * CP_PROJ_FAILURE 00761 * CP_CNSTRFUNC_FAIL 00762 * CP_PROJFUNC_FAIL 00763 * CP_PLSETUP_FAIL 00764 * CP_PLSOLVE_FAIL 00765 * CP_NO_RECOVERY 00766 * 00767 * ----------------------------------------------------------------- 00768 */ 00769 00770 SUNDIALS_EXPORT int CPodeCalcIC(void *cpode_mem); 00771 00772 /* 00773 * ----------------------------------------------------------------- 00774 * Integrator optional input specification functions 00775 * ----------------------------------------------------------------- 00776 * The following functions can be called to set optional inputs 00777 * to values other than the defaults given below: 00778 * 00779 * Function | Optional input / [ default value ] 00780 * ----------------------------------------------------------------- 00781 * | 00782 * CPodeSetErrHandlerFn | user-provided ErrHandler function. 00783 * | [internal] 00784 * | 00785 * CPodeSetErrFile | the file pointer for an error file 00786 * | where all CPODES warning and error 00787 * | messages will be written if the default 00788 * | internal error handling function is used. 00789 * | This parameter can be stdout (standard 00790 * | output), stderr (standard error), or a 00791 * | file pointer (corresponding to a user 00792 * | error file opened for writing) returned 00793 * | by fopen. 00794 * | If not called, then all messages will 00795 * | be written to the standard error stream. 00796 * | [stderr] 00797 * | 00798 * ----------------------------------------------------------------- 00799 * | 00800 * CPodeSetEwtFn | user-provided EwtSet function efun and 00801 * | a pointer to user data that will be 00802 * | passed to the user's efun function 00803 * | every time efun is called. 00804 * | [internal] 00805 * | [NULL] 00806 * | 00807 * CPodeSetMaxOrd | maximum LMM order to be used by the 00808 * | solver. 00809 * | [12 for Adams , 5 for BDF] 00810 * | 00811 * CPodeSetMaxNumSteps | maximum number of internal steps to be 00812 * | taken by the solver in its attempt to 00813 * | reach tout. 00814 * | [500] 00815 * | 00816 * CPodeSetMaxHnilWarns | maximum number of warning messages 00817 * | issued by the solver that t+h==t on the 00818 * | next internal step. A value of -1 means 00819 * | no such messages are issued. 00820 * | [10] 00821 * | 00822 * CPodeSetStabLimDet | flag to turn on/off stability limit 00823 * | detection (TRUE = on, FALSE = off). 00824 * | When BDF is used and order is 3 or 00825 * | greater, CPsldet is called to detect 00826 * | stability limit. If limit is detected, 00827 * | the order is reduced. 00828 * | [FALSE] 00829 * | 00830 * CPodeSetInitStep | initial step size. 00831 * | [estimated by CPODES] 00832 * | 00833 * CPodeSetMinStep | minimum absolute value of step size 00834 * | allowed. 00835 * | [0.0] 00836 * | 00837 * CPodeSetMaxStep | maximum absolute value of step size 00838 * | allowed. 00839 * | [infinity] 00840 * | 00841 * CPodeSetStopTime | the independent variable value past 00842 * | which the solution is not to proceed. 00843 * | [infinity] 00844 * | 00845 * CPodeSetMaxErrTestFails | Maximum number of error test failures 00846 * | in attempting one step. 00847 * | [7] 00848 * | 00849 * ----------------------------------------------------------------- 00850 * | 00851 * CPodeSetMaxNonlinIters | Maximum number of nonlinear solver 00852 * | iterations at one solution. 00853 * | [3] 00854 * | 00855 * CPodeSetMaxConvFails | Maximum number of convergence failures 00856 * | allowed in attempting one step. 00857 * | [10] 00858 * | 00859 * CPodeSetNonlinConvCoef | Coefficient in the nonlinear 00860 * | convergence test. 00861 * | [0.1] 00862 * | 00863 * ----------------------------------------------------------------- 00864 * | 00865 * CPodeSetProjUpdateErrEst| toggles ON/OFF projection of the 00866 * | error estimate. 00867 * | [TRUE] 00868 * | 00869 * CPodeSetProjFrequency | frequency with which the projection 00870 * | step is performed. A value of 1 00871 * | indicates that the projection step 00872 * | will be performed at every step. 00873 * | A value of 0 will disable projection. 00874 * | [1] 00875 * | 00876 * CPodeSetProjTestCnstr | if TRUE, the internal projection 00877 * | function will be performed only if 00878 * | the constraint violation is larger 00879 * | than the prescribed tolerances. 00880 * | Otherwise, the tolerances are ignored 00881 * | and projection is always performed. 00882 * | [FALSE] 00883 * | 00884 * CPodeSetProjLsetupFreq | frequency with which the linear 00885 * | solver setup function is called 00886 * | (i.e. frequency of constraint 00887 * | Jacobian evaluations). The default 00888 * | value of 1 forces a Jacobian 00889 * | evaluation before every single 00890 * | projection step. 00891 * | [1] 00892 * | 00893 * CPodeSetProjNonlinConvCoef | Coefficient in the nonlinear 00894 * | convergence test (for projection). 00895 * | [0.1] 00896 * | 00897 * ----------------------------------------------------------------- 00898 * | 00899 * CPodeSetQuadErrCon | are quadrature variables considered in 00900 * | the error control? 00901 * | If yes, set tolerances for quadrature 00902 * | integration. 00903 * | [errconQ = FALSE] 00904 * | [no tolerances] 00905 * | 00906 * ----------------------------------------------------------------- 00907 * | 00908 * CPodeSetTolerances | Changes the integration tolerances 00909 * | between calls to CPode. 00910 * | [set by CPodeInit/CPodeReInit] 00911 * | 00912 * ---------------------------------------------------------------- 00913 * | 00914 * CPodeSetRootDirection | Specifies the direction of zero 00915 * | crossings to be monitored 00916 * | [both directions] 00917 * | 00918 * ----------------------------------------------------------------- 00919 * Return flag: 00920 * CP_SUCCESS if successful 00921 * CP_MEM_NULL if the CPODES memory is NULL 00922 * CP_ILL_INPUT if an argument has an illegal value 00923 * ----------------------------------------------------------------- 00924 */ 00925 00926 SUNDIALS_EXPORT int CPodeSetErrHandlerFn(void *cpode_mem, CPErrHandlerFn ehfun, void *eh_data); 00927 SUNDIALS_EXPORT int CPodeSetErrFile(void *cpode_mem, FILE *errfp); 00928 00929 SUNDIALS_EXPORT int CPodeSetEwtFn(void *cpode_mem, CPEwtFn efun, void *e_data); 00930 SUNDIALS_EXPORT int CPodeSetMaxOrd(void *cpode_mem, int maxord); 00931 SUNDIALS_EXPORT int CPodeSetMaxNumSteps(void *cpode_mem, long int mxsteps); 00932 SUNDIALS_EXPORT int CPodeSetMaxHnilWarns(void *cpode_mem, int mxhnil); 00933 SUNDIALS_EXPORT int CPodeSetStabLimDet(void *cpode_mem, booleantype stldet); 00934 SUNDIALS_EXPORT int CPodeSetInitStep(void *cpode_mem, realtype hin); 00935 SUNDIALS_EXPORT int CPodeSetMinStep(void *cpode_mem, realtype hmin); 00936 SUNDIALS_EXPORT int CPodeSetMaxStep(void *cpode_mem, realtype hmax); 00937 SUNDIALS_EXPORT int CPodeSetStopTime(void *cpode_mem, realtype tstop); 00938 SUNDIALS_EXPORT int CPodeSetMaxErrTestFails(void *cpode_mem, int maxnef); 00939 00940 SUNDIALS_EXPORT int CPodeSetMaxNonlinIters(void *cpode_mem, int maxcor); 00941 SUNDIALS_EXPORT int CPodeSetMaxConvFails(void *cpode_mem, int maxncf); 00942 SUNDIALS_EXPORT int CPodeSetNonlinConvCoef(void *cpode_mem, realtype nlscoef); 00943 00944 SUNDIALS_EXPORT int CPodeSetProjUpdateErrEst(void *cpode_mem, booleantype proj_err); 00945 SUNDIALS_EXPORT int CPodeSetProjFrequency(void *cpode_mem, long int proj_freq); 00946 SUNDIALS_EXPORT int CPodeSetProjTestCnstr(void *cpode_mem, booleantype test_cnstr); 00947 SUNDIALS_EXPORT int CPodeSetProjLsetupFreq(void *cpode_mem, long int proj_lset_freq); 00948 SUNDIALS_EXPORT int CPodeSetProjNonlinConvCoef(void *cpode_mem, realtype prjcoef); 00949 00950 SUNDIALS_EXPORT int CPodeSetQuadErrCon(void *cpode_mem, booleantype errconQ, 00951 int tol_typeQ, realtype reltolQ, void *abstolQ); 00952 00953 SUNDIALS_EXPORT int CPodeSetTolerances(void *cpode_mem, 00954 int tol_type, realtype reltol, void *abstol); 00955 00956 SUNDIALS_EXPORT int CPodeSetRootDirection(void *cpode_mem, int *rootdir); 00957 00958 /* 00959 * ----------------------------------------------------------------- 00960 * Function : CPode 00961 * ----------------------------------------------------------------- 00962 * CPode integrates the ODE over an interval in t. 00963 * If mode is CP_NORMAL, then the solver integrates from its 00964 * current internal t value to a point at or beyond tout, then 00965 * interpolates to t = tout and returns y(tout) in the user- 00966 * allocated vector yout. If mode is CP_ONE_STEP, then the solver 00967 * takes one internal time step and returns in yout the value of 00968 * y at the new internal time. In this case, tout is used only 00969 * during the first call to CPode to determine the direction of 00970 * integration and the rough scale of the t variable. If mode is 00971 * CP_NORMAL_TSTOP or CP_ONE_STEP_TSTOP, then CPode returns the 00972 * solution at tstop if that comes sooner than tout or the end of 00973 * the next internal step, respectively. In any case, 00974 * the time reached by the solver is placed in (*tret). The 00975 * user is responsible for allocating the memory for this value. 00976 * 00977 * cpode_mem is the pointer to CPODE memory returned by 00978 * CPodeCreate. 00979 * 00980 * tout is the next time at which a computed solution is desired. 00981 * 00982 * tret is a pointer to a real location. CPode sets (*tret) to 00983 * the time reached by the solver and returns yout=y(*tret) 00984 * and ypout=y'(*tret). 00985 * 00986 * yout is the computed solution vector. In CP_NORMAL mode with no 00987 * errors and no roots found, yout=y(tout). 00988 * 00989 * ypout is the computed derivative vector. 00990 * 00991 * mode is CP_NORMAL, CP_ONE_STEP, CP_NORMAL_TSTOP, or 00992 * CP_ONE_STEP_TSTOP. These four modes are described above. 00993 * 00994 * Here is a brief description of each return value: 00995 * 00996 * CP_SUCCESS: CPode succeeded and no roots were found. 00997 * 00998 * CP_ROOT_RETURN: CPode succeeded, and found one or more roots. 00999 * If nrtfn > 1, call CPodeGetRootInfo to see 01000 * which g_i were found to have a root at (*tret). 01001 * 01002 * CP_TSTOP_RETURN: CPode succeeded and returned at tstop. 01003 * 01004 * CP_MEM_NULL: The cpode_mem argument was NULL. 01005 * 01006 * CP_NO_MALLOC: cpode_mem was not allocated. 01007 * 01008 * CP_ILL_INPUT: One of the inputs to CPode is illegal. This 01009 * includes the situation when a component of the 01010 * error weight vectors becomes < 0 during 01011 * internal time-stepping. It also includes the 01012 * situation where a root of one of the root 01013 * functions was found both at t0 and very near t0. 01014 * The ILL_INPUT flag will also be returned if the 01015 * linear solver routine CP--- (called by the user 01016 * after calling CPodeCreate) failed to set one of 01017 * the linear solver-related fields in cpode_mem or 01018 * if the linear solver's init routine failed. In 01019 * any case, the user should see the printed 01020 * error message for more details. 01021 * 01022 * CP_TOO_MUCH_WORK: The solver took mxstep internal steps but 01023 * could not reach tout. The default value for 01024 * mxstep is MXSTEP_DEFAULT = 500. 01025 * 01026 * CP_TOO_MUCH_ACC: The solver could not satisfy the accuracy 01027 * demanded by the user for some internal step. 01028 * 01029 * CP_ERR_FAILURE: Error test failures occurred too many times 01030 * (= MXNEF = 7) during one internal time step or 01031 * occurred with |h| = hmin. 01032 * 01033 * CP_CONV_FAILURE: Convergence test failures occurred too many 01034 * times (= MXNCF = 10) during one internal time 01035 * step or occurred with |h| = hmin. 01036 * 01037 * CP_LINIT_FAIL: The linear solver's initialization function 01038 * failed. 01039 * 01040 * CP_LSETUP_FAIL: The linear solver's setup routine failed in an 01041 * unrecoverable manner. 01042 * 01043 * CP_LSOLVE_FAIL: The linear solver's solve routine failed in an 01044 * unrecoverable manner. 01045 * ----------------------------------------------------------------- 01046 */ 01047 01048 SUNDIALS_EXPORT int CPode(void *cpode_mem, realtype tout, realtype *tret, 01049 N_Vector yout, N_Vector ypout, int mode); 01050 01051 /* 01052 * ----------------------------------------------------------------- 01053 * Function : CPodeGetDky 01054 * ----------------------------------------------------------------- 01055 * CPodeGetDky computes the kth derivative of the y function at 01056 * time t, where tn-hu <= t <= tn, tn denotes the current 01057 * internal time reached, and hu is the last internal step size 01058 * successfully used by the solver. The user may request 01059 * k=0, 1, ..., qu, where qu is the order last used. The 01060 * derivative vector is returned in dky. This vector must be 01061 * allocated by the caller. It is only legal to call this 01062 * function after a successful return from CPode. 01063 * 01064 * cpode_mem is the pointer to CPODES memory returned by 01065 * CPodeCreate. 01066 * 01067 * t is the time at which the kth derivative of y is evaluated. 01068 * The legal range for t is [tn-hu,tn] as described above. 01069 * 01070 * k is the order of the derivative of y to be computed. The 01071 * legal range for k is [0,qu] as described above. 01072 * 01073 * dky is the output derivative vector [((d/dy)^k)y](t). 01074 * 01075 * The return value for CPodeGetDky is one of: 01076 * 01077 * CP_SUCCESS: CPodeGetDky succeeded. 01078 * 01079 * CP_BAD_K: k is not in the range 0, 1, ..., qu. 01080 * 01081 * CP_BAD_T: t is not in the interval [tn-hu,tn]. 01082 * 01083 * CP_BAD_DKY: The dky argument was NULL. 01084 * 01085 * CP_MEM_NULL: The cpode_mem argument was NULL. 01086 * ----------------------------------------------------------------- 01087 */ 01088 01089 SUNDIALS_EXPORT int CPodeGetDky(void *cpode_mem, realtype t, int k, N_Vector dky); 01090 01091 /* 01092 * ----------------------------------------------------------------- 01093 * Quadrature integration solution extraction routines 01094 * ----------------------------------------------------------------- 01095 * The following functions can be called to obtain the quadrature 01096 * variables (or derivatives of them) after a successful integration 01097 * step. If quadratures were not computed, they return CP_NO_QUAD. 01098 * ----------------------------------------------------------------- 01099 */ 01100 01101 SUNDIALS_EXPORT int CPodeGetQuad(void *cpode_mem, realtype t, N_Vector yQout); 01102 SUNDIALS_EXPORT int CPodeGetQuadDky(void *cpode_mem, realtype t, int k, N_Vector dky); 01103 01104 01105 /* 01106 * ----------------------------------------------------------------- 01107 * IC calculation optional output extraction functions 01108 * ----------------------------------------------------------------- 01109 * CPodeGetConsistentIC returns the consistent initial conditions 01110 * computed by CPodeCalcIC 01111 * ----------------------------------------------------------------- 01112 */ 01113 01114 SUNDIALS_EXPORT int CPodeGetConsistentIC(void *cpode_mem, N_Vector yy0, N_Vector yp0); 01115 01116 /* 01117 * ----------------------------------------------------------------- 01118 * Integrator optional output extraction functions 01119 * ----------------------------------------------------------------- 01120 * The following functions can be called to get optional outputs 01121 * and statistics related to the main integrator. 01122 * ----------------------------------------------------------------- 01123 * CPodeGetWorkSpace returns the CPODES real and integer workspaces 01124 * CPodeGetNumSteps returns the cumulative number of internal 01125 * steps taken by the solver 01126 * CPodeGetNumFctEvals returns the number of calls to the user's 01127 * fun function 01128 * CPodeGetNumLinSolvSetups returns the number of calls made to 01129 * the linear solver's setup routine 01130 * CPodeGetNumErrTestFails returns the number of local error test 01131 * failures that have occured 01132 * CPodeGetLastOrder returns the order used during the last 01133 * internal step 01134 * CPodeGetCurrentOrder returns the order to be used on the next 01135 * internal step 01136 * CPodeGetNumStabLimOrderReds returns the number of order 01137 * reductions due to stability limit detection 01138 * CPodeGetActualInitStep returns the actual initial step size 01139 * used by CPODES 01140 * CPodeGetLastStep returns the step size for the last internal step 01141 * CPodeGetCurrentStep returns the step size to be attempted on 01142 * the next internal step 01143 * CPodeGetCurrentTime returns the current internal time reached 01144 * by the solver 01145 * CPodeGetTolScaleFactor returns a suggested factor by which the 01146 * user's tolerances should be scaled when too much accuracy has 01147 * been requested for some internal step 01148 * CPodeGetErrWeights returns the current error weight vector. 01149 * The user must allocate space for eweight. 01150 * CPodeGetEstLocalErrors returns the vector of estimated local 01151 * errors. The user must allocate space for ele. 01152 * CPodeGetNumGEvals returns the number of calls to the user's 01153 * gfun function (for rootfinding) 01154 * CPodeGetRootInfo returns the indices for which g_i was found to 01155 * have a root. The user must allocate space for rootsfound. 01156 * For i = 0 ... nrtfn-1, rootsfound[i] = 1 if g_i has a root, 01157 * and = 0 if not. 01158 * CPodeGetIntegratorStats retruns most of the optional outputs as 01159 * a group. 01160 * CPodeGet* return values: 01161 * CP_SUCCESS if succesful 01162 * CP_MEM_NULL if the CPODES memory was NULL 01163 * CP_NO_SLDET if stability limit was not turned on 01164 * ----------------------------------------------------------------- 01165 */ 01166 01167 SUNDIALS_EXPORT int CPodeGetWorkSpace(void *cpode_mem, long int *lenrw, long int *leniw); 01168 SUNDIALS_EXPORT int CPodeGetNumSteps(void *cpode_mem, long int *nsteps); 01169 SUNDIALS_EXPORT int CPodeGetNumFctEvals(void *cpode_mem, long int *nfevals); 01170 SUNDIALS_EXPORT int CPodeGetNumLinSolvSetups(void *cpode_mem, long int *nlinsetups); 01171 SUNDIALS_EXPORT int CPodeGetNumErrTestFails(void *cpode_mem, long int *netfails); 01172 SUNDIALS_EXPORT int CPodeGetLastOrder(void *cpode_mem, int *qlast); 01173 SUNDIALS_EXPORT int CPodeGetCurrentOrder(void *cpode_mem, int *qcur); 01174 SUNDIALS_EXPORT int CPodeGetNumStabLimOrderReds(void *cpode_mem, long int *nslred); 01175 SUNDIALS_EXPORT int CPodeGetActualInitStep(void *cpode_mem, realtype *hinused); 01176 SUNDIALS_EXPORT int CPodeGetLastStep(void *cpode_mem, realtype *hlast); 01177 SUNDIALS_EXPORT int CPodeGetCurrentStep(void *cpode_mem, realtype *hcur); 01178 SUNDIALS_EXPORT int CPodeGetCurrentTime(void *cpode_mem, realtype *tcur); 01179 SUNDIALS_EXPORT int CPodeGetTolScaleFactor(void *cpode_mem, realtype *tolsfac); 01180 SUNDIALS_EXPORT int CPodeGetErrWeights(void *cpode_mem, N_Vector eweight); 01181 SUNDIALS_EXPORT int CPodeGetEstLocalErrors(void *cpode_mem, N_Vector ele); 01182 SUNDIALS_EXPORT int CPodeGetNumGEvals(void *cpode_mem, long int *ngevals); 01183 SUNDIALS_EXPORT int CPodeGetRootInfo(void *cpode_mem, int *rootsfound); 01184 SUNDIALS_EXPORT int CPodeGetIntegratorStats(void *cpode_mem, long int *nsteps, 01185 long int *nfevals, long int *nlinsetups, 01186 long int *netfails, int *qlast, 01187 int *qcur, realtype *hinused, realtype *hlast, 01188 realtype *hcur, realtype *tcur); 01189 01190 /* 01191 * ----------------------------------------------------------------- 01192 * Nonlinear solver optional output extraction functions 01193 * ----------------------------------------------------------------- 01194 * The following functions can be called to get optional outputs 01195 * and statistics related to the nonlinear solver. 01196 * ----------------------------------------------------------------- 01197 * CPodeGetNumNonlinSolvIters returns the number of nonlinear 01198 * solver iterations performed. 01199 * CPodeGetNumNonlinSolvConvFails returns the number of nonlinear 01200 * convergence failures. 01201 * CPodeGetNonlinSolvStats returns the nonlinear solver optional 01202 * outputs in a group. 01203 * ----------------------------------------------------------------- 01204 */ 01205 01206 SUNDIALS_EXPORT int CPodeGetNumNonlinSolvIters(void *cpode_mem, long int *nniters); 01207 SUNDIALS_EXPORT int CPodeGetNumNonlinSolvConvFails(void *cpode_mem, long int *nncfails); 01208 SUNDIALS_EXPORT int CPodeGetNonlinSolvStats(void *cpode_mem, long int *nniters, 01209 long int *nncfails); 01210 01211 01212 /* 01213 * ----------------------------------------------------------------- 01214 * Projection optional output extraction functions 01215 * ----------------------------------------------------------------- 01216 * The following functions can be called to get optional outputs 01217 * and statistics related to the projection step. 01218 * ----------------------------------------------------------------- 01219 * ----------------------------------------------------------------- 01220 */ 01221 01222 SUNDIALS_EXPORT int CPodeGetProjNumProj(void *cpode_mem, long int *nproj); 01223 SUNDIALS_EXPORT int CPodeGetProjNumCnstrEvals(void *cpode_mem, long int *nce); 01224 SUNDIALS_EXPORT int CPodeGetProjNumLinSolvSetups(void *cpode_mem, long int *nsetupsP); 01225 SUNDIALS_EXPORT int CPodeGetProjNumFailures(void *cpode_mem, long int *nprf); 01226 SUNDIALS_EXPORT int CPodeGetProjStats(void *cpode_mem, long int *nproj, 01227 long int *nce, long int *nsetupsP, 01228 long int *nprf); 01229 01230 /* 01231 * ----------------------------------------------------------------- 01232 * Quadrature integration optional output extraction functions 01233 * ----------------------------------------------------------------- 01234 * The following functions can be called to get optional outputs 01235 * and statistics related to the integration of quadratures. 01236 * ----------------------------------------------------------------- 01237 * CPodeGetQuadNumFunEvals returns the number of calls to the 01238 * user function qfun defining the integrand 01239 * CPodeGetQuadErrWeights returns the vector of error weights for 01240 * the quadrature variables. The user must allocate space for ewtQ. 01241 * ----------------------------------------------------------------- 01242 */ 01243 01244 SUNDIALS_EXPORT int CPodeGetQuadNumFunEvals(void *cpode_mem, long int *nqevals); 01245 SUNDIALS_EXPORT int CPodeGetQuadErrWeights(void *cpode_mem, N_Vector eQweight); 01246 01247 /* 01248 * ----------------------------------------------------------------- 01249 * The following function returns the name of the constant 01250 * associated with a CPODES return flag 01251 * ----------------------------------------------------------------- 01252 */ 01253 01254 SUNDIALS_EXPORT char *CPodeGetReturnFlagName(int flag); 01255 01256 /* 01257 * ----------------------------------------------------------------- 01258 * Function : CPodeFree 01259 * ----------------------------------------------------------------- 01260 * CPodeFree frees the problem memory cpode_mem allocated by 01261 * CPodeCreate and CPodeInit. Its only argument is the pointer 01262 * cpode_mem returned by CPodeCreate. 01263 * ----------------------------------------------------------------- 01264 */ 01265 01266 SUNDIALS_EXPORT void CPodeFree(void **cpode_mem); 01267 01268 /* 01269 * ----------------------------------------------------------------- 01270 * Function : CPodeQuadFree 01271 * ----------------------------------------------------------------- 01272 * CPodeQuadFree frees the problem memory in cpode_mem allocated 01273 * for quadrature integration. Its only argument is the pointer 01274 * cpode_mem returned by CPodeCreate. 01275 * Note that CPodeQuadFree is called by CPodeFree. 01276 * ----------------------------------------------------------------- 01277 */ 01278 01279 SUNDIALS_EXPORT void CPodeQuadFree(void *cpode_mem); 01280 01281 #ifdef __cplusplus 01282 } 01283 #endif 01284 01285 #endif
1.5.6