2.2.12.  DEFINE_RW_HDF_FILE

2.2.12.1. Description

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.

2.2.12.2. Usage

DEFINE_RW_HDF_FILE (name, filename)

Argument Type

Description

symbol name

UDF name.

char *filename

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.

2.2.12.3. 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:

Datasets

can be thought of as arrays that store data. Typically the data are stored as real values.

Groups

are analogous to directories on a file system. A group can contain other groups, datasets, or a combination of both.

Attributes

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.

Link

is an umbrella term that may refer to groups or datasets, but not to attributes.

Path

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
    Write_Complete_User_Dataset
    #include "hdfio.h"
    void Write_Complete_User_Dataset (filename,   path,   ptr,   nelems); 
    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.

    Write_Partial_User_Dataset
    #include "hdfio.h"
    void Write_Partial_User_Dataset (filename,   path,   ptr,   nelems,   datasetsize,   datasetoffset); 
    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.

    Write_User_Attributes
    #include "hdfio.h"
    void Write_User_Attributes (filename,   path,   name,   mpttype,   value,   ...,    NULL ); 
    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.

    Read_Complete_User_Dataset
    #include "hdfio.h"
    void Read_Complete_User_Dataset (filename,   path,   ptr,   nelems); 
    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.

    Read_Partial_User_Dataset
    #include "hdfio.h"
    void Read_Partial_User_Dataset (filename,   path,   ptr,   nelems,   datasetoffset); 
    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.

    Read_User_Attributes
    #include "hdfio.h"
    void Read_User_Attributes (filename,   path,   name,   mpttype,   ptr,   ...,    NULL ); 
    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.

    Get_Next_User_Link_Name
    #include "hdfio.h"
    void Get_Next_User_Link_Name (filename,   path,   prev_name,   next_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.

    2.2.12.4. Examples

    /*
     * 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);
      }
    }
    

    2.2.12.5. Hooking a Read/Write HDF Case or Data File UDF to ANSYS Fluent

    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.


    Release 18.2 - © ANSYS, Inc. All rights reserved.