data_out_base.h

Go to the documentation of this file.

// ---------------------------------------------------------------------
//
// Copyright (C) 1999 - 2023 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------
 
#ifndef dealii_data_out_base_h
#define dealii_data_out_base_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/geometry_info.h>
#include <deal.II/base/mpi_stub.h>
#include <deal.II/base/point.h>
#include <deal.II/base/table.h>
 
#include <deal.II/grid/reference_cell.h>
 
#include <deal.II/numerics/data_component_interpretation.h>
 
// To be able to serialize XDMFEntry
#include <boost/serialization/map.hpp>
 
#include <limits>
#include <ostream>
#include <string>
#include <tuple>
#include <typeinfo>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declarations
#ifndef DOXYGEN
class ParameterHandler;
class XDMFEntry;
#endif
 
namespace DataOutBase
{
  enum class CompressionLevel
  {
    no_compression,
    best_speed,
    best_compression,
    default_compression,
    plain_text
  };
 
 
  template <int dim, int spacedim = dim>
  struct Patch
  {
    static const unsigned int space_dim = spacedim;
 
    std::array<Point<spacedim>, GeometryInfo<dim>::vertices_per_cell> vertices;
 
    std::array<unsigned int, GeometryInfo<dim>::faces_per_cell> neighbors;
 
    unsigned int patch_index;
 
    unsigned int n_subdivisions;
 
    Table<2, float> data;
 
    bool points_are_available;
 
    ReferenceCell reference_cell;
 
    Patch();
 
    bool
    operator==(const Patch &patch) const;
 
    std::size_t
    memory_consumption() const;
 
    void
    swap(Patch<dim, spacedim> &other_patch);
 
    static const unsigned int no_neighbor = numbers::invalid_unsigned_int;
 
    DeclException2(
      ExcInvalidCombinationOfDimensions,
      int,
      int,
      << "It is not possible to have a structural dimension of " << arg1
      << " to be larger than the space dimension of the surrounding"
      << " space " << arg2);
  };
 
 
 
  template <int spacedim>
  struct Patch<0, spacedim>
  {
    static const unsigned int space_dim = spacedim;
 
    Point<spacedim> vertices[1];
 
    static unsigned int neighbors[1];
 
    unsigned int patch_index;
 
    static const unsigned int n_subdivisions;
 
    Table<2, float> data;
 
    bool points_are_available;
 
    static const ReferenceCell reference_cell;
 
    Patch();
 
    bool
    operator==(const Patch &patch) const;
 
    std::size_t
    memory_consumption() const;
 
    void
    swap(Patch<0, spacedim> &other_patch);
 
    static const unsigned int no_neighbor = numbers::invalid_unsigned_int;
 
    DeclException2(
      ExcInvalidCombinationOfDimensions,
      int,
      int,
      << "It is not possible to have a structural dimension of " << arg1
      << " to be larger than the space dimension of the surrounding"
      << " space " << arg2);
  };
 
 
  template <typename FlagsType>
  struct OutputFlagsBase
  {
    static void
    declare_parameters(ParameterHandler &prm);
 
    void
    parse_parameters(const ParameterHandler &prm);
 
    std::size_t
    memory_consumption() const;
  };
 
 
  template <typename FlagsType>
  void
  OutputFlagsBase<FlagsType>::declare_parameters(ParameterHandler &)
  {}
 
 
  template <typename FlagsType>
  void
  OutputFlagsBase<FlagsType>::parse_parameters(const ParameterHandler &)
  {}
 
 
  template <typename FlagsType>
  std::size_t
  OutputFlagsBase<FlagsType>::memory_consumption() const
  {
    return sizeof(FlagsType);
  }
 
 
  struct DXFlags : public OutputFlagsBase<DXFlags>
  {
    bool write_neighbors;
    bool int_binary;
    bool coordinates_binary;
 
    bool data_binary;
 
    bool data_double;
 
    DXFlags(const bool write_neighbors    = false,
            const bool int_binary         = false,
            const bool coordinates_binary = false,
            const bool data_binary        = false);
 
    static void
    declare_parameters(ParameterHandler &prm);
 
    void
    parse_parameters(const ParameterHandler &prm);
  };
 
  struct UcdFlags : public OutputFlagsBase<UcdFlags>
  {
    bool write_preamble;
 
    UcdFlags(const bool write_preamble = false);
 
    static void
    declare_parameters(ParameterHandler &prm);
 
    void
    parse_parameters(const ParameterHandler &prm);
  };
 
  struct GnuplotFlags : public OutputFlagsBase<GnuplotFlags>
  {
    GnuplotFlags();
 
    GnuplotFlags(const std::vector<std::string> &space_dimension_labels);
 
    std::vector<std::string> space_dimension_labels;
 
    std::size_t
    memory_consumption() const;
 
    DeclExceptionMsg(ExcNotEnoughSpaceDimensionLabels,
                     "There should be at least one space dimension per spatial "
                     "dimension (extras are ignored).");
  };
 
  struct PovrayFlags : public OutputFlagsBase<PovrayFlags>
  {
    bool smooth;
 
    bool bicubic_patch;
 
    bool external_data;
 
    PovrayFlags(const bool smooth        = false,
                const bool bicubic_patch = false,
                const bool external_data = false);
 
    static void
    declare_parameters(ParameterHandler &prm);
 
    void
    parse_parameters(const ParameterHandler &prm);
  };
 
 
  struct EpsFlags : public OutputFlagsBase<EpsFlags>
  {
    unsigned int height_vector;
 
    unsigned int color_vector;
 
    enum SizeType
    {
      width,
      height
    };
 
    SizeType size_type;
 
    unsigned int size;
 
    double line_width;
 
    double azimut_angle;
 
    double turn_angle;
 
    double z_scaling;
 
    bool draw_mesh;
 
    bool draw_cells;
 
    bool shade_cells;
 
    struct RgbValues
    {
      float red;
      float green;
      float blue;
 
      bool
      is_grey() const;
    };
 
    using ColorFunction = RgbValues (*)(const double value,
                                        const double min_value,
                                        const double max_value);
 
    ColorFunction color_function;
 
 
    static RgbValues
    default_color_function(const double value,
                           const double min_value,
                           const double max_value);
 
    static RgbValues
    grey_scale_color_function(const double value,
                              const double min_value,
                              const double max_value);
 
    static RgbValues
    reverse_grey_scale_color_function(const double value,
                                      const double min_value,
                                      const double max_value);
 
    EpsFlags(const unsigned int  height_vector  = 0,
             const unsigned int  color_vector   = 0,
             const SizeType      size_type      = width,
             const unsigned int  size           = 300,
             const double        line_width     = 0.5,
             const double        azimut_angle   = 60,
             const double        turn_angle     = 30,
             const double        z_scaling      = 1.0,
             const bool          draw_mesh      = true,
             const bool          draw_cells     = true,
             const bool          shade_cells    = true,
             const ColorFunction color_function = &default_color_function);
 
    static void
    declare_parameters(ParameterHandler &prm);
 
    void
    parse_parameters(const ParameterHandler &prm);
  };
 
  struct GmvFlags : public OutputFlagsBase<GmvFlags>
  {};
 
  struct Hdf5Flags : public OutputFlagsBase<Hdf5Flags>
  {
    DataOutBase::CompressionLevel compression_level;
 
    explicit Hdf5Flags(
      const CompressionLevel compression_level = CompressionLevel::best_speed);
  };
 
  struct TecplotFlags : public OutputFlagsBase<TecplotFlags>
  {
    const char *zone_name;
 
    double solution_time;
 
    TecplotFlags(const char * zone_name     = nullptr,
                 const double solution_time = -1.0);
 
    std::size_t
    memory_consumption() const;
  };
 
  struct VtkFlags : public OutputFlagsBase<VtkFlags>
  {
    double time;
 
    unsigned int cycle;
 
    bool print_date_and_time;
 
    using ZlibCompressionLevel DEAL_II_DEPRECATED =
      DataOutBase::CompressionLevel;
 
    DEAL_II_DEPRECATED static const DataOutBase::CompressionLevel
      no_compression = DataOutBase::CompressionLevel::no_compression;
    DEAL_II_DEPRECATED static const DataOutBase::CompressionLevel
      best_compression = DataOutBase::CompressionLevel::best_compression;
    DEAL_II_DEPRECATED static const DataOutBase::CompressionLevel best_speed =
      DataOutBase::CompressionLevel::best_speed;
    DEAL_II_DEPRECATED static const DataOutBase::CompressionLevel
      default_compression = DataOutBase::CompressionLevel::default_compression;
 
    DataOutBase::CompressionLevel compression_level;
 
    bool write_higher_order_cells;
 
    std::map<std::string, std::string> physical_units;
 
    explicit VtkFlags(
      const double           time  = std::numeric_limits<double>::min(),
      const unsigned int     cycle = std::numeric_limits<unsigned int>::min(),
      const bool             print_date_and_time = true,
      const CompressionLevel compression_level   = CompressionLevel::best_speed,
      const bool             write_higher_order_cells          = false,
      const std::map<std::string, std::string> &physical_units = {});
  };
 
 
  struct SvgFlags : public OutputFlagsBase<SvgFlags>
  {
    unsigned int height;
 
    unsigned int width;
 
    unsigned int height_vector;
 
    int azimuth_angle, polar_angle;
 
    unsigned int line_thickness;
 
    bool margin;
 
    bool draw_colorbar;
 
    SvgFlags(const unsigned int height_vector  = 0,
             const int          azimuth_angle  = 37,
             const int          polar_angle    = 45,
             const unsigned int line_thickness = 1,
             const bool         margin         = true,
             const bool         draw_colorbar  = true);
  };
 
 
  struct Deal_II_IntermediateFlags
    : public OutputFlagsBase<Deal_II_IntermediateFlags>
  {
    static const unsigned int format_version;
  };
 
  struct DataOutFilterFlags
  {
    bool filter_duplicate_vertices;
 
    bool xdmf_hdf5_output;
 
    DataOutFilterFlags(const bool filter_duplicate_vertices = false,
                       const bool xdmf_hdf5_output          = false);
 
    static void
    declare_parameters(ParameterHandler &prm);
 
    void
    parse_parameters(const ParameterHandler &prm);
 
    std::size_t
    memory_consumption() const;
  };
 
  class DataOutFilter
  {
  public:
    DataOutFilter();
 
    DataOutFilter(const DataOutBase::DataOutFilterFlags &flags);
 
    template <int dim>
    void
    write_point(const unsigned int index, const Point<dim> &p);
 
    template <int dim>
    void
    write_cell(const unsigned int                   index,
               const unsigned int                   start,
               const std::array<unsigned int, dim> &offsets);
 
    void
    write_cell_single(const unsigned int   index,
                      const unsigned int   start,
                      const unsigned int   n_points,
                      const ReferenceCell &reference_cell);
 
    void
    write_data_set(const std::string &     name,
                   const unsigned int      dimension,
                   const unsigned int      set_num,
                   const Table<2, double> &data_vectors);
 
    void
    fill_node_data(std::vector<double> &node_data) const;
 
    void
    fill_cell_data(const unsigned int         local_node_offset,
                   std::vector<unsigned int> &cell_data) const;
 
    std::string
    get_data_set_name(const unsigned int set_num) const;
 
    unsigned int
    get_data_set_dim(const unsigned int set_num) const;
 
    const double *
    get_data_set(const unsigned int set_num) const;
 
    unsigned int
    n_nodes() const;
 
    unsigned int
    n_cells() const;
 
    unsigned int
    n_data_sets() const;
 
    void
    flush_points();
 
    void
    flush_cells();
 
 
  private:
    struct Point3Comp
    {
      bool
      operator()(const Point<3> &one, const Point<3> &two) const
      {
        /*
         * The return statement below is an optimized version of the following
         * code:
         *
         * for (unsigned int d=0; d<3; ++d)
         * {
         *   if (one(d) < two(d))
         *     return true;
         *   else if (one(d) > two(d))
         *     return false;
         * }
         * return false;
         */
 
        return (one(0) < two(0) ||
                (!(two(0) < one(0)) &&
                 (one(1) < two(1) || (!(two(1) < one(1)) && one(2) < two(2)))));
      }
    };
 
    using Map3DPoint = std::multimap<Point<3>, unsigned int, Point3Comp>;
 
    DataOutBase::DataOutFilterFlags flags;
 
    unsigned int node_dim;
 
    unsigned int num_cells;
 
    Map3DPoint existing_points;
 
    std::map<unsigned int, unsigned int> filtered_points;
 
    std::map<unsigned int, unsigned int> filtered_cells;
 
    std::vector<std::string> data_set_names;
 
    std::vector<unsigned int> data_set_dims;
 
    std::vector<std::vector<double>> data_sets;
 
    void
    internal_add_cell(const unsigned int cell_index,
                      const unsigned int pt_index);
  };
 
 
  enum OutputFormat
  {
    default_format,
 
    none,
 
    dx,
 
    ucd,
 
    gnuplot,
 
    povray,
 
    eps,
 
    gmv,
 
    tecplot,
 
    vtk,
 
    vtu,
 
    svg,
 
    deal_II_intermediate,
 
    hdf5
  };
 
 
  template <int dim, int spacedim>
  void
  write_dx(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &            nonscalar_data_ranges,
    const DXFlags &flags,
    std::ostream & out);
 
  template <int spacedim>
  void
  write_eps(
    const std::vector<Patch<2, spacedim>> &patches,
    const std::vector<std::string> &       data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const EpsFlags &flags,
    std::ostream &  out);
 
  template <int dim, int spacedim>
  void
  write_eps(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const EpsFlags &flags,
    std::ostream &  out);
 
 
  template <int dim, int spacedim>
  void
  write_gmv(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const GmvFlags &flags,
    std::ostream &  out);
 
  template <int dim, int spacedim>
  void
  write_gnuplot(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &                 nonscalar_data_ranges,
    const GnuplotFlags &flags,
    std::ostream &      out);
 
  template <int dim, int spacedim>
  void
  write_povray(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &                nonscalar_data_ranges,
    const PovrayFlags &flags,
    std::ostream &     out);
 
  template <int dim, int spacedim>
  void
  write_tecplot(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &                 nonscalar_data_ranges,
    const TecplotFlags &flags,
    std::ostream &      out);
 
  template <int dim, int spacedim>
  void
  write_ucd(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const UcdFlags &flags,
    std::ostream &  out);
 
  template <int dim, int spacedim>
  void
  write_vtk(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const VtkFlags &flags,
    std::ostream &  out);
 
 
  template <int dim, int spacedim>
  void
  write_vtu(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const VtkFlags &flags,
    std::ostream &  out);
 
  void
  write_vtu_header(std::ostream &out, const VtkFlags &flags);
 
  void
  write_vtu_footer(std::ostream &out);
 
  template <int dim, int spacedim>
  void
  write_vtu_main(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const VtkFlags &flags,
    std::ostream &  out);
 
  void
  write_pvtu_record(
    std::ostream &                  out,
    const std::vector<std::string> &piece_names,
    const std::vector<std::string> &data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const VtkFlags &flags);
 
  void
  write_pvd_record(
    std::ostream &                                     out,
    const std::vector<std::pair<double, std::string>> &times_and_names);
 
  void
  write_visit_record(std::ostream &                  out,
                     const std::vector<std::string> &piece_names);
 
  void
  write_visit_record(std::ostream &                               out,
                     const std::vector<std::vector<std::string>> &piece_names);
 
  void
  write_visit_record(
    std::ostream &out,
    const std::vector<std::pair<double, std::vector<std::string>>>
      &times_and_piece_names);
 
  template <int spacedim>
  void
  write_svg(
    const std::vector<Patch<2, spacedim>> &patches,
    const std::vector<std::string> &       data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &             nonscalar_data_ranges,
    const SvgFlags &flags,
    std::ostream &  out);
 
  template <int dim, int spacedim>
  void
  write_deal_II_intermediate(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &                              nonscalar_data_ranges,
    const Deal_II_IntermediateFlags &flags,
    std::ostream &                   out);
 
  template <int dim, int spacedim>
  void
  write_deal_II_intermediate_in_parallel(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &                              nonscalar_data_ranges,
    const Deal_II_IntermediateFlags &flags,
    const std::string &              filename,
    const MPI_Comm                   comm,
    const CompressionLevel           compression);
 
  template <int dim, int spacedim>
  void
  write_hdf5_parallel(const std::vector<Patch<dim, spacedim>> &patches,
                      const DataOutFilter &                    data_filter,
                      const DataOutBase::Hdf5Flags &           flags,
                      const std::string &                      filename,
                      const MPI_Comm                           comm);
 
  template <int dim, int spacedim>
  void
  write_hdf5_parallel(const std::vector<Patch<dim, spacedim>> &patches,
                      const DataOutFilter &                    data_filter,
                      const DataOutBase::Hdf5Flags &           flags,
                      const bool                               write_mesh_file,
                      const std::string &                      mesh_filename,
                      const std::string &solution_filename,
                      const MPI_Comm     comm);
 
  template <int dim, int spacedim>
  void
  write_filtered_data(
    const std::vector<Patch<dim, spacedim>> &patches,
    const std::vector<std::string> &         data_names,
    const std::vector<
      std::tuple<unsigned int,
                 unsigned int,
                 std::string,
                 DataComponentInterpretation::DataComponentInterpretation>>
      &            nonscalar_data_ranges,
    DataOutFilter &filtered_data);
 
  std::pair<unsigned int, unsigned int>
  determine_intermediate_format_dimensions(std::istream &input);
 
  OutputFormat
  parse_output_format(const std::string &format_name);
 
  std::string
  get_output_format_names();
 
  std::string
  default_suffix(const OutputFormat output_format);
 
  DeclException2(ExcInvalidDatasetSize,
                 int,
                 int,
                 << "The number of points in this data set is " << arg1
                 << ", but we expected " << arg2
                 << " in each space direction.");
  DeclExceptionMsg(ExcNoPatches,
                   "You are trying to write graphical data into a file, but "
                   "no data is available in the intermediate format that "
                   "the DataOutBase functions require. Did you forget to "
                   "call a function such as DataOut::build_patches()?");
  DeclExceptionMsg(ExcTecplotAPIError,
                   "The error code of one of the Tecplot functions was "
                   "not zero as expected.");
  DeclException1(ExcErrorOpeningTecplotFile,
                 char *,
                 << "There was an error opening Tecplot file " << arg1
                 << " for output.");
 
} // namespace DataOutBase
 
 
 
template <int dim, int spacedim = dim>
class DataOutInterface
{
public:
  DataOutInterface();
 
  virtual ~DataOutInterface() = default;
 
  void
  write_dx(std::ostream &out) const;
 
  void
  write_eps(std::ostream &out) const;
 
  void
  write_gmv(std::ostream &out) const;
 
  void
  write_gnuplot(std::ostream &out) const;
 
  void
  write_povray(std::ostream &out) const;
 
  void
  write_tecplot(std::ostream &out) const;
 
  void
  write_ucd(std::ostream &out) const;
 
  void
  write_vtk(std::ostream &out) const;
 
  void
  write_vtu(std::ostream &out) const;
 
  void
  write_vtu_in_parallel(const std::string &filename, const MPI_Comm comm) const;
 
  void
  write_pvtu_record(std::ostream &                  out,
                    const std::vector<std::string> &piece_names) const;
 
  std::string
  write_vtu_with_pvtu_record(
    const std::string &directory,
    const std::string &filename_without_extension,
    const unsigned int counter,
    const MPI_Comm     mpi_communicator,
    const unsigned int n_digits_for_counter = numbers::invalid_unsigned_int,
    const unsigned int n_groups             = 0) const;
 
  void
  write_svg(std::ostream &out) const;
 
  void
  write_deal_II_intermediate(std::ostream &out) const;
 
  void
  write_deal_II_intermediate_in_parallel(
    const std::string &                 filename,
    const MPI_Comm                      comm,
    const DataOutBase::CompressionLevel compression) const;
 
  XDMFEntry
  create_xdmf_entry(const DataOutBase::DataOutFilter &data_filter,
                    const std::string &               h5_filename,
                    const double                      cur_time,
                    const MPI_Comm                    comm) const;
 
  XDMFEntry
  create_xdmf_entry(const DataOutBase::DataOutFilter &data_filter,
                    const std::string &               h5_mesh_filename,
                    const std::string &               h5_solution_filename,
                    const double                      cur_time,
                    const MPI_Comm                    comm) const;
 
  void
  write_xdmf_file(const std::vector<XDMFEntry> &entries,
                  const std::string &           filename,
                  const MPI_Comm                comm) const;
 
  void
  write_hdf5_parallel(const DataOutBase::DataOutFilter &data_filter,
                      const std::string &               filename,
                      const MPI_Comm                    comm) const;
 
  void
  write_hdf5_parallel(const DataOutBase::DataOutFilter &data_filter,
                      const bool                        write_mesh_file,
                      const std::string &               mesh_filename,
                      const std::string &               solution_filename,
                      const MPI_Comm                    comm) const;
 
  void
  write_filtered_data(DataOutBase::DataOutFilter &filtered_data) const;
 
 
  void
  write(std::ostream &                  out,
        const DataOutBase::OutputFormat output_format =
          DataOutBase::default_format) const;
 
  void
  set_default_format(const DataOutBase::OutputFormat default_format);
 
 
  template <typename FlagType>
  void
  set_flags(const FlagType &flags);
 
 
  std::string
  default_suffix(const DataOutBase::OutputFormat output_format =
                   DataOutBase::default_format) const;
 
  static void
  declare_parameters(ParameterHandler &prm);
 
  void
  parse_parameters(ParameterHandler &prm);
 
  std::size_t
  memory_consumption() const;
 
protected:
  virtual const std::vector<DataOutBase::Patch<dim, spacedim>> &
  get_patches() const = 0;
 
  virtual std::vector<std::string>
  get_dataset_names() const = 0;
 
  virtual std::vector<
    std::tuple<unsigned int,
               unsigned int,
               std::string,
               DataComponentInterpretation::DataComponentInterpretation>>
  get_nonscalar_data_ranges() const;
 
  void
  validate_dataset_names() const;
 
 
  unsigned int default_subdivisions;
 
private:
  DataOutBase::OutputFormat default_fmt;
 
  DataOutBase::DXFlags dx_flags;
 
  DataOutBase::UcdFlags ucd_flags;
 
  DataOutBase::GnuplotFlags gnuplot_flags;
 
  DataOutBase::PovrayFlags povray_flags;
 
  DataOutBase::EpsFlags eps_flags;
 
  DataOutBase::GmvFlags gmv_flags;
 
  DataOutBase::Hdf5Flags hdf5_flags;
 
  DataOutBase::TecplotFlags tecplot_flags;
 
  DataOutBase::VtkFlags vtk_flags;
 
  DataOutBase::SvgFlags svg_flags;
 
  DataOutBase::Deal_II_IntermediateFlags deal_II_intermediate_flags;
};
 
 
 
template <int dim, int spacedim = dim>
class DataOutReader : public DataOutInterface<dim, spacedim>
{
public:
  void
  read(std::istream &in);
 
  void
  read_whole_parallel_file(std::istream &in);
 
  void
  merge(const DataOutReader<dim, spacedim> &other);
 
  DeclExceptionMsg(ExcIncompatibleDatasetNames,
                   "You are trying to merge two sets of patches for which the "
                   "declared names of the variables do not match.");
  DeclExceptionMsg(ExcIncompatiblePatchLists,
                   "You are trying to merge two sets of patches for which the "
                   "number of subdivisions or the number of vector components "
                   "do not match.");
  DeclException4(ExcIncompatibleDimensions,
                 int,
                 int,
                 int,
                 int,
                 << "Either the dimensions <" << arg1 << "> and <" << arg2
                 << "> or the space dimensions <" << arg3 << "> and <" << arg4
                 << "> do not match!");
 
protected:
  virtual const std::vector<::DataOutBase::Patch<dim, spacedim>> &
  get_patches() const override;
 
  virtual std::vector<std::string>
  get_dataset_names() const override;
 
  virtual std::vector<
    std::tuple<unsigned int,
               unsigned int,
               std::string,
               DataComponentInterpretation::DataComponentInterpretation>>
  get_nonscalar_data_ranges() const override;
 
private:
  std::vector<::DataOutBase::Patch<dim, spacedim>> patches;
  std::vector<std::string>                               dataset_names;
 
  std::vector<
    std::tuple<unsigned int,
               unsigned int,
               std::string,
               DataComponentInterpretation::DataComponentInterpretation>>
    nonscalar_data_ranges;
};
 
 
 
class XDMFEntry
{
public:
  XDMFEntry();
 
  XDMFEntry(const std::string &  filename,
            const double         time,
            const std::uint64_t  nodes,
            const std::uint64_t  cells,
            const unsigned int   dim,
            const ReferenceCell &cell_type);
 
  XDMFEntry(const std::string & filename,
            const double        time,
            const std::uint64_t nodes,
            const std::uint64_t cells,
            const unsigned int  dim);
 
  XDMFEntry(const std::string & mesh_filename,
            const std::string & solution_filename,
            const double        time,
            const std::uint64_t nodes,
            const std::uint64_t cells,
            const unsigned int  dim);
 
  XDMFEntry(const std::string &  mesh_filename,
            const std::string &  solution_filename,
            const double         time,
            const std::uint64_t  nodes,
            const std::uint64_t  cells,
            const unsigned int   dim,
            const ReferenceCell &cell_type);
 
  DEAL_II_DEPRECATED
  XDMFEntry(const std::string & mesh_filename,
            const std::string & solution_filename,
            const double        time,
            const std::uint64_t nodes,
            const std::uint64_t cells,
            const unsigned int  dim,
            const unsigned int  spacedim);
 
  XDMFEntry(const std::string &  mesh_filename,
            const std::string &  solution_filename,
            const double         time,
            const std::uint64_t  nodes,
            const std::uint64_t  cells,
            const unsigned int   dim,
            const unsigned int   spacedim,
            const ReferenceCell &cell_type);
 
  void
  add_attribute(const std::string &attr_name, const unsigned int dimension);
 
  template <class Archive>
  void
  serialize(Archive &ar, const unsigned int /*version*/)
  {
    ar &valid &h5_sol_filename &h5_mesh_filename &entry_time &num_nodes
      &num_cells &dimension &space_dimension &cell_type &attribute_dims;
  }
 
  std::string
  get_xdmf_content(const unsigned int indent_level) const;
 
  DEAL_II_DEPRECATED
  std::string
  get_xdmf_content(const unsigned int   indent_level,
                   const ReferenceCell &reference_cell) const;
 
private:
  bool valid;
 
  std::string h5_sol_filename;
 
  std::string h5_mesh_filename;
 
  double entry_time;
 
  std::uint64_t num_nodes;
 
  std::uint64_t num_cells;
 
  unsigned int dimension;
 
  unsigned int space_dimension;
 
  ReferenceCell cell_type;
 
  std::map<std::string, unsigned int> attribute_dims;
};
 
 
 
/* -------------------- inline functions ------------------- */
 
namespace DataOutBase
{
  inline bool
  EpsFlags::RgbValues::is_grey() const
  {
    return (red == green) && (red == blue);
  }
 
 
  /* -------------------- template functions ------------------- */
 
  template <int dim, int spacedim>
  std::ostream &
  operator<<(std::ostream &out, const Patch<dim, spacedim> &patch);
 
 
 
  template <int dim, int spacedim>
  std::istream &
  operator>>(std::istream &in, Patch<dim, spacedim> &patch);
} // namespace DataOutBase
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif