         ************************************************************
	 * PARALLEL TESTS FOR ALCHEMICAL TRANSFORMATION WITH ORAC   *
         ************************************************************

These tests run in parallel. The main prerequisite is:

* MPI (Message Passing Interface) libraries and
  implementation/environment:
  MPICH    [http://www.mpich.org/] 
  -or-
  OPENMPI   [http://www.open-mpi.org/]

Other prerequisites depend on the MPI environment used. You may need
to define a list of hosts where processes shall run, a way of
accessing those hosts, such as ssh, and more.

------------------------------------------------------------------------
BEFORE RUNNING THE TESTS
------------------------------------------------------------------------

* Build a parallel version of the ORAC program, e.g. :

   cd <orac6-root-dir>
   ./configure -GNU -FFTW -OMP -MPI
   make   ! create a MPI executable in  GNU-FFTW-MPI dir    

* Adjust the variables in the first section of ./Makefile :

  O_BIN
  O_BIN_P

* Adjust the variables in the "init and defaults" section of
  ./run_parallel_tests.bash to your MPI environment:

  MPIRUN

* configure and start your MPI environment

------------------------------------------------------------------------
TO RUN THE TESTS
------------------------------------------------------------------------

Tests are preferably run through `make'.

* to run all the tests:

  `make parallel'
  
  this runs command `./run_parallel_tests.bash $ORAC_P $NP', which
  in turn will call the the ancillary program

    ./bennett 

$ORAC_P is the executable parallel version of ORAC (default is GNU-FFTW-OMP-MPI) 
       
$NP is the number of cores (default=8)


In this example parallel execution is done using the hybrid OpenMP/MPI
executable, assuming a total of NP=8 cores.  Each of the NMPI=4 annihilation/creation
trajectories (the MPI instances) is hence generated using 2 OMP
THREADS. 

The tests will create NMPI work directories PAR0000, PAR0001, ..., with
output files from each instance of the program, and a collection of
selected output lines in OUT_PARALLEL_TEST; this file is to be
compared to the reference file OUT_PARALLEL.

NOTE that even small differences of numerical origin will soon drive a
trajectory away from the reference path. Thus, the work distribution
may differ significantly from the reference data.


------------------------------------------------------------------------
SHORT DESCRIPTION OF THE TESTS
------------------------------------------------------------------------


- Please read the manual ( ${ORAC_DIR}/doc/orac-manual.pdf ) for a
  detailed description of the program and its input



In this example, 8 switch-ON and 8 switch-OFF trajectories are run in
parallel for N-Elte378 in liquid hexane starting from the equilibrium
of the thermodynamic states A B such that

state A:  1 ElteN-378 (gas) molecule  + 216 Hexane molecules  P=1Atm T=300 K 
state B:  (1 ElteN-378 + 216 Hexane molecule) solution        P=1Atm T=300 K 

A --> B   switch-on/forward process
B --> A   switch-off/reverse process
 
The switch-on/off nonequilibrium works generated by the alchemical
transformations are fed into the bennett program (see directory
../../tools) to calculate the free energy difference F_B- F_A


a.in:  Generates starting ghost solute configurations
b.in:  Generates starting full solute configurations

# N.B. Tests [ab].in do not actually run in parallel. They run
# one instance of the program in the MPI environment

a.in produces canonically distributed restart files configurations
       pure liquid and pure gas state in the RESTART_A dir.

b.in produces canonically distributed restart files configurations
       solution in the RESTART_B dir.

# Parallel alchemical trajectories are produced with NP=8

1_para.in (for parallel job only) produces work distribution (i.e. many
       trajectories in parallel) for the switching ON process of N-Elte378 in hexane

2_para.in(for parallel job only) produces work distribution (i.e. many
       trajectories in parallel) for the switching OFF process of N-Elte378 in hexane

# Finally, program ./bin/bennett calculates the Free energy change using the 
# bi-directional alchemical works produced above 

test_rest0.in : switching ON of Elte in Hexane up to 1000 fs on 8 processor
test_rest1.in : switching ON of Elte in Hexane from 1000 up to 2000 fs on 8 processor
