Basic README file for TaskSpaces limited experimental release 0.1
=====================================================

description:
----------------
This limited experimental release of the TaskSpaces framework for scientific computing
on computational grids contains the code for the Framework as described in 
   Hans De Sterck, Rob Markel, and Rob Knight, `TaskSpaces: A Software Framework for Parallel
   Bioinformatics on Computational Grids', Chapter in textbook `Parallel Computing for Bioinformatics
   and Computational Biology', A. Zomaya, editor, John Wiley and Sons, 651-669, 2006.
It also contains code for the RNA motif calculations from
   Rob Knight, Hans De Sterck, Rob Markel, Sandra Smit, Alexander Oshmyansky, and Michael Yarus,
   `Abundance of correctly folded RNA motifs in sequence space, calculated on computational grids',
   Nucleic Acids Research 33, 5924-5935, 2005.
Both articles are included in pdf format in the Documents directory of this release.

warning:
------------
This limited experimental release is not for the faint-hearted.
It is a snapshot of the research code at the end of the project,
and is provided as is. The code is not cleaned up and contains
many unused parts. The code is not documented properly. 
Unfortunately, we cannot provide support for this limited release
as we have moved on to different projects.
That said, the release contains a working 'HelloWorld'
example, and the working code for the RNA folding
problem. The purpose of this release is to give access to the
ideas and implementation of TaskSpaces to whoever is
interested in the inner workings of TaskSpaces or in
experimenting with the underlying design ideas, or in
how we did the RNA application. 

basic setup:
----------------
You need the following machine setup to run TaskSpaces:

(a1) a web server machine that can serve all compiled code files
and some configuration files
(a2) one or more worker machines that can run worker processes
(a3) one or more 'bag' machines that can run the task bag and result bag
(a4) an application machine from which you start applications and retrieve results

The 4 system components can also be run on one and the
same machine if you desire. Note that firewall issues may
get into the way of the system performing correctly. It may
be necessary to (partially) disable firewalls on machines that
participate in the grid. You need to know the ip address
or hostname for the web server (a1) and bag (a3) machines
(see step b1 below).

For what follows, #/distrJul2006 will represent the path to the
directory in which you have found this README file.

demo: 'HelloWorld'
--------
Follow these steps to try out the code with a simple 'HelloWorld' application:

(b1) edit the file #/distrJul2006/taskspaces/properties/properties
to specify the settings for your system
(follow the instructions in the file)
(b2) copy the directory #/distrJul2006/taskspaces onto your web server
(b3) copy the Runner.class from #/distrJul2006/taskspaces/system
onto the worker (a2), bag (a3) and application (a4) machines
(b4) start two bags on the bag machine (a3) in two different terminals (these will be the task bag and the result bag):
> java Runner <webserver>/distrJul2006/taskspaces/properties/properties taskspaces.system.Space
> java Runner <webserver>/distrJul2006/taskspaces/properties/properties taskspaces.system.Space
(Replace <webserver> by the URL of your webserver.)
(b5) start one or more workers on the worker machines (a2):
> java Runner <webserver>/distrJul2006/taskspaces/properties/properties taskspaces.system.Node
(b6) start the test application on your application machine (a4):
> java Runner <webserver>/distrJul2006/taskspaces/properties/properties HelloWorld
and type in how many tasks you want

Enjoy! (If something goes wrong, check your properties file, and
check firewall issues.)

After successful completion of the run, the collected results (just
some of the screen output of the various workers) are in the file:
   HelloWorldOutput
on the application machine (a4), and system log files are in the
   logs
directory on the bag machine (a3) and worker machines (a2).

You can relaunch the application as you wish.

You can modify the HelloWorld application for your own
purposes or experiments using the information below.

If you want to explore the RNA motif code referred to above,
look at the README file in the directory
#/distrJul2006/taskspaces/applications/ilehh .

(on my system, the above commands spelled out read:
java Runner hans-de-stercks-computer.local/~desterck/distrJul2006/taskspaces/properties/properties taskspaces.system.Space
java Runner hans-de-stercks-computer.local/~desterck/distrJul2006/taskspaces/properties/properties taskspaces.system.Node
java Runner hans-de-stercks-computer.local/~desterck/distrJul2006/taskspaces/properties/properties HelloWorld
)

changing and compiling the code:
---------------------------------------------
the HelloWorld application code:
> cd #/distrJul2006/taskspaces/applications/HelloWorld
> javac -classpath ../../../:.: HelloWorld.java

all the system code (including the Runner code):
> cd #/distrJul2006/taskspaces/system
> javac *.java

Don't forget to copy any modified Java classes onto your
webserver!

(on my system, the above commands spelled out read:
cd /Users/desterck/Sites/distrJul2006/taskspaces/applications/HelloWorld
javac -classpath ../../../:.: HelloWorld.java
cd /Users/desterck/Sites/distrJul2006/taskspaces/system
javac *.java
)

operating remarks and known issues:
---------------------------------------------------
-You need to run every component in its own window (this means
that you have to keep open many windows...); running some of the
components as background processes has not been tested.
-Tasks are distributed using a single 'task agent' that is sent from the
application machine to the task bag; this reduces the amount of
communication between those two system components.
-System components cannot be reset easily; use control-C and restart
to reset any component; it may be necessary to restart all components
when you restart one of them.
-After any part of the code has been changed and recompiled, all
components have to be restarted manually.
-When starting the system, the bags have to be started first, and the
workers later; otherwise, workers will not take off properly.
