quantum-espresso/PHonon/Doc/INPUT_PH.def

712 lines
24 KiB
Modula-2

input_description -distribution {Quantum Espresso} -package PWscf -program ph.x {
toc {}
intro {
@b {Input data format:} { } = optional, [ ] = it depends, # = comment
@b {Structure of the input data:}
===============================================================================
title_line
@b &INPUTPH
...
@b /
[ xq(1) xq(2) xq(3) ] @i {# if @ref ldisp != .true. and @ref qplot != .true.}
[ nqs @i {# if @ref qplot == .true. }
xq(1,i) xq(2,i) xq(3,1) nq(1)
...
xq(1,nqs) xq(2,nqs) xq(3,nqs) nq(nqs) ]
[ atom(1) atom(2) ... atom(nat_todo) ] @i {# if @ref nat_todo was specified}
}
linecard {
var title_line -type CHARACTER {
info {
Title of the job, i.e., a line that is reprinted on output.
}
}
}
namelist INPUTPH {
dimension amass -start 1 -end ntyp -type REAL {
default { 0.0 }
info {
Atomic mass [amu] of each atomic type.
If not specified, masses are read from data file.
}
}
var outdir -type CHARACTER {
default {
value of the @tt ESPRESSO_TMPDIR environment variable if set;
@br current directory ('./') otherwise
}
info {
Directory containing input, output, and scratch files;
must be the same as specified in the calculation of
the unperturbed system.
}
}
var prefix -type CHARACTER {
default { 'pwscf' }
info {
Prepended to input/output filenames; must be the same
used in the calculation of unperturbed system.
}
}
var niter_ph -type INTEGER {
default { maxter=100 }
info {
Maximum number of iterations in a scf step. If you want
more than 100, edit variable "maxter" in PH/phcom.f90
}
}
var tr2_ph -type REAL {
default { 1e-12 }
info { Threshold for self-consistency. }
}
var alpha_mix(niter) -type REAL {
default { alpha_mix(1)=0.7 }
info {
Mixing factor (for each iteration) for updating
the scf potential:
vnew(in) = alpha_mix*vold(out) + (1-alpha_mix)*vold(in)
}
}
var nmix_ph -type INTEGER {
default { 4 }
info { Number of iterations used in potential mixing. }
}
var verbosity -type CHARACTER {
default { 'default' }
options {
info { Options are: }
opt -val {'debug', 'high', 'medium'} { verbose output }
opt -val {'low', 'default', 'minimal'} { short output }
}
}
var reduce_io -type LOGICAL {
default { .false. }
info { Reduce I/O to the strict minimum. }
}
var max_seconds -type REAL {
default { 1.d7 }
info { Maximum allowed run time before the job stops smoothly. }
}
var fildyn -type CHARACTER {
default { 'matdyn' }
info { File where the dynamical matrix is written. }
}
var fildrho -type CHARACTER {
default { ' ' }
info { File where the charge density responses are written. Note that the file
will actually be saved as ${outdir}/_ph0/${prefix}.${fildrho}1
where ${outdir}, ${prefix} and ${fildrho} are the values of the
corresponding input variables }
}
var fildvscf -type CHARACTER {
default { ' ' }
info {
File where the the potential variation is written
(for later use in electron-phonon calculation, see also fildrho).
}
}
var epsil -type LOGICAL {
default { .false. }
info {
If .true. in a q=0 calculation for a non metal the
macroscopic dielectric constant of the system is
computed. Do not set @ref epsil to .true. if you have a
metallic system or q/=0: the code will complain and stop.
}
}
var lrpa -type LOGICAL {
default { .false. }
info {
If .true. the dielectric constant is calculated at the
RPA level with DV_xc=0.
}
}
var lnoloc -type LOGICAL {
default { .false. }
info {
If .true. the dielectric constant is calculated without
local fields, i.e. by setting DV_H=0 and DV_xc=0.
}
}
var trans -type LOGICAL {
default { .true. }
info {
If .true. the phonons are computed.
If @ref trans .and. @ref epsil are .true. effective charges are
calculated.
}
}
var lraman -type LOGICAL {
default { .false. }
info {
If .true. calculate non-resonant Raman coefficients
using second-order response as in:
M. Lazzeri and F. Mauri, PRL 90, 036401 (2003).
}
}
group {
label { Optional variables for Raman: }
var eth_rps -type REAL {
default { 1.0d-9 }
info { Threshold for calculation of Pc R |psi>. }
}
var eth_ns -type REAL {
default { 1.0e-12 }
info { Threshold for non-scf wavefunction calculation. }
}
var dek -type REAL {
default { 1.0e-3 }
info { Delta_xk used for wavefunction derivation wrt k.}
}
}
var recover -type LOGICAL {
default { .false. }
info { If .true. restart from an interrupted run.}
}
var low_directory_check -type LOGICAL {
default { .false. }
info { If .true. search in the phsave directory only the
quantities requested in input.}
}
var only_init -type LOGICAL {
default { .false. }
info {
If .true. only the bands and other initialization quantities are calculated.
(used for GRID parallelization)}
}
var qplot -type LOGICAL {
default { .false. }
info { If .true. a list of q points is read from input.}
}
var q2d -type LOGICAL {
default { .false. }
info {
If .true. three q points and relative weights are
read from input. The three q points define the rectangle
q(:,1) + l (q(:,2)-q(:,1)) + m (q(:,3)-q(:,1)) where
0< l,m < 1. The weights are integer and those of points two
and three are the number of points in the two directions.
}
}
var q_in_band_form -type LOGICAL {
default { .false. }
info {
This flag is used only when qplot is .true. and q2d is
.false.. When .true. each couple of q points q(:,i+1) and
q(:,i) define the line from q(:,i) to q(:,i+1) and nq
points are generated along that line. nq is the weigth of
q(:,i). When .false. only the list of q points given as
input is calculated. The weights are not used.
}
}
var electron_phonon -type CHARACTER {
default { ' ' }
options {
info {
Options are:
}
opt -val 'simple' {
Electron-phonon lambda coefficients are computed
for a given q and a grid of k-points specified by
the variables nk1, nk2, nk3, k1, k2, k3.
}
opt -val 'interpolated' {
Electron-phonon is calculated by interpolation
over the Brillouin Zone as in M. Wierzbowska, et
al. arXiv:cond-mat/0504077
}
opt -val 'lambda_tetra' {
The electron-phonon coefficient \lambda_{q \nu}
is calculated with the optimized tetrahedron method.
}
opt -val 'gamma_tetra' {
The phonon linewidth \gamma_{q \nu} is calculated
from the electron-phonon interactions
using the optimized tetrahedron method.
}
info {
For metals only, requires gaussian smearing.
If @ref trans=.true., the lambdas are calculated in the same
run, using the same k-point grid for phonons and lambdas.
If @ref trans=.false., the lambdas are calculated using
previously saved DeltaVscf in @ref fildvscf, previously saved
dynamical matrix, and the present punch file. This allows
the use of a different (larger) k-point grid.
}
}
}
var lshift_q -type LOGICAL {
default { .false. }
info {
Use a wave-vector grid displaced by half a grid step
in each direction - meaningful only when ldisp is .true.
When this option is set, the q2r.x code cannot be used.
}
}
var zeu -type LOGICAL {
default { zeu=@ref epsil }
info {
If .true. in a q=0 calculation for a non metal the
effective charges are computed from the dielectric
response. This is the default algorithm. If @ref epsil=.true.
and @ref zeu=.false. only the dielectric tensor is calculated.
}
}
var zue -type LOGICAL {
default { .false. }
info {
If .true. in a q=0 calculation for a non metal the
effective charges are computed from the phonon
density responses. This is an alternative algorithm,
different from the default one (if @ref trans .and. @ref epsil )
The results should be the same within numerical noise.
}
}
var elop -type LOGICAL {
default { .false. }
info {
If .true. calculate electro-optic tensor.
}
}
var fpol -type LOGICAL {
default { .false. }
info {
If .true. calculate dynamic polarizabilities
Requires @ref epsil=.true. ( experimental stage:
see example09 for calculation of methane ).
}
}
var ldisp -type LOGICAL {
default { .false. }
info {
If .true. the run calculates phonons for a grid of
q-points specified by @ref nq1, @ref nq2, @ref nq3 - for direct
calculation of the entire phonon dispersion.
}
}
var nogg -type LOGICAL {
default { .false. }
info {
If .true. disable the "gamma_gamma" trick used to speed
up calculations at q=0 (phonon wavevector) if the sum over
the Brillouin Zone includes k=0 only. The gamma_gamma
trick exploits symmetry and acoustic sum rule to reduce
the number of linear response calculations to the strict
minimum, as it is done in code phcg.x.
}
}
var asr -type LOGICAL {
default { .false. }
info {
Apply Acoustic Sum Rule to dynamical matrix, effective charges
Works only in conjunction with "gamma_gamma" tricks (see above)
}
}
var ldiag -type LOGICAL {
default { .false. }
info {
If .true. forces the diagonalization of the dynamical
matrix also when only a part of the dynamical matrix
has been calculated. It is used together with @ref start_irr
and @ref last_irr. If all modes corresponding to a
given irreducible representation have been calculated,
the phonon frequencies of that representation are
correct. The others are zero or wrong. Use with care.
}
}
var lqdir -type LOGICAL {
default { .false. }
info {
If .true. ph.x creates inside outdir a separate subdirectory
for each q vector. The flag is set to .true. when @ref ldisp=.true.
and @ref fildvscf /= ' ' or when an electron-phonon
calculation is performed. The induced potential is saved
separately for each q inside the subdirectories.
}
}
var search_sym -type LOGICAL {
default { .true. }
info {
Set it to .false. if you want to disable the mode
symmetry analysis.
}
}
vargroup -type INTEGER {
var nq1
var nq2
var nq3
default { 0,0,0 }
info {
Parameters of the Monkhorst-Pack grid (no offset) used
when @ref ldisp=.true. Same meaning as for nk1, nk2, nk3
in the input of pw.x.
}
}
vargroup -type INTEGER {
var nk1
var nk2
var nk3
var k1
var k2
var k3
default { 0,0,0,0,0,0 }
info {
When these parameters are specified the phonon program
runs a pw non-self consistent calculation with a different
k-point grid thant that used for the charge density.
This occurs even in the Gamma case.
nk1,nk2,nk3 are the parameters of the Monkhorst-Pack grid
with offset determined by k1,k2,k3.
}
}
var read_dns_bare -type LOGICAL {
default { .false. }
info {
If .true. the PH code tries to read three files in the DFPT+U
calculation: dns_orth, dns_bare, d2ns_bare.
dns_orth and dns_bare are the first-order variations of
the occupation matrix, while d2ns_bare is the second-order
variation of the occupation matrix. These matrices are
computed only once during the DFPT+U calculation. However,
their calculation (especially of d2ns_bare) is computationally
expensive, this is why they are written to file and then can be
read (e.g. for restart) in order to save time.
}
}
group {
label { Specification of irreducible representation }
var start_irr -type INTEGER {
default { 1 }
see { last_irr }
info {
Perform calculations only from @ref start_irr to @ref last_irr
irreducible representations.
IMPORTANT:
* @ref start_irr must be <= 3*nat
* do not specify @ref nat_todo together with
@ref start_irr, @ref last_irr
}
}
var last_irr -type INTEGER {
default { 3*nat }
see { start_irr }
info {
Perform calculations only from @ref start_irr to @ref last_irr
irreducible representations.
IMPORTANT:
* @ref start_irr must be <= 3*nat
* do not specify @ref nat_todo together with
@ref start_irr, @ref last_irr
}
}
var nat_todo -type INTEGER {
default { 0, i.e. displace all atoms }
info {
Choose the subset of atoms to be used in the linear response
calculation: @ref nat_todo atoms, specified in input (see below)
are displaced. Can be used to estimate modes for a molecule
adsorbed over a surface without performing a full fledged
calculation. Use with care, at your own risk, and be aware
that this is an approximation and may not work.
IMPORTANT:
* @ref nat_todo <= nat
* if linear-response is calculated for a given atom, it
should also be done for all symmetry-equivalent atoms,
or else you will get incorrect results
}
}
var modenum -type INTEGER {
default { 0 }
info {
For single-mode phonon calculation : modenum is the index of the
irreducible representation (irrep) into which the reducible
representation formed by the 3*nat atomic displacements are
decomposed in order to perform the phonon calculation.
Note that a single-mode calculation will not give you the
frequency of a single phonon mode: in general, the selected
"modenum" is not an eigenvector. What you get on output is
a column of the dynamical matrix.
}
}
}
group {
label { q-point specification }
var start_q -type INTEGER {
default { 1 }
see { last_q }
info {
Used only when ldisp=.true..
Computes only the q points from @ref start_q to @ref last_q.
IMPORTANT:
* @ref start_q must be <= @ref nqs (number of q points found)
* do not specify @ref nat_todo together with
@ref start_q, @ref last_q
}
}
var last_q -type INTEGER {
default { number of q points }
see { start_q }
info {
Used only when @ref ldisp=.true..
Computes only the q points from @ref start_q to @ref last_q.
IMPORTANT
* @ref last_q must be <= @ref nqs (number of q points)
* do not specify @ref nat_todo together with
@ref start_q, @ref last_q
}
}
var dvscf_star -type STRUCTURE {
default { disabled }
info {
It contains the following components:
@b dvscf_star%open (logical, default: .false.)
@b dvscf_star%dir (character, default: outdir//"Rotated_DVSCF" or the
ESPRESSO_FILDVSCF_DIR environment variable)
@b dvscf_star%ext (character, default: "dvscf") the extension to use
for the name of the output files, see below
@b dvscf_star%basis (character, default: "cartesian") the basis on which
the rotated dvscf will be saved
@b dvscf_star%pat (logical, default: false) save an optional file with the
displacement patterns and q vector for each dvscf file
IF dvscf_star%open is .true. use symmetry to compute and store the variation
of the self-consistent potential on every q* in the star of the present q.
The rotated dvscf will then be stored in directory dvscf_star%dir with name
prefix.dvscf_star%ext.q_name//"1". Where q_name is derived from the coordinates
of the q-point, expressed as fractions in crystalline coordinates
(notice that ph.x reads q-points in cartesian coordinates).
E.g. q_cryst= (0, 0.5, -0.25) -> q_name = "0_1o2_-1o4"
The dvscf can be represented on a basis of cartesian 1-atom displacements
(dvscf_star%basis='cartesian') or on the basis of the modes at the rotated q-point
(dvscf_star%basis='modes'). Notice that the el-ph wannier code requires 'cartesian'.
Each dvscf file comes with a corresponding pattern file with an additional ".pat"
suffix; this file contains information about the basis and the q-point of the dvscf.
Note: rotating dvscf can require a large amount of RAM memory and can be i/o
intensive; in its current implementation all the operations are done
on a single processor.
Note2: this feature is currently untested with image parallelisation.
}
}
var drho_star -type STRUCTURE {
see {dvscf_star }
default { disabled }
info {
It contains the following components:
@b drho_star%open (logical, default: .false.)
@b drho_star%dir (character, default: outdir//"Rotated_DRHO" or the
ESPRESSO_FILDRHO_DIR environment variable)
@b drho_star%ext (character, default: "drho") the extension to use
for the name of the output files, see below
@b drho_star%basis (character, default: "modes") the basis on which
the rotated drho will be saved
@b drho_star%pat (logical, default: true) save an optional file with the
displacement patterns and q vector for each drho file
Like @ref dvscf_star, but for the perturbation of the charge density.
Notice that the defaults are different.
}
}
}
}
choose {
when -test "ldisp != .true. and qplot != .true." {
linecard {
list xq_list -type REAL {
format { xq(1) xq(2) xq(3) }
info {
The phonon wavevector, in units of 2pi/a0
(a0 = lattice parameter).
Not used if @ref ldisp=.true. or @ref qplot=.true.
}
}
}
}
elsewhen -test "qplot == .true." {
label { Specification of q points when @ref qplot == .true. }
card qPointsSpecs -nameless 1 {
syntax {
line {
var nqs -type INTEGER {
info { Number of q points in the list. Used only if @ref qplot=.true.
}
}
}
table qPoints {
rows -start 1 -end nqs {
colgroup -type REAL {
info {
q-point coordinates; used only with @ref ldisp=.true. and qplot=.true.
The phonon wavevector, in units of 2pi/a0 (a0 = lattice parameter).
The meaning of these q points and their weights nq depend on the
flags q2d and q_in_band_form. (NB: nq is integer)
}
col xq1
col xq2
col xq3
}
col nq -type INTEGER {
info {
The weight of the q-point; the meaning of nq depends
on the flags q2d and q_in_band_form. }
}
}
}
}
}
}
}
choose {
when -test "nat_todo was specified" {
linecard {
list nat_todo_list -type INTEGER {
format { atom(1) atom(2) ... atom(nat_todo) }
info {
Contains the list of indices of atoms used in the
calculation if @ref nat_todo is specified.
}
}
}
}
}
section -title { ADDITIONAL INFORMATION } {
text {
NB: The program ph.x writes on the tmp_dir/_ph0/{prefix}.phsave directory
a file for each representation of each q point. This file is called
dynmat.#iq.#irr.xml where #iq is the number of the q point and #irr
is the number of the representation. These files contain the
contribution to the dynamical matrix of the irr representation for the
iq point.
If recover=.true. ph.x does not recalculate the
representations already saved in the tmp_dir/_ph0/{prefix}.phsave
directory. Moreover ph.x writes on the files patterns.#iq.xml in the
tmp_dir/_ph0/{prefix}.phsave directory the displacement patterns that it
is using. If recover=.true. ph.x does not recalculate the
displacement patterns found in the tmp_dir/_ph0/{prefix}.phsave directory.
This mechanism allows:
1) To recover part of the ph.x calculation even if the recover file
or files are corrupted. You just remove the _ph0/{prefix}.recover
files from the tmp_dir directory. You can also remove all the _ph0
files and keep only the _ph0/{prefix}.phsave directory.
2) To split a phonon calculation into several jobs for different
machines (or set of nodes). Each machine calculates a subset of
the representations and saves its dynmat.#iq.#irr.xml files on
its tmp_dir/_ph0/{prefix}.phsave directory. Then you collect all the
dynmat.#iq.#irr.xml files in one directory and run ph.x to
collect all the dynamical matrices and diagonalize them.
NB: To split the q points in different machines, use the input
variables start_q and last_q. To split the irreducible
representations, use the input variables @ref start_irr, @ref last_irr. Please
note that different machines will use, in general, different
displacement patterns and it is not possible to recollect partial
dynamical matrices generated with different displacement patterns. A
calculation split into different machines will run as follows: A
preparatory run of ph.x with @ref start_irr=0, @ref last_irr=0 produces the sets
of displacement patterns and save them on the patterns.#iq.xml files.
These files are copied in all the tmp_dir/_ph0/{prefix}.phsave directories
of the machines where you plan to run ph.x. ph.x is run in different
machines with complementary sets of start_q, last_q, @ref start_irr and
@ref last_irr variables. All the files dynmat.#iq.#irr.xml are
collected on a single tmp_dir/_ph0/{prefix}.phsave directory (remember to
collect also dynmat.#iq.0.xml). A final run of ph.x in this
machine collects all the data contained in the files and diagonalizes
the dynamical matrices. This is done requesting a complete dispersion
calculation without using start_q, last_q, @ref start_irr, or @ref last_irr.
See an example in examples/GRID_example.
On parallel machines the q point and the irreps calculations can be split
automatically using the -nimage flag. See the phonon user guide for further
information.
}
}
}