Last modified: 30 October 2009
Tool Name: h5diff    
Syntax:
h5diff file1 file2 [OPTIONS] [object1 [object2 ] ]

Purpose:
Compares two HDF5 files and reports the differences.

Description:
h5diff is a command line tool that compares two HDF5 files, file1 and file2, and reports the differences between them. 

Optionally, h5diff will compare two objects within these files. If only one object, object1, is specified, h5diff will compare object1 in file1 with object1 in file2. In two objects, object1 and object2, are specified, h5diff will compare object1 in file1 with object2 in file2. These objects must be HDF5 datasets.

object1 and object2 must be expressed as absolute paths from the respective file's root group.

h5diff has the following four modes of output:
Normal mode: Print the number of differences found and where they occurred.
Report mode (-r): Print the above plus the differences.
Verbose mode (-v): Print the above plus a list of objects and warnings.
Quiet mode (-q): Do not print output (h5diff always returns an exit code of 1 when differences are found).

Additional information, with several sample cases, can be found in the document H5diff Examples.

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

Options and Parameters:
file1
file2
The HDF5 files to be compared.
-h
help message.
-r
Report mode. Print the differences.
-v
Verbose mode. Print the differences, list of objects, warnings.
-q
Quiet mode. Do not print output.
-N
Disables NaN detection; see “h5diff and NaNs” above.
-n count
Print difference up to count differences, then stop. count must be a positive integer.
-d 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
(e.g., |a–b| > delta, where a is a value in file1 and b is a value in file2).
-p 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 difference 1 and the ratio of two corresponding values is greater than relative (e.g., |1–(b/a)| > relative where a is a value in file1 and b is a value in file2).
--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.
Default: Without this option, h5diff checks for strict equality.
This option has no single-letter short form.
object1
object2
Specific object(s) within the files to be compared.

Exit Status:
0 No differences were found.
1 Some differences were found.
>1     An error occurred.

Examples:
The following h5diff call compares the object /a/b in file1 with the object /a/c in file2:
    h5diff file1 file2 /a/b /a/c

This h5diff call compares the object /a/b in file1 with the same object in file2:
    h5diff file1 file2 /a/b

And this h5diff call compares all objects in both files:
    h5diff file1 file2

file1 and file2 can be the same file. Use:
    h5diff file1 file1 /g1/dset1 /g1/dset2 
to compare /g1/dset1  and /g1/dset2 in the same file.

History:
Release     Command Line Tool
1.6.0 Tool introduced in this release.
1.6.10 --use-system-epsilon option added in this release.