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