00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.2 $ 00004 * $Date: 2006/11/29 00:05:06 $ 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 * Common header file for the direct linear solvers in CVODE. 00014 * ----------------------------------------------------------------- 00015 */ 00016 00017 #ifndef _CVDIRECT_H 00018 #define _CVDIRECT_H 00019 00020 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00021 extern "C" { 00022 #endif 00023 00024 #include <sundials/sundials_direct.h> 00025 #include <sundials/sundials_nvector.h> 00026 00027 /* 00028 * ================================================================= 00029 * C V D I R E C T C O N S T A N T S 00030 * ================================================================= 00031 */ 00032 00033 /* 00034 * ----------------------------------------------------------------- 00035 * CVDIRECT return values 00036 * ----------------------------------------------------------------- 00037 */ 00038 00039 #define CVDIRECT_SUCCESS 0 00040 #define CVDIRECT_MEM_NULL -1 00041 #define CVDIRECT_LMEM_NULL -2 00042 #define CVDIRECT_ILL_INPUT -3 00043 #define CVDIRECT_MEM_FAIL -4 00044 00045 /* Additional last_flag values */ 00046 00047 #define CVDIRECT_JACFUNC_UNRECVR -5 00048 #define CVDIRECT_JACFUNC_RECVR -6 00049 00050 /* 00051 * ================================================================= 00052 * F U N C T I O N T Y P E S 00053 * ================================================================= 00054 */ 00055 00056 /* 00057 * ----------------------------------------------------------------- 00058 * Type: CVDlsDenseJacFn 00059 * ----------------------------------------------------------------- 00060 * 00061 * A dense Jacobian approximation function Jac must be of type 00062 * CVDlsDenseJacFn. Its parameters are: 00063 * 00064 * N is the problem size. 00065 * 00066 * Jac is the dense matrix (of type DlsMat) that will be loaded 00067 * by a CVDlsDenseJacFn with an approximation to the Jacobian 00068 * matrix J = (df_i/dy_j) at the point (t,y). 00069 * 00070 * t is the current value of the independent variable. 00071 * 00072 * y is the current value of the dependent variable vector, 00073 * namely the predicted value of y(t). 00074 * 00075 * fy is the vector f(t,y). 00076 * 00077 * jac_data is a pointer to user data - the same as the jac_data 00078 * parameter passed to CVDlsSetJacFn. 00079 * 00080 * tmp1, tmp2, and tmp3 are pointers to memory allocated for 00081 * vectors of length N which can be used by a CVDlsDenseJacFn 00082 * as temporary storage or work space. 00083 * 00084 * A CVDlsDenseJacFn should return 0 if successful, a positive 00085 * value if a recoverable error occurred, and a negative value if 00086 * an unrecoverable error occurred. 00087 * 00088 * ----------------------------------------------------------------- 00089 * 00090 * NOTE: The following are two efficient ways to load a dense Jac: 00091 * (1) (with macros - no explicit data structure references) 00092 * for (j=0; j < Neq; j++) { 00093 * col_j = DENSE_COL(Jac,j); 00094 * for (i=0; i < Neq; i++) { 00095 * generate J_ij = the (i,j)th Jacobian element 00096 * col_j[i] = J_ij; 00097 * } 00098 * } 00099 * (2) (without macros - explicit data structure references) 00100 * for (j=0; j < Neq; j++) { 00101 * col_j = (Jac->data)[j]; 00102 * for (i=0; i < Neq; i++) { 00103 * generate J_ij = the (i,j)th Jacobian element 00104 * col_j[i] = J_ij; 00105 * } 00106 * } 00107 * A third way, using the DENSE_ELEM(A,i,j) macro, is much less 00108 * efficient in general. It is only appropriate for use in small 00109 * problems in which efficiency of access is NOT a major concern. 00110 * 00111 * NOTE: If the user's Jacobian routine needs other quantities, 00112 * they are accessible as follows: hcur (the current stepsize) 00113 * and ewt (the error weight vector) are accessible through 00114 * CVodeGetCurrentStep and CVodeGetErrWeights, respectively 00115 * (see cvode.h). The unit roundoff is available as 00116 * UNIT_ROUNDOFF defined in sundials_types.h. 00117 * 00118 * ----------------------------------------------------------------- 00119 */ 00120 00121 00122 typedef int (*CVDlsDenseJacFn)(int N, realtype t, 00123 N_Vector y, N_Vector fy, 00124 DlsMat Jac, void *jac_data, 00125 N_Vector tmp1, N_Vector tmp2, N_Vector tmp3); 00126 00127 /* 00128 * ----------------------------------------------------------------- 00129 * Type: CVDlsBandJacFn 00130 * ----------------------------------------------------------------- 00131 * 00132 * A band Jacobian approximation function Jac must have the 00133 * prototype given below. Its parameters are: 00134 * 00135 * N is the length of all vector arguments. 00136 * 00137 * mupper is the upper half-bandwidth of the approximate banded 00138 * Jacobian. This parameter is the same as the mupper parameter 00139 * passed by the user to the linear solver initialization function. 00140 * 00141 * mlower is the lower half-bandwidth of the approximate banded 00142 * Jacobian. This parameter is the same as the mlower parameter 00143 * passed by the user to the linear solver initialization function. 00144 * 00145 * t is the current value of the independent variable. 00146 * 00147 * y is the current value of the dependent variable vector, 00148 * namely the predicted value of y(t). 00149 * 00150 * fy is the vector f(t,y). 00151 * 00152 * Jac is the band matrix (of type DlsMat) that will be loaded 00153 * by a CVDlsBandJacFn with an approximation to the Jacobian matrix 00154 * Jac = (df_i/dy_j) at the point (t,y). 00155 * Three efficient ways to load J are: 00156 * 00157 * (1) (with macros - no explicit data structure references) 00158 * for (j=0; j < n; j++) { 00159 * col_j = BAND_COL(Jac,j); 00160 * for (i=j-mupper; i <= j+mlower; i++) { 00161 * generate J_ij = the (i,j)th Jacobian element 00162 * BAND_COL_ELEM(col_j,i,j) = J_ij; 00163 * } 00164 * } 00165 * 00166 * (2) (with BAND_COL macro, but without BAND_COL_ELEM macro) 00167 * for (j=0; j < n; j++) { 00168 * col_j = BAND_COL(Jac,j); 00169 * for (k=-mupper; k <= mlower; k++) { 00170 * generate J_ij = the (i,j)th Jacobian element, i=j+k 00171 * col_j[k] = J_ij; 00172 * } 00173 * } 00174 * 00175 * (3) (without macros - explicit data structure references) 00176 * offset = Jac->smu; 00177 * for (j=0; j < n; j++) { 00178 * col_j = ((Jac->data)[j])+offset; 00179 * for (k=-mupper; k <= mlower; k++) { 00180 * generate J_ij = the (i,j)th Jacobian element, i=j+k 00181 * col_j[k] = J_ij; 00182 * } 00183 * } 00184 * Caution: Jac->smu is generally NOT the same as mupper. 00185 * 00186 * The BAND_ELEM(A,i,j) macro is appropriate for use in small 00187 * problems in which efficiency of access is NOT a major concern. 00188 * 00189 * jac_data is a pointer to user data - the same as the jac_data 00190 * parameter passed to CVDlsSetJacFn. 00191 * 00192 * NOTE: If the user's Jacobian routine needs other quantities, 00193 * they are accessible as follows: hcur (the current stepsize) 00194 * and ewt (the error weight vector) are accessible through 00195 * CVodeGetCurrentStep and CVodeGetErrWeights, respectively 00196 * (see cvode.h). The unit roundoff is available as 00197 * UNIT_ROUNDOFF defined in sundials_types.h 00198 * 00199 * tmp1, tmp2, and tmp3 are pointers to memory allocated for 00200 * vectors of length N which can be used by a CVDlsBandJacFn 00201 * as temporary storage or work space. 00202 * 00203 * A CVDlsBandJacFn should return 0 if successful, a positive value 00204 * if a recoverable error occurred, and a negative value if an 00205 * unrecoverable error occurred. 00206 * ----------------------------------------------------------------- 00207 */ 00208 00209 typedef int (*CVDlsBandJacFn)(int N, int mupper, int mlower, 00210 realtype t, N_Vector y, N_Vector fy, 00211 DlsMat Jac, void *jac_data, 00212 N_Vector tmp1, N_Vector tmp2, N_Vector tmp3); 00213 00214 /* 00215 * ================================================================= 00216 * E X P O R T E D F U N C T I O N S 00217 * ================================================================= 00218 */ 00219 00220 /* 00221 * ----------------------------------------------------------------- 00222 * Optional inputs to the CVDIRECT linear solver 00223 * ----------------------------------------------------------------- 00224 * 00225 * CVDlsSetJacFn specifies the Jacobian approximation routine to be 00226 * used. When using dense Jacobians, a user-supplied jac routine must 00227 * be of type CVDlsDenseJacFn. When using banded Jacobians, a 00228 * user-supplied jac routine must be of type CVDlsBandJacFn. 00229 * By default, a difference quotient approximation, supplied with this 00230 * solver is used. 00231 * CVDlsSetJacFn also specifies a pointer to user data which is 00232 * passed to the user's jac routine every time it is called. 00233 * 00234 * The return value of CVDlsSetJacFn is one of: 00235 * CVDIRECT_SUCCESS if successful 00236 * CVDIRECT_MEM_NULL if the CVODE memory was NULL 00237 * CVDIRECT_LMEM_NULL if the linear solver memory was NULL 00238 * ----------------------------------------------------------------- 00239 */ 00240 00241 SUNDIALS_EXPORT int CVDlsSetJacFn(void *cvode_mem, void *jac, void *jac_data); 00242 00243 /* 00244 * ----------------------------------------------------------------- 00245 * Optional outputs from the CVDIRECT linear solver 00246 * ----------------------------------------------------------------- 00247 * 00248 * CVDlsGetWorkSpace returns the real and integer workspace used 00249 * by the direct linear solver. 00250 * CVDlsGetNumJacEvals returns the number of calls made to the 00251 * Jacobian evaluation routine jac. 00252 * CVDlsGetNumRhsEvals returns the number of calls to the user 00253 * f routine due to finite difference Jacobian 00254 * evaluation. 00255 * CVDlsGetLastFlag returns the last error flag set by any of 00256 * the CVDIRECT interface functions. 00257 * 00258 * The return value of CVDlsGet* is one of: 00259 * CVDIRECT_SUCCESS if successful 00260 * CVDIRECT_MEM_NULL if the CVODE memory was NULL 00261 * CVDIRECT_LMEM_NULL if the linear solver memory was NULL 00262 * ----------------------------------------------------------------- 00263 */ 00264 00265 SUNDIALS_EXPORT int CVDlsGetWorkSpace(void *cvode_mem, long int *lenrwLS, long int *leniwLS); 00266 SUNDIALS_EXPORT int CVDlsGetNumJacEvals(void *cvode_mem, long int *njevals); 00267 SUNDIALS_EXPORT int CVDlsGetNumRhsEvals(void *cvode_mem, long int *nfevalsLS); 00268 SUNDIALS_EXPORT int CVDlsGetLastFlag(void *cvode_mem, int *flag); 00269 00270 /* 00271 * ----------------------------------------------------------------- 00272 * The following function returns the name of the constant 00273 * associated with a CVDIRECT return flag 00274 * ----------------------------------------------------------------- 00275 */ 00276 00277 SUNDIALS_EXPORT char *CVDlsGetReturnFlagName(int flag); 00278 00279 00280 #ifdef __cplusplus 00281 } 00282 #endif 00283 00284 #endif
1.5.6