I. SOFTWARE COMPONENTS

You will find the following software packages:

- torc_lite: a tasking library that allows us to write platform-independent code
- pndl: parallel numerical differentiation library, built on top of torc_lite
- engines: the UQ framework built on top of torc_lite. 


II. PREREQUISITES
- An MPI implementation must be installed on your system (preferably with full thread safety)
- GSL (http://www.gnu.org/software/gsl/) is required by some engines and must be installed on your system


III. INSTALLATION STEPS

1) First we start with torc_lite. We assume that the MPI compiler is named mpicc.
	cd torc_lite
	./configure CC=mpicc --prefix=$HOME/usr/torc
	make; make install
	export PATH=$HOME/usr/torc/bin:$PATH

   If configure reports missing files, you will need to execute the autoreconf command (autoreconf) before executing ./configure 

   In $HOME/usr/torc/bin there are two files (torc_cflags, torc_libs) that facilitate the development of torc-based programs.
   That's why we have added this directory to the PATH environment variable using the export (bash) command. 
 
   After finishing this step, you must be able to run successfully at least one of the demo examples, available in torc/examples

2) We then proceed with the compilation of the various engines (algorithms) of our Uncertainty Quantification and Optimization framework.
   For example, to build the code that implements the TMCMC algorithm:

	cd inference/TMCMC
	make 

   If there are compilation issues then some directories in Makefile might need to be revised.
   For example, the exact location of the GSL library must be specificed.
   Moreover on some platforms, the MPI compiler can be named differently (e.g. CC=cc on Piz Daint).

   The following compilation options are supported:
	- make use_omp=1		# builds the OpenMP version
	- make use_torc=1		# builds the TORC-based version 
	- make use_omp=0 use_torc=0	# builds the serial version
	- make				# default option is use_omp=0


IV. TESTING

1) inference/TMCMC

   The TMCMC sampling algorithm

a) build engine_tmcmc

	cd inference/TMCMC
	make

b) Run the engine
	./engine_tmcmc

   By default, this runs TMCMC for the rosenbrock function in 2D, as defined in fitfun.c 
   This is expected to run and produce some output files (curgen_db_000.txt, curgen_db_001.txt, ...)

   The output files can be visualized with the display_gen tool, available in the display directory, using the following command:
	./display_gen curgen_db 5 2
	5: number of the last generation (curgen_db_000.txt to curgen_db_005.txt will be displayed)
	2: problem dimension

    The runtime options for this engine can be set in the configuration file tmcmc.par

2) singleopt/CMAES

   The CMAES stochastic optimization algorithm

a) Build the engine_cmaes

	cd singleopt/CMAES
	make

b) Run the engine
	./engine_cmaes

   Optimization of the rosenbrock function in 2D.
   More information about the generated output files can be found in the documentation of CMAES.

3) rare/subset

   Subset simulation 

a) Build the two engines

	cd rare/subset
	make

b) Run engine_ss1
	./engine_ss1

   Subset simulation for predefined levels
   This is expected to run and produce some output files (samples_000.txt etc)

   The output files can be displayed with the display_gen tool, using the following command:
	./display_gen samples 8 2
	8: number of the last generation (samples_000.txt to samples_008.txt will be displayed)
	2: problem dimension

   The runtime options for this engine can be set in the configuration file subset.par

c) Run engine_ss2

	./engine_ss2 

   Same as before but for subset simulation with adaptive levels


4) Numerical differentiation

a) Build the parallel numerical differentiation library (PNDL).

	cd derivatives/pndl
	./configure CC=mpicc F90=mpif90 
	make

   A README file with more detailed instructions is available along with the source code of PNDL. 

b) Build the tools 

	cd derivatives/tools
	make

c) Run the tools

	./fd_grad
	./fd_deriv
	./sa_deriv

   fd_grad: Calculation of the most suitable differentiation step per dimension using gradients and Romberg extrapolation   
   fd_deriv: Calculation of the gradient vector and Hessian matrix using PNDL 
   sa_deriv: Stochastic approximation of the Hessian matrix (experimental code)

   Configuration file for all tools: grad.par

5) inference/abc-subsim

   ABC-SUBSIM

   Please check the README-ABC.txt file in the corresponding folder


V) VISUALIZATION

   The display_gen tool, available in the display directority,  can visualize 2D slices of multidimensional data using gnuplot. 

   To build it:
	cd display
	make

   The syntax can invoked as follows:
	./display_gen <datafile> <last gen> <dimension> [var1] [var2]

    - The full name of the file is in the form: <datafile>_<gen>.txt, where gen = 000, 001, ..., <last gen>
    - <dimension> is the number of parameters. This means that the datafile has <dimension>+1 columns, the last containing the result of the function evaluation
    - [var1] and [var2] are optional arguments that specify the indices of the two parameters that will be displayed
	
    Example:
	./display_gen ../inference/TMCMC/curgen_db 4 2 1 2


VI) COUPLING WITH EXTERNAL SOFTWARE

   The coupling/ folder includes examples that demonstrate how external software can be called within a fitness function (fitfun)
   and coupled with any of the engines and tools available in the Pi4U framework.
   External software can include any kind of sequential or parallel code (OpenMP, MPI), 
   and be implemented in any possible programming language and environment (C/C++, Fortran, Python, Matlab). 
 	
Currently the following examples are included:

a) coupling/rosenbrock:
	A simple example; the Rosenbrock function now runs within the external sequential software.
	Passing of parameters is performed through the automatically created params.dat file


VII) NOTES

Do not hesitate to ask for help and report any problems at:
- chatzidp AT ethz.ch
- garampat AT ethz.ch