QuickPi v4.5 Documentation
Copyright (c) 2000-2008 S. Pagliarulo

HOW TO USE THIS DOCUMENT

To properly view this document in Notepad, maximize the Notepad window and 
make sure a fixed-width font such as Courier is selected.  To print this 
document, open it in Notepad or any other word processor and select Print from 
the File menu.

INSTALLATION

Installation of QuickPi is easy.  Simply unzip the QPI45.ZIP file in the 
directory of your choosing.  No changes are made to the Windows registry or 
any other part of the system.  QuickPi is intended for use on Windows XP or 
Windows Vista with a Pentium 4 or newer processor.  The 64-bit (x64) version 
of QuickPi requires Windows x64 edition and an AMD processor with AMD64 
instruction set or an Intel processor with EM64T technology (Intel 64).

DISTRIBUTION NOTES

The files that comprise the QPI45.ZIP file including the QPI v4.5 executable 
are freely available for distribution.  If you plan to distribute QuickPi 
online, you must distribute the entire file set as originally received and not 
the individual files.


-----------------
QUICKPI OVERVIEW

QuickPi is designed to quickly compute Pi to a very high precision.  The 
program is one of the fastest available on the Windows platform.  In addition 
to its speed, QuickPi offers 6 different methods for computing Pi and can also 
compute other constants such as e and the square root of 2 with equal 
precision and speed.

USAGE INFORMATION

QuickPi is a command line program and as such you will need to start a Command 
Prompt window to use it.  Refer to your Windows help guide for information on 
how to start a Command Prompt window.

Once a Command Prompt window has been started, be sure the QuickPi application 
QPI.EXE (or QPI64.EXE) is located in your system path.  If it's not, then 
change the current working directory to that chosen when the program was first 
installed.  Again, refer to your Windows help guide for information on PATHs 
and the CHDIR command.

Entering QPI on the command line without any parameters will produce the 
following information:


QPI-QuickPi v4.5, (c) 2000-2008 S. Pagliarulo
Freely distributable, email: s_pagliarulo@hotmail.com

usage: qpi digits[k|m|g] [destfile] [options|-h]


Information in square brackets [] is optional.  Items separated by a vertical 
bar | indicate an either-or choice.  The k, m and g suffix following "digits" 
allows you to specify kilo (1,024), mega (1,048,576) or giga (1,073,741,824) 
digits respectively.  Other suffixes include th, mi, and bi for a thousand 
(1,000), million (1,000,000) or billion (1,000,000,000) digits respectively.  
For example, to specify 1,000,000 digits of pi, enter:

  qpi 1mi

The output will be sent to the console screen.  To save the output to a text 
file, simply specify a destination file name following the digits 
specification:

  qpi 1mi pi.txt

This will save the output to the file "pi.txt" as well as providing progress 
information to the console screen.  Note, the output of QuickPi 4.5 can also 
be "redirected" with the > operator.  In this case however, no progress 
information will be provided to the console screen.

Entering QPI on the command line with the -h option will produce the following 
help information: 

                               -OPTIONS-

           -PI COMPUTATION-                    -OTHER CONSTANTS-
 -agm[1|2|3]  AGM methods (1,2,3)       -e, -exp    natural log base, e
 -borwein     Borweins' quartic         -2, -sqrt2  Pythagoras' constant
 -chudnovsky  Chudnovskys' method       -phi        golden mean
 -ramanujan   Ramanujan's method        -zeta3      Apery's constant
 -machin      Machin's arctan formula   -gamma      Euler's constant
 -stormer     Stormer arctan formula    -catalan    Catalan's constant
                                        -ln(n)      natural log of (n)
                                        -sqrt(n)    square root of (n)
                                        -cbrt(n)    cube root of (n)

                            -OUTPUT FORMAT-
 -fancy:dpc,dpr,   dpc - digits per column [default=10]
        dpb,bs,dc, dpr - digits per row    [default=50]
        fl         dpb - digits per block  [default=500]
                   bs  - block spacing     [default=1]
                   dc  - digit counting (none,row,block,line) [default=row]
                   fl  - flags (noindent,indent) [default=noindent]

                             -COMPUTATION-
 -formula<n>     use alternate formula (1-n) for computation
 -inverse        compute multiplicative inverse

                          -MEMORY MANAGEMENT-
 -memory:<size>  set upper memory limit (affects performance)
 -swap:<path>    specify the location of swap files
 -noswap         disable swap file creation

                            -MULTITHREADING-
 -threads        collect and output thread usage information
 -threads:<n>    set maximum number of threads (affects performance)
 -nomt           disable multithreading

                            -MISCELLANEOUS-
 -train          train program for optimal performance
 -binary         compress output and create binary file
 -stats          output computation statistics only (suppress digit data)
 -checksum       include checksum of computation result
 -save           save options as default values
 -license        display software license information
 -pause          pause when finished


Most options can be abbreviated to their first letter.  Where duplicates 
exist, using two letters will generally differentiate the options.

OPTION DESCRIPTIONS

-agm[1|2|3]
This option causes QuickPi to compute Pi using one of the AGM (Arithmetic-
Geometric-Mean) formulas first discovered by Gauss and Legendre and later 
independently by Brent and Salamin (1).  QuickPi actually uses optimized 
algorithm variants of these formulas.

Specifying -agm or -agm1 causes QuickPi to use a formula developed by Arnold 
Schonhage (2).  This formula is currently QuickPi's fastest AGM method.  
Specifying -agm2 causes QuickPi to use a formula by Takuya Ooura (3).  This is 
currently QuickPi's second-fastest AGM method.  Specifying -agm3 causes 
QuickPi to use the Brent-Salamin formula.

The AGM formulas are iterations that are quadratic in nature (the number of 
digits doubling with each iteration).  To compute one million digits of Pi, 
the AGM typically uses 19 iterations.

-borwein
This option causes QuickPi to compute Pi using a quartic AGM iteration by 
Jonathan and Peter Borwein.  A quartic iteration quadruples the number of 
digits at each iteration (at the cost of more operations per iteration).  To 
compute two million digits of Pi, the Borwein quartic formula only requires 10 
iterations.

-chudnovsky
This is the default option for QuickPi when no other options are specified.  
This option causes QuickPi to compute Pi using a Ramanujan-like series formula 
discovered by David and Gregory Chudnovsky.  This formula provides 
approximately 14 correct digits per term.  This is currently QuickPi's fastest 
method for computing Pi.

-ramanujan
This option causes QuickPi to compute Pi using one of the many series formulas 
discovered by Srinivasa Ramanujan.  The particular formula used by QuickPi 
provides approximately 8 digits per term and runs predictably slower than the 
series by the Chudnovsky brothers.

-machin
This option causes QuickPi to compute Pi using the arctangent formula 
discovered by John Machin in 1706.  Machin's refinement on the 
Gregory/Leibniz series yielded a formula with a significantly greater rate of 
convergence: pi/4 = 4 arctan(1/5) - arctan(1/239)

-stormer
This option causes QuickPi to compute Pi using an arctangent formula 
discovered by F.C.W. Stormer in 1896.  This is one of the same formulas used 
by Yasumasa Kanada of the University of Tokyo (4) and his team to compute Pi 
to a record 1 trillion digits: pi/4 = 44 arctan(1/57) + 7 arctan(1/239) - 12 
arctan(1/682) + 24 arctan(1/12943)

-e, -exp
This option causes QuickPi to compute the natural logarithmic base, e.  The 
constant e = exp(1) is defined as: 1 + 1/1! + 1/2! + 1/3! + ...

-2, -sqrt2
This option causes QuickPi to compute Pythagoras' constant, the square root of 
2.  QuickPi uses Newton's iteration for computing square roots.  With an 
initial estimate (x), Newton's iteration for the square root of 2 converges 
quadratically using the sequence: x = (x/2 + 1/x).

-phi
This option causes QuickPi to compute the Golden Mean.  Also known as the 
Golden Ratio or the Golden Section, it is usually represented by the Greek 
letter Phi.  QuickPi uses Newton's iteration for computing Phi (see -sqrt2).  
The formula for Phi is: (1 + sqrt(5)) / 2.

-zeta3
This option causes QuickPi to compute Apery's constant, Zeta(3).  Zeta(3) is 
defined by the formula: 1 + 1/2^3 + 1/3^3 + 1/4^3 + ...  QuickPi uses a faster 
series discovered by Amdeberhan and Zeilberger for this computation.

-gamma
This option causes QuickPi to compute Euler's constant (or Mascheroni's 
constant) and is defined as the limit of: 1 + 1/2 + 1/3 + 1/4 + 1/5 + ... + 
1/n - ln(n).  The constant is usually denoted by the lower-case Greek letter 
Gamma.  QuickPi uses a faster method due to Brent and McMillan for this 
computation.

-catalan
This option causes QuickPi to compute Catalan's constant.  Catalan is defined 
by the following series: 1/1^2 - 1/3^2 + 1/5^2 - 1/7^2 + 1/9^2 - ...  and is 
usually denoted as K, G or sometimes C.  QuickPi uses a faster series by 
Alexandru Lupas for this computation.

-ln(n)
This option causes QuickPi to compute the natural logarithm of an integer 
value (n).  Natural logs are the solution to the equation: e^x = n.

-sqrt(n)
This option causes QuickPi to compute the square root of an integer value (n).

-cbrt(n)
This option causes QuickPi to compute the cube root of an integer value (n).

-fancy:
This option allows the formatted output of QuickPi to be customized.  The 
default format is 10 digits per column, 50 digits per row and 500 digits per 
block.  Blocks are separated by 1 blank line, digits are counted after each 
row and lines are not indented.  Specifying each (in order) as follows can 
change these parameters:

  -fancy:dpc,dpr,dpb,bs,dc,fl

For example, the following parameters cause QuickPi to output 5 digits per 
column, 50 digits per row and 1000 digits per block with lines indented.  Note 
that any missing parameters remain unchanged.

  -fancy:5,50,1000,,,indent

There are two other valid parameters for this option.  They are -fancy:default 
and -fancy:raw.  The first causes the QuickPi to revert to its original 
default parameters and the second causes QuickPi to produce unformatted 
output.  Unformatted output is simply a stream of digits without spaces or 
line termination.

-formula<n>
This option enables QuickPi to use an alternate formula for a computation.  
Specifying -formula1 causes QuickPi to use its primary (default) formula and 
specifying -formula2 thru -formula9 causes QuickPi to use an alternate 
(generally slower) formula.  Alternate formulas are useful to verify the 
correctness of a computation.  The following constants have alternate 
formulas:

 -exp             -formula2
 -phi             -formula2
 -catalan         -formula2
 -zeta3           -formula2
 -sqrt(n)         -formula2
 -cbrt(n)         -formula2
 -ln(n)           -formula2

-inverse
This option causes QuickPi to compute the multiplicative inverse or reciprocal 
result.  This option is not available for all constants.

-memory:<size>
This option sets the upper limit of memory use for QuickPi.  The size 
parameter may be followed by an m to indicate megabytes (1048576 bytes).  The 
smallest value that can be specified is 32 megabytes, smaller values are 
ignored.  When the upper limit of memory is reached, QuickPi will reduce its 
memory consumption and may swap memory to disk unless the creation of swap 
files is disabled (see -noswap option).  Note, very large computations may 
still cause QuickPi to go over the specified memory limit. 

-swap:<path>
Normally, QuickPi creates swap files in the current directory.  This option 
causes QuickPi to use the specified path as the location for creating swap 
files.  A drive letter may be included as part of the path.  The path must 
already exist.

-noswap
This option prevents QuickPi from creating swap files when running low on 
memory.

-threads
This option (without a value) causes QuickPi to collect and output information 
related to thread and processor usage.  By default, QuickPi allocates one 
thread for each processor core or SMT execution context.

-threads:<n>
This option (with a value) sets the maximum number of threads that QuickPi can 
use.  Any value in the range from 1 to 32 is accepted.  The actual number of 
threads used depends on the size of a computation, the amount of available 
memory and other internal factors.  Increasing the number of threads does not 
always translate to improved performance.

-nomt
This option completely disables multithreading causing QuickPi to operate as a 
single-threaded application.
 
-train
This option causes QuickPi to train or configure itself for a specific 
computer environment.  Once trained, QuickPi will usually run faster than its 
default configuration.  Training will normally take several minutes to 
complete.  Training information is saved to a QPI.INI file located in the same 
directory as QPI.EXE.  QuickPi will then read the training information the 
next time it's run.  It is recommended that all Windows applications be closed 
and any background tasks (including screensavers) be disabled prior to 
initiating training.

-binary
This option causes QuickPi to write its output as a compressed binary file. 
Compressed files are generally 1/2 to 1/3 the size of QuickPi's normal output.  
A secondary reader program QRD (included) is required to view compressed 
binary files.  The QuickPi Reader program is described below.

-stats
This option causes QuickPi to output computation statistics only and suppress 
the output of digit data.  This can be useful when only the statistics of a 
computation are desired for comparison purposes.

-checksum
This option causes QuickPi to calculate and display a checksum for a 
computation result.  A checksum can be useful to validate a result without 
having to perform a digit by digit comparison.

-save
This option causes QuickPi to save the settings of the above specified options 
to a QPI.INI file located in the same directory as QPI.EXE.  The next time 
QuickPi is started, it will automatically read the QPI.INI file and default to 
the saved options.  This is particularly useful for the -fancy option and its 
various parameters.

-license
This option displays the QuickPi license information.

-pause
This option causes QuickPi to pause and wait for a key to be pressed when its 
operation is complete.  QuickPi will automatically pause if started from the 
Windows Desktop. 


----------------
READER OVERVIEW

The QuickPi Reader is designed to decompress a binary file written by QuickPi 
and output it in a variety of customizable formats.  Using the Reader allows 
you to quickly output all or part of a QuickPi result without having to re-run 
a (perhaps lengthy) QuickPi computation.  In addition, compressed binary files 
are up to 1/2 to 1/3 the size of QuickPi's normal output, saving a significant 
amount of disk space if result files are archived.

USAGE INFORMATION

The QuickPi Reader is a command line program and as such you will need to 
start a Command Prompt window to use it.  Refer to your Windows help guide for 
information on how to start a Command Prompt window.

Once a Command Prompt window has been started, be sure the Reader program 
QRD.EXE (or QRD64.EXE) is located in your system path.  If it's not, then 
change the current working directory to that chosen when the program was first 
installed.  Again, refer to your Windows help guide for information on PATHs 
and the CHDIR command.

Entering QRD on the command line without any parameters will produce the 
following information:


QRD-QuickPi binary reader v4.5, (c) 2000-2008 S. Pagliarulo
Freely distributable, email: s_pagliarulo@hotmail.com

usage: qrd sourcefile [destfile] [options|-h]


Information in square brackets [] is optional.  Items separated by a vertical 
bar | indicate an either-or choice.  For example, to view the compressed 
binary file "pi.bin" created by QuickPi, enter:

  qrd pi.bin

The output will be sent to the console screen.  To save the output to a text 
file, simply specify a destination file name after the source file name:

  qrd pi.bin pi.txt

This will save the output to the file "pi.txt".

Entering QRD on the command line with the -h option will produce the following 
help information:

options:

 -stats            output computation statistics only
 -nostats          output digit data only

 -range:start-end  output a range of digits
                    start - start of range (1-)
                    end - end of range (1-)
 -skip:count,step  skip over output
                    count - output [count] digits
                    step - every [step] digits

 -fancy:dpc,dpr,   customize output format
        dpb,bs,dc,  dpc - digits per column
        fl          dpr - digits per row
                    dpb - digits per block
                    bs  - block spacing
                    dc  - digit counting (none,row,block,line)
                    fl  - flags (noindent,indent)

 -inverse          compute multiplicative inverse
 -square           compute square
 -cube             compute cube
 -ln               compute natural log

 -binary           create binary output file
 -license          display software license information
 -pause            pause when finished


Most options can be abbreviated to their first letter.  Where duplicates 
exist, using two letters will generally differentiate the options.

OPTION DESCRIPTIONS

-stats
This option causes the QuickPi Reader to output computation statistics only 
and suppress the output of digit data.  This option can be used to obtain a 
summary of a compressed binary file's contents.

-nostats
This option causes the QuickPi Reader to suppress the output of computation 
statistics that normally precede the digit data.  This option should be used 
when only digit data is desired.

-range:
This option causes the QuickPi Reader to limit the range of digits output.  A 
starting point, an ending point, or both starting and ending points can be 
entered, separated by a dash.  Multiple ranges can be specified by separating 
them with a comma or by entering multiple -range options from the command 
line.  For example, the following parameters will output the first and last 
100 digits of 20k computed digits:

  -range:1-100,20381-20480

-skip:
This option causes the QuickPi Reader to skip across the full range of 
computed digits and to only occasionally output a specified number of them.  
The first parameter specifies the number of digits to output.  The second 
parameter specifies the skip amount.  For example, the following parameters:

  -skip:100,10000

cause the QuickPi Reader to produce the following output with 20k computed 
digits of Pi:


Listing Pi, 100 digits every 10,000 digits

3.
1415926535 8979323846 2643383279 5028841971 6939937510  : 50
5820974944 5923078164 0628620899 8628034825 3421170679  : 100

5667227966 1988578279 4848855834 3975187445 4551296563  : 10050
4434803966 4205579829 3680435220 2770984294 2325330225  : 10100

2038565390 9910477594 1413215432 8440625030 1802757169  : 20050
6508209642 7348414695 7263978842 5600845312 1406593580  : 20100


-fancy:
This option allows the formatted output of the QuickPi Reader to be 
customized.  The default format is saved as part of the compressed binary file 
created by QuickPi.  Unless changed when using QuickPi, the default format is 
10 digits per column, 50 digits per row and 500 digits per block.  Blocks are 
separated by 1 blank line, digits are counted after each row and lines are not 
indented.  Specifying each (in order) as follows can change these parameters:

  -fancy:dpc,dpr,dpb,bs,dc,fl

For example, the following parameters cause QuickPi Reader to output 5 digits 
per column, 50 digits per row and 1000 digits per block with lines indented.  
Note that any missing parameters remain unchanged.

  -fancy:5,50,1000,,,indent

There are two other valid parameters for this option.  They are -fancy:default 
and -fancy:raw.  The first causes the QuickPi Reader to revert to its original 
default parameters and the second causes the QuickPi Reader to produce 
unformatted output.  Unformatted output is simply a stream of digits without 
spaces or line termination.

-inverse
This option causes the QuickPi Reader to compute and output the multiplicative 
inverse or reciprocal of a result.

-square
This option causes the QuickPi Reader to compute and output the square of a 
result.

-cube
This option causes the QuickPi Reader to compute and output the cube of a 
result.

-ln
This option caused the QuickPi Reader to compute and output the natural 
logarithm of a result.

-binary
This option causes the QuickPi Reader to write its output as a compressed 
binary file.  This option is useful when combined with the -inverse, -square, 
-cube or -ln options.

-license
This option displays the QuickPi Reader license information.

-pause
This option causes the QuickPi Reader to pause and wait for a key to be 
pressed when its operation is complete.  The QuickPi Reader will automatically 
pause if started from the Windows Desktop.


-------------------
PROGRAM LIMITATIONS

The upper limit for the 32-bit version of QuickPi is 1 billion digits.  The 
64-bit version has been successfully tested with over 100 billion digits and 
has a theoretical upper limit of 500 billion digits.  The exact upper limit 
depends on several factors including but not limited to the amount of memory 
and disk space available.  Each new release of QuickPi should continue to 
perform faster and with higher precision.

WARRANTIES AND DISCLAMERS

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY 
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, FUNCTIONALITY 
AND DATA INTEGRITY OR PROTECTION ARE DISCLAIMED.

IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES WHICH MAY 
RESULT FROM THE USE OF THIS SOFTWARE, INCLUDING LOSS OR INTERRUPTION OF 
BUSINESS, ACCIDENTAL LOSS OF DATA OR DAMAGE TO COMPUTER EQUIPMENT.

ACKNOWLEDGEMENTS

My thanks and appreciation to all the Beta testers who have assisted with the 
testing of this version over the past many months.  A special thanks to 
Shigeru Kondo for his extra dedication, enthusiasm, helpful feedback and 
suggestions.

CONTACTING THE AUTHOR

Questions and comments concerning QuickPi should be directed to Steve 
Pagliarulo.  Steve can be contacted via email at: s_pagliarulo@hotmail.com

WEBSITES DEDICATED TO PI

Stu's pi page: http://home.istar.ca/~lyster/pi.html
Xavier Gourdon: http://numbers.computation.free.fr/Constants/constants.html
jasonp's home page: http://www.boo.net/~jasonp/
Shigeru's pi world: http://ja0hxv.calico.jp/pai/estart.html


-------------------
(1) R.P. Brent, Fast multiple-precision evaluation of elementary functions, J. 
ACM 23 (1976), 242-251.

(2) Arnold Schonhage, A.F.W. Grotefeld/E. Vetter, Fast Algorithms, A Multitape 
Turing Machine Implementation, BI Wissenschaftsverlag, Mannheim (1994), p.266.

(3) Takuya Ooura maintains a website dedicated to Pi and the AGM at: 
http://www.kurims.kyoto-u.ac.jp/~ooura/pi_fft.html

(4) The Kanada Laboratory maintains a website dedicated to computing Pi at:
http://www.super-computing.org

