ncmpidiff

ncmpidiff is a parallel utility program that compares the contents of the two files and reports the difference to the standard output. When comparing file headers, the differences of all metadata are reported, including dimensions, attributes, variable types and dimensionality. When comparing variables, only the indices of first array element found differently is reported when option -t is not used. When option -t is used, it reports the element with the largest difference that fails to meet the tolerance requirements.

When comparing two files entirely, ncmpidiff skips the gaps between header and variables and gaps between any two consecutive variables. Note this behavior differs from the Unix command diff which compares two files byte by byte.

The gaps occur when the alignment feature is enabled when creating a new file, which allows to allocate a larger space for the file header and aligns the starting file offsets of fixed-size variables to a user specified file offset boundary(see ncmpi__enddef and PNETCDF_HINTS). Oftentimes, the contents of gaps are arbitrary. Thus, it is possible that two netCDF files of same or different sizes are reported identical by ncmpidiff but not by diff.

cdfdiff is a serial version of ncmpidiff. It can be compiled by gcc without MPI compiler. Thus, it can be useful to run on login nodes in a cross-compile environment.

Synopsis

mpiexec -n NP ncmpidiff [-b] [-q] [-h] [-v var1,...] [-t diff,ratio] file1 file2

cdfdiff [-b] [-q] [-h] [-v var1,...]  file1 file2

Command-line Options

-b

Verbose mode - print results (same or different) for all components (file, header, or variables) in comparison

-q

Quiet mode - print nothing when two components in comparison are the same

-h

Compare file header only

-v var1,...,varn

Compare only the given list of variables, with names separated by comma and no space in between (file header comparison is skipped, unless -h is used.)

-t diff,ratio

Compare variables elementwisely with tolerance (diff and ratio separated by comma without space). diff is the absolute value of element-wise difference of any two variables. ratio is the relative element-wise ratio, for instance, MAX(x,y) / MIN(x,y) - 1, where x is an array element from a variable in the first file and y is the corresponding array element of the same variable in the second file. Note when this option is used, the comparison will compare the entire variables and reports the array indices of element with the largest difference that fails to meet the both tolerance requirements. (This option was first added in version 1.12.0.)

Example output on screen

Below shows an example when comparing two files in verbose mode.

% mpiexec -n 1 ncmpidiff -b tst_rec.nc1 tst_recx.nc2
DIFF: file format (CDF-1) != (CDF-2)
SAME: number of dimensions (3)
SAME: number of variables (2)
SAME: number of global attributes (1)
Global attribute "history":
	SAME: data type (NC_CHAR)
	SAME: length (24)
	SAME: attribute contents
Dimension:
	SAME: dimension "time" length (0)
	SAME: dimension "Y" length (4)
	SAME: dimension "X" length (12)
Variables:
Variable "rec_var":
	SAME: data type (NC_FLOAT)
	SAME: number of dimensions (2)
	dimension 0:
		SAME: name (time)
		SAME: length (0)
	dimension 1:
		SAME: name (X)
		SAME: length (12)
	SAME: number of attributes (0)
Variable "fix_var":
	SAME: data type (NC_FLOAT)
	SAME: number of dimensions (2)
	dimension 0:
		SAME: name (Y)
		SAME: length (4)
	dimension 1:
		SAME: name (X)
		SAME: length (12)
	SAME: number of attributes (0)
number of variables to be compared = 2
DIFF: variable "rec_var" of type "NC_FLOAT" at element [1, 1]
	SAME: variable "rec_var" contents
DIFF: variable "fix_var" of type "NC_FLOAT" at element [1, 2]
Number of differences in header: 1
Number of differences in variables: 2