Debian Codegraph @

include/deal.II/non_matching/coupling.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2018 - 2023 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_non_matching_coupling
16 #define dealii_non_matching_coupling
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/function_lib.h>
21 #include <deal.II/base/quadrature.h>
22
23 #include <deal.II/dofs/dof_handler.h>
24
25 #include <deal.II/fe/component_mask.h>
26 #include <deal.II/fe/fe.h>
27 #include <deal.II/fe/fe_values.h>
28 #include <deal.II/fe/mapping_q1.h>
29
30 #include <deal.II/grid/grid_tools_cache.h>
31
32 #include <deal.II/lac/affine_constraints.h>
33
34 DEAL_II_NAMESPACE_OPEN
35
36 /**
37 * A namespace for functions offering tools to handle two meshes with no
38 * alignment requirements.
39 *
40 * Typically these functions allow for computations on the real-space
41 * intersection between the two meshes e.g. surface integrals and
42 * construction of coupling matrices.
43 */
44 namespace NonMatching
45 {
46 /**
47 * Create a coupling sparsity pattern for non-matching, overlapping grids.
48 *
49 * Given two non-matching triangulations, representing the domains $\Omega$
50 * and $B$, with $B \subseteq \Omega$, and two finite element spaces
51 * $V(\Omega) = \text{span}\{v_i\}_{i=0}^n$ and $Q(B) =
52 * \text{span}\{w_j\}_{j=0}^m$, compute the sparsity pattern that would be
53 * necessary to assemble the matrix
54 * \f[
55 * M_{ij} \dealcoloneq \int_{B} v_i(x) w_j(x) dx,
56 * \quad i \in [0,n), j \in [0,m),
57 * \f]
58 * where $V(\Omega)$ is the finite element space associated with the
59 * `space_dh` passed to this function (or part of it, if specified in
60 * `space_comps`), while $Q(B)$ is the finite element space associated with
61 * the `immersed_dh` passed to this function (or part of it, if specified in
62 * `immersed_comps`).
63 *
64 * The `sparsity` is filled by locating the position of quadrature points
65 * (obtained by the reference quadrature `quad`) defined on elements of $B$
66 * with respect to the embedding triangulation $\Omega$. For each overlapping
67 * cell, the entries corresponding to `space_comps` in `space_dh` and
68 * `immersed_comps` in `immersed_dh` are added to the sparsity pattern.
69 *
70 * The `space_comps` and `immersed_comps` masks are assumed to be ordered in
71 * the same way: the first component of `space_comps` will couple with the
72 * first component of `immersed_comps`, the second with the second, and so
73 * on. If one of the two masks has more non-zero than the other, then the
74 * excess components will be ignored.
75 *
76 * If the domain $B$ does not fall within $\Omega$, an exception will be
77 * thrown by the algorithm that computes the quadrature point locations. In
78 * particular, notice that this function only makes sens for `dim1` lower or
79 * equal than `dim0`. A static assert guards that this is actually the case.
80 *
81 * For both spaces, it is possible to specify a custom Mapping, which
82 * defaults to StaticMappingQ1 for both.
83 *
84 * This function will also work in parallel, provided that the immersed
85 * triangulation is of type parallel::shared::Triangulation<dim1,spacedim>.
86 * An exception is thrown if you use an immersed
87 * parallel::distributed::Triangulation<dim1,spacedim>.
88 *
89 * See the tutorial program step-60 for an example on how to use this
90 * function.
91 */
92 template <int dim0, int dim1, int spacedim, typename number = double>
93 void
94 create_coupling_sparsity_pattern(
95 const DoFHandler<dim0, spacedim> &space_dh,
96 const DoFHandler<dim1, spacedim> &immersed_dh,
97 const Quadrature<dim1> &quad,
98 SparsityPatternBase &sparsity,
99 const AffineConstraints<number> &constraints = {},
100 const ComponentMask &space_comps = {},
101 const ComponentMask &immersed_comps = {},
102 const Mapping<dim0, spacedim> &space_mapping =
103 StaticMappingQ1<dim0, spacedim>::mapping,
104 const Mapping<dim1, spacedim> &immersed_mapping =
105 StaticMappingQ1<dim1, spacedim>::mapping,
106 const AffineConstraints<number> &immersed_constraints =
107 AffineConstraints<number>());
108
109 /**
110 * Same as above, but takes an additional GridTools::Cache object, instead of
111 * creating one internally. In this version of the function, the parameter @p
112 * space_mapping cannot be specified, since it is taken from the @p cache
113 * parameter.
114 */
115 template <int dim0, int dim1, int spacedim, typename number = double>
116 void
117 create_coupling_sparsity_pattern(
118 const GridTools::Cache<dim0, spacedim> &cache,
119 const DoFHandler<dim0, spacedim> &space_dh,
120 const DoFHandler<dim1, spacedim> &immersed_dh,
121 const Quadrature<dim1> &quad,
122 SparsityPatternBase &sparsity,
123 const AffineConstraints<number> &constraints = {},
124 const ComponentMask &space_comps = {},
125 const ComponentMask &immersed_comps = {},
126 const Mapping<dim1, spacedim> &immersed_mapping =
127 StaticMappingQ1<dim1, spacedim>::mapping,
128 const AffineConstraints<number> &immersed_constraints =
129 AffineConstraints<number>());
130
131
132 /**
133 * Create a coupling @ref GlossMassMatrix "mass matrix" for non-matching, overlapping grids.
134 *
135 * Given two non-matching triangulations, representing the domains $\Omega$
136 * and $B$, with $B \subseteq \Omega$, and two finite element spaces
137 * $V(\Omega) = \text{span}\{v_i\}_{i=0}^n$ and $Q(B) =
138 * \text{span}\{w_j\}_{j=0}^m$, compute the coupling matrix
139 * \f[
140 * M_{ij} \dealcoloneq \int_{B} v_i(x) w_j(x) dx,
141 * \quad i \in [0,n), j \in [0,m),
142 * \f]
143 * where $V(\Omega)$ is the finite element space associated with the
144 * `space_dh` passed to this function (or part of it, if specified in
145 * `space_comps`), while $Q(B)$ is the finite element space associated with
146 * the `immersed_dh` passed to this function (or part of it, if specified in
147 * `immersed_comps`).
148 *
149 * The corresponding sparsity patterns can be computed by calling the
150 * make_coupling_sparsity_pattern function. The elements of the matrix are
151 * computed by locating the position of quadrature points defined on elements
152 * of $B$ with respect to the embedding triangulation $\Omega$.
153 *
154 * The `space_comps` and `immersed_comps` masks are assumed to be ordered in
155 * the same way: the first component of `space_comps` will couple with the
156 * first component of `immersed_comps`, the second with the second, and so
157 * on. If one of the two masks has more non-zero entries non-zero than the
158 * other, then the excess components will be ignored.
159 *
160 * If the domain $B$ does not fall within $\Omega$, an exception will be
161 * thrown by the algorithm that computes the quadrature point locations. In
162 * particular, notice that this function only makes sense for `dim1` lower or
163 * equal than `dim0`. A static assert guards that this is actually the case.
164 *
165 * For both spaces, it is possible to specify a custom Mapping, which
166 * defaults to StaticMappingQ1 for both.
167 *
168 * This function will also work in parallel, provided that the immersed
169 * triangulation is of type parallel::shared::Triangulation<dim1,spacedim>.
170 * An exception is thrown if you use an immersed
171 * parallel::distributed::Triangulation<dim1,spacedim>.
172 *
173 * See the tutorial program step-60 for an example on how to use this
174 * function.
175 */
176 template <int dim0, int dim1, int spacedim, typename Matrix>
177 void
178 create_coupling_mass_matrix(
179 const DoFHandler<dim0, spacedim> &space_dh,
180 const DoFHandler<dim1, spacedim> &immersed_dh,
181 const Quadrature<dim1> &quad,
182 Matrix &matrix,
183 const AffineConstraints<typename Matrix::value_type> &constraints =
184 AffineConstraints<typename Matrix::value_type>(),
185 const ComponentMask &space_comps = {},
186 const ComponentMask &immersed_comps = {},
187 const Mapping<dim0, spacedim> &space_mapping =
188 StaticMappingQ1<dim0, spacedim>::mapping,
189 const Mapping<dim1, spacedim> &immersed_mapping =
190 StaticMappingQ1<dim1, spacedim>::mapping,
191 const AffineConstraints<typename Matrix::value_type> &immersed_constraints =
192 AffineConstraints<typename Matrix::value_type>());
193
194 /**
195 * Same as above, but takes an additional GridTools::Cache object, instead of
196 * creating one internally. In this version of the function, the parameter @p
197 * space_mapping cannot specified, since it is taken from the @p cache
198 * parameter.
199 */
200 template <int dim0, int dim1, int spacedim, typename Matrix>
201 void
202 create_coupling_mass_matrix(
203 const GridTools::Cache<dim0, spacedim> &cache,
204 const DoFHandler<dim0, spacedim> &space_dh,
205 const DoFHandler<dim1, spacedim> &immersed_dh,
206 const Quadrature<dim1> &quad,
207 Matrix &matrix,
208 const AffineConstraints<typename Matrix::value_type> &constraints =
209 AffineConstraints<typename Matrix::value_type>(),
210 const ComponentMask &space_comps = {},
211 const ComponentMask &immersed_comps = {},
212 const Mapping<dim1, spacedim> &immersed_mapping =
213 StaticMappingQ1<dim1, spacedim>::mapping,
214 const AffineConstraints<typename Matrix::value_type> &immersed_constraints =
215 AffineConstraints<typename Matrix::value_type>());
216
217 /**
218 * Create a coupling sparsity pattern for non-matching independent grids,
219 * using a convolution kernel with compact support of radius epsilon.
220 *
221 * Given two non-matching triangulations, representing the domains $\Omega^0$
222 * and $\Omega^1$, both embedded in $\mathbb{R}^d$, and two finite element
223 * spaces $V^0(\Omega^0) = \text{span}\{v_i\}_{i=0}^n$ and $V^1(\Omega^1) =
224 * \text{span}\{w_\alpha\}_{\alpha=0}^m$, compute the sparsity pattern that
225 * would be necessary to assemble the matrix
226 *
227 * \f[
228 * M_{i\alpha} \dealcoloneq \int_{\Omega^0} \int_{\Omega^1}
229 * v_i(x) K^{\epsilon}(x-y) w_\alpha(y) dx \ dy,
230 * \quad i \in [0,n), \alpha \in [0,m),
231 * \f]
232 *
233 * where $V^0(\Omega^0)$ is the finite element space associated with the
234 * @p dh0 passed to this function (or part of it, if specified in
235 * @p comps0), while $V^1(\Omega^1)$ is the finite element space associated
236 * with the @p dh1 passed to this function (or part of it, if specified
237 * in @p comps1), and $K^\epsilon$ is a function derived from
238 * CutOffFunctionBase with compact support included in a ball of radius
239 * $\epsilon$.
240 *
241 * The @p comps0 and @p comps1 masks are assumed to be ordered in
242 * the same way: the first component of @p comps0 will couple with the
243 * first component of @p comps1, the second with the second, and so
244 * on. If one of the two masks has more active components than the other, then
245 * the excess components will be ignored.
246 *
247 * For both spaces, it is possible to specify a custom Mapping, which
248 * defaults to StaticMappingQ1 for both.
249 *
250 * This function will also work in parallel, provided that at least one of the
251 * triangulations is of type parallel::shared::Triangulation<dim1,spacedim>.
252 * An exception is thrown if both triagnulations are of type
253 * parallel::distributed::Triangulation<dim1,spacedim>.
254 *
255 * This function assumes that the convolution has support contained in a box
256 * of radius @p epsilon. If epsilon is set to zero, then we assume that the
257 * kernel is the Dirac delta distribution, and the call is forwarded to the
258 * method in this namespace with the same name, that does not take an epsilon
259 * as input (but a quadrature formula @p quad is required). In this case, more
260 * restrictive conditions are required on the two spaces. See the
261 * documentation of the other create_coupling_sparsity_pattern() function.
262 */
263 template <int dim0, int dim1, int spacedim, typename Number = double>
264 void
265 create_coupling_sparsity_pattern(
266 const double &epsilon,
267 const GridTools::Cache<dim0, spacedim> &cache0,
268 const GridTools::Cache<dim1, spacedim> &cache1,
269 const DoFHandler<dim0, spacedim> &dh0,
270 const DoFHandler<dim1, spacedim> &dh1,
271 const Quadrature<dim1> &quad,
272 SparsityPatternBase &sparsity,
273 const AffineConstraints<Number> &constraints0 = AffineConstraints<Number>(),
274 const ComponentMask &comps0 = {},
275 const ComponentMask &comps1 = {});
276
277 /**
278 * Create a coupling @ref GlossMassMatrix "mass matrix" for non-matching independent grids,
279 * using a convolution kernel with compact support.
280 *
281 * Given two non-matching triangulations, representing the domains
282 * $\Omega^0$ and $\Omega^1$, both embedded in $\mathbb{R}^d$, and two finite
283 * element spaces $V^0(\Omega^0) = \text{span}\{v_i\}_{i=0}^n$ and
284 * $V^1(\Omega^1) = \text{span}\{w_\alpha\}_{\alpha=0}^m$, compute the matrix
285 *
286 * \f[
287 * M_{i\alpha} \dealcoloneq \int_{\Omega^0} \int_{\Omega^1}
288 * v_i(x) K^{\epsilon}(x-y) w_\alpha(y) dx \ dy,
289 * \quad i \in [0,n), \alpha \in [0,m),
290 * \f]
291 *
292 * where $V^0(\Omega^0)$ is the finite element space associated with the
293 * @p dh0 passed to this function (or part of it, if specified in
294 * @p comps0), while $V^1(\Omega^1)$ is the finite element space associated
295 * with the @p dh1 passed to this function (or part of it, if specified
296 * in @p comps1), and $K^\epsilon$ is a function derived from
297 * CutOffFunctionBase with compact support included in a ball of radius
298 * $\epsilon$.
299 *
300 * The corresponding sparsity patterns can be computed by calling the
301 * make_coupling_sparsity_pattern() function.
302 *
303 * The @p comps0 and @p comps1 masks are assumed to be ordered in
304 * the same way: the first component of @p comps0 will couple with the
305 * first component of @p comps1, the second with the second, and so
306 * on. If one of the two masks has more active components than the other, then
307 * the excess components will be ignored.
308 *
309 * For both spaces, it is possible to specify a custom Mapping, which
310 * defaults to StaticMappingQ1 for both.
311 *
312 * This function will also work in parallel, provided that one of the two
313 * triangulations is of type parallel::shared::Triangulation<dim1,spacedim>.
314 * An exception is thrown if both triangulations are of type
315 * parallel::distributed::Triangulation<dim1,spacedim>.
316 *
317 * The parameter @p epsilon is used to set the size of the cut-off function
318 * used to compute the convolution. If epsilon is set to zero, then we assume
319 * that the kernel is the Dirac delta distribution, and the call is forwarded
320 * to the method in this namespace with the same name, that does not take an
321 * epsilon as input.
322 */
323 template <int dim0, int dim1, int spacedim, typename Matrix>
324 void
325 create_coupling_mass_matrix(
326 Functions::CutOffFunctionBase<spacedim> &kernel,
327 const double &epsilon,
328 const GridTools::Cache<dim0, spacedim> &cache0,
329 const GridTools::Cache<dim1, spacedim> &cache1,
330 const DoFHandler<dim0, spacedim> &dh0,
331 const DoFHandler<dim1, spacedim> &dh1,
332 const Quadrature<dim0> &quadrature0,
333 const Quadrature<dim1> &quadrature1,
334 Matrix &matrix,
335 const AffineConstraints<typename Matrix::value_type> &constraints0 =
336 AffineConstraints<typename Matrix::value_type>(),
337 const ComponentMask &comps0 = {},
338 const ComponentMask &comps1 = {});
339 } // namespace NonMatching
340 DEAL_II_NAMESPACE_CLOSE
341
342 #endif