### mapm-3.85 README file

    **************************************************************************

    				   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.

    **************************************************************************