00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.3 $ 00004 * $Date: 2006/11/29 00:05:06 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer(s): Alan C. Hindmarsh and Radu Serban @ 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 header file for the CVBANDPRE 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 * Summary: 00019 * These routines provide a band matrix preconditioner based on 00020 * difference quotients of the ODE right-hand side function f. 00021 * The user supplies parameters 00022 * mu = upper half-bandwidth (number of super-diagonals) 00023 * ml = lower half-bandwidth (number of sub-diagonals) 00024 * The routines generate a band matrix of bandwidth ml + mu + 1 00025 * and use this to form a preconditioner for use with the Krylov 00026 * linear solver in CVSP*. Although this matrix is intended to 00027 * approximate the Jacobian df/dy, it may be a very crude 00028 * approximation. The true Jacobian need not be banded, or its 00029 * true bandwith may be larger than ml + mu + 1, as long as the 00030 * banded approximation generated here is sufficiently accurate 00031 * to speed convergence as a preconditioner. 00032 * 00033 * Usage: 00034 * The following is a summary of the usage of this module. 00035 * Details of the calls to CVodeCreate, CVodeMalloc, CVSp*, 00036 * and CVode are available in the User Guide. 00037 * To use these routines, the sequence of calls in the user 00038 * main program should be as follows: 00039 * 00040 * #include <cvode/cvode_bandpre.h> 00041 * #include <nvector_serial.h> 00042 * ... 00043 * void *bp_data; 00044 * ... 00045 * Set y0 00046 * ... 00047 * cvode_mem = CVodeCreate(...); 00048 * ier = CVodeMalloc(...); 00049 * ... 00050 * bp_data = CVBandPrecAlloc(cvode_mem, N, mu, ml); 00051 * ... 00052 * flag = CVBPSptfqmr(cvode_mem, pretype, maxl, bp_data); 00053 * -or- 00054 * flag = CVBPSpgmr(cvode_mem, pretype, maxl, bp_data); 00055 * -or- 00056 * flag = CVBPSpbcg(cvode_mem, pretype, maxl, bp_data); 00057 * ... 00058 * flag = CVode(...); 00059 * ... 00060 * CVBandPrecFree(&bp_data); 00061 * ... 00062 * Free y0 00063 * ... 00064 * CVodeFree(cvode_mem); 00065 * 00066 * Notes: 00067 * (1) Include this file for the CVBandPrecData type definition. 00068 * (2) In the CVBandPrecAlloc call, the arguments N is the 00069 * problem dimension. 00070 * (3) In the CVBPSp* call, the user is free to specify 00071 * the input pretype and the optional input maxl. The last 00072 * argument must be the pointer returned by CVBandPrecAlloc. 00073 * ----------------------------------------------------------------- 00074 */ 00075 00076 #ifndef _CVBANDPRE_H 00077 #define _CVBANDPRE_H 00078 00079 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00080 extern "C" { 00081 #endif 00082 00083 #include <sundials/sundials_nvector.h> 00084 00085 /* CVBANDPRE return values */ 00086 00087 #define CVBANDPRE_SUCCESS 0 00088 #define CVBANDPRE_PDATA_NULL -11 00089 #define CVBANDPRE_RHSFUNC_UNRECVR -12 00090 00091 /* 00092 * ----------------------------------------------------------------- 00093 * Function : CVBandPrecAlloc 00094 * ----------------------------------------------------------------- 00095 * CVBandPrecAlloc allocates and initializes a CVBandPrecData 00096 * structure to be passed to CVSp* (and subsequently used 00097 * by CVBandPrecSetup and CVBandPrecSolve). 00098 * 00099 * The parameters of CVBandPrecAlloc are as follows: 00100 * 00101 * cvode_mem is the pointer to CVODE memory returned by CVodeCreate. 00102 * 00103 * N is the problem size. 00104 * 00105 * mu is the upper half bandwidth. 00106 * 00107 * ml is the lower half bandwidth. 00108 * 00109 * CVBandPrecAlloc returns the storage pointer of type 00110 * CVBandPrecData, or NULL if the request for storage cannot be 00111 * satisfied. 00112 * 00113 * NOTE: The band preconditioner assumes a serial implementation 00114 * of the NVECTOR package. Therefore, CVBandPrecAlloc will 00115 * first test for a compatible N_Vector internal 00116 * representation by checking for required functions. 00117 * ----------------------------------------------------------------- 00118 */ 00119 00120 SUNDIALS_EXPORT void *CVBandPrecAlloc(void *cvode_mem, int N, int mu, int ml); 00121 00122 /* 00123 * ----------------------------------------------------------------- 00124 * Function : CVBPSptfqmr 00125 * ----------------------------------------------------------------- 00126 * CVBPSptfqmr links the CVBANDPPRE preconditioner to the CVSPTFQMR 00127 * linear solver. It performs the following actions: 00128 * 1) Calls the CVSPTFQMR specification routine and attaches the 00129 * CVSPTFQMR linear solver to the integrator memory; 00130 * 2) Sets the preconditioner data structure for CVSPTFQMR 00131 * 3) Sets the preconditioner setup routine for CVSPTFQMR 00132 * 4) Sets the preconditioner solve routine for CVSPTFQMR 00133 * 00134 * Its first 3 arguments are the same as for CVSptfqmr (see 00135 * cvsptfqmr.h). The last argument is the pointer to the CVBANDPPRE 00136 * memory block returned by CVBandPrecAlloc. Note that the user need 00137 * not call CVSptfqmr. 00138 * 00139 * Possible return values are: 00140 * CVSPILS_SUCCESS if successful 00141 * CVSPILS_MEM_NULL if the cvode memory was NULL 00142 * CVSPILS_LMEM_NULL if the cvsptfqmr memory was NULL 00143 * CVSPILS_MEM_FAIL if there was a memory allocation failure 00144 * CVSPILS_ILL_INPUT if a required vector operation is missing 00145 * CVBANDPRE_PDATA_NULL if the bp_data was NULL 00146 * ----------------------------------------------------------------- 00147 */ 00148 00149 SUNDIALS_EXPORT int CVBPSptfqmr(void *cvode_mem, int pretype, int maxl, void *p_data); 00150 00151 /* 00152 * ----------------------------------------------------------------- 00153 * Function : CVBPSpbcg 00154 * ----------------------------------------------------------------- 00155 * CVBPSpbcg links the CVBANDPPRE preconditioner to the CVSPBCG 00156 * linear solver. It performs the following actions: 00157 * 1) Calls the CVSPBCG specification routine and attaches the 00158 * CVSPBCG linear solver to the integrator memory; 00159 * 2) Sets the preconditioner data structure for CVSPBCG 00160 * 3) Sets the preconditioner setup routine for CVSPBCG 00161 * 4) Sets the preconditioner solve routine for CVSPBCG 00162 * 00163 * Its first 3 arguments are the same as for CVSpbcg (see 00164 * cvspbcg.h). The last argument is the pointer to the CVBANDPPRE 00165 * memory block returned by CVBandPrecAlloc. Note that the user need 00166 * not call CVSpbcg. 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 cvspbcg 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 CVBPSpbcg(void *cvode_mem, int pretype, int maxl, void *p_data); 00179 00180 /* 00181 * ----------------------------------------------------------------- 00182 * Function : CVBPSpgmr 00183 * ----------------------------------------------------------------- 00184 * CVBPSpgmr links the CVBANDPPRE preconditioner to the CVSPGMR 00185 * linear solver. It performs the following actions: 00186 * 1) Calls the CVSPGMR specification routine and attaches the 00187 * CVSPGMR linear solver to the integrator memory; 00188 * 2) Sets the preconditioner data structure for CVSPGMR 00189 * 3) Sets the preconditioner setup routine for CVSPGMR 00190 * 4) Sets the preconditioner solve routine for CVSPGMR 00191 * 00192 * Its first 3 arguments are the same as for CVSpgmr (see 00193 * cvspgmr.h). The last argument is the pointer to the CVBANDPPRE 00194 * memory block returned by CVBandPrecAlloc. Note that the user need 00195 * not call CVSpgmr. 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 cvspgmr 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 CVBPSpgmr(void *cvode_mem, int pretype, int maxl, void *p_data); 00208 00209 /* 00210 * ----------------------------------------------------------------- 00211 * Function : CVBandPrecFree 00212 * ----------------------------------------------------------------- 00213 * CVBandPrecFree frees the memory allocated by CVBandPrecAlloc 00214 * in the argument bp_data. 00215 * ----------------------------------------------------------------- 00216 */ 00217 00218 SUNDIALS_EXPORT void CVBandPrecFree(void **bp_data); 00219 00220 /* 00221 * ----------------------------------------------------------------- 00222 * Optional output functions : CVBandPrecGet* 00223 * ----------------------------------------------------------------- 00224 * CVBandPrecGetWorkSpace returns the real and integer work space used 00225 * by CVBANDPRE. 00226 * CVBandPrecGetNumRhsEvals returns the number of calls made from 00227 * CVBANDPRE to the user's right-hand side 00228 * routine f. 00229 * 00230 * The return value of CVBandPrecGet* is one of: 00231 * CVBANDPRE_SUCCESS if successful 00232 * CVBANDPRE_PDATA_NULL if the bp_data memory was NULL 00233 * ----------------------------------------------------------------- 00234 */ 00235 00236 SUNDIALS_EXPORT int CVBandPrecGetWorkSpace(void *bp_data, long int *lenrwLS, long int *leniwLS); 00237 SUNDIALS_EXPORT int CVBandPrecGetNumRhsEvals(void *bp_data, long int *nfevalsBP); 00238 00239 /* 00240 * ----------------------------------------------------------------- 00241 * The following function returns the name of the constant 00242 * associated with a CVBANDPRE return flag 00243 * ----------------------------------------------------------------- 00244 */ 00245 00246 SUNDIALS_EXPORT char *CVBandPrecGetReturnFlagName(int flag); 00247 00248 #ifdef __cplusplus 00249 } 00250 #endif 00251 00252 #endif
1.5.6