Figure 1: Complete field.
field = ImportHDF5Field(filename, datasetname, lowercorner, thickness, stride, vectorimport)
|
Name |
Type |
Defaults |
Description |
|
filename |
string |
(none) |
file name |
|
datasetname |
string |
(none) |
field name |
|
lowercorner |
integer list |
(none) |
coordinates in grid points of the lower corner |
|
thickness |
integer list |
(none) |
thickness of the slab in grid points |
|
stride |
integer list |
(none) |
number of grid points to move in each dimension to get to the next grid point to be imported |
|
vectorimport |
flag |
false |
import the last dimension of the dataset as a vector |
|
Name |
Type |
Description |
|
field |
field |
imported field or a slab of a field |
The module imports a field or a slab of a field from an HDF5 file. The field (which can be either scalar or vector) must be described on a regular grid, and the file must have an appropriate structure described in the section File Structure.
You will encounter the terms "dataset", "attribute", and "root group" in the following text. For their definitions please consult the documentation of the HDF5 library.
In the case of a scalar field, the number of dimensions of the created OpenDX field is equal to the number of dimensions of the dataset, while in the case of a vector field this number is one less. There is no limit on the number of dimensions imposed by the module. The number is limited only by the capabilities of the HDF5 library and OpenDX.
The argument may be left blank. In that case the default dataset is chosen, which is the only dataset in the root group of the file. Asking for a default dataset while there are several datasets in the root group is considered an error.
There are a few restrictions imposed on this input. Firstly, the number of integers of the list must be equal to the number of dimensions of the dataset (for each dimension one integer is required). Secondly, the positions are counted starting at 0, not at 1. Lastly, the value for a dimension cannot be negative, and must be smaller than the size of this dimension.
For instance, to import a two-dimensional dataset at the very beginning, the value entered should be {0, 0}, not {1, 1} (remember that the grid positions are numbered starting at 0). This is only an example, because it would be enough to leave the input blank to get the same results.
If you leave the input blank, the default value is taken, which is {0, ..., 0} with the number of elements equal to the number of dimensions of the dataset.
There are two restrictions on this input. Firstly, the number of elements in the list must be equal to the number of dimensions of the dataset (for each dimension one integer is required). Secondly, for each dimension the thickness of the dimension should be such that the following inequality holds: size >= ( thickness + lower corner coordinate).
For example, having a two-dimensional dataset of sizes {10, 5} and the lower corner at {4, 2}, the thickness values allowed are from {1, 1} to {6, 3}.
If the input is left blank, the default value is assumed which for each dimension equals (size - lower corner coordinate). This means that from the given lower corner the slab will extend to the very end of the dataset.
Two conditions must be met by the input. Firstly, the number of elements in the list must equal to the number of the dataset's dimensions. Secondly, the values must be positive.
For instance, having the stride {1, 2} for a two-dimensional dataset means that from the slab every grid point in the 1st dimension and every second grid point in the 2nd dimension will be imported.
If the input is left blank, then the default value is assumed, which is {1, ..., 1}.
The file must satisfy the following conditions:
The class of the data type of the dataset must be "H5T_FLOAT" (data types that are of this class are for example "NATIVE_FLOAT" or "NATIVE_DOUBLE") or "H5T_INTEGER" (a data type of this class if for example "NATIVE_INT"). Depending on the data type of the dataset, the created OpenDX field is of the "integer", "float" or "double" type. If the class is "H5T_INTEGER", then the OpenDX type is "integer". As for the "H5T_FLOAT" class, if the size in bytes of the dataset's data type is equal to or smaller than the size in bytes of "float", then the data type of the created OpenDX field is "float", otherwise the data type is "double".
The data of the dataset are not enough to create a field. There is still information needed about the origin and delta (grid size) in each dimension. This information must be provided in the dataset's attributes named "origin" and "delta".
The two attributes share the same format. Each attribute must be a dataset which additionally must be a vector. The vector's data type must be of the class "H5T_FLOAT" with the number of elements at most equal to the number of dimensions of the field. The number of elements can be smaller than the number of dimensions of the field though -- in that case the unspecified values for the remaining dimensions are set to zero.
The "origin" attribute provides Cartesian coordinates of the first grid point (the grid point with coordinates {0, ..., 0} in grid positions). The first element tells the coordinate in the first dimension, the second element of the attribute in the second dimension, etc. The attribute defaults to {0, ..., 0} if it is missing.
Each entry in the "delta" attribute supplies information about the distance in Cartesian coordinates between grid positions in a specific dimension. The first element tells the difference in the first dimension, the second element of the attribute in the second dimension, etc. The attribute defaults to {1, ..., 1} if it is missing.
It is important to note that OpenDX accepts data about origin and delta only in the "float" format, and therefore the values provided by the attributes "origin" and "delta" are always converted to this format.
After the module is installed, this example is available as an OpenDX program in the file:
path_to_OpenDX/samples/moduleTryOut/ImportHDF5FieldUsage.net
In the example the file ImportHDF5FieldUsage.h5 is used which was generated by VORPAL (http://www-beams.colorado.edu/~vorpal). The file contains the description of an electric field with two wave packets.
The h5dump tool reports the following
structure of the file:
> h5dump -H ImportHDF5FieldUsage.h5
HDF5 "ImportHDF5FieldUsage.h5" {
GROUP "/" {
DATASET "YeeElecFieldData" {
DATATYPE H5T_IEEE_F32LE
DATASPACE SIMPLE { ( 200, 100, 3 ) / ( 200, 100, 3 ) }
ATTRIBUTE "time" {
DATATYPE H5T_IEEE_F32LE
DATASPACE SCALAR
}
ATTRIBUTE "origin" {
DATATYPE H5T_IEEE_F32LE
DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
}
ATTRIBUTE "delta" {
DATATYPE H5T_IEEE_F32LE
DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
}
ATTRIBUTE "min_ext" {
DATATYPE H5T_IEEE_F32LE
DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
}
ATTRIBUTE "max_ext" {
DATATYPE H5T_IEEE_F32LE
DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
}
}
}
}
We can see that the file complies with the requirements stated in the section File Structure: there is a dataset defined with the data type of the "H5T_FLOAT" class, and two attributes ("origin" and "delta") of the correct format are present. There are additionally other dataset's attributes defined, but they are of no use for the module and therefore are ignored.
The file contains a dataset of dimensions 200x100x3 which describes a two-dimensional field of dimensions 200x100 grid points. The third dimension of the dataset contains three components of an electric field.
To import a scalar field, the value of the "vectorimport" input must be set to "false". In every case of the four examples below, the input "vectorimport" was set to "false".
The easiest way to use the module is only to supply the file name, and the module will import the whole field (Fig. 1).
If the field's resolution is very fine, it suffices to import every second or every third point of the field, thus reducing memory requirements. For example, importing every third point of the field using stride = {3, 3, 1} (Fig. 2) requires nine times less memory than importing the whole field (Fig. 1).
Often it is necessary to import only a slab of a field. Notice that in Fig. 1 most of the field is "empty". It is useful then to import only a portion as is shown in Fig. 3 and Fig. 4.
Figure 1: Complete field.
Figure 2: Complete field with
only every third position in every dimension taken.
Figure 3: A slab of the field
with lowercorner = {50, 35, 0} and thickness = {100, 30, 3}.
Figure 4: A slab of the field
with lowercorner = {50, 35, 0}, thickness = {100,15,3},
stride = {3, 3, 1}.
After the module is installed, this example is available as an OpenDX program in the file:
path_to_OpenDX/samples/moduleTryOut/ImportHDF5FieldUsage2.net
In the example the file ImportHDF5FieldUsage2.h5 is used which contains data generated only for the purpose of this section.
The h5dump tool reports the following
structure of the file:
>h5dump -H ImportHDF5FieldUsage2.h5
HDF5 "ImportHDF5FieldUsage2.h5" {
GROUP "/" {
DATASET "int" {
DATATYPE H5T_STD_I32LE
DATASPACE SIMPLE { ( 50, 50, 3 ) / ( 50, 50, 3 ) }
}
}
}
We can see that the file complies with the requirements stated in the section File Structure: there is a dataset defined with the data type of the "H5T_INTEGER" class. The attributes "origin" and "delta" are not present and they default to {0, 0, 0} and {1, 1, 1}, respectively.
The file contains a dataset of dimensions 50x50x3 which describes a two-dimensional vector field of dimensions 50x50 grid points with three-dimensional vectors. The elements along the third dimension of the dataset are components of the vectors.
To import a vector field, the value of the "vectorimport" input must be set to "true". In every case of the three examples below, the input "vectorimport" was set to "true".
The easiest way to use the module is to supply the file name only, and the module will import the whole field (Fig. 5).
The same as in the case of scalar fields, you can choose to import a slab of a field, and if needed, at lower resolution. For example, a slab with every second point of the field taken in both dimensions can be imported with lowercorner = {0, 25, 0}, thickness = {25, 25, 3} and stride = {2, 2, 1} (Fig. 6).
One can take a slab of vector components. For example, one can create a field of two-dimensional vectors from the field of three-dimensional vectors by discarding the third component of the vector with thickness = {50, 50, 2} (Fig. 7).
Figure 5: Complete field.
Figure 6: A slab of the field,
lowercorner = {0, 25, 0}, thickness = {25, 25, 3} and stride
= {2, 2, 1}.
Figure 7: A field of
two-dimensional vectors, thickness = {50, 50, 2}.
h5dump utility to
examine the structure of an HDF5 file. To get information on
the field which the module produced, use the Print module of
OpenDX. Please consult the OpenDX documentation to learn
about the Print module.
You might want to examine debug messages generated by the module. The module is sensitive to the "d" flag which you can set with the Trace module of OpenDX. Please consult the OpenDX documentation to learn about the Trace module. You need to use the Trace module is the script mode of OpenDX. To start OpenDX in the script mode with the dxhdf5 modules, execute:
dxhdf5 -script -cache offThen type in this example:
dx> Trace("d", 1);
dx> output = ImportHDF5Field("yourFile.h5");
Import, Slab, ImportHDF5Species
ImportHDF5FieldUsage.net
The example is located in:
path_to_OpenDX/samples/moduleTryOut/
Please make sure that you run the program with the above directory as the working directory, for there is an HDF5 file used by the example.
Last modified: 2004/11/19 08:06:26