Debian Codegraph @

include/deal.II/numerics/data_out_dof_data.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_data_out_dof_data_h
16 #define dealii_data_out_dof_data_h
17
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/base/data_out_base.h>
23 #include <deal.II/base/mg_level_object.h>
24 #include <deal.II/base/observer_pointer.h>
25
26 #include <deal.II/dofs/dof_handler.h>
27
28 #include <deal.II/fe/mapping.h>
29
30 #include <deal.II/grid/tria.h>
31
32 #include <deal.II/hp/fe_collection.h>
33 #include <deal.II/hp/fe_values.h>
34 #include <deal.II/hp/mapping_collection.h>
35 #include <deal.II/hp/q_collection.h>
36
37 #include <deal.II/numerics/data_component_interpretation.h>
38 #include <deal.II/numerics/data_postprocessor.h>
39
40 #include <memory>
41
42 DEAL_II_NAMESPACE_OPEN
43
44 namespace Exceptions
45 {
46 /**
47 * A namespace for exceptions that are used throughout the DataOut*
48 * collection of classes.
49 */
50 namespace DataOutImplementation
51 {
52 /**
53 * Exception
54 */
55 DeclException1(ExcInvalidNumberOfSubdivisions,
56 int,
57 << "The number of subdivisions per patch, " << arg1
58 << ", is not valid. It needs to be greater or equal to "
59 "one, or zero if you want it to be determined "
60 "automatically.");
61
62 /**
63 * Exception
64 */
65 DeclExceptionMsg(ExcNoTriangulationSelected,
66 "For the operation you are attempting, you first need to "
67 "tell the DataOut or related object which DoFHandler or "
68 "triangulation you would like to work on. This is "
69 "generally done using the 'attach_dof_handler()' or "
70 "'attach_triangulation()' member functions.");
71
72 /**
73 * Exception
74 */
75 DeclExceptionMsg(ExcNoDoFHandlerSelected,
76 "For the operation you are attempting, you first need to "
77 "tell the DataOut or related object which DoFHandler "
78 "you would like to work on. This is "
79 "generally done using the 'attach_dof_handler()' "
80 "member function.");
81
82 /**
83 * Exception
84 */
85 DeclException3(ExcInvalidVectorSize,
86 int,
87 int,
88 int,
89 << "The vector has size " << arg1
90 << " but the DoFHandler object says that there are " << arg2
91 << " degrees of freedom and there are " << arg3
92 << " active cells. The size of your vector needs to be"
93 << " either equal to the number of degrees of freedom (when"
94 << " the data is of type type_dof_data), or equal to the"
95 << " number of active cells (when the data is of type "
96 << " type_cell_data).");
97 /**
98 * Exception
99 */
100 DeclException2(
101 ExcInvalidCharacter,
102 std::string,
103 std::size_t,
104 << "Please use only the characters [a-zA-Z0-9_<>()] for" << std::endl
105 << "description strings since some graphics formats will only accept these."
106 << std::endl
107 << "The string you gave was <" << arg1
108 << ">, within which the invalid character is <" << arg1[arg2] << ">."
109 << std::endl);
110 /**
111 * Exception
112 */
113 DeclExceptionMsg(
114 ExcOldDataStillPresent,
115 "When attaching a triangulation or DoFHandler object, it is "
116 "not allowed if old data vectors are still referenced. If "
117 "you want to reuse an object of the current type, you first "
118 "need to call the 'clear_data_vector()' function.");
119 /**
120 * Exception
121 */
122 DeclException2(ExcInvalidNumberOfNames,
123 int,
124 int,
125 << "You have to give one name per component in your "
126 << "data vector. The number you gave was " << arg1
127 << ", but the number of components is " << arg2 << '.');
128 /**
129 * Exception
130 */
131 DeclExceptionMsg(ExcIncompatibleDatasetNames,
132 "While merging sets of patches, the two sets to be merged "
133 "need to refer to data that agrees on the names of the "
134 "various variables represented. In other words, you "
135 "cannot merge sets of patches that originate from "
136 "entirely unrelated simulations.");
137 /**
138 * Exception
139 */
140 DeclExceptionMsg(ExcIncompatiblePatchLists,
141 "While merging sets of patches, the two sets to be merged "
142 "need to refer to data that agrees on the number of "
143 "subdivisions and other properties. In other words, you "
144 "cannot merge sets of patches that originate from "
145 "entirely unrelated simulations.");
146
147 DeclException2(ExcInvalidVectorDeclaration,
148 int,
149 std::string,
150 << "When declaring that a number of components in a data "
151 << "set to be output logically form a vector instead of "
152 << "simply a set of scalar fields, you need to specify "
153 << "this for all relevant components. Furthermore, "
154 << "vectors must always consist of exactly <dim> "
155 << "components. However, the vector component at "
156 << "position " << arg1 << " with name <" << arg2
157 << "> does not satisfy these conditions.");
158
159 DeclException2(ExcInvalidTensorDeclaration,
160 int,
161 std::string,
162 << "When declaring that a number of components in a data "
163 << "set to be output logically form a tensor instead of "
164 << "simply a set of scalar fields, you need to specify "
165 << "this for all relevant components. Furthermore, "
166 << "tensors must always consist of exactly <dim*dim> "
167 << "components. However, the tensor component at "
168 << "position " << arg1 << " with name <" << arg2
169 << "> does not satisfy these conditions.");
170
171 } // namespace DataOutImplementation
172 } // namespace Exceptions
173
174
175 namespace internal
176 {
177 namespace DataOutImplementation
178 {
179 /**
180 * The DataEntry classes abstract away the concrete data type of vectors
181 * users can attach to DataOut (and similar) objects and allow the
182 * underlying DataOut functions to query for individual elements of solution
183 * vectors without having to know the concrete vector type. This avoids that
184 * DataOut has to know what vectors are being used, but it has the downside
185 * that DataOut also doesn't know the underlying scalar type of these
186 * vectors.
187 *
188 * If the underlying scalar types all represent real numbers (in the
189 * mathematical sense -- i.e., the scalar type would be @p float,
190 * @p double, etc) then that is not a problem -- DataOut simply
191 * receives the values of individual vector components as @p double
192 * objects. On the other hand, if the vector type uses a std::complex
193 * scalar type, then DataEntry returning a @p double for a vector
194 * entry is not sufficient -- we need to provide DataOut with a way
195 * to query both the real and the imaginary part, so that they can
196 * be written into output files separately.
197 *
198 * This enum allows DataOut to tell a DataEntry function which component
199 * of a vector entry it wants to query, i.e., whether it wants the real
200 * or the imaginary part of a vector entry.
201 */
202 enum class ComponentExtractor
203 {
204 real_part,
205 imaginary_part
206 };
207
208
209 /**
210 * For each vector that has been added through the add_data_vector()
211 * functions, we need to keep track of a pointer to it, and allow data
212 * extraction from it when we generate patches. Unfortunately, we need to
213 * do this for a number of different vector types. Fortunately, they all
214 * have the same interface. So the way we go is to have a base class that
215 * provides the functions to access the vector's information, and to have
216 * a derived template class that can be instantiated for each vector type.
217 * Since the vectors all have the same interface, this is no big problem,
218 * as they can all use the same general templatized code.
219 *
220 * @note This class is an example of the
221 * <a href="https://www.artima.com/cppsource/type_erasure.html">type
222 * erasure</a> design pattern.
223 */
224 template <int dim, int spacedim>
225 class DataEntryBase
226 {
227 public:
228 /**
229 * Constructor. Give a list of names for the individual components of
230 * the vector and their interpretation as scalar or vector data. This
231 * constructor assumes that no postprocessor is going to be used.
232 */
233 DataEntryBase(const DoFHandler<dim, spacedim> *dofs,
234 const std::vector<std::string> &names,
235 const std::vector<
236 DataComponentInterpretation::DataComponentInterpretation>
237 &data_component_interpretation);
238
239 /**
240 * Constructor when a data postprocessor is going to be used. In that
241 * case, the names and vector declarations are going to be acquired from
242 * the postprocessor.
243 */
244 DataEntryBase(const DoFHandler<dim, spacedim> *dofs,
245 const DataPostprocessor<spacedim> *data_postprocessor);
246
247 /**
248 * Destructor made virtual.
249 */
250 virtual ~DataEntryBase() = default;
251
252 /**
253 * Assuming that the stored vector is a cell vector, extract the given
254 * element from it.
255 */
256 virtual double
257 get_cell_data_value(const unsigned int cell_number,
258 const ComponentExtractor extract_component) const = 0;
259
260 /**
261 * Given a FEValuesBase object, extract the values on the present cell
262 * from the vector we actually store.
263 */
264 virtual void
265 get_function_values(const FEValuesBase<dim, spacedim> &fe_patch_values,
266 const ComponentExtractor extract_component,
267 std::vector<double> &patch_values) const = 0;
268
269 /**
270 * Given a FEValuesBase object, extract the values on the present cell
271 * from the vector we actually store. This function does the same as the
272 * one above but for vector-valued finite elements.
273 */
274 virtual void
275 get_function_values(
276 const FEValuesBase<dim, spacedim> &fe_patch_values,
277 const ComponentExtractor extract_component,
278 std::vector<dealii::Vector<double>> &patch_values_system) const = 0;
279
280 /**
281 * Given a FEValuesBase object, extract the gradients on the present
282 * cell from the vector we actually store.
283 */
284 virtual void
285 get_function_gradients(
286 const FEValuesBase<dim, spacedim> &fe_patch_values,
287 const ComponentExtractor extract_component,
288 std::vector<Tensor<1, spacedim>> &patch_gradients) const = 0;
289
290 /**
291 * Given a FEValuesBase object, extract the gradients on the present
292 * cell from the vector we actually store. This function does the same
293 * as the one above but for vector-valued finite elements.
294 */
295 virtual void
296 get_function_gradients(const FEValuesBase<dim, spacedim> &fe_patch_values,
297 const ComponentExtractor extract_component,
298 std::vector<std::vector<Tensor<1, spacedim>>>
299 &patch_gradients_system) const = 0;
300
301 /**
302 * Given a FEValuesBase object, extract the second derivatives on the
303 * present cell from the vector we actually store.
304 */
305 virtual void
306 get_function_hessians(
307 const FEValuesBase<dim, spacedim> &fe_patch_values,
308 const ComponentExtractor extract_component,
309 std::vector<Tensor<2, spacedim>> &patch_hessians) const = 0;
310
311 /**
312 * Given a FEValuesBase object, extract the second derivatives on the
313 * present cell from the vector we actually store. This function does
314 * the same as the one above but for vector-valued finite elements.
315 */
316 virtual void
317 get_function_hessians(const FEValuesBase<dim, spacedim> &fe_patch_values,
318 const ComponentExtractor extract_component,
319 std::vector<std::vector<Tensor<2, spacedim>>>
320 &patch_hessians_system) const = 0;
321
322 /**
323 * Return whether the data represented by (a derived class of) this object
324 * represents a complex-valued (as opposed to real-valued) information.
325 */
326 virtual bool
327 is_complex_valued() const = 0;
328
329 /**
330 * Clear all references to the vectors.
331 */
332 virtual void
333 clear() = 0;
334
335 /**
336 * Determine an estimate for the memory consumption (in bytes) of this
337 * object.
338 */
339 virtual std::size_t
340 memory_consumption() const = 0;
341
342 /**
343 * Pointer to the DoFHandler object that the vector is based on.
344 */
345 ObserverPointer<const DoFHandler<dim, spacedim>> dof_handler;
346
347 /**
348 * Names of the components of this data vector.
349 */
350 const std::vector<std::string> names;
351
352 /**
353 * A vector that for each of the n_output_variables variables of the
354 * current data set indicates whether they are scalar fields, parts of a
355 * vector-field, or any of the other supported kinds of data.
356 */
357 const std::vector<
358 DataComponentInterpretation::DataComponentInterpretation>
359 data_component_interpretation;
360
361 /**
362 * Pointer to a DataPostprocessing object which shall be applied to this
363 * data vector.
364 */
365 ObserverPointer<const dealii::DataPostprocessor<spacedim>> postprocessor;
366
367 /**
368 * Number of output variables this dataset provides (either number of
369 * components in vector valued function / data vector or number of
370 * computed quantities, if DataPostprocessor is applied). This variable
371 * is determined via and thus equivalent to <tt>names.size()</tt>.
372 */
373 unsigned int n_output_variables;
374 };
375
376
377 /**
378 * A data structure that holds all data needed in one thread when building
379 * patches in parallel. These data structures are created globally rather
380 * than on each cell to avoid allocation of memory in the threads. This is
381 * a base class for the AdditionalData kind of data structure discussed in
382 * the documentation of the WorkStream class.
383 *
384 * The <code>cell_to_patch_index_map</code> is an array that stores for
385 * index <tt>[i][j]</tt> the number of the patch that associated with the
386 * cell with index @p j on level @p i. This information is set up prior to
387 * generation of the patches, and is needed to generate neighborship
388 * information.
389 *
390 * This structure is used by several of the DataOut* classes, which
391 * derived their own ParallelData classes from it for additional fields.
392 */
393 template <int dim, int spacedim>
394 struct ParallelDataBase
395 {
396 ParallelDataBase(
397 const unsigned int n_datasets,
398 const unsigned int n_subdivisions,
399 const std::vector<unsigned int> &n_postprocessor_outputs,
400 const Mapping<dim, spacedim> &mapping,
401 const std::vector<
402 std::shared_ptr<dealii::hp::FECollection<dim, spacedim>>>
403 &finite_elements,
404 const UpdateFlags update_flags,
405 const bool use_face_values);
406
407 ParallelDataBase(
408 const unsigned int n_datasets,
409 const unsigned int n_subdivisions,
410 const std::vector<unsigned int> &n_postprocessor_outputs,
411 const dealii::hp::MappingCollection<dim, spacedim> &mapping,
412 const std::vector<
413 std::shared_ptr<dealii::hp::FECollection<dim, spacedim>>>
414 &finite_elements,
415 const UpdateFlags update_flags,
416 const bool use_face_values);
417
418 ParallelDataBase(const ParallelDataBase &data);
419
420 void
421 reinit_all_fe_values(
422 std::vector<std::shared_ptr<DataEntryBase<dim, spacedim>>> &dof_data,
423 const typename dealii::Triangulation<dim, spacedim>::cell_iterator
424 &cell,
425 const unsigned int face = numbers::invalid_unsigned_int);
426
427 const FEValuesBase<dim, spacedim> &
428 get_present_fe_values(const unsigned int dataset) const;
429
430 void
431 resize_system_vectors(const unsigned int n_components);
432
433 const unsigned int n_datasets;
434 const unsigned int n_subdivisions;
435
436 DataPostprocessorInputs::Scalar<spacedim> patch_values_scalar;
437 DataPostprocessorInputs::Vector<spacedim> patch_values_system;
438 std::vector<std::vector<dealii::Vector<double>>> postprocessed_values;
439
440 const dealii::hp::MappingCollection<dim, spacedim> mapping_collection;
441 const std::vector<
442 std::shared_ptr<dealii::hp::FECollection<dim, spacedim>>>
443 finite_elements;
444 const UpdateFlags update_flags;
445
446 std::vector<std::shared_ptr<dealii::hp::FEValues<dim, spacedim>>>
447 x_fe_values;
448 std::vector<std::shared_ptr<dealii::hp::FEFaceValues<dim, spacedim>>>
449 x_fe_face_values;
450 };
451 } // namespace DataOutImplementation
452 } // namespace internal
453
454
455 // TODO: Most of the documentation of DataOut_DoFData applies to DataOut.
456
457 /**
458 * This is an abstract class which provides the functionality to generate
459 * patches for output by base classes from data vectors on a grid. It allows
460 * to attach one or more pointers to a DoFHandler and attached node and cell
461 * data denoting functions on the grid which shall later be written in any of
462 * the implemented data formats.
463 *
464 *
465 * <h3>User visible interface</h3>
466 *
467 * The user visible interface of this class allows the user to specify data in
468 * two different ways. One is to make a DoFHandler object known to this class
469 * and to add data vectors that all correspond to this DoFHandler or the grid
470 * cells which will later be written to a file in some format. The second
471 * approach is to pass a DoFHandler object along with the vector. This allows
472 * setting data from different DoFHandlers in a neat way (of course, they both
473 * need to be based on the same triangulation). Instead of pondering about the
474 * different functions, an example for the first kind is probably the best
475 * explanation:
476 * @code
477 * ...
478 * ... // compute solution, which contains nodal values
479 * ...
480 * ... // compute error_estimator, which contains one value per cell
481 *
482 * std::vector<std::string> solution_names;
483 * solution_names.emplace_back ("x-displacement");
484 * solution_names.emplace_back ("y-displacement");
485 *
486 * DataOut<dim> data_out;
487 * data_out.attach_dof_handler (dof_handler);
488 * data_out.add_data_vector (solution, solution_names);
489 * data_out.add_data_vector (error_estimator, "estimated_error");
490 *
491 * data_out.build_patches ();
492 *
493 * ofstream output_file ("output");
494 * data_out.write_xxx (output_file);
495 *
496 * data_out.clear();
497 * @endcode
498 *
499 * attach_dof_handler() tells this class that all future operations are to
500 * take place with the DoFHandler object and the triangulation it lives on. We
501 * then add the solution vector and the error estimator; note that they have
502 * different dimensions, because the solution is a nodal vector, here
503 * consisting of two components ("x-displacement" and "y-displacement") while
504 * the error estimator probably is a vector holding cell data. When attaching
505 * a data vector, you have to give a name to each component of the vector,
506 * which is done through an object of type <tt>vector<string></tt> as second
507 * argument; if only one component is in the vector, for example if we are
508 * adding cell data as in the second case, or if the finite element used by
509 * the DoFHandler has only one component, then you can use the second
510 * add_data_vector() function which takes a @p string instead of the
511 * <tt>vector<string></tt>.
512 *
513 * The add_data_vector() functions have additional arguments (with default
514 * values) that can be used to specify certain transformations. In particular,
515 * it allows to attach DataPostprocessor arguments to compute derived
516 * information from a data vector at each point at which the field will be
517 * evaluated so that it can be written to a file (for example, the Mach number
518 * in hypersonic flow can be computed from density and velocities; step-29
519 * also shows an example); another piece of information specified through
520 * arguments with default values is how certain output components should be
521 * interpreted, i.e. whether each component of the data is logically an
522 * independent scalar field, or whether some of them together form logically a
523 * vector-field (see the
524 * DataComponentInterpretation::DataComponentInterpretation enum, and the
525 * @ref step_22 "step-22"
526 * tutorial program).
527 *
528 * After adding all data vectors, you need to call a function which generates
529 * the patches (i.e., some intermediate data representation) for output from
530 * the stored data. Derived classes name this function build_patches().
531 * Finally, you write() the data in one format or other, to a file.
532 *
533 * In the example above, an object of type DataOut was used, i.e. an object of
534 * a derived class. This is necessary since the current class does not provide
535 * means to actually generate the patches, only aids to store and access data.
536 * Any real functionality is implemented in derived classes such as DataOut.
537 *
538 * Note that the base class of this class, DataOutInterface offers several
539 * functions to ease programming with run-time determinable output formats
540 * (i.e. you need not use a fixed format by calling
541 * DataOutInterface::write_xxx in the above example, but you can select it by
542 * a run-time parameter without having to write the <tt>if () ... else
543 * ...</tt> clauses yourself), and also functions and classes offering ways to
544 * control the appearance of the output by setting flags for each output
545 * format.
546 *
547 *
548 * <h3>Information for derived classes</h3>
549 *
550 * What this class lacks is a way to produce the patches for output itself,
551 * from the stored data and degree of freedom information. Since this task is
552 * often application dependent it is left to derived classes. For example, in
553 * many applications, it might be wanted to limit the depth of output to a
554 * certain number of refinement levels and write data from finer cells only in
555 * a way interpolated to coarser cells, to reduce the amount of output. Also,
556 * it might be wanted to use different numbers of subdivisions on different
557 * cells when forming a patch, for example to accomplish for different
558 * polynomial degrees of the trial space on different cells. Also, the output
559 * need not necessarily consist of a patch for each cell, but might be made up
560 * of patches for faces, of other things. Take a look at derived classes to
561 * what is possible in this respect.
562 *
563 * For this reason, it is left to a derived class to provide a function, named
564 * usually build_patches() or the like, which fills the #patches array of this
565 * class.
566 *
567 * Regarding the templates of this class, it needs three values: first the
568 * space dimension in which the triangulation and the DoF handler operate,
569 * second the dimension of the objects which the patches represent. Although
570 * in most cases they are equal, there are also classes for which this does
571 * not hold, for example if one outputs the result of a computation exploiting
572 * rotational symmetry in the original domain (in which the space dimension of
573 * the output would be one higher than that of the DoF handler, see the
574 * DataOut_Rotation() class), or one might conceive that one could write a
575 * class that only outputs the solution on a cut through the domain, in which
576 * case the space dimension of the output is less than that of the DoF
577 * handler. The last template argument denotes the dimension of the space into
578 * which the patches are embedded; usually, this dimension is the same as the
579 * dimensio of the patches themselves (which is also the default value of the
580 * template parameter), but there might be cases where this is not so. For
581 * example, in the DataOut_Faces() class, patches are generated from faces of
582 * the triangulation. Thus, the dimension of the patch is one less than the
583 * dimension of the embedding space, which is, in this case, equal to the
584 * dimension of the triangulation and DoF handler. However, for the cut
585 * through the domain mentioned above, if the cut is a straight one, then the
586 * cut can be embedded into a space of one dimension lower than the dimension
587 * of the triangulation, so that the last template parameter has the same
588 * value as the second one.
589 *
590 * @ingroup output
591 */
592 template <int dim,
593 int patch_dim,
594 int spacedim = dim,
595 int patch_spacedim = patch_dim>
596 class DataOut_DoFData : public DataOutInterface<patch_dim, patch_spacedim>
597 {
598 public:
599 /**
600 * Typedef to the iterator type of the dof handler class under
601 * consideration.
602 */
603 using cell_iterator = typename Triangulation<dim, spacedim>::cell_iterator;
604
605 public:
606 /**
607 * Type describing what the vector given to add_data_vector() is: a vector
608 * that has one entry per degree of freedom in a DoFHandler object (such as
609 * solution vectors), or one entry per cell in the triangulation underlying
610 * the DoFHandler object (such as error per cell data). The value
611 * #type_automatic tells add_data_vector() to find out itself (see the
612 * documentation of add_data_vector() for the method used).
613 */
614 enum DataVectorType
615 {
616 /**
617 * Data vector entries are associated to degrees of freedom
618 */
619 type_dof_data,
620
621 /**
622 * Data vector entries are one per grid cell
623 */
624 type_cell_data,
625
626 /**
627 * Find out automatically
628 */
629 type_automatic
630 };
631
632 /**
633 * Constructor
634 */
635 DataOut_DoFData();
636
637 /**
638 * Destructor.
639 */
640 virtual ~DataOut_DoFData() override;
641
642 /**
643 * Designate a dof handler to be used to extract geometry data and the
644 * mapping between nodes and node values. This call is not necessary if all
645 * added data vectors are supplemented with a DoFHandler argument.
646 *
647 * This call is optional: If you add data vectors with specified DoFHandler
648 * object, then that contains all information needed to generate the output.
649 */
650 void
651 attach_dof_handler(const DoFHandler<dim, spacedim> &);
652
653 /**
654 * Designate a triangulation to be used to extract geometry data and the
655 * mapping between nodes and node values.
656 *
657 * This call is optional: If you add data vectors with specified DoFHandler
658 * object, then that contains all information needed to generate the output.
659 * This call is useful when you only output cell vectors and no DoFHandler
660 * at all, in which case it provides the geometry.
661 */
662 void
663 attach_triangulation(const Triangulation<dim, spacedim> &);
664
665 /**
666 * Add a data vector together with its name.
667 *
668 * A pointer to the vector is stored, so you have to make sure the vector
669 * exists at that address at least as long as you call the <tt>write_*</tt>
670 * functions.
671 *
672 * It is assumed that the vector has the same number of components as there
673 * are degrees of freedom in the dof handler, in which case it is assumed to
674 * be a vector storing nodal data; or the size may be the number of active
675 * cells on the present grid, in which case it is assumed to be a cell data
676 * vector. As the number of degrees of freedom and of cells is usually not
677 * equal, the function can determine itself which type of vector it is
678 * given. However, there are corner cases where this automatic determination
679 * does not work. One example is if you compute with piecewise constant
680 * elements and have a scalar solution, then there are as many cells as
681 * there are degrees of freedom (though they may be numbered differently).
682 * Another possibility is if you have a 1d mesh embedded in 2d space and the
683 * mesh consists of a closed curve of cells; in this case, there are as many
684 * nodes as there are cells, and when using a Q1 element you will have as
685 * many degrees of freedom as there are cells. In these cases, you can
686 * change the last argument of the function from its default value
687 * #type_automatic to either #type_dof_data or #type_cell_data, depending on
688 * what the vector represents. Apart from such corner cases, you can leave
689 * the argument at its default value and let the function determine the type
690 * of the vector itself.
691 *
692 * If it is a vector holding DoF data, the names given shall be one for each
693 * component of the underlying finite element. If it is a finite element
694 * composed of only one subelement, then there is another function following
695 * which takes a single name instead of a vector of names.
696 *
697 * The data_component_interpretation argument contains information about how
698 * the individual components of output files that consist of more than one
699 * data set are to be interpreted.
700 *
701 * For example, if one has a finite element for the Stokes equations in 2d,
702 * representing components (u,v,p), one would like to indicate that the
703 * first two, u and v, represent a logical vector so that later on when we
704 * generate graphical output we can hand them off to a visualization program
705 * that will automatically know to render them as a vector field, rather
706 * than as two separate and independent scalar fields.
707 *
708 * The default value of this argument (i.e. an empty vector) corresponds is
709 * equivalent to a vector of values
710 * DataComponentInterpretation::component_is_scalar, indicating that all
711 * output components are independent scalar fields. However, if the given
712 * data vector represents logical vectors, you may pass a vector that
713 * contains values DataComponentInterpretation::component_is_part_of_vector.
714 * In the example above, one would pass in a vector with components
715 * (DataComponentInterpretation::component_is_part_of_vector,
716 * DataComponentInterpretation::component_is_part_of_vector,
717 * DataComponentInterpretation::component_is_scalar) for (u,v,p).
718 *
719 * The names of a data vector shall only contain characters which are
720 * letters, underscore and a few other ones. Refer to the
721 * ExcInvalidCharacter exception declared in this class to see which
722 * characters are valid and which are not.
723 *
724 * @note The actual type for the vector argument may be any vector type from
725 * which FEValues can extract values on a cell using the
726 * FEValuesBase::get_function_values() function.
727 */
728 template <typename VectorType>
729 void
730 add_data_vector(
731 const VectorType &data,
732 const std::vector<std::string> &names,
733 const DataVectorType type = type_automatic,
734 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
735 &data_component_interpretation = {});
736
737 /**
738 * This function is an abbreviation to the above one (see there for a
739 * discussion of the various arguments), intended for use with finite
740 * elements that are not composed of subelements. In this case, only one
741 * name per data vector needs to be given, which is what this function
742 * takes. It simply relays its arguments after a conversion of the @p name
743 * to a vector of strings, to the other add_data_vector() function above.
744 *
745 * If @p data is a vector with multiple components this function will
746 * generate distinct names for all components by appending an underscore and
747 * the number of each component to @p name
748 *
749 * The actual type for the template argument may be any vector type from
750 * which FEValues can extract values on a cell using the
751 * FEValuesBase::get_function_values() function.
752 */
753 template <typename VectorType>
754 void
755 add_data_vector(
756 const VectorType &data,
757 const std::string &name,
758 const DataVectorType type = type_automatic,
759 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
760 &data_component_interpretation = {});
761
762 /**
763 * This function is an extension of the above one (see there for a
764 * discussion of the arguments except the first one) and allows to set a
765 * vector with its own DoFHandler object. This DoFHandler needs to be
766 * compatible with the other DoFHandler objects assigned with calls to @p
767 * add_data_vector or @p attach_dof_handler, in the sense that all of the
768 * DoFHandler objects need to be based on the same triangulation. This
769 * function allows you to export data from multiple DoFHandler objects that
770 * describe different solution components. An example of using this function
771 * is given in step-61.
772 *
773 * Since this function takes a DoFHandler object and hence naturally
774 * represents dof data, the data vector type argument present in the other
775 * methods above is not necessary.
776 */
777 template <typename VectorType>
778 void
779 add_data_vector(
780 const DoFHandler<dim, spacedim> &dof_handler,
781 const VectorType &data,
782 const std::vector<std::string> &names,
783 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
784 &data_component_interpretation = {});
785
786
787 /**
788 * This function is an abbreviation of the function above with only a scalar
789 * @p dof_handler given and a single data name.
790 */
791 template <typename VectorType>
792 void
793 add_data_vector(
794 const DoFHandler<dim, spacedim> &dof_handler,
795 const VectorType &data,
796 const std::string &name,
797 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
798 &data_component_interpretation = {});
799
800 /**
801 * This function is an alternative to the above ones, allowing the output of
802 * derived quantities instead of the given data. This conversion has to be
803 * done in a class derived from DataPostprocessor. This function is used in
804 * step-29. Other uses are shown in step-32 and step-33.
805 *
806 * The names for these derived quantities are provided by the @p
807 * data_postprocessor argument. Likewise, the data_component_interpretation
808 * argument of the other add_data_vector() functions is provided by the
809 * data_postprocessor argument. As only data of type @p type_dof_data can be
810 * transformed, this type is also known implicitly and does not have to be
811 * given.
812 *
813 * @note The actual type for the vector argument may be any vector type from
814 * which FEValues can extract values on a cell using the
815 * FEValuesBase::get_function_values() function.
816 *
817 * @note The DataPostprocessor object (i.e., in reality the object of your
818 * derived class) has to live until the DataOut object is destroyed as the
819 * latter keeps a pointer to the former and will complain if the object
820 * pointed to is destroyed while the latter still has a pointer to it. If
821 * both the data postprocessor and DataOut objects are local variables of a
822 * function (as they are, for example, in step-29), then you can avoid this
823 * error by declaring the data postprocessor variable before the DataOut
824 * variable as objects are destroyed in reverse order of declaration.
825 */
826 template <typename VectorType>
827 void
828 add_data_vector(const VectorType &data,
829 const DataPostprocessor<spacedim> &data_postprocessor);
830
831 /**
832 * Same function as above, but with a DoFHandler object that does not need
833 * to coincide with the DoFHandler initially set. Note that the
834 * postprocessor can only read data from the given DoFHandler and solution
835 * vector, not other solution vectors or DoFHandlers.
836 */
837 template <typename VectorType>
838 void
839 add_data_vector(const DoFHandler<dim, spacedim> &dof_handler,
840 const VectorType &data,
841 const DataPostprocessor<spacedim> &data_postprocessor);
842
843 /**
844 * Add a multilevel data vector.
845 *
846 * This function adds the vector-valued multilevel vector @p data in the
847 * form of a vector on each level that belongs to the DoFHandler @p
848 * dof_handler to the graphical output. This function is typically used in
849 * conjunction with a call to set_cell_selection() that selects cells on a
850 * specific level and not the active cells (the default).
851 *
852 * A vector @p data can be obtained in several ways, for example by using
853 * Multigrid::solution or Multigrid::defect during or after a multigrid
854 * cycle or by interpolating a solution via
855 * MGTransferMatrixFree::interpolate_to_mg().
856 *
857 * The handling of @p names and @p data_component_interpretation is identical
858 * to the add_data_vector() function.
859 */
860 template <typename VectorType>
861 void
862 add_mg_data_vector(
863 const DoFHandler<dim, spacedim> &dof_handler,
864 const MGLevelObject<VectorType> &data,
865 const std::vector<std::string> &names,
866 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
867 &data_component_interpretation = std::vector<
868 DataComponentInterpretation::DataComponentInterpretation>());
869
870 /**
871 * Scalar version of the function above.
872 */
873 template <typename VectorType>
874 void
875 add_mg_data_vector(const DoFHandler<dim, spacedim> &dof_handler,
876 const MGLevelObject<VectorType> &data,
877 const std::string &name);
878
879 /**
880 * Release the pointers to the data vectors. This allows output of a new set
881 * of vectors without supplying the DoF handler again. Therefore, the
882 * DataOut object can be used in an algebraic context. Note that besides the
883 * data vectors also the patches already computed are deleted.
884 */
885 void
886 clear_data_vectors();
887
888 /**
889 * Release pointers to all input data elements, i.e. pointers to
890 * the DoF handler object. This function may be useful when
891 * you have called the @p build_patches function of derived class, since
892 * then the patches are built and the input data is no more needed, nor is
893 * there a need to reference it. You can then output the patches detached
894 * from the main thread and need not make sure anymore that the DoF handler
895 * object must not be deleted before the output thread is
896 * finished.
897 */
898 void
899 clear_input_data_references();
900
901 /**
902 * This function can be used to merge the patches that were created using
903 * the @p build_patches function of the object given as argument into the
904 * list of patches created by this object. This is sometimes handy if one
905 * has, for example, a domain decomposition algorithm where each block is
906 * represented by a DoFHandler of its own, but one wants to output the
907 * solution on all the blocks at the same time.
908 *
909 * For this to work, the given argument and this object need to have the
910 * same number of output vectors, and they need to use the same number of
911 * subdivisions per patch. The output will probably look rather funny if
912 * patches in both objects overlap in space.
913 *
914 * If you call build_patches() for this object after merging in patches, the
915 * previous state is overwritten, and the merged-in patches are lost.
916 *
917 * The second parameter allows to shift each node of the patches in the
918 * object passed in the first parameter by a certain amount. This is
919 * sometimes useful to generate "exploded" views of a collection of blocks.
920 *
921 * This function will fail if either this or the other object did not yet
922 * set up any patches.
923 */
924 template <int dim2, int spacedim2>
925 void
926 merge_patches(
927 const DataOut_DoFData<dim2, patch_dim, spacedim2, patch_spacedim> &source,
928 const Point<patch_spacedim> &shift = Point<patch_spacedim>());
929
930 /**
931 * Release the pointers to the data vectors and the DoF handler. You have to
932 * set all data entries again using the add_data_vector() function. The
933 * pointer to the dof handler is cleared as well, along with all other data.
934 * In effect, this function resets everything to an empty state.
935 */
936 virtual void
937 clear();
938
939 /**
940 * Determine an estimate for the memory consumption (in bytes) of this
941 * object.
942 */
943 std::size_t
944 memory_consumption() const;
945
946 protected:
947 /**
948 * Abbreviate the somewhat lengthy name for the Patch class.
949 */
950 using Patch = dealii::DataOutBase::Patch<patch_dim, patch_spacedim>;
951
952 /**
953 * Pointer to the triangulation object.
954 */
955 ObserverPointer<const Triangulation<dim, spacedim>> triangulation;
956
957 /**
958 * Pointer to the optional handler object.
959 */
960 ObserverPointer<const DoFHandler<dim, spacedim>> dofs;
961
962 /**
963 * List of data elements with vectors of values for each degree of freedom.
964 */
965 std::vector<std::shared_ptr<
966 internal::DataOutImplementation::DataEntryBase<dim, spacedim>>>
967 dof_data;
968
969 /**
970 * List of data elements with vectors of values for each cell.
971 */
972 std::vector<std::shared_ptr<
973 internal::DataOutImplementation::DataEntryBase<dim, spacedim>>>
974 cell_data;
975
976 /**
977 * This is a list of patches that is created each time build_patches() is
978 * called. These patches are used in the output routines of the base
979 * classes.
980 */
981 std::vector<Patch> patches;
982
983 /**
984 * %Function by which the base class's functions get to know what patches
985 * they shall write to a file.
986 */
987 public:
988 virtual const std::vector<Patch> &
989 get_patches() const override;
990
991 protected:
992 /**
993 * Virtual function through which the names of data sets are obtained by the
994 * output functions of the base class.
995 */
996 virtual std::vector<std::string>
997 get_dataset_names() const override;
998
999 /**
1000 * Overload of the respective DataOutInterface::get_nonscalar_data_ranges()
1001 * function. See there for a more extensive documentation.
1002 */
1003 virtual std::vector<
1004 std::tuple<unsigned int,
1005 unsigned int,
1006 std::string,
1007 DataComponentInterpretation::DataComponentInterpretation>>
1008 get_nonscalar_data_ranges() const override;
1009
1010 protected:
1011 /**
1012 * Extracts the finite elements stored in the dof_data object, including a
1013 * dummy object of FE_DGQ<dim>(0) in case only the triangulation is used.
1014 */
1015 std::vector<std::shared_ptr<dealii::hp::FECollection<dim, spacedim>>>
1016 get_fes() const;
1017
1018 // Make all template siblings friends. Needed for the merge_patches()
1019 // function.
1020 template <int, int, int, int>
1021 friend class DataOut_DoFData;
1022
1023 /**
1024 */
1025 template <int, class>
1026 friend class MGDataOut;
1027
1028 private:
1029 /**
1030 * Common function called by the four public add_data_vector methods.
1031 */
1032 template <typename VectorType>
1033 void
1034 add_data_vector_internal(
1035 const DoFHandler<dim, spacedim> *dof_handler,
1036 const VectorType &data,
1037 const std::vector<std::string> &names,
1038 const DataVectorType type,
1039 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1040 &data_component_interpretation,
1041 const bool deduce_output_names);
1042 };
1043
1044
1045
1046 // -------------------- template and inline functions ------------------------
1047 template <int dim, int patch_dim, int spacedim, int patch_spacedim>
1048 template <typename VectorType>
1049 void
1050 DataOut_DoFData<dim, patch_dim, spacedim, patch_spacedim>::add_data_vector(
1051 const VectorType &vec,
1052 const std::string &name,
1053 const DataVectorType type,
1054 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1055 &data_component_interpretation)
1056 {
1057 Assert(triangulation != nullptr,
1058 Exceptions::DataOutImplementation::ExcNoTriangulationSelected());
1059 std::vector<std::string> names(1, name);
1060 add_data_vector_internal(
1061 dofs, vec, names, type, data_component_interpretation, true);
1062 }
1063
1064
1065
1066 template <int dim, int patch_dim, int spacedim, int patch_spacedim>
1067 template <typename VectorType>
1068 void
1069 DataOut_DoFData<dim, patch_dim, spacedim, patch_spacedim>::add_data_vector(
1070 const VectorType &vec,
1071 const std::vector<std::string> &names,
1072 const DataVectorType type,
1073 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1074 &data_component_interpretation)
1075 {
1076 Assert(triangulation != nullptr,
1077 Exceptions::DataOutImplementation::ExcNoTriangulationSelected());
1078 add_data_vector_internal(
1079 dofs, vec, names, type, data_component_interpretation, false);
1080 }
1081
1082
1083
1084 template <int dim, int patch_dim, int spacedim, int patch_spacedim>
1085 template <typename VectorType>
1086 void
1087 DataOut_DoFData<dim, patch_dim, spacedim, patch_spacedim>::add_data_vector(
1088 const DoFHandler<dim, spacedim> &dof_handler,
1089 const VectorType &data,
1090 const std::string &name,
1091 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1092 &data_component_interpretation)
1093 {
1094 std::vector<std::string> names(1, name);
1095 add_data_vector_internal(&dof_handler,
1096 data,
1097 names,
1098 type_dof_data,
1099 data_component_interpretation,
1100 true);
1101 }
1102
1103
1104
1105 template <int dim, int patch_dim, int spacedim, int patch_spacedim>
1106 template <typename VectorType>
1107 void
1108 DataOut_DoFData<dim, patch_dim, spacedim, patch_spacedim>::add_data_vector(
1109 const DoFHandler<dim, spacedim> &dof_handler,
1110 const VectorType &data,
1111 const std::vector<std::string> &names,
1112 const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1113 &data_component_interpretation)
1114 {
1115 add_data_vector_internal(&dof_handler,
1116 data,
1117 names,
1118 type_dof_data,
1119 data_component_interpretation,
1120 false);
1121 }
1122
1123
1124
1125 template <int dim, int patch_dim, int spacedim, int patch_spacedim>
1126 template <typename VectorType>
1127 void
1128 DataOut_DoFData<dim, patch_dim, spacedim, patch_spacedim>::add_data_vector(
1129 const VectorType &vec,
1130 const DataPostprocessor<spacedim> &data_postprocessor)
1131 {
1132 Assert(dofs != nullptr,
1133 Exceptions::DataOutImplementation::ExcNoDoFHandlerSelected());
1134 add_data_vector(*dofs, vec, data_postprocessor);
1135 }
1136
1137
1138
1139 template <int dim, int patch_dim, int spacedim, int patch_spacedim>
1140 template <int dim2, int spacedim2>
1141 void
1142 DataOut_DoFData<dim, patch_dim, spacedim, patch_spacedim>::merge_patches(
1143 const DataOut_DoFData<dim2, patch_dim, spacedim2, patch_spacedim> &source,
1144 const Point<patch_spacedim> &shift)
1145 {
1146 const std::vector<Patch> &source_patches = source.get_patches();
1147 Assert((patches.size() != 0) && (source_patches.size() != 0),
1148 ExcMessage("When calling this function, both the current "
1149 "object and the one being merged need to have a "
1150 "nonzero number of patches associated with it. "
1151 "Either you called this function on objects that "
1152 "are empty, or you may have forgotten to call "
1153 "the 'build_patches()' function."));
1154 // Check equality of component names
1155 Assert(get_dataset_names() == source.get_dataset_names(),
1156 Exceptions::DataOutImplementation::ExcIncompatibleDatasetNames());
1157
1158 // Make sure patches are compatible. Ideally, we would check that all input
1159 // patches from both collections are all compatible, but we'll be content
1160 // with checking that just the first ones from both sources are.
1161 //
1162 // We check compatibility by testing that both sets of patches result
1163 // from the same number of subdivisions, and that they have the same
1164 // number of source vectors (they really should, since we already checked
1165 // that there are the same number of source components above, but you
1166 // never know). This implies that the data should have the same number of
1167 // columns. They should really have the same number of rows as well,
1168 // but depending on whether a patch has points included or not, the
1169 // number of rows may or may not include coordinates for the points,
1170 // and the comparison has to account for that because in each source
1171 // stream, the patches may include some that have points included.
1172 Assert(patches[0].n_subdivisions == source_patches[0].n_subdivisions,
1173 Exceptions::DataOutImplementation::ExcIncompatiblePatchLists());
1174 Assert(patches[0].data.n_cols() == source_patches[0].data.n_cols(),
1175 Exceptions::DataOutImplementation::ExcIncompatiblePatchLists());
1176 Assert((patches[0].data.n_rows() +
1177 (patches[0].points_are_available ? 0 : patch_spacedim)) ==
1178 (source_patches[0].data.n_rows() +
1179 (source_patches[0].points_are_available ? 0 : patch_spacedim)),
1180 Exceptions::DataOutImplementation::ExcIncompatiblePatchLists());
1181
1182 // check equality of the vector data
1183 // specifications
1184 Assert(get_nonscalar_data_ranges().size() ==
1185 source.get_nonscalar_data_ranges().size(),
1186 ExcMessage("Both sources need to declare the same components "
1187 "as vectors."));
1188 for (unsigned int i = 0; i < get_nonscalar_data_ranges().size(); ++i)
1189 {
1190 Assert(std::get<0>(get_nonscalar_data_ranges()[i]) ==
1191 std::get<0>(source.get_nonscalar_data_ranges()[i]),
1192 ExcMessage("Both sources need to declare the same components "
1193 "as vectors."));
1194 Assert(std::get<1>(get_nonscalar_data_ranges()[i]) ==
1195 std::get<1>(source.get_nonscalar_data_ranges()[i]),
1196 ExcMessage("Both sources need to declare the same components "
1197 "as vectors."));
1198 Assert(std::get<2>(get_nonscalar_data_ranges()[i]) ==
1199 std::get<2>(source.get_nonscalar_data_ranges()[i]),
1200 ExcMessage("Both sources need to declare the same components "
1201 "as vectors."));
1202 }
1203
1204 // merge patches. store old number
1205 // of elements, since we need to
1206 // adjust patch numbers, etc
1207 // afterwards
1208 const unsigned int old_n_patches = patches.size();
1209 patches.insert(patches.end(), source_patches.begin(), source_patches.end());
1210
1211 // perform shift, if so desired
1212 if (shift != Point<patch_spacedim>())
1213 for (unsigned int i = old_n_patches; i < patches.size(); ++i)
1214 for (const unsigned int v : GeometryInfo<patch_dim>::vertex_indices())
1215 patches[i].vertices[v] += shift;
1216
1217 // adjust patch numbers
1218 for (unsigned int i = old_n_patches; i < patches.size(); ++i)
1219 patches[i].patch_index += old_n_patches;
1220
1221 // adjust patch neighbors
1222 for (unsigned int i = old_n_patches; i < patches.size(); ++i)
1223 for (const unsigned int n : GeometryInfo<patch_dim>::face_indices())
1224 if (patches[i].neighbors[n] != Patch::no_neighbor)
1225 patches[i].neighbors[n] += old_n_patches;
1226 }
1227
1228
1229 DEAL_II_NAMESPACE_CLOSE
1230
1231 #endif