************************************************************************** MAPM Version 3.85 April 2, 2001 Michael C. Ring ringx004@tc.umn.edu Latest release will be available at http://tc.umn.edu/~ringx004 ************************************************************************** * * * Copyright (C) 1999 - 2001 Michael C. Ring * * * * This software is Freeware. * * * * Permission to use, copy, and distribute this software and its * * documentation for any purpose with or without fee is hereby granted, * * provided that the above copyright notice appear in all copies and * * that both that copyright notice and this permission notice appear * * in supporting documentation. * * * * Permission to modify the software is granted, but not the right to * * distribute the modified code. Modifications are to be distributed * * as patches to released version. * * * * This software is provided "as is" without express or implied warranty. * * * ************************************************************************** --------------------------------------- Mike's Arbitrary Precision Math Library --------------------------------------- Mike's Arbitrary Precision Math Library is a set of functions that allow the user to perform math to any level of accuracy that is desired. The inspiration for this library was Lloyd Zusman's similar APM package that was released in ~1988. I borrowed some of his ideas in my implementation, creating a new data type (MAPM) and how the data type was used by the user. However, there were a few things I wanted my library to do that the original library did not : 1) Round a value to any desired precision. This is very handy when multiplying for many iterations. Since multiplication guarantees an exact result, the number of digits will grow without bound. I wanted a way to trim the number of significant digits that were retained. 2) A natural support for floating point values. From most of the other libraries I looked at, they seem to have a preference for integer only type math manipulations. This library will also do integer only math if you desire. And if a library can only do integers, it can't do ... 3) Trig functions and other common C math library functions. This library will perform the following functions to any desired precision level : SQRT, CBRT, SIN, COS, TAN, ARC-SIN, ARC-COS, ARC-TAN, ARC-TAN2, LOG, LOG10, EXP, POW, SINH, COSH, TANH, ARC-SINH, ARC-COSH, ARC-TANH, and also FACTORIAL. The full 'math.h' is not duplicated, though I think these are most of the important ones. My definition of what's important is what I've actually used in a real application. NOTE: MAPM Library History can now be found in 'history.txt' (I really wasn't sure what to call this library. 'Arbitrary Precision Math' is a defacto standard for what this does, but that name was already taken, so I just put an 'M' in front of it ...) ************************************************************************** KNOWN BUGS : None ************************************************************************** IF YOU ARE IN A HURRY ... UNIX: (assumes gcc compiler) run make (build library + 3 executables) --- OR --- run: mklib (this will create the library, lib_mapm.a) run: mkdemo (this will create 3 executables, 'calc', 'validate', and 'primenum') DOS / Win NT/9x (in a DOS window for NT/9x): see the file 'README.DOS' for instructions. ************************************************************************** calc: This is a command line version of an RPN calculator. If you are familiar with RPN calculators, the use of this program will be quite obvious. The default is 30 decimal places but this can be changed with the '-d' command line option. This is not an interactive program, it just computes an expression from the command line. Run 'calc' with no arguments to get a list of the operators. compute : (345.2 * 87.33) - (11.88 / 3.21E-2) calc 345.2 87.33 x 11.88 3.21E-2 / - result: [2.977622254205607476635514018692E+4] compute PI to 70 decimal places : (6 * arcsin(0.5)) calc -d70 6 .5 as x result : 3.1415926535897932384626433832795028841971693993751058209749445923078164E+0 validate : This program will compare the MAPM math functions to the C standard library functions, like sqrt, sin, exp, etc. This should give the user a good idea that the library is operating correctly. The program will also compute some known quantities to 70 digits of precision, like PI, log(2), etc. There was nothing special about '70' other than that number of digits fit nicely on one line. primenum: This program will generate the first 10 prime numbers starting with the number entered as an argument. Example: primenum 1234567890 will output (actually 1 per line): this took ~5 sec on my PC, a 350MHz PII. 1234567891, 1234567907, 1234567913, 1234567927, 1234567949, 1234567967, 1234567981, 1234568021, 1234568029, 1234568047 ************************************************************************** To use the library, simply include 'm_apm.h' and link your program with the library, lib_mapm.a (unix) or lib_mapm.lib (dos). For unix builds, you also may need to specify the math library (-lm) when linking. The reason is some of the MAPM functions use an iterative algorithm. When you use an iterative solution, you have to supply an initial guess. I use the standard math library to generate this initial guess. I debated whether this library should be stand-alone, i.e. generate it's own initial guesses with some algorithm. In the end, I decided using the standard math library would not be a big inconvienence and also it was just too tempting having an immediate 15 digits of precision. When you prime the iterative routines with 15 accurate digits, the MAPM functions converge faster. See the file 'algorithms.used' to see a description of the algorithms I used in the library. Some I derived on my own, others I borrowed from people smarter than me. Version 2 of the library supports a 'fast' multiplication algorithm. The algorithm used is described in the algorithms.used file. A considerable amount of time went into finding fast algorithms for the library. However, some could possibly be even better. If anyone has a more efficient algorithm for any of these functions, I would like to here from you. See the file 'function.ref' to see a description of all the functions in the library and the calling conventions, prototypes, etc. See the file 'struct.ref' which documents how I store the numbers internally in the MAPM data structure. This will not be needed for normal use, but it will be very useful if you need to change/add to the existing library. ************************************************************************** QUICK TEMPLATE FOR NORMAL USE : The MAPM math is done on a new data type called "M_APM". This is actually a pointer to a structure, but the contents of the structure should never be manipulated: all operations on MAPM entities are done through a functional interface. The MAPM routines will automatically allocate enough space in their results to hold the proper number of digits. The caller must initialize all MAPM values before the routines can operate on them (including the values intended to contain results of calculations). Once this initialization is done, the user never needs to worry about resizing the MAPM values, as this is handled inside the MAPM routines and is totally invisible to the user. The result of a MAPM operation cannot be one of the other MAPM operands. If you want this to be the case, you must put the result into a temporary variable and then assign (m_apm_copy) it to the appropriate operand. All of the MAPM math functions begin with m_apm_*. There are some predefined constants for your use. In case it's not obvious, these should never appear as a 'result' parameter in a function call. The following constants are available : (declared in m_apm.h) MM_Zero MM_One MM_Two MM_Three MM_Four MM_Five MM_Ten MM_PI MM_HALF_PI MM_2_PI MM_E MM_LOG_E_BASE_10 MM_LOG_10_BASE_E MM_LOG_2_BASE_E MM_LOG_3_BASE_E The non-integer constants above (PI, log(2), etc) are accurate to 128 decimal places. The file mapmcnst.c contains these constants. I've included 512 digit constants in this file also that are commented out. If you need more than 512 digits, you can simply use the 'calc' program to generate more precise constants (or create more precise constants at run-time in your app). The number of significant digits in the constants should be 6-8 more than the value specified in the #define. Basic plan of attack: (1) get your 'numbers' into M_APM format. (2) do your high precision math. (3) get the M_APM numbers back into a format you can use. -------- (1) -------- #include "m_apm.h" /* must be included before any M_APM 'declares' */ M_APM area_mapm; /* declare your variables */ M_APM tmp_mapm; M_APM array_mapm[10]; /* can use normal array notation */ M_APM array2d_mapm[10][10]; area_mapm = m_apm_init() /* init your variables */ tmp_mapm = m_apm_init(); for (i=0; i < M; i++) /* must init every element of the array */ array_mapm[i] = m_apm_init(); for (i=0; i < M; i++) for (j=0; j < N; j++) array2d_mapm[i][j] = m_apm_init(); /* * there are 3 ways to convert your number into an M_APM * (see the file function.ref) * * a) literal string (exponential notation OK) * b) long variable * c) double variable */ m_apm_set_string(tmp_mapm, "5.3286E-7"); m_apm_set_long(array_mapm[6], -872253L); m_apm_set_double(array2d_mapm[3][7], -529.4486711); -------- (2) -------- do your math ... m_apm_add(cc_mapm, aa_mapm, MM_PI); m_apm_divide(bb_mapm, DECIMAL_PLACES, aa_mapm, MM_LOG_2_BASE_E); m_apm_sin(bb_mapm, DECIMAL_PLACES, aa_mapm); whatever ... /* * There are 2 functions for converting an M_APM number into * something useful. (SEE THE FILE 'function.ref') * * For both functions, M_APM number -> string is the conversion * * =================== * ==== METHOD 1 ==== : Meant for use with floating point values * =================== * * the format will be in scientific (exponential) notation * * output string = [-]n.nnnnnE+x or ...E-x * * where 'n' are digits and the exponent will be always be present, * including E+0 * * it's easy to convert this to a double: * * double dtmp = atof(out_buffer); * * * =================== * ==== METHOD 2 ==== : Meant for use with integer values * =================== * * the format will simply be digits with a possible leading '-' sign. * * output string = [-]nnnnnn * * where 'n' are digits. * * it's easy to convert this to a long : * long mtmp = atol(out_buffer); * * ... or an int : * int itmp = atoi(out_buffer); * * Note that if the M_APM number has a fractional portion, the fraction * will be truncated and only the integer portion will be output. */ -------- (3) -------- char out_buffer[256]; m_apm_to_string(out_buffer, DECIMAL_PLACES, mapm_number); m_apm_to_integer_string(out_buffer, mapm_number); ************************************************************************** MAPM C++ WRAPPER CLASS: Orion Sky Lawlor (olawlor@acm.org) has added a very nice C++ wrapper class to m_apm.h. This C++ class will have no effect if you just use a normal C compiler. The library will operate as before with no user impacts. For now, I recommend compiling the library as 'C'. In order to compile the library as C++, all the function declarations will need to be updated. This may or may not happen in the near future. Since the C++ wrapper class works very nicely as is, there is no pressing need to update the entire library yet. See the file 'cpp_function.ref' to see a description of how to use the MAPM class. To compile and link the C++ demo program: (assuming the library is already built) UNIX: g++ cpp_demo.cpp lib_mapm.a -s -o cpp_demo -lm GCC for DOS: (gxx is the C++ compiler) gxx cpp_demo.cpp lib_mapm.a -s -o cpp_demo.exe -lm Using the C++ wrapper allows you to do things like: // Compute the factorial of the integer n MAPM factorial(MAPM n) { MAPM i; MAPM product = 1; for (i=2; i <= n; i++) product *= i; return product; } The syntax is the same as if you were just writing normal code, but all the computations will be performed with the high precision math library, using the new 'datatype' MAPM. The default precision of the computations is as follows: Addition, subtraction, and multiplication will maintain ALL significant digits. All other operations (divide, sin, etc) will use the following rules: 1) if the operation uses only one input value [y = sin(x)], the result 'y' will be the same precision as 'x', with a minimum of 30 digits if 'x' is less than 30 digits. 2) if the operation uses two input values [z = atan2(y,x)], the result 'z' will be the max digits of 'x' or 'y' with a minimum of 30. The default precision is 30 digits. You can change the precision at any time with the function 'm_apm_cpp_precision'. (See function.ref) ----> m_apm_cpp_precision(80); will result in all operations being accurate to a minimum of 80 significant digits. If any operand contains more than the minimum number of digits, then the result will contain the max number of digits of the operands. NOTE!: Some real life use with the C++ wrapper has revealed a certain tendency for a program to become quite slow after many iterations (like in a for/while loop). After a little debug, the reason became clear. Remember that multiplication will maintain ALL significant digits : 20 digit number x 20 digit number = 40 digits 40 digit number x 40 digit number = 80 digits 80 digit number x 80 digit number = 160 digits etc. So after numerous iterations, the number of significant digits was growing without bound. The easy way to fix the problem is to simply *round* your result after a multiply or some other complex operation. For example: #define MAX_DIGITS 256 p1 = (p0 * sin(b1) * exp(1 + u1)) / sqrt(1 + b1); p1 = p1.round(MAX_DIGITS); If you 'round' as shown here, your program will likely be nearly as fast as a straight 'C' version. If you have any questions or problems with the C++ wrapper, please let me know. I am not very C++ proficient, but I'd still like to know about any problems. Orion Sky Lawlor (olawlor@acm.org) is the one who implemented the MAPM class, so he'll have to resolve any real hardcore problems, if you have any. ************************************************************************** TESTING : Testing the library was interesting. How do I know it's right? Since I test the library against the standard C runtime math library (see below) I have high confidence that the MAPM library is giving correct results. The logic here is the basic algorithms are independent of the number of digits calculated, more digits just takes longer. The MAPM library has been tested in the following environments : Linux i486 / gcc 2.7.2.3 Linux i686 / gcc 2.91.66 FreeBSD 4.1 / gcc 2.95.1 HP-UX 9.x /gcc 2.5.8 HP-UX 10.x / gcc 2.95.2 Sun 5.5.1 (output from uname) Sun Solaris 2.6 / gcc 2.95.1 DOS 5.0 using Microsoft C 5.1 and 8.00c (16 bit EXEs) DOS 5.0 using GCC 2.8.1 for DOS DOS 5.0 using GCC 2.95.2 for DOS DOS ??? using Borland Turbo C++ 3.0 WIN NT+SP5 using Borland C++ 5.02 IDE, 5.2 & 5.5 command line. WIN98 using Borland C++ 5.5 command line. WIN98 & NT using LCC-WIN32 Ver 3.2 WIN98 & NT using Microsoft Visual C++ 6.0 As a general rule, when calculating a quantity to a given number of decimal places, I calculated 4-6 extra digits and then rounded the result to what was asked for. I decided to be conservative and give a correct answer rather than to be faster and possibly have the last 2-3 digits in error. Also, some of the functions call other functions (calculating arc-cos will call cos, log will call exp, etc.) so I had to calculate a few extra digits in each iteration to guarantee the loops terminated correctly. 1) I debugged the 4 basic math operations. I threw numerous test cases at each of the operations until I knew they were correct. Also note that the math.h type functions all call the 4 basic operations numerous times. So if all the math.h functions work, it is highly probable the 4 basic math operations work also. 2) 'math.h' type functions. SQRT: Not real hard to check. Single stepping through the iterative loop showed it was always converging to the sqrt. CBRT: Similar to sqrt, single stepping through the iterative loop showed it was always converging to the cube root. EXP: I wrote a separate algorithm which expanded the Taylor series manually and compared the results against the library. POW: Straightforward since this just calls 'EXP'. LOG: I wrote a separate algorithm which expanded the Taylor series manually and compared the results against the library. This took a long time to execute since the normal series converges VERY slowly for the log function. This is why the LOG function uses an iterative algorithm. LOG10: Straightforward since this just calls 'LOG'. SIN/COS: I wrote a separate algorithm which expanded the Taylor series manually and compared the results against the library. TAN: Straightforward since this just calls 'SIN' and 'COS'. ARC-x: Single stepping through the iterative loop showed the arc family of functions were always converging. Also used these to compute PI. The value of PI is now known to many, many digits. I computed PI to 1000+ digits by computing: 6 * arcsin(0.5) and 4 * arctan(1) and 3 * arccos(0.5) and compared the output to the published 'real' values of PI. The arc family of functions exercise considerable portions of the library. HYPERBOLIC: The hyperbolic functions just use exp, log, and the 4 basic math operations. All of these functions simply use other existing functions in the library. FINALLY: Run the program 'validate'. This program compares the first 13-14 significant digits of the standard C library against the MAPM library. If this program passes, you can feel confident that the MAPM library is giving correct results. This is because the basic algorithms do not change when calculating more digits, it just takes longer. **************************************************************************
