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().

Attributes#

`RY_TO_EV`
`THZ_TO_EV`
`GHZ_TO_EV`

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.

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