Copyright (c) 2016, Lawrence Livermore National Security, LLC. Produced at the Lawrence Livermore National Laboratory. Written by G. Scott Lloyd, email@example.com. 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.