- Created by Mike McGreevy, last modified by Barbara Jones on Aug 28, 2019
Jump to ...
Switch language ...
Compare two HDF5 files and report the differences
h5diff [OPTIONS] file1 file2 [object1 [object2 ] ]
ph5diff [OPTIONS] file1 file2 [object1 [object2 ] ]
ph5diffare command line tools that compare two HDF5 files, file1 and file2, and report the differences between them.
h5diffis for serial use while
ph5diffis for use in parallel environments.
ph5diff will compare two objects within these files. If only one object, object1, is specified,
h5diff will compare object1 in file1 with object1 in file2. If two objects, object1 and object2, are specified,
h5diff will compare object1 in file1 with object2 in file2.
object1 and object2 can be groups, datasets, named datatypes, or symbolic links (soft links or external links) and must be expressed as absolute paths from the respective file’s root group.
- If these objects are groups,
h5difffirst compares the names of member objects (the relative path from the specified group) and generates a report of objects that appear in only one group or in both groups. Common objects are then compared recursively.
- If these objects are datasets, array rank and dimensions, datatypes, and data values are compared.
.If these objects are named datatypes, the comparison is based on the return value of H5T_EQUAL
- If these objects are symbolic links, the paths to the target objects are compared.
--follow-symlinksoverrides the default behavior when symbolic links are compared.)
ph5diff have the following output modes:
|Default||Prints the number of differences found and where they occurred. |
If no differences are found,
This normal behavior is achieved by using none of the following output mode options.
|Report mode||Prints the above plus the differences.|
|Verbose mode||Prints all of the above plus a list of objects and warnings.|
|Verbose mode |
|Prints a selectable level of detail. |
For details, see “Options and Parameters” below.
|Quiet mode||Prints no output. |
h5diff offers several mutually-exclusive criteria for analyzing differences in raw data:
- Strict equality — The default comparison mode is to check for strict equality of data values.
- Fixed difference — With the
h5diffconsiders two data values to be equal if the absolute value of the difference is less than the specified
- Relative difference — With the
h5diffconsiders two data values to be equal if the absolute value of the relative difference is less than the value specified in
- System epsilon — With the
h5diffconsiders two data values to be equal if the absolute value of the difference is less than the computing platform’s system epsilon (or a pre-determined value if no system epsilon is defined).
h5diff and NaNs:
h5diff detects when a value in a dataset is a NaN (a "not a number" value), but does not differentiate among various types of NaNs. Thus, when one NaN is compared with another NaN,
h5diff treats them as equal; when a NaN is compared with a valid number,
h5diff treats them as not equal.
Note that NaN detection is computationally expensive and slows
h5diff performance dramatically. If you do not have NaNs in your files, or do not care about NaNs, use the
-N option to turn off NaN detection. Similarly, if
h5diff -N produces unexpected differences, running
-N should reveal whether any of the differences are associated with NaN values.
With the following exception,
ph5diffbehave identically. With
ph5diff, the comparison of objects is shared across multiple processors, with the comparison of each pair of objects assigned to a single processor. This work assignment means that
ph5diffwill not speed up the comparison of any given pair of datasets, as the comparison of the pair will still occur on a single processor.
Options and Parameters:
|Print help message.|
|Print version number and exit.|
|Report mode — Print the differences.|
|Verbose mode — Print difference information, list of objects, warnings, etc.|
Verbose mode with levels— Print difference information, list of objects, warnings, etc., with the level of detail determined by value of
|Quiet mode — Do not print output.|
|Follow symbolic links (soft links and external links) and compare the links’ target objects.|
If symbolic link(s) with the same name exist in the files being compared, then determine whether the target of each link is an existing object (dataset, group, or named datatype) or the link is a dangling link (a soft or external link pointing to a target object that does not exist).
If any symbolic link specified in the call to
|Must be used with the |
Check for symbolic links (soft links or external links) that do not resolve to an existing object (dataset, group, or named datatype). If a dangling link is found, this situation is treated as an error and
|Disables NaN detection; see “|
|Print difference up to count differences, then stop. count must be a positive integer.|
|Print only differences that are greater than the limit delta. delta must be a positive number. The comparison criterion is whether the absolute value of the difference of two corresponding values is greater than delta (i.e., |
Do not use
|Print only differences that are greater than a relative error. relative must be a positive number. The comparison criterion is whether the absolute value of the ratio of the difference between two values and one of those values is greater than relative (that is, |
Do not use
|Return a difference if and only if the difference between two data values exceeds the system value for epsilon. That is, if |
If no system epsilon is defined,
Do not use
|Exclude the specified path to an object when comparing files or groups. If a group is excluded, all member objects will also be excluded.|
The specified path is excluded wherever it occurs. This flexibility enables the same option to exclude either objects that exist only in one file or common objects that are known to differ.
When comparing files, path is the absolute path to the excluded object; when comparing groups, path is similar to the relative path from the group to the excluded object. This path can be taken from the first section of the output of the
If there are multiple paths to an object, only the specified path(s) will be excluded; the comparison will include any path not explicitly excluded.
This option can be used repeatedly to exclude multiple paths.
|file1 file2||The HDF5 files to be compared.|
|object1 object2||Specific object(s) within the files to be compared, expressed as absolute paths from the respective file’s root group.|
|Enable the error stack|
Exit Status for h5diff:
|0||No differences were found.|
|1||Some differences were found.|
|>1||An error occurred.|
Exit Status for ph5diff:
Because of the limitations in the MPI standard, the return value is not defined.
file1with the object
h5diff file1 file2 /a/b /a/c
Compare the object
file1 with the same object in
h5diff file1 file2 /a/b
Compare all objects in both files:
h5diff file1 file2
Comparisons executed with the verbose options can produce object and attribute status reports as illustrated below:
h5diff -v file1 file2
... file1 file2 --------------------------------------- x x / x /dset x /g2 x x /g3 ...The sample output above shows that the dataset
dsetexists only in
file2, the group
/g2exists only in
file1, and the group
/g3and the root group exist in both files. Only objects that exist in both files will be compared. More verbose levels can produce more information:
h5diff -v2 file1 file2
... group : ‹/g2› and ‹/g2› 0 differences found obj1 obj2 -------------------------------------- x x float2 x float3 x x integer1 Attributes status: 2 common, 1 only in obj1, 0 only in obj2 ...In this illustration, both objects,
obj2, have attributes named
integer1, while only
obj1has an attribute named
float3. Only attributes that exist on both objects will be compared.
The “Attributes status:” line reports that there are two attributes common to both objects: one attribute attached only to
obj1, and zero attributes attached only to
To see the “Attributes status:” line independently of the immediately-preceding table, use the -v1 option.
h5diff -v1 file1 file2
... group : ‹/g2› and ‹/g2› 0 differences found Attributes status: 2 common, 1 only in obj1, 0 only in obj2 ...
|1.8.2 and 1.6.8||Return value on failure changed in this release.|
|1.8.4 and 1.6.10|
--- Last Modified: August 28, 2019 | 09:02 AM