00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.2 $ 00004 * $Date: 2006/11/29 00:05:07 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer(s): Scott Cohen, Alan Hindmarsh, Radu Serban, and 00007 * Aaron Collier @ LLNL 00008 * ----------------------------------------------------------------- 00009 * Copyright (c) 2002, The Regents of the University of California. 00010 * Produced at the Lawrence Livermore National Laboratory. 00011 * All rights reserved. 00012 * For details, see the LICENSE file. 00013 * ----------------------------------------------------------------- 00014 * This is the common header file for the Scaled Preconditioned 00015 * Iterative Linear Solvers in KINSOL. 00016 * ----------------------------------------------------------------- 00017 */ 00018 00019 #ifndef _KINSPILS_H 00020 #define _KINSPILS_H 00021 00022 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00023 extern "C" { 00024 #endif 00025 00026 #include <sundials/sundials_iterative.h> 00027 #include <sundials/sundials_nvector.h> 00028 00029 00030 /* 00031 * ----------------------------------------------------------------- 00032 * KINSPILS return values 00033 * ----------------------------------------------------------------- 00034 */ 00035 00036 #define KINSPILS_SUCCESS 0 00037 00038 #define KINSPILS_MEM_NULL -1 00039 #define KINSPILS_LMEM_NULL -2 00040 #define KINSPILS_ILL_INPUT -3 00041 #define KINSPILS_MEM_FAIL -4 00042 00043 /* 00044 * ----------------------------------------------------------------- 00045 * KINSPILS solver constant 00046 * ----------------------------------------------------------------- 00047 * KINSPILS_MAXL : maximum dimension of Krylov subspace allowed by 00048 * default 00049 * ----------------------------------------------------------------- 00050 */ 00051 00052 #define KINSPILS_MAXL 10 00053 00054 /* 00055 * ----------------------------------------------------------------- 00056 * Type : KINSpilsPrecSetupFn 00057 * ----------------------------------------------------------------- 00058 * The user-supplied preconditioner setup subroutine should 00059 * compute the right-preconditioner matrix P (stored in memory 00060 * block referenced by P_data pointer) used to form the 00061 * scaled preconditioned linear system: 00062 * 00063 * (Df*J(uu)*(P^-1)*(Du^-1)) * (Du*P*x) = Df*(-F(uu)) 00064 * 00065 * where Du and Df denote the diagonal scaling matrices whose 00066 * diagonal elements are stored in the vectors uscale and 00067 * fscale, repsectively. 00068 * 00069 * The preconditioner setup routine (referenced by iterative linear 00070 * solver modules via pset (type KINSpilsPrecSetupFn)) will not be 00071 * called prior to every call made to the psolve function, but will 00072 * instead be called only as often as necessary to achieve convergence 00073 * of the Newton iteration. 00074 * 00075 * Note: If the psolve routine requires no preparation, then a 00076 * preconditioner setup function need not be given. 00077 * 00078 * uu current iterate (unscaled) [input] 00079 * 00080 * uscale vector (type N_Vector) containing diagonal elements 00081 * of scaling matrix for vector uu [input] 00082 * 00083 * fval vector (type N_Vector) containing result of nonliear 00084 * system function evaluated at current iterate: 00085 * fval = F(uu) [input] 00086 * 00087 * fscale vector (type N_Vector) containing diagonal elements 00088 * of scaling matrix for fval [input] 00089 * 00090 * P_data pointer to user-allocated system memory block used 00091 * for storage of preconditioner matrix-related data 00092 * [output] 00093 * 00094 * vtemp1/vtemp2 available scratch vectors (temporary storage) 00095 * 00096 * If successful, the function should return 0 (zero). If an error 00097 * occurs, then the routine should return a non-zero integer value. 00098 * ----------------------------------------------------------------- 00099 */ 00100 00101 typedef int (*KINSpilsPrecSetupFn)(N_Vector uu, N_Vector uscale, 00102 N_Vector fval, N_Vector fscale, 00103 void *P_data, N_Vector vtemp1, 00104 N_Vector vtemp2); 00105 00106 /* 00107 * ----------------------------------------------------------------- 00108 * Type : KINSpilsPrecSolveFn 00109 * ----------------------------------------------------------------- 00110 * The user-supplied preconditioner solve subroutine (referenced 00111 * by iterative linear solver modules via psolve (type 00112 * KINSpilsPrecSolveFn)) should solve a (scaled) preconditioned 00113 * linear system of the generic form P*z = r, where P denotes the 00114 * right-preconditioner matrix computed by the pset routine. 00115 * 00116 * uu current iterate (unscaled) [input] 00117 * 00118 * uscale vector (type N_Vector) containing diagonal elements 00119 * of scaling matrix for vector uu [input] 00120 * 00121 * fval vector (type N_Vector) containing result of nonliear 00122 * system function evaluated at current iterate: 00123 * fval = F(uu) [input] 00124 * 00125 * fscale vector (type N_Vector) containing diagonal elements 00126 * of scaling matrix for fval [input] 00127 * 00128 * vv vector initially set to the right-hand side vector r, but 00129 * which upon return contains a solution of the linear system 00130 * P*z = r [input/output] 00131 * 00132 * P_data pointer to user-allocated system memory block used 00133 * for storage of preconditioner matrix-related data 00134 * [output] 00135 * 00136 * vtemp available scratch vector (volatile storage) 00137 * 00138 * If successful, the function should return 0 (zero). If a 00139 * recoverable error occurs, then the subroutine should return 00140 * a positive integer value (in this case, KINSOL attempts to 00141 * correct by calling the preconditioner setup function if the 00142 * preconditioner information is out of date). If an unrecoverable 00143 * error occurs, then the preconditioner solve function should return 00144 * a negative integer value. 00145 * ----------------------------------------------------------------- 00146 */ 00147 00148 typedef int (*KINSpilsPrecSolveFn)(N_Vector uu, N_Vector uscale, 00149 N_Vector fval, N_Vector fscale, 00150 N_Vector vv, void *P_data, 00151 N_Vector vtemp); 00152 00153 /* 00154 * ----------------------------------------------------------------- 00155 * Type : KINSpilsJacTimesVecFn 00156 * ----------------------------------------------------------------- 00157 * The (optional) user-supplied matrix-vector product subroutine 00158 * (referenced internally via jtimes (type KINSpilsJacTimesVecFn)) 00159 * is used to compute Jv = J(uu)*v (system Jacobian applied to a 00160 * given vector). If a user-defined routine is not given, then the 00161 * private routine is used. 00162 * 00163 * v unscaled variant of vector to be multiplied by J(uu) [input] 00164 * 00165 * Jv vector containing result of matrix-vector product J(uu)*v 00166 * [output] 00167 * 00168 * uu current iterate (unscaled) [input] 00169 * 00170 * new_uu flag (reset by user) indicating if the iterate uu 00171 * has been updated in the interim - Jacobian needs 00172 * to be updated/reevaluated, if appropriate, unless 00173 * new_uu = FALSE [input/output] 00174 * 00175 * J_data pointer to user-allocated memory block where J(uu) data 00176 * is to be stored [input] 00177 * 00178 * If successful, the function should return 0 (zero). If an error 00179 * occurs, then the routine should return a non-zero integer value. 00180 * ----------------------------------------------------------------- 00181 */ 00182 00183 typedef int (*KINSpilsJacTimesVecFn)(N_Vector v, N_Vector Jv, 00184 N_Vector uu, booleantype *new_uu, 00185 void *J_data); 00186 00187 00188 00189 00190 00191 /* 00192 * ----------------------------------------------------------------- 00193 * Optional Input Specification Functions 00194 * ----------------------------------------------------------------- 00195 * The following functions can be called to set optional inputs: 00196 * 00197 * Function Name | Optional Input [Default Value] 00198 * | 00199 * ----------------------------------------------------------------- 00200 * | 00201 * KINSpilsSetMaxRestarts | maximum number of times the SPGMR 00202 * | (scaled preconditioned GMRES) linear 00203 * | solver can be restarted 00204 * | [0] 00205 * | 00206 * KINSpilsSetPreconditioner | used to set the following: 00207 * | (a) name of user-supplied routine 00208 * | used to compute a preconditioner 00209 * | matrix for the given linear 00210 * | system (pset) 00211 * | [NULL] 00212 * | (b) name of user-supplied routine 00213 * | used to apply preconditioner to 00214 * | linear system (psolve) 00215 * | [NULL] 00216 * | (c) pointer to user-allocated system 00217 * | memory that is passed to the pset 00218 * | and psolve routines 00219 * | [NULL] 00220 * | 00221 * KINSpilsSetJacTimesVecFn | used to set the following: 00222 * | (a) name of user-supplied subroutine 00223 * | used to compute the matrix-vector 00224 * | product J(u)*v, where J denotes 00225 * | the system Jacobian (jtimes) 00226 * | [KINSpilsDQJtimes] (see kinsol_spils.c) 00227 * | (b) pointer to a user-allocated memory 00228 * | block that is passed to the jtimes 00229 * | routine 00230 * | [NULL] 00231 * ----------------------------------------------------------------- 00232 */ 00233 00234 SUNDIALS_EXPORT int KINSpilsSetMaxRestarts(void *kinmem, int maxrs); 00235 SUNDIALS_EXPORT int KINSpilsSetPreconditioner(void *kinmem, 00236 KINSpilsPrecSetupFn pset, 00237 KINSpilsPrecSolveFn psolve, 00238 void *P_data); 00239 SUNDIALS_EXPORT int KINSpilsSetJacTimesVecFn(void *kinmem, 00240 KINSpilsJacTimesVecFn jtimes, 00241 void *J_data); 00242 00243 /* 00244 * ----------------------------------------------------------------- 00245 * KINSpilsSet* Return Values 00246 * ----------------------------------------------------------------- 00247 * The possible return values for the KINSpilsSet* subroutines 00248 * are the following: 00249 * 00250 * KINSPILS_SUCCESS : means the associated parameter was successfully 00251 * set [0] 00252 * 00253 * KINSPILS_ILL_INPUT : means the supplied parameter was invalid 00254 * (check error message) [-3] 00255 * 00256 * KINSPILS_MEM_NULL : means a NULL KINSOL memory block pointer 00257 * was given [-1] 00258 * 00259 * KINSPILS_LMEM_NULL : means system memory has not yet been 00260 * allocated for the linear solver 00261 * (lmem == NULL) [-2] 00262 * ----------------------------------------------------------------- 00263 */ 00264 00265 /* 00266 * ----------------------------------------------------------------- 00267 * Optional Output Extraction Functions 00268 * ----------------------------------------------------------------- 00269 * The following functions can be called to get optional outputs 00270 * and statistical information related to the KINSPILS linear 00271 * solvers: 00272 * 00273 * Function Name | Returned Value 00274 * | 00275 * ----------------------------------------------------------------- 00276 * | 00277 * KINSpilsGetWorkSpace | returns both integer workspace size 00278 * | (total number of long int-sized blocks 00279 * | of memory allocated for 00280 * | vector storage), and real workspace 00281 * | size (total number of realtype-sized 00282 * | blocks of memory allocated 00283 * | for vector storage) 00284 * | 00285 * KINSpilsGetNumPrecEvals | total number of preconditioner 00286 * | evaluations (number of calls made 00287 * | to the user-defined pset routine) 00288 * | 00289 * KINSpilsGetNumPrecSolves | total number of times preconditioner 00290 * | was applied to linear system (number 00291 * | of calls made to the user-supplied 00292 * | psolve function) 00293 * | 00294 * KINSpilsGetNumLinIters | total number of linear iterations 00295 * | performed 00296 * | 00297 * KINSpilsGetNumConvFails | total number of linear convergence 00298 * | failures 00299 * | 00300 * KINSpilsGetNumJtimesEvals | total number of times the matrix- 00301 * | vector product J(u)*v was computed 00302 * | (number of calls made to the jtimes 00303 * | subroutine) 00304 * | 00305 * KINSpilsGetNumFuncEvals | total number of evaluations of the 00306 * | system function F(u) (number of 00307 * | calls made to the user-supplied 00308 * | func routine by the linear solver 00309 * | module member subroutines) 00310 * | 00311 * KINSpilsGetLastFlag | returns the last flag returned by 00312 * | the linear solver 00313 * | 00314 * KINSpilsGetReturnFlagName | returns the name of the constant 00315 * | associated with a KINSPILS return flag 00316 * ----------------------------------------------------------------- 00317 */ 00318 00319 SUNDIALS_EXPORT int KINSpilsGetWorkSpace(void *kinmem, long int *lenrwSG, long int *leniwSG); 00320 SUNDIALS_EXPORT int KINSpilsGetNumPrecEvals(void *kinmem, long int *npevals); 00321 SUNDIALS_EXPORT int KINSpilsGetNumPrecSolves(void *kinmem, long int *npsolves); 00322 SUNDIALS_EXPORT int KINSpilsGetNumLinIters(void *kinmem, long int *nliters); 00323 SUNDIALS_EXPORT int KINSpilsGetNumConvFails(void *kinmem, long int *nlcfails); 00324 SUNDIALS_EXPORT int KINSpilsGetNumJtimesEvals(void *kinmem, long int *njvevals); 00325 SUNDIALS_EXPORT int KINSpilsGetNumFuncEvals(void *kinmem, long int *nfevalsS); 00326 SUNDIALS_EXPORT int KINSpilsGetLastFlag(void *kinmem, int *flag); 00327 SUNDIALS_EXPORT char *KINSpilsGetReturnFlagName(int flag); 00328 00329 /* 00330 * ----------------------------------------------------------------- 00331 * KINSpilsGet* Return Values 00332 * ----------------------------------------------------------------- 00333 * The possible return values for the KINSpilsGet* subroutines 00334 * are the following: 00335 * 00336 * KINSPILS_SUCCESS : means the routine exited normally [0] 00337 * 00338 * KINSPILS_ILL_INPUT : means at least one input parameter was 00339 * invalid (check error message(s)) [-3] 00340 * 00341 * KINSPILS_MEM_NULL : means a NULL KINSOL memory block pointer was 00342 * given [-1] 00343 * 00344 * KINSPILS_LMEM_NULL : means a NULL linear solver memory block pointer 00345 * was given [-2] 00346 * ----------------------------------------------------------------- 00347 */ 00348 00349 00350 00351 #ifdef __cplusplus 00352 } 00353 #endif 00354 00355 #endif
1.5.6