.. _installation:

============
Installation
============

The VTST•Tools has a fortran component which can be linked into the VASP code as well as a collection of scripts.

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

Code change in the VASP main.F file
===================================

In VTST v2.04 and later, a  modification is required in ``main.F`` for the solid-state NEB.

Find and replace:

.. code-block:: sh

      CALL CHAIN_FORCE(T_INFO%NIONS,DYN%POSION,TOTEN,TIFOR, &
           LATT_CUR%A,LATT_CUR%B,IO%IU6)

with

.. code-block:: sh

      CALL CHAIN_FORCE(T_INFO%NIONS,DYN%POSION,TOTEN,TIFOR, &
           TSIF,LATT_CUR%A,LATT_CUR%B,IO%IU6)

For vasp.6.2 and later, also find and replace:

.. code-block:: sh

      IF (LCHAIN) CALL chain_init( T_INFO, IO)

with

.. code-block:: sh

      CALL chain_init( T_INFO, IO)

For vasp.6.2.1 you will need vtstcode 4.1 (revision 182).  A version of the vtstcode that will work with vasp.6.1.x - vasp.6.2.0 has been saved in the vtstcode6.1 directory. 

The vtstcode6.3 directory contains a machine learning optimizer (``IOPT=8``) that has been recently added. Follow the instruction according to the version that is used.

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

Building the VTST code into VASP
================================

The code for the NEB, dimer, Lanczos, and dynamical matrix methods, as well as the steepest descent, force-based conjugate gradient, quick-min, lbfgs, bfgs, and fire optimizers are contained in a single package which interfaces to VASP through the ``chain.F`` file.

To install, download the files in vtsttools/vtstcode, choose a version, and copy the files in the directory into your vasp source directory. The file ``chain.F`` is replaced, so back up the old version. There are other files in the package: ``neb.F``, ``dynmat.F``, ``dimer.F``, ``lanczos.F``, ``sd.F``, ``cg.F``, ``qm.F``, ``lbfgs.F``, ``bfgs.F``, ``fire.F``, and ``opt.F`` in ``vtstcode5/`` and ``vtstcode6.1/`` directories. The ``vtstcode6.3/`` directory contains another file called ``ml_pyamff.F`` and directory named ``pyamff_fortran/``, which interface to a machine learning package `PyAMFF`_.

To build the code, the VASP ``.objects`` and ``makefile`` need to be changed. Find the variable ``SOURCE`` in the ``.objects`` file (a hidden file in ``src/``), which defines which objects will be built, and add the following objects before ``chain.o``:

**vtstcode5 and vtstcode6.1**

.. code-block:: sh

            bfgs.o dynmat.o instanton.o lbfgs.o sd.o cg.o dimer.o bbm.o \
            fire.o lanczos.o neb.o qm.o opt.o

**vtstcode6.3** 

.. code-block:: sh

            bfgs.o dynmat.o instanton.o lbfgs.o sd.o cg.o dimer.o bbm.o \
            fire.o lanczos.o neb.o qm.o \
            pyamff_fortran/*.o ml_pyamff.o \
            opt.o

The objects ``dynmat.o``, ``neb.o``, ``dimer.o``, ``lanczos.o``, and ``instanton.o`` must be in the ``SOURCE`` list before ``chain.o`` appears. The optimizer objects, ``sd.o``, ``cg.o``, ``qm.o``, ``lbfgs.o``, ``bfgs.o``, ``fire.o`` (vtstcode 5 and vtstcode 6.1), ``ml_pyamff.o`` and all the objects in the ``pyamff_fortran/`` directory (vtstcode 6.3) must appear before the optimizer driver ``opt.o``.

If you use vtstcode6.3, you need one more modification. Find the variable ``LIB`` in ``makefile`` that is inside ``src/``, and add the following directory after the last element of the list of library:

**vtstcode6.3**

.. code-block:: sh
        
            LIB= lib parser pyamff_fortran

If you compile in parallel, you need to add ``libs`` to your ``dependencies`` in ``makefile``:

.. code-block:: sh

            dependencies: sources libs 
  
Nothing else needs to be done. This code will not change the working of any other part of vasp. This code will only be run if ``IMAGES`` is set in the ``INCAR`` file, or if ``ICHAIN`` is set, to specify which method should be run.

- ``ICHAIN=0``: Nudged elastic band (default)
- ``ICHAIN=1``: Dynamical matrix
- ``ICHAIN=2``: Dimer
- ``ICHAIN=3``: Lanczos

.. _PyAMFF: https://gitlab.com/pyamff/pyamff