00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.3 $ 00004 * $Date: 2006/11/29 00:05:06 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer(s): Michael Wittman, Alan C. Hindmarsh and 00007 * Radu Serban @ 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 file for the CVBBDPRE module, for a 00015 * band-block-diagonal preconditioner, i.e. a block-diagonal 00016 * matrix with banded blocks, for use with CVSPGMR/CVSPBCG/CVSPTFQMR, 00017 * and the parallel implementation of the NVECTOR module. 00018 * 00019 * Summary: 00020 * 00021 * These routines provide a preconditioner matrix that is 00022 * block-diagonal with banded blocks. The blocking corresponds 00023 * to the distribution of the dependent variable vector y among 00024 * the processors. Each preconditioner block is generated from 00025 * the Jacobian of the local part (on the current processor) of a 00026 * given function g(t,y) approximating f(t,y). The blocks are 00027 * generated by a difference quotient scheme on each processor 00028 * independently. This scheme utilizes an assumed banded 00029 * structure with given half-bandwidths, mudq and mldq. 00030 * However, the banded Jacobian block kept by the scheme has 00031 * half-bandwiths mukeep and mlkeep, which may be smaller. 00032 * 00033 * The user's calling program should have the following form: 00034 * 00035 * #include <nvector_parallel.h> 00036 * #include <cvode/cvode_bbdpre.h> 00037 * ... 00038 * void *cvode_mem; 00039 * void *bbd_data; 00040 * ... 00041 * Set y0 00042 * ... 00043 * cvode_mem = CVodeCreate(...); 00044 * ier = CVodeMalloc(...); 00045 * ... 00046 * bbd_data = CVBBDPrecAlloc(cvode_mem, Nlocal, mudq ,mldq, 00047 * mukeep, mlkeep, dqrely, gloc, cfn); 00048 * flag = CVBBDSpgmr(cvode_mem, pretype, maxl, bbd_data); 00049 * -or- 00050 * flag = CVBBDSpbcg(cvode_mem, pretype, maxl, bbd_data); 00051 * -or- 00052 * flag = CVBBDSptfqmr(cvode_mem, pretype, maxl, bbd_data); 00053 * ... 00054 * ier = CVode(...); 00055 * ... 00056 * CVBBDPrecFree(&bbd_data); 00057 * ... 00058 * CVodeFree(...); 00059 * 00060 * Free y0 00061 * 00062 * The user-supplied routines required are: 00063 * 00064 * f = function defining the ODE right-hand side f(t,y). 00065 * 00066 * gloc = function defining the approximation g(t,y). 00067 * 00068 * cfn = function to perform communication need for gloc. 00069 * 00070 * Notes: 00071 * 00072 * 1) This header file is included by the user for the definition 00073 * of the CVBBDData type and for needed function prototypes. 00074 * 00075 * 2) The CVBBDPrecAlloc call includes half-bandwiths mudq and mldq 00076 * to be used in the difference quotient calculation of the 00077 * approximate Jacobian. They need not be the true 00078 * half-bandwidths of the Jacobian of the local block of g, 00079 * when smaller values may provide a greater efficiency. 00080 * Also, the half-bandwidths mukeep and mlkeep of the retained 00081 * banded approximate Jacobian block may be even smaller, 00082 * to reduce storage and computation costs further. 00083 * For all four half-bandwidths, the values need not be the 00084 * same on every processor. 00085 * 00086 * 3) The actual name of the user's f function is passed to 00087 * CVodeMalloc, and the names of the user's gloc and cfn 00088 * functions are passed to CVBBDPrecAlloc. 00089 * 00090 * 4) The pointer to the user-defined data block f_data, which is 00091 * set through CVodeSetFdata is also available to the user in 00092 * gloc and cfn. 00093 * 00094 * 5) For the CVSpgmr solver, the Gram-Schmidt type gstype, 00095 * is left to the user to specify through CVSpgmrSetGStype. 00096 * 00097 * 6) Optional outputs specific to this module are available by 00098 * way of routines listed below. These include work space sizes 00099 * and the cumulative number of gloc calls. The costs 00100 * associated with this module also include nsetups banded LU 00101 * factorizations, nlinsetups cfn calls, and npsolves banded 00102 * backsolve calls, where nlinsetups and npsolves are 00103 * integrator/CVSPGMR/CVSPBCG/CVSPTFQMR optional outputs. 00104 * ----------------------------------------------------------------- 00105 */ 00106 00107 #ifndef _CVBBDPRE_H 00108 #define _CVBBDPRE_H 00109 00110 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00111 extern "C" { 00112 #endif 00113 00114 #include <sundials/sundials_nvector.h> 00115 00116 /* CVBBDPRE return values */ 00117 00118 #define CVBBDPRE_SUCCESS 0 00119 #define CVBBDPRE_PDATA_NULL -11 00120 #define CVBBDPRE_FUNC_UNRECVR -12 00121 00122 /* 00123 * ----------------------------------------------------------------- 00124 * Type : CVLocalFn 00125 * ----------------------------------------------------------------- 00126 * The user must supply a function g(t,y) which approximates the 00127 * right-hand side function f for the system y'=f(t,y), and which 00128 * is computed locally (without interprocess communication). 00129 * (The case where g is mathematically identical to f is allowed.) 00130 * The implementation of this function must have type CVLocalFn. 00131 * 00132 * This function takes as input the local vector size Nlocal, the 00133 * independent variable value t, the local real dependent 00134 * variable vector y, and a pointer to the user-defined data 00135 * block f_data. It is to compute the local part of g(t,y) and 00136 * store this in the vector g. 00137 * (Allocation of memory for y and g is handled within the 00138 * preconditioner module.) 00139 * The f_data parameter is the same as that specified by the user 00140 * through the CVodeSetFdata routine. 00141 * 00142 * A CVLocalFn should return 0 if successful, a positive value if 00143 * a recoverable error occurred, and a negative value if an 00144 * unrecoverable error occurred. 00145 * ----------------------------------------------------------------- 00146 */ 00147 00148 typedef int (*CVLocalFn)(int Nlocal, realtype t, N_Vector y, 00149 N_Vector g, void *f_data); 00150 00151 /* 00152 * ----------------------------------------------------------------- 00153 * Type : CVCommFn 00154 * ----------------------------------------------------------------- 00155 * The user may supply a function of type CVCommFn which performs 00156 * all interprocess communication necessary to evaluate the 00157 * approximate right-hand side function described above. 00158 * 00159 * This function takes as input the local vector size Nlocal, 00160 * the independent variable value t, the dependent variable 00161 * vector y, and a pointer to the user-defined data block f_data. 00162 * The f_data parameter is the same as that specified by the user 00163 * through the CVodeSetFdata routine. The CVCommFn cfn is 00164 * expected to save communicated data in space defined within the 00165 * structure f_data. Note: A CVCommFn cfn does not have a return value. 00166 * 00167 * Each call to the CVCommFn cfn is preceded by a call to the 00168 * CVRhsFn f with the same (t,y) arguments. Thus cfn can omit any 00169 * communications done by f if relevant to the evaluation of g. 00170 * If all necessary communication was done by f, the user can 00171 * pass NULL for cfn in CVBBDPrecAlloc (see below). 00172 * 00173 * A CVCommFn should return 0 if successful, a positive value if 00174 * a recoverable error occurred, and a negative value if an 00175 * unrecoverable error occurred. 00176 * ----------------------------------------------------------------- 00177 */ 00178 00179 typedef int (*CVCommFn)(int Nlocal, realtype t, N_Vector y, 00180 void *f_data); 00181 00182 /* 00183 * ----------------------------------------------------------------- 00184 * Function : CVBBDPrecAlloc 00185 * ----------------------------------------------------------------- 00186 * CVBBDPrecAlloc allocates and initializes a CVBBDData structure 00187 * to be passed to CVSp* (and used by CVBBDPrecSetup and 00188 * CVBBDPrecSolve). 00189 * 00190 * The parameters of CVBBDPrecAlloc are as follows: 00191 * 00192 * cvode_mem is the pointer to the integrator memory. 00193 * 00194 * Nlocal is the length of the local block of the vectors y etc. 00195 * on the current processor. 00196 * 00197 * mudq, mldq are the upper and lower half-bandwidths to be used 00198 * in the difference quotient computation of the local 00199 * Jacobian block. 00200 * 00201 * mukeep, mlkeep are the upper and lower half-bandwidths of the 00202 * retained banded approximation to the local Jacobian 00203 * block. 00204 * 00205 * dqrely is an optional input. It is the relative increment 00206 * in components of y used in the difference quotient 00207 * approximations. To specify the default, pass 0. 00208 * The default is dqrely = sqrt(unit roundoff). 00209 * 00210 * gloc is the name of the user-supplied function g(t,y) that 00211 * approximates f and whose local Jacobian blocks are 00212 * to form the preconditioner. 00213 * 00214 * cfn is the name of the user-defined function that performs 00215 * necessary interprocess communication for the 00216 * execution of gloc. 00217 * 00218 * CVBBDPrecAlloc returns the storage allocated (type *void), 00219 * or NULL if the request for storage cannot be satisfied. 00220 * ----------------------------------------------------------------- 00221 */ 00222 00223 SUNDIALS_EXPORT void *CVBBDPrecAlloc(void *cvode_mem, int Nlocal, 00224 int mudq, int mldq, 00225 int mukeep, int mlkeep, 00226 realtype dqrely, 00227 CVLocalFn gloc, CVCommFn cfn); 00228 00229 /* 00230 * ----------------------------------------------------------------- 00231 * Function : CVBBDSptfqmr 00232 * ----------------------------------------------------------------- 00233 * CVBBDSptfqmr links the CVBBDPRE preconditioner to the CVSPTFQMR 00234 * linear solver. It performs the following actions: 00235 * 1) Calls the CVSPTFQMR specification routine and attaches the 00236 * CVSPTFQMR linear solver to the integrator memory; 00237 * 2) Sets the preconditioner data structure for CVSPTFQMR 00238 * 3) Sets the preconditioner setup routine for CVSPTFQMR 00239 * 4) Sets the preconditioner solve routine for CVSPTFQMR 00240 * 00241 * Its first 3 arguments are the same as for CVSptfqmr (see 00242 * cvsptfqmr.h). The last argument is the pointer to the CVBBDPRE 00243 * memory block returned by CVBBDPrecAlloc. Note that the user need 00244 * not call CVSptfqmr. 00245 * 00246 * Possible return values are: 00247 * CVSPILS_SUCCESS if successful 00248 * CVSPILS_MEM_NULL if the cvode memory was NULL 00249 * CVSPILS_LMEM_NULL if the cvsptfqmr memory was NULL 00250 * CVSPILS_MEM_FAIL if there was a memory allocation failure 00251 * CVSPILS_ILL_INPUT if a required vector operation is missing 00252 * CVBBDPRE_PDATA_NULL if the bbd_data was NULL 00253 * ----------------------------------------------------------------- 00254 */ 00255 00256 SUNDIALS_EXPORT int CVBBDSptfqmr(void *cvode_mem, int pretype, int maxl, void *bbd_data); 00257 00258 /* 00259 * ----------------------------------------------------------------- 00260 * Function : CVBBDSpbcg 00261 * ----------------------------------------------------------------- 00262 * CVBBDSpbcg links the CVBBDPRE preconditioner to the CVSPBCG 00263 * linear solver. It performs the following actions: 00264 * 1) Calls the CVSPBCG specification routine and attaches the 00265 * CVSPBCG linear solver to the integrator memory; 00266 * 2) Sets the preconditioner data structure for CVSPBCG 00267 * 3) Sets the preconditioner setup routine for CVSPBCG 00268 * 4) Sets the preconditioner solve routine for CVSPBCG 00269 * 00270 * Its first 3 arguments are the same as for CVSpbcg (see 00271 * cvspbcg.h). The last argument is the pointer to the CVBBDPRE 00272 * memory block returned by CVBBDPrecAlloc. Note that the user need 00273 * not call CVSpbcg. 00274 * 00275 * Possible return values are: 00276 * CVSPILS_SUCCESS if successful 00277 * CVSPILS_MEM_NULL if the cvode memory was NULL 00278 * CVSPILS_LMEM_NULL if the cvspbcg memory was NULL 00279 * CVSPILS_MEM_FAIL if there was a memory allocation failure 00280 * CVSPILS_ILL_INPUT if a required vector operation is missing 00281 * CVBBDPRE_PDATA_NULL if the bbd_data was NULL 00282 * ----------------------------------------------------------------- 00283 */ 00284 00285 SUNDIALS_EXPORT int CVBBDSpbcg(void *cvode_mem, int pretype, int maxl, void *bbd_data); 00286 00287 /* 00288 * ----------------------------------------------------------------- 00289 * Function : CVBBDSpgmr 00290 * ----------------------------------------------------------------- 00291 * CVBBDSpgmr links the CVBBDPRE preconditioner to the CVSPGMR 00292 * linear solver. It performs the following actions: 00293 * 1) Calls the CVSPGMR specification routine and attaches the 00294 * CVSPGMR linear solver to the integrator memory; 00295 * 2) Sets the preconditioner data structure for CVSPGMR 00296 * 3) Sets the preconditioner setup routine for CVSPGMR 00297 * 4) Sets the preconditioner solve routine for CVSPGMR 00298 * 00299 * Its first 3 arguments are the same as for CVSpgmr (see 00300 * cvspgmr.h). The last argument is the pointer to the CVBBDPRE 00301 * memory block returned by CVBBDPrecAlloc. Note that the user need 00302 * not call CVSpgmr. 00303 * 00304 * Possible return values are: 00305 * CVSPILS_SUCCESS if successful 00306 * CVSPILS_MEM_NULL if the cvode memory was NULL 00307 * CVSPILS_LMEM_NULL if the cvspgmr memory was NULL 00308 * CVSPILS_MEM_FAIL if there was a memory allocation failure 00309 * CVSPILS_ILL_INPUT if a required vector operation is missing 00310 * CVBBDPRE_PDATA_NULL if the bbd_data was NULL 00311 * ----------------------------------------------------------------- 00312 */ 00313 00314 SUNDIALS_EXPORT int CVBBDSpgmr(void *cvode_mem, int pretype, int maxl, void *bbd_data); 00315 00316 /* 00317 * ----------------------------------------------------------------- 00318 * Function : CVBBDPrecReInit 00319 * ----------------------------------------------------------------- 00320 * CVBBDPrecReInit re-initializes the BBDPRE module when solving a 00321 * sequence of problems of the same size with CVSPGMR/CVBBDPRE or 00322 * CVSPBCG/CVBBDPRE or CVSPTFQMR/CVBBDPRE provided there is no change 00323 * in Nlocal, mukeep, or mlkeep. After solving one problem, and after 00324 * calling CVodeReInit to re-initialize the integrator for a subsequent 00325 * problem, call CVBBDPrecReInit. Then call CVSpgmrSet* or CVSpbcgSet* 00326 * or CVSptfqmrSet* functions if necessary for any changes to CVSPGMR, 00327 * CVSPBCG, or CVSPTFQMR parameters, before calling CVode. 00328 * 00329 * The first argument to CVBBDPrecReInit must be the pointer pdata 00330 * that was returned by CVBBDPrecAlloc. All other arguments have 00331 * the same names and meanings as those of CVBBDPrecAlloc. 00332 * 00333 * The return value of CVBBDPrecReInit is CVBBDPRE_SUCCESS, indicating 00334 * success, or CVBBDPRE_PDATA_NULL if bbd_data was NULL. 00335 * ----------------------------------------------------------------- 00336 */ 00337 00338 SUNDIALS_EXPORT int CVBBDPrecReInit(void *bbd_data, int mudq, int mldq, 00339 realtype dqrely, CVLocalFn gloc, CVCommFn cfn); 00340 00341 /* 00342 * ----------------------------------------------------------------- 00343 * Function : CVBBDPrecFree 00344 * ----------------------------------------------------------------- 00345 * CVBBDPrecFree frees the memory block bbd_data allocated by the 00346 * call to CVBBDAlloc. 00347 * ----------------------------------------------------------------- 00348 */ 00349 00350 SUNDIALS_EXPORT void CVBBDPrecFree(void **bbd_data); 00351 00352 /* 00353 * ----------------------------------------------------------------- 00354 * BBDPRE optional output extraction routines 00355 * ----------------------------------------------------------------- 00356 * CVBBDPrecGetWorkSpace returns the BBDPRE real and integer work space 00357 * sizes. 00358 * CVBBDPrecGetNumGfnEvals returns the number of calls to gfn. 00359 * 00360 * The return value of CVBBDPrecGet* is one of: 00361 * CVBBDPRE_SUCCESS if successful 00362 * CVBBDPRE_PDATA_NULL if the bbd_data memory was NULL 00363 * ----------------------------------------------------------------- 00364 */ 00365 00366 SUNDIALS_EXPORT int CVBBDPrecGetWorkSpace(void *bbd_data, long int *lenrwLS, long int *leniwLS); 00367 SUNDIALS_EXPORT int CVBBDPrecGetNumGfnEvals(void *bbd_data, long int *ngevalsBBDP); 00368 00369 /* 00370 * ----------------------------------------------------------------- 00371 * The following function returns the name of the constant 00372 * associated with a CVBBDPRE return flag 00373 * ----------------------------------------------------------------- 00374 */ 00375 00376 SUNDIALS_EXPORT char *CVBBDPrecGetReturnFlagName(int flag); 00377 00378 #ifdef __cplusplus 00379 } 00380 #endif 00381 00382 #endif
1.5.6