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_usr_stoch_observer.h 00022 00023 \brief In this file a description is given of the interface of user stochastic observer functions. 00024 When creating your own user stochastic observer class use the following as template. 00025 00026 The Usr_SObs to which is being referred in this template can be substituted by your own user stochastic observer object. 00027 00028 <b>Step 1</b>: for creating your own user stochastic observer class call the function CTA_SObs_DefineClass(). 00029 00030 Example: 00031 00032 \code 00033 typedef CTA_Handle CTA_SObsClass; 00034 00035 CTA_Func h_func[CTA_SOBS_NUMFUNC]; 00036 CTA_SObsClass my_own_sobs_class; 00037 CTA_ObsDescrClass obsdescrclass; //observation descriptor class that is being used by stochastic observer 00038 00039 ierr=CTA_Func_Create(" ",&usr_sobs_create_size, hintf, &h_func[CTA_SOBS_CREATE_SIZE]); 00040 //...for all implementation functions... 00041 00042 CTA_SObs_DefineClass("classname", h_func, obsdescrclass, &my_own_sobs_class);\endcode 00043 00044 00045 00046 Making a user stochastic observer class involves the implementation of the following functions: 00047 00048 CTA_SOBS_CREATE_SIZE \n 00049 CTA_SOBS_CREATE_INIT \n 00050 CTA_SOBS_FREE \n 00051 CTA_SOBS_CREATE_SELECTION \n 00052 CTA_SOBS_COUNT \n 00053 CTA_SOBS_GET_OBS_DESCRIPTION \n 00054 CTA_SOBS_GET_VALUES \n 00055 CTA_SOBS_GET_REALISATION \n 00056 CTA_SOBS_GET_EXPECTATION \n 00057 CTA_SOBS_EVALUATE_PDF \n 00058 CTA_SOBS_GET_COV_MATRIX \n 00059 CTA_SOBS_GET_VARIANCE \n 00060 CTA_SOBS_EXPORT \n 00061 CTA_SOBS_GET_TIMES \n 00062 00063 For creating an implementation function see documentation of CTA_Func_Create(). 00064 00065 <b>Step 2</b>: to create an object of the newly defined stochastic observer class call CTA_SObs_Create() in the 00066 same way as creating a CTA_SObs object but with a different class handle, i.e. the user class handle from step 1 above. 00067 00068 Example: 00069 00070 \code 00071 Usr_SObs usrsobs; //user stochastic observer object 00072 CTA_Handle userdata = CTA_NULL; 00073 CTA_SObs_Create(my_own_sobs_class, &userdata, &usrsobs); 00074 \endcode 00075 \n 00076 <b>Note 1: </b> with object data is meant only the object itself including pointer(s) to its contents, but 00077 not the contents of the stochastic observer.\n\n 00078 */ 00079 00080 00081 00082 //#define CTA_SOBS_CREATE_SIZE ( 1) 00083 /** \brief Implementation that forms part of the create process. 00084 * 00085 * Must give the memory size of a new user stochastic observer object. 00086 * 00087 * Example: 00088 * \code 00089 //in header file: 00090 typedef struct { 00091 //your own user object data goes here... 00092 }USR_SOBS; 00093 00094 //user implementation: 00095 void usr_sobs_create_size(...){ 00096 *memsize = sizeof(USR_SOBS); 00097 *retval = CTA_OK; 00098 } 00099 \endcode 00100 * 00101 * \note At index CTA_SOBS_CREATE_SIZE in the function list of the class descriptor. 00102 * 00103 * \param memsize O must receive the number of bytes which are necessary to store one 00104 user stochastic observer class, with a pointer to the contents (data), but without the 00105 contents themselves 00106 * \param retval O must receive return value of user implementation function 00107 * \return no return value 00108 */ 00109 void usr_sobs_create_size(int *memsize, int *retval); 00110 00111 00112 //#define CTA_SOBS_CREATE_INIT ( 2) 00113 /** \brief Implementation that forms part of the create process. 00114 * 00115 * The user stochastic observer object needs to be made ready for use. 00116 * 00117 * \note At index CTA_SOBS_CREATE_INIT in the function list of the class descriptor. 00118 * 00119 * \param sobsdata I pointer to user object data 00120 * \param userdata IO user data 00121 * \param retval O must receive return value of user implementation function 00122 * \return no return value 00123 */ 00124 void usr_sobs_create_init(Usr_SObs *sobsdata, void *userdata, int *retval); 00125 00126 00127 //#define CTA_SOBS_FREE ( 3) 00128 /** \brief Implementation for freeing the object data and associated resources. 00129 * 00130 * \note At index CTA_SOBS_FREE in the function list of the class descriptor. 00131 * 00132 * \param sobsdata IO pointer to user object data 00133 * \param userdata IO user data 00134 * \param retval O must receive return value of user implementation function 00135 * \return no return value 00136 */ 00137 void usr_sobs_free(Usr_SObs *sobsdata, void *userdata, int *retval); 00138 00139 00140 //#define CTA_SOBS_CREATE_SELECTION ( 4) 00141 /** \brief Implementation for creating a new stochastic observer that is subset of existing stochastic observer. 00142 * 00143 * \note At index CTA_SOBS_CREATE_SELECTION in the function list of the class descriptor. 00144 * \note CTA_SObs_CreateTimSel() calls this implementation with userdata a handle of a time selection string. 00145 * 00146 * \param sobsdatain I pointer to object data of in-object 00147 * \param userdata IO user data 00148 * \param sobsdataout IO pointer to object data of out-object 00149 * \param retval O must receive return value of user implementation function 00150 * \return no return value 00151 */ 00152 void usr_sobs_create_selection(Usr_SObs *sobsdatain, void *userdata, Usr_SObs *sobsdataout, int *retval); 00153 00154 00155 //#define CTA_SOBS_COUNT ( 5) 00156 /** \brief Implementation for counting the number of measures 00157 in user stochastic observer object. 00158 * 00159 * \note At index CTA_SOBS_COUNT in the function list of the class descriptor. 00160 * 00161 * \param sobsdata IO pointer to user object data 00162 * \param nmeasr O must receive number of measures in object 00163 * \param retval O must receive return value of user implementation function 00164 * \return no return value 00165 */ 00166 void usr_sobs_count(Usr_SObs *sobsdata, int *nmeasr, int *retval); 00167 00168 00169 //#define CTA_SOBS_GET_OBS_DESCRIPTION ( 6) 00170 /** \brief Implementation for creating the observation description corresponding to the stochastic observer. 00171 * 00172 * \note At index CTA_SOBS_GET_DESCRIPTION in the function list of the class descriptor. 00173 * \note Caller is responsible for freeing the here created observation description 00174 * \note THIS IMPLEMENTATION FUNCTION IS NOT SUPPORTED 00175 * 00176 * \param sobsdata IO pointer to user object data 00177 * \return no return value 00178 */ 00179 void usr_sobs_get_description(Usr_SObs *sobsdata); 00180 00181 00182 //#define CTA_SOBS_GET_VALUES ( 7) 00183 /** \brief Implementation for getting all values of user stochastic observer object. 00184 * 00185 * \note At index CTA_SOBS_GET_VALUES in the function list of the class descriptor. 00186 * 00187 * \param sobsdata IO pointer to user object data 00188 * \param hvec O handle of vector that must receive the values; must exist before calling; 00189 must be of appropriate data type 00190 * \param retval O must receive return value of user implementation function 00191 * \return no return value 00192 */ 00193 void usr_sobs_get_values(Usr_SObs *sobsdata, CTA_Vector *hvec, int *retval); 00194 00195 00196 //#define CTA_SOBS_GET_REALISATION ( 8) 00197 /** \brief Implementation for calculating stochastic realizations for all the 00198 measurements in a user stochastic observer. 00199 * 00200 * \note At index CTA_SOBS_GET_REALISATION in the function list of the class descriptor. 00201 * 00202 * \param sobsdata I pointer to user object data 00203 * \param hvec O handle of vector that must receive realisation; must exist before calling 00204 * \param retval O must receive return value of implementation function 00205 * \return no return value 00206 */ 00207 void usr_sobs_get_realisation(Usr_SObs *sobsdata, CTA_Vector *hvec, int *retval); 00208 00209 00210 //#define CTA_SOBS_GET_EXPECTATION ( 9) 00211 /** \brief Implementation for getting the expectation of the probability density function of the mesurements. 00212 * 00213 * \note At index CTA_SOBS_GET_EXPECTATION in the function list of the class descriptor. 00214 * 00215 * \param sobsdata I pointer to user object data 00216 * \param hvec O handle of vector that must receive expectation; must exist before calling 00217 * \param retval O must receive return value of implementation function 00218 * \return no return value 00219 */ 00220 void usr_sobs_get_expectation(Usr_SObs *sobsdata, CTA_Vector *hvec, int *retval); 00221 00222 00223 //#define CTA_SOBS_EVALUATE_PDF (10) 00224 /** \brief Implementation for getting the value of the probability density function of the mesurements at given location. 00225 * 00226 * \note At index CTA_SOBS_EVALUATE_PDF in the function list of the class descriptor. 00227 * 00228 * \param sobsdata I pointer to user object data 00229 * \param location I handle of vector with location for evaluating pdf 00230 * \param pdfvalue O handle of vector that must receive result of evaluation; must exist before calling 00231 * \param retval O must receive return value of implementation function 00232 * \return no return value 00233 */ 00234 void usr_sobs_evaluate_pdf(Usr_SObs *sobsdata, CTA_Vector *location, CTA_Vector *pdfvalue, int *retval); 00235 00236 00237 //#define CTA_SOBS_GET_COV_MATRIX (11) 00238 /** \brief Implementation for getting all the variances of the measurements in a 00239 user stochastic observer. 00240 * 00241 * \note At index CTA_SOBS_GET_COV_MATRIX in the function list of the class descriptor. 00242 * 00243 * \param sobsdata I pointer to user object data 00244 * \param hmatrix O handle of matrix object that must receive the covariance matrix; must exist before calling 00245 * \param retval O must receive return value of implementation function 00246 * \return no return value 00247 */ 00248 void usr_sobs_get_cov_matrix(Usr_SObs *sobsdata, CTA_Matrix *hmatrix, int *retval); 00249 00250 00251 //#define CTA_SOBS_GET_VARIANCE (12) 00252 /** \brief Implementation for calculating all variances or standard deviations. 00253 * 00254 * \note At index CTA_SOBS_GET_VARIANCE in the function list of the class descriptor. 00255 * 00256 * \param sobsdata I pointer to user object data 00257 * \param variance O handle of vector that must receive variances / standard 00258 deviations; must exist before calling 00259 * \param varflag I variance flag: CTA_TRUE for calculating variances, 00260 CTA_FALSE for standard deviations 00261 * \param retval O must receive return value of implementation function 00262 * \return no return value 00263 */ 00264 void usr_sobs_get_variance(Usr_SObs *sobsdata, CTA_Vector *variance, int *varflag, int *retval); 00265 00266 00267 //#define CTA_SOBS_EXPORT (13) 00268 /** \brief Implementation for exporting user stochastic observer object. 00269 * 00270 * \note At index CTA_SOBS_EXPORT in the function list of the class descriptor. 00271 * 00272 * \param sobsdata I pointer to user object data 00273 * \param userdata IO pointer to user data 00274 * \param retval O must receive return value of implementation function 00275 * \return no return value 00276 */ 00277 void usr_sobs_export(Usr_SObs *sobsdata, void *userdata, int *retval); 00278 00279 00280 //#define CTA_SOBS_GET_TIMES (14) 00281 /** \brief Implementation for getting all times associated with the measurements. 00282 * 00283 * \note At index CTA_SOBS_GET_TIMES in the function list of the class descriptor. 00284 * 00285 * \param sobsdata I pointer to user object data 00286 * \param times O handle of vector that must receive times; must exist before calling 00287 * \param retval O must receive return value of user implementation function 00288 * \return no return value 00289 */ 00290 void usr_sobs_get_times(Usr_SObs *sobsdata, CTA_Vector *times, int *retval); 00291 00292 00293 00294