November 5, 2002

Using the Foldtraj client
-------------------------

System Requirements 
-------------------
The Distributed Folding client will run on just about any computer, but
there are a few minimal system requirements. Generally, your machine must
have: 

   233 MHz Pentium II processor (or equivalent) or faster 
      (see CompatiblityNotes.txt for details)
   20 MB free hard drive space (and up to 100 MB additional temporary space)
   128 MB RAM 
   An internet connection 
   Colour display (optional) 
   A supported operating system (Windows and most flavors of UNIX) 

UNIX Installation 
-----------------
UNIX users will then have to un-gzip and un-tar the package, like so: 

> gzip -d distribfold*.gz 
> tar xvf distribfold*.tar 

A distribfold directory will be created with the required files in it.  Go
into that directory, and type "./foldit" and hit enter to begin the program. 

Windows Installation 
--------------------
The downloaded file is a ZIP archive so simply use WinZip or PKUNZIP to decompress 
it to an empty directory on your machine. The file should be called
distribfold-current-win9x.zip or something similar.  Once this is done, 
browse to the directory you unzipped the files to and double-click
on the "foldit" icon (the file "foldit.bat") to automatically open up a DOS box and
begin the program.  You may wish to make a shortcut to the program on your
Desktop for quicker access. 

What does it do?
----------------
The Foldtraj client is part of the Distributed Folding Project, an
experiment in distributed computing through the internet to help solve the
Protein Folding Problem, one of the computationally intensive problems facing
scientists of the 21st century.  The program probabilistically generates
protein structures, and uploads them to our server every few thousand.  A
small, colorful protein will build itself up on your screen as the program
generates structures so you can see how many you have made and how fast it is
progressing.  When you want to use your computer again, simply hit 'Q' and the
program will end as soon as it uploads the remaining bit of data to our server
(or even better, leave it running in the background).

Signing up
----------
We require you register in order to participate.  To register, simply visit:

http://www.distributedfolding.org/

and click on the High-Flyers link. Fill in your e-mail address, Organization 
and a password.  You may also optionally tell us a bit
more about yourself by filling in the appropriate fields, such as your
name, address and location.  We assure you that this information will remain
strictly confidential and will not be used or sold to marketing agencies.  On
this site you will also find links to a wealth of information about the
Distributed Folding Project, and the algorithm used by the Foldtraj client to
generate protein folds.

Getting your handle
-------------------
A handle is an 8 character code that is needed so that the server can track structures made
by your computer.  Once you have registered, your handle will appear on the web page, and
you will shortly receive an e-mail containing your handle.  No two
participants will have the same handle.  Make sure you keep this e-mail
message for future reference.

Running the Program 
-------------------
The first time you run the program, you will be asked to enter your handle.
This is the 8-character name that was e-mailed to you when you registered and
identifies any files your computer sends to our server as being generated by
you.  Only proteins generated by a user with a valid handle will be accepted
by the server, so enter it exactly as shown in the e-mail you receive.  You
may use this handle on as many machines as you like, it is simply a way of
identifying yourself in an anonymous fashion.  A few seconds after entering
your handle, the program will begin computing. To quit, press 'Q' and it will exit
within a few seconds (after it finishes the structure it is currently working on
and uploading to our server).  The next time you start the program it will remember
your handle, but if you need to change it for some reason, you can do so by
pressing 'C' when prompted just after starting the program, and then waiting a few
seconds.  The program uploads any remaining protein folding data in its buffer when
it starts.

IMPORTANT: if you wish to collaborate with others, you can now do so AFTER you have
registered.  Simply login with your e-mail and password at our website, and you
will be able to select from a list of possible teams to join.  You will also be
able to choose a Username for yourself, which will be used to identify you, along
with your Organization, on statistics pages and such.  Each team has its own page
of statistics automatically generated for it every few minutes, so even if you are
by yourself you may want to create a team so you'll get a team page made for you.

Checking Progress 
-----------------
Once you have registered, you may login using the handle or e-mail and
password you are registered with.  From here, you will be able to view your
total contribution to-date to the project, and the overall progress.  You may
also download the best structure you have created, and the true protein
structure, and view them with the molecular viewing program 'Cn3D', available
for download for most platforms at:

	http://www.ncbi.nlm.nih.gov/Structure/CN3D/cn3d.shtml

This will allow you to see how you are doing compared to others.  The
information available here may change over time, so check back often!

Communication between Client and Server
---------------------------------------
After every few thousand structures (several hours), or when you exit the
program, information about the structures generated is uploaded to our server.
This includes their size, similarity to the native structure, energy score and
certain structural characteristics.  Also, the complete structure for the
conformer which is most similar to the native that was generated will be sent
and stored on our server.  This ensures that all the best structures will be
saved for later inspection and analysis (unfortunately, we do not have space
to store 10 billion complete protein structures!).  At no time is any
information ever sent to or stored on your computer other than an OK or ERROR
response from the server when your computer sends us data.  Also, the
generated structures and a log file are stored temporarily on your computer
until they are sent to the server, at which point they are automatically
removed from your machine.  This amounts to approximately 20K of data
uploaded to our sever approximately once every few hours.  This should
transfer in under ten seconds even via today's slowest internet connections. 

The client will also check automatically for new versions of itself, and when
one becomes available, an update will automatically be downloaded and
installed (after obtaining your approval first).  All updates are digitally
signed and encrypted to prevent unauthorized updates being sent.  If an
update is downloaded and NOT digitally signed, you will be advised as such
and warned not to proceed with the update.

Otherwise, the new version of the client will then continue running without
further intervention required.  If for some reason the update cannot be
downloaded or installed, you will be told, and either the program will
terminate, or it will continue and try again later.  You can always manually
download the latest version at http://www.distributedfolding.org/

Possible Problems
-----------------
A constantly updated list of known bugs and workarounds can also be found at:
http://www.distributedfolding.org/bugs.html
so check here first if you suspect there is a bug in your version of the
program.  To check your version of the program, run the 'foldtrajlite'
executable, with no arguments, at a DOS or UNIX prompt.  The first line
should have the compilation date in it.

Due to the nature of the program, an internet connection is required to send
structure data to our server.  The program is smart enough to detect if the
network is down and cannot contact the server for some reason  In such cases,
it will buffer any such data and try to send the unsent data along with new
data after completing the next unit of work.  If the network is unavailable
for approximately 24 hours, the program will eventually give up and terminate,
displaying an error message to this effect on your screen.  Warning messages
may also be displayed on the client screen if network problems or other
problems are encountered. 

Be careful to enter your handle exactly as given.  If you make a mistake, the
client will eventually terminate telling you you either have network problems
or have given an invalid handle.  Especially be sure not to confuse 0 with o,
and l with 1.  If you find a mistake, you can change your handle as described
above under 'Running the Program'.

We have also observed that strange network problems can be cause by caching
http proxy servers.  If you ISP uses one, it may possibly interfere with
communication to our server, so if you experience problems and can bypass
the proxy, doing so may fix the problem.

Using a Proxy Server
--------------------
If you don't know what a proxy server is, you probably don't need to read
this section.  If your network is set up to block most outgoing traffic on
port 80, the client may not be able to connect successfully to our server
(for example, if you require a proxy server to browse the web).  If you
suspect you are in this category, simply create a small text file called
"proxy.cfg" in the same directory as the client program (and this readme).
In it type two lines; the first line is the name of your proxy server and
the second is the proxy port (often 8080).  If this file is found by the
client at startup, it will try to connect to our server using the proxy
specified.  Here is a sample proxy.cfg:

proxy.foobar.com
8080

If your proxy server requires Basic Authentication, simply add your
username and password after the port number, like so:

proxy.foobar.com
8080
username
password

If your proxy server uses NTLM Authentication replace username above
with username.DOMAIN where DOMAIN is your NT Domain/workgroup name.

Non-interactive Auto-update
---------------------------
For your security, you will be asked for confirmation before any updates
are download and installed on your computer.  All updates are digitally
signed and so if is fairly safe to always allow digitially signed updates
to be installed.  A malicious user would have to compromise the private
encryption key in order to "spoof" and update and make it appear to come
from us.  Thus you have the option of allowing the client to automatically
accept and install digitally signed updates (and automatically refuse
unsigned ones).  By default this feature is disabled and you must give
your consent for downloads to begin, because we feel the choice should be
that of the user.  To enable this feature and allow automatic updating
without your intervention required, simply create a text file in the same
directory as the client, called "autoupdate.cfg" with the the digit 1 on a 
single line.  If you change your mind, simply remove the file, and it will 
revert back to its default behaviour the next time you run it.

Increasing the Buffer Size
--------------------------
By default, if the client has generated six sets of data and not been able to
upload them to our server (for example, because you are disconnected from the
network), it will no longer run until your network is restored and the data
can be uploaded and cleared from your machine.  This is to prevent data from
accumulating on your hard drive.  If you intend to be running the client
offline a fair bit, you may wish to allow it to buffer a larger amount of
work however (at the cost of taking up several more megabytes of disk space).
To do so, simply edit the foldit script (foldit.bat on Windows) and add "-df"
(without the quotes) to the end of the line containing
"foldtrajlite -f protein -n native".  If you later change your mind, simply
remove the -df.
Because data packets are now much smaller than they used to be, this option
is deprecated and it is suggested you always use '-df'.  This will be the
new default or this option may be removed/ignored in a future release.

Quiet Mode
----------
To run the client in quiet mode (i.e. no output whatsoever to the terminal),
simply edit the foldit script (foldit.bat on Windows) and add "-qt" (without
the quotes) to the end of the line containing "foldtrajlite -f protein -n
native".  This may be useful if you are, for example, starting jobs remotely.
You can then terminate jobs by removing foldtrajlite.lock or hitting the 'Q'
key (the latter works on Windows only however).  It is recommended you select
"E-mail me when updates are available" on the logged-in page at
http://www.distributedfolding.org if you are running in quiet mode, or else
you won't be aware when a new update is required.  Alternatively, see
non-interactive auto-update above.  To check progress while in quiet mode, a
file called "progress.txt" will be written to the directory where the program
is installed so you can monitor its progress still.  You may customize this
further by adding '-g ###' where ### is a number, to the foldit script.
This is how often (in number of structures) you want this progress.txt to
be updated, to avoid excessing disk writing.  If you put '-g 0' this will
disable the progress.txt output altogether.

Changing the priority of the client [Advanced Users]
----------------------------------------------------
You can change the default priority of the client by modifying the foldit
script as described above for quiet mode and increasing the buffer size.
Simply add the switch '-p ##' where ## is the desired priority.  This can
range from -20 (extremely aggressive; will pre-empt most other tasks) to
the default of 20 (very passive, only runs when the CPU is idle).  On UNIX
the full range from -20 to 20 is available.  Windows defines three process
priority levels: Low, Normal and High.  Within each of these are several
thread priority levels which allow 'fine tuning'.  Thus the same range
[-20, 20] is used On Windows and mapped accordingly.  Use 15 for Low, 0
for Normal and -15 for High.  Other values will more finely tune the
priority further.

Disabling Network access
------------------------
If you are running on a machine behind a strong firewall, or a machine with
modem access to the internet, or no access at all, you may wish to tell the
client not to access the network.  In this case, all attempts to access the
internet will be bypassed.  Simply add '-i f' to the foldit script as
described above for other optional features.  You will probably want to
increase the buffer size if you do this as well (see relevant section above).
Eventually you will need to either connect to the internet and remove the
'-i f' option, or copy the entire directory to another machine which is
connected to the internet to allow results to be uploaded.
IMPORTANT: it is highly reccommended that you use an increased buffer size
with this option (see Increasing the Buffer Size, above)

Upload Only Option
------------------
If you add '-u t' to the foldit script, the client will perform all normal
startup procedures such as checking for new versions and uploading buffered
data, but then it will exit before starting to generate any structures.
This may be useful for people making 3rd party interfaces to the software
or writing other sorts of scripts.  The 'average' user probably will not use
this option.  All buffered data will be uploaded whether you have increased
the buffer size or not.

Changing Upload Frequency [Advanced Users]
------------------------------------------
You can add '-s ####' where #### is a number between 1000 and 10000 to the
foldit script, to specify the number of structures to build between uploads.
By default, an interval of 5000 is used if you are not connected to the
internet, and if you are connected, by default an interval is obtained
dynamically from the folding server.

Running as a service [Windows NT/2000/XP only]
-----------------------------------------------
The Windows version of the client can be set up to run as a normal Windows NT
service, so that it will start automatically whenever your computer starts up
and run in the background until you shut down.  Structures will be uploaded
every 5000 still, and buffered for later upload at shutdown (so your shutdown
procedure will not be delayed).  It runs at low priority so other tasks will
push it out of the way and so it should not noticeably slow your machine
down.  Be warned that it will only upload after making 5000 structures (a few
hours, depending on your machine speed) so make sure you are connected to the
internet when using the client as a service.  Also, updates will automatically
be accepted (provided they are digitally signed) in this mode and a large
amount of data may be buffered if you do not connect to the network for a long
period of time.  To check progress while running as a service, a file called
"progress.txt" will be written to the directory where the program is installed
so you can monitor its progress still. 

To setup the program to work as a service:

1. Open a DOS prompt to the directory you installed the client.
2. If it is not already there, create a new file called "handle.txt" and in it
	type your 8 character handle followed by Enter (or alternatively, run
	foldit.bat first, enter your handle when asked for it, then quit)
3. Type: foldtrajlite /install (and hit Enter)
4. The next time you reboot your machine it will start automatically

To remove the service:

1. Go to Administrative Tools -> Services
2. Find and Stop the service called Distributed Folding Project
3. Open a DOS prompt to the directory you installed the client.
4. Type: foldtrajlite /remove (and hit Enter)
5. It will not be run on your machine automatically anymore

You may install a second instance of the service by changing step 3 above 
from 'foldtrajlite /install' to 'foldtrajlite /install2'.  Similarly, to
remove this second instance, change step 4 to 'foldtrajlite /remove2'.
Note that if you wish to run two instances, you must install two full
copies of the software in separate directories and install one using 
/install and the other /install2.  Not following this procedure correctly
will result in unpredictable behaviour.

Configuring the service [Windows NT/2000/XP only]
-------------------------------------------------
You should have a SERVICE.CFG file in your client directory after
following the above steps.  If it is not there, remove and re-install
the service.  The first line of this file must contain a number
identifying whether it is copy 1 or copy 2 of the service.  Next, you
may include any of the following options in any order if you wish:

useram=1        makes use of extra RAM for improved speed (see -rt option
                elsewhere in this readme); default is useram=0
priority=###    where -20<=###<=20 sets the priority of the task just like
                the -p option (20=passive, -20=aggressive); default is 20
progress=###    where 0<=###<=100 sets the update interval for the
                progress.txt file, like the -g option (0=disable)
                default is 50
uploadfreq=###  where 999<=###<=10000 controls the upload frequency like
                the -s option; default=999=assigned from our server
connect=0       disables internet usage - use this if you are on dial-up
                or temporarily unable to access the internet for some
                reason; you must eventually remove this to upload your
                data, but your work will be buffered until then; works
                the same as the -if option; default is connect=1
uploadonly=1    behaves as the -ut option, instructing the program to
                upload all buffered work and then terminate.  Do NOT
                combine with the connect=0 option!  Default is
                uploadonly=0

Running Non-interactively or on a Cluster [Advanced Users]
----------------------------------------------------------
You may wish to run the client in a mode requiring absolutely no user
interaction.  This is especially convenient if you want to run it on, for
example, a Beowulf Cluster.  For your convenience we have made it easy to do
so.  See also the section above on "Non-interactive auto-update".

To run on a cluster computer (and we encourage you to do so if you have
access to such a machine):

1. Decompress the package on one node as described above, and add proxy
information as described above if necessary.  Then, create a text file
called "handle.txt".  It should contain a single line with your 8-character
handle you received upon registration.  Save it in the same directory as
the other files.

1a. Edit the foldit script and add "-qt" (without the quotes) to the end of
the line containing "foldtrajlite -f protein -n native".  This supresses all
program output.

1b. Try running the client on the node to ensure it starts without any input
from you.  If any updates are available, for example, you will have to
give it permission to download and install them.  Once you have ensured your
client is up to date, proceed to step 2.

2. Now distribute the directory to the other nodes of your cluster (presumably
you have some script(s) to efficiently do this).  Each node will need a
complete copy of the client software.

3. Now start the "foldit" script on each machine (again, you presumably have
some scripts to do this efficiently.  It will run until you stop it as
described in step 4, or until a mandatory update is released (in which case
it will NOT be automatically installed, the client will simply exit once you
have performed step 4; you must then manually run the client on a node, give
permission to install the update, and then go back to step 2).

4. To halt the screensaver on one or all the nodes, simply delete the file
"foldtrajlite.lock" which will be found in the same directory as all the other
files.  The program will complete the structure it is working on, upload any
remaining data to our server, and then terminate gracefully (could take up
to two minutes depending on your connection and how much data needs to be
uploaded, so please be patient).

Making it run faster [Advanced Users]
-------------------------------------
The software can be made to run roughly twice as fast, at the cost of using
more memory.  Normally the software uses about 25MB RAM while running, but
if you add the '-rt' option to the foldit script, the client will then use
up to 150MB RAM, but run twice as fast.  Make sure you have enough free
RAM (and NOT virtual memory) before using this option or you will not benefit
from the speed improvement.  For the same effect with the Screensaver, simply
select the 'use more RAM' option in the Configuration Dialog Box.  If you
are running the Windows NT/2000/XP service mode of the client, edit the
service.cfg file (you may have to /remove and then /install the service if
this file is missing in your folding directory).  The service.cfg normally
contains a single line with a number (to tell it whether it is copy #1 or
copy #2 of the service).  Add a second line to this file with the text
'useram=1' (without the quotes) in order to tell the service to use up to
150MB RAM as well.

About the Client 
----------------
Sure, we could give you a big flashy 3-D interactive screensaver showing the
actual protein being built up and letting you rotate it around in 3-D space as
it is being built, and it would probably look really cool.  In fact we have
done this for Windows (avaiable on the same site you downloaded this client).
But we want to spend your CPU cycles where they count, in the actual
scientific computation.  Hence we recommend that even Windows users use this
text-based client instead.  Here we have opted for a more "abstract"
representation of the folding protein, using color ASCII art.  While not
looking like a true protein, it should still give you an idea of what is going
on inside your computer's head while the program is running.  Each structure
looks completely different, and each one is only a single sample of an
extremely enormous conformational space.  As a bonus, since the client runs in
text mode, you can even run it through a Telnet session or a dumb terminal! 

Final Words
-----------
Please visit the official Trajectory Directed Ensemble Sampling (TraDES) web
site at:

http://bioinfo.mshri.on.ca/trades/

to learn more about protein folding and Foldtraj.  Visit the Distributed
Folding Project web site for more info about this client:

http://www.distributedfolding.org/

Please direct any technical support questions, comments or suggestions to us at:

trades@mshri.on.ca
