======
PLUTO
======
=============
Introduction
=============
-The purpose of this file is to get you started with the Pluto tool. Most of 
 the information here are lifted from the README and DOC.txt files that come
 with the Pluto tool distribution. Read these files for more details.

-Download Pluto and examples by typing 
    git clone git://repo.or.cz/pluto.git 
 which will create a directory called pluto.

-The Pluto tool is installed on the CS linux machines, so you can 
 play with some examples by typing:
    polycc test/seidel.c --tile –parallel
 in the pluto directory you cloned above.

-Pluto is a tool for automatic parallelization/optimization.

-Polyhedral model based.

-Source to source transformation of C programs.

-Provides mechanisms for coarse-grain parallelism and data locality
 optimizations simultaneously.

-Pluto tries to find affine transformations for efficient tiling and fusion.

-Can generate OpenMP parallel code by adding pragmas to C code (C to OpenMP C).

-Allows user to specify some optimizations details like tiles sizes, unroll
 factor, and fusion structure.

================
How Pluto works
================ 
-The tool accept C code as input.
-A polyhedral representation is extracted from the input code.
-A dependency analysis follows.
-Based on the analysis results, Pluto chooses the transformations to apply to
 the C code automatically.
-Finally, a Pluto post-processing is applied to generate the parallel code by
 inserting OpenMP pragmas. Or to apply optimizations like loop unrolling and
 vectorization.
-These steps are run by the polycc, the wrapper script which does all the 
 transformations as will be shown soon.


==============
Installation:
==============
The tool is supposed to be installed on our CS department machines by the end 
of Wednesday Feb. 29th. You can also install it on your machine using the 
following steps if you have a linux distribution:

-downloaded pluto-0.8.0.tar.gz from http://pluto-compiler.sourceforge.net/
>tar zxvf pluto-0.8.0.tar.gz
>cd pluto-0.8.0/
>./configure [--enable-debug]
>make

-Notes on installation:
 -I used ./configure without the debugging option
 -There was an error regarding missing GMP, GNU Multi Precision library: 
 -The problem was solved after installing libgmp3-dev:
  >sudo apt-get install libgmp3-dev
 -This works for Ubuntu. If you have a Fedora distribution you can install the 
  library using:
  >sudo yum -y install gmp gmp-devel' on a Fedora, or 

-To test that everything is working:
 >make test
-This will run many example and show a lot of output.


=================================
Using Pluto and Running examples:
=================================
-You need to enclose the code to be processed by Pluto within:
#pragma scop
//code to parallelize/optimize goes here
#pragma endscop

-Assume you have the C input file myCode.c, you can run Pluto on this file using:
 ./polycc myCode.c --parallel --tile

-polycc is the wrapper script. It does the transformation.
-This will generate C-OpenMP code file myCode.pluto.c
-You can use the following command on the veges to compile the OpenMP code:
 >gcc -O3 -ftree-vectorize -msse3 -DTIME -fopenmp myCode.pluto.c -o par -lm
-This will generate an executable called "par"
-To run the resulting executable on veges you can first specify number of 
 threads:
 >set OMP_NUM_THREADS=4
 then 
 >./par
-The execution time for the optimized parallel version should be faster than
 the that of the sequential version for this example.

-Another way to run Pluto is by using the Makefiles provided in the
 /examples directory. Browse to any of the /examples directories then do a make:
 This will build a number of executables:
 -'orig': original code.
 -'tiled': tiled code.
 -'par': OpenMP parallelized+locality optimized code.
 -'par2d' code with two degrees of parallelism provided it exists.
-To generate any of the previous executables do: 
 >make <target>', where target can be orig, orig_par, opt, tiled, tiled_par
-You can run those executables and compare the differences in execution times. 
  
-Important: if icc is not available on your machine, then line number 7 in the
 file /examples/common.mk should be commented and line 8 should be 
 uncommented so that pluto would use gcc.

-Pluto provides a number of useful command line options. Here are two important
 ones: 
    --tile
    This is used to tile code. Tile sizes can be changed by editing the file
   'tile.sizes'.

    --parallel
    This is used to parallelized code with OpenMP pragmas.