ScaLAPACK compatibility / BLACS matrices

Data types and functions for BLACS formatted distributed matrices. More...

Data Structures
struct	starneig_blacs_descr
	BLACS descriptor. More...

BLACS contexts
typedef int	starneig_blacs_context_t
	BLACS context.
starneig_blacs_context_t	starneig_distr_to_blacs_context (starneig_distr_t distr)
	Convers a data distribution to a BLACS context. More...
starneig_distr_t	starneig_blacs_context_to_distr (starneig_blacs_context_t context)
	Convers a BLACS context to a data distribution. More...
int	starneig_distr_is_blacs_compatible (starneig_distr_t distr)
	Checks whether a data distribution is BLACS compatible. More...
int	starneig_distr_is_compatible_with (starneig_distr_t distr, starneig_blacs_context_t context)
	Checks whether a data distribution is compatible with a given BLACS context. More...

BLACS descriptors
typedef struct starneig_blacs_descr	starneig_blacs_descr_t
	BLACS descriptor.
void	starneig_blacs_create_matrix (int rows, int cols, int row_blksz, int col_blksz, starneig_datatype_t type, starneig_blacs_context_t context, starneig_blacs_descr_t *descr, void **local)
	Creates a BLACS matrix with uninitialized matrix elements. More...
void	starneig_blacs_destroy_matrix (starneig_blacs_descr_t *descr, void **local)
	Destroyes a BLACS matrix. More...
void	starneig_distr_matrix_to_blacs_descr (starneig_distr_matrix_t matrix, starneig_blacs_context_t context, starneig_blacs_descr_t *descr, void **local)
	Convers a distributed matrix to a BLACS descriptor and a matching local array. More...
starneig_distr_matrix_t	starneig_blacs_descr_to_distr_matrix (starneig_datatype_t type, starneig_distr_t distr, starneig_blacs_descr_t *descr, void *local)
	Convers a BLACS descriptor and a matching local array to a distributed matrix. More...
int	starneig_distr_matrix_is_blacs_compatible (starneig_distr_matrix_t matrix)
	Checks whether a distributed matrix is BLACS compatible. More...
int	starneig_distr_matrix_is_compatible_with (starneig_distr_matrix_t matrix, starneig_blacs_context_t context)
	Checks whether a distributed matrix is compatible with a given BLACS context. More...

Detailed Description

Data types and functions for BLACS formatted distributed matrices.

---

Data Structure Documentation

starneig_blacs_descr

struct starneig_blacs_descr

BLACS descriptor.

Data Fields
int	type	The descriptor type.
starneig_blacs_context_t	context	The related BLACS context.
int	m	The number of (global) rows in the matrix.
int	n	The number of (global) columns in the matrix.
int	sm	The number of rows in a distribution block.
int	sn	The number of columns in a distribution block.
int	rsrc	The process grid row over which the first row is distributed.
int	csrc	The process grid column over which the first column is distributed.
int	lld	The leading dimension of the local array.

Function Documentation

starneig_distr_to_blacs_context()

starneig_blacs_context_t starneig_distr_to_blacs_context

(

starneig_distr_t

distr

)

Convers a data distribution to a BLACS context.

Attention

The data distribution must describe a two-dimensional block cyclic distribution.

Parameters

[in]

distr

The data distribution.

Returns

The BLACS context.

starneig_blacs_context_to_distr()

starneig_distr_t starneig_blacs_context_to_distr

(

starneig_blacs_context_t

context

)

Convers a BLACS context to a data distribution.

Parameters

[in]

context

The BLACS context.

Returns

The data distribution.

starneig_distr_is_blacs_compatible()

int starneig_distr_is_blacs_compatible

(

starneig_distr_t

distr

)

Checks whether a data distribution is BLACS compatible.

Parameters

[in]

distr

The data distribution.

Returns

Non-zero if the data distribution matrix is BLACS compatible.

starneig_distr_is_compatible_with()

int starneig_distr_is_compatible_with	(	starneig_distr_t	distr,
		starneig_blacs_context_t	context
	)

Checks whether a data distribution is compatible with a given BLACS context.

Parameters

[in]	distr	The data distribution.
[in]	context	The BLACS context.

Returns

Non-zero if the data distribution compatible with the BLACS context.

starneig_blacs_create_matrix()

void starneig_blacs_create_matrix	(	int	rows,
		int	cols,
		int	row_blksz,
		int	col_blksz,
		starneig_datatype_t	type,
		starneig_blacs_context_t	context,
		starneig_blacs_descr_t *	descr,
		void **	local
	)

Creates a BLACS matrix with uninitialized matrix elements.

Parameters

[in]	rows	The number of (global) rows in the matrix.
[in]	cols	The number of (global) columns in the matrix.
[in]	row_blksz	The number of rows in a distribution block. Can be set to -1 in which case the library decides the value.
[in]	col_blksz	The number of columns in a distribution block. Can be set to -1 in which case the library decides the value.
[in]	type	The matrix element data type.
[in]	context	The BLACS context.
[out]	descr	The BLACS descriptor.
[out]	local	A pointer to the local array.

starneig_blacs_destroy_matrix()

void starneig_blacs_destroy_matrix	(	starneig_blacs_descr_t *	descr,
		void **	local
	)

Destroyes a BLACS matrix.

Parameters

[in,out]	descr	The BLACS descriptor.
[in,out]	local	A pointer to the local array.

starneig_distr_matrix_to_blacs_descr()

void starneig_distr_matrix_to_blacs_descr	(	starneig_distr_matrix_t	matrix,
		starneig_blacs_context_t	context,
		starneig_blacs_descr_t *	descr,
		void **	local
	)

Convers a distributed matrix to a BLACS descriptor and a matching local array.

This function creates a wrapper object. The contents of the distributed matrix may be modified by the functions that use the wrapper object.

starneig_distr_matrix_t dA = starneig_distr_matrix_create(...);
 
...
 
starneig_distr_t distr = starneig_distr_matrix_get_distr(A);
starneig_blacs_context_t context = starneig_distr_to_blacs_context(distr);
 
starneig_blacs_descr_t descr_a;
double *local_a;
starneig_distr_matrix_to_blacs_descr(
    dA, context, &descr_a, (void **)&local_a);

Parameters

[in]	matrix	The distributed matrix.
[in]	context	The BLACS context. The context must have been converted from the same data distribution the distributed matrix is using or vice versa.
[out]	descr	The BLACS descriptor.
[out]	local	A pointer to the local array.

starneig_blacs_descr_to_distr_matrix()

starneig_distr_matrix_t starneig_blacs_descr_to_distr_matrix	(	starneig_datatype_t	type,
		starneig_distr_t	distr,
		starneig_blacs_descr_t *	descr,
		void *	local
	)

Convers a BLACS descriptor and a matching local array to a distributed matrix.

This function creates a wrapper object. The contents of the local array may be modified by the functions that use the wrapper object. The starneig_distr_matrix_destroy() function does not de-initilize the BLACS descriptor nor free the local array.

starneig_blacs_context_t context;
starneig_blacs_descr_t descr_a;
double *local_a;
 
...
 
starneig_distr_t distr = starneig_blacs_context_to_distr(context);
starneig_distr_matrix_t dA = starneig_blacs_descr_to_distr_matrix(
    STARNEIG_REAL_DOUBLE, distr, descr_a, (void *)local_a);

Parameters

[in]	type	The matrix element data type.
[in]	distr	The data distribution. The data distribution must have been converted from the same BLACS context the BLACS descriptor is using or vice versa.
[in]	descr	The BLACS descriptor.
[in]	local	A pointer to the local array.

Returns

The distributed matrix.

starneig_distr_matrix_is_blacs_compatible()

int starneig_distr_matrix_is_blacs_compatible

(

starneig_distr_matrix_t

matrix

)

Checks whether a distributed matrix is BLACS compatible.

Parameters

[in]

matrix

The distributed matrix.

Returns

Non-zero if the distributed matrix is BLACS compatible.

starneig_distr_matrix_is_compatible_with()

int starneig_distr_matrix_is_compatible_with	(	starneig_distr_matrix_t	matrix,
		starneig_blacs_context_t	context
	)

Checks whether a distributed matrix is compatible with a given BLACS context.

Parameters

[in]	matrix	The distributed matrix.
[in]	context	The BLACS context.

Returns

Non-zero if the distributed matrix compatible with the BLACS context.