dof_handler.h

// ---------------------------------------------------------------------
//
// Copyright (C) 2005 - 2019 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------

#ifndef dealii_hp_dof_handler_h
#define dealii_hp_dof_handler_h



#include <deal.II/base/config.h>

#include <deal.II/base/exceptions.h>
#include <deal.II/base/function.h>
#include <deal.II/base/iterator_range.h>
#include <deal.II/base/smartpointer.h>
#include <deal.II/base/template_constraints.h>

#include <deal.II/distributed/cell_data_transfer.templates.h>

#include <deal.II/dofs/deprecated_function_map.h>
#include <deal.II/dofs/dof_accessor.h>
#include <deal.II/dofs/dof_iterator_selector.h>
#include <deal.II/dofs/number_cache.h>

#include <deal.II/hp/dof_faces.h>
#include <deal.II/hp/dof_level.h>
#include <deal.II/hp/fe_collection.h>

#include <map>
#include <memory>
#include <set>
#include <vector>

DEAL_II_NAMESPACE_OPEN

template <int dim, int spacedim>
class Triangulation;

namespace internal
{
  namespace DoFHandlerImplementation
  {
    struct Implementation;

    namespace Policy
    {
      template <int dim, int spacedim>
      class PolicyBase;
      struct Implementation;
    } // namespace Policy
  }   // namespace DoFHandlerImplementation

  namespace hp
  {
    class DoFLevel;

    namespace DoFHandlerImplementation
    {
      struct Implementation;
    }
  } // namespace hp
} // namespace internal

namespace internal
{
  namespace DoFAccessorImplementation
  {
    struct Implementation;
  }

  namespace DoFCellAccessorImplementation
  {
    struct Implementation;
  }
} // namespace internal



namespace hp
{
  template <int dim, int spacedim = dim>
  class DoFHandler : public Subscriptor
  {
    using ActiveSelector = ::internal::DoFHandlerImplementation::
      Iterators<DoFHandler<dim, spacedim>, false>;
    using LevelSelector = ::internal::DoFHandlerImplementation::
      Iterators<DoFHandler<dim, spacedim>, true>;

  public:
    using cell_accessor = typename ActiveSelector::CellAccessor;

    using face_accessor = typename ActiveSelector::FaceAccessor;

    using line_iterator = typename ActiveSelector::line_iterator;

    using active_line_iterator = typename ActiveSelector::active_line_iterator;

    using quad_iterator = typename ActiveSelector::quad_iterator;

    using active_quad_iterator = typename ActiveSelector::active_quad_iterator;

    using hex_iterator = typename ActiveSelector::hex_iterator;

    using active_hex_iterator = typename ActiveSelector::active_hex_iterator;

#ifndef _MSC_VER
    using active_cell_iterator = typename ActiveSelector::active_cell_iterator;
#else
    using active_cell_iterator = TriaActiveIterator<
      ::DoFCellAccessor<DoFHandler<dim, spacedim>, false>>;
#endif

    using level_cell_iterator = typename LevelSelector::cell_iterator;

#ifndef _MSC_VER
    using cell_iterator = typename ActiveSelector::cell_iterator;
#else
    using cell_iterator =
      TriaIterator<::DoFCellAccessor<DoFHandler<dim, spacedim>, false>>;
#endif

    using face_iterator = typename ActiveSelector::face_iterator;

    using active_face_iterator = typename ActiveSelector::active_face_iterator;

    using level_cell_accessor = typename LevelSelector::CellAccessor;
    using level_face_accessor = typename LevelSelector::FaceAccessor;

    using level_face_iterator = typename LevelSelector::face_iterator;

    static const unsigned int dimension = dim;

    static const unsigned int space_dimension = spacedim;

    static const bool is_hp_dof_handler = true;

    DEAL_II_DEPRECATED
    static const types::global_dof_index invalid_dof_index =
      numbers::invalid_dof_index;

    static const unsigned int default_fe_index = numbers::invalid_unsigned_int;


    DoFHandler();

    DoFHandler(const Triangulation<dim, spacedim> &tria);

    DoFHandler(const DoFHandler &) = delete;

    virtual ~DoFHandler() override;

    DoFHandler &
    operator=(const DoFHandler &) = delete;

    void
    initialize(const Triangulation<dim, spacedim> &   tria,
               const hp::FECollection<dim, spacedim> &fe);

    virtual void
    set_fe(const hp::FECollection<dim, spacedim> &fe);

    virtual void
    distribute_dofs(const hp::FECollection<dim, spacedim> &fe);

    void
    set_active_fe_indices(const std::vector<unsigned int> &active_fe_indices);

    void
    get_active_fe_indices(std::vector<unsigned int> &active_fe_indices) const;

    virtual void
    clear();

    void
    renumber_dofs(const std::vector<types::global_dof_index> &new_numbers);

    unsigned int
    max_couplings_between_dofs() const;

    unsigned int
    max_couplings_between_boundary_dofs() const;

    cell_iterator
    begin(const unsigned int level = 0) const;

    active_cell_iterator
    begin_active(const unsigned int level = 0) const;

    cell_iterator
    end() const;

    cell_iterator
    end(const unsigned int level) const;

    active_cell_iterator
    end_active(const unsigned int level) const;

    IteratorRange<cell_iterator>
    cell_iterators() const;

    IteratorRange<active_cell_iterator>
    active_cell_iterators() const;

    IteratorRange<cell_iterator>
    cell_iterators_on_level(const unsigned int level) const;

    IteratorRange<active_cell_iterator>
    active_cell_iterators_on_level(const unsigned int level) const;

    /*
     * @}
     */

    /*---------------------------------------*/


    types::global_dof_index
    n_dofs() const;

    types::global_dof_index
    n_dofs(const unsigned int level) const;

    types::global_dof_index
    n_boundary_dofs() const;

    template <typename number>
    types::global_dof_index
    n_boundary_dofs(
      const std::map<types::boundary_id, const Function<spacedim, number> *>
        &boundary_ids) const;

    types::global_dof_index
    n_boundary_dofs(const std::set<types::boundary_id> &boundary_ids) const;

    types::global_dof_index
    n_locally_owned_dofs() const;

    const IndexSet &
    locally_owned_dofs() const;

    const std::vector<IndexSet> &
    locally_owned_dofs_per_processor() const;

    const std::vector<types::global_dof_index> &
    n_locally_owned_dofs_per_processor() const;

    const IndexSet &
    locally_owned_mg_dofs(const unsigned int level) const;

    const std::vector<IndexSet> &
    locally_owned_mg_dofs_per_processor(const unsigned int level) const;

    DEAL_II_DEPRECATED
    const hp::FECollection<dim, spacedim> &
    get_fe() const;

    const FiniteElement<dim, spacedim> &
    get_fe(const unsigned int index) const;

    const hp::FECollection<dim, spacedim> &
    get_fe_collection() const;

    const Triangulation<dim, spacedim> &
    get_triangulation() const;

    virtual std::size_t
    memory_consumption() const;

    void
    prepare_for_serialization_of_active_fe_indices();

    void
    deserialize_active_fe_indices();

    template <class Archive>
    void
    save(Archive &ar, const unsigned int version) const;

    template <class Archive>
    void
    load(Archive &ar, const unsigned int version);

    BOOST_SERIALIZATION_SPLIT_MEMBER()

    
    DeclException0(ExcNoFESelected);
    DeclException0(ExcGridsDoNotMatch);
    DeclException0(ExcInvalidBoundaryIndicator);
    DeclException1(ExcMatrixHasWrongSize,
                   int,
                   << "The matrix has the wrong dimension " << arg1);
    DeclException0(ExcFunctionNotUseful);
    DeclException1(ExcNewNumbersNotConsecutive,
                   types::global_dof_index,
                   << "The given list of new dof indices is not consecutive: "
                   << "the index " << arg1 << " does not exist.");
    DeclException2(ExcInvalidFEIndex,
                   int,
                   int,
                   << "The mesh contains a cell with an active_fe_index of "
                   << arg1 << ", but the finite element collection only has "
                   << arg2 << " elements");
    DeclException1(ExcInvalidLevel,
                   int,
                   << "The given level " << arg1
                   << " is not in the valid range!");
    DeclException0(ExcFacesHaveNoLevel);
    DeclException1(ExcEmptyLevel,
                   int,
                   << "You tried to do something on level " << arg1
                   << ", but this level is empty.");

  private:
    SmartPointer<const Triangulation<dim, spacedim>, DoFHandler<dim, spacedim>>
      tria;

    hp::FECollection<dim, spacedim> fe_collection;

    std::unique_ptr<::internal::DoFHandlerImplementation::Policy::
                      PolicyBase<dim, spacedim>>
      policy;


    void
    setup_policy_and_listeners();

    void
    clear_space();

    template <int structdim>
    types::global_dof_index
    get_dof_index(const unsigned int obj_level,
                  const unsigned int obj_index,
                  const unsigned int fe_index,
                  const unsigned int local_index) const;

    template <int structdim>
    void
    set_dof_index(const unsigned int            obj_level,
                  const unsigned int            obj_index,
                  const unsigned int            fe_index,
                  const unsigned int            local_index,
                  const types::global_dof_index global_index) const;

    void
    create_active_fe_table();

    void
    pre_refinement_action();

    void
    post_refinement_action();

    void
    pre_active_fe_index_transfer();

    void
    pre_distributed_active_fe_index_transfer();

    void
    post_active_fe_index_transfer();

    void
    post_distributed_active_fe_index_transfer();

    void
    post_distributed_serialization_of_active_fe_indices();

    std::vector<std::unique_ptr<::internal::hp::DoFLevel>> levels;

    std::unique_ptr<::internal::hp::DoFIndicesOnFaces<dim>> faces;

    ::internal::DoFHandlerImplementation::NumberCache number_cache;

    std::vector<::internal::DoFHandlerImplementation::NumberCache>
      mg_number_cache;

    std::vector<types::global_dof_index> vertex_dofs;

    std::vector<unsigned int> vertex_dof_offsets;

    struct ActiveFEIndexTransfer
    {
      std::map<const cell_iterator, const unsigned int>
        persisting_cells_fe_index;

      std::map<const cell_iterator, const unsigned int> refined_cells_fe_index;

      std::map<const cell_iterator, const unsigned int>
        coarsened_cells_fe_index;

      std::vector<unsigned int> active_fe_indices;

      std::unique_ptr<
        parallel::distributed::
          CellDataTransfer<dim, spacedim, std::vector<unsigned int>>>
        cell_data_transfer;
    };

    std::unique_ptr<ActiveFEIndexTransfer> active_fe_index_transfer;

    std::vector<boost::signals2::connection> tria_listeners;

    template <int, class, bool>
    friend class ::DoFAccessor;
    template <class, bool>
    friend class ::DoFCellAccessor;
    friend struct ::internal::DoFAccessorImplementation::Implementation;
    friend struct ::internal::DoFCellAccessorImplementation::
      Implementation;

    template <int>
    friend class ::internal::hp::DoFIndicesOnFacesOrEdges;
    friend struct ::internal::hp::DoFHandlerImplementation::
      Implementation;
    friend struct ::internal::DoFHandlerImplementation::Policy::
      Implementation;
  };



#ifndef DOXYGEN


  /* ----------------------- Inline functions ----------------------------------
   */


  template <int dim, int spacedim>
  template <typename number>
  types::global_dof_index
  DoFHandler<dim, spacedim>::n_boundary_dofs(
    const std::map<types::boundary_id, const Function<spacedim, number> *>
      &boundary_ids) const
  {
    // extract the set of boundary ids and forget about the function object
    // pointers
    std::set<types::boundary_id> boundary_ids_only;
    for (typename std::map<types::boundary_id,
                           const Function<spacedim, number> *>::const_iterator
           p = boundary_ids.begin();
         p != boundary_ids.end();
         ++p)
      boundary_ids_only.insert(p->first);

    // then just hand everything over to the other function that does the work
    return n_boundary_dofs(boundary_ids_only);
  }
}


namespace internal
{
  template <int dim, int spacedim>
  std::string
  policy_to_string(const ::internal::DoFHandlerImplementation::Policy::
                     PolicyBase<dim, spacedim> &policy);
} // namespace internal


namespace hp
{
  template <int dim, int spacedim>
  template <class Archive>
  void
  DoFHandler<dim, spacedim>::save(Archive &ar, unsigned int) const
  {
    ar &vertex_dofs;
    ar &vertex_dof_offsets;
    ar &number_cache;
    ar &mg_number_cache;

    // some versions of gcc have trouble with loading vectors of
    // std::unique_ptr objects because std::unique_ptr does not
    // have a copy constructor. do it one level at a time
    const unsigned int n_levels = levels.size();
    ar &               n_levels;
    for (unsigned int i = 0; i < n_levels; ++i)
      ar &levels[i];

    // boost dereferences a nullptr when serializing a nullptr
    // at least up to 1.65.1. This causes problems with clang-5.
    // Therefore, work around it.
    bool faces_is_nullptr = (faces.get() == nullptr);
    ar & faces_is_nullptr;
    if (!faces_is_nullptr)
      ar &faces;

    // write out the number of triangulation cells and later check during
    // loading that this number is indeed correct; same with something that
    // identifies the policy
    const unsigned int n_cells = tria->n_cells();
    std::string policy_name    = ::internal::policy_to_string(*policy);

    ar &n_cells &policy_name;
  }



  template <int dim, int spacedim>
  template <class Archive>
  void
  DoFHandler<dim, spacedim>::load(Archive &ar, unsigned int)
  {
    ar &vertex_dofs;
    ar &vertex_dof_offsets;
    ar &number_cache;
    ar &mg_number_cache;

    // boost::serialization can restore pointers just fine, but if the
    // pointer object still points to something useful, that object is not
    // destroyed and we end up with a memory leak. consequently, first delete
    // previous content before re-loading stuff
    levels.clear();
    faces.reset();

    // some versions of gcc have trouble with loading vectors of
    // std::unique_ptr objects because std::unique_ptr does not
    // have a copy constructor. do it one level at a time
    unsigned int size;
    ar &         size;
    levels.resize(size);
    for (unsigned int i = 0; i < size; ++i)
      {
        std::unique_ptr<::internal::hp::DoFLevel> level;
        ar &                                            level;
        levels[i] = std::move(level);
      }

    // Workaround for nullptr, see in save().
    bool faces_is_nullptr = true;
    ar & faces_is_nullptr;
    if (!faces_is_nullptr)
      ar &faces;

    // these are the checks that correspond to the last block in the save()
    // function
    unsigned int n_cells;
    std::string  policy_name;

    ar &n_cells &policy_name;

    AssertThrow(
      n_cells == tria->n_cells(),
      ExcMessage(
        "The object being loaded into does not match the triangulation "
        "that has been stored previously."));
    AssertThrow(policy_name == ::internal::policy_to_string(*policy),
                ExcMessage(
                  "The policy currently associated with this DoFHandler (" +
                  ::internal::policy_to_string(*policy) +
                  ") does not match the one that was associated with the "
                  "DoFHandler previously stored (" +
                  policy_name + ")."));
  }

  template <int dim, int spacedim>
  inline types::global_dof_index
  DoFHandler<dim, spacedim>::n_dofs() const
  {
    return number_cache.n_global_dofs;
  }



  template <int dim, int spacedim>
  inline types::global_dof_index
  DoFHandler<dim, spacedim>::n_dofs(const unsigned int) const
  {
    Assert(false, ExcNotImplemented());
    return numbers::invalid_dof_index;
  }



  template <int dim, int spacedim>
  types::global_dof_index
  DoFHandler<dim, spacedim>::n_locally_owned_dofs() const
  {
    return number_cache.n_locally_owned_dofs;
  }



  template <int dim, int spacedim>
  const IndexSet &
  DoFHandler<dim, spacedim>::locally_owned_dofs() const
  {
    return number_cache.locally_owned_dofs;
  }



  template <int dim, int spacedim>
  const std::vector<types::global_dof_index> &
  DoFHandler<dim, spacedim>::n_locally_owned_dofs_per_processor() const
  {
    return number_cache.n_locally_owned_dofs_per_processor;
  }



  template <int dim, int spacedim>
  const std::vector<IndexSet> &
  DoFHandler<dim, spacedim>::locally_owned_dofs_per_processor() const
  {
    return number_cache.locally_owned_dofs_per_processor;
  }



  template <int dim, int spacedim>
  const IndexSet &
  DoFHandler<dim, spacedim>::locally_owned_mg_dofs(
    const unsigned int level) const
  {
    Assert(false, ExcNotImplemented());
    (void)level;
    Assert(level < this->get_triangulation().n_global_levels(),
           ExcMessage("invalid level in locally_owned_mg_dofs"));
    return mg_number_cache[0].locally_owned_dofs;
  }


  template <int dim, int spacedim>
  const std::vector<IndexSet> &
  DoFHandler<dim, spacedim>::locally_owned_mg_dofs_per_processor(
    const unsigned int level) const
  {
    Assert(false, ExcNotImplemented());
    (void)level;
    Assert(level < this->get_triangulation().n_global_levels(),
           ExcMessage("invalid level in locally_owned_mg_dofs_per_processor"));
    return mg_number_cache[0].locally_owned_dofs_per_processor;
  }



  template <int dim, int spacedim>
  inline const hp::FECollection<dim, spacedim> &
  DoFHandler<dim, spacedim>::get_fe() const
  {
    Assert(fe_collection.size() > 0,
           ExcMessage("No finite element collection is associated with "
                      "this DoFHandler"));
    return fe_collection;
  }



  template <int dim, int spacedim>
  inline const FiniteElement<dim, spacedim> &
  DoFHandler<dim, spacedim>::get_fe(const unsigned int number) const
  {
    Assert(fe_collection.size() > 0,
           ExcMessage("No finite element collection is associated with "
                      "this DoFHandler"));
    return fe_collection[number];
  }



  template <int dim, int spacedim>
  inline const hp::FECollection<dim, spacedim> &
  DoFHandler<dim, spacedim>::get_fe_collection() const
  {
    Assert(fe_collection.size() > 0,
           ExcMessage("No finite element collection is associated with "
                      "this DoFHandler"));
    return fe_collection;
  }



  template <int dim, int spacedim>
  inline const Triangulation<dim, spacedim> &
  DoFHandler<dim, spacedim>::get_triangulation() const
  {
    Assert(tria != nullptr,
           ExcMessage("This DoFHandler object has not been associated "
                      "with a triangulation."));
    return *tria;
  }

#endif

} // namespace hp

DEAL_II_NAMESPACE_CLOSE

#endif