                              PiHex v5.0 readme
                              =================

   I've put together this file out of the questions I've been asked via e-mail so far, so if there is something you would like to see addressed here, send me an e-mail.

WHAT IS PIHEX?
==============

   PiHex is both the overall project and the program you download, which is, strictly speaking, the PiHex _client_.  PiHex (the project) is a distributed computing project using idle time slices on computers scattered around the world to calculate specific bits of Pi without computing all the previous bits.  In this way, PiHex is ideally suited to highly parallel systems (such as the internet) where each computer only has a very limited amount of memory -- with about 100K of memory, PiHex can compute the five trillionth bit of Pi, whereas 'classical' algorithms for computing Pi, which compute all the bits up to a certain point would need over a terabyte of memory, which is out of reach for all but the world's most powerful supercomputers.  PiHex uses Bellard's formula, essentially a refinement of the BBP formula which expresses Pi as an infinite sum.  To calculate the five trillionth bit, we need to add up the five trillionth bits of seven trillion terms.  I assign ranges of terms (eg, first two hundred billion terms) for each computer to add up, and then I add all the results together at the end.

INSTRUCTIONS
============

  Once you've downloaded and unzipped pihex.zip (which you, reading this, presumably have done), you should do the following:

1.  Send me an e-mail at <cperciva@sfu.ca> telling me what type,speed, and number of CPUs you have. For example, a Pentium 166, a K6 233, or a dual Pentium II 333. Other details, such as amount of ram, disk space, network cards, cdrom drives, tape drives, scsi cards, web browsers, brand name, size of floppy drives, and sound card (yes, I have been told all this) are irrelevant.

2.  Copy PiHex into a directory somewhere. (It's probably easiest if you create a separate directory for it so that you don't have to look through 200+ files in your windows directory when it tells you to send me an output file. And yes, some people do this.)

3. (if desired) add a link to PiHex to your startup folder.

4.  Wait for me to reply to your e-mail.  I will attach a file, named range*.ini (ie, range.ini or range1.ini, etc.) to the e-mail.  It will be a MIME-compliant attachment, so anyone using Eudora, Netscape, elm, or probably any other program to read their mail should be able to read it.  In the unlikely possibility that your mail client is not MIME-compatible, don't worry.  The attachment is a text file, so you should be able to just cut and paste into notepad and save the file as range.ini.

5.  Copy the file (range*.ini) into the PiHex directory and run PiHex.  It will start by calculating the one hundred millionth hexit of Pi as a self-test.  When it finishes, it will 'eat' (read and then delete) the range file and start to work on it.  PiHex will then tell you to send me 'output0.txt'. This contains the self-test output.  When I recieve this file, I will check that PiHex appears to be working properly, and then send a second range file to you.  After you recieve confirmation that I have recieved the output file, you can delete it.

6.  Copy the (new) range file into the PiHex directory, and wait for PiHex to finish its current range.

7.  When it finishes, PiHex will tell you to send me a file.  Send it.  I will then send you another range file.  Once you recieve confirmation that I've recieved the file, you can delete it.

8.  Repeat steps 6,7.


NOTES
=====

  Since PiHex only uses idle time slices, it should not interfere with any other programs you are running.  Thus, you can leave it running all the time.

  PiHex subdivides the assigned range into smaller sub-ranges, and writes the sum of each subrange to the output file when it completes, so if your computer crashes at some point, PiHex might lose half an hour of work, but it should be able to restart without any problems.

  PiHex is designed to use all the available CPUs: It spawns a separate thread for each CPU to do that CPU's calculations.  Therefore, if you have a multi-processor machine, you only need to have one copy of PiHex running. For this reason, as well as .ini conflicts, PiHex will not allow you to have two copies running at once.

  PiHex makes very extensive constant use of the CPU's internal floating-point unit.  As a result, it can cause the CPU to overheat.  About 2-3% of computers have this problem.


OUTPUT
======

  PiHex displays status information in its window each five seconds, scrolling upwards. There are four such messages:

1.234567% done, 123.456789MHz
       This means that PiHex is 1.234567% done its current range, and it is
       doing the same amount of calculation as a 123.456789MHz Pentium
       working full-time. This last number will vary depending upon what
       fraction of the CPU time PiHex gets.  Note, the percentage done can
       be negative on multi-processor systems while some processors are
       finishing an old range and others are working on a new range, since it
       is relative to the current range.

Please send output0.txt to cperciva@sfu.ca
       PiHex has finished its range, and wants you to send me the output
       file.

Error: CPU appears to be overheating.
       The CPU is either overheating, or some operating system component
       (device drivers, VxDs, etc.) is leaving the FPU in an incorrect state.
       If this occurs commonly, PiHex cannot run on your computer. If it
       occurs only occasionally, then PiHex can still run, although your
       results may not be correct; this isn't really a problem anyway, since
       all the calculations are done twice in two different positions to
       guard against such errors.

Error: range.ini not found.
       PiHex has finished its range, and cannot find a range file specifying
       the next range for it to work on. Send me an e-mail requesting a new
       range.


  In the output file, (output0.txt or output1.txt), you will see lines like the following:

0000012309CE5400,0000000028000000,000000002C000000,646172B9D0055BE0DC92FE7FD8235419

  This means that starting from the 12309CE5400th hexit, the sum from term 28000000 to term 2C000000-1 is 646172B9D0055BE0DC92FE7FD8235419, to within rounding errors. All these numbers are in hexadecimal, of course.


THE MATH
========

  The famous BBP formula states that

                  infinity    4         2         1         1
                   -----   ------- - ------- - ------- - -------
                    \      8 n + 1   8 n + 4   8 n + 5   8 n + 6
             Pi =    )     -------------------------------------
                    /                         n
                   -----                    16
                   n = 0


  This formula demonstrates that calculating a specific bit of Pi is in SC* in base 16 (<==> base 2).  SC* is (as far as I understand it) the class of algorithms which compute in O((log n)^O(1)) space and O(n*(log n)^O(1)) time.  In other words, SC* algorithms take about linear time, and polynomially logarithmic space.
  We actually use the faster and slightly more complicated Bellard's formula:

        /infinity   n/   32      1     256      64      4       4       1  \\
        | ----- (-1) |- ---- - ---- + ----- - ----- - ----- - ----- + -----||
        |  \         \  4n+1   4n+3   10n+1   10n+3   10n+5   10n+7   10n+9/|
Pi=1/64 |   )    -----------------------------------------------------------|
        |  /                                      n                         |
        | -----                               1024                          |
        \  n=0                                                              /


(if this is illegible, try turning off word wrap)

Suggestions
===========

  PiHex is constantly (well, whenever I have time) improving, so if anyone has any suggestions for how to make it better, please tell me!