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