RetroPsychoKinesis Experiments
Source Code

Downloading and Installation Notes
by John Walker — 11 January 1997


This downloadable distribution contains everything you should need to establish a mirror of the online RetroPsychoKinesis experiments at www.fourmilab.ch, and to develop new experiments of your own.

The Distribution

The source code is supplied as a GZIPped Unix TAR archive. Uncompress and extract the contents with the commands:

    gunzip rpkp.tar.gz
    tar xfv rpkp.tar

which will create an “rpkp” directory containing the documents in the root of the RPKP experiments directory, and the following subdirectories.

analysis
Documents for submitting log retrieval reports, and analysis tools, including the Chi-Square Calculator.
bellcurve
The bell curve visual feedback program and documents to run it.
cgi-bin
Source for CGI programs (Unix shell scripts and Perl programs) for running experiments and producing log reports.
clockface
The clock face visual feedback program and documents to run it.
experiment
Parent class of all experiment programs, and utilities common to all visual feedback programs. Compiled versions of the classes from this directory are copied to the directories containing each visual feedback program.
pipeorgan
The “Probability Pipe Organ” applet, which demonstrates how the binomial distribution approaches the normal distribution as the degrees of freedom and number of trials grows large. This applet is derived from experiment, but overrides many methods of the parent class since it is a demonstration program rather than an on-line experiment.
pendulum
The pendulum visual feedback program and documents to run it.

Installing CGI Programs

The most difficult step in running RPKP experiments at your site is installing the CGI programs. If you do not operate your own Web site, you'll have to persuade your site's administrator to place the programs in the system's CGI directory and (if not already present), install the Perl 4.036 distribution which is required to run the programs. Since poorly-designed CGI programs can seriously compromise system security, many system administrators are reluctant to allow users to run their own CGI scripts—if your Web site is on a commercial Internet Service Provider or a University server, it is extremely unlikely you'll be permitted to install the CGI programs.

If you do have the ability to install the CGI programs, first make sure Perl 4.036 is installed on the system can be accessed by programs in the server's CGI directory. Next, review the declarations at the start of the programs Psiclock.pl and RPKPreport.pl and change file and directory names (particularly the log file where records of RPKP experiments will be kept) to names compatible with your system's directory structure. If you're using a hardware random number generator of your own, as opposed to contacting the Fourmilab HotBits server, you'll have to modify the code in Psiclock.pl to interrogate your generator. Finally, on some versions of Unix, you may have to modify the declarations of $AF_INET and $SOCK_STREAM in Psiclock.pl to be compatible with your socket library.

The “splitfields.pl” utility is required by RPKPreport.pl. Other files from the standard Perl library required by Psiclock.pl and RPKPreport.pl are included; depending on how Perl is installed at your site, you may or may not have to place copies of them in your CGI directory.

The “chisquare” program, used to evaluate the chi-square probability distribution function, is implemented in C in the file analysis/chisquare.c. If you wish to rebuild it before running the Makefile in that directory, gunzip and de-tar the archive DCDFlib.tar.gz, then cd to the resulting DCDFlib/libsrc directory and “make release”. The DCDFlib programs were originally written in FORTRAN and subsequently translated to C—you may receive compiler warnings about unreachable statements; these are generally harmless and can be ignored.

The server programs were developed on Sun Solaris 2.5, which is derived from Unix System V release 4.0. The programs and shell scripts use Unix features in many places—converting them to run on a non-Unix server will be a lot of work, with which I cannot assist you.

Installing the Experiment Directory Tree

By contrast, the rest of the distribution should in unpack in a pretty much ready-to-run configuration. Point your browser at the rpkp/index.html file and navigate around to get a feel for things. Relative pathnames have been used wherever possible, but due to the need to link back and forth between Web documents and CGI programs, there are some places where “/cgi-bin”, “/rpkp”, and “/rpkp/experiments” are hard-coded as the names of the server's CGI script directory and the positions of the main RPKP directory and its experiments subdirectory in the server's home directory. There are also some local links to other items on www.fourmilab.ch (primarily to descriptions of the HotBits server). Change these as required to get everything working. You'll also, of course, want to change the mailto: contact information, home page links, etc. to refer to you and your site.

Developing New Feedback Programs

This source code distribution is provided in “fat” form—compiled versions of all the Java programs are provided and copies of the classes common to the experiments are present in their respective directories. This means you should be able to run the experiments pretty much “out of the box”, without having to install the Java Development Kit, recompile the programs, and delve into the details of the directory structure.

If you are interested in developing new feedback programs, start by examining one of the existing programs; “clockface” and “bellcurve” are the best points of departure for most projects—“pendulum” contains additional complexity due to its animation being only indirectly influenced by the random bit stream.

All of the experiments included in this distribution consist of extensions of the classes “experiment.java” and “VisualFeedback.java” which are in the “experiment” subdirectory. The parent classes provide most of the functionality common to the experiments, and use other utility classes in the “experiment” subdirectory.

Parent classes “experiment.java” and “VisualFeedback.java” form a fully functional applet in their own right, which instead of fancy graphical feedback simply displays the score in the applet's window. This permits stand-alone testing of changes to the parent classes.

Download Source Code Distribution


by John Walker