Reference documentation for deal.II version 8.1.0
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Private Member Functions | List of all members
DataOutBase Class Reference

#include <data_out_base.h>

Inheritance diagram for DataOutBase:
[legend]

Classes

class  DataOutFilter
 
struct  DataOutFilterFlags
 
struct  Deal_II_IntermediateFlags
 
struct  DXFlags
 
class  EpsCell2d
 
struct  EpsFlags
 
struct  GmvFlags
 
struct  GnuplotFlags
 
struct  Patch
 
struct  PovrayFlags
 
class  SvgCell
 
struct  SvgFlags
 
struct  TecplotFlags
 
struct  UcdFlags
 
struct  VtkFlags
 

Public Types

enum  OutputFormat {
  default_format, none, dx, ucd,
  gnuplot, povray, eps, gmv,
  tecplot, tecplot_binary, vtk, vtu,
  svg, deal_II_intermediate, hdf5
}
 

Public Member Functions

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

Static Public Member Functions

template<int dim, int spacedim>
static void write_dx (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const DXFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_eps (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const EpsFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_gmv (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const GmvFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_gnuplot (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const GnuplotFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_povray (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const PovrayFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_tecplot (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const TecplotFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_tecplot_binary (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const TecplotFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_ucd (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const UcdFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_vtk (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const VtkFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_vtu (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const VtkFlags &flags, std::ostream &out)
 
static void write_vtu_header (std::ostream &out, const VtkFlags &flags)
 
static void write_vtu_footer (std::ostream &out)
 
template<int dim, int spacedim>
static void write_vtu_main (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const VtkFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_svg (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const SvgFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static void write_deal_II_intermediate (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, const Deal_II_IntermediateFlags &flags, std::ostream &out)
 
template<int dim, int spacedim>
static 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>
static 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>
static void write_filtered_data (const std::vector< Patch< dim, spacedim > > &patches, const std::vector< std::string > &data_names, const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &vector_data_ranges, DataOutFilter &filtered_data)
 
static std::pair< unsigned int, unsigned intdetermine_intermediate_format_dimensions (std::istream &input)
 
static OutputFormat parse_output_format (const std::string &format_name)
 
static std::string get_output_format_names ()
 
static std::string default_suffix (const OutputFormat output_format)
 
static std::size_t memory_consumption ()
 

Static Private Member Functions

template<int dim, int spacedim, typename STREAM >
static void write_nodes (const std::vector< Patch< dim, spacedim > > &patches, STREAM &out)
 
template<int dim, int spacedim, typename STREAM >
static void write_cells (const std::vector< Patch< dim, spacedim > > &patches, STREAM &out)
 
template<int dim, int spacedim, class STREAM >
static void write_data (const std::vector< Patch< dim, spacedim > > &patches, const unsigned int n_data_sets, const bool double_precision, STREAM &out)
 
static Point< 2 > svg_project_point (Point< 3 > point, Point< 3 > camera_position, Point< 3 > camera_direction, Point< 3 > camera_horizontal, float camera_focus)
 
static Point< 6 > svg_get_gradient_parameters (Point< 3 > points[])
 
template<int dim, int spacedim>
static void write_gmv_reorder_data_vectors (const std::vector< Patch< dim, spacedim > > &patches, Table< 2, double > &data_vectors)
 

Detailed Description

This is a base class for output of data on meshes of very general form. Output data is expected as a set of patches and written to the output stream in the format expected by the visualization tool. For a list of output formats, check the enumeration OutputFormat. For each format listed there, this class contains a function write_format, writing the output. Refer to the documentation of those functions for details on a certain format.

Structure of the output data

Data is not written with the deal.II mesh structure. Instead, it relies on a set of patches created by a derived class (for example the DataOut, DataOutStack, DataOutFaces, DataOutRotation, or MatrixOut classes). Each Patch describes a single logical cell of a mesh, possibly subdivided a number of times to represent higher order polynomials defined on this cell. To this end, a patch consists of a dim-dimensional regular grid with the same number of grid points in each direction. In the simplest case it may consist of the corner points of a single mesh cell. For each point of this local grid, the Patch contains an arbitrary number of data values, though the number of data sets must be the same for each point on each patch.

By offering this interface to the different output formats, it is simple to extend this class to new formats without depending on such things as actual triangulations and handling of data vectors. These things shall be provided by derived class which have a user callable interface then.

Inside each patch, the data is organized in the usual lexicographical order, x running fastest, then y and z. Nodes are stored in this order and cells as well. Each cell in 3D is stored such that the front face is in the xz-plane. In order to enhance intellegibility of this concept, the following two sections are kept from a previous version of this documentation.

Patches

Grids can be thought of as a collection of cells; if you want to write out data on such a grid, you can do so by writing them one cell at a time. The functions in this class therefore take a list of objects describing the data on one cell each. This data for each cell usually consists of a list of vertices for this cell, and a list of data values (for example solution data, error information, etc) at each of these vertices.

In some cases, this interface to a cell is too restricted, however. For example, you may have higher order elements and printing the values at the vertices only is not enough. For this reason, we not only provide writing the data on the vertices only, but the data is organizes as a tensor product grid on each cell. The parameter n_subdivision, which is given for each patch separately, denotes how often the cell is to be divided for output; for example, n_subdivisions==1 yields no subdivision of the cell, n_subdivisions==2 will produce a grid of 3 times 3 points in two spatial dimensions and 3 times 3 times 3 points in three dimensions, n_subdivisions==3 will yield 4 times 4 (times 4) points, etc. The actual location of these points on the patch will be computed by a multilinear transformation from the vertices given for this patch.

For cells at the boundary, a mapping might be used to calculate the position of the inner points. In that case the coordinates are stored inside the Patch, as they cannot be easily recovered otherwise.

Given these comments, the actual data to be printed on this patch of points consists of several data sets each of which has a value at each of the patch points. For example with n_subdivisions==2 in two space dimensions, each data set has to provide nine values, and since the patch is to be printed as a tensor product (or its transformation to the real space cell), its values are to be ordered like (x0,y0) (x0,y1) (x0,y2) (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2), i.e. the z-coordinate runs fastest, then the y-coordinate, then x (if there are that many space directions).

Generalized patches

In general, the patches as explained above might be too restricted. For example, one might want to draw only the outer faces of a domain in a three-dimensional computation, if one is not interested in what happens inside. Then, the objects that should be drawn are two-dimensional in a three-dimensional world. The Patch class and associated output functions handle these cases. The Patch class therefore takes two template parameters, the first, named dim denoting the dimension of the object (in the above example, this would be two), while the second, named spacedim, denotes the dimension of the embedding space (this would be three). The corner points of a patch have the dimension of the space, while their number is determined by the dimension of the patch. By default, the second template parameter has the same value as the first, which would correspond to outputting a cell, rather than a face or something else.

DataOutBaseInterface

This class has an interface that is not usually called by a user directly; also, it consists of static functions only. Usually, derived classes will inherit this class protected to hide this interface to the users of thes classes.

The interface of this class basically consists of the declaration of a data type describing a patch and a bunch of functions taking a list of patches and writing them in one format or other to the stream. It is in the responsibility of the derived classes to provide this list of patches. In addition to the list of patches, a name for each data set may be given.

Querying interface

This class also provides a few functions (parse_output_format(), get_output_format_names(), default_suffix()) that can be used to query which output formats this class supports. The provide a list of names for all the formats we can output, parse a string and return an enum indicating each format, and provide a way to convert a value of this enum into the usual suffix used for files of that name. Using these functions, one can entirely free applications from knowledge which formats the library presently allows to output; several of the example programs show how to do this.

Output parameters

All functions take a parameter which is a structure of type XFlags, where X is the name of the output format. To find out what flags are presently supported, read the documentation of the different structures.

Note that usually the output formats used for scientific visualization programs have no or very few parameters (apart from some compatibility flags) because there the actual appearance of output is determined using the visualization program and the files produced by this class store more or less only raw data.

The direct output formats, like Postscript or Povray need to be given a lot more parameters, though, since there the output file has to contain all details of the viewpoint, light source, etc.

Writing backends

An abstraction layer has been introduced to facilitate coding backends for additional visualization tools. It is applicable for data formats separating the information into a field of vertices, a field of connection information for the grid cells and data fields.

For each of these fields, output functions are implemented, namely write_nodes(), write_cells() and write_data(). In order to use these functions, a format specific output stream must be written, following the examples of DXStream, GmvStream, VtkStream and so on, implemented in the .cc file.

In this framework, the implementation of a new output format is reduced to writing the section headers and the new output stream class for writing a single mesh object.

Credits

Author
Wolfgang Bangerth, Guido Kanschat 1999, 2000, 2001, 2002, 2005, 2006.

Definition at line 219 of file data_out_base.h.

Member Enumeration Documentation

Provide a data type specifying the presently supported output formats.

Enumerator
default_format 

Use the format already stored in the object.

none 

Do not write any output.

dx 

Output for OpenDX.

ucd 

Output in the UCD format for AVS.

gnuplot 

Output for the Gnuplot tool.

povray 

Output for the Povray raytracer.

eps 

Output in encapsulated PostScript.

gmv 

Output for GMV.

tecplot 

Output for Tecplot in text format.

tecplot_binary 

Output for Tecplot in binary format. Faster and smaller than text format.

vtk 

Output in VTK format.

vtu 

Output in VTK format.

svg 

Output in SVG format.

deal_II_intermediate 

Output in deal.II intermediate format.

hdf5 

Output in HDF5 format.

Definition at line 1385 of file data_out_base.h.

Member Function Documentation

template<int dim, int spacedim>
static void DataOutBase::write_dx ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const DXFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in OpenDX format.

Since OpenDX uses some kind of visual data flow oriented programming language, some of these programs are provided in contrib/dx.

template<int dim, int spacedim>
static void DataOutBase::write_eps ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const EpsFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in eps format.

Output in this format circumvents the use of auxiliary graphic programs converting some output format into a graphics format. This has the advantage that output is easy and fast, and the disadvantage that you have to give a whole bunch of parameters which determine the direction of sight, the mode of colorization, the scaling of the height axis, etc. (Of course, all these parameters have reasonable default values, which you may want to change from time to time.) At present, this format only supports output for two-dimensional data, with values in the third direction taken from a data vector.

Basically, output consists of the mesh and the cells in between them. You can draw either of these, or both, or none if you are really interested in an empty picture. If written, the mesh uses black lines. The cells in between the mesh are either not printed (this will result in a loss of hidden line removal, i.e. you can "see through" the cells to lines behind), printed in white (which does nothing apart from the hidden line removal), or colorized using one of the data vectors (which need not be the same as the one used for computing the height information) and a customizable color function. The default color functions chooses the color between black, blue, green, red and white, with growing values of the data field chosen for colorization. At present, cells are displayed with one color per cell only, which is taken from the value of the data field at the center of the cell; bilinear interpolation of the color on a cell is not used.

By default, the viewpoint is chosen like the default viewpoint in GNUPLOT, i.e. with an angle of 60 degrees with respect to the positive z-axis and rotated 30 degrees in positive sense (as seen from above) away from the negative y-axis. Of course you can change these settings.

EPS output is written without a border around the picture, i.e. the bounding box is close to the output on all four sides. Coordinates are written using at most five digits, to keep picture size at a reasonable size.

All parameters along with their default values are listed in the documentation of the EpsFlags member class of this class. See there for more and detailed information.

template<int dim, int spacedim>
static void DataOutBase::write_gmv ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const GmvFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in GMV format.

Data is written in the following format: nodes are considered the points of the patches. In spatial dimensions less than three, zeroes are inserted for the missing coordinates. The data vectors are written as node or cell data, where for the first the data space is interpolated to (bi-,tri-)linear elements.

template<int dim, int spacedim>
static void DataOutBase::write_gnuplot ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const GnuplotFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in gnuplot format. Visualization of two-dimensional data can then be achieved by starting gnuplot and endtering the commands

* set data style lines
* splot "filename" using 1:2:n
* 

This example assumes that the number of the data vector displayed is n-2.

The GNUPLOT format is not able to handle data on unstructured grids directly. Directly would mean that you only give the vertices and the solution values thereon and the program constructs its own grid to represent the data. This is only possible for a structured tensor product grid in two dimensions. However, it is possible to give several such patches within one file, which is exactly what the respective function of this class does: writing each cell's data as a patch of data, at least if the patches as passed from derived classes represent cells. Note that the functions on patches need not be continuous at interfaces between patches, so this method also works for discontinuous elements. Note also, that GNUPLOT can do hidden line removal for patched data.

While this discussion applies to two spatial dimensions, it is more complicated in 3d. The reason is that we could still use patches, but it is difficult when trying to visualize them, since if we use a cut through the data (by, for example, using x- and z-coordinates, a fixed y-value and plot function values in z-direction, then the patched data is not a patch in the sense GNUPLOT wants it any more. Therefore, we use another approach, namely writing the data on the 3d grid as a sequence of lines, i.e. two points each associated with one or more data sets. There are therefore 12 lines for each subcells of a patch.

Given the lines as described above, a cut through this data in Gnuplot can then be achieved like this (& stands for the dollar sign in the following):

*   set data style lines
*   splot [:][:][0:] "T" using 1:2:(&3==.5 ? &4 : -1)
* 

This command plots data in x- and y-direction unbounded, but in z-direction only those data points which are above the x-y-plane (we assume here a positive solution, if it has negative values, you might want to decrease the lower bound). Furthermore, it only takes the data points with z-values (&3) equal to 0.5, i.e. a cut through the domain at z=0.5. For the data points on this plane, the data values of the first data set (&4) are raised in z-direction above the x-y-plane; all other points are denoted the value -1 instead of the value of the data vector and are not plotted due to the lower bound in z plotting direction, given in the third pair of brackets.

More complex cuts are possible, including nonlinear ones. Note however, that only those points which are actually on the cut-surface are plotted.

template<int dim, int spacedim>
static void DataOutBase::write_povray ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const PovrayFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream for the Povray raytracer.

Output in this format creates a povray source file, include standard camera and light source definition for rendering with povray 3.1 At present, this format only supports output for two-dimensional data, with values in the third direction taken from a data vector.

The output uses two different povray-objects:

  • BICUBIC_PATCH A bicubic_patch is a 3-dimensional Bezier patch. It consists of 16 Points describing the surface. The 4 corner points are touched by the object, while the other 12 points pull and stretch the patch into shape. One bicubic_patch is generated on each patch. Therefor the number of subdivisions has to be 3 to provide the patch with 16 points. A bicubic patch is not exact but generates very smooth images.

  • MESH The mesh object is used to store large number of triangles. Every square of the patch data is split into one upper-left and one lower-right triangle. If the number of subdivisions is three, 32 triangle are generated for every patch.

    Using the smooth flag povray interpolates the normals on the triangles, imitating a curved surface

All objects get one texture definition called Tex. This texture has to be declared somewhere before the object data. This may be in an external data file or at the beginning of the output file. Setting the external_data flag to false, an standard camera, light and texture (scaled to fit the scene) is added to the outputfile. Set to true an include file "data.inc" is included. This file is not generated by deal and has to include camera, light and the texture definition Tex.

You need povray (>=3.0) to render the scene. The minimum options for povray are:

*   povray +I<inputfile> +W<horiz. size> +H<ver. size> +L<include path>
* 

If the external file "data.inc" is used, the path to this file has to be included in the povray options.

template<int dim, int spacedim>
static void DataOutBase::write_tecplot ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const TecplotFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in Tecplot ASCII format (FEBLOCK).

For more information consult the Tecplot Users and Reference manuals.

template<int dim, int spacedim>
static void DataOutBase::write_tecplot_binary ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const TecplotFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in Tecplot binary format.

For this to work properly ./configure checks for the Tecplot API at build time. To write Tecplot binary files directly make sure that the TECHOME environment variable points to the Tecplot installation directory, and that the files $TECHOME/include/TECIO.h and $TECHOME/lib/tecio.a are readable. If these files are not available (or in the case of 1D) this function will simply call write_tecplot() and thus larger ASCII data files will be produced rather than more efficient Tecplot binary files.

Warning
TecplotFlags::tecplot_binary_file_name indicates the name of the file to be written. If the file name is not set ASCII output is produced.

For more information consult the Tecplot Users and Reference manuals.

template<int dim, int spacedim>
static void DataOutBase::write_ucd ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const UcdFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in UCD format described in the AVS developer's guide (now AVS). Due to limitations in the present format, only node based data can be output, which in one reason why we invented the patch concept. In order to write higher order elements, you may split them up into several subdivisions of each cell. These subcells will then, however, also appear as different cells by programs which understand the UCD format.

No use is made of the possibility to give model data since these are not supported by all UCD aware programs. You may give cell data in derived classes by setting all values of a given data set on a patch to the same value.

template<int dim, int spacedim>
static void DataOutBase::write_vtk ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const VtkFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in VTK format. The data is written in the traditional VTK format as opposed to the XML-based format that write_vtu() produces.

The vector_data_ranges argument denotes ranges of components in the output that are considered a vector, rather than simply a collection of scalar fields. The VTK output format has special provisions that allow these components to be output by a single name rather than having to group several scalar fields into a vector later on in the visualization program.

Note
VTK is a legacy format and has largely been supplanted by the VTU format (an XML-structured version of VTK). In particular, VTU allows for the compression of data and consequently leads to much smaller file sizes that equivalent VTK files for large files. Since all visualization programs that support VTK also support VTU, you should consider using the latter file format instead, by using the write_vtu() function.
template<int dim, int spacedim>
static void DataOutBase::write_vtu ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const VtkFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in VTU format. The data is written in the XML-based VTK format as opposed to the traditional format that write_vtk() produces.

The vector_data_ranges argument denotes ranges of components in the output that are considered a vector, rather than simply a collection of scalar fields. The VTK output format has special provisions that allow these components to be output by a single name rather than having to group several scalar fields into a vector later on in the visualization program.

Some visualization programs, such as ParaView, can read several separate VTU files to parallelize visualization. In that case, you need a .pvtu file that describes which VTU files form a group. The DataOutInterface::write_pvtu_record() function can generate such a master record. Likewise, DataOutInterface::write_visit_record() does the same for VisIt. Finally, for time dependent problems, you may also want to look at DataOutInterface::write_pvd_record()

The use of this function is explained in step-40.

static void DataOutBase::write_vtu_header ( std::ostream &  out,
const VtkFlags flags 
)
static

This writes the header for the xml based vtu file format. This routine is used internally together with DataOutInterface::write_vtu_footer() and DataOutInterface::write_vtu_main() by DataOutBase::write_vtu().

static void DataOutBase::write_vtu_footer ( std::ostream &  out)
static

This writes the footer for the xml based vtu file format. This routine is used internally together with DataOutInterface::write_vtu_header() and DataOutInterface::write_vtu_main() by DataOutBase::write_vtu().

template<int dim, int spacedim>
static void DataOutBase::write_vtu_main ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const VtkFlags flags,
std::ostream &  out 
)
static

This writes the main part for the xml based vtu file format. This routine is used internally together with DataOutInterface::write_vtu_header() and DataOutInterface::write_vtu_footer() by DataOutBase::write_vtu().

template<int dim, int spacedim>
static void DataOutBase::write_svg ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const SvgFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in SVG format.

SVG (Scalable Vector Graphics) is an XML-based vector image format developed and maintained by the World Wide Web Consortium (W3C). This function conforms to the latest specification SVG 1.1, released on August 16, 2011. Controlling the graphic output is possible by setting or clearing the respective flags (see the SvgFlags struct). At present, this format only supports output for two-dimensional data, with values in the third direction taken from a data vector.

For the output, each patch is subdivided into four triangles which are then written as polygons and filled with a linear color gradient. The arising coloring of the patches visualizes the data values at the vertices taken from the specified data vector. A colorbar can be drawn to encode the coloring.

Note
Yet only implemented for two dimensions with an additional dimension reserved for data information.
template<int dim, int spacedim>
static void DataOutBase::write_deal_II_intermediate ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
const Deal_II_IntermediateFlags flags,
std::ostream &  out 
)
static

Write the given list of patches to the output stream in deal.II intermediate format. This is not a format understood by any other graphics program, but is rather a direct dump of the intermediate internal format used by deal.II. This internal format is generated by the various classes that can generate output using the DataOutBase class, for example from a finite element solution, and is then converted in the present class to the final graphics format.

Note that the intermediate format is what its name suggests: a direct representation of internal data. It isn't standardized and will change whenever we change our internal representation. You can only expect to process files written in this format using the same version of deal.II that was used for writing.

The reason why we offer to write out this intermediate format is that it can be read back into a deal.II program using the DataOutReader class, which is helpful in at least two contexts: First, this can be used to later generate graphical output in any other graphics format presently understood; this way, it is not necessary to know at run-time which output format is requested, or if multiple output files in different formats are needed. Secondly, in contrast to almost all other graphics formats, it is possible to merge several files that contain intermediate format data, and generate a single output file from it, which may be again in intermediate format or any of the final formats. This latter option is most helpful for parallel programs: as demonstrated in the step-17 example program, it is possible to let only one processor generate the graphical output for the entire parallel program, but this can become vastly inefficient if many processors are involved, because the load is no longer balanced. The way out is to let each processor generate intermediate graphical output for its chunk of the domain, and the later merge the different files into one, which is an operation that is much cheaper than the generation of the intermediate data.

Intermediate format deal.II data is usually stored in files with the ending .d2.

template<int dim, int spacedim>
static void DataOutBase::write_hdf5_parallel ( const std::vector< Patch< dim, spacedim > > &  patches,
const DataOutFilter data_filter,
const std::string &  filename,
MPI_Comm  comm 
)
static

Write the data in data_filter to a single HDF5 file containing both the mesh and solution values.

template<int dim, int spacedim>
static void DataOutBase::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 
)
static

Write the data in data_filter to HDF5 file(s). If write_mesh_file is false, the mesh data will not be written and the solution file will contain only the solution values. If write_mesh_file is true and the filenames are the same, the resulting file will contain both mesh data and solution values.

template<int dim, int spacedim>
static void DataOutBase::write_filtered_data ( const std::vector< Patch< dim, spacedim > > &  patches,
const std::vector< std::string > &  data_names,
const std::vector< std_cxx1x::tuple< unsigned int, unsigned int, std::string > > &  vector_data_ranges,
DataOutFilter filtered_data 
)
static

DataOutFilter is an intermediate data format that reduces the amount of data that will be written to files. The object filled by this function can then later be used again to write data in a concrete file format; see, for example, DataOutBase::write_hdf5_parallel().

static std::pair<unsigned int, unsigned int> DataOutBase::determine_intermediate_format_dimensions ( std::istream &  input)
static

Given an input stream that contains data written by write_deal_II_intermediate(), determine the dim and spacedim template parameters with which that function was called, and return them as a pair of values.

Note that this function eats a number of elements at the present position of the stream, and therefore alters it. In order to read from it using, for example, the DataOutReader class, you may wish to either reset the stream to its previous position, or close and reopen it.

static OutputFormat DataOutBase::parse_output_format ( const std::string &  format_name)
static

Return the OutputFormat value corresponding to the given string. If the string does not match any known format, an exception is thrown.

Since this function does not need data from this object, it is static and can thus be called without creating an object of this class. Its main purpose is to allow a program to use any implemented output format without the need to extend the program's parser each time a new format is implemented.

To get a list of presently available format names, e.g. to give it to the ParameterHandler class, use the function get_output_format_names().

static std::string DataOutBase::get_output_format_names ( )
static

Return a list of implemented output formats. The different names are separated by vertical bar signs (`|') as used by the ParameterHandler classes.

static std::string DataOutBase::default_suffix ( const OutputFormat  output_format)
static

Provide a function which tells us which suffix a file with a given output format usually has. At present the following formats are defined:

  • dx: .dx
  • ucd: .inp
  • gnuplot: .gnuplot
  • povray: .pov
  • eps: .eps
  • gmv: .gmv
  • tecplot: .dat
  • tecplot_binary: .plt
  • vtk: .vtk
  • vtu: .vtu
  • svg: .svg
  • deal_II_intermediate: .d2.
static std::size_t DataOutBase::memory_consumption ( )
static

Determine an estimate for the memory consumption (in bytes) of this object. Since sometimes the size of objects can not be determined exactly (for example: what is the memory consumption of an STL std::map type with a certain number of elements?), this is only an estimate. however often quite close to the true value.

template<int dim, int spacedim, typename STREAM >
static void DataOutBase::write_nodes ( const std::vector< Patch< dim, spacedim > > &  patches,
STREAM &  out 
)
staticprivate

Write the coordinates of nodes in the desired format.

template<int dim, int spacedim, typename STREAM >
static void DataOutBase::write_cells ( const std::vector< Patch< dim, spacedim > > &  patches,
STREAM &  out 
)
staticprivate

Write the node numbers of a cell in the desired format.

template<int dim, int spacedim, class STREAM >
static void DataOutBase::write_data ( const std::vector< Patch< dim, spacedim > > &  patches,
const unsigned int  n_data_sets,
const bool  double_precision,
STREAM &  out 
)
staticprivate

Write data in the desired format.

static Point<2> DataOutBase::svg_project_point ( Point< 3 >  point,
Point< 3 >  camera_position,
Point< 3 >  camera_direction,
Point< 3 >  camera_horizontal,
float  camera_focus 
)
staticprivate

This function projects a three-dimensional point (Point<3> point) onto a two-dimensional image plane, specified by the position of the camera viewing system (Point<3> camera_position), camera direction (Point<3> camera_position), camera horizontal (Point<3> camera_horizontal, necessary for the correct alignment of the later images), and the focus of the camera (float camera_focus).

For SVG output.

static Point<6> DataOutBase::svg_get_gradient_parameters ( Point< 3 >  points[])
staticprivate

Function to compute the gradient parameters for a triangle with given values for the vertices.

Used for svg output.

template<int dim, int spacedim>
static void DataOutBase::write_gmv_reorder_data_vectors ( const std::vector< Patch< dim, spacedim > > &  patches,
Table< 2, double > &  data_vectors 
)
staticprivate

This is a helper function for the write_gmv() function. There, the data in the patches needs to be copied around as output is one variable globally at a time, rather than all data on each vertex at a time. This copying around can be done detached from the main thread, and is thus moved into this separate function.

Note that because of the similarity of the formats, this function is also used by the Vtk and Tecplot output functions.


The documentation for this class was generated from the following file: