quantum-espresso/TDDFPT/Doc/INPUT_Davidson.def

input_description -distribution {Quantum ESPRESSO} -package turboTDDFPT -program turbo_davidson.x {

    toc {}

    intro {
    	  Input data format: { } = optional, [ ] = it depends.

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

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

          Comment lines in namelists can be introduced by a "!", exactly as in 
          fortran code. Comments lines in ``cards'' can be introduced by 
          either a "!" or a "#" character in the first position of a line.

          @b {Structure of the input data:}
	  ===============================================================================

	  &LR_INPUT
	    ...
	  /

	  &LR_DAV
	    ...
	  /	    

    }

    namelist LR_INPUT {

	label { This namelist is always needed ! }

	var prefix -type CHARACTER { 
	    default { 'pwscf' }
	    info {
		Sets the prefix for generated and read files. The files 
		generated by the ground state pw.x run should have this 
		same prefix.
	    }
	}

	var outdir -type CHARACTER { 
	    default { './' }
	    info {
		The directory that contains the run critical files, which 
		include the files generated by ground state pw.x run.
	    }
	}

	var wfcdir -type CHARACTER { 
	    default { './' }
	    info {
		The directory that contains the run critical files, which 
		include the files generated by ground state pw.x run.
	    }
	}
        
        var max_seconds -type REAL {
            default { 1.D+7, or 150 days, i.e. no time limit }
            info {
                jobs stops after @ref max_seconds CPU time. Use this option 
                in conjunction with option @ref restart if you need to
                split a job too long to complete into shorter jobs that
                fit into your batch queues.
            }
        }
	
	var restart -type LOGICAL {
	    default {.false.}
	    info {
		When set to .true., turbo_davidson.x will attempt to restart 
		from a previous interrupted calculation if @ref max_seconds
                was specified. 
		Beware, if set to .false. turbo_davidson.x will OVERWRITE any
		previous runs.
	    }
	}

	var lr_verbosity -type INTEGER {
	    default {1}
	    info {
		This integer variable controls the amount of information 
		written to standard output.
	    }
	}

	var disk_io -type CHARACTER {
	    default { 'default' }
	    info {
    		Fine control of disk usage. Currently only 'reduced' is 
		supported where no restart files are written, apart from 
		the 'default' mode.
	    }
	}
    }
    namelist LR_DAV {
	var num_eign -type INTEGER {
	    default {1}
	    info {
		Number of eigenstates to be calculated.
		}
	}

        var num_init -type INTEGER {
            default {2}
            info {
                Number of trial vectors. Usually it is twice as large as
                the number of eigenstates to be calculated (see @ref num_eign).
                }
        }

        var if_random_init -type LOGICAL {
            default {.false.}
            info { 
                When set to .true. trial vectors are chosen randomly, otherwise
                they are guessed from the ground-state calculation. 
                If @ref p_nbnd_occ * @ref p_nbnd_virt < @ref num_init, this term 
                is forced to be .true. The usage of random trial vectors should 
                cause only a slower convergence, and do not affect the final results.
                }
        }

        var num_basis_max -type INTEGER {
            default {20}
            info {
                Maximum number of basis vectors allowed in the subspace. 
                When this number is reached, a discharging routine is called.                
                The memory requirement of the Davidson algorithm is mainly 
                determined by this variable (an estimation of the memory 
                is reported at the beginning of the run).
                }
        }

        var residue_conv_thr -type REAL {
            default {1.0E-4}
            info {
                Threshold for the convergence. When the square of the 
                residue is smaller than this value, the convergence 
                is achieved.
                }
        }

        var precondition -type LOGICAL {
            default {.true.}
            info {
                If set to .true. a precondition is used. At this moment, 
                one sees no reason why not to use the precondition. 
                }
        }

        var single_pole -type LOGICAL {
            default {.false.}
            info {
                A slightly better way to set the initial trial vectors, 
                but the improvement is really small. Currently this flag
                can be used only with LDA/PBE + NC PPs. So do not use 
                it unless it is really necessary. 
                }
        }

        var if_dft_spectrum -type LOGICAL {
            default {.false.}
            info {
                When set to .true. the independent particle approximation
                is used, i.e. the Hartree and exchange-correlation response
                contributions are neglected.
                }
        }

        var reference -type REAL {
            default {0.0d0}
            info {
                Reference energy in units of Ry. This variable is used
                to constrain the Davidson algorithm to converge the eigenstates
                having the energy closest to the reference energy. In this way 
                one can calculate less eigenstates at once, and to perform multiple
                calculations with different reference energies (the post-processing
                code tddfpt_calculate_spectrum.x can be used for this purpose). 
                }
        }
 
       var broadening -type REAL {
            default {0.005d0}
            info {
                Lorentzian broadening (Ry) to broaden the absorption spectrum. 
                }
        }

        var start -type REAL {
            default {0.0d0}
            info {
                The lower limit of the energy (Ry) scale for the spectrum calculation.
                }
        }

        var finish -type REAL {
            default {1.0d0}
            info { 
                The upper limit of the energy (Ry) scale for the spectrum calculation.
                }
        }

        var step -type REAL {
            default {0.001d0}
            info {
                Energy step (Ry) for the spectrum calculation. 
                }
        }

        var p_nbnd_occ -type INTEGER {
            default {10}
            info {
                Number of occupied states selected from the total number
                of occupied states computed by PWscf. This variable is
                useful if there are too many occupied states but your
                are interested in only some of them.
                In priciple this variable and @ref p_nbnd_virt affect only 
                the interpretation of the eigenstates, but do not effect
                their energy and the final absorption spectrum.
                Make sure that min(p_nbnd_occ,nbnd_occ)*min(p_nbnd_virt,nbnd_virt) 
                is lager than the number of initial vectors (@ref num_init), 
                so you will not end up using random trial vectors which would 
                slow down the convergence.
                }
        }

        var p_nbnd_virt -type INTEGER {
            default {10}
            info {
                Number of empty states selected from the total number
                of empty states computed by PWscf. This variable is
                useful if there are too many empty states but your
                are interested in only some of them.
                In priciple this variable and @ref p_nbnd_occ affect only 
                the interpretation of the eigenstates, but do not effect 
                their energy and the final absorption spectrum.
                Make sure that min(p_nbnd_occ,nbnd_occ)*min(p_nbnd_virt,nbnd_virt) 
                is lager than the number of initial vectors (@ref num_init),
                so you will not end up using random trial vectors which would
                slow down the convergence.
                }
        }

        var poor_of_ram -type LOGICAL {
            default {.false.}
            info {
                Use this variable if you do not have enough RAM (only USPP),
                i.e. set it to .true. When this variable is set to .false., 
                you double the memory used for the USPP calculation, but you 
                increase a speed of the calculation by getting rid of
                applying many times of s_psi and cal_bec in the 
                calculation, which takes a lot of time (sometimes more than 
                a half of the whole calculation) when the size of the 
                subspace is more than 100.
                }
        }

        var poor_of_ram2 -type LOGICAL {
            default {.false.}
            info {
                Use this variable if you do not have enough RAM (NCPP and USPP),
                i.e. set it to .true. When this variable is set to .false., 
                you double the memory used for the calculation, but you 
                increase a speed of the calculation by storing D_ and C_ 
                basis: the calculation will be speeded up a lot when 
                one is calculating many transitions at the same time. 
                }
        }

        var max_iter -type INTEGER {
            default {100}
            info {
                Maximum number of Davidson iterations allowed. When the 
                number of iterations arrives this number, the calculation 
                will stop even if the convergence has not been achieved.
                }
        }

	var no_hxc -type LOGICAL {
	    default {.false.}
	    info {
		When set to .true. the change in the internal field 
		(Hartree and exchange-correlation) is ignored in the 
		calculation, resulting in the independent electron 
		approximation.
		}
	}

        var pseudo_hermitian -type LOGICAL {
            default {.true.}
            info {
                When set to .true. the pseudo-Hermitian Lanczos
                algorithm is used. When set to .false. the
                non-Hermitian Lanczos biorthogonalization algorithm
                is used (which is two times slower).
                }
        }

        var ltammd -type LOGICAL {
            default {.false.}
            info {
                When set to .true. the Tamm-Dancoff approximation is used
                in constructing the Liouvillian.
                }
        }

        var lplot_drho -type LOGICAL {
            default {.false.}
            info {
                When set to .true. the turbo_davidson.x code will write 
                files for each eigenstate "drho-of-eign-$i" which are 
                needed to plot the response charge-density at each resonance. 
                This implies a calculation using the pp.x post-processing 
                program with the corresponding input file which must be 
                prepared. See example "H2O-PLOTRHO". 
                }
        }

        var d0psi_rs -type LOGICAL {
            default {.false.}
            info {
                When set to .true. the dipole is computed in the
                real space. When set to .false. the dipole is
                computed in the reciprocal space by computing [H,r].
                Note, currently the commutator does not contain
                a contribution for hybrids [V_EXX,r]. See also
                the variable @ref lshift_d0psi.
                Important: Treatment of the dipole in the real space
                is allowed only if the system is finite.
                }
        }

        var lshift_d0psi -type LOGICAL {
            default {.true.}
            info {
                This variable is used only when @ref d0psi_rs = .true.
                a) If a molecule is placed in the corner of the
                supercell, there is a discontinuity problem for the
                position operator r, which is not periodic. By setting
                @ref lshift_d0psi = .true. the discontinuity problem is
                solved by shifting the position operator r such that
                it is continuous and well defined.
                b) If a molecule is placed in the center of the supercell,
                there is no discontinuity problem for the position operator r,
                and thus you can set @ref lshift_d0psi = .false. But if you still
                set it to .true., this will not harm, because the position
                operator will basically remain as it is, since it is always
                centered wrt the center of the molecule.
                }
        }
    }			
}