template_constraints.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) 2003 - 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_template_constraints_h
#define dealii_template_constraints_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/complex_overloads.h>
#include <deal.II/base/mpi_stub.h>
#include <deal.II/base/std_cxx20/type_traits.h>
 
#include <deal.II/lac/trilinos_tpetra_to_trilinos_wrappers.h>
#include <deal.II/lac/vector_operation.h>
 
#include <complex>
#include <type_traits>
#include <utility>
 
 
DEAL_II_NAMESPACE_OPEN
 
// Detection idiom adapted from Version 2 of the C++ Extensions for Library
// Fundamentals, ISO/IEC TS 19568:2017
namespace internal
{
  namespace SupportsOperation
  {
    template <class...>
    using void_t = void;
 
    template <class Default,
              class AlwaysVoid,
              template <class...>
              class Op,
              class... Args>
    struct detector
    {
      using value_t = std::false_type;
      using type    = Default;
    };
 
    template <class Default, template <class...> class Op, class... Args>
    struct detector<Default, void_t<Op<Args...>>, Op, Args...>
    {
      using value_t = std::true_type;
      using type    = Op<Args...>;
    };
 
 
    struct nonesuch_base
    {};
 
    struct nonesuch : private nonesuch_base
    {
      ~nonesuch()                = delete;
      nonesuch(const nonesuch &) = delete;
      void
      operator=(const nonesuch &) = delete;
    };
 
    template <class Default, template <class...> class Op, class... Args>
    using detected_or = detector<Default, void, Op, Args...>;
 
    template <template <class...> class Op, class... Args>
    using is_detected = typename detected_or<nonesuch, Op, Args...>::value_t;
 
    template <template <class...> class Op, class... Args>
    using detected_t = typename detected_or<nonesuch, Op, Args...>::type;
 
    template <class Default, template <class...> class Op, class... Args>
    using detected_or_t = typename detected_or<Default, Op, Args...>::type;
 
    template <class Expected, template <class...> class Op, class... Args>
    using is_detected_exact = std::is_same<Expected, detected_t<Op, Args...>>;
 
    template <class To, template <class...> class Op, class... Args>
    using is_detected_convertible =
      std::is_convertible<detected_t<Op, Args...>, To>;
  } // namespace SupportsOperation
 
 
  template <template <class...> class Op, class... Args>
  constexpr bool is_supported_operation =
    SupportsOperation::is_detected<Op, Args...>::value;
} // namespace internal
 
 
 
namespace internal
{
  namespace TemplateConstraints
  {
    template <bool... Values>
    struct all_true
    {
      static constexpr bool value = (Values && ...);
    };
 
 
    template <bool... Values>
    struct any_true
    {
      static constexpr bool value = (Values || ...);
    };
  } // namespace TemplateConstraints
} // namespace internal
 
template <class Base, class... Derived>
struct is_base_of_all
{
  static constexpr bool value = internal::TemplateConstraints::all_true<
    std::is_base_of_v<Base, Derived>...>::value;
};
 
 
 
template <typename Type, class... Types>
struct all_same_as
{
  static constexpr bool value = internal::TemplateConstraints::all_true<
    std::is_same_v<Type, Types>...>::value;
};
 
 
 
template <typename Type, class... Types>
struct is_same_as_any_of
{
  static constexpr bool value = internal::TemplateConstraints::any_true<
    std::is_same_v<Type, Types>...>::value;
};
 
 
 
/*
 * A generalization of `std::enable_if` that only works if
 * <i>all</i> of the given boolean template parameters are
 * true. See [here](https://en.cppreference.com/w/cpp/types/enable_if)
 * for what `std::enable_if` does.
 *
 * @note
 * In contrast to `std::enable_if`, this template has no additional
 * template type (which for `std::enable_if` is defaulted to `void`).
 * As a consequence, this structure cannot be used for anything other
 * than enabling or disabling a template declaration; in particular
 * it cannot be used to set the return type of a function as one might
 * do with something like
 * @code
 *   template <typename T>
 *   typename std::enable_if<std::is_floating_point_v<T>, T>::type
 *   abs (const T t);
 * @endcode
 * which declares a function template `abs()` that can only be
 * instantiated if `T` is a floating point type; this function then
 * returns an object of type `T` as indicated by the last argument to
 * `std::enable_if`. The reason `enable_if_all` does not allow providing
 * this additional type is that variadic templates (here, the list of
 * `bool` arguments) must be the last template argument.
 */
template <bool... Values>
struct enable_if_all
  : std::enable_if<internal::TemplateConstraints::all_true<Values...>::value>
{};
 
 
 
/*
 * A generalization of `std::enable_if_t` that only works if
 * <i>all</i> of the given boolean template parameters are
 * true. See [here](https://en.cppreference.com/w/cpp/types/enable_if)
 * for what `std::enable_if_t` does.
 *
 * @note
 * In contrast to `std::enable_if_t`, this template has no additional
 * template type (which for `std::enable_if` is defaulted to `void`).
 * As a consequence, this structure cannot be used for anything other
 * than enabling or disabling a template declaration; in particular
 * it cannot be used to set the return type of a function as one might
 * do with something like
 * @code
 *   template <typename T>
 *   std::enable_if_t<std::is_floating_point_v<T>, T>
 *   abs (const T t);
 * @endcode
 * which declares a function template `abs()` that can only be
 * instantiated if `T` is a floating point type; this function then
 * returns an object of type `T` as indicated by the last argument to
 * `std::enable_if`. The reason `enable_if_all` does not allow providing
 * this additional type is that variadic templates (here, the list of
 * `bool` arguments) must be the last template argument.
 */
template <bool... Values>
using enable_if_all_t = typename enable_if_all<Values...>::type;
 
 
template <typename T>
using begin_and_end_t =
  decltype(std::begin(std::declval<T>()), std::end(std::declval<T>()));
 
template <typename T>
constexpr bool has_begin_and_end =
  internal::is_supported_operation<begin_and_end_t, T>;
 
 
template <typename ArgType, typename ValueType>
struct always_return
{
  ValueType value;
  ValueType
  operator()(const ArgType &)
  {
    return value;
  }
};
 
 
 
struct PointerComparison
{
  template <typename T>
  static bool
  equal(const T *p1, const T *p2)
  {
    return (p1 == p2);
  }
 
 
  template <typename T, typename U>
  static bool
  equal(const T *, const U *)
  {
    return false;
  }
};
 
 
 
namespace internal
{
  template <typename T, typename U>
  struct ProductTypeImpl
  {
    using type = decltype(std::declval<T>() * std::declval<U>());
  };
 
} // namespace internal
 
 
 
template <typename T, typename U>
struct ProductType
{
  using type =
    typename internal::ProductTypeImpl<std::decay_t<T>, std::decay_t<U>>::type;
};
 
namespace internal
{
  // Annoyingly, there is no std::complex<T>::operator*(U) for scalars U
  // other than T (not even in C++11, or C++14). We provide our own overloads
  // in base/complex_overloads.h, but in order for them to work, we have to
  // manually specify all products we want to allow:
 
  template <typename T>
  struct ProductTypeImpl<std::complex<T>, std::complex<T>>
  {
    using type = std::complex<T>;
  };
 
  template <typename T, typename U>
  struct ProductTypeImpl<std::complex<T>, std::complex<U>>
  {
    using type = std::complex<typename ProductType<T, U>::type>;
  };
 
  template <typename U>
  struct ProductTypeImpl<double, std::complex<U>>
  {
    using type = std::complex<typename ProductType<double, U>::type>;
  };
 
  template <typename T>
  struct ProductTypeImpl<std::complex<T>, double>
  {
    using type = std::complex<typename ProductType<T, double>::type>;
  };
 
  template <typename U>
  struct ProductTypeImpl<float, std::complex<U>>
  {
    using type = std::complex<typename ProductType<float, U>::type>;
  };
 
  template <typename T>
  struct ProductTypeImpl<std::complex<T>, float>
  {
    using type = std::complex<typename ProductType<T, float>::type>;
  };
 
} // namespace internal
 
 
 
template <typename T>
struct EnableIfScalar;
 
 
template <>
struct EnableIfScalar<double>
{
  using type = double;
};
 
template <>
struct EnableIfScalar<float>
{
  using type = float;
};
 
template <>
struct EnableIfScalar<long double>
{
  using type = long double;
};
 
template <>
struct EnableIfScalar<int>
{
  using type = int;
};
 
template <>
struct EnableIfScalar<unsigned int>
{
  using type = unsigned int;
};
 
template <typename T>
struct EnableIfScalar<std::complex<T>>
{
  using type = std::complex<T>;
};
 
 
// Forward declarations of vector types
template <typename Number>
class Vector;
 
template <typename Number>
class BlockVector;
 
namespace LinearAlgebra
{
  template <typename Number>
  class ReadWriteVector;
 
  namespace distributed
  {
    template <typename Number, typename MemorySpace>
    class Vector;
 
    template <typename Number, typename MemorySpace>
    class BlockVector;
  } // namespace distributed
} // namespace LinearAlgebra
 
#ifdef DEAL_II_WITH_PETSC
namespace PETScWrappers
{
  class VectorBase;
  class Vector;
  class BlockVector;
 
  namespace MPI
  {
    class Vector;
    class BlockVector;
 
    class SparseMatrix;
    class BlockSparseMatrix;
  } // namespace MPI
} // namespace PETScWrappers
#endif
 
#ifdef DEAL_II_WITH_TRILINOS
#  if defined(DEAL_II_TRILINOS_WITH_EPETRA)
namespace LinearAlgebra
{
  namespace EpetraWrappers
  {
    class Vector;
  }
} // namespace LinearAlgebra
#  endif
#endif
 
 
 
namespace concepts
{
#if defined(DEAL_II_HAVE_CXX20) || defined(DOXYGEN)
  template <typename C>
  concept is_contiguous_container = requires(C &c) {
    {
      std::data(c)
    };
    {
      std::size(c)
    };
  };
 
 
  template <int dim, int spacedim>
  concept is_valid_dim_spacedim =
    (dim >= 1 && spacedim <= 3 && dim <= spacedim);
 
  namespace internal
  {
    template <typename T>
    inline constexpr bool is_dealii_vector_type = false;
 
    template <typename Number>
    inline constexpr bool is_dealii_vector_type<::Vector<Number>> = true;
 
    template <typename Number>
    inline constexpr bool is_dealii_vector_type<::BlockVector<Number>> =
      true;
 
    template <typename Number>
    inline constexpr bool
      is_dealii_vector_type<::LinearAlgebra::ReadWriteVector<Number>> =
        true;
 
    template <typename Number, typename MemorySpace>
    inline constexpr bool is_dealii_vector_type<
      ::LinearAlgebra::distributed::Vector<Number, MemorySpace>> = true;
 
    template <typename Number, typename MemorySpace>
    inline constexpr bool is_dealii_vector_type<
      ::LinearAlgebra::distributed::BlockVector<Number, MemorySpace>> =
      true;
 
#  ifdef DEAL_II_WITH_PETSC
    template <>
    inline constexpr bool is_dealii_vector_type<::PETScWrappers::Vector> =
      true;
 
    template <>
    inline constexpr bool
      is_dealii_vector_type<::PETScWrappers::BlockVector> = true;
 
    template <>
    inline constexpr bool
      is_dealii_vector_type<::PETScWrappers::MPI::Vector> = true;
 
    template <>
    inline constexpr bool
      is_dealii_vector_type<::PETScWrappers::MPI::BlockVector> = true;
#  endif
 
#  ifdef DEAL_II_WITH_TRILINOS
#    if defined(DEAL_II_TRILINOS_WITH_EPETRA)
    template <>
    inline constexpr bool
      is_dealii_vector_type<::TrilinosWrappers::MPI::Vector> = true;
 
    template <>
    inline constexpr bool
      is_dealii_vector_type<::TrilinosWrappers::MPI::BlockVector> = true;
 
    template <>
    inline constexpr bool
      is_dealii_vector_type<::LinearAlgebra::EpetraWrappers::Vector> =
        true;
#    endif
 
#    ifdef DEAL_II_TRILINOS_WITH_TPETRA
    template <typename Number, typename MemorySpace>
    inline constexpr bool is_dealii_vector_type<
      ::LinearAlgebra::TpetraWrappers::Vector<Number, MemorySpace>> =
      true;
 
    template <typename Number, typename MemorySpace>
    inline constexpr bool is_dealii_vector_type<
      ::LinearAlgebra::TpetraWrappers::BlockVector<Number, MemorySpace>> =
      true;
#    endif
#  endif
 
 
    template <typename T>
    inline constexpr bool is_dealii_petsc_vector_type = false;
 
#  ifdef DEAL_II_WITH_PETSC
    template <>
    inline constexpr bool
      is_dealii_petsc_vector_type<::PETScWrappers::VectorBase> = true;
 
    template <>
    inline constexpr bool
      is_dealii_petsc_vector_type<::PETScWrappers::Vector> = true;
 
    template <>
    inline constexpr bool
      is_dealii_petsc_vector_type<::PETScWrappers::BlockVector> = true;
 
    template <>
    inline constexpr bool
      is_dealii_petsc_vector_type<::PETScWrappers::MPI::Vector> = true;
 
    template <>
    inline constexpr bool
      is_dealii_petsc_vector_type<::PETScWrappers::MPI::BlockVector> =
        true;
#  endif
 
 
    template <typename T>
    inline constexpr bool is_dealii_petsc_matrix_type = false;
 
#  ifdef DEAL_II_WITH_PETSC
    template <>
    inline constexpr bool
      is_dealii_petsc_matrix_type<::PETScWrappers::MPI::SparseMatrix> =
        true;
 
    template <>
    inline constexpr bool is_dealii_petsc_matrix_type<
      ::PETScWrappers::MPI::BlockSparseMatrix> = true;
#  endif
  } // namespace internal
 
 
  template <typename VectorType>
  concept is_dealii_vector_type =
    internal::is_dealii_vector_type<std::remove_cv_t<VectorType>>;
 
  template <typename VectorType>
  concept is_writable_dealii_vector_type =
    is_dealii_vector_type<VectorType> && (std::is_const_v<VectorType> == false);
 
  template <typename VectorType>
  concept is_dealii_petsc_vector_type =
    internal::is_dealii_petsc_vector_type<VectorType>;
 
  template <typename VectorType>
  concept is_dealii_petsc_matrix_type =
    internal::is_dealii_petsc_matrix_type<VectorType>;
#endif
} // namespace concepts
 
 
template <int dim, int spacedim>
DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
class Triangulation;
 
template <int dim, int spacedim>
DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
class DoFHandler;
 
namespace parallel
{
  namespace distributed
  {
    template <int dim, int spacedim>
    DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
    class Triangulation;
  }
  namespace shared
  {
    template <int dim, int spacedim>
    DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
    class Triangulation;
  }
  namespace fullydistributed
  {
    template <int dim, int spacedim>
    DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
    class Triangulation;
  }
} // namespace parallel
 
namespace concepts
{
  namespace internal
  {
    template <class T>
    inline constexpr bool is_distributed_vector_type = false;
 
    // ---- deal.II LA distributed vectors ----
    template <typename Number, typename MemorySpace>
    inline constexpr bool is_distributed_vector_type<
      ::LinearAlgebra::distributed::Vector<Number, MemorySpace>> = true;
 
    template <typename Number, typename MemorySpace>
    inline constexpr bool is_distributed_vector_type<
      ::LinearAlgebra::distributed::BlockVector<Number, MemorySpace>> =
      true;
 
#ifdef DEAL_II_TRILINOS_WITH_EPETRA
    template <>
    inline constexpr bool
      is_distributed_vector_type<::TrilinosWrappers::MPI::Vector> = true;
 
    template <>
    inline constexpr bool
      is_distributed_vector_type<::TrilinosWrappers::MPI::BlockVector> =
        true;
#endif
 
#ifdef DEAL_II_WITH_PETSC
    template <>
    inline constexpr bool
      is_distributed_vector_type<::PETScWrappers::MPI::Vector> = true;
 
    template <>
    inline constexpr bool
      is_distributed_vector_type<::PETScWrappers::MPI::BlockVector> =
        true;
#endif
  } // namespace internal
 
#if defined(DEAL_II_HAVE_CXX20) || defined(DOXYGEN)
  namespace internal
  {
    template <typename T>
    inline constexpr bool is_triangulation_or_dof_handler = false;
 
    template <int dim, int spacedim>
    inline constexpr bool
      is_triangulation_or_dof_handler<Triangulation<dim, spacedim>> = true;
 
    template <int dim, int spacedim>
    inline constexpr bool is_triangulation_or_dof_handler<
      parallel::distributed::Triangulation<dim, spacedim>> = true;
 
    template <int dim, int spacedim>
    inline constexpr bool is_triangulation_or_dof_handler<
      parallel::shared::Triangulation<dim, spacedim>> = true;
 
    template <int dim, int spacedim>
    inline constexpr bool is_triangulation_or_dof_handler<
      parallel::fullydistributed::Triangulation<dim, spacedim>> = true;
 
    template <int dim, int spacedim>
    inline constexpr bool
      is_triangulation_or_dof_handler<DoFHandler<dim, spacedim>> = true;
  } // namespace internal
 
 
  template <typename MeshType>
  concept is_triangulation_or_dof_handler =
    internal::is_triangulation_or_dof_handler<MeshType>;
 
  template <typename VectorType>
  concept is_vector_space_vector = requires(VectorType                      U,
                                            VectorType                      V,
                                            VectorType                      W,
                                            typename VectorType::value_type a,
                                            typename VectorType::value_type b,
                                            typename VectorType::value_type s,
                                            VectorOperation::values operation) {
    // Check local type requirements:
    typename VectorType::value_type;
    typename VectorType::size_type;
    typename VectorType::real_type;
 
    // Check some assignment and reinit operations;
    U.reinit(V);
    U.reinit(V, /* omit_zeroing_entries= */ true);
 
    U = V;
    U = a; // assignment of scalar
 
    U.equ(a, V);
 
    // Check scaling operations
    U *= a;
    U /= a;
 
    U.scale(V);
 
    // Vector additions:
    U += V;
    U -= V;
 
    U.add(a);
    U.add(a, V);
    U.add(a, V, b, W);
 
    U.sadd(s, a, V);
 
    // Norms and similar stuff:
    {
      U.mean_value()
    } -> std::convertible_to<typename VectorType::value_type>;
 
    {
      U.l1_norm()
    } -> std::convertible_to<typename VectorType::real_type>;
 
    {
      U.l2_norm()
    } -> std::convertible_to<typename VectorType::real_type>;
 
    {
      U.linfty_norm()
    } -> std::convertible_to<typename VectorType::real_type>;
 
    // Dot products:
    {
      U *V
    } -> std::convertible_to<typename VectorType::value_type>;
 
    {
      U.add_and_dot(a, V, W)
    } -> std::convertible_to<typename VectorType::value_type>;
 
    // Some queries:
    {
      U.size()
    } -> std::convertible_to<typename VectorType::size_type>;
 
    {
      U.all_zero()
    } -> std::same_as<bool>;
 
    {
      U.get_mpi_communicator()
    } -> std::same_as<MPI_Comm>;
 
    // Synchronization:
    {
      U.compress(operation)
    } -> std::same_as<void>;
  };
 
 
  template <typename MatrixType, typename VectorType>
  concept is_linear_operator_on =
    requires(const MatrixType &A, VectorType &dst, const VectorType &src) {
      A.vmult(dst, src);
    };
 
 
  template <typename MatrixType, typename VectorType>
  concept is_transpose_linear_operator_on =
    requires(const MatrixType &A, VectorType &dst, const VectorType &src) {
      A.Tvmult(dst, src);
    };
 
#endif
 
} // namespace concepts
 
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif