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_model.h 00022 00023 \brief In this file a description is given of the interface of user model functions. 00024 When creating your own user model class use the following as template. 00025 00026 The Usr_Model to which is being referred in this template can be substituted by your own user model object. 00027 00028 <b>Step 1</b>: for creating your own user model class call the function CTA_Model_DefineClass(). 00029 00030 Example: 00031 00032 \code 00033 typedef CTA_Handle CTA_ModelClass; 00034 00035 CTA_Func h_func[CTA_MODEL_NUMFUNC]; 00036 CTA_ModelClass my_own_model_class; 00037 00038 ierr=CTA_Func_Create(" ",&usr_model_create_size, hintf, &h_func[CTA_MODEL_CREATE_SIZE]); 00039 //...for all implementation functions... 00040 00041 CTA_Model_DefineClass("classname", h_func, &my_own_model_class);\endcode 00042 00043 Making a user method class involves the implementation of the following functions: 00044 00045 CTA_MODEL_CREATE_SIZE \n 00046 CTA_MODEL_CREATE_INIT \n 00047 CTA_MODEL_FREE \n 00048 CTA_MODEL_COMPUTE \n 00049 CTA_MODEL_SET_STATE \n 00050 CTA_MODEL_GET_STATE \n 00051 CTA_MODEL_AXPY_STATE \n 00052 CTA_MODEL_AXPY_MODEL \n 00053 CTA_MODEL_SET_FORC \n 00054 CTA_MODEL_GET_FORC \n 00055 CTA_MODEL_AXPY_FORC \n 00056 CTA_MODEL_SET_PARAM \n 00057 CTA_MODEL_GET_PARAM \n 00058 CTA_MODEL_AXPY_PARAM \n 00059 CTA_MODEL_IMPORT \n 00060 CTA_MODEL_EXPORT \n 00061 CTA_MODEL_GET_STATESCALING 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 model class call CTA_Model_Create() in the 00066 same way as creating a CTA_Model 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_Model usrmodel; //user model object 00072 CTA_Handle userdata = CTA_NULL; 00073 CTA_Model_Create(my_own_model_class, &userdata, &usrmodel); 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 themselves.\n\n 00078 */ 00079 00080 00081 //#define CTA_MODEL_CREATE_SIZE 00082 /** \brief Implementation that forms part of the create process. 00083 * 00084 * Must give the memory size of a new user model object. 00085 * 00086 * Example: 00087 * \code 00088 //in header file: 00089 typedef struct { 00090 //your own user object data goes here... 00091 }USR_MODEL; 00092 00093 //user implementation: 00094 void usr_model_create_size(...){ 00095 *memsize = sizeof(USR_MODEL); 00096 *retval = CTA_OK; 00097 } 00098 \endcode 00099 * 00100 * \note At index CTA_MODEL_CREATE_SIZE in the function list of the class descriptor. 00101 * 00102 * \param userdata IO pointer to user data 00103 * \param memsize O must receive the number of bytes which are necessary to store one 00104 user method 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_model_create_size(void *userdata, int *memsize, int *retval); 00110 00111 00112 //#define CTA_MODEL_CREATE_INIT 00113 /** \brief Implementation that forms part of the create process. 00114 * 00115 * The user model object needs to be made ready for use. 00116 * 00117 * \note At index CTA_MODEL_CREATE_INIT in the function list of the class descriptor. 00118 * 00119 * \param hmodel I handle of own model instance 00120 * \param objectdata IO pointer to object data 00121 * \param userdata IO pointer to user data 00122 * \param retval O must receive return value of user implementation function 00123 * \return no return value 00124 */ 00125 void usr_model_create_init(CTA_Model *hmodel, Usr_Model *objectdata, void *userdata, int *retval); 00126 00127 00128 //#define CTA_MODEL_FREE 00129 /** \brief Implementation for freeing the object data and associated resources. 00130 * 00131 * \note At index CTA_MODEL_FREE in the function list of the class descriptor. 00132 * 00133 * \param objectdata IO pointer to object data 00134 * \param retval O must receive return value of user implementation function 00135 * \return no return value 00136 */ 00137 void usr_model_free(Usr_Model *objectdata, int *retval); 00138 00139 00140 //#define CTA_MODEL_COMPUTE 00141 /** \brief Implementation for computing a simulation of user model. A simulation is computed at the given time span. 00142 * 00143 * 00144 * 00145 * \note At index CTA_MODEL_COMPUTE in the function list of the class descriptor. 00146 * 00147 * \param objectdata IO pointer to object data 00148 * \param htime I handle of time object describing time span of simulation 00149 * \param retval O must receive return value of user implementation function 00150 * \return no return value 00151 */ 00152 void usr_model_compute(Usr_Model *objectdata, CTA_Time *htime, int *retval); 00153 00154 00155 //#define CTA_MODEL_SET_STATE 00156 /** \brief Implementation for setting model state. 00157 * 00158 * \note At index CTA_MODEL_SET_STATE in the function list of the class descriptor. 00159 * 00160 * \param objectdata IO pointer to object data 00161 * \param hstate I handle of tree-vector describing new model state 00162 * \param retval O must receive return value of user implementation function 00163 * \return no return value 00164 */ 00165 void usr_model_set_state(Usr_Model *objectdata, CTA_TreeVector *hstate, int *retval); 00166 00167 00168 //#define CTA_MODEL_GET_STATE 00169 /** \brief Implementation for getting a model state. 00170 * 00171 * \note At index CTA_MODEL_GET_STATE in the function list of the class descriptor. 00172 * 00173 * \param objectdata I pointer to object data 00174 * \param hstate O handle of tree-vector (if CTA_NULL a new object must be created and caller is responsible for freeing) that must receive model state description 00175 * \param retval O must receive return value of user implementation function 00176 * \return no return value 00177 */ 00178 void usr_model_get_state(Usr_Model *objectdata, CTA_Handle *hstate, int *retval); 00179 00180 00181 //#define CTA_MODEL_AXPY_STATE 00182 /** \brief Implementation for: modelstate=alpha*state+modelstate 00183 * 00184 * \note At index CTA_MODEL_AXPY_STATE in the function list of the class descriptor. 00185 * 00186 * \note If not implemented, a default implementation will be used. 00187 * \param objectdatay IO pointer to object data of model y 00188 * \param alpha I scalar 00189 * \param hstatex I handle of tree-vector x 00190 * \param retval O must receive return value of user implementation function 00191 * \return no return value 00192 */ 00193 void usr_model_axpy_state(Usr_Model *objectdatay, double *alpha, CTA_TreeVector *hstatex, int *retval); 00194 00195 00196 //#define CTA_MODEL_AXPY_MODEL 00197 /** \brief Implementation for: modelstatey=alpha*modelstatex+modelstatey 00198 * 00199 * \note At index CTA_MODEL_AXPY_MODEL in the function list of the class descriptor. 00200 * 00201 * \note If not implemented, a default implementation will be used. 00202 * \param alpha I scalar 00203 * \param objectdatax IO pointer to object data of model x 00204 * \param objectdatay I pointer to object data of model y 00205 * \param retval O must receive return value of user implementation function 00206 * \return no return value 00207 */ 00208 void usr_model_axpy_model(Usr_Model *objectdatay, double *alpha, Usr_Model *objectdatax, int *retval); 00209 00210 00211 //#define CTA_MODEL_SET_FORC 00212 /** \brief Implementation for setting the forcing values of the user model 00213 * 00214 * \note At index CTA_MODEL_SET_FORC in the function list of the class descriptor. 00215 * 00216 * \param objectdata IO pointer to object data 00217 * \param tspan I time span on which to set the forcing values 00218 * \param forc I handle of tree-vector object with new forcings 00219 * \param retval O must receive return value of user implementation function 00220 * \return no return value 00221 */ 00222 void usr_model_set_forc(Usr_Model *objectdata, CTA_Time *tspan, CTA_Handle *forc, int *retval); 00223 00224 00225 //#define CTA_MODEL_GET_FORC 00226 /** \brief Implementation for getting the forcing values. 00227 * 00228 * \note At index CTA_MODEL_GET_FORC in the function list of the class descriptor. 00229 * \note If forc equals CTA_NULL a new object is created, the caller is responsible for freeing it after usage 00230 * 00231 * \param objectdata I pointer to object data 00232 * \param alpha I scalar 00233 * \param forc I handle of tree-vector object that must receive forcing values (if equal to CTA_NULL, it must be created and caller is responsible for freeing) 00234 * \param retval O must receive return value of user implementation function 00235 * \return no return value 00236 */ 00237 void usr_model_get_forc(Usr_Model *objectdata, double *alpha, CTA_TreeVector *forc, int *retval); 00238 00239 00240 //#define CTA_MODEL_AXPY_FORC 00241 /** \brief Implementation for performing axpy operation on the models forcings. 00242 * 00243 * \note At index CTA_MODEL_AXPY_FORC in the function list of the class descriptor. 00244 * 00245 * \note AXPY: y=alpha*x+y. y corresponds to the models 00246 * internal forcings. 00247 * The adjustment to the forcings (alpha*x) is only valid for the given 00248 * time span. Note that the model will use y(t)+x for the given time span 00249 * where y(t) denotes the default forcings of the model. 00250 * 00251 * \param objectdata IO pointer to object data 00252 * \param tspan I handle of time span object 00253 * \param alpha I scalar 00254 * \param forc I handle of forcings x 00255 * \param retval O must receive return value of user implementation function 00256 * \return no return value 00257 */ 00258 void usr_model_axpy_forc(Usr_Model *objectdata, CTA_Time *tspan, int *alpha, CTA_TreeVector *forc, int *retval); 00259 00260 00261 //#define CTA_MODEL_SET_PARAM 00262 /** \brief Implementation for setting model parameters. 00263 * 00264 * \note At index CTA_MODEL_SET_PARAM in the function list of the class descriptor. 00265 * 00266 * \param objectdata I pointer to object data 00267 * \param hparam I handle of parameter object 00268 * \param retval O must receive return value of user implementation function 00269 * \return no return value 00270 */ 00271 void usr_model_set_param(Usr_Model *objectdata, CTA_TreeVector *hparam, int *retval); 00272 00273 00274 //#define CTA_MODEL_GET_PARAM 00275 /** \brief Implementation for getting model parameters. 00276 * 00277 * \note At index CTA_MODEL_GET_PARAM in the function list of the class descriptor. 00278 * 00279 * \param objectdata I pointer to object data 00280 * \param hparam O handle of object (if equal to CTA_NULL it must be created and caller is responsible for freeing) that must receive model parameters 00281 * \param retval O must receive return value of user implementation function 00282 * \return no return value 00283 */ 00284 void usr_model_get_param(Usr_Model *objectdata, CTA_TreeVector *hparam, int *retval); 00285 00286 00287 //#define CTA_MODEL_AXPY_PARAM 00288 /** \brief Implementation for performing axpy operation on the models parameters. 00289 * 00290 * \note At index CTA_MODEL_AXPY_PARAM in the function list of the class descriptor. 00291 * 00292 * \note AXPY: y=alpha*x+y where y corresponds to the models 00293 * internal parameters. 00294 * 00295 * \param objectdata IO pointer to object data 00296 * \param alpha I scalar 00297 * \param hparamx I handle of parameter x that is added to parameters of the model 00298 * \param retval O must receive return value of user implementation function 00299 * \return no return value 00300 */ 00301 void usr_model_axpy_param(Usr_Model *objectdata, double *alpha, CTA_TreeVector *hparamx, int *retval); 00302 00303 //#define CTA_MODEL_GET_NOISE_COUNT 00304 /** \brief Implementation for returning the number of noise parameters: 00305 * the number of columns of the noise covariance matrix. 00306 * 00307 * \note ONLY for Stochastic models. 00308 * 00309 * \param objectdata IO pointer to object data 00310 * \param nnoise O receives number of noise parameters 00311 * \param retval O error status: CTA_OK if successful 00312 */ 00313 void usr_model_get_noisecount(Usr_Model *objectdata, int *nnoise, int *retval); 00314 00315 //#define CTA_MODEL_GET_NOISE_COVAR 00316 /** \brief Implementation of returning covariance matrix of noise parameters. 00317 * 00318 * \note ONLY for Stochastic models. 00319 * The covariance matrix is represented by an array 00320 * of tree-vectors (columns of the matrix) 00321 * optionally a tree-vector is created in that case the caller of this 00322 * method is responsible for freeing that tree-vector. The input tree-vector 00323 * must be compatible (same size and or composition) as the models 00324 * internal tree-vector. 00325 * \note If hstmat[icol] == CTA_NULL a new object is created, user is responsible for freeing this object. 00326 * 00327 * \param objectdata IO pointer to object data 00328 * \param hstmat O receives array of tree-vectors, *hstmat can equal CTA_NULL on calling (see note) 00329 * \param retval O error status: CTA_OK if successful 00330 */ 00331 void usr_model_get_noisecovar(Usr_Model *objectdata, CTA_TreeVector *hstmat, int *retval); 00332 00333 //#define CTA_MODEL_GET_OBSVALUES 00334 /** \brief Implementations to get (interpolate) the models internal state to the 00335 * observations described as specified in the observation 00336 * description component. 00337 * 00338 * \note The interface supports a the time instance for time-interpolation. 00339 * It depends on the model whether and how this is supported. 00340 * 00341 * \param objectdata IO pointer to object data 00342 * \param htime I time instance (for checking and time-interpolation if 00343 * supported by model) 00344 * \param hdescr I observation description component 00345 * \param values O receives values of the models internal state corresponding to 00346 * observations as described in hdescr 00347 * \param retval O error status: CTA_OK if successful 00348 */ 00349 void usr_model_getobsvalues(Usr_Model *objectdata, CTA_Time *htime, CTA_ObsDescr *hdescr, CTA_Vector *values, int *retval); 00350 00351 //#define CTA_MODEL_GET_OBSSELECT 00352 /** \brief Implements to get a query for the stochastic observer in order to 00353 * filter out the observations that can actually be provided by the model. 00354 * 00355 * \param objectdata IO pointer to object data 00356 * \param htime I time instance 00357 * \param hdescr I observation description component 00358 * \param sselect O receives a query to filter out the observations, must exist before calling 00359 * \param retval O error status: CTA_OK if successful 00360 */ 00361 void usr_model_getobsselect(Usr_Model *objectdata, CTA_Time *htime, CTA_ObsDescr *hdescr, CTA_String *sselect, int *retval); 00362 00363 //#define CTA_MODEL_ADD_NOISE 00364 /** \brief Add noise during during the given timespan at 00365 * the Compute 00366 * 00367 * \note Noise is added in the compute-method 00368 * 00369 * \param objectdata IO pointer to object data 00370 * \param htime I timespan for which to compute adding noise 00371 * \param retval O error status: CTA_OK if successful 00372 */ 00373 void usr_model_addnoise(Usr_Model *objectdata, CTA_Time *htime, int *retval); 00374 00375 //#define CTA_MODEL_EXPORT 00376 /** \brief Implements the export the whole internal state of a model 00377 * This export function will export the whole state of the model such that 00378 * a so called "restart" start from this point yielding the same results. 00379 * There are no ruled on the format that is used to store the data. 00380 * Various extra otions are valid but a model will in most cases support an export 00381 * to a file and to a COSTA pack object. 00382 * 00383 * 00384 * \param objectdata IO pointer to object data 00385 * \param hexport I target for export e.g. CTA_File or CTA_Pack 00386 * \param retval O error status: CTA_OK if successful 00387 */ 00388 void usr_model_export(Usr_Model *objectdata, CTA_Time *hexport, int *retval); 00389 00390 //#define CTA_MODEL_IMPORT 00391 /** \brief Implements the import the whole internal state of a model 00392 * After the inport the models internal state is exactly the same as the point that 00393 * the export was created using CTA_Model_Export. 00394 * 00395 * 00396 * \param objectdata IO pointer to object data 00397 * \param himport I handle with data created by CTA_MODEL_Export e.g. CTA_File or CTA_Pack 00398 * \param retval O error status: CTA_OK if successful 00399 */ 00400 void usr_model_import(Usr_Model *objectdata, CTA_Time *himport, int *retval); 00401 00402 00403 //#define cta_model_get_statescaling 00404 /** \brief implements the return of an element wise scaling vector for the 00405 * model state (method cta_model_getstatescaling) 00406 * 00407 * 00408 * \param objectdata io pointer to object data 00409 * \param hscale o tree-vector containing scaling vector. is created 00410 * when hscale==cta_null on input 00411 * \param retval o error status: cta_ok if successful 00412 */ 00413 void usr_model_getstatescaling(Usr_Model *objectdata, CTA_TreeVector *hscale, int *retval); 00414 00415 //#define CTA_MODEL_GETCURRENTTIME 00416 /** \brief implements the return of the current time of the model instance 00417 * (method CTA_Model_GetCurrentTime) 00418 * 00419 * 00420 * \param objectdata io pointer to object data 00421 * \param tCurrent o Current time of the model instance 00422 * \param retval o error status: cta_ok if successful 00423 */ 00424 void usr_model_getcurrenttime(Usr_Model *objectdata, int* tCurrent, int* retval); 00425 00426 //#define CTA_MODEL_GETTIMEHORIZON 00427 /** \brief implements the return of the time horizon of the model instance 00428 * (method CTA_Model_GetTimeHorizon) 00429 * 00430 * 00431 * \param objectdata io pointer to object data 00432 * \param tCurrent o Time horizon of the model instance 00433 * \param retval o error status: cta_ok if successful 00434 */ 00435 void usr_model_gettimehorizon(Usr_Model *objectdata, int* tHorizon, int* retval); 00436 00437