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

cta_usr_model.h File Reference

Functions

Detailed Description

Function Documentation