dof_level.h

// ---------------------------------------------------------------------
//
// Copyright (C) 2003 - 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_level_h
#define dealii_hp_dof_level_h


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

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

#include <vector>


DEAL_II_NAMESPACE_OPEN

namespace hp
{
  template <int, int>
  class DoFHandler;
  template <int, int>
  class FECollection;
} // namespace hp


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


namespace internal
{
  namespace hp
  {
    class DoFLevel
    {
    private:
      using offset_type = unsigned int;

      using active_fe_index_type = unsigned short int;

      using signed_active_fe_index_type = signed short int;

      static const active_fe_index_type invalid_active_fe_index;

      static bool
      is_compressed_entry(const active_fe_index_type active_fe_index);

      static active_fe_index_type
      get_toggled_compression_state(const active_fe_index_type active_fe_index);

      std::vector<active_fe_index_type> active_fe_indices;

      std::vector<active_fe_index_type> future_fe_indices;

      std::vector<offset_type> dof_offsets;

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

      std::vector<offset_type> cell_cache_offsets;

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

    public:
      void
      set_dof_index(const unsigned int            obj_index,
                    const unsigned int            fe_index,
                    const unsigned int            local_index,
                    const types::global_dof_index global_index);

      types::global_dof_index
      get_dof_index(const unsigned int obj_index,
                    const unsigned int fe_index,
                    const unsigned int local_index) const;

      unsigned int
      active_fe_index(const unsigned int obj_index) const;

      bool
      fe_index_is_active(const unsigned int obj_index,
                         const unsigned int fe_index) const;

      void
      set_active_fe_index(const unsigned int obj_index,
                          const unsigned int fe_index);

      unsigned int
      future_fe_index(const unsigned int obj_index) const;

      void
      set_future_fe_index(const unsigned int obj_index,
                          const unsigned int fe_index);

      bool
      future_fe_index_set(const unsigned int obj_index) const;

      void
      clear_future_fe_index(const unsigned int obj_index);

      const types::global_dof_index *
      get_cell_cache_start(const unsigned int obj_index,
                           const unsigned int dofs_per_cell) const;

      std::size_t
      memory_consumption() const;

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

    private:
      template <int dim, int spacedim>
      void
      compress_data(
        const ::hp::FECollection<dim, spacedim> &fe_collection);

      template <int dim, int spacedim>
      void
      uncompress_data(
        const ::hp::FECollection<dim, spacedim> &fe_collection);


      void
      normalize_active_fe_indices();


      template <int, int>
      friend class ::hp::DoFHandler;
      friend struct ::internal::hp::DoFHandlerImplementation::
        Implementation;
      friend struct ::internal::DoFCellAccessorImplementation::
        Implementation;
    };


    // -------------------- template functions --------------------------------


    inline bool
    DoFLevel::is_compressed_entry(const active_fe_index_type active_fe_index)
    {
      return (static_cast<signed_active_fe_index_type>(active_fe_index) < 0);
    }



    inline DoFLevel::active_fe_index_type
    DoFLevel::get_toggled_compression_state(
      const active_fe_index_type active_fe_index)
    {
      // convert the active_fe_index into a signed type, flip all
      // bits, and get the unsigned representation back
      return static_cast<active_fe_index_type>(
        ~(static_cast<signed_active_fe_index_type>(active_fe_index)));
    }



    inline types::global_dof_index
    DoFLevel::get_dof_index(const unsigned int obj_index,
                            const unsigned int fe_index,
                            const unsigned int local_index) const
    {
      (void)fe_index;
      Assert(obj_index < dof_offsets.size(),
             ExcIndexRange(obj_index, 0, dof_offsets.size()));

      // make sure we are on an object for which DoFs have been
      // allocated at all
      Assert(dof_offsets[obj_index] != static_cast<offset_type>(-1),
             ExcMessage("You are trying to access degree of freedom "
                        "information for an object on which no such "
                        "information is available"));

      Assert(fe_index ==
               (is_compressed_entry(active_fe_indices[obj_index]) == false ?
                  active_fe_indices[obj_index] :
                  get_toggled_compression_state(active_fe_indices[obj_index])),
             ExcMessage("FE index does not match that of the present cell"));

      // see if the dof_indices array has been compressed for this
      // particular cell
      if (is_compressed_entry(active_fe_indices[obj_index]) == false)
        return dof_indices[dof_offsets[obj_index] + local_index];
      else
        return dof_indices[dof_offsets[obj_index]] + local_index;
    }



    inline void
    DoFLevel::set_dof_index(const unsigned int            obj_index,
                            const unsigned int            fe_index,
                            const unsigned int            local_index,
                            const types::global_dof_index global_index)
    {
      (void)fe_index;
      Assert(obj_index < dof_offsets.size(),
             ExcIndexRange(obj_index, 0, dof_offsets.size()));

      // make sure we are on an
      // object for which DoFs have
      // been allocated at all
      Assert(dof_offsets[obj_index] != static_cast<offset_type>(-1),
             ExcMessage("You are trying to access degree of freedom "
                        "information for an object on which no such "
                        "information is available"));
      Assert(
        is_compressed_entry(active_fe_indices[obj_index]) == false,
        ExcMessage(
          "This function can no longer be called after compressing the dof_indices array"));
      Assert(fe_index == active_fe_indices[obj_index],
             ExcMessage("FE index does not match that of the present cell"));
      dof_indices[dof_offsets[obj_index] + local_index] = global_index;
    }



    inline unsigned int
    DoFLevel::active_fe_index(const unsigned int obj_index) const
    {
      Assert(obj_index < active_fe_indices.size(),
             ExcIndexRange(obj_index, 0, active_fe_indices.size()));

      if (is_compressed_entry(active_fe_indices[obj_index]) == false)
        return active_fe_indices[obj_index];
      else
        return get_toggled_compression_state(active_fe_indices[obj_index]);
    }



    inline bool
    DoFLevel::fe_index_is_active(const unsigned int obj_index,
                                 const unsigned int fe_index) const
    {
      return (fe_index == active_fe_index(obj_index));
    }



    inline void
    DoFLevel::set_active_fe_index(const unsigned int obj_index,
                                  const unsigned int fe_index)
    {
      Assert(obj_index < active_fe_indices.size(),
             ExcIndexRange(obj_index, 0, active_fe_indices.size()));

      // check whether the given fe_index is within the range of
      // values that we interpret as "not compressed". if not, then
      // the index is so large that we cannot accept it. (but this
      // will not likely happen because it requires someone using an
      // FECollection that has more than 32k entries.)
      Assert(is_compressed_entry(fe_index) == false,
             ExcMessage(
               "You are using an active_fe_index that is larger than an "
               "internal limitation for these objects. Try to work with "
               "hp::FECollection objects that have a more modest size."));
      Assert(fe_index != invalid_active_fe_index,
             ExcMessage(
               "You are using an active_fe_index that is reserved for "
               "internal purposes for these objects. Try to work with "
               "hp::FECollection objects that have a more modest size."));

      active_fe_indices[obj_index] = fe_index;
    }



    inline unsigned int
    DoFLevel::future_fe_index(const unsigned int obj_index) const
    {
      Assert(obj_index < future_fe_indices.size(),
             ExcIndexRange(obj_index, 0, future_fe_indices.size()));

      if (future_fe_index_set(obj_index))
        return future_fe_indices[obj_index];

      return active_fe_index(obj_index);
    }



    inline void
    DoFLevel::set_future_fe_index(const unsigned int obj_index,
                                  const unsigned int fe_index)
    {
      Assert(obj_index < future_fe_indices.size(),
             ExcIndexRange(obj_index, 0, future_fe_indices.size()));

      // check whether the given fe_index is within the range of
      // values that we interpret as "not compressed". if not, then
      // the index is so large that we cannot accept it. (but this
      // will not likely happen because it requires someone using an
      // FECollection that has more than 32k entries.)
      Assert(is_compressed_entry(fe_index) == false,
             ExcMessage(
               "You are using a future_fe_index that is larger than an "
               "internal limitation for these objects. Try to work with "
               "hp::FECollection objects that have a more modest size."));
      Assert(fe_index != invalid_active_fe_index,
             ExcMessage(
               "You are using a future_fe_index that is reserved for "
               "internal purposes for these objects. Try to work with "
               "hp::FECollection objects that have a more modest size."));

      future_fe_indices[obj_index] = fe_index;
    }



    inline bool
    DoFLevel::future_fe_index_set(const unsigned int obj_index) const
    {
      Assert(obj_index < future_fe_indices.size(),
             ExcIndexRange(obj_index, 0, future_fe_indices.size()));

      return (future_fe_indices[obj_index] != invalid_active_fe_index);
    }



    inline void
    DoFLevel::clear_future_fe_index(const unsigned int obj_index)
    {
      Assert(obj_index < future_fe_indices.size(),
             ExcIndexRange(obj_index, 0, future_fe_indices.size()));

      future_fe_indices[obj_index] = invalid_active_fe_index;
    }



    inline const types::global_dof_index *
    DoFLevel::get_cell_cache_start(const unsigned int obj_index,
                                   const unsigned int dofs_per_cell) const
    {
      (void)dofs_per_cell;
      Assert(
        (obj_index < cell_cache_offsets.size()) &&
          (cell_cache_offsets[obj_index] + dofs_per_cell <=
           cell_dof_indices_cache.size()),
        ExcMessage(
          "You are trying to access an element of the cache that stores "
          "the indices of all degrees of freedom that live on one cell. "
          "However, this element does not exist. Did you forget to call "
          "DoFHandler::distribute_dofs(), or did you forget to call it "
          "again after changing the active_fe_index of one of the cells?"));

      return &cell_dof_indices_cache[cell_cache_offsets[obj_index]];
    }



    template <class Archive>
    inline void
    DoFLevel::serialize(Archive &ar, const unsigned int)
    {
      ar & this->active_fe_indices;
      ar & this->cell_cache_offsets;
      ar & this->cell_dof_indices_cache;
      ar & this->dof_indices;
      ar & this->dof_offsets;
      ar & this->future_fe_indices;
    }
  } // namespace hp

} // namespace internal

DEAL_II_NAMESPACE_CLOSE

#endif