SAMRAI::appu::VisItDataWriter< DIM > Class Template Reference

Class VisItDataWriter<DIM> is used by SAMRAI-based application codes to generate VisIt data files. VisIt provides a wide range of visualization and post-processing capabilities. This class supports both cell-centered and node-centered 2D and 3D AMR data where the underlying data type is either double, float, or int. Scalar, vector and 2nd-order tensor variables are supported. This class may be used when the mesh geometry is managed by a geom::CartesianGridGeometry<DIM> object, or when the mesh itself is stored in a state variable to allow moving deformed grids. More...

#include <source/apputils/plotting/VisItDataWriter.h>

List of all members.

Public Member Functions
	VisItDataWriter (const std::string &object_name, const std::string &dump_directory_name, int number_procs_per_file=1, bool is_multiblock=false)
	The constructor initializes the VisIt data writer to a default state.
virtual	~VisItDataWriter ()
	The destructor for a VisItDataWriter object.
void	setDefaultDerivedDataWriter (VisDerivedDataStrategy< DIM > *default_derived_writer)
	This method sets the default data writer to use for derived data.
void	setMaterialsDataWriter (VisMaterialsDataStrategy< DIM > *materials_data_writer)
	This method sets the data writer to use for materials.
void	registerPlotQuantity (const std::string &variable_name, const std::string &variable_type, const int patch_data_index, const int start_depth_index=0, const double scale_factor=1.0, const std::string &variable_centering="UNKNOWN")
	This method registers a variable with the VisIt data writer.
void	registerDerivedPlotQuantity (const std::string &variable_name, const std::string &variable_type, VisDerivedDataStrategy< DIM > *derived_writer=(VisDerivedDataStrategy< DIM > *)(0), const double scale_factor=1.0, const std::string &variable_centering="CELL", const std::string &variable_mix_type="CLEAN")
	This method registers a derived variable with the VisIt data writer.
void	resetLevelPlotQuantity (const std::string &variable_name, const int level_number, const int patch_data_index, const int start_depth_index=0)
	This method resets the patch_data_index, and/or the depth_index, at a specific level, of a previously registered plot variable.
void	registerNodeCoordinates (const int patch_data_index, const int start_depth_index=0)
	This method is used to register node coordinates for deformed structured AMR grids (moving grids).
void	registerSingleNodeCoordinate (const int coordinate_number, const int patch_data_index, const int depth_index=0, const double scale_factor=1.0)
	Same as above method, but allows registration of single coordinate for deformed structured AMR grids (moving grids).
void	registerMaterialNames (const tbox::Array< std::string > &material_names)
	This method registers with the VisIt data writer the names of materials being used in the simulation.
void	registerSparseMaterialNames (const tbox::Array< std::string > &material_names)
	This method registers with the VisIt data writer the names of materials being used in the simulation.
void	registerSpeciesNames (const std::string &material_name, const tbox::Array< std::string > &species_names)
	This method registers the names of the species for a material_name with the VisIt data writer.
void	registerVisItExpressions (const tbox::Array< std::string > &expression_keys, const tbox::Array< std::string > &expressions, const tbox::Array< std::string > &expression_types)
	This method registers expressions that will be embedded in the VisIt datafiles.
void	writePlotData (const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, int time_step, double simulation_time=0.0)
	This method causes the VisIt data writer to dump all registered data. The appropriate packing methods will be invoked for material-related data and derived data.
void	setSummaryFilename (std::string &filename)
	Set the name of the summary file.

---

Detailed Description

template<int DIM>
class SAMRAI::appu::VisItDataWriter< DIM >

Class VisItDataWriter<DIM> is used by SAMRAI-based application codes to generate VisIt data files. VisIt provides a wide range of visualization and post-processing capabilities. This class supports both cell-centered and node-centered 2D and 3D AMR data where the underlying data type is either double, float, or int. Scalar, vector and 2nd-order tensor variables are supported. This class may be used when the mesh geometry is managed by a geom::CartesianGridGeometry<DIM> object, or when the mesh itself is stored in a state variable to allow moving deformed grids.

The VisIt data writer (VDW) supports CELL or NODE centered data of data type double, float, and integer. There is support to convert an alternative user-defined type into standard cell or node centered data for visualization purposes. See method descriptions below for more information. The data actually written by the VDW is of type float so data should not exceed the defined MAX_FLT and/or MIN_FLT. An optional scale factor may be supplied for data that exceeds these values.

After creating a VDW object, the data items to be dumped for plotting must be registered with that object. Thereafter, the object can be used to generate a series of visualization dump files during the execution of an application. The dumps will include all data items registered with the VDW.

This class supports the dumping of data that resides on an AMR patch hierarchy at the time the dump file is written, and derived data, data that does not live on the patch hierarchy, but that can be computed from data which does live on the patch hierarchy. Derived data requires the user to implement a method for a concrete class derived from the VisDerivedDataStrategy<DIM> abstract class.

The class also supports writing material and species data. Material is data which indicates for each cell, the fractional amount of a material compound, e.g. "steel", "gas", "copper", etc., contained in that cell. Species are subcomponents of a material, e.g. if the material is "gas", it may have subcomponents such as "nitrogen", "oxygen", etc. To use material data it is necessary for a user to implement the relevant packing methods for a concrete class derived from the VisMaterialsDataStrategy<DIM> abstract class.

The VDW requires the compilation of SAMRAI with the HDF5 library.

A brief summary of the basic steps typically involved in using the VDW are:

• Create a VisIt data writer object, specifying a name for the object and the name of the directory to contain the visit dump files. An optional argument number_procs_per_file, applicable to parallel runs, sets the number of processors that share a common dump file. This can reduce parallel I/O contention. The default value of this arg is 1. If the value specified is greater than the number of processors, then all processors share a single dump file.

• Register hierarchy variable data fields using registerPlotQuantity(). The variables registered may be scalar, vector, or tensor (depth 1, DIM, and DIM*DIM, respectively) which is specified in the argument list. All variables require a string identifier and an index into the patch data array on the AMR hierarchy. Optionally, a start depth index may be supplied to plot a single component of a multi-component field (i.e. a scalar quantity within a vector, or a vector within a tensor). A scale factor may also optionally be specified. Lastly, for user-defined data that is not cell or node type, the proper centering (cell or node) for the data may be supplied.

• If using derived data, set a default user-defined derived data writer using setDefaultDerivedDataWriter(). A derived data writer may also optionally be specified in the call to registerDerivedPlotQuantity(); if so, this derived data writer will be used for the variable being registered. If no derived writer is specified in the registration call, the default derived data writer will be used.

• Register derived variable data fields using registerDerivedPlotQuantity(). All derived variables require a string identifier. Optionally, a VisDerivedDataStrategy<DIM> object, a scale factor, and centering and may be specified. By default By default, the data is assumed to be cell-centered.

• The resetLevelPlotQuantity() method is provided for cases when a variable lives at different patch data indices on different levels. Invoking this method redefines the patch data array index for a given variable on a given level that will be written to a visit dump file. Before this method is called, the variable must be registered using registerPlotQuantity() method.

• If using deformed structured AMR grids (moving grids), register the coordinates of the nodes using the registerNodeCoordinates() method.

• If using materials, set the user-defined data writer for material data using setMaterialsDataWriter(). Then register the names of the materials being used with registerMaterialNames().

• If using species of the materials, register the names of the species of each material using the registerSpeciesNames() method.

• The writer will generate VisIt dump files when the method writePlotData() is called. Minimally, only a hierarchy and the time step number is needed. A simulation time can also be specified which will be included as part of the file information in the dump

• The document "Generating VisIt Visualization Data Files in SAMRAI" in the SAMRAI documentation directory (docs/userdocs/VisIt-writer.pdf) gives in-depth details on the use of the VDW and materials, as well as example code fragments showing how the various VisItDataWriter methods can be embedded in an application.

---

Constructor & Destructor Documentation

template<int DIM>

SAMRAI::appu::VisItDataWriter< DIM >::VisItDataWriter	(	const std::string &	object_name,
		const std::string &	dump_directory_name,
		int	number_procs_per_file = 1,
		bool	is_multiblock = false
	)

The constructor initializes the VisIt data writer to a default state.

The object_name argument is used primarily for error reporting. The dump_directory_name argument is the name of the directory which will contain the visit dump files. The directory name may include a path. If the dump directory or any intermediate directories in the path do not exist, they will be created. The optional number_procs_per_file argument is applicable to parallel runs and specifies the number of processors that share a common dump file; the default value is 1. If the specified number_procs_per_file is greater than the number of processors, then all processors share a single vis dump file. Reducing the number of files written may reduce parallel I/O contention and thus improve I/O efficiency. The optional argument is_multiblock defaults to false. It must be set to true for problems on multiblock domains, and left false in all other cases.

Before the data writer object can be used for dumping VisIt data, the variables and material-related data (if any) must be registered.

An error results and the program will halt if:

• the data is not 2D nor 3D, i.e. DIM != 2 and DIM != 3
• when assertion checking is active, the object name string is empty, or the number_procs_per_file is <= 0.

Parameters:

	object_name	String name for data writer object
	dump_directory_name	String name for dump directory, which may include a path.
	number_procs_per_file	Optional integer number processors (>= 1) to share a common dump file; default is 1.
	is_multiblock	Optional argument should be set to true only only for problems on a multiblock domain.

template<int DIM>

SAMRAI::appu::VisItDataWriter< DIM >::~VisItDataWriter

(

)

[virtual]

The destructor for a VisItDataWriter object.

The destructor for the writer does nothing interesting.

---

Member Function Documentation

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::setDefaultDerivedDataWriter

(

VisDerivedDataStrategy< DIM > *

default_derived_writer

)

This method sets the default data writer to use for derived data.

If a non-null derived data writer is supplied by the member function registerDerivedPlotQuantity() it will be used in place of the one given here.

An error results and the program will halt if:

• assertion checking is active and the default_derived_writer pointer is null.

Parameters:

default_derived_writer

tbox::Pointer to a VisDerivedDataStrategy object.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::setMaterialsDataWriter

(

VisMaterialsDataStrategy< DIM > *

materials_data_writer

)

This method sets the data writer to use for materials.

An error results and the program will halt if:

• assertion checking is active and the materials_data__writer pointer is null.

Parameters:

materials_data_writer

tbox::Pointer to a VisMaterialsDataStrategy object.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerPlotQuantity	(	const std::string &	variable_name,
		const std::string &	variable_type,
		const int	patch_data_index,
		const int	start_depth_index = 0,
		const double	scale_factor = 1.0,
		const std::string &	variable_centering = "UNKNOWN"
	)

This method registers a variable with the VisIt data writer.

Each plot quantity requires a variable name, which is what VisIt will label the plotted quantity. The variable type is a string specifying either "SCALAR", "VECTOR", or "TENSOR". By default, the dimension of a scalar variable is 1, vector is DIM, and tensor is DIM*DIM. The integer patch data array index and optional depth index indicate where the data may be found on patches in the hierarchy.

A number of optional parameters may be used to further specify characteristics of the plotted variable. The start depth index allows subsets of variables with depth greater than than the supplied type (scalar, vector, tensor) to be specified. For example, a single depth index of a variable with depth greater than one may be registered as a scalar. A scale factor may be specified such that each data value is multiplied by this factor before being written to the file. Finally, Finally, the variable centering may be specified for data that is not standard CELL or NODE centered types. By default, the writer will set the centering according to the type of data in the supplied patch data index. It will revert to the supplied type only if it is unable to determine the type from the index.

Data does not need to exist on all patches or all levels.

An error results and the program will halt if:

• a variable was previously registered with the same name.
• the variable type is not "SCALAR", "VECTOR", or "TENSOR"
• the patch data factory referred to by the patch data array index is null.
• the start depth index is invalid.
• the supplied variable centering is not "CELL" or "NODE".

Parameters:

	variable_name	name of variable.
	variable_type	"SCALAR", "VECTOR", "TENSOR"
	patch_data_index	patch data descriptor id
	start_depth_index	(optional) zero by default; may specify starting index if patch_data_id has depth greater than the supplied variable_type
	scale_factor	(optional) scale factor for data
	variable_centering	(optional) "CELL" or "NODE" - used only when data being registered is not standard cell or node type.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerDerivedPlotQuantity	(	const std::string &	variable_name,
		const std::string &	variable_type,
		VisDerivedDataStrategy< DIM > *	derived_writer = (VisDerivedDataStrategy< DIM > *)(0),
		const double	scale_factor = 1.0,
		const std::string &	variable_centering = "CELL",
		const std::string &	variable_mix_type = "CLEAN"
	)

This method registers a derived variable with the VisIt data writer.

Each derived variable requires a variable name, which is what VisIt will label the plotted quantity. The variable type is a string specifying either "SCALAR", "VECTOR", or "TENSOR". By default, the dimension of a scalar variable is 1, vector is DIM, and tensor is DIM*DIM. The derived writer should implement methods defined in the derived data strategy which compute the derived data.

Optional parameters may be used to further define characteristics of the derived variable. A scale factor may be specified such that each data value is multiplied by this factor before being written to the file. The variable centering should specify the variable as "CELL" or "NODE" type (if unspecified, "CELL" is used by default).

An error results and the program will halt if:

• a variable was previously registered with the same name.
• the variable type is not "SCALAR", "VECTOR", or "TENSOR"
• the derived_writer is NULL and there is no default derived writer.
• the supplied variable centering is not "CELL" or "NODE".

Parameters:

	variable_name	name of variable.
	variable_type	"SCALAR", "VECTOR", "TENSOR"
	derived_writer	(optional) derived data strategy object to use to calculate this derived data - will use default derived data object if not supplied
	scale_factor	(optional) scale factor with which to multiply all data values
	variable_centering	(optional) centering of derived data - "CELL" or "NODE"
	mix	type (optional) indicate whether or not the mixed material state will be stored, "MIXED", or the default of using cell averages "CLEAN". If "MIXED" then packMixedDerivedDataIntoDoubleBuffer() must be provided.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::resetLevelPlotQuantity	(	const std::string &	variable_name,
		const int	level_number,
		const int	patch_data_index,
		const int	start_depth_index = 0
	)

This method resets the patch_data_index, and/or the depth_index, at a specific level, of a previously registered plot variable.

The change redefines the patch data object written to the plot file on the specified level to the data at the new patch data array index / depth index. This method is used when a particular variable lives at different patch data slots on different hierarchy levels. For example, suppose a variable lives at a patch data array index on every level except the finest hierarchy level, where it lives at a different index. First, the variable must be registered using registerPlotQuantity(). Second, the patch data index for the finest hierarchy level is reset using this method. When the data is plotted, it will appear on all levels in the hierarchy. The patch data array index must refer to data with the same type (SCALAR, VECTOR, or TENSOR), centering (NODE or CELL), and data type (int, float, double) as the data for which the variable was originally registered.

An error results and the program will halt if:

• this variable name was not previously registered.
• the patch data referred to by the patch data array index is null, or the data type is not the same type as the data which was originally registered.
• the depth index is invalid.

Parameters:

	variable_name	name of variable.
	level_number	level number on which data index is being reset.
	patch_data_index	new patch data array index.
	start_depth_index	(optional) argument indicating the new depth index.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerNodeCoordinates	(	const int	patch_data_index,
		const int	start_depth_index = 0
	)

This method is used to register node coordinates for deformed structured AMR grids (moving grids).

The patch data index must correspond to an DIM dimensional vector that defines the coordinate location ([X,Y] in 2D, [X,Y,Z] in 3D). The data defining the node locations must be node centered.

An error results and the program will halt if:

• the patch data array index is invalid.
• the depth of the patch data index is less than DIM.

If the nodal coordinates are not in a NodeData object on the hierarchy, you can use registerDerivedPlotQuantity() with the variable name of "Coords", the type of "VECTOR" and the variable_centering of "NODE".

Parameters:

	patch_data_index	patch data index of the coordinate data.
	start_depth_index	(optional) start index for case where coordinate data is a subcomponent of a larger patch data vector

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerSingleNodeCoordinate	(	const int	coordinate_number,
		const int	patch_data_index,
		const int	depth_index = 0,
		const double	scale_factor = 1.0
	)

Same as above method, but allows registration of single coordinate for deformed structured AMR grids (moving grids).

The coordinate number should be 0, 1, or 2 for X, Y, and Z directions, respectively. The patch data index must either be a scalar, or a vector with an appropriate depth index. A scale factor may be used to scale grid data.

If the nodal coordinates are not in a NodeData object on the hierarchy, you can use registerDerivedPlotQuantity() with the variable name of "Coords", the type of "VECTOR" and the variable_centering of "NODE".

Parameters:

	coordinate_number	must be 0 or 1 for 2D, or 0,1,2 for 3D.
	patch_data_index	patch data index of the coordinate data.
	depth_index	(optional) index for case where coordinate data is a subcomponent of a larger patch data vector
	scale_factor	scale factor with which to multiply coordinate data values

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerMaterialNames

(

const tbox::Array< std::string > &

material_names

)

This method registers with the VisIt data writer the names of materials being used in the simulation.

When a mesh has materials defined over it, every cell will contain a fractional amount f (0 <= f <= 1.0) of every material, called a material fraction or volume fraction. The sum of all material fractions for every cell must be 1.0. Since materials are defined over a cell, each materials variable is assumed to be CELL centered.

In order to use materials with VisIt, the application class needs to inherit from VisMaterialsDataStrategy<DIM>, an abstract base class which defines an interface for writing out various materials related fields. A concrete object of this strategy must be registered with the VisIt data writer. That concrete object is responsible for providing a concrete implementation of the method packMaterialFractionsIntoDoubleBuffer() which writes out the material fractions for each registered material over a given patch.

VisIt uses the material fractions to calculate interpolated material boundaries in cells with multiple materials. Therefore VisIt can display a material (or materials) as multiple colored contiguous regions. In addition, VisIt can intersect this volume field with a plane and get accurate 2D boundaries within cells. If desired, the material fractions for a material can be treated as a scalar field and the usual scalar field plot tools, such as pseudocolor and contour, can be applied.

Because species are a subset of materials, it is required that the material names be registered before any species names are registered. New materials may not be added during the simulation; that is, this method should only be called once.

An error results and the program will halt if:

• this method is called more than once.
• the new registerSparseMaterialNames() method is called
• when assertion checking is active, the number of names = 0, or any material name string is empty.

Parameters:

material_names

tbox::Array of strings: the names of the materials.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerSparseMaterialNames

(

const tbox::Array< std::string > &

material_names

)

This method registers with the VisIt data writer the names of materials being used in the simulation.

When a mesh has materials defined over it, every cell will contain a fractional amount f (0 <= f <= 1.0) of every material, called a material fraction or volume fraction. The sum of all material fractions for every cell must be 1.0. Since materials are defined over a cell, each materials variable is assumed to be CELL centered.

In order to use materials with VisIt, the application class needs to inherit from VisMaterialsDataStrategy<DIM>, an abstract base class which defines an interface for writing out various materials related fields. A concrete object of this strategy must be registered with the VisIt data writer. That concrete object is responsible for providing a concrete implementation of the method packMaterialFractionsIntoSparseBuffers() which writes out the material fractions for each registered material over a given patch.

VisIt uses the material fractions to calculate interpolated material boundaries in cells with multiple materials. Therefore VisIt can display a material (or materials) as multiple colored contiguous regions. In addition, VisIt can intersect this volume field with a plane and get accurate 2D boundaries within cells. If desired, the material fractions for a material can be treated as a scalar field and the usual scalar field plot tools, such as pseudocolor and contour, can be applied.

An error results and the program will halt if:

• this method is called more than once.
• the legacy registerMaterialNames() method is called
• when assertion checking is active, the number of names = 0, or any material name string is empty.

Parameters:

material_names

tbox::Array of strings: the names of the materials.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerSpeciesNames	(	const std::string &	material_name,
		const tbox::Array< std::string > &	species_names
	)

This method registers the names of the species for a material_name with the VisIt data writer.

Species are subcomponents of a material. For example, a simulation with 4 materials (e.g. "copper", "gold", "liquid" and "gas") may have one of the materials (e.g. "gas") that is composed of multiple species (e.g. "nitrogen" and helium"). Each species is associated with a particular material, so it is necessary that the "registerMaterialNames()" method is called before this method.

For each species name registered, there is an associated species fraction, which must be between 0 and 1.0 on each cell. The sum of the species fractions for all species of a given material must equal 1.0 in every cell in which that material appears. In VisIt, the species fractions for a species can be treated as a scalar field and the usual scalar plot operations applied to the field to show "concentrations". So, in the example described above, the percentage of nitrogen in the gas can be displayed in a pseudocolor plot.

In order to use species with VisIt, the application class needs to inherit from VisMaterialsDataStrategy<DIM>, an abstract base class which defines an interface for writing out species related fields. A concrete object of the materials data strategy class is responsible for providing an implementation of the method packSpeciesFractionsIntoDoubleBuffer() to write out the species fractions field for each registered species over a given patch.

An error results and the program will halt if:

• this method is called before registerMaterialNames() is called.
• the supplied material name is not in the list of materials supplied in the registerMaterialNames() method.
• the method is called more than once for a given material
• when assertion checking is active, the number of names = 0, or any name string is empty.

Parameters:

	material_name	String name of the material whose species names are being registered.
	species_names	tbox::Array of strings: the names of the species for material_name.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::registerVisItExpressions	(	const tbox::Array< std::string > &	expression_keys,
		const tbox::Array< std::string > &	expressions,
		const tbox::Array< std::string > &	expression_types
	)

This method registers expressions that will be embedded in the VisIt datafiles.

The three Arrays of strings define the names (or keys) of the expressions, the expressions, and the types of the expressions (scalar, vector, tensor). For more information on defining VisIt expressions see the VisItUsersManual.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::writePlotData	(	const tbox::Pointer< hier::BasePatchHierarchy< DIM > >	hierarchy,
		int	time_step,
		double	simulation_time = 0.0
	)

This method causes the VisIt data writer to dump all registered data. The appropriate packing methods will be invoked for material-related data and derived data.

The time step number is used as a file name extension for the dump files. It must be non-negative and greater than the previous time step, if any. A simulation time may be provided as an optional argument. If this time is not specified, a default value of zero is used. The simulation time can be accessed in VisIt's "File Information" dialog box.

An error results and the program will halt if:

• materials have been registered, but setMaterialsDataWriter() has not been called.
• the time step number is <= the previous time step number.
• when assertion checking is active, the hierarchy pointer is null, the time step is < 0, or the dump directory name string is empty,

Parameters:

	hierarchy	A pointer to the patch hierarchy on which the data to be plotted is defined.
	time_step	Non-negative integer value specifying the current time step number.
	simulation_time	Optional argument specifying the double precision simulation time. Default is 0.0.

template<int DIM>

void SAMRAI::appu::VisItDataWriter< DIM >::setSummaryFilename

(

std::string &

filename

)

Set the name of the summary file.

This sets the summary file written at each step of the simulation which describes the data contained in the visit files written by each MPI process. The supplied string is appended with ".samrai" so the actual name of the file will be "<filename>.samrai". If no alternative name is supplied, by default the summary file used is "summary.samrai".

---

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

• source/apputils/plotting/VisItDataWriter.h
• source/apputils/plotting/VisItDataWriter.C

---