utility routines

Functions
int	MatInit (Mat *A, int m, int nnz, int *indices, double *values, int flag#ifdef W_MPI, MPI_Comm comm#endif)
void	MatSetIndices (Mat *A, int m, int nnz, int *indices)
void	MatSetValues (Mat *A, int m, int nnz, double *values)
void	MatFree (Mat *A)
int	MatLoad (Mat *mat, char *filename)
int	MatSave (Mat *mat, char *filename)
int	MatLocalShape (Mat *A, int sflag)
int	MatComShape (Mat *A, int flag, MPI_Comm comm)
int	TrMatVecProd (Mat *A, double *y, double *x, int pflag)
int	MatInfo (Mat *mat, int verbose, char *filename)
	Print information about a matrix.

---

Detailed Description

These are auxiliary utility routines. They may be used in both memory-shared/sequential and dsitributed contexts, though their syntax may change depending on that.

---

Function Documentation

int MatInit	(	Mat *	A,
		int	m,
		int	nnz,
		int *	indices,
		double *	values,
		int flag#ifdef	W_MPI,
		MPI_Comm comm#	endif
	)

Create a matrix specifying the number of local rows m, the number of non-zero elements per row nnz , indices tab, values tab, flag for communication and a communicator comm. indices and values tabs must be allocated and contain at least m*nnz elements. It represents column indices of the nonzero elements. Respectively values tab represents the non-zero values. After call MatInit, all precomputation are done and the matrix structure is ready to use. That means you can start applying matrix operation. Another way to initialize a matrix structure is to apply step by step :

• MatSetIndices
• MatSetValues
• MatLocalShape
• MatComShape

Warning:

do not modify indices tab until you will use the matrix structure.

[MPI COMM!] with Midapack sequential version, there is no communicator argument.

Parameters:

A	pointer to a Mat struct
m	number of local rows
nnz	number of non-zero per row
indices	input tab (modified)
values	input tab
flag	communication flag
comm	MPI communicator

See also:

MatFree

Definition at line 43 of file mapmat.c.

void MatSetIndices	(	Mat *	A,
		int	m,
		int	nnz,
		int *	indices
	)

Set column indices of the nonzero elements. indices tab must be allocated and contains at least m*nnz elements.

Parameters:

A	pointer to a Mat struct
m	number of local rows
nnz	number of non-zero per row
indices	input tab

Returns:

void

Definition at line 70 of file mapmat.c.

void MatSetValues	(	Mat *	A,
		int	m,
		int	nnz,
		double *	values
	)

Set values of the nonzero elements. values tab must be allocated and contains at least m*nnz values.

Parameters:

A	pointer to a Mat struct
m	number of local rows
nnz	number of non-zero per row
values	input tab

Returns:

void

Definition at line 85 of file mapmat.c.

void MatFree

(

Mat *

A

)

Free allocated tabs of a matrix structure including local indices tab and communication tabs. Do not free indices and values which user is responsible for.

Parameters:

A	pointer to a Mat struct

Returns:

void

See also:

MatInit MatLocalShape

Definition at line 99 of file mapmat.c.

int MatLoad	(	Mat *	mat,
		char *	filename
	)

Load matrix from a file. This is MatSave dual routine which loads data into matrix reading a specified file (or several specified files). Number of files should equal number of processor. File format should be ascii files (for examples look at files generated by MapMatSave routine).

Todo:

Implement to read several file formats as basic ASCII, XML, HDF5...

Parameters:

mat	pointer to the Mat
filename	basename of a file, actually data are loaded from several files denotes by "basename + processor number"

Returns:

error code

Definition at line 153 of file mapmat.c.

int MatSave	(	Mat *	mat,
		char *	filename
	)

Write matrix into files This is the dual routine of MatLoad. It saves matrix data into files, and can be usefull to check that data are well stored. Obviously it performs IO, moreover with one file per processor. Therfore, just call this function in a development phase, with few data and few processors.

Parameters:

A	pointer to the Mat
filename	file basename, for instance passing "toto" should produce the output files named "toto_$(rank)"

Returns:

error code

Definition at line 201 of file mapmat.c.

int MatLocalShape	(	Mat *	A,
		int	sflag
	)

Compute a local indices into a dense vector, lindices, and reindices indices tab according the this local dense vector. For this three steps are performed :

• sort and merge indices tab,
• allocate lindices of size lcount and copy the sorted indices
• reindex indices according the local indices

Warning:

lindices is internally allocated ( to free it, use MatFree )

See also:

MatComShape MatFree MatSetIndices

Definition at line 239 of file mapmat.c.

int MatComShape	(	Mat *	A,
		int	flag,
		MPI_Comm	comm
	)

Transform the matrix data structure, identifying columns shared by several processors

Warning:

[MPI ONLY!] this function does not exist in Midapack sequential version

See also:

MatLocalShape MatInit TrMatVecProd

Definition at line 265 of file mapmat.c.

int TrMatVecProd	(	Mat *	A,
		double *	y,
		double *	x,
		int	pflag
	)

Perform a transposed matrix-vector multiplication, using a precomputed communication scheme. Before calling this routine, the communication structure should have been set, calling MatInit or MatComShape. The routine can be divided in two steps :

• a local matrix vector multiplication
• a collective-reduce. it consits in a sum reduce over all processes.

The collective reduce is performed using algorithm previously defined : ring, butterfly ...

See also:

MatVecProd MatComShape TrMatVecProd_Naive MatInit

Parameters:

A	a pointer to a Mat
y	local input vector (distributed)
x	local output vector (overlapped)

Definition at line 445 of file mapmat.c.

int MatInfo	(	Mat *	mat,
		int	verbose,
		char *	filename
	)

Print information about a matrix.

Usefull function to check, debug or bench. It prints matrix array sizes.

See also:

MatSave

Parameters:

A	pointer to the Mat

Definition at line 480 of file mapmat.c.