This directory contains a set of files that implements an evolutionary 
algorithm to optimize clusters formed by rigid-body molecules.
------------------------------------------------------------------------------------
LICENCE:
The EA code is released under the GNU General Public License.
By downloading the software you agree to abide by the GPL conditions.
The most important conditions are:
    * You may copy, modify and redistribute the EA code or modifications 
      freely.
    * Any such redistributions must be done under the terms of the GPL, 
      else the permission is withdrawn. 
------------------------------------------------------------------------------------
CITATION:
If you use the EA code in your work, please use the following citation:

J.L. Llanio-Trujillo, J.M.C. Marques and F.B. Pereira, J. Phys. Chem. A
2011, 115 (11), pp 2130–2138; doi: 10.1021/jp1117695
------------------------------------------------------------------------------------ 
SYSTEM-DEPENDENT FILES:
      fg_value.f --> implementation of the intermolecular potential and
                     derivatives (e.g., TIP4P potential for water).

INPUT FILES:
      parameters.txt --> defines all the relevant parameters for the EA;
                         also included in this file are the number of
                         molecules of the cluster and the range of the
                         searching parameters (encoding the position and
                         the orientation of each molecule).
      qrb.txt --> defines the Cartesian coordinates of the molecular sites;
                  for TIP4P water, one has 4 sites per rigid-body molecule.

OUTPUT FILES:
      best.txt --> where the energy and the solution vector of the putative
                   global minimum are written; the solution vector encodes 
                   n six-tuples (n is the number of molecules of the 
                   cluster); in each tuple, the first three variables 
                   define the Cartesian coordinates of a given molecule 
                   center of mass and the last three specify the 
                   corresponding Euler angles.

      stats.txt --> it stores the evolution of results for every single run. 
                    In each line it displays the current number of evaluations, 
                    the current generation, the average energy of all the 
                    solutions belonging to the population, and the energy of 
                    the best solution found so far. The information written
                    to stats.txt is replicated to the standard output. This 
                    replication can be disabled by setting constant 
                    CONSOLE_PRINTING to 0 (in file ga.h). 

      avg_stats.txt --> this file is created in the end of the optimization 
                        and it keeps a global overview of the detailed results 
                        stored at stats.txt. The first section, identified as 
                        "Last lines" shows the last line of results from every 
                        run. Section "Evolution average results" contains the 
                        evolution results averaged over all runs, namely the 
                        evolution of the mean average fitness of the population 
                        and the evolution of the mean best fitness.
        
LOG FILES:
The EA can generate two log files that report when local search generates solutions 
with variables settings outside pre-specified boundaries.

The file log.eval.txt stores the coordinates of all solutions with variable values 
outside the domain limits. For every solution in this condition, it displays the 
original variable values (before local optimization) and the values after local 
optimization.

If a variable gets outside its domain, the EA expands the boundaries to incorporate 
the new information. The file log_bounds.txt keep a detailed record of all domain 
limits updates.

The creation of the log files can be disabled by setting constants LOG_EVAL and/or 
LOG_BOUNDS to 0 (in file ga.h).

------------------------------------------------------------------------------------
AUXILIARY PROGRAM:
      transform.f90 --> fortran program that, among other things, transforms 
                        the solution vector from file best.txt to Cartesian 
                        coordinates (that are written in file Lab_cartesians.xyz); 
                        this uses a service program (service_water.f) containing 
                        the potential; besides best.txt, it uses parameters.txt
                        and qrb.txt as input files. (It is adapted for TIP4P
                        water clusters, but it can be easily modified for other
                        clusters.)
------------------------------------------------------------------------------------
COMPILATION:
There is a Makefile that can be used to compile the EA with the potential:
            ./make
The Makefile uses "ifort" to compile the fortran code and "icc" to compile
the C code. So, it must be modified for other compilers.
To compile the auxiliary program, it may be used the "ifort" compiler:
            ifort -o transform_water.exe transform.f90 service_water.f
------------------------------------------------------------------------------------
EMAIL FOR OTHER QUESTIONS AND FOR BUG REPORTING:
      Jorge Marques: qtmarque@ci.uc.pt
      Francisco Pereira: xico@eden.dei.uc.pt
------------------------------------------------------------------------------------
