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.