# Vreco_CPMD

## Installation Instructions

This is the development version of the code and needs to be configured as follows:

```bash
$ aclocal
$ autoheader
$ autoconf
$ automake --add-missing
$ ./configure
$ make
```

Manual for Vreco_CPMD.f90 code version 10.3 (Nisanth N. Nair 08/07/08)

## General Description

This program   is useful for  reconstructing the  free energy  surface  from a
metadynamics simulation using CPMD.  There  is no limitation  on the number of
collective variables (CV) the program can handle. For runs with 1 (2) CVs, the
2D (3D)   reconstructed  free energy surfaces,  can  be  viewed in  GNUPLOT or
OpenDX. For a 3 CV case, it is possible to print the 4D free energy surface in
a cube file format  (for e.g., then  using  VMD/OpenDX to visualize). See  the
example directory for examples to plot and visualize the data.

Important to note that, F(s), the free energy in collective variable space, is
printed, where

F(s) = -- SUM_t  V(t,s).

Here V is the biasing  potential added at time t  in the collective variable
space s.

## Compiling Vreco_CPMD.f90


Adjust the Makefile for your compiler, if needed, and type:

make

Note that this program is written  in free format  standard FORTRAN 95. It was
tested with  and without  optimization  with Intel Fortran  version 9.0,  9.1,
10.1, g95 v0.91, gfortran v4.1.2, PGI's pgf90 version 6.2-5 and 7.1-6, and IBM
XLF v9.1 showing reasonably good performance.

The code  is also parallelized using  OpenMP.  You  have to  set the  required
compiler flags for that to enable OpenMP directives. Some  examples are in the
Makefile.  Many OpenMP compilers will try to use all available cpus, which may
lead to suboptimal performance. This can be modified by setting the environment 
variable OMP_NUM_THREADS. e.g., to use two threads do:

```bash
env OMP_NUM_THREADS=2 ./Vreco_CPMD.x < vreco.inp > vreco.out
```

The output will indicate, whether you have an  OpenMP compiled version and how
many threads  will be used. Please  note that when  using PRINT DYNAMIC OpenMP 
performance is only good for large values of PRINT_FRQ.

## Using Vreco_CPMD.x


The program reads in the files 'colvar_mtd' and 'parvar_mtd' generated by CPMD
metadynamics runs to reconstruct the free energy surface. Gaussian centers and
scaling factors during the runs are taken from 'colvar_mtd' and Gaussian width
and  heights are taken  from 'parvar_mtd'.  Copy or  link those  files  to the
working directory (they will _not_ be overwritten) and run an input.

```bash
./Vreco_CPMD.x < vreco.inp  
```

or

```bash
./Vreco_CPMD.x < vreco.inp > vreco.out
```

Some keywords are required to  instruct the program on what  to do.  They  are
read  standard input file, best  through I/O redirection;  see below a list of
the individual input keywords and their function.

The  final  reconstructed potential  will be written  to  'V.final.out' and/or
'V.final.cube'; see  below for  details.  If PRINT  DYNAMIC  is present in the
input file (see below) 'V.dynamic.out' contain the potentials reconstructed at
given intervals of metadynamics steps.

---------------------------------------------------------------------------------
### Input keywords for Vreco_CPMD.f90
---------------------------------------------------------------------------------

IMPORTANT: Input file should begin with the keyword NCV and end with END.

Required keywords:

  NCV: 
         Number of CVs used in the simulations is read from the next line.
         This has to be the first keyword.

  GRIDS: 
         Grid on which the  reconstruction has to be  performed, is read from
         the following  NCV lines.  Minimum  value of  the grid, the  maximum
         value of the grid and the grid-width  are read for  each set of CVs,
         in the same order as in the CPMD input file.   Units of CVs are same
         as  in colvar_mtd output (note: even  if ANGSTROM keyword is present
         distances are in Bohr units in colvar_mtd file). Consult CPMD manual
         for details on units.
         
  HILLS { [SPHERE] [TUBE [RCUT]] }:
        Type of biasing potential used (same keywords as in CPMD input file)
        If SPHERE is present spherical Gaussians are used in the CPMD run. 
        If TUBE is present tube-type Gaussians are used.
        If RCUT is present together with TUBE , shifted Gaussians are used. 
        Gaussians are then trimmed after hill_width*RCUT_value. The RCUT_value 
        is read from the next line if RCUT is present.
        IMPORTANT! no other biasing potentials types are implemented in this version!

 END   
        This must be the last keyword and is _required_.

Optional keywords: the following keywords must appear before the "END" keyword.

  [ PRINT { [DYNAMIC] [WALKER] }]:
        If  DYNAMIC is  present the  reconstructed potential  is printed out
        during  every PRINT_FRQ  metadynamics  steps to  the 'V.dynamic.out'
        file. The   printing frequency, PRINT_FRQ,  is  read  from  the next
        line. Note: each column (after the grid value, if  OUT GRID is used)
        will be the potential  during  the metadynamics steps  in increasing
        order. Similarly,    printing  the walker   position  and  the total
        potential at each  walker positions can  be requested by the keyword
        WALKER.    the  corresponding  output  file   is  'walker.out'.  The
        frequency of printing PRINT_FRQ is read from the next line.  One can
        use PRINT DYNAMIC and  PRINT  WALKER  together, but also as separate
        keywords.

  [ OUT { [GRID] [NOGRID] } ]  (OUT GRID is the default)
        The reconstructed potential is  printed  out with the grid  position
        values (as first NCV columns) if OUT GRID is used.  If OUT NOGRID is
        present, the grid positions will not be printed.

  [ UNITS { [KJ] [KC] [AU] }]   (AU is default)
        Units  of energy used by the  program for printing the free energies
        or  potential.  KJ  stands for kJ/mol,   KC for kcal/mol  and AU for
        atomic units. IMPORTANT! This is only used  for (all) output of this
        program; CPMD units used in  the colvar_mtd and parvar_mtd files are
        properly taken care of by the program.


  [ METASTEP ] 
        Number of metadynamics steps to reconstruction is read from the next
        line. Default is to use all steps from colvar_mtd file.
        
  [ CUBE [FULL] [CVMDCK] [COLVAR] [ONLY] ]
        Print  the reconstructed potential to  a  Gaussian-style cube format
        file.   Only allowed for  cases having 3  CVs.  FULL is the default;
        the full   final  reconstructed free energy   surface  is written to
        'V.final.cube'.  If   CVMDCK is  also present, then   the collective
        coordinates along the trajectory present in the 'cvmdck_mtd' file is
        read   in,  and the    potential  along  this  path  is   written to
        'V.cvmdck.cube'   If COLVAR is also  present,  then  the free energy
        values along the collective   variable in the 'colvar_mtd'  file  is
        written to 'V.colvar.cube'.   If ONLY is present, 'V.final.out' will
        not be written together with the above cube files.

---------------------------------------------------------------------------------
### Output files
---------------------------------------------------------------------------------

V.final.out
        Reconstructed   free energy surface F(s). Units   of  free energy is
        according to the keyword UNITS (see above). IF OUT GRID is used, the
        format of printing will be as follows for a 2 CV case:
        
        grid_x0    grid_y0             F(x0,y0) 
        grid_x0    grid_y0+dy          F(x0,y0+dy) 
        .......
        grid_x0    grid_y0+(Ny-1)*dy   F(x0,y0+(Ny-1)*dy) 
              -blank line-
        grid_x0+dx grid_y0             F(x0+dx,y0)
        grid_x0+dx grid_y0+dy          F(x0+dx,y0+dy)
        .......
        
        If  OUT NOGRID is  used, then the  first two columns will be absent;
        everything else is the same.

V.dynamic.out
        Reconstructed  free energy surface F(s)  during metadynamics run. It
        is  very useful to  decide where  to stop  the  runs for getting the
        final free energy  surface, and to  observe the way  the free energy
        surface builds  up during  the  dynamics.  Units of free   energy is
        according to the keyword UNITS (see above). IF OUT GRID is used, the
        format of printing will be as follows for a 2 CV case:

        grid_x0    grid_y0           F(x0,y0,t)           F(x0,y0,t+n*dt)           F(x0,y0,t+2*n*dt)           ....
        grid_x0    grid_y0+dy        F(x0,y0+dy,t)        F(x0,y0+dy,t+n*dt)        F(x0,y0+dy,t+2*n*dt)        ....
        .......
        grid_x0    grid_y0+(Ny-1)*dy F(x0,y0+(Ny-1)*dy,t) F(x0,y0+(Ny-1)*dy,t+n*dt) F(x0,y0+(Ny-1)*dy,t+2*n*dt) ....
              -blank line-
        grid_x0+dx grid_y0           F(x0+dx,y0,t)        F(x0+dx,y0,t+n*dt)        F(x0+dx,y0,t+2*n*dt)        ....
        grid_x0+dx grid_y0+dy        F(x0+dx,y0+dy,t)     F(x0+dx,y0+dy,t+n*dt)     F(x0+dx,y0+dy,t+2*n*dt)     ....
        .......

V.final.cube
        Final reconstructed free energy surface in a Gaussian-style cube file.

V.colvar.cube
        Free energy values along the trajectory of collective variables (read 
        from colvar_mtd file) in a Gaussian-style  cube file
.
V.cvmdck.cube
        Free energy values along the trajectory of collective coordinates (not
        collective variables)  as in the cvmdck_mtd  file  from  CPMD,  in the
        Gaussian cube file format.

walker.out 
        position of the walker (Gaussian centers) and the total potential at
        this point (read in from 'enevar_mtd') will be written to 'walker.out',
        in the same format as that of 'V.final.out'.


# Manual for mtd_restart_extract.f90 code (Nisanth N. Nair 26/06/08)

This   code   reads a  'MTD_RESTART'  file   and  recreates the  corresponding
'colvar_mtd' and 'parvar_mtd' files, which are required for reconstructing the
free  energy surface.  Useful,  if the *_mtd files  got corrupted, or to check
the biasing hills used in CPMD for actual  calculations.  Output is written to
the files 'colvar_mtd.reco' and 'parvar_mtd.reco'.


To compile:

```bash
make
```

To use:

```bash
./mtd_restart_extract.x
```

Reads in 'MTD_RESTART' from the working directory and writes out
colvar_mtd.reco and parvar_mtd.reco

## Bugs/Comments/Suggestions
Please report bugs to nisanth.nair@theochem.rub.de


# Credits
autotools-skeleton (https://github.com/gizero/autotools-skeleton)