
This example shows how we use DIET in the Grid-TLSE project (gridtlse.org).
We selected a simple scenario where we want to solve a linear system Ax=b.
The tools to solve the system are not given in this example; we simply simulate
these solvers by programs that copy input files in an output file.

Questions: gridtlse-project@listes-diff.enseeiht.fr

Hierarchy of the package
------------------------

TLSE
 |
 | client
   |
   | bin     # client binaries
   | config  # client configuration files
   | work    # client workspaces
   | input   # examples of input file
 |
 | dagda
   |
   | work
     |
     | MA  # storage directory of the MA
     | SeD # storage directory of the SeD
 |
 | service
   | 
   | bin    # diet service binary + deployment scripts
   | config # diet configuration files
   | log    # log
 |
 | solvers
   |
   | bin  # solvers binaries
   | work # solvers workspaces

The files that need some modifications to match your computers contains TO ADAPT

0. Needed packages
   ===============

  + DIET
  + libcurl4-openssl-dev
  + omniorb4
  + libomniorb4-dev
  + omniidl4
  + omniorb4-nameserver

1. Configuration file : tlserc.sh

 a - modify it in order to give the TLSE directory
 b - execute it to define the environment variables

1. Compilation (src directory)
   ===========================

 a - modify Makefile.inc (C Compiler, DIET installation)
 b - make
 c - make install (computer with the services & the clients)
 d - make Services Solvers (computer with only services)
 c - make Clients (computer with only clients)

     2 Seds (DAGDA_TLSE_SeD & DIET_TLSE_SeD) are installed in the service
     directory
     2 Clients (DAGDA_TLSE_Client & DIET_TLSE_Client) are installed in the
     client directory
     2 pseudo-solvers (solver1 & solver2) are installed in the solver
     directory

2. Deployment of DIET SeDs (service directory)
   ===========================================

 a - in the config directory :
     omniORB4.cfg : modify the name of the computer
     MA_TLSE.cfg  : modify the name of the MA and the Dagda storage directory
                    to match the TLSE hierarchy
     TLSE_SeD.cfg : modify the name of the MA and the Dagda storage directory
                    to match the TLSE hierarchy
     deployment.txt :
       first line : the number of couples (solver x computer) = service
       for each couple
         1 line : nameOfTheSolver;nameOfTheBinary;NameOfTheComputer

       in the given file, 3 solvers are deployed on the computer pinguoin,
                          2 solvers are deployed on the computer manchot

 b - in the bin directory : 5 scripts & 2 SeDs (the 2 compiled in step 1)
    TLSE_Restart: redeploys the DIET hierarchy 
                  (launches successively TLSE_CleanAll & TLSE_Run)
    TLSE_CleanAll: stops the DIET hierarchy and erases working files on the MA computer
    TLSE_Run: deploys the DIET hierarchy on the MA computer
    TLSE_MA: deploys MA
    TLSE_AddSeD: deploys Seds with the services defined in the
                 deployment.txt file according to the computer

    You have to adapt these files if you just want to launch the SeDs on a
    computer (TLSE_AddSeD is ok if you don't clean the working directories)

3. Running the Clients (client directory)
   ======================================

We suppose that we have deployed the following DIET/DAGDA hierarchy:

MA on pinguoin
DAGDA_TLSE_SeD on pinguoin and manchot
DIET_TLSE_SeD on pinguoin and manchot

We are on pinguoin
The 2 clients (DAGDA_TLSE_Client & DIET_TLSE_Client) use the input file 
(for instance in.txt)

In this file, we find some inputs of the problem we want to solve :
 - the solver name
 - the solver binary
 - the matrix name
 - the matrix file
 - the matrix address on the gridtlse site (gridtlse.org)
 - the computer name

3.1 DAGDA_TLSE_Client
    -----------------

The DAGDA_TLSE_Client's purpose is to register the matrix in DAGDA and to
place it on the computer where some solves will be perform later. 

We have to develop and use this client and the associated SeD,
because in GRID-TLSE we launch the solve clients in parallel:
if the matrix is not registered then each solve client will register it
and we will have multiple dagda instances of the same matrix.

DAGDA_TLSE_Client is called with 2 parameters:

DAGDA_TLSE_Client <client config file> <input file>

If the computer name is ANY, only the registration phase is performed (no call
to the DAGDA_TLSE_SeD).

###############################################  EXAMPLE 1  #############################################################
  we want to place the place the matrix on pinguoin

  in the client directory
./bin/DAGDA_TLSE_Client ./config/client.cfg ./input/in.txt

     result : you can check the two Dagda storage directories (MA & SeD) to
     verify that there is in each one instance of the matrix

###############################################  EXAMPLE 2  #############################################################
  if we just want to register the matrix

  in the client directory
./bin/DAGDA_TLSE_Client ./config/client.cfg ./input/in_ANY.txt

     result : if this call is the first (the matrix is not yet registered),
     there is only one instance of the matrix in the MA storage directory

3.2 DIET_TLSE_Client
    ----------------

The purpose of this client is to solve the problem described in the input file:

for example
# in.txt #
SolverName=Solver3
SolverBinary=solver3.sh
MatriceName=gre_343
MatriceFile=gre_343.rua.HB.gz
MatriceAdress=http://gridtlse.enseeiht.fr/websolve/DownloadMatrix?id=401
ComputerName=pinguoin

The solver is solver3, the matrix is gre_343 and the computer is pinguoin.
The computer could be ANY if you let DIET choose the computer (file in_ANY.txt).

Some other matrix can be used: 
 - you can go on the GRID-TLSE site (gridtlse.org),
 - browse public matrices
 - select one and copy the link "Download the matrix file"
You can easily construct input files.

DIET_TLSE_Client is called with 4 parameters

DIET_TLSE_Client <client config file> <input file> <experience number> <DAGDA>

experience number parameter is useful to design the different runs

DAGDA parameter could have 2 values:
 ON if we want DAGDA to perform the input matrix management
 OFF if we let the service download the matrix

#################################################  RUN 1  ###############################################################

We want to perform the solve described in in.txt (Solver3 x gre_343 x pinguoin) 
with DAGDA management for the input matrix.

 ./bin/DIET_TLSE_Client ./config/client.cfg ./input/in.txt 22 ON

 CLIENT output
-------------------------------------------------------------------------------------------------------------------------
 MA NAME PARSING = MA_TLSE_pinguoin
## Launch Dagda data manager DAGDA-client-pinguoin-27124
** Client parameters **
input_file : /home/dude/TLSE/client/input/in.txt
experience number : 22
Dagda : ON
work directory /home/dude/TLSE/client/work/workspace_27124 
name = gre_343.rua.HB
                   alias : gre_343.rua.HB, DAGDA://id-018cef41-b662-4480-86fe-1e16f5e5a75d-DAGDA-client-pinguoin-26833, 0
Matrix found : ID Dagda = DAGDA://id-018cef41-b662-4480-86fe-1e16f5e5a75d-DAGDA-client-pinguoin-26833
)solver name : Solver3
CLIENT > serviceName...Solver3_pinguoin
CLIENT > input_file...in.txt
CLIENT > exp_n...22
CLIENT > Calling DIET...
The Master Agent found the following server(s):
    pinguoin:0
Calling the ref Corba of the SeD
CLIENT > Back from diet call with 0...
CLIENT > output file /tmp/out-aa346a71-9a4b-45a5-8555-c6d07441f306.txt - 22532
-------------------------------------------------------------------------------------------------------------------------

    1 - Check that a workspace for the client is created
        (/home/dude/TLSE/client/work/workspace_27124)
    2 - There is only the input file in.txt in this directory
    3 - Check that a workspace for the solver is created (name with the experience number 22)
    4 - Inside, there is the input file and a link to the DAGDA instance of the matrix on the SeD
    5 - the output file /tmp/out-aa346a71-9a4b-45a5-8555-c6d07441f306.txt
        contains the concatenation of the matrix and the input file (Solver3)

#################################################  RUN 2  ###############################################################

We want to perform the solve described in in.txt (Solver3 x gre_343 x pinguoin) 
without DAGDA management for the input matrix.

 ./bin/DIET_TLSE_Client ./config/client.cfg ./input/in.txt 23 OFF

 CLIENT output
-------------------------------------------------------------------------------------------------------------------------
MA NAME PARSING = MA_TLSE_pinguoin
## Launch Dagda data manager DAGDA-client-pinguoin-27327
** Client parameters **
input_file : /home/dude/TLSE/client/input/in.txt
experience number : 23
Dagda : OFF
work directory /home/dude/TLSE/client/work/workspace_27327 
solver name : Solver3
CLIENT > serviceName...Solver3_pinguoin
CLIENT > input_file...in.txt
CLIENT > exp_n...23
CLIENT > Calling DIET...
The Master Agent found the following server(s):
    pinguoin:0
Calling the ref Corba of the SeD
CLIENT > Back from diet call with 0...
CLIENT > output file /tmp/out-70e69c44-9baf-45d5-8d60-4a125e2c3274.txt - 22532
-------------------------------------------------------------------------------------------------------------------------

    1 - Check that a workspace for the client is created
        (/home/dude/TLSE/client/work/workspace_27327)
    2 - There is only the input file in.txt in this directory
    3 - Check that a workspace for the solver is created (name with the experience number 23)
    4 - Inside, there is the input file and the matrix file
    5 - the output file /tmp/out-70e69c44-9baf-45d5-8d60-4a125e2c3274.txt
        contains the concatenation of the matrix and the input file (Solver3)

#################################################  RUN 3  ###############################################################

We want to perform the solve described in in_ANY.txt (Solver3 x gre_343 x no specific computer) 
with DAGDA management for the input matrix.

 ./bin/DIET_TLSE_Client ./config/client.cfg ./input/in_ANY.txt 24 ON

 CLIENT output when manchot is chosen by DIET
-------------------------------------------------------------------------------------------------------------------------
MA NAME PARSING = MA_TLSE_pinguoin
## Launch Dagda data manager DAGDA-client-pinguoin-27909
** Client parameters **
input_file : /home/dude/TLSE/client/input/in_ANY.txt
experience number : 24
Dagda : ON
work directory /home/dude/TLSE/client/work/workspace_27909 
name = gre_343.rua.HB
                   alias : gre_343.rua.HB, DAGDA://id-7b790087-dbfe-4a21-b8d3-d9fe9f614754-DAGDA-client-pinguoin-27773, 0
Matrix found : ID Dagda = DAGDA://id-7b790087-dbfe-4a21-b8d3-d9fe9f614754-DAGDA-client-pinguoin-27773
)solver name : Solver3
CLIENT > serviceName...Solver3
CLIENT > input_file...in.txt
CLIENT > exp_n...24
CLIENT > Calling DIET...
The Master Agent found the following server(s):
    manchot:0
    pinguoin:0
Calling the ref Corba of the SeD
CLIENT > Back from diet call with 0...
CLIENT > output file /tmp/out.3390.txt - 22529
-------------------------------------------------------------------------------------------------------------------------

    1 - Check that a workspace for the client is created
        (/home/dude/TLSE/client/work/workspace_27909)
    2 - There is only the input file in.txt in this directory
    3 - Check that a workspace for the solver is created on manchot (name with the experience number 25)
    4 - Inside, there is the input file and a link to the DAGDA instance of the matrix on the SeD
    5 - the output file /tmp/out.3390.txt on the computer of the CLIENT
        contains the concatenation of the matrix and the input file (Solver3)

#################################################  RUN 4  ###############################################################

We want to perform the solve described in in_ANY.txt (Solver3 x gre_343 x no specific computer) 
without DAGDA management for the input matrix.

 ./bin/DIET_TLSE_Client ./config/client.cfg ./input/in_ANY.txt 25 OFF

 CLIENT output when manchot is chosen by DIET
-------------------------------------------------------------------------------------------------------------------------
A NAME PARSING = MA_TLSE_pinguoin
## Launch Dagda data manager DAGDA-client-pinguoin-27988
** Client parameters **
input_file : /home/dude/TLSE/client/input/in_ANY.txt
experience number : 25
Dagda : OFF
work directory /home/dude/TLSE/client/work/workspace_27988 
solver name : Solver3
CLIENT > serviceName...Solver3
CLIENT > input_file...in.txt
CLIENT > exp_n...25
CLIENT > Calling DIET...
The Master Agent found the following server(s):
    manchot:0
    pinguoin:0
Calling the ref Corba of the SeD
CLIENT > Back from diet call with 0...
-------------------------------------------------------------------------------------------------------------------------

    1 - Check that a workspace for the client is created
        (/home/dude/TLSE/client/work/workspace_27988)
    2 - There is only the input file in.txt in this directory
    3 - Check that a workspace for the solver is created on manchot (name with the experience number 25)
    4 - Inside, there is the input file and the matrix file
    5 - the output file /tmp/out.3390.txt on the computer of the CLIENT
        contains the concatenation of the matrix and the input file (Solver3)

#########################################################################################################################
