Expand all Collapse all

Jump to ...
Summary
Description
Example
Switch language ...
C
C++
FORTRAN
JAVA

h5diff

Compare two HDF5 files and report the differences

Syntax:

h5diff [OPTIONS] file1 file2 [object1 [object2 ] ]

ph5diff [OPTIONS] file1 file2 [object1 [object2 ] ]

Description:

h5diff and ph5diff are command line tools that compare two HDF5 files, file1 and file2, and report the differences between them. h5diff is for serial use while ph5diff is for use in parallel environments.

Optionally, h5diff and 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, h5diff first 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.
(The option --follow-symlinks overrides the default behavior when symbolic links are compared.)

Output modes:
h5diff and ph5diff have the following output modes:

Default		Prints the number of differences found and where they occurred. If no differences are found, `h5diff` and `ph5diff` produce no output. This normal behavior is achieved by using none of the following output mode options.
Report mode	`-r`	Prints the above plus the differences.
Verbose mode	`-v`	Prints all of the above plus a list of objects and warnings.
Verbose mode with levels	`-vn`	Prints a selectable level of detail. For details, see “Options and Parameters” below.
Quiet mode	`-q`	Prints no output. The `h5diff` exit code will be the only feedback provided.

Difference controls:
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 '-d delta' or '--delta=delta' option, h5diff considers two data values to be equal if the absolute value of the difference is less than the specified delta.
Relative difference — With the '-p relative' or '--relative=relative' option, h5diff considers two data values to be equal if the absolute value of the relative difference is less than the value specified in relative.
System epsilon — With the '--use-system-epsilon' option, h5diff considers 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 h5diff without -N should reveal whether any of the differences are associated with NaN values.

Difference between h5diff and ph5diff:
With the following exception, h5diff and ph5diff behave 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 ph5diff will 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:

-h or --help Print help message.

-V or --version Print version number and exit.

-r or --report Report mode — Print the differences.

-v or --verbose Verbose mode — Print difference information, list of objects, warnings, etc.

-vn or
--verbose=n

Verbose mode with levels— Print difference information, list of objects, warnings, etc., with the level of detail determined by value of n:

`0`	Basic difference information, list of objects, and warnings. Identical to `-v, --verbose`.
`1`	All level `0` information plus a one-line attribute status summary.
`2`	All level `1` information plus an extended attribute status report.

-q or --quiet

Quiet mode — Do not print output.

--follow-symlinks

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 both symbolic links are dangling links, they are treated as being the same; by default, h5diff returns an exit code of 0. If, however, --no-dangling-links is used with --follow-symlinks, this situation is treated as an error and h5diff returns an exit code of 2.
If only one of the two links is a dangling link, they are treated as being different and h5diff returns an exit code of 1. If, however, --no-dangling-links is used with --follow-symlinks, this situation is treated as an error and h5diff returns an exit code of 2.
If both symbolic links point to existing objects, h5diff compares the two objects.

If any symbolic link specified in the call to h5diff does not exist, h5diff treats it as an error and returns an exit code of 2.

--no-dangling-links

Must be used with the --follow-symlinks option; otherwise, h5diff shows error message and returns an exit code of 2.

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 h5diff returns an exit code of 2.

-N or --nan Disables NaN detection; see “h5diff and NaNs” above.

-n count or
--count=count

Print difference up to count differences, then stop. count must be a positive integer.

-d delta or
--delta=delta

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., |a–b| > delta, where a is a value in file1 and b is a value in file2).

Do not use -d, --delta with -p, --relative or --use-system-epsilon.

-p relative or
--relative=relative

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, |(a–b)/b)| > relative where a is a value in file1 and b is the corresponding value in file2).

Do not use -p, --relative with -d, --delta or --use-system-epsilon.

--use-system-epsilon

Return a difference if and only if the difference between two data values exceeds the system value for epsilon. That is, if a is a data value in one dataset, b is the corresponding data value in the dataset with which the first dataset is being compared, and epsilon is the system epsilon, return a difference if and only if |a-b| > epsilon.

If no system epsilon is defined, h5diff will use the following values, which approximate common system epsilon values:

FLT_EPSILON=1.19209E-07 for floating-point datatypes
DBL_EPSILON=2.22045E-16 for double precision datatypes

Do not use --use-system-epsilon with -d, --delta or -p, --relative.

--exclude-path "path"

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 --verbose option. For example, if you are comparing the group /groupA in two files and you want to exclude /groupA/groupB/groupC in both files, the exclude option would read as follows:
--exclude-path "/groupB/groupC"

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-error-stack

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.

Example:

Compare the object /a/b in file1 with the object /a/c in file2:
h5diff file1 file2 /a/b /a/c

Compare the object /a/b in file1 with the same object in file2:
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 dset exists only in file2, the group /g2 exists only in file1, and the group /g3 and 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, obj1 and obj2, have attributes named float2 and integer1, while only obj1 has 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 obj2.

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

History:

Release	Change
1.6.0	`h5diff` introduced in this release.
1.8.0	`ph5diff` introduced in this release. `h5diff` command line syntax changed in this release.
1.8.2 and 1.6.8	Return value on failure changed in this release.
1.8.4 and 1.6.10	`--use-system-epsilon` option added in this release.
1.8.5	`--follow-symlinks` option added in this release. `--no-dangling-links` option added in this release.
1.8.6	`--exclude-path` option added in this release.
1.8.7	`-vn, --verbose=n` option, specifying levels of verbose output, added in this release.
1.10.2	`--enable-error-stack` was added

--- Last Modified: August 28, 2019 | 09:02 AM

Page tree

h5diff

Syntax:

Description:

Options and Parameters:

Exit Status for h5diff:

Exit Status for ph5diff:

Example:

History:

The HDF Group

Site

Resources

Connect