cta_usr_matrix.h File Reference

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

Go to the source code of this file.

Functions
void	usr_matrix_create_size (int *m, int *n, CTA_Datatype *datatype, void *userdata, int *retval, int *memsize)
	Implementation that forms part of the create process.
void	usr_matrix_create_init (Usr_Matrix *objectdata, int *m, int *n, CTA_Datatype *datatype, void *userdata, int *retval)
	Implementation that forms part of the create process.
void	usr_matrix_getvals (Usr_Matrix *objectdata, void *vals, int *m, int *n, CTA_Datatype *datatype, void *userdata, int *retval)
	Implementation for getting all values from the user matrix.
void	usr_matrix_getval (Usr_Matrix *objectdata, void *val, int *m, int *n, CTA_Datatype *datatype, void *userdata, int *retval)
	Implementation for getting a single value from the user matrix.
void	usr_matrix_setcol (Usr_Matrix *objectdata, int *n, CTA_Vector *hvec, int *retval)
	Implementation for setting column of user matrix.
void	usr_matrix_setvals (Usr_Matrix *objectdata, void *vals, int *m, int *n, CTA_Datatype *datatype, void *userdata, int *retval)
	Implementation for setting all values of user matrix.
void	usr_matrix_setval (Usr_Matrix *objectdata, void *val, int *m, int *n, CTA_Datatype *datatype, void *userdata, int *retval)
	Implementation for setting a single value of user matrix.
void	usr_matrix_setconst (Usr_Matrix *objectdata, void *val, CTA_Datatype *datatype, void *userdata, int *retval)
	Implementation for setting all user matrix elements to constant value.
void	usr_matrix_free (Usr_Matrix *objectdata, CTA_Handle *userdata, int *retval)
	Implementation for freeing the object data and associated resources.
void	usr_matrix_export (Usr_Matrix *objectdata, CTA_Handle *userdata, int *retval)
	Implementation for exporting user matrix.
void	usr_matrix_ger (Usr_Matrix *A, double *alpha, CTA_Vector *vx, CTA_Vector *vy, int *retval)
	Implementation for applying the BLAS operation GER: A=A+(alpha)x(y(T)).
void	usr_matrix_inv (Usr_Matrix *A, int *retval)
	Implementation for inverting user matrix.
void	usr_matrix_gemv (Usr_Matrix *A, int *trans, double *alpha, CTA_Vector *vx, double *beta, CTA_Vector *vy, int *retval)
	Implementation for applying the BLAS operation GEMV: A=(alpha)Ax+(beta)y.
void	usr_matrix_gemm (Usr_Matrix *C, int *transa, int *transb, double *alpha, Usr_Matrix *A, Usr_Matrix *B, double *beta, int *retval)
	Implementation for applying the BLAS operation GEMM: C=(alpha)AB+(beta)C.
void	usr_matrix_axpy (Usr_Matrix *y, double *alpha, Usr_Matrix *x, int *retval)
	Implementation for applying the BLAS operation AXPY: Y=Y+(alpha)X.

---

Detailed Description

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

The Usr_Matrix to which is being referred in this template can be substituted by your own user matrix.

Step 1: for creating your own user matrix class call the function CTA_Matrix_DefineClass().

Example:

typedef CTA_Handle CTA_MatrixClass;

CTA_Func h_func[CTA_MATRIX_NUMFUNC];
CTA_MatrixClass my_own_matrix_class;

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

CTA_Matrix_DefineClass("classname", h_func, &my_own_matrix_class);

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

CTA_MATRIX_CREATE_SIZE
CTA_MATRIX_CREATE_INIT
CTA_MATRIX_GETVALS
CTA_MATRIX_GETVAL
CTA_MATRIX_SETCOL
CTA_MATRIX_SETVALS
CTA_MATRIX_SETVAL
CTA_MATRIX_SETCONST
CTA_MATRIX_FREE
CTA_MATRIX_EXPORT
CTA_MATRIX_GER
CTA_MATRIX_INV
CTA_MATRIX_GEMV
CTA_MATRIX_GEMM
CTA_MATRIX_AXPY
CTA_MATRIX_NUMFUNC

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

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

Example:

Usr_Matrix usrmat; //user matrix object
int n = 10;
int m = 10;
CTA_Datatype datatype = CTAI_String2Type("CTA_STRING");
CTA_Handle userdata = CTA_NULL;
CTA_Matrix_Create(my_own_matrix_class, m, n, datatype, &userdata, &usrmat);

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

Note 2: matrix indices start from 1, m and n for rows and columns respectively.

Definition in file cta_usr_matrix.h.

---

Function Documentation

void usr_matrix_axpy	(	Usr_Matrix *	y,
		double *	alpha,
		Usr_Matrix *	x,
		int *	retval
	)

Implementation for applying the BLAS operation AXPY: Y=Y+(alpha)X.

i.e. for matrices X and Y, scalar alpha

Note:

At index CTA_MATRIX_AXPY in the function list of the class descriptor.

Parameters:

	y	IO pointer to object data of user matrix y
	alpha	I scalar
	x	I pointer to object data of user matrix x
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_create_init	(	Usr_Matrix *	objectdata,
		int *	m,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation that forms part of the create process.

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

Note:

At index CTA_MATRIX_CREATE_INIT in the function list of the class descriptor.

Parameters:

	objectdata	IO pointer to object data of user matrix
	m	I dimension, m (rows)
	n	I dimension, n (columns)
	datatype	I data type of the matrix elements
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_create_size	(	int *	m,
		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 user matrix object.

Example:

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

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

Note:

At index CTA_MATRIX_CREATE_SIZE in the function list of the class descriptor.

Parameters:

	m	I dimension, m (rows)
	n	I dimension, n (columns)
	datatype	I data type of matrix 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 matrix class, with a pointer to the contents (data), but without the contents themselves

Returns:

no return value

void usr_matrix_export	(	Usr_Matrix *	objectdata,
		CTA_Handle *	userdata,
		int *	retval
	)

Implementation for exporting user matrix.

Note:

At index CTA_MATRIX_EXPORT in the function list of the class descriptor.

Parameters:

	objectdata	I pointer to object data of user matrix
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_free	(	Usr_Matrix *	objectdata,
		CTA_Handle *	userdata,
		int *	retval
	)

Implementation for freeing the object data and associated resources.

Note:

At index CTA_MATRIX_FREE in the function list of the class descriptor.

Parameters:

	objectdata	IO pointer to object data of user matrix
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_gemm	(	Usr_Matrix *	C,
		int *	transa,
		int *	transb,
		double *	alpha,
		Usr_Matrix *	A,
		Usr_Matrix *	B,
		double *	beta,
		int *	retval
	)

Implementation for applying the BLAS operation GEMM: C=(alpha)AB+(beta)C.

i.e. for matrices A,B (both optionally transposed) and C, scalars alpha and beta

Note:

At index CTA_MATRIX_GEMM in the function list of the class descriptor.

Parameters:

	C	IO pointer to object data of user matrix C
	transa	I transpose flag for matrix A (CTA_TRUE for transposing or CTA_FALSE otherwise)
	transb	I transpose flag for matrix B (CTA_TRUE for transposing or CTA_FALSE otherwise)
	alpha	I scalar
	A	I pointer to object data of user matrix A
	B	I pointer to object data of user matrix B
	beta	I scalar
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_gemv	(	Usr_Matrix *	A,
		int *	trans,
		double *	alpha,
		CTA_Vector *	vx,
		double *	beta,
		CTA_Vector *	vy,
		int *	retval
	)

Implementation for applying the BLAS operation GEMV: A=(alpha)Ax+(beta)y.

i.e. for matrix A, vectors x (optionally transposed) and y and scalars alpha and beta

Note:

At index CTA_MATRIX_GEMV in the function list of the class descriptor.

Parameters:

	A	IO pointer to object data of user matrix
	trans	I transpose flag CTA_TRUE/CTA_FALSE for matrix A
	alpha	I scalar
	vx	I handle of vector x
	beta	I scalar
	vy	I handle of vector y
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_ger	(	Usr_Matrix *	A,
		double *	alpha,
		CTA_Vector *	vx,
		CTA_Vector *	vy,
		int *	retval
	)

Implementation for applying the BLAS operation GER: A=A+(alpha)x(y(T)).

i.e. for matrix A, vectors x and y and scalar alpha

Note:

At index CTA_MATRIX_GER in the function list of the class descriptor.

Parameters:

	A	IO pointer to object data of user matrix A; must exist before calling
	alpha	I scalar
	vx	I handle of vector x
	vy	I handle of vector y
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_getval	(	Usr_Matrix *	objectdata,
		void *	val,
		int *	m,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for getting a single value from the user matrix.

Note:

At index CTA_MATRIX_GETVAL in the function list of the class descriptor.

Parameters:

	objectdata	I pointer to object data of user matrix
	val	O must receive value; must exist before calling
	m	I row index of matrix value to get
	n	I column index of matrix value to get
	datatype	I data type of val; must be the same as data type of matrix elements
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_getvals	(	Usr_Matrix *	objectdata,
		void *	vals,
		int *	m,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for getting all values from the user matrix.

Note:

At index CTA_MATRIX_GETVALS in the function list of the class descriptor.

Parameters:

	objectdata	I pointer to object data of user matrix
	vals	O must receive values; must exist before calling
	m	I number of rows of *vals, must be the same as number of rows in matrix
	n	I number of columns of *vals, must be the same as number of columns in matrix
	datatype	I data type of value; must be the same as data type of matrix elements
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_inv	(	Usr_Matrix *	A,
		int *	retval
	)

Implementation for inverting user matrix.

Note:

At index CTA_MATRIX_INV in the function list of the class descriptor.

Parameters:

	A	IO pointer to object data of user matrix
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_setcol	(	Usr_Matrix *	objectdata,
		int *	n,
		CTA_Vector *	hvec,
		int *	retval
	)

Implementation for setting column of user matrix.

Note:

At index CTA_MATRIX_SETCOL in the function list of the class descriptor.

Parameters:

	objectdata	IO pointer to object data of user matrix
	n	I index of column to set
	hvec	I handle of sending column; dimensions must be compatible
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_setconst	(	Usr_Matrix *	objectdata,
		void *	val,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for setting all user matrix elements to constant value.

Note:

At index CTA_MATRIX_SETCONST in the function list of the class descriptor.

Parameters:

	objectdata	IO pointer to object data of user matrix
	val	I constant value to set to
	datatype	I data type of val; must be the same as data type of matrix elements
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_setval	(	Usr_Matrix *	objectdata,
		void *	val,
		int *	m,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for setting a single value of user matrix.

Note:

At index CTA_MATRIX_SETVAL in the function list of the class descriptor.

Parameters:

	objectdata	IO pointer to object data of user matrix
	val	I value to set to
	m	I row index of matrix value to set
	n	I column index of matrix value to set
	datatype	I data type of val; must be the same as data type of matrix elements
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value

void usr_matrix_setvals	(	Usr_Matrix *	objectdata,
		void *	vals,
		int *	m,
		int *	n,
		CTA_Datatype *	datatype,
		void *	userdata,
		int *	retval
	)

Implementation for setting all values of user matrix.

Note:

At index CTA_MATRIX_SETVALS in the function list of the class descriptor.

Parameters:

	objectdata	IO pointer to object data of user matrix
	vals	I values to set to
	m	I number of rows of *vals, must be the same as number of rows in matrix
	n	I number of columns of *vals, must be the same as number of columns in matrix
	datatype	I data type of value; must be the same as data type of matrix elements
	*userdata	IO user data
	retval	O must receive return value of user implementation function

Returns:

no return value