| 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 |