Original version: Sat Aug 14 12:09:45 2010.
Last update: Thu Aug 19 10:09:40 2010.
Nelson H. F. Beebe
University of Utah
Department of Mathematics, 110 LCB
155 S 1400 E RM 233
Salt Lake City, UT 84112-0090
USA
Email: beebe@math.utah.edu,
beebe@acm.org,
beebe@computer.org
WWW URL: http://www.math.utah.edu/~beebe
Telephone: +1 801 581 5254
FAX: +1 801 581 4148
PGP public key (fingerprint = 7C 18 71 99 BC 82 5E AB 06 EB 9B 96 FD 9E 0E 97 A9 3C 57 C2)
MCW public key ID 0xFE0A1F46 (fingerprint = B574 BCC7 210E 9A29 E810 C85B 6ADE 786E FE0A 1F46),
and
notes for its use
This is the home FTP/Web site for the MathCW Mathematical Function Library, a large portable numerical library in C that provides a C99 math-function repertoire with many additional functions, support for extended data types, support for additional I/O formats, and support for decimal, as well as binary, floating-point arithmetic.
The library includes interfaces to Ada, C++, C#, Fortran, Java, and Pascal. Local modifications of the scripting languages mawk, nawk and lua have interfaced them to the library, and provided them with 34-digit decimal floating-point arithmetic.
To use the library with only native floating-point arithmetic, you need to download and install just one distribution file: start here and follow links to the desired operating system and CPU platform.
To use the library also with decimal floating-point arithmetic, you need the library distribution, plus a ready-to-run distribution of gcc with decimal support compiled in. The compiler is then called dgcc to distinguish it from already-installed compilers. To find the needed dgcc distribution, start here and follow links to the desired operating system and CPU platform. Note that the library is highly portable, and available on many more platforms than those that have working decimal arithmetic.
Because support for decimal arithmetic in gcc is not yet mature, on most systems, five or more compiler versions are offered, and their age is often identified by a YYYYMMDD (year month day) timestamp in their filenames.
Other tools that have been revised to replace binary floating-point arithmetic by decimal arithmetic include the dlua, dmawk, and dnawk scripting languages.
To guard against data corruption and hostile attacks, all distribution files are digitally signed with the author's private key, and verifiable with the corresponding public key, available from public key servers, and from links from the author's home page (at the bottom of the address block under the picture), and from the top of this Web page.
For further safety, three different checksums are used: MD5, SHA1SUM, and RIPEMD-160, and the checksum files themselves are digitally signed.
Major design requirements of the MathCW library include these features to enhance robustness and security:
Most MathCW library functions contain no nonconstant static data, and are therefore safe for independent use from multiple threads.
There are, however, some programming considerations:
For examples of threaded programming with math libraries, follow this link.
For both the library and the compiler, the distributions should be unbundled at the level of the normal local installation tree, widely known as /usr/local/ on many Unix systems. However, other tree roots should be possible, such as $HOME/local/ for users who do not have system-installation privileges, or who prefer to have private installations. A sample compiler installation might look like this on a GNU/Linux AMD64/EM64T/x86_64 system:
$ cd /usr/local/
$ tar xfz /tmp/x86_64-unknown-linux-gnu-gcc-4.6-20100424.p1.tar.gz
After installation of the compiler tree, to make it usable, either include its bin directory in your PATH variable, or create symbolic links to compiler components from a directory that is already searched:
$ cd /usr/local/bin
$ ln -s /usr/local/ashare/gcc-4.6-20100424/bin/gcc gcc-4.6-2010052
$ ln -s /usr/local/ashare/gcc-4.6-20100424/bin/g++ g++-4.6-2010052
$ ln -s /usr/local/ashare/gcc-4.6-20100424/bin/gcov gcov-4.6-2010052
$ ln -s gcc-4.6-2010052 dgcc
Including version numbers and timestamps in the executable names allows multiple versions to coexist, and makes it easy to switch compiler versions, just by changing the dgcc symbolic link, or using a specific compiler name.
For programs that require only the facilities of the standard C library, no source code changes are needed.
To access the many additional functions in the MathCW Library, change the header file <math.h> to <mathcw.h>. For even more functions, additional header files may be needed to define function prototypes and constants.
To use decimal arithmetic, you must also include the header file <decfloat.h>.
The new types are decimal_float, decimal_double, decimal_long_double, and decimal_long_long_double. Until the needed compiler extensions are implemented, the last two are equivalent. Eventually, however, the latter will provide a 70D decimal type. The first three decimal types provide precisions of 7D, 16D, and 34D, with approximate power-of-ten ranges for normalized values in [-95,96], [-383,384], and [-6143,6144]. Those ranges are significantly wider than those of the corresponding IEEE 754 binary types. The exact limits are defined in the header file <decfloat.h>.
The supported decimal types occupy 32-, 64-, 128-, and 256-bit memory blocks, the same as the corresponding binary floating-point types (the MathCW library also supports a binary long_long_double type, but compiler support is not yet available for it).
Decimal constants have suffixes DF, DD, DL, and DLL, although the last is not yet recognized by dgcc.
Input and output format specifiers have type modifiers H, DD, DL, and DLL. The irregularity of the first is necessary to avoid an ambiguity with a C99 modifier for upper-case binary fixed point output.
Unlike binary float, which is promoted to double in calls to functions with variable numbers of arguments, such as the printf() family, no such promotion occurs for decimal_float.
Decimal library function names are formed by taking the name of a binary double function, and adding lowercase suffixes: sqrtdf(), sqrtd(), sqrtdl(), and sqrtdll().
A large decimal programming example is available here.
If the directory in which the MathCW Library is installed is searched automatically by the linker, then you can compile, link, and run like this:
$ cc tsqrt.c -lmcw && ./a.out # i.e., change -lm to -lmcw
On some systems, it may be necessary to tell the compiler where to find the library, and to record that information in the executable program. Some compilers may also need to be told where to find locally-installed header files:
$ cc -I/usr/local/include tsqrt.c -L/usr/local/lib64 -Wl,-rpath,/usr/local/lib64 -lmcw && ./a.out # GNU/Linux style
$ cc -I/usr/local/include tsqrt.c -L/usr/local/lib64 -R/usr/local/lib64 -lmcw && ./a.out # alternate Unix style
We recommend that the header-file and library locations be supplied in a local wrapper script, so that they need not be exposed to users. See this link for an example of such a script. Our examples then simplify to just this short command:
$ cc tsqrt.c && ./a.out
On all supported platforms, the MathCW library is built and installed both as a static library (libmcw.a on most Unix platforms), and as a shared object library (usually libmcw.so).
On most Unix systems, the shared library is needed for dynamic linking from C as well as from other languages and tools (e.g., hoc).
The MathCW Library code took several years to develop, and has been tested on many different Unix platforms, and occasionally, also on Microsoft Windows under Cygwin. The code is now considered stable, and no changes are expected in the prototypes of any existing library function. It is possible that additional library functions will be included in the future, but that is unlikely to happen soon. All code that uses the supplied header files should be completely insulated from such future additions. Similarly, programs linked against a current version of the MathCW shared library will run unchanged when a new version of the shared library is installed.
There are many manual page files, and to prevent collisions with existing manual pages, they are installed in subdirectories man3cw, cat3cw, html3cw, and ps3cw. You can view them like this:
$ man -s 3cw sqrt # usual manual page viewer
$ gv /usr/local/man/ps3cw/sqrt.ps # view PostScript
$ lpr /usr/local/man/ps3cw/sqrt.ps # print PostScript
$ lynx /usr/local/man/html3cw/sqrt.html # view with Web browser
$ less /usr/local/man/cat3cw/sqrt.txt # browse the formatted pages
There is a public mailing list for discussions of the MathCW library and the tools available at its Web site. Visit http://mail.math.utah.edu/mailman/listinfo/mathcw to subscribe or to view list archives.
For an indeterminate initial period, list postings are moderated and subject to approval before appearing in the on-line archives.
The MathCW Library is licensed under the GNU Lesser General Public License.
NHFB, New directions in floating-point arithmetic, in Theodore E. Simos and George Maroulis (eds.), Computation in Modern Science and Engineering: Proceedings of the [Fifth] International Conference on Computational Methods in Science and Engineering 2007 (ICCMSE 2007), Corfu, Greece, 25--30 September 2007, 2A, pp. 155--158. American Institute of Physics (2007). ISBN 0-7354-0476-3 (set), 0-7354-0477-1 (vol. 1), 0-7354-0478-X (vol. 2). URL http://www.springer.com/physics/atoms/book/978-0-7354-0478-6.
NHFB, A new math library, International Journal of Quantum Chemistry 109(13) 3008--3025, 5 November 2009. CODEN IJQCB2. ISSN 0020-7608 (print), 1097-461X (electronic). DOI http://dx.doi.org/10.1002/qua.22266.
Library source code will be released when a large book that documents it is published. At the time of writing this, that date is still uncertain, but might be in late 2010.