readme

任意精度的数学库

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


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, 
 *   even 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.
 *
 *   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);

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

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
HP-UX Ver 9.x and 10.x
SunOS 5.5.1  (output from uname)
DOS 5.0 using Microsoft C 5.1 and 8.00c
DOS 5.0 using GCC for DOS

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.

     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.
  
     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.

**************************************************************************
  
     NOTE:     If you ever see the following :

     "Warning! m_apm_## : Desired decimal places exceeds accuracy of constant"

	       Some of the functions use canned 'contants'. For example, 
	       to compute the sine of angle it may be more efficent (for 
	       speed reasons) to compute the cosine of the angle offset 
	       by PI/2 radians. The library needs to know PI/2 to at least
	       the number of digits you specify. If you ask for more decimal
	       places than the canned constants, you will get the above
	       warning. The constants in the library are all 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. The number of significant digits
	       in the constants should be 6-8 more than the value specified
	       in the #define. 

	       [Version 1.10 Update : Since the SIN/COS functions have 
	       been redesigned, the above example is no longer valid. 
	       However, the concept in general is still valid, though 
	       it now mainly applies to the LOG/POW functions.]
	       
	       You will only get the warning if a particular function uses 
	       a canned constant. 

	       PI = 6 * arcsin(0.5)      Good for any precision
	       PI = 4 * arctan(1.0)      Good for any precision
	       PI = 3 * arccos(0.5)      Good for any precision

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