** JoCamls 'R Us: A not so simple ray tracer in JoCaml **

OVERVIEW

  This program is an example of making a pre-existing OCaml  program
  distributed thanks to JoCaml. It is intended to illustrate the
  'distributed loop' idiom of JoCaml in a realistic context.
  Information on JoCaml is available at <http://jocaml.inria.fr/>
  
  The pre-existing program is the ray tracer written by the
  Camls 'R Us team at the ICFP 2000 programming contest.
  The scenes are described using a rather sophisticated language described
  on the contest page <http://www.cs.cornell.edu/icfp/>

  We all know that ray tracers are 'concurrent by nature', but some
  interesting issues remain: such as load balance, management of
  failures... Those points are handled in files renderServer.ml
  and renderClient.ml
  

CREDITS AND LICENSE

  The ray tracer code is from team Camls 'R Us
    * Sébastien Ailleret
    * Pascal Cuoq
    * Damien Doligez
    * Robert Harley
    * Fabrice Le Fessant
    * Xavier Leroy
    * Alan Schmitt
  See <http://caml.inria.fr/pub/old_caml_site/icfp00-contest/>


  This program is distributed under the terms of the GPL (GNU Public License)
  version 2, available from http://www.gnu.org/licenses/gpl.txt.

COMPILATION
  % make

  This builds four programs
    seq.opt    : A sequential ray tracer, equivalent to the one of Camls'R Us
    server.opt : Server for distributed execution, basically interpret
                 gml sources and organize work sharing.
    client.opt : Client for distributed execution, basically performs the
                 ray tracing work.
    spy.opt    : A specialized tool for displaying the images being computed.

  There are bytcode versions of the same programs: seq, server, etc.
  % make byte 

SIMPLE USAGE

  To have N computing agents on your machine

  % ./server.opt [other options] -nclients N < source.gml

  The -graphic option  shows the images being computed (have fun).
  For instance:
  % ./server.opt -antialias -graphic -nclients 4 < gml/fractal.gml


  Performance much depends on the scenes. Let us take benchmarks
  that are nice to concurrent version (ie complex images, with antialiasing
  enabled).

  The computer is a 4 X 3 GHx PC (2 processors X 2 cores)

  Sequential
  % ./seq.opt -antialias < F 

     F                Real time (sec)
     gml/fractal.gml  65
     gml/dice2.gml    16.7

  Concurrent
  % ./server.opt -antialias -nclients N < F

  F is gml/fractal.gml

    N   Real time (sec)
    0   oo
    1   75
    2   41
    3   31
    4   26

  F is gml/dice2.gml
    N   Real time (sec)
    0   oo
    1   17.9
    2   9.1
    3   6.3
    4   4.9


All images:
  % cat gml/*.gml | ./seq.opt -antialias 
     ->  910sec
   % cat gml/*.gml | ./server.opt -antialias -nclients 4
     ->  273sec

ADVANCED USAGE
  On the one hand, launch the tracer on machine A.
    A> ./server.opt -antialias < gml/fractal.gml
  
  On the other hand lauch as many computing agents as you wish
    B> ./client.opt -nclients nb A # nb computing agents on machine B
    C> ./client.opt -nclients nc A # nc computing agents on machine C
    etc.

  On a Grid of 11 biprocessors clocked at 2GHz,
    (A = Grid front end, B = node1, C=node2....)
    With 2 computing agents per processor -> about 9sec
    With 1 computing agent per processor  -> about 11sec
    Sequential                            -> about 56sec

All imagess test on the grid (2x11 GHz)
    -> about 57sec


BONUS

  The server program accepts additional options, here are the most useful
  ones.

  Information on program behavior.
    - Live demo: -demo
    - Print some statistics: -stats


  Nicer images at reasonable price.
    - Adaptive antialiasing: option -adapt

  Combining the following two options may speed up animations
  In the case of numerous simple images, increase both parameters.
    - Compute several images concurrently: -nimages n [default 1]
       *  n <=0 yields maximal concurrency
       *  n > 0  compute at most n images
    - Control task granularity: -nlines n [default 1]


  Sub-directory 'more' contains additional examples. Note that some
  example require pre-processing with cpp.