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 11534317 : return _sys_number;
2427 : }
2428 :
2429 :
2430 :
2431 : inline
2432 850533 : const MeshBase & System::get_mesh() const
2433 : {
2434 18488614 : 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 87666897 : const DofMap & System::get_dof_map() const
2449 : {
2450 87666897 : 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 1719404 : unsigned int System::n_qois() const
2594 : {
2595 1719404 : libmesh_assert_equal_to(this->_qoi.size(), this->_qoi_error_estimates.size());
2596 :
2597 8224140 : 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
|