data_out_base.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1999 - 2019 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.h>
#include <deal.II/base/point.h>
#include <deal.II/base/table.h>

#include <deal.II/numerics/data_component_interpretation.h>

// To be able to serialize XDMFEntry
#include <boost/serialization/map.hpp>

#include <limits>
#include <string>
#include <tuple>
#include <typeinfo>
#include <vector>

// Only include the Tecplot API header if the appropriate files
// were detected by configure
#ifdef DEAL_II_HAVE_TECPLOT
#  include <string.h>

#  include "TECIO.h"
#endif

#include <ostream>

DEAL_II_NAMESPACE_OPEN


class ParameterHandler;
class XDMFEntry;

namespace DataOutBase
{
  template <int dim, int spacedim = dim>
  struct Patch
  {
    static const unsigned int space_dim = spacedim;

    Point<spacedim> vertices[GeometryInfo<dim>::vertices_per_cell];

    unsigned int neighbors[dim > 0 ? GeometryInfo<dim>::faces_per_cell : 1];

    unsigned int patch_index;

    unsigned int n_subdivisions;

    Table<2, float> data;

    bool points_are_available;

    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 unsigned int n_subdivisions;

    Table<2, float> data;

    bool points_are_available;

    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 TecplotFlags : public OutputFlagsBase<TecplotFlags>
  {
    DEAL_II_DEPRECATED const char *tecplot_binary_file_name;

    const char *zone_name;

    double solution_time;

    DEAL_II_DEPRECATED
    TecplotFlags(const char * tecplot_binary_file_name = nullptr,
                 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;

    enum ZlibCompressionLevel
    {
      no_compression,
      best_speed,
      best_compression,
      default_compression
    };

    ZlibCompressionLevel compression_level;

    bool write_higher_order_cells;

    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 ZlibCompressionLevel compression_level        = best_compression,
      const bool                 write_higher_order_cells = false);
  };


  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 unsigned int d1,
               const unsigned int d2,
               const unsigned int d3);

    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 vertices_per_cell;

    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,

    tecplot_binary,

    vtk,

    vtu,

    svg,

    deal_II_intermediate,

    hdf5
  };

  template <int dim, int spacedim>
  DEAL_II_DEPRECATED 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>>
      &            nonscalar_data_ranges,
    const DXFlags &flags,
    std::ostream & out);

  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>
  DEAL_II_DEPRECATED 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>>
      &             nonscalar_data_ranges,
    const EpsFlags &flags,
    std::ostream &  out);

  template <int dim, int spacedim>
  DEAL_II_DEPRECATED 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>>
      &             nonscalar_data_ranges,
    const EpsFlags &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>
  DEAL_II_DEPRECATED 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>>
      &             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>
  DEAL_II_DEPRECATED 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>>
      &             nonscalar_data_ranges,
    const GmvFlags &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>
  DEAL_II_DEPRECATED 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>>
      &                 nonscalar_data_ranges,
    const GnuplotFlags &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>
  DEAL_II_DEPRECATED 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>>
      &                nonscalar_data_ranges,
    const PovrayFlags &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>
  DEAL_II_DEPRECATED 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>>
      &                 nonscalar_data_ranges,
    const TecplotFlags &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>
  DEAL_II_DEPRECATED void
  write_tecplot_binary(
    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>>
      &                 nonscalar_data_ranges,
    const TecplotFlags &flags,
    std::ostream &      out);

  template <int dim, int spacedim>
  DEAL_II_DEPRECATED void
  write_tecplot_binary(
    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>
  DEAL_II_DEPRECATED 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>>
      &             nonscalar_data_ranges,
    const UcdFlags &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>
  DEAL_II_DEPRECATED 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>>
      &             nonscalar_data_ranges,
    const VtkFlags &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>
  DEAL_II_DEPRECATED 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>>
      &             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>
  DEAL_II_DEPRECATED 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>>
      &             nonscalar_data_ranges,
    const VtkFlags &flags,
    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);

  DEAL_II_DEPRECATED
  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>>
      &nonscalar_data_ranges);

  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);

  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>
  DEAL_II_DEPRECATED 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>>
      &             nonscalar_data_ranges,
    const SvgFlags &flags,
    std::ostream &  out);

  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>
  DEAL_II_DEPRECATED 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>>
      &                              nonscalar_data_ranges,
    const Deal_II_IntermediateFlags &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_hdf5_parallel(const std::vector<Patch<dim, spacedim>> &patches,
                      const DataOutFilter &                    data_filter,
                      const std::string &                      filename,
                      MPI_Comm                                 comm);

  template <int dim, int spacedim>
  void
  write_hdf5_parallel(const std::vector<Patch<dim, spacedim>> &patches,
                      const DataOutFilter &                    data_filter,
                      const bool                               write_mesh_file,
                      const std::string &                      mesh_filename,
                      const std::string &solution_filename,
                      MPI_Comm           comm);

  template <int dim, int spacedim>
  DEAL_II_DEPRECATED 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>>
      &            nonscalar_data_ranges,
    DataOutFilter &filtered_data);

  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;

  DEAL_II_DEPRECATED
  void
  write_tecplot_binary(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, MPI_Comm comm) const;

  void
  write_pvtu_record(std::ostream &                  out,
                    const std::vector<std::string> &piece_names) const;

  void
  write_svg(std::ostream &out) const;

  void
  write_deal_II_intermediate(std::ostream &out) const;

  XDMFEntry
  create_xdmf_entry(const DataOutBase::DataOutFilter &data_filter,
                    const std::string &               h5_filename,
                    const double                      cur_time,
                    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,
                    MPI_Comm                          comm) const;

  void
  write_xdmf_file(const std::vector<XDMFEntry> &entries,
                  const std::string &           filename,
                  MPI_Comm                      comm) const;

  void
  write_hdf5_parallel(const DataOutBase::DataOutFilter &data_filter,
                      const std::string &               filename,
                      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,
                      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;

  DEAL_II_DEPRECATED
  virtual std::vector<std::tuple<unsigned int, unsigned int, std::string>>
  get_vector_data_ranges() const;

  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::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
  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 unsigned int nodes,
            const unsigned int cells,
            const unsigned int dim);

  XDMFEntry(const std::string &mesh_filename,
            const std::string &solution_filename,
            const double       time,
            const unsigned int nodes,
            const unsigned int cells,
            const unsigned int dim);

  XDMFEntry(const std::string &mesh_filename,
            const std::string &solution_filename,
            const double       time,
            const unsigned int nodes,
            const unsigned int cells,
            const unsigned int dim,
            const unsigned int spacedim);

  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 &attribute_dims;
  }

  std::string
  get_xdmf_content(const unsigned int indent_level) const;

private:
  bool valid;

  std::string h5_sol_filename;

  std::string h5_mesh_filename;

  double entry_time;

  unsigned int num_nodes;

  unsigned int num_cells;

  unsigned int dimension;

  unsigned int space_dimension;

  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