<!--
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  * Copyright by The HDF Group.                                               *
  * Copyright by the Board of Trustees of the University of Illinois.         *
  * All rights reserved.                                                      *
  *                                                                           *
  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
  * terms governing use, modification, and redistribution, is contained in    *
  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
  * of the source code distribution tree; Copyright.html can be found at the  *
  * root level of an installed copy of the electronic HDF5 document set and   *
  * is linked from the top-level documents page.  It can also be found at     *
  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
  * access to either file, you may request a copy from help@hdfgroup.org.     *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 -->


<!-- NEW PAGE -->
<!-- HEADER RIGHT "h5diff" -->
<hr>
<dl>
<dt><div align=right><font color=999999 size=-1><i>
    Last modified: 22 August 2012
    </i></font></div>

<dt><strong>Tool Name:</strong> <a name="Tools-Diff">h5diff</a>  &nbsp;&nbsp;&nbsp;
<dt><strong>Syntax:</strong>
    <dd><code>h5diff </code> [<em>OPTIONS</em>]
                    <em>file1</em> <em>file2</em> 
                    [<em>object1</em> [<em>object2</em> ] ]       
    <!--
    <dd><code>h5diff </code> <em>file1</em> <em>file2</em> 
                    [<em>OPTIONS</em>]
                    [<em>object1</em> [<em>object2</em> ] ]       
    -->

    <p>
    <dd><code>ph5diff </code> [<em>OPTIONS</em>]
                    <em>file1</em> <em>file2</em> 
                    [<em>object1</em> [<em>object2</em> ] ]       
    <!--
    <dd><code>ph5diff </code> <em>file1</em> <em>file2</em> 
                    [<em>OPTIONS</em>] 
                    [<em>object1</em> [<em>object2</em> ] ]       
    -->

    <p>
<dt><strong>Purpose:</strong>
    <dd>Compare two HDF5 files and report the differences.

    <p>
<dt><strong>Description:</strong>
    <dd><code>h5diff</code> and <code>ph5diff</code> are command line tools 
        that compare two HDF5 files, <em>file1</em> and <em>file2</em>, 
        and report the differences between them.
        <code>h5diff</code> is for serial use while
        <code>ph5diff</code> is for use in parallel environments.
        <p>
        Optionally, <code>h5diff</code> and <code>ph5diff</code> 
        will compare two objects within these files.
        If only one object, <em>object1</em>, is specified, 
        <code>h5diff</code> will compare 
        <em>object1</em> in <em>file1</em>
        with <em>object1</em> in <em>file2</em>.
        If two objects, <em>object1</em> and <em>object2</em>, 
        are specified, <code>h5diff</code> will compare 
        <em>object1</em> in <em>file1</em>
        with <em>object2</em> in <em>file2</em>.
        <p>
        <em>object1</em> and <em>object2</em> 
        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&rsquo;s root group.
        <ul>
            <li>If these objects are groups, <code>h5diff</code>
                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.
            <li>If these objects are datasets, array rank and dimensions, 
                datatypes, and data values are compared.
            <li>If these objects are named datatypes, the comparison 
                is based on the return value of
                <code><a href="RM_H5T.html#Datatype-Equal">H5Tequal</a></code>.
            <li>If these objects are symbolic links, the paths to the target 
                objects are compared.
                <br>
                (The option <code>--follow-symlinks</code> overrides the default 
                behavior when symbolic links are compared.)
        </ul>

        <p>
        <a name="OutputModes">
        <b>Output modes:</b>
        </a>
        <br>
        <code>h5diff</code> and <code>ph5diff</code> 
        have the following output modes:
        <dir>
        <table border=0>
          <tr valign="top"><td>Default</td>
              <td><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
              <td>Prints the number of differences found 
                  and where they occurred.
                  <br>
                  If no differences are found, <code>h5diff</code> and 
                  <code>ph5diff</code> produce no output.
                  <br>
                  This <i>normal</i> behavior is achieved by using 
                  none of the following output mode options.
          </td></tr>
          <tr valign="top"><td>Report mode</td>
              <td><code>-r</code></td>
              <td>Prints the above plus the differences.
          </td></tr>
          <tr valign="top"><td>Verbose&nbsp;mode&nbsp;&nbsp;&nbsp;&nbsp;</td>
              <td><code>-v</code></td>
              <td>Prints all of the above plus a list of objects and warnings.
          </td></tr>
          <tr valign="top"><td>Verbose&nbsp;mode&nbsp;&nbsp;&nbsp;&nbsp;
                         <br>
                         &nbsp;&nbsp;&nbsp;&nbsp;with&nbsp;levels</td>
              <td><code>-v<i>n</i></code></td>
              <td>Prints a selectable level of detail. 
                  <br>
                  For details, see &ldquo;Options and Parameters&rdquo; below.
          </td></tr>
          <tr valign="top"><td>Quiet mode</td>
              <td><code>-q</code></td>
              <td>Prints no output. 
                  <br>
                  The <code>h5diff</code> exit code will be 
                  the only feedback provided.
          </td></tr>
        </table>
        </dir>

        <p>
        <a name="ComparisonModes">
        <b>Difference controls:</b>
        </a>
        <br>
        <code>h5diff</code> offers several mutually-exclusive criteria for
        analyzing differences in raw data:
        <ul>
            <li><i>Strict equality</i> &mdash;
                The default comparison mode is to check for strict 
                equality of data values.
            <li><i>Fixed difference</i> &mdash;
                With the <code>'-d <em>delta</em>'</code> &nbsp;or
                <code>&nbsp;'--delta=<em>delta</em>'</code> option, 
                <code>h5diff</code> considers two data values to be equal
                if the absolute value of the difference is less than the
                specified <code><em>delta</em></code>.
            <li><i>Relative difference</i> &mdash;
                With the <code>'-p <em>relative</em>'</code> &nbsp;or
                <code>&nbsp;'--relative=<em>relative</em>'</code> option,
                <code>h5diff</code> considers two data values to be equal
                if the absolute value of the relative difference is less
                than the value specified in <code><em>relative</em></code>.
            <li><i>System epsilon</i> &mdash;
                With the <code>'--use-system-epsilon'</code> option,
                <code>h5diff</code> considers two data values to be equal
                if the absolute value of the difference is less than the
                computing platform&rsquo;s system epsilon (or a pre-determined
                value if no system epsilon is defined).
        </ul>

        <p>
        <a name="NaNs">
        <b><code>h5diff</code> and NaNs:</b>
        </a>
        <br>
        <code>h5diff</code> 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, <code>h5diff</code> 
        treats them as equal; when a NaN is compared with a valid number,
        <code>h5diff</code> treats them as not equal.
        <p>
        Note that NaN detection is computationally expensive and slows
        <code>h5diff</code> performance dramatically.
        If you do not have NaNs in your files, or do not care about NaNs,
        use the <code>-N</code> option to turn off NaN detection.
        Similarly, if <code>h5diff -N</code> produces unexpected differences,
        running <code>h5diff</code> without <code>-N</code> should reveal 
        whether any of the differences are associated with NaN values.

        <p>
        <b>Difference between <code>h5diff</code> and <code>ph5diff</code>:</b>
        <br>
        With the following exception, 
        <code>h5diff</code> and <code>ph5diff</code> behave identically.
        With <code>ph5diff</code>, 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 
        <code>ph5diff</code> 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.

<!--
        Additional information, with several sample cases, 
        can be found in the document 
        <a href="http://www.hdfgroup.org/HDF5/h5diff/h5diff_design.html">
        <cite>H5diff Examples</cite></a>.
-->

    <p>
<dt><strong>Options and Parameters:</strong>
    <ul><table>
        <tr>
            <td valign="top"><code>-h</code>
                &nbsp;&nbsp;or&nbsp;
                <code>--help</code></td>
            <td valign="top">Print help message.</td></tr>
        <tr>
            <td valign="top"><code>-V</code>
                &nbsp;&nbsp;or&nbsp;
                <code>--version</code></td>
            <td valign="top">Print version number and exit.</td></tr>
        <tr>
            <td valign="top"><code>-r</code>
                &nbsp;&nbsp;or&nbsp;
                <code>--report</code></td>
            <td valign="top">Report mode &mdash; 
                Print the differences.</td></tr>
        <tr>
            <td valign="top"><code>-v</code>
                &nbsp;&nbsp;or&nbsp;
                <code>--verbose</code></td>
            <td valign="top">Verbose mode &mdash; 
                Print difference information, list of objects, warnings, etc.
                </td></tr>
        <tr>
            <td valign="top"><code>-v<em>n</em></code>
                &nbsp;&nbsp;or
                <br>
                <code>&nbsp;&nbsp;--verbose=</code><em>n</em></td>
            <td valign="top">Verbose mode with levels&mdash; 
                Print difference information, list of objects, 
                warnings, etc., with the level of detail determined by
                value of <code><em>n</em></code>:
                <table width="100%">
                    <tr valign="top"><td><code>&nbsp;&nbsp;0&nbsp;&nbsp;</code></td>
                        <td>Basic difference information, list of objects,
                        and warnings.
                        <br>
                        Identical to <code>-v, --verbose</code>.
                        </td></tr>
                    <tr valign="top"><td><code>&nbsp;&nbsp;1</code></td>
                        <td>All level <code>0</code> information
                        plus a one-line attribute status summary.
                        </td></tr>
                    <tr valign="top"><td><code>&nbsp;&nbsp;2</code></td>
                        <td>All level <code>1</code> information
                        plus an extended attribute status report.
                        </td></tr>
                </table>
                </td></tr>
        <tr>
            <td valign="top"><code>-q</code>
                &nbsp;&nbsp;or&nbsp;
                <code>--quiet</code></td>
            <td valign="top">Quiet mode &mdash; 
                Do not print output.
                <p>&nbsp;
                </td></tr>
        <tr>
            <td valign="top"><code>--follow-symlinks</code></td>
            <td valign="top">Follow symbolic links 
                (soft links and external links) and compare the links&rsquo; 
                target objects.
                <p>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). 
                <ul>
                  <li>If both symbolic links are dangling links, 
                    they are treated as being the same; by default, 
                    <code>h5diff</code> returns an exit code of <code>0</code>. 
                    If, however, 
                    <code>--no-dangling-links</code> is used with 
                    <code>--follow-symlinks</code>, this situation is treated as 
                    an error and <code>h5diff</code> returns an exit code of 
                    <code>2</code>.
                  <li>If only one of the two links is a dangling link, 
                    they are treated as being different and <code>h5diff</code> 
                    returns an exit code of <code>1</code>. If, however, 
                    <code>--no-dangling-links</code> is used with 
                    <code>--follow-symlinks</code>, this situation is treated as 
                    an error and <code>h5diff</code> returns an exit code of 
                    <code>2</code>.
                  <li>If both symbolic links point to existing objects, 
                    <code>h5diff</code> compares the two objects. 
                </ul>
                <p>If any symbolic link specified in the call to 
                <code>h5diff</code> does not exist, 
                <code>h5diff</code> treats it as an error and returns 
                an exit code of <code>2</code>.
                </td></tr>
        <tr>
            <td valign="top"><code>--no-dangling-links</code></td>
            <td valign="top">Must be used with the 
                <code>--follow-symlinks</code> option; 
                otherwise, h5diff shows error message and 
                returns an exit code of <code>2</code>.
                <p>
                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 <code>h5diff</code> 
                returns an exit code of <code>2</code>.
                </td></tr>
        <tr>
            <td valign="top"><code>-N</code>
                &nbsp;&nbsp;or&nbsp;
                <code>--nan</code></td>
            <td valign="top">Disables NaN detection;
                see &ldquo;<code>h5diff</code> and NaNs&rdquo; above.
                </td></tr>
        <tr>
            <td valign="top"><code>-n</code> <em>count</em>
                &nbsp;&nbsp;or
                <br>
                <code>&nbsp;&nbsp;--count=</code><em>count</em>
                <p>&nbsp;
                </td>
            <td valign="top">Print difference up to <em>count</em> 
                differences, then stop. 
                <em>count</em> must be a positive integer.
                <p>&nbsp;
                </td></tr>
        <tr>
            <td valign="top"><code>-d</code> <em>delta</em>
                &nbsp;&nbsp;or
                <br>
                <code>&nbsp;&nbsp;--delta=</code><em>delta</em></td>
            <td valign="top">Print only differences that are greater than the 
                limit <em>delta</em>. <em>delta</em> must be a positive number.
                The comparison criterion is whether the absolute value of the 
                difference of two corresponding values is greater than 
                <em>delta</em> 
                (i.e.,&nbsp;<code>&nbsp;|a&ndash;b|&nbsp;&gt;&nbsp;<em>delta</em></code>,
                where <code>a</code> is a value in <em>file1</em> and
                <code>b</code> is a value in <em>file2</em>).
                <p>
                Do not use <code>-d, --delta</code> with 
                <code>-p, --relative</code> or <code>--use-system-epsilon</code>.
                </td></tr>
        <tr>
            <td valign="top"><code>-p</code> <em>relative</em>
                &nbsp;&nbsp;or
                <br>
                <code>&nbsp;&nbsp;--relative=</code><em>relative</em></td>
            <td valign="top">Print only differences that are greater than a 
                relative error. <em>relative</em> 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 <em>relative</em> (that is, 
                <code>|(a&ndash;b)/b)|&nbsp;&gt;&nbsp;<em>relative</em></code>
                where <code>a</code> is a value in <em>file1</em> and
                <code>b</code> is the corresponding value in <em>file2</em>).
                <p>
                Do not use <code>-p, --relative</code> with 
                <code>-d, --delta</code> or <code>--use-system-epsilon</code>.
                </td></tr>
        <tr>
            <td valign="top">
                <code>--use-system-epsilon</code>
                <br>
                <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code>
                </td>
            <td valign="top">Return a difference if and only if the difference
                between two data values exceeds the system value for epsilon.
                That is, if <code><i>a</i></code> is a data value in one dataset,
                <code><i>b</i></code> is the corresponding data value in the 
                dataset with which the first dataset is being compared, and 
                <code><i>epsilon</i></code> is the system epsilon,
                return a difference if and only if 
                <code>|<i>a</i>-<i>b</i>| > <i>epsilon</i></code>.
                <p>
                If no system epsilon is defined, <code>h5diff</code>
                will use the following values, 
                which approximate common system epsilon values:
                <dir>
                <code>FLT_EPSILON=1.19209E-07</code> &nbsp; for 
                      floating-point datatypes
                <br>
                <code>DBL_EPSILON=2.22045E-16</code> &nbsp; for 
                      double precision datatypes
                </dir>
                <p>
                Do not use <code>--use-system-epsilon</code> with
                <code>-d, --delta</code> or <code>-p, --relative</code>.
                <p>&nbsp;
                </td></tr>
        <tr>
            <td valign="top">
                <code>--exclude-path "<em>path</em>"</code>
                </td>
            <td valign="top">Exclude the specified <em>path</em> to an object 
                     when comparing files or groups.  If a group is excluded, 
                     all member objects will also be excluded. 
                     <p>
                     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.
                     <p>
                     When comparing files, <em>path</em> is the 
                     absolute path to the excluded object; when comparing  
                     groups, <em>path</em> is similar to the relative path 
                     from the group to the excluded object.  
                     This <em>path</em> can be taken from the first section of 
                     the output of the <code>--verbose</code> option. 
                     For example, if you are comparing the group 
                     <code>/groupA</code> in two files and you want to exclude 
                     <code>/groupA/groupB/groupC</code> in both files, 
                     the exclude option would read as follows:
                     <br>
                     <code>&nbsp;&nbsp;&nbsp;&nbsp;</code>
                     <code>--exclude-path "/groupB/groupC"</code>
                     <p>
                     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.
                     <p>
                     This option can be used repeatedly to exclude 
                     multiple paths.
                <p>&nbsp;
                </td></tr>
        <tr>
            <td valign="top"><em>file1</em>
                &nbsp;&nbsp;
                <em>file2</em></td>
            <td valign="top">The HDF5 files to be compared.</td></tr>
        <tr>
            <td valign="top"><em>object1</em>
                &nbsp;&nbsp;
                <em>object2</em></td>
            <td valign="top">Specific object(s) within the files 
                to be compared, expressed as absolute paths 
                from the respective file&rsquo;s root group.</td></tr>
    </table></ul>
    <br />
<dt><strong>Exit Status for h5diff:</strong></dt>
    <dd><table border="0" width="100%">
        <tr valign="top" align="left">
            <td width="5%">0</td>
            <td width="95%">No differences were found.</td>
        </tr>
        <tr valign="top" align="left">
            <td>1</td>
            <td>Some differences were found.</td>
        </tr>
        <tr valign="top" align="left">
            <td>&gt;1&nbsp;&nbsp;&nbsp;&nbsp;</td>
            <td>An error occurred.</td>
        </tr>
    </table></dd>
    <br />
<dt><strong>Exit Status for ph5diff:</strong></dt>
    <dd>Because of the limitations in the MPI standard, the return value 
    is not defined. </dd>


    <br />
<dt><strong>Examples:</strong>
    <dd>Compare the object <code>/a/b</code> in <code>file1</code> 
        with the object <code>/a/c</code> in <code>file2</code>:<br>
        <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff file1 file2 /a/b /a/c</code>

        <p>
        Compare the object <code>/a/b</code> in <code>file1</code> 
        with the same object in <code>file2</code>:<br>
        <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff file1 file2 /a/b</code>

        <p>
        Compare all objects in both files:<br>
        <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff file1 file2</code>

<!-- NEW PAGE -->

        <p>
        Comparisons executed with the verbose options can produce 
        object and attribute status reports as illustrated below:<br />
        <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff -v file1 file2</code>
        <pre>
    ...
    file1     file2
    ---------------------------------------
        x      x    /              
               x    /dset          
        x           /g2            
        x      x    /g3            
    ...
        </pre>
        The sample output above shows that 
        the dataset <code>dset</code> exists only in <code>file2</code>,
        the group <code>/g2</code> exists only in <code>file1</code>, and
        the group <code>/g3</code> 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:<br />
        <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff -v2 file1 file2</code>
    
    
        <pre>
    ...
    group  : &lsaquo;/g2&rsaquo; and &lsaquo;/g2&rsaquo;
    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
    ...
        </pre>
        In this illustration, 
        both objects, <code>obj1</code> and <code>obj2</code>,
        have attributes named <code>float2</code> and <code>integer1</code>, 
        while only <code>obj1</code> has an attribute named <code>float3</code>.
        Only attributes that exist on both objects will be compared.
        <p>
        The &ldquo;Attributes status:&rdquo; line reports that there are 
        two attributes common to both objects: 
        one attribute attached only to <code>obj1</code>, and 
        zero attributes attached only to <code>obj2</code>.</p>
        <p>
        To see the &ldquo;Attributes status:&rdquo; line independently 
        of the immediately-preceding table, use the -v1 option.<br />
        <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff -v1 file1 file2</code>
    
        <pre>
    ...
    group  : &lsaquo;/g2&rsaquo; and &lsaquo;/g2&rsaquo;
    0 differences found              
    Attributes status:  2 common, 1 only in obj1, 0 only in obj2
    ...
        </pre>
        

    <p>
<dt><strong>History:</strong>
    <dd><table width="90%">
        <tr>
          <td valign="top" align="left" width="10%">
            <strong>Release</strong>&nbsp;&nbsp;&nbsp;&nbsp;</td>
          <td valign="top" align="left">
            <strong>Change</strong></td></tr>
        <tr>
          <td valign="top">1.6.0</td>
          <td valign="top">
            <code>h5diff</code> introduced in this release.</td></tr>
        <tr>
          <td valign="top">1.8.0</td>
          <td valign="top">
            <code>ph5diff</code> introduced in this release.
            <br>
            <code>h5diff</code> command line syntax changed in this 
            release.</td></tr>
<!--
        <tr>
          <td valign="top">1.8.1</td>
          <td valign="top">
            Original syntax restored; both the original and the new syntax
            are now supported.</td></tr>
-->
        <tr>
          <td valign="top">1.8.2 and 1.6.8</td>
          <td valign="top">
            Return value on failure changed in this release.</td></tr>
        <tr>
          <td valign="top">1.8.4&nbsp;and&nbsp;1.6.10&nbsp;&nbsp;&nbsp;&nbsp;</td>
          <td valign="top">
            <code>--use-system-epsilon</code> option added in this release.
            </td></tr>
        <tr>
          <td valign="top">1.8.5</td>
          <td valign="top">
            <code>--follow-symlinks</code> option added in this release.
            <br>
            <code>--no-dangling-links</code> option added in this release.
            </td></tr>
        <tr>
          <td valign="top">1.8.6</td>
          <td valign="top">
            <code>--exclude-path</code> option added in this release.
            </td></tr>
        <tr>
          <td valign="top">1.8.7</td>
          <td valign="top">
            <code>-v<i>n</i>, --verbose=<i>n</i></code> &nbsp;option, 
            specifying levels of verbose output, added in this release.
            </td></tr>
    </table></dd>

<!--
    <p>
<dt><strong>Current Status:</strong>
    <dd>
    <p>
<dt><strong>See Also:</strong>
    <dd>
-->
</dl>