readme

任意精度的数学库

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

				   MAPM 

			       Version  2.10

			    September 24,  1999

			      Michael C. Ring

			    [e-mail]

**************************************************************************
*                                                                        *
* Copyright (C) 1999   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. *
**************************************************************************

--------------------
MAPM Library History
--------------------

V 1.00  -  June 1, 1999    Initial Release

V 1.10  -  June 20, 1999   Use a stack implementation for local M_APM
			   variables instead of static variables.

			   Use a new faster algorithm for SIN & COS.

V 1.20  -  July 10, 1999   Improve the algorithm for ARCSIN and ARCCOS
			   when the input argument is near 1.0.

			   Added the 'DUP' operator to the 'calc' demo
			   program.

V 1.30  -  July 31, 1999   Added a function to output M_APM values as 
			   integers.

			   Supply another demo program which generates 
			   prime numbers (and uses the integer output
			   format).

			   Improved the 4 iterative routines, dynamically
			   adjusting the local precision each time through
			   the loop. Also changed the tolerance test to 
			   use integers (vs a MAPM number).

V 2.00  -  Aug 15, 1999    Added a 'fast' multiplication algorithm.

V 2.10  -  Sep 24, 1999    Added integer POW function.  Compute X^Y when
			   'Y' is an integer.

			   Added a random number generator (with a period
			   of 1.0E+15).

			   Added function to compute both sin and cos with 
			   one call.

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

	        ---------------------------------------
       	        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, SIN, COS, TAN, ARC-SIN, ARC-COS, ARC-TAN, ARC-TAN2, LOG, LOG10,
   EXP, POW, 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.


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

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

IF YOU ARE IN A HURRY ...

UNIX:  (assumes gcc compiler)

run:   mklib         (this will create the library, lib_mapm.a)

run:   mkdemo        (this will create 3 executables, 'calc', 'validate',
                      and 'primenum')

DOS:
       Depends on your compiler. 

       GCC for DOS:    run  dos\mkallgcc.bat  (builds library + 3 executables)

       Microsoft C 8.00c   run  dos\mklibmsc.bat       (builds library)
       Microsoft C 5.1     run  dos\mklibm51.bat       (builds library)
       Both (5.1 & 8.00c)  run  dos\mkdemo.bat         (builds 3 executables)
       

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 20 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.97762225420560747664E+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 150000 will output (actually 1 per line):

           150001, 150011, 150041, 150053, 150061, 
	   150067, 150077, 150083, 150089, 150091

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

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 considerably 
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 now 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, maybe some could 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.