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.

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

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.