Debian Codegraph @

include/deal.II/numerics/data_postprocessor.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2007 - 2024 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_data_postprocessor_h
16 #define dealii_data_postprocessor_h
17
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/point.h>
24 #include <deal.II/base/tensor.h>
25
26 #include <deal.II/dofs/dof_handler.h>
27
28 #include <deal.II/fe/fe_update_flags.h>
29
30 #include <deal.II/lac/vector.h>
31
32 #include <deal.II/numerics/data_component_interpretation.h>
33
34 #include <any>
35 #include <string>
36 #include <vector>
37
38 DEAL_II_NAMESPACE_OPEN
39
40
41 /**
42 * A namespace for data structures that are going to be passed from
43 * DataOut to the member functions of DataPostprocessor.
44 */
45 namespace DataPostprocessorInputs
46 {
47 /**
48 * A base class containing common elements for the Scalar and Vector classes
49 * that are passed as arguments to
50 * DataPostprocessor::evaluate_scalar_field() and
51 * DataPostprocessor::evaluate_vector_field(). This common base class
52 * provides access to the points at which the solution is being evaluated,
53 * and a few other fields, as described in the following.
54 *
55 * <h4>Normal vector access</h4>
56 *
57 * If appropriate, i.e., if the object that is currently being processed
58 * is a face of a cell and the DataPostprocessor object is called from
59 * DataOutFaces or a similar class, then the current object also
60 * stores the normal vectors to the geometry on which output
61 * is generated, at these evaluation points.
62 *
63 * On the other hand, if the solution is being evaluated on a cell,
64 * then the @p normal_vectors member variable does not contain anything
65 * useful.
66 *
67 *
68 * <h4>Cell access</h4>
69 *
70 * DataPostprocessor is typically called from classes such as DataOut
71 * or DataOutFaces that evaluate solution fields on a cell-by-cell
72 * basis. As a consequence, classes derived from DataPostprocessor
73 * (or DataPostprocessorScalar, DataPostprocessorVector, or
74 * DataPostprocessorTensor) sometimes
75 * need to use which cell is currently under investigation. Consequently,
76 * DataOut and similar classes pass the cell they are currently working
77 * on to DataPostprocessor via the classes in this namespace (and
78 * specifically the current base class).
79 *
80 * However, the situation is not so simple. This is because the current
81 * class (and those derived from it) only knows the space dimension in
82 * which the output lives. But this can come from many sources. For example,
83 * if we are in 3d, this may be because we are working on a DoFHandler<3> or
84 * a DoFHandler<2,3> (i.e., either a 3d mesh, or a 2d meshes of a 2d surface
85 * embedded in 3d space). Another case is classes like DataOutRotation or
86 * DataOutStack, then @p spacedim being equal to 3 might mean that we are
87 * actually working on a DoFHandler<2>.
88 *
89 * In other words, just because we know the value of the @p spacedim
90 * template argument of the current class does not mean that the
91 * data type of the cell iterator that is currently being worked on
92 * is obvious.
93 *
94 * To make the cell iterator accessible nevertheless, this class uses
95 * an object of type std::any to store the cell iterator. You can
96 * think of this as being a void pointer that can point to anything.
97 * To use what is being used therefore requires the user to know the
98 * data type of the thing being pointed to.
99 *
100 * To make this work, the DataOut and related classes store in objects
101 * of the current type a representation of the cell. To get it back out,
102 * you would use the get_cell() function that requires you to say,
103 * as a template parameter, the dimension of the cell that is currently
104 * being processed. This is knowledge you typically have in an
105 * application: for example, if your application runs in @p dim space
106 * dimensions and you are currently using the DataOut class, then the cells
107 * that are worked on have data type <code>DataOut<dim>::cell_iterator</code>.
108 * Consequently, in a postprocessor, you can call <code>inputs.get_cell@<dim@>
109 * </code>. For technical reasons, however, C++ will typically require you to
110 * write this as <code>inputs.template get_cell@<dim@> </code> because the
111 * member function we call here requires that we explicitly provide the
112 * template argument.
113 *
114 * Let us consider a complete example of a postprocessor that computes
115 * the fluid norm of the stress $\|\sigma\| = \|\eta \nabla u\|$ from the
116 * viscosity $\eta$ and the gradient of the fluid velocity, $\nabla u$,
117 * assuming that the viscosity is something that depends on the cell's
118 * material id. This can be done using a class we derive from
119 * DataPostprocessorScalar where we overload the
120 * DataPostprocessor::evaluate_vector_field() function that receives the
121 * values and gradients of the velocity (plus of other solution variables such
122 * as the pressure, but let's ignore those for the moment). Then we could use
123 * code such as this:
124 * @code
125 * template <int dim>
126 * class ComputeStress : public DataPostprocessorScalar<dim>
127 * {
128 * public:
129 * ... // overload other necessary member variables
130 * virtual
131 * void
132 * evaluate_vector_field
133 * (const DataPostprocessorInputs::Vector<dim> &input_data,
134 * std::vector<Vector<double> > &computed_quantities) const override
135 * {
136 * const typename DoFHandler<dim>::cell_iterator current_cell =
137 * input_data.template get_cell<dim>();
138 * const viscosity = look_up_viscosity (current_cell->material_id());
139 *
140 * for (unsigned int q=0; q<input_data.solution_gradients.size(); ++q)
141 * computed_quantities[q][0] =
142 * (viscosity * input_data.solution_gradients[q]).norm();
143 * }
144 * };
145 * @endcode
146 *
147 *
148 * <h4>Face access</h4>
149 *
150 * When a DataPostprocessor object is used for output via the DataOutFaces
151 * class, it is sometimes necessary to also know which face is currently
152 * being worked on. Like accessing the cell as shown above, postprocessors
153 * can then query the face number via the CommonInputs::get_face_number()
154 * function. An example postprocessor that ignores its input and
155 * only puts the @ref GlossBoundaryIndicator "Boundary indicator"
156 * into the output file would then look as follows:
157 * @code
158 * template <int dim>
159 * class BoundaryIds : public DataPostprocessorScalar<dim>
160 * {
161 * public:
162 * BoundaryIds()
163 * : DataPostprocessorScalar<dim>("boundary_id", update_default)
164 * {}
165 *
166 *
167 * virtual void
168 * evaluate_scalar_field(
169 * const DataPostprocessorInputs::Scalar<dim> &inputs,
170 * std::vector<Vector<double>> &computed_quantities) const override
171 * {
172 * AssertDimension(computed_quantities.size(),
173 * inputs.solution_values.size());
174 *
175 * // Get the cell and face we are currently dealing with:
176 * const typename DoFHandler<dim>::active_cell_iterator cell =
177 * inputs.template get_cell<dim>();
178 * const unsigned int face = inputs.get_face_number();
179 *
180 * // Then fill the output fields with the boundary_id of the face
181 * for (auto &output : computed_quantities)
182 * {
183 * AssertDimension(output.size(), 1);
184 * output(0) = cell->face(face)->boundary_id();
185 * }
186 * }
187 * };
188 * @endcode
189 */
190 template <int spacedim>
191 struct CommonInputs
192 {
193 /**
194 * Constructor.
195 */
196 CommonInputs();
197
198 /**
199 * An array of vectors normal to the faces of cells, evaluated at the points
200 * at which we are generating graphical output. This array is only used by
201 * the DataOutFaces class, and is left empty by all other classes for
202 * which the DataPostprocessor framework can be used. In the case of
203 * DataOutFaces, the array contains the outward normal vectors to the
204 * face, seen from the interior of the cell.
205 *
206 * This array is only filled if a user-derived class overloads the
207 * DataPostprocessor::get_needed_update_flags(), and the function
208 * returns (possibly among other flags)
209 * UpdateFlags::update_normal_vectors. Alternatively, a class
210 * derived from DataPostprocessorScalar, DataPostprocessorVector,
211 * or DataPostprocessorTensor may pass this flag to the constructor of
212 * these three classes.
213 */
214 std::vector<Tensor<1, spacedim>> normals;
215
216 /**
217 * An array of coordinates corresponding to the locations at which
218 * we are generating graphical output on one cell.
219 *
220 * This array is only filled if a user-derived class overloads the
221 * DataPostprocessor::get_needed_update_flags(), and the function
222 * returns (possibly among other flags)
223 * UpdateFlags::update_quadrature_points. Alternatively, a class
224 * derived from DataPostprocessorScalar, DataPostprocessorVector,
225 * or DataPostprocessorTensor may pass this flag to the constructor of
226 * these three classes.
227 *
228 * @note In the current context, the flag UpdateFlags::update_quadrature_points
229 * is misnamed because we are not actually performing any quadrature.
230 * Rather, we are *evaluating* the solution at specific evaluation
231 * points, but these points are unrelated to quadrature (i.e.,
232 * to computing integrals) and will, in general, not be located
233 * at Gauss points or the quadrature points of any of the typical
234 * quadrature rules.)
235 */
236 std::vector<Point<spacedim>> evaluation_points;
237
238 /**
239 * Set the cell that is currently being used in evaluating the data
240 * for which the DataPostprocessor object is being called.
241 *
242 * This function is not usually called from user space, but is instead
243 * called by DataOut and similar classes when creating the object that
244 * is then passed to DataPostprocessor.
245 */
246 template <int dim>
247 void
248 set_cell(const typename DoFHandler<dim, spacedim>::cell_iterator &cell);
249
250 /**
251 * Set the cell and face number that is currently being used in evaluating
252 * the data for which the DataPostprocessor object is being called. Given
253 * that a face is required, this function is meant to be called by a class
254 * such as DataOutFaces.
255 *
256 * This function is not usually called from user space, but is instead
257 * called by DataOutFaces and similar classes when creating the object that
258 * is then passed to DataPostprocessor.
259 */
260 template <int dim>
261 void
262 set_cell_and_face(
263 const typename DoFHandler<dim, spacedim>::cell_iterator &cell,
264 const unsigned int face_number);
265
266 /**
267 * Query the cell on which we currently produce graphical output.
268 * See the documentation of the current class for an example on how
269 * to use this function.
270 */
271 template <int dim>
272 typename DoFHandler<dim, spacedim>::cell_iterator
273 get_cell() const;
274
275 /**
276 * Query the face number on which we currently produce graphical output.
277 * See the documentation of the current class for an example on how
278 * to use the related get_cell() function that is meant to query the cell
279 * currently being worked on.
280 *
281 * This function is intended for use when producing graphical output on
282 * faces, for example through the DataOutFaces class.
283 */
284 unsigned int
285 get_face_number() const;
286
287 private:
288 /**
289 * The place where set_cell() stores the cell. Since the actual data
290 * type of the cell iterator can be many different things, the
291 * interface uses std::any here. This makes assignment in set_cell()
292 * simple, but requires knowing the data type of the stored object in
293 * get_cell().
294 */
295 std::any cell;
296
297 /**
298 * The place where set_cell_and_face() stores the number of the face
299 * being worked on.
300 */
301 unsigned int face_number;
302 };
303
304 /**
305 * A structure that is used to pass information to
306 * DataPostprocessor::evaluate_scalar_field(). It contains
307 * the values and (if requested) derivatives of a scalar solution
308 * variable at the evaluation points on a cell or face. (This class
309 * is not used if a scalar solution is complex-valued, however,
310 * since in that case the real and imaginary parts are treated
311 * separately -- resulting in vector-valued inputs to data
312 * postprocessors, which are then passed to
313 * DataPostprocessor::evaluate_vector_field() instead.)
314 *
315 * Through the fields in the CommonInputs base class, this class also
316 * makes available access to the locations of evaluations points,
317 * normal vectors (if appropriate), and which cell data is currently
318 * being evaluated on (also if appropriate).
319 */
320 template <int spacedim>
321 struct Scalar : public CommonInputs<spacedim>
322 {
323 /**
324 * An array of values of the (scalar) solution at each of the evaluation
325 * points used to create graphical output from one cell, face, or other
326 * object.
327 */
328 std::vector<double> solution_values;
329
330 /**
331 * An array of gradients of the (scalar) solution at each of the evaluation
332 * points used to create graphical output from one cell, face, or other
333 * object.
334 *
335 * This array is only filled if a user-derived class overloads the
336 * DataPostprocessor::get_needed_update_flags(), and the function
337 * returns (possibly among other flags)
338 * UpdateFlags::update_gradients. Alternatively, a class
339 * derived from DataPostprocessorScalar, DataPostprocessorVector,
340 * or DataPostprocessorTensor may pass this flag to the constructor of
341 * these three classes.
342 */
343 std::vector<Tensor<1, spacedim>> solution_gradients;
344
345 /**
346 * An array of second derivatives of the (scalar) solution at each of the
347 * evaluation points used to create graphical output from one cell, face, or
348 * other object.
349 *
350 * This array is only filled if a user-derived class overloads the
351 * DataPostprocessor::get_needed_update_flags(), and the function
352 * returns (possibly among other flags)
353 * UpdateFlags::update_hessians. Alternatively, a class
354 * derived from DataPostprocessorScalar, DataPostprocessorVector,
355 * or DataPostprocessorTensor may pass this flag to the constructor of
356 * these three classes.
357 */
358 std::vector<Tensor<2, spacedim>> solution_hessians;
359 };
360
361
362
363 /**
364 * A structure that is used to pass information to
365 * DataPostprocessor::evaluate_vector_field(). It contains
366 * the values and (if requested) derivatives of a vector-valued solution
367 * variable at the evaluation points on a cell or face.
368 *
369 * This class is also used if the solution vector is complex-valued
370 * (whether it is scalar- or vector-valued is immaterial in that case)
371 * since in that case, the DataOut and related classes take apart the real
372 * and imaginary parts of a solution vector. In practice, that means that
373 * if a solution vector has $N$ vector components (i.e., there are
374 * $N$ functions that form the solution of the PDE you are dealing with;
375 * $N$ is not the size of the solution vector), then if the solution is
376 * real-valued the `solution_values` variable below will be an array
377 * with as many entries as there are evaluation points on a cell,
378 * and each entry is a vector of length $N$ representing the $N$
379 * solution functions evaluated at a point. On the other hand, if
380 * the solution is complex-valued (i.e., the vector passed to
381 * DataOut::build_patches() has complex-valued entries), then the
382 * `solution_values` member variable of this class will have $2N$
383 * entries for each evaluation point. The first $N$ of these entries
384 * represent the real parts of the solution, and the second $N$ entries
385 * correspond to the imaginary parts of the solution evaluated at the
386 * evaluation point. The same layout is used for the `solution_gradients`
387 * and `solution_hessians` fields: First the gradients/Hessians of
388 * the real components, then all the gradients/Hessians of the
389 * imaginary components. There is more information about the subject in the
390 * documentation of the DataPostprocessor class itself. step-58 provides an
391 * example of how this class is used in a complex-valued situation.
392 *
393 * Through the fields in the CommonInputs base class, this class also
394 * makes available access to the locations of evaluations points,
395 * normal vectors (if appropriate), and which cell data is currently
396 * being evaluated on (also if appropriate).
397 */
398 template <int spacedim>
399 struct Vector : public CommonInputs<spacedim>
400 {
401 /**
402 * An array of values of a vector-valued solution at each of the evaluation
403 * points used to create graphical output from one cell, face, or other
404 * object.
405 *
406 * The outer vector runs over the evaluation points, whereas the inner
407 * vector runs over the components of the finite element field for which
408 * output will be generated.
409 */
410 std::vector<dealii::Vector<double>> solution_values;
411
412 /**
413 * An array of gradients of a vector-valued solution at each of the
414 * evaluation points used to create graphical output from one cell, face, or
415 * other object.
416 *
417 * The outer vector runs over the evaluation points, whereas the inner
418 * vector runs over the components of the finite element field for which
419 * output will be generated.
420 *
421 * This array is only filled if a user-derived class overloads the
422 * DataPostprocessor::get_needed_update_flags(), and the function
423 * returns (possibly among other flags)
424 * UpdateFlags::update_gradients. Alternatively, a class
425 * derived from DataPostprocessorScalar, DataPostprocessorVector,
426 * or DataPostprocessorTensor may pass this flag to the constructor of
427 * these three classes.
428 */
429 std::vector<std::vector<Tensor<1, spacedim>>> solution_gradients;
430
431 /**
432 * An array of second derivatives of a vector-valued solution at each of the
433 * evaluation points used to create graphical output from one cell, face, or
434 * other object.
435 *
436 * The outer vector runs over the evaluation points, whereas the inner
437 * vector runs over the components of the finite element field for which
438 * output will be generated.
439 *
440 * This array is only filled if a user-derived class overloads the
441 * DataPostprocessor::get_needed_update_flags(), and the function
442 * returns (possibly among other flags)
443 * UpdateFlags::update_hessians. Alternatively, a class
444 * derived from DataPostprocessorScalar, DataPostprocessorVector,
445 * or DataPostprocessorTensor may pass this flag to the constructor of
446 * these three classes.
447 */
448 std::vector<std::vector<Tensor<2, spacedim>>> solution_hessians;
449 };
450
451 } // namespace DataPostprocessorInputs
452
453
454 /**
455 * This class provides an interface to compute derived quantities from a
456 * solution that can then be output in graphical formats for visualization,
457 * using facilities such as the DataOut class.
458 *
459 * For the (graphical) output of a FE solution one frequently wants to include
460 * derived quantities, which are calculated from the values of the solution
461 * and possibly the first and second derivatives of the solution. Examples are
462 * the calculation of Mach numbers from velocity and density in supersonic
463 * flow computations, or the computation of the magnitude of a complex-valued
464 * solution as demonstrated in step-29 and step-58 (where it is actually
465 * the *square* of the magnitude). Other uses are shown in
466 * step-32 and step-33. This class offers the interface to perform such
467 * postprocessing. Given the values and derivatives of the solution at those
468 * points where we want to generated output, the functions of this class can be
469 * overloaded to compute new quantities.
470 *
471 * A data vector and an object of a class derived from the current one can be
472 * given to the DataOut::add_data_vector() function (and similarly for
473 * DataOutRotation and DataOutFaces). This will cause DataOut::build_patches()
474 * to compute the derived quantities instead of using the data provided by the
475 * data vector (typically the solution vector). Note that the
476 * DataPostprocessor object (i.e., in reality the object of your derived
477 * class) has to live until the DataOut object is destroyed as the latter
478 * keeps a pointer to the former and will complain if the object pointed to is
479 * destroyed while the latter still has a pointer to it. If both the data
480 * postprocessor and DataOut objects are local variables of a function (as
481 * they are, for example, in step-29), then you can avoid this error by
482 * declaring the data postprocessor variable before the DataOut variable as
483 * objects are destroyed in reverse order of declaration.
484 *
485 * In order not to perform needless calculations, DataPostprocessor has to
486 * provide information which input data is needed for the calculation of the
487 * derived quantities, i.e. whether it needs the values, the first derivative
488 * and/or the second derivative of the provided data. DataPostprocessor
489 * objects which are used in combination with a DataOutFaces object can also
490 * ask for the normal vectors at each point. The information which data is
491 * needed has to be provided via the UpdateFlags returned by the virtual
492 * function get_needed_update_flags(). It is your responsibility to use only
493 * those values which were updated in the calculation of derived quantities.
494 * The DataOut object will provide references to the requested data in the
495 * call to evaluate_scalar_field() or
496 * evaluate_vector_field() (DataOut decides which of the two
497 * functions to call depending on whether the finite element in use has only a
498 * single, or multiple vector components; note that this is only determined by
499 * the number of components in the finite element in use, and not by whether
500 * the data computed by a class derived from the current one is scalar or
501 * vector valued).
502 *
503 * Furthermore, derived classes have to implement the get_names() function,
504 * where the number of output variables returned by the latter function has to
505 * match the size of the vector returned by the former. Furthermore, this
506 * number has to match the number of computed quantities, of course.
507 *
508 *
509 * <h3>Use in simpler cases</h3>
510 *
511 * Deriving from the current class allows to implement very general
512 * postprocessors. For example, in the step-32 program, we implement a
513 * postprocessor that takes a solution that consists of velocity, pressure and
514 * temperature (dim+2 components) and computes a variety of output quantities,
515 * some of which are vector valued and some of which are scalar. On the other
516 * hand, in step-29 we implement a postprocessor that only computes the
517 * magnitude of a complex number given by a two-component finite element. It
518 * seems silly to have to implement four virtual functions for this
519 * (evaluate_scalar_field() or evaluate_vector_field(), get_names(),
520 * get_update_flags() and get_data_component_interpretation()).
521 *
522 * To this end there are three classes DataPostprocessorScalar,
523 * DataPostprocessorVector, and DataPostprocessorTensor that are meant to be
524 * used if the output quantity is either a single scalar, a single vector
525 * (here used meaning to have exactly @p dim components), or a single
526 * tensor (here used meaning to have exactly <code>dim*dim</code> components).
527 * When using these classes, one only has to write a
528 * constructor that passes the name of the output variable and the update
529 * flags to the constructor of the base class and overload the function that
530 * actually computes the results.
531 *
532 * The DataPostprocessorVector and DataPostprocessorTensor class documentations
533 * also contains a extensive examples of how they can be used. The step-29
534 * tutorial program contains an example of using the DataPostprocessorScalar
535 * class.
536 *
537 *
538 * <h3>Complex-valued solutions</h3>
539 *
540 * There are PDEs whose solutions are complex-valued. For example, step-58 and
541 * step-62 solve problems whose solutions at each point consists of a complex
542 * number represented by a `std::complex<double>` variable. (step-29 also solves
543 * such a problem, but there we choose to represent the solution by two
544 * real-valued fields.) In such cases, the vector that is handed to
545 * DataOut::build_patches() is of type `Vector<std::complex<double>>`, or
546 * something essentially equivalent to this. The issue with this, as also
547 * discussed in the documentation of DataOut itself, is that the most widely
548 * used file formats for visualization (notably, the VTK and VTU formats)
549 * can not actually represent complex quantities. The only thing
550 * that can be stored in these data files are real-valued quantities.
551 *
552 * As a consequence, DataOut is forced to take things apart into their real
553 * and imaginary parts, and both are output as separate quantities. This is the
554 * case for data that is written directly to a file by DataOut, but it is also
555 * the case for data that is first routed through DataPostprocessor objects
556 * (or objects of their derived classes): All these objects see is a collection
557 * of real values, even if the underlying solution vector was complex-valued.
558 *
559 * All of this has two implications:
560 * - If a solution vector is complex-valued, then this results in at least
561 * two input components at each evaluation point. As a consequence, the
562 * DataPostprocessor::evaluate_scalar_field() function is never called,
563 * even if the underlying finite element had only a single solution
564 * component. Instead, DataOut will *always* call
565 * DataPostprocessor::evaluate_vector_field().
566 * - Implementations of the DataPostprocessor::evaluate_vector_field() in
567 * derived classes must understand how the solution values are arranged
568 * in the DataPostprocessorInputs::Vector objects they receive as input.
569 * The rule here is: If the finite element has $N$ vector components
570 * (including the case $N=1$, i.e., a scalar element), then the inputs
571 * for complex-valued solution vectors will have $2N$ components. These
572 * first contain the values (or gradients, or Hessians) of the real
573 * parts of all solution components, and then the values (or gradients,
574 * or Hessians) of the imaginary parts of all solution components.
575 *
576 * step-58 provides an example of how this class (or, rather, the derived
577 * DataPostprocessorScalar class) is used in a complex-valued situation.
578 *
579 * @ingroup output
580 */
581 template <int dim>
582 class DataPostprocessor : public EnableObserverPointer
583 {
584 public:
585 /**
586 * Destructor. This function doesn't actually do anything but is marked as
587 * virtual to ensure that data postprocessors can be destroyed through
588 * pointers to the base class.
589 */
590 virtual ~DataPostprocessor() override = default;
591
592 /**
593 * This is the main function which actually performs the postprocessing. The
594 * second argument is a reference to the postprocessed data which already has
595 * correct size and must be filled by this function.
596 *
597 * The function takes the values, gradients, and higher derivatives of the
598 * solution at all evaluation points, as well as other data such as the
599 * cell, via the first argument. Not all of the member vectors of this
600 * argument will be filled with data -- in fact, derivatives and other
601 * quantities will only be contain valid data if the corresponding flags
602 * are returned by an overridden version of the get_needed_update_flags()
603 * function (implemented in a user's derived class).
604 * Otherwise those vectors will be in an unspecified state.
605 *
606 * This function is called when the finite element field that is being
607 * converted into graphical data by DataOut or similar classes represents
608 * scalar data, i.e., if the finite element in use has only a single
609 * real-valued vector component.
610 */
611 virtual void
612 evaluate_scalar_field(const DataPostprocessorInputs::Scalar<dim> &input_data,
613 std::vector<Vector<double>> &computed_quantities) const;
614
615 /**
616 * Same as the evaluate_scalar_field() function, but this
617 * function is called when the original data vector represents vector data,
618 * i.e., the finite element in use has multiple vector components. This
619 * function is also called if the finite element is scalar but the solution
620 * vector is complex-valued. If the solution vector to be visualized
621 * is complex-valued (whether scalar or not), then the input data contains
622 * first all real parts of the solution vector at each evaluation point, and
623 * then all imaginary parts.
624 */
625 virtual void
626 evaluate_vector_field(const DataPostprocessorInputs::Vector<dim> &input_data,
627 std::vector<Vector<double>> &computed_quantities) const;
628
629 /**
630 * Return the vector of strings describing the names of the computed
631 * quantities.
632 */
633 virtual std::vector<std::string>
634 get_names() const = 0;
635
636 /**
637 * This function returns information about how the individual components of
638 * output files that consist of more than one data set are to be
639 * interpreted.
640 *
641 * For example, if one has a finite element for the Stokes equations in 2d,
642 * representing components (u,v,p), one would like to indicate that the
643 * first two, u and v, represent a logical vector so that later on when we
644 * generate graphical output we can hand them off to a visualization program
645 * that will automatically know to render them as a vector field, rather
646 * than as two separate and independent scalar fields.
647 *
648 * The default implementation of this function returns a vector of values
649 * DataComponentInterpretation::component_is_scalar, indicating that all
650 * output components are independent scalar fields. However, if a derived
651 * class produces data that represents vectors, it may return a vector that
652 * contains values DataComponentInterpretation::component_is_part_of_vector.
653 * In the example above, one would return a vector with components
654 * (DataComponentInterpretation::component_is_part_of_vector,
655 * DataComponentInterpretation::component_is_part_of_vector,
656 * DataComponentInterpretation::component_is_scalar) for (u,v,p).
657 */
658 virtual std::vector<DataComponentInterpretation::DataComponentInterpretation>
659 get_data_component_interpretation() const;
660
661 /**
662 * Return, which data has to be provided to compute the derived quantities.
663 * This has to be a combination of @p update_values, @p update_gradients,
664 * @p update_hessians and @p update_quadrature_points. Note that the flag
665 * @p update_quadrature_points updates
666 * DataPostprocessorInputs::CommonInputs::evaluation_points. If the
667 * DataPostprocessor is to be used in combination with DataOutFaces, you may
668 * also ask for a update of normals via the @p update_normal_vectors flag.
669 * The description of the flags can be found at dealii::UpdateFlags.
670 *
671 * @note In the current context, the flag UpdateFlags::update_quadrature_points
672 * is misnamed because we are not actually performing any quadrature.
673 * Rather, we are *evaluating* the solution at specific evaluation
674 * points, but these points are unrelated to quadrature (i.e.,
675 * to computing integrals) and will, in general, not be located
676 * at Gauss points or the quadrature points of any of the typical
677 * quadrature rules.)
678 */
679 virtual UpdateFlags
680 get_needed_update_flags() const = 0;
681 };
682
683
684
685 /**
686 * This class provides a simpler interface to the functionality offered by the
687 * DataPostprocessor class in case one wants to compute only a single scalar
688 * quantity from the finite element field passed to the DataOut class. For
689 * this particular case, it is clear what the returned value of
690 * DataPostprocessor::get_data_component_interpretation() should be and we
691 * pass the values returned by get_names() and get_needed_update_flags() to
692 * the constructor so that derived classes do not have to implement these
693 * functions by hand.
694 *
695 * All derived classes have to do is implement a constructor and overload
696 * either DataPostprocessor::evaluate_scalar_field() or
697 * DataPostprocessor::evaluate_vector_field() as discussed in the
698 * DataPostprocessor class's documentation.
699 *
700 * An example of how this class can be used can be found in step-29 for the case
701 * where we are interested in computing the magnitude (a scalar) of a
702 * complex-valued solution. While in step-29, the solution vector consists of
703 * separate real and imaginary parts of the solution, step-58 computes the
704 * solution vector as a vector with complex entries and the
705 * DataPostprocessorScalar class is used there to compute the magnitude and
706 * phase of the solution in a different way there.
707 *
708 * An example of how the closely related DataPostprocessorVector
709 * class can be used is found in the documentation of that class.
710 * The same is true for the DataPostprocessorTensor class.
711 *
712 * @ingroup output
713 */
714 template <int dim>
715 class DataPostprocessorScalar : public DataPostprocessor<dim>
716 {
717 public:
718 /**
719 * Constructor. Take the name of the single scalar variable computed by
720 * classes derived from the current one, as well as the update flags
721 * necessary to compute this quantity.
722 *
723 * @param name The name by which the scalar variable computed by this class
724 * should be made available in graphical output files.
725 * @param update_flags This has to be a combination of @p update_values,
726 * @p update_gradients, @p update_hessians and @p update_quadrature_points.
727 * Note that the flag @p update_quadrature_points updates
728 * DataPostprocessorInputs::CommonInputs::evaluation_points. If the
729 * DataPostprocessor is to be used in combination with DataOutFaces, you may
730 * also ask for a update of normals via the @p update_normal_vectors flag.
731 * The description of the flags can be found at dealii::UpdateFlags.
732 *
733 * @note In the current context, the flag UpdateFlags::update_quadrature_points
734 * is misnamed because we are not actually performing any quadrature.
735 * Rather, we are *evaluating* the solution at specific evaluation
736 * points, but these points are unrelated to quadrature (i.e.,
737 * to computing integrals) and will, in general, not be located
738 * at Gauss points or the quadrature points of any of the typical
739 * quadrature rules.)
740 */
741 DataPostprocessorScalar(const std::string &name,
742 const UpdateFlags update_flags);
743
744 /**
745 * Return the vector of strings describing the names of the computed
746 * quantities. Given the purpose of this class, this is a vector with a
747 * single entry equal to the name given to the constructor.
748 */
749 virtual std::vector<std::string>
750 get_names() const override;
751
752 /**
753 * This function returns information about how the individual components of
754 * output files that consist of more than one data set are to be
755 * interpreted. Since the current class is meant to be used for a single
756 * scalar result variable, the returned value is obviously
757 * DataComponentInterpretation::component_is_scalar.
758 */
759 virtual std::vector<DataComponentInterpretation::DataComponentInterpretation>
760 get_data_component_interpretation() const override;
761
762 /**
763 * Return, which data has to be provided to compute the derived quantities.
764 * The flags returned here are the ones passed to the constructor of this
765 * class.
766 */
767 virtual UpdateFlags
768 get_needed_update_flags() const override;
769
770 private:
771 /**
772 * Copies of the two arguments given to the constructor of this class.
773 */
774 const std::string name;
775 const UpdateFlags update_flags;
776 };
777
778
779
780 /**
781 * This class provides a simpler interface to the functionality offered by the
782 * DataPostprocessor class in case one wants to compute only a single vector
783 * quantity (defined as having exactly @p dim components) from the finite element
784 * field passed to the DataOut class. For this particular case, it is clear
785 * what the returned value of
786 * DataPostprocessor::get_data_component_interpretation() should be and we
787 * pass the values returned by get_names() and get_needed_update_flags() to
788 * the constructor so that derived classes do not have to implement these
789 * functions by hand.
790 *
791 * All derived classes have to do is implement a constructor and overload
792 * either DataPostprocessor::evaluate_scalar_field() or
793 * DataPostprocessor::evaluate_vector_field() as discussed in the
794 * DataPostprocessor class's documentation.
795 *
796 * An example of how the closely related class DataPostprocessorScalar is used
797 * can be found in step-29. An example of how the DataPostprocessorTensor
798 * class can be used is found in the documentation of that class.
799 *
800 *
801 * <h3> An example </h3>
802 *
803 * A common example of what one wants to do with postprocessors is to visualize
804 * not just the value of the solution, but the gradient. This is, in fact,
805 * precisely what step-19 needs, and it consequently uses the code below almost
806 * verbatim. Let's, for simplicity,
807 * assume that you have only a scalar solution. In fact, because it's readily
808 * available, let us simply take the step-6 solver to produce such a scalar
809 * solution. The gradient is a vector (with exactly @p dim components), so the
810 * current class fits the bill to produce the gradient through postprocessing.
811 * Then, the following code snippet implements everything you need to have
812 * to visualize the gradient:
813 * @code
814 * template <int dim>
815 * class GradientPostprocessor : public DataPostprocessorVector<dim>
816 * {
817 * public:
818 * GradientPostprocessor ()
819 * :
820 * // call the constructor of the base class. call the variable to
821 * // be output "grad_u" and make sure that DataOut provides us
822 * // with the gradients:
823 * DataPostprocessorVector<dim> ("grad_u",
824 * update_gradients)
825 * {}
826 *
827 * virtual
828 * void
829 * evaluate_scalar_field
830 * (const DataPostprocessorInputs::Scalar<dim> &input_data,
831 * std::vector<Vector<double> > &computed_quantities) const override
832 * {
833 * // ensure that there really are as many output slots
834 * // as there are points at which DataOut provides the
835 * // gradients:
836 * AssertDimension (input_data.solution_gradients.size(),
837 * computed_quantities.size());
838 *
839 * // then loop over all of these inputs:
840 * for (unsigned int p=0; p<input_data.solution_gradients.size(); ++p)
841 * {
842 * // ensure that each output slot has exactly 'dim'
843 * // components (as should be expected, given that we
844 * // want to create vector-valued outputs), and copy the
845 * // gradients of the solution at the evaluation points
846 * // into the output slots:
847 * AssertDimension (computed_quantities[p].size(), dim);
848 * for (unsigned int d=0; d<dim; ++d)
849 * computed_quantities[p][d]
850 * = input_data.solution_gradients[p][d];
851 * }
852 * }
853 * };
854 * @endcode
855 * The only thing that is necessary is to add another output to the call
856 * of DataOut::add_vector() in the @p run() function of the @p Step6 class
857 * of that example program. The corresponding code snippet would then look
858 * like this (where we also use VTU as the file format to output the data):
859 * @code
860 * GradientPostprocessor<dim> gradient_postprocessor;
861 *
862 * DataOut<dim> data_out;
863 * data_out.attach_dof_handler (dof_handler);
864 * data_out.add_data_vector (solution, "solution");
865 * data_out.add_data_vector (solution, gradient_postprocessor);
866 * data_out.build_patches ();
867 *
868 * std::ofstream output ("solution.vtu");
869 * data_out.write_vtu (output);
870 * @endcode
871 *
872 * This leads to the following output for the solution and the
873 * gradients (you may want to compare with the solution shown in the results
874 * section of step-6; the current data is generated on a coarser mesh for
875 * simplicity):
876 *
877 * @image html data_postprocessor_vector_0.png
878 * @image html data_postprocessor_vector_1.png
879 *
880 * In the second image, the background color corresponds to the magnitude of the
881 * gradient vector and the vector glyphs to the gradient itself. It may be
882 * surprising at first to see that from each vertex, multiple vectors originate,
883 * going in different directions. But that is because the solution is only
884 * continuous: in general, the gradient is discontinuous across edges, and so
885 * the multiple vectors originating from each vertex simply represent the
886 * differing gradients of the solution at each adjacent cell.
887 *
888 * The output above -- namely, the gradient $\nabla u$ of the solution --
889 * corresponds to the temperature gradient if one interpreted step-6 as solving
890 * a steady-state heat transfer problem.
891 * It is very small in the central part of the domain because in step-6 we are
892 * solving an equation that has a coefficient $a(\mathbf x)$ that is large in
893 * the central part and small on the outside. This can be thought as a material
894 * that conducts heat well, and consequently the temperature gradient is small.
895 * On the other hand, the "heat flux" corresponds to the quantity
896 * $a(\mathbf x) \nabla u(\mathbf x)$. For the
897 * solution of that equation, the flux should be continuous across the
898 * interface. This is easily verified by the following modification of the
899 * postprocessor:
900 * @code
901 * template <int dim>
902 * class HeatFluxPostprocessor : public DataPostprocessorVector<dim>
903 * {
904 * public:
905 * HeatFluxPostprocessor ()
906 * :
907 * // like above, but now also make sure that DataOut provides
908 * // us with coordinates of the evaluation points:
909 * DataPostprocessorVector<dim> ("heat_flux",
910 * update_gradients | update_quadrature_points)
911 * {}
912 *
913 * virtual
914 * void
915 * evaluate_scalar_field
916 * (const DataPostprocessorInputs::Scalar<dim> &input_data,
917 * std::vector<Vector<double> > &computed_quantities) const override
918 * {
919 * AssertDimension (input_data.solution_gradients.size(),
920 * computed_quantities.size());
921 *
922 * for (unsigned int p=0; p<input_data.solution_gradients.size(); ++p)
923 * {
924 * AssertDimension (computed_quantities[p].size(), dim);
925 * for (unsigned int d=0; d<dim; ++d)
926 * // like above, but also multiply the gradients with
927 * // the coefficient evaluated at the current point:
928 * computed_quantities[p][d]
929 * = coefficient (input_data.evaluation_points[p]) *
930 * input_data.solution_gradients[p][d];
931 * }
932 * }
933 * };
934 * @endcode
935 * With this postprocessor, we get the following picture of the heat flux:
936 *
937 * @image html data_postprocessor_vector_2.png
938 *
939 * As the background color shows, the gradient times the coefficient is now
940 * a continuous function. There are (large) vectors around the interface
941 * where the coefficient jumps (at half the distance between the center of the
942 * disk to the perimeter) that seem to point in the wrong direction; this is
943 * an artifact of the fact that the solution has a discontinuous gradient
944 * at these points and that the numerical solution on the current grid
945 * does not adequately resolve this interface. This, however, is not
946 * important to the current discussion.
947 *
948 * @note In the current context, the flag UpdateFlags::update_quadrature_points
949 * is misnamed because we are not actually performing any quadrature.
950 * Rather, we are *evaluating* the solution at specific evaluation
951 * points, but these points are unrelated to quadrature (i.e.,
952 * to computing integrals) and will, in general, not be located
953 * at Gauss points or the quadrature points of any of the typical
954 * quadrature rules.) In the example above, we need the location
955 * of these evaluation points because we need to evaluate the
956 * coefficients at these points.
957 *
958 *
959 * <h3> Extension to the gradients of vector-valued problems </h3>
960 *
961 * The example above uses a scalar solution and its gradient as an example.
962 * On the other hand, one may want to do something similar for the gradient
963 * of a vector-valued displacement field (such as the strain or
964 * stress of a displacement field, like those computed in step-8, step-17,
965 * step-18, or step-44). In that case, the solution is already vector
966 * valued and the stress is a (symmetric) tensor.
967 *
968 * deal.II does not currently support outputting tensor-valued quantities, but
969 * they can of course be output as a collection of scalar-valued components of
970 * the tensor. This can be facilitated using the DataPostprocessorTensor
971 * class. The documentation of that class contains an example.
972 *
973 *
974 * @ingroup output
975 */
976 template <int dim>
977 class DataPostprocessorVector : public DataPostprocessor<dim>
978 {
979 public:
980 /**
981 * Constructor. Take the name of the single vector variable computed by
982 * classes derived from the current one, as well as the update flags
983 * necessary to compute this quantity.
984 *
985 * @param name The name by which the vector variable computed by this class
986 * should be made available in graphical output files.
987 * @param update_flags This has to be a combination of @p update_values,
988 * @p update_gradients, @p update_hessians and @p update_quadrature_points.
989 * Note that the flag @p update_quadrature_points updates
990 * DataPostprocessorInputs::CommonInputs::evaluation_points. If the
991 * DataPostprocessor is to be used in combination with DataOutFaces, you may
992 * also ask for a update of normals via the @p update_normal_vectors flag.
993 * The description of the flags can be found at dealii::UpdateFlags.
994 *
995 * @note In the current context, the flag UpdateFlags::update_quadrature_points
996 * is misnamed because we are not actually performing any quadrature.
997 * Rather, we are *evaluating* the solution at specific evaluation
998 * points, but these points are unrelated to quadrature (i.e.,
999 * to computing integrals) and will, in general, not be located
1000 * at Gauss points or the quadrature points of any of the typical
1001 * quadrature rules.)
1002 */
1003 DataPostprocessorVector(const std::string &name,
1004 const UpdateFlags update_flags);
1005
1006 /**
1007 * Return the vector of strings describing the names of the computed
1008 * quantities. Given the purpose of this class, this is a vector with dim
1009 * entries all equal to the name given to the constructor.
1010 */
1011 virtual std::vector<std::string>
1012 get_names() const override;
1013
1014 /**
1015 * This function returns information about how the individual components of
1016 * output files that consist of more than one data set are to be
1017 * interpreted. Since the current class is meant to be used for a single
1018 * vector result variable, the returned value is obviously
1019 * DataComponentInterpretation::component_is_part repeated dim times.
1020 */
1021 virtual std::vector<DataComponentInterpretation::DataComponentInterpretation>
1022 get_data_component_interpretation() const override;
1023
1024 /**
1025 * Return which data has to be provided to compute the derived quantities.
1026 * The flags returned here are the ones passed to the constructor of this
1027 * class.
1028 */
1029 virtual UpdateFlags
1030 get_needed_update_flags() const override;
1031
1032 private:
1033 /**
1034 * Copies of the two arguments given to the constructor of this class.
1035 */
1036 const std::string name;
1037 const UpdateFlags update_flags;
1038 };
1039
1040
1041
1042 /**
1043 * This class provides a simpler interface to the functionality offered by the
1044 * DataPostprocessor class in case one wants to compute only a single tensor
1045 * quantity (defined as having exactly <code>dim*dim</code> components) from
1046 * the finite element field passed to the DataOut class.
1047 *
1048 * For this case, we would like to output all of these components as parts
1049 * of a tensor-valued quantity. Unfortunately, the various backends that
1050 * write DataOut data in graphical file formats (see the DataOutBase
1051 * namespace for what formats can be written) do not support tensor data
1052 * at the current time. In fact, neither does the DataComponentInterpretation
1053 * namespace that provides semantic information how individual components
1054 * of graphical data should be interpreted. Nevertheless, like
1055 * DataPostprocessorScalar and DataPostprocessorVector, this class helps
1056 * with setting up what the get_names() and get_needed_update_flags()
1057 * functions required by the DataPostprocessor base class should return,
1058 * and so the current class implements these based on information that
1059 * the constructor of the current class receives from further derived
1060 * classes.
1061 *
1062 * (In order to visualize this collection of scalar fields that, together,
1063 * are then supposed to be interpreted as a tensor, one has to (i) use a
1064 * visualization program that can visualize tensors, and (ii) teach it
1065 * how to re-combine the scalar fields into tensors. In the case of
1066 * VisIt -- see https://wci.llnl.gov/simulation/computer-codes/visit/ --
1067 * this is done by creating a new "Expression": in essence, one creates
1068 * a variable, say "grad_u", that is tensor-valued and whose value is
1069 * given by the expression <code>{{grad_u_xx,grad_u_xy},
1070 * {grad_u_yx, grad_u_yy}}</code>, where the referenced variables are
1071 * the names of scalar fields that, here, are produced by the example
1072 * below. VisIt is then able to visualize this "new" variable as a
1073 * tensor.)
1074 *
1075 * All derived classes have to do is implement a constructor and overload
1076 * either DataPostprocessor::evaluate_scalar_field() or
1077 * DataPostprocessor::evaluate_vector_field() as discussed in the
1078 * DataPostprocessor class's documentation.
1079 *
1080 * An example of how the closely related class DataPostprocessorScalar is used
1081 * can be found in step-29. An example of how the DataPostprocessorVector
1082 * class can be used is found in the documentation of that class.
1083 *
1084 *
1085 * <h3> An example </h3>
1086 *
1087 * A common example of what one wants to do with postprocessors is to visualize
1088 * not just the value of the solution, but the gradient. This class is meant for
1089 * tensor-valued outputs, so we will start with a vector-valued solution: the
1090 * displacement field of step-8. The gradient is a rank-2 tensor (with exactly
1091 * <code>dim*dim</code> components), so the
1092 * current class fits the bill to produce the gradient through postprocessing.
1093 * Then, the following code snippet implements everything you need to have
1094 * to visualize the gradient:
1095 * @code
1096 * template <int dim>
1097 * class GradientPostprocessor : public DataPostprocessorTensor<dim>
1098 * {
1099 * public:
1100 * GradientPostprocessor ()
1101 * :
1102 * DataPostprocessorTensor<dim> ("grad_u",
1103 * update_gradients)
1104 * {}
1105 *
1106 * virtual
1107 * void
1108 * evaluate_vector_field
1109 * (const DataPostprocessorInputs::Vector<dim> &input_data,
1110 * std::vector<Vector<double> > &computed_quantities) const override
1111 * {
1112 * // ensure that there really are as many output slots
1113 * // as there are points at which DataOut provides the
1114 * // gradients:
1115 * AssertDimension (input_data.solution_gradients.size(),
1116 * computed_quantities.size());
1117 *
1118 * for (unsigned int p=0; p<input_data.solution_gradients.size(); ++p)
1119 * {
1120 * // ensure that each output slot has exactly 'dim*dim'
1121 * // components (as should be expected, given that we
1122 * // want to create tensor-valued outputs), and copy the
1123 * // gradients of the solution at the evaluation points
1124 * // into the output slots:
1125 * AssertDimension (computed_quantities[p].size(),
1126 * (Tensor<2,dim>::n_independent_components));
1127 * for (unsigned int d=0; d<dim; ++d)
1128 * for (unsigned int e=0; e<dim; ++e)
1129 * computed_quantities[p][Tensor<2,dim>::component_to_unrolled_index(TableIndices<2>(d,e))]
1130 * = input_data.solution_gradients[p][d][e];
1131 * }
1132 * }
1133 * };
1134 * @endcode
1135 * The only tricky part in this piece of code is how to sort the
1136 * <code>dim*dim</code> elements of the strain tensor into the one vector of
1137 * computed output quantities -- in other words, how to <i>unroll</i> the
1138 * elements of the tensor into the vector. This is facilitated by the
1139 * Tensor::component_to_unrolled_index() function that takes a
1140 * pair of indices that specify a particular element of the
1141 * tensor and returns a vector index that is then used in the code
1142 * above to fill the @p computed_quantities array.
1143 *
1144 * The last thing that is necessary is to add another output to the call
1145 * of DataOut::add_vector() in the @p output_results() function of the @p Step8
1146 * class of that example program. The corresponding code snippet would then look
1147 * like this:
1148 * @code
1149 * GradientPostprocessor<dim> grad_u;
1150 *
1151 * DataOut<dim> data_out;
1152 * data_out.attach_dof_handler (dof_handler);
1153 *
1154 * std::vector<DataComponentInterpretation::DataComponentInterpretation>
1155 * data_component_interpretation
1156 * (dim, DataComponentInterpretation::component_is_part_of_vector);
1157 * data_out.add_data_vector (solution,
1158 * std::vector<std::string>(dim,"displacement"),
1159 * DataOut<dim>::type_dof_data,
1160 * data_component_interpretation);
1161 * data_out.add_data_vector (solution, grad_u);
1162 * data_out.build_patches ();
1163 * data_out.write_vtu (output);
1164 * @endcode
1165 *
1166 * This leads to the following output for the displacement field (i.e., the
1167 * solution) and the gradients (you may want to compare with the solution shown
1168 * in the results section of step-8; the current data is generated on a uniform
1169 * mesh for simplicity):
1170 *
1171 * @image html data_postprocessor_tensor_0.png
1172 * @image html data_postprocessor_tensor_1.png
1173 *
1174 * These pictures show an ellipse representing the gradient tensor at, on
1175 * average, every tenth mesh point. You may want to read through the
1176 * documentation of the VisIt visualization program (see
1177 * https://wci.llnl.gov/simulation/computer-codes/visit/) for an interpretation
1178 * of how exactly tensors are visualizated.
1179 *
1180 * In elasticity, one is often interested not in the gradient of the
1181 * displacement, but in the "strain", i.e., the symmetrized version of the
1182 * gradient
1183 * $\varepsilon=\frac 12 (\nabla u + \nabla u^T)$. This is easily facilitated
1184 * with the following minor modification:
1185 * @code
1186 * template <int dim>
1187 * class StrainPostprocessor : public DataPostprocessorTensor<dim>
1188 * {
1189 * public:
1190 * StrainPostprocessor ()
1191 * :
1192 * DataPostprocessorTensor<dim> ("strain",
1193 * update_gradients)
1194 * {}
1195 *
1196 * virtual
1197 * void
1198 * evaluate_vector_field
1199 * (const DataPostprocessorInputs::Vector<dim> &input_data,
1200 * std::vector<Vector<double> > &computed_quantities) const override
1201 * {
1202 * AssertDimension (input_data.solution_gradients.size(),
1203 * computed_quantities.size());
1204 *
1205 * for (unsigned int p=0; p<input_data.solution_gradients.size(); ++p)
1206 * {
1207 * AssertDimension (computed_quantities[p].size(),
1208 * (Tensor<2,dim>::n_independent_components));
1209 * for (unsigned int d=0; d<dim; ++d)
1210 * for (unsigned int e=0; e<dim; ++e)
1211 * computed_quantities[p][Tensor<2,dim>::component_to_unrolled_index(TableIndices<2>(d,e))]
1212 * = (input_data.solution_gradients[p][d][e]
1213 * +
1214 * input_data.solution_gradients[p][e][d]) / 2;
1215 * }
1216 * }
1217 * };
1218 * @endcode
1219 *
1220 * Using this class in step-8 leads to the following visualization:
1221 *
1222 * @image html data_postprocessor_tensor_2.png
1223 *
1224 * Given how easy it is to output the strain, it would also not be very
1225 * complicated to write a postprocessor that computes the <i>stress</i>
1226 * in the solution field as the stress is easily computed from the
1227 * strain by multiplication with either the strain-stress tensor or,
1228 * in simple cases, the Lam&eacute; constants.
1229 *
1230 * @note Not all graphical output formats support writing tensor data. For
1231 * example, the VTU file format used above when calling `data_out.write_vtu()`
1232 * does, but the original VTK file format does not (or at least
1233 * deal.II's output function does not support writing tensors at
1234 * the time of writing). If the file format you want to output does not
1235 * support writing tensor data, you will get an error. Since most
1236 * visualization programs today support VTU format, and since the
1237 * VTU writer supports writing tensor data, there should always be
1238 * a way for you to output tensor data that you can visualize.
1239 *
1240 * @ingroup output
1241 */
1242 template <int dim>
1243 class DataPostprocessorTensor : public DataPostprocessor<dim>
1244 {
1245 public:
1246 /**
1247 * Constructor. Take the name of the single vector variable computed by
1248 * classes derived from the current one, as well as the update flags
1249 * necessary to compute this quantity.
1250 *
1251 * @param name The name by which the vector variable computed by this class
1252 * should be made available in graphical output files.
1253 * @param update_flags This has to be a combination of @p update_values,
1254 * @p update_gradients, @p update_hessians and @p update_quadrature_points.
1255 * Note that the flag @p update_quadrature_points updates
1256 * DataPostprocessorInputs::CommonInputs::evaluation_points. If the
1257 * DataPostprocessor is to be used in combination with DataOutFaces, you may
1258 * also ask for a update of normals via the @p update_normal_vectors flag.
1259 * The description of the flags can be found at dealii::UpdateFlags.
1260 *
1261 * @note In the current context, the flag UpdateFlags::update_quadrature_points
1262 * is misnamed because we are not actually performing any quadrature.
1263 * Rather, we are *evaluating* the solution at specific evaluation
1264 * points, but these points are unrelated to quadrature (i.e.,
1265 * to computing integrals) and will, in general, not be located
1266 * at Gauss points or the quadrature points of any of the typical
1267 * quadrature rules.)
1268 */
1269 DataPostprocessorTensor(const std::string &name,
1270 const UpdateFlags update_flags);
1271
1272 /**
1273 * Return the vector of strings describing the names of the computed
1274 * quantities. Given the purpose of this class, this is a vector with dim
1275 * entries all equal to the name given to the constructor.
1276 */
1277 virtual std::vector<std::string>
1278 get_names() const override;
1279
1280 /**
1281 * This function returns information about how the individual components of
1282 * output files that consist of more than one data set are to be
1283 * interpreted. Since the current class is meant to be used for a single
1284 * vector result variable, the returned value is obviously
1285 * DataComponentInterpretation::component_is_part repeated dim times.
1286 */
1287 virtual std::vector<DataComponentInterpretation::DataComponentInterpretation>
1288 get_data_component_interpretation() const override;
1289
1290 /**
1291 * Return which data has to be provided to compute the derived quantities.
1292 * The flags returned here are the ones passed to the constructor of this
1293 * class.
1294 */
1295 virtual UpdateFlags
1296 get_needed_update_flags() const override;
1297
1298 private:
1299 /**
1300 * Copies of the two arguments given to the constructor of this class.
1301 */
1302 const std::string name;
1303 const UpdateFlags update_flags;
1304 };
1305
1306
1307
1308 /**
1309 * A namespace that contains concrete implementations of data
1310 * postprocessors, i.e., non-abstract classes based on DataPostprocessor
1311 * or on the intermediate classes DataPostprocessorScalar,
1312 * DataPostprocessorVector, or DataPostprocessorTensor.
1313 */
1314 namespace DataPostprocessors
1315 {
1316 /**
1317 * A concrete data postprocessor class that can be used to output the
1318 * boundary ids of all faces. This is often useful to identify bugs in
1319 * the assignment of boundary indicators when reading meshes from input
1320 * files. See the usage example in the
1321 * @ref GlossBoundaryIndicator "glossary entry on boundary ids"
1322 * to see how this class can be used.
1323 *
1324 * @note This class is intended for use with DataOutFaces, not DataOut.
1325 * This is because it provides information about the *faces* of a
1326 * triangulation, not about cell-based information.
1327 *
1328 * By default, the DataOutFaces class function only generates
1329 * output for faces that lie on the boundary of the domain, and on these
1330 * faces, boundary indicators are available. But one can also
1331 * instruct DataOutFaces to run on internal faces as
1332 * well (by providing an argument to the constructor of the class).
1333 * At these internal faces, no boundary indicator is available because,
1334 * of course, the face is not actually at the boundary. For these
1335 * faces, the current class then outputs -1 as an indicator.
1336 */
1337 template <int dim>
1338 class BoundaryIds : public DataPostprocessorScalar<dim>
1339 {
1340 public:
1341 /**
1342 * Constructor.
1343 */
1344 BoundaryIds();
1345
1346 /**
1347 * The principal function of this class. It puts the boundary id
1348 * of each face into the appropriate output fields.
1349 */
1350 virtual void
1351 evaluate_scalar_field(
1352 const DataPostprocessorInputs::Scalar<dim> &inputs,
1353 std::vector<Vector<double>> &computed_quantities) const override;
1354 };
1355 } // namespace DataPostprocessors
1356
1357
1358
1359 #ifndef DOXYGEN
1360 // -------------------- template functions ----------------------
1361
1362 namespace DataPostprocessorInputs
1363 {
1364 template <int spacedim>
1365 template <int dim>
1366 void
1367 CommonInputs<spacedim>::set_cell(
1368 const typename DoFHandler<dim, spacedim>::cell_iterator &new_cell)
1369 {
1370 // see if we had previously already stored a cell that has the same
1371 // data type; if so, reuse the memory location and avoid calling 'new'
1372 // inside std::any
1373 if (typename DoFHandler<dim, spacedim>::cell_iterator *storage_location =
1374 std::any_cast<typename DoFHandler<dim, spacedim>::cell_iterator>(
1375 &cell))
1376 *storage_location = new_cell;
1377 else
1378 // if we had nothing stored before, or if we had stored a different
1379 // data type, just let std::any replace things
1380 cell = new_cell;
1381
1382 // Also reset the face number, just to make sure nobody
1383 // accidentally uses an outdated value.
1384 face_number = numbers::invalid_unsigned_int;
1385 }
1386
1387
1388
1389 template <int spacedim>
1390 template <int dim>
1391 void
1392 CommonInputs<spacedim>::set_cell_and_face(
1393 const typename DoFHandler<dim, spacedim>::cell_iterator &new_cell,
1394 const unsigned int new_face_number)
1395 {
1396 set_cell<dim>(new_cell);
1397 face_number = new_face_number;
1398 }
1399
1400
1401
1402 template <int spacedim>
1403 template <int dim>
1404 typename DoFHandler<dim, spacedim>::cell_iterator
1405 CommonInputs<spacedim>::get_cell() const
1406 {
1407 Assert(cell.has_value(),
1408 ExcMessage(
1409 "You are trying to access the cell associated with a "
1410 "DataPostprocessorInputs::Scalar object for which no cell has "
1411 "been set."));
1412 Assert((std::any_cast<typename DoFHandler<dim, spacedim>::cell_iterator>(
1413 &cell) != nullptr),
1414 ExcMessage(
1415 "You are trying to access the cell associated with a "
1416 "DataPostprocessorInputs::Scalar with a DoFHandler type that is "
1417 "different from the type with which it has been set. For example, "
1418 "if the cell for which output is currently being generated "
1419 "belongs to a DoFHandler<2, 3> object, then you can only call the "
1420 "current function with a template argument equal to "
1421 "DoFHandler<2, 3>, but not with any other class type or dimension "
1422 "template argument."));
1423
1424 return std::any_cast<typename DoFHandler<dim, spacedim>::cell_iterator>(
1425 cell);
1426 }
1427 } // namespace DataPostprocessorInputs
1428
1429 #endif
1430
1431 DEAL_II_NAMESPACE_CLOSE
1432
1433 #endif