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...
|
| | 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. More...
|
| |
| virtual | ~VisItDataWriter () |
| | The destructor for a VisItDataWriter object. More...
|
| |
| void | setDefaultDerivedDataWriter (VisDerivedDataStrategy< DIM > *default_derived_writer) |
| | This method sets the default data writer to use for derived data. More...
|
| |
| void | setMaterialsDataWriter (VisMaterialsDataStrategy< DIM > *materials_data_writer) |
| | This method sets the data writer to use for materials. More...
|
| |
| 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. More...
|
| |
| void | registerDerivedPlotQuantity (const std::string &variable_name, const std::string &variable_type, VisDerivedDataStrategy< DIM > *derived_writer=(VisDerivedDataStrategy< DIM > *) NULL, 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. More...
|
| |
| 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. More...
|
| |
| 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). More...
|
| |
| 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). More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| void | setSummaryFilename (std::string &filename) |
| | Set the name of the summary file. More...
|
| |
|
| void | initializePlotItem (VisItItem &plotitem, const std::string &variable_name, const std::string &variable_type, const int patch_data_index, const int start_depth_index, const double scale_factor, const std::string &variable_centering) |
| |
| void | resetLevelPlotItem (const std::string &variable_name, int level_number, int patch_data_array_index, int start_depth_index, std::string method_name) |
| |
| void | writeHDFFiles (const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, double simulation_time) |
| |
| void | initializePlotVariableMinMaxInfo (const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy) |
| |
| void | writeVisItVariablesToHDFFile (tbox::Pointer< tbox::Database > processor_HDFGroup, const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, int coarsest_level, int finest_level) |
| |
| void | packRegularAndDerivedData (tbox::Pointer< tbox::Database > patch_HDFGroup, const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const int level_number, const int block_number, hier::Patch< DIM > &patch) |
| |
| void | packMaterialsData (tbox::Pointer< tbox::Database > patch_HDFGroup, const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const int level_number, const int block_number, hier::Patch< DIM > &patch) |
| |
| void | packSpeciesData (const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const int level_number, const int block_number, hier::Patch< DIM > &patch) |
| |
| void | checkFloatMinMax (const std::string &var_name, const double dmin, const double dmax, const int level_number, const int patch_number, const int patch_data_id) |
| |
| int | getGlobalPatchNumber (const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const int level_number, const int block_number, const int patch_number) |
| |
| void | writeParentChildInfoToSummaryHDFFile (const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, tbox::Pointer< tbox::Database > basic_HDFGroup) |
| |
| void | dumpWriteBarrierBegin () |
| |
| void | dumpWriteBarrierEnd () |
| |
| void | writeSummaryToHDFFile (std::string dump_dir_name, const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, int coarsest_plot_level, int finest_plot_level, double simulation_time) |
| |
| void | exchangeMinMaxPatchInformation (const tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const int coarsest_plot_level, const int finest_plot_level) |
| |
| void | packPatchDataIntoDoubleBuffer (const tbox::Pointer< hier::PatchData< DIM > > pdata, const int depth_index, const variable_data_type type_of_data, const hier::Box< DIM > patch_box, double *buffer, const variable_centering centering) |
| |
| void | HDFputIntegerArray2D (const std::string &key, const int *data, const int nelements0, const int nelements1, const hid_t group_id) |
| |
| void | HDFputDoubleArray2D (const std::string &key, const double *data, const int nelements0, const int nelements1, const hid_t group_id) |
| |
| void | HDFputPatchExtentsStructArray (const std::string &key, const patchExtentsStruct *data, const int nelements, const hid_t group_id) |
| |
| void | HDFputPatchMapStructArray (const std::string &key, const patchMapStruct *data, const int nelements, const hid_t group_id) |
| |
| void | HDFputPatchMinMaxStructArray (const std::string &key, const patchMinMaxStruct *data, const int nelements, const hid_t group_id) |
| |
| void | HDFputChildParentStructArray (const std::string &key, const void *data, const int nelements, const hid_t group_id, const int sizeOfStruct, const std::string &fieldName) |
| |
| int | getBufferSize (const hier::Box< DIM > patch_box, const hier::IntVector< DIM > &ghost_cell_width, const variable_centering centering) |
| |
| void | dumpItem (VisItItem &plotitem, std::ostream &os) const |
| |
template<int DIM>
class SAMRAI::appu::VisItDataWriter< DIM >
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.
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" |
|
) |
| |
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. |
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. |
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. |
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. |
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. |
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. |
