1 #ifndef MHDF_PUBLIC_H 2 #define MHDF_PUBLIC_H 3 4 #include <H5Tpublic.h> 5 6 #ifdef __cplusplus 7 extern "C" { 8 #endif 9 10 11 #define MHDF_MESSAGE_BUFFER_LEN 160 12 13 /** \brief Struct used to return error status. */ 14 typedef struct struct_mhdf_Status { char message[MHDF_MESSAGE_BUFFER_LEN]; } mhdf_Status; 15 /* another name/alias/typedef for mhdf_Status*/ 16 typedef mhdf_Status MHDF_Status; 17 18 /** \brief Return 1 if passed status object indicates an error. Zero otherwise. */ 19 int 20 mhdf_isError( mhdf_Status const* ); 21 22 /** \brief Get the error message given a status object. */ 23 const char* 24 mhdf_message( mhdf_Status const* ); 25 26 /*@}*/ 27 28 /** 29 *\defgroup mhdf_type Common element type names. 30 */ 31 /*@{*/ 32 33 /** \brief Name to use for edge element */ 34 #define mhdf_EDGE_TYPE_NAME "Edge" 35 /** \brief Name to use for triangle element */ 36 #define mhdf_TRI_TYPE_NAME "Tri" 37 /** \brief Name to use for quadrilateral element */ 38 #define mhdf_QUAD_TYPE_NAME "Quad" 39 /** \brief Name to use for general polygon element */ 40 #define mhdf_POLYGON_TYPE_NAME "Polygon" 41 /** \brief Name to use for tetrahedral element */ 42 #define mhdf_TET_TYPE_NAME "Tet" 43 /** \brief Name to use for quad-based pyramid element */ 44 #define mhdf_PYRAMID_TYPE_NAME "Pyramid" 45 /** \brief Name to use for triangular prism element */ 46 #define mhdf_PRISM_TYPE_NAME "Prism" 47 /** \brief Name to use for knife element */ 48 #define mdhf_KNIFE_TYPE_NAME "Knife" 49 /** \brief Name to use for quad-sided hexahedral element */ 50 #define mdhf_HEX_TYPE_NAME "Hex" 51 /** \brief Name to use for general polyhedron specified as a arbitrary-length list of faces */ 52 #define mhdf_POLYHEDRON_TYPE_NAME "Polyhedron" 53 /** \brief Name to use for hexagonal-based pyramid */ 54 #define mhdf_SEPTAHEDRON_TYPE_NAME "Septahedron" 55 56 /*@}*/ 57 58 /** \brief Enum for tag data type class 59 * 60 * Enumerates known types for tag data 61 */ 62 typedef enum mhdf_TagDataType { 63 mhdf_OPAQUE = 0, /**< Opaque/unknown type */ 64 mhdf_INTEGER, /**< Integer type */ 65 mhdf_FLOAT, /**< Floating point value */ 66 mhdf_BITFIELD, /**< Bit field */ 67 mhdf_BOOLEAN, /**< Boolean values stored as one byte each */ 68 mhdf_ENTITY_ID /**< Global ID referencing another entity in file */ 69 } MHDF_TagDataType; 70 71 /**\brief Type used when creating index tables 72 * 73 * The data type used by mhdf_create* functions that create tables 74 * if indices (e.g. mhdf_createSetMeta, mhdf_createVarLenTag, etc.). 75 */ 76 typedef long mhdf_index_t; 77 78 79 /*@}*/ 80 81 /** 82 *\defgroup mhdf_file File operations 83 */ 84 /*@{*/ 85 86 /** \brief Opaque handle to an open file */ 87 typedef void* mhdf_FileHandle; 88 /* another name/alias/typedef for mhdf_FileHandle*/ 89 typedef mhdf_FileHandle MHDF_FileHandle; 90 91 92 /* Top level file operations */ 93 94 /** \brief Create a new file. 95 * 96 * Create a new HDF mesh file. This handle must be closed with 97 * <code>mhdf_closeFile</code> to avoid resource loss. 98 * 99 * \param filename The path and name of the file to create 100 * \param overwrite If zero, will fail if the specified file 101 * already exists. If non-zero, will overwrite 102 * an existing file. 103 * \param elem_type_list The list of element types that will be stored 104 * in the file. If the element name exits as a pre- 105 * defined constant (\ref mhdf_type), that constant 106 * should be used. If a constant does not exist for 107 * the type, a similar naming pattern should be used 108 * (accepted name for type, first character uppercase, 109 * subsequent characters lowercase.) The element type 110 * index passed to \ref mhdf_addElement is then an 111 * index into this list. The array may contain 112 * null entries to allow the caller some control over 113 * the assigned indices without creating dummy types 114 * which may confuse readers. 115 * \param elem_type_list_len The length of <code>elem_type_list</code>. 116 * \param id_type Type to use when creating datasets containing file IDs 117 * \param status Passed back status of API call. 118 * \return An opaque handle to the file. 119 */ 120 mhdf_FileHandle 121 mhdf_createFile( const char* filename, 122 int overwrite, 123 const char** elem_type_list, 124 size_t elem_type_list_len, 125 hid_t id_type, 126 mhdf_Status* status ); 127 128 /** \brief Open an existing file. 129 * 130 * Open an existing HDF mesh file. This handle must be closed with 131 * <code>mhdf_closeFile</code> to avoid resource loss. 132 * 133 * \param filename The path and name of the file to open 134 * \param writable If non-zero, open read-write. Otherwise read-only. 135 * \param status Passed back status of API call. 136 * \param max_id Used to pass back the maximum global ID used in the 137 * file. Provided as an indication to the caller of the 138 * size of the mesh. This parameter is optional. NULL 139 * may be passed. 140 * \param id_type Type to use when creating datasets containing file IDs 141 * \return An opaque handle to the file. 142 */ 143 mhdf_FileHandle 144 mhdf_openFile( const char* filename, 145 int writable, 146 unsigned long* max_id, 147 hid_t id_type, 148 mhdf_Status* status ); 149 150 /** \brief Open an existing file with options. 151 * 152 * Open an existing HDF mesh file. This handle must be closed with 153 * <code>mhdf_closeFile</code> to avoid resource loss. This function 154 * allows the calling application to specify the HDF5 access property 155 * list that is passed to the HDF5 H5Fopen API. If this is passed as 156 * H5P_DEFAULT, the behavior is the same as \ref mhdf_openFile . 157 * This argument is typically used to specify a parallel context for 158 * for writing the file in parallel. 159 * 160 * \param filename The path and name of the file to open 161 * \param writable If non-zero, open read-write. Otherwise read-only. 162 * \param status Passed back status of API call. 163 * \param max_id Used to pass back the maximum global ID used in the 164 * file. Provided as an indication to the caller of the 165 * size of the mesh. This parameter is optional. NULL 166 * may be passed. 167 * \param options The HDF5 access property list to use when opening 168 * the file. See the HDF5 documentation for H5Fopen. 169 * \param id_type Type to use when creating datasets containing file IDs 170 * \return An opaque handle to the file. 171 */ 172 mhdf_FileHandle 173 mhdf_openFileWithOpt( const char* filename, 174 int writable, 175 unsigned long* max_id, 176 hid_t id_type, 177 hid_t options, 178 mhdf_Status* status ); 179 180 /**\brief Get number of open HDF5 objects from file */ 181 int 182 mhdf_countOpenHandles( mhdf_FileHandle h ); 183 184 /** Data common to sets, nodes, and each element type */ 185 typedef struct mhdf_EntDesc { 186 long start_id; /**< First file ID for table of data */ 187 long count; /**< Number of entities in table */ 188 int vals_per_ent; /**< Connectivity length for elems, dimension for verts, unused for sets, -1 for variable length poly* data */ 189 int* dense_tag_indices; /**< Indices into mhdf_FileDesc::tags for each tag for which dense data is present for these entities */ 190 int num_dense_tags; /**< Length of dense_tag_indices */ 191 } MHDF_EntDesc; 192 /** Struct describing a tag */ 193 typedef struct mhdf_TagDesc { 194 const char* name; /**< Tag name */ 195 enum mhdf_TagDataType type; /**< Data type */ 196 int size; /**< Tag size (num of data type) */ 197 int bytes; /**< Tag size (number of bytes) */ 198 int storage; /**< MOAB tag type (dense or sparse) */ 199 int have_sparse; /**< Have sparse id/data pairs in file */ 200 void* default_value; /**< Default value, NULL if none. */ 201 int default_value_size; 202 void* global_value; /**< Global value, NULL if none. */ 203 int global_value_size; 204 int* dense_elem_indices; /**< Array of indices indicating element types for which dense 205 data is stored. -2 for sets, -1 for nodes. */ 206 int num_dense_indices; 207 } MHDF_TagDesc; 208 typedef struct mhdf_ElemDesc { 209 const char* handle; /**< String table identifier */ 210 const char* type; /**< String type designator */ 211 int have_adj; /**< File contains adjacency data for this element group */ 212 struct mhdf_EntDesc desc; 213 } MHDF_ElemDesc; 214 typedef struct mhdf_FileDesc { 215 struct mhdf_EntDesc nodes; 216 struct mhdf_EntDesc sets; 217 int have_set_contents; 218 int have_set_children; 219 int have_set_parents; 220 struct mhdf_ElemDesc* elems; /**< Array of element table descriptions */ 221 int num_elem_desc; 222 struct mhdf_TagDesc* tags; /**< Array of tag descriptions */ 223 int num_tag_desc; 224 int * numEntSets ; /* used to be [4] */ 225 /*int num_parts; will look specifically for number of sets with PARALLEL_PARTITION tags*/ 226 /* int num_mats; will look specifically for number of sets with MATERIAL_SET tags*/ 227 /*int num_neumann; will look specifically for number of sets with NEUMANN_SET tags*/ 228 /*int num_diri; will look specifically for number of sets with DIRICHLET_SET tags*/ 229 int **defTagsEntSets; /* we may need to add geometry_dimension tags */ 230 int **defTagsVals ; 231 size_t total_size; /**< Size of memory block containing all struct data */ 232 unsigned char* offset; /**< Unused, may be used by application */ 233 } MHDF_FileDesc; 234 235 /** \brief Get summary of data tables contained within file. 236 * 237 * Returned struct, including all pointed-to data, is allocated in a 238 * single contiguous block of memory with a size equal to 'total_size'. 239 * Caller is responsible for freeing the returned struct FileDesc pointer 240 * (and *only* that pointer, not pointers nexted within the struct!). 241 * Caller may copy (e.g. MPI_BCast) entire struct as one contiguous block, 242 * assuming all nested pointers in the copy are updated to the correct 243 * relative offset from the beginning of the struct. 244 */ 245 MHDF_FileDesc * 246 mhdf_getFileSummary( mhdf_FileHandle file_handle, 247 hid_t file_id_type, 248 mhdf_Status* status, int extraSetInfo); 249 250 /**\brief Fix nested pointers for copied/moved FileDesc struct 251 * 252 * This is a utility method to facility copying/moving/communicating 253 * struct FileDesc instances. The structure and all data it references 254 * are allocated in a single contiguous block of memory of size 255 * FileDesc::total_size. As such, the struct can be copied with a single 256 * memcpy, packed into a single network packet, communicated with a single 257 * MPI call, etc. However, the pointers contained within the struct will 258 * not be valid in the copied instance (they will still point into the 259 * original instance.) Given a pointer to the copied struct and the address 260 * of the original struct, this function will updated all contained pointers. 261 */ 262 void 263 mhdf_fixFileDesc( struct mhdf_FileDesc* copy_ptr, const struct mhdf_FileDesc* orig_addr ); 264 265 /** \brief Close the file 266 * \param handle The file to close. 267 * \param status Passed back status of API call. 268 */ 269 void 270 mhdf_closeFile( mhdf_FileHandle handle, 271 mhdf_Status* status ); 272 273 /**\brief Check for open handles in file 274 **/ 275 276 #ifdef __cplusplus 277 } /* extern "C" */ 278 #endif 279 280 281 #endif /* MHDF_PUBLIC_H*/ 282