Debian Codegraph @

include/deal.II/non_matching/immersed_surface_quadrature.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 2024 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_immersed_surface_quadrature
16 #define dealii_non_matching_immersed_surface_quadrature
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/point.h>
22 #include <deal.II/base/quadrature.h>
23 #include <deal.II/base/tensor.h>
24
25 #include <vector>
26
27 DEAL_II_NAMESPACE_OPEN
28 namespace NonMatching
29 {
30 /**
31 * This class defines a quadrature formula to integrate over the intersection
32 * between an oriented surface, $\hat{S}$, and a cell or face. The word
33 * "immersed" in the class name reflects that the surface may intersect the
34 * cell/face in an arbitrary way.
35 *
36 * The spacedim template parameter of this class is the dimension that the
37 * (spacedim-1)-dimensional surface is embedded in:
38 * $\hat{S} \subset \mathbb{R}^{\text{spacedim}}$. The dim parameter
39 * describes the dimension of the "object" that the surface intersects. That
40 * is, dim = spacedim corresponds to the surface intersecting a cell and
41 * dim = spacedim - 1 corresponds to the surface intersecting a face. The
42 * quadrature formula is described by a set of quadrature points,
43 * $\hat{x}_q \in \mathbb{R}^{\text{dim}}$, weights, $w_q$, and normalized
44 * surface normals, $\hat{n}_q \in \mathbb{R}^{\text{spacedim}}$.
45 *
46 * Consider first the case dim = spacedim. We typically want to compute
47 * integrals in real space. A surface, $S$, intersecting a cell, $K$, in
48 * real space can be mapped onto a surface, $\hat{S}$, intersecting the unit
49 * cell, $\hat{K}$. Thus an integral over $S\cap K$ in real space can be
50 * transformed to an integral over $\hat{S} \cap \hat{K}$ according to
51 * @f[
52 * \int_{S\cap K} f dS =
53 * \int_{S\cap K} f |d\bar{S}| =
54 * \int_{\hat{S}\cap\hat{K}} f \circ F_{K} \det(J) |\left( J^{-1} \right
55 * )^T d\hat{S}|,
56 * @f]
57 * where $F_K$ is the mapping from reference to real space and $J$ is its
58 * Jacobian matrix. This transformation is possible since the continuous
59 * surface elements are vectors:
60 * $d\bar{S}, d\hat{S} \in \mathbb{R}^{spacedim}$, which are parallel to the
61 * normals of $S$ and $\hat{S}$. That is, the normal is needed to do the
62 * transformation. Thus, in addition to storing points and weights, this
63 * quadrature stores also the normalized normal for each quadrature point.
64 * This can be viewed as storing a discrete surface element,
65 * @f[
66 * \Delta \hat{S}_q \dealcoloneq w_q \hat{n}_q \approx d\hat{S}(\hat{x}_q),
67 * @f]
68 * for each quadrature point. The surface integral in real space would then be
69 * approximated as
70 * @f[
71 * \int_{S\cap K} f dS \approx
72 * \sum_{q} f \left(F_{K}(\hat{x}_{q}) \right) \det(J_q)
73 * |\left( J_q^{-1} \right)^T \hat{n}_q| w_q.
74 * @f]
75 *
76 * @image html immersed_surface_quadrature.svg
77 *
78 * When dim = spacedim - 1, this class represents a (spacedim-2)-dimensional
79 * integral. That is, if spacedim = 3 we have a line integral immersed in a
80 * face. Let $\hat{r}(t)$, $t \in [0,T]$ be an arc-length parameterizations of
81 * $\hat{F}\cap \hat{S}$, i.e., the part of the surface that intersects the
82 * face in reference space. This means that $\bar{r}(t) = F_K(\hat{r}(t))$ is
83 * a parameterization of $S\cap F$. The transformation of the line integral
84 * now reads
85 * @f[
86 * \int_{S\cap F} f dr
87 * = \int_{0}^T f(\bar{r}(t)) \left \|\frac{d\bar{r}}{dt} \right \| dt
88 * = \int_{0}^T f(F_K(\hat{r}(t))) \left \| J \frac{d\hat{r}}{dt} \right \| dt
89 * \approx \sum_{q} f \left(F_{K}(\hat{x}_{q}) \right) \|J(\hat{x}_q)
90 * \hat{t}_q \| w_q,
91 * @f]
92 * where $\hat{t}_q = \frac{d\hat{r}}{dt}(x_q) $ is the tangent to the curve
93 * at $\hat{x}_q$. This tangent can also be computed as
94 * $t_q = \hat{n}_q \times \hat{n}_F / \| \hat{n}_q \times \hat{n}_F \|$ where
95 * $\hat{n}_F$ is the face normal. It would be possible to compute the tangent
96 * by only knowing the normal to the curve in the face plane (i.e. the
97 * dim-dimensional normal). However, when these quadratures are used, the weak
98 * form typically involves the so-called conormal, which can not be computed
99 * without knowing the surface normal in
100 * $\mathbb{R}^{\text{spacedim}}$. The conormal is the unit vector parallel to
101 * the projection of the face normal into the surface plane. This is the same
102 * as the normalized
103 * @ref GlossBoundaryForm "boundary form".
104 */
105 template <int dim, int spacedim = dim>
106 class ImmersedSurfaceQuadrature : public Quadrature<dim>
107 {
108 public:
109 /**
110 * Default constructor to initialize the quadrature with no quadrature
111 * points.
112 */
113 ImmersedSurfaceQuadrature() = default;
114
115 /**
116 * Construct a quadrature formula from vectors of points, weights and
117 * surface normals. The points, weights and normals should be with respect
118 * to reference space, and the normals should be normalized.
119 */
120 ImmersedSurfaceQuadrature(const std::vector<Point<dim>> &points,
121 const std::vector<double> &weights,
122 const std::vector<Tensor<1, spacedim>> &normals);
123
124 /**
125 * Clears weights, points and normals vectors.
126 */
127 void
128 clear();
129
130 /**
131 * Extend the given formula by an additional quadrature point.
132 * The point, weight and normal should be with respect to reference space,
133 * and the normal should be normalized.
134 *
135 * This function exists since immersed quadrature rules can be rather
136 * complicated to construct. Often the construction is done by
137 * partitioning the cell into regions and constructing points on each
138 * region separately. This can make it cumbersome to create the quadrature
139 * from the constructor since all quadrature points have to be known at
140 * time of creation of the object.
141 *
142 * @note This function should only be used during construction of the
143 * quadrature formula.
144 */
145 void
146 push_back(const Point<dim> &point,
147 const double weight,
148 const Tensor<1, spacedim> &normal);
149
150 /**
151 * Return a reference to the <tt>i</tt>th surface normal.
152 */
153 const Tensor<1, spacedim> &
154 normal_vector(const unsigned int i) const;
155
156 /**
157 * Return a reference to the whole %vector of normals.
158 */
159 const std::vector<Tensor<1, spacedim>> &
160 get_normal_vectors() const;
161
162 protected:
163 /**
164 * %Vector of surface normals at each quadrature point.
165 */
166 std::vector<Tensor<1, spacedim>> normals;
167 };
168
169 } // namespace NonMatching
170 DEAL_II_NAMESPACE_CLOSE
171
172 #endif