| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 1998 - 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_vector_tools_h |
| 16 |
#define dealii_vector_tools_h |
| 17 |
|
| 18 |
|
| 19 |
#include <deal.II/base/config.h> |
| 20 |
|
| 21 |
#include <deal.II/numerics/vector_tools_boundary.h> |
| 22 |
#include <deal.II/numerics/vector_tools_common.h> |
| 23 |
#include <deal.II/numerics/vector_tools_constraints.h> |
| 24 |
#include <deal.II/numerics/vector_tools_evaluate.h> |
| 25 |
#include <deal.II/numerics/vector_tools_integrate_difference.h> |
| 26 |
#include <deal.II/numerics/vector_tools_interpolate.h> |
| 27 |
#include <deal.II/numerics/vector_tools_mean_value.h> |
| 28 |
#include <deal.II/numerics/vector_tools_point_gradient.h> |
| 29 |
#include <deal.II/numerics/vector_tools_point_value.h> |
| 30 |
#include <deal.II/numerics/vector_tools_project.h> |
| 31 |
#include <deal.II/numerics/vector_tools_rhs.h> |
| 32 |
|
| 33 |
|
| 34 |
DEAL_II_NAMESPACE_OPEN |
| 35 |
|
| 36 |
// TODO: Move documentation of functions to the functions! |
| 37 |
|
| 38 |
/** |
| 39 |
* Provide a namespace which offers some operations on vectors. Among these |
| 40 |
* are assembling of standard vectors, integration of the difference of a |
| 41 |
* finite element solution and a continuous function, interpolations and |
| 42 |
* projections of continuous functions to the finite element space and other |
| 43 |
* operations. |
| 44 |
* |
| 45 |
* @note There exist two versions of almost all functions, one that takes an |
| 46 |
* explicit Mapping argument and one that does not. The second one generally |
| 47 |
* calls the first with an implicit $Q_1$ argument (i.e., with an argument of |
| 48 |
* kind MappingQ(1)). If your intend your code to use a different |
| 49 |
* mapping than a (bi-/tri-)linear one, then you need to call the functions |
| 50 |
* <b>with</b> mapping argument should be used. |
| 51 |
* |
| 52 |
* |
| 53 |
* <h3>Description of operations</h3> |
| 54 |
* |
| 55 |
* This collection of methods offers the following operations: |
| 56 |
* <ul> |
| 57 |
* <li> Interpolation: assign each degree of freedom in the vector to be the |
| 58 |
* value of the function given as argument. This is identical to saying that |
| 59 |
* the resulting finite element function (which is isomorphic to the output |
| 60 |
* vector) has exact function values in all support points of trial functions. |
| 61 |
* The support point of a trial function is the point where its value equals |
| 62 |
* one, e.g. for linear trial functions the support points are four corners of |
| 63 |
* an element. This function therefore relies on the assumption that a finite |
| 64 |
* element is used for which the degrees of freedom are function values |
| 65 |
* (Lagrange elements) rather than gradients, normal derivatives, second |
| 66 |
* derivatives, etc (Hermite elements, quintic Argyris element, etc.). |
| 67 |
* |
| 68 |
* It seems inevitable that some values of the vector to be created are set |
| 69 |
* twice or even more than that. The reason is that we have to loop over all |
| 70 |
* cells and get the function values for each of the trial functions located |
| 71 |
* thereon. This applies also to the functions located on faces and corners |
| 72 |
* which we thus visit more than once. While setting the value in the vector |
| 73 |
* is not an expensive operation, the evaluation of the given function may be, |
| 74 |
* taking into account that a virtual function has to be called. |
| 75 |
* |
| 76 |
* <li> Projection: compute the <i>L</i><sup>2</sup>-projection of the given |
| 77 |
* function onto the finite element space, i.e. if <i>f</i> is the function to |
| 78 |
* be projected, compute <i>f<sub>h</sub></i> in <i>V<sub>h</sub></i> such |
| 79 |
* that |
| 80 |
* (<i>f<sub>h</sub></i>,<i>v<sub>h</sub></i>)=(<i>f</i>,<i>v<sub>h</sub></i>) |
| 81 |
* for all discrete test functions <i>v<sub>h</sub></i>. This is done through |
| 82 |
* the solution of the linear system of equations <i> M v = f</i> where |
| 83 |
* <i>M</i> is the @ref GlossMassMatrix "mass matrix" $m_{ij} = \int_\Omega \phi_i(x) \phi_j(x) dx$ |
| 84 |
* and $f_i = \int_\Omega f(x) \phi_i(x) dx$. The solution vector $v$ then is |
| 85 |
* the nodal representation of the projection <i>f<sub>h</sub></i>. The |
| 86 |
* project() functions are used in the step-21 and step-23 tutorial programs. |
| 87 |
* |
| 88 |
* In order to get proper results, it be may necessary to treat boundary |
| 89 |
* conditions right. Below are listed some cases where this may be needed. If |
| 90 |
* needed, this is done by <i>L</i><sup>2</sup>-projection of the trace of the |
| 91 |
* given function onto the finite element space restricted to the boundary of |
| 92 |
* the domain, then taking this information and using it to eliminate the |
| 93 |
* boundary nodes from the mass matrix of the whole domain, using the |
| 94 |
* MatrixTools::apply_boundary_values() function. The projection of the trace |
| 95 |
* of the function to the boundary is done with the |
| 96 |
* VectorTools::project_boundary_values() (see below) function, which is |
| 97 |
* called with a map of boundary functions |
| 98 |
* std::map<types::boundary_id, const Function<spacedim,number>*> in which all |
| 99 |
* boundary indicators from zero to numbers::internal_face_boundary_id-1 |
| 100 |
* (numbers::internal_face_boundary_id is used for other purposes, see the |
| 101 |
* Triangulation class documentation) point to the function to be projected. |
| 102 |
* The projection to the boundary takes place using a second quadrature |
| 103 |
* formula on the boundary given to the project() function. The first |
| 104 |
* quadrature formula is used to compute the right hand side and for numerical |
| 105 |
* quadrature of the mass matrix. |
| 106 |
* |
| 107 |
* The projection of the boundary values first, then eliminating them from the |
| 108 |
* global system of equations is not needed usually. It may be necessary if |
| 109 |
* you want to enforce special restrictions on the boundary values of the |
| 110 |
* projected function, for example in time dependent problems: you may want to |
| 111 |
* project the initial values but need consistency with the boundary values |
| 112 |
* for later times. Since the latter are projected onto the boundary in each |
| 113 |
* time step, it is necessary that we also project the boundary values of the |
| 114 |
* initial values, before projecting them to the whole domain. |
| 115 |
* |
| 116 |
* Obviously, the results of the two schemes for projection are different. |
| 117 |
* Usually, when projecting to the boundary first, the |
| 118 |
* <i>L</i><sup>2</sup>-norm of the difference between original function and |
| 119 |
* projection over the whole domain will be larger (factors of five have been |
| 120 |
* observed) while the <i>L</i><sup>2</sup>-norm of the error integrated over |
| 121 |
* the boundary should of course be less. The reverse should also hold if no |
| 122 |
* projection to the boundary is performed. |
| 123 |
* |
| 124 |
* The selection whether the projection to the boundary first is needed is |
| 125 |
* done with the <tt>project_to_boundary_first</tt> flag passed to the |
| 126 |
* function. If @p false is given, the additional quadrature formula for |
| 127 |
* faces is ignored. |
| 128 |
* |
| 129 |
* You should be aware of the fact that if no projection to the boundary is |
| 130 |
* requested, a function with zero boundary values may not have zero boundary |
| 131 |
* values after projection. There is a flag for this especially important |
| 132 |
* case, which tells the function to enforce zero boundary values on the |
| 133 |
* respective boundary parts. Since enforced zero boundary values could also |
| 134 |
* have been reached through projection, but are more economically obtain |
| 135 |
* using other methods, the @p project_to_boundary_first flag is ignored if |
| 136 |
* the @p enforce_zero_boundary flag is set. |
| 137 |
* |
| 138 |
* The solution of the linear system is presently done using a simple CG |
| 139 |
* method without preconditioning and without multigrid. This is clearly not |
| 140 |
* too efficient, but sufficient in many cases and simple to implement. This |
| 141 |
* detail may change in the future. |
| 142 |
* |
| 143 |
* <li> Creation of right hand side vectors: The create_right_hand_side() |
| 144 |
* function computes the vector $f_i = \int_\Omega f(x) \phi_i(x) dx$. This is |
| 145 |
* the same as what the <tt>MatrixCreator::create_*</tt> functions which take |
| 146 |
* a right hand side do, but without assembling a matrix. |
| 147 |
* |
| 148 |
* <li> Creation of right hand side vectors for point sources: The |
| 149 |
* create_point_source_vector() function computes the vector $F_i = |
| 150 |
* \int_\Omega \delta(x-x_0) \phi_i(x) dx$. |
| 151 |
* |
| 152 |
* <li> Creation of boundary right hand side vectors: The |
| 153 |
* create_boundary_right_hand_side() function computes the vector $f_i = |
| 154 |
* \int_{\partial\Omega} g(x) \phi_i(x) dx$. This is the right hand side |
| 155 |
* contribution of boundary forces when having inhomogeneous Neumann boundary |
| 156 |
* values in Laplace's equation or other second order operators. This function |
| 157 |
* also takes an optional argument denoting over which parts of the boundary |
| 158 |
* the integration shall extend. If the default argument is used, it is |
| 159 |
* applied to all boundaries. |
| 160 |
* |
| 161 |
* <li> Interpolation of boundary values: The |
| 162 |
* MatrixTools::apply_boundary_values() function takes a list of boundary |
| 163 |
* nodes and their values. You can get such a list by interpolation of a |
| 164 |
* boundary function using the interpolate_boundary_values() function. To use |
| 165 |
* it, you have to specify a list of pairs of boundary indicators (of type |
| 166 |
* <tt>types::boundary_id</tt>; see the section in the documentation of the |
| 167 |
* Triangulation class for more details) and the according functions denoting |
| 168 |
* the Dirichlet boundary values of the nodes on boundary faces with this |
| 169 |
* boundary indicator. |
| 170 |
* |
| 171 |
* Usually, all other boundary conditions, such as inhomogeneous Neumann |
| 172 |
* values or mixed boundary conditions are handled in the weak formulation. No |
| 173 |
* attempt is made to include these into the process of matrix and vector |
| 174 |
* assembly therefore. |
| 175 |
* |
| 176 |
* Within this function, boundary values are interpolated, i.e. a node is |
| 177 |
* given the point value of the boundary function. In some cases, it may be |
| 178 |
* necessary to use the L2-projection of the boundary function or any other |
| 179 |
* method. For this purpose we refer to the project_boundary_values() function |
| 180 |
* below. |
| 181 |
* |
| 182 |
* You should be aware that the boundary function may be evaluated at nodes on |
| 183 |
* the interior of faces. These, however, need not be on the true boundary, |
| 184 |
* but rather are on the approximation of the boundary represented by the |
| 185 |
* mapping of the unit cell to the real cell. Since this mapping will in most |
| 186 |
* cases not be the exact one at the face, the boundary function is evaluated |
| 187 |
* at points which are not on the boundary and you should make sure that the |
| 188 |
* returned values are reasonable in some sense anyway. |
| 189 |
* |
| 190 |
* In 1d the situation is a bit different since there faces (i.e. vertices) |
| 191 |
* have no boundary indicator. It is assumed that if the boundary indicator |
| 192 |
* zero is given in the list of boundary functions, the left boundary point is |
| 193 |
* to be interpolated while the right boundary point is associated with the |
| 194 |
* boundary index 1 in the map. The respective boundary functions are then |
| 195 |
* evaluated at the place of the respective boundary point. |
| 196 |
* |
| 197 |
* <li> Projection of boundary values: The project_boundary_values() function |
| 198 |
* acts similar to the interpolate_boundary_values() function, apart from the |
| 199 |
* fact that it does not get the nodal values of boundary nodes by |
| 200 |
* interpolation but rather through the <i>L</i><sup>2</sup>-projection of the |
| 201 |
* trace of the function to the boundary. |
| 202 |
* |
| 203 |
* The projection takes place on all boundary parts with boundary indicators |
| 204 |
* listed in the map (std::map<types::boundary_id, const |
| 205 |
* Function<spacedim,number>*>) of boundary functions. These boundary parts may |
| 206 |
* or may not be continuous. For these boundary parts, the @ref GlossMassMatrix "mass matrix" is |
| 207 |
* assembled using the MatrixTools::create_boundary_mass_matrix() function, as |
| 208 |
* well as the appropriate right hand side. Then the resulting system of |
| 209 |
* equations is solved using a simple CG method (without preconditioning), which |
| 210 |
* is in most cases sufficient for the present purpose. |
| 211 |
* |
| 212 |
* <li> Computing errors: The function integrate_difference() performs the |
| 213 |
* calculation of the error between a given (continuous) reference function |
| 214 |
* and the finite element solution in different norms. The integration is |
| 215 |
* performed using a given quadrature formula and assumes that the given |
| 216 |
* finite element objects equals that used for the computation of the |
| 217 |
* solution. |
| 218 |
* |
| 219 |
* The result is stored in a vector (named @p difference), where each entry |
| 220 |
* equals the given norm of the difference on a cell. The order of entries is |
| 221 |
* the same as a @p cell_iterator takes when started with @p begin_active and |
| 222 |
* promoted with the <tt>++</tt> operator. |
| 223 |
* |
| 224 |
* This data, one number per active cell, can be used to generate graphical |
| 225 |
* output by directly passing it to the DataOut class through the |
| 226 |
* DataOut::add_data_vector function. Alternatively, the global error can be |
| 227 |
* computed using VectorTools::compute_global_error(). Finally, the output per |
| 228 |
* cell from VectorTools::integrate_difference() can be interpolated to the |
| 229 |
* nodal points of a finite element field using the |
| 230 |
* DoFTools::distribute_cell_to_dof_vector function. |
| 231 |
* |
| 232 |
* Presently, there is the possibility to compute the following values from |
| 233 |
* the difference, on each cell: @p mean, @p L1_norm, @p L2_norm, @p |
| 234 |
* Linfty_norm, @p H1_seminorm and @p H1_norm, see VectorTools::NormType. For |
| 235 |
* the mean difference value, the reference function minus the numerical |
| 236 |
* solution is computed, not the other way round. |
| 237 |
* |
| 238 |
* The infinity norm of the difference on a given cell returns the maximum |
| 239 |
* absolute value of the difference at the quadrature points given by the |
| 240 |
* quadrature formula parameter. This will in some cases not be too good an |
| 241 |
* approximation, since for example the Gauss quadrature formulae do not |
| 242 |
* evaluate the difference at the end or corner points of the cells. You may |
| 243 |
* want to choose a quadrature formula with more quadrature points or one with |
| 244 |
* another distribution of the quadrature points in this case. You should also |
| 245 |
* take into account the superconvergence properties of finite elements in |
| 246 |
* some points: for example in 1d, the standard finite element method is a |
| 247 |
* collocation method and should return the exact value at nodal points. |
| 248 |
* Therefore, the trapezoidal rule should always return a vanishing L-infinity |
| 249 |
* error. Conversely, in 2d the maximum L-infinity error should be located at |
| 250 |
* the vertices or at the center of the cell, which would make it plausible to |
| 251 |
* use the Simpson quadrature rule. On the other hand, there may be |
| 252 |
* superconvergence at Gauss integration points. These examples are not |
| 253 |
* intended as a rule of thumb, rather they are thought to illustrate that the |
| 254 |
* use of the wrong quadrature formula may show a significantly wrong result |
| 255 |
* and care should be taken to chose the right formula. |
| 256 |
* |
| 257 |
* The <i>H</i><sup>1</sup> seminorm is the <i>L</i><sup>2</sup> norm of the |
| 258 |
* gradient of the difference. The square of the full <i>H</i><sup>1</sup> |
| 259 |
* norm is the sum of the square of seminorm and the square of the |
| 260 |
* <i>L</i><sup>2</sup> norm. |
| 261 |
* |
| 262 |
* To get the global <i>L<sup>1</sup></i> error, you have to sum up the |
| 263 |
* entries in @p difference, e.g. using Vector::l1_norm() function. For the |
| 264 |
* global <i>L</i><sup>2</sup> difference, you have to sum up the squares of |
| 265 |
* the entries and take the root of the sum, e.g. using Vector::l2_norm(). |
| 266 |
* These two operations represent the <i>l</i><sub>1</sub> and |
| 267 |
* <i>l</i><sub>2</sub> norms of the vectors, but you need not take the |
| 268 |
* absolute value of each entry, since the cellwise norms are already |
| 269 |
* positive. |
| 270 |
* |
| 271 |
* To get the global mean difference, simply sum up the elements as above. To |
| 272 |
* get the $L_\infty$ norm, take the maximum of the vector elements, e.g. |
| 273 |
* using the Vector::linfty_norm() function. |
| 274 |
* |
| 275 |
* For the global <i>H</i><sup>1</sup> norm and seminorm, the same rule |
| 276 |
* applies as for the <i>L</i><sup>2</sup> norm: compute the |
| 277 |
* <i>l</i><sub>2</sub> norm of the cell error vector. |
| 278 |
* |
| 279 |
* Note that, in the codimension one case, if you ask for a norm that requires |
| 280 |
* the computation of a gradient, then the provided function is automatically |
| 281 |
* projected along the curve, and the difference is only computed on the |
| 282 |
* tangential part of the gradient, since no information is available on the |
| 283 |
* normal component of the gradient anyway. |
| 284 |
* </ul> |
| 285 |
* |
| 286 |
* All functions use the finite element given to the DoFHandler object the |
| 287 |
* last time that the degrees of freedom were distributed over the |
| 288 |
* triangulation. Also, if access to an object describing the exact form of |
| 289 |
* the boundary is needed, the pointer stored within the triangulation object |
| 290 |
* is accessed. |
| 291 |
* |
| 292 |
* @note Instantiations for this template are provided for some vector types, |
| 293 |
* in particular <code>Vector<float>, Vector<double>, |
| 294 |
* BlockVector<float>, BlockVector<double></code>; others can be |
| 295 |
* generated in application code (see the section on |
| 296 |
* @ref Instantiations |
| 297 |
* in the manual). |
| 298 |
* |
| 299 |
* @ingroup numerics |
| 300 |
*/ |
| 301 |
namespace VectorTools |
| 302 |
{} |
| 303 |
|
| 304 |
DEAL_II_NAMESPACE_CLOSE |
| 305 |
|
| 306 |
#endif |