LLNL/unum

Copyright (c) 2016, Lawrence Livermore National Security, LLC.
Produced at the Lawrence Livermore National Laboratory.
Written by G. Scott Lloyd, lloyd23@llnl.gov.
LLNL-CODE-704762.
All rights reserved.

This file is part of Unum.
For details, see http://github.com/LLNL/unum
Please also read COPYING.

--------------------------------------------------------------------------------

This floating-point arithmetic library contains a software 
implementation of Universal Numbers (unums) in 'C' as described by 
John Gustafson in the book "The End of Error: Unum Computing". The 
implementation is patterned after the prototype code printed in the 
book. A download of the Mathematica code is available from the 
publisher's website: 

http://www.crcpress.com/The-End-of-Error-Unum-Computing/Gustafson/9781482239867

Since this 'C' implementation uses names common with the Mathematica 
implementation, the book can be used as a form of documentation to help 
understand the source code. The unum library uses the GNU Multiple 
Precision (GMP) Arithmetic Library for the low-level arithmetic. GMP 
(http://gmplib.org/) must be installed or accessible on your system to 
build and use the unum library. If you don't install GMP to a standard 
location, you can define the following environment variables before 
running "./configure". 

export CPPFLAGS=-I<path to GMP include>
export LDFLAGS=-L<path to libgmp>

Some additional documentation about the unum package can be found in the 
"doc" directory. 

After configuring the distribution with "./configure", existing test 
programs can be executed in a batch by running "make check" from the top 
level directory of the distribution. Once built, they can be 
individually run at the command line from the "tests" directory. 

To help in writing unum test programs, an example "tests/tdev.c" is 
provided. Test programs can be built individually with the standalone 
make file "tests/tdev.mak" that is not part of the autotools build 
system. This make file is handy when making frequent changes to the unum 
library source code since it compiles and links the individual source 
files with a test without the overhead of autotools and building the 
library archive. 

The library supports creation of unums and printing of unum values. It 
also supports variable sized unums from a few bits up to thousands. 
Functions are available that convert between unums and primitive 'C' 
types. The relational operators, four arithmetic operators (add, 
subtract, multiply and divide), and square root are also implemented. 
The guess function, when applied to a unum after an arithmetic 
operation, will produce a rounded result much like a floating-point 
calculation. 

Three main interfaces to unum functionality are available in the "src"
directory:
 * unumxx.h – 'C++' wrapper class that allows unums (actually ubounds)
               to be used with the standard arithmetic operators
 * unum.h   – 'C' function interface that stores unums in a variable length
               byte array
 * ubnd.h   – 'C' function interface that stores unums in a data structure

The C++ wrapper class will generate calls to the ubnd.h interface. 
Within a program, unums are defined with the "ubnd_c" type and may be 
used in place of "floats" and "doubles". A simple example is shown in 
the "tunumxx.cpp" test program. The unum environment must be set with 
the set_uenv() function before any operations occur with unums. Existing 
applications modified to use unums will likely need to have "AUTO_GUESS" 
defined at compile time. This will automatically insert calls to the 
unum guess function at every assignment. 

Operations on unums through the library are several thousand times 
slower than operations on IEEE standard types with floating-point 
hardware. While faster implementations of the library are possible, the 
intent of this implementation is to provide flexibility for research 
purposes and accurate results.