dof_object.h

Go to the documentation of this file.

// The libMesh Finite Element Library.
// Copyright (C) 2002-2025 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner

// This library is free software; you can 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.

// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.

// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA



#ifndef LIBMESH_DOF_OBJECT_H
#define LIBMESH_DOF_OBJECT_H

// Local includes
#include "libmesh/id_types.h"
#include "libmesh/int_range.h"
#include "libmesh/libmesh_config.h"
#include "libmesh/libmesh_common.h"
#include "libmesh/libmesh.h" // libMesh::invalid_uint
#include "libmesh/reference_counted_object.h"

// C++ includes
#include <cstddef>
#include <cstring>
#include <vector>
#include <memory>

namespace libMesh
{

// Forward declarations
class DofObject;


class DofObject : public ReferenceCountedObject<DofObject>
{
#ifdef LIBMESH_IS_UNIT_TESTING
public:
#else
protected:
#endif

  DofObject ();

public:

  ~DofObject () = default;

#ifdef LIBMESH_ENABLE_AMR

#ifndef LIBMESH_ENABLE_DEPRECATED
protected:
#endif
  std::unique_ptr<DofObject> old_dof_object;

public:
  DofObject * get_old_dof_object() { return old_dof_object.get(); }
  const DofObject * get_old_dof_object() const  { return old_dof_object.get(); }

  DofObject & get_old_dof_object_ref()
  {
    libmesh_assert(old_dof_object);
    return *old_dof_object;
  }

  const DofObject & get_old_dof_object_ref() const
  {
    libmesh_assert(old_dof_object);
    return *old_dof_object;
  }

  void clear_old_dof_object ();

  void set_old_dof_object ();

#endif

  void clear_dofs ();

  void invalidate_dofs (const unsigned int sys_num = libMesh::invalid_uint);

  void invalidate_id ();

  void invalidate_processor_id ();

  void invalidate ();

  unsigned int n_dofs (const unsigned int s,
                       const unsigned int var =
                       libMesh::invalid_uint) const;

  dof_id_type id () const;

  dof_id_type & set_id ();

  unique_id_type unique_id () const;

#ifdef LIBMESH_ENABLE_DEPRECATED

  unique_id_type & set_unique_id ();
#endif // LIBMESH_ENABLE_DEPRECATED

  void set_unique_id (unique_id_type new_id);

  void set_id (const dof_id_type dofid)
  { this->set_id() = dofid; }

  bool valid_id () const;

  bool valid_unique_id () const;

  processor_id_type processor_id () const;

  processor_id_type & processor_id ();

  void processor_id (const processor_id_type pid);

  bool valid_processor_id () const;

  unsigned int n_systems() const;

  unsigned int n_pseudo_systems() const;

  void set_n_systems (const unsigned int s);

  void set_extra_integer (const unsigned int index, const dof_id_type value);

  dof_id_type get_extra_integer (const unsigned int index) const;

  template <typename T>
  void set_extra_datum (const unsigned int index, const T value);

  template <typename T>
  T get_extra_datum (const unsigned int index) const;


  void add_system ();

  unsigned int n_var_groups(const unsigned int s) const;

  unsigned int n_vars(const unsigned int s,
                      const unsigned int vg) const;

  unsigned int n_vars(const unsigned int s) const;

  void set_n_vars_per_group(const unsigned int s,
                            const std::vector<unsigned int> & nvpg);

  unsigned int n_comp(const unsigned int s,
                      const unsigned int var) const;

  unsigned int n_comp_group(const unsigned int s,
                            const unsigned int vg) const;

  void set_n_comp(const unsigned int s,
                  const unsigned int var,
                  const unsigned int ncomp);

  void set_n_comp_group(const unsigned int s,
                        const unsigned int vg,
                        const unsigned int ncomp);

  dof_id_type dof_number(const unsigned int s,
                         const unsigned int var,
                         const unsigned int comp) const;

  dof_id_type dof_number(const unsigned int s,
                         const unsigned int vg,
                         const unsigned int vig,
                         const unsigned int comp,
                         const unsigned int n_comp) const;

  std::pair<unsigned int, unsigned int>
  var_to_vg_and_offset(const unsigned int s,
                       const unsigned int var) const;

  void set_dof_number(const unsigned int s,
                      const unsigned int var,
                      const unsigned int comp,
                      const dof_id_type dn);

  bool has_dofs(const unsigned int s=libMesh::invalid_uint) const;

  void set_vg_dof_base(const unsigned int s,
                       const unsigned int vg,
                       const dof_id_type db);

  dof_id_type vg_dof_base(const unsigned int s,
                          const unsigned int vg) const;

  void add_extra_integers (const unsigned int n_integers);

  void add_extra_integers (const unsigned int n_integers,
                           const std::vector<dof_id_type> & default_values);

  unsigned int n_extra_integers () const;

  bool has_extra_integers () const;

  static const dof_id_type invalid_id = static_cast<dof_id_type>(-1);

  static const unique_id_type invalid_unique_id = static_cast<unique_id_type>(-1);

  static const processor_id_type invalid_processor_id = static_cast<processor_id_type>(-1);

  unsigned int packed_indexing_size() const;

  static unsigned int unpackable_indexing_size
  (std::vector<largest_id_type>::const_iterator begin);

  void unpack_indexing(std::vector<largest_id_type>::const_iterator begin);

  void pack_indexing(std::back_insert_iterator<std::vector<largest_id_type>> target) const;

  void debug_buffer () const;

  void print_dof_info() const;

  // Deep copy (or almost-copy) of DofObjects is solely for a couple
  // tricky internal uses.
private:

  DofObject (const DofObject &);

  std::unique_ptr<DofObject>
  construct(const DofObject * other = nullptr);

  DofObject & operator= (const DofObject & dof_obj);

  unsigned int var_to_vg (const unsigned int s,
                          const unsigned int var) const;

  unsigned int system_var_to_vg_var (const unsigned int s,
                                     const unsigned int vg,
                                     const unsigned int var) const;

#ifdef LIBMESH_ENABLE_UNIQUE_ID
  unique_id_type _unique_id;
#endif

  dof_id_type _id;

  processor_id_type _processor_id;

  typedef dof_id_type index_t;
  typedef std::vector<index_t> index_buffer_t;
  index_buffer_t _idx_buf;

  static const index_t ncv_magic = 256; // = 2^8, in case we want to manually bitshift
  static const index_t ncv_magic_exp = 8; // Let's manually bitshift

  unsigned int start_idx(const unsigned int s) const;

  unsigned int end_idx(const unsigned int s) const;

  unsigned int start_idx_ints() const;

  unsigned int end_idx_ints() const;

  // methods only available for unit testing
#ifdef LIBMESH_IS_UNIT_TESTING
public:
  void set_buffer (const std::vector<dof_id_type> & buf)
  { _idx_buf = buf; }
#endif
};



//------------------------------------------------------
// Inline functions
inline
DofObject::DofObject () :
#ifdef LIBMESH_ENABLE_UNIQUE_ID
  _unique_id (invalid_unique_id),
#endif
  _id (invalid_id),
  _processor_id (invalid_processor_id)
{
  this->invalidate();
}



inline
std::unique_ptr<DofObject>
DofObject::construct(const DofObject * other)
{
  return other
    ? std::unique_ptr<DofObject>(new DofObject(*other))
    : std::unique_ptr<DofObject>(new DofObject());
}



inline
void DofObject::invalidate_dofs (const unsigned int sys_num)
{
  const unsigned int n_sys = this->n_systems();
  // If the user does not specify the system number...
  if (sys_num >= n_sys)
    {
      for (auto s : make_range(n_sys))
        for (auto vg : make_range(this->n_var_groups(s)))
          if (this->n_comp_group(s,vg))
            this->set_vg_dof_base(s,vg,invalid_id);
    }
  // ...otherwise invalidate the dofs for all systems
  else
    for (auto vg : make_range(this->n_var_groups(sys_num)))
      if (this->n_comp_group(sys_num,vg))
        this->set_vg_dof_base(sys_num,vg,invalid_id);
}



inline
void DofObject::invalidate_id ()
{
  this->set_id (invalid_id);
}



inline
void DofObject::invalidate_processor_id ()
{
  this->processor_id (invalid_processor_id);
}



inline
void DofObject::invalidate ()
{
  this->invalidate_dofs ();
  this->invalidate_id ();
  this->invalidate_processor_id ();
}



inline
void DofObject::clear_dofs ()
{
  this->set_n_systems(0);
}



inline
unsigned int DofObject::n_dofs (const unsigned int s,
                                const unsigned int var) const
{
  libmesh_assert_less (s, this->n_systems());

  unsigned int num = 0;

  // Count all variables
  if (var == libMesh::invalid_uint)
    for (auto v : make_range(this->n_vars(s)))
      num += this->n_comp(s,v);

  // Only count specified variable
  else
    num = this->n_comp(s,var);

  return num;
}



inline
dof_id_type DofObject::id () const
{
  return _id;
}



inline
dof_id_type & DofObject::set_id ()
{
  return _id;
}



inline
unique_id_type DofObject::unique_id () const
{
#ifdef LIBMESH_ENABLE_UNIQUE_ID
  libmesh_assert (this->valid_unique_id());
  return _unique_id;
#else
  return invalid_unique_id;
#endif
}



#ifdef LIBMESH_ENABLE_DEPRECATED
inline
unique_id_type & DofObject::set_unique_id ()
{
#ifdef LIBMESH_ENABLE_UNIQUE_ID
  libmesh_deprecated();
  return _unique_id;
#else
  libmesh_not_implemented();
#endif
}
#endif // LIBMESH_ENABLE_DEPRECATED



inline
void DofObject::set_unique_id (unique_id_type new_id)
{
#ifdef LIBMESH_ENABLE_UNIQUE_ID
  _unique_id = new_id;
#else
  libmesh_ignore(new_id);
  libmesh_not_implemented();
#endif
}



inline
bool DofObject::valid_id () const
{
  return (DofObject::invalid_id != _id);
}



inline
bool DofObject::valid_unique_id () const
{
#ifdef LIBMESH_ENABLE_UNIQUE_ID
  return (DofObject::invalid_unique_id != _unique_id);
#else
  return false;
#endif
}



inline
processor_id_type DofObject::processor_id () const
{
  return _processor_id;
}



inline
processor_id_type & DofObject::processor_id ()
{
  return _processor_id;
}



inline
void DofObject::processor_id (const processor_id_type pid)
{
  this->processor_id() = pid;
}



inline
bool DofObject::valid_processor_id () const
{
  return (DofObject::invalid_processor_id != _processor_id);
}



inline
unsigned int DofObject::n_systems () const
{
  const int hdr = _idx_buf.empty() ?
    0 : cast_int<int>(dof_id_signed_type(_idx_buf[0]));
  return hdr >= 0 ? hdr : (-hdr-1);
}



inline
unsigned int DofObject::n_pseudo_systems () const
{
  const int hdr = _idx_buf.empty() ?
    0 : cast_int<int>(dof_id_signed_type(_idx_buf[0]));
  return std::abs(hdr);
}



inline
unsigned int DofObject::n_var_groups(const unsigned int s) const
{
  libmesh_assert_less (s, this->n_systems());

  return (this->end_idx(s) - this->start_idx(s)) / 2;
}



inline
unsigned int DofObject::n_vars(const unsigned int s,
                               const unsigned int vg) const
{
  libmesh_assert_less (s,  this->n_systems());
  libmesh_assert_less (vg, this->n_var_groups(s));

  const unsigned int start_idx_sys = this->start_idx(s);

  libmesh_assert_less ((start_idx_sys + 2*vg), _idx_buf.size());

  return (cast_int<unsigned int>
          (_idx_buf[start_idx_sys + 2*vg]) >> ncv_magic_exp);
}



inline
unsigned int DofObject::n_vars(const unsigned int s) const
{
  libmesh_assert_less (s, this->n_systems());

  const unsigned int nvg = this->n_var_groups(s);

  unsigned int val=0;

  for (unsigned int vg=0; vg<nvg; vg++)
    val += this->n_vars(s,vg);

  return val;
}




inline
unsigned int DofObject::n_comp(const unsigned int s,
                               const unsigned int var) const
{
  libmesh_assert_less (s,   this->n_systems());
  libmesh_assert_less (var, this->n_vars(s));

  return this->n_comp_group(s,this->var_to_vg(s,var));
}




inline
unsigned int DofObject::n_comp_group(const unsigned int s,
                                     const unsigned int vg) const
{
  libmesh_assert_less (s,  this->n_systems());
  libmesh_assert_less (vg, this->n_var_groups(s));

  const unsigned int
    start_idx_sys = this->start_idx(s);

  libmesh_assert_less ((start_idx_sys + 2*vg), _idx_buf.size());

  return (_idx_buf[start_idx_sys + 2*vg] % ncv_magic);
}



inline
dof_id_type DofObject::dof_number(const unsigned int s,
                                  const unsigned int var,
                                  const unsigned int comp) const
{
  libmesh_assert_less (s,    this->n_systems());
  libmesh_assert_less (var,  this->n_vars(s));
  libmesh_assert_less (comp, this->n_comp(s,var));

  const std::pair<unsigned int, unsigned int>
    vg_vig = this->var_to_vg_and_offset(s,var);

  const unsigned int
    n_comp = this->n_comp_group(s,vg_vig.first);

  return this->dof_number(s, vg_vig.first, vg_vig.second,
                          comp, n_comp);
}



inline
dof_id_type DofObject::dof_number(const unsigned int s,
                                  const unsigned int vg,
                                  const unsigned int vig,
                                  const unsigned int comp,
                                  const unsigned int n_comp) const
{
  libmesh_assert_less (s,   this->n_systems());
  libmesh_assert_less (vg,  this->n_var_groups(s));
  libmesh_assert_less (vig, this->n_vars(s,vg));

  const unsigned int
    start_idx_sys = this->start_idx(s);

  libmesh_assert_less ((start_idx_sys + 2*vg + 1), _idx_buf.size());

  const dof_id_type
    base_idx = _idx_buf[start_idx_sys + 2*vg + 1];

  // if the first component is invalid, they
  // are all invalid
  if (base_idx == invalid_id)
    return invalid_id;

  // otherwise the index is the first component
  // index augmented by the component number
  else
    return cast_int<dof_id_type>(base_idx + vig*n_comp + comp);
}



inline
void
DofObject::set_extra_integer(const unsigned int index,
                             const dof_id_type value)
{
  libmesh_assert_less(index, this->n_extra_integers());
  libmesh_assert_less(this->n_pseudo_systems(), _idx_buf.size());

  const unsigned int start_idx_i = this->start_idx_ints();

  libmesh_assert_less(start_idx_i+index, _idx_buf.size());
  _idx_buf[start_idx_i+index] = value;
}



inline
dof_id_type
DofObject::get_extra_integer (const unsigned int index) const
{
  libmesh_assert_less(index, this->n_extra_integers());
  libmesh_assert_less(this->n_systems(), _idx_buf.size());

  const unsigned int start_idx_i = this->start_idx_ints();

  libmesh_assert_less(start_idx_i+index, _idx_buf.size());
  return _idx_buf[start_idx_i+index];
}



// If we're using a type T that's a class with no trivial
// copy-assignment, -Wclass-memaccess will scream about doing it with
// memcpy, even if (as with boost::multiprecision::float128) this is a
// false positive.
#include "libmesh/ignore_warnings.h"



template <typename T>
inline
void
DofObject::set_extra_datum(const unsigned int index,
                           const T value)
{
#ifndef NDEBUG
  const unsigned int n_more_integers = (sizeof(T)-1)/sizeof(dof_id_type);
#endif
  libmesh_assert_less(index+n_more_integers, this->n_extra_integers());
  libmesh_assert_less(this->n_pseudo_systems(), _idx_buf.size());

  const unsigned int start_idx_i = this->start_idx_ints();

  libmesh_assert_less(start_idx_i+index+n_more_integers, _idx_buf.size());
  std::memcpy(&_idx_buf[start_idx_i+index], &value, sizeof(T));
}



template <typename T>
inline
T
DofObject::get_extra_datum (const unsigned int index) const
{
#ifndef NDEBUG
  const unsigned int n_more_integers = (sizeof(T)-1)/sizeof(dof_id_type);
#endif
  libmesh_assert_less(index+n_more_integers, this->n_extra_integers());
  libmesh_assert_less(this->n_systems(), _idx_buf.size());

  const unsigned int start_idx_i = this->start_idx_ints();

  libmesh_assert_less(start_idx_i+index+n_more_integers, _idx_buf.size());
  T returnval;
  std::memcpy(&returnval, &_idx_buf[start_idx_i+index], sizeof(T));
  return returnval;
}



#include "libmesh/restore_warnings.h"



inline
unsigned int
DofObject::n_extra_integers () const
{
  if (_idx_buf.empty())
    return 0;

  const int hdr = dof_id_signed_type(_idx_buf[0]);
  if (hdr >= 0)
    return 0;

  const unsigned int start_idx_i = this->start_idx_ints();

  return _idx_buf.size() - start_idx_i;
}



inline
bool
DofObject::has_extra_integers () const
{
  if (_idx_buf.empty())
    return 0;

  return (dof_id_signed_type(_idx_buf[0]) < 0);
}



inline
std::pair<unsigned int, unsigned int>
DofObject::var_to_vg_and_offset(const unsigned int s,
                                const unsigned int var) const
{
  std::pair<unsigned int, unsigned int> returnval(0,0);

  unsigned int & vg = returnval.first;
  unsigned int & offset = returnval.second;

  unsigned int vg_start = 0;
  for (; ; vg++)
    {
      libmesh_assert_less(vg, this->n_var_groups(s));

      const unsigned int vg_end = vg_start + this->n_vars(s,vg);
      if (var < vg_end)
        {
          offset = var - vg_start;
          return returnval;
        }
      vg_start = vg_end;
    }
}



inline
bool DofObject::has_dofs (const unsigned int sys) const
{
  if (sys == libMesh::invalid_uint)
    {
      for (auto s : make_range(this->n_systems()))
        if (this->n_vars(s))
          return true;
    }

  else
    {
      libmesh_assert_less (sys, this->n_systems());

      if (this->n_vars(sys))
        return true;
    }

  return false;
}



inline
unsigned int DofObject::start_idx (const unsigned int s) const
{
  libmesh_assert_less (s, this->n_systems());
  libmesh_assert_less (s, _idx_buf.size());

  return cast_int<unsigned int>(std::abs(dof_id_signed_type(_idx_buf[s])));
}



inline
unsigned int DofObject::end_idx (const unsigned int s) const
{
  libmesh_assert_less (s, this->n_systems());
  libmesh_assert_less (s, _idx_buf.size());

  return ((s+1) == this->n_pseudo_systems()) ?
    cast_int<unsigned int>(_idx_buf.size()) :
    cast_int<unsigned int>(_idx_buf[s+1]);
}



inline
unsigned int DofObject::start_idx_ints () const
{
  libmesh_assert (this->has_extra_integers());

  unsigned int n_sys = this->n_systems();

  libmesh_assert_less(this->n_systems(), _idx_buf.size());
  return n_sys ? cast_int<unsigned int>(_idx_buf[this->n_systems()]) :
                 (n_sys+1);
}



inline
unsigned int DofObject::end_idx_ints () const
{
  libmesh_assert (this->has_extra_integers());

  return cast_int<unsigned int>(_idx_buf.size());
}



inline
void DofObject::set_vg_dof_base(const unsigned int s,
                                const unsigned int vg,
                                const dof_id_type db)
{
  libmesh_assert_less (s,  this->n_systems());
  libmesh_assert_less (vg, this->n_var_groups(s));

  const unsigned int
    start_idx_sys = this->start_idx(s);

  libmesh_assert_less ((start_idx_sys + 2*vg + 1), _idx_buf.size());

  _idx_buf[start_idx_sys + 2*vg + 1] = db;

  libmesh_assert_equal_to (this->vg_dof_base(s,vg), db);
}



inline
dof_id_type DofObject::vg_dof_base(const unsigned int s,
                                   const unsigned int vg) const
{
  libmesh_assert_less (s,  this->n_systems());
  libmesh_assert_less (vg, this->n_var_groups(s));

  const unsigned int
    start_idx_sys = this->start_idx(s);

  libmesh_assert_less ((start_idx_sys + 2*vg + 1), _idx_buf.size());

  // #ifdef DEBUG
  //   std::cout << " [ ";
  //   for (auto i : _idx_buf)
  //     std::cout << i << " ";
  //   std::cout << "]\n";
  // #endif

  return _idx_buf[start_idx_sys + 2*vg + 1];
}



inline
unsigned int DofObject::var_to_vg (const unsigned int s,
                                   const unsigned int var) const
{
  const unsigned int
    nvg = this->n_var_groups(s);

  for (unsigned int vg=0, vg_end=0; vg<nvg; vg++)
    {
      vg_end += this->n_vars(s,vg);
      if (var < vg_end) return vg;
    }

  libmesh_error_msg("Error: could not map variable " << var << " to variable group.");
}



inline
unsigned int DofObject::system_var_to_vg_var (const unsigned int s,
                                              const unsigned int vg,
                                              const unsigned int var) const
{
  unsigned int accumulated_sum=0;

  for (unsigned int vgc=0; vgc<vg; vgc++)
    accumulated_sum += this->n_vars(s,vgc);

  libmesh_assert_less_equal (accumulated_sum, var);

  return (var - accumulated_sum);
}

struct CompareDofObjectsByID
{
  bool operator()(const DofObject * a,
                  const DofObject * b) const
  {
    libmesh_assert (a);
    libmesh_assert (b);

    return a->id() < b->id();
  }
};

struct CompareDofObjectsByPIDAndThenID
{
  bool operator()(const DofObject * a,
                  const DofObject * b) const
  {
    libmesh_assert (a);
    libmesh_assert (b);

    if (a->processor_id() < b->processor_id())
      return true;
    if (b->processor_id() < a->processor_id())
      return false;

    return a->id() < b->id();
  }
};

} // namespace libMesh


#endif // #ifndef LIBMESH_DOF_OBJECT_H