data_out_base.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1999 - 2016 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 at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii__data_out_base_h
#define dealii__data_out_base_h


#include <deal.II/base/config.h>
#include <deal.II/base/point.h>
#include <deal.II/base/table.h>
#include <deal.II/base/geometry_info.h>
#include <deal.II/base/std_cxx11/tuple.h>

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

#include <deal.II/base/mpi.h>

// Only include the Tecplot API header if the appropriate files
// were detected by configure
#ifdef DEAL_II_HAVE_TECPLOT
#  include "TECIO.h"
#  include <string.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<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>
  {};

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

    typedef RgbValues (*ColorFunction) (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>
  {
    const char *tecplot_binary_file_name;

    const char *zone_name;

    double solution_time;

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

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


  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
  {
  private:
    struct Point3Comp
    {
      bool operator() (const Point<3> &lhs, const Point<3> &rhs) const
      {
        return (lhs(0) < rhs(0) || (!(rhs(0) < lhs(0)) && (lhs(1) < rhs(1) || (!(rhs(1) < lhs(1)) && lhs(2) < rhs(2)))));
      }
    };

    typedef std::multimap<Point<3>, unsigned int, Point3Comp> Map3DPoint;

    DataOutBase::DataOutFilterFlags   flags;

    int         node_dim;

    int         n_cell_verts;

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

  public:
    DataOutFilter() : flags(false, true) {};
    DataOutFilter(const DataOutBase::DataOutFilterFlags &flags) : flags(flags) {};

    template<int dim>
    void write_point(const unsigned int &index, const Point<dim> &p);

    template<int dim>
    void write_cell(unsigned int index, unsigned int start, unsigned int d1, unsigned int d2, 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
    {
      return data_set_names.at(set_num);
    };

    unsigned int get_data_set_dim(const unsigned int &set_num) const
    {
      return data_set_dims.at(set_num);
    };

    const double *get_data_set(const unsigned int &set_num) const
    {
      return &data_sets[set_num][0];
    };

    unsigned int n_nodes() const
    {
      return existing_points.size();
    };

    unsigned int n_cells() const
    {
      return filtered_cells.size()/n_cell_verts;
    };

    unsigned int n_data_sets() const
    {
      return data_set_names.size();
    };

    void flush_points () {};

    void flush_cells () {};

  };


  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>
  void write_dx (const std::vector<Patch<dim,spacedim> > &patches,
                 const std::vector<std::string>          &data_names,
                 const std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_data_ranges,
                      const TecplotFlags                      &flags,
                      std::ostream                            &out);

  template <int dim, int spacedim>
  void write_tecplot_binary (
    const std::vector<Patch<dim,spacedim> > &patches,
    const std::vector<std::string>          &data_names,
    const std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_data_ranges,
                       const VtkFlags                          &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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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>
  void write_filtered_data (const std::vector<Patch<dim,spacedim> > &patches,
                            const std::vector<std::string>          &data_names,
                            const std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> > &vector_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.");
  DeclException0 (ExcNoPatches);
  DeclException0 (ExcTecplotAPIError);
  DeclException1 (ExcErrorOpeningTecplotFile,
                  char *,
                  << "There was an error opening Tecplot file " << arg1
                  << " for output");

}




template <int dim, int spacedim=dim>
class DataOutInterface
{
public:
  DataOutInterface ();

  virtual ~DataOutInterface ();

  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_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 char *filename, MPI_Comm comm) const;

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

  void write_pvd_record (std::ostream &out,
                         const std::vector<std::pair<double,std::string> >  &times_and_names) const;

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

  void write_visit_record (std::ostream &out,
                           const std::vector<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;

  virtual
  std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
  get_vector_data_ranges () 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);

  DeclException0 (ExcNoPatches);
  DeclException0 (ExcIncompatibleDatasetNames);
  DeclException0 (ExcIncompatiblePatchLists);
  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;

  virtual std::vector<std::string> get_dataset_names () const;

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

private:
  std::vector<::DataOutBase::Patch<dim,spacedim> > patches;
  std::vector<std::string> dataset_names;

  std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
  vector_data_ranges;
};




class XDMFEntry
{
private:
  bool                                valid;
  std::string                         h5_sol_filename, h5_mesh_filename;
  double                              entry_time;
  unsigned int                        num_nodes, num_cells, dimension;
  std::map<std::string, unsigned int> attribute_dims;

  std::string indent(const unsigned int indent_level) const
  {
    std::string res = "";
    for (unsigned int i=0; i<indent_level; ++i) res += "  ";
    return res;
  }

public:
  XDMFEntry() : valid(false) {};
  XDMFEntry(const std::string filename, const double time, const unsigned int nodes, const unsigned int cells, const unsigned int dim) : valid(true), h5_sol_filename(filename), h5_mesh_filename(filename), entry_time(time), num_nodes(nodes), num_cells(cells), dimension(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) : valid(true), h5_sol_filename(solution_filename), h5_mesh_filename(mesh_filename), entry_time(time), num_nodes(nodes), num_cells(cells), dimension(dim) {};

  void add_attribute(const std::string &attr_name, const unsigned int dimension)
  {
    attribute_dims[attr_name] = 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
    &attribute_dims;
  }

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



/* -------------------- 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);
}


DEAL_II_NAMESPACE_CLOSE

#endif