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