Last modified: 29 April 2014
Tool Name: h5diff    
Syntax:
h5diff [OPTIONS] file1 file2 [object1 [object2 ] ]

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

Purpose:
Compare two HDF5 files and report the differences.

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.

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:

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

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