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

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

List of all members.

Public Member Functions
	CartesianVizamraiDataWriter (const std::string &name)
virtual	~CartesianVizamraiDataWriter ()
void	setFinestLevelToPlot (int finest_level_number)
void	setRatioToCoarserLevel (int level_number, const hier::IntVector< DIM > &ratio)
void	setPlotDataToDouble ()
void	setPlotDataToFloat ()
void	setDerivedDataWriter (VisDerivedDataStrategy< DIM > *derived_writer)
void	setDirectoryName (const std::string &directory_name)
void	registerPlotScalar (const std::string &variable_name, int data_id, int depth_id=0, double scale_factor=1.0)
void	resetLevelPlotScalar (const std::string &variable_name, int level_number, int data_id, int depth_id=0)
void	registerPlotVector (const std::string &variable_name, int data_id, double scale_factor=1.0)
void	resetLevelPlotVector (const std::string &variable_name, int level_number, int data_id)
void	registerDerivedPlotScalar (const std::string &variable_name, VisDerivedDataStrategy< DIM > *derived_writer=(VisDerivedDataStrategy< DIM > *)(0))
void	registerDerivedPlotVector (const std::string &variable_name, int depth, VisDerivedDataStrategy< DIM > *derived_writer=(VisDerivedDataStrategy< DIM > *)(0))
void	writePlotData (const tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, const std::string &file_name, int extension=-1, double plot_time=0.0)
virtual void	printClassData (std::ostream &os) const

---

Detailed Description

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

Class CartesianVizamraiDataWriter<DIM> is used by SAMRAI-based application codes to generate Vizamrai data files. Vizamrai provides a wide range of visualization and post-processing capabilities for data generated on a structured AMR patch hierarchy. Vizamrai supports cell-centered mesh data. This class supports cell-centered data where the underlying data type is either double, float, or int.

This data file writer class can be used to generate Vizamrai data files when the underlying mesh geometry is managed by a geom::CartesianGridGeometry<DIM> object. Two kinds of data quantities are supported by this class. The first is data that resides on an AMR patch hierarchy when a data file is generated. The second is "derived" data that can be computed using data on an AMR patch hierarchy. The first data type requires no user intervention when generating a plot file. The second type, or "derived" data, requires that a user implement a concrete class derived from the VisDerivedDataStrategy<DIM> abstract interface. In an overloaded function of that class, a user generates the "derived" data quantity and writes it to a specified file stream. In either case, scalar or variable data quantities are supported.

Before a Vizamrai data writer object can be used to generate Vizamrai data files, it must first be constructed and initialized. Initialization involves things like setting information about the levels in the AMR hierarchy that will be plotted, setting the type of the data to write out (e.g., double or float), setting the directory into which plot files are written, and registering variable quantities to send to the plot file. After initialization, the object can be used to generate a series of data files during the execution of some simulation code.

Typical usage of this Vizamrai data writer object involves several steps among which are variations. Basic usage is as follows:

1. Create a Cartesian Vizamrai data writer object.
2. Set the finest level to plot with the member function setFinestLevelToPlot(). This is the finest level allowable in any plot file; however, only levels in the hierarchy will be written out.
3. For each level OTHER THAN THE COARSEST , specify the ratio between the index space of the level and the next coarser level in the AMR hierarchy. This information is needed for scaling the AMR levels properly in Vizamrai. The member function to use is setRatioToCoarserLevel().
4. Set the type of data to put in the Vizamrai file, using either setPlotDataToDouble(), or setPlotDataToFloat(). The default is to write float data.
5. Set the directory for the plot files if desired using the function setDirectoryName(). If no directory is specified, files will be written into the current directory.
6. If any "derived" quantities will be generated, set the concrete derived data writer object using setDerivedDataWriter(). Alternatively, one may specify a derived data writer when registering each derived data quantity. This provides flexibility in using different derived data writers for different quantities if desired.
7. Register data quantities using either registerPlotScalar()/registerPlotVector() or registerDerivedPlotScalar()/registerDerivedPlotVector(). Derived data quantities require only a string identifier and a derived data writer if not specified earlier. All other quantities require a string identifier and an index into the patch data array on the AMR hierarchy. A scale factor may also be specified. Note that you cannot register more than one variable with the same name. If this is attempted, an error message is logged and the program will exit.
8. The resetLevelPlotScalar()/resetLevelPlotVector() member functions are provided for cases when a plot quantity lives at different patch data indices on different levels. Calling this routine redefines the patch data index for a given quantity on a given level that will be written to a plot file. Before this function is called, the quantity must be registered using the registerPlotScalar()/registerPlotVector() function.
9. Finally, the writer can be used to generate Vizamrai data files using the member function writePlotData(). Minimally, only a hierarchy and a file name is needed. One can also supply an integer file extension and a plot time, both of which are useful when generating visualization files for time-dependent applications.

During the course of generating Vizamrai data files, certain features of the plot files may change. For example, the directory name can be reset using the setDirectoryName() function. Also, the finest level to plot using the setFinestLevelToPlot() function. Some restrictions apply. Please consult the member function documentation for more details.

See also:

appu::VisDerivedDataStrategy

---

Constructor & Destructor Documentation

template<int DIM>

SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::CartesianVizamraiDataWriter

(

const std::string &

name

)

The constructor for CartesianVizamraiDataWriter<DIM> initializes this Vizamrai data writer to a default state. The default state is to write data as floats (instead of doubles). Before it can be used for writing data to a Vizamrai plot file, the maximum number of hierarchy levels must be set and the variables to plot must be registered. See the member functions setMaxHierarchyLevels() and the register functions.

When assertion checking is active, a non-recoverable exception results if the string is empty. This name is used primarily for error reporting.

Parameters:

name

Name given to object.

template<int DIM>

SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::~CartesianVizamraiDataWriter

(

)

[virtual]

The destructor for the writer does nothing interesting.

---

Member Function Documentation

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::setFinestLevelToPlot

(

int

finest_level_number

)

Set the finest hierarchy level to write to a Vizamrai file. Calling this function is optional. If this function is not called, the finest level to be plotted is the finest level in the hierarchy when the writePlotData() function is called or the finest level for which the function setRatioToCoarsrLevel() has been called, whichever is coarser. Thus, this routine can be used to increase or decrease the number of levels to plot, but it cannot be used to plot a level for which scaling ratio information has not been previously provided.

Calling this function a negative value will result in a plot file with no data written in it when writePlotData() is called.

If the integer is negative, no levels will be written to any plot file. If an attempt is made to set this value larger than the finest level for which previous scaling information has been given (e.g., using setRatioToCoarserLevel()), a warning message will be logged.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::setRatioToCoarserLevel	(	int	level_number,
		const hier::IntVector< DIM > &	ratio
	)

Set the vector ratio between the index space of the patch level with the given number and the next coarser patch level. This information is needed for proper scaling of the domain when Vizamrai visualizes datasets.

If this Vizamrai data writer object will be used to write multiple data files (e.g., for a series of timesteps) and the number of levels will never change, then calling this routine is optional. However, if the number of levels to plot may change from one plot file to the next, this routine must be called for each level finer than the finest level written in the first Vizamrai plot file written by this writer object.

In any case, the number of levels actually written to a plot file will depend on the number of levels in the patch hierarchy sent to the writePlotData() routine, the finest level indicated in the most recent call to the function setFinestLevelToPlot(), and the manner in which this routine is called. Also, when used, this function must be called before the first plot file is written; i.e., before the writePlotData() member function is called.

When assertion checking is active, a non-recoverable exception results if level number is negative. If an attempt is made to call this function after a Vizamrai file has been written by this writer, an error message will be logged and the program will terminate.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::setPlotDataToDouble

(

)

Set the format of the plot data to type double. The default data format is float. If an attempt is made to change the data format after a Vizamrai file has been written by this writer, a warning message will be logged.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::setPlotDataToFloat

(

)

Set the format of the plot data to type float. The default data format is float. If an attempt is made to change the data format after a Vizamrai file has been written by this writer, a warning message will be logged.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::setDerivedDataWriter

(

VisDerivedDataStrategy< DIM > *

derived_writer

)

Set default user-defined data writer for each derived variable quantity to write to the plot file. If a non-null derived data writer is supplied to the member function registerDerivedPlotScalar()/registerDerivedPlotVecotr(), it will supercede the one given here.

When assertion checking is active, a non-recoverable exception results if the pointer is null.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::setDirectoryName

(

const std::string &

directory_name

)

Set name of directory into which Vizamrai files will be written. Permissions are set by default to rwx by user. Any intermediate directories (including the top level) in the path are created if they do not already exist. When running jobs in parallel, only node zero will create the directories. Calling this function is optional. If no directory name is specified, the Vizamrai file will be written into the current directory (i.e., the directory in which the code is executed).

When assertion checking is active, a non-recoverable exception results if the string is empty.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::registerPlotScalar	(	const std::string &	variable_name,
		int	data_id,
		int	depth_id = 0,
		double	scale_factor = 1.0
	)

Register a non-derived scalar variable quantity with given name and patch data id with this Vizamrai data writer. The integer data identifier indicates the descriptor index at which the data may be found on each patch in the hierarchy. The depth index refers to the depth into the patch data array of the scalar plot quantity. For example, when plotting individual entries of a quantity that is maintained as a vector in each cell on the hierarchy, this is the index into the vector (e.g., think "y"-component of velocity, where the velocity is stored as a patch data type of depth DIM. If the data id integer does not correspond to a valid patch data index, or if the depth id integer is out of range for the given data id, an error message will result and the program will exit. See the function registerPlotVector() below for plotting a vector quantity as a vector rather than multiple scalar quantities.

If the scale factor is specified, each data value will be multiplied by this factor before it is written to the data file.

The integer data identifier will be checked to see if it is a valid cell-centered patch data object in the patch descriptor. Valid cell- centered types are double, float, and int.

If a variable was previously registered with the same name, the most recent registration replaces the previous one.

When assertion checking is active, a non-recoverable exception results if the string is empty, or if the data id or depth id are negative.

Parameters:

	variable_name	Vizamrai name identifier for the variable.
	data_id	Cell-centered patch data descriptor identifyer for the variable (may be double, float, or int).
	depth_id	Depth into the patch data array of the scalar plot quantity.
	scale_factor	Scaling factor applied to the variable data when writing viz files.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::resetLevelPlotScalar	(	const std::string &	variable_name,
		int	level_number,
		int	data_id,
		int	depth_id = 0
	)

Change a previously-registered, non-derived variable quantity with given name with this Vizamrai data writer. The change redefines the patch data objects written to the plot file on the specified level to the data at the given descriptor index and depth index. This function is used when a particular data quantity lives at different patch data slots on different hierarchy levels. For example, suppose a plot data quantity lives at a patch data index on every level except the finest hierarchy level, where it lives at a different index. First, that quantity must be registered using registerPlotScalar()/registerPlotVector(). Second, the patch data index for the finest hierarchy level is reset using this function. When the data is plotted, it will appear on all levels in the hierarchy.

Before this function can be called, the plot quantity must already be registered using a registerPlotScalar() function. If it is not, then a warning message will result and the variable will not be registered for plotting.

The data id integer argument must correspond to a valid patch data index with the same type as the data for which the quantity was originally registered using registerPlotScalar(). The depth id integer (if given) only applies to the case where the original registration of the plot quantity with the string name was as a scalar. In this case, the depth id must be valid for the given data id. If either of these arguments is illegal, an error message will be printed and the program will abort. See comments for the registerPlotScalar() function for restrictions on the data types allowed.

If a variable was previously registered with the same name, the most recent registration replaces the previous one.

When assertion checking is active, a non-recoverable exception results if the string is empty, or if the data id, depth id, or level number are negative.

Parameters:

	variable_name	Vizamrai name identifier for the variable.
	level_number	The level number on which variable data is defined.
	data_id	Cell-centered patch data descriptor identifyer for the variable (may be double, float, or int).
	depth_id	Depth into the patch data array of the scalar plot quantity.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::registerPlotVector	(	const std::string &	variable_name,
		int	data_id,
		double	scale_factor = 1.0
	)

Register a non-derived vector quantity with given name and patch data id with this Vizamrai data writer. The integer data identifier indicates the descriptor index at which the data may be found on each patch in the hierarchy. If the data id integer does not correspond to a valid patch data index, an error message will result and the program will exit. No depth index is required, since data at all depths will be written for a vector quantitiy. See the function registerPlotVariable() above for plotting components of a vector as multiple scalar quantities.

If the scale factor is specified, each data value will be multiplied by this factor before it is written to the data file.

The integer data identifier will be checked to see if it is a valid cell-centered patch data object in the patch descriptor. Valid cell- centered types are double, float, and int.

If a variable was previously registered with the same name, the most recent registration replaces the previous one.

When assertion checking is active, a non-recoverable exception results if the string is empty, or if the data id is negative.

Parameters:

	variable_name	Vizamrai name identifier for the variable.
	data_id	Cell-centered patch data descriptor identifyer for the variable (may be double, float, or int).
	scale_factor	Scaling factor applied to the variable data when writing viz files.

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::resetLevelPlotVector	(	const std::string &	variable_name,
		int	level_number,
		int	data_id
	)

Change a previously-registered, non-derived variable quantity with given name with this Vizamrai data writer. The change redefines the patch data objects written to the plot file on the specified level to the data at the given descriptor index and depth index. This function is used when a particular data quantity lives at different patch data slots on different hierarchy levels. For example, suppose a plot data quantity lives at a patch data index on every level except the finest hierarchy level, where it lives at a different index. First, that quantity must be registered using registerPlotVector(). Second, the patch data index for the finest hierarchy level is reset using this function. When the data is plotted, it will appear on all levels in the hierarchy.

Before this function can be called, the plot quantity must already be registered using a registerPlotVector() function. If it is not, then a warning message will result and the variable will not be registered for plotting.

The data id integer argument must correspond to a valid patch data index with the same type as the data for which the quantity was originally registered using registerPlotVector().

If a variable was previously registered with the same name, the most recent registration replaces the previous one.

When assertion checking is active, a non-recoverable exception results if the string is empty, or if the data id, depth id, or level number are negative.

Parameters:

	variable_name	Vizamrai name identifier for the variable.
	level_number	The level number on which variable data is defined.
	data_id	Cell-centered patch data descriptor identifyer for the variable (may be double, float, or int).

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::registerDerivedPlotScalar	(	const std::string &	variable_name,
		VisDerivedDataStrategy< DIM > *	derived_writer = (VisDerivedDataStrategy< DIM > *)(0)
	)

Register a scalar derived variable quantity with the given name with this Vizamrai data writer. If a non-null derived data writer is given it will supercede any that has previously been specified in the setDerivedDataWriter() member function.

When assertion checking is active, a non-recoverable exception results if the argument string is empty.

Parameters:

	variable_name	Vizamrai name identifier for the variable.
	derived_writer	tbox::Pointer to the VizamraiDerivedDataStrategy class (which implements 'writeDerivedDataToStream').

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::registerDerivedPlotVector	(	const std::string &	variable_name,
		int	depth,
		VisDerivedDataStrategy< DIM > *	derived_writer = (VisDerivedDataStrategy< DIM > *)(0)
	)

Register a vector derived variable quantity with given name and depth (i.e., number of components) with this Vizamrai data writer. If a non-null derived data writer is given it will supercede any that has previously been specified in the setDerivedDataWriter() member function.

When assertion checking is active, a non-recoverable exception results if the argument string is empty.

Parameters:

	variable_name	Vizamrai name identifier for the variable.
	depth	number of components
	derived_writer	tbox::Pointer to the VizamraiDerivedDataStrategy class (which implements 'writeDerivedDataToStream').

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::writePlotData	(	const tbox::Pointer< hier::PatchHierarchy< DIM > >	hierarchy,
		const std::string &	file_name,
		int	extension = -1,
		double	plot_time = 0.0
	)

Write Vizamrai plot file with given file name, using data in given hierarchy that matches registered plot quantity information. The data file will be written in the directory specified in the most recent call to setDirectoryName(). If no directory name has been specified, the Vizamrai file will be written into the current directory (i.e., the directory in which the code is executed). Optional arguments are available to provide an integer file number extension and a plot time value to stamp the data in the Vizamrai plot file. If a integer extension (>= 0) is provided, the name of the file will contain `file_name.extention'. Otherwise, the extension will be ignored. If the time is not specified, a default value of zero is used.

If a variable was previously registered with the same name, the most recent registration replaces the previous one.

When assertion checking is active, a non-recoverable exception results if the file name string is empty, or if the hierarchy pointer is null.

Parameters:

	hierarchy	hier::Patch hierarchy on which data is defined.
	file_name	File prefix for vizamrai data files
	extension	Extension which may be appended to the file name (i.e. 'file_name.extension'
	plot_time	Simulation time of the plot

template<int DIM>

void SAMRAI::appu::CartesianVizamraiDataWriter< DIM >::printClassData

(

std::ostream &

os

)

const [virtual]

Send all data in this Vizamrai file writer to given output stream.

---

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

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

---