Numdiff (which I will also write numdiff)
is a little program that can be used to compare
putatively similar files line by line and field by field,
ignoring small numeric differences or/and different numeric formats.
Equivalently, Numdiff is a program with the capability to appropriately
compare files containing numerical fields (and not only).
By default, Numdiff assumes the fields are separated by white
spaces (blanks, horizontal tabulations and newlines), but
the user can also specify its list of separators through the
-s, see the User Manual.
When you compare a couple of such files,
what you want to obtain usually is a list of the numerical fields in
the second file which numerically differ from the corresponding
fields in the first file.
Well known tools like
can not be used to this purpose:
they can not recognize whether a difference between two numerical
fields is only due to the notation or is actually a difference of
Moreover, you could also want to ignore differences in
numerical values as long as they do not overcome a certain threshold.
In other words, you could desire to neglect all small numerical
However, programs like
wdiff can not be used
to ignore small numerical differences, since they do not even know
what a numerical difference is.
That is why I decided to implement Numdiff.
In writing this program I was inspired by
a GPL'ed software by Nelson H. Baabe of the Salt Lake City
Its author had the same good reasons as me to
ndiff is actually a good tool and I used it for a
while. But I did not completely like the way it works and so
was born. Although
numdiff, they are completely
different from the viewpoint of the source code:
numdiff has been
entirely written from scratch.
I know that many people could find Numdiff simply useless. But people working in Scientific Computing or in Numerical Analysis could find it useful for their job. Since one might compare a file containing the output produced by a given numerical program, when it runs in a certain environment, with another file containing the output produced by the same program but in a different environment, which could mean a different operating system or a different compiler on the same system. Other times one has to compare the output of a numerical program, which is made to solve a certain problem, with the one produced by another program, which solves the same problem but using a different algorithm. Finally, one might compare the output of a numerical program with a sample file containing a list of expected data (which could have been computed theoretically). In all these situations Numdiff could turn out very helpful, since it also lets the user specify a tolerance for absolute and/or relative differences, then reporting only the fields which differ enough to exceed these tolerances.
Because a sample is often more useful than many words...
Let us suppose that
file1 contains the list
1.25 -3.45 1.23456789E-2 -5.98765432e+5 100.00
file2 the following one:
1.250001 -3.450003 1.23456788E-2 -5.98765431e+5 100.000022
We can compare these two files by calling
(the name of the program must be written lower case !)
and passing it
file2 as arguments:
numdiff file1 file2
The output of this command will be:
---------------- ##1 #:1 <== 1.25 ==> 1.250001 @ Absolute error = 1.0000000000e-6, Relative error = 8.0000000000e-7 ##1 #:2 <== -3.45 ==> -3.450003 @ Absolute error = 3.0000000000e-6, Relative error = 8.6956521739e-7 ##1 #:3 <== 1.23456789E-2 ==> 1.23456788E-2 @ Absolute error = 1.0000000000e-10, Relative error = 8.1000001393e-9 ##1 #:4 <== -5.98765432e+5 ==> -5.98765431e+5 @ Absolute error = 1.0000000000e-3, Relative error = 1.6701030958e-9 ##1 #:5 <== 100.00 ==> 100.000022 @ Absolute error = 2.2000000000e-5, Relative error = 2.2000000000e-7 +++ File "file1" differs from file "file2"
This text should be self-explanatory. The tags
f are integer numbers, refer respectively to the
line number and to the position of the field within the line.
##1 #:1 <== 1.25 ==> 1.250001 @ Absolute error = 1.0000000000e-6, Relative error = 8.0000000000e-7
means that the first field of the first line is given by
1.25 in the first file,
1.250001 in the second one.
The absolute difference between these two numbers is
1.0000000000e-6, while the relative difference is
Numdiff can also print a sort of statistical report about
the numerical differences discovered in the two files. To this
end is sufficient to specify the option
-S. The output
of the command
numdiff -S file1 file2 will be:
---------------- ##1 #:1 <== 1.25 ==> 1.250001 @ Absolute error = 1.0000000000e-6, Relative error = 8.0000000000e-7 ##1 #:2 <== -3.45 ==> -3.450003 @ Absolute error = 3.0000000000e-6, Relative error = 8.6956521739e-7 ##1 #:3 <== 1.23456789E-2 ==> 1.23456788E-2 @ Absolute error = 1.0000000000e-10, Relative error = 8.1000001393e-9 ##1 #:4 <== -5.98765432e+5 ==> -5.98765431e+5 @ Absolute error = 1.0000000000e-3, Relative error = 1.6701030958e-9 ##1 #:5 <== 100.00 ==> 100.000022 @ Absolute error = 2.2000000000e-5, Relative error = 2.2000000000e-7 Largest absolute error in the set of relevant numerical differences: 1.0000000000e-3 Corresponding relative error = 1.6701030958e-9 Largest relative error in the set of relevant numerical differences: 8.6956521739e-7 Corresponding absolute error = 3.0000000000e-6 +++ File "file1" differs from file "file2"
You can specify an absolute error tolerance (or a relative
error tolerance) by the option
When the user specify an absolute error tolerance,
numdiff only reports the absolute differences
exceeding that tolerance. For instance, the output
numdiff -a 1.0e-5 file1 file2 will be
---------------- ##1 #:4 <== -5.98765432e+5 ==> -5.98765431e+5 @ Absolute error = 1.0000000000e-3, Relative error = 1.6701030958e-9 ##1 #:5 <== 100.00 ==> 100.000022 @ Absolute error = 2.2000000000e-5, Relative error = 2.2000000000e-7 +++ File "file1" differs from file "file2"
Numdiff has many more options and features. You can find a detailed description of them in its User Manual. In particular, Numdiff can also recognize non numerical differences between the files given to it as arguments. If a certain field in at least one of the two files is of non-numerical type, then, instead of doing a numeric comparison, Numdiff will simply do a literal (character by character) comparison.
To successfully compile, build and install Numdiff some
tools are required. The first one is an ANSI C compiler.
This compiler should at least accept the option
in order to place its output in a specified file.
Numdiff has been successfully compiled and tested on
Slackware GNU/Linux 10.2 with the version 3.3.6 of the GNU C Compiler (gcc),
on Slackware GNU/Linux 11 with gcc 3.4.6,
and on SunOS 5.8 with the version 2.95.3 of the same compiler.
Moreover, you need a POSIX implementation of the
(I used both GNU make and smake by Joerg Schilling
to compile Numdiff) and a POSIX implementation
of the commands
At last, you need a proper installation of GNU Texinfo
(in order to install the info documentation) and
a shell sh-compatible.
Configuration, building and installation of Numdiff can be performed through the standard three steps:
./configure make make install
If you leave enabled the Natural Language Support and you
also want to install the localization files (at the moment
only the Italian localization is supplied), then, after
make, you will have to type and run
make install will install all the files in
/usr/local/info, etc. You can specify
an installation prefix other than
/usr/local using the
--prefix in the
For better control, you can use the options
--infodir, and so on.
./configure --help to obtain
the complete list of all the available options.
Anyway, the documentation files, including a full User Manual
available in several formats (HTML, PDF and plain ASCII text),
will always be put in
DOCDIR is the path specified by the option
or, if this option has not been given to
PREFIX is the
installation prefix specified by the
--prefix or the default
Once Numdiff has been installed you can remove all the
files previously installed by a simple
If you have also installed the localization files trough
make install-nls, then, in order to remove also
these ones, use
make uninstall-nls in place
Between the options accepted by
--enable-debug turns on debugging when
compiling the source code. This is obtained by passing to the
-g option, but you can change this default
debugging flag (which could not even be recognized by your compiler)
by setting the environment variable
--enable-optimization turns on basic optimization when
compiling the source code. This is obtained by passing to the
-O option, but you can change this default
flag (which could not even be recognized by your compiler)
by setting the environment variable
--enable-nls turns on Natural Language Support.
But you do not need to use it explicitly, since Natural
Language Support is enabled by default.
However, you can disable it by using
Disabling Natural Language Support is suggested whenever
you want to install Numdiff on a system where is not present
the GNU gettext library. In this case
the installation of Numdiff can be accomplished, for instance,
./configure --disable-nls make make install
--enable-dpa are used
to enable the support for, respectively, multiple precision arithmetic,
high precision arithmetic, long double precision arithmetic and
double precision arithmetic. By default, the support
for multiple precision arithmetic is enabled if no explicit specification
The support for high precision arithmetic requires the installation of HPAlib (version 1.6 or later), a free (LGPL-ed) library for high precision computations available at the web address
Be careful ! Multiple precision arithmetic is better
than high precision arithmetic.
The support for high, long double and double precision
arithmetic is only provided to allow running Numdiff on
very slow computers.
Moreover, some of the features of Numdiff, which can be
activated through some suitable command line options,
are available only if Numdiff has been built with the
support for multiple precision arithmetic.
In particular, when this support is available, the user
can select at runtime, by the option
the precision which Numdiff will have
to use in doing its computations.
At the moment Numdiff can only manage text files with an 8-bit encoding (ASCII and ISO 8859-* text files). Sooner or later Numdiff should support UTF-8 (Unicode) encoding.
Numdiff (also written numdiff) is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Numdiff is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA .
Bug reports have to be sent to the address <ivprimi (a) libero it> . Please, put Numdiff in the subject and indicate the version of Numdiff you are using, the version of the operating system you are running and, if you know it, the version of the compiler used to build Numdiff. Moreover, you should specify whether Numdiff has been built with the support for double, long-double, high or multiple precision arithmetic.
The tar-gzipped archive with the source code of Numdiff can be downloaded from
The latest stable release of Numdiff is given by the version 4.0.0 . Together with the source code, the archive contains a very detailed user manual (in English). The manual, which has been written by using GNU Texinfo, is available in the following formats:
Permission is granted to copy, distribute and/or modify this manual under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "Numdiff User Manual, version 4.0", and with no Back-Cover Texts. A copy of the license is always included in the section entitled "GNU Free Documentation License". You can also obtain a copy of the GNU Free Documentation License by writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
The manual of Numdiff can also be browsed online here.
First I want to thank all the people till now involved in the Free Software community, starting from those ones directly involved in the GNU project (http://www.gnu.org). Without their great work, this little one would have never been done.
Moreover, I have to thank Aurelio Marinho Jargas (<verde (a) aurelio net>), author of txt2tags (http://txt2tags.sf.net), a free (GPL'ed) and wonderful text formatting and conversion tool, which I used in writing this web page.
I want to thank also Mr. Norman Clerman of Opcon Associates, Inc. for several suggestions he gave me to improve the readability and the effectiveness of the output produced by Numdiff. I have to give him credit for the urge to prepare the version 4.0.0 of Numdiff.
A special thank to my friend Mariapia Palombaro since she removed some errors while reviewing the first version of the Numdiff User Manual.