Debian Codegraph @

include/deal.II/numerics/vector_tools_integrate_difference.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_integrate_difference_h
16 #define dealii_vector_tools_integrate_difference_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/lac/read_vector.h>
22
23 #include <deal.II/numerics/vector_tools_common.h>
24
25 DEAL_II_NAMESPACE_OPEN
26
27 template <int dim, int spacedim>
28 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
29 class DoFHandler;
30
31 template <int dim, typename Number>
32 class Function;
33 template <int dim, int spacedim>
34 class Mapping;
35 template <int dim>
36 class Quadrature;
37
38 template <int dim, int spacedim>
39 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
40 class Triangulation;
41
42 namespace hp
43 {
44 template <int dim, int spacedim>
45 class MappingCollection;
46 template <int dim>
47 class QCollection;
48 } // namespace hp
49
50
51 namespace VectorTools
52 {
53 /**
54 * @name Evaluation of functions and errors
55 */
56 /** @{ */
57
58 /**
59 * Compute the cellwise error of the finite element solution. Integrate the
60 * difference between a reference function which is given as a continuous
61 * function object, and a finite element function. The result of this
62 * function is the vector @p difference that contains one value per active
63 * cell $K$ of the triangulation. Each of the values of this vector $d$
64 * equals
65 * @f{align*}{
66 * d_K = \| u-u_h \|_X
67 * @f}
68 * where $X$ denotes the norm chosen and $u$ represents the exact solution.
69 *
70 * It is assumed that the number of components of the function @p
71 * exact_solution matches that of the finite element used by @p dof.
72 *
73 * To compute a global error norm of a finite element solution, use
74 * VectorTools::compute_global_error() with the output vector computed with
75 * this function.
76 *
77 * @param[in] mapping The mapping that is used when integrating the
78 * difference $u-u_h$.
79 * @param[in] dof The DoFHandler object that describes the finite element
80 * space in which the solution vector lives.
81 * @param[in] fe_function A vector with nodal values representing the
82 * numerical approximation $u_h$. This vector needs to correspond to the
83 * finite element space represented by @p dof.
84 * @param[in] exact_solution The exact solution that is used to compute the
85 * error.
86 * @param[out] difference The vector of values $d_K$ computed as above.
87 * @param[in] q The quadrature formula used to approximate the integral
88 * shown above. Note that some quadrature formulas are more useful than
89 * others in integrating $u-u_h$. For example, it is known that the $Q_1$
90 * approximation $u_h$ to the exact solution $u$ of a Laplace equation is
91 * particularly accurate (in fact, superconvergent, i.e. accurate to higher
92 * order) at the 4 Gauss points of a cell in 2d (or 8 points in 3d) that
93 * correspond to a QGauss(2) object. Consequently, because a QGauss(2)
94 * formula only evaluates the two solutions at these particular points,
95 * choosing this quadrature formula may indicate an error far smaller than
96 * it actually is.
97 * @param[in] norm The norm $X$ shown above that should be computed. If the
98 * norm is NormType::Hdiv_seminorm, then the finite element on which this
99 * function is called needs to have at least dim vector components, and the
100 * divergence will be computed on the first div components. This works, for
101 * example, on the finite elements used for the mixed Laplace (step-20) and
102 * the Stokes equations (step-22).
103 * @param[in] weight The additional argument @p weight allows to evaluate
104 * weighted norms. The weight function may be scalar, establishing a
105 * spatially variable weight in the domain for all components equally. This
106 * may be used, for instance, to only integrate over parts of the domain.
107 * The weight function may also be vector-valued, with as many components as
108 * the finite element: Then, different components get different weights. A
109 * typical application is when the error with respect to only one or a
110 * subset of the solution variables is to be computed, in which case the
111 * other components would have weight values equal to zero. The
112 * ComponentSelectFunction class is particularly useful for this purpose as
113 * it provides such a "mask" weight. The weight function is expected to be
114 * positive, but negative values are not filtered. The default value of this
115 * function, a null pointer, is interpreted as "no weighting function",
116 * i.e., weight=1 in the whole domain for all vector components uniformly.
117 * @param[in] exponent This value denotes the $p$ used in computing
118 * $L^p$-norms and $W^{1,p}$-norms. The value is ignored if a @p norm other
119 * than NormType::Lp_norm, NormType::W1p_norm, or NormType::W1p_seminorm
120 * is chosen.
121 *
122 *
123 * See the general documentation of this namespace for more information.
124 *
125 * @note If the integration here happens over the cells of a
126 * parallel::distribute::Triangulation object, then this function computes
127 * the vector elements $d_K$ for an output vector with as many cells as
128 * there are active cells of the triangulation object of the current
129 * processor. However, not all active cells are in fact locally owned: some
130 * may be ghost or artificial cells (see
131 * @ref GlossGhostCell "here"
132 * and
133 * @ref GlossArtificialCell "here").
134 * The vector computed will, in the case of a distributed triangulation,
135 * contain zeros for cells that are not locally owned. As a consequence, in
136 * order to compute the <i>global</i> $L_2$ error (for example), the errors
137 * from different processors need to be combined, see
138 * VectorTools::compute_global_error().
139 *
140 * Instantiations for this template are provided for some vector types (see
141 * the general documentation of the namespace), but only for InVectors as in
142 * the documentation of the namespace, OutVector only Vector<double> and
143 * Vector<float>.
144 *
145 * @dealiiConceptRequires{concepts::is_dealii_vector_type<InVector>
146 * &&concepts::is_writable_dealii_vector_type<OutVector>}
147 */
148 template <int dim, typename Number, class OutVector, int spacedim>
149 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<OutVector>)
150 void integrate_difference(const Mapping<dim, spacedim> &mapping,
151 const DoFHandler<dim, spacedim> &dof,
152 const ReadVector<Number> &fe_function,
153 const Function<spacedim, Number> &exact_solution,
154 OutVector &difference,
155 const Quadrature<dim> &q,
156 const NormType &norm,
157 const Function<spacedim, double> *weight = nullptr,
158 const double exponent = 2.);
159
160 /**
161 * Call the integrate_difference() function, see above, with
162 * <tt>mapping=MappingQ@<dim@>(1)</tt>.
163 *
164 * @dealiiConceptRequires{concepts::is_dealii_vector_type<InVector>
165 * &&concepts::is_writable_dealii_vector_type<OutVector>}
166 */
167 template <int dim, typename Number, class OutVector, int spacedim>
168 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<OutVector>)
169 void integrate_difference(const DoFHandler<dim, spacedim> &dof,
170 const ReadVector<Number> &fe_function,
171 const Function<spacedim, Number> &exact_solution,
172 OutVector &difference,
173 const Quadrature<dim> &q,
174 const NormType &norm,
175 const Function<spacedim, double> *weight = nullptr,
176 const double exponent = 2.);
177
178 /**
179 * Same as above for hp.
180 *
181 * @dealiiConceptRequires{concepts::is_dealii_vector_type<InVector>
182 * &&concepts::is_writable_dealii_vector_type<OutVector>}
183 */
184 template <int dim, typename Number, class OutVector, int spacedim>
185 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<OutVector>)
186 void integrate_difference(const hp::MappingCollection<dim, spacedim> &mapping,
187 const DoFHandler<dim, spacedim> &dof,
188 const ReadVector<Number> &fe_function,
189 const Function<spacedim, Number> &exact_solution,
190 OutVector &difference,
191 const hp::QCollection<dim> &q,
192 const NormType &norm,
193 const Function<spacedim, double> *weight = nullptr,
194 const double exponent = 2.);
195
196 /**
197 * Call the integrate_difference() function, see above, with
198 * <tt>mapping=MappingQ@<dim@>(1)</tt>.
199 *
200 * @dealiiConceptRequires{concepts::is_dealii_vector_type<InVector>
201 * &&concepts::is_writable_dealii_vector_type<OutVector>}
202 */
203 template <int dim, typename Number, class OutVector, int spacedim>
204 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<OutVector>)
205 void integrate_difference(const DoFHandler<dim, spacedim> &dof,
206 const ReadVector<Number> &fe_function,
207 const Function<spacedim, Number> &exact_solution,
208 OutVector &difference,
209 const hp::QCollection<dim> &q,
210 const NormType &norm,
211 const Function<spacedim, double> *weight = nullptr,
212 const double exponent = 2.);
213
214 /**
215 * Take a Vector @p cellwise_error of errors on each cell with
216 * <tt>tria.n_active_cells()</tt> entries and return the global
217 * error as given by @p norm.
218 *
219 * The @p cellwise_error vector is typically an output produced by
220 * VectorTools::integrate_difference() and you normally want to supply the
221 * same value for @p norm as you used in VectorTools::integrate_difference().
222 *
223 * If the given Triangulation is a parallel::TriangulationBase, entries
224 * in @p cellwise_error that do not correspond to locally owned cells are
225 * assumed to be 0.0 and a parallel reduction using MPI is done to compute
226 * the global error.
227 *
228 * @param tria The Triangulation with active cells corresponding with the
229 * entries in @p cellwise_error.
230 * @param cellwise_error Vector of errors on each active cell.
231 * @param norm The type of norm to compute.
232 * @param exponent The exponent $p$ to use for $L^p$-norms and
233 * $W^{1,p}$-norms. The value is ignored if a @p norm other
234 * than NormType::Lp_norm, NormType::W1p_norm, or NormType::W1p_seminorm
235 * is chosen.
236 *
237 * @note Instantiated for type Vector<double> and Vector<float>.
238 *
239 * @dealiiConceptRequires{concepts::is_dealii_vector_type<InVector>}
240 */
241 template <int dim, int spacedim, class InVector>
242 DEAL_II_CXX20_REQUIRES(concepts::is_dealii_vector_type<InVector>)
243 double compute_global_error(const Triangulation<dim, spacedim> &tria,
244 const InVector &cellwise_error,
245 const NormType &norm,
246 const double exponent = 2.);
247
248 /** @} */
249 } // namespace VectorTools
250
251 DEAL_II_NAMESPACE_CLOSE
252
253 #endif // dealii_vector_tools_integrate_difference_h