LCOV - code coverage report
Current view: top level - include/systems - system.h (source / functions) Hit Total Coverage
Test: libMesh/libmesh: #4417 (f0ff5e) with base 9bbd75 Lines: 50 81 61.7 %
Date: 2026-11-16 16:30:47 Functions: 28 47 59.6 %
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_SYSTEM_H
      21             : #define LIBMESH_SYSTEM_H
      22             : 
      23             : // Local Includes
      24             : #include "libmesh/elem_range.h"
      25             : #include "libmesh/enum_subset_solve_mode.h" // SUBSET_ZERO
      26             : #include "libmesh/enum_parallel_type.h" // PARALLEL
      27             : #include "libmesh/fem_function_base.h"
      28             : #include "libmesh/libmesh_common.h"
      29             : #include "libmesh/parallel_object.h"
      30             : #include "libmesh/parameters.h"
      31             : #include "libmesh/qoi_set.h"
      32             : #include "libmesh/reference_counted_object.h"
      33             : #include "libmesh/tensor_value.h" // For point_hessian
      34             : #include "libmesh/enum_matrix_build_type.h" // AUTOMATIC
      35             : 
      36             : // C++ includes
      37             : #include <cstddef>
      38             : #include <set>
      39             : #include <string>
      40             : #include <string_view>
      41             : #include <vector>
      42             : #include <memory>
      43             : #include <optional>
      44             : 
      45             : // This define may be useful in --disable-optional builds when it is
      46             : // possible that libmesh will not have any solvers available.
      47             : #if defined(LIBMESH_HAVE_PETSC) || \
      48             :   defined(LIBMESH_HAVE_EIGEN)   || \
      49             :   defined(LIBMESH_HAVE_LASPACK) || \
      50             :   defined(LIBMESH_TRILINOS_HAVE_AZTECOO)
      51             : #define LIBMESH_HAVE_SOLVER 1
      52             : #endif
      53             : 
      54             : namespace libMesh
      55             : {
      56             : 
      57             : // Forward Declarations
      58             : class System;
      59             : class EquationSystems;
      60             : class MeshBase;
      61             : class Xdr;
      62             : class DofMap;
      63             : template <typename Output> class FunctionBase;
      64             : class ParameterVector;
      65             : class Point;
      66             : class SensitivityData;
      67             : class Matrix;
      68             : template <typename T> class NumericVector;
      69             : template <typename T> class SparseMatrix;
      70             : template <typename T> class VectorValue;
      71             : typedef VectorValue<Number> NumberVectorValue;
      72             : typedef NumberVectorValue Gradient;
      73             : class SystemSubset;
      74             : class FEType;
      75             : class SystemNorm;
      76             : enum FEMNormType : int;
      77             : class Variable;
      78             : class VariableGroup;
      79             : 
      80             : /**
      81             :  * \brief Manages consistently variables, degrees of freedom, and coefficient
      82             :  * vectors.
      83             :  *
      84             :  * This is the base class for classes which contain information related to any
      85             :  * physical process that might be simulated. Such information may range from
      86             :  * the actual solution values to algorithmic flags that may be used to control
      87             :  * the numerical methods employed. In general, use an EquationSystems
      88             :  * object to handle one or more of the children of this class.
      89             :  *
      90             :  * Especially, this class manages the variables of the differential equation,
      91             :  * the coefficient vectors and the \p DofMap, and ensures that these are
      92             :  * consistent. It provides storage for the solution.  Furthermore, (de-)
      93             :  * serialization functionality is provided.
      94             :  *
      95             :  * \author Benjamin S. Kirk
      96             :  * \date 2003-2004
      97             :  */
      98             : class System : public ReferenceCountedObject<System>,
      99             :                public ParallelObject
     100             : {
     101             : public:
     102             : 
     103             :   /**
     104             :    * Constructor.  Optionally initializes required
     105             :    * data structures.
     106             :    */
     107             :   System (EquationSystems & es,
     108             :           const std::string & name,
     109             :           const unsigned int number);
     110             : 
     111             :   /**
     112             :    * Special functions.
     113             :    * - The copy constructor and assignment operator were previously
     114             :    *   declared as private libmesh_not_implemented() functions, this
     115             :    *   is the C++11 way of achieving the same effect.
     116             :    * - The System holds references to Mesh and EquationSystems
     117             :    *   objects, therefore it can't be default move-assigned.
     118             :    * - This class _can_ be default move constructed.
     119             :    * - The destructor dies with an error in dbg/devel modes if libMesh::closed()
     120             :    */
     121             :   System (const System &) = delete;
     122             :   System & operator= (const System &) = delete;
     123             :   System (System &&) = default;
     124             :   System & operator= (System &&) = delete;
     125             :   virtual ~System ();
     126             : 
     127             :   /**
     128             :    * Abstract base class to be used for system initialization.
     129             :    * A user class derived from this class may be used to
     130             :    * initialize the system values by attaching an object
     131             :    * with the method \p attach_init_object.
     132             :    */
     133             :   class Initialization
     134             :   {
     135             :   public:
     136             :     /**
     137             :      * Destructor.  Virtual because we will have virtual functions.
     138             :      */
     139             :     virtual ~Initialization () = default;
     140             : 
     141             :     /**
     142             :      * Initialization function.  This function will be called
     143             :      * to initialize the system values upon creation and must
     144             :      * be provided by the user in a derived class.
     145             :      */
     146             :     virtual void initialize () = 0;
     147             :   };
     148             : 
     149             : 
     150             : 
     151             :   /**
     152             :    * Abstract base class to be used for system assembly.
     153             :    * A user class derived from this class may be used to
     154             :    * assemble the system by attaching an object
     155             :    * with the method \p attach_assemble_object.
     156             :    */
     157             :   class Assembly
     158             :   {
     159             :   public:
     160             :     /**
     161             :      * Destructor.  Virtual because we will have virtual functions.
     162             :      */
     163             :     virtual ~Assembly () = default;
     164             : 
     165             :     /**
     166             :      * Assembly function.  This function will be called
     167             :      * to assemble the system prior to a solve and must
     168             :      * be provided by the user in a derived class.
     169             :      */
     170             :     virtual void assemble () = 0;
     171             :   };
     172             : 
     173             : 
     174             : 
     175             :   /**
     176             :    * Abstract base class to be used for system constraints.
     177             :    * A user class derived from this class may be used to
     178             :    * constrain the system by attaching an object
     179             :    * with the method \p attach_constraint_object.
     180             :    */
     181             :   class Constraint
     182             :   {
     183             :   public:
     184             :     /**
     185             :      * Destructor.  Virtual because we will have virtual functions.
     186             :      */
     187           0 :     virtual ~Constraint () = default;
     188             : 
     189             :     /**
     190             :      * Constraint function.  This function will be called
     191             :      * to constrain the system prior to a solve and must
     192             :      * be provided by the user in a derived class.
     193             :      */
     194             :     virtual void constrain () = 0;
     195             :   };
     196             : 
     197             : 
     198             : 
     199             :   /**
     200             :    * Abstract base class to be used for quantities of interest.
     201             :    * A user class derived from this class may be used to
     202             :    * compute quantities of interest by attaching an object
     203             :    * with the method \p attach_QOI_object.
     204             :    */
     205             :   class QOI
     206             :   {
     207             :   public:
     208             :     /**
     209             :      * Destructor.  Virtual because we will have virtual functions.
     210             :      */
     211             :     virtual ~QOI () = default;
     212             : 
     213             :     /**
     214             :      * Quantity of interest function.  This function will be called
     215             :      * to compute quantities of interest and must be provided by the
     216             :      * user in a derived class.
     217             :      */
     218             :     virtual void qoi (const QoISet & qoi_indices) = 0;
     219             :   };
     220             : 
     221             : 
     222             : 
     223             :   /**
     224             :    * Abstract base class to be used for derivatives of quantities
     225             :    * of interest. A user class derived from this class may be used
     226             :    * to compute quantities of interest by attaching an object
     227             :    * with the method \p attach_QOI_derivative_object.
     228             :    */
     229             :   class QOIDerivative
     230             :   {
     231             :   public:
     232             :     /**
     233             :      * Destructor.  Virtual because we will have virtual functions.
     234             :      */
     235             :     virtual ~QOIDerivative () = default;
     236             : 
     237             :     /**
     238             :      * Quantity of interest derivative function. This function will
     239             :      * be called to compute derivatives of quantities of interest and
     240             :      * must be provided by the user in a derived class.
     241             :      */
     242             :     virtual void qoi_derivative (const QoISet & qoi_indices,
     243             :                                  bool include_liftfunc,
     244             :                                  bool apply_constraints) = 0;
     245             :   };
     246             : 
     247             :   /**
     248             :    * The type of system.
     249             :    */
     250             :   typedef System sys_type;
     251             : 
     252             :   /**
     253             :    * \returns A reference to *this.
     254             :    */
     255             :   sys_type & system () { return *this; }
     256             : 
     257             :   /**
     258             :    * Clear all the data structures associated with
     259             :    * the system.
     260             :    */
     261             :   virtual void clear ();
     262             : 
     263             :   /**
     264             :    * Initializes degrees of freedom on the current mesh.
     265             :    * Sets the
     266             :    */
     267             :   void init ();
     268             : 
     269             :   /**
     270             :    * Reinitializes degrees of freedom and other required data on the
     271             :    * current mesh.
     272             :    *
     273             :    * \note The matrix is not initialized at this time since it may not
     274             :    * be required for all applications. Should be overridden in derived
     275             :    * classes.
     276             :    */
     277             :   virtual void reinit ();
     278             : 
     279             :   /**
     280             :    * Reinitializes the constraints for this system.
     281             :    *
     282             :    * Also prepares the send_list, whether or not constraints have
     283             :    * changed.
     284             :    */
     285             :   virtual void reinit_constraints ();
     286             : 
     287             :   /**
     288             :    * Recomputes the DirichletBoundary constraint values of this system
     289             :    * at the current \p time. If only time changed since the last call
     290             :    * to this method or to reinit_constraints(), the result is the same
     291             :    * as that of reinit_constraints(). This method reuses the
     292             :    * constraints that do not depend on time. See
     293             :    * DofMap::reinit_dirichlet_constraint_values().
     294             :    *
     295             :    * This method also prepares the send_list.
     296             :    */
     297             :   void reinit_dirichlet_constraint_values ();
     298             : 
     299             :   /**
     300             :    * Reinitializes the system with a new mesh.
     301             :    */
     302             :   virtual void reinit_mesh();
     303             : 
     304             :   /**
     305             :    * \returns \p true iff this system has been initialized.
     306             :    */
     307             :   bool is_initialized() const;
     308             : 
     309             :   /**
     310             :    * Update the local values to reflect the solution
     311             :    * on neighboring processors.
     312             :    */
     313             :   virtual void update ();
     314             : 
     315             :   /**
     316             :    * Prepares \p matrix and \p _dof_map for matrix assembly.
     317             :    * Does not actually assemble anything.  For matrix assembly,
     318             :    * use the \p assemble() in derived classes.
     319             :    * Should be overridden in derived classes.
     320             :    */
     321             :   virtual void assemble ();
     322             : 
     323             :   /**
     324             :    * Calls user qoi function.
     325             :    * Can be overridden in derived classes.
     326             :    */
     327             :   virtual void assemble_qoi (const QoISet & qoi_indices = QoISet());
     328             : 
     329             :   /**
     330             :    * Calls user qoi derivative function.
     331             :    * Can be overridden in derived classes.
     332             :    */
     333             :   virtual void assemble_qoi_derivative (const QoISet & qoi_indices = QoISet(),
     334             :                                         bool include_liftfunc = true,
     335             :                                         bool apply_constraints = true);
     336             : 
     337             :   /**
     338             :    * Calls residual parameter derivative function.
     339             :    *
     340             :    * Library subclasses use finite differences by default.
     341             :    *
     342             :    * This should assemble the sensitivity rhs vectors to hold
     343             :    * -(partial R / partial p_i), making them ready to solve
     344             :    * the forward sensitivity equation.
     345             :    *
     346             :    * This method is only implemented in some derived classes.
     347             :    */
     348             :   virtual void assemble_residual_derivatives (const ParameterVector & parameters);
     349             : 
     350             :   /**
     351             :    * After calling this method, any solve will be restricted to the
     352             :    * given subdomain.  To disable this mode, call this method with \p
     353             :    * subset being a \p nullptr.
     354             :    */
     355             :   virtual void restrict_solve_to (const SystemSubset * subset,
     356             :                                   const SubsetSolveMode subset_solve_mode=SUBSET_ZERO);
     357             : 
     358             :   /**
     359             :    * Solves the system.  Should be overridden in derived systems.
     360             :    */
     361           0 :   virtual void solve () {}
     362             : 
     363             :   /**
     364             :    * Solves the sensitivity system, for the provided parameters.
     365             :    * Must be overridden in derived systems.
     366             :    *
     367             :    * \returns A pair with the total number of linear iterations
     368             :    * performed and the (sum of the) final residual norms
     369             :    *
     370             :    * This method is only implemented in some derived classes.
     371             :    */
     372             :   virtual std::pair<unsigned int, Real>
     373             :   sensitivity_solve (const ParameterVector & parameters);
     374             : 
     375             :   /**
     376             :    * Assembles & solves the linear system(s) (dR/du)*u_w = sum(w_p*-dR/dp), for
     377             :    * those parameters p contained within \p parameters weighted by the
     378             :    * values w_p found within \p weights.
     379             :    *
     380             :    * \returns A pair with the total number of linear iterations
     381             :    * performed and the (sum of the) final residual norms
     382             :    *
     383             :    * This method is only implemented in some derived classes.
     384             :    */
     385             :   virtual std::pair<unsigned int, Real>
     386             :   weighted_sensitivity_solve (const ParameterVector & parameters,
     387             :                               const ParameterVector & weights);
     388             : 
     389             :   /**
     390             :    * Solves the adjoint system, for the specified qoi indices, or for
     391             :    * every qoi if \p qoi_indices is nullptr.  Must be overridden in
     392             :    * derived systems.
     393             :    *
     394             :    * \returns A pair with the total number of linear iterations
     395             :    * performed and the (sum of the) final residual norms
     396             :    *
     397             :    * This method is only implemented in some derived classes.
     398             :    */
     399             :   virtual std::pair<unsigned int, Real>
     400             :   adjoint_solve (const QoISet & qoi_indices = QoISet());
     401             : 
     402             :   /**
     403             :    * Assembles & solves the linear system(s)
     404             :    * (dR/du)^T*z_w = sum(w_p*(d^2q/dudp - d^2R/dudp*z)), for those
     405             :    * parameters p contained within \p parameters, weighted by the
     406             :    * values w_p found within \p weights.
     407             :    *
     408             :    * Assumes that adjoint_solve has already calculated z for each qoi
     409             :    * in \p qoi_indices.
     410             :    *
     411             :    * \returns A pair with the total number of linear iterations
     412             :    * performed and the (sum of the) final residual norms
     413             :    *
     414             :    * This method is only implemented in some derived classes.
     415             :    */
     416             :   virtual std::pair<unsigned int, Real>
     417             :   weighted_sensitivity_adjoint_solve (const ParameterVector & parameters,
     418             :                                       const ParameterVector & weights,
     419             :                                       const QoISet & qoi_indices = QoISet());
     420             :   /**
     421             :    * Accessor for the adjoint_already_solved boolean
     422             :    */
     423         784 :   bool is_adjoint_already_solved() const
     424       25384 :   { return adjoint_already_solved;}
     425             : 
     426             :   /**
     427             :    * Setter for the adjoint_already_solved boolean
     428             :    */
     429             :   void set_adjoint_already_solved(bool setting)
     430             :   { adjoint_already_solved = setting;}
     431             : 
     432             : 
     433             :   /**
     434             :    * Solves for the derivative of each of the system's quantities of
     435             :    * interest q in \p qoi[qoi_indices] with respect to each parameter
     436             :    * in \p parameters, placing the result for qoi \p i and parameter
     437             :    * \p j into \p sensitivities[i][j].
     438             :    *
     439             :    * \note \p parameters is a const vector, not a vector-of-const;
     440             :    * parameter values in this vector need to be mutable for finite
     441             :    * differencing to work.
     442             :    *
     443             :    * Automatically chooses the forward method for problems with more
     444             :    * quantities of interest than parameters, or the adjoint method
     445             :    * otherwise.
     446             :    *
     447             :    * This method is only usable in derived classes which override
     448             :    * an implementation.
     449             :    */
     450             :   virtual void qoi_parameter_sensitivity (const QoISet & qoi_indices,
     451             :                                           const ParameterVector & parameters,
     452             :                                           SensitivityData & sensitivities);
     453             : 
     454             :   /**
     455             :    * Solves for parameter sensitivities using the adjoint method.
     456             :    *
     457             :    * This method is only implemented in some derived classes.
     458             :    */
     459             :   virtual void adjoint_qoi_parameter_sensitivity (const QoISet & qoi_indices,
     460             :                                                   const ParameterVector & parameters,
     461             :                                                   SensitivityData & sensitivities);
     462             : 
     463             :   /**
     464             :    * Solves for parameter sensitivities using the forward method.
     465             :    *
     466             :    * This method is only implemented in some derived classes.
     467             :    */
     468             :   virtual void forward_qoi_parameter_sensitivity (const QoISet & qoi_indices,
     469             :                                                   const ParameterVector & parameters,
     470             :                                                   SensitivityData & sensitivities);
     471             : 
     472             :   /**
     473             :    * For each of the system's quantities of interest q in
     474             :    * \p qoi[qoi_indices], and for a vector of parameters p, the
     475             :    * parameter sensitivity Hessian H_ij is defined as
     476             :    * H_ij = (d^2 q)/(d p_i d p_j)
     477             :    * This Hessian is the output of this method, where for each q_i,
     478             :    * H_jk is stored in \p hessian.second_derivative(i,j,k).
     479             :    *
     480             :    * This method is only implemented in some derived classes.
     481             :    */
     482             :   virtual void qoi_parameter_hessian(const QoISet & qoi_indices,
     483             :                                      const ParameterVector & parameters,
     484             :                                      SensitivityData & hessian);
     485             : 
     486             :   /**
     487             :    * For each of the system's quantities of interest q in
     488             :    * \p qoi[qoi_indices], and for a vector of parameters p, the
     489             :    * parameter sensitivity Hessian H_ij is defined as
     490             :    * H_ij = (d^2 q)/(d p_i d p_j)
     491             :    * The Hessian-vector product, for a vector v_k in parameter space, is
     492             :    * S_j = H_jk v_k
     493             :    * This product is the output of this method, where for each q_i,
     494             :    * S_j is stored in \p sensitivities[i][j].
     495             :    *
     496             :    * This method is only implemented in some derived classes.
     497             :    */
     498             :   virtual void qoi_parameter_hessian_vector_product(const QoISet & qoi_indices,
     499             :                                                     const ParameterVector & parameters,
     500             :                                                     const ParameterVector & vector,
     501             :                                                     SensitivityData & product);
     502             : 
     503             :   /**
     504             :    * \returns \p true when the other system contains
     505             :    * identical data, up to the given threshold.  Outputs
     506             :    * some diagnostic info when \p verbose is set.
     507             :    */
     508             :   virtual bool compare (const System & other_system,
     509             :                         const Real threshold,
     510             :                         const bool verbose) const;
     511             : 
     512             :   /**
     513             :    * \returns The system name.
     514             :    */
     515             :   const std::string & name () const;
     516             : 
     517             :   /**
     518             :    * \returns The type of system, helpful in identifying
     519             :    * which system type to use when reading equation system
     520             :    * data from file.  Should be overridden in derived classes.
     521             :    */
     522          12 :   virtual std::string system_type () const { return "Basic"; }
     523             : 
     524             :   /**
     525             :    * Projects arbitrary functions onto the current solution.
     526             :    * The function value \p f and its gradient \p g are
     527             :    * user-provided cloneable functors.
     528             :    * A gradient \p g is only required/used for projecting onto finite
     529             :    * element spaces with continuous derivatives.
     530             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     531             :    * over which to perform the projection.
     532             :    * variable_numbers \p variable_numbers, if provided, indicates the variable numbers
     533             :    * onto which to project.
     534             :    */
     535             :   void project_solution (FunctionBase<Number> * f,
     536             :                          FunctionBase<Gradient> * g = nullptr,
     537             :                          std::optional<ConstElemRange> active_local_range = std::nullopt,
     538             :                          std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
     539             : 
     540             :   /**
     541             :    * Projects arbitrary functions onto the current solution.
     542             :    * The function value \p f and its gradient \p g are
     543             :    * user-provided cloneable functors.
     544             :    * A gradient \p g is only required/used for projecting onto finite
     545             :    * element spaces with continuous derivatives.
     546             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     547             :    * over which to perform the projection.
     548             :    * variable_numbers \p variable_numbers, if provided, indicates the variable numbers
     549             :    * onto which to project.
     550             :    */
     551             :   void project_solution (FEMFunctionBase<Number> * f,
     552             :                          FEMFunctionBase<Gradient> * g = nullptr,
     553             :                          std::optional<ConstElemRange> active_local_range = std::nullopt,
     554             :                          std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
     555             : 
     556             :   /**
     557             :    * Projects arbitrary functions onto the current solution.
     558             :    * The function value \p fptr and its gradient \p gptr are
     559             :    * represented by function pointers.
     560             :    * A gradient \p gptr is only required/used for projecting onto
     561             :    * finite element spaces with continuous derivatives.
     562             :    */
     563             :   typedef Number (*ValueFunctionPointer)(const Point & p,
     564             :                                          const Parameters & Parameters,
     565             :                                          const std::string & sys_name,
     566             :                                          const std::string & unknown_name);
     567             :   typedef Gradient (*GradientFunctionPointer)(const Point & p,
     568             :                                               const Parameters & parameters,
     569             :                                               const std::string & sys_name,
     570             :                                               const std::string & unknown_name);
     571             :   void project_solution (ValueFunctionPointer fptr,
     572             :                          GradientFunctionPointer gptr,
     573             :                          const Parameters & parameters,
     574             :                          std::optional<ConstElemRange> active_local_range = std::nullopt,
     575             :                          std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
     576             : 
     577             :   /**
     578             :    * Projects arbitrary functions onto a vector of degree of freedom
     579             :    * values for the current system.
     580             :    * The function value \p f and its gradient \p g are
     581             :    * user-provided cloneable functors.
     582             :    * A gradient \p g is only required/used for projecting onto finite
     583             :    * element spaces with continuous derivatives.
     584             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     585             :    * over which to perform the projection.
     586             :    * variable_numbers \p variable_numbers, if provided, indicates the variable numbers
     587             :    * onto which to project.
     588             :    *
     589             :    * Constrain the new vector using the requested adjoint rather than
     590             :    * primal constraints if is_adjoint is non-negative.
     591             :    */
     592             :   void project_vector (NumericVector<Number> & new_vector,
     593             :                        FunctionBase<Number> * f,
     594             :                        FunctionBase<Gradient> * g = nullptr,
     595             :                        int is_adjoint = -1,
     596             :                        std::optional<ConstElemRange> active_local_range = std::nullopt,
     597             :                        std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
     598             : 
     599             :   /**
     600             :    * Projects arbitrary functions onto a vector of degree of freedom
     601             :    * values for the current system.
     602             :    * The function value \p f and its gradient \p g are
     603             :    * user-provided cloneable functors.
     604             :    * A gradient \p g is only required/used for projecting onto finite
     605             :    * element spaces with continuous derivatives.
     606             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     607             :    * over which to perform the projection.
     608             :    * variable_numbers \p variable_numbers, if provided, indicates the variable numbers
     609             :    * onto which to project.
     610             :    *
     611             :    * Constrain the new vector using the requested adjoint rather than
     612             :    * primal constraints if is_adjoint is non-negative.
     613             :    */
     614             :   void project_vector (NumericVector<Number> & new_vector,
     615             :                        FEMFunctionBase<Number> * f,
     616             :                        FEMFunctionBase<Gradient> * g = nullptr,
     617             :                        int is_adjoint = -1,
     618             :                        std::optional<ConstElemRange> active_local_range = std::nullopt,
     619             :                        std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
     620             : 
     621             :   /**
     622             :    * Projects arbitrary functions onto a vector of degree of freedom
     623             :    * values for the current system.
     624             :    * The function value \p fptr and its gradient \p gptr are
     625             :    * represented by function pointers.
     626             :    * A gradient \p gptr is only required/used for projecting onto
     627             :    * finite element spaces with continuous derivatives.
     628             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     629             :    * over which to perform the projection.
     630             :    * variable_numbers \p variable_numbers, if provided, indicates the variable numbers
     631             :    * onto which to project.
     632             :    *
     633             :    * Constrain the new vector using the requested adjoint rather than
     634             :    * primal constraints if is_adjoint is non-negative.
     635             :    */
     636             :   void project_vector (ValueFunctionPointer fptr,
     637             :                        GradientFunctionPointer gptr,
     638             :                        const Parameters & parameters,
     639             :                        NumericVector<Number> & new_vector,
     640             :                        int is_adjoint = -1,
     641             :                        std::optional<ConstElemRange> active_local_range = std::nullopt,
     642             :                        std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
     643             : 
     644             :   /**
     645             :    * Projects arbitrary boundary functions onto a vector of degree of
     646             :    * freedom values for the current system.
     647             :    * Only degrees of freedom which affect the function's trace on a
     648             :    * boundary in the set \p b are affected.
     649             :    * Only degrees of freedom associated with the variables listed in
     650             :    * the vector \p variables are projected.
     651             :    * The function value \p f and its gradient \p g are
     652             :    * user-provided cloneable functors.
     653             :    * A gradient \p g is only required/used for projecting onto finite
     654             :    * element spaces with continuous derivatives.
     655             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     656             :    * over which to perform the projection.
     657             :    */
     658             :   void boundary_project_solution (const std::set<boundary_id_type> & b,
     659             :                                   const std::vector<unsigned int> & variables,
     660             :                                   FunctionBase<Number> * f,
     661             :                                   FunctionBase<Gradient> * g = nullptr,
     662             :                                   std::optional<ConstElemRange> active_local_range = std::nullopt);
     663             : 
     664             :   /**
     665             :    * Projects arbitrary boundary functions onto a vector of degree of
     666             :    * freedom values for the current system.
     667             :    * Only degrees of freedom which affect the function's trace on a
     668             :    * boundary in the set \p b are affected.
     669             :    * Only degrees of freedom associated with the variables listed in
     670             :    * the vector \p variables are projected.
     671             :    * The function value \p fptr and its gradient \p gptr are
     672             :    * represented by function pointers.
     673             :    * A gradient \p gptr is only required/used for projecting onto
     674             :    * finite element spaces with continuous derivatives.
     675             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     676             :    * over which to perform the projection.
     677             :    */
     678             :   void boundary_project_solution (const std::set<boundary_id_type> & b,
     679             :                                   const std::vector<unsigned int> & variables,
     680             :                                   ValueFunctionPointer fptr,
     681             :                                   GradientFunctionPointer gptr,
     682             :                                   const Parameters & parameters,
     683             :                                   std::optional<ConstElemRange> active_local_range = std::nullopt);
     684             : 
     685             :   /**
     686             :    * Projects arbitrary boundary functions onto a vector of degree of
     687             :    * freedom values for the current system.
     688             :    * Only degrees of freedom which affect the function's trace on a
     689             :    * boundary in the set \p b are affected.
     690             :    * Only degrees of freedom associated with the variables listed in
     691             :    * the vector \p variables are projected.
     692             :    * The function value \p f and its gradient \p g are
     693             :    * user-provided cloneable functors.
     694             :    * A gradient \p g is only required/used for projecting onto finite
     695             :    * element spaces with continuous derivatives.
     696             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     697             :    * over which to perform the projection.
     698             :    *
     699             :    * Constrain the new vector using the requested adjoint rather than
     700             :    * primal constraints if is_adjoint is non-negative.
     701             :    */
     702             :   void boundary_project_vector (const std::set<boundary_id_type> & b,
     703             :                                 const std::vector<unsigned int> & variables,
     704             :                                 NumericVector<Number> & new_vector,
     705             :                                 FunctionBase<Number> * f,
     706             :                                 FunctionBase<Gradient> * g = nullptr,
     707             :                                 int is_adjoint = -1,
     708             :                                 std::optional<ConstElemRange> active_local_range = std::nullopt) const;
     709             : 
     710             :   /**
     711             :    * Projects arbitrary boundary functions onto a vector of degree of
     712             :    * freedom values for the current system.
     713             :    * Only degrees of freedom which affect the function's trace on a
     714             :    * boundary in the set \p b are affected.
     715             :    * Only degrees of freedom associated with the variables listed in
     716             :    * the vector \p variables are projected.
     717             :    * The function value \p fptr and its gradient \p gptr are
     718             :    * represented by function pointers.
     719             :    * A gradient \p gptr is only required/used for projecting onto
     720             :    * finite element spaces with continuous derivatives.
     721             :    * elem_range \p active_local_range, if provided, indicates the range of elements
     722             :    * over which to perform the projection.
     723             :    *
     724             :    * Constrain the new vector using the requested adjoint rather than
     725             :    * primal constraints if is_adjoint is non-negative.
     726             :    */
     727             :   void boundary_project_vector (const std::set<boundary_id_type> & b,
     728             :                                 const std::vector<unsigned int> & variables,
     729             :                                 ValueFunctionPointer fptr,
     730             :                                 GradientFunctionPointer gptr,
     731             :                                 const Parameters & parameters,
     732             :                                 NumericVector<Number> & new_vector,
     733             :                                 int is_adjoint = -1,
     734             :                                 std::optional<ConstElemRange> active_local_range = std::nullopt) const;
     735             : 
     736             :   /**
     737             :    * \returns The system number.
     738             :    */
     739             :   unsigned int number () const;
     740             : 
     741             :   /**
     742             :    * Fill the input vector \p global_soln so that it contains
     743             :    * the global solution on all processors.
     744             :    * Requires communication with all other processors.
     745             :    */
     746             :   void update_global_solution (std::vector<Number> & global_soln) const;
     747             : 
     748             :   /**
     749             :    * Fill the input vector \p global_soln so that it contains
     750             :    * the global solution on processor \p dest_proc.
     751             :    * Requires communication with all other processors.
     752             :    */
     753             :   void update_global_solution (std::vector<Number> & global_soln,
     754             :                                const processor_id_type dest_proc) const;
     755             : 
     756             :   /**
     757             :    * \returns A constant reference to this systems's \p _mesh.
     758             :    */
     759             :   const MeshBase & get_mesh() const;
     760             : 
     761             :   /**
     762             :    * \returns A reference to this systems's \p _mesh.
     763             :    */
     764             :   MeshBase & get_mesh();
     765             : 
     766             :   /**
     767             :    * \returns A constant reference to this system's \p _dof_map.
     768             :    */
     769             :   const DofMap & get_dof_map() const;
     770             : 
     771             :   /**
     772             :    * \returns A writable reference to this system's \p _dof_map.
     773             :    */
     774             :   DofMap & get_dof_map();
     775             : 
     776             :   /**
     777             :    * \returns A constant reference to this system's parent EquationSystems object.
     778             :    */
     779      616186 :   const EquationSystems & get_equation_systems() const { return _equation_systems; }
     780             : 
     781             :   /**
     782             :    * \returns A reference to this system's parent EquationSystems object.
     783             :    */
     784      223677 :   EquationSystems & get_equation_systems() { return _equation_systems; }
     785             : 
     786             :   /**
     787             :    * \returns \p true if the system is active, \p false otherwise.
     788             :    * An active system will be solved.
     789             :    */
     790             :   bool active () const;
     791             : 
     792             :   /**
     793             :    * Activates the system.  Only active systems are solved.
     794             :    */
     795             :   void activate ();
     796             : 
     797             :   /**
     798             :    * Deactivates the system.  Only active systems are solved.
     799             :    */
     800             :   void deactivate ();
     801             : 
     802             :   /**
     803             :    * Sets the system to be "basic only": i.e. advanced system
     804             :    * components such as ImplicitSystem matrices may not be
     805             :    * initialized.  This is useful for efficiency in certain utility
     806             :    * programs that never use System::solve().  This method must be
     807             :    * called after the System or derived class is created but before it
     808             :    * is initialized; e.g. from within EquationSystems::read()
     809             :    */
     810             :   void set_basic_system_only ();
     811             : 
     812             :   /**
     813             :    * Vector iterator typedefs.
     814             :    */
     815             :   typedef std::map<std::string, std::unique_ptr<NumericVector<Number>>, std::less<>>::iterator       vectors_iterator;
     816             :   typedef std::map<std::string, std::unique_ptr<NumericVector<Number>>, std::less<>>::const_iterator const_vectors_iterator;
     817             : 
     818             :   /**
     819             :    * Beginning of vectors container
     820             :    */
     821             :   vectors_iterator vectors_begin ();
     822             : 
     823             :   /**
     824             :    * Beginning of vectors container
     825             :    */
     826             :   const_vectors_iterator vectors_begin () const;
     827             : 
     828             :   /**
     829             :    * End of vectors container
     830             :    */
     831             :   vectors_iterator vectors_end ();
     832             : 
     833             :   /**
     834             :    * End of vectors container
     835             :    */
     836             :   const_vectors_iterator vectors_end () const;
     837             : 
     838             :   /**
     839             :    * Matrix iterator typedefs.
     840             :    */
     841             :   typedef std::map<std::string, std::unique_ptr<SparseMatrix<Number>>, std::less<>>::iterator        matrices_iterator;
     842             :   typedef std::map<std::string, std::unique_ptr<SparseMatrix<Number>>, std::less<>>::const_iterator  const_matrices_iterator;
     843             : 
     844             :   /**
     845             :    * Beginning of matrices container
     846             :    */
     847             :   matrices_iterator matrices_begin ();
     848             : 
     849             :   /**
     850             :    * Beginning of matrices container
     851             :    */
     852             :   const_matrices_iterator matrices_begin () const;
     853             : 
     854             :   /**
     855             :    * End of matrices container
     856             :    */
     857             :   matrices_iterator matrices_end ();
     858             : 
     859             :   /**
     860             :    * End of matrices container
     861             :    */
     862             :   const_matrices_iterator matrices_end () const;
     863             : 
     864             :   /**
     865             :    * Adds the additional vector \p vec_name to this system.  All the
     866             :    * additional vectors are similarly distributed, like the \p
     867             :    * solution, and initialized to zero.
     868             :    *
     869             :    * By default vectors added by add_vector are projected to changed grids by
     870             :    * reinit().  To zero them instead (more efficient), pass "false" as the
     871             :    * second argument
     872             :    *
     873             :    * If the vector already exists, the existing vector is returned.
     874             :    * after any upgrade to the \p projections or \p type has been made.
     875             :    * We *only* handle upgrades (projections false->true, or type
     876             :    * PARALLEL->GHOSTED) in this fashion, not downgrades, on the theory
     877             :    * that if two codes have differing needs we want to support the
     878             :    * union of those needs, not the intersection.  Downgrades can only
     879             :    * be accomplished manually, via \p set_vector_preservation() or by
     880             :    * setting a vector \p type() and re-initializing.
     881             :    */
     882             :   NumericVector<Number> & add_vector (std::string_view vec_name,
     883             :                                       const bool projections=true,
     884             :                                       const ParallelType type = PARALLEL);
     885             : 
     886             :   /**
     887             :    * Removes the additional vector \p vec_name from this system
     888             :    */
     889             :   void remove_vector(std::string_view vec_name);
     890             : 
     891             :   /**
     892             :    * Tells the System whether or not to project the solution vector onto new
     893             :    * grids when the system is reinitialized.  The solution will be projected
     894             :    * unless project_solution_on_reinit() = false is called.
     895             :    */
     896        2392 :   bool & project_solution_on_reinit (void)
     897        2392 :   { return _solution_projection; }
     898             : 
     899             :   /**
     900             :    * \returns \p true if this \p System has a vector associated with the
     901             :    * given name, \p false otherwise.
     902             :    */
     903             :   bool have_vector (std::string_view vec_name) const;
     904             : 
     905             :   /**
     906             :    * \returns A const pointer to the vector if this \p System has a
     907             :    * vector associated with the given name, \p nullptr otherwise.
     908             :    */
     909             :   const NumericVector<Number> * request_vector (std::string_view vec_name) const;
     910             : 
     911             :   /**
     912             :    * \returns A pointer to the vector if this \p System has a
     913             :    * vector associated with the given name, \p nullptr otherwise.
     914             :    */
     915             :   NumericVector<Number> * request_vector (std::string_view vec_name);
     916             : 
     917             :   /**
     918             :    * \returns A const pointer to this system's additional vector
     919             :    * number \p vec_num (where the vectors are counted starting with
     920             :    * 0), or \p nullptr if the system has no such vector.
     921             :    */
     922             :   const NumericVector<Number> * request_vector (const unsigned int vec_num) const;
     923             : 
     924             :   /**
     925             :    * \returns A writable pointer to this system's additional
     926             :    * vector number \p vec_num (where the vectors are counted starting
     927             :    * with 0), or \p nullptr if the system has no such vector.
     928             :    */
     929             :   NumericVector<Number> * request_vector (const unsigned int vec_num);
     930             : 
     931             :   /**
     932             :    * \returns A const reference to this system's additional vector
     933             :    * named \p vec_name.  Access is only granted when the vector is already
     934             :    * properly initialized.
     935             :    */
     936             :   const NumericVector<Number> & get_vector (std::string_view vec_name) const;
     937             : 
     938             :   /**
     939             :    * \returns A writable reference to this system's additional vector
     940             :    * named \p vec_name.  Access is only granted when the vector is already
     941             :    * properly initialized.
     942             :    */
     943             :   NumericVector<Number> & get_vector (std::string_view vec_name);
     944             : 
     945             :   /**
     946             :    * \returns A const reference to this system's additional vector
     947             :    * number \p vec_num (where the vectors are counted starting with
     948             :    * 0).
     949             :    */
     950             :   const NumericVector<Number> & get_vector (const unsigned int vec_num) const;
     951             : 
     952             :   /**
     953             :    * \returns A writable reference to this system's additional
     954             :    * vector number \p vec_num (where the vectors are counted starting
     955             :    * with 0).
     956             :    */
     957             :   NumericVector<Number> & get_vector (const unsigned int vec_num);
     958             : 
     959             :   /**
     960             :    * \returns The name of this system's additional vector number \p
     961             :    * vec_num (where the vectors are counted starting with 0).
     962             :    */
     963             :   const std::string & vector_name (const unsigned int vec_num) const;
     964             : 
     965             :   /**
     966             :    * \returns The name of a system vector, given a reference to that vector
     967             :    */
     968             :   const std::string & vector_name (const NumericVector<Number> & vec_reference) const;
     969             : 
     970             :   /**
     971             :    * Allows one to set the QoI index controlling whether the vector
     972             :    * identified by vec_name represents a solution from the adjoint
     973             :    * (qoi_num >= 0) or primal (qoi_num == -1) space.  This becomes
     974             :    * significant if those spaces have differing heterogeneous
     975             :    * Dirichlet constraints.
     976             :    *
     977             :    * qoi_num == -2 can be used to indicate a vector which should not
     978             :    * be affected by constraints during projection operations.
     979             :    */
     980             :   void set_vector_as_adjoint (const std::string & vec_name, int qoi_num);
     981             : 
     982             :   /**
     983             :    * \returns The integer describing whether the vector identified by
     984             :    * vec_name represents a solution from an adjoint (non-negative) or
     985             :    * the primal (-1) space.
     986             :    */
     987             :   int vector_is_adjoint (std::string_view vec_name) const;
     988             : 
     989             :   /**
     990             :    * Allows one to set the boolean controlling whether the vector
     991             :    * identified by vec_name should be "preserved": projected to new
     992             :    * meshes, saved, etc.
     993             :    */
     994             :   void set_vector_preservation (const std::string & vec_name, bool preserve);
     995             : 
     996             :   /**
     997             :    * \returns The boolean describing whether the vector identified by
     998             :    * vec_name should be "preserved": projected to new meshes, saved,
     999             :    * etc.
    1000             :    */
    1001             :   bool vector_preservation (std::string_view vec_name) const;
    1002             : 
    1003             :   /**
    1004             :    * \returns A reference to one of the system's adjoint solution
    1005             :    * vectors, by default the one corresponding to the first qoi.
    1006             :    * Creates the vector if it doesn't already exist.
    1007             :    */
    1008             :   NumericVector<Number> & add_adjoint_solution(unsigned int i=0);
    1009             : 
    1010             :   /**
    1011             :    * \returns A reference to one of the system's adjoint solution
    1012             :    * vectors, by default the one corresponding to the first qoi.
    1013             :    */
    1014             :   NumericVector<Number> & get_adjoint_solution(unsigned int i=0);
    1015             : 
    1016             :   /**
    1017             :    * \returns A reference to one of the system's adjoint solution
    1018             :    * vectors, by default the one corresponding to the first qoi.
    1019             :    */
    1020             :   const NumericVector<Number> & get_adjoint_solution(unsigned int i=0) const;
    1021             : 
    1022             :   /**
    1023             :    * \returns A reference to one of the system's solution sensitivity
    1024             :    * vectors, by default the one corresponding to the first parameter.
    1025             :    * Creates the vector if it doesn't already exist.
    1026             :    */
    1027             :   NumericVector<Number> & add_sensitivity_solution(unsigned int i=0);
    1028             : 
    1029             :   /**
    1030             :    * \returns A reference to one of the system's solution sensitivity
    1031             :    * vectors, by default the one corresponding to the first parameter.
    1032             :    */
    1033             :   NumericVector<Number> & get_sensitivity_solution(unsigned int i=0);
    1034             : 
    1035             :   /**
    1036             :    * \returns A reference to one of the system's solution sensitivity
    1037             :    * vectors, by default the one corresponding to the first parameter.
    1038             :    */
    1039             :   const NumericVector<Number> & get_sensitivity_solution(unsigned int i=0) const;
    1040             : 
    1041             :   /**
    1042             :    * \returns A reference to one of the system's weighted sensitivity
    1043             :    * adjoint solution vectors, by default the one corresponding to the
    1044             :    * first qoi.
    1045             :    * Creates the vector if it doesn't already exist.
    1046             :    */
    1047             :   NumericVector<Number> & add_weighted_sensitivity_adjoint_solution(unsigned int i=0);
    1048             : 
    1049             :   /**
    1050             :    * \returns A reference to one of the system's weighted sensitivity
    1051             :    * adjoint solution vectors, by default the one corresponding to the
    1052             :    * first qoi.
    1053             :    */
    1054             :   NumericVector<Number> & get_weighted_sensitivity_adjoint_solution(unsigned int i=0);
    1055             : 
    1056             :   /**
    1057             :    * \returns A reference to one of the system's weighted sensitivity
    1058             :    * adjoint solution vectors, by default the one corresponding to the
    1059             :    * first qoi.
    1060             :    */
    1061             :   const NumericVector<Number> & get_weighted_sensitivity_adjoint_solution(unsigned int i=0) const;
    1062             : 
    1063             :   /**
    1064             :    * \returns A reference to the solution of the last weighted
    1065             :    * sensitivity solve
    1066             :    * Creates the vector if it doesn't already exist.
    1067             :    */
    1068             :   NumericVector<Number> & add_weighted_sensitivity_solution();
    1069             : 
    1070             :   /**
    1071             :    * \returns A reference to the solution of the last weighted
    1072             :    * sensitivity solve
    1073             :    */
    1074             :   NumericVector<Number> & get_weighted_sensitivity_solution();
    1075             : 
    1076             :   /**
    1077             :    * \returns A reference to the solution of the last weighted
    1078             :    * sensitivity solve
    1079             :    */
    1080             :   const NumericVector<Number> & get_weighted_sensitivity_solution() const;
    1081             : 
    1082             :   /**
    1083             :    * \returns A reference to one of the system's adjoint rhs
    1084             :    * vectors, by default the one corresponding to the first qoi.
    1085             :    * Creates the vector if it doesn't already exist.
    1086             :    */
    1087             :   NumericVector<Number> & add_adjoint_rhs(unsigned int i=0);
    1088             : 
    1089             :   /**
    1090             :    * \returns A reference to one of the system's adjoint rhs
    1091             :    * vectors, by default the one corresponding to the first qoi.
    1092             :    * This what the user's QoI derivative code should assemble
    1093             :    * when setting up an adjoint problem
    1094             :    */
    1095             :   NumericVector<Number> & get_adjoint_rhs(unsigned int i=0);
    1096             : 
    1097             :   /**
    1098             :    * \returns A reference to one of the system's adjoint rhs
    1099             :    * vectors, by default the one corresponding to the first qoi.
    1100             :    */
    1101             :   const NumericVector<Number> & get_adjoint_rhs(unsigned int i=0) const;
    1102             : 
    1103             :   /**
    1104             :    * \returns A reference to one of the system's sensitivity rhs
    1105             :    * vectors, by default the one corresponding to the first parameter.
    1106             :    * Creates the vector if it doesn't already exist.
    1107             :    */
    1108             :   NumericVector<Number> & add_sensitivity_rhs(unsigned int i=0);
    1109             : 
    1110             :   /**
    1111             :    * \returns A reference to one of the system's sensitivity rhs
    1112             :    * vectors, by default the one corresponding to the first parameter.
    1113             :    * By default these vectors are built by the library, using finite
    1114             :    * differences, when \p assemble_residual_derivatives() is called.
    1115             :    *
    1116             :    * When assembled, this vector should hold
    1117             :    * -(partial R / partial p_i)
    1118             :    */
    1119             :   NumericVector<Number> & get_sensitivity_rhs(unsigned int i=0);
    1120             : 
    1121             :   /**
    1122             :    * \returns A reference to one of the system's sensitivity rhs
    1123             :    * vectors, by default the one corresponding to the first parameter.
    1124             :    */
    1125             :   const NumericVector<Number> & get_sensitivity_rhs(unsigned int i=0) const;
    1126             : 
    1127             :   /**
    1128             :    * \returns The number of vectors (in addition to the solution)
    1129             :    * handled by this system
    1130             :    * This is the size of the \p _vectors map
    1131             :    */
    1132             :   unsigned int n_vectors () const;
    1133             : 
    1134             :   /**
    1135             :    * \returns The number of matrices
    1136             :    * handled by this system.
    1137             :    * This is the size of the \p _matrices map
    1138             :    */
    1139             :   unsigned int n_matrices () const;
    1140             : 
    1141             :   /**
    1142             :    * \returns The number of variables in the system
    1143             :    */
    1144             :   unsigned int n_vars() const;
    1145             : 
    1146             :   /**
    1147             :    * \returns The number of \p VariableGroup variable groups in the system
    1148             :    */
    1149             :   unsigned int n_variable_groups() const;
    1150             : 
    1151             :   /**
    1152             :    * \returns The total number of scalar components in the system's
    1153             :    * variables.  This will equal \p n_vars() in the case of all
    1154             :    * scalar-valued variables.
    1155             :    */
    1156             :   unsigned int n_components() const;
    1157             : 
    1158             :   /**
    1159             :    * \returns The number of degrees of freedom in the system
    1160             :    */
    1161             :   dof_id_type n_dofs() const;
    1162             : 
    1163             :   /**
    1164             :    * \returns The number of active degrees of freedom
    1165             :    * for this System.
    1166             :    */
    1167             :   dof_id_type n_active_dofs() const;
    1168             : 
    1169             :   /**
    1170             :    * \returns The total number of constrained degrees of freedom
    1171             :    * in the system.
    1172             :    */
    1173             :   dof_id_type n_constrained_dofs() const;
    1174             : 
    1175             :   /**
    1176             :    * \returns The number of constrained degrees of freedom
    1177             :    * on this processor.
    1178             :    */
    1179             :   dof_id_type n_local_constrained_dofs() const;
    1180             : 
    1181             :   /**
    1182             :    * \returns The number of degrees of freedom local
    1183             :    * to this processor
    1184             :    */
    1185             :   dof_id_type n_local_dofs() const;
    1186             : 
    1187             :   /**
    1188             :    * Adds the variable \p var to the list of variables
    1189             :    * for this system. If \p active_subdomains is either \p nullptr
    1190             :    * (the default) or points to an empty set, then it will be assumed that
    1191             :    * \p var has no subdomain restrictions
    1192             :    *
    1193             :    * \returns The index number for the new variable.
    1194             :    */
    1195             :   unsigned int add_variable (std::string_view var,
    1196             :                              const FEType & type,
    1197             :                              const std::set<subdomain_id_type> * const active_subdomains = nullptr);
    1198             : 
    1199             :   /**
    1200             :    * Adds the variable \p var to the list of variables
    1201             :    * for this system.  Same as before, but assumes \p LAGRANGE
    1202             :    * as default value for \p FEType.family. If \p active_subdomains is either
    1203             :    * \p nullptr (the default) or points to an empty set, then it will be assumed
    1204             :    * that \p var has no subdomain restrictions. If \p p_refinement is
    1205             :    * false, then even when on an \p Elem with non-zero \p p_level()
    1206             :    * this variable will not be p-refined.
    1207             :    */
    1208             :   unsigned int add_variable (std::string_view var,
    1209             :                              const Order order = FIRST,
    1210             :                              const FEFamily = LAGRANGE,
    1211             :                              const std::set<subdomain_id_type> * const active_subdomains = nullptr,
    1212             :                              const bool p_refinement = true);
    1213             : 
    1214             :   /**
    1215             :    * Adds the variables \p vars to the list of variables
    1216             :    * for this system. If \p active_subdomains is either \p nullptr
    1217             :    * (the default) or points to an empty set, then it will be assumed that
    1218             :    * the \p vars have no subdomain restrictions
    1219             :    *
    1220             :    * \returns The index number for the last of the new variables.
    1221             :    */
    1222             :   unsigned int add_variables (const std::vector<std::string> & vars,
    1223             :                               const FEType & type,
    1224             :                               const std::set<subdomain_id_type> * const active_subdomains = nullptr);
    1225             : 
    1226             :   /**
    1227             :    * Adds variables \p vars to the list of variables
    1228             :    * for this system. If \p active_subdomains is either \p nullptr
    1229             :    * (the default) or points to an empty set, then it will be assumed that
    1230             :    * the \p vars have no subdomain restrictions. This API will end up
    1231             :    * calling \p this->add_variables(). However, we will additionally store data
    1232             :    * that can be leveraged by the \p DofMap to build degrees of freedom
    1233             :    * containers corresponding to all the variables in this variable array
    1234             :    *
    1235             :    * An 'array variable' is simply a sequence
    1236             :    * of contiguous variable numbers defined by pair where the first member of the pair
    1237             :    * is the first number in the variable sequence and the second member of the pair is
    1238             :    * the number of the last variable in the sequence plus one. Array variables may be
    1239             :    * used in tandem with variable grouping by downstream code to build optimized physics
    1240             :    * kernels since each variable in the array will have the same shape functions.
    1241             :    *
    1242             :    * \returns The index number for the last of the new variables.
    1243             :    */
    1244             :   unsigned int add_variable_array (const std::vector<std::string> & vars,
    1245             :                                    const FEType & type,
    1246             :                                    const std::set<subdomain_id_type> * const active_subdomains = nullptr);
    1247             : 
    1248             :   /**
    1249             :    * Adds the variable \p var to the list of variables
    1250             :    * for this system.  Same as before, but assumes \p LAGRANGE
    1251             :    * as default value for \p FEType.family. If \p active_subdomains is either
    1252             :    * \p nullptr (the default) or points to an empty set, then it will be assumed that
    1253             :    * \p var has no subdomain restrictions. If \p p_refinement is
    1254             :    * false, then even when on an \p Elem with non-zero \p p_level()
    1255             :    * this variable will not be p-refined.
    1256             :    */
    1257             :   unsigned int add_variables (const std::vector<std::string> & vars,
    1258             :                               const Order order = FIRST,
    1259             :                               const FEFamily = LAGRANGE,
    1260             :                               const std::set<subdomain_id_type> * const active_subdomains = nullptr,
    1261             :                               const bool p_refinement = true);
    1262             : 
    1263             :   /**
    1264             :    * Return a constant reference to \p Variable \p var.
    1265             :    */
    1266             :   const Variable & variable (unsigned int var) const;
    1267             : 
    1268             :   /**
    1269             :    * Return a constant reference to \p VariableGroup \p vg.
    1270             :    */
    1271             :   const VariableGroup & variable_group (unsigned int vg) const;
    1272             : 
    1273             :   /**
    1274             :    * \returns \p true if a variable named \p var exists in this System
    1275             :    */
    1276             :   bool has_variable(std::string_view var) const;
    1277             : 
    1278             :   /**
    1279             :    * \returns The name of variable \p i.
    1280             :    */
    1281             :   const std::string & variable_name(const unsigned int i) const;
    1282             : 
    1283             :   /**
    1284             :    * \returns The variable number associated with
    1285             :    * the user-specified variable named \p var.
    1286             :    */
    1287             :   unsigned int variable_number (std::string_view var) const;
    1288             : 
    1289             :   /**
    1290             :    * Fills \p all_variable_numbers with all the variable numbers for the
    1291             :    * variables that have been added to this system.
    1292             :    */
    1293             :   void get_all_variable_numbers(std::vector<unsigned int> & all_variable_numbers) const;
    1294             : 
    1295             :   /**
    1296             :    * \returns An index, starting from 0 for the first component of the
    1297             :    * first variable, and incrementing for each component of each
    1298             :    * (potentially vector-valued) variable in the system in order.
    1299             :    * For systems with only scalar-valued variables, this will be the
    1300             :    * same as \p variable_number(var)
    1301             :    *
    1302             :    * Irony: currently our only non-scalar-valued variable type is
    1303             :    * SCALAR.
    1304             :    */
    1305             :   unsigned int variable_scalar_number (std::string_view var,
    1306             :                                        unsigned int component) const;
    1307             : 
    1308             :   /**
    1309             :    * \returns An index, starting from 0 for the first component of the
    1310             :    * first variable, and incrementing for each component of each
    1311             :    * (potentially vector-valued) variable in the system in order.
    1312             :    * For systems with only scalar-valued variables, this will be the
    1313             :    * same as \p var_num
    1314             :    *
    1315             :    * Irony: currently our only non-scalar-valued variable type is
    1316             :    * SCALAR.
    1317             :    */
    1318             :   unsigned int variable_scalar_number (unsigned int var_num,
    1319             :                                        unsigned int component) const;
    1320             : 
    1321             : 
    1322             :   /**
    1323             :    * \returns The finite element type variable number \p i.
    1324             :    */
    1325             :   const FEType & variable_type (const unsigned int i) const;
    1326             : 
    1327             :   /**
    1328             :    * \returns The finite element type for variable \p var.
    1329             :    */
    1330             :   const FEType & variable_type (std::string_view var) const;
    1331             : 
    1332             :   /**
    1333             :    * \returns \p true when \p VariableGroup structures should be
    1334             :    * automatically identified, \p false otherwise.
    1335             :    */
    1336             :   bool identify_variable_groups () const;
    1337             : 
    1338             :   /**
    1339             :    * Toggle automatic \p VariableGroup identification.
    1340             :    */
    1341             :   void identify_variable_groups (const bool);
    1342             : 
    1343             :   /**
    1344             :    * \returns A norm of variable \p var in the vector \p v, in the specified
    1345             :    * norm (e.g. L2, L_INF, H1)
    1346             :    */
    1347             :   Real calculate_norm(const NumericVector<Number> & v,
    1348             :                       unsigned int var,
    1349             :                       FEMNormType norm_type,
    1350             :                       std::set<unsigned int> * skip_dimensions=nullptr) const;
    1351             : 
    1352             :   /**
    1353             :    * \returns A norm of the vector \p v, using \p component_norm and \p
    1354             :    * component_scale to choose and weight the norms of each variable.
    1355             :    */
    1356             :   Real calculate_norm(const NumericVector<Number> & v,
    1357             :                       const SystemNorm & norm,
    1358             :                       std::set<unsigned int> * skip_dimensions=nullptr) const;
    1359             : 
    1360             :   /**
    1361             :    * Reads the basic data header for this System.
    1362             :    */
    1363             :   void read_header (Xdr & io,
    1364             :                     std::string_view version,
    1365             :                     const bool read_header=true,
    1366             :                     const bool read_additional_data=true,
    1367             :                     const bool read_legacy_format=false);
    1368             : 
    1369             :   /**
    1370             :    * Reads additional data, namely vectors, for this System.
    1371             :    * This method may safely be called on a distributed-memory mesh.
    1372             :    */
    1373             :   template <typename ValType>
    1374             :   void read_serialized_data (Xdr & io,
    1375             :                              const bool read_additional_data=true);
    1376             :   /**
    1377             :    * Non-templated version for backward compatibility.
    1378             :    *
    1379             :    * Reads additional data, namely vectors, for this System.
    1380             :    * This method may safely be called on a distributed-memory mesh.
    1381             :    */
    1382           0 :   void read_serialized_data (Xdr & io,
    1383             :                              const bool read_additional_data=true)
    1384           0 :   { read_serialized_data<Number>(io, read_additional_data); }
    1385             : 
    1386             :   /**
    1387             :    * Read a number of identically distributed vectors.  This method
    1388             :    * allows for optimization for the multiple vector case by only communicating
    1389             :    * the metadata once.
    1390             :    */
    1391             :   template <typename InValType>
    1392             :   std::size_t read_serialized_vectors (Xdr & io,
    1393             :                                        const std::vector<NumericVector<Number> *> & vectors) const;
    1394             : 
    1395             :   /**
    1396             :    * Non-templated version for backward compatibility.
    1397             :    *
    1398             :    * Read a number of identically distributed vectors.  This method
    1399             :    * allows for optimization for the multiple vector case by only communicating
    1400             :    * the metadata once.
    1401             :    */
    1402           8 :   std::size_t read_serialized_vectors (Xdr & io,
    1403             :                                        const std::vector<NumericVector<Number> *> & vectors) const
    1404         284 :   { return read_serialized_vectors<Number>(io, vectors); }
    1405             : 
    1406             :   /**
    1407             :    * Reads additional data, namely vectors, for this System.
    1408             :    * This method may safely be called on a distributed-memory mesh.
    1409             :    * This method will read an individual file for each processor in the simulation
    1410             :    * where the local solution components for that processor are stored.
    1411             :    */
    1412             :   template <typename InValType>
    1413             :   void read_parallel_data (Xdr & io,
    1414             :                            const bool read_additional_data);
    1415             : 
    1416             :   /**
    1417             :    * Non-templated version for backward compatibility.
    1418             :    *
    1419             :    * Reads additional data, namely vectors, for this System.
    1420             :    * This method may safely be called on a distributed-memory mesh.
    1421             :    * This method will read an individual file for each processor in the simulation
    1422             :    * where the local solution components for that processor are stored.
    1423             :    */
    1424             :   void read_parallel_data (Xdr & io,
    1425             :                            const bool read_additional_data)
    1426             :   { read_parallel_data<Number>(io, read_additional_data); }
    1427             : 
    1428             :   /**
    1429             :    * Writes the basic data header for this System.
    1430             :    */
    1431             :   void write_header (Xdr & io,
    1432             :                      std::string_view version,
    1433             :                      const bool write_additional_data) const;
    1434             : 
    1435             :   /**
    1436             :    * Writes additional data, namely vectors, for this System.
    1437             :    * This method may safely be called on a distributed-memory mesh.
    1438             :    */
    1439             :   void write_serialized_data (Xdr & io,
    1440             :                               const bool write_additional_data = true) const;
    1441             : 
    1442             :   /**
    1443             :    * Serialize & write a number of identically distributed vectors.  This method
    1444             :    * allows for optimization for the multiple vector case by only communicating
    1445             :    * the metadata once.
    1446             :    */
    1447             :   std::size_t write_serialized_vectors (Xdr & io,
    1448             :                                         const std::vector<const NumericVector<Number> *> & vectors) const;
    1449             : 
    1450             :   /**
    1451             :    * Writes additional data, namely vectors, for this System.
    1452             :    * This method may safely be called on a distributed-memory mesh.
    1453             :    * This method will create an individual file for each processor in the simulation
    1454             :    * where the local solution components for that processor will be stored.
    1455             :    */
    1456             :   void write_parallel_data (Xdr & io,
    1457             :                             const bool write_additional_data) const;
    1458             : 
    1459             :   /**
    1460             :    * \returns A string containing information about the
    1461             :    * system.
    1462             :    */
    1463             :   std::string get_info () const;
    1464             : 
    1465             :   /**
    1466             :    * Register a user function to use in initializing the system.
    1467             :    */
    1468             :   void attach_init_function (void fptr(EquationSystems & es,
    1469             :                                        const std::string & name));
    1470             : 
    1471             :   /**
    1472             :    * Register a user class to use to initialize the system.
    1473             :    *
    1474             :    * \note This is exclusive with the \p attach_init_function.
    1475             :    */
    1476             :   void attach_init_object (Initialization & init);
    1477             : 
    1478             :   /**
    1479             :    * Register a user function to use in assembling the system
    1480             :    * matrix and RHS.
    1481             :    */
    1482             :   void attach_assemble_function (void fptr(EquationSystems & es,
    1483             :                                            const std::string & name));
    1484             : 
    1485             :   /**
    1486             :    * Register a user object to use in assembling the system
    1487             :    * matrix and RHS.
    1488             :    */
    1489             :   void attach_assemble_object (Assembly & assemble);
    1490             : 
    1491             :   /**
    1492             :    * Register a user function for imposing constraints.
    1493             :    */
    1494             :   void attach_constraint_function (void fptr(EquationSystems & es,
    1495             :                                              const std::string & name));
    1496             : 
    1497             :   /**
    1498             :    * Register a user object for imposing constraints.
    1499             :    */
    1500             :   void attach_constraint_object (Constraint & constrain);
    1501             : 
    1502             :   /**
    1503             :    * \returns true if there is a user-defined constraint object
    1504             :    * attached to this object, false otherwise.  Calling System::
    1505             :    * get_constraint_object() when there is no user-defined constraint
    1506             :    * object attached leads to either undefined behavior (dereferencing
    1507             :    * a nullptr) or an assert (in dbg mode) so you should call this
    1508             :    * function first unless you are sure there is a user-defined
    1509             :    * constraint object attached.
    1510             :    */
    1511             :   bool has_constraint_object () const;
    1512             : 
    1513             :   /**
    1514             :    * Return the user object for imposing constraints.
    1515             :    */
    1516             :   Constraint& get_constraint_object ();
    1517             : 
    1518             :   /**
    1519             :    * Register a user function for evaluating the quantities of interest,
    1520             :    * whose values should be placed in \p System::qoi
    1521             :    */
    1522             :   void attach_QOI_function (void fptr(EquationSystems & es,
    1523             :                                       const std::string & name,
    1524             :                                       const QoISet & qoi_indices));
    1525             : 
    1526             :   /**
    1527             :    * Register a user object for evaluating the quantities of interest,
    1528             :    * whose values should be placed in \p System::qoi
    1529             :    */
    1530             :   void attach_QOI_object (QOI & qoi);
    1531             : 
    1532             :   /**
    1533             :    * Register a user function for evaluating derivatives of a quantity
    1534             :    * of interest with respect to test functions, whose values should
    1535             :    * be placed in \p System::rhs
    1536             :    */
    1537             :   void attach_QOI_derivative (void fptr(EquationSystems & es,
    1538             :                                         const std::string & name,
    1539             :                                         const QoISet & qoi_indices,
    1540             :                                         bool include_liftfunc,
    1541             :                                         bool apply_constraints));
    1542             : 
    1543             :   /**
    1544             :    * Register a user object for evaluating derivatives of a quantity
    1545             :    * of interest with respect to test functions, whose values should
    1546             :    * be placed in \p System::rhs
    1547             :    */
    1548             :   void attach_QOI_derivative_object (QOIDerivative & qoi_derivative);
    1549             : 
    1550             :   /**
    1551             :    * Calls user's attached initialization function, or is overridden by
    1552             :    * the user in derived classes.
    1553             :    */
    1554             :   virtual void user_initialization ();
    1555             : 
    1556             :   /**
    1557             :    * Calls user's attached assembly function, or is overridden by
    1558             :    * the user in derived classes.
    1559             :    */
    1560             :   virtual void user_assembly ();
    1561             : 
    1562             :   /**
    1563             :    * Calls user's attached constraint function, or is overridden by
    1564             :    * the user in derived classes.
    1565             :    */
    1566             :   virtual void user_constrain ();
    1567             : 
    1568             :   /**
    1569             :    * Calls user's attached quantity of interest function, or is
    1570             :    * overridden by the user in derived classes.
    1571             :    */
    1572             :   virtual void user_QOI (const QoISet & qoi_indices);
    1573             : 
    1574             :   /**
    1575             :    * Calls user's attached quantity of interest derivative function,
    1576             :    * or is overridden by the user in derived classes.
    1577             :    */
    1578             :   virtual void user_QOI_derivative (const QoISet & qoi_indices = QoISet(),
    1579             :                                     bool include_liftfunc = true,
    1580             :                                     bool apply_constraints = true);
    1581             : 
    1582             :   /**
    1583             :    * Re-update the local values when the mesh has changed.
    1584             :    * This method takes the data updated by \p update() and
    1585             :    * makes it up-to-date on the current mesh.
    1586             :    */
    1587             :   virtual void re_update ();
    1588             : 
    1589             :   /**
    1590             :    * Restrict vectors after the mesh has coarsened
    1591             :    */
    1592             :   virtual void restrict_vectors ();
    1593             : 
    1594             :   /**
    1595             :    * Prolong vectors after the mesh has refined
    1596             :    */
    1597             :   virtual void prolong_vectors ();
    1598             : 
    1599             :   /// Parameters for the system. If a parameter is not provided, it should be retrieved from the EquationSystems
    1600             :   Parameters parameters;
    1601             : 
    1602             :   /**
    1603             :    * Flag which tells the system to whether or not to
    1604             :    * call the user assembly function during each call to solve().
    1605             :    * By default, every call to solve() begins with a call to the
    1606             :    * user assemble, so this flag is true.  (For explicit systems,
    1607             :    * "solving" the system occurs during the assembly step, so this
    1608             :    * flag is always true for explicit systems.)
    1609             :    *
    1610             :    * You will only want to set this to false if you need direct
    1611             :    * control over when the system is assembled, and are willing to
    1612             :    * track the state of its assembly yourself.  An example of such a
    1613             :    * case is an implicit system with multiple right hand sides.  In
    1614             :    * this instance, a single assembly would likely be followed with
    1615             :    * multiple calls to solve.
    1616             :    *
    1617             :    * The frequency system and Newmark system have their own versions
    1618             :    * of this flag, called _finished_assemble, which might be able to
    1619             :    * be replaced with this more general concept.
    1620             :    */
    1621             :   bool assemble_before_solve;
    1622             : 
    1623             :   /**
    1624             :    * Avoids use of any cached data that might affect any solve result.  Should
    1625             :    * be overridden in derived systems.
    1626             :    */
    1627             :   virtual void disable_cache ();
    1628             : 
    1629             :   /**
    1630             :    * A boolean to be set to true by systems using elem_fixed_solution,
    1631             :    * for optional use by e.g. stabilized methods.
    1632             :    * False by default.
    1633             :    *
    1634             :    * \note For FEMSystem users, if this variable is set to true, it
    1635             :    * must be before init_data() is called.
    1636             :    */
    1637             :   bool use_fixed_solution;
    1638             : 
    1639             :   /**
    1640             :    * A member int that can be employed to indicate increased or
    1641             :    * reduced quadrature order.
    1642             :    *
    1643             :    * \note For FEMSystem users, by default, when calling the
    1644             :    * user-defined residual functions, the FEMSystem will first set up
    1645             :    * an appropriate FEType::default_quadrature_rule() object for
    1646             :    * performing the integration.  This rule will integrate elements of
    1647             :    * order up to 2*p+1 exactly (where p is the sum of the base FEType
    1648             :    * and local p refinement levels), but if additional (or reduced)
    1649             :    * quadrature accuracy is desired then this extra_quadrature_order
    1650             :    * (default 0) will be added.
    1651             :    */
    1652             :   int extra_quadrature_order;
    1653             : 
    1654             : 
    1655             :   //--------------------------------------------------
    1656             :   // The solution and solution access members
    1657             : 
    1658             :   /**
    1659             :    * \returns The current solution for the specified global
    1660             :    * DOF.
    1661             :    */
    1662             :   Number current_solution (const dof_id_type global_dof_number) const;
    1663             : 
    1664             :   /**
    1665             :    * Data structure to hold solution values.
    1666             :    */
    1667             :   std::unique_ptr<NumericVector<Number>> solution;
    1668             : 
    1669             :   /**
    1670             :    * All the values I need to compute my contribution
    1671             :    * to the simulation at hand.  Think of this as the
    1672             :    * current solution with any ghost values needed from
    1673             :    * other processors.  This vector is necessarily larger
    1674             :    * than the \p solution vector in the case of a parallel
    1675             :    * simulation.  The \p update() member is used to synchronize
    1676             :    * the contents of the \p solution and \p current_local_solution
    1677             :    * vectors.
    1678             :    */
    1679             :   std::unique_ptr<NumericVector<Number>> current_local_solution;
    1680             : 
    1681             :   /**
    1682             :    * For time-dependent problems, this is the time t at the beginning of
    1683             :    * the current timestep.
    1684             :    *
    1685             :    * \note For DifferentiableSystem users: do \e not access this time
    1686             :    * during an assembly!  Use the DiffContext::time value instead to
    1687             :    * get correct results.
    1688             :    */
    1689             :   Real time;
    1690             : 
    1691             :   /**
    1692             :    * Number of currently active quantities of interest.
    1693             :    */
    1694             :   unsigned int n_qois() const;
    1695             : 
    1696             : public:
    1697             : 
    1698             :   /**
    1699             :    * Accessors for qoi and qoi_error_estimates vectors
    1700             :    */
    1701             :   void init_qois(unsigned int n_qois);
    1702             : 
    1703             :   void set_qoi(unsigned int qoi_index, Number qoi_value);
    1704             :   Number get_qoi_value(unsigned int qoi_index) const;
    1705             : 
    1706             :   void set_qoi(std::vector<Number> new_qoi);
    1707             : 
    1708             :   /**
    1709             :    * Returns a *copy* of qoi, not a reference
    1710             :    */
    1711             :   std::vector<Number> get_qoi_values() const;
    1712             : 
    1713             :   void set_qoi_error_estimate(unsigned int qoi_index, Number qoi_error_estimate);
    1714             :   Number get_qoi_error_estimate_value(unsigned int qoi_index) const;
    1715             : 
    1716             :   /**
    1717             :    * \returns The value of the solution variable \p var at the physical
    1718             :    * point \p p in the mesh, without knowing a priori which element
    1719             :    * contains \p p, using the degree of freedom coefficients in \p sol
    1720             :    * (or in \p current_local_solution if \p sol is left null).
    1721             :    *
    1722             :    * \note This function uses \p MeshBase::sub_point_locator(); users
    1723             :    * may or may not want to call \p MeshBase::clear_point_locator()
    1724             :    * afterward.  Also, point_locator() is expensive (N log N for
    1725             :    * initial construction, log N for evaluations).  Avoid using this
    1726             :    * function in any context where you are already looping over
    1727             :    * elements.
    1728             :    *
    1729             :    * Because the element containing \p p may lie on any processor,
    1730             :    * this function is parallel-only.
    1731             :    *
    1732             :    * By default this method expects the point to reside inside the domain
    1733             :    * and will abort if no element can be found which contains \p p.  The
    1734             :    * optional parameter \p insist_on_success can be set to false to allow
    1735             :    * the method to return 0 when the point is not located.
    1736             :    */
    1737             :   Number point_value(unsigned int var, const Point & p,
    1738             :                      const bool insist_on_success = true,
    1739             :                      const NumericVector<Number> * sol = nullptr) const;
    1740             : 
    1741             :   /**
    1742             :    * \returns The value of the solution variable \p var at the physical
    1743             :    * point \p p contained in local Elem \p e, using the degree of
    1744             :    * freedom coefficients in \p sol (or in \p current_local_solution
    1745             :    * if \p sol is left null).
    1746             :    *
    1747             :    * This version of point_value can be run in serial, but assumes \p e is in
    1748             :    * the local mesh partition or is algebraically ghosted.
    1749             :    */
    1750             :   Number point_value(unsigned int var, const Point & p, const Elem & e,
    1751             :                      const NumericVector<Number> * sol = nullptr) const;
    1752             : 
    1753             :   /**
    1754             :    * Calls the version of point_value() which takes a reference.
    1755             :    * This function exists only to prevent people from calling the
    1756             :    * version of point_value() that has a boolean third argument, which
    1757             :    * would result in unnecessary PointLocator calls.
    1758             :    */
    1759             :   Number point_value(unsigned int var, const Point & p, const Elem * e) const;
    1760             : 
    1761             :   /**
    1762             :    * Calls the parallel version of point_value().
    1763             :    * This function exists only to prevent people from accidentally
    1764             :    * calling the version of point_value() that has a boolean third
    1765             :    * argument, which would result in incorrect output.
    1766             :    */
    1767             :   Number point_value(unsigned int var, const Point & p, const NumericVector<Number> * sol) const;
    1768             : 
    1769             :   /**
    1770             :    * \returns The gradient of the solution variable \p var at the physical
    1771             :    * point \p p in the mesh, similarly to point_value.
    1772             :    */
    1773             :   Gradient point_gradient(unsigned int var, const Point & p,
    1774             :                           const bool insist_on_success = true,
    1775             :                           const NumericVector<Number> * sol = nullptr) const;
    1776             : 
    1777             :   /**
    1778             :    * \returns The gradient of the solution variable \p var at the physical
    1779             :    * point \p p in local Elem \p e in the mesh, similarly to point_value.
    1780             :    */
    1781             :   Gradient point_gradient(unsigned int var, const Point & p, const Elem & e,
    1782             :                           const NumericVector<Number> * sol = nullptr) const;
    1783             : 
    1784             :   /**
    1785             :    * Calls the version of point_gradient() which takes a reference.
    1786             :    * This function exists only to prevent people from calling the
    1787             :    * version of point_gradient() that has a boolean third argument, which
    1788             :    * would result in unnecessary PointLocator calls.
    1789             :    */
    1790             :   Gradient point_gradient(unsigned int var, const Point & p, const Elem * e) const;
    1791             : 
    1792             :   /**
    1793             :    * Calls the parallel version of point_gradient().
    1794             :    * This function exists only to prevent people from accidentally
    1795             :    * calling the version of point_gradient() that has a boolean third
    1796             :    * argument, which would result in incorrect output.
    1797             :    */
    1798             :   Gradient point_gradient(unsigned int var, const Point & p, const NumericVector<Number> * sol) const;
    1799             : 
    1800             :   /**
    1801             :    * \returns The second derivative tensor of the solution variable \p var
    1802             :    * at the physical point \p p in the mesh, similarly to point_value.
    1803             :    */
    1804             :   Tensor point_hessian(unsigned int var, const Point & p,
    1805             :                        const bool insist_on_success = true,
    1806             :                        const NumericVector<Number> * sol = nullptr) const;
    1807             : 
    1808             :   /**
    1809             :    * \returns The second derivative tensor of the solution variable \p var
    1810             :    * at the physical point \p p in local Elem \p e in the mesh, similarly to
    1811             :    * point_value.
    1812             :    */
    1813             :   Tensor point_hessian(unsigned int var, const Point & p, const Elem & e,
    1814             :                        const NumericVector<Number> * sol = nullptr) const;
    1815             : 
    1816             :   /**
    1817             :    * Calls the version of point_hessian() which takes a reference.
    1818             :    * This function exists only to prevent people from calling the
    1819             :    * version of point_hessian() that has a boolean third argument, which
    1820             :    * would result in unnecessary PointLocator calls.
    1821             :    */
    1822             :   Tensor point_hessian(unsigned int var, const Point & p, const Elem * e) const;
    1823             : 
    1824             :   /**
    1825             :    * Calls the parallel version of point_hessian().
    1826             :    * This function exists only to prevent people from accidentally
    1827             :    * calling the version of point_hessian() that has a boolean third
    1828             :    * argument, which would result in incorrect output.
    1829             :    */
    1830             :   Tensor point_hessian(unsigned int var, const Point & p, const NumericVector<Number> * sol) const;
    1831             : 
    1832             : 
    1833             :   /**
    1834             :    * Fills the std::set with the degrees of freedom on the local
    1835             :    * processor corresponding the the variable number passed in.
    1836             :    */
    1837             :   void local_dof_indices (const unsigned int var,
    1838             :                           std::set<dof_id_type> & var_indices) const;
    1839             : 
    1840             :   /**
    1841             :    * Zeroes all dofs in \p v that correspond to variable number \p
    1842             :    * var_num.
    1843             :    */
    1844             :   void zero_variable (NumericVector<Number> & v, unsigned int var_num) const;
    1845             : 
    1846             :   /**
    1847             :    * Setter and getter functions for project_with_constraints boolean
    1848             :    */
    1849         476 :   bool get_project_with_constraints()
    1850             :   {
    1851       16190 :     return project_with_constraints;
    1852             :   }
    1853             : 
    1854         952 :   void set_project_with_constraints(bool _project_with_constraints)
    1855             :   {
    1856       32856 :     project_with_constraints = _project_with_constraints;
    1857         952 :   }
    1858             : 
    1859             :   /**
    1860             :    * \returns A writable reference to a boolean that determines if this system
    1861             :    * can be written to file or not.  If set to \p true, then
    1862             :    * \p EquationSystems::write will ignore this system.
    1863             :    */
    1864       12996 :   bool & hide_output() { return _hide_output; }
    1865             : 
    1866             : #ifdef LIBMESH_HAVE_METAPHYSICL
    1867             :   /**
    1868             :    * This method creates a projection matrix which corresponds to the
    1869             :    * operation of project_vector between old and new solution spaces.
    1870             :    *
    1871             :    * Heterogeneous Dirichlet boundary conditions are *not* taken into
    1872             :    * account here; if this matrix is used for prolongation (mesh
    1873             :    * refinement) on a side with a heterogeneous BC, the newly created
    1874             :    * degrees of freedom on that side will still match the coarse grid
    1875             :    * approximation of the BC, not the fine grid approximation.
    1876             :    */
    1877             :   void projection_matrix (SparseMatrix<Number> & proj_mat) const;
    1878             : #endif // LIBMESH_HAVE_METAPHYSICL
    1879             : 
    1880             :   /**
    1881             :    * Adds the additional matrix \p mat_name to this system.  Only
    1882             :    * allowed prior to \p assemble().  All additional matrices
    1883             :    * have the same sparsity pattern as the matrix used during
    1884             :    * solution.  When not \p System but the user wants to
    1885             :    * initialize the main/system matrix, then all the additional matrices,
    1886             :    * if existent, have to be initialized by the user, too.
    1887             :    *
    1888             :    * This non-template method will add a derived matrix type corresponding to
    1889             :    * the solver package. If the user wishes to specify the matrix type to add,
    1890             :    * use the templated \p add_matrix method instead
    1891             :    *
    1892             :    * @param mat_name A name for the matrix
    1893             :    * @param type The serial/parallel/ghosted type of the matrix
    1894             :    * @param mat_build_type The matrix type to build
    1895             :    *
    1896             :    */
    1897             :   SparseMatrix<Number> & add_matrix (std::string_view mat_name,
    1898             :                                      ParallelType type = PARALLEL,
    1899             :                                      MatrixBuildType mat_build_type = MatrixBuildType::AUTOMATIC);
    1900             : 
    1901             :   /**
    1902             :   * Adds the additional matrix \p mat_name to this system.  Only
    1903             :   * allowed prior to \p assemble().  All additional matrices
    1904             :   * have the same sparsity pattern as the matrix used during
    1905             :   * solution.  When not \p System but the user wants to
    1906             :   * initialize the main/system matrix, then all the additional matrices,
    1907             :   * if existent, have to be initialized by the user, too.
    1908             :   *
    1909             :   * This method will create add a derived matrix of type
    1910             :   * \p MatrixType<Number>. One can use the non-templated \p add_matrix method to
    1911             :   * add a matrix corresponding to the default solver package
    1912             :   *
    1913             :   * @param mat_name A name for the matrix
    1914             :   * @param type The serial/parallel/ghosted type of the matrix
    1915             :   */
    1916             :   template <template <typename> class>
    1917             :   SparseMatrix<Number> & add_matrix (std::string_view mat_name, ParallelType = PARALLEL);
    1918             : 
    1919             :   /**
    1920             :    * Adds the additional matrix \p mat_name to this system.  Only
    1921             :    * allowed prior to \p assemble().  All additional matrices
    1922             :    * have the same sparsity pattern as the matrix used during
    1923             :    * solution.  When not \p System but the user wants to
    1924             :    * initialize the main/system matrix, then all the additional matrices,
    1925             :    * if existent, have to be initialized by the user, too.
    1926             :    *
    1927             :    * @param mat_name A name for the matrix
    1928             :    * @param matrix The matrix we are handing over the \p System for ownership
    1929             :    * @param type The serial/parallel/ghosted type of the matrix
    1930             :    *
    1931             :    */
    1932             :   SparseMatrix<Number> & add_matrix (std::string_view mat_name,
    1933             :                                      std::unique_ptr<SparseMatrix<Number>> matrix,
    1934             :                                      ParallelType type = PARALLEL);
    1935             : 
    1936             :   /**
    1937             :    * Removes the additional matrix \p mat_name from this system
    1938             :    */
    1939             :   void remove_matrix(std::string_view mat_name);
    1940             : 
    1941             :   /**
    1942             :    * \returns \p true if this \p System has a matrix associated with the
    1943             :    * given name, \p false otherwise.
    1944             :    */
    1945           0 :   inline bool have_matrix (std::string_view mat_name) const { return _matrices.count(mat_name); }
    1946             : 
    1947             :   /**
    1948             :    * \returns A const pointer to this system's additional matrix
    1949             :    * named \p mat_name, or \p nullptr if no matrix by that name
    1950             :    * exists.
    1951             :    */
    1952             :   const SparseMatrix<Number> * request_matrix (std::string_view mat_name) const;
    1953             : 
    1954             :   /**
    1955             :    * \returns A writable pointer to this system's additional matrix
    1956             :    * named \p mat_name, or \p nullptr if no matrix by that name
    1957             :    * exists.
    1958             :    */
    1959             :   SparseMatrix<Number> * request_matrix (std::string_view mat_name);
    1960             : 
    1961             :   /**
    1962             :    * \returns A const reference to this system's matrix
    1963             :    * named \p mat_name.
    1964             :    */
    1965             :   const SparseMatrix<Number> & get_matrix (std::string_view mat_name) const;
    1966             : 
    1967             :   /**
    1968             :    * \returns A writable reference to this system's matrix
    1969             :    * named \p mat_name.
    1970             :    */
    1971             :   SparseMatrix<Number> & get_matrix (std::string_view mat_name);
    1972             : 
    1973             :   /**
    1974             :    * Sets whether to use hash table matrix assembly if the matrix sub-classes support it
    1975             :    */
    1976             :   void prefer_hash_table_matrix_assembly(bool preference);
    1977             : 
    1978             :   /**
    1979             :    * Instructs this system to prefix solve options with its name for solvers that leverage prefixes
    1980             :    */
    1981           0 :   void prefix_with_name(bool value) { _prefix_with_name = value; }
    1982             : 
    1983             :   /**
    1984             :    * @returns Whether we are name prefixing
    1985             :    */
    1986      232185 :   [[nodiscard]] bool prefix_with_name() const { return _prefix_with_name; }
    1987             : 
    1988             :   /**
    1989             :    * @returns A prefix that may be applied to solver options. Note that this
    1990             :    * prefix is only used if \p prefix_with_name()
    1991             :    */
    1992           0 :   std::string prefix() const { return this->name() + "_"; }
    1993             : 
    1994             :   /**
    1995             :    * Sets the solver-package options prefix of every vector and matrix
    1996             :    * this system owns, including ones added later. Each object reads
    1997             :    * options with this prefix the next time it is initialized, so the
    1998             :    * prefix persists through reinitialization, e.g. after adaptivity.
    1999             :    */
    2000             :   void set_options_prefix(std::string options_prefix);
    2001             : 
    2002             :   /**
    2003             :    * \returns The options prefix of this system's vectors and matrices.
    2004             :    * See set_options_prefix().
    2005             :    */
    2006             :   const std::string & options_prefix() const { return _options_prefix; }
    2007             : 
    2008             :   /**
    2009             :    * Request that static condensation be performed for this system
    2010             :    */
    2011             :    virtual void create_static_condensation();
    2012             : 
    2013             :    /**
    2014             :     * @returns Whether this system will be statically condensed
    2015             :     */
    2016             :    bool has_static_condensation() const;
    2017             : 
    2018             :   /*
    2019             :    * If we have e.g. a element space constrained by spline values, we
    2020             :    * can directly project functions only on the constrained basis; to
    2021             :    * get consistent constraining values we have to solve for them.
    2022             :    *
    2023             :    * Constrain the new vector using the requested adjoint rather than
    2024             :    * primal constraints if is_adjoint is non-negative.
    2025             :    */
    2026             :   void solve_for_unconstrained_dofs (NumericVector<Number> &,
    2027             :                                      int is_adjoint = -1) const;
    2028             : 
    2029             : protected:
    2030             : 
    2031             :   /**
    2032             :    * Initializes the data for the system.
    2033             :    *
    2034             :    * \note This is called before any user-supplied initialization
    2035             :    * function so that all required storage will be available.
    2036             :    */
    2037             :   virtual void init_data ();
    2038             : 
    2039             :   /**
    2040             :    * Insertion point for adding matrices in derived classes
    2041             :    * before init_matrices() is called.
    2042             :    */
    2043      353569 :   virtual void add_matrices() {}
    2044             : 
    2045             :   /**
    2046             :    * Initializes the matrices associated with this system.
    2047             :    */
    2048             :   virtual void init_matrices ();
    2049             : 
    2050             :   /**
    2051             :    * \returns Whether or not matrices can still be added without
    2052             :    * expensive per-matrix initialization.
    2053             :    */
    2054         272 :   bool can_add_matrices() const { return !_matrices_initialized; }
    2055             : 
    2056             :   /**
    2057             :    * Projects the vector defined on the old mesh onto the
    2058             :    * new mesh.
    2059             :    *
    2060             :    * Constrain the new vector using the requested adjoint rather than
    2061             :    * primal constraints if is_adjoint is non-negative.
    2062             :    */
    2063             :   void project_vector (NumericVector<Number> &,
    2064             :                        int is_adjoint = -1,
    2065             :                        std::optional<ConstElemRange> active_local_range = std::nullopt,
    2066             :                        std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
    2067             : 
    2068             :   /**
    2069             :    * Projects the vector defined on the old mesh onto the
    2070             :    * new mesh. The original vector is unchanged and the new vector
    2071             :    * is passed through the second argument.
    2072             :    *
    2073             :    * Constrain the new vector using the requested adjoint rather than
    2074             :    * primal constraints if is_adjoint is non-negative.
    2075             :    */
    2076             :   void project_vector (const NumericVector<Number> &,
    2077             :                        NumericVector<Number> &,
    2078             :                        int is_adjoint = -1,
    2079             :                        std::optional<ConstElemRange> active_local_range = std::nullopt,
    2080             :                        std::optional<std::vector<unsigned int>> variable_numbers = std::nullopt) const;
    2081             : 
    2082             :   /**
    2083             :    * Whether this object should condense out constrained degrees of freedom
    2084             :    */
    2085         140 :   virtual bool condense_constrained_dofs() const { return false; }
    2086             : 
    2087             : private:
    2088             :   /**
    2089             :    * Helper function to keep DofMap forward declarable in system.h
    2090             :    */
    2091             :   void late_matrix_init(SparseMatrix<Number> & mat,
    2092             :                         ParallelType type);
    2093             : 
    2094             :   /**
    2095             :    * Finds the discrete norm for the entries in the vector
    2096             :    * corresponding to Dofs associated with var.
    2097             :    */
    2098             :   Real discrete_var_norm (const NumericVector<Number> & v,
    2099             :                           unsigned int var,
    2100             :                           FEMNormType norm_type) const;
    2101             : 
    2102             :   /**
    2103             :    * Reads an input vector from the stream \p io and assigns
    2104             :    * the values to a set of \p DofObjects.  This method uses
    2105             :    * blocked input and is safe to call on a distributed memory-mesh.
    2106             :    * Unless otherwise specified, all variables are read.
    2107             :    *
    2108             :    * If an entry in \p vecs is a null pointer, the corresponding data
    2109             :    * is read (incrementing the file read location) but discarded.
    2110             :    */
    2111             :   template <typename iterator_type, typename InValType>
    2112             :   std::size_t read_serialized_blocked_dof_objects (const dof_id_type n_objects,
    2113             :                                                    const iterator_type begin,
    2114             :                                                    const iterator_type end,
    2115             :                                                    const InValType dummy,
    2116             :                                                    Xdr & io,
    2117             :                                                    const std::vector<NumericVector<Number> *> & vecs,
    2118             :                                                    const unsigned int var_to_read=libMesh::invalid_uint) const;
    2119             : 
    2120             :   /**
    2121             :    * Reads the SCALAR dofs from the stream \p io and assigns the values
    2122             :    * to the appropriate entries of \p vec.
    2123             :    *
    2124             :    * \returns The number of dofs read.
    2125             :    *
    2126             :    * Reads data and discards it if \p vec is a null pointer.
    2127             :    */
    2128             :   unsigned int read_SCALAR_dofs (const unsigned int var,
    2129             :                                  Xdr & io,
    2130             :                                  NumericVector<Number> * vec) const;
    2131             : 
    2132             :   /**
    2133             :    * Reads a vector for this System.
    2134             :    * This method may safely be called on a distributed-memory mesh.
    2135             :    *
    2136             :    * \returns The length of the vector read.
    2137             :    *
    2138             :    * Reads data and discards it if \p vec is a null pointer.
    2139             :    */
    2140             :   template <typename InValType>
    2141             :   numeric_index_type read_serialized_vector (Xdr & io,
    2142             :                                              NumericVector<Number> * vec);
    2143             : 
    2144             :   /**
    2145             :    * Non-templated version for backward compatibility.
    2146             :    *
    2147             :    * Reads a vector for this System.
    2148             :    * This method may safely be called on a distributed-memory mesh.
    2149             :    *
    2150             :    * \returns The length of the vector read.
    2151             :    */
    2152             :   numeric_index_type read_serialized_vector (Xdr & io,
    2153             :                                              NumericVector<Number> & vec)
    2154             :   { return read_serialized_vector<Number>(io, &vec); }
    2155             : 
    2156             :   /**
    2157             :    * Writes an output vector to the stream \p io for a set of \p DofObjects.
    2158             :    * This method uses blocked output and is safe to call on a distributed memory-mesh.
    2159             :    *
    2160             :    * \returns The number of values written
    2161             :    */
    2162             :   template <typename iterator_type>
    2163             :   std::size_t write_serialized_blocked_dof_objects (const std::vector<const NumericVector<Number> *> & vecs,
    2164             :                                                     const dof_id_type n_objects,
    2165             :                                                     const iterator_type begin,
    2166             :                                                     const iterator_type end,
    2167             :                                                     Xdr & io,
    2168             :                                                     const unsigned int var_to_write=libMesh::invalid_uint) const;
    2169             : 
    2170             :   /**
    2171             :    * Writes the SCALAR dofs associated with var to the stream \p io.
    2172             :    *
    2173             :    * \returns The number of values written.
    2174             :    */
    2175             :   unsigned int write_SCALAR_dofs (const NumericVector<Number> & vec,
    2176             :                                   const unsigned int var,
    2177             :                                   Xdr & io) const;
    2178             : 
    2179             :   /**
    2180             :    * Writes a vector for this System.
    2181             :    * This method may safely be called on a distributed-memory mesh.
    2182             :    *
    2183             :    * \returns The number of values written.
    2184             :    */
    2185             :   dof_id_type write_serialized_vector (Xdr & io,
    2186             :                                        const NumericVector<Number> & vec) const;
    2187             : 
    2188             :   /**
    2189             :    * Function that initializes the system.
    2190             :    */
    2191             :   void (* _init_system_function) (EquationSystems & es,
    2192             :                                   const std::string & name);
    2193             : 
    2194             :   /**
    2195             :    * Object that initializes the system.
    2196             :    */
    2197             :   Initialization * _init_system_object;
    2198             : 
    2199             :   /**
    2200             :    * Function that assembles the system.
    2201             :    */
    2202             :   void (* _assemble_system_function) (EquationSystems & es,
    2203             :                                       const std::string & name);
    2204             : 
    2205             :   /**
    2206             :    * Object that assembles the system.
    2207             :    */
    2208             :   Assembly * _assemble_system_object;
    2209             : 
    2210             :   /**
    2211             :    * Function to impose constraints.
    2212             :    */
    2213             :   void (* _constrain_system_function) (EquationSystems & es,
    2214             :                                        const std::string & name);
    2215             : 
    2216             :   /**
    2217             :    * Object that constrains the system.
    2218             :    */
    2219             :   Constraint * _constrain_system_object;
    2220             : 
    2221             :   /**
    2222             :    * Function to evaluate quantity of interest
    2223             :    */
    2224             :   void (* _qoi_evaluate_function) (EquationSystems & es,
    2225             :                                    const std::string & name,
    2226             :                                    const QoISet & qoi_indices);
    2227             : 
    2228             :   /**
    2229             :    * Object to compute quantities of interest.
    2230             :    */
    2231             :   QOI * _qoi_evaluate_object;
    2232             : 
    2233             :   /**
    2234             :    * Function to evaluate quantity of interest derivative
    2235             :    */
    2236             :   void (* _qoi_evaluate_derivative_function) (EquationSystems & es,
    2237             :                                               const std::string & name,
    2238             :                                               const QoISet & qoi_indices,
    2239             :                                               bool include_liftfunc,
    2240             :                                               bool apply_constraints);
    2241             : 
    2242             :   /**
    2243             :    * Object to compute derivatives of quantities of interest.
    2244             :    */
    2245             :   QOIDerivative * _qoi_evaluate_derivative_object;
    2246             : 
    2247             :   /**
    2248             :    * Data structure describing the relationship between
    2249             :    * nodes, variables, etc... and degrees of freedom.
    2250             :    */
    2251             :   std::unique_ptr<DofMap> _dof_map;
    2252             : 
    2253             :   /**
    2254             :    * Constant reference to the \p EquationSystems object
    2255             :    * used for the simulation.
    2256             :    */
    2257             :   EquationSystems & _equation_systems;
    2258             : 
    2259             :   /**
    2260             :    * Constant reference to the \p mesh data structure used
    2261             :    * for the simulation.
    2262             :    */
    2263             :   MeshBase & _mesh;
    2264             : 
    2265             :   /**
    2266             :    * A name associated with this system.
    2267             :    */
    2268             :   const std::string _sys_name;
    2269             : 
    2270             :   /**
    2271             :    * The number associated with this system
    2272             :    */
    2273             :   const unsigned int _sys_number;
    2274             : 
    2275             :   /**
    2276             :    * Flag stating if the system is active or not.
    2277             :    */
    2278             :   bool _active;
    2279             : 
    2280             :   /**
    2281             :    * Some systems need an arbitrary number of vectors.
    2282             :    * This map allows names to be associated with arbitrary
    2283             :    * vectors.  All the vectors in this map will be distributed
    2284             :    * in the same way as the solution vector.
    2285             :    */
    2286             :   std::map<std::string, std::unique_ptr<NumericVector<Number>>, std::less<>> _vectors;
    2287             : 
    2288             :   /**
    2289             :    * Holds true if a vector by that name should be projected
    2290             :    * onto a changed grid, false if it should be zeroed.
    2291             :    */
    2292             :   std::map<std::string, bool, std::less<>> _vector_projections;
    2293             : 
    2294             :   /**
    2295             :    * Holds non-negative if a vector by that name should be projected
    2296             :    * using adjoint constraints/BCs, -1 if primal
    2297             :    */
    2298             :   std::map<std::string, int, std::less<>> _vector_is_adjoint;
    2299             : 
    2300             :   /**
    2301             :    * Some systems need an arbitrary number of matrices.
    2302             :    */
    2303             :   std::map<std::string, std::unique_ptr<SparseMatrix<Number>>, std::less<>> _matrices;
    2304             : 
    2305             :   /**
    2306             :    * Holds the types of the matrices
    2307             :    */
    2308             :   std::map<std::string, ParallelType, std::less<>> _matrix_types;
    2309             : 
    2310             :   /**
    2311             :    * \p false when additional matrices being added require initialization, \p true otherwise.
    2312             :    */
    2313             :   bool _matrices_initialized;
    2314             : 
    2315             :   /**
    2316             :    * Holds true if the solution vector should be projected
    2317             :    * onto a changed grid, false if it should be zeroed.
    2318             :    * This is true by default.
    2319             :    */
    2320             :   bool _solution_projection;
    2321             : 
    2322             :   /**
    2323             :    * Holds true if the components of more advanced system types (e.g.
    2324             :    * system matrices) should not be initialized.
    2325             :    */
    2326             :   bool _basic_system_only;
    2327             : 
    2328             :   /**
    2329             :    * \p true when additional vectors and variables do not require
    2330             :    * immediate initialization, \p false otherwise.
    2331             :    */
    2332             :   bool _is_initialized;
    2333             : 
    2334             :   /**
    2335             :    * This flag is used only when *reading* in a system from file.
    2336             :    * Based on the system header, it keeps track of how many
    2337             :    * additional vectors were actually written for this file.
    2338             :    */
    2339             :   unsigned int _additional_data_written;
    2340             : 
    2341             :   /**
    2342             :    * This vector is used only when *reading* in a system from file.
    2343             :    * Based on the system header, it keeps track of any index remapping
    2344             :    * between variable names in the data file and variable names in the
    2345             :    * already-constructed system.  I.e. if we have a system with
    2346             :    * variables "A1", "A2", "B1", and "B2", but we read in a data file with
    2347             :    * only "A1" and "B1" defined, then we don't want to try and read in
    2348             :    * A2 or B2, and we don't want to assign A1 and B1 values to
    2349             :    * different dof indices.
    2350             :    */
    2351             :   std::vector<unsigned int> _written_var_indices;
    2352             : 
    2353             :   /**
    2354             :    * Has the adjoint problem already been solved?  If the user sets
    2355             :    * \p adjoint_already_solved to \p true, we won't waste time solving
    2356             :    * it again.
    2357             :    */
    2358             :   bool adjoint_already_solved;
    2359             : 
    2360             :   /**
    2361             :    * Are we allowed to write this system to file?  If \p _hide_output is
    2362             :    * \p true, then \p EquationSystems::write will ignore this system.
    2363             :    */
    2364             :   bool _hide_output;
    2365             : 
    2366             :   /**
    2367             :    * Do we want to apply constraints while projecting vectors ?
    2368             :    */
    2369             :   bool project_with_constraints;
    2370             : 
    2371             :   /**
    2372             :    * Whether to use hash table matrix assembly if the matrix sub-classes support it
    2373             :    */
    2374             :   bool _prefer_hash_table_matrix_assembly;
    2375             : 
    2376             :   /**
    2377             :    * Whether any of our matrices require an initial sparsity pattern computation in order to determine preallocation
    2378             :    */
    2379             :   bool _require_sparsity_pattern;
    2380             : 
    2381             :   /**
    2382             :    * Whether we are name prefixing solver options
    2383             :    */
    2384             :   bool _prefix_with_name;
    2385             : 
    2386             :   /**
    2387             :    * Solver-package options prefix of this system's vectors and matrices
    2388             :    */
    2389             :   std::string _options_prefix;
    2390             : 
    2391             :   /**
    2392             :    * Values of the quantities of interest.  This vector needs to be
    2393             :    * both resized and filled by the user before any quantity of
    2394             :    * interest assembly is done and before any sensitivities are
    2395             :    * calculated. Use the get_qoi_values() accessor to get these
    2396             :    * values.
    2397             :    */
    2398             :   std::vector<Number> _qoi;
    2399             : 
    2400             :   /**
    2401             :    * Vector to hold error estimates for qois, either from a steady
    2402             :    * state calculation, or from a single unsteady solver timestep. Used
    2403             :    * by the library after resizing to match the size of the qoi vector.
    2404             :    * User code can use this for accumulating error estimates for example.
    2405             :    * Use the set_qoi_error_estimate()/get_qoi_error_estimate_value()
    2406             :    * accessors to set/get these values.
    2407             :    */
    2408             :   std::vector<Number> _qoi_error_estimates;
    2409             : };
    2410             : 
    2411             : 
    2412             : 
    2413             : // ------------------------------------------------------------
    2414             : // System inline methods
    2415             : inline
    2416      712487 : const std::string & System::name() const
    2417             : {
    2418    14708605 :   return _sys_name;
    2419             : }
    2420             : 
    2421             : 
    2422             : 
    2423             : inline
    2424      682937 : unsigned int System::number() const
    2425             : {
    2426    11536915 :   return _sys_number;
    2427             : }
    2428             : 
    2429             : 
    2430             : 
    2431             : inline
    2432      850533 : const MeshBase & System::get_mesh() const
    2433             : {
    2434    18489041 :   return _mesh;
    2435             : }
    2436             : 
    2437             : 
    2438             : 
    2439             : inline
    2440       30288 : MeshBase & System::get_mesh()
    2441             : {
    2442     1634668 :   return _mesh;
    2443             : }
    2444             : 
    2445             : 
    2446             : 
    2447             : inline
    2448    87667760 : const DofMap & System::get_dof_map() const
    2449             : {
    2450    87667760 :   return *_dof_map;
    2451             : }
    2452             : 
    2453             : 
    2454             : 
    2455             : inline
    2456      312882 : DofMap & System::get_dof_map()
    2457             : {
    2458      312882 :   return *_dof_map;
    2459             : }
    2460             : 
    2461             : 
    2462             : 
    2463             : inline
    2464             : bool System::active() const
    2465             : {
    2466             :   return _active;
    2467             : }
    2468             : 
    2469             : 
    2470             : 
    2471             : inline
    2472             : void System::activate ()
    2473             : {
    2474             :   _active = true;
    2475             : }
    2476             : 
    2477             : 
    2478             : 
    2479             : inline
    2480             : void System::deactivate ()
    2481             : {
    2482             :   _active = false;
    2483             : }
    2484             : 
    2485             : 
    2486             : 
    2487             : inline
    2488       34596 : bool System::is_initialized () const
    2489             : {
    2490       83722 :   return _is_initialized;
    2491             : }
    2492             : 
    2493             : 
    2494             : 
    2495             : inline
    2496           0 : void System::set_basic_system_only ()
    2497             : {
    2498           0 :   _basic_system_only = true;
    2499           0 : }
    2500             : 
    2501             : 
    2502             : 
    2503             : inline
    2504             : unsigned int
    2505           0 : System::variable_scalar_number (std::string_view var,
    2506             :                                 unsigned int component) const
    2507             : {
    2508           0 :   return variable_scalar_number(this->variable_number(var), component);
    2509             : }
    2510             : 
    2511             : 
    2512             : 
    2513             : inline
    2514       22218 : dof_id_type System::n_active_dofs() const
    2515             : {
    2516       22948 :   return this->n_dofs() - this->n_constrained_dofs();
    2517             : }
    2518             : 
    2519             : 
    2520             : 
    2521             : inline
    2522             : bool System::have_vector (std::string_view vec_name) const
    2523             : {
    2524             :   return (_vectors.count(vec_name));
    2525             : }
    2526             : 
    2527             : 
    2528             : 
    2529             : inline
    2530        1698 : unsigned int System::n_vectors () const
    2531             : {
    2532        1698 :   return cast_int<unsigned int>(_vectors.size());
    2533             : }
    2534             : 
    2535             : inline
    2536        1440 : System::vectors_iterator System::vectors_begin ()
    2537             : {
    2538        1440 :   return _vectors.begin();
    2539             : }
    2540             : 
    2541             : inline
    2542        1892 : System::const_vectors_iterator System::vectors_begin () const
    2543             : {
    2544        1892 :   return _vectors.begin();
    2545             : }
    2546             : 
    2547             : inline
    2548        1440 : System::vectors_iterator System::vectors_end ()
    2549             : {
    2550        1440 :   return _vectors.end();
    2551             : }
    2552             : 
    2553             : inline
    2554        3784 : System::const_vectors_iterator System::vectors_end () const
    2555             : {
    2556        3784 :   return _vectors.end();
    2557             : }
    2558             : 
    2559             : inline
    2560             : System::matrices_iterator System::matrices_begin ()
    2561             : {
    2562             :   return _matrices.begin();
    2563             : }
    2564             : 
    2565             : inline
    2566             : System::const_matrices_iterator System::matrices_begin () const
    2567             : {
    2568             :   return _matrices.begin();
    2569             : }
    2570             : 
    2571             : inline
    2572             : System::matrices_iterator System::matrices_end ()
    2573             : {
    2574             :   return _matrices.end();
    2575             : }
    2576             : 
    2577             : inline
    2578             : System::const_matrices_iterator System::matrices_end () const
    2579             : {
    2580             :   return _matrices.end();
    2581             : }
    2582             : 
    2583             : inline
    2584           0 : void System::assemble_residual_derivatives (const ParameterVector &)
    2585             : {
    2586           0 :   libmesh_not_implemented();
    2587             : }
    2588             : 
    2589             : inline
    2590           0 : void System::disable_cache () { assemble_before_solve = true; }
    2591             : 
    2592             : inline
    2593     1719687 : unsigned int System::n_qois() const
    2594             : {
    2595     1719687 :   libmesh_assert_equal_to(this->_qoi.size(), this->_qoi_error_estimates.size());
    2596             : 
    2597     8225214 :   return cast_int<unsigned int>(this->_qoi.size());
    2598             : }
    2599             : 
    2600             : inline
    2601             : std::pair<unsigned int, Real>
    2602           0 : System::sensitivity_solve (const ParameterVector &)
    2603             : {
    2604           0 :   libmesh_not_implemented();
    2605             : }
    2606             : 
    2607             : inline
    2608             : std::pair<unsigned int, Real>
    2609           0 : System::weighted_sensitivity_solve (const ParameterVector &,
    2610             :                                     const ParameterVector &)
    2611             : {
    2612           0 :   libmesh_not_implemented();
    2613             : }
    2614             : 
    2615             : inline
    2616             : std::pair<unsigned int, Real>
    2617           0 : System::adjoint_solve (const QoISet &)
    2618             : {
    2619           0 :   libmesh_not_implemented();
    2620             : }
    2621             : 
    2622             : inline
    2623             : std::pair<unsigned int, Real>
    2624           0 : System::weighted_sensitivity_adjoint_solve (const ParameterVector &,
    2625             :                                             const ParameterVector &,
    2626             :                                             const QoISet &)
    2627             : {
    2628           0 :   libmesh_not_implemented();
    2629             : }
    2630             : 
    2631             : inline
    2632             : void
    2633           0 : System::adjoint_qoi_parameter_sensitivity (const QoISet &,
    2634             :                                            const ParameterVector &,
    2635             :                                            SensitivityData &)
    2636             : {
    2637           0 :   libmesh_not_implemented();
    2638             : }
    2639             : 
    2640             : inline
    2641             : void
    2642           0 : System::forward_qoi_parameter_sensitivity (const QoISet &,
    2643             :                                            const ParameterVector &,
    2644             :                                            SensitivityData &)
    2645             : {
    2646           0 :   libmesh_not_implemented();
    2647             : }
    2648             : 
    2649             : inline
    2650             : void
    2651           0 : System::qoi_parameter_hessian(const QoISet &,
    2652             :                               const ParameterVector &,
    2653             :                               SensitivityData &)
    2654             : {
    2655           0 :   libmesh_not_implemented();
    2656             : }
    2657             : 
    2658             : inline
    2659             : void
    2660           0 : System::qoi_parameter_hessian_vector_product(const QoISet &,
    2661             :                                              const ParameterVector &,
    2662             :                                              const ParameterVector &,
    2663             :                                              SensitivityData &)
    2664             : {
    2665           0 :   libmesh_not_implemented();
    2666             : }
    2667             : 
    2668             : inline
    2669        1080 : unsigned int System::n_matrices () const
    2670             : {
    2671        1080 :   return cast_int<unsigned int>(_matrices.size());
    2672             : }
    2673             : 
    2674             : template <template <typename> class MatrixType>
    2675             : inline
    2676             : SparseMatrix<Number> &
    2677             : System::add_matrix (std::string_view mat_name,
    2678             :                     const ParallelType type)
    2679             : {
    2680             :   // Return the matrix if it is already there.
    2681             :   auto it = this->_matrices.find(mat_name);
    2682             :   if (it != this->_matrices.end())
    2683             :     return *it->second;
    2684             : 
    2685             :   // Otherwise build the matrix to return.
    2686             :   auto pr = _matrices.emplace(mat_name, std::make_unique<MatrixType<Number>>(this->comm()));
    2687             :   _matrix_types.emplace(mat_name, type);
    2688             : 
    2689             :   SparseMatrix<Number> & mat = *(pr.first->second);
    2690             : 
    2691             :   // Initialize it first if we've already initialized the others.
    2692             :   this->late_matrix_init(mat, type);
    2693             : 
    2694             :   return mat;
    2695             : }
    2696             : 
    2697             : inline void
    2698             : System::prefer_hash_table_matrix_assembly(const bool preference)
    2699             : {
    2700             :   libmesh_error_msg_if(
    2701             :       _matrices_initialized,
    2702             :       "System::prefer_hash_table_matrix_assembly() should be called before matrices are initialized");
    2703             :   _prefer_hash_table_matrix_assembly = preference;
    2704             : }
    2705             : } // namespace libMesh
    2706             : 
    2707             : #endif // LIBMESH_SYSTEM_H

Generated by: LCOV version 1.14