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 /** 00021 \file cta_reltable.h 00022 \brief Relation table component that defines a relation between two 00023 elements (ordered) sets of elements. 00024 00025 Relation tables are used to define a relation between elements in sets. 00026 Examples are the elements of a vector, matrix, tree vector or in a 00027 stochastic observer. 00028 00029 The Relation table can be used for copying elements from one set to the 00030 other optionally using interpolation (not yet supported). 00031 00032 */ 00033 00034 #ifndef CTA_RELTABLE_H 00035 #define CTA_RELTABLE_H 00036 #include "cta_system.h" 00037 #include "cta_handles.h" 00038 #include "cta_datatypes.h" 00039 #include "cta_vector.h" 00040 00041 /* Function Handle */ 00042 typedef CTA_Handle CTA_RelTable; 00043 #ifdef __cplusplus 00044 extern "C" { 00045 #endif 00046 00047 /* functions */ 00048 00049 /** \brief Create a relation table 00050 * 00051 * \param hreltable O created relation table 00052 * 00053 * \return error status: CTA_OK if successful 00054 */ 00055 CTAEXPORT int CTA_RelTable_Create(CTA_RelTable *hreltable); 00056 00057 /** \brief Free a relation table object. 00058 * 00059 * \param hreltable IO relation table to be freed, 00060 * value is set to CTA_NULL on return. 00061 * 00062 * \return error status: CTA_OK if successful 00063 */ 00064 CTAEXPORT int CTA_RelTable_Free(CTA_RelTable *hreltable); 00065 00066 /** \brief Copy elements according to relation table 00067 * 00068 * \note we currently only support copying of elements 00069 * between two vector instances. Other types of 00070 * COSTA object will be supported when needed 00071 * in later versions 00072 * 00073 * \param hreltable I handle of relation table 00074 * \param hfrom I Origin object to copy data from 00075 * \param hto I Target object to copy data to 00076 * 00077 * \return error status: CTA_OK if successful 00078 */ 00079 CTAEXPORT int CTA_RelTable_Apply(CTA_RelTable hreltable, 00080 CTA_Handle hfrom, CTA_Handle hto); 00081 00082 /** \brief Copy elements according to inverse of relation table 00083 * 00084 * \note we currently only support copying of elements 00085 * between two vector instances. Other types of 00086 * COSTA object will be supported when needed 00087 * in later versions 00088 * 00089 * \param hreltable I handle of relation table 00090 * \param hfrom I Origin object to copy data from 00091 * \param hto I Target object to copy data to 00092 * 00093 * \return error status: CTA_OK if successful 00094 */ 00095 CTAEXPORT int CTA_RelTable_ApplyInv(CTA_RelTable hreltable, 00096 CTA_Handle hfrom, CTA_Handle hto); 00097 00098 00099 /** \brief Set a relation table 00100 * A Set a relation table that defines a selection of elements 00101 * 00102 * \param hreltable O relation table that is set 00103 * \param vselect I (integer) vector with indices of elements 00104 from the target set that are selected. 00105 * 00106 * \return error status: CTA_OK if successful 00107 */ 00108 CTAEXPORT int CTA_RelTable_SetSelect(CTA_RelTable hreltable, CTA_Vector vselect); 00109 00110 /** \brief Get the number of elements that are copied when the table is applied 00111 * 00112 * 00113 * \param hreltable I relation table 00114 * \param nelt O number of elements that are copied 00115 * 00116 * \return error status: CTA_OK if successful 00117 */ 00118 CTAEXPORT int CTA_RelTable_Count(CTA_RelTable hreltable, int *nelt); 00119 00120 00121 /** \brief Set a relation table that is combination of two 00122 * relation tables. 00123 * 00124 * Set a relation table that is the combination of two exisiting relation 00125 * tables. It is possible to use the inverse of the relation tables when 00126 * needed 00127 *. 00128 * A usefull application of this method is to create a relation table that 00129 * defines a relation between a subset of elements from set1 and a subset of 00130 * the elements of set2. In order to set a relation table of this kind first 00131 * create two relation tables: 00132 * hrel1 elements from set 1 that have a relation with the elements from set 2, 00133 * hrel2 elements from set 2 that have a relation with the elements from set 1 00134 * 00135 * The combined relation table of hrel1 and inverse(hrel2) is a relation 00136 * table that spcifies the relation of a subset of elements from set1 and a 00137 * subset of elements from set2. 00138 * 00139 * \param hreltable O relation table that is set 00140 * \param hrel1 I first relation table 00141 * \param inverse1 I use inverse of hrel1 (CTA_TRUE/CTA_FALSE) 00142 * \param hrel2 I first relation table 00143 * \param inverse2 I use inverse of hrel2 (CTA_TRUE/CTA_FALSE) 00144 * 00145 * \return error status: CTA_OK if successful 00146 */ 00147 CTAEXPORT int CTA_RelTable_SetTableCombine(CTA_RelTable hreltable, 00148 CTA_RelTable hrel1, int inverse1, 00149 CTA_RelTable hrel2, int inverse2 ); 00150 00151 00152 00153 00154 /** \brief Apply relation table to two components 00155 * 00156 * \param reltable (I) Data of relation table 00157 * \param hrom (I) Source set of elements 00158 * \param hto (IO) Target set (some will be overwitten) 00159 * \param iverse (I) CTA_TRUE/CTA_FALSE apply inverse table 00160 * 00161 * \return error status: CTA_OK if successful 00162 * \note Internal routine not a user routine 00163 */ 00164 int CTAI_RelTable_Apply(CTA_RelTable hreltable, 00165 CTA_Handle hfrom, CTA_Handle hto, int inverse); 00166 00167 00168 00169 #ifdef __cplusplus 00170 } 00171 #endif 00172 #endif
1.6.1