Keywords: developer_man

Next: 7 Suggestion for developers Up: User's Guide for the Previous: 5 Files produced by Contents

# 6 The routines of the PHonon package

The routines of the `PHonon` package can be divided in groups of related task. There are high level drivers that call the routines that do the actual work and low level routines that make a single task. Note that the phonon code is tightly integrated in the QE package, so it uses the routines provided by the `Modules` or by the `PW/src` directories. Only a brief comment on the purpose and the use of the routines can be found here. More details might be written inside the routines themselves. We report here the name of the file that contains the routines. Each file might contain more than one routine. Unfortunately sometimes there is no correspondence between the name of the file and the name of the routine. This is mainly for historical reasons. We adopt the following convention: if the file and the routine contained inside have the same name we report only the filename; if the file contains a single routine with a different name or more than one routine, we report in parenthesis the routine name.

Modules that contain the variables used by `ph.x`:

    phcom.f90  Almost all global variables are here.
    elph.f90   Variables needed for the electron-phonon part.
    ramanm.f90 Variables for Raman calculation.

Global variables allocation and deallocation. Note that some variables are allocated by `phq_readin` and by `ph_restart`.

    allocate_phq.f90    This is the main allocation routine in which almost
                        all global variables are allocated. It needs only the
                        dimensions defined in pw.x.
    allocate_part.f90   Allocate quantities for the partial computation of
                        the dynamical matrix. It is called in phq_readin.
    allocate_pert.f90   Allocate the symmetry matrices in the basis of the
                        modes. It needs the maximun number of perturbations.
    deallocate_part.f90 Deallocate the variables allocated by allocate part.
    deallocate_phq.f90  Deallocate all the ph.x variables allocated in
                        allocate_phq. The variables allocated in phq_readin
                        or ph_restart should be deallocated by destroy_status_run,
                        contained in ph_restart.
    clean_pw_ph.f90     Clean all variables of pw.x and of ph.x. Used to
                        reinitialize the calculation at each q.

Starting point and main programs. The directory `PHonon/PH` contains seven executables whose main programs are:

    phonon.f90     This is the main program of ph.x
    q2r.f90        This is the main program of q2r.x
    matdyn.f90     This is the main program of matdyn.x
    dynmat.f90     This is the main program of dynmat.x
    fqha.f90       This is the main program for fqha.x
    dvscf_q2r.f90  This is the main program for dvscf_q2r.x
    postahc.f90    This is the main program for postahc.x

Reading input, pseudopotentials, and files written by `pw.x`:

    phq_readin.f90      This is the routine that reads the input, the PP and
                        the punch file of pw.x.
    bcast_ph_input.f90  This routine broadcasts the input variables to all
                        processors.
    save_ph_input.f90 (save_ph_input_variables) A few input variables are
                      changed by the ph.x code and are saved by this routine.
                      (restore_ph_input_variables) this routine restores the
                      saved variables.
                      (clean_input_variables) deallocate the saved variables.

Check the initial status of the calculation and decide what has to be computed:

    check_initial_status.f90  Tests the initial status of the calculation,
                              prepare or reads the mesh of q points and the
                              irreps, divide the work among images and creates
                              the necessary directories in outdir.
               (image_q_irr) Divide the work among several images.
               (collect_grid_files) Copy the files produced by images in
                             the .phsave directory of the image0.
    check_if_partial_dyn.f90  Control partial calculations in phonon.
    check_restart_recover.f90 Check if a restart or recover file is present
                              in the outdir directory

Note: in the following some of the listed routines are contained in folder `LR_Modules`). Routines that select the small group of q and other symmetry related quantities used by the `ph.x` code:

    set_small_group_of_q.f90  This is a driver that selects among the s matrices
                   those of the small group of q. Check if q-> -q+G symmetry
                   exists. If modenum > 0 removes also the symmetries that do not
                   send the mode in itself.
          (smallg_q) do the actual work of selecting the s matrices.
    mode_group.f90 Find the small group of q and of the mode (used with modenum)

    smallgq.f90 (set_giq)  Find the G vectors associated to each rotation: Sq=q+G.

Routines that manipulate or generate the irreducible representations, the q-point mesh and all the preparatory stuff that is needed by the `ph.x` code:

    q_points.f90   Generate the mesh of q vectors.
    check_q_points_sym.f90  Check if the q point mesh is compatible with the fft
                   mesh used by q2r.x.

    init_representations.f90 This is a driver that initialize all the irreps
                   for all q vectors. First it finds the small group of q
                   and then calls find_irrep for each q.
        (initialize_grid_variables) This routine reads the irreps from file and
                   sets the variables that define the grid of q and irreps.

    find_irrep.f90 Find the irreps of a given q calling set_irr or set_irr_nosym.
       (find_irrep_sym) is a driver that allocate the symmetry matrices in
                    the basis of the modes and calls set_irr_sym to calculate
                    them.

    random_matrix.f90 Generate the random matrix to calculate the irreps.

    set_irr.f90    Call random_matrix to generate a random matrix and
                   symmetrize it. The eigenvectors are the irreps. Count their
                   degeneracy and if search_sym is true find their symmetry.

    set_irr_nosym.f90 As set_irr in the case in which the system has no
                   symmetry or symmetry is not used.

    set_irr_sym.f90 Calculate the rotation matrices on the irreps basis.

High level drivers that make the actual calculation:

    prepare_q.f90  Decides if a given q has to be calculated and if it needs
                the band calculation or just to open the k-point list.

    initialize_ph.f90 Initialization driver. It calls the other initialization
                 routines one after the other: allocate_phq, phq_setup,
                 phq_recover, phq_summary, openfilq, and phq_init.

    phq_setup.f90 Setup many quantities needed by the phonon. The
                 most significant are: the local+SCF potential, derivatives
                 of xc potential, using dmxc or similar functions and setup_dgc,
                 alpha_pv and occupated bands, rotation matrices on the
                 basis of the mode (calling find_irrep_sym), setup the gamma_gamma
                 tricks.

    phq_init.f90 Setup more complex quantities that require the implementation
                 of more complex formula.
                 It is a driver that uses auxiliary routines:
                 set_drhoc, setlocq, dvanqq, drho, dynmat0. Moreover it computes
                 becp1, alphap, eprec.

    phescf.f90  This is the main driver for the electric field perturbations.
                It decides what to compute on the basis of the input flags.
                It can compute polarization, epsilon, raman, and elop.

    phqscf.f90  This is the main driver for the phonon perturbation. It has
                a loop over the irreps at a given q. It calls solve_linter
                to calculate the perturbed wavefunctions and potentials, drhodv
                to update the dynamical matrix and add_zstar_ue to update the
                zue effective charges.

Opening and closing files:

    openfilq.f90 Open almost all files of the ph.x code.
    close_phq.f90 Close the above files if opened.

Drivers that compute the band structure using the `pw.x` routines:

    run_nscf.f90 This routine runs pw.x to calculate the bands. It calls
                 init_run, electrons, and punch. However the functionalities
                 of setup are provided by setup_nscf.
    set_defaults_pw.f90 (setup_nscf)
                This routine sets the input of pw.x with default values.
                It sets the k point list.

Routines that compute quantities independent from the perturbed wavefunctions that are used in the rest of the code (mainly US/PAW part). These routines are called by `phq_init`:

    dvanqq.f90 This routine computes four of the five integrals
               of the augmentation functions and its derivatives with
               derivatives of the local potential. Needed only in the US/PAW case.

    drho.f90   This is a driver that computes the parts of the
               induced charge density and of the dynamical matrix that
               do not depend on the change of the wavefunctions. These
               terms are present only in the US/PAW case.
               It calls many of the following routines.

    compute_becsum_ph.f90  This routine computes becsum.
    compute_alphasum.f90   This routine computes alphasum.
    compute_becalp.f90     Compute the product of vkb and psi_{k+q} or of the
                           derivative of vkb and psi_{k+q}

    compute_drhous.f90  This is a driver that makes a loop over the k points
               to accumulate, using incdrhous, the part of the induced
               charge density due to the change of the orthogonality
               constraint. All the modes are computed here. (US/PAW case only).

    compute_drhous_nc.f90  As compute_drhous in the noncollinear/so case.

    incdrhous.f90  Accumulate for a given k point and a given mode
                   the contribution to the induced charge density due to the
                   change of the orthogonality constraint.
    incdrhous_nc.f90  As incdrhous in the noncollinear/so case.

    compute_nldyn.f90  Computes the orthogonality term in the dynamical matrix.
                       Used only in the US/PAW case.

    compute_weight.f90 Compute the composite weights for metals.

    qdipol_cryst.f90 This routine computes the dipole moment of the augmentation
               functions.

    setlocq.f90 This routine computes the local potential at q+G.
    compute_dvloc.f90 Computes the change of the local potential due to
                a phonon perturbation.

    setqmod.f90 Computes (q+G)**2
    hdiag.f90   Computes the kinetic energy.

Lower level drivers that set up and solve the linear system to calculate the response of the system to a perturbation:

    solve_linter.f90 Driver to calculate the phonon perturbation.
    solve_e.f90      Driver to calculate the static electric field perturbation.
    solve_e_fpol.f90 Driver to calculate the electric field perturbation at
                     imaginary frequency.
    solve_e2.f90     Driver for the electric field perturbation at second order.
    solve_e_nscf.f90 A simplified version of solve_e in which the induced
                     self consistent potential is already known. This
                     routine is used in dhdrhopsi.f90.

Routines used by the above drivers to do their job. Some of these routines are used by all drivers, others are specific for a given perturbation:

    dvpsi_e.f90      Compute the right hand side of the linear system in
                     the electric field case (only non SCF part). It
                     uses commutator_Hx_psi.
    commutator_Hx_psi.f90  Compute the commutator of the Hamiltonian with r.

    dvpsi_e2.f90   Compute the right hand side of the linear system for
                   the second order perturbation in the electric field case.
    dvqpsi_us.f90    Compute the right-hand side of the linear system in the
                     phonon case (Only non SCF part). It uses dvqpsi_us_only.
    dvqpsi_us_only.f90  The part of dvqpsi due to the nonlocal potential.

    cft_wave.f90    Wavefunction from real to reciprocal space and return.
    apply_dpot.f90  Add the contribution of the change of the SCF potential
                    to the right-hand side of the linear system.
    adddvscf.f90    Add the additional US/PAW contributions to the right-hand
                    side of the linear system (phonon case).
    adddvepsi_us.f90 As adddvscf for the electric field case.

    orthogonalize.f90 Apply the projector on the valence bands to the right-hand
                    side of the linear system. Deal with both insulators and metals.

    cgsolve_all.f90  Solve the linear system with an iterative conjugate gradient
                     method.

    pcgreen.f90      Orthogonalize and solve the linear system. Used by
                     solve_e2 and solve_e_nscf instead of the more standard method.
                     Call cgsolve_all for doing the actual calculation.

    gmressolve_all.f90 Solve the linear system in the case of
                       imaginary frequency polarizability calculation.

    ch_psi_all.f90     Apply H+Q-eS to the wavefunctions. Used by the routine that
                       solves the linear system.

    cch_psi_all.f90    As ch_psi_all for complex e. Used by gmresolve_all.

    h_psiq.f90         Calculate h psi for k+q. Compute also S psi.
    cg_psi.f90         Apply the preconditioning.
    ccg_psi.f90        A complex preconditioning for gmresolve_all.

    incdrhoscf.f90     Add the contribution of the computed set of perturbed
                       wavefunction at a given k and for a given perturbation
                       to the perturbed change density.
    incdrhoscf_nc.f90  As incdrhoscf for the noncollinear/so case.
    addusdbec.f90      Add the contribution of the computed set of perturbed
                       wavefunctions at a given k and for a given perturbation
                       to the change of the becsum.
    addusdbec_nc.f90   As addusdbec for the noncollinear/spin-orbit case.

    addusddens.f90     Add the US/PAW augmentation contribution to the change
                       of the charge density. (Phonon case)
    addusddense.f90    Add the US/PAW augmentation contribution to the change
                       of the charge density. (Electric field case)

    dv_of_drho.f90     Compute the change of the SCF potential given the change
                       of the SCF charge density.

    mix_pot.f90        Mix input and output induced SCF potentials. In the
                       PAW case mixes also dbecsum.

    newdq.f90          Integrate the augmentation function with the change of
                       the SCF potential (US/PAW case only). In the PAW case
                       add the PAW contribution to the change of the coefficients
                       of the nonlocal potential. The coefficients calculated
                       here are used by adddvscf (phonon case) and adddvepsi_us
                       (electric field case).

    PW/src/paw_onecenter.f90:
                       (PAW_dpotential) Computes the change of the coefficients
                       on the nonlocal potential due to the perturbation
                       (Only PAW case).

    ef_shift.f90       Accounts for the change of the Fermi level in metals at
                       the gamma point.
      (ef_shift_paw)   Account also for the change of dbecsum.

    localdos.f90       Computes the local DOS.
    addusldos.f90      US contribution to the local DOS.

Routines that calculate the derivative of the xc potential. Note that some of them are also in `Module/funct.f90`:

    setup_dgc.f90   Sets the derivative of the xc functionals needed to
                    calculate the change of the potential. It is called by
                    phq_setup.
    d2mxc.f90       LDA second derivatives of the xc functional
    dgradcorr.f90   Change of the GGA part of the xc potential.
    compute_vsgga.f90  Additional GGA term present in the noncollinear/spin-orbit
                     case.

Routines that deal with the nonlinear core correction (NLCC):

    set_drhoc.f90  Fourier transform of the core charge at q+G. Called by
                   phq_setup.
    addcore.f90    Change of the core charge for a phonon perturbation.
                   Used by dv_of_drho and addnlcc.
    dynmatcc.f90   NLCC contribution to the dynamical matrix independent from
                   the perturbed wavefunctions. Called by dynmat0.
    addnlcc.f90    The nlcc part of the dynamical matrix that depends on the
                   perturbed potential. Called by solve_linter.

Frequency dependent polarizability:

    polariz.f90   Computes the frequency dependent polarizability, given dpsi.

Dielectric tensor:

    dielec.f90    Computes the dielectric tensor, given dpsi.

Born effective charges:

    add_zstar_ue.f90     Add the contribution to zue due to dpsi induced by
                         a phonon
    add_zstar_ue_us.f90  Add the US contribution to zue
    zstar_eu.f90         Compute zeu from the dpsi induced by an electric field
    zstar_eu_us.f90      Add the US/PAW contribution to zeu.
    add_dkmds.f90        Additional terms for the US/PAW Born effective charges
    psidspsi.f90         Calculate <psi_v'|ds/du|psi_v>
    add_for_charges.f90  Calculate dS/du P_c [x, H-eS] |psi>
    addnlcc_zstar_eu_us.f90  Add nlcc contribution to zeu
    dvkb3.f90     Derivative of beta functions with respect to q and tau.

Raman tensor:

    raman.f90       This is the main driver for the raman calculation. It
                    computes the second order response calling solve_e2 and
                    the right hand side calling dvpsi_e2.
    raman_mat.f90   Computes and writes the raman tensor.
    dhdrhopsi.f90   Computes Pc [DH,Drho] |psi>.
    dielec_test.f90 Compute the dielectric constant with the quantities
                    calculated inside dhdrhopsi.

Electro-optic tensor:

    el_opt.f90     Computes the electro-optic tensor.

Dynamical matrix:

    dynmat0.f90      Driver for the part of the dynamical matrix independent
                     from the perturbation. It calls dynmatcc, d2ionq, and
                     dynmat_us. This routine is called by init_phq.

    dynmat_us.f90    Expectation value of the second derivative of the
                     local and nonlocal potentials.
    addusdynmat.f90  US/PAW contribution to the second derivative of
                     the potential. There are terms due to the change of the
                     augmentation function.
    d2ionq.f90       Ewald contribution.

    drhodv.f90       Contribution to the dynamical matrix due to the change
                     of the wavefunctions.
    drhodvnl.f90     Accumulate the contribution to the dynamical matrix due
                     to the change of the wavefunctions (Only the contribution
                     of the nonlocal PP). Called at each k point.
    drhodvloc.f90    As drhodvnl for the local potential. It can be calculated
                     as an integral of the potential and the induced charge
                     density.
    drhodvus.f90     A term present only in the US/PAW case. Integral of the
                     induced SCF potential and the change of the charge at
                     fixed wavefunctions. It is called in solve_linter because
                     the induced potential is not available outside.

    dynmatrix.f90    Is a driver that collects the dynamical matrix, checks if
                     all representations have been calculated, symmetrize the
                     dynamical matrix, computes the matrices rotated in all
                     equivalent q and diagonalizes the matrix. The same is
                     done for zue.

Electron-phonon coupling coefficients:

    elphon.f90   This is a driver that in the case trans=.false. reads the
                 induced self-consistent potential and calculates the
                 electron-phonon matrix elements. It reads also the
                 dynamical matrix and diagonalizes it.
        (readmat) read the dynamical matrix.
        (elphel) compute the electron-phonon matrix elements.
        (elphsum) make a sum over the BZ of the square moduli of the
                  el-ph matrix elements and compute phonon linewidths. This
                  routine makes a linear interpolation on k points
                  (still unsettled). Require compatibility between q and k
                  meshes.
        (elphsum_simple) As elphsum but without the interpolation. It can be
                  used at arbitrary q.
    el_ph_collect.f90  Collect the electron-phonon matrix elements among pools.
    clinear.f90
    ahc.f90       Calculate first- and second-order electron-phonon quantities
                  for the calculation of phonon-induced electron self-energy.

Routines that write the output quantities:

    phq_summary.f90  Summarize what has been read from the pw output and
                     what has been calculated by phq_setup.

    summarize.f90    Write the tensors on output.
         (summarize_epsilon) write the dielectric tensor.
         (summarize_zeu) write zeu.
         (summarize_zue) write zue.
         (summarize_elopt) write the electro-optic tensor.
         (summarize_fpol) write the frequency dependent polarizability.

    write_epsilon_and_zeu.f90 Use the routines of summarize, but contain also old
                     instructions to write the dielectric constant and
                     the Born effective charges in the dynamical matrix file.

    write_modes.f90
          (write_modes_out) This routine writes the modes on output. It is called
                     by set_irr and by phq_summarize.

    write_qplot_data.f90  Write a file that can be read by plotband with
                      q vectors and phonon frequencies.

    write_ramtns.f90  Write the raman tensor.

    write_eigenvectors.f90 Used by matdyn to write the eigenvectors on output.
                     Writes the displacements in several format suited to some
                     molecular graphics programs.

Routines that write on file the induced charge densities:

    punch_plot_e.f90 Write the change of the charge due to an electric field.
    davcio_drho.f90  Write the change of the charge due to a phonon perturbation.

Routines that read or write the `.xml` files with the partial results:

    ph_restart.f90  This file contains many routines to write and read the .xml
                    files that contain the partial results of ph.x. See the section
                    "file produced by ph.x".
           (ph_writefile) This routine can be called from external routines to
                    write the tensors on file.
           (ph_readfile)  This routine can be called from external routines to
                    read the tensors from file.
           (check_directory_phsave) This routine tries to read the files in the
                    phsave directory to check what has been already calculated.
           (check_available_bands) This routine search on the outdir directory
                    for the bands files to see if they have been already
                    calculated.
           (allocate_grid_variables) This routine allocates space for the variables
                    that control the grid calculation.
           (destroy_status_run) This routine deallocates the variables that
                    control the grid and the variables allocated by phq_readin
                    or ph_restart.

    io_dyn_mat.f90  This file contains the routines that read and write the
                    dynamical matrix in .xml format.

    io_dyn_mat_old.f90 These are the routines that read and write the dynamical
                    matrix in the old format (not .xml).

Routines that read or write the recover file:

    phq_recover.f90 This routine reads the recover files and reconstruct the
                    status of the calculation so far.
    write_rec.f90   This file contains the routine that writes the
                    recover file (in unformatted form).
         (read_rec) read the recover file.

Symmetrization of induced potentials:

    symdvscf.f90   Symmetrize the change of the potentials due to a set of
                   perturbations that form an irreducible representation.
    syme.f90       Symmetrize the change of potentials due to electric field
                   perturbations.
    sym_dmag.f90   Symmetrize the change of B_xc due to a set
                   of phonon perturbations.
    sym_dmage.f90  Symmetrize the change of B_xc due to a set of electric field
                   perturbations
    syme2.f90      Symmetrize the potential of the second order response.

and parallel routines that collect on a single processor the quantity to symmetrize and call the previous routines:

    psymdvscf.f90   Parallel version of symdvscf.
    psyme.f90       Parallel version of syme.
    psym_dmag.f90   Parallel version of sym_dmag.
    psym_dmage.f90  Parallel version of sym_dmage.
    psyme2.f90      Parallel version of syme2.

Symmetrization of tensors or other quantities:

    symdyn_munu.f90 Symmetrize a dynamical matrix on the basis of the modes,
                    transforming it in the cartesian basis and applying
                    symdynph_gq.
    symdynph_gq.f90 Symmetrize a dynamical matrix written in cartesian coordinates.
    star_q.f90      Given a q point finds all the q in its star.
    q2qstar_ph.f90  Generate the dynamical matrix in all the q of the star.
    rotate_and_add_dyn.f90 Rotate a dynamical matrix with a given symmetry
                    operation.
    tra_write_matrix.f90 Symmetrize the dynamical matrix written in the basis
                  of the modes, brings it in cartesian form and write it.
    trntnsc.f90   Transform a complex 2D tensor from the crystal basis to the
                  cartesian basis or vice-versa.
    sym_def.f90   Symmetrize the change of the Fermi level due to the phonon
                  perturbations.
    sym_and_write_zue.f90  Symmetrize zue.
    symm.f90      Symmetrize the electron-phonon coefficients.
    rotate_pattern_add.f90  These are a set of auxiliary routines that manipulate
                  the dynamical matrix in different forms. See the heading
                  of this matrix to see its capabilities.

Routines that perform the symmetry analysis of the eigenvectors to find to which irreducible representation they belong:

    prepare_sym_analysis.f90 Prepare the quantities for the symmetry analysis.
    symmorphic_or_nzb.f90  A function that checks if symmetry analysis can be
                           carried out. It returns true if q is not at zone border
                           or if the group is symmorphic.
    find_mode_sym.f90    Symmetry analysis of the modes.

Routines that apply the Clebsch Gordan coefficients for the spin-orbit part of the code:

    transform_alphasum_nc.f90  Apply the coefficients to alphasum (no-so case)
    transform_alphasum_so.f90  Apply the coefficients to alphasum (so case)
    transform_dbecsum_nc.f90   Apply the coefficients to dbecsum (no-so case)
    transform_dbecsum_so.f90   Apply the coefficients to dbecsum (so case)
    transform_int_nc.f90       Apply the coefficients to the integrals (no-so case)
    transform_int_so.f90       Apply the coefficients to the integrals (so case)
    set_int12_nc.f90        This is a driver that call the previous routines
                            according to the type of PP.

Routines that apply the `gamma_gamma` trick:

    find_equiv_sites.f90
    generate_dynamical_matrix_c.f90
    generate_effective_charges_c.f90
    set_asr_c.f90

Routine for the Fourier interpolation of the phonon potential:

    dvscf_interpolate.f90

Miscellaneous routines:

    print_clock_ph.f90   Print timings info.
    stop_ph.f90          Stops the phonon code closing all the files.
    rigid.f90            Used by matdyn and dynmat to compute the long range
                         electrostatic part of the dynamical matrix.
    dyndia.f90           Diagonalizes the dynamical matrix.

Obsolete routines that are here for compatibility with other codes that might use them:

    obsolete.f90

Development routines provided by some developers but still incomplete, or used in proprietary codes not yet in the QE distribution, or added and forgotten:

    acfdtest.f90
    read_wfc_rspace_and_fwfft.f90
    dfile_autoname.f90
    dfile_star.f90
    rotate_dvscf_star.f90
    q_points_wannier.f90
    set_dvscf.f90
    ep_matrix_element_wannier.f90
    io_pattern.f90
    cgsolve_all_imfreq.f90
    q2qstar.f90
    write_matrix.f90
    chi_test.f90

Next: 7 Suggestion for developers Up: User's Guide for the Previous: 5 Files produced by Contents