Output File Formats

This document describes the format of the output NetCDF files generated by the LetzElPhC code: ndb.elph and ndb.Dmats.

`ndb.elph`

The ndb.elph file contains the electron-phonon matrix elements, phonon frequencies, polarization vectors, and required lattice and phonon information.

The electron–phonon matrix elements for phonon absorption are defined as

\[g_{nm}^\nu(\mathbf{k},\mathbf{q})=\langle n, \mathbf{k}+\mathbf{q} \,|\, \partial_{\mathbf{q}\nu} V_{\text{scf}} \,|\, m, \mathbf{k} \rangle,\]

where \(\nu\) is the phonon mode index, \(\mathbf{k}\) is the crystal momentum of the initial electronic state with band index \(m\), and \(\mathbf{k}+\mathbf{q}\) is the crystal momentum of the final electronic state with band index \(n\). Here, \(\mathbf{q}\) denotes the phonon wavevector.

Normalization convention

In this definition of the electron–phonon matrix elements, the prefactor \(\frac{1}{\sqrt{2\omega_{\mathbf{q}}^{\nu}}}\) is not included. The code outputs unnormalized electron–phonon matrix elements according to the definition above.

Dimensions and Coordinates

Dimension Name	Description
`nq`	Number of q-points in the full Brillouin Zone.
`nk`	Number of k-points in the full Brillouin Zone.
`nmodes`	Number of phonon modes.
`nspin`	Number of spin components.
`initial_band`	Number of initial electronic bands.
`final_band_PH_abs`	Number of final electronic bands.
`atom`	Number of atoms in the unit cell.
`pol`	Polarization direction (3 for x, y, z).
`re_im`	Complex number components (2: Real, Imaginary).
`Nx`, `Ny`, `Nz`	FFT grid dimensions.
`nsym_ph`	Number of phonon symmetries.
`dim_two`	Dimension of size 2 (used for maps).

Variables

Electron-Phonon Matrix Elements

Variable Name	Type	Dimensions	Description
`elph_mat`	float	`[nq, nk, nmodes, nspin, initial_band, final_band_PH_abs, re_im]`	Electron–phonon matrix elements \(g_{nm\nu}\) (in units the of \(\mathrm{Ry}^{3/2}\)). Here, \(m\) labels the initial electronic band (corresponding to the `initial_band` dimension), while \(n\) labels the final electronic band (corresponding to the `final_band_PH_abs` dimension).

Convention

Convention: If the electron-phonon calculation is done with convention=

standard: the code stores \( g_{nm}^\nu(\mathbf{k}, \mathbf{q}) \) in the elph_mat variable
yambo: the code stores \( g_{nm}^\nu(\mathbf{k}-\mathbf{q}, \mathbf{q}) \) in the elph_mat variable

Phonon Data

Variable Name	Type	Dimensions	Description
`FREQ`	float	`[nq, nmodes]`	Phonon frequencies (in Ry).
`POLARIZATION_VECTORS`	float	`[nq, nmodes, atom, pol, re_im]`	Phonon polarization (displacement) vectors, which are defined as \(u_{\kappa \alpha}^{\nu} = \frac{1}{\sqrt{M_{\kappa}}} e_{\kappa \alpha}^{\nu},\) where \(e_{\kappa \alpha}^{\nu}\) is the eigenvector of the dynamical matrix corresponding to phonon mode \(\nu\), \(\kappa\) labels the atom in the unit cell, \(\alpha\) denotes the Cartesian direction, and \(M_{\kappa}\) is the mass of atom \(\kappa\).

System Info & Symmetries

Variable Name	Type	Dimensions	Description
`kpoints`	float	`[nk, pol]`	k-points in crystal coordinates in full BZ (electron wavevectors).
`qpoints`	float	`[nq, pol]`	q-points in crystal coordinates in full BZ (phonon wavevectors).
`qpoints_iBZ`	float	`[nq_iBZ, pol]`	q-points in crystal coordinates (for phonons) in irreducible BZ.
`qmap`	int	`[nq, dim_two]`	Mapping from full Brillouin zone (BZ) q-points to the irreducible BZ (iBZ): for each full-BZ q-point `iq`, the mapping `iq_iBZ, isym = qmap[iq]` returns the index of the corresponding iBZ q-point and the symmetry index, such that \(\mathbf{q}_{iq}^{\mathrm{cart}} = \mathrm{symmetry\_matrices}[isym] @ \mathbf{q}_{iq\_iBZ}^{\mathrm{cart}}\), i.e., it specifies which iBZ q-point and phonon symmetry operation reconstruct the full-BZ q-point.
`kmap`	int	`[nk, dim_two]`	Mapping from full Brillouin zone (BZ) k-points to the irreducible BZ (iBZ): for each full-BZ k-point `ik`, the mapping `ik_iBZ, isym = kmap[ik]` returns the index of the corresponding iBZ k-point and the symmetry index, such that \(\mathbf{k}_{ik}^{\mathrm{cart}} = \mathrm{symmetry\_matrices}_{\mathrm{Yambo}}[isym] @ \mathbf{k}_{ik\_iBZ}^{\mathrm{cart}}\). In other words, it specifies which iBZ k-point and symmetry operation reconstruct the full-BZ k-point. Unlike `qmap`, the \(\mathrm{symmetry\_matrices}_{\mathrm{Yambo}}\) correspond to the electronic symmetries (i.e., the symmetries stored in the Yambo SAVE database).
`bands`	int	`[2]`	Start and end band indices used in the calculation.
`number_of_phonon_symmetries`	int	scalar	Number of symmetries used in the phonon calculation.
`time_reversal_phonon`	int	scalar	Flag indicating if time-reversal symmetry is present in the list of phonon symmetries `(1/0)`.
`symmetry_matrices`	float	`[nsym_ph, pol, pol]`	Rotation matrices in cartesian coordinates for symmetries used in phonons calculations.
`fractional_translation`	float	`[nsym_ph, pol]`	Fractional translation vectors in cartesian coordinates for symmetries used in phonons calculations.
`kernel`	char	string	Type of kernel used (e.g., `bare`, `dfpt`).
`convention`	char	string	Convention used (`standard` or `yambo`).

Additional info on Symmetries

Note that the number of symmetries stored in the Yambo SAVE database and the number of phonon symmetries may differ. This can occur because the NSCF calculation may be performed with some or all symmetries disabled, whereas the phonon calculation is typically carried out using the full symmetries.

Tensors

Variable Name	Type	Dimensions	Description
`epsilon`	float	`[pol, pol]`	Dielectric tensor.
`Born_charges`	float	`[natoms, pol, pol]`	Born effective charges. `(atom, efield, atom_direction)`
`Quadrupole_tensor`	float	`[natoms, pol, pol, pol]`	Quadrupole tensor `(atom, efield, qgrad, atom_direction)`.

Additional info on tensors

If the LetzElPhC code detects the files tensors.xml and quadrupole.fmt in the ph_save directory, their contents are read and stored in the corresponding variables. If these files are not present, the associated variables are set to zero.

Reading ndb.elph with YamboPy

The electron-phonon matrix elements, phonon polarization vectors and frequencies stored in the ndb.elph database can be accessed with YamboPy using the LetzElphElectronPhononDB class:

from yambopy import LetzElphElectronPhononDB
lelph_obj = LetzElphElectronPhononDB('ndb.elph')

`ndb.Dmats`

The ndb.Dmats file stores the representation matrices for electronic states under phonon symmetries. The \(\mathcal{D}\) matrices are defined as

\[ \mathcal{D}_{\mathbf{k}, mn}(g) = \langle R\mathbf{k} m \mid \hat{U}(g) \mid \mathbf{k} n \rangle, \]

where \(\hat{U}(g)\) is the unitary operator associated with the symmetry operation \(g:\,\mathbf{x} \rightarrow R\mathbf{x} + \boldsymbol{\tau}\). It should be noted that the above expression is fully general and applies to all systems, including non-collinear (fully spinorial) cases. For nspin = 2, the spin-up and spin-down channels are decoupled in the Kohn–Sham equations; in this case, the spin index is added.

\[ \mathcal{D}_{\mathbf{k}, s, mn}(g) = \langle R\mathbf{k}, s, m \mid \hat{U}(g) \mid \mathbf{k}, s, n \rangle, \]

where \(s\) denotes the spin index (spin up or spin down).

Dimensions

Dimension Name	Description
`nsym_ph`	Number of phonon symmetries.
`nkpts`	Number of k-points in the full Brillouin Zone.
`nspin`	Number of spin components.
`Rk_band`	Number of bands at the rotated k-point (\(Rk\)).
`k_band`	Number of bands at the original k-point (\(k\)).
`re_im`	Complex number components (2: Real, Imaginary).

Variables

Variable Name	Type	Dimensions	Description
`Dmats`	float	`[nsym_ph, nkpts, nspin, Rk_band, k_band, re_im]`	Electronic representation matrices \(\mathcal{D}_{\mathbf{k},s, mn}(g)\) for each phonon symmetry operation \(g\), where \(m\) corresponds to the `Rk_band` dimension and \(n\) corresponds to the `k_band` dimension.