_     _                  __  __ _           _          _
 | |   (_)_ __  _   ___  _|  \/  (_)_ __   __| | ___  __| |
 | |   | | '_ \| | | \ \/ / |\/| | | '_ \ / _` |/ _ \/ _` |
 | |___| | | | | |_| |>  <| |  | | | | | | (_| |  __/ (_| |
 |_____|_|_| |_|\__,_/_/\_\_|  |_|_|_| |_|\__,_|\___|\__,_|
| Home | Software | Mirrors | Writings | Dutch Power Cows | About |

Software

random-folder

| General | README | LICENSE | ChangeLog |

random-folder.pl
================

 Author: Sebastiaan Couwenberg <sebastic@xs4all.nl>
License: GPLv2 or later

random-folder.pl is a simple manager around Stanfords Folding@Home client to
randomly configure an username/team combination to use.

It was originally written to donate some points of the authors Quad Core SMP 
client to his subteam mates.

The script will start the FAH client with the -oneunit and -verbosity 9 flags.
The -oneunit flags tell the FAH client to teminate after completing the current
work unit. The -verbosity 9 flags tell the FAH client to use the most verbose 
logging available, this will increase the useful information in FAHlog.txt (and
its filesize).

While the FAH client is running under the child process of random-folder.pl,
the parent process will poll the child process and the current state & progress
of the FAH clients current work unit.

When the current work unit is finished and all FAH client processes have quit,
random-folder.pl will randomly pick an username/team combination from its 
configuration file, config.xml, and reconfigure the FAH client to use it.

After modifying the FAH client configuration file, client.cfg, to use this
randomly picked username & team number, the FAH client will be restarted, and
its progress will be polled.

Polling is done every 60 minutes when progress is less than 80%, every 30 
minutes when progress is less than 95%, every 5 minutes when progress is
greater than or equal to 95%, and every minute when progess is equal to 100%
or the WU (or more specifically: its queue index) has status 
'ready for upload' or 'deleted'. This is done because there is not much use
checking the progress often when the WU is not almost finishemd, and don't want
to wait to long before rechecking FAH client which may have completed since the
last check.


Requirements
------------

- random-folder.pl only supports v5 Folding@Home Linux CPU clients, the v5
  Folding@Home Linux x86_64 SMP client and the v5 Folding@Home Mac OS X/x86 SMP
  client console version. It also supports the v6 CLI client on Linux and 
  Mac OS X/x86 and its -smp argument.
  The Folding@Home client needs to be installed and configured before using it
  with random-folder.pl.

- Dick Howells qd utility is used to get the status and progress of the 
  current work unit from the FAH clients queue.dat file. 
  A copy of the 32bit Linux binary and 32bit Mac OS X/Universal binary of qd 
  are included in the random-folder tarball, you can get the latest version of
  qd (and its source code) from:
  http://linuxminded.xs4all.nl/?target=software-qd-tools.plc

Perl modules:
- Date::Calc     (http://search.cpan.org/~stbey/Date-Calc-5.4/)
- XML::Simple    (http://search.cpan.org/~grantm/XML-Simple-2.18/)
- Getopt::Mixed  (http://search.cpan.org/~cjm/Getopt-Mixed-1.10/)

On a Debian(-based) system you can install the required Perl modules with:
# aptitude install libdate-calc-perl libxml-simple-perl libgetopt-mixed-perl

On Mac OS X you can install the required Perl modules through Mac Ports with:
$ sudo port install p5-date-calc p5-xml-simple p5-getopt-mixed


Installation
------------

Copy the files listed below from the random-folder tarball to the directory in
which the Folding@Home client is installed:
- random-folder.pl
- config.xml
- linux/qd (or darwin/qd on Mac OS X).

If you're using Mac Ports to install the Perl modules you may want to change 
the path to the perl binary on line 1 in random-folder.pl to: 
/opt/local/bin/perl
Or you can run random-folder.pl als an argument to perl.


Configuration
-------------

The list of username/team combinations from which random-folder.pl will 
randomly choose when reconfiguring the FAH client is configurated in the
config.xml file.

Its syntax is relatively straightforward as can be seen in the default 
configuration:

### config.xml ###
<config>
  <accounts>
    <account>
      <id>0</id>
      <username>Anonymous</username>
      <team>0</team>
      <weight>1</weight>
    </account>
    <account>
      <id>1</id>
      <username>[DPC]_Fatal_Error_Group0smoking2000</username>
      <team>92</team>
      <weight>2</weight>
    </account>
  </accounts>
</config>
### config.xml ###

You probably want to change the accounts from which random-folder.pl will 
choose. Each account is configured in the <accounts> section as an <account>
definition.

The structure for an <account> definition is:
    <account>
      <id>INT</id>
      <username>STRING</username>
      <team>INT</team>
      <weight>INT</weight>
    </account>

The <id> is a sequential number starting at 0 and must be incremented for each
new account in the list. 
The <username> and <team> are the username and team number the FAH client 
should use in its configuration. 
The <weight> sets how many times an account initially appears in the account 
pool, should be >= 1.


Running
-------

By default the FAH client 'FAH504-Linux.exe' is started by random-folder.pl, but
you can specify the 'FAH502-Linux.exe' or 'fah5' SMP client binaries by using the 
-c or --client argument.

The FAH client is started and reconfigured by random-folder.pl, you can pass 
some arguments to the FAH client by specifying them as arguments to 
random-folder.pl with the -a or --argument argument. 

The supported FAH client arguments are:
  -forceasm    Force core assembly optimizations to be used if available
  -advmethods  Use new advanced scientific cores and/or work units if available
  -freeBSD     Make brandelf system call on downloaded cores.
  -openBSD     Make elf2olf system call on downloaded cores.
  -local       Use configuration files from local directory
  -smp [INT]   Request SMP work units (since FAH client v6.00)

The -freeBSD & -openBSD arguemnts should only be used when you're running
random-folder.pl and the FAH client on FreeBSD or OpenBSD ofcourse.

The -local argument must be used when using the Mac OS X SMP client Installer
version, the -local argument is automatically used by random-folder.pl on 
Mac OS X, usage of -local is also required if you're running the v6 FAH client.

The -smp argument can be used when you're running the v6 FAH client and want to
fold SMP work units. Using the -smp arugment when running the v5 FAH client,
the FAH client will refuse to start up and display its usage information, so
do NOT use it with the v5 client.
The -smp argument can optionally be followed by a number to indicate the number
of SMP cores the FAH client should use. This was introduced in FAH v6.02beta1.

By default random-folder.pl starts the FAH client with the arguments:
  -verbosity 9 Sets the output level, from 1 to 9 (max). The default is 3
  -oneunit     Exit after completing one unit
  -local       Use configuration files from local directory (Only on Mac OS X)

'-verbosity 9' is used to have the FAH client write more information to the
FAHlog.txt which qd parses for progress information.

'-oneunit' is used so that the FAH client can be reconfigured with a different
username and team number to use for the next work unit.

'-local' is used on Mac OS X because the FAH client uses ~/Library/Folding@home
by default on Mac OS X. This argument forces the FAH client to use the current
working directory.

For a complete list of arguments to random-folder.pl run:
$ ./random-folder.pl -h
or:
$ ./random-folder.pl --help


Troubleshooting
---------------

If you see the below message (on Mac OS X):
 could not find ParserDetails.ini in /opt/local/lib/perl5/vendor_perl/5.8.8/XML/SAX
 [2007-09-15 14:36:20] Status  : folding now

Then you need to fix XML::SAX by running (as root/with sudo):
 /opt/local/bin/perl -MXML::SAX -e "XML::SAX->add_parser(q(XML::SAX::PurePerl))->save_parsers()" 

See: http://perl-xml.sourceforge.net/faq/#parserdetails.ini


Links
-----
Stanfords Folding@Home project:
http://folding.stanford.edu/

Dick Howells qd (queue dumper):
http://linuxminded.xs4all.nl/mirror/www.boston.quik.com/rph/fah.html#qd
http://linuxminded.xs4all.nl/?target=software-qd-tools.plc

random-folder.pl webpage:
http://linuxminded.xs4all.nl/?target=software-random-folder.plc
http://random-folder.linuxminded.nl/



Fortune:

Perl programming is an *empirical* science!
	-- Larry Wall in <10226@jpl-devvax.JPL.NASA.GOV>