A number of examples on how to use PWscf can be downloaded from the Tests and Examples Page.

Electronic and ionic structure calculations are performed by program pw.x.

Input data

The first line is a job identifier: a job title, job name, whatever may be helpful for you. The second line is the name of the material. Both are just reprinted on output and are harmless whatever you write.

At the third line the namelist input starts. It must contain at least the following variables:

ibrav (integer): bravais-lattice index
celldm (real, dimension 6): crystallographic constants
nat (integer): number of atoms in the unit cell
ntyp (integer): number of types of atoms in the unit cell
pseudop (character, dimension ntyp): name of a file containing a PP (one PP per file, as many PP files as types of atom);
ecut (real, dimension maxter): kinetic energy cutoff (Ry) for each iteration; a value given for one iteration is used also for the following iterations up to a specified different value (maxter, presently 100, is set in the code).

Explanations for the meaning of variables ibrav and celldm are in file INPUT_PW. Please read them carefully. There is a large number of other variables, having default values, which may or may not fit your needs. In particular, remember to set iswitch to the appropriate value or you will default to iswitch=0.

After the namelist, you must specify:

a list of atomic positions and of type of atoms
the correspondence between atom type and PP type (this is actually obsolete and kept just for compatibility with old data files)
k-point grid for Brillouin-Zone integration.

The k-point grid can be either automatically generated or manually provided as a list of k-points and a weight in the Irreducible Brillouin Zone only of the Bravais lattice of the crystal. The code will generate all required k-points and weights if the symmetry of the system is lower than the symmetry of the Bravais lattice.

The automatic generation of k-points follows the convention of Monkhorst and Pack.

Typical cases

We may distinguish the following typical cases for pw.x:

• single-point (fixed-ion) SCF calculation. Set iswitch=0 (this is actually the default).
• band structure calculation. First perform a SCF calculation as above, saving the potential in a file whose file name is specified in output_pot. Then do a second calculation with iswitch=-1, input_pot equal to the potential file previously produced, and the desired grid of k-points (which may differ, and usually does, from the grid used for the self-consistent calculation). In this second calculation you may want to specify the desired number of bands in nbnd. This type of calculation is performed in Example 1.
• structural optimization. Specify iswitch=1. All options for a single SCF calculation apply, plus a few other. You may save the output potential using output_pot for use as input for a non-SCF band-structure calculation. In this case, do not forget to update the ionic coordinates with the final ones when you calculate the bands. This type of calculation is performed in Example 3.
• molecular dynamics. Specify iswitch=3 (iswitch=4 if you want a constrained dynamics) and the time step dt. Other options for setting the initial temperature and for thermalization using velocity rescaling are available. Remember: this is MD on the electronic ground state, not Car-Parrinello MD (presently unimplemented). This type of calculation is performed in Example 4.

TOP

The phonon code ph.x calculates normal modes at a given q-vector. If q=0, you need to perform first a SCF calculation (see above) and to save an output file specified in variable filpun.

For phonons at a generic q-vector, you need to perform first a SCF calculation and to save the potential; then a band-structure calculation (see above) with iswitch=-2, specifying an output file in variable filpun and the q-vector in the last line. Of course the procedure for q 0 works also for q=0.

After the output file filpun has been produced (do not remove any of the files, unless you know which are used and which are not), you can run ph.x.

As for pw.x, the first input line is a job identifier. At the second line the namelist inputph starts. Presently you must specify at least the following variables:

filpun (character): the file written by pw.x (must be the same given in the input of pw.x )
amass (real, dimension ntyp): atomic mass of each atomic type

After the namelist you must specify the q-vector of the phonon mode. This must be the same q-vector given in the input of pw.x.

The meaning of the other variables in the namelist (all having a default value, which may or may not fit your needs) is described in file INPUT_PH. A sample phonon calculation is performed in Example 2.

Notes for parallel execution: presently, ph.x must run on the same number of processors and on the same number of pools that were used to produce file filpun. All data files must be visible from every processor.

Calculation of Interatomic Force Constants in real space

First, dynamical matrices are calculated and saved for a suitable uniform grid of q-vectors. Only the q-vectors in the Irreducible Brillouin Zone of the crystal are needed. If the system is an insulator, effective charges and dielectric tensor must be calculated (variable epsil=.true) at q=0.

Second, all dynamical matrices are given as input to code tools/q2r.x. The q=0 file must be the first in the list. This produces a file of Interatomic Force Constants in real space, up to a distance that depends on the size of the grid of q-vectors. Program tools/matdyn.x may be used to produce phonon modes and frequencies at any q using such file of Interatomic Force Constants. Note that at q=0 in insulators you should use program tools/dynmat.x instead.

See also Example 6.

Calculation of electron-phonon interaction coefficients

The calculation of electron-phonon coefficients in metals is made difficult by the slow convergence of the sum at the Fermi energy. It is convenient to calculate phonons, for each q-vector of a suitable grid, using a smaller k-point grid, saving the dynamical matrix and the self-consistent first-order variation of the potential (variable fildvscf). Then a non-scf calculation with a larger k-point grid is performed, saving the output in file filpun. Finally the electron-phonon calculation is performed by specifying elph=.true., trans=-.false., and the input files filpun, fildvscf, fildyn. The electron-phonon coefficients are calculated using several values of gaussian broadening (see phlib/elphon.F90) because this quickly shows whether results are converged or not with respect to the k-point grid and gaussian broadening.

All of the above must be repeated for all desired q-vectors and the final result is summed over all q-vectors (code not yet available).

See also Example 7.

TOP

There are a number of auxilary codes performing postprocessing tasks such as plotting, averaging, and so on, on the various quantities calculated by pw.x. Such quantities are saved by pw.x into the output file filpun. Note that this is actually composed of four files: one for miscellaneous data, one for charge density, one for potential, and one for wavefunctions (one per processor in parallel execution for the latter).

The main postprocessing code pp.x reads data file filpun and may produce on output either the projection of wavefunctions on atomic wavefunctions, or another file containing one of the following quantities:

charge, spin polarization, various potentials, local density of states at E_F, local density of electronic entropy, STM images, wavefunction squared, electron localization function, planar averages, integrated local density of states

Notes for parallel execution: presently, pp.x must run on the same number of processors and on the same number of pools that were used to produce file filpun. All data files must be visible from every processor. The input must be read from a file: pp.x filename, not pp.x < filename. Only one processor writes the output file.

The file(s) produced by pp.x are processed by program chdens.x for plotting. The type of plotting (along a line, on a plane, three-dimensional, polar) and the output format must be specified here. The output file can be directly read by the free plotting system gnuplot (1D or 2D plots), or by code plotrho.x that is provided with PWscf (only 2D plots). More details on the input data are written in the header of file pplib/chdens.F90.

Notes for parallel execution: presently, chdens.x and plotrho.x may run on parallel machines, but only on one processor.

See Example 5 for a charge density plot, Example 8 for electronic Density of States (DOS) calculation.

TOP