README

   1 This project checks various implementations of various floating
   2 point functions. If you are writing a floating point math library,
   3 and you want to compare it against other implementations in an
   4 automated, way, you might find this useful.
   5
   6 There are
   7
   8  - A bunch of impl-XYZ programs. They get started with option flags
   9    telling them what function f to run. They then listen on stdin
  10    for byte sequences x0, x1, ..., xN, responding on stdout with
  11    byte sequences f(x0), f(x1), ..., f(xN).
  12
  13  - A checker program. It is responsible for starting all the
  14    impl-XYZs, feeding them all the xi values, and then making sure
  15    they return equivalent f(xi) values. If two impls disagree, the
  16    checker prints out a diagnostic to stdout.
  17
  18 To compile everything, go into each directory and run `make' or
  19 `mbld' or whatever. If you like, you can run `make' in the main
  20 directory.
  21
  22 To test a bunch of random values with single precision, on the sine
  23 function, do something like:
  24
  25         checker/obj/checker -s -f sin
  26
  27 To use a specific seed for the random values (by default the seed
  28 is the current time):
  29
  30         checker/obj/checker -s -f sin -r 12345
  31
  32 To exhaustively test every possible single-precision floating point
  33 input:
  34
  35         checker/obj/checker -s -f sin -e
  36
  37 To use double-precision instead (it's not recommended to attempt
  38 to exhaust double-precision):
  39
  40         checker/obj/checker -d -f exp1m
  41
  42 To figure out what functions are supported (legal values for -f):
  43
  44         checker/obj/checker -l
  45
  46 To see all options:
  47
  48         checker/obj/checker -h
  49
  50 ----
  51
  52 On the internal side, an impl program is invoked via:
  53
  54         impl-XYZ [-s|-d] -n <num_inputs> -f <function-name>
  55
  56 where -s and -d specify single/double precision, and num_inputs
  57 describes how much data will be sent in and out for each iteration.
  58 Different functions may take different numbers of arguments (e.g.
  59 sin vs. atan2).
  60
  61 num_inputs is entirely for speed concerns: it is desirable to
  62 exhaustively test single-precision inputs. However, if values are
  63 sent and received one at a time, programs spend most of their time
  64 reading, writing, and waiting for new input.
  65
  66 The checker has to have some way of finding the impl programs. It
  67 does this in the dumbest way possible: walking through all files
  68 in "." and checking if they are 1) executable and 2) the name starts
  69 with "impl-". Therefore, you should probably run the checker from
  70 the root directory of the project.
  71
  72 Since multi-byte data is written and read over channels, endian-ness
  73 is a concern.  This was written and run on little-endian machines.
  74
  75 ----
  76
  77 There's a lot of duplication in the code. This is partially intentional
  78 (to avoid building an over-complicated in a multi-language project)
  79 and partially because I'm lazy.