================================================================================
 File: README for pi
 Author: Chee and Chen Li (June 2000)
 Since CORE Library version 1.2
	$Id: README,v 1.8 2004/11/12 21:59:18 exact Exp $
================================================================================
SYNOPSIS:
	% make		-- makes the executable "newPi"
	% newPi 6644 2	-- computes Pi to 6644 bits (=2000 digits) of accuracy
				using Brent's algorithm, implemented using BigFloat
			   NOTE: 6644 = 2000 * log_2(10).
	% newPi 6644 1	-- computes Pi to 2000 digits using Machin's formula
				implemented using BigFloat

        % make more	-- makes the executable "pi" and "brent"
	% pi 123	-- computes Pi to 123 bits of accuracy
				and sqrt(Pi) to 121 bits of accuracy
        % pi 6644 	-- computes Pi to 6644 bits (=2000 digits) of accuracy
				and sqrt(Pi) to 6642 bits of accuracy
			   	NOTE: 6644 = 2000 * log_2(10).
	% pi 6644 0	-- same as above, but do not compute sqrt(Pi)
			   	Default for second argument is "1")
	% pi 6644 0 2	-- same as above, except self validation of Pi is
				to 2000 digits instead of 250 digits.
				Default for third argument is "1"
	% brent 6644 1	-- to compute Pi to 2000 digits using Brent's algorithm
				implemented using Expr (slow version)

Files in this directory:
	README		-- This file
	Makefile	-- Assumes the current directory is $(CORE)/progs/pi
	pi.cpp 		-- Computes Pi using Machin's formula.
	newPi.cpp 	-- Computes Pi using various algorithms
				(improved Brent's or improved Machin's)
	brent.cpp	-- Brent's algorithm for Pi (original Brent implementation)
	PI2000.html	-- A source for 2000 digits of Pi
	inputs/{PI2000, PI250, ...}	-- Pi to 2000 digits, etc.
================================================================================

INTRODUCTION:

We implement Machin's formula for computing
	Pi = 3.14159265358979323846264338327950288419716939937510582097494459...
to any desired precision.  It serves to check the correctness of 
Core library's numerical outputs and its precision mechanism.
Here is Machin's well-known formula:

    pi/4  = 4 arctan(1/5) - arctan(1/239)
          = \sum_{k=0} ^\infty  (-1)^k
                [   4 / ( (2k +1) 5^{2k+1} )
                  - 1 / ( (2k +1) 239^{2k+1} )  ]

Timing: Using this formula, a Sun Ultra 10 (440 MHz, 256 MB RAM) can 
compute Pi to 2000 digits (=6644 bits) in about 1.51 seconds (using
CORE Version 1.2).   You can get duplicate this timing by running 
the current program with the command arguments

	% pi 6644 0 0
	% pi 10000 0 0	-- this takes 3.24 seconds to compute 3010 digits
	

In some formulas (e.g., for erf(x)), there is also a need for high precision
values of sqrt(Pi).  The program also outputs sqrt(Pi).

NOTE: we include automatic self-verification of the computed values
of Pi up to 250 digits, and sqrt(Pi) up to 100 digits.

=================================================================
BUG REPORT: for some reason, pi does not work correctly on
cygwin platforms for n > 4195 bits.  Actually, this upper bound
seems to vary depending on machines.

4/4/2002, UPDATE: This is not a bug, but a stack overflow problem.  
Please read the file "stackOverflow.txt" found under $(CORE_PATH)/doc
for details on how to fix it.
=================================================================

July, 2002: On Brent's algorithm for Pi:
We also implemented Brent's algorithm for Pi.
Theoretically, this is supposed to be extremely fast (Newton convergence).
But for some reason, it is much slower than the above Machin's formula.
For instance, on Solaris SunBlade 1000 (2x Ultrasparc III 750MHz,
8MB Cache, 2GB Memory), we obtain the following times:
	time pi 10000 0 0: 0.74 seconds	
	time brent 10000 0 0: 19.12 seconds	

Sep, 2002: Update on timing Brent's timing
	New improvements after CORE 1.5 has made Brent's
	algorithm competitive with Machin's formula.  Still,
	more improvements should be expected.
=================================================================
Oct, 2004: 
     We can speed this up with one of two approaches:
	(1) reduce to rational (if using Expr)
	(2) use BigFloats instead of Expr
     In newPi.cpp, we implemented (2), and this gives significant speedup
     (much faster than Maple).  
     We also reimplemented Machin's formula in newPi.cpp, but now
     we use binary split to compute arctan(1/x) where x is a bigInt.
     This greatly speeds up Machin as well.
     The BigFloat version of Brent is a great improvement over the
     old Machin's algorithm, but is still inferior to the improved
     Machin's formula!

     Using the same Solaris SunBlade as above to compute to
     100,000 bits (30102 digits) (timing does not include printout of digits).

	Test			Time		Comment
	====			=====		=======
	newPi 100000 0		3.35 sec	Machin's formula using binary split
	newPi 100000 1		33.3 sec	Brent's algorithm using bigFloat
	pi    100000 0 0	segment fault	Original implementation of Machin's.

=================================================================
