The Matrix class defines a (MPI-)distributed matrix. More...

#include <ginkgo/core/distributed/matrix.hpp>

Inheritance diagram for gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >:

Collaboration diagram for gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >:

Public Types
using	value_type = ValueType

using	index_type = GlobalIndexType

using	local_index_type = LocalIndexType

using	global_index_type = GlobalIndexType

using	global_vector_type = gko::experimental::distributed::Vector< ValueType >

using	local_vector_type = typename global_vector_type::local_vector_type

Public Types inherited from gko::EnablePolymorphicAssignment< Matrix< ValueType, LocalIndexType, GlobalIndexType > >
using	result_type = Matrix< ValueType, LocalIndexType, GlobalIndexType >

Public Types inherited from gko::ConvertibleTo< Matrix< ValueType, LocalIndexType, GlobalIndexType > >
using	result_type = Matrix< ValueType, LocalIndexType, GlobalIndexType >

Public Types inherited from gko::ConvertibleTo< Matrix< next_precision< ValueType >, LocalIndexType, GlobalIndexType > >
using	result_type = Matrix< next_precision< ValueType >, LocalIndexType, GlobalIndexType >

Public Member Functions
void	convert_to (Matrix< next_precision< value_type >, local_index_type, global_index_type > *result) const override

void	move_to (Matrix< next_precision< value_type >, local_index_type, global_index_type > *result) override

void	read_distributed (const device_matrix_data< value_type, global_index_type > &data, ptr_param< const Partition< local_index_type, global_index_type >> partition)
	Reads a square matrix from the device_matrix_data structure and a global partition. More...

void	read_distributed (const matrix_data< value_type, global_index_type > &data, ptr_param< const Partition< local_index_type, global_index_type >> partition)
	Reads a square matrix from the matrix_data structure and a global partition. More...

void	read_distributed (const device_matrix_data< value_type, global_index_type > &data, ptr_param< const Partition< local_index_type, global_index_type >> row_partition, ptr_param< const Partition< local_index_type, global_index_type >> col_partition)
	Reads a matrix from the device_matrix_data structure, a global row partition, and a global column partition. More...

void	read_distributed (const matrix_data< value_type, global_index_type > &data, ptr_param< const Partition< local_index_type, global_index_type >> row_partition, ptr_param< const Partition< local_index_type, global_index_type >> col_partition)
	Reads a matrix from the matrix_data structure, a global row partition, and a global column partition. More...

std::shared_ptr< const LinOp >	get_local_matrix () const
	Get read access to the stored local matrix. More...

std::shared_ptr< const LinOp >	get_non_local_matrix () const
	Get read access to the stored non-local matrix. More...

	Matrix (const Matrix &other)
	Copy constructs a Matrix. More...

	Matrix (Matrix &&other) noexcept
	Move constructs a Matrix. More...

Matrix &	operator= (const Matrix &other)
	Copy assigns a Matrix. More...

Matrix &	operator= (Matrix &&other)
	Move assigns a Matrix. More...

Public Member Functions inherited from gko::experimental::EnableDistributedLinOp< Matrix< ValueType, LocalIndexType, GlobalIndexType > >
const Matrix< ValueType, LocalIndexType, GlobalIndexType > *	apply (ptr_param< const LinOp > b, ptr_param< LinOp > x) const

Matrix< ValueType, LocalIndexType, GlobalIndexType > *	apply (ptr_param< const LinOp > b, ptr_param< LinOp > x)

const Matrix< ValueType, LocalIndexType, GlobalIndexType > *	apply (ptr_param< const LinOp > alpha, ptr_param< const LinOp > b, ptr_param< const LinOp > beta, ptr_param< LinOp > x) const

Matrix< ValueType, LocalIndexType, GlobalIndexType > *	apply (ptr_param< const LinOp > alpha, ptr_param< const LinOp > b, ptr_param< const LinOp > beta, ptr_param< LinOp > x)

Public Member Functions inherited from gko::EnableAbstractPolymorphicObject< Matrix< ValueType, LocalIndexType, GlobalIndexType >, LinOp >
std::unique_ptr< Matrix< ValueType, LocalIndexType, GlobalIndexType > >	create_default (std::shared_ptr< const Executor > exec) const

std::unique_ptr< Matrix< ValueType, LocalIndexType, GlobalIndexType > >	create_default () const

std::unique_ptr< Matrix< ValueType, LocalIndexType, GlobalIndexType > >	clone (std::shared_ptr< const Executor > exec) const

std::unique_ptr< Matrix< ValueType, LocalIndexType, GlobalIndexType > >	clone () const

Matrix< ValueType, LocalIndexType, GlobalIndexType > *	copy_from (const PolymorphicObject *other)

std::enable_if_t< std::is_base_of< PolymorphicObject, std::decay_t< Derived > >::value, Matrix< ValueType, LocalIndexType, GlobalIndexType > > *	copy_from (std::unique_ptr< Derived > &&other)

std::enable_if_t< std::is_base_of< PolymorphicObject, std::decay_t< Derived > >::value, Matrix< ValueType, LocalIndexType, GlobalIndexType > > *	copy_from (const std::unique_ptr< Derived > &other)

Matrix< ValueType, LocalIndexType, GlobalIndexType > *	copy_from (const std::shared_ptr< const PolymorphicObject > &other)

Matrix< ValueType, LocalIndexType, GlobalIndexType > *	move_from (ptr_param< PolymorphicObject > other)

Matrix< ValueType, LocalIndexType, GlobalIndexType > *	clear ()

Public Member Functions inherited from gko::LinOp
LinOp *	apply (ptr_param< const LinOp > b, ptr_param< LinOp > x)
	Applies a linear operator to a vector (or a sequence of vectors). More...

const LinOp *	apply (ptr_param< const LinOp > b, ptr_param< LinOp > x) const

LinOp *	apply (ptr_param< const LinOp > alpha, ptr_param< const LinOp > b, ptr_param< const LinOp > beta, ptr_param< LinOp > x)
	Performs the operation x = alpha * op(b) + beta * x. More...

const LinOp *	apply (ptr_param< const LinOp > alpha, ptr_param< const LinOp > b, ptr_param< const LinOp > beta, ptr_param< LinOp > x) const

const dim< 2 > &	get_size () const noexcept
	Returns the size of the operator. More...

virtual bool	apply_uses_initial_guess () const
	Returns true if the linear operator uses the data given in x as an initial guess. More...

LinOp &	operator= (const LinOp &)=default
	Copy-assigns a LinOp. More...

LinOp &	operator= (LinOp &&other)
	Move-assigns a LinOp. More...

	LinOp (const LinOp &)=default
	Copy-constructs a LinOp. More...

	LinOp (LinOp &&other)
	Move-constructs a LinOp. More...

Public Member Functions inherited from gko::EnableAbstractPolymorphicObject< LinOp >
std::unique_ptr< LinOp >	create_default (std::shared_ptr< const Executor > exec) const

std::unique_ptr< LinOp >	create_default () const

std::unique_ptr< LinOp >	clone (std::shared_ptr< const Executor > exec) const

std::unique_ptr< LinOp >	clone () const

LinOp *	copy_from (const PolymorphicObject *other)

std::enable_if_t< std::is_base_of< PolymorphicObject, std::decay_t< Derived > >::value, LinOp > *	copy_from (std::unique_ptr< Derived > &&other)

std::enable_if_t< std::is_base_of< PolymorphicObject, std::decay_t< Derived > >::value, LinOp > *	copy_from (const std::unique_ptr< Derived > &other)

LinOp *	copy_from (const std::shared_ptr< const PolymorphicObject > &other)

LinOp *	move_from (ptr_param< PolymorphicObject > other)

LinOp *	clear ()

Public Member Functions inherited from gko::PolymorphicObject
PolymorphicObject &	operator= (const PolymorphicObject &)

std::unique_ptr< PolymorphicObject >	create_default (std::shared_ptr< const Executor > exec) const
	Creates a new "default" object of the same dynamic type as this object. More...

std::unique_ptr< PolymorphicObject >	create_default () const
	Creates a new "default" object of the same dynamic type as this object. More...

std::unique_ptr< PolymorphicObject >	clone (std::shared_ptr< const Executor > exec) const
	Creates a clone of the object. More...

std::unique_ptr< PolymorphicObject >	clone () const
	Creates a clone of the object. More...

PolymorphicObject *	copy_from (const PolymorphicObject *other)
	Copies another object into this object. More...

template<typename Derived , typename Deleter >
std::enable_if_t< std::is_base_of< PolymorphicObject, std::decay_t< Derived > >::value, PolymorphicObject > *	copy_from (std::unique_ptr< Derived, Deleter > &&other)
	Moves another object into this object. More...

template<typename Derived , typename Deleter >
std::enable_if_t< std::is_base_of< PolymorphicObject, std::decay_t< Derived > >::value, PolymorphicObject > *	copy_from (const std::unique_ptr< Derived, Deleter > &other)
	Copies another object into this object. More...

PolymorphicObject *	copy_from (const std::shared_ptr< const PolymorphicObject > &other)
	Copies another object into this object. More...

PolymorphicObject *	move_from (ptr_param< PolymorphicObject > other)
	Moves another object into this object. More...

PolymorphicObject *	clear ()
	Transforms the object into its default state. More...

std::shared_ptr< const Executor >	get_executor () const noexcept
	Returns the Executor of the object. More...

Public Member Functions inherited from gko::log::EnableLogging< PolymorphicObject >
void	add_logger (std::shared_ptr< const Logger > logger) override

void	remove_logger (const Logger *logger) override

void	remove_logger (ptr_param< const Logger > logger)

const std::vector< std::shared_ptr< const Logger > > &	get_loggers () const override

void	clear_loggers () override

Public Member Functions inherited from gko::log::Loggable
void	remove_logger (ptr_param< const Logger > logger)

Public Member Functions inherited from gko::EnablePolymorphicAssignment< Matrix< ValueType, LocalIndexType, GlobalIndexType > >
void	convert_to (result_type *result) const override
	Converts the implementer to an object of type result_type. More...

void	move_to (result_type *result) override
	Converts the implementer to an object of type result_type by moving data from this object. More...

Public Member Functions inherited from gko::ConvertibleTo< Matrix< ValueType, LocalIndexType, GlobalIndexType > >
void	convert_to (ptr_param< result_type > result) const

void	move_to (ptr_param< result_type > result)

Public Member Functions inherited from gko::ConvertibleTo< Matrix< next_precision< ValueType >, LocalIndexType, GlobalIndexType > >
virtual void	convert_to (result_type *result) const=0
	Converts the implementer to an object of type result_type. More...

void	convert_to (ptr_param< result_type > result) const

virtual void	move_to (result_type *result)=0
	Converts the implementer to an object of type result_type by moving data from this object. More...

void	move_to (ptr_param< result_type > result)

Public Member Functions inherited from gko::experimental::distributed::DistributedBase
	DistributedBase (const DistributedBase &other)=default

	DistributedBase (DistributedBase &&other)=default

DistributedBase &	operator= (const DistributedBase &)
	Copy assignment that doesn't change the used mpi::communicator. More...

DistributedBase &	operator= (DistributedBase &&) noexcept
	Move assignment that doesn't change the used mpi::communicator. More...

mpi::communicator	get_communicator () const
	Access the used mpi::communicator. More...

Friends
class	EnableCreateMethod< Matrix >

class	EnableDistributedPolymorphicObject< Matrix, LinOp >

class	Matrix< next_precision< ValueType >, LocalIndexType, GlobalIndexType >

Additional Inherited Members
Static Public Member Functions inherited from gko::EnableCreateMethod< Matrix< ValueType, LocalIndexType, GlobalIndexType > >
static std::unique_ptr< Matrix< ValueType, LocalIndexType, GlobalIndexType > >	create (Args &&... args)

Detailed Description

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>
class gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >

The Matrix class defines a (MPI-)distributed matrix.

The matrix is stored in a row-wise distributed format. Each process owns a specific set of rows, where the assignment of rows is defined by a row Partition. The following depicts the distribution of global rows according to their assigned part-id (which will usually be the owning process id):

Part-Id  Global Rows                   Part-Id  Local Rows
      | .. 1  2  .. .. .. |         0        | .. 1  2  .. .. .. |
      | 3  4  .. .. .. .. |                  | 13 .. .. .. 14 .. |
      | .. 5  6  ..  7 .. |  ---->  1        | 3  4  .. .. .. .. |
      | .. .. .. 8  ..  9 |  ---->           | .. .. .. 10 11 12 |
      | .. .. .. 10 11 12 |         2        | .. 5  6  ..  7 .. |
      | 13 .. .. .. 14 .. |                  | .. .. .. 8  ..  9 |

The local rows are further split into two matrices on each process. One matrix, called local, contains only entries from columns that are also owned by the process, while the other one, called non_local, contains entries from columns that are not owned by the process. The non-local matrix is stored in a compressed format, where empty columns are discarded and the remaining columns are renumbered. This splitting is depicted in the following:

Part-Id  Global                            Local      Non-Local
0        | .. 1  ! 2  .. ! .. .. |         | .. 1  |  | 2  |
0        | 3  4  ! .. .. ! .. .. |         | 3  4  |  | .. |
         |-----------------------|
1        | .. 5  ! 6  .. ! 7  .. |  ---->  | 6  .. |  | 5  7  .. |
1        | .. .. ! .. 8  ! ..  9 |  ---->  | 8  .. |  | .. .. 9  |
         |-----------------------|
2        | .. .. ! .. 10 ! 11 12 |         | 11 12 |  | .. 10 |
2        | 13 .. ! .. .. ! 14 .. |         | 14 .. |  | 13 .. |

This uses the same ownership of the columns as for the rows. Additionally, the ownership of the columns may be explicitly defined with an second column partition. If that is not provided, the same row partition will be used for the columns. Using a column partition also allows to create non-square matrices, like the one below:

Part-Id  Global                  Local      Non-Local
P_R/P_C    2  2  0  1
0        | .. 1  2  .. |         | 2  |     | 1  .. |
0        | 3  4  .. .. |         | .. |     | 3  4  |
         |-------------|
1        | .. 5  6  .. |  ---->  | .. |     | 6  5  |
1        | .. .. .. 8  |  ---->  | 8  |     | .. .. |
         |-------------|
2        | .. .. .. 10 |         | .. .. |  | 10 |
2        | 13 .. .. .. |         | 13 .. |  | .. |

Here P_R denotes the row partition and P_C denotes the column partition.

The Matrix should be filled using the read_distributed method, e.g.

auto part = Partition<...>::build_from_mapping(...);
auto mat = Matrix<...>::create(exec, comm);
mat->read_distributed(matrix_data, part);

or if different partitions for the rows and columns are used:

auto row_part = Partition<...>::build_from_mapping(...);
auto col_part = Partition<...>::build_from_mapping(...);
auto mat = Matrix<...>::create(exec, comm);
mat->read_distributed(matrix_data, row_part, col_part);

This will set the dimensions of the global and local matrices automatically by deducing the sizes from the partitions.

By default the Matrix type uses Csr for both stored matrices. It is possible to explicitly change the datatype for the stored matrices, with the constraint that the new type should implement the LinOp and ReadableFromMatrixData interface. The type can be set by:

auto mat = Matrix<ValueType, LocalIndexType[, ...]>::create(
  exec, comm,
  Ell<ValueType, LocalIndexType>::create(exec).get(),
  Coo<ValueType, LocalIndexType>::create(exec).get());

Alternatively, the helper function with_matrix_type can be used:

auto mat = Matrix<ValueType, LocalIndexType>::create(
  exec, comm,
  with_matrix_type<Ell>(),
  with_matrix_type<Coo>());

See also: with_matrix_type

The Matrix LinOp supports the following operations:

experimental::distributed::Matrix *A;       // distributed matrix
experimental::distributed::Vector *b, *x;   // distributed multi-vectors
matrix::Dense *alpha, *beta;  // scalars of dimension 1x1
 
// Applying to distributed multi-vectors computes an SpMV/SpMM product
A->apply(b, x)              // x = A*b
A->apply(alpha, b, beta, x) // x = alpha*A*b + beta*x

Template Parameters

ValueType	The underlying value type.
LocalIndexType	The index type used by the local matrices.
GlobalIndexType	The type for global indices.

Constructor & Destructor Documentation

◆ Matrix() [1/2]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::Matrix ( const Matrix< ValueType, LocalIndexType, GlobalIndexType > & other )

Copy constructs a Matrix.

Parameters

other Matrix to copy from.

◆ Matrix() [2/2]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::Matrix ( Matrix< ValueType, LocalIndexType, GlobalIndexType > && other )

noexcept

Move constructs a Matrix.

Parameters

other Matrix to move from.

Member Function Documentation

◆ get_local_matrix()

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

std::shared_ptr<const LinOp> gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::get_local_matrix ( ) const

inline

Get read access to the stored local matrix.

Returns: Shared pointer to the stored local matrix

◆ get_non_local_matrix()

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

std::shared_ptr<const LinOp> gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::get_non_local_matrix ( ) const

inline

Get read access to the stored non-local matrix.

Returns: Shared pointer to the stored non-local matrix

◆ operator=() [1/2]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

Matrix& gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::operator= ( const Matrix< ValueType, LocalIndexType, GlobalIndexType > & other )

Copy assigns a Matrix.

Parameters

other Matrix to copy from, has to have a communicator of the same size as this.

Returns: this.

◆ operator=() [2/2]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

Matrix& gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::operator= ( Matrix< ValueType, LocalIndexType, GlobalIndexType > && other )

Move assigns a Matrix.

Parameters

other Matrix to move from, has to have a communicator of the same size as this.

Returns: this.

◆ read_distributed() [1/4]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

void gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::read_distributed	(	const device_matrix_data< value_type, global_index_type > &	data,
		ptr_param< const Partition< local_index_type, global_index_type >>	partition
	)

Reads a square matrix from the device_matrix_data structure and a global partition.

The global size of the final matrix is inferred from the size of the partition. Both the number of rows and columns of the device_matrix_data are ignored.

Note: The matrix data can contain entries for rows other than those owned by the process. Entries for those rows are discarded.

Parameters

data	The device_matrix_data structure.
partition	The global row and column partition.

◆ read_distributed() [2/4]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

void gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::read_distributed	(	const device_matrix_data< value_type, global_index_type > &	data,
		ptr_param< const Partition< local_index_type, global_index_type >>	row_partition,
		ptr_param< const Partition< local_index_type, global_index_type >>	col_partition
	)

Reads a matrix from the device_matrix_data structure, a global row partition, and a global column partition.

The global size of the final matrix is inferred from the size of the row partition and the size of the column partition. Both the number of rows and columns of the device_matrix_data are ignored.

Note: The matrix data can contain entries for rows other than those owned by the process. Entries for those rows are discarded.

Parameters

data	The device_matrix_data structure.
row_partition	The global row partition.
col_partition	The global col partition.

◆ read_distributed() [3/4]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

void gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::read_distributed	(	const matrix_data< value_type, global_index_type > &	data,
		ptr_param< const Partition< local_index_type, global_index_type >>	partition
	)

Reads a square matrix from the matrix_data structure and a global partition.

See also: read_distributed

Note: For efficiency it is advised to use the device_matrix_data overload.

◆ read_distributed() [4/4]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>

void gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >::read_distributed	(	const matrix_data< value_type, global_index_type > &	data,
		ptr_param< const Partition< local_index_type, global_index_type >>	row_partition,
		ptr_param< const Partition< local_index_type, global_index_type >>	col_partition
	)

Reads a matrix from the matrix_data structure, a global row partition, and a global column partition.

See also: read_distributed

Note: For efficiency it is advised to use the device_matrix_data overload.

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

ginkgo/core/distributed/matrix.hpp

Public Types

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64> class gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >

Constructor & Destructor Documentation

◆ Matrix() [1/2]

◆ Matrix() [2/2]

Member Function Documentation

◆ get_local_matrix()

◆ get_non_local_matrix()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ read_distributed() [1/4]

◆ read_distributed() [2/4]

◆ read_distributed() [3/4]

◆ read_distributed() [4/4]

template<typename ValueType = default_precision, typename LocalIndexType = int32, typename GlobalIndexType = int64>
class gko::experimental::distributed::Matrix< ValueType, LocalIndexType, GlobalIndexType >