Debian Codegraph @

include/deal.II/numerics/vector_tools.h

raw
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&lt;float&gt;, Vector&lt;double&gt;,
294 * BlockVector&lt;float&gt;, BlockVector&lt;double&gt;</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