dof_tools.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_dof_tools_h
#define dealii_dof_tools_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
#include <deal.II/base/index_set.h>
#include <deal.II/base/point.h>
#include <deal.II/base/types.h>
 
#include <deal.II/dofs/dof_handler.h>
 
#include <deal.II/fe/component_mask.h>
 
#include <deal.II/lac/affine_constraints.h>
#include <deal.II/lac/sparsity_pattern_base.h>
 
#include <map>
#include <ostream>
#include <set>
#include <vector>
 
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declarations
#ifndef DOXYGEN
class BlockMask;
template <int dim, typename RangeNumberType>
class Function;
template <int dim, int spacedim>
class FiniteElement;
namespace hp
{
  template <int dim, int spacedim>
  class MappingCollection;
  template <int dim, int spacedim>
  class FECollection;
} // namespace hp
template <typename MeshType>
DEAL_II_CXX20_REQUIRES(concepts::is_triangulation_or_dof_handler<MeshType>)
class InterGridMap;
template <int dim, int spacedim>
class Mapping;
template <int dim, class T>
class Table;
template <typename Number>
class Vector;
 
namespace GridTools
{
  template <typename CellIterator>
  struct PeriodicFacePair;
}
 
namespace DoFTools
{
  namespace internal
  {
    /*
     * Default value of the face_has_flux_coupling parameter of
     * make_flux_sparsity_pattern. Defined here (instead of using a default
     * lambda in the parameter list) to avoid a bug in gcc where the same lambda
     * gets defined multiple times.
     */
    template <int dim, int spacedim>
    inline bool
    always_couple_on_faces(
      const typename DoFHandler<dim, spacedim>::active_cell_iterator &,
      const unsigned int)
    {
      return true;
    }
  } // namespace internal
} // namespace DoFTools
 
#endif
 
namespace DoFTools
{
  enum Coupling
  {
    none,
    always,
    nonzero
  };
 
  template <int dim, int spacedim>
  void
  convert_couplings_to_blocks(const DoFHandler<dim, spacedim> &dof_handler,
                              const Table<2, Coupling> &table_by_component,
                              std::vector<Table<2, Coupling>> &tables_by_block);
 
  template <int dim, int spacedim>
  Table<2, Coupling>
  dof_couplings_from_component_couplings(
    const FiniteElement<dim, spacedim> &fe,
    const Table<2, Coupling>           &component_couplings);
 
  template <int dim, int spacedim>
  std::vector<Table<2, Coupling>>
  dof_couplings_from_component_couplings(
    const hp::FECollection<dim, spacedim> &fe,
    const Table<2, Coupling>              &component_couplings);
  template <int dim, int spacedim, typename number = double>
  void
  make_sparsity_pattern(
    const DoFHandler<dim, spacedim> &dof_handler,
    SparsityPatternBase             &sparsity_pattern,
    const AffineConstraints<number> &constraints           = {},
    const bool                       keep_constrained_dofs = true,
    const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
  template <int dim, int spacedim, typename number = double>
  void
  make_sparsity_pattern(
    const DoFHandler<dim, spacedim> &dof_handler,
    const Table<2, Coupling>        &coupling,
    SparsityPatternBase             &sparsity_pattern,
    const AffineConstraints<number> &constraints           = {},
    const bool                       keep_constrained_dofs = true,
    const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
  template <int dim, int spacedim>
  void
  make_sparsity_pattern(const DoFHandler<dim, spacedim> &dof_row,
                        const DoFHandler<dim, spacedim> &dof_col,
                        SparsityPatternBase             &sparsity);
 
  template <int dim, int spacedim>
  void
  make_flux_sparsity_pattern(const DoFHandler<dim, spacedim> &dof_handler,
                             SparsityPatternBase             &sparsity_pattern);
 
  template <int dim, int spacedim, typename number>
  void
  make_flux_sparsity_pattern(
    const DoFHandler<dim, spacedim> &dof_handler,
    SparsityPatternBase             &sparsity_pattern,
    const AffineConstraints<number> &constraints,
    const bool                       keep_constrained_dofs = true,
    const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
 
  template <int dim, int spacedim>
  void
  make_flux_sparsity_pattern(
    const DoFHandler<dim, spacedim> &dof,
    SparsityPatternBase             &sparsity,
    const Table<2, Coupling>        &cell_integrals_mask,
    const Table<2, Coupling>        &face_integrals_mask,
    const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
 
  template <int dim, int spacedim, typename number>
  void
  make_flux_sparsity_pattern(
    const DoFHandler<dim, spacedim> &dof,
    SparsityPatternBase             &sparsity,
    const AffineConstraints<number> &constraints,
    const bool                       keep_constrained_dofs,
    const Table<2, Coupling>        &couplings,
    const Table<2, Coupling>        &face_couplings,
    const types::subdomain_id        subdomain_id,
    const std::function<
      bool(const typename DoFHandler<dim, spacedim>::active_cell_iterator &,
           const unsigned int)> &face_has_flux_coupling =
      &internal::always_couple_on_faces<dim, spacedim>);
 
  template <int dim, int spacedim>
  void
  make_boundary_sparsity_pattern(
    const DoFHandler<dim, spacedim>            &dof,
    const std::vector<types::global_dof_index> &dof_to_boundary_mapping,
    SparsityPatternBase                        &sparsity_pattern);
 
  template <int dim, int spacedim, typename number>
  void
  make_boundary_sparsity_pattern(
    const DoFHandler<dim, spacedim> &dof,
    const std::map<types::boundary_id, const Function<spacedim, number> *>
                                               &boundary_ids,
    const std::vector<types::global_dof_index> &dof_to_boundary_mapping,
    SparsityPatternBase                        &sparsity);
 
  template <int dim, int spacedim, typename number>
  void
  make_hanging_node_constraints(const DoFHandler<dim, spacedim> &dof_handler,
                                AffineConstraints<number>       &constraints);
 
  template <int dim, int spacedim>
  void
  compute_intergrid_constraints(
    const DoFHandler<dim, spacedim>               &coarse_grid,
    const unsigned int                             coarse_component,
    const DoFHandler<dim, spacedim>               &fine_grid,
    const unsigned int                             fine_component,
    const InterGridMap<DoFHandler<dim, spacedim>> &coarse_to_fine_grid_map,
    AffineConstraints<double>                     &constraints);
 
 
  template <int dim, int spacedim>
  void
  compute_intergrid_transfer_representation(
    const DoFHandler<dim, spacedim>               &coarse_grid,
    const unsigned int                             coarse_component,
    const DoFHandler<dim, spacedim>               &fine_grid,
    const unsigned int                             fine_component,
    const InterGridMap<DoFHandler<dim, spacedim>> &coarse_to_fine_grid_map,
    std::vector<std::map<types::global_dof_index, float>>
      &transfer_representation);
 
  template <typename FaceIterator, typename number>
  void
  make_periodicity_constraints(
    const FaceIterator                             &face_1,
    const std_cxx20::type_identity_t<FaceIterator> &face_2,
    AffineConstraints<number>                      &constraints,
    const ComponentMask                            &component_mask = {},
    const types::geometric_orientation              combined_orientation =
      numbers::default_geometric_orientation,
    const FullMatrix<double>        &matrix = FullMatrix<double>(),
    const std::vector<unsigned int> &first_vector_components =
      std::vector<unsigned int>(),
    const number periodicity_factor = 1.);
 
 
  template <typename FaceIterator, typename number>
  void
  make_periodicity_constraints_on_level(
    const FaceIterator                             &face_1,
    const std_cxx20::type_identity_t<FaceIterator> &face_2,
    const unsigned int                              level,
    AffineConstraints<number>                      &constraints,
    const ComponentMask                            &component_mask = {},
    const types::geometric_orientation              combined_orientation =
      numbers::default_geometric_orientation,
    const FullMatrix<double>        &matrix = FullMatrix<double>(),
    const std::vector<unsigned int> &first_vector_components =
      std::vector<unsigned int>(),
    const number periodicity_factor = 1.);
 
 
  template <int dim, int spacedim, typename number>
  void
  make_periodicity_constraints(
    const std::vector<GridTools::PeriodicFacePair<
      typename DoFHandler<dim, spacedim>::cell_iterator>> &periodic_faces,
    AffineConstraints<number>                             &constraints,
    const ComponentMask                                   &component_mask = {},
    const std::vector<unsigned int> &first_vector_components =
      std::vector<unsigned int>(),
    const number periodicity_factor = 1.);
 
 
 
  template <int dim, int spacedim, typename number>
  void
  make_periodicity_constraints(const DoFHandler<dim, spacedim> &dof_handler,
                               const types::boundary_id         b_id1,
                               const types::boundary_id         b_id2,
                               const unsigned int               direction,
                               AffineConstraints<number>       &constraints,
                               const ComponentMask &component_mask     = {},
                               const number         periodicity_factor = 1.);
 
 
 
  template <int dim, int spacedim, typename number>
  void
  make_periodicity_constraints(const DoFHandler<dim, spacedim> &dof_handler,
                               const types::boundary_id         b_id,
                               const unsigned int               direction,
                               AffineConstraints<number>       &constraints,
                               const ComponentMask &component_mask     = {},
                               const number         periodicity_factor = 1.);
 
  namespace internal
  {
    template <typename FaceIterator, typename number>
    void
    set_periodicity_constraints(
      const FaceIterator                             &face_1,
      const std_cxx20::type_identity_t<FaceIterator> &face_2,
      const FullMatrix<double>                       &transformation,
      AffineConstraints<number>                      &affine_constraints,
      const ComponentMask                            &component_mask,
      const types::geometric_orientation              combined_orientation,
      const number                                    periodicity_factor,
      const unsigned int level = numbers::invalid_unsigned_int);
  } // namespace internal
 
  template <int dim, int spacedim>
  IndexSet
  extract_hanging_node_dofs(const DoFHandler<dim, spacedim> &dof_handler);
 
  template <int dim, int spacedim>
  IndexSet
  extract_dofs(const DoFHandler<dim, spacedim> &dof_handler,
               const ComponentMask             &component_mask);
 
  template <int dim, int spacedim>
  IndexSet
  extract_dofs(const DoFHandler<dim, spacedim> &dof_handler,
               const BlockMask                 &block_mask);
 
  template <int dim, int spacedim>
  void
  extract_level_dofs(const unsigned int               level,
                     const DoFHandler<dim, spacedim> &dof,
                     const ComponentMask             &component_mask,
                     std::vector<bool>               &selected_dofs);
 
  template <int dim, int spacedim>
  void
  extract_level_dofs(const unsigned int               level,
                     const DoFHandler<dim, spacedim> &dof,
                     const BlockMask                 &component_mask,
                     std::vector<bool>               &selected_dofs);
 
  template <int dim, int spacedim>
  IndexSet
  extract_boundary_dofs(const DoFHandler<dim, spacedim>    &dof_handler,
                        const ComponentMask                &component_mask = {},
                        const std::set<types::boundary_id> &boundary_ids = {});
 
  template <int dim, int spacedim>
  void
  extract_dofs_with_support_on_boundary(
    const DoFHandler<dim, spacedim>    &dof_handler,
    const ComponentMask                &component_mask,
    std::vector<bool>                  &selected_dofs,
    const std::set<types::boundary_id> &boundary_ids =
      std::set<types::boundary_id>());
 
  template <int dim, int spacedim, typename number = double>
  IndexSet
  extract_dofs_with_support_contained_within(
    const DoFHandler<dim, spacedim> &dof_handler,
    const std::function<
      bool(const typename DoFHandler<dim, spacedim>::active_cell_iterator &)>
                                    &predicate,
    const AffineConstraints<number> &constraints = {});
 
  template <int dim, int spacedim>
  std::vector<std::vector<bool>>
  extract_constant_modes(const DoFHandler<dim, spacedim> &dof_handler,
                         const ComponentMask             &component_mask = {});
 
  template <int dim, int spacedim>
  std::vector<std::vector<bool>>
  extract_level_constant_modes(const unsigned int               level,
                               const DoFHandler<dim, spacedim> &dof_handler,
                               const ComponentMask &component_mask = {});
 
  template <int dim, int spacedim>
  std::vector<std::vector<double>>
  extract_rigid_body_modes(const Mapping<dim, spacedim>    &mapping,
                           const DoFHandler<dim, spacedim> &dof_handler,
                           const ComponentMask &component_mask = {});
 
  template <int dim, int spacedim>
  std::vector<std::vector<double>>
  extract_level_rigid_body_modes(const unsigned int               level,
                                 const Mapping<dim, spacedim>    &mapping,
                                 const DoFHandler<dim, spacedim> &dof_handler,
                                 const ComponentMask &component_mask = {});
  template <int dim, int spacedim>
  std::map<typename DoFHandler<dim - 1, spacedim>::active_cell_iterator,
           std::pair<typename DoFHandler<dim, spacedim>::active_cell_iterator,
                     unsigned int>>
  map_boundary_to_bulk_dof_iterators(
    const std::map<typename Triangulation<dim - 1, spacedim>::cell_iterator,
                   typename Triangulation<dim, spacedim>::face_iterator>
                                        &c1_to_c0,
    const DoFHandler<dim, spacedim>     &c0_dh,
    const DoFHandler<dim - 1, spacedim> &c1_dh);
 
  template <int dim, int spacedim>
  void
  extract_subdomain_dofs(const DoFHandler<dim, spacedim> &dof_handler,
                         const types::subdomain_id        subdomain_id,
                         std::vector<bool>               &selected_dofs);
 
  template <int dim, int spacedim>
  IndexSet
  extract_locally_active_dofs(const DoFHandler<dim, spacedim> &dof_handler);
 
  template <int dim, int spacedim>
  DEAL_II_DEPRECATED void
  extract_locally_active_dofs(const DoFHandler<dim, spacedim> &dof_handler,
                              IndexSet                        &dof_set);
 
  template <int dim, int spacedim>
  IndexSet
  extract_locally_active_level_dofs(
    const DoFHandler<dim, spacedim> &dof_handler,
    const unsigned int               level);
 
  template <int dim, int spacedim>
  DEAL_II_DEPRECATED void
  extract_locally_active_level_dofs(
    const DoFHandler<dim, spacedim> &dof_handler,
    IndexSet                        &dof_set,
    const unsigned int               level);
 
  template <int dim, int spacedim>
  IndexSet
  extract_locally_relevant_dofs(const DoFHandler<dim, spacedim> &dof_handler);
 
  template <int dim, int spacedim>
  DEAL_II_DEPRECATED void
  extract_locally_relevant_dofs(const DoFHandler<dim, spacedim> &dof_handler,
                                IndexSet                        &dof_set);
 
  template <int dim, int spacedim>
  std::vector<IndexSet>
  locally_owned_dofs_per_component(const DoFHandler<dim, spacedim> &dof_handler,
                                   const ComponentMask &components = {});
 
  template <int dim, int spacedim>
  std::vector<IndexSet>
  locally_owned_dofs_per_subdomain(
    const DoFHandler<dim, spacedim> &dof_handler);
 
  template <int dim, int spacedim>
  std::vector<IndexSet>
  locally_relevant_dofs_per_subdomain(
    const DoFHandler<dim, spacedim> &dof_handler);
 
  template <int dim, int spacedim>
  IndexSet
  extract_locally_relevant_level_dofs(
    const DoFHandler<dim, spacedim> &dof_handler,
    const unsigned int               level);
 
  template <int dim, int spacedim>
  DEAL_II_DEPRECATED void
  extract_locally_relevant_level_dofs(
    const DoFHandler<dim, spacedim> &dof_handler,
    const unsigned int               level,
    IndexSet                        &dof_set);
 
 
  template <int dim, int spacedim>
  void
  get_subdomain_association(const DoFHandler<dim, spacedim>  &dof_handler,
                            std::vector<types::subdomain_id> &subdomain);
 
  template <int dim, int spacedim>
  unsigned int
  count_dofs_with_subdomain_association(
    const DoFHandler<dim, spacedim> &dof_handler,
    const types::subdomain_id        subdomain);
 
  template <int dim, int spacedim>
  void
  count_dofs_with_subdomain_association(
    const DoFHandler<dim, spacedim> &dof_handler,
    const types::subdomain_id        subdomain,
    std::vector<unsigned int>       &n_dofs_on_subdomain);
 
  template <int dim, int spacedim>
  IndexSet
  dof_indices_with_subdomain_association(
    const DoFHandler<dim, spacedim> &dof_handler,
    const types::subdomain_id        subdomain);
  template <int dim, int spacedim>
  std::vector<types::global_dof_index>
  get_dofs_on_patch(
    const std::vector<typename DoFHandler<dim, spacedim>::active_cell_iterator>
      &patch);
 
  template <int dim, int spacedim>
  void
  make_cell_patches(SparsityPattern                 &block_list,
                    const DoFHandler<dim, spacedim> &dof_handler,
                    const unsigned int               level,
                    const std::vector<bool>         &selected_dofs = {},
                    const types::global_dof_index    offset        = 0);
 
  template <int dim, int spacedim>
  std::vector<unsigned int>
  make_vertex_patches(SparsityPattern                 &block_list,
                      const DoFHandler<dim, spacedim> &dof_handler,
                      const unsigned int               level,
                      const bool                       interior_dofs_only,
                      const bool                       boundary_patches = false,
                      const bool level_boundary_patches                 = false,
                      const bool single_cell_patches                    = false,
                      const bool invert_vertex_mapping = false);
 
  template <int dim, int spacedim>
  std::vector<unsigned int>
  make_vertex_patches(SparsityPattern                 &block_list,
                      const DoFHandler<dim, spacedim> &dof_handler,
                      const unsigned int               level,
                      const BlockMask &exclude_boundary_dofs  = BlockMask(),
                      const bool       boundary_patches       = false,
                      const bool       level_boundary_patches = false,
                      const bool       single_cell_patches    = false,
                      const bool       invert_vertex_mapping  = false);
 
  template <int dim, int spacedim>
  void
  make_child_patches(SparsityPattern                 &block_list,
                     const DoFHandler<dim, spacedim> &dof_handler,
                     const unsigned int               level,
                     const bool                       interior_dofs_only,
                     const bool                       boundary_dofs = false);
 
  template <int dim, int spacedim>
  void
  make_single_patch(SparsityPattern                 &block_list,
                    const DoFHandler<dim, spacedim> &dof_handler,
                    const unsigned int               level,
                    const bool interior_dofs_only = false);
 
  template <int dim, int spacedim>
  std::vector<types::global_dof_index>
  count_dofs_per_fe_component(
    const DoFHandler<dim, spacedim> &dof_handler,
    const bool                       vector_valued_once = false,
    const std::vector<unsigned int> &target_component   = {});
 
  template <int dim, int spacedim>
  std::vector<types::global_dof_index>
  count_dofs_per_fe_block(const DoFHandler<dim, spacedim> &dof,
                          const std::vector<unsigned int> &target_block =
                            std::vector<unsigned int>());
 
  template <int dim, int spacedim>
  unsigned int
  count_dofs_on_patch(
    const std::vector<typename DoFHandler<dim, spacedim>::active_cell_iterator>
      &patch);
 
  template <int dim, int spacedim>
  void
  map_dof_to_boundary_indices(const DoFHandler<dim, spacedim>      &dof_handler,
                              std::vector<types::global_dof_index> &mapping);
 
  template <int dim, int spacedim>
  void
  map_dof_to_boundary_indices(const DoFHandler<dim, spacedim>    &dof_handler,
                              const std::set<types::boundary_id> &boundary_ids,
                              std::vector<types::global_dof_index> &mapping);
 
  template <int dim, int spacedim>
  void
  map_dofs_to_support_points(const Mapping<dim, spacedim>    &mapping,
                             const DoFHandler<dim, spacedim> &dof_handler,
                             std::vector<Point<spacedim>>    &support_points,
                             const ComponentMask             &mask = {},
                             const bool map_locally_relevant_dofs  = true);
 
  template <int dim, int spacedim>
  void
  map_dofs_to_support_points(
    const hp::MappingCollection<dim, spacedim> &mapping,
    const DoFHandler<dim, spacedim>            &dof_handler,
    std::vector<Point<spacedim>>               &support_points,
    const ComponentMask                        &mask = {},
    const bool map_locally_relevant_dofs             = true);
 
  template <int dim, int spacedim>
  std::map<types::global_dof_index, Point<spacedim>>
  map_dofs_to_support_points(const Mapping<dim, spacedim>    &mapping,
                             const DoFHandler<dim, spacedim> &dof_handler,
                             const ComponentMask             &mask = {},
                             const bool map_locally_relevant_dofs  = true);
 
  template <int dim, int spacedim>
  std::map<types::global_dof_index, Point<spacedim>>
  map_dofs_to_support_points(
    const hp::MappingCollection<dim, spacedim> &mapping,
    const DoFHandler<dim, spacedim>            &dof_handler,
    const ComponentMask                        &mask = {},
    const bool map_locally_relevant_dofs             = true);
 
  template <int dim, int spacedim, class Comp>
  void
  map_support_points_to_dofs(
    const Mapping<dim, spacedim>    &mapping,
    const DoFHandler<dim, spacedim> &dof_handler,
    std::map<Point<spacedim>, types::global_dof_index, Comp>
      &point_to_index_map);
  template <int dim, int spacedim, typename Number>
  void
  distribute_cell_to_dof_vector(const DoFHandler<dim, spacedim> &dof_handler,
                                const Vector<Number>            &cell_data,
                                Vector<double>                  &dof_data,
                                const unsigned int               component = 0);
 
 
  template <int spacedim>
  void
  write_gnuplot_dof_support_point_info(
    std::ostream                                             &out,
    const std::map<types::global_dof_index, Point<spacedim>> &support_points);
 
 
  template <int dim, int spacedim, typename number>
  void
  make_zero_boundary_constraints(
    const DoFHandler<dim, spacedim> &dof,
    const types::boundary_id         boundary_id,
    AffineConstraints<number>       &zero_boundary_constraints,
    const ComponentMask             &component_mask = {});
 
  template <int dim, int spacedim, typename number>
  void
  make_zero_boundary_constraints(
    const DoFHandler<dim, spacedim> &dof,
    AffineConstraints<number>       &zero_boundary_constraints,
    const ComponentMask             &component_mask = {});
 
  DeclException0(ExcFiniteElementsDontMatch);
  DeclException0(ExcGridNotCoarser);
  DeclException0(ExcGridsDontMatch);
  DeclException0(ExcNoFESelected);
  DeclException0(ExcInvalidBoundaryIndicator);
} // namespace DoFTools
 
 
 
/* ------------------------- inline functions -------------- */
 
#ifndef DOXYGEN
 
namespace DoFTools
{
  inline Coupling
  operator|=(Coupling &c1, const Coupling c2)
  {
    if (c2 == always)
      c1 = always;
    else if (c1 != always && c2 == nonzero)
      return c1 = nonzero;
    return c1;
  }
 
 
  inline Coupling
  operator|(const Coupling c1, const Coupling c2)
  {
    if (c1 == always || c2 == always)
      return always;
    if (c1 == nonzero || c2 == nonzero)
      return nonzero;
    return none;
  }
 
 
  // ---------------------- inline and template functions --------------------
 
  template <int dim, int spacedim, class Comp>
  void
  map_support_points_to_dofs(
    const Mapping<dim, spacedim>    &mapping,
    const DoFHandler<dim, spacedim> &dof_handler,
    std::map<Point<spacedim>, types::global_dof_index, Comp>
      &point_to_index_map)
  {
    // let the checking of arguments be
    // done by the function first
    // called
    std::vector<Point<spacedim>> support_points(dof_handler.n_dofs());
    map_dofs_to_support_points(mapping, dof_handler, support_points);
    // now copy over the results of the
    // previous function into the
    // output arg
    point_to_index_map.clear();
    for (types::global_dof_index i = 0; i < dof_handler.n_dofs(); ++i)
      point_to_index_map[support_points[i]] = i;
  }
} // namespace DoFTools
 
#endif
 
DEAL_II_NAMESPACE_CLOSE
 
#endif