--------------------------------------------------------------------------------

Copyrigtht 2014 Georgios Karagiannis

This file is part of PISAA_BNLDD.

PISAA_BNLDD is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation version 2 of the License.

PISAA_BNLDD is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with PISAA_BNLDD.  If not, see <http://www.gnu.org/licenses/>.

--------------------------------------------------------------------------------


DESCRIPTION :
-------------

A C code implementation of PISAA for the Bayesian network learning application with discrete data. 

PISAA is a stochastic optimisation algorithm that aims at overcoming the local trapping issue.

The Single Proton Emission Computed Tomography data-set is included.

Karagiannis, G., Konomi, B., Lin, G., & Liang F. (2015). Parallel and Interacting Stochastic Approximation Annealing algorithms for global optimisation, arXiv:1508.04876 [stat.CO]

CONTACT DETAILS :
-----------------

Postdoctoral research associate
Department of Mathematics, Purdue University
150 N. University Street
West Lafayette, IN 47907-2067, USA

Telephone: +1 (765) 496-1007

Email: gkaragia@purdue.edu

Contact email: georgios.stats@gmail.com

REQUIREMENTS :
--------------

C compiler (ANSI C, C99, or later)

This code is tasted successfully with GCC, SUN, INTEL C compilers

FILES :
-------

makefile                    : Makefile

pisaa.c                     : The main function

Crossover_operations.c      : Crossover operations
Crossover_operations.h      : Header file

Mutation_operations.c       : Mutation operations
Mutation_operations.h       : Header file

Self_adjastment_prosedure.c : Functions related to the self adjusting mechanism
Self_adjastment_prosedure.h : Header file

cost_BNDV.c                 : The cost function
cost_BNDV.h                 : Header file

uniformrng.c                : Uniform random number generator
permutrng.c                 : Random permutaion generator
RNG.h                       : Header file

nrutil.c                    : Functions to treat array allocations
nrutil.h                    : Header file

SPECT.dat                   : The Single Proton Emission Computed Tomography 
                              data-set

output_files                : Folder for the output of the program 

exe                         : Binary file  

      input flags :
      
         -ID        Reference number
         -Data      file with the data; 
         -Niter     number of iterations
         -Npop      population size
         -Nsam      size of sample obtained
         -Gwarm     burn in parameter of gain function
         -Ghigh     high value of gain function
         -Gpow      power of gain function
         -Hlow      low limit of grid
         -Hhigh     high limit of grid
         -Hsize     size of grid
         -Hzeta     power of desired probability
         -Hconst    theta normalisation constant
         -Twarm     burn in parameter of temperature sequence
         -Tlow      low value of temperature sequence
         -Thigh     high value of temperature sequence
         -Tpow      power of temperature sequence
        
      output files :
      
        ./output_files/hist-n=%d-r=%d               The approximated values of 
                                                        thetas, and normalised 
                                                        thetas 
        ./output_files/fz_best_trace-n=%d-r=%d      Best value discovered, the 
                                                        whole chain
        ./output_files/fz_best-n=%d-r=%d            Best value discovered, 
                                                        originally

      examples :
      
        make build CC=gcc CFLAGS=-O2 LDFLAGS=-lm
      
        ./exe -ID 1 -Data ./SPECT.dat -Niter 1000000 -Npop 5 -Nsam 1000 

COMMENTS :
----------

- The output gives `mh0 rate=-nan'. This is reasonable. It is referred to the standard Simulated Annealing algorithm which is not used.
 
FUTURE UPDATES :
----------------

- Add a flag that allows one to externally choose the mutation and crossover operations used as well as set the operation rates.

- Add a flag that allows one to choose to adaptively adjust the mutation and crossover operation proposals.

- Make the code use openMP and openMPI.

- Remove the code related to mh0 option.