cta_matrix.h File Reference

The interface description of the COSTA matrix component. For user implementation see cta_usr_matrix.h. More...

#include "cta_system.h"
#include "cta_handles.h"
#include "cta_datatypes.h"
#include "cta_functions.h"
#include "cta_vector.h"

Go to the source code of this file.

Defines
#define	CTA_MATRIX_CREATE_SIZE ( 1)
#define	CTA_MATRIX_CREATE_INIT ( 2)
#define	I_CTA_MATRIX_GETVALS ( 4)
#define	I_CTA_MATRIX_GETVAL ( 5)
#define	I_CTA_MATRIX_SETCOL ( 6)
#define	I_CTA_MATRIX_SETVALS ( 7)
#define	I_CTA_MATRIX_SETVAL ( 8)
#define	I_CTA_MATRIX_SETCONST ( 9)
#define	I_CTA_MATRIX_FREE (10)
#define	I_CTA_MATRIX_EXPORT (11)
#define	I_CTA_MATRIX_GER (12)
#define	I_CTA_MATRIX_INV (13)
#define	I_CTA_MATRIX_GEMV (14)
#define	I_CTA_MATRIX_GEMM (15)
#define	I_CTA_MATRIX_AXPY (16)
#define	CTA_MATRIX_NUMFUNC (17)
Typedefs
typedef CTA_Handle	CTA_Matrix
typedef CTA_Handle	CTA_MatClass
Functions
CTAEXPORT int	CTA_Matrix_DefineClass (const char name, const CTA_Func h_func[CTA_MATRIX_NUMFUNC], CTA_MatClass hmatcl)
	Create a new class (=implementation) of a COSTA matrix component.
CTAEXPORT int	CTA_Matrix_Duplicate (CTA_Matrix hmat1, CTA_Matrix *hmat2)
	Duplicate a matrix instance.
CTAEXPORT int	CTA_Matrix_Create (CTA_MatClass hmatcl, const int m, const int n, CTA_Datatype datatype, CTA_Handle userdata, CTA_Matrix *hmat)
	Create a new matrix.
CTAEXPORT int	CTA_Matrix_GetSize (CTA_Matrix hmat, int m, int n)
CTAEXPORT int	CTA_Matrix_GetDatatype (CTA_Matrix hmat, CTA_Datatype *datatype)
	Get datatype of matrix.
CTAEXPORT int	CTA_Matrix_GetVals (CTA_Matrix hmat, void *vals, int m, int n, CTA_Datatype datatype)
	Get copy of all values in matrix.
CTAEXPORT int	CTA_Matrix_GetVal (CTA_Matrix hmat, void *val, int m, int n, CTA_Datatype datatype)
	Get copy of single value in the matrix.
CTAEXPORT int	CTA_Matrix_SetConstant (CTA_Matrix hmat, void *val, CTA_Datatype datatype)
	Set whole matrix to one single value.
CTAEXPORT int	CTA_Matrix_SetCol (CTA_Matrix hmat, int n, CTA_Vector hvec)
	Set values of a single column of the matrix.
CTAEXPORT int	CTA_Matrix_SetVals (CTA_Matrix hmat, void *vals, int m, int n, CTA_Datatype datatype)
	Set all values of the matrix.
CTAEXPORT int	CTA_Matrix_SetVal (CTA_Matrix hmat, void *val, int m, int n, CTA_Datatype datatype)
	Set a single value in the matrix.
CTAEXPORT int	CTA_Matrix_Export (CTA_Matrix hmat, CTA_Handle usedoc)
	Export a matrix.
CTAEXPORT int	CTA_Matrix_Ger (CTA_Matrix hmat, double alpha, CTA_Vector vx, CTA_Vector vy)
	Perform a rank 1 operation A:=alphaxy'+A.
CTAEXPORT int	CTA_Matrix_Inv (CTA_Matrix hmat)
	Compute inverse of a square matrix A:=inv(A).
CTAEXPORT int	CTA_Matrix_Gemv (CTA_Matrix hmat, int trans, double alpha, CTA_Vector vx, double beta, CTA_Vector vy)
	Perform the matrix multiplication y:=alphaOP(A)x+beta*y where op(X)=X, X^T.
CTAEXPORT int	CTA_Matrix_Gemm (CTA_Matrix mC, int transa, int transb, double alpha, CTA_Matrix mA, CTA_Matrix mB, double beta)
	Perform the matrix multication C:=alphaop(A)op(B)+beta*C where op(X)=X, X^T.
CTAEXPORT int	CTA_Matrix_Axpy (CTA_Matrix mY, double alpha, CTA_Matrix mX)
	Perform the matrix addition Y:=alpha*X+Y.
CTAEXPORT int	CTA_Matrix_EigVals (CTA_Matrix A, CTA_Vector eigvals, CTA_Matrix eigvecs)
	Computes the eigenvalues and optionally the eigenvectors of a general matrix A.
CTAEXPORT int	CTA_Matrix_Free (CTA_Matrix *hmat)
	Free the matrix object.

Detailed Description

The interface description of the COSTA matrix component. For user implementation see cta_usr_matrix.h.

CTA_Matrix is the default class implementation for matrices.

Definition in file cta_matrix.h.

Define Documentation

#define CTA_MATRIX_CREATE_INIT ( 2)

Definition at line 41 of file cta_matrix.h.

#define CTA_MATRIX_CREATE_SIZE ( 1)

Definition at line 40 of file cta_matrix.h.

#define CTA_MATRIX_NUMFUNC (17)

Definition at line 55 of file cta_matrix.h.

#define I_CTA_MATRIX_AXPY (16)

Definition at line 54 of file cta_matrix.h.

#define I_CTA_MATRIX_EXPORT (11)

Definition at line 49 of file cta_matrix.h.

#define I_CTA_MATRIX_FREE (10)

Definition at line 48 of file cta_matrix.h.

#define I_CTA_MATRIX_GEMM (15)

Definition at line 53 of file cta_matrix.h.

#define I_CTA_MATRIX_GEMV (14)

Definition at line 52 of file cta_matrix.h.

#define I_CTA_MATRIX_GER (12)

Definition at line 50 of file cta_matrix.h.

#define I_CTA_MATRIX_GETVAL ( 5)

Definition at line 43 of file cta_matrix.h.

#define I_CTA_MATRIX_GETVALS ( 4)

Definition at line 42 of file cta_matrix.h.

#define I_CTA_MATRIX_INV (13)

Definition at line 51 of file cta_matrix.h.

#define I_CTA_MATRIX_SETCOL ( 6)

Definition at line 44 of file cta_matrix.h.

#define I_CTA_MATRIX_SETCONST ( 9)

Definition at line 47 of file cta_matrix.h.

#define I_CTA_MATRIX_SETVAL ( 8)

Definition at line 46 of file cta_matrix.h.

#define I_CTA_MATRIX_SETVALS ( 7)

Definition at line 45 of file cta_matrix.h.

Typedef Documentation

typedef CTA_Handle CTA_MatClass

Definition at line 37 of file cta_matrix.h.

typedef CTA_Handle CTA_Matrix

Definition at line 36 of file cta_matrix.h.

Function Documentation

CTAEXPORT int CTA_Matrix_Axpy	(	CTA_Matrix	mY,
		double	alpha,
		CTA_Matrix	mX
	)

Perform the matrix addition Y:=alpha*X+Y.

Parameters:

	mY	IO handle of matrix Y
	alpha	I scalar
	mX	I handle of matrix X

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_Create	(	CTA_MatClass	hmatcl,
		const int	m,
		const int	n,
		CTA_Datatype	datatype,
		CTA_Handle	userdata,
		CTA_Matrix *	hmat
	)

Create a new matrix.

Note:

Parameters:

	hmatcl	I matrix class of new matrix
	m	I number of rows
	n	I number of columns
	datatype	I datatype of elements in matrix
	userdata	IO userdata for creation (depends on class)
	hmat	O receives handle of new matrix

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_DefineClass	(	const char *	name,
		const CTA_Func	h_func[CTA_MATRIX_NUMFUNC],
		CTA_MatClass *	hmatcl
	)

Create a new class (=implementation) of a COSTA matrix component.

Parameters:

	name	I name of the new matrix class
	h_func	I COSTA function handles for functions that implement class, missing functions must have value CTA_NULL
	hmatcl	O receives handle of new matrix class

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_Duplicate	(	CTA_Matrix	hmat1,
		CTA_Matrix *	hmat2
	)

Duplicate a matrix instance.

Note:: Only size, data type and class type are duplicated, the values are not copied.

Parameters:

	hmat1	I handle of matrix to be duplicated
	hmat2	O receives handle of duplicate matrix, empty handle before calling

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_EigVals	(	CTA_Matrix	A,
		CTA_Vector	eigvals,
		CTA_Matrix	eigvecs
	)

Computes the eigenvalues and optionally the eigenvectors of a general matrix A.

The computed eigenvectors are normalized to have Euclidean norm equal to 1 and largest component real.

Parameters:

	A	I Matrix A
	eigvals	O Vector with eigenvalues
	eigvecs	O Matrix with eigenvalues. The eigenvectors are not computed when eigvecs in CTA_NULL on entry

Returns:: error status: CTA_OK if successful

Note:: the eigenvalues can be complex. Since COSTA does not yet support complex vectors, only the real part of the eigenvalues is returned.

CTAEXPORT int CTA_Matrix_Export	(	CTA_Matrix	hmat,
		CTA_Handle	usedoc
	)

Export a matrix.

Note:: CTA_DEFAULT_MATRIX supports exporting to:
file (usedoc is handle of COSTA file)

Parameters:

	hmat	I handle of matrix
	usedoc	I configuration of output

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_Free ( CTA_Matrix * hmat )

Free the matrix object.

hmat=CTA_NULL is allowed

Parameters:

hmat

IO handle of matrix, replaced by CTA_NULL on return.

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_Gemm	(	CTA_Matrix	mC,
		int	transa,
		int	transb,
		double	alpha,
		CTA_Matrix	mA,
		CTA_Matrix	mB,
		double	beta
	)

Perform the matrix multication C:=alpha*op(A)*op(B)+beta*C where op(X)=X, X^T.

Parameters:

	mC	IO handle of matrix C
	transa	I transpose flag CTA_TRUE/CTA_FALSE for matrix A
	transb	I transpose flag CTA_TRUE/CTA_FALSE for matrix A
	alpha	I scalar
	mA	I handle of matrix A
	mB	I handle of matrix B
	beta	I scalar

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_Gemv	(	CTA_Matrix	hmat,
		int	trans,
		double	alpha,
		CTA_Vector	vx,
		double	beta,
		CTA_Vector	vy
	)

Perform the matrix multiplication y:=alpha*OP(A)*x+beta*y where op(X)=X, X^T.

Parameters:

	hmat	I handle of matrix (A from the equation above)
	trans	I transpose flag CTA_TRUE/CTA_FALSE for matrix A
	alpha	I scalar
	vx	I vector x
	beta	I scalar
	vy	IO vector y

Returns:: error status: CTA_OK if successful

Note:: it is allowed that vectors are the same object (*vx==*vy)

CTAEXPORT int CTA_Matrix_Ger	(	CTA_Matrix	hmat,
		double	alpha,
		CTA_Vector	vx,
		CTA_Vector	vy
	)

Perform a rank 1 operation A:=alpha*x*y'+A.

Parameters:

	hmat	IO handle of matrix A
	alpha	I scalar
	vx	I vector x
	vy	I vector y

Returns:: error status: CTA_OK if successful

Note:: it is allowed that are the same object (*vx==*vy)

CTAEXPORT int CTA_Matrix_GetDatatype	(	CTA_Matrix	hmat,
		CTA_Datatype *	datatype
	)

Get datatype of matrix.

Note:

Parameters:

	hmat	I handle of matrix
	datatype	O receives data type of matrix

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_GetSize	(	CTA_Matrix	hmat,
		int *	m,
		int *	n
	)

CTAEXPORT int CTA_Matrix_GetVal	(	CTA_Matrix	hmat,
		void *	val,
		int	m,
		int	n,
		CTA_Datatype	datatype
	)

Get copy of single value in the matrix.

Note:: Counting of the indices starts from 1.

Parameters:

	hmat	I handle of matrix
	val	O receives copy of value in matrix
	m	I row index of value to be copied
	n	I column index of value to be copied
	datatype	I data type of *val, must be the same as data type of matrix elements

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_GetVals	(	CTA_Matrix	hmat,
		void *	vals,
		int	m,
		int	n,
		CTA_Datatype	datatype
	)

Get copy of all values in matrix.

Note:: The elements in the matrix are returned column-wise (FORTRAN matrix representation)

Parameters:

	hmat	I handle of matrix
	vals	O copy of values in matrix
	m	I number of rows of vals (must be the same as for the matrix)
	n	I number of columns of vals (must be the same as for the matrix)
	datatype	I data type of *vals, must be the same as data type of matrix elements

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_Inv ( CTA_Matrix hmat )

Compute inverse of a square matrix A:=inv(A).

Parameters:

hmat

IO handle of matrix A

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_SetCol	(	CTA_Matrix	hmat,
		int	n,
		CTA_Vector	hvec
	)

Set values of a single column of the matrix.

Note:: Counting of the indices starts from 1.

Parameters:

	hmat	IO handle of matrix
	n	I index of matrix column to set
	hvec	I handle of COSTA vector the values have to be set to, length must be the same as number of rows of matrix

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_SetConstant	(	CTA_Matrix	hmat,
		void *	val,
		CTA_Datatype	datatype
	)

Set whole matrix to one single value.

Note:

Parameters:

	hmat	IO handle of matrix
	val	I value that must be set
	datatype	I data type of *val, must be the same as data type of matrix elements

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_SetVal	(	CTA_Matrix	hmat,
		void *	val,
		int	m,
		int	n,
		CTA_Datatype	datatype
	)

Set a single value in the matrix.

Parameters:

	hmat	IO handle of matrix
	val	I value to be set at position (m,n)
	m	I row index
	n	I column index
	datatype	I data type of *val, must be the same as data type of matrix elements

Returns:: error status: CTA_OK if successful

CTAEXPORT int CTA_Matrix_SetVals	(	CTA_Matrix	hmat,
		void *	vals,
		int	m,
		int	n,
		CTA_Datatype	datatype
	)

Set all values of the matrix.

Note:: The elements in vals should be column-wise (FORTRAN matrix representation)

Parameters:

	hmat	IO handle of matrix
	vals	I copy of values in matrix
	m	I number of rows of vals (must be the same as for the matrix)
	n	I number of columns of vals (must be the same as for the matrix)
	datatype	I data type of vals

Returns:: error status: CTA_OK if successful

cta_matrix.h File Reference

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation