********************************************************************
**   ProActive Grid Tutorial
**
**   ObjectWeb Conference '05
********************************************************************

NB : explanation is given for a unix-like platform.
Windows users will find example scripts in ProActive/scripts/windows/
and will run .bat script files



1. Software installation
********************************************************************


- install a 1.4+ jdk on your computer

- set the JAVA_HOME environment variable to the installation directory of your jdk

- unzip the prepackaged distribution that contains :
	- ProActive (latest stable version)
	- tutorial text 
	- visuals 
	- skeletons (java files + deployment files)
	- ant files for automatic building of code examples
	- ssh keys for remote connections (non-encrypted : use the same key for both deployment and tunneling)

- compile ProActive and examples
 --> go to tutorial/ProActive/compile 
 --> run ./build examples
 --> build the javadoc : run ./build docs
 JavaDoc will be available in tutorial/ProActive/docs/api/




2. Get a grip on some ProActive features and tools :
********************************************************************



2.1. start the matrix example
-----------------------------
--> go to tutorial/ProActive/scripts/unix/
--> run ./matrix_start.sh

In order to compute a matrix multiplication, the calculation is divided among matrix computers.
A "launcher" active object asynchronously sends parts of the matrix to the matrix computers.

2.2. start the IC2D monitoring GUI
----------------------------------
--> go to tutorial/ProActive/scripts/unix/
--> run ./ic2d.sh

menu "monitoring/monitor a new rmi host" allows you to monitor hosts with a rmi registry
--> try it on your local computer (default proposed host)

menu "monitoring/legend" describes what you can see

--> right-click on the "world panel" in the center and select "VM Layout - Vertical"


2.3 launch asynchronous computations
------------------------------------
 
by pressing <return> in the matrix_start shell

Because the invocation is asynchronous, you can actually launch several computations simultaneously.

It is possible to drag-and-drop active object from one virtual machine to another. The computation
works regardless of the location of the matrix computers.




3. Programming
********************************************************************


We will write a program of the same flavor than the previous matrix example. The objective is to evaluate the PI number
using the Bailey-Borwein-Plouffe formula (see the /doc/miracle.pdf file for further explanations).


PiComputer is in charge of computing an interval
Interval is the input data for PiComputer instances
Result is the output data for PiComputer instances
PIBBP is the main class that starts the computation

The sources are in the directory : tutorial/src/Examples/org/objectweb/proactive/tutorial/


We will work only on the PiBBP class, the other classes are already written.
In the PiBBP class, most of the code is already there, we will only add the remaining instructions, the ones
that use the ProActive API.

*** the code to complete is preceded by //TODO tags.

*** refer to the ProActive API documentation for the methods and parameters to use.
(classes we will use are : org.objectweb.proactive.ProActive and org.objectweb.proactive.core.group.ProActive)


3.1. Simple example
-------------------

This is a simple client - server communication.

in the PiBBP class :
-->implement the runSimple() method :
----> create a PiComputer object (giving the total number of decimals as a parameter to the constructor)
----> define an Interval to compute
----> compute this interval and get the result in a variable of type Result

--> run the example using the tutorial/scripts/build script file :
./build run

--> choose the number of decimals to compute (say 1000 for instance)
--> choose 1. (run simple)
--> choose 1. (no deployment)



3.2. Parallelization
--------------------

Now we will parallelize the computation among members of a group of PiComputer active objects.

-->implement the runParallel() method :
----> create a group of PiComputers in the current VM 
------>(check the javadoc to find the appropriate method in the
org.objectweb.proactive.core.group.ProActiveGroup class)
----> the "distribute" method returns a group of Interval instances that will given as parameters to the PiComputer instances.
----> scatter the parameters
----> compute

--> run the example using the tutorial/scripts/build script file :
./build run

--> choose the number of decimals to compute (say 1000 for instance)
--> choose 2. (run parallel)
--> choose 1. (no deployment)


3.3. Distribution
-----------------

Now we want to parallelize the computation among different virtual machines : each member of the group is
instantiated on a separate virtual machine.

The virtual machines hosting the PiComputers are abstracted as a single entity : a virtual node named "computers-vn".
The same code referring to this virtual node can then be reused without any modification. It can be deployed onto different infrastructures.
We just have to use a different deployment descriptor (deployment on localhost, on a LAN, on a cluster, on a Grid).

--> implement the runParallelDistributed() method
----> instantiate a group of PiComputer instances on the virtual node "computers-vn".

Depending upon the configuration of the network, we will either :

--> customize the tutorial/descriptors/LAN.xml file : it should refer to the host present in the DMZ, which should be accessed through ssh.
This configuration should be straightforward if you are using linux, or cygwin under windows, where batch ssh commands are available. 
In other cases, it should be easier to try the acquisition method (next)

or

--> customize the tutorial/descriptors/acquisition.xml file so that it refers to other existing runtimes.

--> a runtime named "PA_JVM1" can be created locally by launching the script "tutorial/scripts/startNode rmi://localhost/node1".
This runtime can then be acquired remotely in the deployment descriptor as "rmi://the_remote_host:1099/PA_JVM1" 
(1099 is the default port for the rmiregistry)

We can first can try this on our local machine, then on someone else's.


3.4 large scale deployment
--------------------------

From the host in the Demilitarized Zone, you can start a deployment on the cluster of INRIA Sophia and on 
the cluster of Amsterdam (University of Vrije).

Use the private key tutorial/ssh/atacama for the connexion to the remote host as "guest".

--> in tutorial/scripts/ run the build script to start the application
ve more computers, so you can choose a number higher than 1000, say 3000 for a quick run
--> choose 2. (run parallelDistributed)
--> choose 5 or 6 or 7. (deployment on INRIA's cluster, Amsterdam's cluster, or both)


**** do not launch many computations simultaneously on the clusters : the nodes are not
reserved for us, and we are not the only users today.









