mesh_base.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_MESH_BASE_H
#define LIBMESH_MESH_BASE_H

// Local Includes
#include "libmesh/dof_object.h" // for invalid_processor_id
#include "libmesh/enum_order.h"
#include "libmesh/int_range.h"
#include "libmesh/libmesh_common.h"
#include "libmesh/multi_predicates.h"
#include "libmesh/point_locator_base.h"
#include "libmesh/variant_filter_iterator.h"
#include "libmesh/parallel_object.h"
#include "libmesh/simple_range.h"

// C++ Includes
#include <cstddef>
#include <string>
#include <memory>

namespace libMesh
{

// forward declarations
class Elem;
class GhostingFunctor;
class Node;
class Point;
class Partitioner;
class BoundaryInfo;

template <typename T>
class SparseMatrix;

enum ElemType : int;
enum ElemMappingType : unsigned char;

template <class MT>
class MeshInput;


class MeshBase : public ParallelObject
{
public:

  MeshBase (const Parallel::Communicator & comm_in,
            unsigned char dim=1);

  MeshBase (const MeshBase & other_mesh);

  MeshBase(MeshBase &&) = delete;

  MeshBase & operator= (const MeshBase &) = delete;
  MeshBase & operator= (MeshBase && other_mesh);

  virtual MeshBase & assign(MeshBase && other_mesh) = 0;

  bool operator== (const MeshBase & other_mesh) const;

  bool operator!= (const MeshBase & other_mesh) const
  {
    return !(*this == other_mesh);
  }

  bool locally_equals (const MeshBase & other_mesh) const;

  virtual std::unique_ptr<MeshBase> clone() const = 0;

  virtual ~MeshBase ();

  virtual std::unique_ptr<Partitioner> & partitioner() { return _partitioner; }

  const BoundaryInfo & get_boundary_info() const { return *boundary_info; }

  BoundaryInfo & get_boundary_info() { return *boundary_info; }

  virtual void clear ();

  virtual void clear_elems () = 0;

  bool is_prepared () const
  { return _is_prepared; }

  void set_isnt_prepared()
  { _is_prepared = false; }

  virtual bool is_serial () const
  { return true; }

  virtual bool is_serial_on_zero () const
  { return true; }

  virtual void set_distributed ()
  { libmesh_error(); }

  virtual bool is_replicated () const
  { return true; }

  virtual void allgather () {}

  virtual void gather_to_zero() {}

  virtual void delete_remote_elements () {}

  void reinit_ghosting_functors();

  unsigned int mesh_dimension () const;

  void set_mesh_dimension (unsigned char d)
  { _elem_dims.clear(); _elem_dims.insert(d); }

  const std::set<unsigned char> & elem_dimensions() const
  { return _elem_dims; }

  const std::set<Order> & elem_default_orders() const
  { return _elem_default_orders; }

  Order supported_nodal_order() const
  { return _supported_nodal_order; }

  void set_elem_dimensions(std::set<unsigned char> elem_dims);

  typedef std::set<elemset_id_type> elemset_type;

  void add_elemset_code(dof_id_type code, MeshBase::elemset_type id_set);

  unsigned int n_elemsets() const;

  void get_elemsets(dof_id_type elemset_code, MeshBase::elemset_type & id_set_to_fill) const;
  dof_id_type get_elemset_code(const MeshBase::elemset_type & id_set) const;

  std::vector<dof_id_type> get_elemset_codes() const;

  void change_elemset_code(dof_id_type old_code, dof_id_type new_code);

  void change_elemset_id(elemset_id_type old_id, elemset_id_type new_id);

  unsigned int spatial_dimension () const;

  void set_spatial_dimension(unsigned char d);

  virtual dof_id_type n_nodes () const = 0;

  virtual dof_id_type parallel_n_nodes () const = 0;

  dof_id_type n_nodes_on_proc (const processor_id_type proc) const;

  dof_id_type n_local_nodes () const
  { return this->n_nodes_on_proc (this->processor_id()); }

  dof_id_type n_unpartitioned_nodes () const
  { return this->n_nodes_on_proc (DofObject::invalid_processor_id); }

  virtual dof_id_type max_node_id () const = 0;

#ifdef LIBMESH_ENABLE_UNIQUE_ID

  unique_id_type next_unique_id() { return _next_unique_id; }

  virtual void set_next_unique_id(unique_id_type id) = 0;
#endif

  virtual void reserve_nodes (const dof_id_type nn) = 0;

  virtual dof_id_type n_elem () const = 0;

  virtual dof_id_type parallel_n_elem () const = 0;

  virtual dof_id_type max_elem_id () const = 0;

#ifdef LIBMESH_ENABLE_UNIQUE_ID
  virtual unique_id_type parallel_max_unique_id () const = 0;
#endif

  virtual void reserve_elem (const dof_id_type ne) = 0;

  virtual void update_parallel_id_counts () = 0;

  virtual dof_id_type n_active_elem () const = 0;

  dof_id_type n_elem_on_proc (const processor_id_type proc) const;

  dof_id_type n_local_elem () const
  { return this->n_elem_on_proc (this->processor_id()); }

  dof_id_type n_unpartitioned_elem () const
  { return this->n_elem_on_proc (DofObject::invalid_processor_id); }

  dof_id_type n_active_elem_on_proc (const processor_id_type proc) const;

  dof_id_type n_active_local_elem () const
  { return this->n_active_elem_on_proc (this->processor_id()); }

  dof_id_type n_sub_elem () const;

  dof_id_type n_active_sub_elem () const;

  virtual const Point & point (const dof_id_type i) const = 0;

  virtual const Node & node_ref (const dof_id_type i) const
  {
    return *this->node_ptr(i);
  }

  virtual Node & node_ref (const dof_id_type i)
  {
    return *this->node_ptr(i);
  }

  virtual const Node * node_ptr (const dof_id_type i) const = 0;

  virtual Node * node_ptr (const dof_id_type i) = 0;

  virtual const Node * query_node_ptr (const dof_id_type i) const = 0;

  virtual Node * query_node_ptr (const dof_id_type i) = 0;

  virtual const Elem & elem_ref (const dof_id_type i) const
  {
    return *this->elem_ptr(i);
  }

  virtual Elem & elem_ref (const dof_id_type i)
  {
    return *this->elem_ptr(i);
  }

  virtual const Elem * elem_ptr (const dof_id_type i) const = 0;

  virtual Elem * elem_ptr (const dof_id_type i) = 0;

  virtual const Elem * query_elem_ptr (const dof_id_type i) const = 0;

  virtual Elem * query_elem_ptr (const dof_id_type i) = 0;

  virtual Node * add_point (const Point & p,
                            const dof_id_type id = DofObject::invalid_id,
                            const processor_id_type proc_id =
                            DofObject::invalid_processor_id) = 0;

  virtual Node * add_node (Node * n) = 0;

  virtual Node * add_node (std::unique_ptr<Node> n) = 0;

#ifdef LIBMESH_ENABLE_DEPRECATED

  virtual Node * insert_node(Node * n) = 0;

  virtual Node * insert_node(std::unique_ptr<Node> n) = 0;
#endif

  virtual void delete_node (Node * n) = 0;

  virtual void own_node (Node &) {}

  virtual void renumber_node (dof_id_type old_id, dof_id_type new_id) = 0;

  virtual Elem * add_elem (Elem * e) = 0;

  virtual Elem * add_elem (std::unique_ptr<Elem> e) = 0;

  virtual Elem * insert_elem (Elem * e) = 0;

  virtual Elem * insert_elem (std::unique_ptr<Elem> e) = 0;

  virtual void delete_elem (Elem * e) = 0;

  virtual void renumber_elem (dof_id_type old_id, dof_id_type new_id) = 0;

  ElemMappingType default_mapping_type () const
  {
    return _default_mapping_type;
  }

  void set_default_mapping_type (const ElemMappingType type)
  {
    _default_mapping_type = type;
  }

  unsigned char default_mapping_data () const
  {
    return _default_mapping_data;
  }

  void set_default_mapping_data (const unsigned char data)
  {
    _default_mapping_data = data;
  }

  virtual void find_neighbors (const bool reset_remote_elements = false,
                               const bool reset_current_list    = true) = 0;

  void remove_orphaned_nodes ();

  virtual void renumber_nodes_and_elements () = 0;

  virtual void fix_broken_node_and_element_numbering () = 0;


#ifdef LIBMESH_ENABLE_AMR

  virtual bool contract () = 0;
#endif

  unsigned int add_elem_integer(std::string name,
                                bool allocate_data = true,
                                dof_id_type default_value = DofObject::invalid_id);

  std::vector<unsigned int> add_elem_integers(const std::vector<std::string> & names,
                                              bool allocate_data = true,
                                              const std::vector<dof_id_type> * default_values = nullptr);

  /*
   * \returns The index number for the named extra element integer
   * datum, which must have already been added.
   */
  unsigned int get_elem_integer_index(std::string_view name) const;

  /*
   * \returns Whether or not the mesh has an element integer with its name.
   */
  bool has_elem_integer(std::string_view name) const;

  /*
   * \returns The name for the indexed extra element integer
   * datum, which must have already been added.
   */
  const std::string & get_elem_integer_name(unsigned int i) const
  { return _elem_integer_names[i]; }

  /*
   * \returns The number of extra element integers for which space is
   * being reserved on this mesh.
   *
   * If non-integer data has been associated, each datum of type T
   * counts for sizeof(T)/sizeof(dof_id_type) times in the return
   * value.
   */
  unsigned int n_elem_integers() const { return _elem_integer_names.size(); }

  template <typename T>
  unsigned int add_elem_datum(const std::string & name,
                              bool allocate_data = true,
                              const T * default_value = nullptr);

  template <typename T>
  std::vector<unsigned int> add_elem_data(const std::vector<std::string> & names,
                                          bool allocate_data = true,
                                          const std::vector<T> * default_values = nullptr);

  unsigned int add_node_integer(std::string name,
                                bool allocate_data = true,
                                dof_id_type default_value = DofObject::invalid_id);

  std::vector<unsigned int> add_node_integers(const std::vector<std::string> & names,
                                              bool allocate_data = true,
                                              const std::vector<dof_id_type> * default_values = nullptr);

  /*
   * \returns The index number for the named extra node integer
   * datum, which must have already been added.
   */
  unsigned int get_node_integer_index(std::string_view name) const;

  /*
   * \returns Whether or not the mesh has a node integer with its name.
   */
  bool has_node_integer(std::string_view name) const;

  /*
   * \returns The name for the indexed extra node integer
   * datum, which must have already been added.
   */
  const std::string & get_node_integer_name(unsigned int i) const
  { return _node_integer_names[i]; }

  /*
   * \returns The number of extra node integers for which space is
   * being reserved on this mesh.
   *
   * If non-integer data has been associated, each datum of type T
   * counts for sizeof(T)/sizeof(dof_id_type) times in the return
   * value.
   */
  unsigned int n_node_integers() const { return _node_integer_names.size(); }

  template <typename T>
  unsigned int add_node_datum(const std::string & name,
                              bool allocate_data = true,
                              const T * default_value = nullptr);

  template <typename T>
  std::vector<unsigned int> add_node_data(const std::vector<std::string> & name,
                                          bool allocate_data = true,
                                          const std::vector<T> * default_values = nullptr);

#ifdef LIBMESH_ENABLE_DEPRECATED
  void prepare_for_use (const bool skip_renumber_nodes_and_elements, const bool skip_find_neighbors);
  void prepare_for_use (const bool skip_renumber_nodes_and_elements);
#endif // LIBMESH_ENABLE_DEPRECATED
  void prepare_for_use ();

  virtual void partition (const unsigned int n_parts);

  void partition ()
  { this->partition(this->n_processors()); }

  virtual void redistribute ();

  virtual void update_post_partitioning () {}

  void allow_renumbering(bool allow) { _skip_renumber_nodes_and_elements = !allow; }
  bool allow_renumbering() const { return !_skip_renumber_nodes_and_elements; }

  void allow_find_neighbors(bool allow) { _skip_find_neighbors = !allow; }
  bool allow_find_neighbors() const { return !_skip_find_neighbors; }

  void allow_remote_element_removal(bool allow) { _allow_remote_element_removal = allow; }
  bool allow_remote_element_removal() const { return _allow_remote_element_removal; }

  void skip_noncritical_partitioning(bool skip)
  { _skip_noncritical_partitioning = skip; }

  bool skip_noncritical_partitioning() const
  { return _skip_noncritical_partitioning || _skip_all_partitioning || !_partitioner.get(); }


  void skip_partitioning(bool skip) { _skip_all_partitioning = skip; }

  bool skip_partitioning() const { return _skip_all_partitioning; }

  void add_ghosting_functor(GhostingFunctor & ghosting_functor)
  { _ghosting_functors.insert(&ghosting_functor); }

  void add_ghosting_functor(std::shared_ptr<GhostingFunctor> ghosting_functor)
  { _shared_functors[ghosting_functor.get()] = ghosting_functor;
    this->add_ghosting_functor(*ghosting_functor); }

  void remove_ghosting_functor(GhostingFunctor & ghosting_functor);

  std::set<GhostingFunctor *>::const_iterator ghosting_functors_begin() const
  { return _ghosting_functors.begin(); }

  std::set<GhostingFunctor *>::const_iterator ghosting_functors_end() const
  { return _ghosting_functors.end(); }

  GhostingFunctor & default_ghosting() { return *_default_ghosting; }

  void subdomain_ids (std::set<subdomain_id_type> & ids, const bool global = true) const;

  subdomain_id_type n_subdomains () const;

  subdomain_id_type n_local_subdomains () const;

  unsigned int n_partitions () const
  { return _n_parts; }

  std::string get_info (const unsigned int verbosity = 0, const bool global = true) const;

  void print_info (std::ostream & os=libMesh::out, const unsigned int verbosity = 0, const bool global = true) const;

  friend std::ostream & operator << (std::ostream & os, const MeshBase & m);

  virtual void read  (const std::string & name,
                      void * mesh_data=nullptr,
                      bool skip_renumber_nodes_and_elements=false,
                      bool skip_find_neighbors=false) = 0;
  virtual void write (const std::string & name) const = 0;

  virtual void all_first_order () = 0;

  typedef Predicates::multi_predicate Predicate;

  struct element_iterator;
  struct const_element_iterator;

  struct node_iterator;
  struct const_node_iterator;

  virtual void all_second_order_range(const SimpleRange<element_iterator> & range,
                                      const bool full_ordered = true) = 0;

  void all_second_order (const bool full_ordered = true);

  virtual void all_complete_order_range(const SimpleRange<element_iterator> & range) = 0;

  virtual void all_complete_order ();

  unsigned int recalculate_n_partitions();

  std::unique_ptr<PointLocatorBase> sub_point_locator () const;

  void set_point_locator_close_to_point_tol(Real val);
  Real get_point_locator_close_to_point_tol() const;

  void clear_point_locator ();

  void set_count_lower_dim_elems_in_point_locator(bool count_lower_dim_elems);

  bool get_count_lower_dim_elems_in_point_locator() const;

  virtual void libmesh_assert_valid_parallel_ids() const {}

  std::string & subdomain_name(subdomain_id_type id);
  const std::string & subdomain_name(subdomain_id_type id) const;

  subdomain_id_type get_id_by_name(std::string_view name) const;

  /*
   * We have many combinations of iterators that filter on various
   * characteristics; we use macros to make their abstract base class
   * and their subclass declarations more terse.
   */
#define ABSTRACT_ELEM_ITERATORS(TYPE, ARGDECL) \
  virtual element_iterator TYPE##elements_begin(ARGDECL) = 0; \
  virtual element_iterator TYPE##elements_end(ARGDECL) = 0; \
  virtual const_element_iterator TYPE##elements_begin(ARGDECL) const = 0; \
  virtual const_element_iterator TYPE##elements_end(ARGDECL) const = 0; \
  virtual SimpleRange<element_iterator> TYPE##element_ptr_range(ARGDECL) = 0; \
  virtual SimpleRange<const_element_iterator> TYPE##element_ptr_range(ARGDECL) const = 0;

#define DECLARE_ELEM_ITERATORS(TYPE, ARGDECL, ARGS) \
  virtual element_iterator TYPE##elements_begin(ARGDECL) override final; \
  virtual element_iterator TYPE##elements_end(ARGDECL) override final; \
  virtual const_element_iterator TYPE##elements_begin(ARGDECL) const override final; \
  virtual const_element_iterator TYPE##elements_end(ARGDECL) const override final; \
  virtual SimpleRange<element_iterator> TYPE##element_ptr_range(ARGDECL) override final { return {TYPE##elements_begin(ARGS), TYPE##elements_end(ARGS)}; } \
  virtual SimpleRange<const_element_iterator> TYPE##element_ptr_range(ARGDECL) const override final  { return {TYPE##elements_begin(ARGS), TYPE##elements_end(ARGS)}; }

#define ABSTRACT_NODE_ITERATORS(TYPE, ARGDECL) \
  virtual node_iterator TYPE##nodes_begin(ARGDECL) = 0; \
  virtual node_iterator TYPE##nodes_end(ARGDECL) = 0; \
  virtual const_node_iterator TYPE##nodes_begin(ARGDECL) const = 0; \
  virtual const_node_iterator TYPE##nodes_end(ARGDECL) const = 0; \
  virtual SimpleRange<node_iterator> TYPE##node_ptr_range(ARGDECL) = 0; \
  virtual SimpleRange<const_node_iterator> TYPE##node_ptr_range(ARGDECL) const = 0;

#define DECLARE_NODE_ITERATORS(TYPE, ARGDECL, ARGS) \
  virtual node_iterator TYPE##nodes_begin(ARGDECL) override final; \
  virtual node_iterator TYPE##nodes_end(ARGDECL) override final; \
  virtual const_node_iterator TYPE##nodes_begin(ARGDECL) const override final; \
  virtual const_node_iterator TYPE##nodes_end(ARGDECL) const override final; \
  virtual SimpleRange<node_iterator> TYPE##node_ptr_range(ARGDECL) override final { return {TYPE##nodes_begin(ARGS), TYPE##nodes_end(ARGS)}; } \
  virtual SimpleRange<const_node_iterator> TYPE##node_ptr_range(ARGDECL) const override final  { return {TYPE##nodes_begin(ARGS), TYPE##nodes_end(ARGS)}; }

#define LIBMESH_COMMA ,

  /*
   * element_iterator accessors
   *
   * The basic elements_begin() and elements_end() iterators iterate
   * over all elements in a mesh, returning element pointers or const
   * element pointers when dereferenced (depending on whether the mesh
   * reference was const). range-for loops can be written using
   * element_ptr_range()
   *
   * Filtered versions of these iterators, which skip over all
   * elements not matching some predicate, are also available, by
   * adding a prefix to the methods above.  E.g. local_ (in a form
   * like local_elements_begin() or local_element_ptr_range()) will
   * iterate only over elements whose processor_id() is the current
   * processor, or active_ will iterate only over active elements even
   * if the mesh is refined, or active_local_ will iterate over
   * elements that are both active and local.  Negation forms such as
   * not_local_ also exist.
   *
   * For some iterator prefixes, such as type_, an argument is needed
   * for the filter; e.g. the ElemType to select for in that case.
   *
   * All valid prefixes and their corresponding arguments can be found
   * in the macro invocations below.
   */
  ABSTRACT_ELEM_ITERATORS(,)                // elements_begin(), element_ptr_range(): all elements
  ABSTRACT_ELEM_ITERATORS(active_,)         // Elem::active() == true
  ABSTRACT_ELEM_ITERATORS(ancestor_,)       // Elem::ancestor() == true
  ABSTRACT_ELEM_ITERATORS(subactive_,)      // Elem::subactive() == true
  ABSTRACT_ELEM_ITERATORS(local_,)          // Elem::processor_id() == this processor
  ABSTRACT_ELEM_ITERATORS(unpartitioned_,)  // Elem::processor_id() == invalid_processor_id
  ABSTRACT_ELEM_ITERATORS(facelocal_,)      // is on or has a neighbor on this processor
  ABSTRACT_ELEM_ITERATORS(level_,unsigned int level)   // Elem::level() == level
  ABSTRACT_ELEM_ITERATORS(pid_,processor_id_type pid)  // Elem::processor_id() == pid
  ABSTRACT_ELEM_ITERATORS(type_,ElemType type)         // Elem::type() == type

  ABSTRACT_ELEM_ITERATORS(active_subdomain_,subdomain_id_type sid) // active && Elem::subdomain_id() == sid
  ABSTRACT_ELEM_ITERATORS(active_subdomain_set_,std::set<subdomain_id_type> ss) // active && ss.contains(Elem::subdomain_id())

  // Iterators which use negations of filters described above
  ABSTRACT_ELEM_ITERATORS(not_active_,)
  ABSTRACT_ELEM_ITERATORS(not_ancestor_,)
  ABSTRACT_ELEM_ITERATORS(not_subactive_,)
  ABSTRACT_ELEM_ITERATORS(not_local_,)
  ABSTRACT_ELEM_ITERATORS(not_level_,unsigned int level)

  // Iterators which combine multiple of the filters described above
  ABSTRACT_ELEM_ITERATORS(active_local_,)
  ABSTRACT_ELEM_ITERATORS(active_not_local_,)
  ABSTRACT_ELEM_ITERATORS(active_unpartitioned_,)
  ABSTRACT_ELEM_ITERATORS(active_type_,ElemType type)
  ABSTRACT_ELEM_ITERATORS(active_pid_,processor_id_type pid)
  ABSTRACT_ELEM_ITERATORS(local_level_,unsigned int level)
  ABSTRACT_ELEM_ITERATORS(local_not_level_,unsigned int level)
  ABSTRACT_ELEM_ITERATORS(active_local_subdomain_,subdomain_id_type sid)
  ABSTRACT_ELEM_ITERATORS(active_local_subdomain_set_,std::set<subdomain_id_type> ss)

  // Backwards compatibility
  virtual SimpleRange<element_iterator> active_subdomain_elements_ptr_range(subdomain_id_type sid) = 0;
  virtual SimpleRange<const_element_iterator> active_subdomain_elements_ptr_range(subdomain_id_type sid) const = 0;
  virtual SimpleRange<element_iterator> active_local_subdomain_elements_ptr_range(subdomain_id_type sid) = 0;
  virtual SimpleRange<const_element_iterator> active_local_subdomain_elements_ptr_range(subdomain_id_type sid) const = 0;
  virtual SimpleRange<element_iterator> active_subdomain_set_elements_ptr_range(std::set<subdomain_id_type> ss) = 0;
  virtual SimpleRange<const_element_iterator> active_subdomain_set_elements_ptr_range(std::set<subdomain_id_type> ss) const = 0;

  // Discouraged from use - these iterators use outdated
  // pre-GhostingFunctor definitions and should be renamed if not
  // deprecated
  ABSTRACT_ELEM_ITERATORS(semilocal_,)         // active && Elem::is_semilocal()
  ABSTRACT_ELEM_ITERATORS(ghost_,)             // active && Elem::is_semilocal() && not local discouraged
  ABSTRACT_ELEM_ITERATORS(active_semilocal_,)

  // solution can be evaluated, with the given DoF map, for the given
  // variable number, or for all variables by default
  ABSTRACT_ELEM_ITERATORS(evaluable_,const DofMap & dof_map LIBMESH_COMMA unsigned int var_num = libMesh::invalid_uint)

  // solution can be evaluated for all variables of all given DoF maps
  ABSTRACT_ELEM_ITERATORS(multi_evaluable_,std::vector<const DofMap *> dof_maps)

#ifdef LIBMESH_ENABLE_AMR
  ABSTRACT_ELEM_ITERATORS(flagged_,unsigned char rflag)  // Elem::refinement_flag() == rflag

  // Elem::refinement_flag() == rflag && Elem::processor_id() == pid
  ABSTRACT_ELEM_ITERATORS(flagged_pid_,unsigned char rflag LIBMESH_COMMA processor_id_type pid)
#endif

  /*
   * node_iterator accessors
   *
   * The basic nodes_begin() and nodes_end() iterators iterate
   * over all nodes in a mesh, returning node pointers or const
   * node pointers when dereferenced (depending on whether the mesh
   * reference was const). range-for loops can be written using
   * node_ptr_range()
   *
   * Filtered versions of these iterators, which skip over all
   * nodes not matching some predicate, are also available, by
   * adding a prefix to the methods above.  E.g. local_ (in a form
   * like local_nodes_begin() or local_node_ptr_range()) will
   * iterate only over nodes whose processor_id() is the current
   * processor.
   *
   * All valid prefixes and their corresponding arguments can be found
   * in the macro invocations below.
   */
  ABSTRACT_NODE_ITERATORS(,)          // nodes_begin(), node_ptr_range(): all nodes
  ABSTRACT_NODE_ITERATORS(active_,)   // Node::active() == true; i.e. Node::id() != invalid_id
  ABSTRACT_NODE_ITERATORS(local_,)    // Node::processor_id() == this processor
  ABSTRACT_NODE_ITERATORS(bnd_,)      // BoundaryInfo::n_boundary_ids(node) > 0
  ABSTRACT_NODE_ITERATORS(pid_,processor_id_type pid)  // Node::processor_id() == pid
  ABSTRACT_NODE_ITERATORS(bid_,boundary_id_type bid)   // BoundaryInfo::has_boundary_id(node, bid)

  // solution can be evaluated, with the given DoF map, for the given
  // variable number, or for all variables by default
  ABSTRACT_NODE_ITERATORS(evaluable_,const DofMap & dof_map LIBMESH_COMMA unsigned int var_num = libMesh::invalid_uint)

  // solution can be evaluated for all variables of all given DoF maps
  ABSTRACT_NODE_ITERATORS(multi_evaluable_,std::vector<const DofMap *> dof_maps)

  std::map<subdomain_id_type, std::string> & set_subdomain_name_map ()
  { return _block_id_to_name; }
  const std::map<subdomain_id_type, std::string> & get_subdomain_name_map () const
  { return _block_id_to_name; }

  typedef std::vector<std::pair<std::pair<const Elem *, unsigned int>, Real>> constraint_rows_mapped_type;
  typedef std::map<const Node *, constraint_rows_mapped_type> constraint_rows_type;

  constraint_rows_type & get_constraint_rows()
  { return _constraint_rows; }

  const constraint_rows_type & get_constraint_rows() const
  { return _constraint_rows; }

  dof_id_type n_constraint_rows() const;

  void copy_constraint_rows(const MeshBase & other_mesh);

  template <typename T>
  void copy_constraint_rows(const SparseMatrix<T> & constraint_operator,
                            bool precondition_constraint_operator = false);

  void print_constraint_rows(std::ostream & os=libMesh::out,
                             bool print_nonlocal=false) const;

  std::string get_local_constraints(bool print_nonlocal=false) const;

#ifdef LIBMESH_ENABLE_DEPRECATED

  void cache_elem_dims();
#endif // LIBMESH_ENABLE_DEPRECATED

  /*
   * Search the mesh and cache data for the elements
   * present in the mesh.  This is done in prepare_for_use(), but can
   * be done manually by other classes after major mesh modifications.
   * Data cached includes:
   *   - elem dimensions
   *   - elem subdomains
   */
  void cache_elem_data();

  void detect_interior_parents();

  const MeshBase & interior_mesh() const { return *_interior_mesh; }

  MeshBase & interior_mesh() { return *_interior_mesh; }

  void set_interior_mesh(MeshBase & int_mesh) { _interior_mesh = &int_mesh; }

  const std::set<subdomain_id_type> & get_mesh_subdomains() const
  { libmesh_assert(this->is_prepared()); return _mesh_subdomains; }


#ifndef LIBMESH_ENABLE_DEPRECATED
protected:
#endif
  std::unique_ptr<BoundaryInfo> boundary_info;


protected:
  void post_dofobject_moves(MeshBase && other_mesh);

  void copy_cached_data (const MeshBase & other_mesh);

  virtual bool subclass_locally_equals (const MeshBase & other_mesh) const = 0;

  bool nodes_and_elements_equal(const MeshBase & other_mesh) const;

  unsigned int & set_n_partitions ()
  { return _n_parts; }

  unsigned int _n_parts;

  ElemMappingType _default_mapping_type;

  unsigned char _default_mapping_data;

  bool _is_prepared;

  mutable std::unique_ptr<PointLocatorBase> _point_locator;

  bool _count_lower_dim_elems_in_point_locator;

  std::unique_ptr<Partitioner> _partitioner;

#ifdef LIBMESH_ENABLE_UNIQUE_ID

  unique_id_type _next_unique_id;
#endif

  MeshBase *_interior_mesh;

  bool _skip_noncritical_partitioning;

  bool _skip_all_partitioning;

  bool _skip_renumber_nodes_and_elements;

  bool _skip_find_neighbors;

  bool _allow_remote_element_removal;

  std::map<subdomain_id_type, std::string> _block_id_to_name;

  std::set<unsigned char> _elem_dims;

  std::set<Order> _elem_default_orders;

  Order _supported_nodal_order;

  std::set<subdomain_id_type> _mesh_subdomains;

  std::map<dof_id_type, const MeshBase::elemset_type *> _elemset_codes;
  std::map<MeshBase::elemset_type, dof_id_type> _elemset_codes_inverse_map;
  MeshBase::elemset_type _all_elemset_ids;

  unsigned char _spatial_dimension;

  std::vector<std::string> _elem_integer_names;

  std::vector<dof_id_type> _elem_integer_default_values;

  std::vector<std::string> _node_integer_names;

  std::vector<dof_id_type> _node_integer_default_values;

  void size_elem_extra_integers();

  void size_node_extra_integers();

  std::pair<std::vector<unsigned int>, std::vector<unsigned int>>
    merge_extra_integer_names(const MeshBase & other);

  std::unique_ptr<GhostingFunctor> _default_ghosting;

  std::set<GhostingFunctor *> _ghosting_functors;

  std::map<GhostingFunctor *, std::shared_ptr<GhostingFunctor> > _shared_functors;

  // Keep track of any constraint equations that are inherent to the
  // mesh, such as FE nodes whose Rational Bernstein values need to be
  // constrained in terms of values on spline control nodes.
  //
  // _constraint_rows[constrained_node][i].first.first is an
  // element (e.g. a NodeElem for a spline control node),
  // _constraint_rows[constrained_node][i].first.second is the
  // local node id of that element which is a constraining node,
  // _constraint_rows[constrained_node][i].second is that node's
  // constraint coefficient.
  constraint_rows_type _constraint_rows;

  Real _point_locator_close_to_point_tol;

  friend class Partitioner;

  friend class MeshInput<MeshBase>;

  friend class BoundaryInfo;

  friend class MeshCommunication;


#ifdef LIBMESH_ENABLE_DEPRECATED
typedef variant_filter_iterator<MeshBase::Predicate, Elem *> elem_filter_iter;

typedef variant_filter_iterator<MeshBase::Predicate,
                                Elem * const,
                                Elem * const &,
                                Elem * const *> const_elem_filter_iter;

typedef variant_filter_iterator<MeshBase::Predicate, Node *> node_filter_iter;

typedef variant_filter_iterator<MeshBase::Predicate,
                                Node * const,
                                Node * const &,
                                Node * const *> const_node_filter_iter;
#else
typedef variant_filter_iterator<MeshBase::Predicate,
                                Elem * const,
                                Elem * const &,
                                Elem * const *,
                                const Elem * const,
                                const Elem * const &,
                                const Elem * const *> elem_filter_iter;

typedef variant_filter_iterator<MeshBase::Predicate,
                                const Elem * const,
                                const Elem * const &,
                                const Elem * const *> const_elem_filter_iter;

typedef variant_filter_iterator<MeshBase::Predicate,
                                Node * const,
                                Node * const &,
                                Node * const *,
                                const Node * const,
                                const Node * const &,
                                const Node * const *> node_filter_iter;

typedef variant_filter_iterator<MeshBase::Predicate,
                                const Node * const,
                                const Node * const &,
                                const Node * const *> const_node_filter_iter;
#endif // LIBMESH_ENABLE_DEPRECATED

};











struct
MeshBase::element_iterator : MeshBase::elem_filter_iter
{
  // Templated forwarding ctor -- forwards to appropriate variant_filter_iterator ctor
  template <typename PredType, typename IterType>
  element_iterator (const IterType & d,
                    const IterType & e,
                    const PredType & p ) :
    elem_filter_iter(d,e,p) {}
};




struct
MeshBase::const_element_iterator : MeshBase::const_elem_filter_iter
{
  template <typename PredType, typename IterType>
  const_element_iterator (const IterType & d,
                          const IterType & e,
                          const PredType & p ) :
    const_elem_filter_iter(d,e,p)  {}

  const_element_iterator (const MeshBase::element_iterator & rhs) :
    const_elem_filter_iter(rhs) {}
};







struct
MeshBase::node_iterator : MeshBase::node_filter_iter
{
  template <typename PredType, typename IterType>
  node_iterator (const IterType & d,
                 const IterType & e,
                 const PredType & p ) :
    node_filter_iter(d,e,p)  {}
};




struct
MeshBase::const_node_iterator : MeshBase::const_node_filter_iter
{
  template <typename PredType, typename IterType>
  const_node_iterator (const IterType & d,
                       const IterType & e,
                       const PredType & p ) :
    const_node_filter_iter(d,e,p)  {}

  const_node_iterator (const MeshBase::node_iterator & rhs) :
    const_node_filter_iter(rhs) {}
};


template <typename T>
inline
unsigned int MeshBase::add_elem_datum(const std::string & name,
                                      bool allocate_data,
                                      const T * default_value)
{
  const std::size_t old_size = _elem_integer_names.size();

  unsigned int n_more_integers = (sizeof(T)-1)/sizeof(dof_id_type);
  std::vector<dof_id_type> int_data(n_more_integers+1, DofObject::invalid_id);
  if (default_value)
    std::memcpy(int_data.data(), default_value, sizeof(T));

  unsigned int start_idx = this->add_elem_integer(name, false, int_data[0]);
  for (unsigned int i=0; i != n_more_integers; ++i)
    this->add_elem_integer(name+"__"+std::to_string(i), false, int_data[i+1]);

  if (allocate_data && old_size != _elem_integer_names.size())
    this->size_elem_extra_integers();

  return start_idx;
}


template <typename T>
inline
std::vector<unsigned int> MeshBase::add_elem_data(const std::vector<std::string> & names,
                                                  bool allocate_data,
                                                  const std::vector<T> * default_values)
{
  libmesh_assert(!default_values || default_values->size() == names.size());

  std::vector<unsigned int> returnval(names.size());

  const std::size_t old_size = _elem_integer_names.size();

  for (auto i : index_range(names))
    returnval[i] =
      this->add_elem_datum<T>(names[i], false,
                              default_values ?
                              (*default_values)[i] : nullptr);

  if (allocate_data && old_size != _elem_integer_names.size())
    this->size_elem_extra_integers();

  return returnval;
}


template <typename T>
inline
unsigned int MeshBase::add_node_datum(const std::string & name,
                                      bool allocate_data,
                                      const T * default_value)
{
  const std::size_t old_size = _node_integer_names.size();

  unsigned int n_more_integers = (sizeof(T)-1)/sizeof(dof_id_type);
  std::vector<dof_id_type> int_data(n_more_integers+1, DofObject::invalid_id);
  if (default_value)
    std::memcpy(int_data.data(), default_value, sizeof(T));

  unsigned int start_idx = this->add_node_integer(name, false, int_data[0]);
  for (unsigned int i=0; i != n_more_integers; ++i)
    this->add_node_integer(name+"__"+std::to_string(i), false, int_data[i+1]);

  if (allocate_data && old_size != _node_integer_names.size())
    this->size_node_extra_integers();

  return start_idx;
}


template <typename T>
inline
std::vector<unsigned int> MeshBase::add_node_data(const std::vector<std::string> & names,
                                                  bool allocate_data,
                                                  const std::vector<T> * default_values)
{
  libmesh_assert(!default_values || default_values->size() == names.size());

  std::vector<unsigned int> returnval(names.size());

  const std::size_t old_size = _node_integer_names.size();

  for (auto i : index_range(names))
    returnval[i] =
      this->add_node_datum<T>(names[i], false,
                              default_values ?
                              (*default_values)[i] : nullptr);

  if (allocate_data && old_size != _node_integer_names.size())
    this->size_node_extra_integers();

  return returnval;
}



} // namespace libMesh

#endif // LIBMESH_MESH_BASE_H