LCOV - code coverage report
Current view: top level - include/base - dof_map.h (source / functions) Hit Total Coverage
Test: libMesh/libmesh: #4417 (f0ff5e) with base 9bbd75 Lines: 221 236 93.6 %
Date: 2026-11-16 16:30:47 Functions: 67 76 88.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_DOF_MAP_H
      21             : #define LIBMESH_DOF_MAP_H
      22             : 
      23             : // Local Includes
      24             : #include "libmesh/libmesh_common.h"
      25             : #include "libmesh/reference_counted_object.h"
      26             : #include "libmesh/libmesh.h" // libMesh::invalid_uint
      27             : #include "libmesh/variable.h"
      28             : #include "libmesh/threads.h"
      29             : #include "libmesh/threads_allocators.h"
      30             : #include "libmesh/elem_range.h"
      31             : #include "libmesh/ghosting_functor.h"
      32             : #include "libmesh/sparsity_pattern.h"
      33             : #include "libmesh/parallel_object.h"
      34             : #include "libmesh/point.h"
      35             : #include "libmesh/utility.h"
      36             : #include "libmesh/elem.h"
      37             : #include "libmesh/fe_interface.h"
      38             : #include "libmesh/libmesh_logging.h"
      39             : #include "libmesh/enum_elem_type.h"
      40             : #include "libmesh/mesh_subdivision_support.h"
      41             : #include "libmesh/dof_map_base.h"
      42             : 
      43             : // TIMPI includes
      44             : #include "timpi/parallel_implementation.h"
      45             : #include "timpi/parallel_sync.h"
      46             : 
      47             : // C++ Includes
      48             : #include <algorithm>
      49             : #include <cstddef>
      50             : #include <iterator>
      51             : #include <map>
      52             : #include <string>
      53             : #include <vector>
      54             : #include <memory>
      55             : 
      56             : namespace libMesh
      57             : {
      58             : 
      59             : // Forward Declarations
      60             : class CouplingMatrix;
      61             : class DefaultCoupling;
      62             : class DirichletBoundary;
      63             : class DirichletBoundaries;
      64             : class DofMap;
      65             : class DofObject;
      66             : class FEType;
      67             : class MeshBase;
      68             : class PeriodicBoundaryBase;
      69             : class PeriodicBoundaries;
      70             : class System;
      71             : class NonlinearImplicitSystem;
      72             : class StaticCondensationDofMap;
      73             : template <typename T> class DenseVectorBase;
      74             : template <typename T> class DenseVector;
      75             : template <typename T> class DenseMatrix;
      76             : template <typename T> class SparseMatrix;
      77             : template <typename T> class NumericVector;
      78             : enum Order : int;
      79             : 
      80             : 
      81             : 
      82             : // ------------------------------------------------------------
      83             : // Do we need constraints for anything?
      84             : 
      85             : #if defined(LIBMESH_ENABLE_AMR) ||              \
      86             :   defined(LIBMESH_ENABLE_PERIODIC) ||           \
      87             :   defined(LIBMESH_ENABLE_DIRICHLET)
      88             : #  define LIBMESH_ENABLE_CONSTRAINTS 1
      89             : #endif
      90             : 
      91             : // ------------------------------------------------------------
      92             : // AMR constraint matrix types
      93             : 
      94             : #ifdef LIBMESH_ENABLE_CONSTRAINTS
      95             : /**
      96             :  * A row of the Dof constraint matrix.
      97             :  */
      98             : typedef std::map<dof_id_type, Real,
      99             :                  std::less<dof_id_type>,
     100             :                  Threads::scalable_allocator<std::pair<const dof_id_type, Real>>> DofConstraintRow;
     101             : 
     102             : /**
     103             :  * The constraint matrix storage format.
     104             :  * We're using a class instead of a typedef to allow forward
     105             :  * declarations and future flexibility.  Don't delete this from
     106             :  * a pointer-to-std-map; the destructor isn't virtual!
     107             :  */
     108      381261 : class DofConstraints : public std::map<dof_id_type,
     109             :                                        DofConstraintRow,
     110             :                                        std::less<dof_id_type>,
     111             :                                        Threads::scalable_allocator<std::pair<const dof_id_type, DofConstraintRow>>>
     112             : {
     113             : };
     114             : 
     115             : /**
     116             :  * Storage for DofConstraint right hand sides for a particular
     117             :  * problem.  Each dof id with a non-zero constraint offset
     118             :  * stores it in such a structure.
     119             :  */
     120      381125 : class DofConstraintValueMap :
     121             :     public std::map<dof_id_type, Number,
     122             :                     std::less<dof_id_type>,
     123             :                     Threads::scalable_allocator<std::pair<const dof_id_type, Number>>>
     124             : {
     125             : };
     126             : 
     127             : /**
     128             :  * Storage for DofConstraint right hand sides for all adjoint
     129             :  * problems.
     130             :  */
     131      381125 : class AdjointDofConstraintValues :
     132             :     public std::map<unsigned int, DofConstraintValueMap,
     133             :                     std::less<unsigned int>,
     134             :                     Threads::scalable_allocator
     135             :                     <std::pair<const unsigned int, DofConstraintValueMap>>>
     136             : {
     137             : };
     138             : 
     139             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
     140             : /**
     141             :  * A row of the Node constraint mapping.  Currently this just
     142             :  * stores the topology of the constrained Nodes, but for forward
     143             :  * compatibility we also include coefficients, so we could add
     144             :  * Lagrange-positioned-node constraints later.
     145             :  */
     146             : typedef std::map<const Node *, Real,
     147             :                  std::less<const Node *>,
     148             :                  Threads::scalable_allocator<std::pair<const Node * const, Real>>> NodeConstraintRow;
     149             : 
     150             : /**
     151             :  * The Node constraint storage format.
     152             :  * We're using a class instead of a typedef to allow forward
     153             :  * declarations and future flexibility.  Don't delete this from
     154             :  * a pointer-to-std-map; the destructor isn't virtual!
     155             :  */
     156       10586 : class NodeConstraints : public std::map<const Node *,
     157             :                                         std::pair<NodeConstraintRow,Point>,
     158             :                                         std::less<const Node *>,
     159             :                                         Threads::scalable_allocator<std::pair<const Node * const, std::pair<NodeConstraintRow,Point>>>>
     160             : {
     161             : };
     162             : #endif // LIBMESH_ENABLE_NODE_CONSTRAINTS
     163             : 
     164             : #endif // LIBMESH_ENABLE_CONSTRAINTS
     165             : 
     166             : 
     167             : 
     168             : /**
     169             :  * This class handles the numbering of degrees of freedom on a mesh.
     170             :  * For systems of equations the class supports a fixed number of variables.
     171             :  * The degrees of freedom are numbered such that sequential, contiguous blocks
     172             :  * belong to distinct processors.  This is so that the resulting data
     173             :  * structures will work well with parallel linear algebra packages.
     174             :  *
     175             :  * \author Benjamin S. Kirk
     176             :  * \date 2002-2007
     177             :  * \brief Manages the degrees of freedom (DOFs) in a simulation.
     178             :  */
     179             : class DofMap : public DofMapBase,
     180             :                public ReferenceCountedObject<DofMap>
     181             : {
     182             : public:
     183             : 
     184             :   /**
     185             :    * Constructor.  Requires the number of the system for which we
     186             :    * will be numbering degrees of freedom & the parent object
     187             :    * we are contained in, which defines our communication space.
     188             :    */
     189             :   explicit
     190             :   DofMap(const unsigned int sys_number,
     191             :          MeshBase & mesh);
     192             : 
     193             :   /**
     194             :    * Destructor.
     195             :    */
     196             :   ~DofMap();
     197             : 
     198             :   /**
     199             :    * Backwards compatibility for prior AugmentSparsityPattern users.
     200             :    */
     201             :   class AugmentSparsityPattern : public SparsityPattern::AugmentSparsityPattern
     202             :   {};
     203             : 
     204             :   /**
     205             :    * Abstract base class to be used to add user-defined parallel
     206             :    * degree of freedom couplings.
     207             :    */
     208             :   class AugmentSendList
     209             :   {
     210             :   public:
     211             :     virtual ~AugmentSendList () = default;
     212             : 
     213             :     /**
     214             :      * User-defined function to augment the send list.
     215             :      */
     216             :     virtual void augment_send_list (std::vector<dof_id_type> & send_list) = 0;
     217             :   };
     218             : 
     219             :   /**
     220             :    * Additional matrices may be attached to this \p DofMap.
     221             :    * They are initialized to the same sparsity structure as
     222             :    * the major matrix.
     223             :    */
     224             :   void attach_matrix (SparseMatrix<Number> & matrix);
     225             : 
     226             :   /**
     227             :    * Additional matrices may be be temporarily initialized by this \p
     228             :    * DofMap.
     229             :    * They are initialized to the same sparsity structure as
     230             :    * the major matrix.
     231             :    */
     232             :   void update_sparsity_pattern(SparseMatrix<Number> & matrix) const;
     233             : 
     234             :   /**
     235             :    * Matrices should not be attached more than once.  We can test for
     236             :    * an already-attached matrix if necessary using \p is_attached
     237             :    */
     238             :   bool is_attached (SparseMatrix<Number> & matrix);
     239             : 
     240             :   /**
     241             :    * Distribute dofs on the current mesh.  Also builds the send list for
     242             :    * processor \p proc_id, which defaults to 0 for ease of use in serial
     243             :    * applications.
     244             :    * \returns The total number of DOFs for the System, summed across all procs.
     245             :    */
     246             :   std::size_t distribute_dofs (MeshBase &);
     247             : 
     248             :   /**
     249             :    * Computes the sparsity pattern for the matrices corresponding to
     250             :    * \p proc_id and sends that data to Linear Algebra packages for
     251             :    * preallocation of sparse matrices.
     252             :    */
     253             :   void compute_sparsity (const MeshBase &);
     254             : 
     255             :   /**
     256             :    * Returns true iff a sparsity pattern has already been computed.
     257             :    */
     258             :   bool computed_sparsity_already () const;
     259             : 
     260             :   /**
     261             :    * Sets the current policy for constructing sparsity patterns: if
     262             :    * \p use_constraints is true (for robustness), we explicitly
     263             :    * account for sparsity entries created by constraint matrix pre-
     264             :    * and post- application.  If \p use_constraints is false (for
     265             :    * speed), we calculate only the sparsity pattern of an
     266             :    * unconstrained matrix.  This is false by default, because in
     267             :    * nearly all applications our constraints do not increase the
     268             :    * number of non-zeros required in a sparse matrix.
     269             :    */
     270             :   void set_constrained_sparsity_construction(bool use_constraints);
     271             : 
     272             :   /**
     273             :    * Sets _need_full_sparsity_pattern to true regardless of the
     274             :    * requirements by matrices
     275             :    */
     276             :   void full_sparsity_pattern_needed();
     277             : 
     278             :   /**
     279             :    * Sets _need_ghost_constraints to true regardless of the requirements
     280             :    * by static condensation
     281             :    */
     282             :   void ghost_constraints_needed();
     283             : 
     284             :   /**
     285             :    * Returns true iff the current policy when constructing sparsity
     286             :    * patterns is to explicitly account for sparsity entries created by
     287             :    * constraint matrix pre- and post- application.
     288             :    */
     289             :   bool constrained_sparsity_construction();
     290             : 
     291             :   /**
     292             :    * Clears the sparsity pattern
     293             :    */
     294             :   void clear_sparsity();
     295             : 
     296             :   /**
     297             :    * Remove any default ghosting functor(s).  User-added ghosting
     298             :    * functors will be unaffected.
     299             :    *
     300             :    * Unless user-added equivalent ghosting functors exist, removing
     301             :    * the default coupling functor is only safe for explicit solves,
     302             :    * and removing the default algebraic ghosting functor is only safe
     303             :    * for codes where no evaluations on neighbor cells (e.g. no jump
     304             :    * error estimators) are done.
     305             :    *
     306             :    * Defaults can be restored manually via add_default_ghosting(), or
     307             :    * automatically if clear() returns the DofMap to a default state.
     308             :    */
     309             :   void remove_default_ghosting();
     310             : 
     311             :   /**
     312             :    * Add the default functor(s) for coupling and algebraic ghosting.
     313             :    * User-added ghosting functors will be unaffected.
     314             :    */
     315             :   void add_default_ghosting();
     316             : 
     317             :   /**
     318             :    * Iterator type for coupling and algebraic ghosting functor ranges.
     319             :    * This has changed in the past and may change again; code should
     320             :    * use auto or the type here.
     321             :    */
     322             :   typedef std::vector<GhostingFunctor *>::const_iterator GhostingFunctorIterator;
     323             : 
     324             :   /**
     325             :    * Adds a functor which can specify coupling requirements for
     326             :    * creation of sparse matrices.
     327             :    * Degree of freedom pairs which match the elements and variables
     328             :    * returned by these functors will be added to the sparsity pattern,
     329             :    * and the degrees of freedom which live on other processors will be
     330             :    * added to the send_list for use on ghosted vectors, and the
     331             :    * elements which live on other processors will be ghosted on a
     332             :    * distributed mesh.
     333             :    *
     334             :    * GhostingFunctor memory must be managed by the code which calls
     335             :    * this function; the GhostingFunctor lifetime is expected to extend
     336             :    * until either the functor is removed or the DofMap is destructed.
     337             :    *
     338             :    * When \p to_mesh is true, the \p coupling_functor is also added to
     339             :    * our associated mesh, to ensure that coupled elements do not get
     340             :    * lost during mesh distribution.  (if coupled elements were
     341             :    * *already* lost there's no getting them back after the fact,
     342             :    * sorry)
     343             :    *
     344             :    * If \p to_mesh is false, no change to mesh ghosting is made;
     345             :    * the Mesh must already have ghosting functor(s) specifying a
     346             :    * superset of \p coupling_functor or this is a horrible bug.
     347             :    */
     348             :   void add_coupling_functor(GhostingFunctor & coupling_functor,
     349             :                             bool to_mesh = true);
     350             : 
     351             :   /**
     352             :    * Adds a functor which can specify coupling requirements for
     353             :    * creation of sparse matrices.
     354             :    *
     355             :    * GhostingFunctor memory when using this method is managed by the
     356             :    * shared_ptr mechanism.
     357             :    */
     358             :   void add_coupling_functor(std::shared_ptr<GhostingFunctor> coupling_functor,
     359             :                             bool to_mesh = true)
     360             :   { _shared_functors[coupling_functor.get()] = coupling_functor;
     361             :     this->add_coupling_functor(*coupling_functor, to_mesh); }
     362             : 
     363             :   /**
     364             :    * Removes a functor which was previously added to the set of
     365             :    * coupling functors, from both this DofMap and from the underlying
     366             :    * mesh.
     367             :    */
     368             :   void remove_coupling_functor(GhostingFunctor & coupling_functor);
     369             : 
     370             :   /**
     371             :    * Beginning of range of coupling functors
     372             :    */
     373      318098 :   GhostingFunctorIterator coupling_functors_begin() const
     374      652094 :   { return _coupling_functors.begin(); }
     375             : 
     376             :   /**
     377             :    * End of range of coupling functors
     378             :    */
     379      318098 :   GhostingFunctorIterator coupling_functors_end() const
     380      652094 :   { return _coupling_functors.end(); }
     381             : 
     382             :   /**
     383             :    * Default coupling functor
     384             :    */
     385           0 :   DefaultCoupling & default_coupling() { return *_default_coupling; }
     386             : 
     387             :   /**
     388             :    * Adds a functor which can specify algebraic ghosting requirements
     389             :    * for use with distributed vectors.  Degrees of freedom on other
     390             :    * processors which match the elements and variables returned by
     391             :    * these functors will be added to the send_list, and the elements
     392             :    * on other processors will be ghosted on a distributed mesh, so
     393             :    * that the elements can always be found and the solutions on them
     394             :    * will always be evaluable.
     395             :    *
     396             :    * GhostingFunctor memory must be managed by the code which calls
     397             :    * this function; the GhostingFunctor lifetime is expected to extend
     398             :    * until either the functor is removed or the DofMap is destructed.
     399             :    *
     400             :    * When \p to_mesh is true, the \p coupling_functor is also added to
     401             :    * our associated mesh, to ensure that evaluable elements do not get
     402             :    * lost during mesh distribution.  (if evaluable elements were
     403             :    * *already* lost there's no getting them back after the fact,
     404             :    * sorry)
     405             :    *
     406             :    * If \p to_mesh is false, no change to mesh ghosting is made;
     407             :    * the Mesh must already have ghosting functor(s) specifying a
     408             :    * superset of \p evaluable_functor or this is a horrible bug.
     409             :    */
     410             :   void add_algebraic_ghosting_functor(GhostingFunctor & evaluable_functor,
     411             :                                       bool to_mesh = true);
     412             : 
     413             :   /**
     414             :    * Adds a functor which can specify algebraic ghosting requirements
     415             :    * for use with distributed vectors.
     416             :    *
     417             :    * GhostingFunctor memory when using this method is managed by the
     418             :    * shared_ptr mechanism.
     419             :    */
     420             :   void add_algebraic_ghosting_functor(std::shared_ptr<GhostingFunctor> evaluable_functor,
     421             :                                       bool to_mesh = true)
     422             :   { _shared_functors[evaluable_functor.get()] = evaluable_functor;
     423             :     this->add_algebraic_ghosting_functor(*evaluable_functor, to_mesh); }
     424             : 
     425             :   /**
     426             :    * Removes a functor which was previously added to the set of
     427             :    * algebraic ghosting functors, from both this DofMap and from the
     428             :    * underlying mesh.
     429             :    */
     430             :   void remove_algebraic_ghosting_functor(GhostingFunctor & evaluable_functor);
     431             : 
     432             :   /**
     433             :    * Beginning of range of algebraic ghosting functors
     434             :    */
     435        1764 :   GhostingFunctorIterator algebraic_ghosting_functors_begin() const
     436       13390 :   { return _algebraic_ghosting_functors.begin(); }
     437             : 
     438             :   /**
     439             :    * End of range of algebraic ghosting functors
     440             :    */
     441        1764 :   GhostingFunctorIterator algebraic_ghosting_functors_end() const
     442       13390 :   { return _algebraic_ghosting_functors.end(); }
     443             : 
     444             :   /**
     445             :    * Default algebraic ghosting functor
     446             :    */
     447           0 :   DefaultCoupling & default_algebraic_ghosting() { return *_default_evaluating; }
     448             : 
     449             :   /**
     450             :    * Attach an object to use to populate the
     451             :    * sparsity pattern with extra entries.
     452             :    *
     453             :    * Care must be taken that when adding entries they are sorted into the Rows
     454             :    *
     455             :    * Further, you _must_ modify n_nz and n_oz properly!
     456             :    *
     457             :    * This is an advanced function... use at your own peril!
     458             :    */
     459             :   void attach_extra_sparsity_object (SparsityPattern::AugmentSparsityPattern & asp)
     460             :   {
     461             :     _augment_sparsity_pattern = &asp;
     462             :   }
     463             : 
     464             :   /**
     465             :    * Attach a function pointer to use as a callback to populate the
     466             :    * sparsity pattern with extra entries.
     467             :    *
     468             :    * Care must be taken that when adding entries they are sorted into the Rows
     469             :    *
     470             :    * Further, you _must_ modify n_nz and n_oz properly!
     471             :    *
     472             :    * This is an advanced function... use at your own peril!
     473             :    */
     474             :   void attach_extra_sparsity_function(void (*func)(SparsityPattern::Graph & sparsity,
     475             :                                                    std::vector<dof_id_type> & n_nz,
     476             :                                                    std::vector<dof_id_type> & n_oz,
     477             :                                                    void *),
     478             :                                       void * context = nullptr)
     479             :   { _extra_sparsity_function = func; _extra_sparsity_context = context; }
     480             : 
     481             :   /**
     482             :    * Attach an object to populate the send_list with extra entries.
     483             :    * This should only add to the send list, but no checking is done
     484             :    * to enforce this behavior.
     485             :    *
     486             :    * This is an advanced function... use at your own peril!
     487             :    */
     488             :   void attach_extra_send_list_object (DofMap::AugmentSendList & asl)
     489             :   {
     490             :     _augment_send_list = &asl;
     491             :   }
     492             : 
     493             :   /**
     494             :    * Attach a function pointer to use as a callback to populate the
     495             :    * send_list with extra entries.
     496             :    */
     497             :   void attach_extra_send_list_function(void (*func)(std::vector<dof_id_type> &, void *),
     498             :                                        void * context = nullptr)
     499             :   { _extra_send_list_function = func; _extra_send_list_context = context; }
     500             : 
     501             :   /**
     502             :    * Takes the \p _send_list vector (which may have duplicate entries)
     503             :    * and sorts it.  The duplicate entries are then removed, resulting in
     504             :    * a sorted \p _send_list with unique entries.  Also calls any user-provided
     505             :    * methods for adding to the send list.
     506             :    */
     507             :   void prepare_send_list ();
     508             : 
     509             :   /**
     510             :    * Clears the \p _send_list vector. This should be done in order to completely
     511             :    * rebuild the send_list from scratch rather than merely adding to the existing
     512             :    * send_list.
     513             :    */
     514       22240 :   void clear_send_list ()
     515             :   {
     516       22240 :     _send_list.clear();
     517       22240 :   }
     518             : 
     519             :   /**
     520             :    * Clears the \p _send_list vector and then rebuilds it. This may be needed
     521             :    * in special situations, for example when an algebraic coupling functor cannot
     522             :    * be added to the \p DofMap until after it is completely setup. Then this method
     523             :    * can be used to rebuild the send_list once the algebraic coupling functor is
     524             :    * added. Note that while this will recommunicate constraints with the updated
     525             :    * send_list, this does assume no new constraints have been added since the previous
     526             :    * reinit_constraints call.
     527             :    */
     528             :   void reinit_send_list (MeshBase & mesh);
     529             : 
     530             : 
     531             :   /**
     532             :    * \returns A constant reference to the \p _send_list for this processor.
     533             :    *
     534             :    * The \p _send_list contains the global indices of all the
     535             :    * variables in the global solution vector that influence the
     536             :    * current processor.  This information can be used for gathers at
     537             :    * each solution step to retrieve solution values needed for
     538             :    * computation.
     539             :    */
     540     2956690 :   const std::vector<dof_id_type> & get_send_list() const { return _send_list; }
     541             : 
     542             :   /**
     543             :    * \returns A constant reference to the \p _n_nz list for this processor.
     544             :    *
     545             :    * The vector contains the bandwidth of the on-processor coupling for each
     546             :    * row of the global matrix that the current processor owns.  This
     547             :    * information can be used to preallocate space for a parallel sparse matrix.
     548             :    */
     549             :   const std::vector<dof_id_type> & get_n_nz() const
     550             :   {
     551             :     libmesh_assert(_sp);
     552             :     return _sp->get_n_nz();
     553             :   }
     554             : 
     555             :   /**
     556             :    * \returns A constant reference to the \p _n_oz list for this processor.
     557             :    *
     558             :    * The vector contains the bandwidth of the off-processor coupling for each
     559             :    * row of the global matrix that the current processor owns.  This
     560             :    * information can be used to preallocate space for a parallel sparse matrix.
     561             :    */
     562             :   const std::vector<dof_id_type> & get_n_oz() const
     563             :   {
     564             :     libmesh_assert(_sp);
     565             :     return _sp->get_n_oz();
     566             :   }
     567             : 
     568             : 
     569             :   /**
     570             :    * \returns A constant pointer to the sparsity pattern stored here,
     571             :    * once that has been computed.  Returns null if no sparsity pattern
     572             :    * has yet been computed.
     573             :    *
     574             :    * If need_full_sparsity_pattern is false, the "sparsity pattern"
     575             :    * may only own n_nz and n_oz lists.
     576             :    */
     577         708 :   const SparsityPattern::Build * get_sparsity_pattern() const
     578             :   {
     579         708 :     return _sp.get();
     580             :   }
     581             : 
     582             :   /**
     583             :    * \returns The number of variables in the system
     584             :    */
     585             :   unsigned int n_vars() const;
     586             : 
     587             :   /**
     588             :    * \returns The name of variable \p i.
     589             :    */
     590             :   const std::string & variable_name(const unsigned int i) const;
     591             : 
     592             :   /**
     593             :    * \returns The total number of scalar components in the system's
     594             :    * variables.  This will equal \p n_vars() in the case of all
     595             :    * scalar-valued variables. If vector variables are involved, we
     596             :    * will need to leverage the \p mesh
     597             :    */
     598             :   unsigned int n_components(const MeshBase & mesh) const;
     599             : 
     600             :   /**
     601             :    * \returns \p true when \p VariableGroup structures should be
     602             :    * automatically identified, \p false otherwise.
     603             :    */
     604             :   bool identify_variable_groups () const;
     605             : 
     606             :   /**
     607             :    * Toggle automatic \p VariableGroup identification.
     608             :    */
     609             :   void identify_variable_groups (const bool);
     610             : 
     611             :   /**
     612             :    * \returns An index, starting from 0 for the first component of the
     613             :    * first variable, and incrementing for each component of each
     614             :    * (potentially vector-valued) variable in the system in order.
     615             :    * For systems with only scalar-valued variables, this will be the
     616             :    * same as \p var_num
     617             :    *
     618             :    * Irony: currently our only non-scalar-valued variable type is
     619             :    * SCALAR.
     620             :    */
     621             :   unsigned int variable_scalar_number (unsigned int var_num,
     622             :                                        unsigned int component) const;
     623             : 
     624             :   /**
     625             :    * \returns The finite element type for variable number \p i.
     626             :    */
     627             :   const FEType & variable_type (const unsigned int i) const;
     628             : 
     629             :   /**
     630             :    * \returns The finite element type for variable \p var.
     631             :    */
     632             :   const FEType & variable_type (std::string_view var) const;
     633             : 
     634             :   /**
     635             :    * \returns The variable number associated with
     636             :    * the user-specified variable named \p var.
     637             :    */
     638             :   unsigned int variable_number (std::string_view var) const;
     639             : 
     640             :   /**
     641             :    * \returns \p true if a variable named \p var exists in this System
     642             :    */
     643             :   bool has_variable(std::string_view var) const;
     644             : 
     645             :   /**
     646             :    * Fills \p all_variable_numbers with all the variable numbers for the
     647             :    * variables that have been added to this system.
     648             :    */
     649             :   void get_all_variable_numbers(std::vector<unsigned int> & all_variable_numbers) const;
     650             : 
     651             :   /**
     652             :    * Adds the variable \p var to the list of variables
     653             :    * for this system. If \p active_subdomains is either \p nullptr
     654             :    * (the default) or points to an empty set, then it will be assumed that
     655             :    * \p var has no subdomain restrictions
     656             :    *
     657             :    * \returns The index number for the new variable.
     658             :    */
     659             :   unsigned int add_variable (System & sys,
     660             :                              std::string_view var,
     661             :                              const FEType & type,
     662             :                              const std::set<subdomain_id_type> * const active_subdomains = nullptr);
     663             : 
     664             :   /**
     665             :    * Adds the variables \p vars to the list of variables
     666             :    * for this system. If \p active_subdomains is either \p nullptr
     667             :    * (the default) or points to an empty set, then it will be assumed that
     668             :    * the \p vars have no subdomain restrictions
     669             :    *
     670             :    * \returns The index number for the last of the new variables.
     671             :    */
     672             :   unsigned int add_variables (System & sys,
     673             :                               const std::vector<std::string> & vars,
     674             :                               const FEType & type,
     675             :                               const std::set<subdomain_id_type> * const active_subdomains = nullptr);
     676             : 
     677             :   /**
     678             :    * Adds variables \p vars to the list of variables
     679             :    * for this system. If \p active_subdomains is either \p nullptr
     680             :    * (the default) or points to an empty set, then it will be assumed that
     681             :    * the \p vars have no subdomain restrictions. This API will end up
     682             :    * calling \p this->add_variables(). However, we will additionally store data
     683             :    * that can be leveraged by the \p DofMap to build degrees of freedom
     684             :    * containers corresponding to all the variables in this variable array
     685             :    *
     686             :    * An 'array variable' is simply a sequence
     687             :    * of contiguous variable numbers defined by pair where the first member of the pair
     688             :    * is the first number in the variable sequence and the second member of the pair is
     689             :    * the number of the last variable in the sequence plus one. Array variables may be
     690             :    * used in tandem with variable grouping by downstream code to build optimized physics
     691             :    * kernels since each variable in the array will have the same shape functions.
     692             :    *
     693             :    * \returns The index number for the last of the new variables.
     694             :    */
     695             :   unsigned int add_variable_array (System & sys,
     696             :                                    const std::vector<std::string> & vars,
     697             :                                    const FEType & type,
     698             :                                    const std::set<subdomain_id_type> * const active_subdomains = nullptr);
     699             : 
     700             :   /**
     701             :    * Specify whether or not we perform an extra (opt-mode enabled) check
     702             :    * for constraint loops. If a constraint loop is present then
     703             :    * the system constraints are not valid, so if \p error_on_constraint_loop
     704             :    * is true we will throw an error in this case.
     705             :    *
     706             :    * \note We previously referred to these types of constraints as
     707             :    * "cyclic" but that has now been deprecated, and these will now
     708             :    * instead be referred to as "constraint loops" in libMesh.
     709             :    */
     710             :   void set_error_on_cyclic_constraint(bool error_on_cyclic_constraint);
     711             :   void set_error_on_constraint_loop(bool error_on_constraint_loop);
     712             : 
     713             :   /**
     714             :    * \returns The \p VariableGroup description object for group \p g.
     715             :    */
     716             :   const VariableGroup & variable_group (const unsigned int c) const;
     717             : 
     718             :   const Variable & variable (const unsigned int c) const override;
     719             : 
     720             :   /**
     721             :    * \returns The approximation order for variable \p c.
     722             :    */
     723             :   Order variable_order (const unsigned int c) const;
     724             : 
     725             :   /**
     726             :    * \returns The approximation order for \p VariableGroup \p vg.
     727             :    */
     728             :   Order variable_group_order (const unsigned int vg) const;
     729             : 
     730             :   /**
     731             :    * \returns The finite element type for \p VariableGroup \p vg.
     732             :    */
     733             :   const FEType & variable_group_type (const unsigned int vg) const;
     734             : 
     735             :   /**
     736             :    * \returns The number of variables in the global solution vector. Defaults
     737             :    * to 1, should be 1 for a scalar equation, 3 for 2D incompressible Navier
     738             :    * Stokes (u,v,p), etc...
     739             :    */
     740    12246682 :   unsigned int n_variable_groups() const
     741    24285980 :   { return cast_int<unsigned int>(_variable_groups.size()); }
     742             : 
     743     1870656 :   unsigned int n_variables() const override
     744     1936256 :   { return cast_int<unsigned int>(_variables.size()); }
     745             : 
     746             :   /**
     747             :    * \returns The variable group number that the provided variable number belongs to
     748             :    */
     749             :   unsigned int var_group_from_var_number(unsigned int var_num) const;
     750             : 
     751             :   /**
     752             :    * \returns \p true if the variables are capable of being stored in a blocked
     753             :    * form.  Presently, this means that there can only be one variable group,
     754             :    * and that the group has more than one variable.
     755             :    */
     756       46600 :   bool has_blocked_representation() const
     757             :   {
     758       48088 :     return ((this->n_variable_groups() == 1) && (this->n_variables() > 1));
     759             :   }
     760             : 
     761             :   /**
     762             :    * \returns The block size, if the variables are amenable to block storage.
     763             :    * Otherwise 1.
     764             :    * This routine was originally designed to enable a blocked storage, but
     765             :    * it turns out this information is still super useful for solvers even when
     766             :    * we do not use the blocked storage (e.g., MATMPIBAIJ in PETSc). For example (in PCHMG),
     767             :    * for a system of PDEs, to construct an efficient multilevel preconditioner, we coarsen
     768             :    * the matrix of one single PDE instead of the entire huge matrix. In order to
     769             :    * accomplish this, we need to know many PDEs we have. Another use case,
     770             :    * the fieldsplit preconditioner can be constructed in place with this info without
     771             :    * involving any user efforts.
     772             :    */
     773       48088 :   unsigned int block_size() const
     774             :   {
     775       46738 :     return (this->has_blocked_representation() ? this->n_variables() : 1);
     776             :   }
     777             : 
     778             :   using DofMapBase::n_dofs;
     779             :   /**
     780             :    * \returns The total number of degrees of freedom for a particular
     781             :    * variable \p vn.
     782             :    */
     783             :   dof_id_type n_dofs(const unsigned int vn) const
     784             :   {
     785             :     dof_id_type n = this->n_local_dofs(vn);
     786             :     this->comm().sum(n);
     787             :     return n;
     788             :   }
     789             : 
     790             :   /**
     791             :    * \returns The number of SCALAR dofs.
     792             :    */
     793      395381 :   dof_id_type n_SCALAR_dofs() const { return _n_SCALAR_dofs; }
     794             : 
     795             :   using DofMapBase::n_local_dofs;
     796             :   /**
     797             :    * \returns The number of degrees of freedom on this processor for a
     798             :    * particular variable \p vn.  This is an O(N) operation on serialized or
     799             :    * O(N/Nproc) operation on distributed meshes.
     800             :    */
     801           0 :   dof_id_type n_local_dofs(const unsigned int vn) const
     802             :   {
     803             :     dof_id_type n;
     804           0 :     this->local_variable_indices(n, _mesh, vn);
     805           0 :     return n;
     806             :   }
     807             : 
     808             :   /**
     809             :    * \returns The number of degrees of freedom on each partition for a
     810             :    * particular variable \p vn.
     811             :    */
     812         804 :   std::vector<dof_id_type> n_dofs_per_processor(const unsigned int vn) const
     813             :   {
     814         804 :     std::vector<dof_id_type> n_local_dofs(this->n_processors(), 0);
     815         804 :     this->comm().allgather(this->n_local_dofs(vn), n_local_dofs);
     816         804 :     return n_local_dofs;
     817             :   }
     818             : 
     819             :   /**
     820             :    * \returns The processor id that owns the dof index \p dof
     821             :    */
     822      254285 :   processor_id_type dof_owner(const dof_id_type dof) const
     823             :   { std::vector<dof_id_type>::const_iterator ub =
     824      254285 :       std::upper_bound(_end_df.begin(), _end_df.end(), dof);
     825        7481 :     libmesh_assert (ub != _end_df.end());
     826      254285 :     return cast_int<processor_id_type>(ub - _end_df.begin());
     827             :   }
     828             : 
     829             :   void dof_indices (const Elem * const elem,
     830             :                     std::vector<dof_id_type> & di) const;
     831             : 
     832             :   /**
     833             :    * Fills the vector \p di with the global degree of freedom indices
     834             :    * for the element.  For one variable, and potentially for a
     835             :    * non-default element p refinement level
     836             :    */
     837             :   void dof_indices (const Elem * const elem,
     838             :                     std::vector<dof_id_type> & di,
     839             :                     const unsigned int vn,
     840             :                     int p_level = -12345) const override;
     841             : 
     842             :   /**
     843             :    * Fills the vector \p di with the global degree of freedom indices
     844             :    * for the element. This will aggregate all the degrees of the freedom
     845             :    * from the variable array that \p vn is a member of, and potentially for a
     846             :    * non-default element p refinement level
     847             :    */
     848             :   void array_dof_indices(const Elem * const elem,
     849             :                          std::vector<dof_id_type> & di,
     850             :                          const unsigned int vn,
     851             :                          int p_level = -12345) const;
     852             : 
     853             :   void array_dof_indices(const Node * const node,
     854             :                          std::vector<dof_id_type> & di,
     855             :                          const unsigned int vn) const;
     856             : 
     857             :   template <typename DofIndicesFunctor>
     858             :   void array_dof_indices(const DofIndicesFunctor & functor,
     859             :                          std::vector<dof_id_type> & di,
     860             :                          const unsigned int vn) const;
     861             : 
     862             :   /**
     863             :    * Retrieves degree of freedom indices for a given \p elem and then performs actions for these
     864             :    * indices defined by the user-provided functors \p scalar_dofs_functor and \p field_dofs_functor.
     865             :    * This API is useful when a user wants to do more than simply fill a degree of freedom container
     866             :    * @param elem The element to get degrees of freedom for
     867             :    * @param di A container for degrees of freedom. It is up to the provided functors how this gets
     868             :    *           filled
     869             :    * @param vn The variable number to retrieve degrees of freedom for
     870             :    * @param scalar_dofs_functor The functor that acts on scalar degrees of freedom. This functor has
     871             :    *                            the interface:
     872             :    *                            void scalar_dofs_functor(const Elem & elem,
     873             :    *                                                    std::vector<dof_id_type> & di,
     874             :    *                                                    const std::vector<dof_id_type> & scalar_dof_indices)
     875             :    *                            where \p di is the degree of freedom container described above and
     876             :    *                            \p scalar_dof_indices are the scalar dof indices available to
     877             :    *                            \p elem
     878             :    * @param field_dofs_functor The functor that acts on "field" (e.g. non-scalar, non-global)
     879             :    *                           degrees of freedom. This functor has
     880             :    *                           the interface:
     881             :    *                           void field_dofs_functor(const Elem & elem,
     882             :    *                                                   const unsigned int node_num,
     883             :    *                                                   const unsigned int var_num,
     884             :    *                                                   std::vector<dof_id_type> & di,
     885             :    *                                                   const dof_id_type field_dof)
     886             :    *                           where \p field_dof represents a field degree of freedom to act on and
     887             :    *                           is associated with \p node_num and \p var_num. If the degree of
     888             :    *                           freedom is elemental than \p node_num will be \p invalid_uint. \p di
     889             :    *                           is again the degree of freedom container provided above
     890             :    */
     891             :   template <typename ScalarDofsFunctor, typename FieldDofsFunctor>
     892             :   void dof_indices(const Elem * const elem,
     893             :                    std::vector<dof_id_type> & di,
     894             :                    const unsigned int vn,
     895             :                    ScalarDofsFunctor scalar_dofs_functor,
     896             :                    FieldDofsFunctor field_dofs_functor,
     897             :                    int p_level = -12345) const;
     898             : 
     899             :   /**
     900             :    * Fills the vector \p di with the global degree of freedom indices
     901             :    * for the \p node.
     902             :    */
     903             :   void dof_indices (const Node * const node,
     904             :                     std::vector<dof_id_type> & di) const;
     905             : 
     906             :   /**
     907             :    * Fills the vector \p di with the global degree of freedom indices
     908             :    * for the \p node, for one variable \p vn.
     909             :    */
     910             :   void dof_indices (const Node * const node,
     911             :                     std::vector<dof_id_type> & di,
     912             :                     const unsigned int vn) const override;
     913             : 
     914             :   /**
     915             :    * Appends to the vector \p di the global degree of freedom indices
     916             :    * for \p elem.node_ref(n), for one variable \p vn.  On hanging
     917             :    * nodes with both vertex and non-vertex DoFs, only those indices
     918             :    * which are directly supported on \p elem are included.
     919             :    */
     920             :   void dof_indices (const Elem & elem,
     921             :                     unsigned int n,
     922             :                     std::vector<dof_id_type> & di,
     923             :                     const unsigned int vn) const;
     924             : 
     925             : #ifdef LIBMESH_ENABLE_AMR
     926             : 
     927             :   /**
     928             :    * Appends to the vector \p di the old global degree of freedom
     929             :    * indices for \p elem.node_ref(n), for one variable \p vn.  On
     930             :    * hanging nodes with both vertex and non-vertex DoFs, only those
     931             :    * indices which are directly supported on \p elem are included.
     932             :    */
     933             :   void old_dof_indices (const Elem & elem,
     934             :                         unsigned int n,
     935             :                         std::vector<dof_id_type> & di,
     936             :                         const unsigned int vn) const;
     937             : 
     938             : #endif // LIBMESH_ENABLE_AMR
     939             : 
     940             :   /**
     941             :    * Fills the vector \p di with the global degree of freedom indices
     942             :    * corresponding to the SCALAR variable vn. If old_dofs=true,
     943             :    * the old SCALAR dof indices are returned.
     944             :    *
     945             :    * \note We do not need to pass in an element since SCALARs are
     946             :    * global variables.
     947             :    */
     948             :   void SCALAR_dof_indices (std::vector<dof_id_type> & di,
     949             :                            const unsigned int vn,
     950             :                            const bool old_dofs=false) const;
     951             : 
     952             :   /**
     953             :    * \returns \p true if degree of freedom index \p dof_index
     954             :    * is either a local index or in the \p send_list.
     955             :    *
     956             :    * \note This is an O(logN) operation for a send_list of size N; we
     957             :    * don't cache enough information for O(1) right now.
     958             :    */
     959             :   bool semilocal_index (dof_id_type dof_index) const;
     960             : 
     961             :   /**
     962             :    * \returns \p true if all degree of freedom indices in \p
     963             :    * dof_indices are either local indices or in the \p send_list.
     964             :    *
     965             :    * \note This is an O(logN) operation for a send_list of size N; we
     966             :    * don't cache enough information for O(1) right now.
     967             :    */
     968             :   bool all_semilocal_indices (const std::vector<dof_id_type> & dof_indices) const;
     969             : 
     970             :   /**
     971             :    * \returns \p true if degree of freedom index \p dof_index
     972             :    * is a local index.
     973             :    */
     974    80333628 :   bool local_index (dof_id_type dof_index) const
     975    87454170 :   { return (dof_index >= this->first_dof()) && (dof_index < this->end_dof()); }
     976             : 
     977             :   /**
     978             :    * \returns \p true iff our solutions can be locally evaluated on
     979             :    * \p obj (which should be an Elem or a Node) for variable number \p
     980             :    * var_num (for all variables, if \p var_num is invalid_uint)
     981             :    */
     982             :   template <typename DofObjectSubclass>
     983             :   bool is_evaluable(const DofObjectSubclass & obj,
     984             :                     unsigned int var_num = libMesh::invalid_uint) const;
     985             : 
     986             :   /**
     987             :    * Allow the implicit_neighbor_dofs flag to be set programmatically.
     988             :    * This overrides the --implicit_neighbor_dofs commandline option.
     989             :    * We can use this to set the implicit neighbor dofs option differently
     990             :    * for different systems, whereas the commandline option is the same
     991             :    * for all systems.
     992             :    */
     993             :   void set_implicit_neighbor_dofs(bool implicit_neighbor_dofs);
     994             : 
     995             :   /**
     996             :    * Set the _verify_dirichlet_bc_consistency flag.
     997             :    */
     998             :   void set_verify_dirichlet_bc_consistency(bool val);
     999             : 
    1000             :   /**
    1001             :    * Tells other library functions whether or not this problem
    1002             :    * includes coupling between dofs in neighboring cells, as can
    1003             :    * currently be specified on the command line or inferred from
    1004             :    * the use of all discontinuous variables.
    1005             :    */
    1006             :   bool use_coupled_neighbor_dofs(const MeshBase & mesh) const;
    1007             : 
    1008             :   /**
    1009             :    * Builds the local element vector \p Ue from the global vector \p Ug,
    1010             :    * accounting for any constrained degrees of freedom.  For an element
    1011             :    * without constrained degrees of freedom this is the trivial mapping
    1012             :    * \f$ Ue[i] = Ug[dof_indices[i]] \f$
    1013             :    *
    1014             :    * \note The user must ensure that the element vector \p Ue is
    1015             :    * properly sized when calling this method.  This is because there
    1016             :    * is no \p resize() method in the \p DenseVectorBase<> class.
    1017             :    */
    1018             :   void extract_local_vector (const NumericVector<Number> & Ug,
    1019             :                              const std::vector<dof_id_type> & dof_indices,
    1020             :                              DenseVectorBase<Number> & Ue) const;
    1021             : 
    1022             :   /**
    1023             :    * If T == dof_id_type, counts, if T == std::vector<dof_id_type>, fills an
    1024             :    * array of, those dof indices which belong to the given variable number and
    1025             :    * live on the current processor.
    1026             :    */
    1027             :   template <typename T, std::enable_if_t<std::is_same_v<T, dof_id_type> ||
    1028             :                                          std::is_same_v<T, std::vector<dof_id_type>>, int> = 0>
    1029             :   void local_variable_indices(T & idx,
    1030             :                               const MeshBase & mesh,
    1031             :                               unsigned int var_num) const;
    1032             : 
    1033             :   /**
    1034             :    * If T == dof_id_type, counts, if T == std::vector<dof_id_type>, fills an
    1035             :    * array of, those dof indices which belong to the given variable number and
    1036             :    * live on the current processor.
    1037             :    */
    1038             :   template <typename T,
    1039             :             std::enable_if_t<std::is_same_v<T, dof_id_type> ||
    1040             :                                  std::is_same_v<T, std::vector<dof_id_type>>,
    1041             :                              int> = 0>
    1042             :   void local_variable_indices(T & idx, unsigned int var_num) const
    1043             :   { this->local_variable_indices(idx, this->_mesh, var_num); }
    1044             : 
    1045             : #ifdef LIBMESH_ENABLE_CONSTRAINTS
    1046             : 
    1047             :   //--------------------------------------------------------------------
    1048             :   // Constraint-specific methods
    1049             :   /**
    1050             :    * \returns The total number of constrained degrees of freedom
    1051             :    * in the problem.
    1052             :    */
    1053             :   dof_id_type n_constrained_dofs() const;
    1054             : 
    1055             :   /**
    1056             :    * \returns The number of constrained degrees of freedom
    1057             :    * on this processor.
    1058             :    */
    1059             :   dof_id_type n_local_constrained_dofs() const;
    1060             : 
    1061             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
    1062             :   /**
    1063             :    * \returns The total number of constrained Nodes
    1064             :    * in the mesh.
    1065             :    */
    1066             :   dof_id_type n_constrained_nodes() const
    1067             :   { return cast_int<dof_id_type>(_node_constraints.size()); }
    1068             : #endif // LIBMESH_ENABLE_NODE_CONSTRAINTS
    1069             : 
    1070             :   /**
    1071             :    * Rebuilds the raw degree of freedom and DofObject constraints,
    1072             :    * based on attached DirichletBoundary objects and on non-conforming
    1073             :    * interface in adapted meshes.
    1074             :    *
    1075             :    * A time is specified for use in building time-dependent Dirichlet
    1076             :    * constraints.
    1077             :    */
    1078             :   void create_dof_constraints (const MeshBase &, Real time=0);
    1079             : 
    1080             :   /**
    1081             :    * Recomputes the DirichletBoundary constraint values at a new \p
    1082             :    * time. The result is the same as that of create_dof_constraints()
    1083             :    * at \p time.
    1084             :    *
    1085             :    * Only the DirichletBoundary values change with time. The degrees
    1086             :    * of freedom that each DirichletBoundary claims depend only on the
    1087             :    * mesh. The hanging-node, periodic and p-refinement constraints also
    1088             :    * depend only on the mesh. Thus create_dof_constraints() keeps a
    1089             :    * copy of the constraints that it builds before it applies the
    1090             :    * DirichletBoundary objects. It also records the local elements that
    1091             :    * carry a DirichletBoundary id. This method restores that copy. Then
    1092             :    * it applies the DirichletBoundary objects again, on those elements
    1093             :    * only and in the same order. Thus overlapping boundaries resolve as
    1094             :    * they do in create_dof_constraints(). Last, it processes any spline
    1095             :    * constraint rows of the mesh, as create_dof_constraints() does.
    1096             :    *
    1097             :    * This method calls create_dof_constraints() instead if one of these
    1098             :    * conditions is true:
    1099             :    * - No copy matches the current degrees of freedom and boundaries.
    1100             :    * - There are no DirichletBoundary objects.
    1101             :    *
    1102             :    * As after create_dof_constraints(), add any user constraints and
    1103             :    * then call process_constraints().
    1104             :    * System::reinit_dirichlet_constraint_values() does these steps.
    1105             :    */
    1106             :   void reinit_dirichlet_constraint_values (const MeshBase & mesh, Real time);
    1107             : 
    1108             :   /**
    1109             :    * Gathers constraint equation dependencies from other processors
    1110             :    */
    1111             :   void allgather_recursive_constraints (MeshBase &);
    1112             : 
    1113             :   /**
    1114             :    * Sends constraint equations to constraining processors
    1115             :    */
    1116             :   void scatter_constraints (MeshBase &);
    1117             : 
    1118             :   /**
    1119             :    * Helper function for querying about constraint equations on other
    1120             :    * processors.  If any id in \p requested_dof_ids is constrained on
    1121             :    * another processor, its constraint will be added on this processor
    1122             :    * as well.  If \p look_for_constrainees is true, then constraints
    1123             :    * will also be returned if the id appears as a constraining value
    1124             :    * not just if it appears as a constrained value.
    1125             :    *
    1126             :    * This function operates recursively: if the constraint for a
    1127             :    * constrained dof is newly added locally, then any other dofs which
    1128             :    * constrain it are queried to see if they are in turn constrained,
    1129             :    * and so on.
    1130             :    */
    1131             :   void gather_constraints (MeshBase & mesh,
    1132             :                            std::set<dof_id_type> & unexpanded_dofs,
    1133             :                            bool look_for_constrainees);
    1134             : 
    1135             :   /**
    1136             :    * Postprocesses any constrained degrees of freedom
    1137             :    * to be constrained only in terms of unconstrained dofs, then adds
    1138             :    * unconstrained dofs to the send_list and prepares that for use.
    1139             :    * This should be run after both system (create_dof_constraints) and
    1140             :    * user constraints have all been added.
    1141             :    */
    1142             :   void process_constraints (MeshBase &);
    1143             : 
    1144             :   /**
    1145             :    * Throw an error if we detect any constraint loops, i.e.
    1146             :    * A -> B -> C -> A
    1147             :    * that is, "dof A is constrained in terms of dof B which is
    1148             :    * constrained in terms of dof C which is constrained in terms of
    1149             :    * dof A", since these are not supported by libMesh and give
    1150             :    * erroneous results if they are present.
    1151             :    *
    1152             :    * \note The original "cyclic constraint" terminology was
    1153             :    * unfortunate since the word cyclic is used by some software to
    1154             :    * indicate an actual type of rotational/angular constraint and not
    1155             :    * (as here) a cyclic graph. The former nomenclature will eventually
    1156             :    * be deprecated in favor of "constraint loop".
    1157             :    */
    1158             :   void check_for_cyclic_constraints();
    1159             :   void check_for_constraint_loops();
    1160             : 
    1161             :   /**
    1162             :    * Adds a copy of the user-defined row to the constraint matrix, using
    1163             :    * an inhomogeneous right-hand-side for the constraint equation.
    1164             :    */
    1165             :   void add_constraint_row (const dof_id_type dof_number,
    1166             :                            const DofConstraintRow & constraint_row,
    1167             :                            const Number constraint_rhs,
    1168             :                            const bool forbid_constraint_overwrite);
    1169             : 
    1170             :   /**
    1171             :    * Adds a copy of the user-defined row to the constraint matrix,
    1172             :    * using an inhomogeneous right-hand-side for the adjoint constraint
    1173             :    * equation.
    1174             :    *
    1175             :    * \p forbid_constraint_overwrite here only tests for overwriting
    1176             :    * the rhs.  This method should only be used when an equivalent
    1177             :    * constraint (with a potentially different rhs) already exists for
    1178             :    * the primal problem.
    1179             :    */
    1180             :   void add_adjoint_constraint_row (const unsigned int qoi_index,
    1181             :                                    const dof_id_type dof_number,
    1182             :                                    const DofConstraintRow & constraint_row,
    1183             :                                    const Number constraint_rhs,
    1184             :                                    const bool forbid_constraint_overwrite);
    1185             : 
    1186             :   /**
    1187             :    * Adds a copy of the user-defined row to the constraint matrix, using
    1188             :    * a homogeneous right-hand-side for the constraint equation.
    1189             :    * By default, produces an error if the DOF was already constrained.
    1190             :    */
    1191       17640 :   void add_constraint_row (const dof_id_type dof_number,
    1192             :                            const DofConstraintRow & constraint_row,
    1193             :                            const bool forbid_constraint_overwrite = true)
    1194      231622 :   { add_constraint_row(dof_number, constraint_row, 0., forbid_constraint_overwrite); }
    1195             : 
    1196             :   /**
    1197             :    * \returns An iterator pointing to the first DoF constraint row.
    1198             :    */
    1199             :   DofConstraints::const_iterator constraint_rows_begin() const
    1200             :   { return _dof_constraints.begin(); }
    1201             : 
    1202             :   /**
    1203             :    * \returns An iterator pointing just past the last DoF constraint row.
    1204             :    */
    1205             :   DofConstraints::const_iterator constraint_rows_end() const
    1206             :   { return _dof_constraints.end(); }
    1207             : 
    1208             :   /**
    1209             :    * Provide a const accessor to the DofConstraints map. This allows the user
    1210             :    * to quickly search the data structure rather than just iterating over it.
    1211             :    */
    1212      220801 :   const DofConstraints & get_dof_constraints() const { return _dof_constraints; }
    1213             : 
    1214             :   void stash_dof_constraints()
    1215             :   {
    1216             :     libmesh_assert(_stashed_dof_constraints.empty());
    1217             :     _dof_constraints.swap(_stashed_dof_constraints);
    1218             :   }
    1219             : 
    1220             :   void unstash_dof_constraints()
    1221             :   {
    1222             :     libmesh_assert(_dof_constraints.empty());
    1223             :     _dof_constraints.swap(_stashed_dof_constraints);
    1224             :   }
    1225             : 
    1226             :   /**
    1227             :    * Similar to the stash/unstash_dof_constraints() API, but swaps
    1228             :    * _dof_constraints and _stashed_dof_constraints without asserting
    1229             :    * that the source or destination is empty first.
    1230             :    *
    1231             :    * \note There is an implicit assumption that swapping between sets
    1232             :    * of Constraints does not change the sparsity pattern or expand the
    1233             :    * send_list, since the only thing changed is the DofConstraints
    1234             :    * themselves.  This is intended to work for swapping between
    1235             :    * DofConstraints A and B, where A is used to define the send_list,
    1236             :    * and B is a subset of A.
    1237             :    */
    1238             :   void swap_dof_constraints()
    1239             :   {
    1240             :     _dof_constraints.swap(_stashed_dof_constraints);
    1241             :   }
    1242             : 
    1243             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
    1244             :   /**
    1245             :    * \returns An iterator pointing to the first Node constraint row.
    1246             :    */
    1247             :   NodeConstraints::const_iterator node_constraint_rows_begin() const
    1248             :   { return _node_constraints.begin(); }
    1249             : 
    1250             :   /**
    1251             :    * \returns An iterator pointing just past the last Node constraint row.
    1252             :    */
    1253             :   NodeConstraints::const_iterator node_constraint_rows_end() const
    1254             :   { return _node_constraints.end(); }
    1255             : #endif // LIBMESH_ENABLE_NODE_CONSTRAINTS
    1256             : 
    1257             :   /**
    1258             :    * \returns \p true if the degree of freedom dof is constrained,
    1259             :    * \p false otherwise.
    1260             :    */
    1261             :   bool is_constrained_dof (const dof_id_type dof) const;
    1262             : 
    1263             :   /**
    1264             :    * \returns \p true if the system has any heterogeneous constraints for
    1265             :    * adjoint solution \p qoi_num, \p false otherwise.
    1266             :    */
    1267             :   bool has_heterogeneous_adjoint_constraints (const unsigned int qoi_num) const;
    1268             : 
    1269             :   /**
    1270             :    * Backwards compatibility with misspelling.
    1271             :    */
    1272        3072 :   bool has_heterogenous_adjoint_constraints (const unsigned int qoi_num) const
    1273             :   {
    1274       79722 :     return this->has_heterogeneous_adjoint_constraints (qoi_num);
    1275             :   }
    1276             : 
    1277             :   /**
    1278             :    * \returns The heterogeneous constraint value if the degree of
    1279             :    * freedom \p dof has a heterogeneous constraint for adjoint solution
    1280             :    * \p qoi_num, zero otherwise.
    1281             :    */
    1282             :   Number has_heterogeneous_adjoint_constraint (const unsigned int qoi_num,
    1283             :                                                const dof_id_type dof) const;
    1284             : 
    1285             :   /**
    1286             :    * Backwards compatibility with misspelling.
    1287             :    */
    1288     1093446 :   Number has_heterogenous_adjoint_constraint (const unsigned int qoi_num,
    1289             :                                               const dof_id_type dof) const
    1290             :   {
    1291     1414426 :     return this->has_heterogeneous_adjoint_constraint (qoi_num, dof);
    1292             :   }
    1293             : 
    1294             :   /**
    1295             :    * \returns A reference to the set of right-hand-side values in
    1296             :    * primal constraint equations
    1297             :    */
    1298             :   DofConstraintValueMap & get_primal_constraint_values();
    1299             : 
    1300             :   /**
    1301             :    * \returns \p true if the Node is constrained,
    1302             :    * false otherwise.
    1303             :    */
    1304             :   bool is_constrained_node (const Node * node) const;
    1305             : 
    1306             :   /**
    1307             :    * Prints (from processor 0) all DoF and Node constraints.  If \p
    1308             :    * print_nonlocal is true, then each constraint is printed once for
    1309             :    * each processor that knows about it, which may be useful for \p
    1310             :    * DistributedMesh debugging.
    1311             :    */
    1312             :   void print_dof_constraints(std::ostream & os=libMesh::out,
    1313             :                              bool print_nonlocal=false) const;
    1314             : 
    1315             :   /**
    1316             :    * Gets a string reporting all DoF and Node constraints local to
    1317             :    * this processor.  If \p print_nonlocal is true, then nonlocal
    1318             :    * constraints which are locally known are included.
    1319             :    */
    1320             :   std::string get_local_constraints(bool print_nonlocal=false) const;
    1321             : 
    1322             : 
    1323             :   /**
    1324             :    * Tests the constrained degrees of freedom on the numeric vector \p v, which
    1325             :    * represents a solution defined on the mesh, returning a pair whose first
    1326             :    * entry is the maximum absolute error on a constrained DoF and whose second
    1327             :    * entry is the maximum relative error.  Useful for debugging purposes.
    1328             :    *
    1329             :    * If \p v == nullptr, the system solution vector is tested.
    1330             :    */
    1331             :   std::pair<Real, Real> max_constraint_error(const System & system,
    1332             :                                              NumericVector<Number> * v = nullptr) const;
    1333             : 
    1334             : #endif // LIBMESH_ENABLE_CONSTRAINTS
    1335             : 
    1336             :   //--------------------------------------------------------------------
    1337             :   // Constraint-specific methods
    1338             :   // Some of these methods are enabled (but inlined away to nothing)
    1339             :   // when constraints are disabled at configure-time.  This is to
    1340             :   // increase API compatibility of user code with different library
    1341             :   // builds.
    1342             : 
    1343             :   /**
    1344             :    * Constrains the element matrix.  This method requires the
    1345             :    * element matrix to be square, in which case the elem_dofs
    1346             :    * correspond to the global DOF indices of both the rows and
    1347             :    * columns of the element matrix.  For this case the rows
    1348             :    * and columns of the matrix necessarily correspond to variables
    1349             :    * of the same approximation order.
    1350             :    *
    1351             :    * If \p asymmetric_constraint_rows is set to true (as it is by
    1352             :    * default), constraint row equations will be reinforced in a way
    1353             :    * which breaks matrix symmetry but makes inexact linear solver
    1354             :    * solutions more likely to satisfy hanging node constraints.
    1355             :    */
    1356             :   void constrain_element_matrix (DenseMatrix<Number> & matrix,
    1357             :                                  std::vector<dof_id_type> & elem_dofs,
    1358             :                                  bool asymmetric_constraint_rows = true) const;
    1359             : 
    1360             :   /**
    1361             :    * Constrains the element matrix.  This method allows the
    1362             :    * element matrix to be non-square, in which case the row_dofs
    1363             :    * and col_dofs may be of different size and correspond to
    1364             :    * variables approximated in different spaces.
    1365             :    */
    1366             :   void constrain_element_matrix (DenseMatrix<Number> & matrix,
    1367             :                                  std::vector<dof_id_type> & row_dofs,
    1368             :                                  std::vector<dof_id_type> & col_dofs,
    1369             :                                  bool asymmetric_constraint_rows = true) const;
    1370             : 
    1371             :   /**
    1372             :    * Constrains the element vector.
    1373             :    */
    1374             :   void constrain_element_vector (DenseVector<Number> & rhs,
    1375             :                                  std::vector<dof_id_type> & dofs,
    1376             :                                  bool asymmetric_constraint_rows = true) const;
    1377             : 
    1378             :   /**
    1379             :    * Constrains the element matrix and vector.  This method requires
    1380             :    * the element matrix to be square, in which case the elem_dofs
    1381             :    * correspond to the global DOF indices of both the rows and
    1382             :    * columns of the element matrix.  For this case the rows
    1383             :    * and columns of the matrix necessarily correspond to variables
    1384             :    * of the same approximation order.
    1385             :    */
    1386             :   void constrain_element_matrix_and_vector (DenseMatrix<Number> & matrix,
    1387             :                                             DenseVector<Number> & rhs,
    1388             :                                             std::vector<dof_id_type> & elem_dofs,
    1389             :                                             bool asymmetric_constraint_rows = true) const;
    1390             : 
    1391             :   /**
    1392             :    * Constrains the element matrix and vector.  This method requires
    1393             :    * the element matrix to be square, in which case the elem_dofs
    1394             :    * correspond to the global DOF indices of both the rows and
    1395             :    * columns of the element matrix.  For this case the rows
    1396             :    * and columns of the matrix necessarily correspond to variables
    1397             :    * of the same approximation order.
    1398             :    *
    1399             :    * The heterogeneous version of this method creates linear systems in
    1400             :    * which heterogeneously constrained degrees of freedom will solve to
    1401             :    * their correct offset values, as would be appropriate for finding
    1402             :    * a solution to a linear problem in a single algebraic solve.  The
    1403             :    * non-heterogeneous version of this method creates linear systems in
    1404             :    * which even heterogeneously constrained degrees of freedom are
    1405             :    * solved without offset values taken into account, as would be
    1406             :    * appropriate for finding linearized updates to a solution in which
    1407             :    * heterogeneous constraints are already satisfied.
    1408             :    *
    1409             :    * By default, the constraints for the primal solution of this
    1410             :    * system are used.  If a non-negative \p qoi_index is passed in,
    1411             :    * then the constraints for the corresponding adjoint solution are
    1412             :    * used instead.
    1413             :    */
    1414             :   void heterogeneously_constrain_element_matrix_and_vector (DenseMatrix<Number> & matrix,
    1415             :                                                             DenseVector<Number> & rhs,
    1416             :                                                             std::vector<dof_id_type> & elem_dofs,
    1417             :                                                             bool asymmetric_constraint_rows = true,
    1418             :                                                             int qoi_index = -1) const;
    1419             : 
    1420             :   /*
    1421             :    * Backwards compatibility with misspelling.
    1422             :    */
    1423           0 :   void heterogenously_constrain_element_matrix_and_vector (DenseMatrix<Number> & matrix,
    1424             :                                                            DenseVector<Number> & rhs,
    1425             :                                                            std::vector<dof_id_type> & elem_dofs,
    1426             :                                                            bool asymmetric_constraint_rows = true,
    1427             :                                                            int qoi_index = -1) const
    1428             :   {
    1429             :     return this->heterogeneously_constrain_element_matrix_and_vector
    1430       15527 :       (matrix, rhs, elem_dofs, asymmetric_constraint_rows, qoi_index);
    1431             :   }
    1432             : 
    1433             :   /**
    1434             :    * Constrains the element vector.  This method requires
    1435             :    * the element matrix to be square and not-yet-constrained, in which
    1436             :    * case the elem_dofs correspond to the global DOF indices of both
    1437             :    * the rows and columns of the element matrix.
    1438             :    *
    1439             :    * The heterogeneous version of this method creates linear systems in
    1440             :    * which heterogeneously constrained degrees of freedom will solve to
    1441             :    * their correct offset values, as would be appropriate for finding
    1442             :    * a solution to a linear problem in a single algebraic solve.  The
    1443             :    * non-heterogeneous version of this method creates linear systems in
    1444             :    * which even heterogeneously constrained degrees of freedom are
    1445             :    * solved without offset values taken into account, as would be
    1446             :    * appropriate for finding linearized updates to a solution in which
    1447             :    * heterogeneous constraints are already satisfied.
    1448             :    *
    1449             :    * Note the sign difference from the nonlinear heterogeneous constraint
    1450             :    * method: Solving u:=K\f has the opposite sign convention from
    1451             :    * u:=u_in-J\r, and we apply heterogeneous constraints accordingly.
    1452             :    *
    1453             :    * By default, the constraints for the primal solution of this
    1454             :    * system are used.  If a non-negative \p qoi_index is passed in,
    1455             :    * then the constraints for the corresponding adjoint solution are
    1456             :    * used instead.
    1457             :    */
    1458             :   void heterogeneously_constrain_element_vector (const DenseMatrix<Number> & matrix,
    1459             :                                                  DenseVector<Number> & rhs,
    1460             :                                                  std::vector<dof_id_type> & elem_dofs,
    1461             :                                                  bool asymmetric_constraint_rows = true,
    1462             :                                                  int qoi_index = -1) const;
    1463             : 
    1464             :   /*
    1465             :    * Backwards compatibility with misspelling.
    1466             :    */
    1467         140 :   void heterogenously_constrain_element_vector (const DenseMatrix<Number> & matrix,
    1468             :                                                 DenseVector<Number> & rhs,
    1469             :                                                 std::vector<dof_id_type> & elem_dofs,
    1470             :                                                 bool asymmetric_constraint_rows = true,
    1471             :                                                 int qoi_index = -1) const
    1472             :   {
    1473             :     return this->heterogeneously_constrain_element_vector
    1474        1680 :       (matrix, rhs, elem_dofs, asymmetric_constraint_rows, qoi_index);
    1475             :   }
    1476             : 
    1477             :   /**
    1478             :    * Constrains the element Jacobian and residual.  The element
    1479             :    * Jacobian is square, and the elem_dofs should correspond to the
    1480             :    * global DOF indices of both the rows and columns of the element
    1481             :    * matrix.
    1482             :    *
    1483             :    * The residual-constraining version of this method creates linear
    1484             :    * systems in which heterogeneously constrained degrees of freedom
    1485             :    * create non-zero residual terms when not at their correct offset
    1486             :    * values, as would be appropriate for finding a solution to a
    1487             :    * nonlinear problem in a quasi-Newton solve.
    1488             :    *
    1489             :    * Note the sign difference from the linear heterogeneous constraint
    1490             :    * method: Solving u:=u_in-J\r has the opposite sign convention from
    1491             :    * u:=K\f, and we apply heterogeneous constraints accordingly.
    1492             :    *
    1493             :    * The \p solution vector passed in should be a serialized or
    1494             :    * ghosted primal solution
    1495             :    */
    1496             :   void heterogeneously_constrain_element_jacobian_and_residual (DenseMatrix<Number> & matrix,
    1497             :                                                                 DenseVector<Number> & rhs,
    1498             :                                                                 std::vector<dof_id_type> & elem_dofs,
    1499             :                                                                 NumericVector<Number> & solution_local) const;
    1500             : 
    1501             :   /**
    1502             :    * Constrains the element residual.  The element Jacobian is square,
    1503             :    * and the elem_dofs should correspond to the global DOF indices of
    1504             :    * both the rows and columns of the element matrix.
    1505             :    *
    1506             :    * The residual-constraining version of this method creates linear
    1507             :    * systems in which heterogeneously constrained degrees of freedom
    1508             :    * create non-zero residual terms when not at their correct offset
    1509             :    * values, as would be appropriate for finding a solution to a
    1510             :    * nonlinear problem in a quasi-Newton solve.
    1511             :    *
    1512             :    * The \p solution vector passed in should be a serialized or
    1513             :    * ghosted primal solution
    1514             :    */
    1515             :   void heterogeneously_constrain_element_residual (DenseVector<Number> & rhs,
    1516             :                                                    std::vector<dof_id_type> & elem_dofs,
    1517             :                                                    NumericVector<Number> & solution_local) const;
    1518             : 
    1519             : 
    1520             :   /**
    1521             :    * Constrains the element residual.  The element Jacobian is square,
    1522             :    * and the elem_dofs should correspond to the global DOF indices of
    1523             :    * both the rows and columns of the element matrix, and the dof
    1524             :    * constraint should not include any heterogeneous terms.
    1525             :    *
    1526             :    * The residual-constraining version of this method creates linear
    1527             :    * systems in which heterogeneously constrained degrees of freedom
    1528             :    * create non-zero residual terms when not at their correct offset
    1529             :    * values, as would be appropriate for finding a solution to a
    1530             :    * nonlinear problem in a quasi-Newton solve.
    1531             :    *
    1532             :    * The \p solution vector passed in should be a serialized or
    1533             :    * ghosted primal solution
    1534             :    */
    1535             :   void constrain_element_residual (DenseVector<Number> & rhs,
    1536             :                                    std::vector<dof_id_type> & elem_dofs,
    1537             :                                    NumericVector<Number> & solution_local) const;
    1538             : 
    1539             :   /**
    1540             :    * Constrains a dyadic element matrix B = v w'.  This method
    1541             :    * requires the element matrix to be square, in which case the
    1542             :    * elem_dofs correspond to the global DOF indices of both the rows
    1543             :    * and columns of the element matrix.  For this case the rows and
    1544             :    * columns of the matrix necessarily correspond to variables of the
    1545             :    * same approximation order.
    1546             :    */
    1547             :   void constrain_element_dyad_matrix (DenseVector<Number> & v,
    1548             :                                       DenseVector<Number> & w,
    1549             :                                       std::vector<dof_id_type> & row_dofs,
    1550             :                                       bool asymmetric_constraint_rows = true) const;
    1551             : 
    1552             :   /**
    1553             :    * Does not actually constrain anything, but modifies \p dofs in the
    1554             :    * same way as any of the constrain functions would do, i.e. adds
    1555             :    * those dofs in terms of which any of the existing dofs is
    1556             :    * constrained.
    1557             :    */
    1558             :   void constrain_nothing (std::vector<dof_id_type> & dofs) const;
    1559             : 
    1560             :   /**
    1561             :    * Constrains the numeric vector \p v, which represents a solution defined on
    1562             :    * the mesh.  This may need to be used after a linear solve, if your linear
    1563             :    * solver's solutions do not satisfy your DoF constraints to a tight enough
    1564             :    * tolerance.
    1565             :    *
    1566             :    * If \p v == nullptr, the system solution vector is constrained
    1567             :    *
    1568             :    * If \p homogeneous == true, heterogeneous constraints are enforced
    1569             :    * as if they were homogeneous.  This might be appropriate for e.g. a
    1570             :    * vector representing a difference between two
    1571             :    * heterogeneously-constrained solutions.
    1572             :    */
    1573             :   void enforce_constraints_exactly (const System & system,
    1574             :                                     NumericVector<Number> * v = nullptr,
    1575             :                                     bool homogeneous = false) const;
    1576             : 
    1577             :   /**
    1578             :    * Heterogeneously constrains the numeric vector \p v, which
    1579             :    * represents an adjoint solution defined on the mesh for quantity
    1580             :    * fo interest \p q.  For homogeneous constraints, use \p
    1581             :    * enforce_constraints_exactly instead
    1582             :    */
    1583             :   void enforce_adjoint_constraints_exactly (NumericVector<Number> & v,
    1584             :                                             unsigned int q) const;
    1585             : 
    1586             :   void enforce_constraints_on_residual (const NonlinearImplicitSystem & system,
    1587             :                                         NumericVector<Number> * rhs,
    1588             :                                         NumericVector<Number> const * solution,
    1589             :                                         bool homogeneous = true) const;
    1590             : 
    1591             :   void enforce_constraints_on_jacobian (const NonlinearImplicitSystem & system,
    1592             :                                         SparseMatrix<Number> * jac) const;
    1593             : 
    1594             : #ifdef LIBMESH_ENABLE_PERIODIC
    1595             : 
    1596             :   //--------------------------------------------------------------------
    1597             :   // PeriodicBoundary-specific methods
    1598             : 
    1599             :   /**
    1600             :    * Adds a copy of the specified periodic boundary to the system.
    1601             :    */
    1602             :   void add_periodic_boundary (const PeriodicBoundaryBase & periodic_boundary);
    1603             : 
    1604             :   /**
    1605             :    * Add a periodic boundary pair
    1606             :    *
    1607             :    * \param boundary - primary boundary
    1608             :    * \param inverse_boundary - inverse boundary
    1609             :    */
    1610             :   void add_periodic_boundary (const PeriodicBoundaryBase & boundary, const PeriodicBoundaryBase & inverse_boundary);
    1611             : 
    1612             :   /**
    1613             :    * \returns \p true if the boundary given by \p boundaryid is periodic,
    1614             :    * false otherwise
    1615             :    */
    1616             :   bool is_periodic_boundary (const boundary_id_type boundaryid) const;
    1617             : 
    1618             :   PeriodicBoundaries * get_periodic_boundaries()
    1619             :   {
    1620             :     return _periodic_boundaries.get();
    1621             :   }
    1622             : 
    1623             :   const PeriodicBoundaries * get_periodic_boundaries() const
    1624             :   {
    1625             :     return _periodic_boundaries.get();
    1626             :   }
    1627             : 
    1628             : #endif // LIBMESH_ENABLE_PERIODIC
    1629             : 
    1630             : 
    1631             : #ifdef LIBMESH_ENABLE_DIRICHLET
    1632             : 
    1633             :   //--------------------------------------------------------------------
    1634             :   // DirichletBoundary-specific methods
    1635             : 
    1636             :   /**
    1637             :    * Adds a copy of the specified Dirichlet boundary to the system.
    1638             :    *
    1639             :    * The constraints implied by DirichletBoundary objects are imposed
    1640             :    * in the same order in which DirichletBoundary objects are added to
    1641             :    * the DofMap. When multiple DirichletBoundary objects would impose
    1642             :    * competing constraints on a given DOF, the *first*
    1643             :    * DirichletBoundary to constrain the DOF "wins". This distinction
    1644             :    * is important when e.g. two surfaces (sidesets) intersect. The
    1645             :    * nodes on the intersection will be constrained according to
    1646             :    * whichever sideset's DirichletBoundary object was added to the
    1647             :    * DofMap first.
    1648             :    */
    1649             :   void add_dirichlet_boundary (const DirichletBoundary & dirichlet_boundary);
    1650             : 
    1651             :   /**
    1652             :    * Adds a copy of the specified Dirichlet boundary to the system,
    1653             :    * corresponding to the adjoint problem defined by Quantity of
    1654             :    * Interest \p q.
    1655             :    */
    1656             :   void add_adjoint_dirichlet_boundary (const DirichletBoundary & dirichlet_boundary,
    1657             :                                        unsigned int q);
    1658             : 
    1659             :   /**
    1660             :    * Removes the specified Dirichlet boundary from the system.
    1661             :    */
    1662             :   void remove_dirichlet_boundary (const DirichletBoundary & dirichlet_boundary);
    1663             : 
    1664             :   /**
    1665             :    * Removes from the system the specified Dirichlet boundary for the
    1666             :    * adjoint equation defined by Quantity of interest index q
    1667             :    */
    1668             :   void remove_adjoint_dirichlet_boundary (const DirichletBoundary & dirichlet_boundary,
    1669             :                                           unsigned int q);
    1670             : 
    1671             :   const DirichletBoundaries * get_dirichlet_boundaries() const
    1672             :   {
    1673             :     return _dirichlet_boundaries.get();
    1674             :   }
    1675             : 
    1676          24 :   DirichletBoundaries * get_dirichlet_boundaries()
    1677             :   {
    1678          24 :     return _dirichlet_boundaries.get();
    1679             :   }
    1680             : 
    1681             :   bool has_adjoint_dirichlet_boundaries(unsigned int q) const;
    1682             : 
    1683             :   const DirichletBoundaries *
    1684             :   get_adjoint_dirichlet_boundaries(unsigned int q) const;
    1685             : 
    1686             :   DirichletBoundaries *
    1687             :   get_adjoint_dirichlet_boundaries(unsigned int q);
    1688             : 
    1689             :   /**
    1690             :    * Check that all the ids in dirichlet_bcids are actually present in the mesh.
    1691             :    * If not, this will throw an error.
    1692             :    */
    1693             :   void check_dirichlet_bcid_consistency (const MeshBase & mesh,
    1694             :                                          const DirichletBoundary & boundary) const;
    1695             : 
    1696             : private:
    1697             :   /**
    1698             :    * Adds the constraints of each primal and adjoint DirichletBoundary
    1699             :    * at \p time on the elements of \p range.
    1700             :    *
    1701             :    * \returns If \p record_elems is true, the elements of \p range
    1702             :    * that carry a DirichletBoundary id, sorted by id. Otherwise, an
    1703             :    * empty vector.
    1704             :    */
    1705             :   std::vector<const Elem *> apply_dirichlet_boundaries (const MeshBase & mesh,
    1706             :                                                         Real time,
    1707             :                                                         ConstElemRange & range,
    1708             :                                                         bool record_elems);
    1709             : 
    1710             : public:
    1711             : #endif // LIBMESH_ENABLE_DIRICHLET
    1712             : 
    1713             : 
    1714             : #ifdef LIBMESH_ENABLE_AMR
    1715             : 
    1716             :   //--------------------------------------------------------------------
    1717             :   // AMR-specific methods
    1718             : 
    1719             :   /**
    1720             :    * After a mesh is refined and repartitioned it is possible that the
    1721             :    * \p _send_list will need to be augmented.  This is the case when an
    1722             :    * element is refined and its children end up on different processors
    1723             :    * than the parent.  These children will need values from the parent
    1724             :    * when projecting the solution onto the refined mesh, hence the parent's
    1725             :    * DOF indices need to be included in the \p _send_list.
    1726             :    */
    1727             :   // void augment_send_list_for_projection(const MeshBase &);
    1728             : 
    1729             : #ifdef LIBMESH_ENABLE_AMR
    1730             : 
    1731             :   /**
    1732             :    * Fills the vector di with the global degree of freedom indices
    1733             :    * for the element using the \p DofMap::old_dof_object.
    1734             :    * If no variable number is specified then all
    1735             :    * variables are returned.
    1736             :    */
    1737             :   void old_dof_indices (const Elem * const elem,
    1738             :                         std::vector<dof_id_type> & di,
    1739             :                         const unsigned int vn = libMesh::invalid_uint) const;
    1740             : 
    1741             : #endif // LIBMESH_ENABLE_AMR
    1742             : 
    1743             :   /**
    1744             :    * Constrains degrees of freedom on side \p s of element \p elem which
    1745             :    * correspond to variable number \p var and to p refinement levels
    1746             :    * above \p p.
    1747             :    */
    1748             :   void constrain_p_dofs (unsigned int var,
    1749             :                          const Elem * elem,
    1750             :                          unsigned int s,
    1751             :                          unsigned int p);
    1752             : 
    1753             : #endif // LIBMESH_ENABLE_AMR
    1754             : 
    1755             :   /**
    1756             :    * Reinitialize the underlying data structures conformal to the current mesh.
    1757             :    */
    1758             :   void reinit
    1759             :     (MeshBase & mesh,
    1760             :      const std::map<const Node *, std::set<subdomain_id_type>> &
    1761             :        constraining_subdomains);
    1762             : 
    1763             :   /**
    1764             :    * Free all new memory associated with the object, but restore its
    1765             :    * original state, with the mesh pointer and any default ghosting.
    1766             :    */
    1767             :   virtual void clear () override;
    1768             : 
    1769             :   /**
    1770             :    * Prints summary info about the sparsity bandwidth and constraints.
    1771             :    */
    1772             :   void print_info(std::ostream & os=libMesh::out) const;
    1773             : 
    1774             :   /**
    1775             :    * Gets summary info about the sparsity bandwidth and constraints.
    1776             :    */
    1777             :   std::string get_info() const;
    1778             : 
    1779             :   /**
    1780             :    * Degree of freedom coupling.  If left empty each DOF
    1781             :    * couples to all others.  Can be used to reduce memory
    1782             :    * requirements for sparse matrices.  DOF 0 might only
    1783             :    * couple to itself, in which case \p dof_coupling(0,0)
    1784             :    * should be 1 and \p dof_coupling(0,j) = 0 for j not equal
    1785             :    * to 0.
    1786             :    *
    1787             :    * This variable is named as though it were class private,
    1788             :    * but it is in the public interface.  Also there are no
    1789             :    * public methods for accessing it...  This typically means
    1790             :    * you should only use it if you know what you are doing.
    1791             :    */
    1792             :   CouplingMatrix * _dof_coupling;
    1793             : 
    1794             :   /**
    1795             :    * \returns The number of the system we are responsible for.
    1796             :    */
    1797             :   unsigned int sys_number() const;
    1798             : 
    1799             :   /**
    1800             :    * Builds a sparsity pattern for matrices using the current
    1801             :    * degree-of-freedom numbering and coupling.
    1802             :    *
    1803             :    * By default, ignores constraint equations, for build speed; this
    1804             :    * is valid for the combination of !need_full_sparsity_pattern and
    1805             :    * constraints which only come from periodic boundary conditions and
    1806             :    * adaptive mesh refinement, where matrix constraint adds some
    1807             :    * matrix entries but removes equally many (or more) other entries.
    1808             :    *
    1809             :    * Can be told to calculate sparsity for the constrained matrix,
    1810             :    * which may be necessary in the case of spline control node
    1811             :    * constraints or sufficiently many user constraints.
    1812             :    */
    1813             :   std::unique_ptr<SparsityPattern::Build> build_sparsity(const MeshBase & mesh,
    1814             :                                                          bool calculate_constrained = false,
    1815             :                                                          bool use_condensed_system = false) const;
    1816             : 
    1817             :   /**
    1818             :    * Set whether the given variable group should be p-refined on a
    1819             :    * p-refined Elem.  This changes the FEType of the variable group to
    1820             :    * enable or disable p-refinement.
    1821             :    */
    1822             :   void should_p_refine(unsigned int g, bool p_refine);
    1823             : 
    1824             :   /**
    1825             :    * Whether the given variable group should be p-refined
    1826             :    */
    1827             :   bool should_p_refine(unsigned int g) const;
    1828             : 
    1829             :   /**
    1830             :    * Whether the given variable should be p-refined
    1831             :    */
    1832             :   bool should_p_refine_var(unsigned int var) const;
    1833             : 
    1834             :   // Prevent bad user implicit conversions
    1835             :   void should_p_refine(FEFamily, bool) = delete;
    1836             :   void should_p_refine(Order, bool) = delete;
    1837             :   bool should_p_refine(FEFamily) const = delete;
    1838             :   bool should_p_refine(Order) const = delete;
    1839             : 
    1840             :   /**
    1841             :    * Add a static condensation class
    1842             :    */
    1843             :   void create_static_condensation(MeshBase & mesh, System & system);
    1844             : 
    1845             :   /**
    1846             :    * Checks whether we have static condensation
    1847             :    */
    1848       91080 :   bool has_static_condensation() const { return _sc.get(); }
    1849             : 
    1850             :   /**
    1851             :    * @returns the static condensation class. This should have been already added with a call to \p
    1852             :    * add_static_condensation()
    1853             :    */
    1854             :   StaticCondensationDofMap & get_static_condensation();
    1855             : 
    1856             :   /**
    1857             :    * @returns the static condensation class. This should have been already added with a call to \p
    1858             :    * add_static_condensation()
    1859             :    */
    1860             :   const StaticCondensationDofMap & get_static_condensation() const;
    1861             : 
    1862             :   /**
    1863             :    * Calls reinit on the static condensation map if it exists
    1864             :    */
    1865             :   void reinit_static_condensation();
    1866             : 
    1867             : private:
    1868             : 
    1869             :   /**
    1870             :    * Retrieve the array variable bounds for a given variable \p vi. This variable may
    1871             :    * lie anywhere within an array variable range. An 'array variable' is simply a sequence
    1872             :    * of contiguous variable numbers defined by pair where the first member of the pair
    1873             :    * is the first number in the variable sequence and the second member of the pair is
    1874             :    * the number of the last variable in the sequence plus one. Array variables may be
    1875             :    * used in tandem with variable grouping by downstream code to build optimized physics
    1876             :    * kernels since each variable in the array will have the same shape functions.
    1877             :    *
    1878             :    * We note that we store array variables as a container of the above described pairs. Within
    1879             :    * this API we will do a binary search such that the complexity is O(log(N)) where N is the
    1880             :    * number of array variables present in \p this
    1881             :    */
    1882             :   const std::pair<unsigned int, unsigned int> &
    1883             :   get_variable_array(unsigned int vi) const;
    1884             : 
    1885             :   /**
    1886             :    * Helper function that gets the dof indices on the current element
    1887             :    * for a non-SCALAR type variable, where the variable is identified
    1888             :    * by its variable group number \p vg and its offset \p vig from the
    1889             :    * first variable in that group.
    1890             :    *
    1891             :    * In DEBUG mode, the tot_size parameter will add up the total
    1892             :    * number of dof indices that should have been added to di, and v
    1893             :    * will be the variable number corresponding to vg and vig.
    1894             :    */
    1895             :   void _dof_indices (const Elem & elem,
    1896             :                      int p_level,
    1897             :                      std::vector<dof_id_type> & di,
    1898             :                      const unsigned int vg,
    1899             :                      const unsigned int vig,
    1900             :                      const Node * const * nodes,
    1901             :                      unsigned int       n_nodes,
    1902             :                      const unsigned int v
    1903             : #ifdef DEBUG
    1904             :                      ,
    1905             :                      std::size_t & tot_size
    1906             : #endif
    1907             :                     ) const;
    1908             : 
    1909             :   /**
    1910             :    * As above except a \p field_dofs_functor must be provided. This method is useful when the caller
    1911             :    * wants to do more than simply fill a degree of freedom container
    1912             :    * @param field_dofs_functor This functor has the interface:
    1913             :    *                           void field_dofs_functor(const Elem & elem,
    1914             :    *                                                   const unsigned int node_num,
    1915             :    *                                                   const unsigned int var_num,
    1916             :    *                                                   std::vector<dof_id_type> & di,
    1917             :    *                                                   const dof_id_type field_dof)
    1918             :    *                           where \p field_dof represents a field degree of freedom to act on and
    1919             :    *                           is associated with \p node_num and \p var_num. If the degree of
    1920             :    *                           freedom is elemental than \p node_num will be \p invalid_uint. \p di
    1921             :    *                           is the degree of freedom container provided to the \p _dof_indices
    1922             :    *                           method
    1923             :    */
    1924             :   template <typename FieldDofsFunctor>
    1925             :   void _dof_indices (const Elem & elem,
    1926             :                      int p_level,
    1927             :                      std::vector<dof_id_type> & di,
    1928             :                      const unsigned int vg,
    1929             :                      const unsigned int vig,
    1930             :                      const Node * const * nodes,
    1931             :                      unsigned int       n_nodes,
    1932             :                      const unsigned int v,
    1933             : #ifdef DEBUG
    1934             :                      std::size_t & tot_size,
    1935             : #endif
    1936             :                      FieldDofsFunctor field_dofs_functor) const;
    1937             : 
    1938             :   /**
    1939             :    * Helper function that implements the element-nodal versions of
    1940             :    * dof_indices and old_dof_indices
    1941             :    */
    1942             :   void _node_dof_indices (const Elem & elem,
    1943             :                           unsigned int n,
    1944             :                           const DofObject & obj,
    1945             :                           std::vector<dof_id_type> & di,
    1946             :                           const unsigned int vn) const;
    1947             : 
    1948             :   /**
    1949             :    * Invalidates all active DofObject dofs for this system
    1950             :    */
    1951             :   void invalidate_dofs(MeshBase & mesh) const;
    1952             : 
    1953             :   /**
    1954             :    * \returns The Node pointer with index \p i from the \p mesh.
    1955             :    */
    1956             :   DofObject * node_ptr(MeshBase & mesh, dof_id_type i) const;
    1957             : 
    1958             :   /**
    1959             :    * \returns The Elem pointer with index \p i from the \p mesh.
    1960             :    */
    1961             :   DofObject * elem_ptr(MeshBase & mesh, dof_id_type i) const;
    1962             : 
    1963             :   /**
    1964             :    * A member function type like \p node_ptr() or \p elem_ptr().
    1965             :    */
    1966             :   typedef DofObject * (DofMap::*dofobject_accessor)
    1967             :     (MeshBase & mesh, dof_id_type i) const;
    1968             : 
    1969             :   /**
    1970             :    * Helper function for distributing dofs in parallel
    1971             :    */
    1972             :   template<typename iterator_type>
    1973             :   void set_nonlocal_dof_objects(iterator_type objects_begin,
    1974             :                                 iterator_type objects_end,
    1975             :                                 MeshBase & mesh,
    1976             :                                 dofobject_accessor objects);
    1977             : 
    1978             :   /**
    1979             :    * We may have mesh constraint rows with dependent nodes in one
    1980             :    * subdomain but dependency nodes in another subdomain, and we may
    1981             :    * have variables whose subdomain restriction includes the dependent
    1982             :    * subdomain but not the dependency.  In those cases we need to
    1983             :    * place degrees of freedom on dependency nodes anyway.
    1984             :    *
    1985             :    * The set value for node n will include all subdomain ids of
    1986             :    * elements with nodes in subdomains constrained by n.
    1987             :    *
    1988             :    * We use a map<set> rather than a multimap here because we expect
    1989             :    * to be inserting the same subdomain multiple times and we don't
    1990             :    * need duplicate values.
    1991             :    */
    1992             :   std::map<const Node *, std::set<subdomain_id_type>>
    1993             :   calculate_constraining_subdomains();
    1994             : 
    1995             :   /**
    1996             :    * Distributes the global degrees of freedom, for dofs on
    1997             :    * this processor.  In this format the local
    1998             :    * degrees of freedom are in a contiguous block for each
    1999             :    * variable in the system.
    2000             :    * Starts at index next_free_dof, and increments it to
    2001             :    * the post-final index.
    2002             :    *
    2003             :    * Uses the provided constraining_subdomains map from
    2004             :    * calculate_constraining_subdomains() to ensure allocation of all
    2005             :    * DoFs on constraining nodes.
    2006             :    */
    2007             :   void distribute_local_dofs_var_major
    2008             :     (dof_id_type & next_free_dof,
    2009             :      MeshBase & mesh,
    2010             :      const std::map<const Node *, std::set<subdomain_id_type>> &
    2011             :        constraining_subdomains);
    2012             : 
    2013             :   /**
    2014             :    * Distributes the global degrees of freedom for dofs on this
    2015             :    * processor.  In this format all the degrees of freedom at a
    2016             :    * node/element are in contiguous blocks.  Starts at index \p
    2017             :    * next_free_dof, and increments it to the post-final index.  If \p
    2018             :    * build_send_list is \p true, builds the send list.  If \p false,
    2019             :    * clears and reserves the send list.
    2020             :    *
    2021             :    * Uses the provided constraining_subdomains map from
    2022             :    * calculate_constraining_subdomains() to ensure allocation of all
    2023             :    * DoFs on constraining nodes.
    2024             :    *
    2025             :    * \note The degrees of freedom for a given variable are not in
    2026             :    * contiguous blocks, as in the case of \p distribute_local_dofs_var_major.
    2027             :    */
    2028             :   void distribute_local_dofs_node_major
    2029             :     (dof_id_type & next_free_dof,
    2030             :      MeshBase & mesh,
    2031             :      const std::map<const Node *, std::set<subdomain_id_type>> &
    2032             :        constraining_subdomains);
    2033             : 
    2034             :   /*
    2035             :    * Helper method for the above two to count + distriubte SCALAR dofs
    2036             :    */
    2037             :   void distribute_scalar_dofs (dof_id_type & next_free_dof);
    2038             : 
    2039             : #ifdef DEBUG
    2040             :   /*
    2041             :    * Internal assertions for distribute_local_dofs_*
    2042             :    */
    2043             :   void assert_no_nodes_missed(MeshBase & mesh);
    2044             : #endif
    2045             : 
    2046             :   /*
    2047             :    * A utility method for obtaining a set of elements to ghost along
    2048             :    * with merged coupling matrices.
    2049             :    */
    2050             :   typedef std::set<std::unique_ptr<CouplingMatrix>, Utility::CompareUnderlying> CouplingMatricesSet;
    2051             :   static void
    2052             :   merge_ghost_functor_outputs (GhostingFunctor::map_type & elements_to_ghost,
    2053             :                                CouplingMatricesSet & temporary_coupling_matrices,
    2054             :                                const GhostingFunctorIterator & gf_begin,
    2055             :                                const GhostingFunctorIterator & gf_end,
    2056             :                                const MeshBase::const_element_iterator & elems_begin,
    2057             :                                const MeshBase::const_element_iterator & elems_end,
    2058             :                                processor_id_type p);
    2059             : 
    2060             :   /**
    2061             :    * Adds entries to the \p _send_list vector corresponding to DoFs
    2062             :    * on elements neighboring the current processor.
    2063             :    */
    2064             :   void add_neighbors_to_send_list(MeshBase & mesh);
    2065             : 
    2066             : #ifdef LIBMESH_ENABLE_CONSTRAINTS
    2067             : 
    2068             :   /**
    2069             :    * Build the constraint matrix C associated with the element
    2070             :    * degree of freedom indices elem_dofs. The optional parameter
    2071             :    * \p called_recursively should be left at the default value
    2072             :    * \p false.  This is used to handle the special case of
    2073             :    * an element's degrees of freedom being constrained in terms
    2074             :    * of other, local degrees of freedom.  The usual case is
    2075             :    * for an elements DOFs to be constrained by some other,
    2076             :    * external DOFs.
    2077             :    */
    2078             :   void build_constraint_matrix (DenseMatrix<Number> & C,
    2079             :                                 std::vector<dof_id_type> & elem_dofs,
    2080             :                                 const bool called_recursively=false) const;
    2081             : 
    2082             :   /**
    2083             :    * Build the constraint matrix C and the forcing vector H
    2084             :    * associated with the element degree of freedom indices elem_dofs.
    2085             :    * The optional parameter \p called_recursively should be left at
    2086             :    * the default value \p false.  This is used to handle the special
    2087             :    * case of an element's degrees of freedom being constrained in
    2088             :    * terms of other, local degrees of freedom.  The usual case is for
    2089             :    * an elements DOFs to be constrained by some other, external DOFs
    2090             :    * and/or Dirichlet conditions.
    2091             :    *
    2092             :    * The forcing vector will depend on which solution's heterogeneous
    2093             :    * constraints are being applied.  For the default \p qoi_index this
    2094             :    * will be the primal solution; for \p qoi_index >= 0 the
    2095             :    * corresponding adjoint solution's constraints will be used.
    2096             :    */
    2097             :   void build_constraint_matrix_and_vector (DenseMatrix<Number> & C,
    2098             :                                            DenseVector<Number> & H,
    2099             :                                            std::vector<dof_id_type> & elem_dofs,
    2100             :                                            int qoi_index = -1,
    2101             :                                            const bool called_recursively=false) const;
    2102             : 
    2103             :   /**
    2104             :    * Finds all the DOFS associated with the element DOFs elem_dofs.
    2105             :    * This will account for off-element couplings via hanging nodes.
    2106             :    */
    2107             :   void find_connected_dofs (std::vector<dof_id_type> & elem_dofs) const;
    2108             : 
    2109             :   /**
    2110             :    * Finds all the DofObjects associated with the set in \p objs.
    2111             :    * This will account for off-element couplings via hanging nodes.
    2112             :    */
    2113             :   void find_connected_dof_objects (std::vector<const DofObject *> & objs) const;
    2114             : 
    2115             :   /**
    2116             :    * Adds entries to the \p _send_list vector corresponding to DoFs
    2117             :    * which are dependencies for constraint equations on the current
    2118             :    * processor.
    2119             :    */
    2120             :   void add_constraints_to_send_list(const MeshBase & mesh);
    2121             : 
    2122             :   /**
    2123             :    * Adds any spline constraints from the Mesh to our DoF constraints.
    2124             :    * If any Dirichlet constraints exist on spline-constrained nodes,
    2125             :    * l2-projects those constraints onto the spline basis.
    2126             :    */
    2127             :   void process_mesh_constraint_rows(const MeshBase & mesh);
    2128             : 
    2129             : #endif // LIBMESH_ENABLE_CONSTRAINTS
    2130             : 
    2131             :   /**
    2132             :    * This flag indicates whether or not we do an opt-mode check for
    2133             :    * the presence of constraint loops, i.e. cases where the constraint
    2134             :    * graph is cyclic.
    2135             :    */
    2136             :   bool _error_on_constraint_loop;
    2137             : 
    2138             :   /**
    2139             :    * This flag indicates whether or not we explicitly take constraint
    2140             :    * equations into account when computing a sparsity pattern.
    2141             :    */
    2142             :   bool _constrained_sparsity_construction;
    2143             : 
    2144             :   /**
    2145             :    * The variables in this system/degree of freedom map
    2146             :    */
    2147             :   std::vector<Variable> _variables;
    2148             : 
    2149             :   /**
    2150             :    * The variable groups in this system/degree of freedom map
    2151             :    */
    2152             :   std::vector<VariableGroup> _variable_groups;
    2153             : 
    2154             :   /**
    2155             :    * The variable group number for each variable.
    2156             :    */
    2157             :   std::vector<unsigned int> _variable_group_numbers;
    2158             : 
    2159             :   /**
    2160             :    * A map from variable number to variable group number
    2161             :    */
    2162             :   std::unordered_map<unsigned int, unsigned int> _var_to_vg;
    2163             : 
    2164             :   /**
    2165             :    * The variable numbers corresponding to user-specified
    2166             :    * names, useful for name-based lookups.
    2167             :    */
    2168             :   std::map<std::string, unsigned int, std::less<>> _variable_numbers;
    2169             : 
    2170             :   /**
    2171             :    * Array variable information storage. For a given array "variable", the first member of the pair
    2172             :    * denotes the first variable number present in the array variable and the second member of the
    2173             :    * pair denotes the last variable number present in the array variables plus one
    2174             :    */
    2175             :   std::vector<std::pair<unsigned int, unsigned int>> _array_variables;
    2176             : 
    2177             :   /**
    2178             :    * \p true when \p VariableGroup structures should be automatically
    2179             :    * identified, \p false otherwise.  Defaults to \p true.
    2180             :    */
    2181             :   bool _identify_variable_groups = true;
    2182             : 
    2183             :   /**
    2184             :    * The number of the system we manage DOFs for.
    2185             :    */
    2186             :   const unsigned int _sys_number;
    2187             : 
    2188             :   /**
    2189             :    * The mesh that system uses.
    2190             :    */
    2191             :   MeshBase & _mesh;
    2192             : 
    2193             :   /**
    2194             :    * Additional matrices handled by this object.  These pointers do \e
    2195             :    * not handle the memory, instead, \p System, who
    2196             :    * told \p DofMap about them, owns them.
    2197             :    */
    2198             :   std::vector<SparseMatrix<Number> * > _matrices;
    2199             : 
    2200             :   /**
    2201             :    * First DOF index for SCALAR variable v, or garbage for non-SCALAR
    2202             :    * variable v
    2203             :    */
    2204             :   std::vector<dof_id_type> _first_scalar_df;
    2205             : 
    2206             :   /**
    2207             :    * A list containing all the global DOF indices that affect the
    2208             :    * solution on my processor.
    2209             :    */
    2210             :   std::vector<dof_id_type> _send_list;
    2211             : 
    2212             :   /**
    2213             :    * Function object to call to add extra entries to the sparsity pattern
    2214             :    */
    2215             :   SparsityPattern::AugmentSparsityPattern * _augment_sparsity_pattern;
    2216             : 
    2217             :   /**
    2218             :    * A function pointer to a function to call to add extra entries to the sparsity pattern
    2219             :    */
    2220             :   void (*_extra_sparsity_function)(SparsityPattern::Graph &,
    2221             :                                    std::vector<dof_id_type> & n_nz,
    2222             :                                    std::vector<dof_id_type> & n_oz,
    2223             :                                    void *);
    2224             :   /**
    2225             :    * A pointer associated with the extra sparsity that can optionally be passed in
    2226             :    */
    2227             :   void * _extra_sparsity_context;
    2228             : 
    2229             :   /**
    2230             :    * Function object to call to add extra entries to the send list
    2231             :    */
    2232             :   AugmentSendList * _augment_send_list;
    2233             : 
    2234             :   /**
    2235             :    * A function pointer to a function to call to add extra entries to the send list
    2236             :    */
    2237             :   void (*_extra_send_list_function)(std::vector<dof_id_type> &, void *);
    2238             : 
    2239             :   /**
    2240             :    * A pointer associated with the extra send list that can optionally be passed in
    2241             :    */
    2242             :   void * _extra_send_list_context;
    2243             : 
    2244             :   /**
    2245             :    * The default coupling GhostingFunctor, used to implement standard
    2246             :    * libMesh sparsity pattern construction.
    2247             :    *
    2248             :    * We use a std::unique_ptr here to reduce header dependencies.
    2249             :    */
    2250             :   std::unique_ptr<DefaultCoupling> _default_coupling;
    2251             : 
    2252             :   /**
    2253             :    * The default algebraic GhostingFunctor, used to implement standard
    2254             :    * libMesh send_list construction.
    2255             :    *
    2256             :    * We use a std::unique_ptr here to reduce header dependencies.
    2257             :    */
    2258             :   std::unique_ptr<DefaultCoupling> _default_evaluating;
    2259             : 
    2260             :   /**
    2261             :    * The list of all GhostingFunctor objects to be used when
    2262             :    * distributing ghosted vectors.
    2263             :    *
    2264             :    * The library should automatically refer these functors to the
    2265             :    * MeshBase, too, so any algebraically ghosted dofs will live on
    2266             :    * geometrically ghosted elements.
    2267             :    *
    2268             :    * Keep these in a vector so any parallel computation is done in the
    2269             :    * same order on all processors.
    2270             :    */
    2271             :   std::vector<GhostingFunctor *> _algebraic_ghosting_functors;
    2272             : 
    2273             :   /**
    2274             :    * The list of all GhostingFunctor objects to be used when
    2275             :    * coupling degrees of freedom in matrix sparsity patterns.
    2276             :    *
    2277             :    * These objects will *also* be used as algebraic ghosting functors,
    2278             :    * but not vice-versa.
    2279             :    *
    2280             :    * The library should automatically refer these functors to the
    2281             :    * MeshBase, too, so any dofs coupled to local dofs will live on
    2282             :    * geometrically ghosted elements.
    2283             :    */
    2284             :   std::vector<GhostingFunctor *> _coupling_functors;
    2285             : 
    2286             :   /**
    2287             :    * Hang on to references to any GhostingFunctor objects we were
    2288             :    * passed in shared_ptr form
    2289             :    */
    2290             :   std::map<GhostingFunctor *, std::shared_ptr<GhostingFunctor> > _shared_functors;
    2291             : 
    2292             :   /**
    2293             :    * Default false; set to true if any attached matrix requires a full
    2294             :    * sparsity pattern.
    2295             :    */
    2296             :   bool _need_full_sparsity_pattern;
    2297             : 
    2298             :   /**
    2299             :    * Default false; set to true if the dependencies of constrained ghost
    2300             :    * DOFs supported by local elements should also be ghosted
    2301             :    */
    2302             :   bool _need_ghost_constraints;
    2303             : 
    2304             :   /**
    2305             :    * The sparsity pattern of the global matrix.  If
    2306             :    * need_full_sparsity_pattern is true, we save the entire sparse
    2307             :    * graph here.  Otherwise we save just the n_nz and n_oz vectors.
    2308             :    */
    2309             :   std::unique_ptr<SparsityPattern::Build> _sp;
    2310             : 
    2311             :   /**
    2312             :    * The total number of SCALAR dofs associated to
    2313             :    * all SCALAR variables.
    2314             :    */
    2315             :   dof_id_type _n_SCALAR_dofs;
    2316             : 
    2317             : #ifdef LIBMESH_ENABLE_AMR
    2318             : 
    2319             :   /**
    2320             :    * First old DOF index for SCALAR variable v, or garbage for
    2321             :    * non-SCALAR variable v
    2322             :    */
    2323             :   std::vector<dof_id_type> _first_old_scalar_df;
    2324             : #endif
    2325             : 
    2326             : #ifdef LIBMESH_ENABLE_CONSTRAINTS
    2327             :   /**
    2328             :    * Data structure containing DOF constraints.  The ith
    2329             :    * entry is the constraint matrix row for DOF i.
    2330             :    */
    2331             :   DofConstraints _dof_constraints, _stashed_dof_constraints;
    2332             : 
    2333             :   DofConstraintValueMap      _primal_constraint_values;
    2334             : 
    2335             :   AdjointDofConstraintValues _adjoint_constraint_values;
    2336             : #endif
    2337             : 
    2338             : #ifdef LIBMESH_ENABLE_DIRICHLET
    2339             :   /**
    2340             :    * The data from the last create_dof_constraints() call that
    2341             :    * reinit_dirichlet_constraint_values() uses at a new time.
    2342             :    */
    2343       10586 :   struct DirichletConstraintCache
    2344             :   {
    2345             :     /// Whether the cache matches the current degrees of freedom and boundaries
    2346             :     bool valid = false;
    2347             : 
    2348             :     /// The constraints that create_dof_constraints() built before it
    2349             :     /// applied the DirichletBoundary objects
    2350             :     DofConstraints dof_constraints;
    2351             :     DofConstraintValueMap primal_constraint_values;
    2352             :     AdjointDofConstraintValues adjoint_constraint_values;
    2353             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
    2354             :     NodeConstraints node_constraints;
    2355             : #endif
    2356             : 
    2357             :     /// The local active elements carrying any DirichletBoundary id,
    2358             :     /// sorted by id
    2359             :     std::vector<const Elem *> boundary_elems;
    2360             :   };
    2361             : 
    2362             :   DirichletConstraintCache _dirichlet_cache;
    2363             : #endif
    2364             : 
    2365             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
    2366             :   /**
    2367             :    * Data structure containing DofObject constraints.
    2368             :    */
    2369             :   NodeConstraints _node_constraints;
    2370             : #endif // LIBMESH_ENABLE_NODE_CONSTRAINTS
    2371             : 
    2372             : 
    2373             : #ifdef LIBMESH_ENABLE_PERIODIC
    2374             :   /**
    2375             :    * Data structure containing periodic boundaries.  The ith
    2376             :    * entry is the constraint matrix row for boundaryid i.
    2377             :    */
    2378             :   std::unique_ptr<PeriodicBoundaries> _periodic_boundaries;
    2379             : #endif
    2380             : 
    2381             : #ifdef LIBMESH_ENABLE_DIRICHLET
    2382             :   /**
    2383             :    * Data structure containing Dirichlet functions.  The ith
    2384             :    * entry is the constraint matrix row for boundaryid i.
    2385             :    */
    2386             :   std::unique_ptr<DirichletBoundaries> _dirichlet_boundaries;
    2387             : 
    2388             :   /**
    2389             :    * Data structure containing Dirichlet functions.  The ith
    2390             :    * entry is the constraint matrix row for boundaryid i.
    2391             :    */
    2392             :   std::vector<std::unique_ptr<DirichletBoundaries>> _adjoint_dirichlet_boundaries;
    2393             : #endif
    2394             : 
    2395             :   friend class SparsityPattern::Build;
    2396             : 
    2397             :   /**
    2398             :    * Bools to indicate if we override the --implicit_neighbor_dofs
    2399             :    * commandline options.
    2400             :    */
    2401             :   bool _implicit_neighbor_dofs_initialized;
    2402             :   bool _implicit_neighbor_dofs;
    2403             : 
    2404             :   /**
    2405             :    * Flag which determines whether we should do some additional
    2406             :    * checking of the consistency of the DirichletBoundary objects
    2407             :    * added by the user. Defaults to true, but can be disabled in cases
    2408             :    * where you only want to add DirichletBoundary objects "locally"
    2409             :    * and can guarantee that no repartitioning will be done, since
    2410             :    * repartitioning could cause processors to own new boundary sides
    2411             :    * for which they no longer have the proper DirichletBoundary
    2412             :    * objects stored.
    2413             :    */
    2414             :   bool _verify_dirichlet_bc_consistency;
    2415             : 
    2416             :   /// Static condensation class
    2417             :   std::unique_ptr<StaticCondensationDofMap> _sc;
    2418             : };
    2419             : 
    2420             : 
    2421             : // ------------------------------------------------------------
    2422             : // Dof Map inline member functions
    2423             : inline
    2424    44548482 : unsigned int DofMap::sys_number() const
    2425             : {
    2426   308627487 :   return _sys_number;
    2427             : }
    2428             : 
    2429             : 
    2430             : 
    2431             : inline
    2432    49012508 : const VariableGroup & DofMap::variable_group (const unsigned int g) const
    2433             : {
    2434    49012508 :   libmesh_assert_less (g, _variable_groups.size());
    2435             : 
    2436   317279775 :   return _variable_groups[g];
    2437             : }
    2438             : 
    2439             : 
    2440             : 
    2441             : inline
    2442    70290619 : const Variable & DofMap::variable (const unsigned int c) const
    2443             : {
    2444     6578384 :   libmesh_assert_less (c, _variables.size());
    2445             : 
    2446    75653487 :   return _variables[c];
    2447             : }
    2448             : 
    2449             : 
    2450             : 
    2451             : inline
    2452             : Order DofMap::variable_order (const unsigned int c) const
    2453             : {
    2454             :   libmesh_assert_less (c, _variables.size());
    2455             : 
    2456             :   return _variables[c].type().order;
    2457             : }
    2458             : 
    2459             : 
    2460             : 
    2461             : inline
    2462             : Order DofMap::variable_group_order (const unsigned int vg) const
    2463             : {
    2464             :   libmesh_assert_less (vg, _variable_groups.size());
    2465             : 
    2466             :   return _variable_groups[vg].type().order;
    2467             : }
    2468             : 
    2469             : 
    2470             : 
    2471             : inline
    2472     1882846 : const FEType & DofMap::variable_type (const unsigned int c) const
    2473             : {
    2474     1882846 :   libmesh_assert_less (c, _variables.size());
    2475             : 
    2476    15235172 :   return _variables[c].type();
    2477             : }
    2478             : 
    2479             : 
    2480             : 
    2481             : inline
    2482             : const FEType & DofMap::variable_group_type (const unsigned int vg) const
    2483             : {
    2484             :   libmesh_assert_less (vg, _variable_groups.size());
    2485             : 
    2486             :   return _variable_groups[vg].type();
    2487             : }
    2488             : 
    2489             : 
    2490             : #ifdef LIBMESH_ENABLE_CONSTRAINTS
    2491             : 
    2492             : 
    2493             : inline
    2494     1432396 : bool DofMap::is_constrained_node (const Node *
    2495             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
    2496             :                                   node
    2497             : #endif
    2498             :                                   ) const
    2499             : {
    2500             : #ifdef LIBMESH_ENABLE_NODE_CONSTRAINTS
    2501     1432396 :   if (_node_constraints.count(node))
    2502       18265 :     return true;
    2503             : #endif
    2504             : 
    2505     1414131 :   return false;
    2506             : }
    2507             : 
    2508             : 
    2509             : inline
    2510    52838477 : bool DofMap::is_constrained_dof (const dof_id_type dof) const
    2511             : {
    2512    52838477 :   if (_dof_constraints.count(dof))
    2513     5772331 :     return true;
    2514             : 
    2515    47066146 :   return false;
    2516             : }
    2517             : 
    2518             : 
    2519             : inline
    2520       79722 : bool DofMap::has_heterogeneous_adjoint_constraints (const unsigned int qoi_num) const
    2521             : {
    2522             :   AdjointDofConstraintValues::const_iterator it =
    2523        3072 :     _adjoint_constraint_values.find(qoi_num);
    2524       82794 :   if (it == _adjoint_constraint_values.end())
    2525        1618 :     return false;
    2526       24662 :   if (it->second.empty())
    2527       23040 :     return false;
    2528             : 
    2529          14 :   return true;
    2530             : }
    2531             : 
    2532             : 
    2533             : inline
    2534     1414426 : Number DofMap::has_heterogeneous_adjoint_constraint (const unsigned int qoi_num,
    2535             :                                                     const dof_id_type dof) const
    2536             : {
    2537             :   AdjointDofConstraintValues::const_iterator it =
    2538     1093446 :     _adjoint_constraint_values.find(qoi_num);
    2539     1414426 :   if (it != _adjoint_constraint_values.end())
    2540             :     {
    2541             :       DofConstraintValueMap::const_iterator rhsit =
    2542      104428 :         it->second.find(dof);
    2543      425408 :       if (rhsit == it->second.end())
    2544      154302 :         return 0;
    2545             :       else
    2546        1820 :         return rhsit->second;
    2547             :     }
    2548             : 
    2549      989018 :   return 0;
    2550             : }
    2551             : 
    2552             : 
    2553             : 
    2554             : inline
    2555             : DofConstraintValueMap & DofMap::get_primal_constraint_values()
    2556             : {
    2557             :   return _primal_constraint_values;
    2558             : }
    2559             : 
    2560             : 
    2561             : 
    2562             : #else
    2563             : 
    2564             : //--------------------------------------------------------------------
    2565             : // Constraint-specific methods get inlined into nothing if
    2566             : // constraints are disabled, so there's no reason for users not to
    2567             : // use them.
    2568             : 
    2569             : inline void DofMap::constrain_element_matrix (DenseMatrix<Number> &,
    2570             :                                               std::vector<dof_id_type> &,
    2571             :                                               bool) const {}
    2572             : 
    2573             : inline void DofMap::constrain_element_matrix (DenseMatrix<Number> &,
    2574             :                                               std::vector<dof_id_type> &,
    2575             :                                               std::vector<dof_id_type> &,
    2576             :                                               bool) const {}
    2577             : 
    2578             : inline void DofMap::constrain_element_vector (DenseVector<Number> &,
    2579             :                                               std::vector<dof_id_type> &,
    2580             :                                               bool) const {}
    2581             : 
    2582             : inline void DofMap::constrain_element_matrix_and_vector (DenseMatrix<Number> &,
    2583             :                                                          DenseVector<Number> &,
    2584             :                                                          std::vector<dof_id_type> &,
    2585             :                                                          bool) const {}
    2586             : 
    2587             : inline void DofMap::heterogeneously_constrain_element_matrix_and_vector
    2588             :   (DenseMatrix<Number> &, DenseVector<Number> &,
    2589             :    std::vector<dof_id_type> &, bool, int) const {}
    2590             : 
    2591             : inline void DofMap::heterogeneously_constrain_element_vector
    2592             :   (const DenseMatrix<Number> &, DenseVector<Number> &,
    2593             :    std::vector<dof_id_type> &, bool, int) const {}
    2594             : 
    2595             : inline void DofMap::constrain_element_dyad_matrix (DenseVector<Number> &,
    2596             :                                                    DenseVector<Number> &,
    2597             :                                                    std::vector<dof_id_type> &,
    2598             :                                                    bool) const {}
    2599             : 
    2600             : inline void DofMap::constrain_nothing (std::vector<dof_id_type> &) const {}
    2601             : 
    2602             : inline void DofMap::enforce_constraints_exactly (const System &,
    2603             :                                                  NumericVector<Number> *,
    2604             :                                                  bool) const {}
    2605             : 
    2606             : inline void DofMap::enforce_adjoint_constraints_exactly (NumericVector<Number> &,
    2607             :                                                          unsigned int) const {}
    2608             : 
    2609             : 
    2610             : inline void DofMap::enforce_constraints_on_residual
    2611             :   (const NonlinearImplicitSystem &,
    2612             :    NumericVector<Number> *,
    2613             :    NumericVector<Number> const *,
    2614             :    bool) const {}
    2615             : 
    2616             : inline void DofMap::enforce_constraints_on_jacobian
    2617             :   (const NonlinearImplicitSystem &,
    2618             :    SparseMatrix<Number> *) const {}
    2619             : 
    2620             : #endif // LIBMESH_ENABLE_CONSTRAINTS
    2621             : 
    2622             : 
    2623             : 
    2624             : inline
    2625             : void DofMap::set_constrained_sparsity_construction(bool use_constraints)
    2626             : {
    2627             :   // This got only partly finished...
    2628             :   if (use_constraints)
    2629             :     libmesh_not_implemented();
    2630             : 
    2631             : #ifdef LIBMESH_ENABLE_CONSTRAINTS
    2632             :   _constrained_sparsity_construction = use_constraints;
    2633             : #endif
    2634             :   libmesh_ignore(use_constraints);
    2635             : }
    2636             : 
    2637             : inline
    2638             : void DofMap::full_sparsity_pattern_needed()
    2639             : {
    2640             :   _need_full_sparsity_pattern = true;
    2641             : }
    2642             : 
    2643             : inline
    2644             : void DofMap::ghost_constraints_needed()
    2645             : {
    2646             :   _need_ghost_constraints = true;
    2647             : }
    2648             : 
    2649             : inline
    2650             : bool DofMap::constrained_sparsity_construction()
    2651             : {
    2652             : #ifdef LIBMESH_ENABLE_CONSTRAINTS
    2653             :   return _constrained_sparsity_construction;
    2654             : #else
    2655             :   return true;
    2656             : #endif
    2657             : }
    2658             : 
    2659             : inline
    2660             : void DofMap::should_p_refine(const unsigned int g, const bool p_refine)
    2661             : {
    2662             : #ifdef LIBMESH_ENABLE_AMR
    2663             :   VariableGroup & var = _variable_groups[g];
    2664             :   var.type().p_refinement = p_refine;
    2665             : 
    2666             :   for (auto v : make_range(var.first_scalar_number(0),
    2667             :                            var.first_scalar_number(0) +
    2668             :                            var.n_variables()))
    2669             :     this->_variables[v].type().p_refinement = p_refine;
    2670             : 
    2671             : 
    2672             : #else
    2673             :   libmesh_ignore(g, p_refine);
    2674             : #endif
    2675             : }
    2676             : 
    2677             : inline
    2678             : bool DofMap::should_p_refine(const unsigned int g) const
    2679             : {
    2680             : #ifdef LIBMESH_ENABLE_AMR
    2681             :   const VariableGroup & var = this->variable_group(g);
    2682             :   return var.type().p_refinement;
    2683             : #else
    2684             :   libmesh_ignore(g);
    2685             :   return false;
    2686             : #endif
    2687             : }
    2688             : 
    2689             : inline
    2690             : unsigned int DofMap::var_group_from_var_number(const unsigned int var_num) const
    2691             : {
    2692             :   libmesh_assert(var_num < n_variables());
    2693             :   return libmesh_map_find(_var_to_vg, var_num);
    2694             : }
    2695             : 
    2696             : inline
    2697             : bool DofMap::should_p_refine_var(const unsigned int var) const
    2698             : {
    2699             : #ifdef LIBMESH_ENABLE_AMR
    2700             :   const auto vg = this->var_group_from_var_number(var);
    2701             :   return this->should_p_refine(vg);
    2702             : #else
    2703             :   libmesh_ignore(var);
    2704             :   return false;
    2705             : #endif
    2706             : }
    2707             : 
    2708             : template <typename FieldDofsFunctor>
    2709   273079684 : void DofMap::_dof_indices (const Elem & elem,
    2710             :                            int p_level,
    2711             :                            std::vector<dof_id_type> & di,
    2712             :                            const unsigned int vg,
    2713             :                            const unsigned int vig,
    2714             :                            const Node * const * nodes,
    2715             :                            unsigned int       n_nodes,
    2716             :                            const unsigned int v,
    2717             : #ifdef DEBUG
    2718             :                            std::size_t & tot_size,
    2719             : #endif
    2720             :                            FieldDofsFunctor field_dofs_functor) const
    2721             : {
    2722    24035296 :   const VariableGroup & var = this->variable_group(vg);
    2723             : 
    2724   273079684 :   if (var.active_on_subdomain(elem.subdomain_id()))
    2725             :     {
    2726   272941831 :       const ElemType type        = elem.type();
    2727    24087617 :       const unsigned int sys_num = this->sys_number();
    2728             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
    2729    31639567 :       const bool is_inf          = elem.infinite();
    2730             : #endif
    2731             : 
    2732             :       const bool extra_hanging_dofs =
    2733   272941831 :         FEInterface::extra_hanging_dofs(var.type());
    2734             : 
    2735   272941831 :       FEType fe_type = var.type();
    2736             : 
    2737   272941831 :       const bool add_p_level = fe_type.p_refinement;
    2738             : 
    2739             : #ifdef DEBUG
    2740             :       // The number of dofs per element is non-static for subdivision FE
    2741    24024923 :       if (var.type().family == SUBDIVISION)
    2742        3936 :         tot_size += n_nodes;
    2743             :       else
    2744             :         // FIXME: Is the passed-in p_level just elem.p_level()? If so,
    2745             :         // this seems redundant.
    2746    24020987 :         tot_size += FEInterface::n_dofs(fe_type, add_p_level*p_level, &elem);
    2747             : #endif
    2748             : 
    2749             :       // The total Order is not required when getting the function
    2750             :       // pointer, it is only needed when the function is called (see
    2751             :       // below).
    2752             :       const FEInterface::n_dofs_at_node_ptr ndan =
    2753   272941831 :         FEInterface::n_dofs_at_node_function(fe_type, &elem);
    2754             : 
    2755             :       // Get the node-based DOF numbers
    2756  1642451727 :       for (unsigned int n=0; n != n_nodes; n++)
    2757             :         {
    2758  1369509896 :           const Node & node = *nodes[n];
    2759             : 
    2760             :           // Cache the intermediate lookups that are common to every
    2761             :           // component
    2762             : #ifdef DEBUG
    2763             :           const std::pair<unsigned int, unsigned int>
    2764   122301068 :             vg_and_offset = node.var_to_vg_and_offset(sys_num,v);
    2765   122301068 :           libmesh_assert_equal_to (vg, vg_and_offset.first);
    2766   122301068 :           libmesh_assert_equal_to (vig, vg_and_offset.second);
    2767             : #endif
    2768  1369509896 :           const unsigned int n_comp = node.n_comp_group(sys_num,vg);
    2769             : 
    2770             :           // There is a potential problem with h refinement.  Imagine a
    2771             :           // quad9 that has a linear FE on it.  Then, on the hanging side,
    2772             :           // it can falsely identify a DOF at the mid-edge node. This is why
    2773             :           // we go through FEInterface instead of node.n_comp() directly.
    2774  1369509896 :           const unsigned int nc =
    2775             : #ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
    2776    59298700 :             is_inf ?
    2777       82322 :             FEInterface::n_dofs_at_node(fe_type, add_p_level*p_level, &elem, n) :
    2778             : #endif
    2779  1369903455 :             ndan (type, fe_type.order + add_p_level*p_level, n);
    2780             : 
    2781             :           // If this is a non-vertex on a hanging node with extra
    2782             :           // degrees of freedom, we use the non-vertex dofs (which
    2783             :           // come in reverse order starting from the end, to
    2784             :           // simplify p refinement)
    2785  1369509896 :           if (extra_hanging_dofs && !elem.is_vertex(n))
    2786             :             {
    2787    51623513 :               const int dof_offset = n_comp - nc;
    2788             : 
    2789             :               // We should never have fewer dofs than necessary on a
    2790             :               // node unless we're getting indices on a parent element,
    2791             :               // and we should never need the indices on such a node
    2792    51623513 :               if (dof_offset < 0)
    2793             :                 {
    2794           0 :                   libmesh_assert(!elem.active());
    2795           0 :                   di.resize(di.size() + nc, DofObject::invalid_id);
    2796             :                 }
    2797             :               else
    2798   137421729 :                 for (int i=int(n_comp)-1; i>=dof_offset; i--)
    2799             :                   {
    2800     6943590 :                     const dof_id_type d =
    2801    85798216 :                       node.dof_number(sys_num, vg, vig, i, n_comp);
    2802     6943590 :                     libmesh_assert_not_equal_to (d, DofObject::invalid_id);
    2803    85798216 :                     field_dofs_functor(elem, n, v, di, d);
    2804             :                   }
    2805             :             }
    2806             :           // If this is a vertex or an element without extra hanging
    2807             :           // dofs, our dofs come in forward order coming from the
    2808             :           // beginning
    2809             :           else
    2810             :             {
    2811             :               // We have a good component index only if it's being
    2812             :               // used on this FE type (nc) *and* it's available on
    2813             :               // this DofObject (n_comp).
    2814  1317886383 :               const unsigned int good_nc = std::min(n_comp, nc);
    2815  2552708024 :               for (unsigned int i=0; i!=good_nc; ++i)
    2816             :                 {
    2817   109071996 :                   const dof_id_type d =
    2818  1234599612 :                     node.dof_number(sys_num, vg, vig, i, n_comp);
    2819   109071996 :                   libmesh_assert_not_equal_to (d, DofObject::invalid_id);
    2820   109071996 :                   libmesh_assert_less (d, this->n_dofs());
    2821  1234821641 :                   field_dofs_functor(elem, n, v, di, d);
    2822             :                 }
    2823             : 
    2824             :               // With fewer good component indices than we need, e.g.
    2825             :               // due to subdomain expansion, the remaining expected
    2826             :               // indices are marked invalid.
    2827  1317886383 :               if (n_comp < nc)
    2828           0 :                 for (unsigned int i=n_comp; i!=nc; ++i)
    2829           0 :                   di.push_back(DofObject::invalid_id);
    2830             :             }
    2831             :         }
    2832             : 
    2833             :       // If there are any element-based DOF numbers, get them
    2834   272941831 :       const unsigned int nc = FEInterface::n_dofs_per_elem(fe_type, add_p_level*p_level, &elem);
    2835             : 
    2836             :       // We should never have fewer dofs than necessary on an
    2837             :       // element unless we're getting indices on a parent element
    2838             :       // (and we should never need those indices) or off-domain for a
    2839             :       // subdomain-restricted variable (where invalid_id is the
    2840             :       // correct thing to return)
    2841   272941831 :       if (nc != 0)
    2842             :         {
    2843     1767841 :           const unsigned int n_comp = elem.n_comp_group(sys_num,vg);
    2844    20084039 :           if (elem.n_systems() > sys_num && nc <= n_comp)
    2845             :             {
    2846   114727914 :               for (unsigned int i=0; i<nc; i++)
    2847             :                 {
    2848     8277435 :                   const dof_id_type d =
    2849    94481160 :                     elem.dof_number(sys_num, vg, vig, i, n_comp);
    2850     8277435 :                   libmesh_assert_not_equal_to (d, DofObject::invalid_id);
    2851             : 
    2852    94643875 :                   field_dofs_functor(elem, invalid_uint, v, di, d);
    2853             :                 }
    2854             :             }
    2855             :           else
    2856             :             {
    2857           0 :               libmesh_assert(!elem.active() || fe_type.family == LAGRANGE || fe_type.family == SUBDIVISION);
    2858           0 :               di.resize(di.size() + nc, DofObject::invalid_id);
    2859             :             }
    2860             :         }
    2861             :     }
    2862   273079684 : }
    2863             : 
    2864             : 
    2865             : 
    2866             : template <typename ScalarDofsFunctor, typename FieldDofsFunctor>
    2867   114775124 : void DofMap::dof_indices (const Elem * const elem,
    2868             :                           std::vector<dof_id_type> & di,
    2869             :                           const unsigned int vn,
    2870             :                           ScalarDofsFunctor scalar_dofs_functor,
    2871             :                           FieldDofsFunctor field_dofs_functor,
    2872             :                           int p_level) const
    2873             : {
    2874             :   // We now allow elem==nullptr to request just SCALAR dofs
    2875             :   // libmesh_assert(elem);
    2876             : 
    2877             :   // dof_indices() is a relatively light-weight function that is
    2878             :   // called millions of times in normal codes. Therefore, it is not a
    2879             :   // good candidate for logging, since the cost of the logging code
    2880             :   // itself is roughly on par with the time required to call
    2881             :   // dof_indices().
    2882             :   // LOG_SCOPE("dof_indices()", "DofMap");
    2883             : 
    2884             :   // Clear the DOF indices vector
    2885    11023215 :   di.clear();
    2886             : 
    2887             :   // Use the default p refinement level?
    2888   114775124 :   if (p_level == -12345)
    2889   113300334 :     p_level = elem ? elem->p_level() : 0;
    2890             : 
    2891   114837850 :   const unsigned int vg = this->_variable_group_numbers[vn];
    2892    11023215 :   const VariableGroup & var = this->variable_group(vg);
    2893   114775124 :   const unsigned int vig = vn - var.number();
    2894             : 
    2895             : #ifdef DEBUG
    2896             :   // Check that sizes match in DEBUG mode
    2897    11023215 :   std::size_t tot_size = 0;
    2898             : #endif
    2899             : 
    2900   114775124 :   if (elem && elem->type() == TRI3SUBDIVISION)
    2901             :     {
    2902             :       // Subdivision surface FE require the 1-ring around elem
    2903        2712 :       const Tri3Subdivision * sd_elem = static_cast<const Tri3Subdivision *>(elem);
    2904             : 
    2905             :       // Ghost subdivision elements have no real dofs
    2906       29832 :       if (!sd_elem->is_ghost())
    2907             :         {
    2908             :           // Determine the nodes contributing to element elem
    2909        4608 :           std::vector<const Node *> elem_nodes;
    2910       25344 :           MeshTools::Subdivision::find_one_ring(sd_elem, elem_nodes);
    2911             : 
    2912       25344 :           _dof_indices(*elem, p_level, di, vg, vig, elem_nodes.data(),
    2913             :                        cast_int<unsigned int>(elem_nodes.size()), vn,
    2914             : #ifdef DEBUG
    2915             :                        tot_size,
    2916             : #endif
    2917             :                        field_dofs_functor);
    2918             :         }
    2919             : 
    2920       29832 :       return;
    2921             :     }
    2922             : 
    2923             :   // Get the dof numbers
    2924   114843247 :   if (var.type().family == SCALAR &&
    2925     1027221 :       (!elem ||
    2926     1027253 :        var.active_on_subdomain(elem->subdomain_id())))
    2927             :     {
    2928             : #ifdef DEBUG
    2929       97955 :       tot_size += var.type().order;
    2930             : #endif
    2931      195910 :       std::vector<dof_id_type> di_new;
    2932     1027253 :       this->SCALAR_dof_indices(di_new,vn);
    2933     1027253 :       scalar_dofs_functor(*elem, di, di_new);
    2934             :     }
    2935   113718039 :   else if (elem)
    2936   113718039 :     _dof_indices(*elem, p_level, di, vg, vig, elem->get_nodes(),
    2937   113718039 :                  elem->n_nodes(), vn,
    2938             : #ifdef DEBUG
    2939             :                  tot_size,
    2940             : #endif
    2941             :                  field_dofs_functor);
    2942             : 
    2943             : #ifdef DEBUG
    2944    11020503 :   libmesh_assert_equal_to (tot_size, di.size());
    2945             : #endif
    2946             : }
    2947             : 
    2948             : inline
    2949          18 : StaticCondensationDofMap & DofMap::get_static_condensation()
    2950             : {
    2951          18 :   libmesh_assert(_sc);
    2952          18 :   return *_sc;
    2953             : }
    2954             : 
    2955             : inline
    2956          28 : const StaticCondensationDofMap & DofMap::get_static_condensation() const
    2957             : {
    2958          28 :   libmesh_assert(_sc);
    2959          28 :   return *_sc;
    2960             : }
    2961             : 
    2962             : inline const std::pair<unsigned int, unsigned int> &
    2963         104 : DofMap::get_variable_array(const unsigned int vi) const
    2964             : {
    2965          88 :   auto it = std::upper_bound(
    2966             :       _array_variables.begin(),
    2967             :       _array_variables.end(),
    2968             :       vi,
    2969         136 :       [](unsigned int value, const std::pair<unsigned int, unsigned int> & b) { return value < b.first; });
    2970             : 
    2971          16 :   libmesh_assert_msg(it != _array_variables.begin(),
    2972             :                      "Passed in " << std::to_string(vi) << " is not in any of our array variables");
    2973          16 :   --it;
    2974          16 :   libmesh_assert_msg(vi < it->second,
    2975             :                      "Passed in " << std::to_string(vi) << " is not in any of our array variables");
    2976         120 :   return *it;
    2977             : }
    2978             : 
    2979             : template <typename DofIndicesFunctor>
    2980         120 : void DofMap::array_dof_indices(const DofIndicesFunctor & functor,
    2981             :                                std::vector<dof_id_type> & di,
    2982             :                                const unsigned int vn) const
    2983             : {
    2984         136 :   const auto [begin, end] = this->get_variable_array(vn);
    2985         104 :   functor(di, begin);
    2986             : 
    2987         120 :   const unsigned int count = end - begin;
    2988             :   // We make count, which could be >> ntest, the inner index in hopes of vectorization
    2989         120 :   if (count > 1)
    2990             :     {
    2991          40 :       const dof_id_type component_size = di.size();
    2992         120 :       di.resize(count * component_size);
    2993             : 
    2994        1512 :       const auto pack_container = [&di,
    2995             :                                    component_size](const unsigned int j,
    2996             :                                                    const std::vector<dof_id_type> & j_dof_indices,
    2997          32 :                                                    const unsigned int stride) {
    2998          32 :         if (&j_dof_indices != &di)
    2999           4 :           libmesh_assert(j_dof_indices.size() == component_size);
    3000        1568 :         for (const auto i : make_range(component_size))
    3001        1536 :           di[j * component_size + i] = j_dof_indices[i] + stride * j;
    3002             :       };
    3003         104 :       pack_container(0, di, 0);
    3004             : 
    3005         120 :       const auto & fe_type = _variable_groups[libmesh_map_find(_var_to_vg, vn)].type();
    3006         136 :       if (const bool lagrange = fe_type.family == LAGRANGE;
    3007         120 :           lagrange || (FEInterface::get_continuity(fe_type) == DISCONTINUOUS))
    3008             :         {
    3009          90 :           const auto stride = lagrange ? 1 : component_size;
    3010         180 :           for (const auto j : make_range((unsigned int)1, count))
    3011          78 :             pack_container(j, di, stride);
    3012             :         }
    3013             :       else
    3014             :         {
    3015          30 :           static thread_local std::vector<dof_id_type> work_dof_indices;
    3016           4 :           unsigned int j = 1;
    3017          60 :           for (const auto i : make_range(begin + 1, end))
    3018             :             {
    3019          26 :               functor(work_dof_indices, i);
    3020          30 :               pack_container(j++, work_dof_indices, 0);
    3021             :             }
    3022             :         }
    3023             :     }
    3024         120 : }
    3025             : 
    3026             : inline
    3027    10604891 : unsigned int DofMap::n_vars() const
    3028             : {
    3029    21188844 :   return cast_int<unsigned int>(_variables.size());
    3030             : }
    3031             : 
    3032             : inline
    3033     2730179 : const std::string & DofMap::variable_name (const unsigned int i) const
    3034             : {
    3035     2730179 :   libmesh_assert_less (i, _variables.size());
    3036             : 
    3037    33318576 :   return _variables[i].name();
    3038             : }
    3039             : 
    3040             : inline
    3041        1360 : bool DofMap::identify_variable_groups () const
    3042             : {
    3043       47026 :   return _identify_variable_groups;
    3044             : }
    3045             : 
    3046             : inline
    3047           0 : void DofMap::identify_variable_groups (const bool ivg)
    3048             : {
    3049           0 :   _identify_variable_groups = ivg;
    3050           0 : }
    3051             : 
    3052             : inline
    3053      374701 : unsigned int DofMap::n_components(const MeshBase & mesh) const
    3054             : {
    3055      385619 :   if (_variables.empty())
    3056       10546 :     return 0;
    3057             : 
    3058         372 :   const Variable & last = _variables.back();
    3059       13155 :   return last.first_scalar_number() + last.n_components(mesh);
    3060             : }
    3061             : 
    3062             : inline
    3063             : unsigned int
    3064      546081 : DofMap::variable_scalar_number (unsigned int var_num,
    3065             :                                 unsigned int component) const
    3066             : {
    3067     7410392 :   return _variables[var_num].first_scalar_number() + component;
    3068             : }
    3069             : 
    3070             : inline
    3071       34666 : const FEType & DofMap::variable_type (std::string_view var) const
    3072             : {
    3073       35576 :   return _variables[this->variable_number(var)].type();
    3074             : }
    3075             : 
    3076         898 : inline bool DofMap::has_variable(std::string_view var) const
    3077             : {
    3078         898 :   return _variable_numbers.count(var);
    3079             : }
    3080             : 
    3081      374373 : inline unsigned int DofMap::variable_number(std::string_view var) const
    3082             : {
    3083     8475006 :   auto var_num = libmesh_map_find(_variable_numbers, var);
    3084      374373 :   libmesh_assert_equal_to(_variables[var_num].name(), var);
    3085      374373 :   return var_num;
    3086             : }
    3087             : 
    3088             : } // namespace libMesh
    3089             : 
    3090             : #endif // LIBMESH_DOF_MAP_H

Generated by: LCOV version 1.14