LCOV - code coverage report
Current view: top level - include/mesh - mesh_base.h (source / functions) Hit Total Coverage
Test: libMesh/libmesh: #4417 (f0ff5e) with base 9bbd75 Lines: 147 162 90.7 %
Date: 2026-11-16 16:30:47 Functions: 126 237 53.2 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : // The libMesh Finite Element Library.
       2             : // Copyright (C) 2002-2026 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
       3             : 
       4             : // This library is free software; you can redistribute it and/or
       5             : // modify it under the terms of the GNU Lesser General Public
       6             : // License as published by the Free Software Foundation; either
       7             : // version 2.1 of the License, or (at your option) any later version.
       8             : 
       9             : // This library is distributed in the hope that it will be useful,
      10             : // but WITHOUT ANY WARRANTY; without even the implied warranty of
      11             : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      12             : // Lesser General Public License for more details.
      13             : 
      14             : // You should have received a copy of the GNU Lesser General Public
      15             : // License along with this library; if not, write to the Free Software
      16             : // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
      17             : 
      18             : 
      19             : 
      20             : #ifndef LIBMESH_MESH_BASE_H
      21             : #define LIBMESH_MESH_BASE_H
      22             : 
      23             : // Local Includes
      24             : #include "libmesh/dof_object.h" // for invalid_processor_id
      25             : #include "libmesh/enum_order.h"
      26             : #include "libmesh/int_range.h"
      27             : #include "libmesh/libmesh_common.h"
      28             : #include "libmesh/multi_predicates.h"
      29             : #include "libmesh/point_locator_base.h"
      30             : #include "libmesh/variant_filter_iterator.h"
      31             : #include "libmesh/parallel_object.h"
      32             : #include "libmesh/simple_range.h"
      33             : 
      34             : // C++ Includes
      35             : #include <cstddef>
      36             : #include <string>
      37             : #include <memory>
      38             : 
      39             : #include "libmesh/vector_value.h"
      40             : 
      41             : namespace libMesh
      42             : {
      43             : // Forward declarations
      44             : class BoundaryInfo;
      45             : class Elem;
      46             : class GhostingFunctor;
      47             : class Node;
      48             : class Point;
      49             : class Partitioner;
      50             : class PeriodicBoundary;
      51             : class PeriodicBoundaries;
      52             : 
      53             : template <typename T>
      54             : class SparseMatrix;
      55             : 
      56             : enum ElemType : int;
      57             : enum ElemMappingType : unsigned char;
      58             : 
      59             : template <class MT>
      60             : class MeshInput;
      61             : 
      62             : template <typename iterator_type, typename object_type>
      63             : class StoredRange;
      64             : 
      65             : /**
      66             :  * This is the \p MeshBase class. This class provides all the data necessary
      67             :  * to describe a geometric entity.  It allows for the description of a
      68             :  * \p dim dimensional object that lives in \p LIBMESH_DIM-dimensional space.
      69             :  * \par
      70             :  * A mesh is made of nodes and elements, and this class provides data
      71             :  * structures to store and access both.  A mesh may be partitioned into a
      72             :  * number of subdomains, and this class provides that functionality.
      73             :  * Furthermore, this class provides functions for reading and writing a
      74             :  * mesh to disk in various formats.
      75             :  *
      76             :  * \author Benjamin S. Kirk
      77             :  * \date 2002
      78             :  * \brief Base class for Mesh.
      79             :  */
      80             : class MeshBase : public ParallelObject
      81             : {
      82             : public:
      83             : 
      84             :   /**
      85             :    * Constructor.  Takes \p dim, the dimension of the mesh.
      86             :    * The mesh dimension can be changed (and may automatically be
      87             :    * changed by mesh generation/loading) later.
      88             :    */
      89             :   MeshBase (const Parallel::Communicator & comm_in,
      90             :             unsigned char dim=1);
      91             : 
      92             :   /**
      93             :    * Copy-constructor.
      94             :    */
      95             :   MeshBase (const MeshBase & other_mesh);
      96             : 
      97             :   /**
      98             :    * Move-constructor - deleted because after a theoretical move-construction
      99             :    * and then destruction of the moved-from object, the moved \p BoundaryInfo
     100             :    * would hold an invalid reference to the moved-from mesh
     101             :    */
     102             :   MeshBase(MeshBase &&) = delete;
     103             : 
     104             :   /**
     105             :    * Copy and move assignment are not allowed because MeshBase
     106             :    * subclasses manually manage memory (Elems and Nodes) and therefore
     107             :    * the default versions of these operators would leak memory.  Since
     108             :    * we don't want to maintain non-default copy and move assignment
     109             :    * operators at this time, the safest and most self-documenting
     110             :    * approach is to delete them.
     111             :    *
     112             :    * If you need to copy a Mesh, use the clone() method.
     113             :    */
     114             :   MeshBase & operator= (const MeshBase &) = delete;
     115             :   MeshBase & operator= (MeshBase && other_mesh);
     116             : 
     117             :   /**
     118             :    * Shim to allow operator = (&&) to behave like a virtual function
     119             :    * without having to be one.
     120             :    */
     121             :   virtual MeshBase & assign(MeshBase && other_mesh) = 0;
     122             : 
     123             :   /**
     124             :    * This tests for exactly-equal data in all the senses that a
     125             :    * mathematician would care about (element connectivity, nodal
     126             :    * coordinates), but in the senses a programmer would care about it
     127             :    * allows for non-equal equivalence in some ways (we accept
     128             :    * different Elem/Node addresses in memory) but not others (we do
     129             :    * not accept different subclass types, nor even different Elem/Node
     130             :    * ids).
     131             :    *
     132             :    * Though this method is non-virtual, its implementation calls the
     133             :    * virtual function \p subclass_first_difference_from() to test for
     134             :    * equality of subclass-specific data as well.
     135             :    */
     136             :   bool operator== (const MeshBase & other_mesh) const;
     137             : 
     138             :   bool operator!= (const MeshBase & other_mesh) const
     139             :   {
     140             :     return !(*this == other_mesh);
     141             :   }
     142             : 
     143             :   /**
     144             :    * This behaves like libmesh_assert(*this == other_mesh), but gives
     145             :    * a more useful accounting of the first difference found, if the
     146             :    * assertion fails.
     147             :    */
     148             :   void assert_equal_to (const MeshBase & other_mesh,
     149             :                         std::string_view failure_context) const;
     150             : 
     151             :   /**
     152             :    * This behaves the same as operator==, but only for the local and
     153             :    * ghosted aspects of the mesh; i.e. operator== is true iff local
     154             :    * equality is true on every rank.
     155             :    */
     156             :   bool locally_equals (const MeshBase & other_mesh) const;
     157             : 
     158             :   /**
     159             :    * Virtual "copy constructor".  The copy will be of the same
     160             :    * subclass as \p this, and will satisfy "copy == this" when it is
     161             :    * created.
     162             :    */
     163             :   virtual std::unique_ptr<MeshBase> clone() const = 0;
     164             : 
     165             :   /**
     166             :    * Destructor.
     167             :    */
     168             :   virtual ~MeshBase ();
     169             : 
     170             :   /**
     171             :    * A partitioner to use at each partitioning
     172             :    */
     173      626177 :   virtual std::unique_ptr<Partitioner> & partitioner() { return _partitioner; }
     174             : 
     175             :   /**
     176             :    * The information about boundary ids on the mesh
     177             :    */
     178      780951 :   const BoundaryInfo & get_boundary_info() const { return *boundary_info; }
     179             : 
     180             :   /**
     181             :    * Writable information about boundary ids on the mesh
     182             :    */
     183     1386425 :   BoundaryInfo & get_boundary_info() { return *boundary_info; }
     184             : 
     185             :   /**
     186             :    * Deletes all the element and node data that is currently stored.
     187             :    *
     188             :    * elem and node extra_integer data is nevertheless *retained* here,
     189             :    * for better compatibility between that feature and older code's
     190             :    * use of MeshBase::clear()
     191             :    */
     192             :   virtual void clear ();
     193             : 
     194             :   /**
     195             :    * Deletes all the element data that is currently stored.
     196             :    *
     197             :    * No Node is removed from the mesh, however even NodeElem elements
     198             :    * are deleted, so the remaining Nodes will be considered "unused"
     199             :    * and cleared unless they are reconnected to new elements before
     200             :    * the next preparation step.
     201             :    *
     202             :    * This does not affect BoundaryInfo data; any boundary information
     203             :    * associated elements should already be cleared.
     204             :    */
     205             :   virtual void clear_elems () = 0;
     206             : 
     207             :   /**
     208             :    * \returns \p true if the mesh is marked as having undergone all of
     209             :    * the preparation done in a call to \p prepare_for_use, \p false
     210             :    * otherwise.
     211             :    */
     212             :   bool is_prepared () const;
     213             : 
     214             :   /**
     215             :    * \returns the \p Preparation structure with details about in what
     216             :    * ways \p this mesh is currently prepared or unprepared.  This
     217             :    * structure may change in the future when cache designs change.
     218             :    */
     219             :   struct Preparation;
     220             : 
     221        8184 :   Preparation preparation () const
     222      113129 :   { return _preparation; }
     223             : 
     224             : #ifdef LIBMESH_ENABLE_DEPRECATED
     225             :   /**
     226             :    * Tells this we have done some operation where we should no longer
     227             :    * consider ourself prepared.  This is a very coarse setting; it is
     228             :    * generally more efficient to mark finer-grained settings instead.
     229             :    *
     230             :    * This method name is now deprecated, in part to match the less
     231             :    * awkward unset_has_ names of the more fine-grained methods, in
     232             :    * part as a way to prompt older user codes to use the more
     233             :    * fine-grained methods where they can, to speed up the
     234             :    * complete_preparation() calls afterward.
     235             :    */
     236             :   void set_isnt_prepared()
     237             :   { libmesh_deprecated(); _preparation = false; }
     238             : #endif // LIBMESH_ENABLE_DEPRECATED
     239             : 
     240             :   /**
     241             :    * Tells this we have done some operation where we should no longer
     242             :    * consider ourself prepared.  This is a very coarse setting; it is
     243             :    * generally more efficient to mark finer-grained settings instead.
     244             :    */
     245             :   void unset_is_prepared();
     246             : 
     247             :   /**
     248             :    * Tells this we have done some operation creating unpartitioned
     249             :    * elements.
     250             :    *
     251             :    * User code which adds elements to this mesh must either partition
     252             :    * them too or call this method.
     253             :    */
     254           0 :   void unset_is_partitioned()
     255           0 :   { _preparation.is_partitioned = false; }
     256             : 
     257             :   /**
     258             :    * Tells this we have done some operation (e.g. adding objects to a
     259             :    * distributed mesh on one processor only) which can lose
     260             :    * synchronization of id counts.
     261             :    *
     262             :    * User code which does distributed additions of nodes or elements
     263             :    * must call either this method or \p update_parallel_id_counts().
     264             :    */
     265             :   void unset_has_synched_id_counts()
     266             :   { _preparation.has_synched_id_counts = false; }
     267             : 
     268             :   /**
     269             :    * Tells this we have done some operation (e.g. adding elements
     270             :    * without setting their neighbor pointers, or adding disjoint
     271             :    * neighbor boundary pairs) which requires neighbor pointers to be
     272             :    * determined later.
     273             :    *
     274             :    * User code which adds new elements to this mesh must call this
     275             :    * function or manually set neighbor pointer from and to those
     276             :    * elements.
     277             :    */
     278          16 :   void unset_has_neighbor_ptrs()
     279        4708 :   { _preparation.has_neighbor_ptrs = false; }
     280             : 
     281             :   /**
     282             :    * Tells this we have done some operation (e.g. adding elements with
     283             :    * a new dimension or subdomain value) which may invalidate cached
     284             :    * summaries of element data.
     285             :    *
     286             :    * User code which adds new elements to this mesh must call this
     287             :    * function.
     288             :    */
     289          22 :   void unset_has_cached_elem_data()
     290      309489 :   { _preparation.has_cached_elem_data = false; }
     291             : 
     292             :   /**
     293             :    * Tells this we have done some operation (e.g. refining elements
     294             :    * with interior parents) which requires interior parent pointers to
     295             :    * be found later.
     296             :    *
     297             :    * Most user code will not need to call this method; any user code
     298             :    * that manipulates interior parents or their boundary elements may
     299             :    * be an exception.
     300             :    */
     301             :   void unset_has_interior_parent_ptrs()
     302             :   { _preparation.has_interior_parent_ptrs = false; }
     303             : 
     304             :   /**
     305             :    * Tells this we have done some operation (e.g. repartitioning)
     306             :    * which may have left elements as ghosted which on a distributed
     307             :    * mesh should be remote.
     308             :    *
     309             :    * User code should probably never need to use this; we can set it
     310             :    * in Partitioner.  Any user code which manually repartitions
     311             :    * elements on distributed meshes may need to call this manually, in
     312             :    * addition to manually communicating elements with newly-created
     313             :    * ghosting requirements.
     314             :    */
     315           0 :   void unset_has_removed_remote_elements()
     316           0 :   { _preparation.has_removed_remote_elements = false; }
     317             : 
     318             :   /**
     319             :    * Tells this we have done some operation (e.g. coarsening)
     320             :    * which may have left orphaned nodes in need of removal.
     321             :    *
     322             :    * Most user code should probably never need to use this; we can set
     323             :    * it in MeshRefinement.  User code which deletes elements without
     324             :    * carefully deleting orphaned nodes should call this manually.
     325             :    */
     326           0 :   void unset_has_removed_orphaned_nodes()
     327           0 :   { _preparation.has_removed_orphaned_nodes = false; }
     328             : 
     329             :   /**
     330             :    * Tells this we have done some operation (e.g. adding or removing
     331             :    * elements) which may require a reinit() of custom ghosting
     332             :    * functors.
     333             :    *
     334             :    * User code which adds or removes elements should call this method.
     335             :    * User code which moves nodes ... should probably call this method,
     336             :    * in case ghosting functors depending on position exist?
     337             :    */
     338          94 :   void unset_has_reinit_ghosting_functors()
     339        3337 :   { _preparation.has_reinit_ghosting_functors = false; }
     340             : 
     341             :   /**
     342             :    * Tells this we have done some operation which may have invalidated
     343             :    * our cached boundary id sets.
     344             :    *
     345             :    * User code which removes elements, or which adds or removes
     346             :    * boundary entries, should call this method.
     347             :    */
     348           2 :   void unset_has_boundary_id_sets()
     349        3245 :   { _preparation.has_boundary_id_sets = false; }
     350             : 
     351             :   /**
     352             :    * Tells this we have done some operation which may have left the
     353             :    * subdomain id to name map inconsistent across processors.
     354             :    *
     355             :    * User code which adds or changes subdomain names should call this
     356             :    * method.
     357             :    */
     358       77636 :   void unset_has_synched_subdomain_name_map()
     359     1446263 :   { _preparation.has_synched_subdomain_name_map = false; }
     360             : 
     361             :   /**
     362             :    * \returns \p true if all elements and nodes of the mesh
     363             :    * exist on the current processor, \p false otherwise
     364             :    */
     365      889633 :   virtual bool is_serial () const
     366      889633 :   { return true; }
     367             : 
     368             :   /**
     369             :    * \returns \p true if all elements and nodes of the mesh
     370             :    * exist on the processor 0, \p false otherwise
     371             :    */
     372        1813 :   virtual bool is_serial_on_zero () const
     373        1813 :   { return true; }
     374             : 
     375             :   /**
     376             :    * Asserts that not all elements and nodes of the mesh necessarily
     377             :    * exist on the current processor.  Only valid to call on classes
     378             :    * which can be created in a distributed form.
     379             :    */
     380           0 :   virtual void set_distributed ()
     381           0 :   { libmesh_error(); }
     382             : 
     383             :   /**
     384             :    * \returns \p true if new elements and nodes can and should be
     385             :    * created in synchronization on all processors, \p false otherwise
     386             :    */
     387     3023220 :   virtual bool is_replicated () const
     388     3023220 :   { return true; }
     389             : 
     390             :   /**
     391             :    * Gathers all elements and nodes of the mesh onto
     392             :    * every processor
     393             :    */
     394           2 :   virtual void allgather () {}
     395             : 
     396             :   /**
     397             :    * Gathers all elements and nodes of the mesh onto
     398             :    * processor zero
     399             :    */
     400           0 :   virtual void gather_to_zero() {}
     401             : 
     402             :   /**
     403             :    * When supported, deletes all nonlocal elements of the mesh
     404             :    * except for "ghosts" which touch a local element, and deletes
     405             :    * all nodes which are not part of a local or ghost element
     406             :    */
     407       85837 :   virtual void delete_remote_elements () {
     408       85837 :     _preparation.has_removed_remote_elements = true;
     409       85837 :   }
     410             : 
     411             :   /**
     412             :    * Loops over ghosting functors and calls mesh_reinit()
     413             :    */
     414             :   void reinit_ghosting_functors();
     415             : 
     416             :   /**
     417             :    * \returns The logical dimension of the mesh; i.e. the manifold
     418             :    * dimension of the elements in the mesh.  When we have
     419             :    * multi-dimensional meshes (e.g. hexes and quads in the same mesh)
     420             :    * then this will return the largest such dimension.
     421             :    */
     422             :   unsigned int mesh_dimension () const;
     423             : 
     424             :   /**
     425             :    * Resets the logical dimension of the mesh. If the mesh has
     426             :    * elements of multiple dimensions, this should be set to the largest
     427             :    * dimension. E.g. if the mesh has 1D and 2D elements, this should
     428             :    * be set to 2. If the mesh has 2D and 3D elements, this should be
     429             :    * set to 3.
     430             :    */
     431       14371 :   void set_mesh_dimension (unsigned char d)
     432      443639 :   { _elem_dims.clear(); _elem_dims.insert(d); }
     433             : 
     434             :   /**
     435             :    * \returns A const reference to a std::set of element dimensions
     436             :    * present in the mesh.
     437             :    */
     438             :   const std::set<unsigned char> & elem_dimensions() const;
     439             : 
     440             :   /**
     441             :    * \returns A const reference to a std::set of element default
     442             :    * orders present in the mesh.
     443             :    */
     444             :   const std::set<Order> & elem_default_orders() const;
     445             : 
     446             :   /**
     447             :    * \returns The smallest supported_nodal_order() of any element
     448             :    * present in the mesh, which is thus the maximum supported nodal
     449             :    * order on the mesh as a whole.
     450             :    */
     451             :   Order supported_nodal_order() const;
     452             : 
     453             :   /**
     454             :    * Most of the time you should not need to call this, as the element
     455             :    * dimensions will be set automatically by a call to cache_elem_data(),
     456             :    * therefore only call this if you know what you're doing.
     457             :    *
     458             :    * In some specialized situations, for example when adding a single
     459             :    * Elem on all procs, it can be faster to skip calling cache_elem_data()
     460             :    * and simply specify the element dimensions manually, which is why this
     461             :    * setter exists.
     462             :    */
     463             :   void set_elem_dimensions(std::set<unsigned char> elem_dims);
     464             : 
     465             :   /**
     466             :    * Typedef for the "set" container used to store elemset ids. The
     467             :    * main requirements are that the entries be sorted and unique, so
     468             :    * std::set works for this, but there may be more efficient
     469             :    * alternatives.
     470             :    */
     471             :   typedef std::set<elemset_id_type> elemset_type;
     472             : 
     473             :   /**
     474             :    * Tabulate a user-defined "code" for elements which belong to the element sets
     475             :    * specified in \p id_set. For example, suppose that we have two elemsets A and
     476             :    * B with the following Elem ids:
     477             :    * Elemset A = {1, 3}
     478             :    * Elemset B = {2, 3}
     479             :    *
     480             :    * This implies the following mapping from elem id to elemset id:
     481             :    * Elem 1 -> {A}
     482             :    * Elem 2 -> {B}
     483             :    * Elem 3 -> {A,B}
     484             :    *
     485             :    * In this case, we would need to tabulate three different elemset codes, e.g.:
     486             :    * 0 -> {A}
     487             :    * 1 -> {B}
     488             :    * 2 -> {A,B}
     489             :    *
     490             :    * Also sets up the inverse mapping, so that if one knows all the
     491             :    * element sets an Elem belongs to, one can look up the
     492             :    * corresponding elemset code.
     493             :    */
     494             :   void add_elemset_code(dof_id_type code, MeshBase::elemset_type id_set);
     495             : 
     496             :   /**
     497             :    * Returns the number of unique elemset ids which have been added
     498             :    * via add_elemset_code(), which is the size of the _all_elemset_ids
     499             :    * set.
     500             :    */
     501             :   unsigned int n_elemsets() const;
     502             : 
     503             :   /**
     504             :    * Look up the element sets for a given elemset code and
     505             :    * vice-versa. The elemset must have been previously stored by
     506             :    * calling add_elemset_code(). If no such code/set is found, returns
     507             :    * the empty set or DofObject::invalid_id, respectively.
     508             :    */
     509             :   void get_elemsets(dof_id_type elemset_code, MeshBase::elemset_type & id_set_to_fill) const;
     510             :   dof_id_type get_elemset_code(const MeshBase::elemset_type & id_set) const;
     511             : 
     512             :   /**
     513             :    * Return a vector of all elemset codes defined on the mesh. We get
     514             :    * this by looping over the _elemset_codes map.
     515             :    */
     516             :   std::vector<dof_id_type> get_elemset_codes() const;
     517             : 
     518             :   /**
     519             :    * Replace elemset code "old_code" with "new_code". This function loops over
     520             :    * all elements and changes the extra integer corresponding to the "elemset_code"
     521             :    * label, and updates the _elemset_codes and _elemset_codes_inverse_map members.
     522             :    * Does not change the elemset ids of any of the sets.
     523             :    */
     524             :   void change_elemset_code(dof_id_type old_code, dof_id_type new_code);
     525             : 
     526             :   /**
     527             :    * Replace elemset id "old_id" with "new_id". Does not change any of the
     528             :    * elemset codes, so does not need to loop over the elements themselves.
     529             :    */
     530             :   void change_elemset_id(elemset_id_type old_id, elemset_id_type new_id);
     531             : 
     532             :   /**
     533             :    * \returns The "spatial dimension" of the mesh.
     534             :    *
     535             :    * The spatial dimension is defined as:
     536             :    *
     537             :    *   1 - for an exactly x-aligned mesh of 1D elements
     538             :    *   2 - for an exactly x-y planar mesh of 2D elements
     539             :    *   3 - otherwise
     540             :    *
     541             :    * No tolerance checks are performed to determine whether the Mesh
     542             :    * is x-aligned or x-y planar, only strict equality with zero in the
     543             :    * higher dimensions is checked.  Also, x-z and y-z planar meshes are
     544             :    * considered to have spatial dimension == 3.
     545             :    *
     546             :    * The spatial dimension is updated during mesh preparation based
     547             :    * on the dimensions of the various elements present in the Mesh,
     548             :    * but is *never automatically decreased*.
     549             :    *
     550             :    * For example, if the user calls set_spatial_dimension(2) and then
     551             :    * later inserts 3D elements into the mesh,
     552             :    * Mesh::spatial_dimension() will return 3 after the next call to
     553             :    * prepare_for_use() or complete_preparation().  On the other hand,
     554             :    * if the user calls set_spatial_dimension(3) and then inserts only
     555             :    * x-aligned 1D elements into the Mesh, mesh.spatial_dimension()
     556             :    * will remain 3.
     557             :    */
     558             :   unsigned int spatial_dimension () const;
     559             : 
     560             :   /**
     561             :    * Sets the "spatial dimension" of the Mesh.  See the documentation
     562             :    * for Mesh::spatial_dimension() for more information.
     563             :    */
     564             :   void set_spatial_dimension(unsigned char d);
     565             : 
     566             :   /**
     567             :    * \returns The number of nodes in the mesh.
     568             :    *
     569             :    * This function and others must be defined in derived classes since
     570             :    * the MeshBase class has no specific storage for nodes or elements.
     571             :    * The standard \p n_nodes() function may return a cached value on
     572             :    * distributed meshes, and so can be called by any processor at any
     573             :    * time.
     574             :    */
     575             :   virtual dof_id_type n_nodes () const = 0;
     576             : 
     577             :   /**
     578             :    * \returns The number of nodes in the mesh.
     579             :    *
     580             :    * This function and others must be overridden in derived classes since
     581             :    * the MeshBase class has no specific storage for nodes or elements.
     582             :    * The \p parallel_n_nodes() function computes a parallel-synchronized
     583             :    * value on distributed meshes, and so must be called in parallel
     584             :    * only.
     585             :    */
     586             :   virtual dof_id_type parallel_n_nodes () const = 0;
     587             : 
     588             :   /**
     589             :    * \returns The number of nodes on processor \p proc.
     590             :    */
     591             :   dof_id_type n_nodes_on_proc (const processor_id_type proc) const;
     592             : 
     593             :   /**
     594             :    * \returns The number of nodes on the local processor.
     595             :    */
     596         510 :   dof_id_type n_local_nodes () const
     597     4311711 :   { return this->n_nodes_on_proc (this->processor_id()); }
     598             : 
     599             :   /**
     600             :    * \returns The number of nodes owned by no processor.
     601             :    */
     602       48440 :   dof_id_type n_unpartitioned_nodes () const
     603     4664811 :   { return this->n_nodes_on_proc (DofObject::invalid_processor_id); }
     604             : 
     605             :   /**
     606             :    * \returns A number one greater than the maximum node id in the
     607             :    * mesh. A more apt name for this method would be end_node_id
     608             :    */
     609             :   virtual dof_id_type max_node_id () const = 0;
     610             : 
     611             : #ifdef LIBMESH_ENABLE_UNIQUE_ID
     612             :   /**
     613             :    * \returns The next unique id to be used.
     614             :    */
     615        9729 :   unique_id_type next_unique_id() const { return _next_unique_id; }
     616             : 
     617             :   /**
     618             :    * Sets the next available unique id to be used.  On a
     619             :    * ReplicatedMesh, or when adding unpartitioned objects to a
     620             :    * DistributedMesh, this must be kept in sync on all processors.
     621             :    *
     622             :    * On a DistributedMesh, other unique_id values (larger than this
     623             :    * one) may be chosen next, to allow unique_id assignment without
     624             :    * communication.
     625             :    */
     626             :   virtual void set_next_unique_id(unique_id_type id) = 0;
     627             : #endif
     628             : 
     629             :   /**
     630             :    * Reserves space for a known number of nodes.
     631             :    *
     632             :    * \note This method may or may not do anything, depending on the
     633             :    * actual \p Mesh implementation.  If you know the number of nodes
     634             :    * you will add and call this method before repeatedly calling \p
     635             :    * add_point() the implementation will be more efficient.
     636             :    */
     637             :   virtual void reserve_nodes (const dof_id_type nn) = 0;
     638             : 
     639             :   /**
     640             :    * \returns The number of elements in the mesh.
     641             :    *
     642             :    * The standard n_elem() function may return a cached value on
     643             :    * distributed meshes, and so can be called by any processor at any
     644             :    * time.
     645             :    */
     646             :   virtual dof_id_type n_elem () const = 0;
     647             : 
     648             :   /**
     649             :    * \returns The number of elements in the mesh.
     650             :    *
     651             :    * The parallel_n_elem() function computes a parallel-synchronized
     652             :    * value on distributed meshes, and so must be called in parallel
     653             :    * only.
     654             :    */
     655             :   virtual dof_id_type parallel_n_elem () const = 0;
     656             : 
     657             :   /**
     658             :    * \returns A number one greater than the maximum element id in the
     659             :    * mesh. A more apt name for this method would be end_elem_id
     660             :    */
     661             :   virtual dof_id_type max_elem_id () const = 0;
     662             : 
     663             :   /**
     664             :    * \returns A number greater than or equal to the maximum unique_id in the
     665             :    * mesh.
     666             :    */
     667             : #ifdef LIBMESH_ENABLE_UNIQUE_ID
     668             :   virtual unique_id_type parallel_max_unique_id () const = 0;
     669             : #endif
     670             : 
     671             :   /**
     672             :    * Reserves space for a known number of elements.
     673             :    *
     674             :    * \note This method may or may not do anything, depending on the
     675             :    * actual \p Mesh implementation.  If you know the number of
     676             :    * elements you will add and call this method before repeatedly
     677             :    * calling \p add_point() the implementation will be more efficient.
     678             :    */
     679             :   virtual void reserve_elem (const dof_id_type ne) = 0;
     680             : 
     681             :   /**
     682             :    * Updates parallel caches so that methods like n_elem()
     683             :    * accurately reflect changes on other processors
     684             :    */
     685             :   virtual void update_parallel_id_counts () = 0;
     686             : 
     687             :   /**
     688             :    * \returns The number of active elements in the mesh.
     689             :    *
     690             :    * Implemented in terms of active_element_iterators.
     691             :    */
     692             :   virtual dof_id_type n_active_elem () const = 0;
     693             : 
     694             :   /**
     695             :    * \returns The number of elements on processor \p proc.
     696             :    */
     697             :   dof_id_type n_elem_on_proc (const processor_id_type proc) const;
     698             : 
     699             :   /**
     700             :    * \returns The number of elements on the local processor.
     701             :    */
     702         494 :   dof_id_type n_local_elem () const
     703     4310692 :   { return this->n_elem_on_proc (this->processor_id()); }
     704             : 
     705             :   /**
     706             :    * \returns The number of elements owned by no processor.
     707             :    */
     708       66927 :   dof_id_type n_unpartitioned_elem () const
     709     5279226 :   { return this->n_elem_on_proc (DofObject::invalid_processor_id); }
     710             : 
     711             :   /**
     712             :    * \returns The number of active elements on processor \p proc.
     713             :    */
     714             :   dof_id_type n_active_elem_on_proc (const processor_id_type proc) const;
     715             : 
     716             :   /**
     717             :    * \returns The number of active elements on the local processor.
     718             :    */
     719         216 :   dof_id_type n_active_local_elem () const
     720     1678716 :   { return this->n_active_elem_on_proc (this->processor_id()); }
     721             : 
     722             :   /**
     723             :    * \returns The number of elements that will be written
     724             :    * out in certain I/O formats.
     725             :    *
     726             :    * For example, a 9-noded quadrilateral will be broken into 4 linear
     727             :    * sub-elements for plotting purposes.  Thus, for a mesh of 2 \p
     728             :    * QUAD9 elements \p n_tecplot_elem() will return 8.  Implemented in
     729             :    * terms of element_iterators.
     730             :    */
     731             :   dof_id_type n_sub_elem () const;
     732             : 
     733             :   /**
     734             :    * Same as \p n_sub_elem(), but only counts active elements.
     735             :    */
     736             :   dof_id_type n_active_sub_elem () const;
     737             : 
     738             :   /**
     739             :    * \returns A constant reference (for reading only) to the
     740             :    * \f$ i^{th} \f$ point, which should be present in this processor's
     741             :    * subset of the mesh data structure.
     742             :    */
     743             :   virtual const Point & point (const dof_id_type i) const = 0;
     744             : 
     745             :   /**
     746             :    * \returns A constant reference (for reading only) to the
     747             :    * \f$ i^{th} \f$ node, which should be present in this processor's
     748             :    * subset of the mesh data structure.
     749             :    */
     750    63859160 :   virtual const Node & node_ref (const dof_id_type i) const
     751             :   {
     752    63859160 :     return *this->node_ptr(i);
     753             :   }
     754             : 
     755             :   /**
     756             :    * \returns A reference to the \f$ i^{th} \f$ node, which should be
     757             :    * present in this processor's subset of the mesh data structure.
     758             :    */
     759   427070109 :   virtual Node & node_ref (const dof_id_type i)
     760             :   {
     761   427070109 :     return *this->node_ptr(i);
     762             :   }
     763             : 
     764             :   /**
     765             :    * \returns A pointer to the \f$ i^{th} \f$ node, which should be
     766             :    * present in this processor's subset of the mesh data structure.
     767             :    */
     768             :   virtual const Node * node_ptr (const dof_id_type i) const = 0;
     769             : 
     770             :   /**
     771             :    * \returns A writable pointer to the \f$ i^{th} \f$ node, which
     772             :    * should be present in this processor's subset of the mesh data
     773             :    * structure.
     774             :    */
     775             :   virtual Node * node_ptr (const dof_id_type i) = 0;
     776             : 
     777             :   /**
     778             :    * \returns A pointer to the \f$ i^{th} \f$ node, or \p nullptr if no such
     779             :    * node exists in this processor's mesh data structure.
     780             :    */
     781             :   virtual const Node * query_node_ptr (const dof_id_type i) const = 0;
     782             : 
     783             :   /**
     784             :    * \returns A writable pointer to the \f$ i^{th} \f$ node, or \p nullptr if
     785             :    * no such node exists in this processor's mesh data structure.
     786             :    */
     787             :   virtual Node * query_node_ptr (const dof_id_type i) = 0;
     788             : 
     789             :   /**
     790             :    * \returns A reference to the \f$ i^{th} \f$ element, which should be
     791             :    * present in this processor's subset of the mesh data structure.
     792             :    */
     793     5376327 :   virtual const Elem & elem_ref (const dof_id_type i) const
     794             :   {
     795     5376327 :     return *this->elem_ptr(i);
     796             :   }
     797             : 
     798             :   /**
     799             :    * \returns A writable reference to the \f$ i^{th} \f$ element, which
     800             :    * should be present in this processor's subset of the mesh data
     801             :    * structure.
     802             :    */
     803   314442589 :   virtual Elem & elem_ref (const dof_id_type i)
     804             :   {
     805   314442589 :     return *this->elem_ptr(i);
     806             :   }
     807             : 
     808             :   /**
     809             :    * \returns A pointer to the \f$ i^{th} \f$ element, which should be
     810             :    * present in this processor's subset of the mesh data structure.
     811             :    */
     812             :   virtual const Elem * elem_ptr (const dof_id_type i) const = 0;
     813             : 
     814             :   /**
     815             :    * \returns A writable pointer to the \f$ i^{th} \f$ element, which
     816             :    * should be present in this processor's subset of the mesh data
     817             :    * structure.
     818             :    */
     819             :   virtual Elem * elem_ptr (const dof_id_type i) = 0;
     820             : 
     821             :   /**
     822             :    * \returns A pointer to the \f$ i^{th} \f$ element, or nullptr if no
     823             :    * such element exists in this processor's mesh data structure.
     824             :    */
     825             :   virtual const Elem * query_elem_ptr (const dof_id_type i) const = 0;
     826             : 
     827             :   /**
     828             :    * \returns A writable pointer to the \f$ i^{th} \f$ element, or nullptr
     829             :    * if no such element exists in this processor's mesh data structure.
     830             :    */
     831             :   virtual Elem * query_elem_ptr (const dof_id_type i) = 0;
     832             : 
     833             :   /**
     834             :    * Add a new \p Node at \p Point \p p to the end of the vertex array,
     835             :    * with processor_id \p procid.
     836             :    * Use DofObject::invalid_processor_id (default) to add a node to all
     837             :    * processors, or this->processor_id() to add a node to the local
     838             :    * processor only.
     839             :    * If adding a node locally, passing an \p id other than
     840             :    * DofObject::invalid_id will set that specific node id.  Only
     841             :    * do this in parallel if you are manually keeping ids consistent.
     842             :    */
     843             :   virtual Node * add_point (const Point & p,
     844             :                             const dof_id_type id = DofObject::invalid_id,
     845             :                             const processor_id_type proc_id =
     846             :                             DofObject::invalid_processor_id) = 0;
     847             : 
     848             :   /**
     849             :    * Add \p Node \p n to the end of the vertex array.
     850             :    */
     851             :   virtual Node * add_node (Node * n) = 0;
     852             : 
     853             :   /**
     854             :    * Version of add_node() taking a std::unique_ptr by value. The version
     855             :    * taking a dumb pointer will eventually be deprecated in favor of this
     856             :    * version. This API is intended to indicate that ownership of the Node
     857             :    * is transferred to the Mesh when this function is called, and it should
     858             :    * play more nicely with the Node::build() API which has always returned
     859             :    * a std::unique_ptr.
     860             :    */
     861             :   virtual Node * add_node (std::unique_ptr<Node> n) = 0;
     862             : 
     863             :   /**
     864             :    * Removes the Node n from the mesh.
     865             :    */
     866             :   virtual void delete_node (Node * n) = 0;
     867             : 
     868             :   /**
     869             :    * Takes ownership of node \p n on this partition of a distributed
     870             :    * mesh, by setting n.processor_id() to this->processor_id(), as
     871             :    * well as changing n.id() and moving it in the mesh's internal
     872             :    * container to give it a new authoritative id.
     873             :    */
     874           0 :   virtual void own_node (Node &) {}
     875             : 
     876             :   /**
     877             :    * Changes the id of node \p old_id, both by changing node(old_id)->id() and
     878             :    * by moving node(old_id) in the mesh's internal container.  No element with
     879             :    * the id \p new_id should already exist.
     880             :    */
     881             :   virtual void renumber_node (dof_id_type old_id, dof_id_type new_id) = 0;
     882             : 
     883             :   /**
     884             :    * Add elem \p e to the end of the element array.
     885             :    * To add an element locally, set e->processor_id() before adding it.
     886             :    * To ensure a specific element id, call e->set_id() before adding it;
     887             :    * only do this in parallel if you are manually keeping ids consistent.
     888             :    *
     889             :    * Users should call MeshBase::complete_preparation() after elements are
     890             :    * added to and/or deleted from the mesh.
     891             :    */
     892             :   virtual Elem * add_elem (Elem * e) = 0;
     893             : 
     894             :   /**
     895             :    * Version of add_elem() taking a std::unique_ptr by value. The version
     896             :    * taking a dumb pointer will eventually be deprecated in favor of this
     897             :    * version. This API is intended to indicate that ownership of the Elem
     898             :    * is transferred to the Mesh when this function is called, and it should
     899             :    * play more nicely with the Elem::build() API which has always returned
     900             :    * a std::unique_ptr.
     901             :    */
     902             :   virtual Elem * add_elem (std::unique_ptr<Elem> e) = 0;
     903             : 
     904             :   /**
     905             :    * Insert elem \p e to the element array, preserving its id
     906             :    * and replacing/deleting any existing element with the same id.
     907             :    *
     908             :    * Users should call MeshBase::complete_preparation() after elements are
     909             :    * added to and/or deleted from the mesh.
     910             :    */
     911             :   virtual Elem * insert_elem (Elem * e) = 0;
     912             : 
     913             :   /**
     914             :    * Version of insert_elem() taking a std::unique_ptr by value. The version
     915             :    * taking a dumb pointer will eventually be deprecated in favor of this
     916             :    * version. This API is intended to indicate that ownership of the Elem
     917             :    * is transferred to the Mesh when this function is called, and it should
     918             :    * play more nicely with the Elem::build() API which has always returned
     919             :    * a std::unique_ptr.
     920             :    */
     921             :   virtual Elem * insert_elem (std::unique_ptr<Elem> e) = 0;
     922             : 
     923             :   /**
     924             :    * Removes element \p e from the mesh. This method must be
     925             :    * implemented in derived classes in such a way that it does not
     926             :    * invalidate element iterators.  Users should call
     927             :    * MeshBase::complete_preparation() after elements are added to
     928             :    * and/or deleted from the mesh.
     929             :    *
     930             :    * \note Calling this method may produce isolated nodes, i.e. nodes
     931             :    * not connected to any element.
     932             :    */
     933             :   virtual void delete_elem (Elem * e) = 0;
     934             : 
     935             :   /**
     936             :    * Changes the id of element \p old_id, both by changing elem(old_id)->id()
     937             :    * and by moving elem(old_id) in the mesh's internal container.  No element
     938             :    * with the id \p new_id should already exist.
     939             :    */
     940             :   virtual void renumber_elem (dof_id_type old_id, dof_id_type new_id) = 0;
     941             : 
     942             :   /**
     943             :    * Returns the default master space to physical space mapping basis
     944             :    * functions to be used on newly added elements.
     945             :    */
     946     1825861 :   ElemMappingType default_mapping_type () const
     947             :   {
     948    60155726 :     return _default_mapping_type;
     949             :   }
     950             : 
     951             :   /**
     952             :    * Set the default master space to physical space mapping basis
     953             :    * functions to be used on newly added elements.
     954             :    */
     955          44 :   void set_default_mapping_type (const ElemMappingType type)
     956             :   {
     957       16841 :     _default_mapping_type = type;
     958          44 :   }
     959             : 
     960             :   /**
     961             :    * Returns any default data value used by the master space to
     962             :    * physical space mapping.
     963             :    */
     964     1825861 :   unsigned char default_mapping_data () const
     965             :   {
     966    60155726 :     return _default_mapping_data;
     967             :   }
     968             : 
     969             :   /**
     970             :    * Set the default master space to physical space mapping basis
     971             :    * functions to be used on newly added elements.
     972             :    */
     973          44 :   void set_default_mapping_data (const unsigned char data)
     974             :   {
     975       16841 :     _default_mapping_data = data;
     976          44 :   }
     977             : 
     978             :   /**
     979             :    * Locate element face (edge in 2D) neighbors.  This is done with the help
     980             :    * of a \p std::map that functions like a hash table.
     981             :    * After this routine is called all the elements with a \p nullptr neighbor
     982             :    * pointer are guaranteed to be on the boundary.  Thus this routine is
     983             :    * useful for automatically determining the boundaries of the domain.
     984             :    *
     985             :    * If \p reset_remote_elements is left to false, remote neighbor
     986             :    * links are not reset and searched for in the local mesh.
     987             :    *
     988             :    * If \p reset_current_list is left as true, then any existing links
     989             :    * will be reset before initiating the algorithm, while honoring the
     990             :    * value of the \p reset_remote_elements flag.
     991             :    *
     992             :    * If \p assert_valid is left as true, then in dbg mode extensive
     993             :    * consistency checking is performed before returning.
     994             :    *
     995             :    * If \p check_non_remote is set to false, then only sides which
     996             :    * currently have remote neighbor_ptr links are checked for possible
     997             :    * semilocal side-neighbors.  This is intended to handle a corner case
     998             :    * where ancestor neighbors are redistributed to a processor only by
     999             :    * other processors who do not see that neighbor link.
    1000             :    */
    1001             :   virtual void find_neighbors (const bool reset_remote_elements = false,
    1002             :                                const bool reset_current_list    = true,
    1003             :                                const bool assert_valid          = true,
    1004             :                                const bool check_non_remote      = true) = 0;
    1005             : 
    1006             :   /**
    1007             :    * Removes any orphaned nodes, nodes not connected to any elements.
    1008             :    * Typically done automatically in a preparation step
    1009             :    */
    1010             :   void remove_orphaned_nodes ();
    1011             : 
    1012             :   /**
    1013             :    * After partitioning a mesh it is useful to renumber the nodes and elements
    1014             :    * so that they lie in contiguous blocks on the processors.  This method
    1015             :    * does just that.
    1016             :    */
    1017             :   virtual void renumber_nodes_and_elements () = 0;
    1018             : 
    1019             :   /**
    1020             :    * There is no reason for a user to ever call this function.
    1021             :    *
    1022             :    * This function restores a previously broken element/node numbering such that
    1023             :    * \p mesh.node_ref(n).id() == n.
    1024             :    */
    1025             :   virtual void fix_broken_node_and_element_numbering () = 0;
    1026             : 
    1027             : 
    1028             : #ifdef LIBMESH_ENABLE_AMR
    1029             :   /**
    1030             :    * Delete subactive (i.e. children of coarsened) elements.
    1031             :    * This removes all elements descended from currently active
    1032             :    * elements in the mesh.
    1033             :    */
    1034             :   virtual bool contract () = 0;
    1035             : #endif
    1036             : 
    1037             :   /**
    1038             :    * Register an integer datum (of type dof_id_type) to be added to
    1039             :    * each element in the mesh.
    1040             :    *
    1041             :    * If the mesh already has elements, data by default is allocated in
    1042             :    * each of them.  This may be expensive to do repeatedly; use
    1043             :    * add_elem_integers instead.  Alternatively, the \p allocate_data
    1044             :    * option can be manually set to false, but if this is done then a
    1045             :    * manual call to \p size_elem_extra_integers() will need to be done
    1046             :    * before the new space is usable.
    1047             :    *
    1048             :    * Newly allocated values for the new datum will be initialized to
    1049             :    * \p default_value
    1050             :    *
    1051             :    * \returns The index number for the new datum, or for the existing
    1052             :    * datum if one by the same name has already been added.
    1053             :    */
    1054             :   unsigned int add_elem_integer(std::string name,
    1055             :                                 bool allocate_data = true,
    1056             :                                 dof_id_type default_value = DofObject::invalid_id);
    1057             : 
    1058             :   /**
    1059             :    * Register integer data (of type dof_id_type) to be added to
    1060             :    * each element in the mesh, one string name for each new integer.
    1061             :    *
    1062             :    * If the mesh already has elements, data by default is allocated in
    1063             :    * each of them.
    1064             :    *
    1065             :    * Newly allocated values for the new datum with name \p names[i]
    1066             :    * will be initialized to \p default_values[i], or to
    1067             :    * DofObject::invalid_id if \p default_values is null.
    1068             :    *
    1069             :    * \returns The index numbers for the new data, and/or for existing
    1070             :    * data if data by some of the same names has already been added.
    1071             :    */
    1072             :   std::vector<unsigned int> add_elem_integers(const std::vector<std::string> & names,
    1073             :                                               bool allocate_data = true,
    1074             :                                               const std::vector<dof_id_type> * default_values = nullptr);
    1075             : 
    1076             :   /*
    1077             :    * \returns The index number for the named extra element integer
    1078             :    * datum, which must have already been added.
    1079             :    */
    1080             :   unsigned int get_elem_integer_index(std::string_view name) const;
    1081             : 
    1082             :   /*
    1083             :    * \returns Whether or not the mesh has an element integer with its name.
    1084             :    */
    1085             :   bool has_elem_integer(std::string_view name) const;
    1086             : 
    1087             :   /*
    1088             :    * \returns The name for the indexed extra element integer
    1089             :    * datum, which must have already been added.
    1090             :    */
    1091          19 :   const std::string & get_elem_integer_name(unsigned int i) const
    1092          38 :   { return _elem_integer_names[i]; }
    1093             : 
    1094             :   /*
    1095             :    * \returns The number of extra element integers for which space is
    1096             :    * being reserved on this mesh.
    1097             :    *
    1098             :    * If non-integer data has been associated, each datum of type T
    1099             :    * counts for sizeof(T)/sizeof(dof_id_type) times in the return
    1100             :    * value.
    1101             :    */
    1102        1215 :   unsigned int n_elem_integers() const { return _elem_integer_names.size(); }
    1103             : 
    1104             :   /**
    1105             :    * Register a datum (of type T) to be added to each element in the
    1106             :    * mesh.
    1107             :    *
    1108             :    * If the mesh already has elements, data by default is allocated in
    1109             :    * each of them.  This may be expensive to do repeatedly; use
    1110             :    * add_elem_data instead.  Alternatively, the \p allocate_data
    1111             :    * option can be manually set to false, but if this is done then a
    1112             :    * manual call to \p size_elem_extra_integers() will need to be done
    1113             :    * before the new space is usable.
    1114             :    *
    1115             :    * Newly allocated values for the new datum will be initialized to
    1116             :    * \p *default_value if \p default_value is not null, or to
    1117             :    * meaningless memcpy output otherwise.
    1118             :    *
    1119             :    * \returns The index numbers for the new data, and/or for existing
    1120             :    * data if data by some of the same names has already been added.
    1121             :    *
    1122             :    * If type T is larger than dof_id_type, its data will end up
    1123             :    * spanning multiple index values, but will be queried with the
    1124             :    * starting index number.
    1125             :    *
    1126             :    * No type checking is done with this function!  If you add data of
    1127             :    * type T, don't try to access it with a call specifying type U.
    1128             :    */
    1129             :   template <typename T>
    1130             :   unsigned int add_elem_datum(const std::string & name,
    1131             :                               bool allocate_data = true,
    1132             :                               const T * default_value = nullptr);
    1133             : 
    1134             :   /**
    1135             :    * Register data (of type T) to be added to each element in the
    1136             :    * mesh.
    1137             :    *
    1138             :    * If the mesh already has elements, data is allocated in each.
    1139             :    *
    1140             :    * Newly allocated values for the new datum with name \p names[i]
    1141             :    * will be initialized to \p default_values[i], or to
    1142             :    * meaningless memcpy output if \p default_values is null.
    1143             :    *
    1144             :    * \returns The starting index number for the new data, or for the
    1145             :    * existing data if one by the same name has already been added.
    1146             :    *
    1147             :    * If type T is larger than dof_id_type, each datum will end up
    1148             :    * spanning multiple index values, but will be queried with the
    1149             :    * starting index number.
    1150             :    *
    1151             :    * No type checking is done with this function!  If you add data of
    1152             :    * type T, don't try to access it with a call specifying type U.
    1153             :    */
    1154             :   template <typename T>
    1155             :   std::vector<unsigned int> add_elem_data(const std::vector<std::string> & names,
    1156             :                                           bool allocate_data = true,
    1157             :                                           const std::vector<T> * default_values = nullptr);
    1158             : 
    1159             :   /**
    1160             :    * Register an integer datum (of type dof_id_type) to be added to
    1161             :    * each node in the mesh.
    1162             :    *
    1163             :    * If the mesh already has nodes, data by default is allocated in
    1164             :    * each of them.  This may be expensive to do repeatedly; use
    1165             :    * add_node_integers instead.  Alternatively, the \p allocate_data
    1166             :    * option can be manually set to false, but if this is done then a
    1167             :    * manual call to \p size_node_extra_integers() will need to be done
    1168             :    * before the new space is usable.
    1169             :    *
    1170             :    * Newly allocated values for the new datum will be initialized to
    1171             :    * \p default_value
    1172             :    *
    1173             :    * \returns The index number for the new datum, or for the existing
    1174             :    * datum if one by the same name has already been added.
    1175             :    */
    1176             :   unsigned int add_node_integer(std::string name,
    1177             :                                 bool allocate_data = true,
    1178             :                                 dof_id_type default_value = DofObject::invalid_id);
    1179             : 
    1180             :   /**
    1181             :    * Register integer data (of type dof_id_type) to be added to
    1182             :    * each node in the mesh.
    1183             :    *
    1184             :    * If the mesh already has nodes, data by default is allocated in
    1185             :    * each.
    1186             :    *
    1187             :    * Newly allocated values for the new datum with name \p names[i]
    1188             :    * will be initialized to \p default_values[i], or to
    1189             :    * DofObject::invalid_id if \p default_values is null.
    1190             :    *
    1191             :    * \returns The index numbers for the new data, and/or for existing
    1192             :    * data if data by some of the same names has already been added.
    1193             :    */
    1194             :   std::vector<unsigned int> add_node_integers(const std::vector<std::string> & names,
    1195             :                                               bool allocate_data = true,
    1196             :                                               const std::vector<dof_id_type> * default_values = nullptr);
    1197             : 
    1198             :   /*
    1199             :    * \returns The index number for the named extra node integer
    1200             :    * datum, which must have already been added.
    1201             :    */
    1202             :   unsigned int get_node_integer_index(std::string_view name) const;
    1203             : 
    1204             :   /*
    1205             :    * \returns Whether or not the mesh has a node integer with its name.
    1206             :    */
    1207             :   bool has_node_integer(std::string_view name) const;
    1208             : 
    1209             :   /*
    1210             :    * \returns The name for the indexed extra node integer
    1211             :    * datum, which must have already been added.
    1212             :    */
    1213          36 :   const std::string & get_node_integer_name(unsigned int i) const
    1214          72 :   { return _node_integer_names[i]; }
    1215             : 
    1216             :   /*
    1217             :    * \returns The number of extra node integers for which space is
    1218             :    * being reserved on this mesh.
    1219             :    *
    1220             :    * If non-integer data has been associated, each datum of type T
    1221             :    * counts for sizeof(T)/sizeof(dof_id_type) times in the return
    1222             :    * value.
    1223             :    */
    1224        1215 :   unsigned int n_node_integers() const { return _node_integer_names.size(); }
    1225             : 
    1226             :   /**
    1227             :    * Register a datum (of type T) to be added to each node in the
    1228             :    * mesh.
    1229             :    *
    1230             :    * If the mesh already has nodes, data by default is allocated in
    1231             :    * each of them.  This may be expensive to do repeatedly; use
    1232             :    * add_node_data instead.  Alternatively, the \p allocate_data
    1233             :    * option can be manually set to false, but if this is done then a
    1234             :    * manual call to \p size_node_extra_integers() will need to be done
    1235             :    * before the new space is usable.
    1236             :    *
    1237             :    * Newly allocated values for the new datum will be initialized to
    1238             :    * \p *default_value if \p default_value is not null, or to
    1239             :    * meaningless memcpy output otherwise.
    1240             :    *
    1241             :    * \returns The starting index number for the new datum, or for the
    1242             :    * existing datum if one by the same name has already been added.
    1243             :    *
    1244             :    * If type T is larger than dof_id_type, its data will end up
    1245             :    * spanning multiple index values, but will be queried with the
    1246             :    * starting index number.
    1247             :    *
    1248             :    * No type checking is done with this function!  If you add data of
    1249             :    * type T, don't try to access it with a call specifying type U.
    1250             :    */
    1251             :   template <typename T>
    1252             :   unsigned int add_node_datum(const std::string & name,
    1253             :                               bool allocate_data = true,
    1254             :                               const T * default_value = nullptr);
    1255             : 
    1256             :   /**
    1257             :    * Register data (of type T) to be added to each node in the
    1258             :    * mesh.
    1259             :    *
    1260             :    * If the mesh already has nodes, data by default is allocated in each.
    1261             :    *
    1262             :    * Newly allocated values for the new datum with name \p names[i]
    1263             :    * will be initialized to \p default_values[i], or to
    1264             :    * meaningless memcpy output if \p default_values is null.
    1265             :    *
    1266             :    * \returns The starting index number for the new data, or for the
    1267             :    * existing data if one by the same name has already been added.
    1268             :    *
    1269             :    * If type T is larger than dof_id_type, its data will end up
    1270             :    * spanning multiple index values, but will be queried with the
    1271             :    * starting index number.
    1272             :    *
    1273             :    * No type checking is done with this function!  If you add data of
    1274             :    * type T, don't try to access it with a call specifying type U.
    1275             :    */
    1276             :   template <typename T>
    1277             :   std::vector<unsigned int> add_node_data(const std::vector<std::string> & name,
    1278             :                                           bool allocate_data = true,
    1279             :                                           const std::vector<T> * default_values = nullptr);
    1280             : 
    1281             :   /**
    1282             :    * Prepare a newly created (or read) mesh for use.
    1283             :    * This involves several steps:
    1284             :    *  1.) renumbering (if enabled)
    1285             :    *  2.) removing any orphaned nodes
    1286             :    *  3.) updating parallel id counts
    1287             :    *  4.) finding neighbor links
    1288             :    *  5.) caching summarized element data
    1289             :    *  6.) finding interior parent links
    1290             :    *  7.) clearing any old point locator
    1291             :    *  8.) calling reinit() on ghosting functors
    1292             :    *  9.) repartitioning (if enabled)
    1293             :    *  10.) removing any remote elements (if enabled)
    1294             :    *  11.) regenerating summarized boundary id sets
    1295             :    *
    1296             :    * For backwards compatibility, prepare_for_use() performs *all* those
    1297             :    * steps, regardless of the official preparation() state of the
    1298             :    * mesh.  In codes which have maintained a valid preparation() state
    1299             :    * via methods such as unset_has_synched_id_counts(), calling
    1300             :    * complete_preparation() will result in a fully-prepared mesh at
    1301             :    * less cost.
    1302             :    *
    1303             :    * The argument to skip renumbering is now deprecated - to prevent a
    1304             :    * mesh from being renumbered, set allow_renumbering(false). The argument to skip
    1305             :    * finding neighbors is also deprecated. To prevent find_neighbors, set
    1306             :    * allow_find_neighbors(false)
    1307             :    *
    1308             :    * If this is a distributed mesh, local copies of remote elements
    1309             :    * will be deleted here - to keep those elements replicated during
    1310             :    * preparation, set allow_remote_element_removal(false).
    1311             :    */
    1312             : #ifdef LIBMESH_ENABLE_DEPRECATED
    1313             :   void prepare_for_use (const bool skip_renumber_nodes_and_elements, const bool skip_find_neighbors);
    1314             :   void prepare_for_use (const bool skip_renumber_nodes_and_elements);
    1315             : #endif // LIBMESH_ENABLE_DEPRECATED
    1316             :   void prepare_for_use ();
    1317             : 
    1318             :   /*
    1319             :    * Prepare a newly created or modified mesh for use.
    1320             :    *
    1321             :    * Unlike \p prepare_for_use(), \p complete_preparation() performs
    1322             :    * *only* those preparatory steps that have been marked as
    1323             :    * necessary in the MeshBase::Preparation state.
    1324             :    */
    1325             :   void complete_preparation();
    1326             : 
    1327             :   /**
    1328             :    * Call the default partitioner (currently \p metis_partition()).
    1329             :    */
    1330             :   virtual void partition (const unsigned int n_parts);
    1331             : 
    1332        2028 :   void partition ()
    1333      615622 :   { this->partition(this->n_processors()); }
    1334             : 
    1335             :   /**
    1336             :    * Redistribute elements between processors.  This gets called
    1337             :    * automatically by the Partitioner, and merely notifies any
    1338             :    * GhostingFunctors of redistribution in the case of a
    1339             :    * ReplicatedMesh or serialized DistributedMesh
    1340             :    */
    1341             :   virtual void redistribute ();
    1342             : 
    1343             :   /**
    1344             :    * Recalculate any cached data (or invalidate any caches that are
    1345             :    * computed on the fly) after elements and nodes have been
    1346             :    * repartitioned.
    1347             :    */
    1348             :   virtual void update_post_partitioning ();
    1349             : 
    1350             :   /**
    1351             :    * If false is passed in then this mesh will no longer be renumbered
    1352             :    * when being prepared for use.  This may slightly adversely affect
    1353             :    * performance during subsequent element access, particularly when
    1354             :    * using a distributed mesh.
    1355             :    *
    1356             :    * Important! When allow_renumbering(false) is set,
    1357             :    * ReplicatedMesh::n_elem() and ReplicatedMesh::n_nodes() will
    1358             :    * return *wrong* values whenever adaptive refinement is followed by
    1359             :    * adaptive coarsening. (Uniform refinement followed by uniform
    1360             :    * coarsening is OK.) This is due to the fact that n_elem() and
    1361             :    * n_nodes() are currently O(1) functions that just return the size
    1362             :    * of the respective underlying vectors, and this size is wrong when
    1363             :    * the numbering includes "gaps" from nodes and elements that have
    1364             :    * been deleted. We plan to implement a caching mechanism in the
    1365             :    * near future that will fix this incorrect behavior.
    1366             :    */
    1367       85188 :   void allow_renumbering(bool allow) { _skip_renumber_nodes_and_elements = !allow; }
    1368       83599 :   bool allow_renumbering() const { return !_skip_renumber_nodes_and_elements; }
    1369             : 
    1370             :   /**
    1371             :    * If \p false is passed then this mesh will no longer work to find element
    1372             :    * neighbors when being prepared for use
    1373             :    */
    1374      103951 :   void allow_find_neighbors(bool allow) { _skip_find_neighbors = !allow; }
    1375      212104 :   bool allow_find_neighbors() const { return !_skip_find_neighbors; }
    1376             : 
    1377             :   /**
    1378             :    * If \p false is passed then this mesh will no longer work to detect
    1379             :    * interior parents when being prepared for use
    1380             :    */
    1381       48259 :   void allow_detect_interior_parents(bool allow) { _skip_detect_interior_parents = !allow; }
    1382       47475 :   bool allow_detect_interior_parents() const { return !_skip_detect_interior_parents; }
    1383             : 
    1384             :   /**
    1385             :    * If false is passed in then this mesh will no longer have remote
    1386             :    * elements deleted when being prepared for use; i.e. even a
    1387             :    * DistributedMesh will remain (if it is already) serialized.
    1388             :    * This may adversely affect performance and memory use.
    1389             :    */
    1390      868534 :   void allow_remote_element_removal(bool allow) { _allow_remote_element_removal = allow; }
    1391      515981 :   bool allow_remote_element_removal() const { return _allow_remote_element_removal; }
    1392             : 
    1393             :   /**
    1394             :    * If \p true is passed, then this mesh will no longer require
    1395             :    * unique_ids to be unique across the set of all DofObjects. That
    1396             :    * is, although no two Elems (resp. Nodes) will share the same
    1397             :    * unique_id, a given Elem and Node might share the same unique_id.
    1398             :    */
    1399         142 :   void allow_node_and_elem_unique_id_overlap(bool allow) { _allow_node_and_elem_unique_id_overlap = allow; }
    1400       91222 :   bool allow_node_and_elem_unique_id_overlap() const { return _allow_node_and_elem_unique_id_overlap; }
    1401             : 
    1402             :   /**
    1403             :    * \returns \p true while this mesh redistributes elements to match
    1404             :    * new processor ids. During that time a processor may own an
    1405             :    * element whose neighbors have not arrived yet.
    1406             :    */
    1407          32 :   bool is_redistributing() const { return _is_redistributing; }
    1408             : 
    1409             :   /**
    1410             :    * If true is passed in then the elements on this mesh will no
    1411             :    * longer be (re)partitioned, and the nodes on this mesh will only
    1412             :    * be repartitioned if they are found "orphaned" via coarsening or
    1413             :    * other removal of the last element responsible for their
    1414             :    * node/element processor id consistency.
    1415             :    *
    1416             :    * \note It would probably be a bad idea to call this on a
    1417             :    * DistributedMesh _before_ the first partitioning has happened...
    1418             :    * because no elements would get assigned to your processor pool.
    1419             :    *
    1420             :    * \note Skipping partitioning can have adverse effects on your
    1421             :    * performance when using AMR... i.e. you could get large load
    1422             :    * imbalances.  However you might still want to use this if the
    1423             :    * communication and computation of the rebalance and repartition is
    1424             :    * too high for your application.
    1425             :    *
    1426             :    * It is also possible, for backwards-compatibility purposes, to
    1427             :    * skip noncritical partitioning by resetting the partitioner()
    1428             :    * pointer for this mesh.
    1429             :    */
    1430             :   void skip_noncritical_partitioning(bool skip)
    1431             :   { _skip_noncritical_partitioning = skip; }
    1432             : 
    1433        4217 :   bool skip_noncritical_partitioning() const
    1434      174157 :   { return _skip_noncritical_partitioning || _skip_all_partitioning || !_partitioner.get(); }
    1435             : 
    1436             : 
    1437             :   /**
    1438             :    * If true is passed in then nothing on this mesh will be
    1439             :    * (re)partitioned.
    1440             :    *
    1441             :    * \note The caveats for skip_noncritical_partitioning() still
    1442             :    * apply, and removing elements from a mesh with this setting
    1443             :    * enabled can leave node processor ids in an inconsistent state
    1444             :    * (not matching any attached element), causing failures in other
    1445             :    * library code.  Do not use this setting along with element
    1446             :    * deletion or coarsening.
    1447             :    */
    1448       35226 :   void skip_partitioning(bool skip) { _skip_all_partitioning = skip; }
    1449             : 
    1450     1044290 :   bool skip_partitioning() const { return _skip_all_partitioning; }
    1451             : 
    1452             :   /**
    1453             :    * Adds a functor which can specify ghosting requirements for use on
    1454             :    * distributed meshes.  Multiple ghosting functors can be added; any
    1455             :    * element which is required by any functor will be ghosted.
    1456             :    *
    1457             :    * GhostingFunctor memory must be managed by the code which calls
    1458             :    * this function; the GhostingFunctor lifetime is expected to extend
    1459             :    * until either the functor is removed or the Mesh is destructed.
    1460             :    */
    1461             :   void add_ghosting_functor(GhostingFunctor & ghosting_functor);
    1462             : 
    1463             :   /**
    1464             :    * Adds a functor which can specify ghosting requirements for use on
    1465             :    * distributed meshes.  Multiple ghosting functors can be added; any
    1466             :    * element which is required by any functor will be ghosted.
    1467             :    *
    1468             :    * GhostingFunctor memory when using this method is managed by the
    1469             :    * shared_ptr mechanism.
    1470             :    */
    1471       33098 :   void add_ghosting_functor(std::shared_ptr<GhostingFunctor> ghosting_functor)
    1472       62494 :   { _shared_functors[ghosting_functor.get()] = ghosting_functor;
    1473       33098 :     this->add_ghosting_functor(*ghosting_functor); }
    1474             : 
    1475             :   /**
    1476             :    * Removes a functor which was previously added to the set of
    1477             :    * ghosting functors.
    1478             :    */
    1479             :   void remove_ghosting_functor(GhostingFunctor & ghosting_functor);
    1480             : 
    1481             :   /**
    1482             :    * Iterator type for ghosting functor ranges.  This has changed in
    1483             :    * the past and may change again; code should use auto or the type
    1484             :    * here.
    1485             :    */
    1486             :   typedef std::vector<GhostingFunctor *>::const_iterator GhostingFunctorIterator;
    1487             :   typedef std::vector<GhostingFunctor *>::iterator NonConstGhostingFunctorIterator;
    1488             : 
    1489             :   /**
    1490             :    * Beginning of range of ghosting functors
    1491             :    */
    1492         949 :   GhostingFunctorIterator ghosting_functors_begin() const
    1493        1898 :   { return _ghosting_functors.begin(); }
    1494             : 
    1495        3530 :   NonConstGhostingFunctorIterator ghosting_functors_begin()
    1496        3530 :   { return _ghosting_functors.begin(); }
    1497             : 
    1498             :   /**
    1499             :    * End of range of ghosting functors
    1500             :    */
    1501         949 :   GhostingFunctorIterator ghosting_functors_end() const
    1502        1898 :   { return _ghosting_functors.end(); }
    1503             : 
    1504        3530 :   NonConstGhostingFunctorIterator ghosting_functors_end()
    1505        3530 :   { return _ghosting_functors.end(); }
    1506             : 
    1507             :   /**
    1508             :    * Default ghosting functor
    1509             :    */
    1510           6 :   GhostingFunctor & default_ghosting() { return *_default_ghosting; }
    1511             : 
    1512             :   /**
    1513             :    * Constructs a list of all subdomain identifiers in the local mesh if
    1514             :    * \p global == false, and in the global mesh if \p global == true (default).
    1515             :    * Subdomains correspond to separate subsets of the mesh which could correspond
    1516             :    * e.g. to different materials in a solid mechanics application,
    1517             :    * or regions where different physical processes are important.  The subdomain
    1518             :    * mapping is independent from the parallel decomposition.
    1519             :    *
    1520             :    * Unpartitioned elements are included in the set in the case that \p
    1521             :    * global == true. If \p global == false, the unpartitioned elements are not
    1522             :    * included because unpartitioned elements do not have a sense of locality.
    1523             :    */
    1524             :   void subdomain_ids (std::set<subdomain_id_type> & ids, const bool global = true) const;
    1525             : 
    1526             :   /**
    1527             :    * \returns The number of subdomains in the global mesh. Subdomains correspond
    1528             :    * to separate subsets of the mesh which could correspond e.g. to different
    1529             :    * materials in a solid mechanics application, or regions where different
    1530             :    * physical processes are important.  The subdomain mapping is independent
    1531             :    * from the parallel decomposition.
    1532             :    *
    1533             :    * This relies on the mesh cached element data being prepared.
    1534             :    */
    1535             :   subdomain_id_type n_subdomains () const;
    1536             : 
    1537             :   /**
    1538             :    * \returns The number of subdomains in the local mesh. Subdomains correspond
    1539             :    * to separate subsets of the mesh which could correspond e.g. to different
    1540             :    * materials in a solid mechanics application, or regions where different
    1541             :    * physical processes are important.  The subdomain mapping is independent
    1542             :    * from the parallel decomposition.
    1543             :    *
    1544             :    * This relies on the mesh cached element data being prepared.
    1545             :    */
    1546             :   subdomain_id_type n_local_subdomains () const;
    1547             : 
    1548             :   /**
    1549             :    * \returns The number of partitions which have been defined via
    1550             :    * a call to either mesh.partition() or by building a Partitioner
    1551             :    * object and calling partition.
    1552             :    *
    1553             :    * \note The partitioner object is responsible for setting this
    1554             :    * value.
    1555             :    */
    1556        8624 :   unsigned int n_partitions () const
    1557       58517 :   { return _n_parts; }
    1558             : 
    1559             :   /**
    1560             :    * \returns A string containing relevant information
    1561             :    * about the mesh.
    1562             :    *
    1563             :    * \p verbosity sets the verbosity, with 0 being the least and 2 being the greatest.
    1564             :    * 0 - Dimensions, number of nodes, number of elems, number of subdomains, number of
    1565             :    *     partitions, prepared status.
    1566             :    * 1 - Adds the mesh bounding box, mesh element types, specific nodesets/edgesets/sidesets
    1567             :    *     with element types, number of nodes/edges/sides.
    1568             :    * 2 - Adds volume information and bounding boxes to boundary information.
    1569             :    *
    1570             :    * The \p global parameter pertains primarily to verbosity levels 1 and above.
    1571             :    * When \p global == true, information is only output on rank 0 and the information
    1572             :    * is reduced. When \p global == false, information is output on all ranks that pertains
    1573             :    * only to that local partition.
    1574             :    */
    1575             :   std::string get_info (const unsigned int verbosity = 0, const bool global = true) const;
    1576             : 
    1577             :   /**
    1578             :    * Prints relevant information about the mesh.
    1579             :    *
    1580             :    * Take note of the docstring for get_info() for more information pretaining to
    1581             :    * the \p verbosity and \p global parameters.
    1582             :    */
    1583             :   void print_info (std::ostream & os=libMesh::out, const unsigned int verbosity = 0, const bool global = true) const;
    1584             : 
    1585             :   /**
    1586             :    * Equivalent to calling print_info() above, but now you can write:
    1587             :    * Mesh mesh;
    1588             :    * libMesh::out << mesh << std::endl;
    1589             :    */
    1590             :   friend std::ostream & operator << (std::ostream & os, const MeshBase & m);
    1591             : 
    1592             :   /**
    1593             :    * Interfaces for reading/writing a mesh to/from a file.  Must be
    1594             :    * implemented in derived classes.
    1595             :    */
    1596             :   virtual void read  (const std::string & name,
    1597             :                       void * mesh_data=nullptr,
    1598             :                       bool skip_renumber_nodes_and_elements=false,
    1599             :                       bool skip_find_neighbors=false,
    1600             :                       bool skip_detect_interior_parents=false) = 0;
    1601             :   virtual void write (const std::string & name) const = 0;
    1602             : 
    1603             :   /**
    1604             :    * Converts a mesh with higher-order
    1605             :    * elements into a mesh with linear elements.  For
    1606             :    * example, a mesh consisting of \p Tet10 will be converted
    1607             :    * to a mesh with \p Tet4 etc.
    1608             :    */
    1609             :   virtual void all_first_order () = 0;
    1610             : 
    1611             :   /**
    1612             :    * We need an empty, generic class to act as a predicate for this
    1613             :    * and derived mesh classes.
    1614             :    */
    1615             :   typedef Predicates::multi_predicate Predicate;
    1616             : 
    1617             :   /**
    1618             :    * structs for the element_iterator's.
    1619             :    *
    1620             :    * \note These iterators were designed so that derived mesh classes
    1621             :    * could use the _same_ base class iterators interchangeably.  Their
    1622             :    * definition comes later in the header file.
    1623             :    */
    1624             :   struct element_iterator;
    1625             :   struct const_element_iterator;
    1626             : 
    1627             :   /**
    1628             :    * structs for the node_iterator's.
    1629             :    *
    1630             :    * \note These iterators were designed so that derived mesh classes
    1631             :    * could use the _same_ base class iterators interchangeably.  Their
    1632             :    * definition comes later in the header file.
    1633             :    */
    1634             :   struct node_iterator;
    1635             :   struct const_node_iterator;
    1636             : 
    1637             :   /**
    1638             :    * Converts a set of this Mesh's elements defined by \p range from
    1639             :    * FIRST order to SECOND order. Must be called on conforming,
    1640             :    * non-refined meshes. For example, a mesh consisting of \p Tet4
    1641             :    * will be converted to a mesh with \p Tet10 etc.
    1642             :    *
    1643             :    * \note For some elements like \p Hex8 there exist two higher order
    1644             :    * equivalents, \p Hex20 and \p Hex27.  When \p full_ordered is \p
    1645             :    * true (default), then \p Hex27 is built.  Otherwise, \p Hex20 is
    1646             :    * built.  The same holds obviously for \p Quad4, \p Prism6, etc.
    1647             :    */
    1648             :   virtual void all_second_order_range(const SimpleRange<element_iterator> & range,
    1649             :                                       const bool full_ordered = true) = 0;
    1650             : 
    1651             :   /**
    1652             :    * Calls the range-based version of this function with a range
    1653             :    * consisting of all elements in the mesh.
    1654             :    */
    1655             :   void all_second_order (const bool full_ordered = true);
    1656             : 
    1657             :   /**
    1658             :    * Converts a set of elements in this (conforming, non-refined) mesh
    1659             :    * into "complete" order elements, i.e. elements which
    1660             :    * can store degrees of freedom on any vertex, edge, or face.  For
    1661             :    * example, a mesh consisting of \p Tet4 or \p Tet10 will be
    1662             :    * converted to a mesh with \p Tet14 etc.
    1663             :    */
    1664             :   virtual void all_complete_order_range(const SimpleRange<element_iterator> & range) = 0;
    1665             : 
    1666             :   /**
    1667             :    * Calls the range-based version of this function with a range
    1668             :    * consisting of all elements in the mesh.
    1669             :    */
    1670             :   virtual void all_complete_order ();
    1671             : 
    1672             :   /**
    1673             :    * In a few (very rare) cases, the user may have manually tagged the
    1674             :    * elements with specific processor IDs by hand, without using a
    1675             :    * partitioner.  In this case, the Mesh will not know that the total
    1676             :    * number of partitions, _n_parts, has changed, unless you call this
    1677             :    * function.  This is an O(N active elements) calculation.  The return
    1678             :    * value is the number of partitions, and _n_parts is also set by
    1679             :    * this function.
    1680             :    */
    1681             :   unsigned int recalculate_n_partitions();
    1682             : 
    1683             :   /**
    1684             :    * \returns A pointer to a subordinate \p PointLocatorBase object
    1685             :    * for this mesh, constructing a master PointLocator first if
    1686             :    * necessary.  This should not be used in threaded or
    1687             :    * non-parallel_only code unless the master has already been
    1688             :    * constructed.
    1689             :    */
    1690             :   std::unique_ptr<PointLocatorBase> sub_point_locator () const;
    1691             : 
    1692             :   /**
    1693             :    * Set value used by PointLocatorBase::close_to_point_tol().
    1694             :    *
    1695             :    * Defaults to 0.0. If nonzero, calls close_to_point_tol() whenever
    1696             :    * a new PointLocator is built for use by this Mesh.  Since the Mesh
    1697             :    * controls the creation and destruction of the PointLocator, if
    1698             :    * there are any parameters we need to customize on it, the Mesh
    1699             :    * will need to know about them.
    1700             :    */
    1701             :   void set_point_locator_close_to_point_tol(Real val);
    1702             :   Real get_point_locator_close_to_point_tol() const;
    1703             : 
    1704             :   /**
    1705             :    * Releases the current \p PointLocator object.
    1706             :    */
    1707             :   void clear_point_locator ();
    1708             : 
    1709             :   /**
    1710             :    * In the point locator, do we count lower dimensional elements
    1711             :    * when we refine point locator regions? This is relevant in
    1712             :    * tree-based point locators, for example.
    1713             :    */
    1714             :   void set_count_lower_dim_elems_in_point_locator(bool count_lower_dim_elems);
    1715             : 
    1716             :   /**
    1717             :    * Get the current value of _count_lower_dim_elems_in_point_locator.
    1718             :    */
    1719             :   bool get_count_lower_dim_elems_in_point_locator() const;
    1720             : 
    1721             :   /**
    1722             :    * Verify id and processor_id consistency of our elements and
    1723             :    * nodes containers.
    1724             :    * Calls libmesh_assert() on each possible failure.
    1725             :    * Currently only implemented on DistributedMesh; a serial data
    1726             :    * structure is much harder to get out of sync.
    1727             :    */
    1728         292 :   virtual void libmesh_assert_valid_parallel_ids() const {}
    1729             : 
    1730             : #ifdef LIBMESH_ENABLE_DEPRECATED
    1731             :   /**
    1732             :    * \deprecated
    1733             :    * \returns A writable reference for setting an optional name for a
    1734             :    * subdomain.  This method is deprecated; use set_subdomain_name()
    1735             :    * instead.
    1736             :    */
    1737             :   std::string & subdomain_name(subdomain_id_type id);
    1738             : #endif // LIBMESH_ENABLE_DEPRECATED
    1739             : 
    1740             :   /**
    1741             :    * \returns A reference for getting an optional name for a
    1742             :    * subdomain.
    1743             :    */
    1744             :   const std::string & subdomain_name(subdomain_id_type id) const;
    1745             : 
    1746             :   /**
    1747             :    * Sets the \p name for the provided \p id
    1748             :    * @param id The subdomain id to set the name for
    1749             :    * @param name The subdomain name
    1750             :    * @param synchronous Whether this method is being called across all mesh ranks. If this is true,
    1751             :    * then we don't have to register this collective container as being out of sync
    1752             :    */
    1753             :   void set_subdomain_name(subdomain_id_type id,
    1754             :                           const std::string & name,
    1755             :                           bool synchronous = false);
    1756             : 
    1757             :   /**
    1758             :    * \returns The id of the named subdomain if it exists,
    1759             :    * \p Elem::invalid_subdomain_id otherwise.
    1760             :    */
    1761             :   subdomain_id_type get_id_by_name(std::string_view name) const;
    1762             : 
    1763             :   /*
    1764             :    * We have many combinations of iterators that filter on various
    1765             :    * characteristics; we use macros to make their abstract base class
    1766             :    * and their subclass declarations more terse.
    1767             :    */
    1768             : #define ABSTRACT_ELEM_ITERATORS(TYPE, ARGDECL) \
    1769             :   virtual element_iterator TYPE##elements_begin(ARGDECL) = 0; \
    1770             :   virtual element_iterator TYPE##elements_end(ARGDECL) = 0; \
    1771             :   virtual const_element_iterator TYPE##elements_begin(ARGDECL) const = 0; \
    1772             :   virtual const_element_iterator TYPE##elements_end(ARGDECL) const = 0; \
    1773             :   virtual SimpleRange<element_iterator> TYPE##element_ptr_range(ARGDECL) = 0; \
    1774             :   virtual SimpleRange<const_element_iterator> TYPE##element_ptr_range(ARGDECL) const = 0;
    1775             : 
    1776             : #define DECLARE_ELEM_ITERATORS(TYPE, ARGDECL, ARGS) \
    1777             :   virtual element_iterator TYPE##elements_begin(ARGDECL) override final; \
    1778             :   virtual element_iterator TYPE##elements_end(ARGDECL) override final; \
    1779             :   virtual const_element_iterator TYPE##elements_begin(ARGDECL) const override final; \
    1780             :   virtual const_element_iterator TYPE##elements_end(ARGDECL) const override final; \
    1781             :   virtual SimpleRange<element_iterator> TYPE##element_ptr_range(ARGDECL) override final { return {TYPE##elements_begin(ARGS), TYPE##elements_end(ARGS)}; } \
    1782             :   virtual SimpleRange<const_element_iterator> TYPE##element_ptr_range(ARGDECL) const override final  { return {TYPE##elements_begin(ARGS), TYPE##elements_end(ARGS)}; }
    1783             : 
    1784             : #define ABSTRACT_NODE_ITERATORS(TYPE, ARGDECL) \
    1785             :   virtual node_iterator TYPE##nodes_begin(ARGDECL) = 0; \
    1786             :   virtual node_iterator TYPE##nodes_end(ARGDECL) = 0; \
    1787             :   virtual const_node_iterator TYPE##nodes_begin(ARGDECL) const = 0; \
    1788             :   virtual const_node_iterator TYPE##nodes_end(ARGDECL) const = 0; \
    1789             :   virtual SimpleRange<node_iterator> TYPE##node_ptr_range(ARGDECL) = 0; \
    1790             :   virtual SimpleRange<const_node_iterator> TYPE##node_ptr_range(ARGDECL) const = 0;
    1791             : 
    1792             : #define DECLARE_NODE_ITERATORS(TYPE, ARGDECL, ARGS) \
    1793             :   virtual node_iterator TYPE##nodes_begin(ARGDECL) override final; \
    1794             :   virtual node_iterator TYPE##nodes_end(ARGDECL) override final; \
    1795             :   virtual const_node_iterator TYPE##nodes_begin(ARGDECL) const override final; \
    1796             :   virtual const_node_iterator TYPE##nodes_end(ARGDECL) const override final; \
    1797             :   virtual SimpleRange<node_iterator> TYPE##node_ptr_range(ARGDECL) override final { return {TYPE##nodes_begin(ARGS), TYPE##nodes_end(ARGS)}; } \
    1798             :   virtual SimpleRange<const_node_iterator> TYPE##node_ptr_range(ARGDECL) const override final  { return {TYPE##nodes_begin(ARGS), TYPE##nodes_end(ARGS)}; }
    1799             : 
    1800             : #define LIBMESH_COMMA ,
    1801             : 
    1802             :   /*
    1803             :    * element_iterator accessors
    1804             :    *
    1805             :    * The basic elements_begin() and elements_end() iterators iterate
    1806             :    * over all elements in a mesh, returning element pointers or const
    1807             :    * element pointers when dereferenced (depending on whether the mesh
    1808             :    * reference was const). range-for loops can be written using
    1809             :    * element_ptr_range()
    1810             :    *
    1811             :    * Filtered versions of these iterators, which skip over all
    1812             :    * elements not matching some predicate, are also available, by
    1813             :    * adding a prefix to the methods above.  E.g. local_ (in a form
    1814             :    * like local_elements_begin() or local_element_ptr_range()) will
    1815             :    * iterate only over elements whose processor_id() is the current
    1816             :    * processor, or active_ will iterate only over active elements even
    1817             :    * if the mesh is refined, or active_local_ will iterate over
    1818             :    * elements that are both active and local.  Negation forms such as
    1819             :    * not_local_ also exist.
    1820             :    *
    1821             :    * For some iterator prefixes, such as type_, an argument is needed
    1822             :    * for the filter; e.g. the ElemType to select for in that case.
    1823             :    *
    1824             :    * All valid prefixes and their corresponding arguments can be found
    1825             :    * in the macro invocations below.
    1826             :    */
    1827             :   ABSTRACT_ELEM_ITERATORS(,)                // elements_begin(), element_ptr_range(): all elements
    1828             :   ABSTRACT_ELEM_ITERATORS(active_,)         // Elem::active() == true
    1829             :   ABSTRACT_ELEM_ITERATORS(ancestor_,)       // Elem::ancestor() == true
    1830             :   ABSTRACT_ELEM_ITERATORS(subactive_,)      // Elem::subactive() == true
    1831             :   ABSTRACT_ELEM_ITERATORS(local_,)          // Elem::processor_id() == this processor
    1832             :   ABSTRACT_ELEM_ITERATORS(unpartitioned_,)  // Elem::processor_id() == invalid_processor_id
    1833             :   ABSTRACT_ELEM_ITERATORS(facelocal_,)      // is on or has a neighbor on this processor
    1834             :   ABSTRACT_ELEM_ITERATORS(level_,unsigned int level)   // Elem::level() == level
    1835             :   ABSTRACT_ELEM_ITERATORS(pid_,processor_id_type pid)  // Elem::processor_id() == pid
    1836             :   ABSTRACT_ELEM_ITERATORS(type_,ElemType type)         // Elem::type() == type
    1837             : 
    1838             :   ABSTRACT_ELEM_ITERATORS(active_subdomain_,subdomain_id_type sid) // active && Elem::subdomain_id() == sid
    1839             :   ABSTRACT_ELEM_ITERATORS(active_subdomain_set_,std::set<subdomain_id_type> ss) // active && ss.contains(Elem::subdomain_id())
    1840             : 
    1841             :   // Iterators which use negations of filters described above
    1842             :   ABSTRACT_ELEM_ITERATORS(not_active_,)
    1843             :   ABSTRACT_ELEM_ITERATORS(not_ancestor_,)
    1844             :   ABSTRACT_ELEM_ITERATORS(not_subactive_,)
    1845             :   ABSTRACT_ELEM_ITERATORS(not_local_,)
    1846             :   ABSTRACT_ELEM_ITERATORS(not_level_,unsigned int level)
    1847             : 
    1848             :   // Iterators which combine multiple of the filters described above
    1849             :   ABSTRACT_ELEM_ITERATORS(active_local_,)
    1850             :   ABSTRACT_ELEM_ITERATORS(active_not_local_,)
    1851             :   ABSTRACT_ELEM_ITERATORS(active_unpartitioned_,)
    1852             :   ABSTRACT_ELEM_ITERATORS(active_type_,ElemType type)
    1853             :   ABSTRACT_ELEM_ITERATORS(active_pid_,processor_id_type pid)
    1854             :   ABSTRACT_ELEM_ITERATORS(local_level_,unsigned int level)
    1855             :   ABSTRACT_ELEM_ITERATORS(local_not_level_,unsigned int level)
    1856             :   ABSTRACT_ELEM_ITERATORS(active_local_subdomain_,subdomain_id_type sid)
    1857             :   ABSTRACT_ELEM_ITERATORS(active_local_subdomain_set_,std::set<subdomain_id_type> ss)
    1858             : 
    1859             :   // Backwards compatibility
    1860             :   virtual SimpleRange<element_iterator> active_subdomain_elements_ptr_range(subdomain_id_type sid) = 0;
    1861             :   virtual SimpleRange<const_element_iterator> active_subdomain_elements_ptr_range(subdomain_id_type sid) const = 0;
    1862             :   virtual SimpleRange<element_iterator> active_local_subdomain_elements_ptr_range(subdomain_id_type sid) = 0;
    1863             :   virtual SimpleRange<const_element_iterator> active_local_subdomain_elements_ptr_range(subdomain_id_type sid) const = 0;
    1864             :   virtual SimpleRange<element_iterator> active_subdomain_set_elements_ptr_range(std::set<subdomain_id_type> ss) = 0;
    1865             :   virtual SimpleRange<const_element_iterator> active_subdomain_set_elements_ptr_range(std::set<subdomain_id_type> ss) const = 0;
    1866             : 
    1867             :   // Discouraged from use - these iterators use outdated
    1868             :   // pre-GhostingFunctor definitions and should be renamed if not
    1869             :   // deprecated
    1870             :   ABSTRACT_ELEM_ITERATORS(semilocal_,)         // active && Elem::is_semilocal()
    1871             :   ABSTRACT_ELEM_ITERATORS(ghost_,)             // active && Elem::is_semilocal() && not local discouraged
    1872             :   ABSTRACT_ELEM_ITERATORS(active_semilocal_,)
    1873             : 
    1874             :   // solution can be evaluated, with the given DoF map, for the given
    1875             :   // variable number, or for all variables by default
    1876             :   ABSTRACT_ELEM_ITERATORS(evaluable_,const DofMap & dof_map LIBMESH_COMMA unsigned int var_num = libMesh::invalid_uint)
    1877             : 
    1878             :   // solution can be evaluated for all variables of all given DoF maps
    1879             :   ABSTRACT_ELEM_ITERATORS(multi_evaluable_,std::vector<const DofMap *> dof_maps)
    1880             : 
    1881             : #ifdef LIBMESH_ENABLE_AMR
    1882             :   ABSTRACT_ELEM_ITERATORS(flagged_,unsigned char rflag)  // Elem::refinement_flag() == rflag
    1883             : 
    1884             :   // Elem::refinement_flag() == rflag && Elem::processor_id() == pid
    1885             :   ABSTRACT_ELEM_ITERATORS(flagged_pid_,unsigned char rflag LIBMESH_COMMA processor_id_type pid)
    1886             : #endif
    1887             : 
    1888             :   /*
    1889             :    * node_iterator accessors
    1890             :    *
    1891             :    * The basic nodes_begin() and nodes_end() iterators iterate
    1892             :    * over all nodes in a mesh, returning node pointers or const
    1893             :    * node pointers when dereferenced (depending on whether the mesh
    1894             :    * reference was const). range-for loops can be written using
    1895             :    * node_ptr_range()
    1896             :    *
    1897             :    * Filtered versions of these iterators, which skip over all
    1898             :    * nodes not matching some predicate, are also available, by
    1899             :    * adding a prefix to the methods above.  E.g. local_ (in a form
    1900             :    * like local_nodes_begin() or local_node_ptr_range()) will
    1901             :    * iterate only over nodes whose processor_id() is the current
    1902             :    * processor.
    1903             :    *
    1904             :    * All valid prefixes and their corresponding arguments can be found
    1905             :    * in the macro invocations below.
    1906             :    */
    1907             :   ABSTRACT_NODE_ITERATORS(,)          // nodes_begin(), node_ptr_range(): all nodes
    1908             :   ABSTRACT_NODE_ITERATORS(active_,)   // Node::active() == true; i.e. Node::id() != invalid_id
    1909             :   ABSTRACT_NODE_ITERATORS(local_,)    // Node::processor_id() == this processor
    1910             :   ABSTRACT_NODE_ITERATORS(bnd_,)      // BoundaryInfo::n_boundary_ids(node) > 0
    1911             :   ABSTRACT_NODE_ITERATORS(pid_,processor_id_type pid)  // Node::processor_id() == pid
    1912             :   ABSTRACT_NODE_ITERATORS(bid_,boundary_id_type bid)   // BoundaryInfo::has_boundary_id(node, bid)
    1913             : 
    1914             :   // solution can be evaluated, with the given DoF map, for the given
    1915             :   // variable number, or for all variables by default
    1916             :   ABSTRACT_NODE_ITERATORS(evaluable_,const DofMap & dof_map LIBMESH_COMMA unsigned int var_num = libMesh::invalid_uint)
    1917             : 
    1918             :   // solution can be evaluated for all variables of all given DoF maps
    1919             :   ABSTRACT_NODE_ITERATORS(multi_evaluable_,std::vector<const DofMap *> dof_maps)
    1920             : 
    1921             :   // Technically these define libMesh::MeshBase::*Range, but since
    1922             :   // those don't conflict with libMesh::*Range they're as good as
    1923             :   // a real forward declaration, which we can't do here.
    1924             :   typedef StoredRange<MeshBase::element_iterator,             Elem *>      ElemRange;
    1925             :   typedef StoredRange<MeshBase::const_element_iterator, const Elem *> ConstElemRange;
    1926             :   typedef StoredRange<MeshBase::node_iterator,             Node *>         NodeRange;
    1927             :   typedef StoredRange<MeshBase::const_node_iterator, const Node *>    ConstNodeRange;
    1928             : 
    1929             :   /**
    1930             :    * \returns A reference to a cached vector copy of a range of
    1931             :    * pointers to all semilocal elements, suitable for threading.
    1932             :    */
    1933             :   const ElemRange & element_stored_range();
    1934             :   const ConstElemRange & element_stored_range() const;
    1935             :   const ConstElemRange & const_element_stored_range() const;
    1936             : 
    1937             :   /**
    1938             :    * \returns A reference to a cached vector copy of a range of
    1939             :    * pointers to all active local elements, suitable for threading.
    1940             :    */
    1941             :   const ElemRange & active_local_element_stored_range();
    1942             :   const ConstElemRange & active_local_element_stored_range() const;
    1943             :   const ConstElemRange & const_active_local_element_stored_range() const;
    1944             : 
    1945             :   /**
    1946             :    * \returns A reference to a cached vector copy of a range of
    1947             :    * pointers to all local elements, suitable for threading.
    1948             :    */
    1949             :   const ElemRange & local_element_stored_range();
    1950             :   const ConstElemRange & local_element_stored_range() const;
    1951             :   const ConstElemRange & const_local_element_stored_range() const;
    1952             : 
    1953             :   /**
    1954             :    * \returns A reference to a cached vector copy of a range of
    1955             :    * pointers to all semilocal nodes, suitable for threading.
    1956             :    */
    1957             :   const NodeRange & node_stored_range();
    1958             :   const ConstNodeRange & node_stored_range() const;
    1959             :   const ConstNodeRange & const_node_stored_range() const;
    1960             : 
    1961             :   /**
    1962             :    * \returns A reference to a cached vector copy of a range of
    1963             :    * pointers to all local nodes, suitable for threading.
    1964             :    */
    1965             :   const NodeRange & local_node_stored_range();
    1966             :   const ConstNodeRange & local_node_stored_range() const;
    1967             :   const ConstNodeRange & const_local_node_stored_range() const;
    1968             : 
    1969             :   /**
    1970             :    * \returns A reference to a cached vector copy of a range of
    1971             :    * pointers to all unpartitioned nodes, suitable for threading.
    1972             :    */
    1973             :   const NodeRange & unpartitioned_node_stored_range();
    1974             :   const ConstNodeRange & unpartitioned_node_stored_range() const;
    1975             :   const ConstNodeRange & const_unpartitioned_node_stored_range() const;
    1976             : 
    1977             :   /**
    1978             :    * Clears stored ranges, to indicate that the mesh has changed and
    1979             :    * they should be regenerated when next needed.
    1980             :    */
    1981             :   void clear_stored_ranges();
    1982             : 
    1983             :   /**
    1984             :    * \returns A writable reference to the whole subdomain name map
    1985             :    */
    1986       19148 :   std::map<subdomain_id_type, std::string> & set_subdomain_name_map ()
    1987       42543 :   { this->unset_has_synched_subdomain_name_map(); return _block_id_to_name; }
    1988        2131 :   const std::map<subdomain_id_type, std::string> & get_subdomain_name_map () const
    1989        2407 :   { return _block_id_to_name; }
    1990             : 
    1991             :   typedef std::vector<std::pair<std::pair<const Elem *, unsigned int>, Real>> constraint_rows_mapped_type;
    1992             :   typedef std::map<const Node *, constraint_rows_mapped_type> constraint_rows_type;
    1993             : 
    1994             :   /**
    1995             :    * Constraint rows accessors.
    1996             :    */
    1997             : #ifdef LIBMESH_ENABLE_DEPRECATED
    1998       11600 :   constraint_rows_type & get_constraint_rows()
    1999       11600 :   { libmesh_deprecated(); return _constraint_rows; }
    2000             : #endif
    2001             : 
    2002      112089 :   const constraint_rows_type & get_constraint_rows() const
    2003      112089 :   { return _constraint_rows; }
    2004             : 
    2005          16 :   constraint_rows_type & set_constraint_rows()
    2006         257 :   { _preparation.has_cached_elem_data = false; return _constraint_rows; }
    2007             : 
    2008             :   /**
    2009             :    * Returns how many total constraint rows we have.  This is cached data,
    2010             :    * so it can be called from individual ranks.
    2011             :    */
    2012             :   dof_id_type n_constraint_rows() const;
    2013             : 
    2014             :   /**
    2015             :    * Copy the constraints from the other mesh to this mesh
    2016             :    */
    2017             :   void copy_constraint_rows(const MeshBase & other_mesh);
    2018             : 
    2019             :   /**
    2020             :    * Copy the constraints from the given matrix to this mesh.  The
    2021             :    * \p constraint_operator should be an mxn matrix, where
    2022             :    * m == this->n_nodes() and the operator indexing matches the
    2023             :    * current node indexing.  This may require users to disable mesh
    2024             :    * renumbering in between loading a mesh file and loading a
    2025             :    * constraint matrix which matches it.
    2026             :    *
    2027             :    * If any "constraint" rows in the matrix are unit vectors, the node
    2028             :    * corresponding to that row index will be left unconstrained, and
    2029             :    * will be used to constrain any other nodes which have a non-zero
    2030             :    * in the column index of that unit vector.
    2031             :    *
    2032             :    * For each matrix column index which does not correspond to an
    2033             :    * existing node, a new NodeElem will be added to the mesh on which
    2034             :    * to store the new unconstrained degree(s) of freedom.
    2035             :    *
    2036             :    * If \p precondition_constraint_operator is true, then the values
    2037             :    * of those new unconstrained degrees of freedom may be scaled to
    2038             :    * improve the conditioning of typical PDE matrices integrated on
    2039             :    * constrained mesh elements.
    2040             :    *
    2041             :    * \p T for the constraint_operator in this function should be \p
    2042             :    * Real or \p Number ... and the data should be \p Real - we just
    2043             :    * allow complex \p T for the sake of subclasses which have to be
    2044             :    * configured and compiled with only one runtime option.
    2045             :    */
    2046             :   template <typename T>
    2047             :   void copy_constraint_rows(const SparseMatrix<T> & constraint_operator,
    2048             :                             bool precondition_constraint_operator = false);
    2049             : 
    2050             :   /**
    2051             :    * Prints (from processor 0) all mesh constraint rows.  If \p
    2052             :    * print_nonlocal is true, then each constraint is printed once for
    2053             :    * each processor that knows about it, which may be useful for \p
    2054             :    * DistributedMesh debugging.
    2055             :    */
    2056             :   void print_constraint_rows(std::ostream & os=libMesh::out,
    2057             :                              bool print_nonlocal=false) const;
    2058             : 
    2059             :   /**
    2060             :    * Gets a string reporting all mesh constraint rows local to
    2061             :    * this processor.  If \p print_nonlocal is true, then nonlocal
    2062             :    * constraints which are locally known are included.
    2063             :    */
    2064             :   std::string get_local_constraints(bool print_nonlocal=false) const;
    2065             : 
    2066             : #ifdef LIBMESH_ENABLE_DEPRECATED
    2067             :   /**
    2068             :    * \deprecated This method has ben replaced by \p cache_elem_data which
    2069             :    * caches data in addition to elem dimensions (e.g. elem subdomain ids)
    2070             :    * Search the mesh and cache the different dimensions of the elements
    2071             :    * present in the mesh.  This is done in prepare_for_use(), but can
    2072             :    * be done manually by other classes after major mesh modifications.
    2073             :    */
    2074             :   void cache_elem_dims();
    2075             : #endif // LIBMESH_ENABLE_DEPRECATED
    2076             : 
    2077             :   /*
    2078             :    * Search the mesh and cache data for the elements
    2079             :    * present in the mesh.  This is done in prepare_for_use(), but can
    2080             :    * be done manually by other classes after major mesh modifications.
    2081             :    * Data cached includes:
    2082             :    *   - elem dimensions
    2083             :    *   - elem subdomains
    2084             :    */
    2085             :   void cache_elem_data();
    2086             : 
    2087             :   /**
    2088             :    * libMesh often expects all processors to know about names of all
    2089             :    * subdomain ids, but distributed mesh generators may only know
    2090             :    * about part of a mesh when creating names.  This method can
    2091             :    * synchronize the subdomain id to name map across processors,
    2092             :    * assuming no conflicts exist.  It is called automatically during
    2093             :    * complete_preparation() unless the map is already known to be
    2094             :    * synchronized.
    2095             :    */
    2096             :   void sync_subdomain_name_map();
    2097             : 
    2098             :   /**
    2099             :    * Search the mesh for elements that have a neighboring element
    2100             :    * of dim+1 and set that element as the interior parent
    2101             :    */
    2102             :   void detect_interior_parents();
    2103             : 
    2104             :   /**
    2105             :    * \return A mesh that may own interior parents of elements in this
    2106             :    * mesh.  In most cases this mesh includes its own interior parents,
    2107             :    * but in cases where a separate "interior" mesh was used to create
    2108             :    * this mesh as a distinct lower-dimensional boundary (or boundary
    2109             :    * subset) mesh, the original mesh will be returned here.
    2110             :    */
    2111         298 :   const MeshBase & interior_mesh() const { return *_interior_mesh; }
    2112             : 
    2113             :   /**
    2114             :    * \return A writeable reference to the interior mesh.
    2115             :    */
    2116       34397 :   MeshBase & interior_mesh() { return *_interior_mesh; }
    2117             : 
    2118             :   /**
    2119             :    * Sets the interior mesh.  For advanced use only.
    2120             :    */
    2121        3635 :   void set_interior_mesh(MeshBase & int_mesh) { _interior_mesh = &int_mesh; }
    2122             : 
    2123             :   /**
    2124             :    * \return The cached mesh subdomains. As long as the mesh is prepared, this
    2125             :    * should contain all the subdomain ids across processors. Relies on the mesh
    2126             :    * being prepared
    2127             :    */
    2128             :   const std::set<subdomain_id_type> & get_mesh_subdomains() const;
    2129             : 
    2130             :   /**
    2131             :    * \return The cached mesh subdomains. As long as the mesh is prepared, this
    2132             :    * should contain all the subdomain ids across processors. Relies on the mesh
    2133             :    * being prepared
    2134             :    */
    2135             :   const std::set<subdomain_id_type> & get_mesh_local_subdomains() const;
    2136             : 
    2137             : #ifdef LIBMESH_ENABLE_PERIODIC
    2138             :   /**
    2139             :    * Register a pair of boundaries as disjoint neighbor boundary pairs.
    2140             :    */
    2141             :   void add_disjoint_neighbor_boundary_pairs(const boundary_id_type b1,
    2142             :                                    const boundary_id_type b2,
    2143             :                                    const RealVectorValue & translation);
    2144             : 
    2145             :   PeriodicBoundaries * get_disjoint_neighbor_boundary_pairs();
    2146             : 
    2147             :   const PeriodicBoundaries * get_disjoint_neighbor_boundary_pairs() const;
    2148             : 
    2149             :   void remove_disjoint_boundary_pair(const boundary_id_type b1,
    2150             :                                      const boundary_id_type b2);
    2151             : #endif
    2152             : 
    2153             :   /**
    2154             :    * Flags indicating in what ways a mesh has been prepared for use.
    2155             :    */
    2156             :   struct Preparation
    2157             :   {
    2158             :     /**
    2159             :      * Constructor. Initializes all flags to false.
    2160             :      */
    2161             :     Preparation();
    2162             : 
    2163             :     /**
    2164             :      * Returns true iff all the flags are true.
    2165             :      */
    2166             :     explicit operator bool() const;
    2167             : 
    2168             :     /**
    2169             :      * Set all flags to the "set_all" value.
    2170             :      */
    2171             :     Preparation & operator= (bool set_all);
    2172             : 
    2173             :     /**
    2174             :      * Two Preparation objects are equivalent iff all the flags match,
    2175             :      * regardless of the true/false status of any given flag.
    2176             :      */
    2177             :     bool operator== (const Preparation & other) const;
    2178             :     bool operator!= (const Preparation & other) const;
    2179             : 
    2180             :     // Assert that a Preparation object is identical across processors
    2181             :     void libmesh_assert_consistent (const Parallel::Communicator & libmesh_dbg_var(comm));
    2182             : 
    2183             :     bool is_partitioned;
    2184             :     bool has_synched_id_counts;
    2185             :     bool has_neighbor_ptrs;
    2186             :     bool has_cached_elem_data;
    2187             :     bool has_interior_parent_ptrs;
    2188             :     bool has_removed_remote_elements;
    2189             :     bool has_removed_orphaned_nodes;
    2190             :     bool has_boundary_id_sets;
    2191             :     bool has_reinit_ghosting_functors;
    2192             :     bool has_synched_subdomain_name_map;
    2193             :   };
    2194             : 
    2195             : protected:
    2196             : 
    2197             : #ifdef LIBMESH_ENABLE_PERIODIC
    2198             :   /// @brief The disjoint neighbor boundary id pairs.
    2199             :   std::unique_ptr<PeriodicBoundaries> _disjoint_neighbor_boundary_pairs;
    2200             : #endif
    2201             : 
    2202             :   /**
    2203             :    * This class holds the boundary information.  It can store nodes, edges,
    2204             :    * and faces with a corresponding id that facilitates setting boundary
    2205             :    * conditions.
    2206             :    *
    2207             :    * Direct access to this class is now officially deprecated and will
    2208             :    * be removed in future libMesh versions.  Use the \p get_boundary_info()
    2209             :    * accessor instead.
    2210             :    */
    2211             :   std::unique_ptr<BoundaryInfo> boundary_info;
    2212             : 
    2213             :   /**
    2214             :    * Moves any superclass data (e.g. GhostingFunctors that might rely
    2215             :    * on element and nodal data (which is managed by subclasses!)
    2216             :    * being already moved first.
    2217             :    *
    2218             :    * Must be manually called in dofobject-managing subclass move
    2219             :    * operators.
    2220             :    */
    2221             :   void post_dofobject_moves(MeshBase && other_mesh);
    2222             : 
    2223             :   /**
    2224             :    * Helper class to copy cached data, to synchronize with a possibly
    2225             :    * unprepared \p other_mesh
    2226             :    */
    2227             :   void copy_cached_data (const MeshBase & other_mesh);
    2228             : 
    2229             :   /**
    2230             :    * Shim to allow operator == (&) to behave like a virtual function
    2231             :    * without having to be one.
    2232             :    *
    2233             :    * \returns a string describing the first difference found when
    2234             :    * comparing subclass-specific data between \p this and \p
    2235             :    * other_mesh, or an empty string if no differences are found.
    2236             :    */
    2237             :   virtual std::string_view subclass_first_difference_from (const MeshBase & other_mesh) const = 0;
    2238             : 
    2239             :   /**
    2240             :    * Tests for equality of all elements and nodes in the mesh.  Helper
    2241             :    * function for subclass_equals() in unstructured mesh subclasses.
    2242             :    */
    2243             :   bool nodes_and_elements_equal(const MeshBase & other_mesh) const;
    2244             : 
    2245             :   /**
    2246             :    * \returns A string describing the first difference found on this
    2247             :    * rank, in either \p MeshBase data or subclass-specific data,
    2248             :    * between \p this and \p other_mesh, or an empty string if no
    2249             :    * differences are found.  Used by \p operator== to determine whether
    2250             :    * differences exist, and by \p assert_equal_to to give debugging
    2251             :    * feedback.
    2252             :    */
    2253             :   std::string_view first_difference_from(const MeshBase & other_mesh) const;
    2254             : 
    2255             :   /**
    2256             :    * \returns A writable reference to the number of partitions.
    2257             :    */
    2258       18971 :   unsigned int & set_n_partitions ()
    2259       18971 :   { return _n_parts; }
    2260             : 
    2261             :   /**
    2262             :    * The number of partitions the mesh has.  This is set by
    2263             :    * the partitioners, and may not be changed directly by
    2264             :    * the user.
    2265             :    *
    2266             :    * \note The number of partitions \e need \e not equal
    2267             :    * this->n_processors(), consider for example the case where you
    2268             :    * simply want to partition a mesh on one processor and view the
    2269             :    * result in GMV.
    2270             :    */
    2271             :   unsigned int _n_parts;
    2272             : 
    2273             :   /**
    2274             :    * The default mapping type (typically Lagrange) between master and
    2275             :    * physical space to assign to newly added elements.
    2276             :    */
    2277             :   ElemMappingType _default_mapping_type;
    2278             : 
    2279             :   /**
    2280             :    * The default mapping data (unused with Lagrange, used for nodal
    2281             :    * weight lookup index with rational bases) to assign to newly added
    2282             :    * elements.
    2283             :    */
    2284             :   unsigned char _default_mapping_data;
    2285             : 
    2286             :   /**
    2287             :    * Flags indicating in what ways \p this mesh has been prepared.
    2288             :    */
    2289             :   Preparation _preparation;
    2290             : 
    2291             :   /**
    2292             :    * A cached \p ElemRange for threaded mutation of all semilocal
    2293             :    * elements of this mesh.
    2294             :    *
    2295             :    * This will not actually be built unless needed.  We do need this
    2296             :    * to be mutable so that we can build it on the fly if a const elem
    2297             :    * range (using it) is requested
    2298             :    */
    2299             :   mutable std::unique_ptr<ElemRange> _element_stored_range;
    2300             : 
    2301             :   /**
    2302             :    * A shim to _element_stored_range
    2303             :    */
    2304             :   mutable std::unique_ptr<ConstElemRange> _const_element_stored_range;
    2305             : 
    2306             :   /**
    2307             :    * A cached \p ElemRange for threaded calculation on all active
    2308             :    * local elements of this mesh.
    2309             :    *
    2310             :    * This will not actually be built unless needed.  We do need this
    2311             :    * to be mutable so that we can build it on the fly if a const elem
    2312             :    * range (using it) is requested
    2313             :    */
    2314             :   mutable std::unique_ptr<ElemRange>
    2315             :     _active_local_element_stored_range;
    2316             : 
    2317             :   /**
    2318             :    * A shim to _active_local_element_stored_range
    2319             :    */
    2320             :   mutable std::unique_ptr<ConstElemRange>
    2321             :     _const_active_local_element_stored_range;
    2322             : 
    2323             :   /**
    2324             :    * A cached \p ElemRange for threaded calculation on all
    2325             :    * local elements of this mesh.
    2326             :    *
    2327             :    * This will not actually be built unless needed.  We do need this
    2328             :    * to be mutable so that we can build it on the fly if a const elem
    2329             :    * range (using it) is requested
    2330             :    */
    2331             :   mutable std::unique_ptr<ElemRange>
    2332             :     _local_element_stored_range;
    2333             : 
    2334             :   /**
    2335             :    * A shim to _local_element_stored_range
    2336             :    */
    2337             :   mutable std::unique_ptr<ConstElemRange>
    2338             :     _const_local_element_stored_range;
    2339             : 
    2340             :   /**
    2341             :    * A cached \p NodeRange for threaded mutation of all semilocal
    2342             :    * nodes of this mesh, or (via a temporary shim) for read-only
    2343             :    * iteration over all nodes.
    2344             :    *
    2345             :    * This will not actually be built unless needed.  We do need this
    2346             :    * to be mutable so that we can build it on the fly if a const node
    2347             :    * range (using it) is requested
    2348             :    */
    2349             :   mutable std::unique_ptr<NodeRange> _node_stored_range;
    2350             : 
    2351             :   /**
    2352             :    * A shim to _node_stored_range
    2353             :    */
    2354             :   mutable std::unique_ptr<ConstNodeRange> _const_node_stored_range;
    2355             : 
    2356             :   /**
    2357             :    * A cached \p NodeRange for threaded mutation of all local
    2358             :    * nodes of this mesh.
    2359             :    *
    2360             :    * This will not actually be built unless needed.  We do need this
    2361             :    * to be mutable so that we can build it on the fly if a const node
    2362             :    * range (using it) is requested
    2363             :    */
    2364             :   mutable std::unique_ptr<NodeRange> _local_node_stored_range;
    2365             : 
    2366             :   /**
    2367             :    * A shim to _local_node_stored_range
    2368             :    */
    2369             :   mutable std::unique_ptr<ConstNodeRange> _const_local_node_stored_range;
    2370             : 
    2371             :   /**
    2372             :    * A cached \p NodeRange for threaded mutation of all unpartitioned
    2373             :    * nodes of this mesh.
    2374             :    *
    2375             :    * This will not actually be built unless needed.  We do need this
    2376             :    * to be mutable so that we can build it on the fly if a const node
    2377             :    * range (using it) is requested
    2378             :    */
    2379             :   mutable std::unique_ptr<NodeRange> _unpartitioned_node_stored_range;
    2380             : 
    2381             :   /**
    2382             :    * A shim to _unpartitioned_node_stored_range
    2383             :    */
    2384             :   mutable std::unique_ptr<ConstNodeRange> _const_unpartitioned_node_stored_range;
    2385             : 
    2386             :   /**
    2387             :    * A \p PointLocator class for this mesh.
    2388             :    * This will not actually be built unless needed. Further, since we want
    2389             :    * our \p point_locator() method to be \p const (yet do the dynamic allocating)
    2390             :    * this needs to be mutable.  Since the PointLocatorBase::build() member is used,
    2391             :    * and it operates on a constant reference to the mesh, this is OK.
    2392             :    */
    2393             :   mutable std::unique_ptr<PointLocatorBase> _point_locator;
    2394             : 
    2395             :   /**
    2396             :    * Do we count lower dimensional elements in point locator refinement?
    2397             :    * This is relevant in tree-based point locators, for example.
    2398             :    */
    2399             :   bool _count_lower_dim_elems_in_point_locator;
    2400             : 
    2401             :   /**
    2402             :    * A partitioner to use at each prepare_for_use().
    2403             :    *
    2404             :    * This will be built in the constructor of each derived class, but
    2405             :    * can be replaced by the user through the partitioner() accessor.
    2406             :    */
    2407             :   std::unique_ptr<Partitioner> _partitioner;
    2408             : 
    2409             : #ifdef LIBMESH_ENABLE_UNIQUE_ID
    2410             :   /**
    2411             :    * The next available unique id for assigning ids to DOF objects
    2412             :    */
    2413             :   unique_id_type _next_unique_id;
    2414             : #endif
    2415             : 
    2416             :   /**
    2417             :    * Defaulting to \p this, a pointer to the mesh used to generate
    2418             :    * boundary elements on \p this.
    2419             :    */
    2420             :   MeshBase *_interior_mesh;
    2421             : 
    2422             :   /**
    2423             :    * If this is true then no partitioning should be done with the
    2424             :    * possible exception of orphaned nodes.
    2425             :    */
    2426             :   bool _skip_noncritical_partitioning;
    2427             : 
    2428             :   /**
    2429             :    * If this is true then no partitioning should be done.
    2430             :    */
    2431             :   bool _skip_all_partitioning;
    2432             : 
    2433             :   /**
    2434             :    * If this is true then renumbering will be kept to a minimum.
    2435             :    *
    2436             :    * This is set when prepare_for_use() is called.
    2437             :    */
    2438             :   bool _skip_renumber_nodes_and_elements;
    2439             : 
    2440             :   /**
    2441             :    * If this is \p true then we will skip \p find_neighbors in \p prepare_for_use
    2442             :    */
    2443             :   bool _skip_find_neighbors;
    2444             : 
    2445             :   /**
    2446             :    * If this is \p true then we will skip \p detect_interior_parents in \p prepare_for_use
    2447             :    */
    2448             :   bool _skip_detect_interior_parents;
    2449             : 
    2450             :   /**
    2451             :    * If this is false then even on DistributedMesh remote elements
    2452             :    * will not be deleted during mesh preparation.
    2453             :    *
    2454             :    * This is true by default.
    2455             :    */
    2456             :   bool _allow_remote_element_removal;
    2457             : 
    2458             :   /**
    2459             :    * The Exodus reader (and potentially other readers in the future?)
    2460             :    * now supports setting Node and Elem unique_ids based on values
    2461             :    * from within the Exodus file itself, rather than generating them
    2462             :    * automatically in LibMesh. In this case, the unique_ids will not
    2463             :    * necessarily be unique across the set of all _DofObjects_,
    2464             :    * although they should still be unique within the individual sets
    2465             :    * of Elems and Nodes. The reader can therefore set this Mesh flag
    2466             :    * (which defaults to false) to indicate we should be less strict
    2467             :    * when checking the "uniqueness" of unique_ids.
    2468             :    */
    2469             :   bool _allow_node_and_elem_unique_id_overlap;
    2470             : 
    2471             :   /**
    2472             :    * True while \p MeshCommunication::redistribute() moves elements
    2473             :    * to match new processor ids.
    2474             :    */
    2475             :   bool _is_redistributing;
    2476             : 
    2477             :   /**
    2478             :    * This structure maintains the mapping of named blocks
    2479             :    * for file formats that support named blocks.  Currently
    2480             :    * this is only implemented for ExodusII
    2481             :    */
    2482             :   std::map<subdomain_id_type, std::string> _block_id_to_name;
    2483             : 
    2484             :   /**
    2485             :    * We cache the dimension of the elements present in the mesh.
    2486             :    * So, if we have a mesh with 1D and 2D elements, this structure
    2487             :    * will contain 1 and 2.
    2488             :    */
    2489             :   std::set<unsigned char> _elem_dims;
    2490             : 
    2491             :   /**
    2492             :    * We cache the (default) order of the geometric elements present in
    2493             :    * the mesh.  E.g. if we have a mesh with TRI3 and TRI6 elements,
    2494             :    * this structure will contain FIRST and SECOND.
    2495             :    */
    2496             :   std::set<Order> _elem_default_orders;
    2497             : 
    2498             :   /**
    2499             :    * We cache the maximum nodal order supported by all the mesh's
    2500             :    * elements (the minimum supported_nodal_order() of any element)
    2501             :    */
    2502             :   Order _supported_nodal_order;
    2503             : 
    2504             :   /**
    2505             :    * We cache the subdomain ids of the elements present in the mesh.
    2506             :    */
    2507             :   std::set<subdomain_id_type> _mesh_subdomains;
    2508             : 
    2509             :   /**
    2510             :    * We also cache the subdomain ids of the elements owned by this
    2511             :    * processor.
    2512             :    */
    2513             :   std::set<subdomain_id_type> _mesh_local_subdomains;
    2514             : 
    2515             :   /**
    2516             :    * Map from "element set code" to list of set ids to which that element
    2517             :    * belongs (and vice-versa). Remarks:
    2518             :    * 1.) The elemset code is a dof_id_type because (if used) it is
    2519             :    * stored as an extra_integer (named "elemset_code") on all elements,
    2520             :    * and extra_integers are of type dof_id_type. Elements which do not
    2521             :    * belong to any set should be assigned an elemset code of DofObject::invalid_id.
    2522             :    * 2.) Element sets can be thought of as a generalization of the concept
    2523             :    * of a subdomain. Subdomains have the following restrictions:
    2524             :    *   a.) A given element can only belong to a single subdomain
    2525             :    *   b.) When using Exodus file input/output, subdomains are (unfortunately)
    2526             :    *   tied to the concept of exodus element blocks, which consist of a single
    2527             :    *   geometric element type, somewhat limiting their generality.
    2528             :    * 3.) The user is responsible for filling in the values of this map
    2529             :    * in a consistent manner, unless the elemsets are read in from an
    2530             :    * Exodus file, in which case the elemset codes will be set up
    2531             :    * automatically. The codes can basically be chosen arbitrarily,
    2532             :    * with the one requirement that elements which belong to no sets
    2533             :    * should have a set code of DofObject::invalid_id.
    2534             :    * 4.) We also keep a list of all the elemset ids which have been added in
    2535             :    * order to support O(1) performance behavior in n_elemsets() calls.
    2536             :    */
    2537             :   std::map<dof_id_type, const MeshBase::elemset_type *> _elemset_codes;
    2538             :   std::map<MeshBase::elemset_type, dof_id_type> _elemset_codes_inverse_map;
    2539             :   MeshBase::elemset_type _all_elemset_ids;
    2540             : 
    2541             :   /**
    2542             :    * The "spatial dimension" of the Mesh.  See the documentation for
    2543             :    * Mesh::spatial_dimension() for more information.
    2544             :    */
    2545             :   unsigned char _spatial_dimension;
    2546             : 
    2547             :   /**
    2548             :    * The array of names for integer data associated with each element
    2549             :    * in the mesh
    2550             :    */
    2551             :   std::vector<std::string> _elem_integer_names;
    2552             : 
    2553             :   /**
    2554             :    * The array of default initialization values for integer data
    2555             :    * associated with each element in the mesh
    2556             :    */
    2557             :   std::vector<dof_id_type> _elem_integer_default_values;
    2558             : 
    2559             :   /**
    2560             :    * The array of names for integer data associated with each node
    2561             :    * in the mesh
    2562             :    */
    2563             :   std::vector<std::string> _node_integer_names;
    2564             : 
    2565             :   /**
    2566             :    * The array of default initialization values for integer data
    2567             :    * associated with each node in the mesh
    2568             :    */
    2569             :   std::vector<dof_id_type> _node_integer_default_values;
    2570             : 
    2571             :   /**
    2572             :    * Size extra-integer arrays of all elements in the mesh
    2573             :    */
    2574             :   void size_elem_extra_integers();
    2575             : 
    2576             :   /**
    2577             :    * Size extra-integer arrays of all nodes in the mesh
    2578             :    */
    2579             :   void size_node_extra_integers();
    2580             : 
    2581             :   /**
    2582             :    * Merge extra-integer arrays from an \p other mesh.  Returns two
    2583             :    * mappings from index values in \p other to (possibly newly created)
    2584             :    * index values with the same string name in \p this mesh, the first
    2585             :    * for element integers and the second for node integers.
    2586             :    */
    2587             :   std::pair<std::vector<unsigned int>, std::vector<unsigned int>>
    2588             :     merge_extra_integer_names(const MeshBase & other);
    2589             : 
    2590             :   /**
    2591             :    * The default geometric GhostingFunctor, used to implement standard
    2592             :    * libMesh element ghosting behavior.  We use a base class pointer
    2593             :    * here to avoid dragging in more header dependencies.
    2594             :    */
    2595             :   std::unique_ptr<GhostingFunctor> _default_ghosting;
    2596             : 
    2597             :   /**
    2598             :    * The list of all GhostingFunctor objects to be used when
    2599             :    * distributing a DistributedMesh.
    2600             :    *
    2601             :    * Basically unused by ReplicatedMesh for now, but belongs to
    2602             :    * MeshBase because the cost is trivial.
    2603             :    */
    2604             :   std::vector<GhostingFunctor *> _ghosting_functors;
    2605             : 
    2606             :   /**
    2607             :    * Hang on to references to any GhostingFunctor objects we were
    2608             :    * passed in shared_ptr form
    2609             :    */
    2610             :   std::map<GhostingFunctor *, std::shared_ptr<GhostingFunctor> > _shared_functors;
    2611             : 
    2612             :   // Keep track of any constraint equations that are inherent to the
    2613             :   // mesh, such as FE nodes whose Rational Bernstein values need to be
    2614             :   // constrained in terms of values on spline control nodes.
    2615             :   //
    2616             :   // _constraint_rows[constrained_node][i].first.first is an
    2617             :   // element (e.g. a NodeElem for a spline control node),
    2618             :   // _constraint_rows[constrained_node][i].first.second is the
    2619             :   // local node id of that element which is a constraining node,
    2620             :   // _constraint_rows[constrained_node][i].second is that node's
    2621             :   // constraint coefficient.
    2622             :   constraint_rows_type _constraint_rows;
    2623             : 
    2624             :   dof_id_type _n_constraint_rows;
    2625             : 
    2626             :   /**
    2627             :    * Helper function for subclasses to use to set _n_constraint_rows
    2628             :    */
    2629             :   dof_id_type count_constraint_rows();
    2630             : 
    2631             :   /**
    2632             :    * If nonzero, we will call PointLocatorBase::set_close_to_point_tol()
    2633             :    * on any PointLocators that we create.
    2634             :    */
    2635             :   Real _point_locator_close_to_point_tol;
    2636             : 
    2637             :   /**
    2638             :    * The partitioner class is a friend so that it can set
    2639             :    * the number of partitions.
    2640             :    */
    2641             :   friend class Partitioner;
    2642             : 
    2643             :   /**
    2644             :    * The MeshInput classes are friends so that they can set the number
    2645             :    * of partitions.
    2646             :    */
    2647             :   friend class MeshInput<MeshBase>;
    2648             : 
    2649             :   /**
    2650             :    * Make the \p BoundaryInfo class a friend so that
    2651             :    * it can create and interact with \p BoundaryMesh.
    2652             :    */
    2653             :   friend class BoundaryInfo;
    2654             : 
    2655             :   /**
    2656             :    * Make the \p MeshCommunication class a friend so that
    2657             :    * it can directly broadcast *_integer_names
    2658             :    */
    2659             :   friend class MeshCommunication;
    2660             : 
    2661             : 
    2662             :   /**
    2663             :    * The original iterator classes weren't properly const-safe;
    2664             :    * relying on their const-incorrectness is now deprecated.
    2665             :    */
    2666             : #ifdef LIBMESH_ENABLE_DEPRECATED
    2667             : typedef variant_filter_iterator<MeshBase::Predicate, Elem *> elem_filter_iter;
    2668             : 
    2669             : typedef variant_filter_iterator<MeshBase::Predicate,
    2670             :                                 Elem * const,
    2671             :                                 Elem * const &,
    2672             :                                 Elem * const *> const_elem_filter_iter;
    2673             : 
    2674             : typedef variant_filter_iterator<MeshBase::Predicate, Node *> node_filter_iter;
    2675             : 
    2676             : typedef variant_filter_iterator<MeshBase::Predicate,
    2677             :                                 Node * const,
    2678             :                                 Node * const &,
    2679             :                                 Node * const *> const_node_filter_iter;
    2680             : #else
    2681             : typedef variant_filter_iterator<MeshBase::Predicate,
    2682             :                                 Elem * const,
    2683             :                                 Elem * const &,
    2684             :                                 Elem * const *,
    2685             :                                 const Elem * const,
    2686             :                                 const Elem * const &,
    2687             :                                 const Elem * const *> elem_filter_iter;
    2688             : 
    2689             : typedef variant_filter_iterator<MeshBase::Predicate,
    2690             :                                 const Elem * const,
    2691             :                                 const Elem * const &,
    2692             :                                 const Elem * const *> const_elem_filter_iter;
    2693             : 
    2694             : typedef variant_filter_iterator<MeshBase::Predicate,
    2695             :                                 Node * const,
    2696             :                                 Node * const &,
    2697             :                                 Node * const *,
    2698             :                                 const Node * const,
    2699             :                                 const Node * const &,
    2700             :                                 const Node * const *> node_filter_iter;
    2701             : 
    2702             : typedef variant_filter_iterator<MeshBase::Predicate,
    2703             :                                 const Node * const,
    2704             :                                 const Node * const &,
    2705             :                                 const Node * const *> const_node_filter_iter;
    2706             : #endif // LIBMESH_ENABLE_DEPRECATED
    2707             : 
    2708             : };
    2709             : 
    2710             : 
    2711             : 
    2712             : 
    2713             : 
    2714             : 
    2715             : 
    2716             : 
    2717             : 
    2718             : 
    2719             : 
    2720             : /**
    2721             :  * The definition of the element_iterator struct.
    2722             :  */
    2723             : struct
    2724    64532387 : MeshBase::element_iterator : MeshBase::elem_filter_iter
    2725             : {
    2726             :   // Templated forwarding ctor -- forwards to appropriate variant_filter_iterator ctor
    2727             :   template <typename PredType, typename IterType>
    2728     1235584 :   element_iterator (const IterType & d,
    2729             :                     const IterType & e,
    2730             :                     const PredType & p ) :
    2731    48967474 :     elem_filter_iter(d,e,p) {}
    2732             : };
    2733             : 
    2734             : 
    2735             : 
    2736             : 
    2737             : /**
    2738             :  * The definition of the const_element_iterator struct.  It is similar to the regular
    2739             :  * iterator above, but also provides an additional conversion-to-const ctor.
    2740             :  */
    2741             : struct
    2742    91028141 : MeshBase::const_element_iterator : MeshBase::const_elem_filter_iter
    2743             : {
    2744             :   /**
    2745             :    * Templated forwarding ctor -- forwards to appropriate variant_filter_iterator ctor.
    2746             :    */
    2747             :   template <typename PredType, typename IterType>
    2748     9558970 :   const_element_iterator (const IterType & d,
    2749             :                           const IterType & e,
    2750             :                           const PredType & p ) :
    2751    57687020 :     const_elem_filter_iter(d,e,p)  {}
    2752             : 
    2753             :   /**
    2754             :    * The conversion-to-const ctor.  Takes a regular iterator and calls the appropriate
    2755             :    * variant_filter_iterator copy constructor.
    2756             :    *
    2757             :    * \note This one is \e not templated!
    2758             :    */
    2759     8306484 :   const_element_iterator (const MeshBase::element_iterator & rhs) :
    2760     4636813 :     const_elem_filter_iter(rhs) {}
    2761             : };
    2762             : 
    2763             : 
    2764             : 
    2765             : 
    2766             : 
    2767             : 
    2768             : 
    2769             : /**
    2770             :  * The definition of the node_iterator struct.
    2771             :  */
    2772             : struct
    2773    13272797 : MeshBase::node_iterator : MeshBase::node_filter_iter
    2774             : {
    2775             :   /**
    2776             :    * Templated forwarding ctor -- forwards to appropriate variant_filter_iterator ctor.
    2777             :    */
    2778             :   template <typename PredType, typename IterType>
    2779      514692 :   node_iterator (const IterType & d,
    2780             :                  const IterType & e,
    2781             :                  const PredType & p ) :
    2782    10183009 :     node_filter_iter(d,e,p)  {}
    2783             : };
    2784             : 
    2785             : 
    2786             : 
    2787             : 
    2788             : /**
    2789             :  * The definition of the const_node_iterator struct.  It is similar to the regular
    2790             :  * iterator above, but also provides an additional conversion-to-const ctor.
    2791             :  */
    2792             : struct
    2793    18487611 : MeshBase::const_node_iterator : MeshBase::const_node_filter_iter
    2794             : {
    2795             :   /**
    2796             :    * Templated forwarding ctor -- forwards to appropriate variant_filter_iterator ctor.
    2797             :    */
    2798             :   template <typename PredType, typename IterType>
    2799      744448 :   const_node_iterator (const IterType & d,
    2800             :                        const IterType & e,
    2801             :                        const PredType & p ) :
    2802    19032055 :     const_node_filter_iter(d,e,p)  {}
    2803             : 
    2804             :   /**
    2805             :    * The conversion-to-const ctor.  Takes a regular iterator and calls the appropriate
    2806             :    * variant_filter_iterator copy constructor.
    2807             :    *
    2808             :    * \note This one is *not* templated!
    2809             :    */
    2810           0 :   const_node_iterator (const MeshBase::node_iterator & rhs) :
    2811           0 :     const_node_filter_iter(rhs) {}
    2812             : };
    2813             : 
    2814             : 
    2815             : // ------------------------------------------------------------
    2816             : // Elem class member functions
    2817             : inline
    2818      130793 : const std::set<unsigned char> & MeshBase::elem_dimensions() const
    2819             : {
    2820      130793 :   libmesh_assert(_preparation.has_cached_elem_data);
    2821      130793 :   return _elem_dims;
    2822             : }
    2823             : 
    2824             : 
    2825             : inline
    2826           0 : const std::set<Order> & MeshBase::elem_default_orders() const
    2827             : {
    2828           0 :   libmesh_assert(_preparation.has_cached_elem_data);
    2829           0 :   return _elem_default_orders;
    2830             : }
    2831             : 
    2832             : 
    2833             : inline
    2834          12 : Order MeshBase::supported_nodal_order() const
    2835             : {
    2836          12 :   libmesh_assert(_preparation.has_cached_elem_data);
    2837         414 :   return _supported_nodal_order;
    2838             : }
    2839             : 
    2840             : 
    2841             : inline
    2842        7830 : unsigned int MeshBase::spatial_dimension () const
    2843             : {
    2844        7830 :   libmesh_assert(_preparation.has_cached_elem_data);
    2845             : 
    2846      240076 :   return cast_int<unsigned int>(_spatial_dimension);
    2847             : }
    2848             : 
    2849             : 
    2850             : inline
    2851       31424 : dof_id_type MeshBase::n_constraint_rows () const
    2852             : {
    2853       31424 :   libmesh_assert(_preparation.has_synched_id_counts);
    2854             : 
    2855      740644 :   return _n_constraint_rows;
    2856             : }
    2857             : 
    2858             : 
    2859             : template <typename T>
    2860             : inline
    2861             : unsigned int MeshBase::add_elem_datum(const std::string & name,
    2862             :                                       bool allocate_data,
    2863             :                                       const T * default_value)
    2864             : {
    2865             :   const std::size_t old_size = _elem_integer_names.size();
    2866             : 
    2867             :   unsigned int n_more_integers = (sizeof(T)-1)/sizeof(dof_id_type);
    2868             :   std::vector<dof_id_type> int_data(n_more_integers+1, DofObject::invalid_id);
    2869             :   if (default_value)
    2870             :     std::memcpy(int_data.data(), default_value, sizeof(T));
    2871             : 
    2872             :   unsigned int start_idx = this->add_elem_integer(name, false, int_data[0]);
    2873             :   for (unsigned int i=0; i != n_more_integers; ++i)
    2874             :     this->add_elem_integer(name+"__"+std::to_string(i), false, int_data[i+1]);
    2875             : 
    2876             :   if (allocate_data && old_size != _elem_integer_names.size())
    2877             :     this->size_elem_extra_integers();
    2878             : 
    2879             :   return start_idx;
    2880             : }
    2881             : 
    2882             : 
    2883             : template <typename T>
    2884             : inline
    2885             : std::vector<unsigned int> MeshBase::add_elem_data(const std::vector<std::string> & names,
    2886             :                                                   bool allocate_data,
    2887             :                                                   const std::vector<T> * default_values)
    2888             : {
    2889             :   libmesh_assert(!default_values || default_values->size() == names.size());
    2890             : 
    2891             :   std::vector<unsigned int> returnval(names.size());
    2892             : 
    2893             :   const std::size_t old_size = _elem_integer_names.size();
    2894             : 
    2895             :   for (auto i : index_range(names))
    2896             :     returnval[i] =
    2897             :       this->add_elem_datum<T>(names[i], false,
    2898             :                               default_values ?
    2899             :                               (*default_values)[i] : nullptr);
    2900             : 
    2901             :   if (allocate_data && old_size != _elem_integer_names.size())
    2902             :     this->size_elem_extra_integers();
    2903             : 
    2904             :   return returnval;
    2905             : }
    2906             : 
    2907             : 
    2908             : template <typename T>
    2909             : inline
    2910          72 : unsigned int MeshBase::add_node_datum(const std::string & name,
    2911             :                                       bool allocate_data,
    2912             :                                       const T * default_value)
    2913             : {
    2914          12 :   const std::size_t old_size = _node_integer_names.size();
    2915             : 
    2916           6 :   unsigned int n_more_integers = (sizeof(T)-1)/sizeof(dof_id_type);
    2917          72 :   std::vector<dof_id_type> int_data(n_more_integers+1, DofObject::invalid_id);
    2918          72 :   if (default_value)
    2919          72 :     std::memcpy(int_data.data(), default_value, sizeof(T));
    2920             : 
    2921          78 :   unsigned int start_idx = this->add_node_integer(name, false, int_data[0]);
    2922          36 :   for (unsigned int i=0; i != n_more_integers; ++i)
    2923          36 :     this->add_node_integer(name+"__"+std::to_string(i), false, int_data[i+1]);
    2924             : 
    2925          72 :   if (allocate_data && old_size != _node_integer_names.size())
    2926          72 :     this->size_node_extra_integers();
    2927             : 
    2928          78 :   return start_idx;
    2929             : }
    2930             : 
    2931             : 
    2932             : template <typename T>
    2933             : inline
    2934             : std::vector<unsigned int> MeshBase::add_node_data(const std::vector<std::string> & names,
    2935             :                                                   bool allocate_data,
    2936             :                                                   const std::vector<T> * default_values)
    2937             : {
    2938             :   libmesh_assert(!default_values || default_values->size() == names.size());
    2939             : 
    2940             :   std::vector<unsigned int> returnval(names.size());
    2941             : 
    2942             :   const std::size_t old_size = _node_integer_names.size();
    2943             : 
    2944             :   for (auto i : index_range(names))
    2945             :     returnval[i] =
    2946             :       this->add_node_datum<T>(names[i], false,
    2947             :                               default_values ?
    2948             :                               (*default_values)[i] : nullptr);
    2949             : 
    2950             :   if (allocate_data && old_size != _node_integer_names.size())
    2951             :     this->size_node_extra_integers();
    2952             : 
    2953             :   return returnval;
    2954             : }
    2955             : 
    2956             : 
    2957             : 
    2958             : } // namespace libMesh
    2959             : 
    2960             : #endif // LIBMESH_MESH_BASE_H

Generated by: LCOV version 1.14