Reference documentation for deal.II version Git 98872c4d47 2020-10-01 08:48:12 +0200
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Private Attributes | List of all members
Particles::DataOut< dim, spacedim > Class Template Reference

#include <deal.II/particles/data_out.h>

Inheritance diagram for Particles::DataOut< dim, spacedim >:
[legend]

Public Member Functions

 DataOut ()=default
 
 ~DataOut ()=default
 
void build_patches (const Particles::ParticleHandler< dim, spacedim > &particles, const std::vector< std::string > &data_component_names={}, const std::vector< DataComponentInterpretation::DataComponentInterpretation > &data_component_interpretations={})
 
void write_dx (std::ostream &out) const
 
void write_eps (std::ostream &out) const
 
void write_gmv (std::ostream &out) const
 
void write_gnuplot (std::ostream &out) const
 
void write_povray (std::ostream &out) const
 
void write_tecplot (std::ostream &out) const
 
void write_ucd (std::ostream &out) const
 
void write_vtk (std::ostream &out) const
 
void write_vtu (std::ostream &out) const
 
void write_vtu_in_parallel (const std::string &filename, MPI_Comm comm) const
 
void write_pvtu_record (std::ostream &out, const std::vector< std::string > &piece_names) const
 
std::string write_vtu_with_pvtu_record (const std::string &directory, const std::string &filename_without_extension, const unsigned int counter, const MPI_Comm &mpi_communicator, const unsigned int n_digits_for_counter=numbers::invalid_unsigned_int, const unsigned int n_groups=0) const
 
void write_svg (std::ostream &out) const
 
void write_deal_II_intermediate (std::ostream &out) const
 
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)
 
void set_flags (const FlagType &flags)
 
std::string default_suffix (const DataOutBase::OutputFormat output_format=DataOutBase::default_format) const
 
void parse_parameters (ParameterHandler &prm)
 
std::size_t memory_consumption () const
 

Static Public Member Functions

static void declare_parameters (ParameterHandler &prm)
 

Protected Member Functions

virtual const std::vector< DataOutBase::Patch< 0, 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
 
void validate_dataset_names () const
 

Protected Attributes

unsigned int default_subdivisions
 

Private Attributes

std::vector< DataOutBase::Patch< 0, spacedim > > patches
 
std::vector< std::string > dataset_names
 
std::vector< DataComponentInterpretation::DataComponentInterpretationdata_component_interpretations
 

Detailed Description

template<int dim, int spacedim = dim>
class Particles::DataOut< dim, spacedim >

This class generates graphical output for the particles stored by a ParticleHandler object. From a particle handler, it generates patches which can then be used to write traditional output files. This class currently only supports witing the particle position and their ID and does not allow to write the properties attached to the particles

Definition at line 44 of file data_out.h.

Constructor & Destructor Documentation

◆ DataOut()

template<int dim, int spacedim = dim>
Particles::DataOut< dim, spacedim >::DataOut ( )
default

Default constructor for the Particles::DataOut class.

◆ ~DataOut()

template<int dim, int spacedim = dim>
Particles::DataOut< dim, spacedim >::~DataOut ( )
default

Destructor for the Particles::DataOut class.

Member Function Documentation

◆ build_patches()

template<int dim, int spacedim>
void DataOut< dim, spacedim >::build_patches ( const Particles::ParticleHandler< dim, spacedim > &  particles,
const std::vector< std::string > &  data_component_names = {},
const std::vector< DataComponentInterpretation::DataComponentInterpretation > &  data_component_interpretations = {} 
)

Build the patches for a given particle handler.

Parameters
[in]particlesA particle handler for which the patches will be built. A dim=0 patch is built for each particle. The position of the particle is used to build the node position and the ID of the particle is added as a single data element.
[in]data_component_namesAn optional vector of strings that describe the properties of each particle. Particle properties will only be written if this vector is provided.
[in]data_component_interpretationsAn optional vector that controls if the particle properties are interpreted as scalars, vectors, or tensors. Has to be of the same length as data_component_names.

Definition at line 28 of file data_out.cc.

◆ get_patches()

template<int dim, int spacedim>
const std::vector< DataOutBase::Patch< 0, spacedim > > & DataOut< dim, spacedim >::get_patches ( ) const
overrideprotectedvirtual

Returns the patches built by the data_out class which was previously built using a particle handler

Implements DataOutInterface< 0, spacedim >.

Definition at line 108 of file data_out.cc.

◆ get_dataset_names()

template<int dim, int spacedim>
std::vector< std::string > DataOut< dim, spacedim >::get_dataset_names ( ) const
overrideprotectedvirtual

Virtual function through which the names of data sets are obtained from this class

Implements DataOutInterface< 0, spacedim >.

Definition at line 117 of file data_out.cc.

◆ get_nonscalar_data_ranges()

template<int dim, int spacedim>
std::vector< std::tuple< unsigned int, unsigned int, std::string, DataComponentInterpretation::DataComponentInterpretation > > DataOut< dim, spacedim >::get_nonscalar_data_ranges ( ) const
overrideprotectedvirtual

Overload of the respective DataOutInterface::get_nonscalar_data_ranges() function. See there for a more extensive documentation. This function is a reimplementation of the function DataOut_DoFData::get_nonscalar_data_ranges().

Reimplemented from DataOutInterface< 0, spacedim >.

Definition at line 130 of file data_out.cc.

◆ write_dx()

void DataOutInterface< dim, spacedim >::write_dx ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in OpenDX format. See DataOutBase::write_dx.

Definition at line 6917 of file data_out_base.cc.

◆ write_eps()

void DataOutInterface< dim, spacedim >::write_eps ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in EPS format. See DataOutBase::write_eps.

Definition at line 6969 of file data_out_base.cc.

◆ write_gmv()

void DataOutInterface< dim, spacedim >::write_gmv ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in GMV format. See DataOutBase::write_gmv.

Definition at line 6982 of file data_out_base.cc.

◆ write_gnuplot()

void DataOutInterface< dim, spacedim >::write_gnuplot ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in GNUPLOT format. See DataOutBase::write_gnuplot.

Definition at line 6943 of file data_out_base.cc.

◆ write_povray()

void DataOutInterface< dim, spacedim >::write_povray ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in POVRAY format. See DataOutBase::write_povray.

Definition at line 6956 of file data_out_base.cc.

◆ write_tecplot()

void DataOutInterface< dim, spacedim >::write_tecplot ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in Tecplot format. See DataOutBase::write_tecplot.

Definition at line 6995 of file data_out_base.cc.

◆ write_ucd()

void DataOutInterface< dim, spacedim >::write_ucd ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in UCD format for AVS. See DataOutBase::write_ucd.

Definition at line 6930 of file data_out_base.cc.

◆ write_vtk()

void DataOutInterface< dim, spacedim >::write_vtk ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in Vtk format. See DataOutBase::write_vtk.

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.

Definition at line 7008 of file data_out_base.cc.

◆ write_vtu()

void DataOutInterface< dim, spacedim >::write_vtu ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in Vtu (VTK's XML) format. See DataOutBase::write_vtu.

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 centralized record. Likewise, DataOutInterface::write_visit_record() does the same for older versions of VisIt (although VisIt can also read pvtu records since version 2.5.1). Finally, DataOutInterface::write_pvd_record() can be used to group together the files that jointly make up a time dependent simulation.

Definition at line 7019 of file data_out_base.cc.

◆ write_vtu_in_parallel()

void DataOutInterface< dim, spacedim >::write_vtu_in_parallel ( const std::string &  filename,
MPI_Comm  comm 
) const
inherited

Collective MPI call to write the solution from all participating nodes (those in the given communicator) to a single compressed .vtu file on a shared file system. The communicator can be a sub communicator of the one used by the computation. This routine uses MPI I/O to achieve high performance on parallel filesystems. Also see DataOutInterface::write_vtu().

Definition at line 7041 of file data_out_base.cc.

◆ write_pvtu_record()

void DataOutInterface< dim, spacedim >::write_pvtu_record ( std::ostream &  out,
const std::vector< std::string > &  piece_names 
) const
inherited

Some visualization programs, such as ParaView, can read several separate VTU files that all form part of the same simulation, in order to parallelize visualization. In that case, you need a .pvtu file that describes which VTU files (written, for example, through the DataOutInterface::write_vtu() function) form a group. The current function can generate such a centralized record.

The central record file generated by this function contains a list of (scalar or vector) fields that describes which fields can actually be found in the individual files that comprise the set of parallel VTU files along with the names of these files. This function gets the names and types of fields through the get_dataset_names() and get_nonscalar_data_ranges() functions of this class. The second argument to this function specifies the names of the files that form the parallel set.

Note
Use DataOutBase::write_vtu() and DataOutInterface::write_vtu() for writing each piece. Also note that only one parallel process needs to call the current function, listing the names of the files written by all parallel processes.
The use of this function is explained in step-40.
In order to tell Paraview to group together multiple pvtu files that each describe one time step of a time dependent simulation, see the DataOutBase::write_pvd_record() function.
Older versions of VisIt (before 2.5.1), can not read pvtu records. However, it can read visit records as written by the write_visit_record() function.

Definition at line 7144 of file data_out_base.cc.

◆ write_vtu_with_pvtu_record()

std::string DataOutInterface< dim, spacedim >::write_vtu_with_pvtu_record ( const std::string &  directory,
const std::string &  filename_without_extension,
const unsigned int  counter,
const MPI_Comm &  mpi_communicator,
const unsigned int  n_digits_for_counter = numbers::invalid_unsigned_int,
const unsigned int  n_groups = 0 
) const
inherited

This function writes several .vtu files and a .pvtu record in parallel and constructs the filenames automatically. It is a combination of DataOutInterface::write_vtu() or DataOutInterface::write_vtu_in_parallel(), and DataOutInterface::write_pvtu_record().

For example, running write_vtu_with_pvtu_record("output/", "solution", 3, comm, 4, 2) on 10 processes generates the files

output/solution_0003.0.vtu
output/solution_0003.1.vtu
output/solution_0003.pvtu

where the .0.vtu file contains the output of the first half of the processes grouped together, and the .1.vtu the data from the remaining half.

A specified directory and a filename_without_extension form the first part of the filename. The filename is then extended with a counter labeling the current timestep/iteration/etc., the processor ID, and finally the .vtu/.pvtu ending. Since the number of timesteps to be written depends on the application, the number of digits to be reserved in the filename can be specified as parameter n_digits_for_counter, and the number is not padded with leading zeros if this parameter is left at its default value numbers::invalid_unsigned_int. If more than one file identifier is needed (e.g. time step number and iteration counter of solver), the last identifier is used as counter, while all other identifiers have to be added to filename_without_extension when calling this function.

In a parallel setting, several files are typically written per time step. The number of files written in parallel depends on the number of MPI processes (see parameter mpi_communicator), and a specified number of n_groups with default value 0. The background is that VTU file output supports grouping files from several CPUs into a given number of files using MPI I/O when writing on a parallel filesystem. The default value of n_groups is 0, meaning that every MPI rank will write one file. A value of 1 will generate one big file containing the solution over the whole domain, while a larger value will create n_groups files (but not more than there are MPI ranks).

Note that only one processor needs to generate the .pvtu file, where processor zero is chosen to take over this job.

The return value is the filename of the centralized file for the pvtu record.

Note
The code simply combines the strings directory and filename_without_extension, i.e., the user has to make sure that directory contains a trailing character, e.g. "/", that separates the directory from the filename.
Use an empty string "" for the first argument if output is to be written in the current working directory.

Definition at line 7157 of file data_out_base.cc.

◆ write_svg()

void DataOutInterface< dim, spacedim >::write_svg ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in SVG format. See DataOutBase::write_svg.

Definition at line 7030 of file data_out_base.cc.

◆ write_deal_II_intermediate()

void DataOutInterface< dim, spacedim >::write_deal_II_intermediate ( std::ostream &  out) const
inherited

Obtain data through get_patches() and write it to out in deal.II intermediate format. See DataOutBase::write_deal_II_intermediate.

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.

Definition at line 7239 of file data_out_base.cc.

◆ create_xdmf_entry() [1/2]

XDMFEntry DataOutInterface< dim, spacedim >::create_xdmf_entry ( const DataOutBase::DataOutFilter data_filter,
const std::string &  h5_filename,
const double  cur_time,
MPI_Comm  comm 
) const
inherited

Create an XDMFEntry based on the data in the data_filter. This assumes the mesh and solution data were written to a single file. See write_xdmf_file() for an example of usage.

Definition at line 7252 of file data_out_base.cc.

◆ create_xdmf_entry() [2/2]

XDMFEntry DataOutInterface< dim, spacedim >::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
inherited

Create an XDMFEntry based on the data in the data_filter. This assumes the mesh and solution data were written to separate files. See write_xdmf_file() for an example of usage.

Definition at line 7266 of file data_out_base.cc.

◆ write_xdmf_file()

void DataOutInterface< dim, spacedim >::write_xdmf_file ( const std::vector< XDMFEntry > &  entries,
const std::string &  filename,
MPI_Comm  comm 
) const
inherited

Write an XDMF file based on the provided vector of XDMFEntry objects. Below is an example of how to use this function with HDF5 and the DataOutFilter:

DataOutBase::DataOutFilter data_filter(flags);
std::vector<XDMFEntry> xdmf_entries;
// Filter the data and store it in data_filter
data_out.write_filtered_data(data_filter);
// Write the filtered data to HDF5
data_out.write_hdf5_parallel(data_filter, "solution.h5", MPI_COMM_WORLD);
// Create an XDMF entry detailing the HDF5 file
auto new_xdmf_entry = data_out.create_xdmf_entry(data_filter,
"solution.h5",
simulation_time,
MPI_COMM_WORLD);
// Add the XDMF entry to the list
xdmf_entries.push_back(new_xdmf_entry);
// Create an XDMF file from all stored entries
data_out.write_xdmf_file(xdmf_entries, "solution.xdmf", MPI_COMM_WORLD);

Definition at line 7339 of file data_out_base.cc.

◆ write_hdf5_parallel() [1/2]

void DataOutInterface< dim, spacedim >::write_hdf5_parallel ( const DataOutBase::DataOutFilter data_filter,
const std::string &  filename,
MPI_Comm  comm 
) const
inherited

Write the data in data_filter to a single HDF5 file containing both the mesh and solution values. Below is an example of how to use this function with the DataOutFilter:

DataOutBase::DataOutFilter data_filter(flags);
// Filter the data and store it in data_filter
data_out.write_filtered_data(data_filter);
// Write the filtered data to HDF5
data_out.write_hdf5_parallel(data_filter, "solution.h5", MPI_COMM_WORLD);

Definition at line 7517 of file data_out_base.cc.

◆ write_hdf5_parallel() [2/2]

void DataOutInterface< dim, spacedim >::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
inherited

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.

Definition at line 7529 of file data_out_base.cc.

◆ write_filtered_data()

void DataOutInterface< dim, spacedim >::write_filtered_data ( DataOutBase::DataOutFilter filtered_data) const
inherited

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().

Definition at line 7389 of file data_out_base.cc.

◆ write()

void DataOutInterface< dim, spacedim >::write ( std::ostream &  out,
const DataOutBase::OutputFormat  output_format = DataOutBase::default_format 
) const
inherited

Write data and grid to out according to the given data format. This function simply calls the appropriate write_* function. If no output format is requested, the default_format is written.

An error occurs if no format is provided and the default format is default_format.

Definition at line 7924 of file data_out_base.cc.

◆ set_default_format()

void DataOutInterface< dim, spacedim >::set_default_format ( const DataOutBase::OutputFormat  default_format)
inherited

Set the default format. The value set here is used anytime, output for format default_format is requested.

Definition at line 7990 of file data_out_base.cc.

◆ set_flags()

void DataOutInterface< dim, spacedim >::set_flags ( const FlagType &  flags)
inherited

Set the flags to be used for output. This method expects flags to be a member of one of the child classes of OutputFlagsBase.

Definition at line 8000 of file data_out_base.cc.

◆ default_suffix()

std::string DataOutInterface< dim, spacedim >::default_suffix ( const DataOutBase::OutputFormat  output_format = DataOutBase::default_format) const
inherited

A function that returns the same string as the respective function in the base class does; the only exception being that if the parameter is omitted, then the value for the present default format is returned, i.e. the correct suffix for the format that was set through set_default_format() or parse_parameters() before calling this function.

Definition at line 8035 of file data_out_base.cc.

◆ declare_parameters()

void DataOutInterface< dim, spacedim >::declare_parameters ( ParameterHandler prm)
staticinherited

Declare parameters for all output formats by declaring subsections within the parameter file for each output format and call the respective declare_parameters functions of the flag classes for each output format.

Some of the declared subsections may not contain entries, if the respective format does not export any flags.

Note that the top-level parameters denoting the number of subdivisions per patch and the output format are not declared, since they are only passed to virtual functions and are not stored inside objects of this type. You have to declare them yourself.

Definition at line 8048 of file data_out_base.cc.

◆ parse_parameters()

void DataOutInterface< dim, spacedim >::parse_parameters ( ParameterHandler prm)
inherited

Read the parameters declared in declare_parameters() and set the flags for the output formats accordingly.

The flags thus obtained overwrite all previous contents of the flag objects as default-constructed or set by the set_flags() function.

Definition at line 8101 of file data_out_base.cc.

◆ memory_consumption()

std::size_t DataOutInterface< dim, spacedim >::memory_consumption ( ) const
inherited

Return an estimate for the memory consumption, in bytes, of this object. This is not exact (but will usually be close) because calculating the memory usage of trees (e.g., std::map) is difficult.

Definition at line 8148 of file data_out_base.cc.

◆ validate_dataset_names()

void DataOutInterface< dim, spacedim >::validate_dataset_names ( ) const
protectedinherited

Validate that the names of the datasets returned by get_dataset_names() and get_nonscalar_data_ranges() are valid. This currently consists of checking that names are not used more than once. If an invalid state is encountered, an Assert() will be triggered in debug mode.

Definition at line 8183 of file data_out_base.cc.

Member Data Documentation

◆ patches

template<int dim, int spacedim = dim>
std::vector<DataOutBase::Patch<0, spacedim> > Particles::DataOut< dim, spacedim >::patches
private

This is a vector of patches that is created each time build_patches() is called. These patches are used in the output routines of the base classes.

Definition at line 115 of file data_out.h.

◆ dataset_names

template<int dim, int spacedim = dim>
std::vector<std::string> Particles::DataOut< dim, spacedim >::dataset_names
private

A vector of field names for all data components stored in patches.

Definition at line 120 of file data_out.h.

◆ data_component_interpretations

template<int dim, int spacedim = dim>
std::vector<DataComponentInterpretation::DataComponentInterpretation> Particles::DataOut< dim, spacedim >::data_component_interpretations
private

A vector that for each of the data components of the current data set indicates whether they are scalar fields, parts of a vector-field, or any of the other supported kinds of data.

Definition at line 128 of file data_out.h.

◆ default_subdivisions

unsigned int DataOutInterface< dim, spacedim >::default_subdivisions
protectedinherited

The default number of subdivisions for patches. This is filled by parse_parameters() and should be obeyed by build_patches() in derived classes.

Definition at line 3016 of file data_out_base.h.


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