Debian Codegraph @

include/deal.II/base/data_out_base.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_base_h
16 #define dealii_data_out_base_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/geometry_info.h>
22 #include <deal.II/base/mpi_stub.h>
23 #include <deal.II/base/point.h>
24 #include <deal.II/base/table.h>
25
26 #include <deal.II/grid/reference_cell.h>
27
28 #include <deal.II/numerics/data_component_interpretation.h>
29
30 // To be able to serialize XDMFEntry
31 #include <boost/serialization/map.hpp>
32
33 #include <limits>
34 #include <ostream>
35 #include <string>
36 #include <tuple>
37 #include <typeinfo>
38 #include <vector>
39
40 DEAL_II_NAMESPACE_OPEN
41
42 // Forward declarations
43 #ifndef DOXYGEN
44 class ParameterHandler;
45 class XDMFEntry;
46 #endif
47
48 /**
49 * This is a base class for output of data on meshes of very general form.
50 * Output data is expected as a set of <tt>patches</tt> and written to the
51 * output stream in the format expected by the visualization tool. For a list
52 * of output formats, check the enumeration #OutputFormat. For each format
53 * listed there, this class contains a function <tt>write_format</tt>, writing
54 * the output. Refer to the documentation of those functions for details on a
55 * certain format.
56 *
57 * <h3>Structure of the output data</h3>
58 *
59 * Data is not written with the deal.II mesh structure. Instead, it relies on
60 * a set of <tt>patches</tt> created by a derived class (for example the
61 * DataOut, DataOutStack, DataOutFaces, DataOutRotation, or MatrixOut
62 * classes). Each Patch describes a single logical cell of a mesh, possibly
63 * subdivided a number of times to represent higher order polynomials defined
64 * on this cell. To this end, a patch consists of a <tt>dim</tt>-dimensional
65 * regular grid with the same number of grid points in each direction. In the
66 * simplest case it may consist of the corner points of a single mesh cell.
67 * For each point of this local grid, the Patch contains an arbitrary number
68 * of data values, though the number of data sets must be the same for each
69 * point on each patch.
70 *
71 * By offering this interface to the different output formats, it is simple to
72 * extend this class to new formats without depending on such things as actual
73 * triangulations and handling of data vectors. These things shall be provided
74 * by derived class which have a user callable interface then.
75 *
76 * Inside each patch, the data is organized in the usual lexicographical
77 * order, <i>x</i> running fastest, then <i>y</i> and <i>z</i>. Nodes are
78 * stored in this order and cells as well. Each cell in 3d is stored such that
79 * the front face is in the <i>xz</i>-plane. In order to enhance
80 * intelligibility of this concept, the following two sections are kept from a
81 * previous version of this documentation.
82 *
83 *
84 * <h4>Patches</h4>
85 *
86 * Grids can be thought of as a collection of cells; if you want to write out
87 * data on such a grid, you can do so by writing them one cell at a time. The
88 * functions in this class therefore take a list of objects describing the
89 * data on one cell each. This data for each cell usually consists of a list
90 * of vertices for this cell, and a list of data values (for example solution
91 * data, error information, etc) at each of these vertices.
92 *
93 * In some cases, this interface to a cell is too restricted, however. For
94 * example, you may have higher order elements and printing the values at the
95 * vertices only is not enough. For this reason, we not only provide writing
96 * the data on the vertices only, but the data is organizes as a tensor
97 * product grid on each cell. The parameter <tt>n_subdivisions</tt>, which is
98 * given for each patch separately, denotes how often the cell is to be
99 * divided for output; for example, <tt>n_subdivisions==1</tt> yields no
100 * subdivision of the cell, <tt>n_subdivisions==2</tt> will produce a grid of
101 * 3 times 3 points in two spatial dimensions and 3 times 3 times 3 points in
102 * three dimensions, <tt>n_subdivisions==3</tt> will yield 4 times 4 (times 4)
103 * points, etc. The actual location of these points on the patch will be
104 * computed by a multilinear transformation from the vertices given for this
105 * patch. For cells at the boundary, a mapping might be used to calculate the
106 * position of the inner points. In that case the coordinates are stored
107 * inside the Patch, as they cannot be easily recovered otherwise.
108 *
109 * Given these comments, the actual data to be printed on this patch of points
110 * consists of several data sets each of which has a value at each of the
111 * patch points. For example with <tt>n_subdivisions==2</tt> in two space
112 * dimensions, each data set has to provide nine values, and since the patch
113 * is to be printed as a tensor product (or its transformation to the real
114 * space cell), its values are to be ordered like <i>(x0,y0) (x0,y1) (x0,y2)
115 * (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2)</i>, i.e. the z-coordinate
116 * runs fastest, then the y-coordinate, then x (if there are that many space
117 * directions).
118 *
119 *
120 * <h4>Generalized patches</h4>
121 *
122 * In general, the patches as explained above might be too restricted. For
123 * example, one might want to draw only the outer faces of a domain in a
124 * three-dimensional computation, if one is not interested in what happens
125 * inside. Then, the objects that should be drawn are two-dimensional in a
126 * three-dimensional world. The Patch class and associated output functions
127 * handle these cases. The Patch class therefore takes two template
128 * parameters, the first, named <tt>dim</tt> denoting the dimension of the
129 * object (in the above example, this would be two), while the second, named
130 * <tt>spacedim</tt>, denotes the dimension of the embedding space (this would
131 * be three). The corner points of a patch have the dimension of the space,
132 * while their number is determined by the dimension of the patch. By default,
133 * the second template parameter has the same value as the first, which would
134 * correspond to outputting a cell, rather than a face or something else.
135 *
136 * <h3>DataOutBaseInterface</h3>
137 *
138 * The members of this namespace are not usually called from user code
139 * directly. Rather, classes that use the functions declared here are
140 * typically derived from DataOutInterface.
141 *
142 * The interface of this class basically consists of the declaration of a data
143 * type describing a patch and a bunch of functions taking a list of patches
144 * and writing them in one format or other to the stream. It is in the
145 * responsibility of the derived classes to provide this list of patches. In
146 * addition to the list of patches, a name for each data set may be given.
147 *
148 *
149 * <h3>Querying interface</h3>
150 *
151 * This class also provides a few functions (parse_output_format(),
152 * get_output_format_names(), default_suffix()) that can be used to query
153 * which output formats this class supports. The provide a list of names for
154 * all the formats we can output, parse a string and return an enum indicating
155 * each format, and provide a way to convert a value of this enum into the
156 * usual suffix used for files of that name. Using these functions, one can
157 * entirely free applications from knowledge which formats the library
158 * presently allows to output; several of the example programs show how to do
159 * this.
160 *
161 * <h3>Output parameters</h3>
162 *
163 * All functions take a parameter which is a structure of type
164 * <tt>XFlags</tt>, where <tt>X</tt> is the name of the output format. To find
165 * out what flags are presently supported, read the documentation of the
166 * different structures.
167 *
168 * Note that usually the output formats used for scientific visualization
169 * programs have no or very few parameters (apart from some compatibility
170 * flags) because there the actual appearance of output is determined using
171 * the visualization program and the files produced by this class store more
172 * or less only raw data.
173 *
174 * The direct output formats, like Postscript or Povray need to be given a lot
175 * more parameters, though, since there the output file has to contain all
176 * details of the viewpoint, light source, etc.
177 *
178 * <h3>Writing backends</h3>
179 *
180 * An abstraction layer has been introduced to facilitate coding backends for
181 * additional visualization tools. It is applicable for data formats
182 * separating the information into a field of vertices, a field of connection
183 * information for the grid cells and data fields.
184 *
185 * For each of these fields, output functions are implemented, namely
186 * write_nodes(), write_cells() and write_data(). In order to use these
187 * functions, a format specific output stream must be written, following the
188 * examples of DXStream, GmvStream, VtkStream and so on, implemented in the
189 * .cc file.
190 *
191 * In this framework, the implementation of a new output format is reduced to
192 * writing the section headers and the new output stream class for writing a
193 * single mesh object.
194 *
195 * @ingroup output
196 */
197 namespace DataOutBase
198 {
199 /**
200 * An enum for different levels of compression used in several places
201 * to determine zlib compression levels for binary output. At some
202 * places, it is possible to output the data also as plain text as
203 * an alternative, which is convenient for debugging. We use
204 * this flag to indicate such an output as well.
205 */
206 enum class CompressionLevel
207 {
208 /**
209 * Do not use any compression.
210 */
211 no_compression,
212 /**
213 * Use the fastest available compression algorithm.
214 */
215 best_speed,
216 /**
217 * Use the algorithm which results in the smallest compressed files.
218 */
219 best_compression,
220 /**
221 * Use the default compression algorithm. This is a compromise between
222 * speed and file size.
223 */
224 default_compression,
225 /**
226 * Output as plain text (ASCII) if available.
227 */
228 plain_text
229 };
230
231
232 /**
233 * Data structure describing a patch of data in <tt>dim</tt> space
234 * dimensions.
235 *
236 * A patch consists of the following data:
237 * <ul>
238 * <li> the corner #vertices,
239 * <li> the number #n_subdivisions of the number of cells the Patch has in
240 * each space direction,
241 * <li> the #data attached to each vertex, in the usual lexicographic
242 * ordering,
243 * <li> information on #neighbors.
244 * </ul>
245 *
246 * See the general documentation of the DataOutBase class for more
247 * information on its contents and purposes. In the case of two dimensions,
248 * the next picture is an example of <tt>n_subdivisions</tt> = 4 because the
249 * number of (sub)cells within each patch is equal to
250 * <tt>2<sup>dim</sup></tt>.
251 *
252 * @ingroup output
253 */
254 template <int dim, int spacedim = dim>
255 struct Patch
256 {
257 /**
258 * Make the <tt>spacedim</tt> template parameter available.
259 */
260 static const unsigned int space_dim = spacedim;
261
262 /**
263 * Corner points of a patch. Interior points are computed by a multilinear
264 * transformation of the unit cell to the cell specified by these corner
265 * points, if <code>points_are_available==false</code>.
266 *
267 * On the other hand, if <code>points_are_available==true</code>, then
268 * the coordinates of the points at which output is to be generated
269 * is attached in additional rows to the <code>data</code> table.
270 *
271 * The order of points is the same as for cells in the
272 * triangulation.
273 *
274 * @note This array is sized to accommodate the maximal number of vertices
275 * one might encounter in a cell, namely those for a hypercube cell.
276 * For other kinds of cells (triangles, tetrahedra, etc.), only the
277 * first few elements of this array will be used.
278 */
279 std::array<Point<spacedim>, GeometryInfo<dim>::vertices_per_cell> vertices;
280
281 /**
282 * Patch indices of neighbors of the current patch. This is made available
283 * for the OpenDX format that requires neighbor
284 * information for advanced output.
285 *
286 * @note This array is sized to accommodate the maximal number of faces
287 * one might encounter in a cell, namely those for a hypercube cell.
288 * For other kinds of cells (triangles, tetrahedra, etc.), only the
289 * first few elements of this array will be used.
290 */
291 std::array<unsigned int, GeometryInfo<dim>::faces_per_cell> neighbors;
292
293 /**
294 * Number of this patch. Since we are not sure patches are always
295 * handled in the same order, we better store this.
296 */
297 unsigned int patch_index;
298
299 /**
300 * Number of subdivisions with which this patch is to be written.
301 * <tt>1</tt> means no subdivision, <tt>2</tt> means bisection, <tt>3</tt>
302 * trisection, etc.
303 */
304 unsigned int n_subdivisions;
305
306 /**
307 * Data vectors. The format is as follows: <tt>data(i,.)</tt> denotes the
308 * data belonging to the <tt>i</tt>th data vector. <tt>data.n_cols()</tt>
309 * therefore equals the number of output points; this number is
310 * <tt>(subdivisions+1)^{dim}</tt>. <tt>data.n_rows()</tt> equals the number
311 * of data vectors. For the current purpose, a data vector equals one
312 * scalar, even if multiple scalars may later be interpreted as vectors.
313 *
314 * Within each column, <tt>data(.,j)</tt> are the data values at the
315 * output point <tt>j</tt>, where <tt>j</tt> denotes the usual
316 * lexicographic ordering in deal.II. This is also the order of points as
317 * provided by the <tt>QIterated</tt> class when used with the
318 * <tt>QTrapezoid</tt> class as subquadrature.
319 *
320 * Since the number of data vectors is usually the same for all patches to
321 * be printed, <tt>data.size()</tt> should yield the same value for all
322 * patches provided. The exception are patches for which
323 * points_are_available are set, where the actual coordinates of the point
324 * are appended to the 'data' field, see the documentation of the
325 * points_are_available flag.
326 */
327 Table<2, float> data;
328
329 /**
330 * A flag indicating whether the coordinates of the interior patch points
331 * (assuming that the patch is supposed to be subdivided further) are
332 * appended to the @p data table (@p true) or not (@p false). The latter
333 * is the default and in this case the locations of the points interior to
334 * this patch are computed by (bi-, tri-)linear interpolation from the
335 * vertices of the patch.
336 *
337 * This option exists since patch points may be evaluated using a Mapping
338 * (rather than by a linear interpolation) and therefore have to be stored
339 * in the Patch structure.
340 */
341 bool points_are_available;
342
343 /**
344 * Reference-cell type of the underlying cell of this patch.
345 */
346 ReferenceCell reference_cell;
347
348 /**
349 * Default constructor. Sets #n_subdivisions to one, #points_are_available
350 * to false, and #patch_index to #no_neighbor.
351 */
352 Patch();
353
354 /**
355 * Compare the present patch for equality with another one. This is used
356 * in a few of the automated tests in our testsuite.
357 */
358 bool
359 operator==(const Patch &patch) const;
360
361 /**
362 * Return an estimate for the memory consumption, in bytes, of this
363 * object. This is not exact (but will usually be close) because
364 * calculating the memory usage of trees (e.g., <tt>std::map</tt>) is
365 * difficult.
366 */
367 std::size_t
368 memory_consumption() const;
369
370 /**
371 * Swap the current object's contents with those of the given argument.
372 */
373 void
374 swap(Patch<dim, spacedim> &other_patch) noexcept;
375
376 /**
377 * Value to be used if this patch has no neighbor on one side.
378 */
379 static const unsigned int no_neighbor = numbers::invalid_unsigned_int;
380
381 /**
382 * @addtogroup Exceptions
383 * @{
384 */
385
386 /**
387 * Exception
388 */
389 DeclException2(
390 ExcInvalidCombinationOfDimensions,
391 int,
392 int,
393 << "It is not possible to have a structural dimension of " << arg1
394 << " to be larger than the space dimension of the surrounding"
395 << " space " << arg2);
396 /** @} */
397 };
398
399
400
401 /**
402 * A specialization of the general Patch<dim,spacedim> template that is
403 * tailored to the case of points, i.e., zero-dimensional objects embedded
404 * in @p spacedim dimensional space.
405 *
406 * The current class is compatible with the general template to allow for
407 * using the same functions accessing patches of arbitrary dimensionality
408 * in a generic way. However, it makes some variables that are nonsensical
409 * for zero-dimensional patches into @p static variables that exist only
410 * once in the entire program, as opposed to once per patch. Specifically,
411 * this is the case for the @p neighbors array and the @p n_subdivisions
412 * member variable that make no sense for zero-dimensional patches because
413 * points have no natural neighbors across their non-existent faces, nor
414 * can they reasonably be subdivided.
415 */
416 template <int spacedim>
417 struct Patch<0, spacedim>
418 {
419 /**
420 * Make the <tt>spacedim</tt> template parameter available.
421 */
422 static const unsigned int space_dim = spacedim;
423
424 /**
425 * Corner points of a patch. For the current class of zero-dimensional
426 * patches, there is of course only a single vertex.
427 *
428 * If <code>points_are_available==true</code>, then
429 * the coordinates of the point at which output is to be generated
430 * is attached as an additional row to the <code>data</code> table.
431 */
432 Point<spacedim> vertices[1];
433
434 /**
435 * An unused, @p static variable that exists only to allow access
436 * from general code in a generic fashion.
437 */
438 static unsigned int neighbors[1];
439
440 /**
441 * Number of this patch. Since we are not sure patches are always
442 * handled in the same order, we better store this.
443 */
444 unsigned int patch_index;
445
446 /**
447 * Number of subdivisions with which this patch is to be written.
448 * <tt>1</tt> means no subdivision, <tt>2</tt> means bisection, <tt>3</tt>
449 * trisection, etc.
450 *
451 * Since subdivision makes no sense for zero-dimensional patches,
452 * this variable is not used but exists only to allow access
453 * from general code in a generic fashion.
454 */
455 static const unsigned int n_subdivisions;
456
457 /**
458 * Data vectors. The format is as follows: <tt>data(i,.)</tt> denotes the
459 * data belonging to the <tt>i</tt>th data vector. <tt>data.n_cols()</tt>
460 * therefore equals the number of output points; this number is
461 * of course one for the current class, given that we produce output on
462 * points. <tt>data.n_rows()</tt> equals the number of
463 * data vectors. For the current purpose, a data vector equals one scalar,
464 * even if multiple scalars may later be interpreted as vectors.
465 *
466 * Within each column, <tt>data(.,j)</tt> are the data values at the
467 * output point <tt>j</tt>; for the current class, @p j can only
468 * be zero.
469 *
470 * Since the number of data vectors is usually the same for all patches to
471 * be printed, <tt>data.size()</tt> should yield the same value for all
472 * patches provided. The exception are patches for which
473 * points_are_available are set, where the actual coordinates of the point
474 * are appended to the 'data' field, see the documentation of the
475 * points_are_available flag.
476 */
477 Table<2, float> data;
478
479 /**
480 * A flag indicating whether the coordinates of the interior patch points
481 * (assuming that the patch is supposed to be subdivided further) are
482 * appended to the @p data table (@p true) or not (@p false). The latter
483 * is the default and in this case the locations of the points interior to
484 * this patch are computed by (bi-, tri-)linear interpolation from the
485 * vertices of the patch.
486 *
487 * This option exists since patch points may be evaluated using a Mapping
488 * (rather than by a linear interpolation) and therefore have to be stored
489 * in the Patch structure.
490 */
491 bool points_are_available;
492
493 /**
494 * Reference-cell type of the underlying cell of this patch. Since for
495 * zero-dimensional objects, a patch can only refer to a vertex, this
496 * field is always equal to ReferenceCells::Vertex and can not be changed.
497 */
498 static const ReferenceCell reference_cell;
499
500 /**
501 * Default constructor. Sets #points_are_available
502 * to false, and #patch_index to #no_neighbor.
503 */
504 Patch();
505
506 /**
507 * Compare the present patch for equality with another one. This is used
508 * in a few of the automated tests in our testsuite.
509 */
510 bool
511 operator==(const Patch &patch) const;
512
513 /**
514 * Return an estimate for the memory consumption, in bytes, of this
515 * object. This is not exact (but will usually be close) because
516 * calculating the memory usage of trees (e.g., <tt>std::map</tt>) is
517 * difficult.
518 */
519 std::size_t
520 memory_consumption() const;
521
522 /**
523 * Swap the current object's contents with those of the given argument.
524 */
525 void
526 swap(Patch<0, spacedim> &other_patch) noexcept;
527
528 /**
529 * Value to be used if this patch has no neighbor on one side.
530 */
531 static const unsigned int no_neighbor = numbers::invalid_unsigned_int;
532
533 /**
534 * @addtogroup Exceptions
535 * @{
536 */
537
538 /**
539 * Exception
540 */
541 DeclException2(
542 ExcInvalidCombinationOfDimensions,
543 int,
544 int,
545 << "It is not possible to have a structural dimension of " << arg1
546 << " to be larger than the space dimension of the surrounding"
547 << " space " << arg2);
548 /** @} */
549 };
550
551
552 /**
553 * Base class describing common functionality between different output
554 * flags.
555 *
556 * This is implemented with the "Curiously Recurring Template Pattern";
557 * derived classes use their own type to fill in the typename so that
558 * <tt>memory_consumption</tt> works correctly. See the Wikipedia page on
559 * the pattern for more information.
560 *
561 * @ingroup output
562 */
563 template <typename FlagsType>
564 struct OutputFlagsBase
565 {
566 /**
567 * Declare all flags with name and type as offered by this class, for use
568 * in input files.
569 *
570 * This method does nothing, but child classes may override this method to
571 * add fields to <tt>prm</tt>.
572 */
573 static void
574 declare_parameters(ParameterHandler &prm);
575
576 /**
577 * Read the parameters declared in declare_parameters() and set the flags
578 * for this output format accordingly.
579 *
580 * This method does nothing, but child classes may override this method to
581 * add fields to <tt>prm</tt>.
582 */
583 void
584 parse_parameters(const ParameterHandler &prm);
585
586 /**
587 * Return an estimate for the memory consumption, in bytes, of this
588 * object. This is not exact (but will usually be close) because
589 * calculating the memory usage of trees (e.g., <tt>std::map</tt>) is
590 * difficult.
591 */
592 std::size_t
593 memory_consumption() const;
594 };
595
596
597 template <typename FlagsType>
598 void
599 OutputFlagsBase<FlagsType>::declare_parameters(ParameterHandler &)
600 {}
601
602
603 template <typename FlagsType>
604 void
605 OutputFlagsBase<FlagsType>::parse_parameters(const ParameterHandler &)
606 {}
607
608
609 template <typename FlagsType>
610 std::size_t
611 OutputFlagsBase<FlagsType>::memory_consumption() const
612 {
613 return sizeof(FlagsType);
614 }
615
616
617 /**
618 * Flags controlling the details of output in OpenDX format.
619 *
620 * @ingroup output
621 */
622 struct DXFlags : public OutputFlagsBase<DXFlags>
623 {
624 /**
625 * Write neighbor information. This information is necessary for instance,
626 * if OpenDX is supposed to compute integral curves (streamlines). If it
627 * is not present, streamlines end at cell boundaries.
628 */
629 bool write_neighbors;
630 /**
631 * Write integer values of the Triangulation in binary format.
632 */
633 bool int_binary;
634 /**
635 * Write coordinate vectors in binary format.
636 */
637 bool coordinates_binary;
638
639 /**
640 * Write data vectors in binary format.
641 */
642 bool data_binary;
643
644 /**
645 * Write binary coordinate vectors as double (64 bit) numbers instead of
646 * float (32 bit).
647 */
648 bool data_double;
649
650 /**
651 * Constructor.
652 */
653 DXFlags(const bool write_neighbors = false,
654 const bool int_binary = false,
655 const bool coordinates_binary = false,
656 const bool data_binary = false);
657
658 /**
659 * Declare all flags with name and type as offered by this class, for use
660 * in input files.
661 */
662 static void
663 declare_parameters(ParameterHandler &prm);
664
665 /**
666 * Read the parameters declared in declare_parameters() and set the flags
667 * for this output format accordingly.
668 *
669 * The flags thus obtained overwrite all previous contents of this object.
670 */
671 void
672 parse_parameters(const ParameterHandler &prm);
673 };
674
675 /**
676 * Flags controlling the details of output in UCD format for AVS.
677 *
678 * @ingroup output
679 */
680 struct UcdFlags : public OutputFlagsBase<UcdFlags>
681 {
682 /**
683 * Write a comment at the beginning of the file stating the date of
684 * creation and some other data. While this is supported by the UCD
685 * format and AVS, some other programs get confused by this, so the
686 * default is to not write a preamble. However, a preamble can be written
687 * using this flag.
688 *
689 * Default: <code>false</code>.
690 */
691 bool write_preamble;
692
693 /**
694 * Constructor.
695 */
696 UcdFlags(const bool write_preamble = false);
697
698 /**
699 * Declare all flags with name and type as offered by this class, for use
700 * in input files.
701 */
702 static void
703 declare_parameters(ParameterHandler &prm);
704
705 /**
706 * Read the parameters declared in declare_parameters() and set the flags
707 * for this output format accordingly.
708 *
709 * The flags thus obtained overwrite all previous contents of this object.
710 */
711 void
712 parse_parameters(const ParameterHandler &prm);
713 };
714
715 /**
716 * Flags controlling the details of output in Gnuplot format.
717 *
718 * @ingroup output
719 */
720 struct GnuplotFlags : public OutputFlagsBase<GnuplotFlags>
721 {
722 /**
723 * Default constructor. Sets up the dimension labels with the default values
724 * of <tt>"x"</tt>, <tt>"y"</tt>, and <tt>"z"</tt>.
725 */
726 GnuplotFlags();
727
728 /**
729 * Constructor which sets up non-default values for the dimension labels.
730 */
731 GnuplotFlags(const std::vector<std::string> &space_dimension_labels);
732
733 /**
734 * Labels to use in each spatial dimension. These default to <tt>"x"</tt>,
735 * <tt>"y"</tt>, and <tt>"z"</tt>. Labels are printed to the Gnuplot file
736 * surrounded by angle brackets: For example, if the space dimension is 2
737 * and the labels are <tt>"x"</tt> and <tt>"t"</tt>, then the relevant
738 * line will start with
739 * @verbatim
740 * # <x> <t>
741 * @endverbatim
742 * Any extra labels will be ignored.
743 *
744 * If you specify these labels yourself then there should be at least
745 * <tt>spacedim</tt> labels, where <tt>spacedim</tt> is the spatial
746 * dimension of the output data.
747 */
748 std::vector<std::string> space_dimension_labels;
749
750 /**
751 * Return an estimate for the memory consumption, in bytes, of this
752 * object.
753 */
754 std::size_t
755 memory_consumption() const;
756
757 /**
758 * Exception to raise when there are not enough specified dimension
759 * labels.
760 */
761 DeclExceptionMsg(ExcNotEnoughSpaceDimensionLabels,
762 "There should be at least one space dimension per spatial "
763 "dimension (extras are ignored).");
764 };
765
766 /**
767 * Flags controlling the details of output in Povray format. Several flags
768 * are implemented, see their respective documentation.
769 *
770 * @ingroup output
771 */
772 struct PovrayFlags : public OutputFlagsBase<PovrayFlags>
773 {
774 /**
775 * Normal vector interpolation, if set to true
776 *
777 * default = false
778 */
779 bool smooth;
780
781 /**
782 * Use bicubic patches (b-splines) instead of triangles.
783 *
784 * default = false
785 */
786 bool bicubic_patch;
787
788 /**
789 * include external "data.inc" with camera, light and texture definition
790 * for the scene.
791 *
792 * default = false
793 */
794 bool external_data;
795
796 /**
797 * Constructor.
798 */
799 PovrayFlags(const bool smooth = false,
800 const bool bicubic_patch = false,
801 const bool external_data = false);
802
803 /**
804 * Declare all flags with name and type as offered by this class, for use
805 * in input files.
806 */
807 static void
808 declare_parameters(ParameterHandler &prm);
809
810 /**
811 * Read the parameters declared in declare_parameters() and set the flags
812 * for this output format accordingly.
813 *
814 * The flags thus obtained overwrite all previous contents of this object.
815 */
816 void
817 parse_parameters(const ParameterHandler &prm);
818 };
819
820
821 /**
822 * Flags controlling the details of output in encapsulated postscript
823 * format.
824 *
825 * @ingroup output
826 */
827 struct EpsFlags : public OutputFlagsBase<EpsFlags>
828 {
829 /**
830 * This denotes the number of the data vector which shall be used for
831 * generating the height information. By default, the first data vector is
832 * taken, i.e. <tt>height_vector==0</tt>, if there is any data vector. If
833 * there is no data vector, no height information is generated.
834 */
835 unsigned int height_vector;
836
837 /**
838 * Number of the vector which is to be taken to colorize cells. The same
839 * applies as for #height_vector.
840 */
841 unsigned int color_vector;
842
843 /**
844 * Enum denoting the possibilities whether the scaling should be done such
845 * that the given <tt>size</tt> equals the width or the height of the
846 * resulting picture.
847 */
848 enum SizeType
849 {
850 /// Scale to given width
851 width,
852 /// Scale to given height
853 height
854 };
855
856 /**
857 * See above. Default is <tt>width</tt>.
858 */
859 SizeType size_type;
860
861 /**
862 * Width or height of the output as given in postscript units This usually
863 * is given by the strange unit 1/72 inch. Whether this is height or width
864 * is specified by the flag <tt>size_type</tt>.
865 *
866 * Default is 300, which represents a size of roughly 10 cm.
867 */
868 unsigned int size;
869
870 /**
871 * Width of a line in postscript units. Default is 0.5.
872 */
873 double line_width;
874
875 /**
876 * Angle of the line origin-viewer against the z-axis in degrees.
877 *
878 * Default is the Gnuplot-default of 60.
879 */
880 double azimut_angle;
881
882 /**
883 * Angle by which the viewers position projected onto the x-y-plane is
884 * rotated around the z-axis, in positive sense when viewed from above.
885 * The unit are degrees, and zero equals a position above or below the
886 * negative y-axis.
887 *
888 * Default is the Gnuplot-default of 30. An example of a Gnuplot-default
889 * of 0 is the following:
890 *
891 * @verbatim
892 *
893 * 3________7
894 * / /|
895 * / / |
896 * 2/______6/ |
897 * | | | |
898 * O--> | 0___|___4
899 * | / | /
900 * | / | /
901 * 1|/______5/
902 *
903 * @endverbatim
904 */
905 double turn_angle;
906
907 /**
908 * Factor by which the z-axis is to be stretched as compared to the x- and
909 * y-axes. This is to compensate for the different sizes that coordinate
910 * and solution values may have and to prevent that the plot looks to much
911 * out-of-place (no elevation at all if solution values are much smaller
912 * than coordinate values, or the common "extremely mountainous area" in
913 * the opposite case.
914 *
915 * Default is <tt>1.0</tt>.
916 */
917 double z_scaling;
918
919 /**
920 * Flag the determines whether the lines bounding the cells (or the parts
921 * of each patch) are to be plotted.
922 *
923 * Default: <tt>true</tt>.
924 */
925 bool draw_mesh;
926
927 /**
928 * Flag whether to fill the regions between the lines bounding the cells
929 * or not. If not, no hidden line removal is performed, which in this
930 * crude implementation is done through writing the cells in a
931 * back-to-front order, thereby hiding the cells in the background by
932 * cells in the foreground.
933 *
934 * If this flag is <tt>false</tt> and #draw_mesh is <tt>false</tt> as
935 * well, nothing will be printed.
936 *
937 * If this flag is <tt>true</tt>, then the cells will be drawn either
938 * colored by one of the data sets (if #shade_cells is <tt>true</tt>), or
939 * pure white (if #shade_cells is false or if there are no data sets).
940 *
941 * Default is <tt>true</tt>.
942 */
943 bool draw_cells;
944
945 /**
946 * Flag to determine whether the cells shall be colorized by the data set
947 * denoted by #color_vector, or simply be painted in white. This flag only
948 * makes sense if <tt>#draw_cells==true</tt>. Colorization is done through
949 * #color_function.
950 *
951 * Default is <tt>true</tt>.
952 */
953 bool shade_cells;
954
955 /**
956 * Structure keeping the three color values in the RGB system.
957 */
958 struct RgbValues
959 {
960 float red;
961 float green;
962 float blue;
963
964 /**
965 * Return <tt>true</tt> if the color represented by the three color
966 * values is a grey scale, i.e. all components are equal.
967 */
968 bool
969 is_grey() const;
970 };
971
972 /**
973 * Definition of a function pointer type taking a value and returning a
974 * triple of color values in RGB values.
975 *
976 * Besides the actual value by which the color is to be computed, min and
977 * max values of the data to be colorized are given as well.
978 */
979 using ColorFunction = RgbValues (*)(const double value,
980 const double min_value,
981 const double max_value);
982
983 /**
984 * This is a pointer to the function which is used to colorize the cells.
985 * By default, it points to the static function default_color_function()
986 * which is a member of this class.
987 */
988 ColorFunction color_function;
989
990
991 /**
992 * Default colorization function. This one does what one usually wants: It
993 * shifts colors from black (lowest value) through blue, green and red to
994 * white (highest value). For the exact definition of the color scale
995 * refer to the implementation.
996 *
997 * This function was originally written by Stefan Nauber.
998 */
999 static RgbValues
1000 default_color_function(const double value,
1001 const double min_value,
1002 const double max_value);
1003
1004 /**
1005 * This is an alternative color function producing a grey scale between
1006 * black (lowest values) and white (highest values). You may use it by
1007 * setting the #color_function variable to the address of this function.
1008 */
1009 static RgbValues
1010 grey_scale_color_function(const double value,
1011 const double min_value,
1012 const double max_value);
1013
1014 /**
1015 * This is one more alternative color function producing a grey scale
1016 * between white (lowest values) and black (highest values), i.e. the
1017 * scale is reversed to the previous one. You may use it by setting the
1018 * #color_function variable to the address of this function.
1019 */
1020 static RgbValues
1021 reverse_grey_scale_color_function(const double value,
1022 const double min_value,
1023 const double max_value);
1024
1025 /**
1026 * Constructor.
1027 */
1028 EpsFlags(const unsigned int height_vector = 0,
1029 const unsigned int color_vector = 0,
1030 const SizeType size_type = width,
1031 const unsigned int size = 300,
1032 const double line_width = 0.5,
1033 const double azimut_angle = 60,
1034 const double turn_angle = 30,
1035 const double z_scaling = 1.0,
1036 const bool draw_mesh = true,
1037 const bool draw_cells = true,
1038 const bool shade_cells = true,
1039 const ColorFunction color_function = &default_color_function);
1040
1041 /**
1042 * Declare all flags with name and type as offered by this class, for use
1043 * in input files.
1044 *
1045 * For coloring, only the color functions declared in this class are
1046 * offered.
1047 */
1048 static void
1049 declare_parameters(ParameterHandler &prm);
1050
1051 /**
1052 * Read the parameters declared in declare_parameters() and set the flags
1053 * for this output format accordingly.
1054 *
1055 * The flags thus obtained overwrite all previous contents of this object.
1056 */
1057 void
1058 parse_parameters(const ParameterHandler &prm);
1059 };
1060
1061 /**
1062 * Flags controlling the details of output in GMV format. At present no
1063 * flags are implemented.
1064 *
1065 * @ingroup output
1066 */
1067 struct GmvFlags : public OutputFlagsBase<GmvFlags>
1068 {};
1069
1070 /**
1071 * Flags controlling the details of output in HDF5 format.
1072 *
1073 * @ingroup output
1074 */
1075 struct Hdf5Flags : public OutputFlagsBase<Hdf5Flags>
1076 {
1077 /**
1078 * Flag determining the compression level at which zlib, if available, is
1079 * run. The default is <tt>best_speed</tt>.
1080 */
1081 DataOutBase::CompressionLevel compression_level;
1082
1083 explicit Hdf5Flags(
1084 const CompressionLevel compression_level = CompressionLevel::best_speed);
1085 };
1086
1087 /**
1088 * Flags controlling the details of output in Tecplot format.
1089 *
1090 * @ingroup output
1091 */
1092 struct TecplotFlags : public OutputFlagsBase<TecplotFlags>
1093 {
1094 /**
1095 * Tecplot allows to assign names to zones. This variable stores this
1096 * name.
1097 */
1098 const char *zone_name;
1099
1100 /**
1101 * Solution time for each zone in a strand. This value must be
1102 * non-negative, otherwise it will not be written to file. Do not assign any
1103 * value for this in case of a static zone.
1104 */
1105 double solution_time;
1106
1107 /**
1108 * Constructor.
1109 */
1110 TecplotFlags(const char *zone_name = nullptr,
1111 const double solution_time = -1.0);
1112
1113 /**
1114 * Return an estimate for the memory consumption, in bytes, of this
1115 * object.
1116 */
1117 std::size_t
1118 memory_consumption() const;
1119 };
1120
1121 /**
1122 * Flags controlling the details of output in VTK format.
1123 *
1124 * @ingroup output
1125 */
1126 struct VtkFlags : public OutputFlagsBase<VtkFlags>
1127 {
1128 /**
1129 * The time of the time step if this file is part of a time dependent
1130 * simulation.
1131 *
1132 * The value of this variable is written into the output file according to
1133 * the instructions provided in
1134 * http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files
1135 * unless it is at its default value of
1136 * @verbatim std::numeric_limits<unsigned int>::min() @endverbatim.
1137 */
1138 double time;
1139
1140 /**
1141 * The number of the time step if this file is part of a time dependent
1142 * simulation, or the cycle within a nonlinear or other iteration.
1143 *
1144 * The value of this variable is written into the output file according to
1145 * the instructions provided in
1146 * http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files
1147 * unless it is at its default value of
1148 * @verbatim std::numeric_limits<unsigned int>::min() @endverbatim.
1149 */
1150 unsigned int cycle;
1151
1152 /**
1153 * Flag to determine whether the current date and time shall be printed as
1154 * a comment in the file's second line.
1155 *
1156 * Default is <tt>true</tt>.
1157 */
1158 bool print_date_and_time;
1159
1160 /**
1161 * Flag determining the compression level at which zlib, if available, is
1162 * run. The default is <tt>best_speed</tt>.
1163 */
1164 DataOutBase::CompressionLevel compression_level;
1165
1166 /**
1167 * Flag determining whether to write patches as linear cells
1168 * or as a high-order Lagrange cell.
1169 *
1170 * Default is <tt>false</tt>.
1171 *
1172 * @note The ability to write data that corresponds to higher order
1173 * polynomials rather than simply linear or bilinear is a feature that was
1174 * only introduced in VTK 8.1.0 in December 2017. You will need at least
1175 * Paraview version 5.5.0 released in April 2018 or a similarly recent
1176 * version of VisIt for this feature to work (for example, VisIt 3.1.1,
1177 * released in February 2020, does not yet support this feature). Older
1178 * versions of these programs are likely going to result in errors when
1179 * trying to read files generated with this flag set to true. Experience
1180 * with these programs shows that these error messages are likely going to
1181 * be rather less descriptive and more obscure.
1182 */
1183 bool write_higher_order_cells;
1184
1185 /**
1186 * A map that describes for (some or all) of the output quantities what
1187 * the physical units are. This field is ignored for VTK file format, but
1188 * used for VTU format where it is attached to the individual scalar,
1189 * vector, or tensor fields for use by visualization or other postprocessing
1190 * tools. The default is to not attach any physical units to fields at all,
1191 * i.e., an empty map.
1192 *
1193 * If the map does not contain an entry for a specific output variable, then
1194 * no unit will be written into the output file. In other words, it is not
1195 * an error to provide units for only some variables.
1196 *
1197 * step-19, step-44 and step-69 all demonstrate how to use this variable.
1198 *
1199 * @note While the functions that make use of this information do not care
1200 * about how physical units are specified, downstream postprocessing tools
1201 * should and do. As a consequence, these units should be specified in a
1202 * format that is understandable to these postprocessing tools. As an
1203 * example, the [unyt project](https://unyt.readthedocs.io/en/stable/)
1204 * describes a standard for describing and converting units.
1205 */
1206 std::map<std::string, std::string> physical_units;
1207
1208 /**
1209 * Constructor. Initializes the member variables with names corresponding
1210 * to the argument names of this function.
1211 */
1212 explicit VtkFlags(
1213 const double time = std::numeric_limits<double>::min(),
1214 const unsigned int cycle = std::numeric_limits<unsigned int>::min(),
1215 const bool print_date_and_time = true,
1216 const CompressionLevel compression_level = CompressionLevel::best_speed,
1217 const bool write_higher_order_cells = false,
1218 const std::map<std::string, std::string> &physical_units = {});
1219 };
1220
1221
1222 /**
1223 * Flags for SVG output.
1224 *
1225 * @ingroup output
1226 */
1227 struct SvgFlags : public OutputFlagsBase<SvgFlags>
1228 {
1229 /**
1230 * Height of the image in SVG units. Default value is 4000.
1231 */
1232 unsigned int height;
1233
1234 /**
1235 * Width of the image in SVG units. If left zero, the width is computed
1236 * from the height.
1237 */
1238 unsigned int width;
1239
1240 /**
1241 * This denotes the number of the data vector which shall be used for
1242 * generating the height information. By default, the first data vector is
1243 * taken, i.e. <tt>#height_vector==0</tt>, if there is any data vector. If
1244 * there is no data vector, no height information is generated.
1245 */
1246 unsigned int height_vector;
1247
1248 /**
1249 * Angles for the perspective view
1250 */
1251 int azimuth_angle, polar_angle;
1252
1253 unsigned int line_thickness;
1254
1255 /**
1256 * Draw a margin of 5% around the plotted area
1257 */
1258 bool margin;
1259
1260 /**
1261 * Draw a colorbar encoding the cell coloring
1262 */
1263 bool draw_colorbar;
1264
1265 /**
1266 * Constructor.
1267 */
1268 SvgFlags(const unsigned int height_vector = 0,
1269 const int azimuth_angle = 37,
1270 const int polar_angle = 45,
1271 const unsigned int line_thickness = 1,
1272 const bool margin = true,
1273 const bool draw_colorbar = true);
1274 };
1275
1276
1277 /**
1278 * Flags controlling the details of output in deal.II intermediate format.
1279 * At present no flags are implemented.
1280 *
1281 * @ingroup output
1282 */
1283 struct Deal_II_IntermediateFlags
1284 : public OutputFlagsBase<Deal_II_IntermediateFlags>
1285 {
1286 /**
1287 * An indicator of the current file format version used to write
1288 * intermediate format. We do not attempt to be backward compatible, so
1289 * this number is used only to verify that the format we are writing is
1290 * what the current readers and writers understand.
1291 */
1292 static const unsigned int format_version;
1293 };
1294
1295 /**
1296 * Flags controlling the behavior of the DataOutFilter class.
1297 *
1298 * @ingroup output
1299 */
1300 struct DataOutFilterFlags
1301 {
1302 /**
1303 * Whether or not to filter out duplicate vertices and associated values.
1304 * Setting this value to `true` will drastically
1305 * reduce the output data size but will result in an output file that
1306 * does not faithfully represent the actual data if the data corresponds
1307 * to discontinuous fields. In particular, along subdomain boundaries
1308 * the data will still be discontinuous, while it will look like a
1309 * continuous field inside of the subdomain.
1310 */
1311 bool filter_duplicate_vertices;
1312
1313 /**
1314 * Whether the XDMF output refers to HDF5 files. This affects how output
1315 * is structured.
1316 */
1317 bool xdmf_hdf5_output;
1318
1319 /**
1320 * Constructor.
1321 */
1322 DataOutFilterFlags(const bool filter_duplicate_vertices = false,
1323 const bool xdmf_hdf5_output = false);
1324
1325 /**
1326 * Declare all flags with name and type as offered by this class, for use
1327 * in input files.
1328 */
1329 static void
1330 declare_parameters(ParameterHandler &prm);
1331
1332 /**
1333 * Read the parameters declared in <tt>declare_parameters</tt> and set the
1334 * flags for this output format accordingly.
1335 *
1336 * The flags thus obtained overwrite all previous contents of this object.
1337 */
1338 void
1339 parse_parameters(const ParameterHandler &prm);
1340
1341 /**
1342 * Determine an estimate for the memory consumption (in bytes) of this
1343 * object.
1344 */
1345 std::size_t
1346 memory_consumption() const;
1347 };
1348
1349 /**
1350 * DataOutFilter provides a way to remove redundant vertices and values
1351 * generated by the deal.II output. By default, DataOutBase and the classes
1352 * that build on it output data at each vertex of each cell. This means that
1353 * data is output multiple times for each vertex of the mesh, once for each
1354 * cell adjacent to the vertex. The purpose of
1355 * this scheme is to support output of discontinuous quantities, either
1356 * because the finite element space is discontinuous or because the quantity
1357 * that is output is computed from a solution field and is discontinuous
1358 * across faces (for example for quantities computed via DataPostprocessor;
1359 * typical cases where output quantities are discontinuous are when a
1360 * postprocessor computes a quantity using the *gradient* of the solution,
1361 * which is generally discontinuous even if the element itself is
1362 * continuous). Other cases where the output is discontinuous are if the
1363 * data to be output is not a finite element field but, for example,
1364 * results from a class such as MatrixOut.
1365 *
1366 * This class is an attempt to rein in the amount of data that is written.
1367 * If the fields that are written to files are indeed discontinuous, the
1368 * only way to faithfully represent them is indeed to write multiple values
1369 * for each vertex (this is typically done by creating multiple logical nodes
1370 * in the output file, all of which have the same physical location; data is
1371 * then associated to nodes, allowing to have multiple values associated
1372 * with the same location). However,
1373 * for fine meshes, one may not necessarily be interested in an exact
1374 * representation of output fields that will likely only have small
1375 * discontinuities. Rather, it may be sufficient to just output one value
1376 * per vertex, which may be chosen arbitrarily from among those that are
1377 * defined at this vertex, i.e., chosen arbitrarily from any of the
1378 * adjacent cells.
1379 */
1380 class DataOutFilter
1381 {
1382 public:
1383 /**
1384 * Default constructor.
1385 */
1386 DataOutFilter();
1387
1388 /**
1389 * Constructor with a given set of flags. See DataOutFilterFlags for
1390 * possible flags.
1391 */
1392 DataOutFilter(const DataOutBase::DataOutFilterFlags &flags);
1393
1394 /**
1395 * Write a point with the specified index into the filtered data set. If
1396 * the point already exists and we are filtering redundant values, the
1397 * provided index will internally refer to another recorded point.
1398 */
1399 template <int dim>
1400 void
1401 write_point(const unsigned int index, const Point<dim> &p);
1402
1403 /**
1404 * Record a deal.II cell in the internal reordered format.
1405 */
1406 template <int dim>
1407 void
1408 write_cell(const unsigned int index,
1409 const unsigned int start,
1410 const std::array<unsigned int, dim> &offsets);
1411
1412 /**
1413 * Record a single deal.II cell without subdivisions (e.g. simplex) in the
1414 * internal reordered format.
1415 */
1416 void
1417 write_cell_single(const unsigned int index,
1418 const unsigned int start,
1419 const unsigned int n_points,
1420 const ReferenceCell &reference_cell);
1421
1422 /**
1423 * Filter and record a data set. If there are multiple values at a given
1424 * vertex and redundant values are being removed, one is arbitrarily
1425 * chosen as the recorded value. In the future this can be expanded to
1426 * average/min/max multiple values at a given vertex.
1427 */
1428 void
1429 write_data_set(const std::string &name,
1430 const unsigned int dimension,
1431 const unsigned int set_num,
1432 const Table<2, double> &data_vectors);
1433
1434 /**
1435 * Resize and fill a vector with all the filtered node vertex points, for
1436 * output to a file.
1437 */
1438 void
1439 fill_node_data(std::vector<double> &node_data) const;
1440
1441 /**
1442 * Resize and fill a vector with all the filtered cell vertex indices, for
1443 * output to a file.
1444 */
1445 void
1446 fill_cell_data(const unsigned int local_node_offset,
1447 std::vector<unsigned int> &cell_data) const;
1448
1449 /**
1450 * Get the name of the data set indicated by the set number.
1451 */
1452 std::string
1453 get_data_set_name(const unsigned int set_num) const;
1454
1455 /**
1456 * Get the dimensionality of the data set indicated by the set number.
1457 */
1458 unsigned int
1459 get_data_set_dim(const unsigned int set_num) const;
1460
1461 /**
1462 * Get the raw double valued data of the data set indicated by the set
1463 * number.
1464 */
1465 const double *
1466 get_data_set(const unsigned int set_num) const;
1467
1468 /**
1469 * Return the number of nodes in this DataOutFilter. This may be smaller
1470 * than the original number of nodes if filtering is enabled.
1471 */
1472 unsigned int
1473 n_nodes() const;
1474
1475 /**
1476 * Return the number of filtered cells in this DataOutFilter. Cells are
1477 * not filtered so this will be the original number of cells.
1478 */
1479 unsigned int
1480 n_cells() const;
1481
1482 /**
1483 * Return the number of filtered data sets in this DataOutFilter. Data
1484 * sets are not filtered so this will be the original number of data sets.
1485 */
1486 unsigned int
1487 n_data_sets() const;
1488
1489 /**
1490 * Empty functions to do base class inheritance.
1491 */
1492 void
1493 flush_points();
1494
1495 /**
1496 * Empty functions to do base class inheritance.
1497 */
1498 void
1499 flush_cells();
1500
1501
1502 private:
1503 /**
1504 * Empty class to provide comparison function for Map3dPoint.
1505 */
1506 struct Point3Comp
1507 {
1508 bool
1509 operator()(const Point<3> &one, const Point<3> &two) const
1510 {
1511 /*
1512 * The return statement below is an optimized version of the following
1513 * code:
1514 *
1515 * for (unsigned int d=0; d<3; ++d)
1516 * {
1517 * if (one(d) < two(d))
1518 * return true;
1519 * else if (one(d) > two(d))
1520 * return false;
1521 * }
1522 * return false;
1523 */
1524
1525 return (one[0] < two[0] ||
1526 (!(two[0] < one[0]) &&
1527 (one[1] < two[1] || (!(two[1] < one[1]) && one[2] < two[2]))));
1528 }
1529 };
1530
1531 using Map3DPoint = std::multimap<Point<3>, unsigned int, Point3Comp>;
1532
1533 /**
1534 * Flags used to specify filtering behavior.
1535 */
1536 DataOutBase::DataOutFilterFlags flags;
1537
1538 /**
1539 * The number of space dimensions in which the vertices represented
1540 * by the current object live. This corresponds to the usual
1541 * @p dim argument, but since this class is not templated on the
1542 * dimension, we need to store it here.
1543 */
1544 unsigned int node_dim;
1545
1546 /**
1547 * The number of cells stored in
1548 * @ref filtered_cells.
1549 */
1550 unsigned int num_cells;
1551
1552 /**
1553 * Map of points to an internal index.
1554 */
1555 Map3DPoint existing_points;
1556
1557 /**
1558 * Map of actual point index to internal point index.
1559 */
1560 std::map<unsigned int, unsigned int> filtered_points;
1561
1562 /**
1563 * Map of cells to the filtered points.
1564 */
1565 std::map<unsigned int, unsigned int> filtered_cells;
1566
1567 /**
1568 * Data set names.
1569 */
1570 std::vector<std::string> data_set_names;
1571
1572 /**
1573 * Data set dimensions.
1574 */
1575 std::vector<unsigned int> data_set_dims;
1576
1577 /**
1578 * Data set data.
1579 */
1580 std::vector<std::vector<double>> data_sets;
1581
1582 /**
1583 * Record a cell vertex index based on the internal reordering.
1584 */
1585 void
1586 internal_add_cell(const unsigned int cell_index,
1587 const unsigned int pt_index);
1588 };
1589
1590
1591 /**
1592 * Provide a data type specifying the presently supported output formats.
1593 */
1594 enum OutputFormat
1595 {
1596 /**
1597 * Use the format already stored in the object.
1598 */
1599 default_format,
1600
1601 /**
1602 * Do not write any output.
1603 */
1604 none,
1605
1606 /**
1607 * Output for OpenDX.
1608 */
1609 dx,
1610
1611 /**
1612 * Output in the UCD format for AVS.
1613 */
1614 ucd,
1615
1616 /**
1617 * Output for the Gnuplot tool.
1618 */
1619 gnuplot,
1620
1621 /**
1622 * Output for the Povray raytracer.
1623 */
1624 povray,
1625
1626 /**
1627 * Output in encapsulated PostScript.
1628 */
1629 eps,
1630
1631 /**
1632 * Output for GMV.
1633 */
1634 gmv,
1635
1636 /**
1637 * Output for Tecplot in text format.
1638 */
1639 tecplot,
1640
1641 /**
1642 * Output in VTK format.
1643 */
1644 vtk,
1645
1646 /**
1647 * Output in VTK format.
1648 */
1649 vtu,
1650
1651 /**
1652 * Output in SVG format.
1653 */
1654 svg,
1655
1656 /**
1657 * Output in deal.II intermediate format.
1658 */
1659 deal_II_intermediate,
1660
1661 /**
1662 * Output in HDF5 format.
1663 */
1664 hdf5
1665 };
1666
1667
1668 /**
1669 * Write the given list of patches to the output stream in OpenDX format.
1670 */
1671 template <int dim, int spacedim>
1672 void
1673 write_dx(
1674 const std::vector<Patch<dim, spacedim>> &patches,
1675 const std::vector<std::string> &data_names,
1676 const std::vector<
1677 std::tuple<unsigned int,
1678 unsigned int,
1679 std::string,
1680 DataComponentInterpretation::DataComponentInterpretation>>
1681 &nonscalar_data_ranges,
1682 const DXFlags &flags,
1683 std::ostream &out);
1684
1685 /**
1686 * Write the given list of patches to the output stream in eps format.
1687 *
1688 * Output in this format circumvents the use of auxiliary graphic programs
1689 * converting some output format into a graphics format. This has the
1690 * advantage that output is easy and fast, and the disadvantage that you
1691 * have to give a whole bunch of parameters which determine the direction of
1692 * sight, the mode of colorization, the scaling of the height axis, etc. (Of
1693 * course, all these parameters have reasonable default values, which you
1694 * may want to change.)
1695 *
1696 * This function only supports output for two-dimensional domains (i.e.,
1697 * with dim==2), with values in the vertical direction taken from a data
1698 * vector.
1699 *
1700 * Basically, output consists of the mesh and the cells in between them. You
1701 * can draw either of these, or both, or none if you are really interested
1702 * in an empty picture. If written, the mesh uses black lines. The cells in
1703 * between the mesh are either not printed (this will result in a loss of
1704 * hidden line removal, i.e. you can "see through" the cells to lines
1705 * behind), printed in white (which does nothing apart from the hidden line
1706 * removal), or colorized using one of the data vectors (which need not be
1707 * the same as the one used for computing the height information) and a
1708 * customizable color function. The default color functions chooses the
1709 * color between black, blue, green, red and white, with growing values of
1710 * the data field chosen for colorization. At present, cells are displayed
1711 * with one color per cell only, which is taken from the value of the data
1712 * field at the center of the cell; bilinear interpolation of the color on a
1713 * cell is not used.
1714 *
1715 * By default, the viewpoint is chosen like the default viewpoint in
1716 * GNUPLOT, i.e. with an angle of 60 degrees with respect to the positive
1717 * z-axis and rotated 30 degrees in positive sense (as seen from above) away
1718 * from the negative y-axis. Of course you can change these settings.
1719 *
1720 * EPS output is written without a border around the picture, i.e. the
1721 * bounding box is close to the output on all four sides. Coordinates are
1722 * written using at most five digits, to keep picture size at a reasonable
1723 * size.
1724 *
1725 * All parameters along with their default values are listed in the
1726 * documentation of the <tt>EpsFlags</tt> member class of this class. See
1727 * there for more and detailed information.
1728 */
1729 template <int spacedim>
1730 void
1731 write_eps(
1732 const std::vector<Patch<2, spacedim>> &patches,
1733 const std::vector<std::string> &data_names,
1734 const std::vector<
1735 std::tuple<unsigned int,
1736 unsigned int,
1737 std::string,
1738 DataComponentInterpretation::DataComponentInterpretation>>
1739 &nonscalar_data_ranges,
1740 const EpsFlags &flags,
1741 std::ostream &out);
1742
1743 /**
1744 * This is the same function as above except for domains that are not
1745 * two-dimensional. This function is not implemented (and will throw an error
1746 * if called) but is declared to allow for dimension-independent programs.
1747 */
1748 template <int dim, int spacedim>
1749 void
1750 write_eps(
1751 const std::vector<Patch<dim, spacedim>> &patches,
1752 const std::vector<std::string> &data_names,
1753 const std::vector<
1754 std::tuple<unsigned int,
1755 unsigned int,
1756 std::string,
1757 DataComponentInterpretation::DataComponentInterpretation>>
1758 &nonscalar_data_ranges,
1759 const EpsFlags &flags,
1760 std::ostream &out);
1761
1762
1763 /**
1764 * Write the given list of patches to the output stream in GMV format.
1765 *
1766 * Data is written in the following format: nodes are considered the points
1767 * of the patches. In spatial dimensions less than three, zeroes are
1768 * inserted for the missing coordinates. The data vectors are written as
1769 * node or cell data, where for the first the data space is interpolated to
1770 * (bi-,tri-)linear elements.
1771 */
1772 template <int dim, int spacedim>
1773 void
1774 write_gmv(
1775 const std::vector<Patch<dim, spacedim>> &patches,
1776 const std::vector<std::string> &data_names,
1777 const std::vector<
1778 std::tuple<unsigned int,
1779 unsigned int,
1780 std::string,
1781 DataComponentInterpretation::DataComponentInterpretation>>
1782 &nonscalar_data_ranges,
1783 const GmvFlags &flags,
1784 std::ostream &out);
1785
1786 /**
1787 * Write the given list of patches to the output stream in gnuplot format.
1788 * Visualization of two-dimensional data can then be achieved by starting
1789 * <tt>gnuplot</tt> and entering the commands
1790 *
1791 * @verbatim
1792 * set data style lines
1793 * splot "filename" using 1:2:n
1794 * @endverbatim
1795 * This example assumes that the number of the data vector displayed is
1796 * <b>n-2</b>.
1797 *
1798 * The GNUPLOT format is not able to handle data on unstructured grids
1799 * directly. Directly would mean that you only give the vertices and the
1800 * solution values thereon and the program constructs its own grid to
1801 * represent the data. This is only possible for a structured tensor product
1802 * grid in two dimensions. However, it is possible to give several such
1803 * patches within one file, which is exactly what the respective function of
1804 * this class does: writing each cell's data as a patch of data, at least if
1805 * the patches as passed from derived classes represent cells. Note that the
1806 * functions on patches need not be continuous at interfaces between
1807 * patches, so this method also works for discontinuous elements. Note also,
1808 * that GNUPLOT can do hidden line removal for patched data.
1809 *
1810 * While this discussion applies to two spatial dimensions, it is more
1811 * complicated in 3d. The reason is that we could still use patches, but it
1812 * is difficult when trying to visualize them, since if we use a cut through
1813 * the data (by, for example, using x- and z-coordinates, a fixed y-value
1814 * and plot function values in z-direction, then the patched data is not a
1815 * patch in the sense GNUPLOT wants it any more. Therefore, we use another
1816 * approach, namely writing the data on the 3d grid as a sequence of lines,
1817 * i.e. two points each associated with one or more data sets. There are
1818 * therefore 12 lines for each subcells of a patch.
1819 *
1820 * Given the lines as described above, a cut through this data in Gnuplot
1821 * can then be achieved like this:
1822 * @verbatim
1823 * set data style lines
1824 * splot [:][:][0:] "T" using 1:2:(\$3==.5 ? \$4 : -1)
1825 * @endverbatim
1826 *
1827 * This command plots data in $x$- and $y$-direction unbounded, but in
1828 * $z$-direction only those data points which are above the $x$-$y$-plane (we
1829 * assume here a positive solution, if it has negative values, you might
1830 * want to decrease the lower bound). Furthermore, it only takes the data
1831 * points with z-values (<tt>&3</tt>) equal to 0.5, i.e. a cut through the
1832 * domain at <tt>z=0.5</tt>. For the data points on this plane, the data
1833 * values of the first data set (<tt>&4</tt>) are raised in z-direction
1834 * above the x-y-plane; all other points are denoted the value <tt>-1</tt>
1835 * instead of the value of the data vector and are not plotted due to the
1836 * lower bound in z plotting direction, given in the third pair of brackets.
1837 *
1838 * More complex cuts are possible, including nonlinear ones. Note however,
1839 * that only those points which are actually on the cut-surface are plotted.
1840 */
1841 template <int dim, int spacedim>
1842 void
1843 write_gnuplot(
1844 const std::vector<Patch<dim, spacedim>> &patches,
1845 const std::vector<std::string> &data_names,
1846 const std::vector<
1847 std::tuple<unsigned int,
1848 unsigned int,
1849 std::string,
1850 DataComponentInterpretation::DataComponentInterpretation>>
1851 &nonscalar_data_ranges,
1852 const GnuplotFlags &flags,
1853 std::ostream &out);
1854
1855 /**
1856 * Write the given list of patches to the output stream for the Povray
1857 * raytracer.
1858 *
1859 * Output in this format creates a povray source file, include standard
1860 * camera and light source definition for rendering with povray 3.1 At
1861 * present, this format only supports output for two-dimensional data, with
1862 * values in the third direction taken from a data vector.
1863 *
1864 * The output uses two different povray-objects:
1865 *
1866 * <ul>
1867 * <li> <tt>BICUBIC_PATCH</tt> A <tt>bicubic_patch</tt> is a 3-dimensional
1868 * Bezier patch. It consists of 16 Points describing the surface. The 4
1869 * corner points are touched by the object, while the other 12 points pull
1870 * and stretch the patch into shape. One <tt>bicubic_patch</tt> is generated
1871 * on each patch. Therefore the number of subdivisions has to be 3 to provide
1872 * the patch with 16 points. A bicubic patch is not exact but generates very
1873 * smooth images.
1874 *
1875 * <li> <tt>MESH</tt> The mesh object is used to store large number of
1876 * triangles. Every square of the patch data is split into one upper-left
1877 * and one lower-right triangle. If the number of subdivisions is three, 32
1878 * triangle are generated for every patch.
1879 *
1880 * Using the smooth flag povray interpolates the normals on the triangles,
1881 * imitating a curved surface
1882 * </ul>
1883 *
1884 * All objects get one texture definition called Tex. This texture has to be
1885 * declared somewhere before the object data. This may be in an external
1886 * data file or at the beginning of the output file. Setting the
1887 * <tt>external_data</tt> flag to false, an standard camera, light and
1888 * texture (scaled to fit the scene) is added to the output file. Set to
1889 * true an include file "data.inc" is included. This file is not generated
1890 * by deal and has to include camera, light and the texture definition Tex.
1891 *
1892 * You need povray (>=3.0) to render the scene. The minimum options for
1893 * povray are:
1894 * @verbatim
1895 * povray +I<inputfile> +W<horiz. size> +H<ver. size> +L<include path>
1896 * @endverbatim
1897 * If the external file "data.inc" is used, the path to this file has to be
1898 * included in the povray options.
1899 */
1900 template <int dim, int spacedim>
1901 void
1902 write_povray(
1903 const std::vector<Patch<dim, spacedim>> &patches,
1904 const std::vector<std::string> &data_names,
1905 const std::vector<
1906 std::tuple<unsigned int,
1907 unsigned int,
1908 std::string,
1909 DataComponentInterpretation::DataComponentInterpretation>>
1910 &nonscalar_data_ranges,
1911 const PovrayFlags &flags,
1912 std::ostream &out);
1913
1914 /**
1915 * Write the given list of patches to the output stream in Tecplot ASCII
1916 * format (FEBLOCK).
1917 *
1918 * For more information consult the Tecplot Users and Reference manuals.
1919 */
1920 template <int dim, int spacedim>
1921 void
1922 write_tecplot(
1923 const std::vector<Patch<dim, spacedim>> &patches,
1924 const std::vector<std::string> &data_names,
1925 const std::vector<
1926 std::tuple<unsigned int,
1927 unsigned int,
1928 std::string,
1929 DataComponentInterpretation::DataComponentInterpretation>>
1930 &nonscalar_data_ranges,
1931 const TecplotFlags &flags,
1932 std::ostream &out);
1933
1934 /**
1935 * Write the given list of patches to the output stream in UCD format
1936 * described in the AVS developer's guide (now AVS). Due to limitations in
1937 * the present format, only node based data can be output, which in one
1938 * reason why we invented the patch concept. In order to write higher order
1939 * elements, you may split them up into several subdivisions of each cell.
1940 * These subcells will then, however, also appear as different cells by
1941 * programs which understand the UCD format.
1942 *
1943 * No use is made of the possibility to give model data since these are not
1944 * supported by all UCD aware programs. You may give cell data in derived
1945 * classes by setting all values of a given data set on a patch to the same
1946 * value.
1947 */
1948 template <int dim, int spacedim>
1949 void
1950 write_ucd(
1951 const std::vector<Patch<dim, spacedim>> &patches,
1952 const std::vector<std::string> &data_names,
1953 const std::vector<
1954 std::tuple<unsigned int,
1955 unsigned int,
1956 std::string,
1957 DataComponentInterpretation::DataComponentInterpretation>>
1958 &nonscalar_data_ranges,
1959 const UcdFlags &flags,
1960 std::ostream &out);
1961
1962 /**
1963 * Write the given list of patches to the output stream in VTK format. The
1964 * data is written in the traditional VTK format as opposed to the XML-based
1965 * format that write_vtu() produces.
1966 *
1967 * The nonscalar_data_ranges argument denotes ranges of components in the
1968 * output that are considered a vector, rather than simply a collection of
1969 * scalar fields. The VTK output format has special provisions that allow
1970 * these components to be output by a single name rather than having to
1971 * group several scalar fields into a vector later on in the visualization
1972 * program.
1973 *
1974 * @note VTK is a legacy format and has largely been supplanted by the VTU
1975 * format (an XML-structured version of VTK). In particular, VTU allows for
1976 * the compression of data and consequently leads to much smaller file sizes
1977 * that equivalent VTK files for large files. Since all visualization
1978 * programs that support VTK also support VTU, you should consider using the
1979 * latter file format instead, by using the write_vtu() function.
1980 */
1981 template <int dim, int spacedim>
1982 void
1983 write_vtk(
1984 const std::vector<Patch<dim, spacedim>> &patches,
1985 const std::vector<std::string> &data_names,
1986 const std::vector<
1987 std::tuple<unsigned int,
1988 unsigned int,
1989 std::string,
1990 DataComponentInterpretation::DataComponentInterpretation>>
1991 &nonscalar_data_ranges,
1992 const VtkFlags &flags,
1993 std::ostream &out);
1994
1995
1996 /**
1997 * Write the given list of patches to the output stream in VTU format. The
1998 * data is written in the XML-based VTK format as opposed to the traditional
1999 * format that write_vtk() produces.
2000 *
2001 * The nonscalar_data_ranges argument denotes ranges of components in the
2002 * output that are considered a vector, rather than simply a collection of
2003 * scalar fields. The VTK output format has special provisions that allow
2004 * these components to be output by a single name rather than having to
2005 * group several scalar fields into a vector later on in the visualization
2006 * program.
2007 *
2008 * Some visualization programs, such as ParaView, can read several separate
2009 * VTU files to parallelize visualization. In that case, you need a
2010 * <code>.pvtu</code> file that describes which VTU files form a group. The
2011 * DataOutInterface::write_pvtu_record() function can generate such a
2012 * centralized record. Likewise, DataOutInterface::write_visit_record() does
2013 * the same for VisIt (although VisIt can also read <code>pvtu</code> records
2014 * since version 2.5.1). Finally, for time dependent problems, you may also
2015 * want to look at DataOutInterface::write_pvd_record()
2016 *
2017 * The use of this function is explained in step-40.
2018 */
2019 template <int dim, int spacedim>
2020 void
2021 write_vtu(
2022 const std::vector<Patch<dim, spacedim>> &patches,
2023 const std::vector<std::string> &data_names,
2024 const std::vector<
2025 std::tuple<unsigned int,
2026 unsigned int,
2027 std::string,
2028 DataComponentInterpretation::DataComponentInterpretation>>
2029 &nonscalar_data_ranges,
2030 const VtkFlags &flags,
2031 std::ostream &out);
2032
2033 /**
2034 * This writes the header for the xml based vtu file format. This routine is
2035 * used internally together with DataOutInterface::write_vtu_footer() and
2036 * DataOutInterface::write_vtu_main() by DataOutBase::write_vtu().
2037 */
2038 void
2039 write_vtu_header(std::ostream &out, const VtkFlags &flags);
2040
2041 /**
2042 * This function writes the footer for the xml based vtu file format. This
2043 * routine is used internally together with
2044 * DataOutInterface::write_vtu_header() and DataOutInterface::write_vtu_main()
2045 * by DataOutBase::write_vtu().
2046 */
2047 void
2048 write_vtu_footer(std::ostream &out);
2049
2050 /**
2051 * This function writes the main part for the xml based vtu file format. This
2052 * routine is used internally together with
2053 * DataOutInterface::write_vtu_header() and
2054 * DataOutInterface::write_vtu_footer() by DataOutBase::write_vtu().
2055 */
2056 template <int dim, int spacedim>
2057 void
2058 write_vtu_main(
2059 const std::vector<Patch<dim, spacedim>> &patches,
2060 const std::vector<std::string> &data_names,
2061 const std::vector<
2062 std::tuple<unsigned int,
2063 unsigned int,
2064 std::string,
2065 DataComponentInterpretation::DataComponentInterpretation>>
2066 &nonscalar_data_ranges,
2067 const VtkFlags &flags,
2068 std::ostream &out);
2069
2070 /**
2071 * Some visualization programs, such as ParaView, can read several separate
2072 * VTU files that all form part of the same simulation, in order to
2073 * parallelize visualization. In that case, you need a
2074 * <code>.pvtu</code> file that describes which VTU files (written, for
2075 * example, through the DataOutInterface::write_vtu() function) form a group.
2076 * The current function can generate such a centralized record.
2077 *
2078 * This function is typically not called by itself from user space, but
2079 * you may want to call it through DataOutInterface::write_pvtu_record()
2080 * since the DataOutInterface class has access to information that you
2081 * would have to provide to the current function by hand.
2082 *
2083 * In any case, whether this function is called directly or via
2084 * DataOutInterface::write_pvtu_record(), the central record file so
2085 * written contains a list of (scalar or vector) fields that describes which
2086 * fields can actually be found in the individual files that comprise the set
2087 * of parallel VTU files along with the names of these files. This function
2088 * gets the names and types of fields through the third and fourth
2089 * argument; you can determine these by hand, but in practice, this function
2090 * is most easily called by calling DataOutInterfaces::write_pvtu_record(),
2091 * which determines the last two arguments by calling
2092 * DataOutInterface::get_dataset_names() and
2093 * DataOutInterface::get_nonscalar_data_ranges() functions. The second
2094 * argument to this function specifies the names of the files that form the
2095 * parallel set.
2096 *
2097 * @note Use DataOutBase::write_vtu() and DataOutInterface::write_vtu()
2098 * for writing each piece. Also note that
2099 * only one parallel process needs to call the current function, listing the
2100 * names of the files written by all parallel processes.
2101 *
2102 * @note In order to tell Paraview to group together multiple
2103 * <code>pvtu</code> files that each describe one time step of a time
2104 * dependent simulation, see the DataOutBase::write_pvd_record()
2105 * function.
2106 *
2107 * @note Older versions of VisIt (before 2.5.1), can not read
2108 * <code>pvtu</code> records. However, it can read visit records as written
2109 * by the write_visit_record() function.
2110 */
2111 void
2112 write_pvtu_record(
2113 std::ostream &out,
2114 const std::vector<std::string> &piece_names,
2115 const std::vector<std::string> &data_names,
2116 const std::vector<
2117 std::tuple<unsigned int,
2118 unsigned int,
2119 std::string,
2120 DataComponentInterpretation::DataComponentInterpretation>>
2121 &nonscalar_data_ranges,
2122 const VtkFlags &flags);
2123
2124 /**
2125 * In ParaView it is possible to visualize time-dependent data tagged with
2126 * the current integration time of a time dependent simulation. To use this
2127 * feature you need a <code>.pvd</code> file that describes which VTU or
2128 * PVTU file belongs to which timestep. This function writes a file that
2129 * provides this mapping, i.e., it takes a list of pairs each of which
2130 * indicates a particular time instant and the corresponding file that
2131 * contains the graphical data for this time instant.
2132 *
2133 * A typical use case, in program that computes a time dependent solution,
2134 * would be the following (<code>time</code> and <code>time_step</code> are
2135 * member variables of the class with types <code>double</code> and
2136 * <code>unsigned int</code>, respectively; the variable
2137 * <code>times_and_names</code> is of type
2138 * <code>std::vector@<std::pair@<double,std::string@> @></code>):
2139 *
2140 * @code
2141 * template <int dim>
2142 * void MyEquation<dim>::output_results () const
2143 * {
2144 * DataOut<dim> data_out;
2145 *
2146 * data_out.attach_dof_handler(dof_handler);
2147 * data_out.add_data_vector(solution, "U");
2148 * data_out.build_patches();
2149 *
2150 * const std::string filename = "solution-" +
2151 * Utilities::int_to_string (timestep_n, 3) +
2152 * ".vtu";
2153 * std::ofstream output(filename);
2154 * data_out.write_vtu(output);
2155 *
2156 * times_and_names.emplace_back (time, filename);
2157 * std::ofstream pvd_output ("solution.pvd");
2158 * DataOutBase::write_pvd_record (pvd_output, times_and_names);
2159 * }
2160 * @endcode
2161 *
2162 * @note See DataOutInterface::write_vtu, DataOutInterface::write_pvtu_record,
2163 * and DataOutInterface::write_vtu_in_parallel
2164 * for writing solutions at each timestep.
2165 *
2166 * @note The second element of each pair, i.e., the file in which the
2167 * graphical data for each time is stored, may itself be again a file that
2168 * references other files. For example, it could be the name for a
2169 * <code>.pvtu</code> file that references multiple parts of a parallel
2170 * computation.
2171 */
2172 void
2173 write_pvd_record(
2174 std::ostream &out,
2175 const std::vector<std::pair<double, std::string>> &times_and_names);
2176
2177 /**
2178 * This function is the exact equivalent of the write_pvtu_record() function
2179 * but for older versions of the VisIt visualization program and for one
2180 * visualization graph (or one time step only). See there for the purpose of
2181 * this function.
2182 *
2183 * This function is documented in the "Creating a master file for parallel"
2184 * section (section 5.7) of the "Getting data into VisIt" report that can be
2185 * found here:
2186 * https://visit-dav.github.io/visit-website/pdfs/GettingDataIntoVisIt2.0.0.pdf
2187 */
2188 void
2189 write_visit_record(std::ostream &out,
2190 const std::vector<std::string> &piece_names);
2191
2192 /**
2193 * This function is equivalent to the write_visit_record() above but for
2194 * multiple time steps. Here is an example of how the function would be
2195 * used:
2196 * @code
2197 * const unsigned int number_of_time_steps = 3;
2198 * std::vector<std::vector<std::string > > piece_names(number_of_time_steps);
2199 *
2200 * piece_names[0].emplace_back("subdomain_01.time_step_0.vtk");
2201 * piece_names[0].emplace_back("subdomain_02.time_step_0.vtk");
2202 *
2203 * piece_names[1].emplace_back("subdomain_01.time_step_1.vtk");
2204 * piece_names[1].emplace_back("subdomain_02.time_step_1.vtk");
2205 *
2206 * piece_names[2].emplace_back("subdomain_01.time_step_2.vtk");
2207 * piece_names[2].emplace_back("subdomain_02.time_step_2.vtk");
2208 *
2209 * std::ofstream visit_output ("solution.visit");
2210 *
2211 * DataOutBase::write_visit_record(visit_output, piece_names);
2212 * @endcode
2213 *
2214 * This function is documented in the "Creating a master file for parallel"
2215 * section (section 5.7) of the "Getting data into VisIt" report that can be
2216 * found here:
2217 * https://visit-dav.github.io/visit-website/pdfs/GettingDataIntoVisIt2.0.0.pdf
2218 */
2219 void
2220 write_visit_record(std::ostream &out,
2221 const std::vector<std::vector<std::string>> &piece_names);
2222
2223 /**
2224 * This function is equivalent to the write_visit_record() above but for
2225 * multiple time steps and with additional information about the time for
2226 * each timestep. Here is an example of how the function would be
2227 * used:
2228 * @code
2229 * const unsigned int number_of_time_steps = 3;
2230 * std::vector<std::pair<double,std::vector<std::string > > >
2231 * times_and_piece_names(number_of_time_steps);
2232 *
2233 * times_and_piece_names[0].first = 0.0;
2234 * times_and_piece_names[0].second.emplace_back("subdomain_01.time_step_0.vtk");
2235 * times_and_piece_names[0].second.emplace_back("subdomain_02.time_step_0.vtk");
2236 *
2237 * times_and_piece_names[1].first = 0.5;
2238 * times_and_piece_names[1].second.emplace_back("subdomain_01.time_step_1.vtk");
2239 * times_and_piece_names[1].second.emplace_back("subdomain_02.time_step_1.vtk");
2240 *
2241 * times_and_piece_names[2].first = 1.0;
2242 * times_and_piece_names[2].second.emplace_back("subdomain_01.time_step_2.vtk");
2243 * times_and_piece_names[2].second.emplace_back("subdomain_02.time_step_2.vtk");
2244 *
2245 * std::ofstream visit_output ("solution.visit");
2246 *
2247 * DataOutBase::write_visit_record(visit_output, times_and_piece_names);
2248 * @endcode
2249 *
2250 * This function is documented in the "Creating a master file for parallel"
2251 * section (section 5.7) of the "Getting data into VisIt" report that can be
2252 * found here:
2253 * https://visit-dav.github.io/visit-website/pdfs/GettingDataIntoVisIt2.0.0.pdf
2254 */
2255 void
2256 write_visit_record(
2257 std::ostream &out,
2258 const std::vector<std::pair<double, std::vector<std::string>>>
2259 &times_and_piece_names);
2260
2261 /**
2262 * Write the given list of patches to the output stream in SVG format.
2263 *
2264 * SVG (Scalable Vector Graphics) is an XML-based vector image format
2265 * developed and maintained by the World Wide Web Consortium (W3C). This
2266 * function conforms to the latest specification SVG 1.1, released on August
2267 * 16, 2011. Controlling the graphic output is possible by setting or
2268 * clearing the respective flags (see the SvgFlags struct). At present, this
2269 * format only supports output for two-dimensional data, with values in the
2270 * third direction taken from a data vector.
2271 *
2272 * For the output, each patch is subdivided into four triangles which are
2273 * then written as polygons and filled with a linear color gradient. The
2274 * arising coloring of the patches visualizes the data values at the
2275 * vertices taken from the specified data vector. A colorbar can be drawn to
2276 * encode the coloring.
2277 *
2278 * @note This function is so far only implemented for two dimensions with an
2279 * additional dimension reserved for data information.
2280 */
2281 template <int spacedim>
2282 void
2283 write_svg(
2284 const std::vector<Patch<2, spacedim>> &patches,
2285 const std::vector<std::string> &data_names,
2286 const std::vector<
2287 std::tuple<unsigned int,
2288 unsigned int,
2289 std::string,
2290 DataComponentInterpretation::DataComponentInterpretation>>
2291 &nonscalar_data_ranges,
2292 const SvgFlags &flags,
2293 std::ostream &out);
2294
2295 /**
2296 * Write the given list of patches to the output stream in deal.II
2297 * intermediate format. This is not a format understood by any other
2298 * graphics program, but is rather a direct dump of the intermediate
2299 * internal format used by deal.II. This internal format is generated by the
2300 * various classes that can generate output using the DataOutBase class, for
2301 * example from a finite element solution, and is then converted in the
2302 * present class to the final graphics format.
2303 *
2304 * Note that the intermediate format is what its name suggests: a direct
2305 * representation of internal data. It isn't standardized and will change
2306 * whenever we change our internal representation. You can only expect to
2307 * process files written in this format using the same version of deal.II
2308 * that was used for writing.
2309 *
2310 * The reason why we offer to write out this intermediate format is that it
2311 * can be read back into a deal.II program using the DataOutReader class,
2312 * which is helpful in at least two contexts: First, this can be used to
2313 * later generate graphical output in any other graphics format presently
2314 * understood; this way, it is not necessary to know at run-time which
2315 * output format is requested, or if multiple output files in different
2316 * formats are needed. Secondly, in contrast to almost all other graphics
2317 * formats, it is possible to merge several files that contain intermediate
2318 * format data, and generate a single output file from it, which may be
2319 * again in intermediate format or any of the final formats. This latter
2320 * option is most helpful for parallel programs: as demonstrated in the
2321 * step-17 example program, it is possible to let only one processor
2322 * generate the graphical output for the entire parallel program, but this
2323 * can become vastly inefficient if many processors are involved, because
2324 * the load is no longer balanced. The way out is to let each processor
2325 * generate intermediate graphical output for its chunk of the domain, and
2326 * the later merge the different files into one, which is an operation that
2327 * is much cheaper than the generation of the intermediate data.
2328 *
2329 * Intermediate format deal.II data is usually stored in files with the
2330 * ending <tt>.d2</tt>.
2331 */
2332 template <int dim, int spacedim>
2333 void
2334 write_deal_II_intermediate(
2335 const std::vector<Patch<dim, spacedim>> &patches,
2336 const std::vector<std::string> &data_names,
2337 const std::vector<
2338 std::tuple<unsigned int,
2339 unsigned int,
2340 std::string,
2341 DataComponentInterpretation::DataComponentInterpretation>>
2342 &nonscalar_data_ranges,
2343 const Deal_II_IntermediateFlags &flags,
2344 std::ostream &out);
2345
2346 /**
2347 * Like write_deal_II_intermediate() but write all patches from all ranks
2348 * using MPI I/O
2349 * into a single file with name @p name. Compression using zlib is optional and controlled
2350 * by the @p compression argument.
2351 *
2352 * The files typically have the extension <tt>.pd2</tt>.
2353 */
2354 template <int dim, int spacedim>
2355 void
2356 write_deal_II_intermediate_in_parallel(
2357 const std::vector<Patch<dim, spacedim>> &patches,
2358 const std::vector<std::string> &data_names,
2359 const std::vector<
2360 std::tuple<unsigned int,
2361 unsigned int,
2362 std::string,
2363 DataComponentInterpretation::DataComponentInterpretation>>
2364 &nonscalar_data_ranges,
2365 const Deal_II_IntermediateFlags &flags,
2366 const std::string &filename,
2367 const MPI_Comm comm,
2368 const CompressionLevel compression);
2369
2370 /**
2371 * Write the data in @p data_filter to a single HDF5 file containing both the
2372 * mesh and solution values.
2373 */
2374 template <int dim, int spacedim>
2375 void
2376 write_hdf5_parallel(const std::vector<Patch<dim, spacedim>> &patches,
2377 const DataOutFilter &data_filter,
2378 const DataOutBase::Hdf5Flags &flags,
2379 const std::string &filename,
2380 const MPI_Comm comm);
2381
2382 /**
2383 * Write the data in @p data_filter to HDF5 file(s). If @p write_mesh_file is
2384 * false, the mesh data will not be written and the solution file will
2385 * contain only the solution values. If @p write_mesh_file is true and the
2386 * filenames are the same, the resulting file will contain both mesh data
2387 * and solution values.
2388 */
2389 template <int dim, int spacedim>
2390 void
2391 write_hdf5_parallel(const std::vector<Patch<dim, spacedim>> &patches,
2392 const DataOutFilter &data_filter,
2393 const DataOutBase::Hdf5Flags &flags,
2394 const bool write_mesh_file,
2395 const std::string &mesh_filename,
2396 const std::string &solution_filename,
2397 const MPI_Comm comm);
2398
2399 /**
2400 * DataOutFilter is an intermediate data format that reduces the amount of
2401 * data that will be written to files. The object filled by this function
2402 * can then later be used again to write data in a concrete file format;
2403 * see, for example, DataOutBase::write_hdf5_parallel().
2404 */
2405 template <int dim, int spacedim>
2406 void
2407 write_filtered_data(
2408 const std::vector<Patch<dim, spacedim>> &patches,
2409 const std::vector<std::string> &data_names,
2410 const std::vector<
2411 std::tuple<unsigned int,
2412 unsigned int,
2413 std::string,
2414 DataComponentInterpretation::DataComponentInterpretation>>
2415 &nonscalar_data_ranges,
2416 DataOutFilter &filtered_data);
2417
2418 /**
2419 * Given an input stream that contains data written by
2420 * write_deal_II_intermediate(), determine the <tt>dim</tt> and
2421 * <tt>spacedim</tt> template parameters with which that function was
2422 * called, and return them as a pair of values.
2423 *
2424 * Note that this function eats a number of elements at the present position
2425 * of the stream, and therefore alters it. In order to read from it using,
2426 * for example, the DataOutReader class, you may wish to either reset the
2427 * stream to its previous position, or close and reopen it.
2428 */
2429 std::pair<unsigned int, unsigned int>
2430 determine_intermediate_format_dimensions(std::istream &input);
2431
2432 /**
2433 * Return the OutputFormat value corresponding to the given string. If the
2434 * string does not match any known format, an exception is thrown.
2435 *
2436 * The main purpose of this function is to allow a program to use any
2437 * implemented output format without the need to extend the program's parser
2438 * each time a new format is implemented.
2439 *
2440 * To get a list of presently available format names, e.g. to give it to the
2441 * ParameterHandler class, use the function get_output_format_names().
2442 */
2443 OutputFormat
2444 parse_output_format(const std::string &format_name);
2445
2446 /**
2447 * Return a list of implemented output formats. The different names are
2448 * separated by vertical bar signs (<tt>`|'</tt>) as used by the
2449 * ParameterHandler classes.
2450 */
2451 std::string
2452 get_output_format_names();
2453
2454 /**
2455 * Provide a function which tells us which suffix a file with a given output
2456 * format usually has. At present the following formats are defined:
2457 * <ul>
2458 * <li> <tt>dx</tt>: <tt>.dx</tt>
2459 * <li> <tt>ucd</tt>: <tt>.inp</tt>
2460 * <li> <tt>gnuplot</tt>: <tt>.gnuplot</tt>
2461 * <li> <tt>povray</tt>: <tt>.pov</tt>
2462 * <li> <tt>eps</tt>: <tt>.eps</tt>
2463 * <li> <tt>gmv</tt>: <tt>.gmv</tt>
2464 * <li> <tt>tecplot</tt>: <tt>.dat</tt>
2465 * <li> <tt>vtk</tt>: <tt>.vtk</tt>
2466 * <li> <tt>vtu</tt>: <tt>.vtu</tt>
2467 * <li> <tt>svg</tt>: <tt>.svg</tt>
2468 * <li> <tt>deal_II_intermediate</tt>: <tt>.d2</tt>.
2469 * </ul>
2470 *
2471 * @deprecated Using Tecplot binary output is deprecated.
2472 */
2473 std::string
2474 default_suffix(const OutputFormat output_format);
2475
2476 /**
2477 * @addtogroup Exceptions
2478 * @{
2479 */
2480
2481 /**
2482 * Exception
2483 */
2484 DeclException2(ExcInvalidDatasetSize,
2485 int,
2486 int,
2487 << "The number of points in this data set is " << arg1
2488 << ", but we expected " << arg2
2489 << " in each space direction.");
2490 /**
2491 * An output function did not receive any patches for writing.
2492 */
2493 DeclExceptionMsg(ExcNoPatches,
2494 "You are trying to write graphical data into a file, but "
2495 "no data is available in the intermediate format that "
2496 "the DataOutBase functions require. Did you forget to "
2497 "call a function such as DataOut::build_patches()?");
2498 /**
2499 * Exception
2500 */
2501 DeclExceptionMsg(ExcTecplotAPIError,
2502 "The error code of one of the Tecplot functions was "
2503 "not zero as expected.");
2504 /**
2505 * Exception
2506 */
2507 DeclException1(ExcErrorOpeningTecplotFile,
2508 char *,
2509 << "There was an error opening Tecplot file " << arg1
2510 << " for output.");
2511
2512 /** @} */
2513 } // namespace DataOutBase
2514
2515
2516
2517 /**
2518 * This class is the interface to the functions in the DataOutBase namespace,
2519 * as already its name might suggest. It does not offer much functionality
2520 * apart from a way to access the implemented formats and a way to dynamically
2521 * dispatch what output format to chose.
2522 *
2523 * This class is thought as a base class to classes actually generating data
2524 * for output. It has two abstract virtual functions, get_patches() and
2525 * get_dataset_names() produce the data which is actually needed. These are
2526 * the only functions that need to be overloaded by a derived class. In
2527 * addition to that, it has a function for each output format supported by
2528 * the underlying base class which gets the output data using these two
2529 * virtual functions and passes them to the raw output functions.
2530 *
2531 * The purpose of this class is mainly two-fold: to support storing flags by
2532 * which the output in the different output formats are controlled, and means
2533 * to work with output in a way where output format, flags and other things
2534 * are determined at run time. In addition to that it offers the abstract
2535 * interface to derived classes briefly discussed above.
2536 *
2537 *
2538 * <h3>Output flags</h3>
2539 *
2540 * The way we treat flags in this class is very similar to that used in the
2541 * <tt>GridOut</tt> class. For detailed information on the why's and how's, as
2542 * well as an example of programming, we refer to the documentation of that
2543 * class.
2544 *
2545 * Basically, this class stores a set of flags for each output format
2546 * supported by the underlying <tt>DataOutBase</tt> class. These are used
2547 * whenever one of the <tt>write_*</tt> functions is used. By default, the
2548 * values of these flags are set to reasonable start-ups, but in case you want
2549 * to change them, you can create a structure holding the flags for one of the
2550 * output formats and set it using the <tt>set_flags</tt> functions of this
2551 * class to determine all future output the object might produce by that
2552 * output format.
2553 *
2554 * For information on what parameters are supported by different output
2555 * functions, please see the documentation of the <tt>DataOutBase</tt> class
2556 * and its member classes.
2557 *
2558 *
2559 * <h3>Run time selection of output parameters</h3>
2560 *
2561 * In the output flags classes, described above, many flags are defined for
2562 * output in the different formats. In order to make them available to the
2563 * input file handler class <tt>ParameterHandler</tt>, each of these has a
2564 * function declaring these flags to the parameter handler and to read them
2565 * back from an actual input file. In order to avoid that in user programs
2566 * these functions have to be called for each available output format and the
2567 * respective flag class, the present <tt>DataOutInterface</tt> class offers a
2568 * function <tt>declare_parameters</tt> which calls the respective function of
2569 * all known output format flags classes. The flags of each such format are
2570 * packed together in a subsection in the input file. Likewise, there is a
2571 * function <tt>parse_parameters</tt> which reads these parameters and stores
2572 * them in the flags associated with this object (see above).
2573 *
2574 * Using these functions, you do not have to track which formats are presently
2575 * implemented.
2576 *
2577 * Usage is as follows:
2578 * @code
2579 * // within function declaring parameters:
2580 * prm.enter_subsection("Output format options");
2581 * DataOutInterface<dim>::declare_parameters(prm);
2582 * prm.leave_subsection();
2583 *
2584 * ...
2585 * // within function doing the output:
2586 * DataOut<dim> out;
2587 * prm.enter_subsection("Output format options");
2588 * out.parse_parameters(prm);
2589 * prm.leave_subsection();
2590 * @endcode
2591 * Note that in the present example, the class <tt>DataOut</tt> was used.
2592 * However, any other class derived from <tt>DataOutInterface</tt> would work
2593 * alike.
2594 *
2595 *
2596 * <h3>Run time selection of formats</h3>
2597 *
2598 * This class, much like the <tt>GridOut</tt> class, has a set of functions
2599 * providing a list of supported output formats, an <tt>enum</tt> denoting all
2600 * these and a function to parse a string and return the respective
2601 * <tt>enum</tt> value if it is a valid output format's name (actually, these
2602 * functions are inherited from the base class). Finally, there is a function
2603 * <tt>write</tt>, which takes a value of this <tt>enum</tt> and dispatches to
2604 * one of the actual <tt>write_*</tt> functions depending on the output format
2605 * selected by this value.
2606 *
2607 * The functions offering the different output format names are, respectively,
2608 * <tt>default_suffix</tt>, <tt>parse_output_format</tt>, and
2609 * <tt>get_output_format_names</tt>. They make the selection of output formats
2610 * in parameter files much easier, and especially independent of the formats
2611 * presently implemented. User programs need therefore not be changed whenever
2612 * a new format is implemented.
2613 *
2614 * Additionally, objects of this class have a default format, which can be set
2615 * by the parameter "Output format" of the parameter file. Within a program,
2616 * this can be changed by the member function <tt>set_default_format</tt>.
2617 * Using this default format, it is possible to leave the format selection
2618 * completely to the parameter file. A suitable suffix for the output file
2619 * name can be obtained by <tt>default_suffix</tt> without arguments.
2620 *
2621 * @ingroup output
2622 */
2623 template <int dim, int spacedim = dim>
2624 class DataOutInterface
2625 {
2626 public:
2627 /**
2628 * Constructor.
2629 */
2630 DataOutInterface();
2631
2632 /**
2633 * Destructor. Does nothing, but is declared virtual since this class has
2634 * virtual functions.
2635 */
2636 virtual ~DataOutInterface() = default;
2637
2638 /**
2639 * Obtain data through get_patches() and write it to <tt>out</tt> in OpenDX
2640 * format. See DataOutBase::write_dx.
2641 */
2642 void
2643 write_dx(std::ostream &out) const;
2644
2645 /**
2646 * Obtain data through get_patches() and write it to <tt>out</tt> in EPS
2647 * format. See DataOutBase::write_eps.
2648 */
2649 void
2650 write_eps(std::ostream &out) const;
2651
2652 /**
2653 * Obtain data through get_patches() and write it to <tt>out</tt> in GMV
2654 * format. See DataOutBase::write_gmv.
2655 */
2656 void
2657 write_gmv(std::ostream &out) const;
2658
2659 /**
2660 * Obtain data through get_patches() and write it to <tt>out</tt> in GNUPLOT
2661 * format. See DataOutBase::write_gnuplot.
2662 */
2663 void
2664 write_gnuplot(std::ostream &out) const;
2665
2666 /**
2667 * Obtain data through get_patches() and write it to <tt>out</tt> in POVRAY
2668 * format. See DataOutBase::write_povray.
2669 */
2670 void
2671 write_povray(std::ostream &out) const;
2672
2673 /**
2674 * Obtain data through get_patches() and write it to <tt>out</tt> in Tecplot
2675 * format. See DataOutBase::write_tecplot.
2676 */
2677 void
2678 write_tecplot(std::ostream &out) const;
2679
2680 /**
2681 * Obtain data through get_patches() and write it to <tt>out</tt> in UCD
2682 * format for AVS. See DataOutBase::write_ucd.
2683 */
2684 void
2685 write_ucd(std::ostream &out) const;
2686
2687 /**
2688 * Obtain data through get_patches() and write it to <tt>out</tt> in Vtk
2689 * format. See DataOutBase::write_vtk.
2690 *
2691 * @note VTK is a legacy format and has largely been supplanted by the VTU
2692 * format (an XML-structured version of VTK). In particular, VTU allows for
2693 * the compression of data and consequently leads to much smaller file sizes
2694 * that equivalent VTK files for large files. Since all visualization
2695 * programs that support VTK also support VTU, you should consider using the
2696 * latter file format instead, by using the write_vtu() function.
2697 */
2698 void
2699 write_vtk(std::ostream &out) const;
2700
2701 /**
2702 * Obtain data through get_patches() and write it to <tt>out</tt> in Vtu
2703 * (VTK's XML) format. See DataOutBase::write_vtu.
2704 *
2705 * Some visualization programs, such as ParaView, can read several separate
2706 * VTU files to parallelize visualization. In that case, you need a
2707 * <code>.pvtu</code> file that describes which VTU files form a group. The
2708 * DataOutInterface::write_pvtu_record() function can generate such a
2709 * centralized record. Likewise, DataOutInterface::write_visit_record() does
2710 * the same for older versions of VisIt (although VisIt can also read
2711 * <code>pvtu</code> records since version 2.5.1). Finally,
2712 * DataOutInterface::write_pvd_record() can be used to group together the
2713 * files that jointly make up a time dependent simulation.
2714 */
2715 void
2716 write_vtu(std::ostream &out) const;
2717
2718 /**
2719 * Collective MPI call to write the solution from all participating nodes
2720 * (those in the given communicator) to a single compressed .vtu file on a
2721 * shared file system. The communicator can be a sub communicator of the
2722 * one used by the computation. This routine uses MPI I/O to achieve high
2723 * performance on parallel filesystems. In order to use this function,
2724 * you need to be using a file system that supports parallel MPI I/O,
2725 * and you will get error messages about failed MPI calls if you do not.
2726 * Also see DataOutInterface::write_vtu().
2727 */
2728 void
2729 write_vtu_in_parallel(const std::string &filename, const MPI_Comm comm) const;
2730
2731 /**
2732 * Some visualization programs, such as ParaView and VisIt, can read several
2733 * separate VTU files that all form part of the same simulation, in order to
2734 * parallelize visualization. In that case, you need a
2735 * <code>.pvtu</code> file that describes which VTU files (written, for
2736 * example, through the DataOutInterface::write_vtu() function) form a group.
2737 * The current function can generate such a centralized record.
2738 *
2739 * The central record file generated by this function
2740 * contains a list of (scalar or vector) fields that describes which
2741 * fields can actually be found in the individual files that comprise the set
2742 * of parallel VTU files along with the names of these files. This function
2743 * gets the names and types of fields through the get_dataset_names() and
2744 * get_nonscalar_data_ranges() functions of this class. The second argument
2745 * to this function specifies the names of the files that form the parallel
2746 * set.
2747 *
2748 * @note Use DataOutBase::write_vtu() and DataOutInterface::write_vtu()
2749 * for writing each piece. Also note that
2750 * only one parallel process needs to call the current function, listing the
2751 * names of the files written by all parallel processes.
2752 *
2753 * @note The use of this function is explained in step-40.
2754 *
2755 * @note In order to tell Paraview to group together multiple
2756 * <code>pvtu</code> files that each describe one time step of a time
2757 * dependent simulation, see the DataOutBase::write_pvd_record()
2758 * function.
2759 *
2760 * @note Older versions of VisIt (before 2.5.1), can not read
2761 * <code>pvtu</code> records. However, it can read visit records as written
2762 * by the write_visit_record() function.
2763 */
2764 void
2765 write_pvtu_record(std::ostream &out,
2766 const std::vector<std::string> &piece_names) const;
2767
2768 /**
2769 * This function writes several .vtu files and a .pvtu record in parallel
2770 * and constructs the filenames automatically. It is a combination of
2771 * DataOutInterface::write_vtu() or
2772 * DataOutInterface::write_vtu_in_parallel(), and
2773 * DataOutInterface::write_pvtu_record().
2774 *
2775 * For example, running
2776 * <code> write_vtu_with_pvtu_record("output/", "solution", 3, comm, 4, 2)
2777 * </code> on 10 processes generates the files
2778 * @code
2779 * output/solution_0003.0.vtu
2780 * output/solution_0003.1.vtu
2781 * output/solution_0003.pvtu
2782 * @endcode
2783 * where the `.0.vtu` file contains the output of the first half of the
2784 * processes grouped together, and the `.1.vtu` the data from the remaining
2785 * half.
2786 *
2787 * A specified @p directory and a @p filename_without_extension
2788 * form the first part of the filename. The filename is then extended with
2789 * a @p counter labeling the current timestep/iteration/etc., the processor ID,
2790 * and finally the .vtu/.pvtu ending. Since the number of timesteps to be
2791 * written depends on the application, the number of digits to be reserved in
2792 * the filename can be specified as parameter @p n_digits_for_counter, and the number
2793 * is not padded with leading zeros if this parameter is left at its default
2794 * value numbers::invalid_unsigned_int. If more than one file identifier
2795 * is needed (e.g. time step number and iteration counter of solver), the
2796 * last identifier is used as @p counter, while all other identifiers have to be
2797 * added to @p filename_without_extension when calling this function.
2798 *
2799 * In a
2800 * parallel setting, several files are typically written per time step. The
2801 * number of files written in parallel depends on the number of MPI processes
2802 * (see parameter @p mpi_communicator), and a
2803 * specified number of @p n_groups with default value 0. The background is that
2804 * VTU file output supports grouping files from several CPUs into a given
2805 * number of files using MPI I/O when writing on a parallel filesystem. The
2806 * default value of @p n_groups is 0, meaning that every MPI rank will write one
2807 * file. A value of 1 will generate one big file containing the solution over
2808 * the whole domain, while a larger value will create @p n_groups files (but not
2809 * more than there are MPI ranks). For all values other than `n_groups==0`,
2810 * this function calls write_vtu_in_parallel(); for this function to work you
2811 * need to be using a file system that supports parallel MPI I/O, and you will
2812 * get error messages about failed MPI calls if you do not.
2813 *
2814 * Note that only one processor needs to
2815 * generate the .pvtu file, where processor zero is chosen to take over this
2816 * job.
2817 *
2818 * The return value is the filename of the centralized file for the pvtu
2819 * record.
2820 *
2821 * @note The code simply combines the strings @p directory and
2822 * @p filename_without_extension, i.e., the user has to make sure that
2823 * @p directory contains a trailing character, e.g. "/", that separates the
2824 * directory from the filename.
2825 *
2826 * @note Use an empty string "" for the first argument if output is to be
2827 * written in the current working directory.
2828 */
2829 std::string
2830 write_vtu_with_pvtu_record(
2831 const std::string &directory,
2832 const std::string &filename_without_extension,
2833 const unsigned int counter,
2834 const MPI_Comm mpi_communicator,
2835 const unsigned int n_digits_for_counter = numbers::invalid_unsigned_int,
2836 const unsigned int n_groups = 0) const;
2837
2838 /**
2839 * Obtain data through get_patches() and write it to <tt>out</tt> in SVG
2840 * format. See DataOutBase::write_svg.
2841 */
2842 void
2843 write_svg(std::ostream &out) const;
2844
2845 /**
2846 * Obtain data through get_patches() and write it to <tt>out</tt> in deal.II
2847 * intermediate format. See DataOutBase::write_deal_II_intermediate.
2848 *
2849 * Note that the intermediate format is what its name suggests: a direct
2850 * representation of internal data. It isn't standardized and will change
2851 * whenever we change our internal representation. You can only expect to
2852 * process files written in this format using the same version of deal.II
2853 * that was used for writing.
2854 */
2855 void
2856 write_deal_II_intermediate(std::ostream &out) const;
2857
2858 /**
2859 * Obtain data through get_patches() and write it using MPI I/O in parallel
2860 * to the file @p filename in the parallel
2861 * deal.II intermediate format. See
2862 * DataOutBase::write_deal_II_intermediate_in_parallel().
2863 */
2864 void
2865 write_deal_II_intermediate_in_parallel(
2866 const std::string &filename,
2867 const MPI_Comm comm,
2868 const DataOutBase::CompressionLevel compression) const;
2869
2870 /**
2871 * Create an XDMFEntry based on the data in the data_filter. This assumes
2872 * the mesh and solution data were written to a single file. See
2873 * write_xdmf_file() for an example of usage.
2874 */
2875 XDMFEntry
2876 create_xdmf_entry(const DataOutBase::DataOutFilter &data_filter,
2877 const std::string &h5_filename,
2878 const double cur_time,
2879 const MPI_Comm comm) const;
2880
2881 /**
2882 * Create an XDMFEntry based on the data in the data_filter. This assumes
2883 * the mesh and solution data were written to separate files. See
2884 * write_xdmf_file() for an example of usage.
2885 */
2886 XDMFEntry
2887 create_xdmf_entry(const DataOutBase::DataOutFilter &data_filter,
2888 const std::string &h5_mesh_filename,
2889 const std::string &h5_solution_filename,
2890 const double cur_time,
2891 const MPI_Comm comm) const;
2892
2893 /**
2894 * Write an XDMF file based on the provided vector of XDMFEntry objects.
2895 * Below is an example of how to use this function with HDF5 and the
2896 * DataOutFilter:
2897 *
2898 * @code
2899 * DataOutBase::DataOutFilterFlags flags(true, true);
2900 * DataOutBase::DataOutFilter data_filter(flags);
2901 * std::vector<XDMFEntry> xdmf_entries;
2902 * // Filter the data and store it in data_filter
2903 * data_out.write_filtered_data(data_filter);
2904 * // Write the filtered data to HDF5
2905 * data_out.write_hdf5_parallel(data_filter, "solution.h5", MPI_COMM_WORLD);
2906 * // Create an XDMF entry detailing the HDF5 file
2907 * auto new_xdmf_entry = data_out.create_xdmf_entry(data_filter,
2908 * "solution.h5",
2909 * simulation_time,
2910 * MPI_COMM_WORLD);
2911 * // Add the XDMF entry to the list
2912 * xdmf_entries.push_back(new_xdmf_entry);
2913 * // Create an XDMF file from all stored entries
2914 * data_out.write_xdmf_file(xdmf_entries, "solution.xdmf", MPI_COMM_WORLD);
2915 * @endcode
2916 */
2917 void
2918 write_xdmf_file(const std::vector<XDMFEntry> &entries,
2919 const std::string &filename,
2920 const MPI_Comm comm) const;
2921
2922 /**
2923 * Write the data in @p data_filter to a single HDF5 file containing both the
2924 * mesh and solution values. Below is an example of how to use this function
2925 * with the DataOutFilter:
2926 *
2927 * @code
2928 * DataOutBase::DataOutFilterFlags flags(true, true);
2929 * DataOutBase::DataOutFilter data_filter(flags);
2930 * // Filter the data and store it in data_filter
2931 * data_out.write_filtered_data(data_filter);
2932 * // Write the filtered data to HDF5
2933 * data_out.write_hdf5_parallel(data_filter, "solution.h5", MPI_COMM_WORLD);
2934 * @endcode
2935 */
2936 void
2937 write_hdf5_parallel(const DataOutBase::DataOutFilter &data_filter,
2938 const std::string &filename,
2939 const MPI_Comm comm) const;
2940
2941 /**
2942 * Write the data in data_filter to HDF5 file(s). If write_mesh_file is
2943 * false, the mesh data will not be written and the solution file will
2944 * contain only the solution values. If write_mesh_file is true and the
2945 * filenames are the same, the resulting file will contain both mesh data
2946 * and solution values.
2947 */
2948 void
2949 write_hdf5_parallel(const DataOutBase::DataOutFilter &data_filter,
2950 const bool write_mesh_file,
2951 const std::string &mesh_filename,
2952 const std::string &solution_filename,
2953 const MPI_Comm comm) const;
2954
2955 /**
2956 * DataOutFilter is an intermediate data format that reduces the amount of
2957 * data that will be written to files. The object filled by this function
2958 * can then later be used again to write data in a concrete file format;
2959 * see, for example, DataOutBase::write_hdf5_parallel().
2960 */
2961 void
2962 write_filtered_data(DataOutBase::DataOutFilter &filtered_data) const;
2963
2964
2965 /**
2966 * Write data and grid to <tt>out</tt> according to the given data format.
2967 * This function simply calls the appropriate <tt>write_*</tt> function. If
2968 * no output format is requested, the <tt>default_format</tt> is written.
2969 *
2970 * An error occurs if no format is provided and the default format is
2971 * <tt>default_format</tt>.
2972 */
2973 void
2974 write(std::ostream &out,
2975 const DataOutBase::OutputFormat output_format =
2976 DataOutBase::default_format) const;
2977
2978 /**
2979 * Set the default format. The value set here is used anytime, output for
2980 * format <tt>default_format</tt> is requested.
2981 */
2982 void
2983 set_default_format(const DataOutBase::OutputFormat default_format);
2984
2985
2986 /**
2987 * Set the flags to be used for output. This method expects <tt>flags</tt>
2988 * to be a member of one of the child classes of <tt>OutputFlagsBase</tt>.
2989 */
2990 template <typename FlagType>
2991 void
2992 set_flags(const FlagType &flags);
2993
2994
2995 /**
2996 * A function that returns the same string as the respective function in the
2997 * base class does; the only exception being that if the parameter is
2998 * omitted, then the value for the present default format is returned, i.e.
2999 * the correct suffix for the format that was set through
3000 * set_default_format() or parse_parameters() before calling this function.
3001 */
3002 std::string
3003 default_suffix(const DataOutBase::OutputFormat output_format =
3004 DataOutBase::default_format) const;
3005
3006 /**
3007 * Declare parameters for all output formats by declaring subsections within
3008 * the parameter file for each output format and call the respective
3009 * <tt>declare_parameters</tt> functions of the flag classes for each output
3010 * format.
3011 *
3012 * Some of the declared subsections may not contain entries, if the
3013 * respective format does not export any flags.
3014 *
3015 * Note that the top-level parameters denoting the number of subdivisions
3016 * per patch and the output format are not declared, since they are only
3017 * passed to virtual functions and are not stored inside objects of this
3018 * type. You have to declare them yourself.
3019 */
3020 static void
3021 declare_parameters(ParameterHandler &prm);
3022
3023 /**
3024 * Read the parameters declared in declare_parameters() and set the flags
3025 * for the output formats accordingly.
3026 *
3027 * The flags thus obtained overwrite all previous contents of the flag
3028 * objects as default-constructed or set by the set_flags() function.
3029 */
3030 void
3031 parse_parameters(ParameterHandler &prm);
3032
3033 /**
3034 * Return an estimate for the memory consumption, in bytes, of this object.
3035 * This is not exact (but will usually be close) because calculating the
3036 * memory usage of trees (e.g., <tt>std::map</tt>) is difficult.
3037 */
3038 std::size_t
3039 memory_consumption() const;
3040
3041 protected:
3042 /**
3043 * This is the abstract function through which derived classes propagate
3044 * preprocessed data in the form of Patch structures (declared in the base
3045 * class DataOutBase) to the actual output function. You need to overload
3046 * this function to allow the output functions to know what they shall
3047 * print.
3048 */
3049 virtual const std::vector<DataOutBase::Patch<dim, spacedim>> &
3050 get_patches() const = 0;
3051
3052 /**
3053 * Abstract virtual function through which the names of data sets are
3054 * obtained by the output functions of the base class.
3055 */
3056 virtual std::vector<std::string>
3057 get_dataset_names() const = 0;
3058
3059 /**
3060 * This functions returns information about how the individual components of
3061 * output files that consist of more than one data set are to be
3062 * interpreted.
3063 *
3064 * It returns a list of index pairs and corresponding name and type indicating
3065 * which components of the output are to be considered vector- or
3066 * tensor-valued rather than just a collection of scalar data. The index pairs
3067 * are inclusive; for example, if we have a Stokes problem in 2d with
3068 * components (u,v,p), then the corresponding vector data range should be
3069 * (0,1), and the returned list would consist of only a single element with a
3070 * tuple such as (0,1,"velocity",component_is_part_of_vector).
3071 *
3072 * Since some of the derived classes do not know about non-scalar data, this
3073 * function has a default implementation that simply returns an empty
3074 * string, meaning that all data is to be considered a collection of scalar
3075 * fields.
3076 */
3077 virtual std::vector<
3078 std::tuple<unsigned int,
3079 unsigned int,
3080 std::string,
3081 DataComponentInterpretation::DataComponentInterpretation>>
3082 get_nonscalar_data_ranges() const;
3083
3084 /**
3085 * Validate that the names of the datasets returned by get_dataset_names() and
3086 * get_nonscalar_data_ranges() are valid. This currently consists of checking
3087 * that names are not used more than once. If an invalid state is encountered,
3088 * an Assert() will be triggered in debug mode.
3089 */
3090 void
3091 validate_dataset_names() const;
3092
3093
3094 /**
3095 * The default number of subdivisions for patches. This is filled by
3096 * parse_parameters() and should be obeyed by build_patches() in derived
3097 * classes.
3098 */
3099 unsigned int default_subdivisions;
3100
3101 private:
3102 /**
3103 * Standard output format. Use this format, if output format default_format
3104 * is requested. It can be changed by the <tt>set_format</tt> function or in
3105 * a parameter file.
3106 */
3107 DataOutBase::OutputFormat default_fmt;
3108
3109 /**
3110 * Flags to be used upon output of OpenDX data. Can be changed by using the
3111 * <tt>set_flags</tt> function.
3112 */
3113 DataOutBase::DXFlags dx_flags;
3114
3115 /**
3116 * Flags to be used upon output of UCD data. Can be changed by using the
3117 * <tt>set_flags</tt> function.
3118 */
3119 DataOutBase::UcdFlags ucd_flags;
3120
3121 /**
3122 * Flags to be used upon output of GNUPLOT data. Can be changed by using the
3123 * <tt>set_flags</tt> function.
3124 */
3125 DataOutBase::GnuplotFlags gnuplot_flags;
3126
3127 /**
3128 * Flags to be used upon output of POVRAY data. Can be changed by using the
3129 * <tt>set_flags</tt> function.
3130 */
3131 DataOutBase::PovrayFlags povray_flags;
3132
3133 /**
3134 * Flags to be used upon output of EPS data in one space dimension. Can be
3135 * changed by using the <tt>set_flags</tt> function.
3136 */
3137 DataOutBase::EpsFlags eps_flags;
3138
3139 /**
3140 * Flags to be used upon output of gmv data in one space dimension. Can be
3141 * changed by using the <tt>set_flags</tt> function.
3142 */
3143 DataOutBase::GmvFlags gmv_flags;
3144
3145 /**
3146 * Flags to be used upon output of hdf5 data in one space dimension. Can be
3147 * changed by using the <tt>set_flags</tt> function.
3148 */
3149 DataOutBase::Hdf5Flags hdf5_flags;
3150
3151 /**
3152 * Flags to be used upon output of Tecplot data in one space dimension. Can
3153 * be changed by using the <tt>set_flags</tt> function.
3154 */
3155 DataOutBase::TecplotFlags tecplot_flags;
3156
3157 /**
3158 * Flags to be used upon output of vtk data in one space dimension. Can be
3159 * changed by using the <tt>set_flags</tt> function.
3160 */
3161 DataOutBase::VtkFlags vtk_flags;
3162
3163 /**
3164 * Flags to be used upon output of svg data in one space dimension. Can be
3165 * changed by using the <tt>set_flags</tt> function.
3166 */
3167 DataOutBase::SvgFlags svg_flags;
3168
3169 /**
3170 * Flags to be used upon output of deal.II intermediate data in one space
3171 * dimension. Can be changed by using the <tt>set_flags</tt> function.
3172 */
3173 DataOutBase::Deal_II_IntermediateFlags deal_II_intermediate_flags;
3174 };
3175
3176
3177
3178 /**
3179 * A class that is used to read data written in deal.II intermediate format
3180 * back in, so that it can be written out in any of the other supported
3181 * graphics formats. This class has two main purposes:
3182 *
3183 * The first use of this class is so that application programs can defer the
3184 * decision of which graphics format to use until after the program has been
3185 * run. The data is written in intermediate format into a file, and later on
3186 * it can then be converted into any graphics format you wish. This may be
3187 * useful, for example, if you want to convert it to gnuplot format to get a
3188 * quick glimpse and later on want to convert it to OpenDX format as well to
3189 * get a high quality version of the data. The present class allows to read
3190 * this intermediate format back into the program, and allows it to be written
3191 * in any other supported format using the relevant functions of the base
3192 * class.
3193 *
3194 * The second use is mostly useful in parallel programs: rather than having
3195 * one central process generate the graphical output for the entire program,
3196 * one can let each process generate the graphical data for the cells it owns,
3197 * and write it into a separate file in intermediate format. Later on, all
3198 * these intermediate files can then be read back in and merged together, a
3199 * process that is fast compared to generating the data in the first place.
3200 * The use of the intermediate format is mostly because it allows separate
3201 * files to be merged, while this is almost impossible once the data has been
3202 * written out in any of the supported established graphics formats.
3203 *
3204 * This second use scenario is explained in some detail in the step-18 example
3205 * program.
3206 *
3207 * In order to read data back into this object, you have to know the template
3208 * parameters for the space dimension which were used when writing the
3209 * data. If this knowledge is available at compile time, then this is no
3210 * problem. However, if it is not (such as in a simple format converter), then
3211 * it needs to be figured out at run time, even though the compiler already
3212 * needs it at compile time. A way around using the
3213 * DataOutBase::determine_intermediate_format_dimensions() function.
3214 *
3215 * Note that the intermediate format is what its name suggests: a direct
3216 * representation of internal data. It isn't standardized and will change
3217 * whenever we change our internal representation. You can only expect to
3218 * process files written in this format using the same version of deal.II that
3219 * was used for writing.
3220 *
3221 * @ingroup input output
3222 */
3223 template <int dim, int spacedim = dim>
3224 class DataOutReader : public DataOutInterface<dim, spacedim>
3225 {
3226 public:
3227 /**
3228 * Read a sequence of patches as written previously by
3229 * <tt>DataOutBase::write_deal_II_intermediate</tt> and store them in the
3230 * present object. This overwrites any previous content.
3231 */
3232 void
3233 read(std::istream &in);
3234
3235 /**
3236 * Read all data previously written using
3237 * DataOutBase::write_deal_II_intermediate_in_parallel() from all
3238 * MPI ranks into this data structure.
3239 */
3240 void
3241 read_whole_parallel_file(std::istream &in);
3242
3243 /**
3244 * This function can be used to merge the patches read by the other object
3245 * into the patches that this present object stores. This is sometimes handy
3246 * if one has, for example, a domain decomposition algorithm where each
3247 * block is represented by a DoFHandler of its own, but one wants to output
3248 * the solution on all the blocks at the same time. Alternatively, it may
3249 * also be used for parallel programs, where each process only generates
3250 * output for its share of the cells, even if all processes can see all
3251 * cells.
3252 *
3253 * For this to work, the input files for the present object and the given
3254 * argument need to have the same number of output vectors, and they need to
3255 * use the same number of subdivisions per patch. The output will probably
3256 * look rather funny if patches in both objects overlap in space.
3257 *
3258 * If you call read() for this object after merging in patches, the previous
3259 * state is overwritten, and the merged-in patches are lost.
3260 *
3261 * This function will fail if either this or the other object did not yet
3262 * set up any patches.
3263 */
3264 void
3265 merge(const DataOutReader<dim, spacedim> &other);
3266
3267 /**
3268 * Exception
3269 */
3270 DeclExceptionMsg(ExcIncompatibleDatasetNames,
3271 "You are trying to merge two sets of patches for which the "
3272 "declared names of the variables do not match.");
3273 /**
3274 * Exception
3275 */
3276 DeclExceptionMsg(ExcIncompatiblePatchLists,
3277 "You are trying to merge two sets of patches for which the "
3278 "number of subdivisions or the number of vector components "
3279 "do not match.");
3280 /**
3281 * Exception
3282 */
3283 DeclException4(ExcIncompatibleDimensions,
3284 int,
3285 int,
3286 int,
3287 int,
3288 << "Either the dimensions <" << arg1 << "> and <" << arg2
3289 << "> or the space dimensions <" << arg3 << "> and <" << arg4
3290 << "> do not match!");
3291
3292 protected:
3293 /**
3294 * This is the function through which this class propagates preprocessed
3295 * data in the form of Patch structures (declared in the base class
3296 * DataOutBase) to the actual output function.
3297 *
3298 * It returns the patches as read the last time a stream was given to the
3299 * read() function.
3300 */
3301 virtual const std::vector<dealii::DataOutBase::Patch<dim, spacedim>> &
3302 get_patches() const override;
3303
3304 /**
3305 * Abstract virtual function through which the names of data sets are
3306 * obtained by the output functions of the base class.
3307 *
3308 * Return the names of the variables as read the last time we read a file.
3309 */
3310 virtual std::vector<std::string>
3311 get_dataset_names() const override;
3312
3313 /**
3314 * This functions returns information about how the individual components of
3315 * output files that consist of more than one data set are to be
3316 * interpreted.
3317 *
3318 * It returns a list of index pairs and corresponding name indicating which
3319 * components of the output are to be considered vector-valued rather than
3320 * just a collection of scalar data. The index pairs are inclusive; for
3321 * example, if we have a Stokes problem in 2d with components (u,v,p), then
3322 * the corresponding vector data range should be (0,1), and the returned
3323 * list would consist of only a single element with a tuple such as
3324 * (0,1,"velocity").
3325 *
3326 * Since some of the derived classes do not know about vector data, this
3327 * function has a default implementation that simply returns an empty
3328 * string, meaning that all data is to be considered a collection of scalar
3329 * fields.
3330 */
3331 virtual std::vector<
3332 std::tuple<unsigned int,
3333 unsigned int,
3334 std::string,
3335 DataComponentInterpretation::DataComponentInterpretation>>
3336 get_nonscalar_data_ranges() const override;
3337
3338 private:
3339 /**
3340 * Arrays holding the set of patches as well as the names of output
3341 * variables, all of which we read from an input stream.
3342 */
3343 std::vector<dealii::DataOutBase::Patch<dim, spacedim>> patches;
3344 std::vector<std::string> dataset_names;
3345
3346 /**
3347 * Information about whether certain components of the output field are to
3348 * be considered vectors.
3349 */
3350 std::vector<
3351 std::tuple<unsigned int,
3352 unsigned int,
3353 std::string,
3354 DataComponentInterpretation::DataComponentInterpretation>>
3355 nonscalar_data_ranges;
3356 };
3357
3358
3359
3360 /**
3361 * A class to store relevant data to use when writing a lightweight XDMF
3362 * file. The XDMF file in turn points to heavy data files (such as HDF5)
3363 * where the actual simulation data is stored.
3364 * This allows flexibility in arranging the data, and also
3365 * allows the mesh to be separated from the point data.
3366 */
3367 class XDMFEntry
3368 {
3369 public:
3370 /**
3371 * Default constructor that creates an invalid object.
3372 */
3373 XDMFEntry();
3374
3375 /**
3376 * Simplified constructor that calls the complete constructor for
3377 * cases where <code>solution_filename == mesh_filename</code>, and
3378 * <code>dim==spacedim</code>.
3379 */
3380 XDMFEntry(const std::string &filename,
3381 const double time,
3382 const std::uint64_t nodes,
3383 const std::uint64_t cells,
3384 const unsigned int dim,
3385 const ReferenceCell &cell_type);
3386
3387 /**
3388 * Simplified constructor that calls the complete constructor for
3389 * cases where <code>dim==spacedim</code>.
3390 */
3391 XDMFEntry(const std::string &mesh_filename,
3392 const std::string &solution_filename,
3393 const double time,
3394 const std::uint64_t nodes,
3395 const std::uint64_t cells,
3396 const unsigned int dim,
3397 const ReferenceCell &cell_type);
3398
3399 /**
3400 * Constructor that sets all members to provided parameters.
3401 */
3402 XDMFEntry(const std::string &mesh_filename,
3403 const std::string &solution_filename,
3404 const double time,
3405 const std::uint64_t nodes,
3406 const std::uint64_t cells,
3407 const unsigned int dim,
3408 const unsigned int spacedim,
3409 const ReferenceCell &cell_type);
3410
3411 /**
3412 * Record an attribute and associated dimensionality.
3413 */
3414 void
3415 add_attribute(const std::string &attr_name, const unsigned int dimension);
3416
3417 /**
3418 * Read or write the data of this object for serialization using the
3419 * [BOOST serialization
3420 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
3421 */
3422 template <class Archive>
3423 void
3424 serialize(Archive &ar, const unsigned int /*version*/)
3425 {
3426 ar &valid &h5_sol_filename &h5_mesh_filename &entry_time &num_nodes
3427 &num_cells &dimension &space_dimension &cell_type &attribute_dims;
3428 }
3429
3430 /**
3431 * Get the XDMF content associated with this entry.
3432 * If the entry is not valid, this returns an empty string.
3433 */
3434 std::string
3435 get_xdmf_content(const unsigned int indent_level) const;
3436
3437 private:
3438 /**
3439 * Whether this entry is valid and contains data to be written.
3440 */
3441 bool valid;
3442
3443 /**
3444 * The name of the HDF5 heavy data solution file this entry references.
3445 */
3446 std::string h5_sol_filename;
3447
3448 /**
3449 * The name of the HDF5 mesh file this entry references.
3450 */
3451 std::string h5_mesh_filename;
3452
3453 /**
3454 * The simulation time associated with this entry.
3455 */
3456 double entry_time;
3457
3458 /**
3459 * The number of data nodes.
3460 */
3461 std::uint64_t num_nodes;
3462
3463 /**
3464 * The number of data cells.
3465 */
3466 std::uint64_t num_cells;
3467
3468 /**
3469 * The dimension associated with the data.
3470 */
3471 unsigned int dimension;
3472
3473 /**
3474 * The dimension of the space the data lives in.
3475 * Note that dimension <= space_dimension.
3476 */
3477 unsigned int space_dimension;
3478
3479 /**
3480 * The type of cell in deal.II language. We currently only support
3481 * xdmf entries where all cells have the same type.
3482 */
3483 ReferenceCell cell_type;
3484
3485 /**
3486 * The attributes associated with this entry and their dimension.
3487 */
3488 std::map<std::string, unsigned int> attribute_dims;
3489 };
3490
3491
3492
3493 /* -------------------- inline functions ------------------- */
3494
3495 namespace DataOutBase
3496 {
3497 inline bool
3498 EpsFlags::RgbValues::is_grey() const
3499 {
3500 return (red == green) && (red == blue);
3501 }
3502
3503
3504 /* -------------------- template functions ------------------- */
3505
3506 /**
3507 * Output operator for an object of type <tt>DataOutBase::Patch</tt>. This
3508 * operator dumps the intermediate graphics format represented by the patch
3509 * data structure. It may later be converted into regular formats for a
3510 * number of graphics programs.
3511 */
3512 template <int dim, int spacedim>
3513 std::ostream &
3514 operator<<(std::ostream &out, const Patch<dim, spacedim> &patch);
3515
3516
3517
3518 /**
3519 * Input operator for an object of type <tt>DataOutBase::Patch</tt>. This
3520 * operator reads the intermediate graphics format represented by the patch
3521 * data structure, using the format in which it was written using the
3522 * operator<<.
3523 */
3524 template <int dim, int spacedim>
3525 std::istream &
3526 operator>>(std::istream &in, Patch<dim, spacedim> &patch);
3527 } // namespace DataOutBase
3528
3529
3530 DEAL_II_NAMESPACE_CLOSE
3531
3532 #endif