------------------------------------------------------------------------
INPUT FILE DESCRIPTION

Program: neb.x / NEB / Quantum Espresso
------------------------------------------------------------------------


Input data format: { } = optional, [ ] = it depends, | = or

All quantities whose dimensions are not explicitly specified are in
RYDBERG ATOMIC UNITS

BEWARE: TABS, DOS <CR><LF> CHARACTERS ARE POTENTIAL SOURCES OF TROUBLE

General input file structure:
===============================================================================

neb.x DOES NOT READ FROM STANDARD INPUT
There are two ways for running a calculation with neb.x:
1) specifying a file to parse with the ./neb.x -inp or
 neb.x -input command line option.
2) or specifying the number of copies of PWscf input ./neb.x -input\_images.

For case 1) a file containing KEYWORDS has to be written (see below).
These KEYWORDS tells the parser which part of the file regards neb specifics
and which part regards the energy/force engine (at the moment only PW).
After the parsing different files are generated: neb.dat, with
neb specific variables and a set of pw_*.in PWscf input files like
one for each input position. All options for a single SCF calculation apply.

The general structure of the file to be parsed is:

BEGIN
BEGIN_PATH_INPUT
... neb specific namelists and cards
END_PATH_INPUT
BEGIN_ENGINE_INPUT
...pw specific namelists and cards
BEGIN_POSITIONS
FIRST_IMAGE
...pw ATOMIC_POSITIONS card
INTERMEDIATE_IMAGE
...pw ATOMIC_POSITIONS card
LAST_IMAGE
...pw ATOMIC_POSITIONS card
END_POSITIONS
... other pw specific cards
END_ENGINE_INPUT
END

For case 2) neb.dat and all pw_1.in, pw_2.in ... should be already present.

Structure of the input data (file neb.dat) :
===============================================================================

&PATH
  ...
/

[ CLIMBING_IMAGES
   list of images, separated by a comma ]



========================================================================
NAMELIST: &PATH

   +--------------------------------------------------------------------
   Variable:       string_method
   
   Type:           CHARACTER
   Default:        'neb'
   Description:    a string describing the task to be performed:
                      'neb',
                      'smd'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       restart_mode
   
   Type:           CHARACTER
   Default:        'from_scratch'
   Description:    'from_scratch'  : from scratch
                   
                   'restart'       : from previous interrupted run
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nstep_path
   
   Type:           INTEGER
   Description:    number of ionic + electronic steps
   Default:        1
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       num_of_images
   
   Type:           INTEGER
   Default:        0
   Description:    Number of points used to discretize the path
                   (it must be larger than 3).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       opt_scheme
   
   Type:           CHARACTER
   Default:        'quick-min'
   Description:    Specify the type of optimization scheme:
                   
                   'sd'         : steepest descent
                   
                   'broyden'    : quasi-Newton Broyden's second method (suggested)
                   
                   'broyden2'   : another variant of the quasi-Newton Broyden's
                                  second method to be tested and compared with the
                                  previous one.
                   
                   'quick-min'  : an optimisation algorithm based on the
                                  projected velocity Verlet scheme
                   
                   'langevin'   : finite temperature langevin dynamics of the
                                  string (smd only). It is used to compute the
                                  average path and the free-energy profile.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       CI_scheme
   
   Type:           CHARACTER
   Default:        'no-CI'
   Description:    Specify the type of Climbing Image scheme:
                   
                   'no-CI'      : climbing image is not used
                   
                   'auto'       : original CI scheme. The image highest in energy
                                  does not feel the effect of springs and is
                                  allowed to climb along the path
                   
                   'manual'     : images that have to climb are manually selected.
                                  See also CLIMBING_IMAGES card
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       first_last_opt
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    Also the first and the last configurations are optimized
                   "on the fly" (these images do not feel the effect of the springs).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       temp_req
   
   Type:           REAL
   Default:        0.D0 Kelvin
   Description:    Temperature used for the langevin dynamics of the string.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ds
   
   Type:           REAL
   Default:        1.D0
   Description:    Optimisation step length ( Hartree atomic units ).
                   If opt_scheme="broyden", ds is used as a guess for the
                   diagonal part of the Jacobian matrix.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variables:      k_max, k_min
   
   Type:           REAL
   Default:        0.1D0 Hartree atomic units
   Description:    Set them to use a Variable Elastic Constants scheme
                   elastic constants are in the range [ k_min, k_max ]
                   this is useful to rise the resolution around the saddle point.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       path_thr
   
   Type:           REAL
   Default:        0.05D0 eV / Angstrom
   Description:    The simulation stops when the error ( the norm of the force
                   orthogonal to the path in eV/A ) is less than path_thr.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       use_masses
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If. TRUE. the optimisation of the path is performed using
                   mass-weighted coordinates. Useful together with quick-min
                   optimization scheme, if some bonds are much stiffer than
                   others. By assigning a larger (fictitious) mass to atoms
                   with stiff bonds, one may use a longer time step "ds"
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       use_freezing
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If. TRUE. the images are optimised according to their error:
                   only those images with an error larger than half of the largest
                   are optimised. The other images are kept frozen.
   +--------------------------------------------------------------------
   
===END OF NAMELIST======================================================


========================================================================
CARD: CLIMBING_IMAGES 

   OPTIONAL CARD, NEEDED ONLY IF CI_SCHEME = 'MANUAL', IGNORED OTHERWISE !
   
   /////////////////////////////////////////
   // Syntax:                             //
   /////////////////////////////////////////
   
      CLIMBING_IMAGES 
         index1, index2, ... indexN
   
   /////////////////////////////////////////
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Variables:      index1, index2, ... indexN
      
      Type:           INTEGER
      Description:    index1, index2, ..., indexN are indices of the images to which the
                      Climbing-Image procedure apply. If more than one image is specified
                      they must be separated by a comma.
      +--------------------------------------------------------------------
      
      
===END OF CARD==========================================================