2 General structure of ph.x
Keywords: developer_man

Next: 3 GRID parallelization and Up: User's Guide for the Previous: 1.2 Who may read Contents

# 2 General structure of `ph.x`

The behavior of the `ph.x` code is controlled by a set of flags. In a general run when all control flags are `.true.` the phonon code computes the following quantities in the given order:

                                  frequency             q        perturbations

    polarizability                   iu                 gamma       x,y,z
    dielectric constant               0                 gamma       x,y,z
    zeu                               0                 gamma       x,y,z
    electro optic coefficient         0                 gamma       x,y,x
    raman tensor                      0                 gamma       3 x 3
    dynamical matrix                  0                 all q      all irreps
    zue                               0                 gamma      all irreps
    electron phonon interactions      0                 all q      all irreps

    zeu = Born effective charges as derivative of the forces,
    zue = Born effective charges as derivative of the polarization

Two control flags associated to every calculated quantity allow to set/unset the calculation of that quantity independently from the others. One of these flags is an input variable:

    fpol,             if .TRUE. computes the frequency dependent polarizability
    epsil,            if .TRUE. computes the dielectric constant
    zeu,              if .TRUE. computes eff. charges as induced forces
    lraman,           if .TRUE. computes the raman tensor
    elop,             if .TRUE. computes the el-optical coefficient
    trans,            if .TRUE. computes the dynamical matrix
    zue,              if .TRUE. computes eff. charges as induced polarization
    elph              if .TRUE. computes the electron phonon coupling

By default, only the `trans` flag is `.true.`. The second flag is described in the following Section.

The phonon code contains three loops. The outer loop is over q points. The other two loops are inside the q-point loop, but they are separate and carried out sequentially. There is a loop over the frequencies that calculates the frequency dependent polarizabilities and a loop over the irreducible representations (`irreps`). In addition to this there is the calculation of the response to the electric field. The loop over the frequencies and the response to an electric field are calculated only if q is the Γ point. The size of the loops over the frequencies and over q points is controlled by input variables.

    nfs               ! number of frequencies
    fiu(nfs)          ! frequencies in Ry

    nq1, nq2, nq3     ! the mesh of q points
    or
    xq                ! the coordinates of a q point

    start_q           ! initial q to calculate
    last_q            ! last q to calculate
    start_irr         ! initial representation to calculate
    last_irr          ! last representation to calculate

The run can be controlled also in other two ways by the following input variables:

    nat_todo          ! the number of atoms to move
    atomo(nat_todo)   ! which atoms to move

    or

    modenum           ! the response to a single mode

The first two options limit the calculation to the representations in which at least one of a set of atoms (specified by `atomo`) moves. The second option calculates only the motion with respect to one vibrational mode.

The flow of the code can be summarized as follows:

    1) Read input and set the flags of the quantities to compute
       1.1) Read all the quantities written by pw.x
       1.2) Read the pseudopotential data

    2) Decide what must be calculated.
       2.1) If not already on disk, compute the grid of q points and
            all the modes for all q points and save on disk (SD)
       2.2) If image parallelization is requested divide the work among images

    3) In a recover run check what is already available on the .xml files and
       sets the appropriate done flags to .TRUE.

    4) Start a main loop over the q points:

       4.1) Compute all quantities that do not depend on the response of the system
       4.2) Check if a band calculation is needed and do it.
       NB: the following points are executed only when q is Gamma.
         4.3) Start a loop on the frequencies
              4.3.1) Compute the polarizability as a function of iu SD
         4.4) Compute the response to an electric field
         4.5) Compute epsilon and SD
         4.6) Compute zeu and SD
         4.7) Compute the electro-optic coefficient and SD
         4.8) Compute the second order response to E
         4.9) Compute Raman tensor and SD
       END NB

    5) Start a loop over the irreducible representation
         5.1) Compute the response to an irreducible representation
         5.1.1) Accumulate the contribution to electron-phonon SD
         5.1.2) Accumulate the contribution to the dynamical matrix
         5.1.3) Accumulate the contribution to zue
         5.1.4) SD this contribution to the dynamical matrix and to zue
    continue the loop 5) until all representations of the current q point
    have been computed

    6) diagonalize the dynamical matrix and SD (only if all representations of
       this q have been computed)

    7) Sum over k and bands the electron-phonon couplings to calculate gamma_mat
       SD (only if all representations of this q have been computed)

    8) continue the loop at point 4 until all q points have been computed

In more detail the quantities calculated by the phonon code and the routines where these quantities are calculated are:

- 4.2.1) The polarization as a function of the complex frequency is a `3x3` real tensor for each frequency: `polar(3,3,nfs)` (calculated in `polariz`). These quantities are presently written on output.

- 4.5) The dielectric constant is a real `3x3` tensor: `epsilon` (calculated in `dielec`).

- 4.6) Zeu is a real array: `zstareu(3,3,nat)`. The first index is the electric field, while the other two indices give the atom that moves and the direction.

- The electro-optic tensor is a three indices tensor `eloptns(3,3,3)` that is calculated by the routine `el_opt`. It requires the response to the electric field perturbation.

- The raman tensor is a real array `ramtns(3,3,3,nat)` that gives the derivatives of the dielectric constant when the atom nat moves. The third index give the direction of the displacement. It requires the first and the second order response of the wavefunctions with respect to the electric field perturbation. It is calculated by the routine `raman_mat`.

- The dynamical matrix is a complex matrix of dimensions `(3 * nat, 3 * nat)`. It is calculated by three routines: `dynmat0` computes the part that does not require the linear response of the system. It has an ion-ion term, a term common to NC, US, and PAW scheme and the nonlinear core correction term. The US and PAW schemes have additional parts, one of them calculated inside `dynmat0` with a call to `addusdynmat`, and another part calculated in `drho`. There is then a contribution that requires the response of the wavefunctions calculated in `drhodv` and `drhodvloc` which is common to the NC, US, and PAW schemes. The latter two schemes have other contributions calculated in `drhodvus`. This routine contains also the additional PAW term.

- 5.1.3 Zue is a real array: `zstarue(3,nat,3)`. The first two indices give the atom that moves and the direction, the third gives the electric field.

- The electron phonon coefficients are explained in the `PHonon` user guide. `ph.x` saves on `.xml` files g, ν(, i, j) for all the modes of an irreducible representation. The coefficients are saved for each k and for all the perturbations. Each irreducible representation is contained in a different file (see below). Note that these quantities are gauge dependent, so if you calculate them on different machines with the GRID parallelization, you can use them only for gauge invariant quantities. Be very careful with it. (still at an experimental stage).

All the quantities calculated by the phonon code are saved in the `fildyn` files with the exception of the polarization as a function of the complex frequency that is written on output, and of the electron phonon coefficients. The output of the code in the latter case is given by the files `a2Fq2r.#.#iq`.

The charge density response to the electric field perturbations and to the atomic displacements, or the change of the Kohn and Sham potential can be saved on disk giving appropriate input variables. These quantities are saved on disk by `solve_e` and `solve_linter`.

Next: 3 GRID parallelization and Up: User's Guide for the Previous: 1.2 Who may read Contents