quantum-espresso/NEB/Doc/INPUT_NEB.def

# store a short description of ATOMIC_POSITIONS card, because it is used below three times

set card_ATOMIC_POSITIONS {
    card ATOMIC_POSITIONS {
        message {
            For the description of ATOMIC_POSITIONS card see file: @link INPUT_PW.html or INPUT_PW.txt
        }                           
        flag atompos_unit -use optional {
            enum { alat | bohr | angstrom | crystal | crystal_sg }
        }               
    }
}

set card_TOTAL_CHARGE {
    card TOTAL_CHARGE {
        label {
            Optional card, needed only if @ref lfcp == .TRUE.
        }
        syntax {
            list tot_charge_list -type REAL {
                format { tot_charge }
                info {
                    tot_charge is the total charge of the system.
                }
            }
        }
    }
}

# standard *.def description follows

input_description -distribution {Quantum ESPRESSO} -package NEB -program neb.x {

    toc {}

    intro {
        @b {Input data format:} { } = optional, [ ] = it depends, | = or
        
        All quantities whose dimensions are not explicitly specified are in
        RYDBERG ATOMIC UNITS

        @b BEWARE: TABS, DOS <CR><LF> CHARACTERS ARE POTENTIAL SOURCES OF TROUBLE 
        
        @b {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 @b {./neb.x -inp} or @b {./neb.x -input}
            command line option.
    
        (2) or specifying the number of copies of PWscf inputs with the @b {./neb.x -input_images}

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

        The general structure of the file to be parsed is:
	==================================================

        @b BEGIN
          @b BEGIN_PATH_INPUT
            ... neb specific namelists and cards
          @b END_PATH_INPUT

          @b BEGIN_ENGINE_INPUT
            ...pw specific namelists and cards
            @b BEGIN_POSITIONS
              @b FIRST_IMAGE
              ...pw ATOMIC_POSITIONS card
              ...pw TOTAL_CHARGE card (only for FCP)
              @b INTERMEDIATE_IMAGE
              ...pw ATOMIC_POSITIONS card
              ...pw TOTAL_CHARGE card (only for FCP)
              @b LAST_IMAGE
              ...pw ATOMIC_POSITIONS card
              ...pw TOTAL_CHARGE card (only for FCP)
            @b END_POSITIONS
            ... other pw specific cards
          @b END_ENGINE_INPUT
        @b END

	
        @b {For case (2)} neb.dat and all pw_1.in, pw_2.in ... should be already present. 

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

        @b &PATH
          ...
        @b /

        [ @b CLIMBING_IMAGES
           list of images, separated by a comma ]
    }

    supercard BEGIN -endtag END {
        
        supercard BEGIN_PATH_INPUT -endtag END_PATH_INPUT {

            namelist PATH {

                var string_method -type CHARACTER {
                    default { 'neb' }
                    options {
			info {
			    A string describing the task to be performed. Options are:
			}
			opt -val 'neb' { nudget-elastic-band }
                        opt -val 'smd' { string-method-dynamics }
		    }
                }
                
                var restart_mode -type CHARACTER {
                    default { 'from_scratch' }
                    options {
			info {Options are:}
                        opt -val 'from_scratch' { from scratch }                       
                        opt -val 'restart'      { from previous interrupted run }			
                    }
                }
                
                var nstep_path -type INTEGER {
                    info {
                        number of ionic + electronic steps
                    }
                    default {
                        1 
                    }
                }
                
                var num_of_images -type INTEGER { 
                    default { 0 }
                    info {
                        Number of points used to discretize the path
                        (it must be larger than 3).
                    }
                }

                var opt_scheme -type CHARACTER { 
                    default { 'quick-min' }
		    options {
			info {
			    Specify the type of optimization scheme:
			}			
                        opt -val 'sd' {
			    steepest descent
			}
                        opt -val 'broyden' {
			    quasi-Newton Broyden's second method (suggested)
			}
                        opt -val 'broyden2' {
			    another variant of the quasi-Newton Broyden's 
			    second method to be tested and compared with the
			    previous one.
			}
                        opt -val 'quick-min' {
			    an optimisation algorithm based on the
			    projected velocity Verlet scheme
			}
                        opt -val 'langevin' {
			    finite temperature langevin dynamics of the
			    string (smd only). It is used to compute the
			    average path and the free-energy profile.
			}
                    }
                }

                var CI_scheme -type CHARACTER {
                    default { 'no-CI' }
		    options {
			info {
			    Specify the type of Climbing Image scheme:
			}
                        opt -val 'no-CI' {
			    climbing image is not used
			}
                        opt -val 'auto' {
			    original CI scheme. The image highest in energy
			    does not feel the effect of springs and is
			    allowed to climb along the path
			}
                        opt -val 'manual' {
			    images that have to climb are manually selected.
			    See also @ref CLIMBING_IMAGES card
			}
                    }
                }

                var first_last_opt -type LOGICAL { 
                    default { .FALSE. }
                    info {
                        Also the first and the last configurations are optimized
                        "on the fly" (these images do not feel the effect of the springs).
                    }
                }

                var minimum_image -type LOGICAL { 
                    default { .FALSE. }
                    info {
                        Assume a "minimum image criterion" to build the path. If an atom
                        moves by more than half the length of a crystal axis between one
                        image and the next in the input (before interpolation),
                        an appropriate periodic replica of that atom is chosen.
                        Useful to avoid jumps in the initial reaction path.
                    }
                }

                var temp_req -type REAL { 
                    default { 0.D0 Kelvin }
                    info {
                        Temperature used for the langevin dynamics of the string.
                    }
                }

                var ds -type REAL { 
                    default { 1.D0 }
                    info {
                        Optimisation step length ( Hartree atomic units ).
                        If @ref opt_scheme=="broyden", ds is used as a guess for the
                        diagonal part of the Jacobian matrix.
                    }
                }

                vargroup -type REAL {
                    var k_max
                    var k_min
                    default { 0.1D0 Hartree atomic units }
                    info {
                        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.
                    }
                }

                var path_thr -type REAL { 
                    default { 0.05D0 eV / Angstrom }
                    info {
                        The simulation stops when the error ( the norm of the force
                        orthogonal to the path in eV/A ) is less than path_thr.
                    }
                }

                var use_masses -type LOGICAL { 
                    default { .FALSE. }
                    info {
                        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"
                    }
                }

                var use_freezing -type LOGICAL { 
                    default { .FALSE. }
                    info {
                        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.
                    }
                }

                var lfcp -type LOGICAL {
                    see { fcp_mu }
                    default { .FALSE. }
                    info {
                        If .TRUE. perform a constant bias potential (constant-mu) calculation with
                        - ESM method (assume_isolated = 'esm' and esm_bc = 'bc2' or 'bc3' must be
                                      set in SYSTEM namelist) or
                        - ESM-RISM method (assume_isolated = 'esm' and esm_bc = 'bc1' must be set
                                           set in SYSTEM namelist, and trism = .TRUE. must be set
                                           set in CONTROL namelist).

                        @ref fcp_mu gives the target Fermi energy.
                        See the header of PW/src/fcp_module.f90 for documentation
                    }
                }

                var fcp_mu -type REAL {
                    see { lfcp }
                    default { 0.d0 }
                    info {
                        If @ref lfcp == .TRUE., gives the target Fermi energy [eV].
                        One can specify the total charge of the system for the first
                        and last image by giving @ref TOTAL_CHARGE cards
                        so that the Fermi energy of these systems will be the target value,
                        otherwise @ref first_last_opt should be .TRUE.
                        For the initial charge of intermediate images, the @ref TOTAL_CHARGE
                        is linearly interpolated between the initial and the final ones 
                        unless the @ref TOTAL_CHARGE is given in the input file.
                    }
                }

                var fcp_thr -type REAL {
                    see { lfcp }
                    default { 0.01D0 V }
                    info {
                        The simulation stops when the error ( the maximum of the force
                        acting on the FCP in V ) is less than fcp_thr.
                    }
                }

                var fcp_scheme -type CHARACTER {
                    see { lfcp }
                    default { 'lm' }
                    options {
                        info {
                            Specify the type of optimization scheme for FCP:
                        }
                        opt -val 'lm' {
                            Line-Minimization method.
                        }
                        opt -val 'newton' {
                            Newton-Raphson method with diagonal hessian matrix.
                            Also, coupling with DIIS.
                        }
                        opt -val 'coupled' {
                            Coupled method with ionic positions.
                            This is available only if @ref opt_scheme == 'broyden',
                            or 'broyden2'.
                        }
                    }
                }
            }


            #
            # CLIMBING_IMAGES
            #

            card CLIMBING_IMAGES {
                label { 
                    Optional card, needed only if @ref CI_scheme == 'manual', ignored otherwise ! 
                }

                syntax {
                    list climbing_images_list -type INTEGER {
                        format { index1, index2, ... indexN }
                        info {          
                            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.
                        }
                    }
                }
            }
        }

        supercard BEGIN_ENGINE_INPUT -endtag END_ENGINE_INPUT {
            message {
                Here comes the pw.x specific namelists and cards (see file: @link INPUT_PW.html or INPUT_PW.txt)
                with the exception of @ref ATOMIC_POSITIONS cards, which are specified separately within the
		@ref BEGIN_POSITIONS/END_POSITIONS supercard as described below.

                So the input that follows here is of the following structure:
                
                   @b &CONTROL
                      ...
                   @b /
                   @b &SYSTEM
                     ...
                   @b /
                   @b &ELECTRONS
                     ...
                   @b /
                   ...
            }

            supercard BEGIN_POSITIONS -endtag END_POSITIONS {
                message {
                    NB:
                    Atomic positions for all the images are specified within the @ref BEGIN_POSITIONS / END_POSITIONS
                    supercard, where each instance of @ref ATOMIC_POSITIONS card is prefixed either by @ref FIRST_IMAGE, 
                    @ref INTERMEDIATE_IMAGE, or @ref LAST_IMAGE keywords.
                    IF @ref lfcp == .TRUE., total charges for all images have to be specified with @ref TOTAL_CHARGE cards.

                    Note that intermediate images are optional, i.e., there can be none or any number of
                    @ref INTERMEDIATE_IMAGE images.
		}
		supercard FIRST_IMAGE {
		    eval $card_ATOMIC_POSITIONS
                    eval $card_TOTAL_CHARGE
		}
		
		optional {
		    supercard INTERMEDIATE_IMAGE -remark {
			There can be any number (including zero) of INTERMEDIATE_IMAGE supercards.
		    } {
			eval $card_ATOMIC_POSITIONS
                        eval $card_TOTAL_CHARGE
		    }
		}
            
		supercard LAST_IMAGE {
		    eval $card_ATOMIC_POSITIONS
                    eval $card_TOTAL_CHARGE
		}
	    }

	    message {
		Here can follow other @b pw specific @b cards ...
	    }
        }
    }
}