Ginkgo: gko::experimental::distributed Namespace Reference

| Ginkgo Generated from branch based on main. Ginkgo version 1.11.0 A numerical linear algebra library targeting many-core architectures

Loading...
Searching...
No Matches
gko::experimental::distributed Namespace Reference

The distributed namespace. More...

## Namespaces
namespace | preconditioner
| The Preconditioner namespace.

## Classes
class | Partition
| Represents a partition of a range of indices [0, size) into a disjoint set of parts. More...
class | DistributedBase
| A base class for distributed objects. More...
class | index_map
| This class defines mappings between global and local indices. More...
class | Vector
| Vector is a format which explicitly stores (multiple) distributed column vectors in a dense storage format. More...
class | Matrix
| The Matrix class defines a (MPI-)distributed matrix. More...
class | RowGatherer
| The distributed::RowGatherer gathers the rows of distributed::Vector that are located on other processes. More...

## Typedefs
using | comm_index_type
| Make mpi::comm_index_type available in this namespace.

## Enumerations
enum class | index_space { local , non_local , combined }
| Index space classification for the locally stored indices. More...
enum class | assembly_mode { communicate , local_only }
| assembly_mode defines how the read_distributed function of the distributed matrix treats non-local indices in the (device_)matrix_data: More...

## Functions
template<typename ValueType>
gko::detail::temporary_conversion< Vector< ValueType > > | make_temporary_conversion (LinOp *matrix)
| Convert the given LinOp from experimental::distributed::Vector<...> to experimental::distributed::Vector<ValueType>.
template<typename ValueType>
gko::detail::temporary_conversion< const Vector< ValueType > > | make_temporary_conversion (const LinOp *matrix)
| Convert the given LinOp from experimental::distributed::Vector<...> to experimental::distributed::Vector<ValueType>.
template<typename ValueType, typename Function, typename... Args>
void | precision_dispatch (Function fn, Args *... linops)
| Calls the given function with each given argument LinOp temporarily converted into experimental::distributed::Vector<ValueType> as parameters.
template<typename ValueType, typename Function>
void | mixed_precision_dispatch (Function fn, const LinOp *in, LinOp *out)
template<typename ValueType, typename Function>
void | precision_dispatch_real_complex (Function fn, const LinOp *in, LinOp *out)
| Calls the given function with the given LinOps temporarily converted to experimental::distributed::Vector<ValueType>* as parameters.
template<typename ValueType, typename Function>
void | mixed_precision_dispatch_real_complex (Function fn, const LinOp *in, LinOp *out)
template<typename ValueType, typename Function>
void | precision_dispatch_real_complex (Function fn, const LinOp *alpha, const LinOp *in, LinOp *out)
| Calls the given function with the given LinOps temporarily converted to experimental::distributed::Vector<ValueType>* as parameters.
template<typename ValueType, typename Function>
void | precision_dispatch_real_complex (Function fn, const LinOp *alpha, const LinOp *in, const LinOp *beta, LinOp *out)
| Calls the given function with the given LinOps temporarily converted to experimental::distributed::Vector<ValueType>* as parameters.
template<typename ValueType, typename LocalIndexType, typename GlobalIndexType>
device_matrix_data< ValueType, GlobalIndexType > | assemble_rows_from_neighbors (mpi::communicator comm, const device_matrix_data< ValueType, GlobalIndexType > &input, ptr_param< const Partition< LocalIndexType, GlobalIndexType > > partition)
| Assembles device_matrix_data entries owned by this MPI rank from other ranks and communicates entries located on this MPI rank owned by other ranks to their respective owners.
template<typename LocalIndexType, typename GlobalIndexType>
std::unique_ptr< Partition< LocalIndexType, GlobalIndexType > > | build_partition_from_local_range (std::shared_ptr< const Executor > exec, mpi::communicator comm, span local_range)
| Builds a partition from a local range.
template<typename LocalIndexType, typename GlobalIndexType>
std::unique_ptr< Partition< LocalIndexType, GlobalIndexType > > | build_partition_from_local_size (std::shared_ptr< const Executor > exec, mpi::communicator comm, size_type local_size)
| Builds a partition from a local size.

## Detailed Description

The distributed namespace.

## Enumeration Type Documentation

## ◆ assembly_mode

enum class gko::experimental::distributed::assembly_mode
| strong

assembly_mode defines how the read_distributed function of the distributed matrix treats non-local indices in the (device_)matrix_data:

- communicate communicates the overlap between ranks and adds up all local contributions. Indices smaller than 0 or larger than the global size of the matrix are ignored.
- local_only does not communicate any overlap but ignores all non-local indices.

## ◆ index_space

enum class gko::experimental::distributed::index_space
| strong

Index space classification for the locally stored indices.

The definitions of the enum values is clarified in index_map.

Enumerator
local | indices that are locally owned
non_local | indices that are owned by other processes
combined | both local and non_local indices

## Function Documentation

## ◆ assemble_rows_from_neighbors()

template<typename ValueType, typename LocalIndexType, typename GlobalIndexType>

device_matrix_data< ValueType, GlobalIndexType > gko::experimental::distributed::assemble_rows_from_neighbors | ( | mpi::communicator | comm,
|  | const device_matrix_data< ValueType, GlobalIndexType > & | input,
|  | ptr_param< const Partition< LocalIndexType, GlobalIndexType > > | partition )

Assembles device_matrix_data entries owned by this MPI rank from other ranks and communicates entries located on this MPI rank owned by other ranks to their respective owners.

This can be useful e.g. in a finite element code where each rank assembles a local contribution to a global system matrix and the global matrix has to be assembled by summing up the local contributions on rank boundaries. The partition used is only relevant for row ownership.

Parameters

  comm | the communicator used to assemble the global matrix.
  input | the device_matrix_data structure.
  partition | the partition used to determine row owndership.

Returns
  the globally assembled device_matrix_data structure for this MPI rank.

## ◆ build_partition_from_local_range()

template<typename LocalIndexType, typename GlobalIndexType>

std::unique_ptr< Partition< LocalIndexType, GlobalIndexType > > gko::experimental::distributed::build_partition_from_local_range | ( | std::shared_ptr< const Executor > | exec,
|  | mpi::communicator | comm,
|  | span | local_range )

Builds a partition from a local range.

Parameters

  exec | the Executor on which the partition should be built.
  comm | the communicator used to determine the global partition.
  local_range | the start and end indices of the local range.

Warning
  This throws, if the resulting partition would contain gaps. That means that for a partition of size n every local range r_i = [s_i, e_i) either s_i != 0 and another local range r_j = [s_j, e_j = s_i) exists, or e_i != n and another local range r_j = [s_j = e_i, e_j) exists.

Returns
  a Partition where each range has the individual local_start and local_ends.

## ◆ build_partition_from_local_size()

template<typename LocalIndexType, typename GlobalIndexType>

std::unique_ptr< Partition< LocalIndexType, GlobalIndexType > > gko::experimental::distributed::build_partition_from_local_size | ( | std::shared_ptr< const Executor > | exec,
|  | mpi::communicator | comm,
|  | size_type | local_size )

Builds a partition from a local size.

Parameters

  exec | the Executor on which the partition should be built.
  comm | the communicator used to determine the global partition.
  local_range | the number of the locally owned indices

Returns
  a Partition where each range has the specified local size. More specifically, if this is called on process i with local_size s_i, then the range i has size s_i, and range r_i = [start, start + s_i), where start = sum_j^(i-1) s_j.

## ◆ make_temporary_conversion() [1/2]

template<typename ValueType>

gko::detail::temporary_conversion< const Vector< ValueType > > gko::experimental::distributed::make_temporary_conversion | ( | const LinOp * | matrix | ) |

Convert the given LinOp from experimental::distributed::Vector<...> to experimental::distributed::Vector<ValueType>.

The conversion tries to convert the input LinOp to all Dense types with value type recursively reachable by next_precision_base<...> starting from the ValueType template parameter. This means that all real-to-real and complex-to-complex conversions for default precisions are being considered. If the input matrix is non-const, the contents of the modified converted object will be converted back to the input matrix when the returned object is destroyed. This may lead to a loss of precision!

Parameters

  matrix | the input matrix which is supposed to be converted. It is wrapped unchanged if it is already of type experimental::distributed::Vector<ValueType>, otherwise it will be converted to this type if possible.

Returns
  a detail::temporary_conversion pointing to the (potentially converted) object.

Exceptions

  NotSupported | if the input matrix cannot be converted to experimental::distributed::Vector<ValueType>

Template Parameters

  ValueType | the value type into whose associated Vector type to convert the input LinOp.

## ◆ make_temporary_conversion() [2/2]

template<typename ValueType>

gko::detail::temporary_conversion< Vector< ValueType > > gko::experimental::distributed::make_temporary_conversion | ( | LinOp * | matrix | ) |

Convert the given LinOp from experimental::distributed::Vector<...> to experimental::distributed::Vector<ValueType>.

The conversion tries to convert the input LinOp to all Dense types with value type recursively reachable by next_precision_base<...> starting from the ValueType template parameter. This means that all real-to-real and complex-to-complex conversions for default precisions are being considered. If the input matrix is non-const, the contents of the modified converted object will be converted back to the input matrix when the returned object is destroyed. This may lead to a loss of precision!

Parameters

  matrix | the input matrix which is supposed to be converted. It is wrapped unchanged if it is already of type experimental::distributed::Vector<ValueType>, otherwise it will be converted to this type if possible.

Returns
  a detail::temporary_conversion pointing to the (potentially converted) object.

Exceptions

  NotSupported | if the input matrix cannot be converted to experimental::distributed::Vector<ValueType>

Template Parameters

  ValueType | the value type into whose associated Vector type to convert the input LinOp.

Referenced by precision_dispatch(), precision_dispatch_real_complex(), precision_dispatch_real_complex(), and precision_dispatch_real_complex().

## ◆ precision_dispatch()

template<typename ValueType, typename Function, typename... Args>

void gko::experimental::distributed::precision_dispatch | ( | Function | fn,
|  | Args *... | linops )

Calls the given function with each given argument LinOp temporarily converted into experimental::distributed::Vector<ValueType> as parameters.

Parameters

  fn | the given function. It will be passed one (potentially const) experimental::distributed::Vector<ValueType>* parameter per parameter in the parameter pack linops.
  linops | the given arguments to be converted and passed on to fn.

Template Parameters

  ValueType | the value type to use for the parameters of fn.
  Function | the function pointer, lambda or other functor type to call with the converted arguments.
  Args | the argument type list.

References make_temporary_conversion().

Referenced by precision_dispatch_real_complex().

## ◆ precision_dispatch_real_complex() [1/3]

template<typename ValueType, typename Function>

void gko::experimental::distributed::precision_dispatch_real_complex | ( | Function | fn,
|  | const LinOp * | alpha,
|  | const LinOp * | in,
|  | const LinOp * | beta,
|  | LinOp * | out )

Calls the given function with the given LinOps temporarily converted to experimental::distributed::Vector<ValueType>* as parameters.

If ValueType is real and both input vectors are complex, uses experimental::distributed::Vector::get_real_view() to convert them into real matrices after precision conversion.

See also
  precision_dispatch()

References gko::is_complex(), make_temporary_conversion(), and gko::make_temporary_conversion().

## ◆ precision_dispatch_real_complex() [2/3]

template<typename ValueType, typename Function>

void gko::experimental::distributed::precision_dispatch_real_complex | ( | Function | fn,
|  | const LinOp * | alpha,
|  | const LinOp * | in,
|  | LinOp * | out )

Calls the given function with the given LinOps temporarily converted to experimental::distributed::Vector<ValueType>* as parameters.

If ValueType is real and both input vectors are complex, uses experimental::distributed::Vector::get_real_view() to convert them into real matrices after precision conversion.

See also
  precision_dispatch()

References gko::is_complex(), make_temporary_conversion(), and gko::make_temporary_conversion().

## ◆ precision_dispatch_real_complex() [3/3]

template<typename ValueType, typename Function>

void gko::experimental::distributed::precision_dispatch_real_complex | ( | Function | fn,
|  | const LinOp * | in,
|  | LinOp * | out )

Calls the given function with the given LinOps temporarily converted to experimental::distributed::Vector<ValueType>* as parameters.

If ValueType is real and both input vectors are complex, uses experimental::distributed::Vector::get_real_view() to convert them into real matrices after precision conversion.

See also
  precision_dispatch()

References gko::is_complex(), make_temporary_conversion(), and precision_dispatch().