DEFINE_RW_HDF_FILE is a general-purpose
macro that you can use to read or write customized information from
or to HDF-formatted case or data files. You can read and write custom
datasets of real values as well as attributes of various types.
DEFINE_RW_HDF_FILE (name, filename)
|
Argument Type |
Description |
|
|
UDF name. |
|
|
Name of the file you are reading or writing. |
Function returns
void
There are two arguments to DEFINE_RW_HDF_FILE: name and filename. You supply name, the name of the UDF. filename is passed from the solver to the UDF. Because
of the structured nature of the HDF file format, a series of helper
functions are made available for performing the low-level read/write
operations. These are detailed in Helper Functions.
HDF-format files use a compressed binary format. In order to make reading and writing these files easier, a series of helper functions are made available for use in your UDF. The following terminology is used in the descriptions of the helper functions:
can be thought of as arrays that store data. Typically the data are stored as real values.
are analogous to directories on a file system. A group can contain other groups, datasets, or a combination of both.
are name/value pairs that assigned to datasets or groups and are generally used for storing metadata. For example, a dataset may have an attribute for the number of elements in the dataset.
is an umbrella term that may refer to groups or datasets, but not to attributes.
is a string representation of a link in the HDF file.
The path of the root group of the file is denoted by /. Any link in the file can be identified by specifying the absolute
path to the link (for example, /path/to/link).
The following functions are made available by including hdfio.h in your UDF source file and are used to perform
HDF-format reading and writing. Note that all functions prepend /user to the provided path parameter.
Thus, all user-defined data written or accessed by these functions
is stored under the group /user.
| Write_Complete_User_Dataset |
| Write_Partial_User_Dataset |
| Write_User_Attributes |
| Read_Complete_User_Dataset |
| Read_Partial_User_Dataset |
| Read_User_Attributes |
| Get_Next_User_Link_Name |
#include "hdfio.h"
void Write_Complete_User_Dataset
();
char* filename
;
char* path
;
real* ptr
;
size_t nelems
;filename
Name of the HDF file to which data is to be written.
In a DEFINE_RW_HDF_FILE macro, this is generally
passed in by Fluent.
path
Path in the file at which the dataset will be written.
ptr
Pointer to the data that will be written. Note that the data type must be real.
nelems
Number of data elements to be written from a node.
This is the basic function for writing data to an HDF file.
The function assumes that data is only in nodes and is already arranged
sequentially according to node rank. Therefore, data in node0 is written
first followed by data in node1, and so on. A new dataset is created
at path and the size of the created dataset
is the sum of nelems across all nodes.
#include "hdfio.h"
void Write_Partial_User_Dataset
();
char* filename
;
char* path
;
real* ptr
;
size_t nelems
;
size_t datasetsize
;
size_t datasetoffset
;filename
Name of the HDF file to which data is to be written.
In a DEFINE_RW_HDF_FILE macro, this is generally
passed in by Fluent.
path
Path in the file at which the dataset will be written.
ptr
Pointer to the data that will be written. Note that the data type must be real.
nelems
Number of data elements to be written from a node.
datasetsize
Total size of the dataset into which the data will
be written. This must be larger than the sum of nelems across all nodes.
datasetoffset
The offset within the dataset at which writing will start.
This function can be used when it is desirable to write data to the same dataset through multiple calls. The dataset will be created the first time and data will be written into the dataset in subsequent calls from each compute node.
#include "hdfio.h"
void Write_User_Attributes
();
char* filename
;
char* path
;
char* name
;
MPT_Datatype mpttype
;
type
value
;
...
;
NULL
;filename
Name of the HDF file.
path
Path to the link in the file for which the attributes will be written.
name
Name of the attribute.
mpttype
The datatype of the attribute value. This can be one of MPT_SHORT, MPT_INT, MPT_LONG, MPT_LONG_LONG, MPT_SIZE_T, MPT_DOUBLE
value
Value of the attribute. The type of the attribute should be short, int, long, long long, size_t, or double according to the value of mpttype
...
Multiple attributes can be specified by including
additional triplets of name, mpttype, and value.
NULL
the list of parameters must be terminated with NULL.
#include "hdfio.h"
void Read_Complete_User_Dataset
();
char* filename
;
char* path
;
real* ptr
;
size_t nelems
;filename
Name of the HDF file from which data is to be read.
In a DEFINE_RW_HDF_FILE macro, this is generally
passed in by Fluent.
path
Path in the file from which the dataset will be read.
ptr
Pointer to the location where the read data will be stored. Note that the data type is assumed to be real.
nelems
Number of data elements to be read into a node.
This is the basic function for writing data from an HDF file.
As in the Write_Complete_User_Data function,
the data is read sequentially according to node rank. Therefore, data
that is read first fills node0 followed by node1, and so on.
#include "hdfio.h"
void Read_Partial_User_Dataset
();
char* filename
;
char* path
;
real* ptr
;
size_t nelems
;
size_t datasetoffset
;filename
Name of the HDF file from which data is to be read.
In a DEFINE_RW_HDF_FILE macro, this is generally
passed in by Fluent.
path
Path in the file from which the dataset will be read.
ptr
Pointer to the location where the read data will be stored. Note that the data type is assumed to be real.
nelems
Number of data elements to be read into a node.
datasetoffset
The offset within the dataset at which reading will start.
This function can be used to read a portion of a dataset from an HDF file.
#include "hdfio.h"
void Read_User_Attributes
();
char* filename
;
char* path
;
char* name
;
MPT_Datatype mpttype
;
type* ptr
;
...
;
NULL
;filename
Name of the HDF file.
path
Path to the link in the file for which the attributes will be read.
name
Name of the attribute to read.
mpttype
The datatype of the attribute value. This can be one of MPT_SHORT, MPT_INT, MPT_LONG, MPT_LONG_LONG, MPT_SIZE_T, MPT_DOUBLE
ptr
Pointer to the location in which to store the attribute
value. The pointer type should be short, int, long, long long, size_t, or double according to the value of mpttype
...
Multiple attributes can be read by including additional
triplets of name, mpttype, and ptr.
NULL
the list of parameters must be terminated with NULL.
#include "hdfio.h"
void Get_Next_User_Link_Name
();
char* filename
;
char* path
;
char* prev_name
;
char* next_name
;filename
Name of the HDF file.
path
Path to a group in the file under which the links reside.
prev_name
Name of a link under the group at path. The name of the next link after prev_name (based on order of creation in the document) will be returned in next_name. A value of NULL can be used to get the first
link within a group.
next_name
The name of the link following prev_name is returned in next_name. If prev_name is the last link in the group, an empty string will be returned.
This function is typically used to iterate over the links under
a group. The iteration is started by passing NULL as the value for prev_name. Iteration continues by using the value returned
in next_name as the value of prev_name in the next iteration. The iteration is complete when an empty string
is returned in next_name.
/*
* UDF that writes a complete dataset to an HDF file, sets an attribute for the dataset
* and then reads it back. These demonstrate the use of the following helper functions:
* Write_Complete_User_Dataset
* Write_User_Attributes
* Read_Complete_User_Dataset
* Read_User_Attributes
*/
#include "udf.h"
#include "hdfio.h"
#define ELEM_COUNT 50
DEFINE_RW_HDF_FILE(write_complete_dataset, filename)
{
size_t i, nelems = ELEM_COUNT;
real* ptr = NULL;
char* path = "/test/complete_data";
/* Assign equal number of elements in all the nodes
* and fill with some values. Write a dataset with
* all the values at the end. Also write an attribute
* with total number of elements.
*/
#if RP_NODE
ptr = (real*)CX_Malloc(sizeof(real) * nelems);
for (i = 0; i < nelems; ++i) {
ptr[i] = (real)((myid + 1) * i);
}
#endif
Write_Complete_User_Dataset(filename, path, ptr, nelems);
Write_User_Attributes(filename, path,
"totalElems", MPT_SIZE_T, (size_t)(nelems * compute_node_count),
NULL
);
if (NNULLP(ptr)) {
CX_Free(ptr);
}
}
DEFINE_RW_HDF_FILE(read_complete_dataset, filename)
{
size_t nelems = 0, totalElems = 0;
real* ptr = NULL;
char* path = "/test/complete_data";
/* Read complete dataset and check the elements. */
Read_User_Attributes(filename, path,
"totalElems", MPT_SIZE_T, &totalElems,
NULL
);
#if RP_NODE
nelems = totalElems / compute_node_count;
ptr = (real*)CX_Malloc(sizeof(real) * nelems);
#endif
Read_Complete_User_Dataset(filename, path, ptr, nelems);
if (NNULLP(ptr)) {
CX_Free(ptr);
}
}
After the UDF that you have defined using DEFINE_RW_HDF_FILE is interpreted (Interpreting UDFs)
or compiled (Compiling UDFs), the name
of the argument that you supplied as the first DEFINE macro argument (for example, write_complete_dataset) will become visible and selectable via the User-Defined
Function Hooks dialog box in ANSYS Fluent. Note that you can
hook multiple read/write functions to your model. See Hooking DEFINE_RW_FILE and DEFINE_RW_HDF_FILE UDFs for details.