cta_usr_model.h

Go to the documentation of this file.
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 

Generated on Mon Apr 6 14:05:58 2009 for COSTA by  doxygen 1.5.2