WriteHDF5.hpp

Go to the documentation of this file.

/**
 * MOAB, a Mesh-Oriented datABase, is a software component for creating,
 * storing and accessing finite element mesh data.
 *
 * Copyright 2004 Sandia Corporation. Under the terms of Contract
 * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
 * retains certain rights in this software.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 */
 
#ifndef WRITE_HDF5_HPP
#define WRITE_HDF5_HPP
 
#include <list>
#include "moab/MOABConfig.h"
#ifdef MOAB_HAVE_MPI // include this before HDF5 headers to avoid conflicts
#include "moab_mpi.h"
#endif
#include "moab_mpe.h"
#include "mhdf.h"
#include "moab/Forward.hpp"
#include "moab/Range.hpp"
#include "moab/WriterIface.hpp"
#include "moab/RangeMap.hpp"
#include "moab/WriteUtilIface.hpp"
#include "DebugOutput.hpp"
#include "HDF5Common.hpp"
 
namespace moab
{
 
class IODebugTrack;
 
/* If this define is not set, node->entity adjacencies will not be written */
#undef MB_H5M_WRITE_NODE_ADJACENCIES
 
/**
 * \brief Write mesh database to MOAB's native HDF5-based file format.
 * \author Jason Kraftcheck
 * \date 01 April 2004
 */
class WriteHDF5 : public WriterIface
{
 
 public:
 static WriterIface* factory( Interface* );
 
 WriteHDF5( Interface* iface );
 
 virtual ~WriteHDF5();
 
 /** Export specified meshsets to file
 * \param filename The filename to export.
 * \param export_sets Array of handles to sets to export, or NULL to export all.
 * \param export_set_count Length of <code>export_sets</code> array.
 */
 ErrorCode write_file( const char* filename,
 const bool overwrite,
 const FileOptions& opts,
 const EntityHandle* export_sets,
 const int export_set_count,
 const std::vector< std::string >& qa_records,
 const Tag* tag_list = NULL,
 int num_tags = 0,
 int user_dimension = 3 );
 
 /** The type to use for entity IDs w/in the file.
 *
 * NOTE: If this is changed, the value of id_type
 * MUST be changed accordingly.
 */
 typedef EntityHandle wid_t; // change the name,
 // to avoid conflicts to /usr/include/x86_64-linux-gnu/bits/types.h : id_t , which is unsigned
 // int
 
 /** HDF5 type corresponding to type of wid_t */
 static const hid_t id_type;
 
 struct ExportType
 {
 //! The type of the entities in the range
 EntityType type;
 //! The number of nodes per entity - not used for nodes and sets
 int num_nodes;
 
 virtual ~ExportType() {}
 
 bool operator==( const ExportType& t ) const
 {
 return t.type == type && t.num_nodes == num_nodes;
 }
 bool operator!=( const ExportType& t ) const
 {
 return t.type != type || t.num_nodes != num_nodes;
 }
 bool operator<( const ExportType& t ) const
 {
 return type < t.type || ( type == t.type && num_nodes < t.num_nodes );
 }
 };
 
 //! Range of entities, grouped by type, to export
 struct ExportSet : public ExportType
 {
 //! The range of entities.
 Range range;
 //! The first Id allocated by the mhdf library. Entities in range have sequential IDs.
 wid_t first_id;
 //! The offset at which to begin writing this processor's data.
 //! Always zero except for parallel IO.
 long offset;
 //! Offset for adjacency data. Always zero except for parallel IO
 long adj_offset;
 //! If doing parallel IO, largest number of entities to write
 //! for any processor (needed to do collective IO). Zero if unused.
 long max_num_ents, max_num_adjs;
 //! The total number of entities that will be written to the file
 //! for this group. For serial IO, this should always be range.size().
 //! For parallel IO, it will be the sum of range size over all processors.
 //! For parallel IO, this value is undefined except for on the root
 //! processor.
 long total_num_ents;
 
 bool operator<( const ExportType& other ) const
 {
 return type < other.type || ( type == other.type && num_nodes < other.num_nodes );
 }
 
 bool operator<( std::pair< int, int > other ) const
 {
 return type < other.first || ( type == other.first && num_nodes < other.second );
 }
 
 bool operator==( const ExportType& other ) const
 {
 return ( type == other.type && num_nodes == other.num_nodes );
 }
 
 bool operator==( std::pair< int, int > other ) const
 {
 return ( type == other.first && num_nodes == other.second );
 }
 
 const char* name() const;
 };
 
 //! Tag to write to file.
 struct TagDesc
 {
 //! The tag handle
 Tag tag_id;
 //! The offset at which to begin writting this processor's data.
 //! Always zero except for parallel IO.
 wid_t sparse_offset;
 //! For variable-length tags, a second offset for the tag data table,
 //! separate from the offset used for the ID and Index tables.
 //! Always zero except for parallel IO.
 wid_t var_data_offset;
 //! Write sparse tag data (for serial, is always equal to !range.empty())
 bool write_sparse;
 //! If doing parallel IO, largest number, over all processes, of entities
 //! for which to write tag data. Zero if unused.
 unsigned long max_num_ents;
 //! For variable-length tags during parallel IO: the largest number
 //! of tag values to be written on by any process, used to calculate
 //! the total number of collective writes that all processes must do.
 //! Zero for fixed-length tags or if not doing parallel IO.
 unsigned long max_num_vals;
 
 //! List of entity groups for which to write tag data in
 //! dense format
 std::vector< ExportType > dense_list;
 
 bool have_dense( const ExportType& type ) const
 {
 return std::find( dense_list.begin(), dense_list.end(), type ) != dense_list.end();
 }
 
 bool operator<( const TagDesc& ) const;
 };
 
 /** Create attributes holding the HDF5 type handle for the
 * type of a bunch of the default tags.
 */
 // static ErrorCode register_known_tag_types( Interface* );
 
 //! Store old HDF5 error handling function
 struct HDF5ErrorHandler
 {
 HDF5_Error_Func_Type func;
 void* data;
 };
 
 mhdf_FileHandle file_ptr()
 {
 return filePtr;
 }
 
 WriteUtilIface* write_util()
 {
 return writeUtil;
 }
 
 protected:
 //! Store old HDF5 error handling function
 HDF5ErrorHandler errorHandler;
 
 /** Function to create the file. Virtual to allow override
 * for parallel version.
 */
 virtual ErrorCode parallel_create_file( const char* filename,
 bool overwrite,
 const std::vector< std::string >& qa_records,
 const FileOptions& opts,
 const Tag* tag_list,
 int num_tags,
 int dimension = 3,
 double* times = 0 );
 virtual ErrorCode write_finished();
 virtual void debug_barrier_line( int lineno );
 
 //! Gather tags
 ErrorCode gather_tags( const Tag* user_tag_list, int user_tag_list_length );
 
 /** Check if tag values for a given ExportSet should be written in dense format
 *
 *\param ents ExportSet to consider
 *\param all_tagged Range containing all the entities in ents.range for
 * which an explicit tag value is stored. Range may
 * also contain entities not in ents.range, but may
 * not contain entities in ents.range for which no tag
 * value is stored.
 *\param prefer_dense If true, will return true if at least 2/3 of the
 * entities are tagged. This should not be passed as
 * true if the tag does not have a default value, as
 * tag values must be stored for all entities in the
 * ExportSet for dense-formatted data.
 */
 bool check_dense_format_tag( const ExportSet& ents, const Range& all_tagged, bool prefer_dense );
 
 /** Helper function for create-file
 *
 * Calculate the sum of the number of non-set adjacencies
 * of all entities in the passed range.
 */
 ErrorCode count_adjacencies( const Range& elements, wid_t& result );
 
 public: // make these public so helper classes in WriteHDF5Parallel can use them
 /** Helper function for create-file
 *
 * Create zero-ed tables where element connectivity and
 * adjacency data will be stored.
 */
 ErrorCode create_elem_table( const ExportSet& block, long num_ents, long& first_id_out );
 
 /** Helper function for create-file
 *
 * Create zero-ed table where set descriptions will be written
 */
 ErrorCode create_set_meta( long num_sets, long& first_id_out );
 
 protected:
 /** Helper function for create-file
 *
 * Calculate total length of set contents and child tables.
 */
 ErrorCode count_set_size( const Range& sets,
 long& contents_length_out,
 long& children_length_out,
 long& parents_length_out );
 
 //! Get information about a meshset
 ErrorCode get_set_info( EntityHandle set,
 long& num_entities,
 long& num_children,
 long& num_parents,
 unsigned long& flags );
 
 /** Helper function for create-file
 *
 * Create zero-ed tables where set data will be written.
 */
 ErrorCode create_set_tables( long contents_length, long children_length, long parents_length );
 
 //! Write exodus-type QA info
 ErrorCode write_qa( const std::vector< std::string >& list );
 
 //!\brief Get tagged entities for which to write tag values
 ErrorCode get_num_sparse_tagged_entities( const TagDesc& tag, size_t& count );
 //!\brief Get tagged entities for which to write tag values
 ErrorCode get_sparse_tagged_entities( const TagDesc& tag, Range& range );
 //!\brief Get entities that will be written to file
 void get_write_entities( Range& range );
 
 //! The size of the data buffer (<code>dataBuffer</code>).
 size_t bufferSize;
 //! A memory buffer to use for all I/O operations.
 char* dataBuffer;
 
 //! Interface pointer passed to constructor
 Interface* iFace;
 //! Cached pointer to writeUtil interface.
 WriteUtilIface* writeUtil;
 
 //! The file handle from the mhdf library
 mhdf_FileHandle filePtr;
 
 //! Map from entity handles to file IDs
 RangeMap< EntityHandle, wid_t > idMap;
 
 //! The list elements to export.
 std::list< ExportSet > exportList;
 //! The list of nodes to export
 ExportSet nodeSet;
 //! The list of sets to export
 ExportSet setSet;
 
 const ExportSet* find( const ExportType& type ) const
 {
 if( type.type == MBVERTEX )
 return &nodeSet;
 else if( type.type == MBENTITYSET )
 return &setSet;
 else
 {
 std::list< ExportSet >::const_iterator it;
 it = std::find( exportList.begin(), exportList.end(), type );
 return it == exportList.end() ? 0 : &*it;
 }
 }
 
 //! Offset into set contents table (zero except for parallel)
 unsigned long setContentsOffset;
 //! Offset into set children table (zero except for parallel)
 unsigned long setChildrenOffset, setParentsOffset;
 //! The largest number of values to write
 //! for any processor (needed to do collective IO).
 long maxNumSetContents, maxNumSetChildren, maxNumSetParents;
 //! Flags idicating if set data should be written.
 //! For the normal (non-parallel) case, these values
 //! will depend only on whether or not there is any
 //! data to be written. For parallel-meshes, opening
 //! the data table is collective so the values must
 //! depend on whether or not any processor has meshsets
 //! to be written.
 bool writeSets, writeSetContents, writeSetChildren, writeSetParents;
 
 //! Struct describing a set for which the contained and linked entity
 //! lists are something other than the local values. Used to store
 //! data for shared sets owned by this process when writing in parallel.
 struct SpecialSetData
 {
 EntityHandle setHandle;
 unsigned setFlags;
 std::vector< wid_t > contentIds;
 std::vector< wid_t > childIds;
 std::vector< wid_t > parentIds;
 };
 struct SpecSetLess
 {
 bool operator()( const SpecialSetData& a, SpecialSetData b ) const
 {
 return a.setHandle < b.setHandle;
 }
 };
 
 //! Array of special/shared sets, in order of handle value.
 std::vector< SpecialSetData > specialSets;
 const SpecialSetData* find_set_data( EntityHandle h ) const
 {
 return const_cast< WriteHDF5* >( this )->find_set_data( h );
 }
 SpecialSetData* find_set_data( EntityHandle h );
 
 //! The list of tags to export
 std::list< TagDesc > tagList;
 
 //! True if doing parallel write
 bool parallelWrite;
 //! True if using collective IO calls for parallel write
 bool collectiveIO;
 //! True if writing dense-formatted tag data
 bool writeTagDense;
 
 //! Property set to pass to H5Dwrite calls.
 //! For serial, should be H5P_DEFAULTS.
 //! For parallel, may request collective IO.
 hid_t writeProp;
 
 //! Utility to log debug output
 DebugOutput dbgOut;
 
 static MPEState topState;
 static MPEState subState;
 
 //! Look for overlapping and/or missing writes
 bool debugTrack;
 
 void print_id_map() const;
 void print_id_map( std::ostream& str, const char* prefix = "" ) const;
 
 /** Helper function for create-file
 *
 * Write tag meta-info and create zero-ed table where
 * tag values will be written.
 *\param num_entities Number of entities for which to write tag data.
 *\param var_len_total For variable-length tags, the total number of values
 * in the data table.
 */
 ErrorCode create_tag( const TagDesc& tag_data, unsigned long num_entities, unsigned long var_len_total );
 
 /**\brief add entities to idMap */
 ErrorCode assign_ids( const Range& entities, wid_t first_id );
 
 /** Get possibly compacted list of IDs for passed entities
 *
 * For the passed range of entities, determine if IDs
 * can be compacted and write IDs to passed list.
 *
 * If the IDs are not compacted, the output list will contain
 * a simple ordered list of IDs.
 *
 * If IDs are compacted, the output list will contain
 * {start,count} pairs.
 *
 * If the ID list is compacted, ranged_list will be 'true'.
 * Otherwise it will be 'false'.
 */
 ErrorCode range_to_blocked_list( const Range& input_range,
 std::vector< wid_t >& output_id_list,
 bool& ranged_list );
 
 /** Get possibly compacted list of IDs for passed entities
 *
 * For the passed range of entities, determine if IDs
 * can be compacted and write IDs to passed list.
 *
 * If the IDs are not compacted, the output list will contain
 * a simple ordered list of IDs.
 *
 * If IDs are compacted, the output list will contain
 * {start,count} pairs.
 *
 * If the ID list is compacted, ranged_list will be 'true'.
 * Otherwise it will be 'false'.
 */
 ErrorCode range_to_blocked_list( const EntityHandle* input_ranges,
 size_t num_input_ranges,
 std::vector< wid_t >& output_id_list,
 bool& ranged_list );
 
 ErrorCode range_to_id_list( const Range& input_range, wid_t* array );
 //! Get IDs for entities
 ErrorCode vector_to_id_list( const std::vector< EntityHandle >& input,
 std::vector< wid_t >& output,
 bool remove_non_written = false );
 //! Get IDs for entities
 ErrorCode vector_to_id_list( const EntityHandle* input, wid_t* output, size_t num_entities );
 //! Get IDs for entities
 ErrorCode vector_to_id_list( const EntityHandle* input,
 size_t input_len,
 wid_t* output,
 size_t& output_len,
 bool remove_non_written );
 
 /** When writing tags containing EntityHandles to file, need to convert tag
 * data from EntityHandles to file IDs. This function does that.
 *
 * If the handle is not valid or does not correspond to an entity that will
 * be written to the file, the file ID is set to zero.
 *\param data The data buffer. As input, an array of EntityHandles. As
 * output an array of file IDS, where the size of each integral
 * file ID is the same as the size of EntityHandle.
 *\param count The number of handles in the buffer.
 *\return true if at least one of the handles is valid and will be written to
 * the file or at least one of the handles is NULL (zero). false
 * otherwise
 */
 bool convert_handle_tag( EntityHandle* data, size_t count ) const;
 bool convert_handle_tag( const EntityHandle* source, EntityHandle* dest, size_t count ) const;
 
 /** Get IDs of adjacent entities.
 *
 * For all entities adjacent to the passed entity, if the
 * adjacent entity is to be exported (ID is not zero), append
 * the ID to the passed list.
 */
 ErrorCode get_adjacencies( EntityHandle entity, std::vector< wid_t >& adj );
 
 //! get sum of lengths of tag values (as number of type) for
 //! variable length tag data.
 ErrorCode get_tag_data_length( const TagDesc& tag_info, const Range& range, unsigned long& result );
 
 private:
 //! Do the actual work of write_file. Separated from write_file
 //! for easier resource cleanup.
 ErrorCode write_file_impl( const char* filename,
 const bool overwrite,
 const FileOptions& opts,
 const EntityHandle* export_sets,
 const int export_set_count,
 const std::vector< std::string >& qa_records,
 const Tag* tag_list,
 int num_tags,
 int user_dimension = 3 );
 
 ErrorCode init();
 
 ErrorCode serial_create_file( const char* filename,
 bool overwrite,
 const std::vector< std::string >& qa_records,
 const Tag* tag_list,
 int num_tags,
 int dimension = 3 );
 
 /** Get all mesh to export from given list of sets.
 *
 * Populate exportSets, nodeSet and setSet with lists of
 * entities to write.
 *
 * \param export_sets The list of meshsets to export
 */
 ErrorCode gather_mesh_info( const std::vector< EntityHandle >& export_sets );
 
 //! Same as gather_mesh_info, except for entire mesh
 ErrorCode gather_all_mesh();
 
 //! Initialize internal data structures from gathered mesh
 ErrorCode initialize_mesh( const Range entities_by_dim[5] );
 
 /** Write out the nodes.
 *
 * Note: Assigns IDs to nodes.
 */
 ErrorCode write_nodes();
 
 /** Write out element connectivity.
 *
 * Write connectivity for passed set of elements.
 *
 * Note: Assigns element IDs.
 * Note: Must do write_nodes first so node IDs get assigned.
 */
 ErrorCode write_elems( ExportSet& elemset );
 
 /** Write out meshsets
 *
 * Write passed set of meshsets, including parent/child relations.
 *
 * Note: Must have written nodes and element connectivity
 * so entities have assigned IDs.
 */
 ErrorCode write_sets( double* times );
 
 /** Write set contents/parents/children lists
 *
 *\param which_data Which set data to write (contents, parents, or children)
 *\param handle HDF5 handle for data set in which to write data
 *\param track Debugging tool
 *\param ranged Will be populated with handles of sets for which
 * contents were written in a range-compacted format.
 * (mhdf_SET_RANGE_BIT). Should be null for parents/children.
 *\param null_stripped Will be populated with handles of sets for which
 * invalid or null handles were stripped from the contents
 * list. This is only done for unordered sets. This argument
 * should be null if writing parents/children because those
 * lists are always ordered.
 *\param set_sizes Will be populated with the length of the data written
 * for those sets for which the handles were added to
 * either \c ranged or \c null_stripped. Values are
 * in handle order.
 */
 ErrorCode write_set_data( const WriteUtilIface::EntityListType which_data,
 const hid_t handle,
 IODebugTrack& track,
 Range* ranged = 0,
 Range* null_stripped = 0,
 std::vector< long >* set_sizes = 0 );
 
 /** Write adjacency info for passed set of elements
 *
 * Note: Must have written element connectivity so elements
 * have IDs assigned.
 */
 ErrorCode write_adjacencies( const ExportSet& export_set );
 
 /** Write tag information and data.
 *
 * Note: Must have already written nodes, elem connectivity and
 * sets so that entities have IDs assigned.
 */
 
 //! Write tag for all entities.
 ErrorCode write_tag( const TagDesc& tag_data, double* times );
 
 //! Get element connectivity
 ErrorCode get_connectivity( Range::const_iterator begin,
 Range::const_iterator end,
 int nodes_per_element,
 wid_t* id_data_out );
 
 //! Get size data for tag
 //!\param tag MOAB tag ID
 //!\param moab_type Output: DataType for tag
 //!\param num_bytes Output: MOAB tag size (bits for bit tags).
 //! MB_VARIABLE_LENGTH for variable-length tags.
 //!\param elem_size Output: Size of of the base data type of the
 //! tag data (e.g. sizeof(double) if
 //! moab_type == MB_TYPE_DOUBLE).
 //! One for bit and opaque tags.
 //!\param array_size Output: The number of valeus of size elem_size
 //! for each tag. Always 1 for opaque data.
 //! Nubmer of bits for bit tags.
 //!\param file_type Output: mhdf type enumeration
 //!\param hdf_type Output: Handle to HDF5 type object. Caller is
 //! responsible for releasing this object
 //! (calling H5Tclose).
 ErrorCode get_tag_size( Tag tag,
 DataType& moab_type,
 int& num_bytes,
 int& elem_size,
 int& file_size,
 mhdf_TagDataType& file_type,
 hid_t& hdf_type );
 
 //! Write ID table for sparse tag
 ErrorCode write_sparse_ids( const TagDesc& tag_data,
 const Range& range,
 hid_t table_handle,
 size_t table_size,
 const char* name = 0 );
 
 //! Write fixed-length tag data in sparse format
 ErrorCode write_sparse_tag( const TagDesc& tag_data,
 const std::string& tag_name,
 DataType tag_data_type,
 hid_t hdf5_data_type,
 int hdf5_type_size );
 
 //! Write end index data_set for a variable-length tag
 ErrorCode write_var_len_indices( const TagDesc& tag_data,
 const Range& range,
 hid_t idx_table,
 size_t table_size,
 int type_size,
 const char* name = 0 );
 
 //! Write tag value data_set for a variable-length tag
 ErrorCode write_var_len_data( const TagDesc& tag_data,
 const Range& range,
 hid_t table,
 size_t table_size,
 bool handle_tag,
 hid_t hdf_type,
 int type_size,
 const char* name = 0 );
 
 //! Write varialbe-length tag data
 ErrorCode write_var_len_tag( const TagDesc& tag_info,
 const std::string& tag_name,
 DataType tag_data_type,
 hid_t hdf5_type,
 int hdf5_type_size );
 
 //! Write dense-formatted tag data
 ErrorCode write_dense_tag( const TagDesc& tag_data,
 const ExportSet& elem_data,
 const std::string& tag_name,
 DataType tag_data_type,
 hid_t hdf5_data_type,
 int hdf5_type_size );
 
 //! Write data for fixed-size tag
 ErrorCode write_tag_values( Tag tag_id,
 hid_t data_table,
 unsigned long data_offset,
 const Range& range,
 DataType tag_data_type,
 hid_t hdf5_data_type,
 int hdf5_type_size,
 unsigned long max_num_ents,
 IODebugTrack& debug_track );
 
 protected:
 enum TimingValues
 {
 TOTAL_TIME = 0,
 GATHER_TIME,
 CREATE_TIME,
 CREATE_NODE_TIME,
 NEGOTIATE_TYPES_TIME,
 CREATE_ELEM_TIME,
 FILEID_EXCHANGE_TIME,
 CREATE_ADJ_TIME,
 CREATE_SET_TIME,
 SHARED_SET_IDS,
 SHARED_SET_CONTENTS,
 SET_OFFSET_TIME,
 CREATE_TAG_TIME,
 COORD_TIME,
 CONN_TIME,
 SET_TIME,
 SET_META,
 SET_CONTENT,
 SET_PARENT,
 SET_CHILD,
 ADJ_TIME,
 TAG_TIME,
 DENSE_TAG_TIME,
 SPARSE_TAG_TIME,
 VARLEN_TAG_TIME,
 NUM_TIMES
 };
 
 virtual void print_times( const double times[NUM_TIMES] ) const;
};
 
} // namespace moab
 
#endif