00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.5 $ 00004 * $Date: 2006/11/30 21:10:55 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer(s): Allan G. Taylor, Alan C. Hindmarsh, Radu Serban, 00007 * and Aaron Collier @ LLNL 00008 * ----------------------------------------------------------------- 00009 * Copyright (c) 2002, The Regents of the University of California 00010 * Produced at the Lawrence Livermore National Laboratory 00011 * All rights reserved 00012 * For details, see the LICENSE file 00013 * ----------------------------------------------------------------- 00014 * This is the header (include) file for the main IDA solver. 00015 * ----------------------------------------------------------------- 00016 * 00017 * IDA is used to solve numerically the initial value problem 00018 * for the differential algebraic equation (DAE) system 00019 * F(t,y,y') = 0, 00020 * given initial conditions 00021 * y(t0) = y0, y'(t0) = yp0. 00022 * Here y and F are vectors of length N. 00023 * 00024 * ----------------------------------------------------------------- 00025 */ 00026 00027 #ifndef _IDA_H 00028 #define _IDA_H 00029 00030 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00031 extern "C" { 00032 #endif 00033 00034 #include <stdio.h> 00035 00036 #include <sundials/sundials_nvector.h> 00037 00038 /* 00039 * ================================================================= 00040 * I D A C O N S T A N T S 00041 * ================================================================= 00042 */ 00043 00044 /* 00045 * ---------------------------------------------------------------- 00046 * Inputs to IDAMalloc, IDAReInit, IDACalcIC, and IDASolve. 00047 * ---------------------------------------------------------------- 00048 */ 00049 00050 /* itol */ 00051 #define IDA_SS 1 00052 #define IDA_SV 2 00053 #define IDA_WF 3 00054 00055 /* itask */ 00056 #define IDA_NORMAL 1 00057 #define IDA_ONE_STEP 2 00058 #define IDA_NORMAL_TSTOP 3 00059 #define IDA_ONE_STEP_TSTOP 4 00060 00061 /* icopt */ 00062 #define IDA_YA_YDP_INIT 1 00063 #define IDA_Y_INIT 2 00064 00065 /* 00066 * ---------------------------------------- 00067 * IDA return flags 00068 * ---------------------------------------- 00069 */ 00070 00071 #define IDA_SUCCESS 0 00072 #define IDA_TSTOP_RETURN 1 00073 #define IDA_ROOT_RETURN 2 00074 00075 #define IDA_WARNING 99 00076 00077 #define IDA_MEM_NULL -1 00078 #define IDA_ILL_INPUT -2 00079 #define IDA_NO_MALLOC -3 00080 #define IDA_TOO_MUCH_WORK -4 00081 #define IDA_TOO_MUCH_ACC -5 00082 #define IDA_ERR_FAIL -6 00083 #define IDA_CONV_FAIL -7 00084 #define IDA_LINIT_FAIL -8 00085 #define IDA_LSETUP_FAIL -9 00086 #define IDA_LSOLVE_FAIL -10 00087 #define IDA_RES_FAIL -11 00088 #define IDA_CONSTR_FAIL -12 00089 #define IDA_REP_RES_ERR -13 00090 00091 #define IDA_MEM_FAIL -14 00092 00093 #define IDA_BAD_T -15 00094 00095 #define IDA_BAD_EWT -16 00096 #define IDA_FIRST_RES_FAIL -17 00097 #define IDA_LINESEARCH_FAIL -18 00098 #define IDA_NO_RECOVERY -19 00099 00100 #define IDA_RTFUNC_FAIL -20 00101 00102 /* 00103 * ---------------------------------------------------------------- 00104 * Type : IDAResFn 00105 * ---------------------------------------------------------------- 00106 * The F function which defines the DAE system F(t,y,y')=0 00107 * must have type IDAResFn. 00108 * Symbols are as follows: 00109 * t <-> t y <-> yy 00110 * y' <-> yp F <-> rr 00111 * A IDAResFn takes as input the independent variable value t, 00112 * the dependent variable vector yy, and the derivative (with 00113 * respect to t) of the yy vector, yp. It stores the result of 00114 * F(t,y,y') in the vector rr. The yy, yp, and rr arguments are of 00115 * type N_Vector. The res_data parameter is the pointer res_data 00116 * passed by the user to the IDASetRdata routine. This user-supplied 00117 * pointer is passed to the user's res function every time it is called, 00118 * to provide access in res to user data. 00119 * 00120 * A IDAResFn res should return a value of 0 if successful, a positive 00121 * value if a recoverable error occured (e.g. yy has an illegal value), 00122 * or a negative value if a nonrecoverable error occured. In the latter 00123 * case, the program halts. If a recoverable error occured, the integrator 00124 * will attempt to correct and retry. 00125 * ---------------------------------------------------------------- 00126 */ 00127 00128 typedef int (*IDAResFn)(realtype tt, N_Vector yy, N_Vector yp, 00129 N_Vector rr, void *res_data); 00130 00131 /* 00132 * ----------------------------------------------------------------- 00133 * Type : IDARootFn 00134 * ----------------------------------------------------------------- 00135 * A function g, which defines a set of functions g_i(t,y,y') whose 00136 * roots are sought during the integration, must have type IDARootFn. 00137 * The function g takes as input the independent variable value t, 00138 * the dependent variable vector y, and its t-derivative yp (= y'). 00139 * It stores the nrtfn values g_i(t,y,y') in the realtype array gout. 00140 * (Allocation of memory for gout is handled within IDA.) 00141 * The g_data parameter is the same as that passed by the user 00142 * to the IDARootInit routine. This user-supplied pointer is 00143 * passed to the user's g function every time it is called. 00144 * 00145 * An IDARootFn should return 0 if successful or a non-zero value 00146 * if an error occured (in which case the integration will be halted). 00147 * ----------------------------------------------------------------- 00148 */ 00149 00150 typedef int (*IDARootFn)(realtype t, N_Vector y, N_Vector yp, 00151 realtype *gout, void *g_data); 00152 00153 /* 00154 * ----------------------------------------------------------------- 00155 * Type : IDAEwtFn 00156 * ----------------------------------------------------------------- 00157 * A function e, which sets the error weight vector ewt, must have 00158 * type IDAEwtFn. 00159 * The function e takes as input the current dependent variable y. 00160 * It must set the vector of error weights used in the WRMS norm: 00161 * 00162 * ||y||_WRMS = sqrt [ 1/N * sum ( ewt_i * y_i)^2 ] 00163 * 00164 * Typically, the vector ewt has components: 00165 * 00166 * ewt_i = 1 / (reltol * |y_i| + abstol_i) 00167 * 00168 * The e_data parameter is the same as that passed by the user 00169 * to the IDASetEdata routine. This user-supplied pointer is 00170 * passed to the user's e function every time it is called. 00171 * An IDAEwtFn e must return 0 if the error weight vector has been 00172 * successfuly set and a non-zero value otherwise. 00173 * ----------------------------------------------------------------- 00174 */ 00175 00176 typedef int (*IDAEwtFn)(N_Vector y, N_Vector ewt, void *e_data); 00177 00178 /* 00179 * ----------------------------------------------------------------- 00180 * Type : IDAErrHandlerFn 00181 * ----------------------------------------------------------------- 00182 * A function eh, which handles error messages, must have type 00183 * IDAErrHandlerFn. 00184 * The function eh takes as input the error code, the name of the 00185 * module reporting the error, the error message, and a pointer to 00186 * user data, the same as that passed to CVodeSetErrHandlerFn. 00187 * 00188 * All error codes are negative, except IDA_WARNING which indicates 00189 * a warning (the solver continues). 00190 * 00191 * An IDAErrHandlerFn has no return value. 00192 * ----------------------------------------------------------------- 00193 */ 00194 00195 typedef void (*IDAErrHandlerFn)(int error_code, 00196 const char *module, const char *function, 00197 char *msg, void *eh_data); 00198 00199 /* 00200 * ================================================================ 00201 * U S E R - C A L L A B L E R O U T I N E S 00202 * ================================================================ 00203 */ 00204 00205 /* 00206 * ---------------------------------------------------------------- 00207 * Function : IDACreate 00208 * ---------------------------------------------------------------- 00209 * IDACreate creates an internal memory block for a problem to 00210 * be solved by IDA. 00211 * 00212 * If successful, IDACreate returns a pointer to initialized 00213 * problem memory. This pointer should be passed to IDAMalloc. 00214 * If an initialization error occurs, IDACreate prints an error 00215 * message to standard err and returns NULL. 00216 * 00217 * ---------------------------------------------------------------- 00218 */ 00219 00220 SUNDIALS_EXPORT void *IDACreate(void); 00221 00222 /* 00223 * ---------------------------------------------------------------- 00224 * Integrator optional input specification functions 00225 * ---------------------------------------------------------------- 00226 * The following functions can be called to set optional inputs 00227 * to values other than the defaults given below: 00228 * 00229 * | 00230 * Function | Optional input / [ default value ] 00231 * | 00232 * ---------------------------------------------------------------- 00233 * | 00234 * IDASetErrHandlerFn | user-provided ErrHandler function. 00235 * | [internal] 00236 * | 00237 * IDASetErrFile | the file pointer for an error file 00238 * | where all CVODE warning and error 00239 * | messages will be written if the default 00240 * | internal error handling function is used. 00241 * | This parameter can be stdout (standard 00242 * | output), stderr (standard error), or a 00243 * | file pointer (corresponding to a user 00244 * | error file opened for writing) returned 00245 * | by fopen. 00246 * | If not called, then all messages will 00247 * | be written to the standard error stream. 00248 * | [stderr] 00249 * | 00250 * IDASetRdata | a pointer to user data that will be 00251 * | passed to the user's res function every 00252 * | time res is called. 00253 * | [NULL] 00254 * | 00255 * IDASetEwtFn | user-provide EwtSet function e and 00256 * | a pointer to user data that will be 00257 * | passed to the user's e function every 00258 * | time e is called. 00259 * | [NULL] 00260 * | [NULL] 00261 * | 00262 * IDASetMaxOrd | maximum lmm order to be used by the 00263 * | solver. 00264 * | [5] 00265 * | 00266 * IDASetMaxNumSteps | maximum number of internal steps to be 00267 * | taken by the solver in its attempt to 00268 * | reach tout. 00269 * | [500] 00270 * | 00271 * IDASetInitStep | initial step size. 00272 * | [estimated by IDA] 00273 * | 00274 * IDASetMaxStep | maximum absolute value of step size 00275 * | allowed. 00276 * | [infinity] 00277 * | 00278 * IDASetStopTime | the independent variable value past 00279 * | which the solution is not to proceed. 00280 * | [infinity] 00281 * | 00282 * IDASetNonlinConvCoef | Newton convergence test constant 00283 * | for use during integration. 00284 * | [0.33] 00285 * | 00286 * IDASetMaxErrTestFails| Maximum number of error test failures 00287 * | in attempting one step. 00288 * | [10] 00289 * | 00290 * IDASetMaxNonlinIters | Maximum number of nonlinear solver 00291 * | iterations at one solution. 00292 * | [4] 00293 * | 00294 * IDASetMaxConvFails | Maximum number of allowable conv. 00295 * | failures in attempting one step. 00296 * | [10] 00297 * | 00298 * IDASetSuppressAlg | flag to indicate whether or not to 00299 * | suppress algebraic variables in the 00300 * | local error tests: 00301 * | FALSE = do not suppress; 00302 * | TRUE = do suppress; 00303 * | [FALSE] 00304 * | NOTE: if suppressed algebraic variables 00305 * | is selected, the nvector 'id' must be 00306 * | supplied for identification of those 00307 * | algebraic components (see IDASetId). 00308 * | 00309 * IDASetId | an N_Vector, which states a given 00310 * | element to be either algebraic or 00311 * | differential. 00312 * | A value of 1.0 indicates a differential 00313 * | variable while a 0.0 indicates an 00314 * | algebraic variable. 'id' is required 00315 * | if optional input SUPPRESSALG is set, 00316 * | or if IDACalcIC is to be called with 00317 * | icopt = IDA_YA_YDP_INIT. 00318 * | 00319 * IDASetConstraints | an N_Vector defining inequality 00320 * | constraints for each component of the 00321 * | solution vector y. If a given element 00322 * | of this vector has values +2 or -2, 00323 * | then the corresponding component of y 00324 * | will be constrained to be > 0.0 or 00325 * | <0.0, respectively, while if it is +1 00326 * | or -1, the y component is constrained 00327 * | to be >= 0.0 or <= 0.0, respectively. 00328 * | If a component of constraints is 0.0, 00329 * | then no constraint is imposed on the 00330 * | corresponding component of y. 00331 * | The presence of a non-NULL constraints 00332 * | vector that is not 0.0 (ZERO) in all 00333 * | components will cause constraint 00334 * | checking to be performed. 00335 * | 00336 * ----------------------------------------------------------------- 00337 * | 00338 * IDASetTolerances | Changes the integration tolerances 00339 * | between calls to IDASolve(). 00340 * | [set by IDAMalloc/IDAReInit] 00341 * | 00342 * ---------------------------------------------------------------- 00343 * Return flag: 00344 * IDA_SUCCESS if successful 00345 * IDA_MEM_NULL if the ida memory is NULL 00346 * IDA_ILL_INPUT if an argument has an illegal value 00347 * 00348 * ---------------------------------------------------------------- 00349 */ 00350 00351 SUNDIALS_EXPORT int IDASetErrHandlerFn(void *ida_mem, IDAErrHandlerFn ehfun, void *eh_data); 00352 SUNDIALS_EXPORT int IDASetErrFile(void *ida_mem, FILE *errfp); 00353 SUNDIALS_EXPORT int IDASetRdata(void *ida_mem, void *res_data); 00354 SUNDIALS_EXPORT int IDASetEwtFn(void *ida_mem, IDAEwtFn efun, void *edata); 00355 SUNDIALS_EXPORT int IDASetMaxOrd(void *ida_mem, int maxord); 00356 SUNDIALS_EXPORT int IDASetMaxNumSteps(void *ida_mem, long int mxsteps); 00357 SUNDIALS_EXPORT int IDASetInitStep(void *ida_mem, realtype hin); 00358 SUNDIALS_EXPORT int IDASetMaxStep(void *ida_mem, realtype hmax); 00359 SUNDIALS_EXPORT int IDASetStopTime(void *ida_mem, realtype tstop); 00360 SUNDIALS_EXPORT int IDASetNonlinConvCoef(void *ida_mem, realtype epcon); 00361 SUNDIALS_EXPORT int IDASetMaxErrTestFails(void *ida_mem, int maxnef); 00362 SUNDIALS_EXPORT int IDASetMaxNonlinIters(void *ida_mem, int maxcor); 00363 SUNDIALS_EXPORT int IDASetMaxConvFails(void *ida_mem, int maxncf); 00364 SUNDIALS_EXPORT int IDASetSuppressAlg(void *ida_mem, booleantype suppressalg); 00365 SUNDIALS_EXPORT int IDASetId(void *ida_mem, N_Vector id); 00366 SUNDIALS_EXPORT int IDASetConstraints(void *ida_mem, N_Vector constraints); 00367 00368 SUNDIALS_EXPORT int IDASetTolerances(void *ida_mem, int itol, realtype rtol, void *atol); 00369 00370 /* 00371 * ---------------------------------------------------------------- 00372 * Function : IDAMalloc 00373 * ---------------------------------------------------------------- 00374 * IDAMalloc allocates and initializes memory for a problem to 00375 * to be solved by IDA. 00376 * 00377 * res is the residual function F in F(t,y,y') = 0. 00378 * 00379 * t0 is the initial value of t, the independent variable. 00380 * 00381 * yy0 is the initial condition vector y(t0). 00382 * 00383 * yp0 is the initial condition vector y'(t0) 00384 * 00385 * itol is the type of tolerances to be used. 00386 * The legal values are: 00387 * IDA_SS (scalar relative and absolute tolerances), 00388 * IDA_SV (scalar relative tolerance and vector 00389 * absolute tolerance). 00390 * IDA_WF (user-provided weight function) 00391 * 00392 * rtol is the relative tolerance scalar. 00393 * 00394 * atol is a pointer (void) to the absolute tolerance scalar or 00395 * an N_Vector tolerance or an IDAEwtFn funciton. 00396 * (ewt) 00397 * Both rtol and atol are used to compute the error weight 00398 * vector, ewt. The error test required of a correction 00399 * delta is that the weighted-RMS norm of delta be less 00400 * than or equal to 1.0. Other convergence tests use the 00401 * same norm. The weighting vector used in this norm is 00402 * ewt. The components of ewt are defined by 00403 * ewt[i] = 1.0/(rtol*yy[i] + atol[i]). Here, yy is the 00404 * current approximate solution. See the routine 00405 * N_VWrmsNorm for the norm used in this error test. 00406 * 00407 * Note: The tolerance values may be changed in between calls to 00408 * IDASolve for the same problem. These values refer to 00409 * (*rtol) and either (*atol), for a scalar absolute 00410 * tolerance, or the components of atol, for a vector 00411 * absolute tolerance. 00412 * 00413 * IDA_SUCCESS if successful 00414 * IDA_MEM_NULL if the ida memory was NULL 00415 * IDA_MEM_FAIL if a memory allocation failed 00416 * IDA_ILL_INPUT f an argument has an illegal value. 00417 * 00418 * ---------------------------------------------------------------- 00419 */ 00420 00421 SUNDIALS_EXPORT int IDAMalloc(void *ida_mem, IDAResFn res, 00422 realtype t0, N_Vector yy0, N_Vector yp0, 00423 int itol, realtype rtol, void *atol); 00424 00425 /* 00426 * ---------------------------------------------------------------- 00427 * Function : IDAReInit 00428 * ---------------------------------------------------------------- 00429 * IDAReInit re-initializes IDA for the solution of a problem, 00430 * where a prior call to IDAMalloc has been made. 00431 * IDAReInit performs the same input checking and initializations 00432 * that IDAMalloc does. 00433 * But it does no memory allocation, assuming that the existing 00434 * internal memory is sufficient for the new problem. 00435 * 00436 * The use of IDAReInit requires that the maximum method order, 00437 * maxord, is no larger for the new problem than for the problem 00438 * specified in the last call to IDAMalloc. This condition is 00439 * automatically fulfilled if the default value for maxord is 00440 * specified. 00441 * 00442 * Following the call to IDAReInit, a call to the linear solver 00443 * specification routine is necessary if a different linear solver 00444 * is chosen, but may not be otherwise. If the same linear solver 00445 * is chosen, and there are no changes in its input parameters, 00446 * then no call to that routine is needed. 00447 * 00448 * The first argument to IDAReInit is: 00449 * 00450 * ida_mem = pointer to IDA memory returned by IDACreate. 00451 * 00452 * All the remaining arguments to IDAReInit have names and 00453 * meanings identical to those of IDAMalloc. 00454 * 00455 * The return value of IDAReInit is equal to SUCCESS = 0 if there 00456 * were no errors; otherwise it is a negative int equal to: 00457 * IDA_MEM_NULL indicating ida_mem was NULL, or 00458 * IDA_NO_MALLOC indicating that ida_mem was not allocated. 00459 * IDA_ILL_INPUT indicating an input argument was illegal 00460 * (including an attempt to increase maxord). 00461 * In case of an error return, an error message is also printed. 00462 * ---------------------------------------------------------------- 00463 */ 00464 00465 SUNDIALS_EXPORT int IDAReInit(void *ida_mem, IDAResFn res, 00466 realtype t0, N_Vector yy0, N_Vector yp0, 00467 int itol, realtype rtol, void *atol); 00468 00469 /* ---------------------------------------------------------------- 00470 * Initial Conditions optional input specification functions 00471 * ---------------------------------------------------------------- 00472 * The following functions can be called to set optional inputs 00473 * to control the initial conditions calculations. 00474 * 00475 * | 00476 * Function | Optional input / [ default value ] 00477 * | 00478 * -------------------------------------------------------------- 00479 * | 00480 * IDASetNonlinConvCoefIC | positive coeficient in the Newton 00481 * | convergence test. This test uses a 00482 * | weighted RMS norm (with weights 00483 * | defined by the tolerances, as in 00484 * | IDASolve). For new initial value 00485 * | vectors y and y' to be accepted, the 00486 * | norm of J-inverse F(t0,y,y') is 00487 * | required to be less than epiccon, 00488 * | where J is the system Jacobian. 00489 * | [0.01 * 0.33] 00490 * | 00491 * IDASetMaxNumStepsIC | maximum number of values of h allowed 00492 * | when icopt = IDA_YA_YDP_INIT, where 00493 * | h appears in the system Jacobian, 00494 * | J = dF/dy + (1/h)dF/dy'. 00495 * | [5] 00496 * | 00497 * IDASetMaxNumJacsIC | maximum number of values of the 00498 * | approximate Jacobian or preconditioner 00499 * | allowed, when the Newton iterations 00500 * | appear to be slowly converging. 00501 * | [4] 00502 * | 00503 * IDASetMaxNumItersIC | maximum number of Newton iterations 00504 * | allowed in any one attempt to solve 00505 * | the IC problem. 00506 * | [10] 00507 * | 00508 * IDASetLineSearchOffIC | a boolean flag to turn off the 00509 * | linesearch algorithm. 00510 * | [FALSE] 00511 * | 00512 * IDASetStepToleranceIC | positive lower bound on the norm of 00513 * | a Newton step. 00514 * | [(unit roundoff)^(2/3) 00515 * 00516 * ---------------------------------------------------------------- 00517 * Return flag: 00518 * IDA_SUCCESS if successful 00519 * IDA_MEM_NULL if the ida memory is NULL 00520 * IDA_ILL_INPUT if an argument has an illegal value 00521 * 00522 * ---------------------------------------------------------------- 00523 */ 00524 00525 SUNDIALS_EXPORT int IDASetNonlinConvCoefIC(void *ida_mem, realtype epiccon); 00526 SUNDIALS_EXPORT int IDASetMaxNumStepsIC(void *ida_mem, int maxnh); 00527 SUNDIALS_EXPORT int IDASetMaxNumJacsIC(void *ida_mem, int maxnj); 00528 SUNDIALS_EXPORT int IDASetMaxNumItersIC(void *ida_mem, int maxnit); 00529 SUNDIALS_EXPORT int IDASetLineSearchOffIC(void *ida_mem, booleantype lsoff); 00530 SUNDIALS_EXPORT int IDASetStepToleranceIC(void *ida_mem, realtype steptol); 00531 00532 /* 00533 * ----------------------------------------------------------------- 00534 * Function : IDARootInit 00535 * ----------------------------------------------------------------- 00536 * IDARootInit initializes a rootfinding problem to be solved 00537 * during the integration of the DAE system. It must be called 00538 * after IDACreate, and before IDASolve. The arguments are: 00539 * 00540 * ida_mem = pointer to IDA memory returned by IDACreate. 00541 * 00542 * nrtfn = number of functions g_i, an int >= 0. 00543 * 00544 * g = name of user-supplied function, of type IDARootFn, 00545 * defining the functions g_i whose roots are sought. 00546 * 00547 * g_data = a pointer to user data that will be passed to the 00548 * user's g function every time g is called. 00549 * 00550 * If a new problem is to be solved with a call to IDAReInit, 00551 * where the new problem has no root functions but the prior one 00552 * did, then call IDARootInit with nrtfn = 0. 00553 * 00554 * The return value of IDARootInit is IDA_SUCCESS = 0 if there were 00555 * no errors; otherwise it is a negative int equal to: 00556 * IDA_MEM_NULL indicating ida_mem was NULL, or 00557 * IDA_MEM_FAIL indicating a memory allocation failed. 00558 * (including an attempt to increase maxord). 00559 * IDA_ILL_INPUT indicating nrtfn > 0 but g = NULL. 00560 * In case of an error return, an error message is also printed. 00561 * ----------------------------------------------------------------- 00562 */ 00563 00564 SUNDIALS_EXPORT int IDARootInit(void *ida_mem, int nrtfn, IDARootFn g, void *g_data); 00565 00566 /* 00567 * ---------------------------------------------------------------- 00568 * Function : IDACalcIC 00569 * ---------------------------------------------------------------- 00570 * IDACalcIC calculates corrected initial conditions for the DAE 00571 * system for a class of index-one problems of semi-implicit form. 00572 * It uses Newton iteration combined with a Linesearch algorithm. 00573 * Calling IDACalcIC is optional. It is only necessary when the 00574 * initial conditions do not solve the given system. I.e., if 00575 * y0 and yp0 are known to satisfy F(t0, y0, yp0) = 0, then 00576 * a call to IDACalcIC is NOT necessary (for index-one problems). 00577 * 00578 * A call to IDACalcIC must be preceded by a successful call to 00579 * IDAMalloc or IDAReInit for the given DAE problem, and by a 00580 * successful call to the linear system solver specification 00581 * routine. 00582 * 00583 * The call to IDACalcIC should precede the call(s) to IDASolve 00584 * for the given problem. 00585 * 00586 * The arguments to IDACalcIC are as follows: 00587 * 00588 * ida_mem is the pointer to IDA memory returned by IDACreate. 00589 * 00590 * icopt is the option of IDACalcIC to be used. 00591 * icopt = IDA_YA_YDP_INIT directs IDACalcIC to compute 00592 * the algebraic components of y and differential 00593 * components of y', given the differential 00594 * components of y. This option requires that the 00595 * N_Vector id was set through a call to IDASetId 00596 * specifying the differential and algebraic 00597 * components. 00598 * icopt = IDA_Y_INIT directs IDACalcIC to compute all 00599 * components of y, given y'. id is not required. 00600 * 00601 * tout1 is the first value of t at which a soluton will be 00602 * requested (from IDASolve). (This is needed here to 00603 * determine the direction of integration and rough scale 00604 * in the independent variable t.) 00605 * 00606 * 00607 * IDACalcIC returns an int flag. Its symbolic values and their 00608 * meanings are as follows. (The numerical return values are set 00609 * above in this file.) All unsuccessful returns give a negative 00610 * return value. If IFACalcIC failed, y0 and yp0 contain 00611 * (possibly) altered values, computed during the attempt. 00612 * 00613 * IDA_SUCCESS IDACalcIC was successful. The corrected 00614 * initial value vectors were stored internally. 00615 * 00616 * IDA_MEM_NULL The argument ida_mem was NULL. 00617 * 00618 * IDA_ILL_INPUT One of the input arguments was illegal. 00619 * See printed message. 00620 * 00621 * IDA_LINIT_FAIL The linear solver's init routine failed. 00622 * 00623 * IDA_BAD_EWT Some component of the error weight vector 00624 * is zero (illegal), either for the input 00625 * value of y0 or a corrected value. 00626 * 00627 * IDA_RES_FAIL The user's residual routine returned 00628 * a non-recoverable error flag. 00629 * 00630 * IDA_FIRST_RES_FAIL The user's residual routine returned 00631 * a recoverable error flag on the first call, 00632 * but IDACalcIC was unable to recover. 00633 * 00634 * IDA_LSETUP_FAIL The linear solver's setup routine had a 00635 * non-recoverable error. 00636 * 00637 * IDA_LSOLVE_FAIL The linear solver's solve routine had a 00638 * non-recoverable error. 00639 * 00640 * IDA_NO_RECOVERY The user's residual routine, or the linear 00641 * solver's setup or solve routine had a 00642 * recoverable error, but IDACalcIC was 00643 * unable to recover. 00644 * 00645 * IDA_CONSTR_FAIL IDACalcIC was unable to find a solution 00646 * satisfying the inequality constraints. 00647 * 00648 * IDA_LINESEARCH_FAIL The Linesearch algorithm failed to find a 00649 * solution with a step larger than steptol 00650 * in weighted RMS norm. 00651 * 00652 * IDA_CONV_FAIL IDACalcIC failed to get convergence of the 00653 * Newton iterations. 00654 * 00655 * ---------------------------------------------------------------- 00656 */ 00657 00658 SUNDIALS_EXPORT int IDACalcIC(void *ida_mem, int icopt, realtype tout1); 00659 00660 /* 00661 * ---------------------------------------------------------------- 00662 * Function : IDASolve 00663 * ---------------------------------------------------------------- 00664 * IDASolve integrates the DAE over an interval in t, the 00665 * independent variable. If itask is IDA_NORMAL, then the solver 00666 * integrates from its current internal t value to a point at or 00667 * beyond tout, then interpolates to t = tout and returns y(tret) 00668 * in the user-allocated vector yret. In general, tret = tout. 00669 * If itask is IDA_ONE_STEP, then the solver takes one internal 00670 * step of the independent variable and returns in yret the value 00671 * of y at the new internal independent variable value. In this 00672 * case, tout is used only during the first call to IDASolve to 00673 * determine the direction of integration and the rough scale of 00674 * the problem. If itask is IDA_NORMAL_TSTOP or IDA_ONE_STEP_TSTOP, 00675 * then IDA returns the solution at tstop if that comes sooner than 00676 * tout or the end of the next internal step, respectively. 00677 * In any case, the independent variable value reached by the solver 00678 * is placed in (*tret). The user is responsible for allocating the 00679 * memory for this value. 00680 * 00681 * ida_mem is the pointer (void) to IDA memory returned by 00682 * IDACreate. 00683 * 00684 * tout is the next independent variable value at which a 00685 * computed solution is desired. 00686 * 00687 * tret is a pointer to a real location. IDASolve sets (*tret) 00688 * to the actual t value reached, corresponding to the 00689 * solution vector yret. In IDA_NORMAL mode, with no 00690 * errors and no roots found, (*tret) = tout. 00691 * 00692 * yret is the computed solution vector. With no errors, 00693 * yret = y(tret). 00694 * 00695 * ypret is the derivative of the computed solution at t = tret. 00696 * 00697 * Note: yret and ypret may be the same N_Vectors as y0 and yp0 00698 * in the call to IDAMalloc or IDAReInit. 00699 * 00700 * itask is IDA_NORMAL, IDA_NORMAL_TSTOP, IDA_ONE_STEP, or 00701 * IDA_ONE_STEP_TSTOP. These modes are described above. 00702 * 00703 * 00704 * The return values for IDASolve are described below. 00705 * (The numerical return values are defined above in this file.) 00706 * All unsuccessful returns give a negative return value. 00707 * 00708 * IDA_SUCCESS 00709 * IDASolve succeeded and no roots were found. 00710 * 00711 * IDA_ROOT_RETURN: IDASolve succeeded, and found one or more roots. 00712 * If nrtfn > 1, call IDAGetRootInfo to see which g_i were found 00713 * to have a root at (*tret). 00714 * 00715 * IDA_TSTOP_RETURN: 00716 * IDASolve returns computed results for the independent variable 00717 * value tstop. That is, tstop was reached. 00718 * 00719 * IDA_MEM_NULL: 00720 * The IDA_mem argument was NULL. 00721 * 00722 * IDA_ILL_INPUT: 00723 * One of the inputs to IDASolve is illegal. This includes the 00724 * situation when a component of the error weight vectors 00725 * becomes < 0 during internal stepping. It also includes the 00726 * situation where a root of one of the root functions was found 00727 * both at t0 and very near t0. The ILL_INPUT flag 00728 * will also be returned if the linear solver function IDA--- 00729 * (called by the user after calling IDACreate) failed to set one 00730 * of the linear solver-related fields in ida_mem or if the linear 00731 * solver's init routine failed. In any case, the user should see 00732 * the printed error message for more details. 00733 * 00734 * IDA_TOO_MUCH_WORK: 00735 * The solver took mxstep internal steps but could not reach tout. 00736 * The default value for mxstep is MXSTEP_DEFAULT = 500. 00737 * 00738 * IDA_TOO_MUCH_ACC: 00739 * The solver could not satisfy the accuracy demanded by the user 00740 * for some internal step. 00741 * 00742 * IDA_ERR_FAIL: 00743 * Error test failures occurred too many times (=MXETF = 10) during 00744 * one internal step. 00745 * 00746 * IDA_CONV_FAIL: 00747 * Convergence test failures occurred too many times (= MXNCF = 10) 00748 * during one internal step. 00749 * 00750 * IDA_LSETUP_FAIL: 00751 * The linear solver's setup routine failed 00752 * in an unrecoverable manner. 00753 * 00754 * IDA_LSOLVE_FAIL: 00755 * The linear solver's solve routine failed 00756 * in an unrecoverable manner. 00757 * 00758 * IDA_CONSTR_FAIL: 00759 * The inequality constraints were violated, 00760 * and the solver was unable to recover. 00761 * 00762 * IDA_REP_RES_ERR: 00763 * The user's residual function repeatedly returned a recoverable 00764 * error flag, but the solver was unable to recover. 00765 * 00766 * IDA_RES_FAIL: 00767 * The user's residual function returned a nonrecoverable error 00768 * flag. 00769 * 00770 * ---------------------------------------------------------------- 00771 */ 00772 00773 SUNDIALS_EXPORT int IDASolve(void *ida_mem, realtype tout, realtype *tret, 00774 N_Vector yret, N_Vector ypret, int itask); 00775 00776 /* 00777 * ---------------------------------------------------------------- 00778 * Function: IDAGetSolution 00779 * ---------------------------------------------------------------- 00780 * 00781 * This routine evaluates y(t) and y'(t) as the value and 00782 * derivative of the interpolating polynomial at the independent 00783 * variable t, and stores the results in the vectors yret and 00784 * ypret. It uses the current independent variable value, tn, 00785 * and the method order last used, kused. This function is 00786 * called by IDASolve with t = tout, t = tn, or t = tstop. 00787 * 00788 * If kused = 0 (no step has been taken), or if t = tn, then the 00789 * order used here is taken to be 1, giving yret = phi[0], 00790 * ypret = phi[1]/psi[0]. 00791 * 00792 * The return values are: 00793 * IDA_SUCCESS: succeess. 00794 * IDA_BAD_T: t is not in the interval [tn-hu,tn]. 00795 * IDA_MEM_NULL: The ida_mem argument was NULL. 00796 * 00797 * ---------------------------------------------------------------- 00798 */ 00799 00800 SUNDIALS_EXPORT int IDAGetSolution(void *ida_mem, realtype t, 00801 N_Vector yret, N_Vector ypret); 00802 00803 /* ---------------------------------------------------------------- 00804 * Integrator optional output extraction functions 00805 * ---------------------------------------------------------------- 00806 * 00807 * The following functions can be called to get optional outputs 00808 * and statistics related to the main integrator. 00809 * ---------------------------------------------------------------- 00810 * 00811 * IDAGetWorkSpace returns the IDA real and integer workspace sizes 00812 * IDAGetNumSteps returns the cumulative number of internal 00813 * steps taken by the solver 00814 * IDAGetNumRhsEvals returns the number of calls to the user's 00815 * res function 00816 * IDAGetNumLinSolvSetups returns the number of calls made to 00817 * the linear solver's setup routine 00818 * IDAGetNumErrTestFails returns the number of local error test 00819 * failures that have occured 00820 * IDAGetNumBacktrackOps returns the number of backtrack 00821 * operations done in the linesearch algorithm in IDACalcIC 00822 * IDAGetConsistentIC returns the consistent initial conditions 00823 * computed by IDACalcIC 00824 * IDAGetLastOrder returns the order used during the last 00825 * internal step 00826 * IDAGetCurentOrder returns the order to be used on the next 00827 * internal step 00828 * IDAGetActualInitStep returns the actual initial step size 00829 * used by IDA 00830 * IDAGetLAstStep returns the step size for the last internal 00831 * step (if from IDASolve), or the last value of the 00832 * artificial step size h (if from IDACalcIC) 00833 * IDAGetCurrentStep returns the step size to be attempted on the 00834 * next internal step 00835 * IDAGetCurrentTime returns the current internal time reached 00836 * by the solver 00837 * IDAGetTolScaleFactor returns a suggested factor by which the 00838 * user's tolerances should be scaled when too much 00839 * accuracy has been requested for some internal step 00840 * IDAGetErrWeights returns the current state error weight vector. 00841 * The user must allocate space for eweight. 00842 * IDAGetEstLocalErrors returns the estimated local errors. The user 00843 * must allocate space for the vector ele. 00844 * IDAGetNumGEvals returns the number of calls to the user's 00845 * g function (for rootfinding) 00846 * IDAGetRootInfo returns the indices for which g_i was found to 00847 * have a root. The user must allocate space for rootsfound. 00848 * For i = 0 ... nrtfn-1, rootsfound[i] = 1 if g_i has a root, 00849 * and rootsfound[i]= 0 if not. 00850 * 00851 * IDAGet* return values: 00852 * IDA_SUCCESS if succesful 00853 * IDA_MEM_NULL if the ida memory was NULL 00854 * IDA_ILL_INPUT if some input is illegal 00855 * 00856 * ---------------------------------------------------------------- 00857 */ 00858 00859 SUNDIALS_EXPORT int IDAGetWorkSpace(void *ida_mem, long int *lenrw, long int *leniw); 00860 SUNDIALS_EXPORT int IDAGetNumSteps(void *ida_mem, long int *nsteps); 00861 SUNDIALS_EXPORT int IDAGetNumResEvals(void *ida_mem, long int *nrevals); 00862 SUNDIALS_EXPORT int IDAGetNumLinSolvSetups(void *ida_mem, long int *nlinsetups); 00863 SUNDIALS_EXPORT int IDAGetNumErrTestFails(void *ida_mem, long int *netfails); 00864 SUNDIALS_EXPORT int IDAGetNumBacktrackOps(void *ida_mem, long int *nbacktr); 00865 SUNDIALS_EXPORT int IDAGetConsistentIC(void *ida_mem, N_Vector yy0_mod, N_Vector yp0_mod); 00866 SUNDIALS_EXPORT int IDAGetLastOrder(void *ida_mem, int *klast); 00867 SUNDIALS_EXPORT int IDAGetCurrentOrder(void *ida_mem, int *kcur); 00868 SUNDIALS_EXPORT int IDAGetActualInitStep(void *ida_mem, realtype *hinused); 00869 SUNDIALS_EXPORT int IDAGetLastStep(void *ida_mem, realtype *hlast); 00870 SUNDIALS_EXPORT int IDAGetCurrentStep(void *ida_mem, realtype *hcur); 00871 SUNDIALS_EXPORT int IDAGetCurrentTime(void *ida_mem, realtype *tcur); 00872 SUNDIALS_EXPORT int IDAGetTolScaleFactor(void *ida_mem, realtype *tolsfact); 00873 SUNDIALS_EXPORT int IDAGetErrWeights(void *ida_mem, N_Vector eweight); 00874 SUNDIALS_EXPORT int IDAGetEstLocalErrors(void *ida_mem, N_Vector ele); 00875 SUNDIALS_EXPORT int IDAGetNumGEvals(void *ida_mem, long int *ngevals); 00876 SUNDIALS_EXPORT int IDAGetRootInfo(void *ida_mem, int *rootsfound); 00877 00878 /* 00879 * ---------------------------------------------------------------- 00880 * As a convenience, the following function provides the 00881 * optional outputs in a group. 00882 * ---------------------------------------------------------------- 00883 */ 00884 00885 SUNDIALS_EXPORT int IDAGetIntegratorStats(void *ida_mem, long int *nsteps, 00886 long int *nrevals, long int *nlinsetups, 00887 long int *netfails, int *qlast, int *qcur, 00888 realtype *hinused, realtype *hlast, realtype *hcur, 00889 realtype *tcur); 00890 00891 /* 00892 * ---------------------------------------------------------------- 00893 * Nonlinear solver optional output extraction functions 00894 * ---------------------------------------------------------------- 00895 * 00896 * The following functions can be called to get optional outputs 00897 * and statistics related to the nonlinear solver. 00898 * -------------------------------------------------------------- 00899 * 00900 * IDAGetNumNonlinSolvIters returns the number of nonlinear 00901 * solver iterations performed. 00902 * IDAGetNumNonlinSolvConvFails returns the number of nonlinear 00903 * convergence failures. 00904 * 00905 * ---------------------------------------------------------------- 00906 */ 00907 00908 SUNDIALS_EXPORT int IDAGetNumNonlinSolvIters(void *ida_mem, long int *nniters); 00909 SUNDIALS_EXPORT int IDAGetNumNonlinSolvConvFails(void *ida_mem, long int *nncfails); 00910 00911 /* 00912 * ---------------------------------------------------------------- 00913 * As a convenience, the following function provides the 00914 * nonlinear solver optional outputs in a group. 00915 * ---------------------------------------------------------------- 00916 */ 00917 00918 SUNDIALS_EXPORT int IDAGetNonlinSolvStats(void *ida_mem, long int *nniters, 00919 long int *nncfails); 00920 00921 /* 00922 * ----------------------------------------------------------------- 00923 * The following function returns the name of the constant 00924 * associated with an IDA return flag 00925 * ----------------------------------------------------------------- 00926 */ 00927 00928 SUNDIALS_EXPORT char *IDAGetReturnFlagName(int flag); 00929 00930 /* 00931 * ---------------------------------------------------------------- 00932 * Function : IDAFree 00933 * ---------------------------------------------------------------- 00934 * IDAFree frees the problem memory IDA_mem allocated by 00935 * IDAMalloc. Its only argument is the pointer idamem 00936 * returned by IDAMalloc. 00937 * ---------------------------------------------------------------- 00938 */ 00939 00940 SUNDIALS_EXPORT void IDAFree(void **ida_mem); 00941 00942 #ifdef __cplusplus 00943 } 00944 #endif 00945 00946 #endif
1.5.6