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 #ifndef CTA_TREEVECTOR_H 00020 #define CTA_TREEVECTOR_H 00021 #include "cta_system.h" 00022 #include "cta_datatypes.h" 00023 #include "cta_handles.h" 00024 #include "cta_vector.h" 00025 #include "cta_matrix.h" 00026 #include "cta_metainfo.h" 00027 00028 /** 00029 \file cta_treevector.h 00030 \brief Interface description of the COSTA default tree-vector component. 00031 00032 The tree-vector is an extension of a vector component. A tree-vector 00033 either contains a single vector or is a concatenation of a number of 00034 tree-vectors, called sub-tree-vectors in this context. The usage of 00035 sub-tree-vectors makes is possible to concatenate models or extend models 00036 as is done when a deterministic model is extended into a stochastic model. 00037 The sub-tree-vectors are also very useful inside the model source code where the 00038 whole state of the model is not represented by a single vector. 00039 The default tree-vector component uses COSTA vector-components for storing the values. 00040 00041 Each (sub-)tree-vector has a tag. Tree-vectors having the same tag are considered 00042 to be the same, meaning they have the same buildup in sub-tree-vectors, length and 00043 datatypes. 00044 */ 00045 00046 00047 /** 00048 Type definition of a handle to a COSTA tree-vector instance 00049 */ 00050 typedef CTA_Handle CTA_TreeVector; 00051 00052 #ifdef __cplusplus 00053 extern "C" { 00054 #endif 00055 00056 /** \brief Create a tree-vector. 00057 * 00058 * \param name I name of the tree-vector, this is a human readable 00059 * string used for (debug) output and not by the algorithms 00060 * itself 00061 * \param tag I tag of this tree-vector 00062 * \param treevec O new tree-vector 00063 * 00064 * \return error status: CTA_OK if successful 00065 */ 00066 CTAEXPORT int CTA_TreeVector_Create(const char *name, const char *tag, CTA_TreeVector *treevec); 00067 00068 /** \brief Duplicate a tree-vector. 00069 * 00070 * \note Duplication means that a new tree-vector is created that is identical to 00071 * the originating tree-vector. All data in the original tree-vector is also copied. 00072 * 00073 * \param treevec1 I handle of treevector to be duplicated 00074 * \param treevec2 O receives handle to duplicate 00075 * 00076 * \return error status: CTA_OK if successful 00077 */ 00078 CTAEXPORT int CTA_TreeVector_Duplicate(CTA_TreeVector treevec1, CTA_TreeVector *treevec2 ); 00079 00080 00081 /** \brief Define a tree-vector to be a concatination of other tree-vectors. 00082 * 00083 * \note The concatenation is done by reference (handle). The sub-tree-vectors that 00084 * are concatenated are not copied. 00085 * 00086 * \param treevec1 I tree-vector that will be concatenation of the sub-tree-vectors provided in parameter treevecs 00087 * \param treevecs I array of the sub-tree-vectors 00088 * \param ntreevecs I number of sub-tree-vectors in treevecs 00089 * 00090 * \return error status: CTA_OK if successful 00091 */ 00092 CTAEXPORT int CTA_TreeVector_Conc(CTA_TreeVector treevec1, CTA_TreeVector *treevecs, int ntreevecs); 00093 00094 /** \brief Get the handle of a sub-tree-vectors using its tag. 00095 * 00096 * \note This is done by reference (handle). The handle of the 00097 * returned sub-tree-vector is not a copy 00098 * 00099 * \param treevec I Tree-vector 00100 * \param tag I tag of the requested sub-tree-vector 00101 * \param subtreevec O receives handle of the requested sub-tree-vectors, this is by reference, not a copy 00102 * 00103 * \return error status: CTA_OK if successful 00104 */ 00105 CTAEXPORT int CTA_TreeVector_GetSubTreeVec(CTA_TreeVector treevec, const char *tag, CTA_TreeVector *subtreevec); 00106 00107 /** \brief Get the tag of a sub-tree-vector using its index (starting with 0). 00108 * 00109 * \param treevec I Tree-vector 00110 * \param index I index of the requested sub-tree-vector 00111 * \param tag O String of standard length containnig the tag 00112 * 00113 * \return error status: CTA_OK if successful 00114 */ 00115 CTAEXPORT int CTA_TreeVector_GetSubTreeVecId(CTA_TreeVector treevec, int index, char tag[CTA_STRLEN_TAG]); 00116 00117 00118 /** \brief Get the handle of a first-layer sub-tree-vector using its index. 00119 * 00120 * \note The concatination is done by reference (handle). The handle of the 00121 * returned sub-tree-vector is not a copy 00122 * 00123 * \param treevec I Tree-vector 00124 * \param index I index of requested sub-tree-vector. Note that the first sub-tree-vector has index 1. 00125 * \param subtreevec O receives handle of the requested sub-tree-vector, this is by reference, not a copy 00126 * 00127 * \return error status: CTA_OK if successful 00128 */ 00129 CTAEXPORT int CTA_TreeVector_GetSubTreeVecIndex(CTA_TreeVector treevec, int index, 00130 CTA_TreeVector *subtreevec); 00131 00132 /** \brief Get number of sub-treevectors 00133 * 00134 * \note In case of a leaf 0 is returned 00135 * 00136 * \param treevec I Tree-vector 00137 * \param numSubTrees O Number of sub-treevectors 00138 * 00139 * \return error status: CTA_OK if successful 00140 */ 00141 CTAEXPORT int CTA_TreeVector_GetNumSubTree(CTA_TreeVector treevec, int* numSubTrees); 00142 00143 00144 /** \brief Get the tag of the tree-vector. 00145 * 00146 * Note tag should be large enough to hold the result 00147 * length of CTA_STRLEN_TAG is always save (no internal protection) 00148 * 00149 * \param treevec I Tree-vector 00150 * \param tag O receives the tag of the requested sub-tree-vector (see note) 00151 * 00152 * \return error status: CTA_OK if successful 00153 */ 00154 CTAEXPORT int CTA_TreeVector_GetTag(CTA_TreeVector treevec, char *tag); 00155 00156 00157 /** \brief Set the values of the tree-vector 00158 * 00159 * \note This operation is only possible when all data elements in the tree-vector 00160 * are of the same type and the size of the tree-vector corresponds to the 00161 * size of the input vector. 00162 * 00163 * \param treevec IO TreeVector 00164 * \param hvec I handle of the vector containing new values (see note) 00165 * 00166 * \return error status: CTA_OK if successful 00167 */ 00168 CTAEXPORT int CTA_TreeVector_SetVec(CTA_TreeVector treevec, CTA_Vector hvec); 00169 00170 /** \brief Get the values of the tree-vector. 00171 * 00172 * \note This operation is only possible when all data elements in the tree-vector 00173 * are of the same type and the size of the tree-vector corresponds to the 00174 * vector size. 00175 * 00176 * \param treevec I Tree-vector 00177 * \param hvec O Vector that is receiving the values; must exist before calling 00178 * 00179 * \return error status: CTA_OK if successful 00180 */ 00181 CTAEXPORT int CTA_TreeVector_GetVec(CTA_TreeVector treevec, CTA_Vector hvec); 00182 00183 /** \brief Axpy operation between two tree-vectors. 00184 * 00185 * \note Axpy: y=alpha*x+y. Add alpha times tree-vector x to 00186 * this tree-vector (y). 00187 * 00188 * \param y IO Tree-vector (y) 00189 * \param alpha I scalar 00190 * \param x I Tree-vector (x) 00191 * 00192 * \return error status: CTA_OK if successful 00193 */ 00194 CTAEXPORT int CTA_TreeVector_Axpy(CTA_TreeVector y, double alpha, CTA_TreeVector x); 00195 00196 /** \brief Compute dot product of two tree-vectors. 00197 * 00198 * \note dotprod = sum[all i] (treevec1_i * treevec2_i) 00199 * 00200 * \param treevec1 I first tree-vector 00201 * \param treevec2 I second tree-vector 00202 * \param dotprod O receives the dot product 00203 * 00204 * \return error status: CTA_OK if successful 00205 */ 00206 CTAEXPORT int CTA_TreeVector_Dot(CTA_TreeVector treevec1, CTA_TreeVector treevec2, double *dotprod); 00207 00208 /** \brief Compute the 2-norm of a tree-vector. 00209 * 00210 * \param treevec1 I Tree-vector 00211 * \param nrm2 O receives the 2-norm 00212 * 00213 * \return error status: CTA_OK if successful 00214 */ 00215 CTAEXPORT int CTA_TreeVector_Nrm2(CTA_TreeVector treevec1, double *nrm2); 00216 00217 00218 /** \brief Copy a tree-vector 00219 * 00220 * \note The two tree-vectors must be compatible: same structure and datatypes. 00221 * 00222 * \param treevec1 I sending tree-vector 00223 * \param treevec2 O receiving tree-vector 00224 * 00225 * \return error status: CTA_OK if successful 00226 */ 00227 CTAEXPORT int CTA_TreeVector_Copy(CTA_TreeVector treevec1, CTA_TreeVector treevec2); 00228 00229 /** \brief Set whole tree-vector equal to a constant value. 00230 * 00231 * \note This method can only be used if all elements of the tree-vector 00232 * have the same data type. 00233 * 00234 * \param treevec IO TreeVector 00235 * \param val I value to set 00236 * \param datatype I data type of val, must be same as data type of tree-vector 00237 * 00238 * \return error status: CTA_OK if successful 00239 */ 00240 CTAEXPORT int CTA_TreeVector_SetConstant(CTA_TreeVector treevec, void *val,CTA_Datatype datatype); 00241 00242 /** \brief Scale tree-vector. 00243 * 00244 * \param treevec IO handle of tree-vector 00245 * \param alpha I scalar 00246 * 00247 * \return error status: CTA_OK if successful 00248 */ 00249 CTAEXPORT int CTA_TreeVector_Scal(CTA_TreeVector treevec, double alpha); 00250 00251 /** \brief Set all values of the tree-vector. 00252 * 00253 * \note This method can only be used if all elements of the tree-vector 00254 * are of the same data type. 00255 * 00256 * \param treevec IO Tree-vector 00257 * \param val I values to be set 00258 * \param nval I number of elements in val 00259 * \param datatype I data type of *val, must be the same as data type of elements in tree-vector 00260 * 00261 * \return error status: CTA_OK if successful 00262 */ 00263 CTAEXPORT int CTA_TreeVector_SetVals(CTA_TreeVector treevec, void *val,int nval, CTA_Datatype datatype); 00264 00265 00266 /** \brief Get all values of the tree-vector. 00267 * 00268 * \note This method can only be used if all elements of the tree-vector 00269 * are of the same data type. 00270 * 00271 * \param treevec I Tree-vector 00272 * \param val O receives the values 00273 * \param nval I number of elements in val 00274 * \param datatype I data type of *val, must be the same as data type of elements in tree-vector 00275 * 00276 * \return error status: CTA_OK if successful 00277 */ 00278 CTAEXPORT int CTA_TreeVector_GetVals(CTA_TreeVector treevec, void *val,int nval,CTA_Datatype datatype); 00279 00280 /** \brief Set single value of the tree-vector. 00281 * 00282 * \param treevec IO Tree-Vector 00283 * \param i I index of value in tree-vector 00284 * \param val I value to be set 00285 * \param datatype I data type of *val, must be the same as data type of element in tree-vector 00286 * 00287 * \return error status: CTA_OK if successful 00288 */ 00289 CTAEXPORT int CTA_TreeVector_SetVal(CTA_TreeVector treevec, int i, void *val, CTA_Datatype datatype); 00290 00291 00292 /** \brief Get single value of the tree-vector. 00293 * 00294 * \param treevec I Tree-vector 00295 * \param i I index in value in tree-vector 00296 * \param val O returned value 00297 * \param datatype I data type of *val, must be the same as data type of element in tree-vector 00298 * 00299 * \return error status: CTA_OK if successful 00300 */ 00301 CTAEXPORT int CTA_TreeVector_GetVal(CTA_TreeVector treevec, int i, void *val,CTA_Datatype datatype); 00302 00303 /** \brief Get size of tree-vector. 00304 * 00305 * \param treevec I Tree-vector 00306 * \param n O receives size of tree-vector 00307 * 00308 * \return error status: CTA_OK if successful 00309 */ 00310 CTAEXPORT int CTA_TreeVector_GetSize(CTA_TreeVector treevec, int *n); 00311 00312 /** \brief Export tree-vector. 00313 * 00314 * Can export tree-vector to file or pack object.\n 00315 * usrdata must contain a handle of the file or pack object to be used.\n 00316 * Dependency: CTA_Vector_Export() 00317 * 00318 * 00319 * \param treevec I Tree-vector 00320 * \param usrdata I export properties 00321 * 00322 * \return error status: CTA_OK if successful 00323 */ 00324 CTAEXPORT int CTA_TreeVector_Export(CTA_TreeVector treevec, CTA_Handle usrdata); 00325 00326 /** \brief Import Tree-vector. 00327 * 00328 * Can import tree-vector from file or pack object.\n 00329 * usrdata must contain a handle of the file or pack object to be used.\n 00330 * Dependency: CTA_Vector_Import() 00331 * 00332 * 00333 * \param treevec I Tree-vector 00334 * \param usrdata I import properties 00335 * 00336 * \return error status: CTA_OK if successful 00337 */ 00338 CTAEXPORT int CTA_TreeVector_Import(CTA_TreeVector treevec, CTA_Handle usrdata); 00339 00340 /** \brief Import Tree-vector as flat vector. 00341 * 00342 * Can import tree-vector from netcdf file.\n 00343 * usrdata must contain a handle of the file .\n 00344 * Dependency: CTA_Vector_VImport() 00345 * 00346 * 00347 * \param treevec I Tree-vector 00348 * \param usrdata I import properties 00349 * 00350 * \return error status: CTA_OK if successful 00351 */ 00352 CTAEXPORT int CTA_TreeVector_VImport(CTA_TreeVector treevec, CTA_Handle usrdata); 00353 00354 00355 /** \brief Free Tree-vector. 00356 * 00357 * \param treevec I handle of tree-vector 00358 * \param recursive I also free all sub-tree-vectors, yes: CTA_TRUE or no: CTA_FALSE 00359 * 00360 * \return error status: CTA_OK if successful 00361 */ 00362 CTAEXPORT int CTA_TreeVector_Free(CTA_TreeVector *treevec, int recursive); 00363 00364 /** \brief Print tree-vector information. 00365 * 00366 * Gives following information:\n\n 00367 * Tree-vector information:\n 00368 * tag: [tag]\n 00369 * nsubtreevecs: [number of sub-tree-vectors]\n 00370 * 00371 * If nsubtreevecs > 0: recursively prints all sub-tree-vectors 00372 * Else prints:\n 00373 * leaf: yes\n 00374 * tree-vector size (leaf) 00375 * 00376 * \param treevec I tree-vector 00377 * 00378 * \return error status: CTA_OK if successful 00379 */ 00380 CTAEXPORT int CTA_TreeVector_Info(CTA_TreeVector treevec); 00381 00382 /** \brief Perform the matrix multiplication C:=alpha*op(A)*op(B)+beta*C 00383 where op(X)=X, X^T. However C and A are matrices of wich the columns are 00384 tree-vectors 00385 * 00386 * \param sC IO array of tree-vector (matrix C) 00387 * \param nc I number of columns of C (dimension of sC) 00388 * \param transa I transpose flag CTA_TRUE/CTA_FALSE for matrix A (not supported) 00389 * \param transb I transpose flag CTA_TRUE/CTA_FALSE for matrix B 00390 * \param alpha I scalar 00391 * \param sA I handle of matrix A 00392 * \param na I number of columns of A (dimension of sA) 00393 * \param mB I handle of matrix B 00394 * \param beta I scalar 00395 * \return error status: CTA_OK if successful 00396 */ 00397 CTAEXPORT int CTA_TreeVector_Gemm(CTA_TreeVector *sC, int nc, int transa, int transb, double alpha, CTA_TreeVector *sA, int na, 00398 CTA_Matrix mB, double beta); 00399 00400 00401 /** \brief Generate XML from one COSTA tree-vector 00402 * 00403 * \param treevec I handle of a COSTA tree-vector 00404 * \param writer I the XML text writer 00405 */ 00406 CTAEXPORT void CTAI_XML_WriteTreeVec(CTA_TreeVector treevec, xmlTextWriter *writer); 00407 00408 /** \brief Create a COSTA tree-vector from XML. 00409 * 00410 * \param cur_node I Current XML node 00411 * \return Handle to create or CTA_NULL in case of an error. 00412 */ 00413 CTAEXPORT CTA_TreeVector CTAI_XML_CreateTreeVec(xmlNode *cur_node); 00414 00415 00416 /** \brief Perform given operation on all leafs of the treevector 00417 * 00418 * \param treevec1 I handle of first COSTA tree-vector 00419 * \param treevec2 I handle of second COSTA tree-vector 00420 * \param treevec I handle of a COSTA tree-vector 00421 * \param op I operation to perform on the leafs 00422 * \param arg I additional argument of operation 00423 * \return error status: CTA_OK if successful 00424 */ 00425 CTAEXPORT int CTA_TreeVector_OpOnLeafs(CTA_TreeVector treevec1, CTA_TreeVector treevec2, CTA_Func op, CTA_Handle arg); 00426 00427 /** \brief Elementwise division of two vectors 00428 * \note y:=y./x 00429 * 00430 * \param y I handle of a COSTA tree-vector (y) 00431 * \param x I handle of a COSTA tree-vector (y) 00432 * \return error status: CTA_OK if successful 00433 */ 00434 CTAEXPORT int CTA_TreeVector_ElmDiv(CTA_TreeVector y, CTA_TreeVector x); 00435 00436 /** \brief Elementwise multiplication of two vectors 00437 * \note y:=y.*x 00438 * 00439 * \param y I handle of a COSTA tree-vector (y) 00440 * \param x I handle of a COSTA tree-vector (y) 00441 * \return error status: CTA_OK if successful 00442 */ 00443 CTAEXPORT int CTA_TreeVector_ElmProd(CTA_TreeVector y, CTA_TreeVector x); 00444 00445 /** \brief Elementwise sqare root 00446 * \note y:=sqrt(y) 00447 * 00448 * \param y I handle of a COSTA tree-vector (y) 00449 * \return error status: CTA_OK if successful 00450 */ 00451 CTAEXPORT int CTA_TreeVector_ElmSqrt(CTA_TreeVector y); 00452 00453 00454 /** \brief Set nocompute flag of a sub-tree vector 00455 * 00456 * When this flag is set, the values of the sub-treevector will 00457 * be ignored in all basic vector operations (including asking the 00458 * total length of the tree-vector). This propertie is used for 00459 * additionally adding some meta information 00460 * 00461 * \note the nocompute flag is set at the level of the parent! 00462 * so the "isolated" sub-treevector can be used in basic vector 00463 * operations. 00464 * 00465 * \param x I handle of a COSTA tree-vector (y) 00466 * \param tag I tag of sub-treevector 00467 * \return error status: CTA_OK if successful 00468 */ 00469 CTAEXPORT int CTA_TreeVector_SetSubTreeNocompute(CTA_TreeVector x, const char *tag); 00470 00471 /** \brief Increase the reference count of a treevector and all subtrevectors 00472 * 00473 * \param treevec I handle of a COSTA tree-vector 00474 * \return error status: CTA_OK if successful 00475 * 00476 */ 00477 CTAEXPORT int CTA_TreeVector_IncRefCount(CTA_TreeVector treevec); 00478 00479 00480 00481 CTAEXPORT int CTA_TreeVector_SetMetainfo(CTA_TreeVector treevec, CTA_Metainfo minfo); 00482 CTAEXPORT int CTA_TreeVector_GetMetainfo(CTA_TreeVector treevec, CTA_Metainfo minfo); 00483 00484 00485 CTAEXPORT int CTAI_TreeVec_GetVecNumHandles(CTA_TreeVector treevec); 00486 00487 CTAEXPORT int CTAI_TreeVec_List(CTA_TreeVector treevec, CTA_Vector taglist, int *indx); 00488 00489 CTAEXPORT int CTA_TreeVector_List(CTA_TreeVector treevec, CTA_Vector taglist ); 00490 00491 CTAEXPORT int CTA_TreeVector_GetVecNumHandles(CTA_TreeVector treevec); 00492 00493 CTAEXPORT void CTAI_Treevector_Operation_ScaledRMS(char *tag, CTA_Vector v1, 00494 CTA_Vector vscal, CTA_Handle hdum, int *retval); 00495 00496 CTAEXPORT void CTAI_Treevector_Operation_Amax(char *tag, CTA_Vector v1, 00497 CTA_Vector * v2, CTA_Handle hdum, int *retval); 00498 00499 CTAEXPORT void CTAI_Treevector_Operation_PrintEntry(char *tag, CTA_Vector v1, 00500 CTA_Vector v2, CTA_Handle hdum, int *retval); 00501 00502 CTAEXPORT void CTAI_Treevector_Operation_ScaledSSQ(char *tag, CTA_Vector v1, 00503 CTA_Vector vscal, CTA_Handle hdum, int *retval); 00504 00505 CTAEXPORT void CTAI_Treevector_Operation_MaxAbs(char *tag, CTA_Vector v1, 00506 CTA_Vector , CTA_Handle hdum, int *retval); 00507 00508 #ifdef __cplusplus 00509 } 00510 #endif 00511 #endif 00512