Debian Codegraph @

include/deal.II/multigrid/mg_constrained_dofs.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2010 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_mg_constrained_dofs_h
16 #define dealii_mg_constrained_dofs_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/mg_level_object.h>
22
23 #include <deal.II/fe/component_mask.h>
24
25 #include <deal.II/lac/affine_constraints.h>
26
27 #include <set>
28 #include <vector>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declaration
33 #ifndef DOXYGEN
34 template <int dim, int spacedim>
35 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
36 class DoFHandler;
37 #endif
38
39
40 /**
41 * Collection of boundary constraints and refinement edge constraints for
42 * level vectors.
43 *
44 * @ingroup mg
45 */
46 class MGConstrainedDoFs : public EnableObserverPointer
47 {
48 public:
49 using size_dof = std::vector<std::set<types::global_dof_index>>::size_type;
50 /**
51 * Fill the internal data structures with hanging node constraints extracted
52 * from the dof handler object. Works with natural boundary conditions only.
53 * There exists a sister function setting up boundary constraints as well.
54 *
55 * This function ensures that on every level, degrees of freedom at interior
56 * edges of a refinement level are treated corrected but leaves degrees of
57 * freedom at the boundary of the domain untouched assuming that no
58 * Dirichlet boundary conditions for them exist.
59 *
60 * Furthermore, this call sets up an AffineConstraints object on each
61 * level that contains possible periodicity constraints in case those
62 * have been added to the underlying triangulation. The AffineConstraints
63 * object can be queried by get_level_constraints(level). Note that the
64 * current implementation of periodicity constraints in this class does
65 * not support rotation matrices in the periodicity definition, i.e., the
66 * respective argument in the GridTools::collect_periodic_faces() may not
67 * be different from the identity matrix.
68 * If no level_relevant_dofs are passed as the second argument, the function
69 * uses the locally relevant level DoFs, extracted by
70 * DoFTools::extract_locally_relevant_level_dofs(). Otherwise, the
71 * user-provided IndexSets, which should define a superset of locally relevant
72 * DoFs, are used on each level to allow the user to add additional indices to
73 * the set of constrained DoFs.
74 */
75 template <int dim, int spacedim>
76 void
77 initialize(const DoFHandler<dim, spacedim> &dof,
78 const MGLevelObject<IndexSet> &level_relevant_dofs =
79 MGLevelObject<IndexSet>());
80
81 /**
82 * Fill the internal data structures with information
83 * about Dirichlet boundary dofs.
84 *
85 * The initialize() function has to be called before
86 * to set hanging node constraints.
87 *
88 * This function can be called multiple times to allow considering
89 * different sets of boundary_ids for different components.
90 */
91 template <int dim, int spacedim>
92 void
93 make_zero_boundary_constraints(
94 const DoFHandler<dim, spacedim> &dof,
95 const std::set<types::boundary_id> &boundary_ids,
96 const ComponentMask &component_mask = {});
97
98 /**
99 * Add Dirichlet boundary dofs to the internal data structures
100 * on level @p level.
101 * The indices are restricted to the set of locally relevant
102 * level dofs.
103 */
104 template <int dim, int spacedim>
105 void
106 add_boundary_indices(const DoFHandler<dim, spacedim> &dof,
107 const unsigned int level,
108 const IndexSet &boundary_indices);
109
110 /**
111 * Add user defined constraints to be used on level @p level.
112 *
113 * The user can call this function multiple times and any new,
114 * conflicting constraints will overwrite the previous constraints
115 * for that DoF.
116 *
117 * Before the transfer, the user defined constraints will be distributed
118 * to the source vector, and then any DoF index set using
119 * make_zero_boundary_constraints() will be overwritten with
120 * value zero.
121 *
122 * @note This is currently only implemented for MGTransferMatrixFree.
123 */
124 void
125 add_user_constraints(const unsigned int level,
126 const AffineConstraints<double> &constraints_on_level);
127
128 /**
129 * Fill the internal data structures with information
130 * about no normal flux boundary dofs.
131 *
132 * This function is limited to meshes whose no normal flux boundaries
133 * have faces which are normal to the x-, y-, or z-axis. Also, for a
134 * specific boundary id, all faces must be facing in the same direction,
135 * i.e., a boundary normal to the x-axis must have a different boundary
136 * id than a boundary normal to the y- or z-axis and so on. If the mesh
137 * was produced, for example, using the <tt>GridGenerator::hyper_cube()</tt>
138 * function, setting <tt>colorize=true</tt> during mesh generation and calling
139 * make_no_normal_flux_constraints() for each no normal flux boundary is
140 * sufficient.
141 */
142 template <int dim, int spacedim>
143 void
144 make_no_normal_flux_constraints(const DoFHandler<dim, spacedim> &dof,
145 const types::boundary_id bid,
146 const unsigned int first_vector_component);
147
148 /**
149 * Clear the user constraints on all levels.
150 */
151 void
152 clear_user_constraints();
153
154 /**
155 * Reset the data structures.
156 */
157 void
158 clear();
159
160 /**
161 * Determine whether a dof index is subject to a boundary constraint.
162 */
163 bool
164 is_boundary_index(const unsigned int level,
165 const types::global_dof_index index) const;
166
167 /**
168 * Determine whether a dof index is at the refinement edge.
169 */
170 bool
171 at_refinement_edge(const unsigned int level,
172 const types::global_dof_index index) const;
173
174
175 /**
176 * Determine whether the (i,j) entry of the interface matrix
177 * on a given level should be set. This is taken in terms of
178 * dof i, that is, return true if i is at a refinement edge,
179 * j is not, and both are not on the external boundary.
180 */
181 bool
182 is_interface_matrix_entry(const unsigned int level,
183 const types::global_dof_index i,
184 const types::global_dof_index j) const;
185
186 /**
187 * Return the indices of level dofs on the given level that are subject to
188 * Dirichlet boundary conditions (as set by the @p function_map parameter in
189 * initialize()). The indices are restricted to the set of locally relevant
190 * level dofs.
191 */
192 const IndexSet &
193 get_boundary_indices(const unsigned int level) const;
194
195
196 /**
197 * Return the indices of dofs on the given level that lie on an refinement
198 * edge (dofs on faces to neighbors that are coarser).
199 */
200 const IndexSet &
201 get_refinement_edge_indices(unsigned int level) const;
202
203
204 /**
205 * Return if Dirichlet boundary indices are set in initialize().
206 */
207 bool
208 have_boundary_indices() const;
209
210 /**
211 * Return the AffineConstraints object for a given level, containing
212 * periodicity constraints (if enabled on the triangulation).
213 */
214 const AffineConstraints<double> &
215 get_level_constraints(const unsigned int level) const;
216
217 /**
218 * Return the user defined constraint matrix for a given level. These
219 * constraints are set using the function add_user_constraints() and
220 * should not contain constraints for DoF indices set in
221 * make_zero_boundary_constraints() as they will be overwritten during
222 * the transfer.
223 */
224 const AffineConstraints<double> &
225 get_user_constraint_matrix(const unsigned int level) const;
226
227 /**
228 * Merge selected constraints of a specified @p level into a given single
229 * AffineConstraints object.
230 *
231 * @param constraints AffineConstraints object to be filled.
232 * @param level Refinement to be considered.
233 * @param add_boundary_indices Add boundary indices.
234 * @param add_refinement_edge_indices Add refinement-edge indices.
235 * @param add_level_constraints Add level constraints including the one passed
236 * during initialize() and periodicity constraints.
237 * @param add_user_constraints Add user constraints.
238 */
239 template <typename Number>
240 void
241 merge_constraints(AffineConstraints<Number> &constraints,
242 const unsigned int level,
243 const bool add_boundary_indices,
244 const bool add_refinement_edge_indices,
245 const bool add_level_constraints,
246 const bool add_user_constraints) const;
247
248 private:
249 /**
250 * The indices of boundary dofs for each level.
251 */
252 std::vector<IndexSet> boundary_indices;
253
254 /**
255 * The degrees of freedom on a given level that live on the refinement edge
256 * between the level and cells on a coarser level.
257 */
258 std::vector<IndexSet> refinement_edge_indices;
259
260 /**
261 * Constraint matrices containing information regarding potential
262 * periodic boundary conditions for each level .
263 */
264 std::vector<AffineConstraints<double>> level_constraints;
265
266 /**
267 * Constraint matrices defined by user.
268 */
269 std::vector<AffineConstraints<double>> user_constraints;
270 };
271
272
273
274 inline bool
275 MGConstrainedDoFs::is_boundary_index(const unsigned int level,
276 const types::global_dof_index index) const
277 {
278 if (boundary_indices.empty())
279 return false;
280
281 AssertIndexRange(level, boundary_indices.size());
282 return boundary_indices[level].is_element(index);
283 }
284
285
286
287 inline bool
288 MGConstrainedDoFs::at_refinement_edge(const unsigned int level,
289 const types::global_dof_index index) const
290 {
291 AssertIndexRange(level, refinement_edge_indices.size());
292
293 return refinement_edge_indices[level].is_element(index);
294 }
295
296
297
298 inline bool
299 MGConstrainedDoFs::is_interface_matrix_entry(
300 const unsigned int level,
301 const types::global_dof_index i,
302 const types::global_dof_index j) const
303 {
304 const IndexSet &interface_dofs_on_level =
305 this->get_refinement_edge_indices(level);
306
307 return interface_dofs_on_level.is_element(i) // at_refinement_edge(i)
308 && !interface_dofs_on_level.is_element(j) // !at_refinement_edge(j)
309 && !this->is_boundary_index(level, i) // !on_boundary(i)
310 && !this->is_boundary_index(level, j); // !on_boundary(j)
311 }
312
313
314
315 inline const IndexSet &
316 MGConstrainedDoFs::get_boundary_indices(const unsigned int level) const
317 {
318 AssertIndexRange(level, boundary_indices.size());
319 return boundary_indices[level];
320 }
321
322
323
324 inline const IndexSet &
325 MGConstrainedDoFs::get_refinement_edge_indices(unsigned int level) const
326 {
327 AssertIndexRange(level, refinement_edge_indices.size());
328 return refinement_edge_indices[level];
329 }
330
331
332
333 inline bool
334 MGConstrainedDoFs::have_boundary_indices() const
335 {
336 return boundary_indices.size() != 0;
337 }
338
339
340
341 inline const AffineConstraints<double> &
342 MGConstrainedDoFs::get_level_constraints(const unsigned int level) const
343 {
344 AssertIndexRange(level, level_constraints.size());
345 return level_constraints[level];
346 }
347
348
349
350 inline const AffineConstraints<double> &
351 MGConstrainedDoFs::get_user_constraint_matrix(const unsigned int level) const
352 {
353 AssertIndexRange(level, user_constraints.size());
354 return user_constraints[level];
355 }
356
357
358
359 DEAL_II_NAMESPACE_CLOSE
360
361 #endif