00001 /* 00002 * ----------------------------------------------------------------- 00003 * $Revision: 1.2 $ 00004 * $Date: 2006/11/29 00:05:07 $ 00005 * ----------------------------------------------------------------- 00006 * Programmer(s): Radu Serban and Aaron Collier @ 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 a generic NVECTOR package. 00014 * It defines the N_Vector structure (_generic_N_Vector) which 00015 * contains the following fields: 00016 * - an implementation-dependent 'content' field which contains 00017 * the description and actual data of the vector 00018 * - an 'ops' filed which contains a structure listing operations 00019 * acting on such vectors 00020 * 00021 * Part I of this file contains type declarations for the 00022 * _generic_N_Vector and _generic_N_Vector_Ops structures, as well 00023 * as references to pointers to such structures (N_Vector). 00024 * 00025 * Part II of this file contains the prototypes for the vector 00026 * functions which operate on N_Vector. 00027 * 00028 * At a minimum, a particular implementation of an NVECTOR must 00029 * do the following: 00030 * - specify the 'content' field of N_Vector, 00031 * - implement the operations on those N_Vectors, 00032 * - provide a constructor routine for new vectors 00033 * 00034 * Additionally, an NVECTOR implementation may provide the following: 00035 * - macros to access the underlying N_Vector data 00036 * - a constructor for an array of N_Vectors 00037 * - a constructor for an empty N_Vector (i.e., a new N_Vector with 00038 * a NULL data pointer). 00039 * - a routine to print the content of an N_Vector 00040 * ----------------------------------------------------------------- 00041 */ 00042 00043 #ifndef _NVECTOR_H 00044 #define _NVECTOR_H 00045 00046 #ifdef __cplusplus /* wrapper to enable C++ usage */ 00047 extern "C" { 00048 #endif 00049 00050 #include <sundials/sundials_types.h> 00051 00052 /* 00053 * ----------------------------------------------------------------- 00054 * Generic definition of N_Vector 00055 * ----------------------------------------------------------------- 00056 */ 00057 00058 /* Forward reference for pointer to N_Vector_Ops object */ 00059 typedef struct _generic_N_Vector_Ops *N_Vector_Ops; 00060 00061 /* Forward reference for pointer to N_Vector object */ 00062 typedef struct _generic_N_Vector *N_Vector; 00063 00064 /* Define array of N_Vectors */ 00065 typedef N_Vector *N_Vector_S; 00066 00067 /* Structure containing function pointers to vector operations */ 00068 struct _generic_N_Vector_Ops { 00069 N_Vector (*nvclone)(N_Vector); 00070 N_Vector (*nvcloneempty)(N_Vector); 00071 void (*nvdestroy)(N_Vector); 00072 void (*nvspace)(N_Vector, long int *, long int *); 00073 realtype* (*nvgetarraypointer)(N_Vector); 00074 void (*nvsetarraypointer)(realtype *, N_Vector); 00075 void (*nvlinearsum)(realtype, N_Vector, realtype, N_Vector, N_Vector); 00076 void (*nvconst)(realtype, N_Vector); 00077 void (*nvprod)(N_Vector, N_Vector, N_Vector); 00078 void (*nvdiv)(N_Vector, N_Vector, N_Vector); 00079 void (*nvscale)(realtype, N_Vector, N_Vector); 00080 void (*nvabs)(N_Vector, N_Vector); 00081 void (*nvinv)(N_Vector, N_Vector); 00082 void (*nvaddconst)(N_Vector, realtype, N_Vector); 00083 realtype (*nvdotprod)(N_Vector, N_Vector); 00084 realtype (*nvmaxnorm)(N_Vector); 00085 realtype (*nvwrmsnorm)(N_Vector, N_Vector); 00086 realtype (*nvwrmsnormmask)(N_Vector, N_Vector, N_Vector); 00087 realtype (*nvmin)(N_Vector); 00088 realtype (*nvwl2norm)(N_Vector, N_Vector); 00089 realtype (*nvl1norm)(N_Vector); 00090 void (*nvcompare)(realtype, N_Vector, N_Vector); 00091 booleantype (*nvinvtest)(N_Vector, N_Vector); 00092 booleantype (*nvconstrmask)(N_Vector, N_Vector, N_Vector); 00093 realtype (*nvminquotient)(N_Vector, N_Vector); 00094 }; 00095 00096 /* 00097 * ----------------------------------------------------------------- 00098 * A vector is a structure with an implementation-dependent 00099 * 'content' field, and a pointer to a structure of vector 00100 * operations corresponding to that implementation. 00101 * ----------------------------------------------------------------- 00102 */ 00103 00104 struct _generic_N_Vector { 00105 void *content; 00106 struct _generic_N_Vector_Ops *ops; 00107 }; 00108 00109 /* 00110 * ----------------------------------------------------------------- 00111 * Functions exported by NVECTOR module 00112 * ----------------------------------------------------------------- 00113 */ 00114 00115 /* 00116 * ----------------------------------------------------------------- 00117 * N_VClone 00118 * Creates a new vector of the same type as an existing vector. 00119 * It does not copy the vector, but rather allocates storage for 00120 * the new vector. 00121 * 00122 * N_VCloneEmpty 00123 * Creates a new vector of the same type as an existing vector, 00124 * but does not allocate storage. 00125 * 00126 * N_VDestroy 00127 * Destroys a vector created with N_VClone. 00128 * 00129 * N_VSpace 00130 * Returns space requirements for one N_Vector (type 'realtype' in 00131 * lrw and type 'long int' in liw). 00132 * 00133 * N_VGetArrayPointer 00134 * Returns a pointer to the data component of the given N_Vector. 00135 * NOTE: This function assumes that the internal data is stored 00136 * as a contiguous 'realtype' array. This routine is only used in 00137 * the solver-specific interfaces to the dense and banded linear 00138 * solvers, as well as the interfaces to the banded preconditioners 00139 * distributed with SUNDIALS. 00140 * 00141 * N_VSetArrayPointer 00142 * Overwrites the data field in the given N_Vector with a user-supplied 00143 * array of type 'realtype'. 00144 * NOTE: This function assumes that the internal data is stored 00145 * as a contiguous 'realtype' array. This routine is only used in 00146 * the interfaces to the dense linear solver. 00147 * 00148 * N_VLinearSum 00149 * Performs the operation z = a*x + b*y 00150 * 00151 * N_VConst 00152 * Performs the operation z[i] = c for i = 0, 1, ..., N-1 00153 * 00154 * N_VProd 00155 * Performs the operation z[i] = x[i]*y[i] for i = 0, 1, ..., N-1 00156 * 00157 * N_VDiv 00158 * Performs the operation z[i] = x[i]/y[i] for i = 0, 1, ..., N-1 00159 * 00160 * N_VScale 00161 * Performs the operation z = c*x 00162 * 00163 * N_VAbs 00164 * Performs the operation z[i] = |x[i]| for i = 0, 1, ..., N-1 00165 * 00166 * N_VInv 00167 * Performs the operation z[i] = 1/x[i] for i = 0, 1, ..., N-1 00168 * This routine does not check for division by 0. It should be 00169 * called only with an N_Vector x which is guaranteed to have 00170 * all non-zero components. 00171 * 00172 * N_VAddConst 00173 * Performs the operation z[i] = x[i] + b for i = 0, 1, ..., N-1 00174 * 00175 * N_VDotProd 00176 * Returns the dot product of two vectors: 00177 * sum (i = 0 to N-1) {x[i]*y[i]} 00178 * 00179 * N_VMaxNorm 00180 * Returns the maximum norm of x: 00181 * max (i = 0 to N-1) ABS(x[i]) 00182 * 00183 * N_VWrmsNorm 00184 * Returns the weighted root mean square norm of x with weight 00185 * vector w: 00186 * sqrt [(sum (i = 0 to N-1) {(x[i]*w[i])^2})/N] 00187 * 00188 * N_VWrmsNormMask 00189 * Returns the weighted root mean square norm of x with weight 00190 * vector w, masked by the elements of id: 00191 * sqrt [(sum (i = 0 to N-1) {(x[i]*w[i]*msk[i])^2})/N] 00192 * where msk[i] = 1.0 if id[i] > 0 and 00193 * msk[i] = 0.0 if id[i] < 0 00194 * 00195 * N_VMin 00196 * Returns the smallest element of x: 00197 * min (i = 0 to N-1) x[i] 00198 * 00199 * N_VWL2Norm 00200 * Returns the weighted Euclidean L2 norm of x with weight 00201 * vector w: 00202 * sqrt [(sum (i = 0 to N-1) {(x[i]*w[i])^2})] 00203 * 00204 * N_VL1Norm 00205 * Returns the L1 norm of x: 00206 * sum (i = 0 to N-1) {ABS(x[i])} 00207 * 00208 * N_VCompare 00209 * Performs the operation 00210 * z[i] = 1.0 if ABS(x[i]) >= c i = 0, 1, ..., N-1 00211 * 0.0 otherwise 00212 * 00213 * N_VInvTest 00214 * Performs the operation z[i] = 1/x[i] with a test for 00215 * x[i] == 0.0 before inverting x[i]. 00216 * This routine returns TRUE if all components of x are non-zero 00217 * (successful inversion) and returns FALSE otherwise. 00218 * 00219 * N_VConstrMask 00220 * Performs the operation : 00221 * m[i] = 1.0 if constraint test fails for x[i] 00222 * m[i] = 0.0 if constraint test passes for x[i] 00223 * where the constraint tests are as follows: 00224 * If c[i] = +2.0, then x[i] must be > 0.0. 00225 * If c[i] = +1.0, then x[i] must be >= 0.0. 00226 * If c[i] = -1.0, then x[i] must be <= 0.0. 00227 * If c[i] = -2.0, then x[i] must be < 0.0. 00228 * This routine returns a boolean FALSE if any element failed 00229 * the constraint test, TRUE if all passed. It also sets a 00230 * mask vector m, with elements equal to 1.0 where the 00231 * corresponding constraint test failed, and equal to 0.0 00232 * where the constraint test passed. 00233 * This routine is specialized in that it is used only for 00234 * constraint checking. 00235 * 00236 * N_VMinQuotient 00237 * Performs the operation : 00238 * minq = min ( num[i]/denom[i]) over all i such that 00239 * denom[i] != 0. 00240 * This routine returns the minimum of the quotients obtained 00241 * by term-wise dividing num[i] by denom[i]. A zero element 00242 * in denom will be skipped. If no such quotients are found, 00243 * then the large value BIG_REAL is returned. 00244 * 00245 * ----------------------------------------------------------------- 00246 * 00247 * The following table lists the vector functions used by 00248 * different modules in SUNDIALS. The symbols in the table 00249 * have the following meaning: 00250 * S - called by the solver; 00251 * D - called by the dense linear solver module 00252 * B - called by the band linear solver module 00253 * Di - called by the diagonal linear solver module 00254 * I - called by the iterative linear solver module 00255 * BP - called by the band preconditioner module 00256 * BBDP - called by the band-block diagonal preconditioner module 00257 * F - called by the Fortran-to-C interface 00258 * 00259 * ------------------------------------------------ 00260 * MODULES 00261 * NVECTOR ------------------------------------------------ 00262 * FUNCTIONS CVODE/CVODES IDA KINSOL 00263 * ----------------------------------------------------------------- 00264 * N_VClone S Di I S I BBDP S I BBDP 00265 * ----------------------------------------------------------------- 00266 * N_VCloneEmpty F F F 00267 * ----------------------------------------------------------------- 00268 * N_VDestroy S Di I S I BBDP S I BBDP 00269 * ----------------------------------------------------------------- 00270 * N_VSpace S S S 00271 * ----------------------------------------------------------------- 00272 * N_VGetArrayPointer D B BP BBDP F D B BBDP BBDP F 00273 * ----------------------------------------------------------------- 00274 * N_VSetArrayPointer D F D F 00275 * ----------------------------------------------------------------- 00276 * N_VLinearSum S D Di I S D I S I 00277 * ----------------------------------------------------------------- 00278 * N_VConst S I S I I 00279 * ----------------------------------------------------------------- 00280 * N_VProd S Di I S I S I 00281 * ----------------------------------------------------------------- 00282 * N_VDiv S Di I S I S I 00283 * ----------------------------------------------------------------- 00284 * N_VScale S D B Di I BP BBDP S D B I BBDP S I BBDP 00285 * ----------------------------------------------------------------- 00286 * N_VAbs S S S 00287 * ----------------------------------------------------------------- 00288 * N_VInv S Di S S 00289 * ----------------------------------------------------------------- 00290 * N_VAddConst S Di S 00291 * ----------------------------------------------------------------- 00292 * N_VDotProd I I I 00293 * ----------------------------------------------------------------- 00294 * N_VMaxNorm S S S 00295 * ----------------------------------------------------------------- 00296 * N_VWrmsNorm S D B I BP BBDP S 00297 * ----------------------------------------------------------------- 00298 * N_VWrmsNormMask S 00299 * ----------------------------------------------------------------- 00300 * N_VMin S S S 00301 * ----------------------------------------------------------------- 00302 * N_VWL2Norm S I 00303 * ----------------------------------------------------------------- 00304 * N_VL1Norm I 00305 * ----------------------------------------------------------------- 00306 * N_VCompare Di S 00307 * ----------------------------------------------------------------- 00308 * N_VInvTest Di 00309 * ----------------------------------------------------------------- 00310 * N_VConstrMask S S 00311 * ----------------------------------------------------------------- 00312 * N_VMinQuotient S S 00313 * ----------------------------------------------------------------- 00314 */ 00315 00316 SUNDIALS_EXPORT N_Vector N_VClone(N_Vector w); 00317 SUNDIALS_EXPORT N_Vector N_VCloneEmpty(N_Vector w); 00318 SUNDIALS_EXPORT void N_VDestroy(N_Vector v); 00319 SUNDIALS_EXPORT void N_VSpace(N_Vector v, long int *lrw, long int *liw); 00320 SUNDIALS_EXPORT realtype *N_VGetArrayPointer(N_Vector v); 00321 SUNDIALS_EXPORT void N_VSetArrayPointer(realtype *v_data, N_Vector v); 00322 SUNDIALS_EXPORT void N_VLinearSum(realtype a, N_Vector x, realtype b, N_Vector y, N_Vector z); 00323 SUNDIALS_EXPORT void N_VConst(realtype c, N_Vector z); 00324 SUNDIALS_EXPORT void N_VProd(N_Vector x, N_Vector y, N_Vector z); 00325 SUNDIALS_EXPORT void N_VDiv(N_Vector x, N_Vector y, N_Vector z); 00326 SUNDIALS_EXPORT void N_VScale(realtype c, N_Vector x, N_Vector z); 00327 SUNDIALS_EXPORT void N_VAbs(N_Vector x, N_Vector z); 00328 SUNDIALS_EXPORT void N_VInv(N_Vector x, N_Vector z); 00329 SUNDIALS_EXPORT void N_VAddConst(N_Vector x, realtype b, N_Vector z); 00330 SUNDIALS_EXPORT realtype N_VDotProd(N_Vector x, N_Vector y); 00331 SUNDIALS_EXPORT realtype N_VMaxNorm(N_Vector x); 00332 SUNDIALS_EXPORT realtype N_VWrmsNorm(N_Vector x, N_Vector w); 00333 SUNDIALS_EXPORT realtype N_VWrmsNormMask(N_Vector x, N_Vector w, N_Vector id); 00334 SUNDIALS_EXPORT realtype N_VMin(N_Vector x); 00335 SUNDIALS_EXPORT realtype N_VWL2Norm(N_Vector x, N_Vector w); 00336 SUNDIALS_EXPORT realtype N_VL1Norm(N_Vector x); 00337 SUNDIALS_EXPORT void N_VCompare(realtype c, N_Vector x, N_Vector z); 00338 SUNDIALS_EXPORT booleantype N_VInvTest(N_Vector x, N_Vector z); 00339 SUNDIALS_EXPORT booleantype N_VConstrMask(N_Vector c, N_Vector x, N_Vector m); 00340 SUNDIALS_EXPORT realtype N_VMinQuotient(N_Vector num, N_Vector denom); 00341 00342 /* 00343 * ----------------------------------------------------------------- 00344 * Additional functions exported by NVECTOR module 00345 * ----------------------------------------------------------------- 00346 */ 00347 00348 /* 00349 * ----------------------------------------------------------------- 00350 * N_VCloneEmptyVectorArray 00351 * Creates (by cloning 'w') an array of 'count' empty N_Vectors 00352 * 00353 * N_VCloneVectorArray 00354 * Creates (by cloning 'w') an array of 'count' N_Vectors 00355 * 00356 * N_VDestroyVectorArray 00357 * Frees memory for an array of 'count' N_Vectors that was 00358 * created by a call to N_VCloneVectorArray 00359 * 00360 * These functions are used by the SPGMR iterative linear solver 00361 * module and by the CVODES and IDAS solvers. 00362 * ----------------------------------------------------------------- 00363 */ 00364 00365 SUNDIALS_EXPORT N_Vector *N_VCloneEmptyVectorArray(int count, N_Vector w); 00366 SUNDIALS_EXPORT N_Vector *N_VCloneVectorArray(int count, N_Vector w); 00367 SUNDIALS_EXPORT void N_VDestroyVectorArray(N_Vector *vs, int count); 00368 00369 #ifdef __cplusplus 00370 } 00371 #endif 00372 00373 #endif
1.6.1