h5diff
[OPTIONS]
file1 file2
[object1 [object2 ] ]
ph5diff
[OPTIONS]
file1 file2
[object1 [object2 ] ]
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.
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.
H5Tequal
.
--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:
'-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
.
'-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
.
'--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.
-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 :
| ||||||
-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 any symbolic link specified in the call to
| ||||||
--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 | ||||||
-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 | ||||||
-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 | ||||||
--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, FLT_EPSILON=1.19209E-07 for
floating-point datatypes
DBL_EPSILON=2.22045E-16 for
double precision datatypes
Do not use
| ||||||
--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 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. |
0 | No differences were found. |
1 | Some differences were found. |
>1 | An error occurred. |
/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 ...
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.
|