00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.3 $ 00004 * $Date: 2006/11/29 00:05:06 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer: 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 CVSBANDPRE module, which 00014 * provides a banded difference quotient Jacobian-based 00015 * preconditioner and solver routines for use with CVSPGMR, 00016 * CVSPBCG, or CVSPTFQMR. 00017 * 00018 * 00019 * Part I contains type definitions and function prototypes for using 00020 * CVSBANDPRE on forward problems (IVP integration and/or FSA) 00021 * 00022 * Part II contains type definitions and function prototypes for using 00023 * CVSBANDPRE on adjopint (backward) problems 00024 * ----------------------------------------------------------------- 00025 */ 00026 00027 #ifndef _CVSBANDPRE_H 00028 #define _CVSBANDPRE_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 A N D P R E C O N S T A N T S 00039 * ================================================================= 00040 */ 00041 00042 /* CVBANDPRE return values */ 00043 00044 #define CVBANDPRE_SUCCESS 0 00045 #define CVBANDPRE_PDATA_NULL -11 00046 #define CVBANDPRE_RHSFUNC_UNRECVR -12 00047 00048 #define CVBANDPRE_ADJMEM_NULL -111 00049 #define CVBANDPRE_MEM_FAIL -112 00050 00051 /* 00052 * ================================================================= 00053 * PART I - forward problems 00054 * ================================================================= 00055 */ 00056 00057 /* 00058 * ----------------------------------------------------------------- 00059 * 00060 * SUMMARY 00061 * 00062 * These routines provide a band matrix preconditioner based on 00063 * difference quotients of the ODE right-hand side function f. 00064 * The user supplies parameters 00065 * mu = upper half-bandwidth (number of super-diagonals) 00066 * ml = lower half-bandwidth (number of sub-diagonals) 00067 * The routines generate a band matrix of bandwidth ml + mu + 1 00068 * and use this to form a preconditioner for use with the Krylov 00069 * linear solver in CVSP*. Although this matrix is intended to 00070 * approximate the Jacobian df/dy, it may be a very crude 00071 * approximation. The true Jacobian need not be banded, or its 00072 * true bandwith may be larger than ml + mu + 1, as long as the 00073 * banded approximation generated here is sufficiently accurate 00074 * to speed convergence as a preconditioner. 00075 * 00076 * Usage: 00077 * The following is a summary of the usage of this module. 00078 * Details of the calls to CVodeCreate, CVodeMalloc, CVSp*, 00079 * and CVode are available in the User Guide. 00080 * To use these routines, the sequence of calls in the user 00081 * main program should be as follows: 00082 * 00083 * #include <cvodes/cvodes_bandpre.h> 00084 * #include <nvector_serial.h> 00085 * ... 00086 * void *bp_data; 00087 * ... 00088 * Set y0 00089 * ... 00090 * cvode_mem = CVodeCreate(...); 00091 * ier = CVodeMalloc(...); 00092 * ... 00093 * bp_data = CVBandPrecAlloc(cvode_mem, N, mu, ml); 00094 * ... 00095 * flag = CVBPSptfqmr(cvode_mem, pretype, maxl, bp_data); 00096 * -or- 00097 * flag = CVBPSpgmr(cvode_mem, pretype, maxl, bp_data); 00098 * -or- 00099 * flag = CVBPSpbcg(cvode_mem, pretype, maxl, bp_data); 00100 * ... 00101 * flag = CVode(...); 00102 * ... 00103 * CVBandPrecFree(&bp_data); 00104 * ... 00105 * Free y0 00106 * ... 00107 * CVodeFree(cvode_mem); 00108 * 00109 * Notes: 00110 * (1) Include this file for the CVBandPrecData type definition. 00111 * (2) In the CVBandPrecAlloc call, the arguments N is the 00112 * problem dimension. 00113 * (3) In the CVBPSp* call, the user is free to specify 00114 * the input pretype and the optional input maxl. The last 00115 * argument must be the pointer returned by CVBandPrecAlloc. 00116 * ----------------------------------------------------------------- 00117 */ 00118 00119 00120 /* 00121 * ----------------------------------------------------------------- 00122 * Function : CVBandPrecAlloc 00123 * ----------------------------------------------------------------- 00124 * CVBandPrecAlloc allocates and initializes a CVBandPrecData 00125 * structure to be passed to CVSp* (and subsequently used 00126 * by CVBandPrecSetup and CVBandPrecSolve). 00127 * 00128 * The parameters of CVBandPrecAlloc are as follows: 00129 * 00130 * cvode_mem is the pointer to CVODE memory returned by CVodeCreate. 00131 * 00132 * N is the problem size. 00133 * 00134 * mu is the upper half bandwidth. 00135 * 00136 * ml is the lower half bandwidth. 00137 * 00138 * CVBandPrecAlloc returns the storage pointer of type 00139 * CVBandPrecData, or NULL if the request for storage cannot be 00140 * satisfied. 00141 * 00142 * NOTE: The band preconditioner assumes a serial implementation 00143 * of the NVECTOR package. Therefore, CVBandPrecAlloc will 00144 * first test for a compatible N_Vector internal 00145 * representation by checking for required functions. 00146 * ----------------------------------------------------------------- 00147 */ 00148 00149 SUNDIALS_EXPORT void *CVBandPrecAlloc(void *cvode_mem, int N, int mu, int ml); 00150 00151 /* 00152 * ----------------------------------------------------------------- 00153 * Function : CVBPSptfqmr 00154 * ----------------------------------------------------------------- 00155 * CVBPSptfqmr links the CVBANDPPRE preconditioner to the CVSPTFQMR 00156 * linear solver. It performs the following actions: 00157 * 1) Calls the CVSPTFQMR specification routine and attaches the 00158 * CVSPTFQMR linear solver to the integrator memory; 00159 * 2) Sets the preconditioner data structure for CVSPTFQMR 00160 * 3) Sets the preconditioner setup routine for CVSPTFQMR 00161 * 4) Sets the preconditioner solve routine for CVSPTFQMR 00162 * 00163 * Its first 3 arguments are the same as for CVSptfqmr (see 00164 * cvsptfqmr.h). The last argument is the pointer to the CVBANDPPRE 00165 * memory block returned by CVBandPrecAlloc. Note that the user need 00166 * not call CVSptfqmr. 00167 * 00168 * Possible return values are: 00169 * CVSPILS_SUCCESS if successful 00170 * CVSPILS_MEM_NULL if the cvode memory was NULL 00171 * CVSPILS_LMEM_NULL if the cvsptfqmr memory was NULL 00172 * CVSPILS_MEM_FAIL if there was a memory allocation failure 00173 * CVSPILS_ILL_INPUT if a required vector operation is missing 00174 * CVBANDPRE_PDATA_NULL if the bp_data was NULL 00175 * ----------------------------------------------------------------- 00176 */ 00177 00178 SUNDIALS_EXPORT int CVBPSptfqmr(void *cvode_mem, int pretype, int maxl, void *p_data); 00179 00180 /* 00181 * ----------------------------------------------------------------- 00182 * Function : CVBPSpbcg 00183 * ----------------------------------------------------------------- 00184 * CVBPSpbcg links the CVBANDPPRE preconditioner to the CVSPBCG 00185 * linear solver. It performs the following actions: 00186 * 1) Calls the CVSPBCG specification routine and attaches the 00187 * CVSPBCG linear solver to the integrator memory; 00188 * 2) Sets the preconditioner data structure for CVSPBCG 00189 * 3) Sets the preconditioner setup routine for CVSPBCG 00190 * 4) Sets the preconditioner solve routine for CVSPBCG 00191 * 00192 * Its first 3 arguments are the same as for CVSpbcg (see 00193 * cvspbcgs.h). The last argument is the pointer to the CVBANDPPRE 00194 * memory block returned by CVBandPrecAlloc. Note that the user need 00195 * not call CVSpbcg. 00196 * 00197 * Possible return values are: 00198 * CVSPILS_SUCCESS if successful 00199 * CVSPILS_MEM_NULL if the cvode memory was NULL 00200 * CVSPILS_LMEM_NULL if the cvspbcg memory was NULL 00201 * CVSPILS_MEM_FAIL if there was a memory allocation failure 00202 * CVSPILS_ILL_INPUT if a required vector operation is missing 00203 * CVBANDPRE_PDATA_NULL if the bp_data was NULL 00204 * ----------------------------------------------------------------- 00205 */ 00206 00207 SUNDIALS_EXPORT int CVBPSpbcg(void *cvode_mem, int pretype, int maxl, void *p_data); 00208 00209 /* 00210 * ----------------------------------------------------------------- 00211 * Function : CVBPSpgmr 00212 * ----------------------------------------------------------------- 00213 * CVBPSpgmr links the CVBANDPPRE preconditioner to the CVSPGMR 00214 * linear solver. It performs the following actions: 00215 * 1) Calls the CVSPGMR specification routine and attaches the 00216 * CVSPGMR linear solver to the integrator memory; 00217 * 2) Sets the preconditioner data structure for CVSPGMR 00218 * 3) Sets the preconditioner setup routine for CVSPGMR 00219 * 4) Sets the preconditioner solve routine for CVSPGMR 00220 * 00221 * Its first 3 arguments are the same as for CVSpgmr (see 00222 * cvspgmr.h). The last argument is the pointer to the CVBANDPPRE 00223 * memory block returned by CVBandPrecAlloc. Note that the user need 00224 * not call CVSpgmr. 00225 * 00226 * Possible return values are: 00227 * CVSPILS_SUCCESS if successful 00228 * CVSPILS_MEM_NULL if the cvode memory was NULL 00229 * CVSPILS_LMEM_NULL if the cvspgmr memory was NULL 00230 * CVSPILS_MEM_FAIL if there was a memory allocation failure 00231 * CVSPILS_ILL_INPUT if a required vector operation is missing 00232 * CVBANDPRE_PDATA_NULL if the bp_data was NULL 00233 * ----------------------------------------------------------------- 00234 */ 00235 00236 SUNDIALS_EXPORT int CVBPSpgmr(void *cvode_mem, int pretype, int maxl, void *p_data); 00237 00238 /* 00239 * ----------------------------------------------------------------- 00240 * Function : CVBandPrecFree 00241 * ----------------------------------------------------------------- 00242 * CVBandPrecFree frees the memory allocated by CVBandPrecAlloc 00243 * in the argument bp_data. 00244 * ----------------------------------------------------------------- 00245 */ 00246 00247 SUNDIALS_EXPORT void CVBandPrecFree(void **bp_data); 00248 00249 /* 00250 * ----------------------------------------------------------------- 00251 * Optional output functions : CVBandPrecGet* 00252 * ----------------------------------------------------------------- 00253 * CVBandPrecGetWorkSpace returns the real and integer work space used 00254 * by CVBANDPRE. 00255 * CVBandPrecGetNumRhsEvals returns the number of calls made from 00256 * CVBANDPRE to the user's right-hand side 00257 * routine f. 00258 * 00259 * The return value of CVBandPrecGet* is one of: 00260 * CVBANDPRE_SUCCESS if successful 00261 * CVBANDPRE_PDATA_NULL if the bp_data memory was NULL 00262 * ----------------------------------------------------------------- 00263 */ 00264 00265 SUNDIALS_EXPORT int CVBandPrecGetWorkSpace(void *bp_data, long int *lenrwLS, long int *leniwLS); 00266 SUNDIALS_EXPORT int CVBandPrecGetNumRhsEvals(void *bp_data, long int *nfevalsBP); 00267 00268 /* 00269 * ----------------------------------------------------------------- 00270 * The following function returns the name of the constant 00271 * associated with a CVBANDPRE return flag 00272 * ----------------------------------------------------------------- 00273 */ 00274 00275 SUNDIALS_EXPORT char *CVBandPrecGetReturnFlagName(int flag); 00276 00277 /* 00278 * ================================================================= 00279 * PART II - backward problems 00280 * ================================================================= 00281 */ 00282 00283 /* 00284 * ----------------------------------------------------------------- 00285 * Functions: CVBandPrecAllocB, CVBPSp*B 00286 * ----------------------------------------------------------------- 00287 * Interface functions for the CVBANDPRE preconditioner to be used 00288 * on the backward phase. 00289 * 00290 * CVBandPrecAllocB interfaces to the CVBANDPRE preconditioner 00291 * for the backward integration. The pointer to the structure 00292 * returned by this routine should then be used in the call to 00293 * CVBPSp*B which interfaces to CVBPSPGMR/CVBPSPBCG/CVSPTFQMR. 00294 * ----------------------------------------------------------------- 00295 */ 00296 00297 SUNDIALS_EXPORT int CVBandPrecAllocB(void *cvadj_mem, int nB, int muB, int mlB); 00298 00299 SUNDIALS_EXPORT int CVBPSptfqmrB(void *cvadj_mem, int pretypeB, int maxlB); 00300 SUNDIALS_EXPORT int CVBPSpbcgB(void *cvadj_mem, int pretypeB, int maxlB); 00301 SUNDIALS_EXPORT int CVBPSpgmrB(void *cvadj_mem, int pretypeB, int maxlB); 00302 00303 SUNDIALS_EXPORT void CVBandPrecFreeB(void *cvadj_mem); 00304 00305 #ifdef __cplusplus 00306 } 00307 #endif 00308 00309 #endif
1.6.1