Matrix class for data distributed over MPI in the 2-d block cyclic format. More...

#include <mpimat.hh>

Inheritance diagram for fml::mpimat< REAL >:

Public Member Functions
	mpimat (const grid &blacs_grid)
	Construct matrix object with no internal allocated storage. More...

	mpimat (const grid &blacs_grid, int bf_rows, int bf_cols)
	Construct matrix object. More...

	mpimat (const grid &blacs_grid, len_t nrows, len_t ncols, int bf_rows, int bf_cols)
	Construct matrix object. More...

	mpimat (const grid &blacs_grid, REAL *data_, len_t nrows, len_t ncols, int bf_rows, int bf_cols, bool free_on_destruct=false)
	Construct matrix object with inherited data. Essentially the same as using the minimal constructor and immediately calling the `inherit()` method. More...

	mpimat (const mpimat &x)

void	resize (len_t nrows, len_t ncols)
	Resize the internal object storage. More...

void	resize (len_t nrows, len_t ncols, int bf_rows, int bf_cols)
	Resize the internal object storage. More...

void	inherit (grid &blacs_grid, REAL *data_, len_t nrows, len_t ncols, int bf_rows, int bf_cols, bool free_on_destruct=false)
	Set the internal object storage to the specified array. More...

mpimat< REAL >	dupe () const
	Duplicate the object in a deep copy.

void	print (uint8_t ndigits=4, bool add_final_blank=true) const
	Print all values in the object. More...

void	info () const
	Print some brief information about the object. More...

void	fill_zero ()
	Set all values to zero. More...

void	fill_val (const REAL v)
	Set all values to input value. More...

void	fill_linspace ()
	Set values to linearly spaced numbers. More...

void	fill_linspace (const REAL start, const REAL stop)

void	fill_eye ()
	Set diagonal entries to 1 and non-diagonal entries to 0. More...

void	fill_diag (const cpuvec< REAL > &v)
	Set diagonal entries of the matrix to those in the vector. More...

void	fill_runif (const uint32_t seed, const REAL min=0, const REAL max=1)
	Set diagonal entries to 1 and non-diagonal entries to 0. More...

void	fill_runif (const REAL min=0, const REAL max=1)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	fill_rnorm (const uint32_t seed, const REAL mean=0, const REAL sd=1)
	Set diagonal entries to 1 and non-diagonal entries to 0. More...

void	fill_rnorm (const REAL mean=0, const REAL sd=1)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	diag (cpuvec< REAL > &v)
	Get the diagonal entries. More...

void	antidiag (cpuvec< REAL > &v)
	Get the anti-diagonal entries, i.e. those on the bottom-left to top-right. More...

void	scale (const REAL s)
	Multiply all values by the input value. More...

void	rev_rows ()
	Reverse the rows of the matrix. More...

void	rev_cols ()
	Reverse the columns of the matrix. More...

bool	any_inf () const
	Are any values infinite? More...

bool	any_nan () const
	Are any values NaN? More...

REAL	get (const len_t i) const
	Get the specified value. More...

REAL	get (const len_t i, const len_t j) const
	Get the specified value. More...

void	set (const len_t i, const REAL v)
	Set the storage at the specified index with the provided value. More...

void	set (const len_t i, const len_t j, const REAL v)
	Set the storage at the specified index with the provided value. More...

void	get_row (const len_t i, cpuvec< REAL > &v) const
	Get the specified row. More...

void	set_row (const len_t i, const cpuvec< REAL > &v)
	Set the specified row. More...

void	get_col (const len_t j, cpuvec< REAL > &v) const
	Get the specified column. More...

void	set_col (const len_t j, const cpuvec< REAL > &v)
	Set the specified column. More...

bool	operator== (const mpimat< REAL > &x) const
	See if the two objects are the same. More...

bool	operator!= (const mpimat< REAL > &x) const
	See if the two objects are not the same. Uses same internal logic as the `==` method. More...

mpimat< REAL > &	operator= (const mpimat< REAL > &x)
	Operator that sets the LHS to a shallow copy of the input. Desctruction of the LHS object will not result in the internal array storage being freed. More...

len_local_t	nrows_local () const

len_local_t	ncols_local () const

int	bf_rows () const

int	bf_cols () const

int *	desc_ptr ()

const int *	desc_ptr () const

const grid	get_grid () const

void	fill_linspace (const int start, const int stop)

Public Member Functions inherited from fml::unimat< REAL >
bool	is_square () const
	Is the matrix square?

len_t	nrows () const
	Number of rows.

len_t	ncols () const
	Number of columns.

REAL *	data_ptr ()
	Pointer to the internal array.

REAL *	data_ptr () const

Protected Attributes
len_local_t	m_local

len_local_t	n_local

int	mb

int	nb

int	desc [9]

grid	g

Protected Attributes inherited from fml::unimat< REAL >
len_t	m

len_t	n

REAL *	data

bool	free_data

Additional Inherited Members
Protected Member Functions inherited from fml::unimat< REAL >
bool	should_free () const

void	check_index (const len_t i) const

void	check_index (const len_t i, const len_t j) const

void	printval (const REAL val, uint8_t ndigits) const

void	printval (const int val, uint8_t ndigits) const

Detailed Description

template<typename REAL>
class fml::mpimat< REAL >

Matrix class for data distributed over MPI in the 2-d block cyclic format.

Template Parameters

REAL	should be 'float' or 'double'.

Constructor & Destructor Documentation

◆ mpimat() [1/4]

template<typename REAL >

fml::mpimat< REAL >::mpimat ( const grid & blacs_grid )

Construct matrix object with no internal allocated storage.

Parameters

[in] blacs_grid Scalapack grid object.

Communication Details
The method has no communication.

grid g = grid(PROC_GRID_SQUARE);

mpimat<float> x(g);

◆ mpimat() [2/4]

template<typename REAL >

fml::mpimat< REAL >::mpimat	(	const grid &	blacs_grid,
		int	bf_rows,
		int	bf_cols
	)

Construct matrix object.

Parameters

[in]	blacs_grid	Scalapack grid object.
[in]	nrows,ncols	Number rows/columns of the matrix.
[in]	bf_rows,bf_cols	Row/column blocking factor.

Exceptions
If the allocation fails, a bad_alloc exception will be thrown. If the input values are invalid, a runtime_error exception will be thrown.

Communication Details
The method has no communication.

grid g = grid(PROC_GRID_SQUARE);

mpimat<float> x(g, 1, 1);

◆ mpimat() [3/4]

template<typename REAL >

fml::mpimat< REAL >::mpimat	(	const grid &	blacs_grid,
		len_t	nrows,
		len_t	ncols,
		int	bf_rows,
		int	bf_cols
	)

Construct matrix object.

Parameters

[in]	blacs_grid	Scalapack grid object.
[in]	nrows,ncols	Number rows/columns of the array, i.e. the length of the array is nrows*ncols.
[in]	bf_rows,bf_cols	Row/column blocking factor.

Exceptions
If the input values are invalid, a runtime_error exception will be thrown.

Communication Details
The method has no communication.

grid g = grid(PROC_GRID_SQUARE);

mpimat<float> x(g, 3, 2, 1, 1);

◆ mpimat() [4/4]

template<typename REAL >

fml::mpimat< REAL >::mpimat	(	const grid &	blacs_grid,
		REAL *	data_,
		len_t	nrows,
		len_t	ncols,
		int	bf_rows,
		int	bf_cols,
		bool	free_on_destruct = `false`
	)

Construct matrix object with inherited data. Essentially the same as using the minimal constructor and immediately calling the inherit() method.

Parameters

[in]	blacs_grid	Scalapack grid object.
[in]	data_	Storage array.
[in]	nrows,ncols	Number rows/columns of the array, i.e. the length of the array is nrows*ncols.
[in]	bf_rows,bf_cols	Row/column blocking factor.
[in]	free_on_destruct	Should the inherited array `data_` be freed when the matrix object is destroyed?

Exceptions
If the input values are invalid, a runtime_error exception will be thrown.

Communication Details
The method has no communication.

Member Function Documentation

◆ antidiag()

template<typename REAL >

void fml::mpimat< REAL >::antidiag ( fml::cpuvec< REAL > & v )

Get the anti-diagonal entries, i.e. those on the bottom-left to top-right.

Parameters

[out] v The anti-diagonal. Length should match the length of the diagonal of the input (minimum of the matrix dimensions). If not, the vector will automatically be resized.

Memory Allocations
If the output dimension is inappropriately sized, it will automatically be re-allocated.

Exceptions
If a reallocation is triggered and fails, a bad_alloc exception will be thrown.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ any_inf()

template<typename REAL >

bool fml::mpimat< REAL >::any_inf

Are any values infinite?

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ any_nan()

template<typename REAL >

bool fml::mpimat< REAL >::any_nan

Are any values NaN?

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ diag()

template<typename REAL >

void fml::mpimat< REAL >::diag ( fml::cpuvec< REAL > & v )

Get the diagonal entries.

Parameters

[out] v The diagonal. Length should match the length of the diagonal of the input (minimum of the matrix dimensions). If not, the vector will automatically be resized.

Memory Allocations
If the output dimension is inappropriately sized, it will automatically be re-allocated.

Exceptions
If a reallocation is triggered and fails, a bad_alloc exception will be thrown.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ fill_diag()

template<typename REAL >

void fml::mpimat< REAL >::fill_diag ( const cpuvec< REAL > & v )

Set diagonal entries of the matrix to those in the vector.

If the vector is smaller than the matrix diagonal, the vector will recycle until the matrix diagonal is filled. If the vector is longer, then not all of it will be used.

Parameters

[in] v Vector of values to set the matrix diagonal to.

Communication Details
The method has no communication.

◆ fill_eye()

template<typename REAL >

void fml::mpimat< REAL >::fill_eye

Set diagonal entries to 1 and non-diagonal entries to 0.

Communication Details
The method has no communication.

◆ fill_linspace()

template<typename T >

void fml::mpimat< T >::fill_linspace

Set values to linearly spaced numbers.

Parameters

[in] start,stop Beginning/ending numbers. If not supplied, the matrix will be filled with whole numbers from 1 to the total number of elements.

Communication Details
The method has no communication.

◆ fill_rnorm()

template<typename REAL >

void fml::mpimat< REAL >::fill_rnorm	(	const uint32_t	seed,
		const REAL	mean = `0`,
		const REAL	sd = `1`
	)

Set diagonal entries to 1 and non-diagonal entries to 0.

Parameters

[in]	seed	Seed for the rng.
[in]	mean,sd	Parameters for the generator.

Communication Details
The method has no communication.

◆ fill_runif()

template<typename REAL >

void fml::mpimat< REAL >::fill_runif	(	const uint32_t	seed,
		const REAL	min = `0`,
		const REAL	max = `1`
	)

Set diagonal entries to 1 and non-diagonal entries to 0.

Parameters

[in]	seed	Seed for the rng.
[in]	min,max	Parameters for the generator.

Communication Details
The method has no communication.

◆ fill_val()

template<typename REAL >

void fml::mpimat< REAL >::fill_val ( const REAL v )

Set all values to input value.

Parameters

[in] v Value to set all data values to.

Communication Details
The method has no communication.

◆ fill_zero()

template<typename REAL >

void fml::mpimat< REAL >::fill_zero

Set all values to zero.

Communication Details
The method has no communication.

◆ get() [1/2]

template<typename REAL >

REAL fml::mpimat< REAL >::get ( const len_t i ) const

Get the specified value.

All processes receive the return.

Parameters

[in] i The index of the desired value, 0-indexed. The numbering considers the internal storage as a 1-dimensional array.

Exceptions
If indices are out of bounds, the method will throw a runtime_error exception.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ get() [2/2]

template<typename REAL >

REAL fml::mpimat< REAL >::get	(	const len_t	i,
		const len_t	j
	)		const

Get the specified value.

All processes receive the return.

Parameters

[in] i,j The indices of the desired value, 0-indexed.

Exceptions
If indices are out of bounds, the method will throw a runtime_error exception.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ get_col()

template<typename REAL >

void fml::mpimat< REAL >::get_col	(	const len_t	j,
		fml::cpuvec< REAL > &	v
	)		const

Get the specified column.

The return vector of column values is set on all processes.

Parameters

[in]	j	The desired column, 0-indexed.
[out]	v	The column values.

Memory Allocations
If the output dimension is inappropriately sized, it will automatically be re-allocated.

Exceptions
If j is an inappropriate value (i.e. does not refer to a matrix column), then the method will throw a logic_error exception. If a reallocation is triggered and fails, a bad_alloc exception will be thrown.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ get_row()

template<typename REAL >

void fml::mpimat< REAL >::get_row	(	const len_t	i,
		fml::cpuvec< REAL > &	v
	)		const

Get the specified row.

The return vector of row values is set on all processes.

Parameters

[in]	i	The desired row, 0-indexed.
[out]	v	The row values.

Memory Allocations
If the output dimension is inappropriately sized, it will automatically be re-allocated.

Exceptions
If i is an inappropriate value (i.e. does not refer to a matrix row), then the method will throw a logic_error exception. If a reallocation is triggered and fails, a bad_alloc exception will be thrown.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ info()

template<typename REAL >

void fml::mpimat< REAL >::info

Print some brief information about the object.

Printing will only be done by rank 0.

Communication Details
The method has no communication.

◆ inherit()

template<typename REAL >

void fml::mpimat< REAL >::inherit	(	fml::grid &	blacs_grid,
		REAL *	data_,
		len_t	nrows,
		len_t	ncols,
		int	bf_rows,
		int	bf_cols,
		bool	free_on_destruct = `false`
	)

Set the internal object storage to the specified array.

Parameters

[in]	data	Value storage.
[in]	nrows,ncols	Number rows/columns of the matrix. The product of these should be the length of the input `data`.
[in]	bf_rows,bf_cols	Row/column blocking factor.
[in]	free_on_destruct	Should the object destructor free the internal array `data`?

Exceptions
If the input values are invalid, a runtime_error exception will be thrown.

Communication Details
The method has no communication.

◆ operator!=()

template<typename REAL >

bool fml::mpimat< REAL >::operator!= ( const mpimat< REAL > & x ) const

See if the two objects are not the same. Uses same internal logic as the == method.

Parameters

[in] Comparison object.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ operator=()

template<typename REAL >

fml::mpimat< REAL > & fml::mpimat< REAL >::operator= ( const mpimat< REAL > & x )

Operator that sets the LHS to a shallow copy of the input. Desctruction of the LHS object will not result in the internal array storage being freed.

Parameters

[in] x Setter value.

Communication Details
The method has no communication.

◆ operator==()

template<typename REAL >

bool fml::mpimat< REAL >::operator== ( const mpimat< REAL > & x ) const

See if the two objects are the same.

All processes receive the return.

Parameters

[in] Comparison object.

Returns: If the dimensions mismatch, then false is necessarily returned. Next, if the grid objects have different ordinal context numbers, then false is returned. Next, if the pointer to the internal storage arrays match, then true is returned. Otherwise the objects are compared value by value.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ print()

template<typename REAL >

void fml::mpimat< REAL >::print	(	uint8_t	ndigits = `4`,
		bool	add_final_blank = `true`
	)		const

Print all values in the object.

Printing will only be done by rank 0.

Parameters

[in]	ndigits	Number of decimal digits to print.
[in]	add_final_blank	Should a final blank line be printed?

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ resize() [1/2]

template<typename REAL >

void fml::mpimat< REAL >::resize	(	len_t	nrows,
		len_t	ncols
	)

Resize the internal object storage.

Parameters

[in] nrows,ncols Number rows/columns needed.

Memory Allocations
Resizing triggers a re-allocation.

Exceptions
If the reallocation fails, a bad_alloc exception will be thrown. If the input values are invalid, a runtime_error exception will be thrown.

Communication Details
The method has no communication.

◆ resize() [2/2]

template<typename REAL >

void fml::mpimat< REAL >::resize	(	len_t	nrows,
		len_t	ncols,
		int	bf_rows,
		int	bf_cols
	)

Resize the internal object storage.

Parameters

[in]	nrows,ncols	Number rows/columns needed.
[in]	bf_rows,bf_cols	Row/column blocking factor.

Memory Allocations
Resizing triggers a re-allocation.

Exceptions
If the reallocation fails, a bad_alloc exception will be thrown. If the input values are invalid, a runtime_error exception will be thrown.

Communication Details
The method has no communication.

◆ rev_cols()

template<typename REAL >

void fml::mpimat< REAL >::rev_cols

Reverse the columns of the matrix.

Communication Details
The method will communicate with all columns in the BLACS grid.

◆ rev_rows()

template<typename REAL >

void fml::mpimat< REAL >::rev_rows

Reverse the rows of the matrix.

Communication Details
The method will communicate with all rows in the BLACS grid.

◆ scale()

template<typename REAL >

void fml::mpimat< REAL >::scale ( const REAL s )

Multiply all values by the input value.

Parameters

[in] s Scaling value.

Communication Details
The method has no communication.

◆ set() [1/2]

template<typename REAL >

void fml::mpimat< REAL >::set	(	const len_t	i,
		const len_t	j,
		const REAL	v
	)

Set the storage at the specified index with the provided value.

Parameters

[in]	i,j	The indices of the desired value, 0-indexed.
[in]	v	Setter value.

Exceptions
If indices are out of bounds, the method will throw a runtime_error exception.

Communication Details
The method has no communication.

◆ set() [2/2]

template<typename REAL >

void fml::mpimat< REAL >::set	(	const len_t	i,
		const REAL	v
	)

Set the storage at the specified index with the provided value.

Parameters

[in]	i	The index of the desired value, 0-indexed. The numbering considers the internal storage as a 1-dimensional array.
[in]	v	Setter value.

Exceptions
If indices are out of bounds, the method will throw a runtime_error exception.

Communication Details
The method has no communication.

◆ set_col()

template<typename REAL >

void fml::mpimat< REAL >::set_col	(	const len_t	j,
		const cpuvec< REAL > &	v
	)

Set the specified column.

The return vector of column values is set on all processes.

Parameters

[in]	j	The desired column, 0-indexed.
[in]	v	The column values.

Memory Allocations
If the output dimension is inappropriately sized, it will automatically be re-allocated.

Exceptions
If j is an inappropriate value (i.e. does not refer to a matrix column), then the method will throw a logic_error exception. If the vector is inappropriately sized, a runtime_error exception will be thrown.

Communication Details
The method will communicate across all processes in the BLACS grid.

◆ set_row()

template<typename REAL >

void fml::mpimat< REAL >::set_row	(	const len_t	i,
		const cpuvec< REAL > &	v
	)

Set the specified row.

Parameters

[in]	i	The desired row, 0-indexed.
[in]	v	The row values.

Exceptions
If i is an inappropriate value (i.e. does not refer to a matrix row), then the method will throw a logic_error exception. If the vector is inappropriately sized, a runtime_error exception will be thrown.

Communication Details
The method will communicate across all processes in the BLACS grid.

The documentation for this class was generated from the following file:

fml/src/fml/mpi/mpimat.hh

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

template<typename REAL> class fml::mpimat< REAL >

Constructor & Destructor Documentation

◆ mpimat() [1/4]

◆ mpimat() [2/4]

◆ mpimat() [3/4]

◆ mpimat() [4/4]

Member Function Documentation

◆ antidiag()

◆ any_inf()

◆ any_nan()

◆ diag()

◆ fill_diag()

◆ fill_eye()

◆ fill_linspace()

◆ fill_rnorm()

◆ fill_runif()

◆ fill_val()

◆ fill_zero()

◆ get() [1/2]

◆ get() [2/2]

◆ get_col()

◆ get_row()

◆ info()

◆ inherit()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ print()

◆ resize() [1/2]

◆ resize() [2/2]

◆ rev_cols()

◆ rev_rows()

◆ scale()

◆ set() [1/2]

◆ set() [2/2]

◆ set_col()

◆ set_row()

template<typename REAL>
class fml::mpimat< REAL >