00001 /* 00002 COSTA: Problem solving environment for data assimilation 00003 Copyright (C) 2005 Nils van Velzen 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00018 */ 00019 00020 /* parameters for different functions */ 00021 #define CTA_VECTOR_CREATE_SIZE ( 1) 00022 #define CTA_VECTOR_CREATE_INIT ( 2) 00023 #define CTA_VECTOR_GETVALS ( 3) 00024 #define CTA_VECTOR_SETVALS ( 4) 00025 #define CTA_VECTOR_SETCONST ( 5) 00026 #define CTA_VECTOR_SCAL ( 6) 00027 #define CTA_VECTOR_COPY ( 7) 00028 #define CTA_VECTOR_AXPY ( 8) 00029 #define CTA_VECTOR_DOT ( 9) 00030 #define CTA_VECTOR_NRM2 (10) 00031 #define CTA_VECTOR_AMAX (11) 00032 #define CTA_VECTOR_GETMAXLEN (12) 00033 #define CTA_VECTOR_FREE (13) 00034 #define CTA_VECTOR_GETVAL (14) 00035 #define CTA_VECTOR_SETVAL (15) 00036 #define CTA_VECTOR_EXPORT (16) 00037 #define CTA_VECTOR_PRINT_TABLE (17) 00038 #define CTA_VECTOR_APPENDVAL (18) 00039 #define CTA_VECTOR_ELMDIV (19) 00040 #define CTA_VECTOR_IMPORT (20) 00041 #define CTA_VECTOR_NUMFUNC (21) 00042 00043 /** 00044 \file cta_usr_vector.h 00045 00046 \brief In this file a description is given of the interface of user vector functions. 00047 When creating your own vector class use the following as template. 00048 00049 The Usr_Vector to which is being referred in this template can be substituted by your own user vector object. 00050 00051 <b>Step 1</b>: for creating your own user vector class call the function CTA_Vector_DefineClass(). 00052 00053 Example: 00054 00055 \code 00056 typedef CTA_Handle CTA_VectorClass; 00057 00058 CTA_Func h_func[CTA_VECTOR_NUMFUNC]; 00059 CTA_VectorClass my_own_vector_class; 00060 00061 ierr=CTA_Func_Create(" ",&usr_vector_create_size, hintf, &h_func[CTA_VECTOR_CREATE_SIZE]); 00062 //...for all implementation functions... 00063 00064 CTA_Vector_DefineClass("classname", h_func, &my_own_vector_class);\endcode 00065 00066 Making a user vector class involves the implementation of the following functions: 00067 00068 <code>CTA_VECTOR_CREATE_SIZE \n 00069 CTA_VECTOR_CREATE_INIT \n 00070 CTA_VECTOR_GETVALS \n 00071 CTA_VECTOR_SETVALS \n 00072 CTA_VECTOR_SETCONST \n 00073 CTA_VECTOR_SCAL \n 00074 CTA_VECTOR_COPY \n 00075 CTA_VECTOR_AXPY \n 00076 CTA_VECTOR_DOT \n 00077 CTA_VECTOR_NRM2 \n 00078 CTA_VECTOR_AMAX \n 00079 CTA_VECTOR_GETMAXLEN \n 00080 CTA_VECTOR_FREE \n 00081 CTA_VECTOR_GETVAL \n 00082 CTA_VECTOR_SETVAL \n 00083 CTA_VECTOR_EXPORT \n 00084 CTA_VECTOR_PRINT_TABLE \n 00085 CTA_VECTOR_APPENDVAL \n 00086 CTA_VECTOR_ELMDIV \n 00087 CTA_VECTOR_IMPORT \n</code> 00088 00089 For creating an implementation function see documentation of CTA_Func_Create(). 00090 00091 <b>Step 2</b>: to create an object of the newly defined vector class call CTA_Vector_Create() in the 00092 same way as creating a CTA_Vector but with a different class handle, i.e. the user class handle from step 1 above. 00093 00094 Example: 00095 00096 \code 00097 Usr_Vector usrvec; //user vector object 00098 int nelements = 10; 00099 CTA_Datatype datatype = CTAI_String2Type("CTA_STRING"); 00100 CTA_Handle userdata = CTA_NULL; 00101 CTA_Vector_Create(my_own_vector_class, nelements, datatype, &userdata, &usrvec); 00102 \endcode 00103 \n 00104 <b>Note 1: </b> with object data is meant only the object itself including pointer(s) to its contents, but 00105 not the contents of the vector.\n\n 00106 <b>Note 2: </b> vector indices start from 1.\n\n 00107 */ 00108 00109 00110 //CTA_VECTOR_CREATE_SIZE ( 1) 00111 /** \brief Implementation that forms part of the create process. 00112 * 00113 * Must give the memory size of a new object. 00114 * 00115 * Example: 00116 * \code 00117 //in header file: 00118 typedef struct { 00119 //your own user object data goes here... 00120 }USR_VECTOR; 00121 00122 //user implementation: 00123 void usr_vector_create_size(...){ 00124 *memsize = sizeof(USR_VECTOR); 00125 *retval = CTA_OK; 00126 } 00127 \endcode 00128 * 00129 * \note At index CTA_VECTOR_CREATE_SIZE in the function list of the class descriptor. 00130 * 00131 * \param n I dimension 00132 * \param datatype I data type of the vector elements 00133 * \param userdata IO user data 00134 * \param retval O must receive return value of user implementation function 00135 * \param memsize O must receive the number of bytes which are necessary to store one 00136 user vector class, with a pointer to the contents (data), but without the 00137 contents themselves 00138 * \return no return value 00139 */ 00140 void usr_vector_create_size(int *n, CTA_Datatype *datatype, 00141 void *userdata, int *retval, int *memsize); 00142 00143 00144 //CTA_VECTOR_CREATE_INIT ( 2) 00145 /** \brief Implementation that forms part of the create process. 00146 * 00147 * The user vector object needs to be made ready for use. 00148 * 00149 * \note At index CTA_VECTOR_CREATE_INIT in the function list of the class descriptor. 00150 * 00151 * \param objectdata IO pointer to object data of user vector 00152 * \param n I size of vector data 00153 * \param datatype I data type of the vector elements 00154 * \param userdata IO user data 00155 * \param retval O must receive return value of user implementation function 00156 * \return no return value 00157 */ 00158 void usr_vector_create_init(Usr_Vector *objectdata, int *n, CTA_Datatype *datatype, 00159 void *userdata, int *retval); 00160 00161 00162 //CTA_VECTOR_GETVALS ( 3) 00163 /** \brief Implementation for retrieving all values of the user vector. 00164 * 00165 * \note At index CTA_VECTOR_GETVALS in the function list of the class descriptor. 00166 * 00167 * \param x I pointer to object data of the user vector 00168 * \param vals O must receive the values of the user vector 00169 * \param n I number of elements in the vals buffer, must equal number of elements in user vector 00170 * \param datatype I data type of elements of vals, must be the same as data type of user vector x 00171 * \param userdata IO user data 00172 * \param retval O must receive return value of user implementation function 00173 * \return no return value 00174 */ 00175 void usr_vector_getvals(Usr_Vector *x, void *vals, int *n, CTA_Datatype *datatype, 00176 void *userdata, int *retval); 00177 00178 00179 //CTA_VECTOR_SETVALS ( 4) 00180 /** \brief Implementation for setting all values of the user vector. 00181 * 00182 * \note At index CTA_VECTOR_SETVALS in the function list of the class descriptor. 00183 * 00184 * \param x I pointer to object data of user vector 00185 * \param vals I new values 00186 * \param n I number of elements in the vals buffer, must equal number of elements in user vector 00187 * \param datatype I data type of elements of vals, must be the same as data type of user vector x 00188 * \param userdata IO user data 00189 * \param retval O must receive return value of user implementation function 00190 * \return no return value 00191 */ 00192 void usr_vector_setvals(Usr_Vector *x, void *vals, int *n, CTA_Datatype *datatype, 00193 void *userdata, int *retval); 00194 00195 00196 //CTA_VECTOR_SETCONST ( 5) 00197 /** \brief Implementation for setting all values of user vector to same value. 00198 * 00199 * \note At index CTA_VECTOR_SETCONST in the function list of the class descriptor. 00200 * 00201 * \param x I pointer to object data of user vector 00202 * \param val I value to set vector elements to 00203 * \param datatype I data type of elements of vals, must be the same as data type of user vector x 00204 * \param userdata IO user data 00205 * \param retval O must receive return value of user implementation function 00206 * \return no return value 00207 */ 00208 void usr_vector_setconst(Usr_Vector *x, void *val, CTA_Datatype *datatype, 00209 void *userdata, int *retval); 00210 00211 00212 //CTA_VECTOR_SCAL ( 6) 00213 /** \brief Implementation for scaling the user vector: x=ax 00214 * 00215 * \note At index CTA_VECTOR_SCAL in the function list of the class descriptor. 00216 * 00217 * \param x IO pointer to object data of user vector 00218 * \param alpha I scaling factor 00219 * \param userdata IO user data 00220 * \param retval O must receive return value of user implementation function 00221 * \return no return value 00222 */ 00223 void usr_vector_scal(Usr_Vector *x, double *alpha, void *userdata, int *retval); 00224 00225 00226 //CTA_VECTOR_COPY ( 7) 00227 /** \brief Implementation for copying the user vector. 00228 * 00229 * \note At index CTA_VECTOR_COPY in the function list of the class descriptor. 00230 * 00231 * \param x I pointer to object data of a user vector 00232 * \param y O pointer to object data of user vector y that must receive copy of x; must exist before calling 00233 * \param userdata IO user data 00234 * \param retval O must receive return value of user implementation function 00235 * \return no return value 00236 */ 00237 void usr_vector_copy(Usr_Vector *x, Usr_Vector *y, void *userdata, 00238 int *retval); 00239 00240 00241 //CTA_VECTOR_AXPY ( 8) 00242 /** \brief Implementation for applying the BLAS operation axpy: y=y+ax 00243 * 00244 * \note At index CTA_VECTOR_AXPY in the function list of the class descriptor. 00245 * 00246 * \param y IO pointer to object data of user vector y; must exist before calling 00247 * \param alpha I scaling factor 00248 * \param x I pointer to object data of user vector x 00249 * \param userdata IO user data 00250 * \param retval O must receive return value of user implementation function 00251 * \return no return value 00252 */ 00253 void usr_vector_axpy(Usr_Vector *y, double *alpha, Usr_Vector *x, 00254 void *userdata, int *retval); 00255 00256 //CTA_VECTOR_DOT ( 9) 00257 /** \brief Implementation for calculating the dot product of two user vectors x.y 00258 * 00259 * \note At index CTA_VECTOR_DOT in the function list of the class descriptor. 00260 * 00261 * \param y I pointer to object data of user vector y 00262 * \param x I pointer to object data of user vector x 00263 * \param userdata IO user data 00264 * \param dotprod O must receive the dot product 00265 * \param retval O must receive return value of user implementation function 00266 * \return no return value 00267 */ 00268 void usr_vector_dot(Usr_Vector *x, Usr_Vector *y, void *userdata, 00269 double *dotprod, int *retval); 00270 00271 //CTA_VECTOR_NRM2 (10) 00272 /** \brief Implementation for calculating the 2-norm of a user vector 00273 * 00274 * \note At index CTA_VECTOR_NRM2 in the function list of the class descriptor. 00275 * 00276 * \param x I pointer to object data of user vector 00277 * \param userdata IO user data 00278 * \param norm2 O must receive the 2-norm 00279 * \param retval O must receive return value of user implementation function 00280 * \return no return value 00281 */ 00282 void usr_vector_nrm2(Usr_Vector *x, void *userdata, double *norm2, int *retval); 00283 00284 //CTA_VECTOR_AMAX (11) 00285 /** \brief Implementation for getting the index of the element with the largest maximum value. First index is 1. 00286 * 00287 * \note At index CTA_VECTOR_AMAX in the function list of the class descriptor. 00288 * 00289 * \param x I pointer to object data of user vector 00290 * \param userdata IO user data 00291 * \param iloc O must receive index of maximum value 00292 * \param retval O must receive return value of user implementation function 00293 * \return no return value 00294 */ 00295 void usr_vector_amax(Usr_Vector *x, void *userdata, int *iloc, int *retval); 00296 00297 00298 //CTA_VECTOR_GETMAXLEN (12) 00299 /** \brief Implementation for getting the maximum length in case of vector with string elements. 00300 * 00301 * \note At index CTA_VECTOR_GETMAXLEN in the function list of the class descriptor. 00302 * 00303 * \param x I pointer to object data of user vector 00304 * \param userdata IO user data 00305 * \param maxlen O must receive maximum length 00306 * \param retval O must receive return value of user implementation function 00307 * \return no return value 00308 */ 00309 void usr_vector_getmaxlen(Usr_Vector *x, void *userdata, int *maxlen, int *retval); 00310 00311 00312 //CTA_VECTOR_FREE (13) 00313 /** \brief Implementation for freeing the user vector. 00314 * 00315 * \note At index CTA_VECTOR_FREE in the function list of the class descriptor. 00316 * 00317 * \param x IO pointer to object data of user vector 00318 * \param userdata IO user data 00319 * \param retval O must receive return value of user implementation function 00320 * \return no return value 00321 */ 00322 void usr_vector_free(Usr_Vector *x, void *userdata, int *retval); 00323 00324 00325 //CTA_VECTOR_GETVAL (14) 00326 /** \brief Implementation for retrieving a single value of user vector at given index 00327 * 00328 * \note At index CTA_VECTOR_GETVAL in the function list of the class descriptor. 00329 * 00330 * \param x I pointer to object data of user vector 00331 * \param i I index of value to retrieve 00332 * \param val O must receive value; must exist before calling 00333 * \param datatype I data type of *val, must be the same as data type of user vector x 00334 * \param userdata IO user data 00335 * \param retval O must receive return value of user implementation function 00336 * \return no return value 00337 */ 00338 void usr_vector_getval(Usr_Vector *x, int *i, void *val, CTA_Datatype *datatype, 00339 void *userdata, int *retval); 00340 00341 00342 //CTA_VECTOR_SETVAL (15) 00343 /** \brief Implementation for setting a single value of a user vector. 00344 * 00345 * \note At index CTA_VECTOR_SETVAL in the function list of the class descriptor. 00346 * 00347 * \param x I pointer to object data of user vector 00348 * \param i I index of value to set 00349 * \param val I new data of value 00350 * \param datatype I data type of *val, must be the same as data type of user vector x 00351 * \param userdata IO user data 00352 * \param retval O must receive return value of user implementation function 00353 * \return no return value 00354 */ 00355 void usr_vector_setval(Usr_Vector *x, int *i, void *val, CTA_Datatype *datatype, 00356 void *userdata, int *retval); 00357 00358 00359 //CTA_VECTOR_EXPORT (16) 00360 /** \brief Implementation for exporting a user vector. 00361 * 00362 * \note At index CTA_VECTOR_EXPORT in the function list of the class descriptor. 00363 * \n For example implementation for exporting a user vector to a pack object or to screen. 00364 * 00365 * \param x I pointer to object data of user vector 00366 * \param userdata IO user data 00367 * \param retval O must receive return value of user implementation function 00368 * \return no return value 00369 */ 00370 void usr_vector_export(Usr_Vector *x, void userdata, int *retval); 00371 00372 00373 //CTA_VECTOR_PRINT_TABLE (17) 00374 /** \brief Implementation for printing a table. 00375 * 00376 * \note At index CTA_VECTOR_PRINT_TABLE in the function list of the class descriptor. 00377 * 00378 * \param table IO array of vectors that forms the table to be filled 00379 * \param ncolumns I number of columns 00380 * \param formats I user vector 00381 * \param retval O must receive return value of user implementation function 00382 * \return no return value 00383 */ 00384 void usr_vector_print_table(Usr_Vector **table, int *ncolumns, 00385 Usr_Vector * formats, int *retval); 00386 00387 00388 //CTA_VECTOR_APPENDVAL (18) 00389 /** \brief Implementation for appending a single value to the user vector. 00390 * 00391 * \note At index CTA_VECTOR_APPENDVAL in the function list of the class descriptor. 00392 * 00393 * \param x IO pointer to object data of user vector 00394 * \param val I value to append 00395 * \param datatype I data type of value to append, must be the same as data type of user vector x 00396 * \param retval O must receive return value of user implementation function 00397 * \return no return value 00398 */ 00399 void usr_vector_appendval(Usr_Vector *x, void *val, CTA_Datatype *datatype, 00400 int *retval); 00401 00402 00403 //CTA_VECTOR_ELMDIV (19) 00404 /** \brief Implementation for element-wise division of user vector. 00405 * 00406 * \note At index CTA_VECTOR_ELMDIV in the function list of the class descriptor. 00407 * 00408 * \param y IO pointer to object data of receiving user vector 00409 * \param x I pointer to object data of user vector x 00410 * \param userdata IO user data 00411 * \param retval O must receive return value of user implementation function 00412 * \return no return value 00413 */ 00414 void usr_vector_elmdiv(Usr_Vector *y, CTAI_Vector_blas *x, 00415 void *userdata, int *retval); 00416 00417 00418 00419 //CTA_VECTOR_IMPORT (20) 00420 /** \brief Implementation for importing a user vector. 00421 * 00422 * \note At index CTA_VECTOR_IMPORT in the function list of the class descriptor. 00423 * 00424 * \param x O pointer to object data of user vector that must receive import result 00425 * \param userdata IO user data 00426 * \param retval O must receive return value of user implementation function 00427 * \return no return value 00428 */ 00429 void usr_vector_import(Usr_Vector *x, void userdata, int *retval); 00430 00431 00432 00433 00434 00435 00436 00437 00438 00439 00440