cta_usr_vector.h File Reference

In this file a description is given of the interface of user vector functions. When creating your own vector class use the following as template. More...

Go to the source code of this file.

Defines
#define	CTA_VECTOR_CREATE_SIZE ( 1)
#define	CTA_VECTOR_CREATE_INIT ( 2)
#define	CTA_VECTOR_GETVALS ( 3)
#define	CTA_VECTOR_SETVALS ( 4)
#define	CTA_VECTOR_SETCONST ( 5)
#define	CTA_VECTOR_SCAL ( 6)
#define	CTA_VECTOR_COPY ( 7)
#define	CTA_VECTOR_AXPY ( 8)
#define	CTA_VECTOR_DOT ( 9)
#define	CTA_VECTOR_NRM2 (10)
#define	CTA_VECTOR_AMAX (11)
#define	CTA_VECTOR_GETMAXLEN (12)
#define	CTA_VECTOR_FREE (13)
#define	CTA_VECTOR_GETVAL (14)
#define	CTA_VECTOR_SETVAL (15)
#define	CTA_VECTOR_EXPORT (16)
#define	CTA_VECTOR_PRINT_TABLE (17)
#define	CTA_VECTOR_APPENDVAL (18)
#define	CTA_VECTOR_ELMDIV (19)
#define	CTA_VECTOR_IMPORT (20)
#define	CTA_VECTOR_NUMFUNC (21)
Functions
void	usr_vector_create_size (int n, CTA_Datatype datatype, void userdata, int retval, int *memsize)
	Implementation that forms part of the create process.
void	usr_vector_create_init (Usr_Vector objectdata, int n, CTA_Datatype datatype, void userdata, int *retval)
	Implementation that forms part of the create process.
void	usr_vector_getvals (Usr_Vector x, void vals, int n, CTA_Datatype datatype, void userdata, int retval)
	Implementation for retrieving all values of the user vector.
void	usr_vector_setvals (Usr_Vector x, void vals, int n, CTA_Datatype datatype, void userdata, int retval)
	Implementation for setting all values of the user vector.
void	usr_vector_setconst (Usr_Vector x, void val, CTA_Datatype datatype, void userdata, int *retval)
	Implementation for setting all values of user vector to same value.
void	usr_vector_scal (Usr_Vector x, double alpha, void userdata, int retval)
	Implementation for scaling the user vector: x=ax.
void	usr_vector_copy (Usr_Vector x, Usr_Vector y, void userdata, int retval)
	Implementation for copying the user vector.
void	usr_vector_axpy (Usr_Vector y, double alpha, Usr_Vector x, void userdata, int *retval)
	Implementation for applying the BLAS operation axpy: y=y+ax.
void	usr_vector_dot (Usr_Vector x, Usr_Vector y, void userdata, double dotprod, int *retval)
	Implementation for calculating the dot product of two user vectors x.y.
void	usr_vector_nrm2 (Usr_Vector x, void userdata, double norm2, int retval)
	Implementation for calculating the 2-norm of a user vector.
void	usr_vector_amax (Usr_Vector x, void userdata, int iloc, int retval)
	Implementation for getting the index of the element with the largest maximum value. First index is 1.
void	usr_vector_getmaxlen (Usr_Vector x, void userdata, int maxlen, int retval)
	Implementation for getting the maximum length in case of vector with string elements.
void	usr_vector_free (Usr_Vector x, void userdata, int *retval)
	Implementation for freeing the user vector.
void	usr_vector_getval (Usr_Vector x, int i, void val, CTA_Datatype datatype, void userdata, int retval)
	Implementation for retrieving a single value of user vector at given index.
void	usr_vector_setval (Usr_Vector x, int i, void val, CTA_Datatype datatype, void userdata, int retval)
	Implementation for setting a single value of a user vector.
void	usr_vector_export (Usr_Vector x, void userdata, int retval)
	Implementation for exporting a user vector.
void	usr_vector_print_table (Usr_Vector *table, int ncolumns, Usr_Vector formats, int retval)
	Implementation for printing a table.
void	usr_vector_appendval (Usr_Vector x, void val, CTA_Datatype datatype, int retval)
	Implementation for appending a single value to the user vector.
void	usr_vector_elmdiv (Usr_Vector y, CTAI_Vector_blas x, void userdata, int retval)
	Implementation for element-wise division of user vector.
void	usr_vector_import (Usr_Vector x, void userdata, int retval)
	Implementation for importing a user vector.

Detailed Description

In this file a description is given of the interface of user vector functions. When creating your own vector class use the following as template.

The Usr_Vector to which is being referred in this template can be substituted by your own user vector object.

Step 1: for creating your own user vector class call the function CTA_Vector_DefineClass().

Example:

typedef CTA_Handle CTA_VectorClass;

CTA_Func h_func[CTA_VECTOR_NUMFUNC];
CTA_VectorClass my_own_vector_class;

ierr=CTA_Func_Create(" ",&usr_vector_create_size, hintf, &h_func[CTA_VECTOR_CREATE_SIZE]);
//...for all implementation functions...

CTA_Vector_DefineClass("classname", h_func, &my_own_vector_class);

Making a user vector class involves the implementation of the following functions:

CTA_VECTOR_CREATE_SIZE CTA_VECTOR_CREATE_INIT CTA_VECTOR_GETVALS CTA_VECTOR_SETVALS CTA_VECTOR_SETCONST CTA_VECTOR_SCAL CTA_VECTOR_COPY CTA_VECTOR_AXPY CTA_VECTOR_DOT CTA_VECTOR_NRM2 CTA_VECTOR_AMAX CTA_VECTOR_GETMAXLEN CTA_VECTOR_FREE CTA_VECTOR_GETVAL CTA_VECTOR_SETVAL CTA_VECTOR_EXPORT CTA_VECTOR_PRINT_TABLE CTA_VECTOR_APPENDVAL CTA_VECTOR_ELMDIV CTA_VECTOR_IMPORT

For creating an implementation function see documentation of CTA_Func_Create().

Step 2: to create an object of the newly defined vector class call CTA_Vector_Create() in the same way as creating a CTA_Vector but with a different class handle, i.e. the user class handle from step 1 above.

Example:

Usr_Vector usrvec; //user vector object
int nelements = 10;
CTA_Datatype datatype = CTAI_String2Type("CTA_STRING");
CTA_Handle userdata = CTA_NULL;
CTA_Vector_Create(my_own_vector_class, nelements, datatype, &userdata, &usrvec);

Note 1: with object data is meant only the object itself including pointer(s) to its contents, but not the contents of the vector.

Note 2: vector indices start from 1.

Definition in file cta_usr_vector.h.

Define Documentation

#define CTA_VECTOR_AMAX (11)

Definition at line 31 of file cta_usr_vector.h.

#define CTA_VECTOR_APPENDVAL (18)

Definition at line 38 of file cta_usr_vector.h.

#define CTA_VECTOR_AXPY ( 8)

Definition at line 28 of file cta_usr_vector.h.

#define CTA_VECTOR_COPY ( 7)

Definition at line 27 of file cta_usr_vector.h.

#define CTA_VECTOR_CREATE_INIT ( 2)

Definition at line 22 of file cta_usr_vector.h.

#define CTA_VECTOR_CREATE_SIZE ( 1)

Definition at line 21 of file cta_usr_vector.h.

#define CTA_VECTOR_DOT ( 9)

Definition at line 29 of file cta_usr_vector.h.

#define CTA_VECTOR_ELMDIV (19)

Definition at line 39 of file cta_usr_vector.h.

#define CTA_VECTOR_EXPORT (16)

Definition at line 36 of file cta_usr_vector.h.

#define CTA_VECTOR_FREE (13)

Definition at line 33 of file cta_usr_vector.h.

#define CTA_VECTOR_GETMAXLEN (12)

Definition at line 32 of file cta_usr_vector.h.

#define CTA_VECTOR_GETVAL (14)

Definition at line 34 of file cta_usr_vector.h.

#define CTA_VECTOR_GETVALS ( 3)

Definition at line 23 of file cta_usr_vector.h.

#define CTA_VECTOR_IMPORT (20)

Definition at line 40 of file cta_usr_vector.h.

#define CTA_VECTOR_NRM2 (10)

Definition at line 30 of file cta_usr_vector.h.

#define CTA_VECTOR_NUMFUNC (21)

Definition at line 41 of file cta_usr_vector.h.

#define CTA_VECTOR_PRINT_TABLE (17)

Definition at line 37 of file cta_usr_vector.h.

#define CTA_VECTOR_SCAL ( 6)

Definition at line 26 of file cta_usr_vector.h.

#define CTA_VECTOR_SETCONST ( 5)

Definition at line 25 of file cta_usr_vector.h.

#define CTA_VECTOR_SETVAL (15)

Definition at line 35 of file cta_usr_vector.h.

#define CTA_VECTOR_SETVALS ( 4)

Definition at line 24 of file cta_usr_vector.h.

Function Documentation

void usr_vector_amax	(	Usr_Vector *	x,
		void *	userdata,
		int *	iloc,
		int *	retval
	)

Implementation for getting the index of the element with the largest maximum value. First index is 1.

Note:: At index CTA_VECTOR_AMAX in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of user vector
	userdata	IO user data
	iloc	O must receive index of maximum value
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_appendval	(	Usr_Vector *	x,
		void *	val,
		CTA_Datatype *	datatype,
		int *	retval
	)

Implementation for appending a single value to the user vector.

Note:: At index CTA_VECTOR_APPENDVAL in the function list of the class descriptor.

Parameters:

	x	IO pointer to object data of user vector
	val	I value to append
	datatype	I data type of value to append, must be the same as data type of user vector x
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_axpy	(	Usr_Vector *	y,
		double *	alpha,
		Usr_Vector *	x,
		void *	userdata,
		int *	retval
	)

Implementation for applying the BLAS operation axpy: y=y+ax.

Note:: At index CTA_VECTOR_AXPY in the function list of the class descriptor.

Parameters:

	y	IO pointer to object data of user vector y; must exist before calling
	alpha	I scaling factor
	x	I pointer to object data of user vector x
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_copy	(	Usr_Vector *	x,
		Usr_Vector *	y,
		void *	userdata,
		int *	retval
	)

Implementation for copying the user vector.

Note:: At index CTA_VECTOR_COPY in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of a user vector
	y	O pointer to object data of user vector y that must receive copy of x; must exist before calling
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_create_init	(	Usr_Vector *	objectdata,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation that forms part of the create process.

The user vector object needs to be made ready for use.

Note:: At index CTA_VECTOR_CREATE_INIT in the function list of the class descriptor.

Parameters:

	objectdata	IO pointer to object data of user vector
	n	I size of vector data
	datatype	I data type of the vector elements
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_create_size	(	int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval,
		int *	memsize
	)

Implementation that forms part of the create process.

Must give the memory size of a new object.

Example:

//in header file:
typedef struct {
   //your own user object data goes here...
}USR_VECTOR;

//user implementation:
void usr_vector_create_size(...){
   *memsize = sizeof(USR_VECTOR);
   *retval = CTA_OK;
}

Note:: At index CTA_VECTOR_CREATE_SIZE in the function list of the class descriptor.

Parameters:

	n	I dimension
	datatype	I data type of the vector elements
	userdata	IO user data
	retval	O must receive return value of user implementation function
	memsize	O must receive the number of bytes which are necessary to store one user vector class, with a pointer to the contents (data), but without the contents themselves

Returns:: no return value

void usr_vector_dot	(	Usr_Vector *	x,
		Usr_Vector *	y,
		void *	userdata,
		double *	dotprod,
		int *	retval
	)

Implementation for calculating the dot product of two user vectors x.y.

Note:: At index CTA_VECTOR_DOT in the function list of the class descriptor.

Parameters:

	y	I pointer to object data of user vector y
	x	I pointer to object data of user vector x
	userdata	IO user data
	dotprod	O must receive the dot product
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_elmdiv	(	Usr_Vector *	y,
		CTAI_Vector_blas *	x,
		void *	userdata,
		int *	retval
	)

Implementation for element-wise division of user vector.

Note:: At index CTA_VECTOR_ELMDIV in the function list of the class descriptor.

Parameters:

	y	IO pointer to object data of receiving user vector
	x	I pointer to object data of user vector x
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_export	(	Usr_Vector *	x,
		void	userdata,
		int *	retval
	)

Implementation for exporting a user vector.

Note:: At index CTA_VECTOR_EXPORT in the function list of the class descriptor.
For example implementation for exporting a user vector to a pack object or to screen.

Parameters:

	x	I pointer to object data of user vector
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_free	(	Usr_Vector *	x,
		void *	userdata,
		int *	retval
	)

Implementation for freeing the user vector.

Note:: At index CTA_VECTOR_FREE in the function list of the class descriptor.

Parameters:

	x	IO pointer to object data of user vector
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_getmaxlen	(	Usr_Vector *	x,
		void *	userdata,
		int *	maxlen,
		int *	retval
	)

Implementation for getting the maximum length in case of vector with string elements.

Note:: At index CTA_VECTOR_GETMAXLEN in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of user vector
	userdata	IO user data
	maxlen	O must receive maximum length
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_getval	(	Usr_Vector *	x,
		int *	i,
		void *	val,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for retrieving a single value of user vector at given index.

Note:: At index CTA_VECTOR_GETVAL in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of user vector
	i	I index of value to retrieve
	val	O must receive value; must exist before calling
	datatype	I data type of *val, must be the same as data type of user vector x
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_getvals	(	Usr_Vector *	x,
		void *	vals,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for retrieving all values of the user vector.

Note:: At index CTA_VECTOR_GETVALS in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of the user vector
	vals	O must receive the values of the user vector
	n	I number of elements in the vals buffer, must equal number of elements in user vector
	datatype	I data type of elements of vals, must be the same as data type of user vector x
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_import	(	Usr_Vector *	x,
		void	userdata,
		int *	retval
	)

Implementation for importing a user vector.

Note:: At index CTA_VECTOR_IMPORT in the function list of the class descriptor.

Parameters:

	x	O pointer to object data of user vector that must receive import result
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_nrm2	(	Usr_Vector *	x,
		void *	userdata,
		double *	norm2,
		int *	retval
	)

Implementation for calculating the 2-norm of a user vector.

Note:: At index CTA_VECTOR_NRM2 in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of user vector
	userdata	IO user data
	norm2	O must receive the 2-norm
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_print_table	(	Usr_Vector **	table,
		int *	ncolumns,
		Usr_Vector *	formats,
		int *	retval
	)

Implementation for printing a table.

Note:: At index CTA_VECTOR_PRINT_TABLE in the function list of the class descriptor.

Parameters:

	table	IO array of vectors that forms the table to be filled
	ncolumns	I number of columns
	formats	I user vector
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_scal	(	Usr_Vector *	x,
		double *	alpha,
		void *	userdata,
		int *	retval
	)

Implementation for scaling the user vector: x=ax.

Note:: At index CTA_VECTOR_SCAL in the function list of the class descriptor.

Parameters:

	x	IO pointer to object data of user vector
	alpha	I scaling factor
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_setconst	(	Usr_Vector *	x,
		void *	val,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for setting all values of user vector to same value.

Note:: At index CTA_VECTOR_SETCONST in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of user vector
	val	I value to set vector elements to
	datatype	I data type of elements of vals, must be the same as data type of user vector x
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_setval	(	Usr_Vector *	x,
		int *	i,
		void *	val,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for setting a single value of a user vector.

Note:: At index CTA_VECTOR_SETVAL in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of user vector
	i	I index of value to set
	val	I new data of value
	datatype	I data type of *val, must be the same as data type of user vector x
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

void usr_vector_setvals	(	Usr_Vector *	x,
		void *	vals,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for setting all values of the user vector.

Note:: At index CTA_VECTOR_SETVALS in the function list of the class descriptor.

Parameters:

	x	I pointer to object data of user vector
	vals	I new values
	n	I number of elements in the vals buffer, must equal number of elements in user vector
	datatype	I data type of elements of vals, must be the same as data type of user vector x
	userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:: no return value

cta_usr_vector.h File Reference

Defines

Functions

Detailed Description

Define Documentation

Function Documentation