Debian Codegraph @

include/deal.II/numerics/vector_tools_project.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_project_h
16 #define dealii_vector_tools_project_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/template_constraints.h>
22 #include <deal.II/base/vectorization.h>
23
24 #include <functional>
25 #include <memory>
26
27 DEAL_II_NAMESPACE_OPEN
28
29 template <typename number>
30 class AffineConstraints;
31
32 template <int dim, int spacedim>
33 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
34 class DoFHandler;
35
36 template <int dim, typename Number>
37 class Function;
38 template <int dim, int spacedim>
39 class Mapping;
40 template <int dim, typename number, typename VectorizedArrayType>
41 class MatrixFree;
42 template <int dim>
43 class Quadrature;
44 template <int dim>
45 class QGauss;
46 template <typename Number, std::size_t width>
47 class VectorizedArray;
48 namespace hp
49 {
50 template <int dim, int spacedim>
51 class MappingCollection;
52 template <int dim>
53 class QCollection;
54 } // namespace hp
55
56
57 namespace VectorTools
58 {
59 /**
60 * @name Interpolation and projection
61 * @{
62 */
63
64 /**
65 * Compute the projection of @p function to the finite element space. In other
66 * words, given a function $f(\mathbf x)$, the current function computes a
67 * finite element function $f_h(\mathbf x)=\sum_j F_j \varphi_j(\mathbf x)$
68 * characterized by the (output) vector of nodal values $F$ that satisfies
69 * the equation
70 * @f{align*}{
71 * (\varphi_i, f_h)_\Omega = (\varphi_i,f)_\Omega
72 * @f}
73 * for all test functions $\varphi_i$. This requires solving a linear system
74 * involving the @ref GlossMassMatrix "mass matrix" since the equation above is equivalent to
75 * the linear system
76 * @f{align*}{
77 * \sum_j (\varphi_i, \varphi_j)_\Omega F_j = (\varphi_i,f)_\Omega
78 * @f}
79 * which can also be written as $MF = \Phi$ with
80 * $M_{ij} = (\varphi_i, \varphi_j)_\Omega$ and
81 * $\Phi_i = (\varphi_i,f)_\Omega$.
82 *
83 * By default, no boundary values for $f_h$ are needed nor
84 * imposed, but there are optional parameters to this function that allow
85 * imposing either zero boundary values or, in a first step, to project
86 * the boundary values of $f$ onto the finite element space on the boundary
87 * of the mesh in a similar way to above, and then using these values as the
88 * imposed boundary values for $f_h$. The ordering of arguments to this
89 * function is such that you need not give a second quadrature formula (of
90 * type `Quadrature<dim-1>` and used for the computation of the matrix and
91 * right hand side for the projection of boundary values) if you
92 * don't want to project to the boundary first, but that you must if you want
93 * to do so.
94 *
95 * A MatrixFree implementation is used if the following conditions are met:
96 * - @p enforce_zero_boundary is false,
97 * - @p project_to_boundary_first is false,
98 * - the FiniteElement is supported by the MatrixFree class,
99 * - the FiniteElement has less than five components
100 * - the degree of the FiniteElement is less than nine.
101 * - dim==spacedim
102 *
103 * In this case, this function performs numerical quadrature using the given
104 * quadrature formula for integration of the right hand side $\Phi_i$ and
105 * for the mass operator. In the case of hypercube cells, a
106 * QGauss(fe_degree+2) object is used for the mass operator. You should
107 * therefore make sure that the given quadrature formula is sufficiently
108 * accurate for creating the right-hand side.
109 *
110 * Otherwise, only serial Triangulations are supported and the @ref GlossMassMatrix "mass matrix"
111 * is assembled using MatrixTools::create_mass_matrix. The given
112 * quadrature rule is then used for both the matrix and the right-hand side.
113 * You should therefore make sure that the given quadrature formula is also
114 * sufficient for creating the mass matrix. In particular, the degree of the
115 * quadrature formula must be sufficiently high to ensure that the mass
116 * matrix is invertible. For example, if you are using a FE_Q(k) element,
117 * then the integrand of the matrix entries $M_{ij}$ is of polynomial
118 * degree $2k$ in each variable, and you need a Gauss quadrature formula
119 * with $k+1$ points in each coordinate direction to ensure that $M$
120 * is invertible.
121 *
122 * See the general documentation of this namespace for further information.
123 *
124 * In 1d, the default value of the boundary quadrature formula is an invalid
125 * object since integration on the boundary doesn't happen in 1d.
126 *
127 * @param[in] mapping The mapping object to use.
128 * @param[in] dof The DoFHandler the describes the finite element space to
129 * project into and that corresponds to @p vec.
130 * @param[in] constraints Constraints to be used when assembling the mass
131 * matrix, typically needed when you have hanging nodes.
132 * @param[in] quadrature The quadrature formula to be used for assembling the
133 * mass matrix.
134 * @param[in] function The function to project into the finite element space.
135 * @param[out] vec The output vector where the projected function will be
136 * stored in. This vector is required to be already initialized and must not
137 * have ghost elements.
138 * @param[in] enforce_zero_boundary If true, @p vec will have zero boundary
139 * conditions.
140 * @param[in] q_boundary Quadrature rule to be used if @p project_to_boundary_first
141 * is true.
142 * @param[in] project_to_boundary_first If true, perform a projection on the
143 * boundary before projecting the interior of the function.
144 *
145 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
146 */
147 template <int dim, typename VectorType, int spacedim>
148 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
149 void project(
150 const Mapping<dim, spacedim> &mapping,
151 const DoFHandler<dim, spacedim> &dof,
152 const AffineConstraints<typename VectorType::value_type> &constraints,
153 const Quadrature<dim> &quadrature,
154 const Function<spacedim, typename VectorType::value_type> &function,
155 VectorType &vec,
156 const bool enforce_zero_boundary = false,
157 const Quadrature<dim - 1> &q_boundary = (dim > 1 ? QGauss<dim - 1>(2) :
158 Quadrature<dim - 1>()),
159 const bool project_to_boundary_first = false);
160
161 /**
162 * Call the project() function above, with
163 * <tt>mapping=MappingQ@<dim@>(1)</tt>.
164 *
165 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
166 */
167 template <int dim, typename VectorType, int spacedim>
168 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
169 void project(
170 const DoFHandler<dim, spacedim> &dof,
171 const AffineConstraints<typename VectorType::value_type> &constraints,
172 const Quadrature<dim> &quadrature,
173 const Function<spacedim, typename VectorType::value_type> &function,
174 VectorType &vec,
175 const bool enforce_zero_boundary = false,
176 const Quadrature<dim - 1> &q_boundary = (dim > 1 ? QGauss<dim - 1>(2) :
177 Quadrature<dim - 1>()),
178 const bool project_to_boundary_first = false);
179
180 /**
181 * Same as above, but with hp-capabilities.
182 *
183 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
184 */
185 template <int dim, typename VectorType, int spacedim>
186 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
187 void project(
188 const hp::MappingCollection<dim, spacedim> &mapping,
189 const DoFHandler<dim, spacedim> &dof,
190 const AffineConstraints<typename VectorType::value_type> &constraints,
191 const hp::QCollection<dim> &quadrature,
192 const Function<spacedim, typename VectorType::value_type> &function,
193 VectorType &vec,
194 const bool enforce_zero_boundary = false,
195 const hp::QCollection<dim - 1> &q_boundary = hp::QCollection<dim - 1>(
196 dim > 1 ? QGauss<dim - 1>(2) : Quadrature<dim - 1>()),
197 const bool project_to_boundary_first = false);
198
199 /**
200 * Call the project() function above, with a collection of $Q_1$ mapping
201 * objects, i.e., with hp::StaticMappingQ1::mapping_collection.
202 *
203 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
204 */
205 template <int dim, typename VectorType, int spacedim>
206 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
207 void project(
208 const DoFHandler<dim, spacedim> &dof,
209 const AffineConstraints<typename VectorType::value_type> &constraints,
210 const hp::QCollection<dim> &quadrature,
211 const Function<spacedim, typename VectorType::value_type> &function,
212 VectorType &vec,
213 const bool enforce_zero_boundary = false,
214 const hp::QCollection<dim - 1> &q_boundary = hp::QCollection<dim - 1>(
215 dim > 1 ? QGauss<dim - 1>(2) : Quadrature<dim - 1>()),
216 const bool project_to_boundary_first = false);
217
218 /**
219 * The same as above for projection of scalar-valued quadrature data.
220 * The user provided function should return a value at the quadrature point
221 * based on the cell iterator and quadrature number and of course should be
222 * consistent with the provided @p quadrature object, which will be used
223 * to assemble the right-hand-side.
224 *
225 * This function can be used with lambdas:
226 * @code
227 * VectorTools::project
228 * (mapping,
229 * dof_handler,
230 * constraints,
231 * quadrature_formula,
232 * [&] (const typename DoFHandler<dim>::active_cell_iterator & cell,
233 * const unsigned int q) -> double
234 * {
235 * return qp_data.get_data(cell)[q]->density;
236 * },
237 * field);
238 * @endcode
239 * where <code>qp_data</code> is a CellDataStorage object, which stores
240 * quadrature point data.
241 *
242 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
243 */
244 template <int dim, typename VectorType, int spacedim>
245 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
246 void project(
247 const Mapping<dim, spacedim> &mapping,
248 const DoFHandler<dim, spacedim> &dof,
249 const AffineConstraints<typename VectorType::value_type> &constraints,
250 const Quadrature<dim> &quadrature,
251 const std::function<typename VectorType::value_type(
252 const typename DoFHandler<dim, spacedim>::active_cell_iterator &,
253 const unsigned int)> &func,
254 VectorType &vec_result);
255
256 /**
257 * The same as above for projection of scalar-valued MatrixFree quadrature
258 * data.
259 * The user provided function @p func should return a VectorizedArray value
260 * at the quadrature point based on the cell number and quadrature number and
261 * should be consistent with the @p n_q_points_1d.
262 *
263 * This function can be used with lambdas:
264 * @code
265 * VectorTools::project
266 * (matrix_free_data,
267 * constraints,
268 * 3,
269 * [&] (const unsigned int cell,
270 * const unsigned int q) -> VectorizedArray<double>
271 * {
272 * return qp_data(cell,q);
273 * },
274 * field);
275 * @endcode
276 * where <code>qp_data</code> is a an object of type Table<2,
277 * VectorizedArray<double> >, which stores quadrature point data.
278 *
279 * @p fe_component allow to additionally specify which component of @p data
280 * to use in case it was constructed with an <code>std::vector<const
281 * DoFHandler<dim>*></code>. It will be used internally in constructor of
282 * FEEvaluation object.
283 *
284 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
285 */
286 template <int dim, typename VectorType>
287 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
288 void project(
289 std::shared_ptr<
290 const MatrixFree<dim,
291 typename VectorType::value_type,
292 VectorizedArray<typename VectorType::value_type>>> data,
293 const AffineConstraints<typename VectorType::value_type> &constraints,
294 const unsigned int n_q_points_1d,
295 const std::function<VectorizedArray<typename VectorType::value_type>(
296 const unsigned int,
297 const unsigned int)> &func,
298 VectorType &vec_result,
299 const unsigned int fe_component = 0);
300
301 /**
302 * Same as above but for <code>n_q_points_1d =
303 * matrix_free.get_dof_handler().get_fe().degree+1</code>.
304 *
305 * @dealiiConceptRequires{concepts::is_writable_dealii_vector_type<VectorType>}
306 */
307 template <int dim, typename VectorType>
308 DEAL_II_CXX20_REQUIRES(concepts::is_writable_dealii_vector_type<VectorType>)
309 void project(
310 std::shared_ptr<
311 const MatrixFree<dim,
312 typename VectorType::value_type,
313 VectorizedArray<typename VectorType::value_type>>> data,
314 const AffineConstraints<typename VectorType::value_type> &constraints,
315 const std::function<VectorizedArray<typename VectorType::value_type>(
316 const unsigned int,
317 const unsigned int)> &func,
318 VectorType &vec_result,
319 const unsigned int fe_component = 0);
320
321 /** @} */
322
323 } // namespace VectorTools
324
325 DEAL_II_NAMESPACE_CLOSE
326
327 #endif // dealii_vector_tools_project_h