
    epsilon is a simple program to help curb floating
point round-off errors in data files.  Compile it by typing 'make'.

     This utility accepts an arbitrary text file (assumed to
be a formatted data file of some sort) and a threshold value, and outputs
a new text file in which all floating point numbers differing by less than
the threshold value in the original file are forced to be equal in the
output file.

     The following usage message is obtained by running epsilon with no 
arguments:

Usage: epsilon <threshold> < [-format [fgd]]> [-integer] <infile> <outfile> 
  If infile = '-' or outfile = '-' then they are
   replaced by stdin or stdout respectively. 

Notes:

1) Numbers differing by less than threshold will be equated.

2) The optional argument -format [fgd] specifies the output format.

   -format f means standard floating point (%lf) format.
   -format e means %e (exponential) format.
   -format g means %g (shorter of %e and %f) format.
   -format d rounds each floating point number to its nearest integer
      and prints the result as an integer in %d format.

   The default format is f (%lf).

3) The optional argument -integer specifies that the program treat integers
   in the file as floating point numbers.  Thus if threshold = 0.2 and the
   numbers 1 and 1.1 are encountered then they will be printed out as 1.0
   (in whatever format is specified.)

   The default action is to ignore integers.  Thus in the default mode,
    if 1 and 1.1 appear they will be printed as 1 and 1.1, regardless of
    the threshold.

4)  The program forces nearly equal values to be equal to the first
    occurence of the value in the file.  Also, the program equates
    transitively, i.e. if threshold = 0.15 and the numbers 1.1  1.2 1.3
    appear in the the file (in that order) then they will all be forced
    to 1.1 in the output (except in the case discussed in 5) below.)
    (Note if they occured in the order
    1.1  1.3  1.2 the output would be  1.1  1.3  1.1.  Well,
    if your file has this sort of thing you probably should be fixing
    your computations instead of using epsilon!)

5)  Numbers that differ from 0.0 by less than threshold are forced
    to 0.0 in the output.

6) The program assumes floating point numbers are whitespace separated.
   So numbers such as (1.1, 2.0, 3.1) will remain unchanged regardless
   of the threshold.

7)  Watch out for files with floating point numbers that aren't part of the
    data.  e.g.  a file containing "Softimage Version 1.1" might get
    changed to "Softimage Version 1.2" if you're not careful!

8) The program builds a list of all values encountered in the file,
   and then compares each new value with the preceding values.  Thus:

   space requirements = O(#values)

   time requirements = O((#values * #values))

   The time requirements could be reduced to O(#values * log(#values))
   simply by ordering the list according to magnitude.

8)  epsilon is available via anonymous ftp at our site (poincare.geom.umn.edu) 
    in the directory ~ftp/pub.  The tar file epsilon.tar contains the source 
    epsilon.c,
    a makefile, and this article.   Comments, suggestions, bug reports should
    be sent to orloff@poincare.geom.umn.edu

Toby Orloff
