cta_usr_model.h File Reference

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)

Detailed Description

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.


Function Documentation

void usr_model_addnoise ( Usr_Model *  objectdata,
CTA_Time htime,
int *  retval 
)

Add noise during during the given timespan at the Compute.

Note:
Noise is added in the compute-method
Parameters:
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.

Note:
At index CTA_MODEL_AXPY_FORC in the function list of the class descriptor.
AXPY: y=alpha*x+y. y corresponds to the models internal forcings. The adjustment to the forcings (alpha*x) is only valid for the given time span. Note that the model will use y(t)+x for the given time span where y(t) denotes the default forcings of the model.
Parameters:
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
Returns:
no return value
void usr_model_axpy_model ( Usr_Model *  objectdatay,
double *  alpha,
Usr_Model *  objectdatax,
int *  retval 
)

Implementation for: modelstatey=alpha*modelstatex+modelstatey.

Note:
At index CTA_MODEL_AXPY_MODEL in the function list of the class descriptor.
If not implemented, a default implementation will be used.
Parameters:
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
Returns:
no return value
void usr_model_axpy_param ( Usr_Model *  objectdata,
double *  alpha,
CTA_TreeVector hparamx,
int *  retval 
)

Implementation for performing axpy operation on the models parameters.

Note:
At index CTA_MODEL_AXPY_PARAM in the function list of the class descriptor.
AXPY: y=alpha*x+y where y corresponds to the models internal parameters.
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
Returns:
no return value
void usr_model_axpy_state ( Usr_Model *  objectdatay,
double *  alpha,
CTA_TreeVector hstatex,
int *  retval 
)

Implementation for: modelstate=alpha*state+modelstate.

Note:
At index CTA_MODEL_AXPY_STATE in the function list of the class descriptor.
If not implemented, a default implementation will be used.
Parameters:
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
Returns:
no return value
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.

Note:
At index CTA_MODEL_COMPUTE in the function list of the class descriptor.
Parameters:
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
Returns:
no return value
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.

Note:
At index CTA_MODEL_CREATE_INIT in the function list of the class descriptor.
Parameters:
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
Returns:
no return value
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;
}
Note:
At index I_CTA_MODEL_CREATE_SIZE in the function list of the class descriptor.
Parameters:
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
Returns:
no return value
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.

Parameters:
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.

Note:
At index CTA_MODEL_FREE in the function list of the class descriptor.
Parameters:
objectdata IO pointer to object data
retval O must receive return value of user implementation function
Returns:
no return value
void usr_model_get_forc ( Usr_Model *  objectdata,
double *  alpha,
CTA_TreeVector forc,
int *  retval 
)

Implementation for getting the forcing values.

Note:
At index CTA_MODEL_GET_FORC in the function list of the class descriptor.
If forc equals CTA_NULL a new object is created, the caller is responsible for freeing it after usage
Parameters:
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
Returns:
no return value
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.

Note:
ONLY for Stochastic models.
Parameters:
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.

Note:
ONLY for Stochastic models. The covariance matrix is represented by an array of tree-vectors (columns of the matrix) optionally a tree-vector is created in that case the caller of this method is responsible for freeing that tree-vector. The input tree-vector must be compatible (same size and or composition) as the models internal tree-vector.
If hstmat[icol] == CTA_NULL a new object is created, user is responsible for freeing this object.
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.

Note:
At index CTA_MODEL_GET_PARAM in the function list of the class descriptor.
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
Returns:
no return value
void usr_model_get_state ( Usr_Model *  objectdata,
CTA_Handle hstate,
int *  retval 
)

Implementation for getting a model state.

Note:
At index I_CTA_MODEL_GET_STATE in the function list of the class descriptor.
Parameters:
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
Returns:
no return value
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)

Parameters:
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.

Parameters:
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.

Note:
The interface supports a the time instance for time-interpolation. It depends on the model whether and how this is supported.
Parameters:
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)

Parameters:
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)

Parameters:
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.

Parameters:
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.

Note:
At index CTA_MODEL_SET_FORC in the function list of the class descriptor.
Parameters:
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
Returns:
no return value
void usr_model_set_param ( Usr_Model *  objectdata,
CTA_TreeVector hparam,
int *  retval 
)

Implementation for setting model parameters.

Note:
At index CTA_MODEL_SET_PARAM in the function list of the class descriptor.
Parameters:
objectdata I pointer to object data
hparam I handle of parameter object
retval O must receive return value of user implementation function
Returns:
no return value
void usr_model_set_state ( Usr_Model *  objectdata,
CTA_TreeVector hstate,
int *  retval 
)

Implementation for setting model state.

Note:
At index I_CTA_MODEL_SET_STATE in the function list of the class descriptor.
Parameters:
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
Returns:
no return value

Generated on 4 Mar 2014 for OpenDA by  doxygen 1.6.1