00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.4 $ 00004 * $Date: 2006/11/29 00:05:07 $ 00005 * ----------------------------------------------------------------- 00006 * Programmers: Alan Hindmarsh, Radu Serban and Aaron Collier @ LLNL 00007 * ----------------------------------------------------------------- 00008 * Copyright (c) 2002, 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 common header file for the Scaled and Preconditioned 00014 * Iterative Linear Solvers in IDA. 00015 * ----------------------------------------------------------------- 00016 */ 00017 00018 #ifndef _IDASPILS_H 00019 #define _IDASPILS_H 00020 00021 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00022 extern "C" { 00023 #endif 00024 00025 #include <sundials/sundials_iterative.h> 00026 #include <sundials/sundials_nvector.h> 00027 00028 /* 00029 * ----------------------------------------------------------------- 00030 * IDASPILS return values 00031 * ----------------------------------------------------------------- 00032 */ 00033 00034 #define IDASPILS_SUCCESS 0 00035 #define IDASPILS_MEM_NULL -1 00036 #define IDASPILS_LMEM_NULL -2 00037 #define IDASPILS_ILL_INPUT -3 00038 #define IDASPILS_MEM_FAIL -4 00039 00040 /* 00041 * ----------------------------------------------------------------- 00042 * Type : IDASpilsPrecSetupFn 00043 * ----------------------------------------------------------------- 00044 * The optional user-supplied functions PrecSetup and PrecSolve 00045 * together must define the left preconditoner matrix P 00046 * approximating the system Jacobian matrix 00047 * J = dF/dy + c_j*dF/dy' 00048 * (where the DAE system is F(t,y,y') = 0), and solve the linear 00049 * systems P z = r. PrecSetup is to do any necessary setup 00050 * operations, and PrecSolve is to compute the solution of 00051 * P z = r. 00052 * 00053 * The preconditioner setup function PrecSetup is to evaluate and 00054 * preprocess any Jacobian-related data needed by the 00055 * preconditioner solve function PrecSolve. This might include 00056 * forming a crude approximate Jacobian, and performing an LU 00057 * factorization on it. This function will not be called in 00058 * advance of every call to PrecSolve, but instead will be called 00059 * only as often as necessary to achieve convergence within the 00060 * Newton iteration. If the PrecSolve function needs no 00061 * preparation, the PrecSetup function can be NULL. 00062 * 00063 * Each call to the PrecSetup function is preceded by a call to 00064 * the system function res with the same (t,y,y') arguments. 00065 * Thus the PrecSetup function can use any auxiliary data that is 00066 * computed and saved by the res function and made accessible 00067 * to PrecSetup. 00068 * 00069 * A preconditioner setup function PrecSetup must have the 00070 * prototype given below. Its parameters are as follows: 00071 * 00072 * tt is the current value of the independent variable t. 00073 * 00074 * yy is the current value of the dependent variable vector, 00075 * namely the predicted value of y(t). 00076 * 00077 * yp is the current value of the derivative vector y', 00078 * namely the predicted value of y'(t). 00079 * 00080 * rr is the current value of the residual vector F(t,y,y'). 00081 * 00082 * c_j is the scalar in the system Jacobian, proportional to 1/hh. 00083 * 00084 * prec_data is a pointer to user preconditioner data - the same as 00085 * the pdata parameter passed to IDASp*. 00086 * 00087 * tmp1, tmp2, tmp3 are pointers to vectors of type N_Vector 00088 * which can be used by an IDASpilsPrecSetupFn routine 00089 * as temporary storage or work space. 00090 * 00091 * NOTE: If the user's preconditioner needs other quantities, 00092 * they are accessible as follows: hcur (the current stepsize) 00093 * and ewt (the error weight vector) are accessible through 00094 * IDAGetCurrentStep and IDAGetErrWeights, respectively (see 00095 * ida.h). The unit roundoff is available as 00096 * UNIT_ROUNDOFF defined in sundials_types.h 00097 * 00098 * The IDASpilsPrecSetupFn should return 00099 * 0 if successful, 00100 * a positive int if a recoverable error occurred, or 00101 * a negative int if a nonrecoverable error occurred. 00102 * In the case of a recoverable error return, the integrator will 00103 * attempt to recover by reducing the stepsize (which changes cj). 00104 * ----------------------------------------------------------------- 00105 */ 00106 00107 typedef int (*IDASpilsPrecSetupFn)(realtype tt, 00108 N_Vector yy, N_Vector yp, N_Vector rr, 00109 realtype c_j, void *prec_data, 00110 N_Vector tmp1, N_Vector tmp2, 00111 N_Vector tmp3); 00112 00113 /* 00114 * ----------------------------------------------------------------- 00115 * Type : IDASpilsPrecSolveFn 00116 * ----------------------------------------------------------------- 00117 * The optional user-supplied function PrecSolve must compute a 00118 * solution to the linear system P z = r, where P is the left 00119 * preconditioner defined by the user. If no preconditioning 00120 * is desired, pass NULL for PrecSolve to IDASp*. 00121 * 00122 * A preconditioner solve function PrecSolve must have the 00123 * prototype given below. Its parameters are as follows: 00124 * 00125 * tt is the current value of the independent variable t. 00126 * 00127 * yy is the current value of the dependent variable vector y. 00128 * 00129 * yp is the current value of the derivative vector y'. 00130 * 00131 * rr is the current value of the residual vector F(t,y,y'). 00132 * 00133 * rvec is the input right-hand side vector r. 00134 * 00135 * zvec is the computed solution vector z. 00136 * 00137 * c_j is the scalar in the system Jacobian, proportional to 1/hh. 00138 * 00139 * delta is an input tolerance for use by PrecSolve if it uses an 00140 * iterative method in its solution. In that case, the 00141 * the residual vector r - P z of the system should be 00142 * made less than delta in weighted L2 norm, i.e., 00143 * sqrt [ Sum (Res[i]*ewt[i])^2 ] < delta . 00144 * Note: the error weight vector ewt can be obtained 00145 * through a call to the routine IDAGetErrWeights. 00146 * 00147 * prec_data is a pointer to user preconditioner data - the same as 00148 * the pdata parameter passed to IDASp*. 00149 * 00150 * tmp is an N_Vector which can be used by the PrecSolve 00151 * routine as temporary storage or work space. 00152 * 00153 * The IDASpilsPrecSolveFn should return 00154 * 0 if successful, 00155 * a positive int if a recoverable error occurred, or 00156 * a negative int if a nonrecoverable error occurred. 00157 * Following a recoverable error, the integrator will attempt to 00158 * recover by updating the preconditioner and/or reducing the 00159 * stepsize. 00160 * ----------------------------------------------------------------- 00161 */ 00162 00163 typedef int (*IDASpilsPrecSolveFn)(realtype tt, 00164 N_Vector yy, N_Vector yp, N_Vector rr, 00165 N_Vector rvec, N_Vector zvec, 00166 realtype c_j, realtype delta, void *prec_data, 00167 N_Vector tmp); 00168 00169 /* 00170 * ----------------------------------------------------------------- 00171 * Type : IDASpilsJacTimesVecFn 00172 * ----------------------------------------------------------------- 00173 * The user-supplied function jtimes is to generate the product 00174 * J*v for given v, where J is the Jacobian matrix 00175 * J = dF/dy + c_j*dF/dy' 00176 * or an approximation to it, and v is a given vector. 00177 * It should return 0 if successful and a nonzero int otherwise. 00178 * 00179 * A function jtimes must have the prototype given below. Its 00180 * parameters are as follows: 00181 * 00182 * tt is the current value of the independent variable. 00183 * 00184 * yy is the current value of the dependent variable vector, 00185 * namely the predicted value of y(t). 00186 * 00187 * yp is the current value of the derivative vector y', 00188 * namely the predicted value of y'(t). 00189 * 00190 * rr is the current value of the residual vector F(t,y,y'). 00191 * 00192 * v is the N_Vector to be multiplied by J. 00193 * 00194 * Jv is the output N_Vector containing J*v. 00195 * 00196 * c_j is the scalar in the system Jacobian, proportional 00197 * to 1/hh. 00198 * 00199 * jac_data is a pointer to user Jacobian data, the same as the 00200 * pointer passed to IDASp*. 00201 * 00202 * tmp1, tmp2 are two N_Vectors which can be used by Jtimes for 00203 * work space. 00204 * ----------------------------------------------------------------- 00205 */ 00206 00207 typedef int (*IDASpilsJacTimesVecFn)(realtype tt, 00208 N_Vector yy, N_Vector yp, N_Vector rr, 00209 N_Vector v, N_Vector Jv, 00210 realtype c_j, void *jac_data, 00211 N_Vector tmp1, N_Vector tmp2); 00212 00213 00214 /* 00215 * ----------------------------------------------------------------- 00216 * Optional inputs to the IDASPILS linear solver 00217 * ----------------------------------------------------------------- 00218 * 00219 * IDASpilsSetPreconditioner specifies the PrecSetup and PrecSolve 00220 * functions, as well as a pointer to user preconditioner 00221 * data. This pointer is passed to PrecSetup and PrecSolve 00222 * every time these routines are called. 00223 * Default is NULL for al three arguments. 00224 * IDASpilsSetJacTimesVecFn specifies the jtimes function. 00225 * Default is to use an internal finite difference 00226 * approximation routine. It also specifies a pointer 00227 * to user Jacobian data. This pointer is passed to jtimes 00228 * every time the jtimes routine is called. 00229 * IDASpilsSetGSType specifies the type of Gram-Schmidt 00230 * orthogonalization to be used. This must be one of 00231 * the two enumeration constants MODIFIED_GS or 00232 * CLASSICAL_GS defined in iterativ.h. These correspond 00233 * to using modified Gram-Schmidt and classical 00234 * Gram-Schmidt, respectively. 00235 * Default value is MODIFIED_GS. 00236 * Only for IDASPGMR. 00237 * IDASpilsSetMaxRestarts specifies the maximum number of restarts 00238 * to be used in the GMRES algorithm. maxrs must be a 00239 * non-negative integer. Pass 0 to specify no restarts. 00240 * Default is 5. 00241 * Only for IDASPGMR. 00242 * IDASpbcgSetMaxl specifies the maximum Krylov subspace size. 00243 * Default is 5. 00244 * Only for IDASPBCG and IDASPTFQMR. 00245 * IDASpilsSetEpsLin specifies the factor in the linear iteration 00246 * convergence test constant. 00247 * Default is 0.05 00248 * IDASpilsSetIncrementFactor specifies a factor in the increments 00249 * to yy used in the difference quotient approximations 00250 * to matrix-vector products Jv. 00251 * Default is 1.0 00252 * 00253 * The return value of IDASpilsSet* is one of: 00254 * IDASPILS_SUCCESS if successful 00255 * IDASPILS_MEM_NULL if the ida memory was NULL 00256 * IDASPILS_LMEM_NULL if the linear solver memory was NULL 00257 * ----------------------------------------------------------------- 00258 */ 00259 00260 SUNDIALS_EXPORT int IDASpilsSetPreconditioner(void *ida_mem, IDASpilsPrecSetupFn pset, 00261 IDASpilsPrecSolveFn psolve, void *prec_data); 00262 SUNDIALS_EXPORT int IDASpilsSetJacTimesVecFn(void *ida_mem, IDASpilsJacTimesVecFn jtimes, 00263 void *jac_data); 00264 SUNDIALS_EXPORT int IDASpilsSetGSType(void *ida_mem, int gstype); 00265 SUNDIALS_EXPORT int IDASpilsSetMaxRestarts(void *ida_mem, int maxrs); 00266 SUNDIALS_EXPORT int IDASpilsSetMaxl(void *ida_mem, int maxl); 00267 SUNDIALS_EXPORT int IDASpilsSetEpsLin(void *ida_mem, realtype eplifac); 00268 SUNDIALS_EXPORT int IDASpilsSetIncrementFactor(void *ida_mem, realtype dqincfac); 00269 00270 /* 00271 * ----------------------------------------------------------------- 00272 * Optional outputs from the IDASPILS linear solver 00273 *---------------------------------------------------------------- 00274 * 00275 * IDASpilsGetWorkSpace returns the real and integer workspace used 00276 * by IDASPILS. 00277 * IDASpilsGetNumPrecEvals returns the number of preconditioner 00278 * evaluations, i.e. the number of calls made to PrecSetup 00279 * with jok==FALSE. 00280 * IDASpilsGetNumPrecSolves returns the number of calls made to 00281 * PrecSolve. 00282 * IDASpilsGetNumLinIters returns the number of linear iterations. 00283 * IDASpilsGetNumConvFails returns the number of linear 00284 * convergence failures. 00285 * IDASpilsGetNumJtimesEvals returns the number of calls to jtimes 00286 * IDASpilsGetNumResEvals returns the number of calls to the user 00287 * res routine due to finite difference Jacobian times vector 00288 * evaluation. 00289 * IDASpilsGetLastFlag returns the last error flag set by any of 00290 * the IDASPILS interface functions. 00291 * 00292 * The return value of IDASpilsGet* is one of: 00293 * IDASPILS_SUCCESS if successful 00294 * IDASPILS_MEM_NULL if the ida memory was NULL 00295 * IDASPILS_LMEM_NULL if the linear solver memory was NULL 00296 * ----------------------------------------------------------------- 00297 */ 00298 00299 SUNDIALS_EXPORT int IDASpilsGetWorkSpace(void *ida_mem, long int *lenrwLS, long int *leniwLS); 00300 SUNDIALS_EXPORT int IDASpilsGetNumPrecEvals(void *ida_mem, long int *npevals); 00301 SUNDIALS_EXPORT int IDASpilsGetNumPrecSolves(void *ida_mem, long int *npsolves); 00302 SUNDIALS_EXPORT int IDASpilsGetNumLinIters(void *ida_mem, long int *nliters); 00303 SUNDIALS_EXPORT int IDASpilsGetNumConvFails(void *ida_mem, long int *nlcfails); 00304 SUNDIALS_EXPORT int IDASpilsGetNumJtimesEvals(void *ida_mem, long int *njvevals); 00305 SUNDIALS_EXPORT int IDASpilsGetNumResEvals(void *ida_mem, long int *nrevalsLS); 00306 SUNDIALS_EXPORT int IDASpilsGetLastFlag(void *ida_mem, int *flag); 00307 00308 /* 00309 * ----------------------------------------------------------------- 00310 * The following function returns the name of the constant 00311 * associated with an IDASPILS return flag 00312 * ----------------------------------------------------------------- 00313 */ 00314 00315 SUNDIALS_EXPORT char *IDASpilsGetReturnFlagName(int flag); 00316 00317 00318 #ifdef __cplusplus 00319 } 00320 #endif 00321 00322 #endif
1.6.1