Debian Codegraph @

include/deal.II/fe/fe_values_base.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2023 - 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_fe_values_base_h
16 #define dealii_fe_values_base_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/derivative_form.h>
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/exceptions.h>
24 #include <deal.II/base/point.h>
25 #include <deal.II/base/quadrature.h>
26 #include <deal.II/base/std_cxx20/iota_view.h>
27 #include <deal.II/base/symmetric_tensor.h>
28
29 #include <deal.II/dofs/dof_accessor.h>
30 #include <deal.II/dofs/dof_handler.h>
31
32 #include <deal.II/fe/fe.h>
33 #include <deal.II/fe/fe_update_flags.h>
34 #include <deal.II/fe/fe_values_extractors.h>
35 #include <deal.II/fe/fe_values_views.h>
36 #include <deal.II/fe/mapping.h>
37 #include <deal.II/fe/mapping_related_data.h>
38
39 #include <deal.II/grid/tria.h>
40 #include <deal.II/grid/tria_iterator.h>
41
42 #include <deal.II/hp/q_collection.h>
43
44 #include <deal.II/lac/read_vector.h>
45
46 #include <boost/signals2/connection.hpp>
47
48 #include <algorithm>
49 #include <memory>
50 #include <optional>
51 #include <type_traits>
52 #include <variant>
53
54 DEAL_II_NAMESPACE_OPEN
55
56 /**
57 * FEValues, FEFaceValues and FESubfaceValues objects are interfaces to finite
58 * element and mapping classes on the one hand side, to cells and quadrature
59 * rules on the other side. They allow to evaluate values or derivatives of
60 * shape functions at the quadrature points of a quadrature formula when
61 * projected by a mapping from the unit cell onto a cell in real space. The
62 * reason for this abstraction is possible optimization: Depending on the type
63 * of finite element and mapping, some values can be computed once on the unit
64 * cell. Others must be computed on each cell, but maybe computation of
65 * several values at the same time offers ways for optimization. Since this
66 * interplay may be complex and depends on the actual finite element, it
67 * cannot be left to the applications programmer.
68 *
69 * FEValues, FEFaceValues and FESubfaceValues provide only data handling:
70 * computations are left to objects of type Mapping and FiniteElement. These
71 * provide functions <tt>get_*_data</tt> and <tt>fill_*_values</tt> which are
72 * called by the constructor and <tt>reinit</tt> functions of
73 * <tt>FEValues*</tt>, respectively.
74 *
75 * <h3>General usage</h3>
76 *
77 * Usually, an object of <tt>FEValues*</tt> is used in integration loops over
78 * all cells of a triangulation (or faces of cells). To take full advantage of
79 * the optimization features, it should be constructed before the loop so that
80 * information that does not depend on the location and shape of cells can be
81 * computed once and for all (this includes, for example, the values of shape
82 * functions at quadrature points for the most common elements: we can
83 * evaluate them on the unit cell and they will be the same when mapped to the
84 * real cell). Then, in the loop over all cells, it must be re-initialized for
85 * each grid cell to compute that part of the information that changes
86 * depending on the actual cell (for example, the gradient of shape functions
87 * equals the gradient on the unit cell -- which can be computed once and for
88 * all -- times the Jacobian matrix of the mapping between unit and real cell,
89 * which needs to be recomputed for each cell).
90 *
91 * A typical piece of code, adding up local contributions to the Laplace
92 * matrix looks like this:
93 *
94 * @code
95 * FEValues values (mapping, finite_element, quadrature, flags);
96 * for (const auto &cell : dof_handler.active_cell_iterators())
97 * {
98 * values.reinit(cell);
99 * for (unsigned int q=0; q<quadrature.size(); ++q)
100 * for (unsigned int i=0; i<finite_element.n_dofs_per_cell(); ++i)
101 * for (unsigned int j=0; j<finite_element.n_dofs_per_cell(); ++j)
102 * A(i,j) += fe_values.shape_value(i,q) *
103 * fe_values.shape_value(j,q) *
104 * fe_values.JxW(q);
105 * ...
106 * }
107 * @endcode
108 *
109 * The individual functions used here are described below. Note that by
110 * design, the order of quadrature points used inside the FEValues object is
111 * the same as defined by the quadrature formula passed to the constructor of
112 * the FEValues object above.
113 *
114 * <h3>Member functions</h3>
115 *
116 * The functions of this class fall into different categories:
117 * <ul>
118 * <li> shape_value(), shape_grad(), etc: return one of the values of this
119 * object at a time. These functions are inlined, so this is the suggested
120 * access to all finite element values. There should be no loss in performance
121 * with an optimizing compiler. If the finite element is vector valued, then
122 * these functions return the only non-zero component of the requested shape
123 * function. However, some finite elements have shape functions that have more
124 * than one non-zero component (we call them non-"primitive"), and in this
125 * case this set of functions will throw an exception since they cannot
126 * generate a useful result. Rather, use the next set of functions.
127 *
128 * <li> shape_value_component(), shape_grad_component(), etc: This is the same
129 * set of functions as above, except that for vector valued finite elements
130 * they return only one vector component. This is useful for elements of which
131 * shape functions have more than one non-zero component, since then the above
132 * functions cannot be used, and you have to walk over all (or only the
133 * non-zero) components of the shape function using this set of functions.
134 *
135 * <li> get_function_values(), get_function_gradients(), etc.: Compute a
136 * finite element function or its derivative in quadrature points.
137 *
138 * <li> reinit: initialize the FEValues object for a certain cell. This
139 * function is not in the present class but only in the derived classes and
140 * has a variable call syntax. See the docs for the derived classes for more
141 * information.
142 * </ul>
143 *
144 *
145 * <h3>Internals about the implementation</h3>
146 *
147 * The mechanisms by which this class work are discussed on the page on
148 * @ref UpdateFlags "Update flags"
149 * and about the
150 * @ref FE_vs_Mapping_vs_FEValues "How Mapping, FiniteElement, and FEValues work together".
151 *
152 *
153 * @ingroup feaccess
154 */
155 template <int dim, int spacedim>
156 class FEValuesBase : public EnableObserverPointer
157 {
158 public:
159 /**
160 * Dimension in which this object operates.
161 */
162 static constexpr unsigned int dimension = dim;
163
164 /**
165 * Dimension of the space in which this object operates.
166 */
167 static constexpr unsigned int space_dimension = spacedim;
168
169 /**
170 * Number of quadrature points of the current object. Its value is
171 * initialized by the value of max_n_quadrature_points and is updated,
172 * e.g., if FEFaceValues::reinit() is called for a new cell/face.
173 *
174 * @note The default value equals to the value of max_n_quadrature_points.
175 */
176 const unsigned int n_quadrature_points;
177
178 /**
179 * Maximum number of quadrature points. This value might be different from
180 * n_quadrature_points, e.g., if a QCollection with different face quadrature
181 * rules has been passed to initialize FEFaceValues.
182 *
183 * This is mostly useful to initialize arrays to allocate the maximum amount
184 * of memory that may be used when re-sizing later on to a the current
185 * number of quadrature points given by n_quadrature_points.
186 */
187 const unsigned int max_n_quadrature_points;
188
189 /**
190 * Number of shape functions per cell. If we use this base class to evaluate
191 * a finite element on faces of cells, this is still the number of degrees
192 * of freedom per cell, not per face.
193 */
194 const unsigned int dofs_per_cell;
195
196
197 /**
198 * Constructor. Set up the array sizes with <tt>n_q_points</tt> quadrature
199 * points, <tt>dofs_per_cell</tt> trial functions per cell and with the
200 * given pattern to update the fields when the <tt>reinit</tt> function of
201 * the derived classes is called. The fields themselves are not set up, this
202 * must happen in the constructor of the derived class.
203 */
204 FEValuesBase(const unsigned int n_q_points,
205 const unsigned int dofs_per_cell,
206 const UpdateFlags update_flags,
207 const Mapping<dim, spacedim> &mapping,
208 const FiniteElement<dim, spacedim> &fe);
209
210 /**
211 * The copy assignment is deleted since objects of this class are not
212 * copyable.
213 */
214 FEValuesBase &
215 operator=(const FEValuesBase &) = delete;
216
217 /**
218 * The copy constructor is deleted since objects of this class are not
219 * copyable.
220 */
221 FEValuesBase(const FEValuesBase &) = delete;
222
223 /**
224 * Destructor.
225 */
226 virtual ~FEValuesBase() override;
227
228 /**
229 * Explicitly allow to check for cell similarity.
230 * The detection of simple geometries with CellSimilarity is sensitive to the
231 * first cell detected. When using multiple threads, each thread might get a
232 * thread local copy of the FEValues object that is initialized to the first
233 * cell the thread sees. As this cell might be different between runs and
234 * number of threads used, this slight deviation leads to difference in
235 * roundoff errors that propagate through the program. Therefore, deal.II
236 * disables the CellSimilarity check by default in programs that use more than
237 * one thread. This function can be used to disable this behavior: When
238 * called, FEValues objects will always do the similarity check, even in cases
239 * where the program uses multiple threads. This substantially accelerates the
240 * operations of FEValues because many operations can be avoided if a cell is,
241 * for example, just a translation of the previous cell. On the other hand,
242 * you might get results that differ by an amount proportional to round-off
243 * between the case of using or not using cell similarity information, and
244 * because the order of cells assigned to individual threads may differ from
245 * run to run, when you call this function you may end up with results that
246 * differ by round-off between runs of the same program.
247 */
248 void
249 always_allow_check_for_cell_similarity(const bool allow);
250
251 /// @name Access to shape function values
252 ///
253 /// These fields are filled by the finite element.
254 /** @{ */
255
256 /**
257 * Value of a shape function at a quadrature point on the cell, face or
258 * subface selected the last time the <tt>reinit</tt> function of the
259 * derived class was called.
260 *
261 * If the shape function is vector-valued, then this returns the only
262 * non-zero component. If the shape function has more than one non-zero
263 * component (i.e. it is not primitive), then throw an exception of type
264 * ExcShapeFunctionNotPrimitive. In that case, use the
265 * shape_value_component() function.
266 *
267 * @param i Number of the shape function $\varphi_i$ to be evaluated. Note
268 * that this number runs from zero to dofs_per_cell, even in the case of an
269 * FEFaceValues or FESubfaceValues object.
270 *
271 * @param q_point Number of the quadrature point at which function is to be
272 * evaluated
273 *
274 * @dealiiRequiresUpdateFlags{update_values}
275 */
276 const double &
277 shape_value(const unsigned int i, const unsigned int q_point) const;
278
279 /**
280 * Compute one vector component of the value of a shape function at a
281 * quadrature point. If the finite element is scalar, then only component
282 * zero is allowed and the return value equals that of the shape_value()
283 * function. If the finite element is vector valued but all shape functions
284 * are primitive (i.e. they are non-zero in only one component), then the
285 * value returned by shape_value() equals that of this function for exactly
286 * one component. This function is therefore only of greater interest if the
287 * shape function is not primitive, but then it is necessary since the other
288 * function cannot be used.
289 *
290 * @param i Number of the shape function $\varphi_i$ to be evaluated.
291 *
292 * @param q_point Number of the quadrature point at which function is to be
293 * evaluated.
294 *
295 * @param component vector component to be evaluated.
296 *
297 * @dealiiRequiresUpdateFlags{update_values}
298 */
299 double
300 shape_value_component(const unsigned int i,
301 const unsigned int q_point,
302 const unsigned int component) const;
303
304 /**
305 * Compute the gradient of the <tt>i</tt>th shape function at the
306 * <tt>quadrature_point</tt>th quadrature point with respect to real cell
307 * coordinates. If you want to get the derivative in one of the coordinate
308 * directions, use the appropriate function of the Tensor class to extract
309 * one component of the Tensor returned by this function. Since only a
310 * reference to the gradient's value is returned, there should be no major
311 * performance drawback.
312 *
313 * If the shape function is vector-valued, then this returns the only
314 * non-zero component. If the shape function has more than one non-zero
315 * component (i.e. it is not primitive), then it will throw an exception of
316 * type ExcShapeFunctionNotPrimitive. In that case, use the
317 * shape_grad_component() function.
318 *
319 * The same holds for the arguments of this function as for the
320 * shape_value() function.
321 *
322 * @param i Number of the shape function $\varphi_i$ to be evaluated.
323 *
324 * @param q_point Number of the quadrature point at which function
325 * is to be evaluated.
326 *
327 * @dealiiRequiresUpdateFlags{update_gradients}
328 */
329 const Tensor<1, spacedim> &
330 shape_grad(const unsigned int i, const unsigned int q_point) const;
331
332 /**
333 * Return one vector component of the gradient of a shape function at a
334 * quadrature point. If the finite element is scalar, then only component
335 * zero is allowed and the return value equals that of the shape_grad()
336 * function. If the finite element is vector valued but all shape functions
337 * are primitive (i.e. they are non-zero in only one component), then the
338 * value returned by shape_grad() equals that of this function for exactly
339 * one component. This function is therefore only of greater interest if the
340 * shape function is not primitive, but then it is necessary since the other
341 * function cannot be used.
342 *
343 * The same holds for the arguments of this function as for the
344 * shape_value_component() function.
345 *
346 * @dealiiRequiresUpdateFlags{update_gradients}
347 */
348 Tensor<1, spacedim>
349 shape_grad_component(const unsigned int i,
350 const unsigned int q_point,
351 const unsigned int component) const;
352
353 /**
354 * Second derivatives of the <tt>i</tt>th shape function at the
355 * <tt>q_point</tt>th quadrature point with respect to real cell
356 * coordinates. If you want to get the derivatives in one of the coordinate
357 * directions, use the appropriate function of the Tensor class to extract
358 * one component. Since only a reference to the hessian values is returned,
359 * there should be no major performance drawback.
360 *
361 * If the shape function is vector-valued, then this returns the only
362 * non-zero component. If the shape function has more than one non-zero
363 * component (i.e. it is not primitive), then throw an exception of type
364 * ExcShapeFunctionNotPrimitive. In that case, use the
365 * shape_hessian_component() function.
366 *
367 * The same holds for the arguments of this function as for the
368 * shape_value() function.
369 *
370 * @dealiiRequiresUpdateFlags{update_hessians}
371 */
372 const Tensor<2, spacedim> &
373 shape_hessian(const unsigned int i, const unsigned int q_point) const;
374
375 /**
376 * Return one vector component of the hessian of a shape function at a
377 * quadrature point. If the finite element is scalar, then only component
378 * zero is allowed and the return value equals that of the shape_hessian()
379 * function. If the finite element is vector valued but all shape functions
380 * are primitive (i.e. they are non-zero in only one component), then the
381 * value returned by shape_hessian() equals that of this function for
382 * exactly one component. This function is therefore only of greater
383 * interest if the shape function is not primitive, but then it is necessary
384 * since the other function cannot be used.
385 *
386 * The same holds for the arguments of this function as for the
387 * shape_value_component() function.
388 *
389 * @dealiiRequiresUpdateFlags{update_hessians}
390 */
391 Tensor<2, spacedim>
392 shape_hessian_component(const unsigned int i,
393 const unsigned int q_point,
394 const unsigned int component) const;
395
396 /**
397 * Third derivatives of the <tt>i</tt>th shape function at the
398 * <tt>q_point</tt>th quadrature point with respect to real cell
399 * coordinates. If you want to get the 3rd derivatives in one of the
400 * coordinate directions, use the appropriate function of the Tensor class
401 * to extract one component. Since only a reference to the 3rd derivative
402 * values is returned, there should be no major performance drawback.
403 *
404 * If the shape function is vector-valued, then this returns the only
405 * non-zero component. If the shape function has more than one non-zero
406 * component (i.e. it is not primitive), then throw an exception of type
407 * ExcShapeFunctionNotPrimitive. In that case, use the
408 * shape_3rdderivative_component() function.
409 *
410 * The same holds for the arguments of this function as for the
411 * shape_value() function.
412 *
413 * @dealiiRequiresUpdateFlags{update_3rd_derivatives}
414 */
415 const Tensor<3, spacedim> &
416 shape_3rd_derivative(const unsigned int i, const unsigned int q_point) const;
417
418 /**
419 * Return one vector component of the third derivative of a shape function
420 * at a quadrature point. If the finite element is scalar, then only
421 * component zero is allowed and the return value equals that of the
422 * shape_3rdderivative() function. If the finite element is vector valued
423 * but all shape functions are primitive (i.e. they are non-zero in only one
424 * component), then the value returned by shape_3rdderivative() equals that
425 * of this function for exactly one component. This function is therefore
426 * only of greater interest if the shape function is not primitive, but then
427 * it is necessary since the other function cannot be used.
428 *
429 * The same holds for the arguments of this function as for the
430 * shape_value_component() function.
431 *
432 * @dealiiRequiresUpdateFlags{update_3rd_derivatives}
433 */
434 Tensor<3, spacedim>
435 shape_3rd_derivative_component(const unsigned int i,
436 const unsigned int q_point,
437 const unsigned int component) const;
438
439 /** @} */
440 /// @name Access to values of global finite element fields
441 /** @{ */
442
443 /**
444 * Return the values of a finite element function at the quadrature points
445 * of the current cell, face, or subface (selected the last time the reinit()
446 * function was called). That is, if the first argument @p fe_function is a
447 * vector of nodal values of a finite element function $u_h(\mathbf x)$
448 * defined on a DoFHandler object, then the output vector (the second
449 * argument,
450 * @p values) is the vector of values $u_h(\mathbf x_q^K)$ where $x_q^K$ are
451 * the quadrature points on the current cell $K$.
452 * This function is first discussed in the Results
453 * section of step-4, and the related get_function_gradients() function
454 * is also used in step-15 along with numerous other
455 * tutorial programs.
456 *
457 * If the current cell is not active (i.e., it has children), then the finite
458 * element function is, strictly speaking, defined by shape functions
459 * that live on these child cells. Rather than evaluating the shape functions
460 * on the child cells, with the quadrature points defined on the current
461 * cell, this function first interpolates the finite element function to shape
462 * functions defined on the current cell, and then evaluates this interpolated
463 * function.
464 *
465 * This function may only be used if the finite element in use is a scalar
466 * one, i.e. has only one vector component. To get values of multi-component
467 * elements, there is another get_function_values() below,
468 * returning a vector of vectors of results.
469 *
470 * @param[in] fe_function A vector of values that describes (globally) the
471 * finite element function that this function should evaluate at the
472 * quadrature points of the current cell.
473 *
474 * @param[out] values The values of the function specified by fe_function at
475 * the quadrature points of the current cell. The object is assume to
476 * already have the correct size. The data type stored by this output vector
477 * must be what you get when you multiply the values of shape function times
478 * the type used to store the values of the unknowns $U_j$ of your finite
479 * element vector $U$ (represented by the @p fe_function argument). This
480 * happens to be equal to the type of the elements of the solution vector.
481 *
482 * @post <code>values[q]</code> will contain the value of the field
483 * described by fe_function at the $q$th quadrature point.
484 *
485 * @dealiiRequiresUpdateFlags{update_values}
486 */
487 template <typename Number>
488 void
489 get_function_values(const ReadVector<Number> &fe_function,
490 std::vector<Number> &values) const;
491
492 /**
493 * This function does the same as the other get_function_values(), but
494 * applied to multi-component (vector-valued) elements. The meaning of the
495 * arguments is as explained there.
496 *
497 * @post <code>values[q]</code> is a vector of values of the field described
498 * by fe_function at the $q$th quadrature point. The size of the vector
499 * accessed by <code>values[q]</code> equals the number of components of the
500 * finite element, i.e. <code>values[q](c)</code> returns the value of the
501 * $c$th vector component at the $q$th quadrature point.
502 *
503 * @dealiiRequiresUpdateFlags{update_values}
504 */
505 template <typename Number>
506 void
507 get_function_values(const ReadVector<Number> &fe_function,
508 std::vector<Vector<Number>> &values) const;
509
510 /**
511 * Generate function values from an arbitrary vector. This function
512 * does in essence the same as the first function of this name above,
513 * except that it does not make the assumption that the input vector
514 * corresponds to a DoFHandler that describes the unknowns of a finite
515 * element field (and for which we would then assume that
516 * `fe_function.size() == dof_handler.n_dofs()`). Rather, the nodal
517 * values corresponding to the current cell are elements of an otherwise
518 * arbitrary vector, and these elements are indexed by the second
519 * argument to this function. What the rest of the `fe_function` input
520 * argument corresponds to is of no consequence to this function.
521 *
522 * Given this, the function above corresponds to passing `fe_function`
523 * as first argument to the current function, and using the
524 * `local_dof_indices` array that results from the following call as
525 * second argument to the current function:
526 * @code
527 * cell->get_dof_indices (local_dof_indices);
528 * @endcode
529 * (See DoFCellAccessor::get_dof_indices() for more information.)
530 *
531 * Likewise, the function above is equivalent to calling
532 * @code
533 * cell->get_dof_values (fe_function, local_dof_values);
534 * @endcode
535 * and then calling the current function with `local_dof_values` as
536 * first argument, and an array with indices `{0,...,fe.dofs_per_cell-1}`
537 * as second argument.
538 *
539 * The point of the current function is that one sometimes wants to
540 * evaluate finite element functions at quadrature points with nodal
541 * values that are not stored in a global vector -- for example, one could
542 * modify these local values first, such as by applying a limiter
543 * or by ensuring that all nodal values are positive, before evaluating
544 * the finite element field that corresponds to these local values on the
545 * current cell. Another application is where one wants to postprocess
546 * the solution on a cell into a different finite element space on every
547 * cell, without actually creating a corresponding DoFHandler -- in that
548 * case, all one would compute is a local representation of that
549 * postprocessed function, characterized by its nodal values; this function
550 * then allows the evaluation of that representation at quadrature points.
551 *
552 * @param[in] fe_function A vector of nodal values. This vector can have
553 * an arbitrary size, as long as all elements index by `indices` can
554 * actually be accessed.
555 *
556 * @param[in] indices A vector of indices into `fe_function`. This vector
557 * must have length equal to the number of degrees of freedom on the
558 * current cell, and must identify elements in `fe_function` in the
559 * order in which degrees of freedom are indexed on the reference cell.
560 *
561 * @param[out] values A vector of values of the given finite element field,
562 * at the quadrature points on the current object.
563 *
564 * @dealiiRequiresUpdateFlags{update_values}
565 */
566 template <typename Number>
567 void
568 get_function_values(const ReadVector<Number> &fe_function,
569 const ArrayView<const types::global_dof_index> &indices,
570 std::vector<Number> &values) const;
571
572 /**
573 * Generate vector function values from an arbitrary vector.
574 *
575 * This function corresponds to the previous one, just for the vector-valued
576 * case.
577 *
578 * @dealiiRequiresUpdateFlags{update_values}
579 */
580 template <typename Number>
581 void
582 get_function_values(const ReadVector<Number> &fe_function,
583 const ArrayView<const types::global_dof_index> &indices,
584 std::vector<Vector<Number>> &values) const;
585
586
587 /**
588 * Generate vector function values from an arbitrary vector. This
589 * function is similar to the previous one, but the `indices`
590 * vector may also be a multiple of the number of dofs per
591 * cell. Then, the vectors in <tt>value</tt> should allow for the same
592 * multiple of the components of the finite element.
593 *
594 * Depending on the value of the last argument, the outer vector of
595 * <tt>values</tt> has either the length of the quadrature rule
596 * (<tt>quadrature_points_fastest == false</tt>) or the length of components
597 * to be filled <tt>quadrature_points_fastest == true</tt>. If <tt>p</tt> is
598 * the current quadrature point number and <tt>i</tt> is the vector
599 * component of the solution desired, the access to <tt>values</tt> is
600 * <tt>values[p][i]</tt> if <tt>quadrature_points_fastest == false</tt>, and
601 * <tt>values[i][p]</tt> otherwise.
602 *
603 * Since this function allows for fairly general combinations of argument
604 * sizes, be aware that the checks on the arguments may not detect errors.
605 *
606 * @dealiiRequiresUpdateFlags{update_values}
607 */
608 template <typename Number>
609 void
610 get_function_values(const ReadVector<Number> &fe_function,
611 const ArrayView<const types::global_dof_index> &indices,
612 ArrayView<std::vector<Number>> values,
613 const bool quadrature_points_fastest) const;
614
615 /** @} */
616 /// @name Access to derivatives of global finite element fields
617 /** @{ */
618
619 /**
620 * Return the gradients of a finite element function at the quadrature points
621 * of the current cell, face, or subface (selected the last time the reinit()
622 * function was called). That is, if the first argument @p fe_function is a
623 * vector of nodal values of a finite element function $u_h(\mathbf x)$
624 * defined on a DoFHandler object, then the output vector (the second
625 * argument,
626 * @p values) is the vector of values $\nabla u_h(\mathbf x_q^K)$ where
627 * $x_q^K$ are the quadrature points on the current cell $K$. This function is
628 * first discussed in the Results section of step-4, and it is also used in
629 * step-15 along with numerous other tutorial programs.
630 *
631 * This function may only be used if the finite element in use is a scalar
632 * one, i.e. has only one vector component. There is a corresponding
633 * function of the same name for vector-valued finite elements.
634 *
635 * @param[in] fe_function A vector of values that describes (globally) the
636 * finite element function that this function should evaluate at the
637 * quadrature points of the current cell.
638 *
639 * @param[out] gradients The gradients of the function specified by
640 * fe_function at the quadrature points of the current cell. The gradients
641 * are computed in real space (as opposed to on the unit cell). The object
642 * is assume to already have the correct size. The data type stored by this
643 * output vector must be what you get when you multiply the gradients of
644 * shape function times the type used to store the values of the unknowns
645 * $U_j$ of your finite element vector $U$ (represented by the @p
646 * fe_function argument).
647 *
648 * @post <code>gradients[q]</code> will contain the gradient of the field
649 * described by fe_function at the $q$th quadrature point.
650 * <code>gradients[q][d]</code> represents the derivative in coordinate
651 * direction $d$ at quadrature point $q$.
652 *
653 * @note The actual data type of the input vector may be either a
654 * Vector&lt;T&gt;, BlockVector&lt;T&gt;, or one of the PETSc or Trilinos
655 * vector wrapper classes. It represents a global vector of DoF values
656 * associated with the DoFHandler object with which this FEValues object was
657 * last initialized.
658 *
659 * @dealiiRequiresUpdateFlags{update_gradients}
660 */
661 template <typename Number>
662 void
663 get_function_gradients(
664 const ReadVector<Number> &fe_function,
665 std::vector<Tensor<1, spacedim, Number>> &gradients) const;
666
667 /**
668 * This function does the same as the other get_function_gradients(), but
669 * applied to multi-component (vector-valued) elements. The meaning of the
670 * arguments is as explained there.
671 *
672 * @post <code>gradients[q]</code> is a vector of gradients of the field
673 * described by fe_function at the $q$th quadrature point. The size of the
674 * vector accessed by <code>gradients[q]</code> equals the number of
675 * components of the finite element, i.e. <code>gradients[q][c]</code>
676 * returns the gradient of the $c$th vector component at the $q$th
677 * quadrature point. Consequently, <code>gradients[q][c][d]</code> is the
678 * derivative in coordinate direction $d$ of the $c$th vector component of
679 * the vector field at quadrature point $q$ of the current cell.
680 *
681 * @dealiiRequiresUpdateFlags{update_gradients}
682 */
683 template <typename Number>
684 void
685 get_function_gradients(
686 const ReadVector<Number> &fe_function,
687 std::vector<std::vector<Tensor<1, spacedim, Number>>> &gradients) const;
688
689 /**
690 * This function relates to the first of the get_function_gradients() function
691 * above in the same way as the get_function_values() with similar arguments
692 * relates to the first of the get_function_values() functions. See there for
693 * more information.
694 *
695 * @dealiiRequiresUpdateFlags{update_gradients}
696 */
697 template <typename Number>
698 void
699 get_function_gradients(
700 const ReadVector<Number> &fe_function,
701 const ArrayView<const types::global_dof_index> &indices,
702 std::vector<Tensor<1, spacedim, Number>> &gradients) const;
703
704 /**
705 * This function relates to the first of the get_function_gradients() function
706 * above in the same way as the get_function_values() with similar arguments
707 * relates to the first of the get_function_values() functions. See there for
708 * more information.
709 *
710 * @dealiiRequiresUpdateFlags{update_gradients}
711 */
712 template <typename Number>
713 void
714 get_function_gradients(
715 const ReadVector<Number> &fe_function,
716 const ArrayView<const types::global_dof_index> &indices,
717 ArrayView<std::vector<Tensor<1, spacedim, Number>>> gradients,
718 const bool quadrature_points_fastest = false) const;
719
720 /** @} */
721 /// @name Access to second derivatives
722 ///
723 /// Hessian matrices and Laplacians of global finite element fields
724 /** @{ */
725
726 /**
727 * Compute the tensor of second derivatives of a finite element at the
728 * quadrature points of a cell. This function is the equivalent of the
729 * corresponding get_function_values() function (see there for more
730 * information) but evaluates the finite element field's second derivatives
731 * instead of its value.
732 *
733 * This function may only be used if the finite element in use is a scalar
734 * one, i.e. has only one vector component. There is a corresponding
735 * function of the same name for vector-valued finite elements.
736 *
737 * @param[in] fe_function A vector of values that describes (globally) the
738 * finite element function that this function should evaluate at the
739 * quadrature points of the current cell.
740 *
741 * @param[out] hessians The Hessians of the function specified by
742 * fe_function at the quadrature points of the current cell. The Hessians
743 * are computed in real space (as opposed to on the unit cell). The object
744 * is assume to already have the correct size. The data type stored by this
745 * output vector must be what you get when you multiply the Hessians of
746 * shape function times the type used to store the values of the unknowns
747 * $U_j$ of your finite element vector $U$ (represented by the @p
748 * fe_function argument).
749 *
750 * @post <code>hessians[q]</code> will contain the Hessian of the field
751 * described by fe_function at the $q$th quadrature point.
752 * <code>hessians[q][i][j]</code> represents the $(i,j)$th component of the
753 * matrix of second derivatives at quadrature point $q$.
754 *
755 * @note The actual data type of the input vector may be either a
756 * Vector&lt;T&gt;, BlockVector&lt;T&gt;, or one of the PETSc or Trilinos
757 * vector wrapper classes. It represents a global vector of DoF values
758 * associated with the DoFHandler object with which this FEValues object was
759 * last initialized.
760 *
761 * @dealiiRequiresUpdateFlags{update_hessians}
762 */
763 template <typename Number>
764 void
765 get_function_hessians(
766 const ReadVector<Number> &fe_function,
767 std::vector<Tensor<2, spacedim, Number>> &hessians) const;
768
769 /**
770 * This function does the same as the other get_function_hessians(), but
771 * applied to multi-component (vector-valued) elements. The meaning of the
772 * arguments is as explained there.
773 *
774 * @post <code>hessians[q]</code> is a vector of Hessians of the field
775 * described by fe_function at the $q$th quadrature point. The size of the
776 * vector accessed by <code>hessians[q]</code> equals the number of
777 * components of the finite element, i.e. <code>hessians[q][c]</code>
778 * returns the Hessian of the $c$th vector component at the $q$th quadrature
779 * point. Consequently, <code>hessians[q][c][i][j]</code> is the $(i,j)$th
780 * component of the matrix of second derivatives of the $c$th vector
781 * component of the vector field at quadrature point $q$ of the current
782 * cell.
783 *
784 * @dealiiRequiresUpdateFlags{update_hessians}
785 */
786 template <typename Number>
787 void
788 get_function_hessians(
789 const ReadVector<Number> &fe_function,
790 std::vector<std::vector<Tensor<2, spacedim, Number>>> &hessians,
791 const bool quadrature_points_fastest = false) const;
792
793 /**
794 * This function relates to the first of the get_function_hessians() function
795 * above in the same way as the get_function_values() with similar arguments
796 * relates to the first of the get_function_values() functions. See there for
797 * more information.
798 *
799 * @dealiiRequiresUpdateFlags{update_hessians}
800 */
801 template <typename Number>
802 void
803 get_function_hessians(
804 const ReadVector<Number> &fe_function,
805 const ArrayView<const types::global_dof_index> &indices,
806 std::vector<Tensor<2, spacedim, Number>> &hessians) const;
807
808 /**
809 * This function relates to the first of the get_function_hessians() function
810 * above in the same way as the get_function_values() with similar arguments
811 * relates to the first of the get_function_values() functions. See there for
812 * more information.
813 *
814 * @dealiiRequiresUpdateFlags{update_hessians}
815 */
816 template <typename Number>
817 void
818 get_function_hessians(
819 const ReadVector<Number> &fe_function,
820 const ArrayView<const types::global_dof_index> &indices,
821 ArrayView<std::vector<Tensor<2, spacedim, Number>>> hessians,
822 const bool quadrature_points_fastest = false) const;
823
824 /**
825 * Compute the (scalar) Laplacian (i.e. the trace of the tensor of second
826 * derivatives) of a finite element at the quadrature points of a cell. This
827 * function is the equivalent of the corresponding get_function_values()
828 * function (see there for more information) but evaluates the finite
829 * element field's second derivatives instead of its value.
830 *
831 * This function may only be used if the finite element in use is a scalar
832 * one, i.e. has only one vector component. There is a corresponding
833 * function of the same name for vector-valued finite elements.
834 *
835 * @param[in] fe_function A vector of values that describes (globally) the
836 * finite element function that this function should evaluate at the
837 * quadrature points of the current cell.
838 *
839 * @param[out] laplacians The Laplacians of the function specified by
840 * fe_function at the quadrature points of the current cell. The Laplacians
841 * are computed in real space (as opposed to on the unit cell). The object
842 * is assume to already have the correct size. The data type stored by this
843 * output vector must be what you get when you multiply the Laplacians of
844 * shape function times the type used to store the values of the unknowns
845 * $U_j$ of your finite element vector $U$ (represented by the @p
846 * fe_function argument). This happens to be equal to the type of the
847 * elements of the input vector.
848 *
849 * @post <code>laplacians[q]</code> will contain the Laplacian of the field
850 * described by fe_function at the $q$th quadrature point.
851 *
852 * @post For each component of the output vector, there holds
853 * <code>laplacians[q]=trace(hessians[q])</code>, where <tt>hessians</tt>
854 * would be the output of the get_function_hessians() function.
855 *
856 * @note The actual data type of the input vector may be either a
857 * Vector&lt;T&gt;, BlockVector&lt;T&gt;, or one of the PETSc or Trilinos
858 * vector wrapper classes. It represents a global vector of DoF values
859 * associated with the DoFHandler object with which this FEValues object was
860 * last initialized.
861 *
862 * @dealiiRequiresUpdateFlags{update_hessians}
863 */
864 template <typename Number>
865 void
866 get_function_laplacians(const ReadVector<Number> &fe_function,
867 std::vector<Number> &laplacians) const;
868
869 /**
870 * This function does the same as the other get_function_laplacians(), but
871 * applied to multi-component (vector-valued) elements. The meaning of the
872 * arguments is as explained there.
873 *
874 * @post <code>laplacians[q]</code> is a vector of Laplacians of the field
875 * described by fe_function at the $q$th quadrature point. The size of the
876 * vector accessed by <code>laplacians[q]</code> equals the number of
877 * components of the finite element, i.e. <code>laplacians[q][c]</code>
878 * returns the Laplacian of the $c$th vector component at the $q$th
879 * quadrature point.
880 *
881 * @post For each component of the output vector, there holds
882 * <code>laplacians[q][c]=trace(hessians[q][c])</code>, where
883 * <tt>hessians</tt> would be the output of the get_function_hessians()
884 * function.
885 *
886 * @dealiiRequiresUpdateFlags{update_hessians}
887 */
888 template <typename Number>
889 void
890 get_function_laplacians(const ReadVector<Number> &fe_function,
891 std::vector<Vector<Number>> &laplacians) const;
892
893 /**
894 * This function relates to the first of the get_function_laplacians()
895 * function above in the same way as the get_function_values() with similar
896 * arguments relates to the first of the get_function_values() functions. See
897 * there for more information.
898 *
899 * @dealiiRequiresUpdateFlags{update_hessians}
900 */
901 template <typename Number>
902 void
903 get_function_laplacians(
904 const ReadVector<Number> &fe_function,
905 const ArrayView<const types::global_dof_index> &indices,
906 std::vector<Number> &laplacians) const;
907
908 /**
909 * This function relates to the first of the get_function_laplacians()
910 * function above in the same way as the get_function_values() with similar
911 * arguments relates to the first of the get_function_values() functions. See
912 * there for more information.
913 *
914 * @dealiiRequiresUpdateFlags{update_hessians}
915 */
916 template <typename Number>
917 void
918 get_function_laplacians(
919 const ReadVector<Number> &fe_function,
920 const ArrayView<const types::global_dof_index> &indices,
921 std::vector<Vector<Number>> &laplacians) const;
922
923 /**
924 * This function relates to the first of the get_function_laplacians()
925 * function above in the same way as the get_function_values() with similar
926 * arguments relates to the first of the get_function_values() functions. See
927 * there for more information.
928 *
929 * @dealiiRequiresUpdateFlags{update_hessians}
930 */
931 template <typename Number>
932 void
933 get_function_laplacians(
934 const ReadVector<Number> &fe_function,
935 const ArrayView<const types::global_dof_index> &indices,
936 std::vector<std::vector<Number>> &laplacians,
937 const bool quadrature_points_fastest = false) const;
938
939 /** @} */
940 /// @name Access to third derivatives of global finite element fields
941 /** @{ */
942
943 /**
944 * Compute the tensor of third derivatives of a finite element at the
945 * quadrature points of a cell. This function is the equivalent of the
946 * corresponding get_function_values() function (see there for more
947 * information) but evaluates the finite element field's third derivatives
948 * instead of its value.
949 *
950 * This function may only be used if the finite element in use is a scalar
951 * one, i.e. has only one vector component. There is a corresponding
952 * function of the same name for vector-valued finite elements.
953 *
954 * @param[in] fe_function A vector of values that describes (globally) the
955 * finite element function that this function should evaluate at the
956 * quadrature points of the current cell.
957 *
958 * @param[out] third_derivatives The third derivatives of the function
959 * specified by fe_function at the quadrature points of the current cell.
960 * The third derivatives are computed in real space (as opposed to on the
961 * unit cell). The object is assumed to already have the correct size. The
962 * data type stored by this output vector must be what you get when you
963 * multiply the third derivatives of shape function times the type used to
964 * store the values of the unknowns $U_j$ of your finite element vector $U$
965 * (represented by the @p fe_function argument).
966 *
967 * @post <code>third_derivatives[q]</code> will contain the third
968 * derivatives of the field described by fe_function at the $q$th quadrature
969 * point. <code>third_derivatives[q][i][j][k]</code> represents the
970 * $(i,j,k)$th component of the 3rd order tensor of third derivatives at
971 * quadrature point $q$.
972 *
973 * @note The actual data type of the input vector may be either a
974 * Vector&lt;T&gt;, BlockVector&lt;T&gt;, or one of the PETSc or Trilinos
975 * vector wrapper classes. It represents a global vector of DoF values
976 * associated with the DoFHandler object with which this FEValues object was
977 * last initialized.
978 *
979 * @dealiiRequiresUpdateFlags{update_3rd_derivatives}
980 */
981 template <typename Number>
982 void
983 get_function_third_derivatives(
984 const ReadVector<Number> &fe_function,
985 std::vector<Tensor<3, spacedim, Number>> &third_derivatives) const;
986
987 /**
988 * This function does the same as the other
989 * get_function_third_derivatives(), but applied to multi-component
990 * (vector-valued) elements. The meaning of the arguments is as explained
991 * there.
992 *
993 * @post <code>third_derivatives[q]</code> is a vector of third derivatives
994 * of the field described by fe_function at the $q$th quadrature point. The
995 * size of the vector accessed by <code>third_derivatives[q]</code> equals
996 * the number of components of the finite element, i.e.
997 * <code>third_derivatives[q][c]</code> returns the third derivative of the
998 * $c$th vector component at the $q$th quadrature point. Consequently,
999 * <code>third_derivatives[q][c][i][j][k]</code> is the $(i,j,k)$th
1000 * component of the tensor of third derivatives of the $c$th vector
1001 * component of the vector field at quadrature point $q$ of the current
1002 * cell.
1003 *
1004 * @dealiiRequiresUpdateFlags{update_3rd_derivatives}
1005 */
1006 template <typename Number>
1007 void
1008 get_function_third_derivatives(
1009 const ReadVector<Number> &fe_function,
1010 std::vector<std::vector<Tensor<3, spacedim, Number>>> &third_derivatives,
1011 const bool quadrature_points_fastest = false) const;
1012
1013 /**
1014 * This function relates to the first of the get_function_third_derivatives()
1015 * function above in the same way as the get_function_values() with similar
1016 * arguments relates to the first of the get_function_values() functions. See
1017 * there for more information.
1018 *
1019 * @dealiiRequiresUpdateFlags{update_3rd_derivatives}
1020 */
1021 template <typename Number>
1022 void
1023 get_function_third_derivatives(
1024 const ReadVector<Number> &fe_function,
1025 const ArrayView<const types::global_dof_index> &indices,
1026 std::vector<Tensor<3, spacedim, Number>> &third_derivatives) const;
1027
1028 /**
1029 * This function relates to the first of the get_function_third_derivatives()
1030 * function above in the same way as the get_function_values() with similar
1031 * arguments relates to the first of the get_function_values() functions. See
1032 * there for more information.
1033 *
1034 * @dealiiRequiresUpdateFlags{update_3rd_derivatives}
1035 */
1036 template <typename Number>
1037 void
1038 get_function_third_derivatives(
1039 const ReadVector<Number> &fe_function,
1040 const ArrayView<const types::global_dof_index> &indices,
1041 ArrayView<std::vector<Tensor<3, spacedim, Number>>> third_derivatives,
1042 const bool quadrature_points_fastest = false) const;
1043 /** @} */
1044
1045 /// @name Cell degrees of freedom
1046 /** @{ */
1047
1048 /**
1049 * Return an object that can be thought of as an array containing all
1050 * indices from zero (inclusive) to `dofs_per_cell` (exclusive). This allows
1051 * one to write code using range-based `for` loops of the following kind:
1052 * @code
1053 * FEValues<dim> fe_values (...);
1054 * FullMatrix<double> cell_matrix (...);
1055 *
1056 * for (auto &cell : dof_handler.active_cell_iterators())
1057 * {
1058 * cell_matrix = 0;
1059 * fe_values.reinit(cell);
1060 * for (const auto q : fe_values.quadrature_point_indices())
1061 * for (const auto i : fe_values.dof_indices())
1062 * for (const auto j : fe_values.dof_indices())
1063 * cell_matrix(i,j) += ...; // Do something for DoF indices (i,j)
1064 * // at quadrature point q
1065 * }
1066 * @endcode
1067 * Here, we are looping over all degrees of freedom on all cells, with
1068 * `i` and `j` taking on all valid indices for cell degrees of freedom, as
1069 * defined by the finite element passed to `fe_values`.
1070 */
1071 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1072 dof_indices() const;
1073
1074 /**
1075 * Return an object that can be thought of as an array containing all
1076 * indices from @p start_dof_index (inclusive) to `dofs_per_cell` (exclusive).
1077 * This allows one to write code using range-based `for` loops of the
1078 * following kind:
1079 * @code
1080 * FEValues<dim> fe_values (...);
1081 * FullMatrix<double> cell_matrix (...);
1082 *
1083 * for (auto &cell : dof_handler.active_cell_iterators())
1084 * {
1085 * cell_matrix = 0;
1086 * fe_values.reinit(cell);
1087 * for (const auto q : fe_values.quadrature_point_indices())
1088 * for (const auto i : fe_values.dof_indices())
1089 * for (const auto j : fe_values.dof_indices_starting_at(i))
1090 * cell_matrix(i,j) += ...; // Do something for DoF indices (i,j)
1091 * // at quadrature point q
1092 * }
1093 * @endcode
1094 * Here, we are looping over all local degrees of freedom on all cells, with
1095 * `i` taking on all valid indices for cell degrees of freedom, as
1096 * defined by the finite element passed to `fe_values`, and `j` taking
1097 * on a specified subset of `i`'s range, starting at `i` itself and ending at
1098 * the number of cell degrees of freedom. In this way, we can construct the
1099 * upper half and the diagonal of a @ref GlossStiffnessMatrix "stiffness matrix" contribution (assuming it
1100 * is symmetric, and that only one half of it needs to be computed), for
1101 * example.
1102 *
1103 * @note If the @p start_dof_index is equal to the number of DoFs in the cell,
1104 * then the returned index range is empty.
1105 */
1106 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1107 dof_indices_starting_at(const unsigned int start_dof_index) const;
1108
1109 /**
1110 * Return an object that can be thought of as an array containing all
1111 * indices from zero (inclusive) to @p end_dof_index (inclusive). This allows
1112 * one to write code using range-based `for` loops of the following kind:
1113 * @code
1114 * FEValues<dim> fe_values (...);
1115 * FullMatrix<double> cell_matrix (...);
1116 *
1117 * for (auto &cell : dof_handler.active_cell_iterators())
1118 * {
1119 * cell_matrix = 0;
1120 * fe_values.reinit(cell);
1121 * for (const auto q : fe_values.quadrature_point_indices())
1122 * for (const auto i : fe_values.dof_indices())
1123 * for (const auto j : fe_values.dof_indices_ending_at(i))
1124 * cell_matrix(i,j) += ...; // Do something for DoF indices (i,j)
1125 * // at quadrature point q
1126 * }
1127 * @endcode
1128 * Here, we are looping over all local degrees of freedom on all cells, with
1129 * `i` taking on all valid indices for cell degrees of freedom, as
1130 * defined by the finite element passed to `fe_values`, and `j` taking
1131 * on a specified subset of `i`'s range, starting at zero and ending at
1132 * `i` itself. In this way, we can construct the lower half and the
1133 * diagonal of a @ref GlossStiffnessMatrix "stiffness matrix" contribution (assuming it is symmetric, and
1134 * that only one half of it needs to be computed), for example.
1135 *
1136 * @note If the @p end_dof_index is equal to zero, then the returned index
1137 * range is empty.
1138 */
1139 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1140 dof_indices_ending_at(const unsigned int end_dof_index) const;
1141
1142 /** @} */
1143
1144 /// @name Geometry of the cell
1145 /** @{ */
1146
1147 /**
1148 * Return an object that can be thought of as an array containing all
1149 * indices from zero to `n_quadrature_points`. This allows to write code
1150 * using range-based `for` loops of the following kind:
1151 * @code
1152 * FEValues<dim> fe_values (...);
1153 *
1154 * for (auto &cell : dof_handler.active_cell_iterators())
1155 * {
1156 * fe_values.reinit(cell);
1157 * for (const auto q_point : fe_values.quadrature_point_indices())
1158 * ... do something at the quadrature point ...
1159 * }
1160 * @endcode
1161 * Here, we are looping over all quadrature points on all cells, with
1162 * `q_point` taking on all valid indices for quadrature points, as defined
1163 * by the quadrature rule passed to `fe_values`.
1164 *
1165 * @see CPP11
1166 */
1167 std_cxx20::ranges::iota_view<unsigned int, unsigned int>
1168 quadrature_point_indices() const;
1169
1170 /**
1171 * Return the location of the <tt>q_point</tt>th quadrature point in
1172 * real space.
1173 *
1174 * @dealiiRequiresUpdateFlags{update_quadrature_points}
1175 */
1176 const Point<spacedim> &
1177 quadrature_point(const unsigned int q_point) const;
1178
1179 /**
1180 * Return a reference to the vector of quadrature points in real space.
1181 *
1182 * @dealiiRequiresUpdateFlags{update_quadrature_points}
1183 */
1184 const std::vector<Point<spacedim>> &
1185 get_quadrature_points() const;
1186
1187 /**
1188 * Mapped quadrature weight. If this object refers to a volume evaluation
1189 * (i.e. the derived class is of type FEValues), then this is the Jacobi
1190 * determinant times the weight of the <tt>q_point</tt>th unit quadrature
1191 * point.
1192 *
1193 * For surface evaluations (i.e. classes FEFaceValues or FESubfaceValues),
1194 * it is the mapped surface element times the weight of the quadrature
1195 * point.
1196 *
1197 * You can think of the quantity returned by this function as the volume or
1198 * surface element $dx, ds$ in the integral that we implement here by
1199 * quadrature.
1200 *
1201 * @dealiiRequiresUpdateFlags{update_JxW_values}
1202 */
1203 double
1204 JxW(const unsigned int q_point) const;
1205
1206 /**
1207 * Return a reference to the array holding the values returned by JxW().
1208 */
1209 const std::vector<double> &
1210 get_JxW_values() const;
1211
1212 /**
1213 * Return the Jacobian of the transformation at the specified quadrature
1214 * point, i.e. $J_{ij}=dx_i/d\hat x_j$
1215 *
1216 * @dealiiRequiresUpdateFlags{update_jacobians}
1217 */
1218 const DerivativeForm<1, dim, spacedim> &
1219 jacobian(const unsigned int q_point) const;
1220
1221 /**
1222 * Return a reference to the array holding the values returned by
1223 * jacobian().
1224 *
1225 * @dealiiRequiresUpdateFlags{update_jacobians}
1226 */
1227 const std::vector<DerivativeForm<1, dim, spacedim>> &
1228 get_jacobians() const;
1229
1230 /**
1231 * Return the second derivative of the transformation from unit to real
1232 * cell, i.e. the first derivative of the Jacobian, at the specified
1233 * quadrature point, i.e. $G_{ijk}=dJ_{jk}/d\hat x_i$.
1234 *
1235 * @dealiiRequiresUpdateFlags{update_jacobian_grads}
1236 */
1237 const DerivativeForm<2, dim, spacedim> &
1238 jacobian_grad(const unsigned int q_point) const;
1239
1240 /**
1241 * Return a reference to the array holding the values returned by
1242 * jacobian_grads().
1243 *
1244 * @dealiiRequiresUpdateFlags{update_jacobian_grads}
1245 */
1246 const std::vector<DerivativeForm<2, dim, spacedim>> &
1247 get_jacobian_grads() const;
1248
1249 /**
1250 * Return the second derivative of the transformation from unit to real
1251 * cell, i.e. the first derivative of the Jacobian, at the specified
1252 * quadrature point, pushed forward to the real cell coordinates, i.e.
1253 * $G_{ijk}=dJ_{iJ}/d\hat x_K (J_{jJ})^{-1} (J_{kK})^{-1}$.
1254 *
1255 * @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_grads}
1256 */
1257 const Tensor<3, spacedim> &
1258 jacobian_pushed_forward_grad(const unsigned int q_point) const;
1259
1260 /**
1261 * Return a reference to the array holding the values returned by
1262 * jacobian_pushed_forward_grads().
1263 *
1264 * @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_grads}
1265 */
1266 const std::vector<Tensor<3, spacedim>> &
1267 get_jacobian_pushed_forward_grads() const;
1268
1269 /**
1270 * Return the third derivative of the transformation from unit to real cell,
1271 * i.e. the second derivative of the Jacobian, at the specified quadrature
1272 * point, i.e. $G_{ijkl}=\frac{d^2J_{ij}}{d\hat x_k d\hat x_l}$.
1273 *
1274 * @dealiiRequiresUpdateFlags{update_jacobian_2nd_derivatives}
1275 */
1276 const DerivativeForm<3, dim, spacedim> &
1277 jacobian_2nd_derivative(const unsigned int q_point) const;
1278
1279 /**
1280 * Return a reference to the array holding the values returned by
1281 * jacobian_2nd_derivatives().
1282 *
1283 * @dealiiRequiresUpdateFlags{update_jacobian_2nd_derivatives}
1284 */
1285 const std::vector<DerivativeForm<3, dim, spacedim>> &
1286 get_jacobian_2nd_derivatives() const;
1287
1288 /**
1289 * Return the third derivative of the transformation from unit to real cell,
1290 * i.e. the second derivative of the Jacobian, at the specified quadrature
1291 * point, pushed forward to the real cell coordinates, i.e.
1292 * $G_{ijkl}=\frac{d^2J_{iJ}}{d\hat x_K d\hat x_L} (J_{jJ})^{-1}
1293 * (J_{kK})^{-1}(J_{lL})^{-1}$.
1294 *
1295 * @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_2nd_derivatives}
1296 */
1297 const Tensor<4, spacedim> &
1298 jacobian_pushed_forward_2nd_derivative(const unsigned int q_point) const;
1299
1300 /**
1301 * Return a reference to the array holding the values returned by
1302 * jacobian_pushed_forward_2nd_derivatives().
1303 *
1304 * @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_2nd_derivatives}
1305 */
1306 const std::vector<Tensor<4, spacedim>> &
1307 get_jacobian_pushed_forward_2nd_derivatives() const;
1308
1309 /**
1310 * Return the fourth derivative of the transformation from unit to real
1311 * cell, i.e. the third derivative of the Jacobian, at the specified
1312 * quadrature point, i.e. $G_{ijklm}=\frac{d^2J_{ij}}{d\hat x_k d\hat x_l
1313 * d\hat x_m}$.
1314 *
1315 * @dealiiRequiresUpdateFlags{update_jacobian_3rd_derivatives}
1316 */
1317 const DerivativeForm<4, dim, spacedim> &
1318 jacobian_3rd_derivative(const unsigned int q_point) const;
1319
1320 /**
1321 * Return a reference to the array holding the values returned by
1322 * jacobian_3rd_derivatives().
1323 *
1324 * @dealiiRequiresUpdateFlags{update_jacobian_3rd_derivatives}
1325 */
1326 const std::vector<DerivativeForm<4, dim, spacedim>> &
1327 get_jacobian_3rd_derivatives() const;
1328
1329 /**
1330 * Return the fourth derivative of the transformation from unit to real
1331 * cell, i.e. the third derivative of the Jacobian, at the specified
1332 * quadrature point, pushed forward to the real cell coordinates, i.e.
1333 * $G_{ijklm}=\frac{d^3J_{iJ}}{d\hat x_K d\hat x_L d\hat x_M} (J_{jJ})^{-1}
1334 * (J_{kK})^{-1} (J_{lL})^{-1} (J_{mM})^{-1}$.
1335 *
1336 * @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_3rd_derivatives}
1337 */
1338 const Tensor<5, spacedim> &
1339 jacobian_pushed_forward_3rd_derivative(const unsigned int q_point) const;
1340
1341 /**
1342 * Return a reference to the array holding the values returned by
1343 * jacobian_pushed_forward_3rd_derivatives().
1344 *
1345 * @dealiiRequiresUpdateFlags{update_jacobian_pushed_forward_2nd_derivatives}
1346 */
1347 const std::vector<Tensor<5, spacedim>> &
1348 get_jacobian_pushed_forward_3rd_derivatives() const;
1349
1350 /**
1351 * Return the inverse Jacobian of the transformation at the specified
1352 * quadrature point, i.e. $J_{ij}=d\hat x_i/dx_j$
1353 *
1354 * @dealiiRequiresUpdateFlags{update_inverse_jacobians}
1355 */
1356 const DerivativeForm<1, spacedim, dim> &
1357 inverse_jacobian(const unsigned int q_point) const;
1358
1359 /**
1360 * Return a reference to the array holding the values returned by
1361 * inverse_jacobian().
1362 *
1363 * @dealiiRequiresUpdateFlags{update_inverse_jacobians}
1364 */
1365 const std::vector<DerivativeForm<1, spacedim, dim>> &
1366 get_inverse_jacobians() const;
1367
1368 /**
1369 * Return the normal vector at a quadrature point. If you call this
1370 * function for a face (i.e., when using a FEFaceValues or FESubfaceValues
1371 * object), then this function returns the outward normal vector to
1372 * the cell at the <tt>q_point</tt>th quadrature point of the face.
1373 *
1374 * In contrast, if you call this function for a cell of codimension one
1375 * (i.e., when using a `FEValues<dim,spacedim>` object with
1376 * `spacedim>dim`), then this function returns the normal vector to the
1377 * cell -- in other words, an approximation to the normal vector to the
1378 * manifold in which the triangulation is embedded. There are of
1379 * course two normal directions to a manifold in that case, and this
1380 * function returns the "up" direction as induced by the numbering of the
1381 * vertices.
1382 *
1383 * The length of the vector is normalized to one.
1384 *
1385 * @dealiiRequiresUpdateFlags{update_normal_vectors}
1386 */
1387 const Tensor<1, spacedim> &
1388 normal_vector(const unsigned int q_point) const;
1389
1390 /**
1391 * Return the normal vectors at all quadrature points represented by
1392 * this object. See the normal_vector() function for what the normal
1393 * vectors represent.
1394 *
1395 * @dealiiRequiresUpdateFlags{update_normal_vectors}
1396 */
1397 const std::vector<Tensor<1, spacedim>> &
1398 get_normal_vectors() const;
1399
1400 /** @} */
1401
1402 /// @name Extractors Methods to extract individual components
1403 /** @{ */
1404
1405 /**
1406 * Create a view of the current FEValues object that represents a particular
1407 * scalar component of the possibly vector-valued finite element. The
1408 * concept of views is explained in the documentation of the namespace
1409 * FEValuesViews and in particular in the
1410 * @ref vector_valued
1411 * topic.
1412 */
1413 const FEValuesViews::Scalar<dim, spacedim> &
1414 operator[](const FEValuesExtractors::Scalar &scalar) const;
1415
1416 /**
1417 * Create a view of the current FEValues object that represents a set of
1418 * <code>dim</code> scalar components (i.e. a vector) of the vector-valued
1419 * finite element. The concept of views is explained in the documentation of
1420 * the namespace FEValuesViews and in particular in the
1421 * @ref vector_valued
1422 * topic.
1423 */
1424 const FEValuesViews::Vector<dim, spacedim> &
1425 operator[](const FEValuesExtractors::Vector &vector) const;
1426
1427 /**
1428 * Create a view of the current FEValues object that represents a set of
1429 * <code>(dim*dim + dim)/2</code> scalar components (i.e. a symmetric 2nd
1430 * order tensor) of the vector-valued finite element. The concept of views
1431 * is explained in the documentation of the namespace FEValuesViews and in
1432 * particular in the
1433 * @ref vector_valued
1434 * topic.
1435 */
1436 const FEValuesViews::SymmetricTensor<2, dim, spacedim> &
1437 operator[](const FEValuesExtractors::SymmetricTensor<2> &tensor) const;
1438
1439
1440 /**
1441 * Create a view of the current FEValues object that represents a set of
1442 * <code>(dim*dim)</code> scalar components (i.e. a 2nd order tensor) of the
1443 * vector-valued finite element. The concept of views is explained in the
1444 * documentation of the namespace FEValuesViews and in particular in the
1445 * @ref vector_valued
1446 * topic.
1447 */
1448 const FEValuesViews::Tensor<2, dim, spacedim> &
1449 operator[](const FEValuesExtractors::Tensor<2> &tensor) const;
1450
1451 /** @} */
1452
1453 /// @name Access to the raw data
1454 /** @{ */
1455
1456 /**
1457 * Constant reference to the selected mapping object.
1458 */
1459 const Mapping<dim, spacedim> &
1460 get_mapping() const;
1461
1462 /**
1463 * Constant reference to the selected finite element object.
1464 */
1465 const FiniteElement<dim, spacedim> &
1466 get_fe() const;
1467
1468 /**
1469 * Return the update flags set for this object.
1470 */
1471 UpdateFlags
1472 get_update_flags() const;
1473
1474 /**
1475 * Return a triangulation iterator to the current cell.
1476 */
1477 typename Triangulation<dim, spacedim>::cell_iterator
1478 get_cell() const;
1479
1480 /**
1481 * Return the relation of the current cell to the previous cell. This allows
1482 * re-use of some cell data (like local matrices for equations with constant
1483 * coefficients) if the result is <tt>CellSimilarity::translation</tt>.
1484 */
1485 CellSimilarity::Similarity
1486 get_cell_similarity() const;
1487
1488 /**
1489 * Determine an estimate for the memory consumption (in bytes) of this
1490 * object.
1491 */
1492 std::size_t
1493 memory_consumption() const;
1494 /** @} */
1495
1496
1497 /**
1498 * This exception is thrown if FEValuesBase is asked to return the value of
1499 * a field which was not required by the UpdateFlags for this FEValuesBase.
1500 *
1501 * @ingroup Exceptions
1502 */
1503 DeclException1(
1504 ExcAccessToUninitializedField,
1505 std::string,
1506 << "You are requesting information from an FEValues/FEFaceValues/FESubfaceValues "
1507 << "object for which this kind of information has not been computed. What "
1508 << "information these objects compute is determined by the update_* flags you "
1509 << "pass to the constructor. Here, the operation you are attempting requires "
1510 << "the <" << arg1
1511 << "> flag to be set, but it was apparently not specified "
1512 << "upon construction.");
1513
1514 /**
1515 * FEValues::reinit() has not been called for any cell.
1516 *
1517 * @ingroup Exceptions
1518 */
1519 DeclExceptionMsg(ExcNotReinited,
1520 "FEValues object is not reinit'ed to any cell");
1521
1522 /**
1523 * Mismatch between the FEValues FiniteElement and
1524 * cell->get_dof_handler().get_fe()
1525 *
1526 * @ingroup Exceptions
1527 */
1528 DeclExceptionMsg(
1529 ExcFEDontMatch,
1530 "The FiniteElement you provided to FEValues and the FiniteElement that belongs "
1531 "to the DoFHandler that provided the cell iterator do not match.");
1532 /**
1533 * A given shape function is not primitive, but it needs to be.
1534 *
1535 * @ingroup Exceptions
1536 */
1537 DeclException1(ExcShapeFunctionNotPrimitive,
1538 int,
1539 << "The shape function with index " << arg1
1540 << " is not primitive, i.e. it is vector-valued and "
1541 << "has more than one non-zero vector component. This "
1542 << "function cannot be called for these shape functions. "
1543 << "Maybe you want to use the same function with the "
1544 << "_component suffix?");
1545
1546 /**
1547 * The given FiniteElement is not a primitive element, see
1548 * FiniteElement::is_primitive().
1549 *
1550 * @ingroup Exceptions
1551 */
1552 DeclExceptionMsg(
1553 ExcFENotPrimitive,
1554 "The given FiniteElement is not a primitive element but the requested operation "
1555 "only works for those. See FiniteElement::is_primitive() for more information.");
1556
1557 protected:
1558 /**
1559 * Objects of the FEValues class need to store an iterator
1560 * to the present cell in order to be able to extract the values of the
1561 * degrees of freedom on this cell in the get_function_values() and assorted
1562 * functions.
1563 *
1564 * The problem is that the iterators given to the various reinit() functions
1565 * can either be Triangulation iterators, or DoFHandler cell or level
1566 * iterators. All three are valid, and provide different functionality that is
1567 * used in different contexts; as a consequence we need to be able to store
1568 * all three. This class provides the ability to store an object of any of
1569 * these types, via a member variable that is a std::variant that encapsulates
1570 * an object of any of the three types. Because a std::variant always stores
1571 * an object of *one* of these types, we wrap the std::variant object into a
1572 * std::optional that allows us to encode a "not yet initialized" state.
1573 */
1574 class CellIteratorWrapper
1575 {
1576 public:
1577 DeclExceptionMsg(
1578 ExcNeedsDoFHandler,
1579 "You have previously called the FEValues::reinit() function with a "
1580 "cell iterator of type Triangulation<dim,spacedim>::cell_iterator. However, "
1581 "when you do this, you cannot call some functions in the FEValues "
1582 "class, such as the get_function_values/gradients/hessians/third_derivatives "
1583 "functions. If you need these functions, then you need to call "
1584 "FEValues::reinit() with an iterator type that allows to extract "
1585 "degrees of freedom, such as DoFHandler<dim,spacedim>::cell_iterator.");
1586
1587 /**
1588 * Constructor. Creates an unusable object that is not associated with
1589 * any cell at all.
1590 */
1591 CellIteratorWrapper() = default;
1592
1593 /**
1594 * Constructor.
1595 */
1596 CellIteratorWrapper(
1597 const typename Triangulation<dim, spacedim>::cell_iterator &cell);
1598
1599 /**
1600 * Constructor.
1601 */
1602 CellIteratorWrapper(
1603 const typename DoFHandler<dim, spacedim>::cell_iterator &cell);
1604
1605 /**
1606 * Constructor.
1607 */
1608 CellIteratorWrapper(
1609 const typename DoFHandler<dim, spacedim>::level_cell_iterator &cell);
1610
1611 /**
1612 * Indicate whether FEValues::reinit() was called.
1613 */
1614 bool
1615 is_initialized() const;
1616
1617 /**
1618 * Conversion operator to an iterator for triangulations. This
1619 * conversion is implicit for the original iterators, since they are derived
1620 * classes. However, since here we have kind of a parallel class hierarchy,
1621 * we have to have a conversion operator.
1622 */
1623 operator typename Triangulation<dim, spacedim>::cell_iterator() const;
1624
1625 /**
1626 * Return the number of degrees of freedom the DoF
1627 * handler object has to which the iterator belongs to.
1628 */
1629 types::global_dof_index
1630 n_dofs_for_dof_handler() const;
1631
1632 /**
1633 * Call @p get_interpolated_dof_values of the iterator with the
1634 * given arguments.
1635 */
1636 template <typename Number>
1637 void
1638 get_interpolated_dof_values(const ReadVector<Number> &in,
1639 Vector<Number> &out) const;
1640
1641 private:
1642 /**
1643 * The cell in question, if one has been assigned to this object. The
1644 * concrete data type can either be a Triangulation cell iterator, a
1645 * DoFHandler cell iterator, or a DoFHandler level cell iterator.
1646 */
1647 std::optional<
1648 std::variant<typename Triangulation<dim, spacedim>::cell_iterator,
1649 typename DoFHandler<dim, spacedim>::cell_iterator,
1650 typename DoFHandler<dim, spacedim>::level_cell_iterator>>
1651 cell;
1652 };
1653
1654 /**
1655 * Store the cell selected last time the reinit() function was called. This
1656 * is necessary for the <tt>get_function_*</tt> functions as well as the
1657 * functions of same name in the extractor classes.
1658 */
1659 CellIteratorWrapper present_cell;
1660
1661 /**
1662 * A signal connection we use to ensure we get informed whenever the
1663 * triangulation changes by refinement. We need to know about that because
1664 * it invalidates all cell iterators and, as part of that, the
1665 * 'present_cell' iterator we keep around between subsequent calls to
1666 * reinit() in order to compute the cell similarity.
1667 */
1668 boost::signals2::connection tria_listener_refinement;
1669
1670 /**
1671 * A signal connection we use to ensure we get informed whenever the
1672 * triangulation changes by mesh transformations. We need to know about that
1673 * because it invalidates all cell iterators and, as part of that, the
1674 * 'present_cell' iterator we keep around between subsequent calls to
1675 * reinit() in order to compute the cell similarity.
1676 */
1677 boost::signals2::connection tria_listener_mesh_transform;
1678
1679 /**
1680 * A function that is connected to the triangulation in order to reset the
1681 * stored 'present_cell' iterator to an invalid one whenever the
1682 * triangulation is changed and the iterator consequently becomes invalid.
1683 */
1684 void
1685 invalidate_present_cell();
1686
1687 /**
1688 * This function is called by the various reinit() functions in derived
1689 * classes. Given the cell indicated by the argument, test whether we have
1690 * to throw away the previously stored present_cell argument because it
1691 * would require us to compare cells from different triangulations. In
1692 * checking all this, also make sure that we have tria_listener connected to
1693 * the triangulation to which we will set present_cell right after calling
1694 * this function.
1695 */
1696 void
1697 maybe_invalidate_previous_present_cell(
1698 const typename Triangulation<dim, spacedim>::cell_iterator &cell);
1699
1700 /**
1701 * A pointer to the mapping object associated with this FEValues object.
1702 */
1703 const ObserverPointer<const Mapping<dim, spacedim>,
1704 FEValuesBase<dim, spacedim>>
1705 mapping;
1706
1707 /**
1708 * A pointer to the internal data object of mapping, obtained from
1709 * Mapping::get_data(), Mapping::get_face_data(), or
1710 * Mapping::get_subface_data().
1711 */
1712 std::unique_ptr<typename Mapping<dim, spacedim>::InternalDataBase>
1713 mapping_data;
1714
1715 /**
1716 * An object into which the Mapping::fill_fe_values() and similar functions
1717 * place their output.
1718 */
1719 internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
1720 mapping_output;
1721
1722 /**
1723 * A pointer to the finite element object associated with this FEValues
1724 * object.
1725 */
1726 const ObserverPointer<const FiniteElement<dim, spacedim>,
1727 FEValuesBase<dim, spacedim>>
1728 fe;
1729
1730 /**
1731 * A pointer to the internal data object of finite element, obtained from
1732 * FiniteElement::get_data(), Mapping::get_face_data(), or
1733 * FiniteElement::get_subface_data().
1734 */
1735 std::unique_ptr<typename FiniteElement<dim, spacedim>::InternalDataBase>
1736 fe_data;
1737
1738 /**
1739 * An object into which the FiniteElement::fill_fe_values() and similar
1740 * functions place their output.
1741 */
1742 dealii::internal::FEValuesImplementation::FiniteElementRelatedData<dim,
1743 spacedim>
1744 finite_element_output;
1745
1746
1747 /**
1748 * Original update flags handed to the constructor of FEValues.
1749 */
1750 UpdateFlags update_flags;
1751
1752 /**
1753 * Initialize some update flags. Called from the @p initialize functions of
1754 * derived classes, which are in turn called from their constructors.
1755 *
1756 * Basically, this function finds out using the finite element and mapping
1757 * object already stored which flags need to be set to compute everything
1758 * the user wants, as expressed through the flags passed as argument.
1759 */
1760 UpdateFlags
1761 compute_update_flags(const UpdateFlags update_flags) const;
1762
1763 /**
1764 * An enum variable that can store different states of the current cell in
1765 * comparison to the previously visited cell. If wanted, additional states
1766 * can be checked here and used in one of the methods used during reinit.
1767 */
1768 CellSimilarity::Similarity cell_similarity;
1769
1770 /**
1771 * A function that checks whether the new cell is similar to the one
1772 * previously used. Then, a significant amount of the data can be reused,
1773 * e.g. the derivatives of the basis functions in real space, shape_grad.
1774 */
1775 void
1776 check_cell_similarity(
1777 const typename Triangulation<dim, spacedim>::cell_iterator &cell);
1778
1779 private:
1780 /**
1781 * A cache for all possible FEValuesViews objects.
1782 */
1783 dealii::internal::FEValuesViews::Cache<dim, spacedim> fe_values_views_cache;
1784
1785 /**
1786 * Whether checking for cell similarity is allowed.
1787 */
1788 bool check_for_cell_similarity_allowed;
1789
1790 // Make the view classes friends of this class, since they access internal
1791 // data.
1792 template <int, int>
1793 friend class FEValuesViews::Scalar;
1794 template <int, int>
1795 friend class FEValuesViews::Vector;
1796 template <int, int, int>
1797 friend class FEValuesViews::SymmetricTensor;
1798 template <int, int, int>
1799 friend class FEValuesViews::Tensor;
1800 };
1801
1802 #ifndef DOXYGEN
1803
1804 /*---------------------- Inline functions: FEValuesBase ---------------------*/
1805
1806 template <int dim, int spacedim>
1807 inline const FEValuesViews::Scalar<dim, spacedim> &
1808 FEValuesBase<dim, spacedim>::operator[](
1809 const FEValuesExtractors::Scalar &scalar) const
1810 {
1811 AssertIndexRange(scalar.component, fe_values_views_cache.scalars.size());
1812
1813 return fe_values_views_cache.scalars[scalar.component].value_or_initialize(
1814 [scalar, this]() {
1815 return FEValuesViews::Scalar<dim, spacedim>(*this, scalar.component);
1816 });
1817 }
1818
1819
1820
1821 template <int dim, int spacedim>
1822 inline const FEValuesViews::Vector<dim, spacedim> &
1823 FEValuesBase<dim, spacedim>::operator[](
1824 const FEValuesExtractors::Vector &vector) const
1825 {
1826 AssertIndexRange(vector.first_vector_component,
1827 fe_values_views_cache.vectors.size());
1828
1829 return fe_values_views_cache.vectors[vector.first_vector_component]
1830 .value_or_initialize([vector, this]() {
1831 return FEValuesViews::Vector<dim, spacedim>(
1832 *this, vector.first_vector_component);
1833 });
1834 }
1835
1836
1837
1838 template <int dim, int spacedim>
1839 inline const FEValuesViews::SymmetricTensor<2, dim, spacedim> &
1840 FEValuesBase<dim, spacedim>::operator[](
1841 const FEValuesExtractors::SymmetricTensor<2> &tensor) const
1842 {
1843 Assert(
1844 tensor.first_tensor_component <
1845 fe_values_views_cache.symmetric_second_order_tensors.size(),
1846 ExcIndexRange(tensor.first_tensor_component,
1847 0,
1848 fe_values_views_cache.symmetric_second_order_tensors.size()));
1849
1850 return fe_values_views_cache
1851 .symmetric_second_order_tensors[tensor.first_tensor_component]
1852 .value_or_initialize([tensor, this]() {
1853 return FEValuesViews::SymmetricTensor<2, dim, spacedim>(
1854 *this, tensor.first_tensor_component);
1855 });
1856 }
1857
1858
1859
1860 template <int dim, int spacedim>
1861 inline const FEValuesViews::Tensor<2, dim, spacedim> &
1862 FEValuesBase<dim, spacedim>::operator[](
1863 const FEValuesExtractors::Tensor<2> &tensor) const
1864 {
1865 AssertIndexRange(tensor.first_tensor_component,
1866 fe_values_views_cache.second_order_tensors.size());
1867
1868 return fe_values_views_cache
1869 .second_order_tensors[tensor.first_tensor_component]
1870 .value_or_initialize([tensor, this]() {
1871 return FEValuesViews::Tensor<2, dim, spacedim>(
1872 *this, tensor.first_tensor_component);
1873 });
1874 }
1875
1876
1877
1878 template <int dim, int spacedim>
1879 inline const double &
1880 FEValuesBase<dim, spacedim>::shape_value(const unsigned int i,
1881 const unsigned int q_point) const
1882 {
1883 AssertIndexRange(i, fe->n_dofs_per_cell());
1884 Assert(this->update_flags & update_values,
1885 ExcAccessToUninitializedField("update_values"));
1886 Assert(fe->is_primitive(i), ExcShapeFunctionNotPrimitive(i));
1887 Assert(present_cell.is_initialized(), ExcNotReinited());
1888 // if the entire FE is primitive,
1889 // then we can take a short-cut:
1890 if (fe->is_primitive())
1891 return this->finite_element_output.shape_values(i, q_point);
1892 else
1893 {
1894 // otherwise, use the mapping
1895 // between shape function
1896 // numbers and rows. note that
1897 // by the assertions above, we
1898 // know that this particular
1899 // shape function is primitive,
1900 // so we can call
1901 // system_to_component_index
1902 const unsigned int row =
1903 this->finite_element_output
1904 .shape_function_to_row_table[i * fe->n_components() +
1905 fe->system_to_component_index(i).first];
1906 return this->finite_element_output.shape_values(row, q_point);
1907 }
1908 }
1909
1910
1911
1912 template <int dim, int spacedim>
1913 inline double
1914 FEValuesBase<dim, spacedim>::shape_value_component(
1915 const unsigned int i,
1916 const unsigned int q_point,
1917 const unsigned int component) const
1918 {
1919 AssertIndexRange(i, fe->n_dofs_per_cell());
1920 Assert(this->update_flags & update_values,
1921 ExcAccessToUninitializedField("update_values"));
1922 AssertIndexRange(component, fe->n_components());
1923 Assert(present_cell.is_initialized(), ExcNotReinited());
1924
1925 // check whether the shape function
1926 // is non-zero at all within
1927 // this component:
1928 if (fe->get_nonzero_components(i)[component] == false)
1929 return 0;
1930
1931 // look up the right row in the
1932 // table and take the data from
1933 // there
1934 const unsigned int row =
1935 this->finite_element_output
1936 .shape_function_to_row_table[i * fe->n_components() + component];
1937 return this->finite_element_output.shape_values(row, q_point);
1938 }
1939
1940
1941
1942 template <int dim, int spacedim>
1943 inline const Tensor<1, spacedim> &
1944 FEValuesBase<dim, spacedim>::shape_grad(const unsigned int i,
1945 const unsigned int q_point) const
1946 {
1947 AssertIndexRange(i, fe->n_dofs_per_cell());
1948 Assert(this->update_flags & update_gradients,
1949 ExcAccessToUninitializedField("update_gradients"));
1950 Assert(fe->is_primitive(i), ExcShapeFunctionNotPrimitive(i));
1951 Assert(present_cell.is_initialized(), ExcNotReinited());
1952 // if the entire FE is primitive,
1953 // then we can take a short-cut:
1954 if (fe->is_primitive())
1955 return this->finite_element_output.shape_gradients[i][q_point];
1956 else
1957 {
1958 // otherwise, use the mapping
1959 // between shape function
1960 // numbers and rows. note that
1961 // by the assertions above, we
1962 // know that this particular
1963 // shape function is primitive,
1964 // so we can call
1965 // system_to_component_index
1966 const unsigned int row =
1967 this->finite_element_output
1968 .shape_function_to_row_table[i * fe->n_components() +
1969 fe->system_to_component_index(i).first];
1970 return this->finite_element_output.shape_gradients[row][q_point];
1971 }
1972 }
1973
1974
1975
1976 template <int dim, int spacedim>
1977 inline Tensor<1, spacedim>
1978 FEValuesBase<dim, spacedim>::shape_grad_component(
1979 const unsigned int i,
1980 const unsigned int q_point,
1981 const unsigned int component) const
1982 {
1983 AssertIndexRange(i, fe->n_dofs_per_cell());
1984 Assert(this->update_flags & update_gradients,
1985 ExcAccessToUninitializedField("update_gradients"));
1986 AssertIndexRange(component, fe->n_components());
1987 Assert(present_cell.is_initialized(), ExcNotReinited());
1988 // check whether the shape function
1989 // is non-zero at all within
1990 // this component:
1991 if (fe->get_nonzero_components(i)[component] == false)
1992 return Tensor<1, spacedim>();
1993
1994 // look up the right row in the
1995 // table and take the data from
1996 // there
1997 const unsigned int row =
1998 this->finite_element_output
1999 .shape_function_to_row_table[i * fe->n_components() + component];
2000 return this->finite_element_output.shape_gradients[row][q_point];
2001 }
2002
2003
2004
2005 template <int dim, int spacedim>
2006 inline const Tensor<2, spacedim> &
2007 FEValuesBase<dim, spacedim>::shape_hessian(const unsigned int i,
2008 const unsigned int q_point) const
2009 {
2010 AssertIndexRange(i, fe->n_dofs_per_cell());
2011 Assert(this->update_flags & update_hessians,
2012 ExcAccessToUninitializedField("update_hessians"));
2013 Assert(fe->is_primitive(i), ExcShapeFunctionNotPrimitive(i));
2014 Assert(present_cell.is_initialized(), ExcNotReinited());
2015 // if the entire FE is primitive,
2016 // then we can take a short-cut:
2017 if (fe->is_primitive())
2018 return this->finite_element_output.shape_hessians[i][q_point];
2019 else
2020 {
2021 // otherwise, use the mapping
2022 // between shape function
2023 // numbers and rows. note that
2024 // by the assertions above, we
2025 // know that this particular
2026 // shape function is primitive,
2027 // so we can call
2028 // system_to_component_index
2029 const unsigned int row =
2030 this->finite_element_output
2031 .shape_function_to_row_table[i * fe->n_components() +
2032 fe->system_to_component_index(i).first];
2033 return this->finite_element_output.shape_hessians[row][q_point];
2034 }
2035 }
2036
2037
2038
2039 template <int dim, int spacedim>
2040 inline Tensor<2, spacedim>
2041 FEValuesBase<dim, spacedim>::shape_hessian_component(
2042 const unsigned int i,
2043 const unsigned int q_point,
2044 const unsigned int component) const
2045 {
2046 AssertIndexRange(i, fe->n_dofs_per_cell());
2047 Assert(this->update_flags & update_hessians,
2048 ExcAccessToUninitializedField("update_hessians"));
2049 AssertIndexRange(component, fe->n_components());
2050 Assert(present_cell.is_initialized(), ExcNotReinited());
2051 // check whether the shape function
2052 // is non-zero at all within
2053 // this component:
2054 if (fe->get_nonzero_components(i)[component] == false)
2055 return Tensor<2, spacedim>();
2056
2057 // look up the right row in the
2058 // table and take the data from
2059 // there
2060 const unsigned int row =
2061 this->finite_element_output
2062 .shape_function_to_row_table[i * fe->n_components() + component];
2063 return this->finite_element_output.shape_hessians[row][q_point];
2064 }
2065
2066
2067
2068 template <int dim, int spacedim>
2069 inline const Tensor<3, spacedim> &
2070 FEValuesBase<dim, spacedim>::shape_3rd_derivative(
2071 const unsigned int i,
2072 const unsigned int q_point) const
2073 {
2074 AssertIndexRange(i, fe->n_dofs_per_cell());
2075 Assert(this->update_flags & update_3rd_derivatives,
2076 ExcAccessToUninitializedField("update_3rd_derivatives"));
2077 Assert(fe->is_primitive(i), ExcShapeFunctionNotPrimitive(i));
2078 Assert(present_cell.is_initialized(), ExcNotReinited());
2079 // if the entire FE is primitive,
2080 // then we can take a short-cut:
2081 if (fe->is_primitive())
2082 return this->finite_element_output.shape_3rd_derivatives[i][q_point];
2083 else
2084 {
2085 // otherwise, use the mapping
2086 // between shape function
2087 // numbers and rows. note that
2088 // by the assertions above, we
2089 // know that this particular
2090 // shape function is primitive,
2091 // so we can call
2092 // system_to_component_index
2093 const unsigned int row =
2094 this->finite_element_output
2095 .shape_function_to_row_table[i * fe->n_components() +
2096 fe->system_to_component_index(i).first];
2097 return this->finite_element_output.shape_3rd_derivatives[row][q_point];
2098 }
2099 }
2100
2101
2102
2103 template <int dim, int spacedim>
2104 inline Tensor<3, spacedim>
2105 FEValuesBase<dim, spacedim>::shape_3rd_derivative_component(
2106 const unsigned int i,
2107 const unsigned int q_point,
2108 const unsigned int component) const
2109 {
2110 AssertIndexRange(i, fe->n_dofs_per_cell());
2111 Assert(this->update_flags & update_3rd_derivatives,
2112 ExcAccessToUninitializedField("update_3rd_derivatives"));
2113 AssertIndexRange(component, fe->n_components());
2114 Assert(present_cell.is_initialized(), ExcNotReinited());
2115 // check whether the shape function
2116 // is non-zero at all within
2117 // this component:
2118 if (fe->get_nonzero_components(i)[component] == false)
2119 return Tensor<3, spacedim>();
2120
2121 // look up the right row in the
2122 // table and take the data from
2123 // there
2124 const unsigned int row =
2125 this->finite_element_output
2126 .shape_function_to_row_table[i * fe->n_components() + component];
2127 return this->finite_element_output.shape_3rd_derivatives[row][q_point];
2128 }
2129
2130
2131
2132 template <int dim, int spacedim>
2133 inline const FiniteElement<dim, spacedim> &
2134 FEValuesBase<dim, spacedim>::get_fe() const
2135 {
2136 return *fe;
2137 }
2138
2139
2140
2141 template <int dim, int spacedim>
2142 inline const Mapping<dim, spacedim> &
2143 FEValuesBase<dim, spacedim>::get_mapping() const
2144 {
2145 return *mapping;
2146 }
2147
2148
2149
2150 template <int dim, int spacedim>
2151 inline UpdateFlags
2152 FEValuesBase<dim, spacedim>::get_update_flags() const
2153 {
2154 return this->update_flags;
2155 }
2156
2157
2158
2159 template <int dim, int spacedim>
2160 inline const std::vector<Point<spacedim>> &
2161 FEValuesBase<dim, spacedim>::get_quadrature_points() const
2162 {
2163 Assert(this->update_flags & update_quadrature_points,
2164 ExcAccessToUninitializedField("update_quadrature_points"));
2165 Assert(present_cell.is_initialized(), ExcNotReinited());
2166 return this->mapping_output.quadrature_points;
2167 }
2168
2169
2170
2171 template <int dim, int spacedim>
2172 inline const std::vector<double> &
2173 FEValuesBase<dim, spacedim>::get_JxW_values() const
2174 {
2175 Assert(this->update_flags & update_JxW_values,
2176 ExcAccessToUninitializedField("update_JxW_values"));
2177 Assert(present_cell.is_initialized(), ExcNotReinited());
2178 return this->mapping_output.JxW_values;
2179 }
2180
2181
2182
2183 template <int dim, int spacedim>
2184 inline const std::vector<DerivativeForm<1, dim, spacedim>> &
2185 FEValuesBase<dim, spacedim>::get_jacobians() const
2186 {
2187 Assert(this->update_flags & update_jacobians,
2188 ExcAccessToUninitializedField("update_jacobians"));
2189 Assert(present_cell.is_initialized(), ExcNotReinited());
2190 return this->mapping_output.jacobians;
2191 }
2192
2193
2194
2195 template <int dim, int spacedim>
2196 inline const std::vector<DerivativeForm<2, dim, spacedim>> &
2197 FEValuesBase<dim, spacedim>::get_jacobian_grads() const
2198 {
2199 Assert(this->update_flags & update_jacobian_grads,
2200 ExcAccessToUninitializedField("update_jacobians_grads"));
2201 Assert(present_cell.is_initialized(), ExcNotReinited());
2202 return this->mapping_output.jacobian_grads;
2203 }
2204
2205
2206
2207 template <int dim, int spacedim>
2208 inline const Tensor<3, spacedim> &
2209 FEValuesBase<dim, spacedim>::jacobian_pushed_forward_grad(
2210 const unsigned int q_point) const
2211 {
2212 Assert(this->update_flags & update_jacobian_pushed_forward_grads,
2213 ExcAccessToUninitializedField("update_jacobian_pushed_forward_grads"));
2214 Assert(present_cell.is_initialized(), ExcNotReinited());
2215 return this->mapping_output.jacobian_pushed_forward_grads[q_point];
2216 }
2217
2218
2219
2220 template <int dim, int spacedim>
2221 inline const std::vector<Tensor<3, spacedim>> &
2222 FEValuesBase<dim, spacedim>::get_jacobian_pushed_forward_grads() const
2223 {
2224 Assert(this->update_flags & update_jacobian_pushed_forward_grads,
2225 ExcAccessToUninitializedField("update_jacobian_pushed_forward_grads"));
2226 Assert(present_cell.is_initialized(), ExcNotReinited());
2227 return this->mapping_output.jacobian_pushed_forward_grads;
2228 }
2229
2230
2231
2232 template <int dim, int spacedim>
2233 inline const DerivativeForm<3, dim, spacedim> &
2234 FEValuesBase<dim, spacedim>::jacobian_2nd_derivative(
2235 const unsigned int q_point) const
2236 {
2237 Assert(this->update_flags & update_jacobian_2nd_derivatives,
2238 ExcAccessToUninitializedField("update_jacobian_2nd_derivatives"));
2239 Assert(present_cell.is_initialized(), ExcNotReinited());
2240 return this->mapping_output.jacobian_2nd_derivatives[q_point];
2241 }
2242
2243
2244
2245 template <int dim, int spacedim>
2246 inline const std::vector<DerivativeForm<3, dim, spacedim>> &
2247 FEValuesBase<dim, spacedim>::get_jacobian_2nd_derivatives() const
2248 {
2249 Assert(this->update_flags & update_jacobian_2nd_derivatives,
2250 ExcAccessToUninitializedField("update_jacobian_2nd_derivatives"));
2251 Assert(present_cell.is_initialized(), ExcNotReinited());
2252 return this->mapping_output.jacobian_2nd_derivatives;
2253 }
2254
2255
2256
2257 template <int dim, int spacedim>
2258 inline const Tensor<4, spacedim> &
2259 FEValuesBase<dim, spacedim>::jacobian_pushed_forward_2nd_derivative(
2260 const unsigned int q_point) const
2261 {
2262 Assert(this->update_flags & update_jacobian_pushed_forward_2nd_derivatives,
2263 ExcAccessToUninitializedField(
2264 "update_jacobian_pushed_forward_2nd_derivatives"));
2265 Assert(present_cell.is_initialized(), ExcNotReinited());
2266 return this->mapping_output.jacobian_pushed_forward_2nd_derivatives[q_point];
2267 }
2268
2269
2270
2271 template <int dim, int spacedim>
2272 inline const std::vector<Tensor<4, spacedim>> &
2273 FEValuesBase<dim, spacedim>::get_jacobian_pushed_forward_2nd_derivatives() const
2274 {
2275 Assert(this->update_flags & update_jacobian_pushed_forward_2nd_derivatives,
2276 ExcAccessToUninitializedField(
2277 "update_jacobian_pushed_forward_2nd_derivatives"));
2278 Assert(present_cell.is_initialized(), ExcNotReinited());
2279 return this->mapping_output.jacobian_pushed_forward_2nd_derivatives;
2280 }
2281
2282
2283
2284 template <int dim, int spacedim>
2285 inline const DerivativeForm<4, dim, spacedim> &
2286 FEValuesBase<dim, spacedim>::jacobian_3rd_derivative(
2287 const unsigned int q_point) const
2288 {
2289 Assert(this->update_flags & update_jacobian_3rd_derivatives,
2290 ExcAccessToUninitializedField("update_jacobian_3rd_derivatives"));
2291 Assert(present_cell.is_initialized(), ExcNotReinited());
2292 return this->mapping_output.jacobian_3rd_derivatives[q_point];
2293 }
2294
2295
2296
2297 template <int dim, int spacedim>
2298 inline const std::vector<DerivativeForm<4, dim, spacedim>> &
2299 FEValuesBase<dim, spacedim>::get_jacobian_3rd_derivatives() const
2300 {
2301 Assert(this->update_flags & update_jacobian_3rd_derivatives,
2302 ExcAccessToUninitializedField("update_jacobian_3rd_derivatives"));
2303 Assert(present_cell.is_initialized(), ExcNotReinited());
2304 return this->mapping_output.jacobian_3rd_derivatives;
2305 }
2306
2307
2308
2309 template <int dim, int spacedim>
2310 inline const Tensor<5, spacedim> &
2311 FEValuesBase<dim, spacedim>::jacobian_pushed_forward_3rd_derivative(
2312 const unsigned int q_point) const
2313 {
2314 Assert(this->update_flags & update_jacobian_pushed_forward_3rd_derivatives,
2315 ExcAccessToUninitializedField(
2316 "update_jacobian_pushed_forward_3rd_derivatives"));
2317 Assert(present_cell.is_initialized(), ExcNotReinited());
2318 return this->mapping_output.jacobian_pushed_forward_3rd_derivatives[q_point];
2319 }
2320
2321
2322
2323 template <int dim, int spacedim>
2324 inline const std::vector<Tensor<5, spacedim>> &
2325 FEValuesBase<dim, spacedim>::get_jacobian_pushed_forward_3rd_derivatives() const
2326 {
2327 Assert(this->update_flags & update_jacobian_pushed_forward_3rd_derivatives,
2328 ExcAccessToUninitializedField(
2329 "update_jacobian_pushed_forward_3rd_derivatives"));
2330 Assert(present_cell.is_initialized(), ExcNotReinited());
2331 return this->mapping_output.jacobian_pushed_forward_3rd_derivatives;
2332 }
2333
2334
2335
2336 template <int dim, int spacedim>
2337 inline const std::vector<DerivativeForm<1, spacedim, dim>> &
2338 FEValuesBase<dim, spacedim>::get_inverse_jacobians() const
2339 {
2340 Assert(this->update_flags & update_inverse_jacobians,
2341 ExcAccessToUninitializedField("update_inverse_jacobians"));
2342 Assert(present_cell.is_initialized(), ExcNotReinited());
2343 return this->mapping_output.inverse_jacobians;
2344 }
2345
2346
2347
2348 template <int dim, int spacedim>
2349 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
2350 FEValuesBase<dim, spacedim>::dof_indices() const
2351 {
2352 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
2353 0U, dofs_per_cell);
2354 }
2355
2356
2357
2358 template <int dim, int spacedim>
2359 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
2360 FEValuesBase<dim, spacedim>::dof_indices_starting_at(
2361 const unsigned int start_dof_index) const
2362 {
2363 Assert(start_dof_index <= dofs_per_cell,
2364 ExcIndexRange(start_dof_index, 0, dofs_per_cell + 1));
2365 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
2366 start_dof_index, dofs_per_cell);
2367 }
2368
2369
2370
2371 template <int dim, int spacedim>
2372 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
2373 FEValuesBase<dim, spacedim>::dof_indices_ending_at(
2374 const unsigned int end_dof_index) const
2375 {
2376 Assert(end_dof_index < dofs_per_cell,
2377 ExcIndexRange(end_dof_index, 0, dofs_per_cell));
2378 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
2379 0U, end_dof_index + 1);
2380 }
2381
2382
2383
2384 template <int dim, int spacedim>
2385 inline std_cxx20::ranges::iota_view<unsigned int, unsigned int>
2386 FEValuesBase<dim, spacedim>::quadrature_point_indices() const
2387 {
2388 return std_cxx20::ranges::iota_view<unsigned int, unsigned int>(
2389 0U, n_quadrature_points);
2390 }
2391
2392
2393
2394 template <int dim, int spacedim>
2395 inline const Point<spacedim> &
2396 FEValuesBase<dim, spacedim>::quadrature_point(const unsigned int q_point) const
2397 {
2398 Assert(this->update_flags & update_quadrature_points,
2399 ExcAccessToUninitializedField("update_quadrature_points"));
2400 AssertIndexRange(q_point, this->mapping_output.quadrature_points.size());
2401 Assert(present_cell.is_initialized(), ExcNotReinited());
2402
2403 return this->mapping_output.quadrature_points[q_point];
2404 }
2405
2406
2407
2408 template <int dim, int spacedim>
2409 inline double
2410 FEValuesBase<dim, spacedim>::JxW(const unsigned int q_point) const
2411 {
2412 Assert(this->update_flags & update_JxW_values,
2413 ExcAccessToUninitializedField("update_JxW_values"));
2414 AssertIndexRange(q_point, this->mapping_output.JxW_values.size());
2415 Assert(present_cell.is_initialized(), ExcNotReinited());
2416
2417 return this->mapping_output.JxW_values[q_point];
2418 }
2419
2420
2421
2422 template <int dim, int spacedim>
2423 inline const DerivativeForm<1, dim, spacedim> &
2424 FEValuesBase<dim, spacedim>::jacobian(const unsigned int q_point) const
2425 {
2426 Assert(this->update_flags & update_jacobians,
2427 ExcAccessToUninitializedField("update_jacobians"));
2428 AssertIndexRange(q_point, this->mapping_output.jacobians.size());
2429 Assert(present_cell.is_initialized(), ExcNotReinited());
2430
2431 return this->mapping_output.jacobians[q_point];
2432 }
2433
2434
2435
2436 template <int dim, int spacedim>
2437 inline const DerivativeForm<2, dim, spacedim> &
2438 FEValuesBase<dim, spacedim>::jacobian_grad(const unsigned int q_point) const
2439 {
2440 Assert(this->update_flags & update_jacobian_grads,
2441 ExcAccessToUninitializedField("update_jacobians_grads"));
2442 AssertIndexRange(q_point, this->mapping_output.jacobian_grads.size());
2443 Assert(present_cell.is_initialized(), ExcNotReinited());
2444
2445 return this->mapping_output.jacobian_grads[q_point];
2446 }
2447
2448
2449
2450 template <int dim, int spacedim>
2451 inline const DerivativeForm<1, spacedim, dim> &
2452 FEValuesBase<dim, spacedim>::inverse_jacobian(const unsigned int q_point) const
2453 {
2454 Assert(this->update_flags & update_inverse_jacobians,
2455 ExcAccessToUninitializedField("update_inverse_jacobians"));
2456 AssertIndexRange(q_point, this->mapping_output.inverse_jacobians.size());
2457 Assert(present_cell.is_initialized(), ExcNotReinited());
2458
2459 return this->mapping_output.inverse_jacobians[q_point];
2460 }
2461
2462
2463
2464 template <int dim, int spacedim>
2465 inline const Tensor<1, spacedim> &
2466 FEValuesBase<dim, spacedim>::normal_vector(const unsigned int q_point) const
2467 {
2468 Assert(this->update_flags & update_normal_vectors,
2469 (typename FEValuesBase<dim, spacedim>::ExcAccessToUninitializedField(
2470 "update_normal_vectors")));
2471 AssertIndexRange(q_point, this->mapping_output.normal_vectors.size());
2472 Assert(present_cell.is_initialized(), ExcNotReinited());
2473
2474 return this->mapping_output.normal_vectors[q_point];
2475 }
2476
2477 #endif
2478
2479 DEAL_II_NAMESPACE_CLOSE
2480
2481 #endif