PAOFLOW.elphon.qe_elph_io#

Readers for Quantum ESPRESSO electron-phonon coupling output (Phase 1).

These parsers ingest the coarse-grid coupling that ph.x (electron_phonon='interpolated') and the lambda.x post-processing use, so that PAOFLOW’s isotropic Eliashberg engine (PAOFLOW.elphon.eph_kq.eliashberg_from_modes()) can be validated against QE’s lambda.x on the same electron-phonon matrix elements. This isolates the property calculation (a2F / lambda / Tc) from the way the matrix elements are obtained (finite differences of the PAO Hamiltonian in the later phase).

Three files are parsed:

  • lambda.in – the lambda.x driver input: emax, degauss, the smearing method, the irreducible q-points with their weights, the list of per-q elph.inp_lambda.N files and the Coulomb pseudopotential mu*.

  • elph.inp_lambda.N – one per irreducible q-point: the squared phonon frequencies omega^2 (Ry^2) and, for every Gaussian broadening, the DOS at E_F (states / spin / Ry) and the mode-resolved lambda_{q nu} / linewidth gamma_{q nu} (GHz).

  • *.dyn – a QE dynamical-matrix file: diagonalised frequencies (THz) and mode eigenvectors, kept for cross-checks and reuse in the later phase.

All frequencies are returned in THz for direct use by PAOFLOW.elphon.eph_kq.eliashberg_from_modes().

The EPW readers (read_epw_ukk(), read_epw_epb()) load the coarse Bloch-basis coupling that epw.x writes with epbwrite = .true.; read_epw_a2f() reads EPW’s own Eliashberg function for comparison.

Attributes#

Functions#

read_lambda_in(path)

Parse a lambda.x input file.

read_elph_inp_lambda(path)

Parse one elph.inp_lambda.N file (one irreducible q-point).

load_qe_coupling(lambda_in_path[, base_dir])

Load a complete QE coarse-grid coupling data set for the Eliashberg engine.

lambda_from_gamma(gamma_ghz, dos_ry, omega_thz)

Recompute the mode coupling from the QE linewidth (units cross-check).

read_qe_dyn(path)

Parse phonon frequencies and eigenvectors from a QE dynamical-matrix file.

read_qe_el_ph_mat(path)

Read a patched-QE el_ph_mat dump (elphmat.<iq>.dat).

el_ph_mat_to_cartesian(el_ph_mat, u)

Rotate el_ph_mat from the displacement-pattern basis to Cartesian.

read_qe_ahc_gkk(ahc_dir, iq, nbnd, nmodes, nk[, ahc_nbnd])

Read one q of the unpatched QE AHC electron-phonon dump.

read_epw_a2f(path)

Read an EPW <prefix>.a2f file (first phonon smearing).

read_epw_ukk(path, nk)

Read the band bookkeeping of an EPW prefix.ukk file.

read_epw_epb(epw_dir, prefix, nbnd, nk, nat, nbndep)

Read EPW's coarse Bloch-basis electron-phonon matrix elements (epbwrite).

write_epw_ukk(path, nk, nbnd[, ibndkept])

Write a prefix.ukk with identity rotations for read_epw_ukk() (dev / parity tool).

write_epw_epb(epw_dir, prefix, xq_cart, et_ry, dynq, ...)

Write prefix.epb1..N in EPW's epbwrite layout (dev / parity tool).

Module Contents#

PAOFLOW.elphon.qe_elph_io.RY_TO_EV = 13.605693122994[source]#
PAOFLOW.elphon.qe_elph_io.THZ_TO_EV = 0.004135667696[source]#
PAOFLOW.elphon.qe_elph_io.GHZ_TO_EV = 4.135667696e-06[source]#
PAOFLOW.elphon.qe_elph_io.read_lambda_in(path)[source]#

Parse a lambda.x input file.

Parameters:

path (str) – Path to the lambda.in file.

Returns:

{'emax', 'degauss', 'smearing_method', 'qpoints', 'weights', 'elph_files', 'mu_star'}. qpoints is (nq, 3) (fractional reciprocal coordinates), weights is (nq,) (raw, un-normalised), elph_files is the list of elph.inp_lambda.N paths as written in the file.

Return type:

dict

PAOFLOW.elphon.qe_elph_io.read_elph_inp_lambda(path)[source]#

Parse one elph.inp_lambda.N file (one irreducible q-point).

Parameters:

path (str) – Path to an elph.inp_lambda.N file.

Returns:

{'q', 'nsigma', 'nmode', 'omega2_ry', 'omega_thz', 'sigma_ry', 'dos_ry', 'ef_ev', 'lambda_qv', 'gamma_ghz'}. omega_thz is (nmode,) (signed THz); lambda_qv and gamma_ghz are (nsigma, nmode); dos_ry / ef_ev / sigma_ry are (nsigma,) (DOS in states / spin / Ry).

Return type:

dict

PAOFLOW.elphon.qe_elph_io.load_qe_coupling(lambda_in_path, base_dir=None)[source]#

Load a complete QE coarse-grid coupling data set for the Eliashberg engine.

Reads lambda.in and every referenced elph.inp_lambda.N file and packs the mode-resolved coupling into arrays indexed by (sigma, q, mode).

Parameters:
  • lambda_in_path (str) – Path to the lambda.x input file.

  • base_dir (str, optional) – Directory the elph.inp_lambda.N paths are relative to (default: the directory of lambda_in_path).

Returns:

{'qpoints', 'weights', 'mu_star', 'sigma_ry', 'omega_thz', 'lambda_qv', 'gamma_ghz', 'dos_ry', 'ef_ev', 'nq', 'nsigma', 'nmode'}. omega_thz is (nq, nmode); lambda_qv / gamma_ghz are (nsigma, nq, nmode); dos_ry / ef_ev are (nsigma, nq); weights are the raw per-q weights from lambda.in.

Return type:

dict

PAOFLOW.elphon.qe_elph_io.lambda_from_gamma(gamma_ghz, dos_ry, omega_thz)[source]#

Recompute the mode coupling from the QE linewidth (units cross-check).

QE defines the isotropic mode coupling as

\[\lambda_{q\nu} = \frac{\gamma_{q\nu}} {\pi\, N(E_F)\, \omega_{q\nu}^2},\]

with the linewidth gamma and frequency omega in the same energy units and N(E_F) the DOS per spin. This helper reproduces lambda_{q nu} from the tabulated gamma (GHz) and N(E_F) (states / spin / Ry), so a comparison with the lambda(nu) values printed by QE validates the unit conventions used here.

Parameters:
  • gamma_ghz (array_like) – Linewidths in GHz (any shape).

  • dos_ry (array_like) – DOS at E_F in states / spin / Ry, broadcastable to gamma_ghz.

  • omega_thz (array_like) – Phonon frequencies in THz, broadcastable to gamma_ghz.

Returns:

lambda_{q nu} (dimensionless); zero where omega is non-positive.

Return type:

ndarray

PAOFLOW.elphon.qe_elph_io.read_qe_dyn(path)[source]#

Parse phonon frequencies and eigenvectors from a QE dynamical-matrix file.

Kept for cross-checking the elph.inp_lambda frequencies and for reuse in the finite-difference phase (mode eigenvectors at the coarse q-points).

Parameters:

path (str) – Path to a QE *.dyn file (matrix + diagonalisation block).

Returns:

{'q', 'freq_thz', 'eigenvectors'} for the (first) diagonalised q-point in the file. freq_thz is (nmode,); eigenvectors is (nmode, natom, 3) complex (None if the file has no diagonalisation block).

Return type:

dict

PAOFLOW.elphon.qe_elph_io.read_qe_el_ph_mat(path)[source]#

Read a patched-QE el_ph_mat dump (elphmat.<iq>.dat).

The dump is written by the PAOFLOW-patched PHonon/PH/elphon.f90 (elphsum) and stores QE’s full DFPT electron-phonon matrix elements on the coarse k-grid for one (irreducible) q – i.e. the complete bare-local + bare-nonlocal + induced coupling (including any NLCC / ultrasoft augmentation) that ph.x computes internally. This is the input for the pseudo-atomic-orbital (Agapito & Bernardi, Phys. Rev. B 97, 235146 (2018)) interpolation route, which needs no potential reconstruction.

Parameters:

path (str) – Path to elphmat.<iq>.dat (Fortran unformatted).

Returns:

{'nbnd', 'nksq', 'nat', 'nkstot', 'el_ph_mat', 'u', 'xq', 'xk', 'et'}. el_ph_mat is (nbnd, nbnd, nksq, 3*nat) in the displacement-pattern basis (rotate to Cartesian with el_ph_mat_to_cartesian() using u); xk is (nksq, 3) (the k-points, cartesian in tpiba) and et is (nksq, nbnd) band energies (Ry) at those k. For a lgamma (q=0) run the stored k and k+q lists coincide; otherwise the k sublist is extracted from the interleaved (k, k+q) dump.

Return type:

dict

PAOFLOW.elphon.qe_elph_io.el_ph_mat_to_cartesian(el_ph_mat, u)[source]#

Rotate el_ph_mat from the displacement-pattern basis to Cartesian.

d^{cart}_{mn,c}(k) = sum_p conj(u_{c,p})\, el_ph_mat_{mn,p}(k) with the canonical QE pattern matrix u returned by read_qe_el_ph_mat().

Parameters:
  • el_ph_mat (ndarray (nbnd, nbnd, nksq, 3*nat)) – Pattern-basis matrix elements.

  • u (ndarray (3*nat, 3*nat)) – QE canonical displacement-pattern matrix.

Returns:

Cartesian deformation potentials d_{mn,c}(k).

Return type:

ndarray (nbnd, nbnd, nksq, 3*nat)

PAOFLOW.elphon.qe_elph_io.read_qe_ahc_gkk(ahc_dir, iq, nbnd, nmodes, nk, ahc_nbnd=None)[source]#

Read one q of the unpatched QE AHC electron-phonon dump.

Standard QE electron_phonon='ahc' (Lihm & Park; PHonon/PH/ahc.f90) writes, per q, the full DFPT coupling

ahc_gkk(ib, jb, imode) = <psi_{ib}(k+q)| dV/du_{q,imode} |psi_{jb}(k)>

– identical to el_ph_mat (bare local + bare nonlocal + induced) – but already in the Cartesian displacement basis (imode = 3(iat-1)+idir), so no pattern rotation is needed. This is the recommended, patch-free input for the PAO route on norm-conserving pseudopotentials (AHC is not implemented for USPP / PAW / DFPT+U / magnetism – use read_qe_el_ph_mat() there).

The files are plain Fortran direct-access binaries in ahc_dir:

  • ahc_gkk_iq<iq>.bin – complex (nbnd, ahc_nbnd, nmodes, nk) (F order);

  • ahc_etk_iq<iq>.bin – real (nbnd, nk) band energies at k (Ry);

  • ahc_etq_iq<iq>.bin – real (nbnd, nk) band energies at k+q (Ry).

The k-record order is the ph.x (nscf) k-order, i.e. the same order as read_nscf() kpts_cryst and the PAOFLOW projections A_k for the same lead.save.

Parameters:
  • ahc_dir (str) – Directory containing the ahc_*_iq<iq>.bin files.

  • iq (int) – 1-based q index (matches <prefix>.dyn<iq>).

  • nbnd (int) – Number of bands in the AHC run (the k+q index range).

  • nmodes (int) – Number of phonon modes (3*nat).

  • nk (int) – Number of k-points (nk1*nk2*nk3).

  • ahc_nbnd (int, optional) – Number of k-side bands stored (jb range). Defaults to nbnd (the recommended full-band setting ahc_nbnd=nbnd, ahc_nbndskip=0).

Returns:

{'el_cart', 'etk', 'etq', 'nbnd', 'ahc_nbnd', 'nmodes', 'nk'}. el_cart is (nbnd, ahc_nbnd, nk, nmodes) – Cartesian deformation potentials d_{mn,c}(k) (m = k+q band, n = k band); etk and etq are (nk, nbnd) band energies (Ry) at k and k+q.

Return type:

dict

PAOFLOW.elphon.qe_elph_io.read_epw_a2f(path)[source]#

Read an EPW <prefix>.a2f file (first phonon smearing).

The data block has omega (meV) followed by one a2F column per smearing, or (isotropic Eliashberg runs) omega, a2F, lambda(omega). Header and footer lines (integrated couplings, smearing list) are skipped: only numeric rows with the most frequent column count are kept.

Returns:

omega_mev, a2f, lam_cum – Frequencies (meV), a2F and the cumulative lambda(omega) = 2 int_0^omega a2F/w dw (read from the file when it has three columns).

Return type:

ndarray

PAOFLOW.elphon.qe_elph_io.read_epw_ukk(path, nk)[source]#

Read the band bookkeeping of an EPW prefix.ukk file.

Parameters:
  • path (str) – Path to prefix.ukk (formatted, written by EPW write_filukk).

  • nk (int) – Number of coarse k-points (the nscf grid).

Returns:

nbndep (int), nbndskip (int), ibndkept ((nbndep,) int, 0-based nscf band index of each band kept in the e-ph calculation), u ((nk, nbndep, nwann) complex Wannier rotations), lwin ((nk, nbndep) bool, outer disentanglement window), exband ((nbnd,) bool, bands excluded via bands_skipped), nbnd and nwann.

Return type:

dict

Raises:

ValueError – If the file is inconsistent with nk.

PAOFLOW.elphon.qe_elph_io.read_epw_epb(epw_dir, prefix, nbnd, nk, nat, nbndep)[source]#

Read EPW’s coarse Bloch-basis electron-phonon matrix elements (epbwrite).

epw.x with epbwrite = .true. writes one file per pool, prefix.epb1 ... prefix.epbN, each holding a single unformatted record nqc, xqc, et, dynq, epmatq, zstar, epsi for that pool’s block of k-points. The blocks are concatenated here in nscf k order.

Parameters:
  • epw_dir (str) – Directory with the prefix.epb* files (EPW outdir).

  • prefix (str) – Calculation prefix.

  • nbnd (int) – Number of bands in the nscf run.

  • nk (int) – Number of coarse k-points (full grid of the nscf run).

  • nat (int) – Number of atoms.

  • nbndep (int) – Number of bands kept in the e-ph calculation (nbnd minus exclude_bands), e.g. read_epw_ukk() ['nbndep'].

Returns:

xq_cart : (nq, 3) coarse q-points, Cartesian, 2 pi/alat (EPW star order, the full coarse grid). et_ry : (nk, nbnd) band energies (Ry, all bands, absolute). dynq : (3 nat, 3 nat, nq) complex force-constant matrices (Ry/bohr^2, not divided by the masses, acoustic sum rule applied). epmatq : (nbndep, nbndep, nk, 3 nat, nq) complex, <psi_{m,k+q}| dV/du_{c}(q) |psi_{n,k}> (Ry/bohr) in the Cartesian displacement basis c = 3 * atom + direction. zstar : (nat, 3, 3) Born charges; epsi : (3, 3).

Return type:

dict

Raises:

Notes

k-points are distributed over pools as in Quantum ESPRESSO: the first nk mod npool pools hold one extra k-point. Both psi_{k+q} and psi_k are the nscf wavefunctions of the save directory, so the matrix elements share the band gauge of PAO projections computed on that save.

PAOFLOW.elphon.qe_elph_io.write_epw_ukk(path, nk, nbnd, ibndkept=None)[source]#

Write a prefix.ukk with identity rotations for read_epw_ukk() (dev / parity tool).

Parameters:
  • path (str)

  • nk (int) – Number of coarse k-points.

  • nbnd (int) – Bands of the nscf run.

  • ibndkept (ndarray of int, optional) – 0-based bands kept (default: all). Only a contiguous block starting at the lowest kept band is representable (EPW exclude_bands = 1:nbndskip).

PAOFLOW.elphon.qe_elph_io.write_epw_epb(epw_dir, prefix, xq_cart, et_ry, dynq, epmatq, zstar, epsi, npool=1)[source]#

Write prefix.epb1..N in EPW’s epbwrite layout (dev / parity tool).

Parameters:
  • epw_dir (str)

  • prefix (str)

  • xq_cart (ndarray (nq, 3)) – Coarse q-points (Cartesian, 2 pi / alat).

  • et_ry (ndarray (nk, nbnd)) – Band energies (Ry).

  • dynq (ndarray (3 nat, 3 nat, nq))

  • epmatq (ndarray (nbndep, nbndep, nk, 3 nat, nq)) – Matrix elements as returned by read_epw_epb().

  • zstar (ndarray (nat, 3, 3))

  • epsi (ndarray (3, 3))

  • npool (int, optional) – Number of pool files; the k-points are split as QE does.

Returns:

The files written. Records above 2 GiB are split into gfortran subrecords.

Return type:

list of str