PiFast43 usage
==============

Run PiFast43.exe in a dos window if you are on Windows.
(On unix platforms, launch PiFast33 in a unix shell window.
You may type chmod +x PiFast33 before running it on unix).


0. First specify the menu item you want to use :
   [0] To compute Pi with the Chudnovsky formula. This Pi computation method is the
       fastest.
   [1] To compute Pi with the Ramanujan formula. This second mode is here for
       verification and is ~40% slower than mode [0]. 
   [2] To compute E with the exponential series 1+1/1!+1/2!+1/3!+...
   [3] To compute E with the inverse of the exponential series 
       1-1/1!+1/2!-1/3!+... [2] and [3] give the same timings and can
       be used together to check a E computation.
   [4] To compute Sqrt(2) (+verification). This item is essentially here to test 
       PiFast on ranges that I cannot reach on my computer. The timings are at 
       least ten times faster compared to the Pi computation.
   [5] To define your own constant formula with hypergeometric series. Your 
       definition is then stored in a .pifast file and can be used to effectively
       compute the constant. See section <Defining a user constant> later in this
       help file for more informations.
   [6] To compute a user constant from a .pifast file.
   [7] When a computation has been completed with a compressed
       output, this menu permits to decompress the corresponding data.
       Decompression can be made only on given digit indexes, or on regular user specified
       ranges. Different output decompression format are also available.
   [8] When a pi computation (option [0] or [1]) have been completed
       with a compressed result, this option rereads the compressed pi
       file and check the result. It makes use of the Fabrice Bellard
       formula which computes directly the n-th bit of pi. The
       verification is several times faster than the direct computation.
 


1. Memory mode
   [0] To make the computation run in the standard mode (no disk memory usage). This mode
       should be used for not too big computations.
   [1] To make the computation run in the basic disk memory mode. The disk memory mode 
       permits to reach a larger number of digits but is slower than
       [0] when the number of digits is not large. For example, on my 128M 
       machine, the best timings for 32 millions digits are obtained
       with the standard mode, and the disk memory mode [1] is faster for 
       64 millions digits. 
       The exact threshold depends on your machine and disk memory access  
       speed.
       This mode does not exists in version 4.1 if you chose the user 
       constant computation [6].
   [2] To make the computation run in the advanced disk memory mode. 
       You should use it if you want to reach a very large number of
       digits. It is asymptotically faster than the mode [1] but more disk
       memory consuming (~twice than mode [1]). 
       The threshold highly depends on the machine. On my
       128M machine, the best timings for 64 millions digits are obtained in
       mode [1], the timings slightly better in mode [2] for 128
       millions digits, much better in mode [2] for 256 millions digits.
       This mode does not exists in version 4.1 if you chose the user 
       constant computation [6].
 
2. Then specify the number of digits wanted (at least 10000). This
   number does not need to be a power of two or whatever. From version 4.3, the number of 
   digits can be specified with classic factors using letters :
   k (x 1000), K (x 1024=2^10), 
   m (x 1,000,000), M (x 1,048,576=2^20), 
   g (x1,000,000,000), G (x1,073,741,824=2^30).
   For example, entering "4M" will compute 4,194,304 digits.

3. Then several possible memory management mode are proposed to you,
   depending on the available physical memory at running time. They 
   correspond to an FFT size expressed in k. Choose the fastest which
   fits in your available physical memory, and enter the corresponding FFT size.

4. Specify if you would like the output to be directly compressed by
   PiFast. If the compressed output mode is choosen, the compressed data
   can be decompressed by running PiFast again with choice [5] in the 
   menu. Different output format are also available while decompressing
   the data. For a pi computation, the compressed output mode permits to run
   pifast again and check your pi computation with the Fabrice Bellard formula.

5. (Disk memory mode with Pi computations only)
   In the disk memory mode, you can achieve your computation in 
   several runs. That means that you can for example run the program
   only during the night or when you do not work on your computer.
   You should specify a time threshold (Tmax) in hours (floating point
   values are valid). The computation stops as soon as the timing since
   the beginning of the run is more than Tmax, at the end of a step
   of the algorithm. Specify a zero value for Tmax if you do not want
   to use this feature.
   The time threshold is not really precise since a complete step must
   be performed before the execution is stopped.
   After a run which has been stopped at some step, a new execution of
   the program detects the existence of a parameter file ("ParamPiFast")
   and automatically continue the computation at the next step. (Do not
   kill the other files "AA", "PP" and "QQ", they are needed to continue
   the execution).
   You must also specify a time threshold for this second execution, that
   can brings you to a third run, etc.
   A timing summary of each of your steps appears as a header in the
   result file pi.txt.
   Trick : entering the time threshold of -1 stops the run at the
   end of the series computation.

The PiFast program has an easy auto-verification for the constants pi and E
(it compares some of the digits computed with some precomputed digits in a table).

NOTE : the amount of disk space specified in the disk memory mode
       takes into account the needed disk space to write the output
       data.

====================
| Execution sample |
====================

(example with version 4.1, in the disk memory huge mode, with compressed output) :


| > C: PiFast41
|
|PiFast, version 4.1 (Copyright 1999-2001 Xavier Gourdon)
|http://numbers.computation.free.fr/Constants/PiProgram/pifast.html
|Menu :
|[0] Compute Pi with Chudnovsky method (Fastest)
|[1] Compute Pi with Ramanujan method
|[2] Compute E by the exponential series exp(1)
|[3] Compute E by the exponential series 1/exp(-1)
|[4] Compute Sqrt(2) (useful for testing)
|[5] Define your constant with hypergeometric series
|[6] Compute a user constant from a .pifast file
|[7] Decompress a result file
|[8] Check a compress result Pi file
|Enter your choice : 0
|
|Choose your computation mode :
|[0] standard mode (no disk memory used)
|[1] basic disk memory mode (for big computations)
|[2] advanced disk memory mode (for huge computations)
|Enter your choice : 2
|
|Number of decimal digits : 1000000
|Possible FFT modes, with approximate needed memory :
|
|FFT Size=  32 k, Mem=1908 K, MemDisk=4395 k (Fastest mode)
|FFT Size=  16 k, Mem=1138 K, MemDisk=4395 k (Time: Fastest mode * 1.1)
|FFT Size=   8 k, Mem=754 K, MemDisk=4395 k (Time: Fastest mode * 1.2)
|FFT Size=   4 k, Mem=561 K, MemDisk=4395 k (Time: Fastest mode * 1.4)
|FFT Size=   2 k, Mem=465 K, MemDisk=4395 k (Time: Fastest mode * 1.9)
|FFT Size=   1 k, Mem=417 K, MemDisk=4395 k (Time: Fastest mode * 2.5)
|...
|
|Enter FFT Size in k :16
|
|Compressed output (also useful to specify output format) ? [0=No, 1=Yes] : 1
|
|In this mode, you can do your computation
|in several runs by entering a time threshold for the current
|run. The next run will start where the current run has stopped.
|Time threshold in hours (0 if single run wanted) : 0
|
|Total Physical Memory Allocated = 1360 Kbytes
|Computing series with index N=70529
|Starting step 4
|Starting step 3 .....
|Starting step 2 .....
|Starting step 1 .....
|Starting step 0 .....
|Series computing time : 26.32
|Inverse :   Done
|Division time : 5.21
|SquareRoot :   Done
|InvSqrt time : 2.46
|Final huge multiplication time : 1.80
|---------------------------------------------------------------
|Computation time of this run : 35.89 seconds
|Total computation time : 35.89 seconds(~ 0.01 hours)
|Writing informations into file pi.txt
|
|The computation seems OK
|Compressing result file ...

To decompress digits between position 999000 and 1000000, rerun PiFast
again, choose mode 7 and you are lead to 

| Decompress :
| [0] The latest Pi compressed file
| [1] The latest E compressed file
| [2] The latest Sqrt2 compressed file
| [3] The latest user constant compressed file
| Enter your choice : 0
| *******************************************************
| 
| Decompressing Pi file
| 
| ===========================
| |      OUTPUT FILE        |
| ===========================
| 
| Output [0=standard output, 1=file] : 0
| ===========================
| |       DIGITS RANGE      |
| ===========================
| 
| The file contains 1000000 decimal digits.
| All digits [0], range specification [1], x digits every y digits [2] ? : 1
| Enter start index of digit : 999000
| Enter end index of digit : 1000000
| ===========================
| |      OUTPUT FORMAT      |
| ===========================
| 
| Enter output format [0=Default, 1=Custom] : 0
| 
| ++++++++++++++++++++++++++++++++++++++++++++++++++
| 
| Pi digits between digit 999001 and digit 1000000
| 3036010723 4368901360 6427581425 2839878594 9179979611  : 999050
| 2196379757 6519245218 6709608809 2137111977 5000878159  : 999100
| 3043072934 4883930957 5741592413 7528597779 7291893453  : 999150
| 8505080383 1986774590 0251865791 7237080857 4164297153  : 999200
| 8078840607 1306868036 1982419715 7747638950 7253468404  : 999250
| 5691927595 3193722370 2229015580 0656076047 3854735990  : 999300
| 4477996748 7499697694 2713766869 5533195125 3377640985  : 999350
| 8709668386 3263926164 9456086841 4037456842 0719405950  : 999400
| 7017430354 6918215090 0466493998 5517413893 8519757312  : 999450
| 1568261622 8622318810 9672974760 6013028331 1937161140  : 999500
| 8747270676 2558567775 1199566674 8615196491 2970193318  : 999550
| 0849941096 1813929649 2789360902 1253544332 7375064260  : 999600
| 6242994120 3273625582 4417498345 0947309453 4366159072  : 999650
| 8416319368 3075719798 0682315357 3715557181 6122156787  : 999700
| 9364250138 8711702327 5555779302 2667858031 9993081083  : 999750
| 0576307652 3320507400 1393909580 7901637717 6292592837  : 999800
| 6487479017 7274125678 1905555621 8050487674 6991140839  : 999850
| 9779193765 4232062337 4717324703 3697633579 2589151526  : 999900
| 0315614033 3212728491 9441843715 0696552087 5424505989  : 999950
| 5678796130 3311646283 9963464604 2209010610 5779458151  : 1000000


============================
| Defining a user constant |
============================

From version 4.1, PiFast can be used to compute your own constant with
your own formula (see section <Formula and algorithm used>, paragraph
"User constant computation" in the doc.txt file). 
You should first define your constant by choosing mode [5] in the main 
menu. Your definition is stored in a file with the suffix .pifast, and
you can compute it as many times as you want by running PiFast again
and choosing mode [6].

A user constant is a finite linear combination of the form

  C = beta_0 * H_0 + beta_1 * H_1 + ...

where beta_0, beta_1, ... are rational integer p/q,
and   H_0, H_1, ... some hypergeometric series. 
The H_i can be one of the predefined series

  arctan(Z), arctanh(Z) or log(1/(1-Z)), 
 
or can be specified in a general way in one of the two forms :

  alpha + beta * sum_{n>=1}  F(i)/G(i) * Z^i                      (1)
  alpha + beta * sum_{n>=1} [ prod_{1<=i<=n} (F(i)/G(i)) ] Z^i    (2)

Once the item [5] has been choosen in the main menu, you should :
* Enter the constant name,
* Enter your comments associated to the constant (like the formula in a 
  mathematical form, the name and date of the formula, your name ...).
  To end the comments input, just type <RETURN>,  then <.> (the character "dot"),
  then <RETURN>.
* Enter the number N of terms in your constant defined as 

    C = sum_{0<=i<N} beta_i * H_i    (*)

  If your formula only contains 1 hypergeometric function, just type 1.
* Then repeat N times the following :
  () enter the value of the coefficient beta_i of the i-th term of (*).
     beta_i can be either an integer, or a fraction (enter the fraction in
     the form p/q, like 101/1001 for example). Negative values are allowed.
     The values p and q in beta_i = p/q should be not too large (8 digits at most).
  () choose the hypergeometric series type, either a general hypergeometric series
     defined after (choice [0]), or a predefined hypergeometric series like
     arctan(Z), arctanh(Z) or log(1/(1-Z)).
  () if you chose a predefined series, enter the rational integer parameter Z
     just as you entered beta_i. Negative values are allowed, and unlike
     beta_i, Z has no size limitation.
  () if you chose a general hypergeometric series, chose your definition mode
     [0] : alpha + beta * sum_{n>=1}  F(n)/G(n) * Z^n
     [1] : alpha + beta * sum_{n>=1} [ prod_{1<=i<=n} (F(i)/G(i)) ] Z^n
     Then enter 
     + the rational integers alpha and beta (no size limitation),
     + the expression for the polynomial F(n) with integer coefficients. PiFast 
       includes a specific syntaxic analyser, so that you can enter your polynomial
       from its formula (like in a computer algebra system). The indeterminate is the
       character 'n', positive power are accepted (fractions not allowed) and the
       character '*' can be omitted between a number and another expression. 
       There is no size limitation in the numbers.
       syntaxic examples : 

               1+2n*(2n+1)^2-n^6
               n+n^2+13565*(n^2+1)^10
               
     + the expression for the polynomial G(n),
     + the rational integer Z, in the form p/q (no size limitation).
     
     A check is then performed to see if your hypergeometric series is valid :
       . It should be geometrically convergent,
       . in the definition mode [1], F and G should have same degree.
     No simplification is done by PiFast so you should simplify by yourself
     the formula to have maximum efficiency.

* Once your formula is defined, you should enter a file name to save your definition.
  The suffix .pifast will be automatically added to your file name. The file name
  can be different from the constant name.
* Your constant definition is then saved in your specified file and the program
  exits.

You will be able to compute your constant from your definition by running PiFast 
again, choosing mode [6] in the main menu, and entering your file name (.pifast 
suffix can be omitted). Some predefined .pifast files can also be found from 
the page http://numbers.computation.free.fr/Constants/PiProgram/pifast.html

The constant definition can be quite laborious but is done only once. The
.pifast file can also be modified directly (be careful to let the 
<RETURN>.<RETURN> at the end of the comment part).

==============================
| Constant definition sample |
==============================

As an example, we define the user constant from a well known Euler formula

                     ----                
              /      \     2^n * (n!)^2  \   
   Pi = 2 *  (  1 +  /    -------------   )   
              \      ----    (2n+1)!     /   
                     n>=1                      

For maximum efficiency, we first simplify this formula to 

                     ----                
              /      \           n!        \   
   Pi = 2 *  (  1 +  /    ----------------  )   
              \      ----  3*5*...*(2n+1)  /   
                     n>=1                      
 
Then run PiFast41, choose mode [5] and we are lead to 


|          ************************************
|          *                                  *
|          *      User constant definition    *
|          *    (see help.txt file for help)  *
|          *                                  *
|          ************************************
|
|Enter the constant name : Pi_Euler
|Comments (type <RETURN>.<RETURN> to end) :
|Pi formula from Euler :
|
|    Pi = 2 * [ 1 + sum_{n>0} 2^n*(n!)^2/(2n+1)! ]
|.
|
|The constant is defined in the form :
|Pi_Euler =  sum_{0<=i<N} beta_i * H_i
|where beta_i are fractions are H_i hypergeometric series
|
|Enter the number N of functions : 1
|
|Enter beta_0 : 2
|************ hypergeometric series H_0 ************
|Enter your series type :
|[0] : General hypergeometric series
|[1] : arctan(Z)  = Z - Z^3/3 + Z^5/5 ...
|[2] : arctanh(Z) = Z + Z^3/3 + Z^5/5 ...
|[3] : log 1/(1-Z) = Z + Z^2/2 + Z^3/3 ...
|Enter your choice : 0
|Choose your hypergeometric series definition mode :
|[0] : alpha + beta * sum_{n>=1}  F(n)/G(n) * Z^n
|[1] : alpha + beta * sum_{n>=1} [ prod_{1<=i<=n} (F(i)/G(i)) ] Z^n
|Enter your definition mode : 1
|Enter alpha : 1
|Enter beta : 1
|Enter expression for polynomial F : n
|Enter expression for polynomial G : 2n+1
|Enter Z : 1
|Your series is well defined, it converges like (1/2.000000)^n
|Approximate value is H ~ 1.570796326795
|Approximate value : Pi_Euler = 3.141593
|
|You have defined a user constant. You must save it to a file,
|and reload it for each computation.
|File name (suffix .pifast will be automatically added) : Pi_Euler_Sample
|File Pi_Euler_Sample.pifast saved.