In this file a description is given of the interface of user model functions. When creating your own user model class use the following as template. More...
Go to the source code of this file.
Functions | |
void | usr_model_create_size (void *userdata, int *memsize, int *retval) |
Implementation that forms part of the create process. | |
void | usr_model_create_init (CTA_Model *hmodel, Usr_Model *objectdata, void *userdata, int *retval) |
Implementation that forms part of the create process. | |
void | usr_model_free (Usr_Model *objectdata, int *retval) |
Implementation for freeing the object data and associated resources. | |
void | usr_model_compute (Usr_Model *objectdata, CTA_Time *htime, int *retval) |
Implementation for computing a simulation of user model. A simulation is computed at the given time span. | |
void | usr_model_set_state (Usr_Model *objectdata, CTA_TreeVector *hstate, int *retval) |
Implementation for setting model state. | |
void | usr_model_get_state (Usr_Model *objectdata, CTA_Handle *hstate, int *retval) |
Implementation for getting a model state. | |
void | usr_model_axpy_state (Usr_Model *objectdatay, double *alpha, CTA_TreeVector *hstatex, int *retval) |
Implementation for: modelstate=alpha*state+modelstate. | |
void | usr_model_axpy_model (Usr_Model *objectdatay, double *alpha, Usr_Model *objectdatax, int *retval) |
Implementation for: modelstatey=alpha*modelstatex+modelstatey. | |
void | usr_model_set_forc (Usr_Model *objectdata, CTA_Time *tspan, CTA_Handle *forc, int *retval) |
Implementation for setting the forcing values of the user model. | |
void | usr_model_get_forc (Usr_Model *objectdata, double *alpha, CTA_TreeVector *forc, int *retval) |
Implementation for getting the forcing values. | |
void | usr_model_axpy_forc (Usr_Model *objectdata, CTA_Time *tspan, int *alpha, CTA_TreeVector *forc, int *retval) |
Implementation for performing axpy operation on the models forcings. | |
void | usr_model_set_param (Usr_Model *objectdata, CTA_TreeVector *hparam, int *retval) |
Implementation for setting model parameters. | |
void | usr_model_get_param (Usr_Model *objectdata, CTA_TreeVector *hparam, int *retval) |
Implementation for getting model parameters. | |
void | usr_model_axpy_param (Usr_Model *objectdata, double *alpha, CTA_TreeVector *hparamx, int *retval) |
Implementation for performing axpy operation on the models parameters. | |
void | usr_model_get_noisecount (Usr_Model *objectdata, int *nnoise, int *retval) |
Implementation for returning the number of noise parameters: the number of columns of the noise covariance matrix. | |
void | usr_model_get_noisecovar (Usr_Model *objectdata, CTA_TreeVector *hstmat, int *retval) |
Implementation of returning covariance matrix of noise parameters. | |
void | usr_model_getobsvalues (Usr_Model *objectdata, CTA_Time *htime, CTA_ObsDescr *hdescr, CTA_Vector *values, int *retval) |
Implementations to get (interpolate) the models internal state to the observations described as specified in the observation description component. | |
void | usr_model_getobsselect (Usr_Model *objectdata, CTA_Time *htime, CTA_ObsDescr *hdescr, CTA_String *sselect, int *retval) |
Implements to get a query for the stochastic observer in order to filter out the observations that can actually be provided by the model. | |
void | usr_model_addnoise (Usr_Model *objectdata, CTA_Time *htime, int *retval) |
Add noise during during the given timespan at the Compute. | |
void | usr_model_export (Usr_Model *objectdata, CTA_Time *hexport, int *retval) |
Implements the export the whole internal state of a model This export function will export the whole state of the model such that a so called "restart" start from this point yielding the same results. There are no ruled on the format that is used to store the data. Various extra otions are valid but a model will in most cases support an export to a file and to a COSTA pack object. | |
void | usr_model_import (Usr_Model *objectdata, CTA_Time *himport, int *retval) |
Implements the import the whole internal state of a model After the inport the models internal state is exactly the same as the point that the export was created using CTA_Model_Export. | |
void | usr_model_getstatescaling (Usr_Model *objectdata, CTA_TreeVector *hscale, int *retval) |
implements the return of an element wise scaling vector for the model state (method cta_model_getstatescaling) | |
void | usr_model_getcurrenttime (Usr_Model *objectdata, int *tCurrent, int *retval) |
implements the return of the current time of the model instance (method CTA_Model_GetCurrentTime) | |
void | usr_model_gettimehorizon (Usr_Model *objectdata, int *tHorizon, int *retval) |
implements the return of the time horizon of the model instance (method CTA_Model_GetTimeHorizon) |
In this file a description is given of the interface of user model functions. When creating your own user model class use the following as template.
The Usr_Model to which is being referred in this template can be substituted by your own user model object.
Step 1: for creating your own user model class call the function CTA_Model_DefineClass().
Example:
typedef CTA_Handle CTA_ModelClass; CTA_Func h_func[CTA_MODEL_NUMFUNC]; CTA_ModelClass my_own_model_class; ierr=CTA_Func_Create(" ",&usr_model_create_size, hintf, &h_func[I_CTA_MODEL_CREATE_SIZE]); //...for all implementation functions... CTA_Model_DefineClass("classname", h_func, &my_own_model_class);
Making a user method class involves the implementation of the following functions:
CTA_MODEL_CREATE_SIZE
CTA_MODEL_CREATE_INIT
CTA_MODEL_FREE
CTA_MODEL_COMPUTE
CTA_MODEL_SET_STATE
CTA_MODEL_GET_STATE
CTA_MODEL_AXPY_STATE
CTA_MODEL_AXPY_MODEL
CTA_MODEL_SET_FORC
CTA_MODEL_GET_FORC
CTA_MODEL_AXPY_FORC
CTA_MODEL_SET_PARAM
CTA_MODEL_GET_PARAM
CTA_MODEL_AXPY_PARAM
CTA_MODEL_IMPORT
CTA_MODEL_EXPORT
CTA_MODEL_GET_STATESCALING
For creating an implementation function see documentation of CTA_Func_Create().
Step 2: to create an object of the newly defined model class call CTA_Model_Create() in the same way as creating a CTA_Model object but with a different class handle, i.e. the user class handle from step 1 above.
Example:
Usr_Model usrmodel; //user model object CTA_Handle userdata = CTA_NULL; CTA_Model_Create(my_own_model_class, &userdata, &usrmodel);
Note 1: with object data is meant only the object itself including pointer(s) to its contents, but not the contents themselves.
Definition in file cta_usr_model.h.
void usr_model_addnoise | ( | Usr_Model * | objectdata, | |
CTA_Time * | htime, | |||
int * | retval | |||
) |
Add noise during during the given timespan at the Compute.
objectdata | IO pointer to object data | |
htime | I timespan for which to compute adding noise | |
retval | O error status: CTA_OK if successful |
void usr_model_axpy_forc | ( | Usr_Model * | objectdata, | |
CTA_Time * | tspan, | |||
int * | alpha, | |||
CTA_TreeVector * | forc, | |||
int * | retval | |||
) |
Implementation for performing axpy operation on the models forcings.
objectdata | IO pointer to object data | |
tspan | I handle of time span object | |
alpha | I scalar | |
forc | I handle of forcings x | |
retval | O must receive return value of user implementation function |
void usr_model_axpy_model | ( | Usr_Model * | objectdatay, | |
double * | alpha, | |||
Usr_Model * | objectdatax, | |||
int * | retval | |||
) |
Implementation for: modelstatey=alpha*modelstatex+modelstatey.
alpha | I scalar | |
objectdatax | IO pointer to object data of model x | |
objectdatay | I pointer to object data of model y | |
retval | O must receive return value of user implementation function |
void usr_model_axpy_param | ( | Usr_Model * | objectdata, | |
double * | alpha, | |||
CTA_TreeVector * | hparamx, | |||
int * | retval | |||
) |
Implementation for performing axpy operation on the models parameters.
objectdata | IO pointer to object data | |
alpha | I scalar | |
hparamx | I handle of parameter x that is added to parameters of the model | |
retval | O must receive return value of user implementation function |
void usr_model_axpy_state | ( | Usr_Model * | objectdatay, | |
double * | alpha, | |||
CTA_TreeVector * | hstatex, | |||
int * | retval | |||
) |
Implementation for: modelstate=alpha*state+modelstate.
objectdatay | IO pointer to object data of model y | |
alpha | I scalar | |
hstatex | I handle of tree-vector x | |
retval | O must receive return value of user implementation function |
void usr_model_compute | ( | Usr_Model * | objectdata, | |
CTA_Time * | htime, | |||
int * | retval | |||
) |
Implementation for computing a simulation of user model. A simulation is computed at the given time span.
objectdata | IO pointer to object data | |
htime | I handle of time object describing time span of simulation | |
retval | O must receive return value of user implementation function |
void usr_model_create_init | ( | CTA_Model * | hmodel, | |
Usr_Model * | objectdata, | |||
void * | userdata, | |||
int * | retval | |||
) |
Implementation that forms part of the create process.
The user model object needs to be made ready for use.
hmodel | I handle of own model instance | |
objectdata | IO pointer to object data | |
userdata | IO pointer to user data | |
retval | O must receive return value of user implementation function |
void usr_model_create_size | ( | void * | userdata, | |
int * | memsize, | |||
int * | retval | |||
) |
Implementation that forms part of the create process.
Must give the memory size of a new user model object.
Example:
//in header file: typedef struct { //your own user object data goes here... }USR_MODEL; //user implementation: void usr_model_create_size(...){ *memsize = sizeof(USR_MODEL); *retval = CTA_OK; }
userdata | IO pointer to user data | |
memsize | O must receive the number of bytes which are necessary to store one user method class, with a pointer to the contents (data), but without the contents themselves | |
retval | O must receive return value of user implementation function |
void usr_model_export | ( | Usr_Model * | objectdata, | |
CTA_Time * | hexport, | |||
int * | retval | |||
) |
Implements the export the whole internal state of a model This export function will export the whole state of the model such that a so called "restart" start from this point yielding the same results. There are no ruled on the format that is used to store the data. Various extra otions are valid but a model will in most cases support an export to a file and to a COSTA pack object.
objectdata | IO pointer to object data | |
hexport | I target for export e.g. CTA_File or CTA_Pack | |
retval | O error status: CTA_OK if successful |
void usr_model_free | ( | Usr_Model * | objectdata, | |
int * | retval | |||
) |
Implementation for freeing the object data and associated resources.
objectdata | IO pointer to object data | |
retval | O must receive return value of user implementation function |
void usr_model_get_forc | ( | Usr_Model * | objectdata, | |
double * | alpha, | |||
CTA_TreeVector * | forc, | |||
int * | retval | |||
) |
Implementation for getting the forcing values.
objectdata | I pointer to object data | |
alpha | I scalar | |
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) | |
retval | O must receive return value of user implementation function |
void usr_model_get_noisecount | ( | Usr_Model * | objectdata, | |
int * | nnoise, | |||
int * | retval | |||
) |
Implementation for returning the number of noise parameters: the number of columns of the noise covariance matrix.
objectdata | IO pointer to object data | |
nnoise | O receives number of noise parameters | |
retval | O error status: CTA_OK if successful |
void usr_model_get_noisecovar | ( | Usr_Model * | objectdata, | |
CTA_TreeVector * | hstmat, | |||
int * | retval | |||
) |
Implementation of returning covariance matrix of noise parameters.
objectdata | IO pointer to object data | |
hstmat | O receives array of tree-vectors, *hstmat can equal CTA_NULL on calling (see note) | |
retval | O error status: CTA_OK if successful |
void usr_model_get_param | ( | Usr_Model * | objectdata, | |
CTA_TreeVector * | hparam, | |||
int * | retval | |||
) |
Implementation for getting model parameters.
objectdata | I pointer to object data | |
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 | |
retval | O must receive return value of user implementation function |
void usr_model_get_state | ( | Usr_Model * | objectdata, | |
CTA_Handle * | hstate, | |||
int * | retval | |||
) |
Implementation for getting a model state.
objectdata | I pointer to object data | |
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 | |
retval | O must receive return value of user implementation function |
void usr_model_getcurrenttime | ( | Usr_Model * | objectdata, | |
int * | tCurrent, | |||
int * | retval | |||
) |
implements the return of the current time of the model instance (method CTA_Model_GetCurrentTime)
objectdata | io pointer to object data | |
tCurrent | o Current time of the model instance | |
retval | o error status: cta_ok if successful |
void usr_model_getobsselect | ( | Usr_Model * | objectdata, | |
CTA_Time * | htime, | |||
CTA_ObsDescr * | hdescr, | |||
CTA_String * | sselect, | |||
int * | retval | |||
) |
Implements to get a query for the stochastic observer in order to filter out the observations that can actually be provided by the model.
objectdata | IO pointer to object data | |
htime | I time instance | |
hdescr | I observation description component | |
sselect | O receives a query to filter out the observations, must exist before calling | |
retval | O error status: CTA_OK if successful |
void usr_model_getobsvalues | ( | Usr_Model * | objectdata, | |
CTA_Time * | htime, | |||
CTA_ObsDescr * | hdescr, | |||
CTA_Vector * | values, | |||
int * | retval | |||
) |
Implementations to get (interpolate) the models internal state to the observations described as specified in the observation description component.
objectdata | IO pointer to object data | |
htime | I time instance (for checking and time-interpolation if supported by model) | |
hdescr | I observation description component | |
values | O receives values of the models internal state corresponding to observations as described in hdescr | |
retval | O error status: CTA_OK if successful |
void usr_model_getstatescaling | ( | Usr_Model * | objectdata, | |
CTA_TreeVector * | hscale, | |||
int * | retval | |||
) |
implements the return of an element wise scaling vector for the model state (method cta_model_getstatescaling)
objectdata | io pointer to object data | |
hscale | o tree-vector containing scaling vector. is created when hscale==cta_null on input | |
retval | o error status: cta_ok if successful |
void usr_model_gettimehorizon | ( | Usr_Model * | objectdata, | |
int * | tHorizon, | |||
int * | retval | |||
) |
implements the return of the time horizon of the model instance (method CTA_Model_GetTimeHorizon)
objectdata | io pointer to object data | |
tCurrent | o Time horizon of the model instance | |
retval | o error status: cta_ok if successful |
void usr_model_import | ( | Usr_Model * | objectdata, | |
CTA_Time * | himport, | |||
int * | retval | |||
) |
Implements the import the whole internal state of a model After the inport the models internal state is exactly the same as the point that the export was created using CTA_Model_Export.
objectdata | IO pointer to object data | |
himport | I handle with data created by CTA_MODEL_Export e.g. CTA_File or CTA_Pack | |
retval | O error status: CTA_OK if successful |
void usr_model_set_forc | ( | Usr_Model * | objectdata, | |
CTA_Time * | tspan, | |||
CTA_Handle * | forc, | |||
int * | retval | |||
) |
Implementation for setting the forcing values of the user model.
objectdata | IO pointer to object data | |
tspan | I time span on which to set the forcing values | |
forc | I handle of tree-vector object with new forcings | |
retval | O must receive return value of user implementation function |
void usr_model_set_param | ( | Usr_Model * | objectdata, | |
CTA_TreeVector * | hparam, | |||
int * | retval | |||
) |
Implementation for setting model parameters.
objectdata | I pointer to object data | |
hparam | I handle of parameter object | |
retval | O must receive return value of user implementation function |
void usr_model_set_state | ( | Usr_Model * | objectdata, | |
CTA_TreeVector * | hstate, | |||
int * | retval | |||
) |
Implementation for setting model state.
objectdata | IO pointer to object data | |
hstate | I handle of tree-vector describing new model state | |
retval | O must receive return value of user implementation function |