Folding@home
fpd
qd
qdinfo.dat
qdiprint
xyz2pdb
qbm
qfix
qgen
wuinfo
The programs described on this web page, and available here for download, work with data from the Folding@home client.  They are a set of independent tools which can be used to monitor and examine client data, to help diagnose problems, and to recover from several cases when the client queue has lost track of current work.  This software is not part of the Folding@home client distributed by the Pande Group at Stanford University, nor has it in any way been developed by them.  They are aware of it, however, and have neither approved nor disapproved of its use.

The first program, fpd, displays an image of the current protein molecule in an X and OpenGL environment, and shows some information about the most recent ten work units downloaded.  The second program, qd, prints out a more comprehensive dump of the Folding@home queue.dat file, which holds the information about the most recent ten work units.  The third program, qdiprint, presents work unit point value information in readable form from the qd info file qdinfo.dat.  The fourth program, xyz2pdb, translates from the Folding@home .xyz molecule display data file format into the more widely-used .pdb format.  The other programs perform more limited functions with the queue.dat file or other folding work files.  As supplied here, they are C sources, which may require editing to select a few options before compilation for your system.  Several precompiled versions of most of these programs are available for download from this site.

This is free software; you can distribute it and/or modify it under the terms of the GNU Public License.  There is no warranty.  If it breaks, as they say, you get to keep the pieces.


fpd.c This program displays an image of the current protein molecule and shows some information about the most recent ten work units downloaded.  It requires X Windows with OpenGL (GLX) extensions.  The source available here is for Linux, and it has only been tested under Linux, but it has a definition at the beginning to set the format for Windows or Mac OS X.  At present, this definition only affects the default interpretation of the queue.dat file, and it is quite possible that other changes will be necessary.  I'd appreciate feedback if you have troubles or know of changes needed for other environments.  I know that at present the window title doesn't display properly under some versions of the Enlightenment window manager.  If you know how to fix it, please send me e-mail.

An experimental OpenBSD version, for systems with X support, has been compiled off-site and is hosted by Alex Kirk.  If anyone downloads this, please send me a report as to whether it actually works.  The file is in ELF format, for OpenBSD systems later than V3.3.

Considerable work has also been done on Mac OS X by A. Kraus, leading to the compiled Mac GUI version described below, and by Kevin Bernhagen, leading to a version of fpd bundled with InCrease.

The program has a fairly large number of configuration arguments which may be given on the command line.  To see them, run it as fpd -help.  There is also a help screen which explains the menu buttons and molecule colors, a run-time configuration options screen, and a queue information screen.  This version of the program does not refresh its display on a timed basis, so it neither uses processor time unexpectedly nor necessarily shows current data.  It can be refreshed easily with a mouse click.

Click here to see a log of changes to the program.

A precompiled binary version of fpd is available for Linux.  Depending on the download method, users may have to change the permissions of the downloaded file to make it executable.  If you have any trouble with this precompiled version, please let me know.

The precompiled version prints timestamps on queue data in local time.
Linux Version   fpd (50K)
OpenBSD (ELF) Version   fpd (63K)
Here are a few sample screen shots of fpd displaying a p162_villin and a p724_Abeta21-43-amberGS:

fpd #1      fpd #2      fpd #3      fpd #4      fpd #5

Two precompiled installable Mac OS X GUI versions of fpd are also available.

The first Mac OS X version is courtesy of A. Kraus.  The downloadable tarball contains all the necessary files to install fpd as an application.  The internal OpenGL display code, and the functions which read and interpret the XYZ data file, are directly from the native X Windows version of fpd.  All the configuration options and run-time controls have been reimplemented for OS X.  In this version, the XYZ file is selected in an Open... menu after the program is started.  You can either open work/current.xyz directly from the folding directory, or any other selection if you collect these files somewhere else.
Mac OS X GUI Version    fpd-Cocoa-alpha2.tar.gz (71K)
Mac OS X GUI Version    fpd-Cocoa-1-1-beta1.tar.gz (98K)
There may be later versions available directly from his web site.

Here are some sample screen shots of the Mac GUI version of fpd displaying a p673_1LE1_342K and a p1006_ppg10_pfold:

macfpd #1            macfpd #2

The second Mac OS X version is courtesy of Kevin Bernhagen.  It comes bundled with InCrease, and will be downloaded directly from his web site.
Mac OS X Version with InCrease    fpd.dmg (66K)

qd.c This program prints out a formatted dump of the queue.dat file.  The default definitions in the source file should, in most compilation environments, produce a version for the system it is being compiled on.  If the usual predefined variables aren't there, it will default to a version for Linux, but an explicit compilation switch can be used to set the format for Windows or Mac OS X.  I'd appreciate feedback if you have troubles or know of changes necessary for other environments.  I know the table of points per work unit is occasionally incomplete, but I try to keep it up to date, and if you have to compile it without "ctime" support, you'll have to adjust the time zone definition at the beginning.  Also, this program is not in any official way connected to the Stanford code, so if it calls data items the wrong thing, it is purely an error of my own interpretation.

While the output from qd is primarily from queue.dat, it will be embellished with data and calculations obtained from other files, if they can be read.  In all, several client files may be examined for each queue index, and qd can also search for score and deadline information in a file called emprotz.dat (it used to be emprotx.dat), if it is present in the folding directory.  This file is a frequently-updated data file used by a third-party monitoring program for Windows called Electron Microscope, written by Larry Perry, aka "TheWeatherMan".  You can obtain this file as needed from his web site, whether or not you run Electron Microscope.  Follow the download instructions when you get there.

For a detailed explanation of all the fields in the qd output, and how to interpret the data in them, click here.

In April 2003, qd had some major internal changes.  Since that time, its behavior can be influenced by a large collection of command-line flags, and it also can read project and score information from a separate data file, called qdinfo.dat.  This means you don't have to keep downloading new versions of the executable program to stay up to date with new projects.  It will now be sufficient just to download the data file, although downloading the executable, except possibly for versions I don't compile myself, will be just as good, because it will have the latest data in its built-in tables.

For OpenBSD users, the Linux version can be used under Linux emulation after an elf2olf command is run on it, but there is also a version available which is natively compiled under OpenBSD.  This is courtesy of Alex Kirk.

I also have available two precompiled versions for Mac OS X.  The first is a CLI version, essentially identical in operation to the Linux and Windows versions described on this page.  It comes courtesy of Kevin Bernhagen, aka "calxalot", and is automatically recompiled daily and packaged with several other useful files.  The other Mac program is a GUI version, described a little more fully below, courtesy of A. Kraus.  I can't compile and package Mac versions here under Linux, so the qdinfo.dat file may be more important on the Mac.

The following flags are supported:
-u  Print usage message
-h  Print an explanation of the status codes
-i  Format with deeper indentation
-c  Compact format (omit several lines)
-p  Don't look at FAH files other than <queue.dat>
-f  Explicitly specify folding directory
-q  Explicitly specify queue data file (implies -p)
-n  Explicitly specify qd info file (default <qdinfo.dat>)
-m  Explicitly specify EMIII info file (default <emprotz.dat>)
-s  Specify type of queue data file (linux, windows, mac)
-t  Override time zone (needs argument)
-z  Force UTC
-v  Just print version information and stop
-d  Print debug dump
-e  Print all entries even if they're garbage
-l  Format for log entry data
-L  Format for log entry data with specified ID string
 
Here is a sample of the output, abbreviated here to show only several of the ten queue entries:
qd released 11 April 2003; qd info 11 April 2003
Queue version 3.24
Current index: 6
 Index 7: finished (0.178 pt/hr) 3.04 X min speed
  server: 171.64.122.121:80; project: 624, "p624_TZ1_EXT"
  Folding: run 1, clone 2, generation 8; benchmark 671; misc: 500, 200
  issue: Sat Mar 22 22:55:25 2003; begin: Sat Mar 22 22:55:32 2003
  end: Thu Mar 27 13:23:33 2003; expire: Sat Apr  5 22:55:32 2003 (14 days)
  core URL: http://www.stanford.edu/~pande/Linux/x86/Core_65.fah
  user: rph_iv; team: 0; ID: 3539220A7A46065D; mach ID: 1
  work/wudata_00.dat file size: 100523; WU type: Folding@Home
 Index 8: empty
 Index 9: finished (0.286 pt/hr) 24.5 X min speed
  server: 171.64.122.123:8080; project: 533, "p533_BBA5 in water"
[snip...]
 Index 6: folding now (0.242 pt/hr) 7.03 X min speed; 72% complete
  server: 171.64.122.124:8080; project: 542, "p542_BBA5_N in water"
  Folding: run 37, clone 58, generation 1; benchmark 756; misc: 500, 300
  issue: Mon Apr  7 11:12:08 2003; begin: Mon Apr  7 11:13:34 2003
  expect: Sun Apr 13 03:47:37 2003; due: Sat May 17 11:13:34 2003 (40 days)
  core URL: http://www.stanford.edu/~pande/Linux/x86/Core_78.fah
  user: rph_iv; team: 0; ID: 3539220A7A46065D; mach ID: 1
  work/wudata_09.dat file size: 352034; WU type: Folding@Home
Average pph: 0.220, ppd: 5.26, ppw: 36.8, ppy: 1923
 
A more current printout can be examined in detail on the qd explanation page.

As of 7 December 2004 (functional revision "027"), there is also a compact printout suitable for concatenating to a log file, or as input for a logging program.  Here is what that format looks like, as it would be printed when qd is called, for example, with the -L abc flag:
qd released 7 December 2004 (fr 027); qd info 7 December 2004 (rph)
Queue version 5.01
Current index: 4
- 093E74E0 093F81B0  abc.5   872   190    26     1   318   31.00   1.622 G "p872_p53dimer872"
- 093F822D 00000000  abc.6   872    60    21     6   318   31.00   5.831DG "p872_p53dimer872"
- 093FCD61 0940D877  abc.7   873   106     9     6   318   31.00   1.632 G
- 0940D9B3 0941E541  abc.8   873    35    20    10   316   31.00   1.629 G "p873_p53dimer873"
- 0941E5C7 0942EEEA  abc.9   872   247    15     2   316   31.00   1.644 G "p872_p53dimer872"
- 0942EF62 0943FAD1  abc.0   873   188    12     5   316   31.00   1.630 G "p873_p53dimer873"
- 0943FB67 0945081D  abc.1   872   276     5     4   316   31.00   1.622 G "p872_p53dimer872"
- 0945088B 094611C2  abc.2   873   283    29     4   316   31.00   1.644 G "p873_p53dimer873"
- 09461215 09481C02  abc.3   230     1    56    51   316   78.00   2.102 G "p230_villin8Murea4nmBox"
- 09481C93 00000001  abc.4  1407    63     0     1   316  235.00   2.048RG "p1407_polyQ20x2 in water"
Average download rate 5.415 KB/s (u=4); upload rate 2.976 KB/s (u=4)
Performance fraction 0.917107 (u=4)
 
The two hexadecimal numbers at the beginning of each line are the starting and finishing time for the unit, so combined logs spanning multiple cycles of the queue and including results from more than one machine can be sorted together into chronological order.  After the dates, the fields are LogID.index, project, run, clone, generation, benchmark, points, points/hour, and project name.  The character "D", "R", or "U" immediately after the points/hour field notes whether the unit was deleted, currently running, or the point value is unknown, respectively.  The character in the next column indicates the core being used, "P" for GPU (10), "T" for Tinker (65), "G" for Gromacs (78), "D" for Double-precision Gromacs (79), "B" for GB Gromacs (7A), "A" for Amber (82), "Q" for QMD (96), "3" for Gromacs 3.3 (A0), "S" for Gromacs SMP (A1), or "N" for Genome (C9 or CA).  The letter will be lower-case if there is no deadline for the unit.

As of 20 May 2005 (functional revision "030"), there is a second compact format which omits several lines of each queue index entry which are not of much interest when using qd simply for looking up work unit history.  Here is what one index entry of that format looks like, as it would be printed when qd is called with the -c flag:
 Index 7: folding now 180.00 pts (0.459 pt/hr) 3.12 X min speed; 60.9% complete
  server: 171.65.103.157:8080; project: 2002, "p2002_ab1-43_4mer_opls"
  Folding: run 17, clone 52, generation 1; benchmark 115; misc: 500, 400
  issue: Tue May 10 10:40:09 2005; begin: Tue May 10 10:40:46 2005
  expect: Thu May 26 18:51:19 2005; due: Thu Jun 30 10:40:46 2005 (51 days)
  user: rph_iv; team: 0; ID: 3539220A7A46065D; mach ID: 1
 
Four precompiled binaries of this command-line version of qd are available.  The native Linux and Windows x86 versions are compiled under Linux, the Windows version cross-compiled with mingw.  The OpenBSD version is natively compiled under OpenBSD and hosted courtesy of Alex Kirk.  This file presently is in a.out format, suitable for OpenBSD V3.3 or earlier.  The link below will fetch the executable file directly from his web site, which, according to him, should always reflect version changes within a day.  The Mac OS X CLI version is similarly automatically recompiled daily, and hosted courtesy of Kevin Bernhagen.  This version comes as a compressed tarball, which includes a compiled mac_qd executable program file, packaged with qdinfo.dat and emprotz.dat.  My local mirrors of these downloadable files will usually not be as up to date. 

Depending on the download method, non-Windows users may have to change the permissions of the downloaded file to make it executable.

If you have any trouble with these precompiled versions, please let me know.

Note for Windows users: This program must be run from the prompt in a command (DOS) window or its output won't stay on the screen.  The simplest way is to put the binary file qd.exe in your folding directory (where queue.dat is), use the appropriate cd commands in the command window to make that the current directory, then type the command qd, with flags as desired.  If you want to capture the output, either cut and paste from the screen or redirect it to a file.

The precompiled versions print timestamps in local time.  For UTC, use the -z command-line switch.
The files below are buggy and have not been updated since 11 August 2005.
Updates for qd, qdinfo.dat and qdiprint can be found on the qd-tools webpage.
The qd versions below are kept for historic reasons.
The bugs have been fixed in the qd-tools version.
Linux Version   qd (34K)
Windows Version   qd.exe (34K)
OpenBSD (a.out) Version   qd (46K)
Mac OS X CLI Version    or (local mirror)   qd.tgz (24K)

Data file, for any system   qdinfo.dat (17K)
A precompiled installable Mac OS X GUI version of qd is also available, courtesy of A. Kraus.  The downloadable tarball contains all the necessary files to install qd as an application.  In this version, the queue file (normally queue.dat in the folding directory) is selected in a Queue → Open... menu after the program is started.  There is also a qd → Preferences panel in which a default folding directory may be specified so that its queue.dat file will be opened automatically at startup.
Mac OS X GUI Version    qd-Cocoa-1-1.tar.gz (54K)    warning - not for V4 client
Mac OS X GUI Version    qd-Cocoa-1-2-beta1.tar.gz (57K)
There may be later versions available directly from his web site.

Here is a sample screen shot of the Mac GUI version of qd:

qd #1

Note that while the presentation might not look as nice, there is somewhat more information available in the Mac CLI version, which can be useful for some diagnostic purposes.


qdiprint.c This program prints out point value information from the qd data file in readable form.  It expects to find a recent copy of the data file qdinfo.dat (see above) in the folding directory, the same way qd does.  With no arguments, qdiprint will produce a full dump of the point table, including all history information.  If it is given numeric arguments, it will print data only for projects with those numbers.  The program is started and run the same way as qd, but with a reduced set of command line flags.  Here is a complete list:
Usage: qdiprint [<flags> <flag args>]* [<project number or range>]*
 -u      Print this usage message (and exit)
 -n file Explicitly specify qd info file
 -t zone Override time zone (+HHMM or -HHMM)
 -z      Force UTC (same as -t +0000)
 -v      Print info version, stop if no project specified
 
Here is a sample of the output, showing the point history for projects 210 to 219 and 1108, including one which has been changed several times:
#> qdiprint 210-219 1108

Project 210, 7.60 points
Project 211, 6.40 points
Project 212, 135.00 points
  160.00 points until Mon Apr 19 20:33:00 2004
  75.00 points until Sun Apr 11 20:33:00 2004
  32.00 points until Wed Apr  7 19:33:00 2004
  6.40 points until Fri Mar 26 17:33:00 2004
Project 213, 6.40 points
Project 1108, 37.00 points
  14.60 points until Mon Apr 19 20:33:00 2004
 
The times are not necessarily very accurate, being determined not so much by when the points were actually changed as by the time I noticed the changes on the Stanford project summary web page.  I check the Stanford page automatically at 0635 and 1835 UTC (0535 and 1735 UTC during the summer), and occasionally when I use the network for other reasons, so my times could be late by as much as twelve hours.

Three precompiled binaries of this command-line version of qdiprint are available.  Depending on the download method, non-Windows users may have to change the permissions of the downloaded file to make it executable.
Linux Version   qdiprint (8K)
Windows Version   qdiprint.exe (7K)
Mac OS X CLI Version   mac_qdiprint.gz (6K)

xyz2pdb.c This program converts a molecule display file in .xyz format into .pdb format.  The .xyz format is used by the Folding@home client and cores, usually seen as the file work/current.xyz, which contains the XYZ coordinates and bonding information for the molecule currently being simulated.  The .pdb format is an industry-standard file format for representing similar information.  There are publicly-available utilities for both Windows and Linux which can display .pdb files.

Most of the code in xyz2pdb is borrowed from fpd, which also does all of this processing of the .xyz data, with the exception of outputting it in .pdb format.

With no arguments, xyz2pdb will act as a filter, that is, it will read the .xyz data from its standard input, and write the .pdb data on its standard output.  It can be given command-line arguments, however, to change this behavior, including several to select only certain features for conversion.  It also will, by default, ignore the bond information in its input file, and rederive it itself, sometimes avoiding errors in the input data.  There is a flag to disable this default.

Here is a list of all of its flag arguments:
Usage: xyz2pdb [<flags> with arguments, as follows]

 -o <PDB file name>        default is <stdout>
 -xyzfile <XYZ file name>  default is <stdin>
 -debug <level>            0 to 9 [0]
 -backbone                 output backbone only
 -noh                      don't output hydrogen atoms
 -noh2o                    don't output water molecules
 -nourea                   don't output urea molecules
 -usebond                  derive bond info from input file only
 -help                     print this information
 
Two precompiled binaries of this command-line version of xyz2pdb are available.  Depending on the download method, non-Windows users may have to change the permissions of the downloaded file to make it executable.
Linux Version   xyz2pdb (15K)
Windows Version   xyz2pdb.exe (15K)

qbm.c This program is a stripped-down version of qd, which only calculates and prints a benchmark value I've proposed for predicting the performance of a machine with Folding@home work units.  A similar value is printed by qd as the last line of its output, differing slightly because qd takes the partial current unit into account and qbm does not.

NOTICE: As of 1 May 2003, the point value table in qbm.c will no longer be regularly kept up to date on this web page.  Put a recent copy of the data file qdinfo.dat (see above) into the folding directory and qbm will use it.


qfix.c This program will attempt to repair the queue.dat file if it is suffering from several sorts of errors the client has, from time to time, made.  It will try to do the following repairs: Note that this program is potentially dangerous to your Folding@home work queue, since if it finds something it thinks is wrong, it will rewrite the queue.dat file.  It is strongly recommended that a copy be made of queue.dat before running qfix.  It will also be a good idea to stop the running client while running qfix.  If you don't, nothing really bad will happen, except that the client won't notice that anything has been done, and it will eventually overwrite the fixed queue with its own internal data.

Three precompiled binaries of this command-line version of qfix are available.  Depending on the download method, non-Windows users may have to change the permissions of the downloaded file to make it executable.
The files below don't support FAH clients newer than v5,
and have not been updated since 11 August 2005.
Updates for qfix can be found on the qd-tools webpage.
The qfix versions below are kept for historic reasons.
The bugs have been fixed in the qd-tools version.
Linux Version   qfix (8K)
Windows Version   qfix.exe (9K)
Mac OS X CLI Version   mac_qfix.gz (6K)

qgen This program will attempt to rebuild the queue.dat file if it has been lost or is unavailable.  It can be used to recover orphaned work, or to prepare results to be returned by a machine which did not do the calculations.  In cases where qfix can not adjust an existing queue.dat file, qgen might still succeed, but it is more complicated to run.  Use qgen only if other methods have failed.

The source for qgen is not being distributed at this time.  If you think you want qgen, go to this page and read the directions.


wuinfo.c This program will look for wuinfo_xx.dat files in your folding work subdirectory and print the unit progress it sees there.  It is an extremely simple program, meant to be used mainly as a diagnostic in case unitinfo.txt doesn't contain what is expected.

Two precompiled binaries of this command-line version of wuinfo are available.  Depending on the download method, non-Windows users may have to change the permissions of the downloaded file to make it executable.
The files below may crash if they process files with 0 completed and/or total steps,
and have not been updated since 11 August 2005.
Updates for wuinfo can be found on the qd-tools webpage.
The wuinfo versions below are kept for historic reasons.
The bugs have been fixed in the qd-tools version.
Linux Version   wuinfo (4K)
Windows Version   wuinfo.exe (5K)

This page has been accessed times since 15 October 2001 up to 10 December 2005.


Dick Howell