Debian Codegraph @

include/deal.II/numerics/vector_tools_mean_value.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_vector_tools_mean_value_h
16 #define dealii_vector_tools_mean_value_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/template_constraints.h>
22
23 #include <deal.II/lac/read_vector.h>
24
25 #include <vector>
26
27 DEAL_II_NAMESPACE_OPEN
28
29 #ifndef DOXYGEN
30 // forward declarations
31 template <int dim, int spacedim>
32 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
33 class DoFHandler;
34 template <int dim, int spacedim>
35 class Mapping;
36 template <int dim>
37 class Quadrature;
38 namespace hp
39 {
40 template <int dim, int spacedim>
41 class MappingCollection;
42 template <int dim>
43 class QCollection;
44 } // namespace hp
45 #endif
46
47 namespace VectorTools
48 {
49 /**
50 * Mean value operations
51 */
52 /** @{ */
53
54 /**
55 * Subtract the (algebraic) mean value from a vector.
56 *
57 * This function is most frequently used as a mean-value filter for Stokes:
58 * The pressure in Stokes' equations with only Dirichlet boundaries for the
59 * velocities is only determined up to a constant. This function allows to
60 * subtract the mean value of the pressure. It is usually called in a
61 * preconditioner and generates updates with mean value zero. The mean value
62 * is computed as the mean value of the degrees of freedom values as given
63 * by the input vector; they are not weighted by the area of cells, i.e. the
64 * mean is computed as $\sum_i v_i$, rather than as $\int_\Omega v(x) =
65 * \int_\Omega \sum_i v_i \phi_i(x)$. The latter can be obtained from the
66 * VectorTools::compute_mean_function, however.
67 *
68 * Apart from the vector @p v to operate on, this function takes a boolean
69 * mask @p p_select that has a true entry for every element of the vector
70 * for which the mean value shall be computed and later subtracted. The
71 * argument is used to denote which components of the solution vector
72 * correspond to the pressure, and avoid touching all other components of
73 * the vector, such as the velocity components. (Note, however, that the
74 * mask is not a
75 * @ref GlossComponentMask
76 * operating on the vector components of the finite element the solution
77 * vector @p v may be associated with; rather, it is a mask on the entire
78 * vector, without reference to what the vector elements mean.)
79 *
80 * The boolean mask @p p_select has an empty vector as default value, which
81 * will be interpreted as selecting all vector elements, hence, subtracting
82 * the algebraic mean value on the whole vector. This allows to call this
83 * function without a boolean mask if the whole vector should be processed.
84 *
85 * @note In the context of using this function to filter out the kernel of
86 * an operator (such as the null space of the Stokes operator that consists
87 * of the constant pressures), this function only makes sense for finite
88 * elements for which the null space indeed consists of the vector
89 * $(1,1,\ldots,1)^T$. This is the case for example for the usual Lagrange
90 * elements where the sum of all shape functions equals the function that is
91 * constant one. However, it is not true for some other functions: for
92 * example, for the FE_DGP element (another valid choice for the pressure in
93 * Stokes discretizations), the first shape function on each cell is
94 * constant while further elements are $L_2$ orthogonal to it (on the
95 * reference cell); consequently, the sum of all shape functions is not
96 * equal to one, and the vector that is associated with the constant mode is
97 * not equal to $(1,1,\ldots,1)^T$. For such elements, a different procedure
98 * has to be used when subtracting the mean value.
99 *
100 * @warning This function can only be used for distributed vector classes
101 * provided the boolean mask is empty, i.e. selecting the whole vector.
102 *
103 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
104 */
105 template <typename VectorType>
106 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
107 void subtract_mean_value(VectorType &v,
108 const std::vector<bool> &p_select = {});
109
110 /**
111 * Add the constant @p constant_adjustment to the specified
112 * component of the finite element function given by the coefficient
113 * vector @p solution defined by the given DoFHandler.
114 *
115 * This operation is a common operation to compute a solution with
116 * mean pressure zero for a Stokes flow problem. Here, one can
117 * use VectorTools::compute_mean_value() to compute the value to
118 * subtract.
119 *
120 * For a nodal finite element like FE_Q, this function will simply add
121 * the value @p constant_adjustment to each coefficient of the corresponding
122 * component. If you have the component in a separate block @p b, you
123 * could directly use
124 * <code>solution.block(b) += constant_adjustment</code>
125 * instead of calling this function (and this would be more efficient).
126 * For other finite element spaces like FE_DGP, the logic is more
127 * complicated and handled correctly by this function.
128 *
129 * @note Not all kinds of finite elements are supported and the selected
130 * component must not be part of a non-primitive element for this
131 * implementation to work.
132 *
133 * @note In contrast to subtract_mean_value(), this function can
134 * adjust a single component of a distributed vector.
135 *
136 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
137 */
138 template <typename VectorType, int dim, int spacedim = dim>
139 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
140 void add_constant(VectorType &solution,
141 const DoFHandler<dim, spacedim> &dof_handler,
142 const unsigned int component,
143 const typename VectorType::value_type constant_adjustment);
144
145 /**
146 * Compute the mean value of one component of the solution.
147 *
148 * This function integrates the chosen component over the whole domain and
149 * returns the result, i.e. it computes $\frac{1}{|\Omega|}\int_\Omega
150 * [u_h(x)]_c \; dx$ where $c$ is the vector component and $u_h$ is the
151 * function representation of the nodal vector given as fourth argument. The
152 * integral is evaluated numerically using the quadrature formula given as
153 * third argument.
154 *
155 * This function is used in the "Possibilities for extensions" part of the
156 * results section of
157 * @ref step_3 "step-3".
158 *
159 * @note The function is most often used when solving a problem whose
160 * solution is only defined up to a constant, for example a pure Neumann
161 * problem or the pressure in a Stokes or Navier-Stokes problem. In both
162 * cases, subtracting the mean value as computed by the current function,
163 * from the nodal vector does not generally yield the desired result of a
164 * finite element function with mean value zero. In fact, it only works for
165 * Lagrangian elements. For all other elements, you will need to compute the
166 * mean value and subtract it right inside the evaluation routine.
167 */
168 template <int dim, typename Number, int spacedim>
169 Number
170 compute_mean_value(
171 const hp::MappingCollection<dim, spacedim> &mapping_collection,
172 const DoFHandler<dim, spacedim> &dof,
173 const hp::QCollection<dim> &q_collection,
174 const ReadVector<Number> &v,
175 const unsigned int component);
176
177 /**
178 * Calls the other compute_mean_value() function, see above, for the non-hp
179 * case. That means, it requires a single FiniteElement, a single Quadrature,
180 * and a single Mapping object.
181 */
182 template <int dim, typename Number, int spacedim>
183 Number
184 compute_mean_value(const Mapping<dim, spacedim> &mapping,
185 const DoFHandler<dim, spacedim> &dof,
186 const Quadrature<dim> &quadrature,
187 const ReadVector<Number> &v,
188 const unsigned int component);
189
190 /**
191 * Call the other compute_mean_value() function, see above, with
192 * <tt>mapping=MappingQ@<dim@>(1)</tt>.
193 */
194 template <int dim, typename Number, int spacedim>
195 Number
196 compute_mean_value(const DoFHandler<dim, spacedim> &dof,
197 const Quadrature<dim> &quadrature,
198 const ReadVector<Number> &v,
199 const unsigned int component);
200 /** @} */
201 } // namespace VectorTools
202
203 DEAL_II_NAMESPACE_CLOSE
204
205 #endif // dealii_vector_tools_mean_value_h