dof_accessor.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 1998 - 2023 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Part of the source code is dual licensed under Apache-2.0 WITH
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information
// governing the source code and code contributions can be found in
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
//
// ------------------------------------------------------------------------
 
#ifndef dealii_dof_accessor_h
#define dealii_dof_accessor_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/dofs/dof_handler.h>
#include <deal.II/dofs/dof_iterator_selector.h>
 
#include <deal.II/grid/tria_accessor.h>
 
#include <deal.II/lac/read_vector.h>
 
#include <boost/container/small_vector.hpp>
 
#include <set>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declarations
#ifndef DOXYGEN
template <typename number>
class FullMatrix;
template <typename number>
class Vector;
template <typename number>
class AffineConstraints;
 
template <typename Accessor>
class TriaRawIterator;
 
template <int, int>
class FiniteElement;
 
namespace internal
{
  namespace DoFCellAccessorImplementation
  {
    struct Implementation;
  }
 
  namespace DoFHandlerImplementation
  {
    struct Implementation;
    namespace Policy
    {
      struct Implementation;
    }
  } // namespace DoFHandlerImplementation
 
  namespace hp
  {
    namespace DoFHandlerImplementation
    {
      struct Implementation;
    }
  } // namespace hp
} // namespace internal
#endif
 
// note: the file dof_accessor.templates.h is included at the end of
// this file.  this includes a lot of templates and thus makes
// compilation slower, but at the same time allows for more aggressive
// inlining and thus faster code.
 
 
namespace internal
{
  namespace DoFAccessorImplementation
  {
    template <int structdim, int dim, int spacedim>
    struct Inheritance
    {
      using BaseClass = ::TriaAccessor<structdim, dim, spacedim>;
    };
 
 
    template <int dim, int spacedim>
    struct Inheritance<dim, dim, spacedim>
    {
      using BaseClass = ::CellAccessor<dim, spacedim>;
    };
 
    struct Implementation;
  } // namespace DoFAccessorImplementation
} // namespace internal
 
 
/* -------------------------------------------------------------------------- */
 
 
 
template <int structdim, int dim, int spacedim, bool level_dof_access>
class DoFAccessor : public ::internal::DoFAccessorImplementation::
                      Inheritance<structdim, dim, spacedim>::BaseClass
{
public:
  static constexpr unsigned int dimension = dim;
 
  static constexpr unsigned int space_dimension = spacedim;
 
  using BaseClass = typename ::internal::DoFAccessorImplementation::
    Inheritance<structdim, dimension, space_dimension>::BaseClass;
 
  using AccessorData = DoFHandler<dimension, space_dimension>;
 
  DoFAccessor();
 
  DoFAccessor(const Triangulation<dim, spacedim> *tria,
              const int                           level,
              const int                           index,
              const DoFHandler<dim, spacedim>    *dof_handler);
 
  DoFAccessor(const DoFAccessor<structdim, dim, spacedim, level_dof_access> &) =
    default;
 
  DoFAccessor(                                                    // NOLINT
    DoFAccessor<structdim, dim, spacedim, level_dof_access> &&) = // NOLINT
    default;                                                      // NOLINT
 
  ~DoFAccessor() = default;
 
  template <int structdim2, int dim2, int spacedim2>
  DoFAccessor(const InvalidAccessor<structdim2, dim2, spacedim2> &);
 
  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
  DoFAccessor(
    const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &);
 
  template <bool level_dof_access2>
  DoFAccessor(const DoFAccessor<structdim, dim, spacedim, level_dof_access2> &);
 
  DoFAccessor<structdim, dim, spacedim, level_dof_access> &
  operator=(const DoFAccessor<structdim, dim, spacedim, level_dof_access> &da) =
    delete;
 
  DoFAccessor<structdim, dim, spacedim, level_dof_access> &       // NOLINT
  operator=(                                                      // NOLINT
    DoFAccessor<structdim, dim, spacedim, level_dof_access> &&) = // NOLINT
    default;                                                      // NOLINT
 
  const DoFHandler<dim, spacedim> &
  get_dof_handler() const;
 
  template <bool level_dof_access2>
  void
  copy_from(const DoFAccessor<structdim, dim, spacedim, level_dof_access2> &a);
 
  void
  copy_from(const TriaAccessorBase<structdim, dim, spacedim> &da);
 
  static bool
  is_level_cell();
 
  TriaIterator<DoFAccessor<structdim, dim, spacedim, level_dof_access>>
  child(const unsigned int c) const;
 
  typename ::internal::DoFHandlerImplementation::
    Iterators<dim, spacedim, level_dof_access>::line_iterator
    line(const unsigned int i) const;
 
  typename ::internal::DoFHandlerImplementation::
    Iterators<dim, spacedim, level_dof_access>::quad_iterator
    quad(const unsigned int i) const;
 
  void
  get_dof_indices(
    std::vector<types::global_dof_index> &dof_indices,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  void
  get_mg_dof_indices(
    const int                             level,
    std::vector<types::global_dof_index> &dof_indices,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  void
  set_mg_dof_indices(
    const int                                   level,
    const std::vector<types::global_dof_index> &dof_indices,
    const types::fe_index fe_index = numbers::invalid_fe_index);
 
  types::global_dof_index
  vertex_dof_index(
    const unsigned int    vertex,
    const unsigned int    i,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  types::global_dof_index
  mg_vertex_dof_index(
    const int             level,
    const unsigned int    vertex,
    const unsigned int    i,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  types::global_dof_index
  dof_index(const unsigned int    i,
            const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  types::global_dof_index
  mg_dof_index(const int level, const unsigned int i) const;
 
  unsigned int
  n_active_fe_indices() const;
 
  types::fe_index
  nth_active_fe_index(const unsigned int n) const;
 
  std::set<types::fe_index>
  get_active_fe_indices() const;
 
  bool
  fe_index_is_active(const types::fe_index fe_index) const;
 
  const FiniteElement<dim, spacedim> &
  get_fe(const types::fe_index fe_index) const;
 
  DeclExceptionMsg(ExcInvalidObject,
                   "This accessor object has not been "
                   "associated with any DoFHandler object.");
  DeclException0(ExcVectorNotEmpty);
  DeclException0(ExcVectorDoesNotMatch);
  DeclException0(ExcMatrixDoesNotMatch);
  DeclException0(ExcNotActive);
  DeclException0(ExcCantCompareIterators);
 
protected:
  DoFHandler<dim, spacedim> *dof_handler;
 
public:
  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
  bool
  operator==(
    const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
 
  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
  bool
  operator!=(
    const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
 
protected:
  void
  set_dof_handler(DoFHandler<dim, spacedim> *dh);
 
  void
  set_dof_index(
    const unsigned int            i,
    const types::global_dof_index index,
    const types::fe_index         fe_index = numbers::invalid_fe_index) const;
 
  void
  set_mg_dof_index(const int                     level,
                   const unsigned int            i,
                   const types::global_dof_index index) const;
 
  void
  set_mg_vertex_dof_index(
    const int                     level,
    const unsigned int            vertex,
    const unsigned int            i,
    const types::global_dof_index index,
    const types::fe_index         fe_index = numbers::invalid_fe_index) const;
 
  // Iterator classes need to be friends because they need to access
  // operator== and operator!=.
  template <typename>
  friend class TriaRawIterator;
  template <int, int, int, bool>
  friend class DoFAccessor;
 
private:
  // Make the DoFHandler class a friend so that it can call the set_xxx()
  // functions.
  friend class DoFHandler<dim, spacedim>;
 
  friend struct ::internal::DoFHandlerImplementation::Policy::
    Implementation;
  friend struct ::internal::DoFHandlerImplementation::Implementation;
  friend struct ::internal::hp::DoFHandlerImplementation::Implementation;
  friend struct ::internal::DoFCellAccessorImplementation::Implementation;
  friend struct ::internal::DoFAccessorImplementation::Implementation;
};
 
 
 
template <int spacedim, bool level_dof_access>
class DoFAccessor<0, 1, spacedim, level_dof_access>
  : public TriaAccessor<0, 1, spacedim>
{
public:
  static constexpr unsigned int dimension = 1;
 
  static constexpr unsigned int space_dimension = spacedim;
 
  using BaseClass = TriaAccessor<0, 1, spacedim>;
 
  using AccessorData = DoFHandler<1, spacedim>;
 
  DoFAccessor();
 
  DoFAccessor(
    const Triangulation<1, spacedim>                       *tria,
    const typename TriaAccessor<0, 1, spacedim>::VertexKind vertex_kind,
    const unsigned int                                      vertex_index,
    const DoFHandler<1, spacedim>                          *dof_handler);
 
  DoFAccessor(const Triangulation<1, spacedim> *,
              const int                                  = 0,
              const int                                  = 0,
              const DoFHandler<1, spacedim> *dof_handler = 0);
 
  template <int structdim2, int dim2, int spacedim2>
  DoFAccessor(const InvalidAccessor<structdim2, dim2, spacedim2> &);
 
  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
  DoFAccessor(
    const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &);
 
  DoFAccessor(const DoFAccessor<0, 1, spacedim, level_dof_access> &) = default;
 
  // NOLINTNEXTLINE OSX does not compile with noexcept
  DoFAccessor(DoFAccessor<0, 1, spacedim, level_dof_access> &&) = default;
 
  ~DoFAccessor() = default;
 
  DoFAccessor<0, 1, spacedim, level_dof_access> &
  operator=(const DoFAccessor<0, 1, spacedim, level_dof_access> &da) = delete;
 
  DoFAccessor<0, 1, spacedim, level_dof_access> &
  operator=(DoFAccessor<0, 1, spacedim, level_dof_access> &&) noexcept =
    default;
 
  const DoFHandler<1, spacedim> &
  get_dof_handler() const;
 
  template <bool level_dof_access2>
  void
  copy_from(const DoFAccessor<0, 1, spacedim, level_dof_access2> &a);
 
  void
  copy_from(const TriaAccessorBase<0, 1, spacedim> &da);
 
  TriaIterator<DoFAccessor<0, 1, spacedim, level_dof_access>>
  child(const unsigned int c) const;
 
  typename ::internal::DoFHandlerImplementation::
    Iterators<1, spacedim, level_dof_access>::line_iterator
    line(const unsigned int i) const;
 
  typename ::internal::DoFHandlerImplementation::
    Iterators<1, spacedim, level_dof_access>::quad_iterator
    quad(const unsigned int i) const;
 
  void
  get_dof_indices(
    std::vector<types::global_dof_index> &dof_indices,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  void
  get_mg_dof_indices(
    const int                             level,
    std::vector<types::global_dof_index> &dof_indices,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  types::global_dof_index
  vertex_dof_index(
    const unsigned int    vertex,
    const unsigned int    i,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  types::global_dof_index
  dof_index(const unsigned int    i,
            const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  unsigned int
  n_active_fe_indices() const;
 
  types::fe_index
  nth_active_fe_index(const unsigned int n) const;
 
  bool
  fe_index_is_active(const types::fe_index fe_index) const;
 
  const FiniteElement<1, spacedim> &
  get_fe(const types::fe_index fe_index) const;
 
  DeclExceptionMsg(ExcInvalidObject,
                   "This accessor object has not been "
                   "associated with any DoFHandler object.");
  DeclException0(ExcVectorNotEmpty);
  DeclException0(ExcVectorDoesNotMatch);
  DeclException0(ExcMatrixDoesNotMatch);
  DeclException0(ExcNotActive);
  DeclException0(ExcCantCompareIterators);
 
protected:
  DoFHandler<1, spacedim> *dof_handler;
 
  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
  bool
  operator==(
    const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
 
  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
  bool
  operator!=(
    const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &) const;
 
  void
  set_dof_handler(DoFHandler<1, spacedim> *dh);
 
  void
  set_dof_index(
    const unsigned int            i,
    const types::global_dof_index index,
    const types::fe_index         fe_index = numbers::invalid_fe_index) const;
 
  // Iterator classes need to be friends because they need to access
  // operator== and operator!=.
  template <typename>
  friend class TriaRawIterator;
 
 
  // Make the DoFHandler class a friend so that it can call the set_xxx()
  // functions.
  friend class DoFHandler<1, spacedim>;
 
  friend struct ::internal::DoFHandlerImplementation::Policy::
    Implementation;
  friend struct ::internal::DoFHandlerImplementation::Implementation;
  friend struct ::internal::hp::DoFHandlerImplementation::Implementation;
  friend struct ::internal::DoFCellAccessorImplementation::Implementation;
};
 
 
 
/* -------------------------------------------------------------------------- */
 
 
template <int structdim, int dim, int spacedim = dim>
class DoFInvalidAccessor : public InvalidAccessor<structdim, dim, spacedim>
{
public:
  using AccessorData =
    typename InvalidAccessor<structdim, dim, spacedim>::AccessorData;
 
  DoFInvalidAccessor(const void         *parent     = nullptr,
                     const int           level      = -1,
                     const int           index      = -1,
                     const AccessorData *local_data = nullptr);
 
  DoFInvalidAccessor(const DoFInvalidAccessor<structdim, dim, spacedim> &);
 
  template <typename OtherAccessor>
  DoFInvalidAccessor(const OtherAccessor &);
 
  types::global_dof_index
  dof_index(const unsigned int    i,
            const types::fe_index fe_index =
              DoFHandler<dim, spacedim>::default_fe_index) const;
 
  void
  set_dof_index(
    const unsigned int            i,
    const types::global_dof_index index,
    const types::fe_index         fe_index = numbers::invalid_fe_index) const;
};
 
 
 
/* -------------------------------------------------------------------------- */
 
 
template <int dimension_, int space_dimension_, bool level_dof_access>
class DoFCellAccessor : public DoFAccessor<dimension_,
                                           dimension_,
                                           space_dimension_,
                                           level_dof_access>
{
public:
  static const unsigned int dim = dimension_;
 
  static const unsigned int spacedim = space_dimension_;
 
 
  using AccessorData = DoFHandler<dimension_, space_dimension_>;
 
  using BaseClass =
    DoFAccessor<dimension_, dimension_, space_dimension_, level_dof_access>;
 
  using Container = DoFHandler<dimension_, space_dimension_>;
 
  using face_iterator = TriaIterator<DoFAccessor<dimension_ - 1,
                                                 dimension_,
                                                 space_dimension_,
                                                 level_dof_access>>;
 
  DoFCellAccessor(const Triangulation<dimension_, space_dimension_> *tria,
                  const int                                          level,
                  const int                                          index,
                  const AccessorData *local_data);
 
  template <int structdim2, int dim2, int spacedim2>
  DoFCellAccessor(const InvalidAccessor<structdim2, dim2, spacedim2> &);
 
  template <int structdim2, int dim2, int spacedim2, bool level_dof_access2>
  explicit DoFCellAccessor(
    const DoFAccessor<structdim2, dim2, spacedim2, level_dof_access2> &);
 
  DoFCellAccessor(
    const DoFCellAccessor<dimension_, space_dimension_, level_dof_access> &) =
    default;
 
  DoFCellAccessor(                                                  // NOLINT
    DoFCellAccessor<dimension_, space_dimension_, level_dof_access> // NOLINT
      &&) = default;                                                // NOLINT
 
  ~DoFCellAccessor() = default;
 
  DoFCellAccessor<dimension_, space_dimension_, level_dof_access> &
  operator=(
    const DoFCellAccessor<dimension_, space_dimension_, level_dof_access> &da) =
    delete;
 
  DoFCellAccessor<dimension_, space_dimension_, level_dof_access> & // NOLINT
  operator=(                                                        // NOLINT
    DoFCellAccessor<dimension_, space_dimension_, level_dof_access> // NOLINT
      &&) = default;                                                // NOLINT
 
  TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
  parent() const;
 
  TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
  neighbor(const unsigned int i) const;
 
  TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
  periodic_neighbor(const unsigned int i) const;
 
  TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
  neighbor_or_periodic_neighbor(const unsigned int i) const;
 
  TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
  child(const unsigned int i) const;
 
  boost::container::small_vector<
    TriaIterator<
      DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>,
    GeometryInfo<dimension_>::max_children_per_cell>
  child_iterators() const;
 
  face_iterator
  face(const unsigned int i) const;
 
  boost::container::small_vector<face_iterator,
                                 GeometryInfo<dimension_>::faces_per_cell>
  face_iterators() const;
 
  TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
  neighbor_child_on_subface(const unsigned int face_no,
                            const unsigned int subface_no) const;
 
  TriaIterator<DoFCellAccessor<dimension_, space_dimension_, level_dof_access>>
  periodic_neighbor_child_on_subface(const unsigned int face_no,
                                     const unsigned int subface_no) const;
 
  template <class InputVector, typename number>
  void
  get_dof_values(const InputVector &values, Vector<number> &local_values) const;
 
  template <typename Number, typename ForwardIterator>
  void
  get_dof_values(const ReadVector<Number> &values,
                 ForwardIterator           local_values_begin,
                 ForwardIterator           local_values_end) const;
 
  template <class InputVector, typename ForwardIterator>
  void
  get_dof_values(
    const AffineConstraints<typename InputVector::value_type> &constraints,
    const InputVector                                         &values,
    ForwardIterator local_values_begin,
    ForwardIterator local_values_end) const;
 
  template <class OutputVector, typename number>
  void
  set_dof_values(const Vector<number> &local_values,
                 OutputVector         &values) const;
 
  template <typename Number>
  void
  get_interpolated_dof_values(
    const ReadVector<Number> &values,
    Vector<Number>           &interpolated_values,
    const types::fe_index     fe_index = numbers::invalid_fe_index) const;
 
  template <class OutputVector, typename number>
  void
  set_dof_values_by_interpolation(
    const Vector<number> &local_values,
    OutputVector         &values,
    const types::fe_index fe_index      = numbers::invalid_fe_index,
    const bool            perform_check = false) const;
 
  template <class OutputVector, typename number>
  void
  distribute_local_to_global_by_interpolation(
    const Vector<number> &local_values,
    OutputVector         &values,
    const types::fe_index fe_index = numbers::invalid_fe_index) const;
 
  template <typename number, typename OutputVector>
  void
  distribute_local_to_global(const Vector<number> &local_source,
                             OutputVector         &global_destination) const;
 
  template <typename ForwardIterator, typename OutputVector>
  void
  distribute_local_to_global(ForwardIterator local_source_begin,
                             ForwardIterator local_source_end,
                             OutputVector   &global_destination) const;
 
  template <typename ForwardIterator, typename OutputVector>
  void
  distribute_local_to_global(
    const AffineConstraints<typename OutputVector::value_type> &constraints,
    ForwardIterator local_source_begin,
    ForwardIterator local_source_end,
    OutputVector   &global_destination) const;
 
  template <typename number, typename OutputMatrix>
  void
  distribute_local_to_global(const FullMatrix<number> &local_source,
                             OutputMatrix &global_destination) const;
 
  template <typename number, typename OutputMatrix, typename OutputVector>
  void
  distribute_local_to_global(const FullMatrix<number> &local_matrix,
                             const Vector<number>     &local_vector,
                             OutputMatrix             &global_matrix,
                             OutputVector             &global_vector) const;
 
  void
  get_active_or_mg_dof_indices(
    std::vector<types::global_dof_index> &dof_indices) const;
 
  void
  get_dof_indices(std::vector<types::global_dof_index> &dof_indices) const;
 
  void
  get_mg_dof_indices(std::vector<types::global_dof_index> &dof_indices) const;
 
  const FiniteElement<dimension_, space_dimension_> &
  get_fe() const;
 
  types::fe_index
  active_fe_index() const;
 
  void
  set_active_fe_index(const types::fe_index i) const;
  void
  set_dof_indices(const std::vector<types::global_dof_index> &dof_indices);
 
  void
  set_mg_dof_indices(const std::vector<types::global_dof_index> &dof_indices);
 
  const FiniteElement<dimension_, space_dimension_> &
  get_future_fe() const;
 
  types::fe_index
  future_fe_index() const;
 
  void
  set_future_fe_index(const types::fe_index i) const;
 
  bool
  future_fe_index_set() const;
 
  void
  clear_future_fe_index() const;
private:
  friend struct ::internal::DoFCellAccessorImplementation::Implementation;
};
 
 
template <int structdim, int dim, int spacedim, bool level_dof_access>
inline bool
DoFAccessor<structdim, dim, spacedim, level_dof_access>::is_level_cell()
{
  return level_dof_access;
}
 
 
 
template <int structdim, int dim, int spacedim>
template <typename OtherAccessor>
DoFInvalidAccessor<structdim, dim, spacedim>::DoFInvalidAccessor(
  const OtherAccessor &)
{
  Assert(false,
         ExcMessage("You are attempting an illegal conversion between "
                    "iterator/accessor types. The constructor you call "
                    "only exists to make certain template constructs "
                    "easier to write as dimension independent code but "
                    "the conversion is not valid in the current context."));
}
 
 
 
DEAL_II_NAMESPACE_CLOSE
 
// include more templates
#include <deal.II/dofs/dof_accessor.templates.h>
 
 
#endif