multigrid.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 1999 - 2026 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_multigrid_h
#define dealii_multigrid_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/enable_observer_pointer.h>
#include <deal.II/base/mg_level_object.h>
#include <deal.II/base/observer_pointer.h>
 
#include <deal.II/distributed/tria.h>
 
#include <deal.II/dofs/dof_handler.h>
 
#include <deal.II/lac/sparse_matrix.h>
#include <deal.II/lac/vector.h>
 
#include <deal.II/multigrid/mg_base.h>
 
#include <boost/signals2.hpp>
 
#include <vector>
 
 
DEAL_II_NAMESPACE_OPEN
 
#ifdef signals
#  error \
    "The name 'signals' is already defined. You are most likely using the QT library \
and using the 'signals' keyword. You can either #include the Qt headers (or any conflicting headers) \
*after* the deal.II headers or you can define the 'QT_NO_KEYWORDS' macro and use the 'Q_SIGNALS' macro."
#endif
 
namespace mg
{
  struct Signals
  {
    boost::signals2::signal<void(const bool before)> transfer_to_mg;
 
    boost::signals2::signal<void(const bool before)> transfer_to_global;
 
    boost::signals2::signal<void(const bool before, const unsigned int level)>
      coarse_solve;
 
    boost::signals2::signal<void(const bool before, const unsigned int level)>
      restriction;
 
    boost::signals2::signal<void(const bool before, const unsigned int level)>
      prolongation;
 
    boost::signals2::signal<void(const bool before, const unsigned int level)>
      pre_smoother_step;
 
    boost::signals2::signal<void(const bool before, const unsigned int level)>
      post_smoother_step;
 
    boost::signals2::signal<void(const bool before, const unsigned int level)>
      residual_step;
 
    boost::signals2::signal<void(const bool before, const unsigned int level)>
      edge_prolongation;
  };
} // namespace mg
 
template <typename VectorType>
class Multigrid : public EnableObserverPointer
{
public:
  enum Cycle
  {
    v_cycle,
    w_cycle,
    f_cycle
  };
 
  using vector_type       = VectorType;
  using const_vector_type = const VectorType;
 
  Multigrid(const MGMatrixBase<VectorType>     &matrix,
            const MGCoarseGridBase<VectorType> &coarse,
            const MGTransferBase<VectorType>   &transfer,
            const MGSmootherBase<VectorType>   &pre_smooth,
            const MGSmootherBase<VectorType>   &post_smooth,
            const unsigned int                  minlevel = 0,
            const unsigned int maxlevel = numbers::invalid_unsigned_int,
            Cycle              cycle    = v_cycle);
 
  void
  reinit(const unsigned int minlevel, const unsigned int maxlevel);
 
  void
  cycle();
 
  void
  vcycle();
 
  void
  set_edge_matrices(const MGMatrixBase<VectorType> &edge_out,
                    const MGMatrixBase<VectorType> &edge_in);
 
  void
  set_edge_in_matrix(const MGMatrixBase<VectorType> &edge_in);
 
  void
  set_edge_flux_matrices(const MGMatrixBase<VectorType> &edge_down,
                         const MGMatrixBase<VectorType> &edge_up);
 
  unsigned int
  get_maxlevel() const;
 
  unsigned int
  get_minlevel() const;
 
  void
  set_maxlevel(const unsigned int);
 
  void
  set_minlevel(const unsigned int level, bool relative = false);
 
  void set_cycle(Cycle);
 
  boost::signals2::connection
  connect_pre_smoother_step(
    const std::function<void(const bool, const unsigned int)> &slot);
 
  boost::signals2::connection
  connect_residual_step(
    const std::function<void(const bool, const unsigned int)> &slot);
 
  boost::signals2::connection
  connect_restriction(
    const std::function<void(const bool, const unsigned int)> &slot);
 
  boost::signals2::connection
  connect_coarse_solve(
    const std::function<void(const bool, const unsigned int)> &slot);
 
  boost::signals2::connection
  connect_prolongation(
    const std::function<void(const bool, const unsigned int)> &slot);
 
  boost::signals2::connection
  connect_edge_prolongation(
    const std::function<void(const bool, const unsigned int)> &slot);
 
  boost::signals2::connection
  connect_post_smoother_step(
    const std::function<void(const bool, const unsigned int)> &slot);
 
private:
  mg::Signals signals;
 
  void
  level_v_step(const unsigned int level);
 
  void
  level_step(const unsigned int level,
             const Cycle        cycle,
             const unsigned int iteration);
 
  Cycle cycle_type;
 
  unsigned int minlevel;
 
  unsigned int maxlevel;
 
public:
  MGLevelObject<VectorType> defect;
 
  MGLevelObject<VectorType> solution;
 
private:
  MGLevelObject<VectorType> t;
 
  MGLevelObject<VectorType> defect2;
 
 
  ObserverPointer<const MGMatrixBase<VectorType>, Multigrid<VectorType>> matrix;
 
  ObserverPointer<const MGCoarseGridBase<VectorType>, Multigrid<VectorType>>
    coarse;
 
  ObserverPointer<const MGTransferBase<VectorType>, Multigrid<VectorType>>
    transfer;
 
  ObserverPointer<const MGSmootherBase<VectorType>, Multigrid<VectorType>>
    pre_smooth;
 
  ObserverPointer<const MGSmootherBase<VectorType>, Multigrid<VectorType>>
    post_smooth;
 
  ObserverPointer<const MGMatrixBase<VectorType>> edge_out;
 
  ObserverPointer<const MGMatrixBase<VectorType>> edge_in;
 
  ObserverPointer<const MGMatrixBase<VectorType>, Multigrid<VectorType>>
    edge_down;
 
  ObserverPointer<const MGMatrixBase<VectorType>, Multigrid<VectorType>>
    edge_up;
 
  template <int dim, typename OtherVectorType, typename TransferType>
  friend class PreconditionMG;
};
 
 
template <int dim, typename VectorType, typename TransferType>
class PreconditionMG : public EnableObserverPointer
{
public:
  PreconditionMG(const DoFHandler<dim> &dof_handler,
                 Multigrid<VectorType> &mg,
                 const TransferType    &transfer);
 
  PreconditionMG(const std::vector<const DoFHandler<dim> *> &dof_handler,
                 Multigrid<VectorType>                      &mg,
                 const TransferType                         &transfer);
 
  bool
  empty() const;
 
  template <typename OtherVectorType>
  void
  vmult(OtherVectorType &dst, const OtherVectorType &src) const;
 
  template <typename OtherVectorType>
  void
  vmult_add(OtherVectorType &dst, const OtherVectorType &src) const;
 
  template <typename OtherVectorType>
  void
  Tvmult(OtherVectorType &dst, const OtherVectorType &src) const;
 
  template <typename OtherVectorType>
  void
  Tvmult_add(OtherVectorType &dst, const OtherVectorType &src) const;
 
  IndexSet
  locally_owned_range_indices(const unsigned int block = 0) const;
 
  IndexSet
  locally_owned_domain_indices(const unsigned int block = 0) const;
 
  MPI_Comm
  get_mpi_communicator() const;
 
  boost::signals2::connection
  connect_transfer_to_mg(const std::function<void(bool)> &slot);
 
  boost::signals2::connection
  connect_transfer_to_global(const std::function<void(bool)> &slot);
 
  Multigrid<VectorType> &
  get_multigrid();
 
  const Multigrid<VectorType> &
  get_multigrid() const;
 
private:
  std::vector<ObserverPointer<const DoFHandler<dim>,
                              PreconditionMG<dim, VectorType, TransferType>>>
    dof_handler_vector;
 
  std::vector<const DoFHandler<dim> *> dof_handler_vector_raw;
 
  ObserverPointer<Multigrid<VectorType>,
                  PreconditionMG<dim, VectorType, TransferType>>
    multigrid;
 
  ObserverPointer<const TransferType,
                  PreconditionMG<dim, VectorType, TransferType>>
    transfer;
 
  const bool uses_dof_handler_vector;
 
  mg::Signals signals;
};
 
#ifndef DOXYGEN
/* --------------------------- inline functions --------------------- */
 
 
template <typename VectorType>
Multigrid<VectorType>::Multigrid(const MGMatrixBase<VectorType>     &matrix,
                                 const MGCoarseGridBase<VectorType> &coarse,
                                 const MGTransferBase<VectorType>   &transfer,
                                 const MGSmootherBase<VectorType>   &pre_smooth,
                                 const MGSmootherBase<VectorType> &post_smooth,
                                 const unsigned int                min_level,
                                 const unsigned int                max_level,
                                 Cycle                             cycle)
  : cycle_type(cycle)
  , matrix(&matrix, typeid(*this).name())
  , coarse(&coarse, typeid(*this).name())
  , transfer(&transfer, typeid(*this).name())
  , pre_smooth(&pre_smooth, typeid(*this).name())
  , post_smooth(&post_smooth, typeid(*this).name())
  , edge_out(nullptr, typeid(*this).name())
  , edge_in(nullptr, typeid(*this).name())
  , edge_down(nullptr, typeid(*this).name())
  , edge_up(nullptr, typeid(*this).name())
{
  if (max_level == numbers::invalid_unsigned_int)
    maxlevel = matrix.get_maxlevel();
  else
    maxlevel = max_level;
  reinit(min_level, maxlevel);
}
 
 
 
template <typename VectorType>
inline unsigned int
Multigrid<VectorType>::get_maxlevel() const
{
  return maxlevel;
}
 
 
 
template <typename VectorType>
inline unsigned int
Multigrid<VectorType>::get_minlevel() const
{
  return minlevel;
}
 
 
/* --------------------------- inline functions --------------------- */
 
 
namespace internal
{
  namespace PreconditionMGImplementation
  {
    template <typename DoFHandlerType,
              typename VectorType,
              typename TransferType,
              typename OtherVectorType>
    using get_dof_handler_vector_support =
      decltype(std::declval<TransferType>().copy_from_mg(
        std::vector<const DoFHandlerType *>{},
        std::declval<OtherVectorType &>(),
        std::declval<MGLevelObject<VectorType>>()));
 
    template <typename DoFHandlerType,
              typename VectorType,
              typename TransferType,
              typename OtherVectorType>
    constexpr bool supports_dof_handler_vector =
      ::internal::is_supported_operation<get_dof_handler_vector_support,
                                                 DoFHandlerType,
                                                 VectorType,
                                                 TransferType,
                                                 OtherVectorType>;
 
    template <int dim,
              typename VectorType,
              typename TransferType,
              typename OtherVectorType>
    void
    vmult(const std::vector<const DoFHandler<dim> *> &dof_handler_vector,
          Multigrid<VectorType>                      &multigrid,
          const TransferType                         &transfer,
          OtherVectorType                            &dst,
          const OtherVectorType                      &src,
          const bool                                  uses_dof_handler_vector,
          const typename ::mg::Signals         &signals)
    {
      if constexpr (supports_dof_handler_vector<DoFHandler<dim>,
                                                VectorType,
                                                TransferType,
                                                OtherVectorType>)
        {
          signals.transfer_to_mg(true);
          if (uses_dof_handler_vector)
            transfer.copy_to_mg(dof_handler_vector, multigrid.defect, src);
          else
            transfer.copy_to_mg(*dof_handler_vector[0], multigrid.defect, src);
          signals.transfer_to_mg(false);
 
          multigrid.cycle();
 
          signals.transfer_to_global(true);
          if (uses_dof_handler_vector)
            transfer.copy_from_mg(dof_handler_vector, dst, multigrid.solution);
          else
            transfer.copy_from_mg(*dof_handler_vector[0],
                                  dst,
                                  multigrid.solution);
          signals.transfer_to_global(false);
        }
      else
        {
          (void)uses_dof_handler_vector;
          Assert(!uses_dof_handler_vector, ExcInternalError());
 
          signals.transfer_to_mg(true);
          transfer.copy_to_mg(*dof_handler_vector[0], multigrid.defect, src);
          signals.transfer_to_mg(false);
 
          multigrid.cycle();
 
          signals.transfer_to_global(true);
          transfer.copy_from_mg(*dof_handler_vector[0],
                                dst,
                                multigrid.solution);
          signals.transfer_to_global(false);
        }
    }
 
    template <int dim,
              typename VectorType,
              typename TransferType,
              typename OtherVectorType>
    void
    vmult_add(const std::vector<const DoFHandler<dim> *> &dof_handler_vector,
              Multigrid<VectorType>                      &multigrid,
              const TransferType                         &transfer,
              OtherVectorType                            &dst,
              const OtherVectorType                      &src,
              const bool                          uses_dof_handler_vector,
              const typename ::mg::Signals &signals)
    {
      if constexpr (supports_dof_handler_vector<DoFHandler<dim>,
                                                VectorType,
                                                TransferType,
                                                OtherVectorType>)
        {
          signals.transfer_to_mg(true);
          if (uses_dof_handler_vector)
            transfer.copy_to_mg(dof_handler_vector, multigrid.defect, src);
          else
            transfer.copy_to_mg(*dof_handler_vector[0], multigrid.defect, src);
          signals.transfer_to_mg(false);
 
          multigrid.cycle();
 
          signals.transfer_to_global(true);
          if (uses_dof_handler_vector)
            transfer.copy_from_mg_add(dof_handler_vector,
                                      dst,
                                      multigrid.solution);
          else
            transfer.copy_from_mg_add(*dof_handler_vector[0],
                                      dst,
                                      multigrid.solution);
          signals.transfer_to_global(false);
        }
      else
        {
          (void)uses_dof_handler_vector;
          Assert(!uses_dof_handler_vector, ExcInternalError());
 
          signals.transfer_to_mg(true);
          transfer.copy_to_mg(*dof_handler_vector[0], multigrid.defect, src);
          signals.transfer_to_mg(false);
 
          multigrid.cycle();
 
          signals.transfer_to_global(true);
          transfer.copy_from_mg_add(*dof_handler_vector[0],
                                    dst,
                                    multigrid.solution);
          signals.transfer_to_global(false);
        }
    }
  } // namespace PreconditionMGImplementation
} // namespace internal
 
template <int dim, typename VectorType, typename TransferType>
PreconditionMG<dim, VectorType, TransferType>::PreconditionMG(
  const DoFHandler<dim> &dof_handler,
  Multigrid<VectorType> &mg,
  const TransferType    &transfer)
  : dof_handler_vector(1, &dof_handler)
  , dof_handler_vector_raw(1, &dof_handler)
  , multigrid(&mg)
  , transfer(&transfer)
  , uses_dof_handler_vector(false)
{}
 
template <int dim, typename VectorType, typename TransferType>
PreconditionMG<dim, VectorType, TransferType>::PreconditionMG(
  const std::vector<const DoFHandler<dim> *> &dof_handler,
  Multigrid<VectorType>                      &mg,
  const TransferType                         &transfer)
  : dof_handler_vector(dof_handler.size())
  , dof_handler_vector_raw(dof_handler.size())
  , multigrid(&mg)
  , transfer(&transfer)
  , uses_dof_handler_vector(true)
{
  for (unsigned int i = 0; i < dof_handler.size(); ++i)
    {
      dof_handler_vector[i]     = dof_handler[i];
      dof_handler_vector_raw[i] = dof_handler[i];
    }
}
 
template <int dim, typename VectorType, typename TransferType>
inline bool
PreconditionMG<dim, VectorType, TransferType>::empty() const
{
  return false;
}
 
template <int dim, typename VectorType, typename TransferType>
template <typename OtherVectorType>
void
PreconditionMG<dim, VectorType, TransferType>::vmult(
  OtherVectorType       &dst,
  const OtherVectorType &src) const
{
  internal::PreconditionMGImplementation::vmult(dof_handler_vector_raw,
                                                *multigrid,
                                                *transfer,
                                                dst,
                                                src,
                                                uses_dof_handler_vector,
                                                this->signals);
}
 
 
template <int dim, typename VectorType, typename TransferType>
IndexSet
PreconditionMG<dim, VectorType, TransferType>::locally_owned_range_indices(
  const unsigned int block) const
{
  AssertIndexRange(block, dof_handler_vector.size());
  return dof_handler_vector[block]->locally_owned_dofs();
}
 
 
template <int dim, typename VectorType, typename TransferType>
IndexSet
PreconditionMG<dim, VectorType, TransferType>::locally_owned_domain_indices(
  const unsigned int block) const
{
  AssertIndexRange(block, dof_handler_vector.size());
  return dof_handler_vector[block]->locally_owned_dofs();
}
 
 
 
template <int dim, typename VectorType, typename TransferType>
MPI_Comm
PreconditionMG<dim, VectorType, TransferType>::get_mpi_communicator() const
{
  // currently parallel GMG works with parallel triangulations only,
  // so it should be a safe bet to use it to query MPI communicator:
  const Triangulation<dim> &tria = dof_handler_vector[0]->get_triangulation();
  const parallel::TriangulationBase<dim> *ptria =
    dynamic_cast<const parallel::TriangulationBase<dim> *>(&tria);
  Assert(ptria != nullptr, ExcInternalError());
  return ptria->get_mpi_communicator();
}
 
 
 
template <int dim, typename VectorType, typename TransferType>
boost::signals2::connection
PreconditionMG<dim, VectorType, TransferType>::connect_transfer_to_mg(
  const std::function<void(bool)> &slot)
{
  return this->signals.transfer_to_mg.connect(slot);
}
 
 
 
template <int dim, typename VectorType, typename TransferType>
boost::signals2::connection
PreconditionMG<dim, VectorType, TransferType>::connect_transfer_to_global(
  const std::function<void(bool)> &slot)
{
  return this->signals.transfer_to_global.connect(slot);
}
 
 
 
template <int dim, typename VectorType, typename TransferType>
template <typename OtherVectorType>
void
PreconditionMG<dim, VectorType, TransferType>::vmult_add(
  OtherVectorType       &dst,
  const OtherVectorType &src) const
{
  internal::PreconditionMGImplementation::vmult_add(dof_handler_vector_raw,
                                                    *multigrid,
                                                    *transfer,
                                                    dst,
                                                    src,
                                                    uses_dof_handler_vector,
                                                    this->signals);
}
 
 
template <int dim, typename VectorType, typename TransferType>
template <typename OtherVectorType>
void
PreconditionMG<dim, VectorType, TransferType>::Tvmult(
  OtherVectorType &,
  const OtherVectorType &) const
{
  DEAL_II_NOT_IMPLEMENTED();
}
 
 
template <int dim, typename VectorType, typename TransferType>
template <typename OtherVectorType>
void
PreconditionMG<dim, VectorType, TransferType>::Tvmult_add(
  OtherVectorType &,
  const OtherVectorType &) const
{
  DEAL_II_NOT_IMPLEMENTED();
}
 
 
template <int dim, typename VectorType, typename TransferType>
Multigrid<VectorType> &
PreconditionMG<dim, VectorType, TransferType>::get_multigrid()
{
  return *this->multigrid;
}
 
 
template <int dim, typename VectorType, typename TransferType>
const Multigrid<VectorType> &
PreconditionMG<dim, VectorType, TransferType>::get_multigrid() const
{
  return *this->multigrid;
}
 
#endif // DOXYGEN
 
DEAL_II_NAMESPACE_CLOSE
 
#endif