00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.3 $ 00004 * $Date: 2006/11/29 00:05:05 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer: Radu Serban @ LLNL 00007 * ----------------------------------------------------------------- 00008 * Copyright (c) 2006, 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 CPBANDPRE module, which 00014 * provides a banded difference quotient Jacobian-based 00015 * preconditioner and solver routines for use with CPSPGMR, 00016 * CPSPBCG, or CPSPTFQMR. 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 * (for explicit-form ODEs) or on the residual function F (for 00022 * implicit-form ODEs). 00023 * The user supplies parameters 00024 * mu = upper half-bandwidth (number of super-diagonals) 00025 * ml = lower half-bandwidth (number of sub-diagonals) 00026 * The routines generate a band matrix of bandwidth ml + mu + 1 00027 * and use this to form a preconditioner for use with one of the 00028 * CSPILS iterative linear solvers. Although this matrix is intended 00029 * to approximate the Jacobian df/dy (respectively dF/dy + gamma*dF/dy, 00030 * it may be a very crude approximation. The true Jacobian need not 00031 * be banded, or its true bandwith may be larger than ml + mu + 1, 00032 * as long as the banded approximation generated here is sufficiently 00033 * accurate to speed convergence as a preconditioner. 00034 * 00035 * Usage: 00036 * The following is a summary of the usage of this module. 00037 * Details of the calls to CPodeCreate, CPodeMalloc, CPSp*, 00038 * and CPode are available in the User Guide. 00039 * To use these routines, the sequence of calls in the user 00040 * main program should be as follows: 00041 * 00042 * #include <cpodes/cpodes_bandpre.h> 00043 * #include <nvector_serial.h> 00044 * ... 00045 * void *bp_data; 00046 * ... 00047 * Set y0 00048 * ... 00049 * cpode_mem = CPodeCreate(...); 00050 * ier = CPodeMalloc(...); 00051 * ... 00052 * bp_data = CPBandPrecAlloc(cpode_mem, N, mu, ml); 00053 * ... 00054 * flag = CPBPSptfqmr(cpode_mem, pretype, maxl, bp_data); 00055 * -or- 00056 * flag = CPBPSpgmr(cpode_mem, pretype, maxl, bp_data); 00057 * -or- 00058 * flag = CPBPSpbcg(cpode_mem, pretype, maxl, bp_data); 00059 * ... 00060 * flag = CPode(...); 00061 * ... 00062 * CPBandPrecFree(&bp_data); 00063 * ... 00064 * Free y0 00065 * ... 00066 * CPodeFree(cpode_mem); 00067 * 00068 * Notes: 00069 * (1) Include this file for the CPBandPrecData type definition. 00070 * (2) In the CPBandPrecAlloc call, the arguments N is the 00071 * problem dimension. 00072 * (3) In the CPBPSp* call, the user is free to specify 00073 * the input pretype and the optional input maxl. The last 00074 * argument must be the pointer returned by CPBandPrecAlloc. 00075 * ----------------------------------------------------------------- 00076 */ 00077 00078 #ifndef _CPBANDPRE_H 00079 #define _CPBANDPRE_H 00080 00081 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00082 extern "C" { 00083 #endif 00084 00085 #include <sundials/sundials_nvector.h> 00086 00087 /* CPBANDPRE return values */ 00088 00089 #define CPBANDPRE_SUCCESS 0 00090 #define CPBANDPRE_PDATA_NULL -11 00091 #define CPBANDPRE_FUNC_UNRECVR -12 00092 00093 /* 00094 * ----------------------------------------------------------------- 00095 * Function : CPBandPrecAlloc 00096 * ----------------------------------------------------------------- 00097 * CPBandPrecAlloc allocates and initializes a CPBandPrecData 00098 * structure to be passed to CPSp* (and subsequently used 00099 * by CPBandPrecSetup and CPBandPrecSolve). 00100 * 00101 * The parameters of CPBandPrecAlloc are as follows: 00102 * 00103 * cpode_mem is the pointer to CPODES memory returned by CPodeCreate. 00104 * 00105 * N is the problem size. 00106 * 00107 * mu is the upper half bandwidth. 00108 * 00109 * ml is the lower half bandwidth. 00110 * 00111 * CPBandPrecAlloc returns the storage pointer of type 00112 * CPBandPrecData, or NULL if the request for storage cannot be 00113 * satisfied. 00114 * 00115 * NOTE: The band preconditioner assumes a serial implementation 00116 * of the NVECTOR package. Therefore, CPBandPrecAlloc will 00117 * first test for a compatible N_Vector internal 00118 * representation by checking for required functions. 00119 * ----------------------------------------------------------------- 00120 */ 00121 00122 SUNDIALS_EXPORT void *CPBandPrecAlloc(void *cpode_mem, int N, int mu, int ml); 00123 00124 /* 00125 * ----------------------------------------------------------------- 00126 * Function : CPBPSptfqmr 00127 * ----------------------------------------------------------------- 00128 * CPBPSptfqmr links the CPBANDPPRE preconditioner to the CPSPTFQMR 00129 * linear solver. It performs the following actions: 00130 * 1) Calls the CPSPTFQMR specification routine and attaches the 00131 * CPSPTFQMR linear solver to the integrator memory; 00132 * 2) Sets the preconditioner data structure for CPSPTFQMR 00133 * 3) Sets the preconditioner setup routine for CPSPTFQMR 00134 * 4) Sets the preconditioner solve routine for CPSPTFQMR 00135 * 00136 * Its first 3 arguments are the same as for CPSptfqmr (see 00137 * cpsptfqmr.h). The last argument is the pointer to the CPBANDPPRE 00138 * memory block returned by CPBandPrecAlloc. Note that the user need 00139 * not call CPSptfqmr. 00140 * 00141 * Possible return values are: 00142 * CPSPILS_SUCCESS if successful 00143 * CPSPILS_MEM_NULL if the CPODES memory was NULL 00144 * CPSPILS_LMEM_NULL if the CPSPILS memory was NULL 00145 * CPSPILS_MEM_FAIL if there was a memory allocation failure 00146 * CPSPILS_ILL_INPUT if a required vector operation is missing 00147 * CPBANDPRE_PDATA_NULL if the bp_data was NULL 00148 * ----------------------------------------------------------------- 00149 */ 00150 00151 SUNDIALS_EXPORT int CPBPSptfqmr(void *cpode_mem, int pretype, int maxl, void *p_data); 00152 00153 /* 00154 * ----------------------------------------------------------------- 00155 * Function : CPBPSpbcg 00156 * ----------------------------------------------------------------- 00157 * CPBPSpbcg links the CPBANDPPRE preconditioner to the CPSPBCG 00158 * linear solver. It performs the following actions: 00159 * 1) Calls the CPSPBCG specification routine and attaches the 00160 * CPSPBCG linear solver to the integrator memory; 00161 * 2) Sets the preconditioner data structure for CPSPBCG 00162 * 3) Sets the preconditioner setup routine for CPSPBCG 00163 * 4) Sets the preconditioner solve routine for CPSPBCG 00164 * 00165 * Its first 3 arguments are the same as for CPSpbcg (see 00166 * cpspbcg.h). The last argument is the pointer to the CPBANDPPRE 00167 * memory block returned by CPBandPrecAlloc. Note that the user need 00168 * not call CPSpbcg. 00169 * 00170 * Possible return values are: 00171 * CPSPILS_SUCCESS if successful 00172 * CPSPILS_MEM_NULL if the CPODEs memory was NULL 00173 * CPSPILS_LMEM_NULL if the CPSPILS memory was NULL 00174 * CPSPILS_MEM_FAIL if there was a memory allocation failure 00175 * CPSPILS_ILL_INPUT if a required vector operation is missing 00176 * CPBANDPRE_PDATA_NULL if the bp_data was NULL 00177 * ----------------------------------------------------------------- 00178 */ 00179 00180 SUNDIALS_EXPORT int CPBPSpbcg(void *cpode_mem, int pretype, int maxl, void *p_data); 00181 00182 /* 00183 * ----------------------------------------------------------------- 00184 * Function : CPBPSpgmr 00185 * ----------------------------------------------------------------- 00186 * CPBPSpgmr links the CPBANDPPRE preconditioner to the CPSPGMR 00187 * linear solver. It performs the following actions: 00188 * 1) Calls the CPSPGMR specification routine and attaches the 00189 * CPSPGMR linear solver to the integrator memory; 00190 * 2) Sets the preconditioner data structure for CPSPGMR 00191 * 3) Sets the preconditioner setup routine for CPSPGMR 00192 * 4) Sets the preconditioner solve routine for CPSPGMR 00193 * 00194 * Its first 3 arguments are the same as for CPSpgmr (see 00195 * cpspgmr.h). The last argument is the pointer to the CPBANDPPRE 00196 * memory block returned by CPBandPrecAlloc. Note that the user need 00197 * not call CPSpgmr. 00198 * 00199 * Possible return values are: 00200 * CPSPILS_SUCCESS if successful 00201 * CPSPILS_MEM_NULL if the CPODES memory was NULL 00202 * CPSPILS_LMEM_NULL if the CPSPILS memory was NULL 00203 * CPSPILS_MEM_FAIL if there was a memory allocation failure 00204 * CPSPILS_ILL_INPUT if a required vector operation is missing 00205 * CPBANDPRE_PDATA_NULL if the bp_data was NULL 00206 * ----------------------------------------------------------------- 00207 */ 00208 00209 SUNDIALS_EXPORT int CPBPSpgmr(void *cpode_mem, int pretype, int maxl, void *p_data); 00210 00211 /* 00212 * ----------------------------------------------------------------- 00213 * Function : CPBandPrecFree 00214 * ----------------------------------------------------------------- 00215 * CPBandPrecFree frees the memory allocated by CPBandPrecAlloc 00216 * in the argument bp_data. 00217 * ----------------------------------------------------------------- 00218 */ 00219 00220 SUNDIALS_EXPORT void CPBandPrecFree(void **bp_data); 00221 00222 /* 00223 * ----------------------------------------------------------------- 00224 * Optional output functions : CPBandPrecGet* 00225 * ----------------------------------------------------------------- 00226 * CPBandPrecGetWorkSpace returns the real and integer work space used 00227 * by CPBANDPRE. 00228 * CPBandPrecGetNumFctEvals returns the number of calls made from 00229 * CPBANDPRE to the user's ODE function. 00230 * 00231 * The return value of CPBandPrecGet* is one of: 00232 * CPBANDPRE_SUCCESS if successful 00233 * CPBANDPRE_PDATA_NULL if the bp_data memory was NULL 00234 * ----------------------------------------------------------------- 00235 */ 00236 00237 SUNDIALS_EXPORT int CPBandPrecGetWorkSpace(void *bp_data, long int *lenrwLS, long int *leniwLS); 00238 SUNDIALS_EXPORT int CPBandPrecGetNumFctEvals(void *bp_data, long int *nfevalsBP); 00239 00240 /* 00241 * ----------------------------------------------------------------- 00242 * The following function returns the name of the constant 00243 * associated with a CPBANDPRE return flag 00244 * ----------------------------------------------------------------- 00245 */ 00246 00247 SUNDIALS_EXPORT char *CPBandPrecGetReturnFlagName(int flag); 00248 00249 #ifdef __cplusplus 00250 } 00251 #endif 00252 00253 #endif
1.5.6