Ginkgo  Generated from pipelines/2017069469 branch based on develop. Ginkgo version 1.11.0
A numerical linear algebra library targeting many-core architectures
matrix.hpp
1 // SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
2 //
3 // SPDX-License-Identifier: BSD-3-Clause
4 
5 #ifndef GKO_PUBLIC_CORE_DISTRIBUTED_MATRIX_HPP_
6 #define GKO_PUBLIC_CORE_DISTRIBUTED_MATRIX_HPP_
7 
8 
9 #include <ginkgo/config.hpp>
10 
11 
12 #if GINKGO_BUILD_MPI
13 
14 
15 #include <ginkgo/core/base/dense_cache.hpp>
16 #include <ginkgo/core/base/lin_op.hpp>
17 #include <ginkgo/core/base/mpi.hpp>
18 #include <ginkgo/core/base/std_extensions.hpp>
19 #include <ginkgo/core/distributed/base.hpp>
20 #include <ginkgo/core/distributed/index_map.hpp>
21 #include <ginkgo/core/distributed/row_gatherer.hpp>
22 #include <ginkgo/core/distributed/vector_cache.hpp>
23 
24 
25 namespace gko {
26 namespace matrix {
27 
28 
29 template <typename ValueType, typename IndexType>
30 class Csr;
31 
32 
33 }
34 
35 
36 namespace multigrid {
37 
38 
39 template <typename ValueType, typename IndexType>
40 class Pgm;
41 
42 
43 }
44 
45 
46 namespace detail {
47 
48 
53 template <typename Builder, typename ValueType, typename IndexType,
54  typename = void>
55 struct is_matrix_type_builder : std::false_type {};
56 
57 
58 template <typename Builder, typename ValueType, typename IndexType>
59 struct is_matrix_type_builder<
60  Builder, ValueType, IndexType,
61  xstd::void_t<
62  decltype(std::declval<Builder>().template create<ValueType, IndexType>(
63  std::declval<std::shared_ptr<const Executor>>()))>>
64  : std::true_type {};
65 
66 
67 template <template <typename, typename> class MatrixType,
68  typename... CreateArgs>
69 struct MatrixTypeBuilderFromValueAndIndex {
70  template <typename ValueType, typename IndexType, std::size_t... I>
71  auto create_impl(std::shared_ptr<const Executor> exec,
72  std::index_sequence<I...>)
73  {
74  return MatrixType<ValueType, IndexType>::create(
75  exec, std::get<I>(create_args)...);
76  }
77 
78 
79  template <typename ValueType, typename IndexType>
80  auto create(std::shared_ptr<const Executor> exec)
81  {
82  // with c++17 we could use std::apply
83  static constexpr auto size = sizeof...(CreateArgs);
84  return create_impl<ValueType, IndexType>(
85  std::move(exec), std::make_index_sequence<size>{});
86  }
87 
88  std::tuple<CreateArgs...> create_args;
89 };
90 
91 
92 } // namespace detail
93 
94 
126 template <template <typename, typename> class MatrixType, typename... Args>
127 auto with_matrix_type(Args&&... create_args)
128 {
129  return detail::MatrixTypeBuilderFromValueAndIndex<MatrixType, Args...>{
130  std::forward_as_tuple(create_args...)};
131 }
132 
133 
134 namespace experimental {
135 namespace distributed {
136 
137 
147 enum class assembly_mode { communicate, local_only };
148 
149 
150 template <typename LocalIndexType, typename GlobalIndexType>
151 class Partition;
152 template <typename ValueType>
153 class Vector;
154 
155 
260 template <typename ValueType = default_precision,
261  typename LocalIndexType = int32, typename GlobalIndexType = int64>
262 class Matrix
263  : public EnableLinOp<Matrix<ValueType, LocalIndexType, GlobalIndexType>>,
264  public ConvertibleTo<
265  Matrix<next_precision<ValueType>, LocalIndexType, GlobalIndexType>>,
266 #if GINKGO_ENABLE_HALF || GINKGO_ENABLE_BFLOAT16
267  public ConvertibleTo<Matrix<next_precision<ValueType, 2>, LocalIndexType,
268  GlobalIndexType>>,
269 #endif
270 #if GINKGO_ENABLE_HALF && GINKGO_ENABLE_BFLOAT16
271  public ConvertibleTo<Matrix<next_precision<ValueType, 3>, LocalIndexType,
272  GlobalIndexType>>,
273 #endif
274  public DistributedBase {
275  friend class EnablePolymorphicObject<Matrix, LinOp>;
276  friend class Matrix<previous_precision<ValueType>, LocalIndexType,
277  GlobalIndexType>;
278  friend class multigrid::Pgm<ValueType, LocalIndexType>;
279 
280 
281 public:
282  using value_type = ValueType;
283  using index_type = GlobalIndexType;
284  using local_index_type = LocalIndexType;
285  using global_index_type = GlobalIndexType;
286  using global_vector_type =
288  using local_vector_type = typename global_vector_type::local_vector_type;
289 
293  GlobalIndexType>>::convert_to;
295  GlobalIndexType>>::move_to;
296 
297  void convert_to(Matrix<next_precision<value_type>, local_index_type,
298  global_index_type>* result) const override;
299 
300  void move_to(Matrix<next_precision<value_type>, local_index_type,
301  global_index_type>* result) override;
302 
303 #if GINKGO_ENABLE_HALF || GINKGO_ENABLE_BFLOAT16
304  friend class Matrix<previous_precision<ValueType, 2>, LocalIndexType,
305  GlobalIndexType>;
307  global_index_type>>::convert_to;
309  global_index_type>>::move_to;
310 
311  void convert_to(Matrix<next_precision<value_type, 2>, local_index_type,
312  global_index_type>* result) const override;
313 
314  void move_to(Matrix<next_precision<value_type, 2>, local_index_type,
315  global_index_type>* result) override;
316 #endif
317 
318 #if GINKGO_ENABLE_HALF && GINKGO_ENABLE_BFLOAT16
319  friend class Matrix<previous_precision<ValueType, 3>, LocalIndexType,
320  GlobalIndexType>;
322  global_index_type>>::convert_to;
324  global_index_type>>::move_to;
325 
326  void convert_to(Matrix<next_precision<value_type, 3>, local_index_type,
327  global_index_type>* result) const override;
328 
329  void move_to(Matrix<next_precision<value_type, 3>, local_index_type,
330  global_index_type>* result) override;
331 #endif
332 
349  void read_distributed(
352  partition,
353  assembly_mode assembly_type = assembly_mode::local_only);
354 
364  void read_distributed(
367  partition,
368  assembly_mode assembly_type = assembly_mode::local_only);
369 
388  void read_distributed(
391  row_partition,
393  col_partition,
394  assembly_mode assembly_type = assembly_mode::local_only);
395 
405  void read_distributed(
408  row_partition,
410  col_partition,
411  assembly_mode assembly_type = assembly_mode::local_only);
412 
418  std::shared_ptr<const LinOp> get_local_matrix() const { return local_mtx_; }
419 
425  std::shared_ptr<const LinOp> get_non_local_matrix() const
426  {
427  return non_local_mtx_;
428  }
429 
435  Matrix(const Matrix& other);
436 
442  Matrix(Matrix&& other) noexcept;
443 
452  Matrix& operator=(const Matrix& other);
453 
462  Matrix& operator=(Matrix&& other);
463 
473  static std::unique_ptr<Matrix> create(std::shared_ptr<const Executor> exec,
474  mpi::communicator comm);
475 
496  template <typename MatrixType,
497  typename = std::enable_if_t<gko::detail::is_matrix_type_builder<
498  MatrixType, ValueType, LocalIndexType>::value>>
499  static std::unique_ptr<Matrix> create(std::shared_ptr<const Executor> exec,
500  mpi::communicator comm,
501  MatrixType matrix_template)
502  {
503  return create(
504  exec, comm,
505  matrix_template.template create<ValueType, LocalIndexType>(exec));
506  }
507 
536  template <typename LocalMatrixType, typename NonLocalMatrixType,
537  typename = std::enable_if_t<
538  gko::detail::is_matrix_type_builder<
539  LocalMatrixType, ValueType, LocalIndexType>::value &&
540  gko::detail::is_matrix_type_builder<
541  NonLocalMatrixType, ValueType, LocalIndexType>::value>>
542  static std::unique_ptr<Matrix> create(
543  std::shared_ptr<const Executor> exec, mpi::communicator comm,
544  LocalMatrixType local_matrix_template,
545  NonLocalMatrixType non_local_matrix_template)
546  {
547  return create(
548  exec, comm,
549  local_matrix_template.template create<ValueType, LocalIndexType>(
550  exec),
551  non_local_matrix_template
552  .template create<ValueType, LocalIndexType>(exec));
553  }
554 
569  static std::unique_ptr<Matrix> create(
570  std::shared_ptr<const Executor> exec, mpi::communicator comm,
571  ptr_param<const LinOp> matrix_template);
572 
589  static std::unique_ptr<Matrix> create(
590  std::shared_ptr<const Executor> exec, mpi::communicator comm,
591  ptr_param<const LinOp> local_matrix_template,
592  ptr_param<const LinOp> non_local_matrix_template);
593 
606  static std::unique_ptr<Matrix> create(std::shared_ptr<const Executor> exec,
607  mpi::communicator comm, dim<2> size,
608  std::shared_ptr<LinOp> local_linop);
609 
628  [[deprecated(
629  "Please use the overload with an index_map instead.")]] static std::
630  unique_ptr<Matrix>
631  create(std::shared_ptr<const Executor> exec, mpi::communicator comm,
632  dim<2> size, std::shared_ptr<LinOp> local_linop,
633  std::shared_ptr<LinOp> non_local_linop,
634  std::vector<comm_index_type> recv_sizes,
635  std::vector<comm_index_type> recv_offsets,
636  array<local_index_type> recv_gather_idxs);
637 
651  static std::unique_ptr<Matrix> create(
652  std::shared_ptr<const Executor> exec, mpi::communicator comm,
654  std::shared_ptr<LinOp> local_linop,
655  std::shared_ptr<LinOp> non_local_linop);
656 
664  void col_scale(ptr_param<const global_vector_type> scaling_factors);
665 
673  void row_scale(ptr_param<const global_vector_type> scaling_factors);
674 
675 protected:
676  explicit Matrix(std::shared_ptr<const Executor> exec,
677  mpi::communicator comm);
678 
679  explicit Matrix(std::shared_ptr<const Executor> exec,
680  mpi::communicator comm,
681  ptr_param<const LinOp> local_matrix_template,
682  ptr_param<const LinOp> non_local_matrix_template);
683 
684  explicit Matrix(std::shared_ptr<const Executor> exec,
685  mpi::communicator comm, dim<2> size,
686  std::shared_ptr<LinOp> local_linop);
687 
688  explicit Matrix(std::shared_ptr<const Executor> exec,
689  mpi::communicator comm,
691  std::shared_ptr<LinOp> local_linop,
692  std::shared_ptr<LinOp> non_local_linop);
693 
694  void apply_impl(const LinOp* b, LinOp* x) const override;
695 
696  void apply_impl(const LinOp* alpha, const LinOp* b, const LinOp* beta,
697  LinOp* x) const override;
698 
699 private:
700  std::shared_ptr<RowGatherer<LocalIndexType>> row_gatherer_;
702  gko::detail::ScalarCache one_scalar_;
703  detail::GenericVectorCache recv_buffer_;
704  detail::GenericVectorCache host_recv_buffer_;
705  std::shared_ptr<LinOp> local_mtx_;
706  std::shared_ptr<LinOp> non_local_mtx_;
707 };
708 
709 
710 } // namespace distributed
711 } // namespace experimental
712 } // namespace gko
713 
714 
715 #endif
716 
717 
718 #endif // GKO_PUBLIC_CORE_DISTRIBUTED_MATRIX_HPP_
gko::with_matrix_type
auto with_matrix_type(Args &&... create_args)
This function returns a type that delays a call to MatrixType::create.
Definition: matrix.hpp:127
gko::matrix::Csr
CSR is a matrix format which stores only the nonzero coefficients by compressing each row of the matr...
Definition: matrix.hpp:30
gko::experimental::distributed::assembly_mode
assembly_mode
assembly_mode defines how the read_distributed function of the distributed matrix treats non-local in...
Definition: matrix.hpp:147
gko::LinOp
Definition: lin_op.hpp:117
gko::matrix::Dense< value_type >
gko::experimental::distributed::Matrix
The Matrix class defines a (MPI-)distributed matrix.
Definition: matrix.hpp:262
gko::experimental::distributed::Vector
Vector is a format which explicitly stores (multiple) distributed column vectors in a dense storage f...
Definition: matrix.hpp:153
gko::experimental::distributed::Matrix::get_local_matrix
std::shared_ptr< const LinOp > get_local_matrix() const
Get read access to the stored local matrix.
Definition: matrix.hpp:418
gko::experimental::distributed::Matrix::create
static std::unique_ptr< Matrix > create(std::shared_ptr< const Executor > exec, mpi::communicator comm, LocalMatrixType local_matrix_template, NonLocalMatrixType non_local_matrix_template)
Creates an empty distributed matrix with specified types for the local matrix and the non-local matri...
Definition: matrix.hpp:542
gko::experimental::distributed::Matrix::col_scale
void col_scale(ptr_param< const global_vector_type > scaling_factors)
Scales the columns of the matrix by the respective entries of the vector.
gko::experimental::distributed::Matrix::create
static std::unique_ptr< Matrix > create(std::shared_ptr< const Executor > exec, mpi::communicator comm)
Creates an empty distributed matrix.
gko
The Ginkgo namespace.
Definition: abstract_factory.hpp:20
gko::experimental::distributed::Matrix::get_non_local_matrix
std::shared_ptr< const LinOp > get_non_local_matrix() const
Get read access to the stored non-local matrix.
Definition: matrix.hpp:425
gko::array< local_index_type >
gko::multigrid::Pgm
Parallel graph match (Pgm) is the aggregate method introduced in the paper M.
Definition: matrix.hpp:40
gko::experimental::mpi::communicator
A thin wrapper of MPI_Comm that supports most MPI calls.
Definition: mpi.hpp:419
gko::dim< 2 >
gko::matrix_data
This structure is used as an intermediate data type to store a sparse matrix.
Definition: matrix_data.hpp:126
gko::ptr_param
This class is used for function parameters in the place of raw pointers.
Definition: utils_helper.hpp:41
gko::next_precision
typename detail::find_precision_impl< T, step >::type next_precision
Obtains the next move type of T in the singly-linked precision corresponding bfloat16/half.
Definition: math.hpp:466
gko::experimental::distributed::Partition
Represents a partition of a range of indices [0, size) into a disjoint set of parts.
Definition: assembly.hpp:26
gko::previous_precision
typename detail::find_precision_impl< T, -step >::type previous_precision
Obtains the previous move type of T in the singly-linked precision corresponding bfloat16/half.
Definition: math.hpp:473
gko::experimental::distributed::Matrix::operator=
Matrix & operator=(const Matrix &other)
Copy assigns a Matrix.
gko::int64
std::int64_t int64
64-bit signed integral type.
Definition: types.hpp:113
gko::default_precision
double default_precision
Precision used if no precision is explicitly specified.
Definition: types.hpp:172
gko::ConvertibleTo
ConvertibleTo interface is used to mark that the implementer can be converted to the object of Result...
Definition: polymorphic_object.hpp:479
gko::int32
std::int32_t int32
32-bit signed integral type.
Definition: types.hpp:107
gko::experimental::distributed::Matrix::create
static std::unique_ptr< Matrix > create(std::shared_ptr< const Executor > exec, mpi::communicator comm, MatrixType matrix_template)
Creates an empty distributed matrix with specified type for local matrices.
Definition: matrix.hpp:499
gko::experimental::distributed::DistributedBase
A base class for distributed objects.
Definition: base.hpp:32
gko::experimental::distributed::index_map< local_index_type, global_index_type >
gko::experimental::distributed::Matrix::read_distributed
void read_distributed(const device_matrix_data< value_type, global_index_type > &data, std::shared_ptr< const Partition< local_index_type, global_index_type >> partition, assembly_mode assembly_type=assembly_mode::local_only)
Reads a square matrix from the device_matrix_data structure and a global partition.
gko::experimental::distributed::Matrix::row_scale
void row_scale(ptr_param< const global_vector_type > scaling_factors)
Scales the rows of the matrix by the respective entries of the vector.
gko::device_matrix_data
This type is a device-side equivalent to matrix_data.
Definition: device_matrix_data.hpp:36
gko::experimental::distributed::Matrix::Matrix
Matrix(const Matrix &other)
Copy constructs a Matrix.
gko::EnableLinOp
The EnableLinOp mixin can be used to provide sensible default implementations of the majority of the ...
Definition: lin_op.hpp:877
gko::EnablePolymorphicObject
This mixin inherits from (a subclass of) PolymorphicObject and provides a base implementation of a ne...
Definition: polymorphic_object.hpp:667