PAOFLOW.elphon.phonon_assisted_absorption#

Phonon-assisted (indirect) optical absorption from the PAO electron-phonon route.

Second-order (photon + phonon) absorption of an indirect-gap semiconductor, following EPW’s lindabs (indabs.f90; Noffsinger et al., Phys. Rev. Lett. 108, 167402 (2012)), with every ingredient interpolated in the PAO basis:

The direct (vertical) absorption of EPW’s dirabs is computed alongside, on the same velocities. All quantities are in Rydberg atomic units internally; the public driver takes and returns electron-volts.

Attributes#

Functions#

fermi_occupation(energy, temperature)

Fermi-Dirac occupation 1 / (1 + exp(e / T)) (EPW wgauss(-e/T, -99)).

bose_occupation(energy, temperature)

Bose-Einstein occupation 1 / (exp(w / T) - 1) for positive energy.

gaussian_delta(x, sigma)

Normalised Gaussian exp(-(x/sigma)^2) / (sigma sqrt(pi)) (EPW w0gauss).

lorentzian_delta(x, sigma)

Normalised Lorentzian (sigma / pi) / (sigma^2 + x^2).

indirect_absorption_kernel(energy_k, energy_kq, ...[, ...])

Phonon-assisted Im eps(omega) from one block of (k, k+q) pairs at one q.

direct_absorption_kernel(energy_k, velocity_k, ...[, ...])

Direct (vertical) Im eps(omega) from one block of k-points (EPW dirabs).

intrinsic_fermi_levels(energies, temperatures, nelec)

Charge-neutral (intrinsic) Fermi level at each temperature.

varshni_gap(e0_ev[, alpha_ev_per_k, beta_k])

Temperature-dependent band gap of the Varshni form.

varshni_shift([alpha_ev_per_k, beta_k])

Varshni temperature dependence as a rigid shift of a Hamiltonian's own gap.

scissor_per_temperature(temps_k, dft_gap_ev[, ...])

Rigid conduction-band shift at each temperature.

scissor_velocities(velocity, energies, scissor, conduction)

Velocity matrix elements of the scissor-corrected Hamiltonian.

scissor_shift_dielectric(omega_ev, eps1, eps2, scissor_ev)

Apply a scissor to an independent-particle dielectric function.

pao_band_gaps(HRs, at, nk_dense, nelec[, ...])

Indirect and direct gaps of a PAO Hamiltonian on a dense k-grid.

absorption_coefficient(photon_energy_ev, eps2[, ...])

Absorption coefficient alpha = omega Im eps / (n_r c) in cm^-1.

phonon_assisted_absorption_dense_q(A, HRs, kpts_cryst, ...)

Phonon-assisted and direct optical absorption with dense k and q interpolation.

thermal_emissivity(results, thickness_m[, angles_deg, ...])

Spectral and total hemispherical emissivity of a slab at each temperature.

direct_scissor_shifts(results[, direct_scissor, scissors])

Shift (eV) of an external direct dielectric function at each temperature.

dielectric_onset_ev(omega_ev, eps2[, fraction])

Onset of an absorption spectrum: lowest energy where eps2 reaches a fraction of its maximum.

check_direct_dielectric_gap(results, direct_dielectric)

Warn when an external direct dielectric function does not match the Hamiltonian's direct gap.

external_refractive_index(direct_dielectric)

Real refractive index of a dielectric function, (omega_ev, n).

read_direct_dielectric(outdir[, components])

Read the diagonal dielectric function written by PAOFLOW's dielectric_tensor.

write_emissivity_outputs(emissivity, outdir)

Write the thermal-emissivity spectra and totals.

write_absorption_outputs(results, outdir)

Write the absorption spectra in EPW's file layout plus an .npz archive.

Module Contents#

PAOFLOW.elphon.phonon_assisted_absorption.EPW_ETAS_EV = (0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5)[source]#
PAOFLOW.elphon.phonon_assisted_absorption.KELVIN_TO_EV = 8.617333262e-05[source]#
PAOFLOW.elphon.phonon_assisted_absorption.EV_TO_CM1 = 8065.543937[source]#
PAOFLOW.elphon.phonon_assisted_absorption.HBAR_C_EV_CM = 1.973269804e-05[source]#
PAOFLOW.elphon.phonon_assisted_absorption.DELTA_CUTOFF = 6.0[source]#
PAOFLOW.elphon.phonon_assisted_absorption.fermi_occupation(energy, temperature)[source]#

Fermi-Dirac occupation 1 / (1 + exp(e / T)) (EPW wgauss(-e/T, -99)).

Parameters:
  • energy (ndarray) – Energies relative to the Fermi level (same units as temperature).

  • temperature (float) – k_B T; 0 gives a step function.

Returns:

Occupations, same shape as energy.

Return type:

ndarray

PAOFLOW.elphon.phonon_assisted_absorption.bose_occupation(energy, temperature)[source]#

Bose-Einstein occupation 1 / (exp(w / T) - 1) for positive energy.

Parameters:
  • energy (ndarray) – Phonon energies (same units as temperature), positive.

  • temperature (float) – k_B T; 0 gives zero occupation.

Returns:

Occupations, same shape as energy.

Return type:

ndarray

PAOFLOW.elphon.phonon_assisted_absorption.gaussian_delta(x, sigma)[source]#

Normalised Gaussian exp(-(x/sigma)^2) / (sigma sqrt(pi)) (EPW w0gauss).

PAOFLOW.elphon.phonon_assisted_absorption.lorentzian_delta(x, sigma)[source]#

Normalised Lorentzian (sigma / pi) / (sigma^2 + x^2).

PAOFLOW.elphon.phonon_assisted_absorption.indirect_absorption_kernel(energy_k, energy_kq, velocity_k, velocity_kq, coupling, phonon_energy, temperatures, photon_energy, etas, degauss, fsthick, eps_acoustic, weight=1.0, spin_degeneracy=2.0, occupation_tol=1e-12, pair_block=2048, fermi_levels=None)[source]#

Phonon-assisted Im eps(omega) from one block of (k, k+q) pairs at one q.

Parameters:
  • energy_k (ndarray, shape (nk, nband)) – Band energies at k and k+q relative to the Fermi level (Ry).

  • energy_kq (ndarray, shape (nk, nband)) – Band energies at k and k+q relative to the Fermi level (Ry).

  • velocity_k (ndarray, shape (nk, 3, nband, nband), complex) – Velocity matrix elements <m|v_alpha|n> at k and k+q (Ry bohr), in the gauge of coupling.

  • velocity_kq (ndarray, shape (nk, 3, nband, nband), complex) – Velocity matrix elements <m|v_alpha|n> at k and k+q (Ry bohr), in the gauge of coupling.

  • coupling (ndarray, shape (nk, nmode, nband, nband), complex) – g_{mn,nu} = <m, k+q|dV_{q nu}|n, k> without \(1/\sqrt{2\omega}\) (Rydberg units; band_vertex()).

  • phonon_energy (ndarray, shape (nmode,)) – Phonon energies at q (Ry); modes below eps_acoustic are skipped.

  • temperatures (sequence of float) – k_B T values (Ry).

  • photon_energy (ndarray, shape (nomega,)) – Photon energies (Ry), positive.

  • etas (sequence of float) – Imaginary broadenings of the intermediate-state denominators (Ry).

  • degauss (float or ndarray, shape (nk, nband, nband)) – Smearing of the energy-conserving delta (Ry): one value, or one per (k, i, j) pair (adaptive smearing, pair_widths()).

  • fsthick (float) – Only states with |e| < fsthick enter as initial or final states (Ry).

  • eps_acoustic (float) – Phonon-energy threshold (Ry).

  • weight (float, optional) – Multiplies the block sum, e.g. w_q / (N_k Omega).

  • spin_degeneracy (float, optional) – 2 without spin-orbit coupling (EPW’s 16 pi^2 prefactor), 1 with it.

  • occupation_tol (float, optional) – Pairs whose occupation factors f_i (1 - f_j) + (1 - f_i) f_j stay below this at every temperature are skipped (0 keeps all, as EPW).

  • pair_block (int, optional) – Number of (k, i, j) pairs processed at once (memory control).

  • fermi_levels (sequence of float, optional) – Fermi level of each temperature (Ry) on the energy scale of energy_k, which only sets the occupations (default 0 for all; the fsthick window stays centred on 0).

Returns:

eps2_gaussian, eps2_lorentzian – Diagonal components of Im eps with a Gaussian and a Lorentzian delta.

Return type:

ndarray, shape (ntemp, neta, 3, nomega)

Notes

For an initial state \(i\) at \(\mathbf{k}\), a final state \(j\) at \(\mathbf{k}+\mathbf{q}\) and a phonon \(\nu\), the two time orderings (photon first, phonon first) give the amplitudes

\[S^{a/e}_{1,\alpha} = \sum_m \frac{g_{jm,\nu}\, v^{\alpha}_{mi}(\mathbf{k})} {\varepsilon_{m\mathbf{k}} - \varepsilon_{j\mathbf{k}+\mathbf{q}} \pm \omega_{\mathbf{q}\nu} + i\eta}, \qquad S^{a/e}_{2,\alpha} = \sum_m \frac{v^{\alpha}_{jm}(\mathbf{k}+\mathbf{q})\, g_{mi,\nu}} {\varepsilon_{m\mathbf{k}+\mathbf{q}} - \varepsilon_{i\mathbf{k}} \mp \omega_{\mathbf{q}\nu} + i\eta},\]

for phonon absorption (\(a\), upper signs) and emission (\(e\)), and

\[\mathrm{Im}\,\varepsilon_{\alpha\alpha}(\omega) \mathrel{+}= w\, \frac{8\pi^2 g_s}{\omega^2} \sum_{ij\nu} P^{a/e}\, \frac{|S^{a/e}_{1,\alpha} + S^{a/e}_{2,\alpha}|^2}{2\omega_{\mathbf{q}\nu}}\, \delta(\varepsilon_{j\mathbf{k}+\mathbf{q}} - \varepsilon_{i\mathbf{k}} - \omega \mp \omega_{\mathbf{q}\nu}),\]

with \(P^a = n f_i (1 - f_j) - (n + 1)(1 - f_i) f_j\) and \(P^e = (n + 1) f_i (1 - f_j) - n (1 - f_i) f_j\) (\(n\) Bose, \(f\) Fermi occupations). \(8\pi^2 g_s = 8\pi^2 e^2\) in Rydberg units for \(g_s = 2\), EPW’s cfac. As in EPW, a (pair, mode, omega) term is kept when either delta lies within six smearings, and the intermediate states \(m\) run over the bands of the window.

PAOFLOW.elphon.phonon_assisted_absorption.direct_absorption_kernel(energy_k, velocity_k, temperatures, photon_energy, degauss, fsthick, weight=1.0, spin_degeneracy=2.0, fermi_levels=None, pair_block=2048)[source]#

Direct (vertical) Im eps(omega) from one block of k-points (EPW dirabs).

Parameters:
  • energy_k (ndarray, shape (nk, nband)) – Band energies relative to the Fermi level (Ry).

  • velocity_k (ndarray, shape (nk, 3, nband, nband), complex) – Velocity matrix elements (Ry bohr).

  • temperatures (sequence of float) – k_B T values (Ry).

  • photon_energy (ndarray, shape (nomega,)) – Photon energies (Ry).

  • degauss (float or ndarray, shape (nk, nband, nband)) – Smearing of the delta (Ry): one value, or one per (k, i, j) pair (adaptive smearing, pair_widths() with a zero q spacing). Smearing of the energy-conserving delta (Ry).

  • fsthick (float) – Energy window around the Fermi level (Ry).

  • weight (float, optional) – Multiplies the block sum, e.g. 1 / (N_k Omega).

  • spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.

  • fermi_levels (sequence of float, optional) – Fermi level of each temperature (Ry), as in indirect_absorption_kernel().

  • pair_block (int, optional) – Transitions per batch: the delta functions are (pair_block, nomega) arrays, which bounds the memory of wide photon grids and many bands.

Returns:

eps2_gaussian, eps2_lorentzian

Return type:

ndarray, shape (ntemp, 3, nomega)

Notes

\[\mathrm{Im}\,\varepsilon_{\alpha\alpha}(\omega) \mathrel{+}= w\, \frac{8\pi^2 g_s}{\omega^2} \sum_{ij} (f_i - f_j)\, |v^{\alpha}_{ji}|^2\, \delta(\varepsilon_j - \varepsilon_i - \omega),\]

keeping a term when the delta lies within six smearings, as EPW.

PAOFLOW.elphon.phonon_assisted_absorption.intrinsic_fermi_levels(energies, temperatures, nelec, spin_degeneracy=2.0, niter=200)[source]#

Charge-neutral (intrinsic) Fermi level at each temperature.

Parameters:
  • energies (ndarray, shape (nk, nband)) – Band energies of all bands on a uniform k-grid (any energy unit).

  • temperatures (sequence of float) – k_B T values, same unit as energies (positive).

  • nelec (float) – Valence electrons per cell.

  • spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.

  • niter (int, optional) – Bisection steps.

Returns:

Fermi levels \(\mu(T)\) on the scale of energies.

Return type:

ndarray, shape (ntemp,)

Notes

Solves the charge neutrality

\[\frac{g_s}{N_k} \sum_{n\mathbf{k}} f\left(\frac{\varepsilon_{n\mathbf{k}} - \mu}{k_B T}\right) = N_{el}\]

by bisection, so the thermally excited electrons and holes balance; in a semiconductor \(\mu(T)\) moves from mid-gap toward the band with the smaller density of states.

PAOFLOW.elphon.phonon_assisted_absorption.SILICON_VARSHNI = (1.17, 0.000473, 636.0)[source]#
PAOFLOW.elphon.phonon_assisted_absorption.varshni_gap(e0_ev, alpha_ev_per_k=0.000473, beta_k=636.0)[source]#

Temperature-dependent band gap of the Varshni form.

Parameters:
  • e0_ev (float) – Gap at 0 K (eV), e.g. the experimental value or an eACBN0 gap.

  • alpha_ev_per_k (float, optional) – Varshni parameters (defaults: silicon, Varshni, Physica 34, 149 (1967)).

  • beta_k (float, optional) – Varshni parameters (defaults: silicon, Varshni, Physica 34, 149 (1967)).

Returns:

T (K) -> E_g(T) in eV, the target_gap_ev of phonon_assisted_absorption_dense_q().

Return type:

callable

Notes

\[E_g(T) = E_0 - \frac{\alpha T^2}{T + \beta}.\]
PAOFLOW.elphon.phonon_assisted_absorption.varshni_shift(alpha_ev_per_k=SILICON_VARSHNI[1], beta_k=SILICON_VARSHNI[2])[source]#

Varshni temperature dependence as a rigid shift of a Hamiltonian’s own gap.

Parameters:
  • alpha_ev_per_k (float, optional) – Varshni alpha (eV/K); default Si.

  • beta_k (float, optional) – Varshni beta (K); default Si.

Returns:

T (K) -> Delta(T) in eV, the scissor_ev of phonon_assisted_absorption_dense_q() and carrier_scattering_dense_q().

Return type:

callable

Notes

\[\Delta(T) = -\frac{\alpha T^2}{T + \beta}, \qquad \Delta(0) = 0,\]

i.e. varshni_gap() with \(E_0 = 0\). Use it when the Hamiltonian already has the 0 K gap (an eACBN0 PAO Hamiltonian): the band energies then follow \(E_g^{H} + \Delta(T)\) without a 0 K scissor.

PAOFLOW.elphon.phonon_assisted_absorption.scissor_per_temperature(temps_k, dft_gap_ev, scissor_ev=None, target_gap_ev=None)[source]#

Rigid conduction-band shift at each temperature.

Parameters:
  • temps_k (sequence of float) – Temperatures (K).

  • dft_gap_ev (float) – Indirect gap of the PAO spectrum on the dense grid (eV).

  • scissor_ev (float or callable, optional) – Explicit shift (eV), the same at every temperature, or T (K) -> Delta(T) (varshni_shift()) relative to the Hamiltonian’s own gap.

  • target_gap_ev (float or callable, optional) – Gap to reproduce (eV), fixed or T (K) -> E_g(T) (varshni_gap()).

Returns:

Scissor \(\Delta(T) = E_g^{target}(T) - E_g^{DFT}\) (eV); zeros when neither scissor_ev nor target_gap_ev is given.

Return type:

ndarray, shape (ntemp,)

Raises:

ValueError – If both scissor_ev and target_gap_ev are given.

PAOFLOW.elphon.phonon_assisted_absorption.scissor_velocities(velocity, energies, scissor, conduction, mode='renormalized')[source]#

Velocity matrix elements of the scissor-corrected Hamiltonian.

Parameters:
  • velocity (ndarray, shape (nk, 3, nband, nband), complex) – Kohn-Sham (PAO) band velocities.

  • energies (ndarray, shape (nk, nband)) – Kohn-Sham band energies (same unit as scissor).

  • scissor (float) – Rigid shift of the conduction bands.

  • conduction (ndarray of bool, shape (nband,)) – Conduction-band mask.

  • mode ({'renormalized', 'ks'}, optional) – 'renormalized' (default) applies the Levine-Allan factor below; 'ks' keeps the Kohn-Sham velocities (EPW’s scissor).

Returns:

Velocities to use with the shifted energies.

Return type:

ndarray, shape (nk, 3, nband, nband), complex

Raises:

ValueError – For an unknown mode.

Notes

A scissor operator \(H_\Delta = H + \Delta\, P_c\) (\(P_c\) the conduction projector) leaves the position matrix elements unchanged, so the velocity \(i[H_\Delta, \mathbf r]\) of a valence-conduction pair scales with its transition energy (Levine and Allan, Phys. Rev. Lett. 63, 1719 (1989); Del Sole and Girlanda, Phys. Rev. B 48, 11789 (1993)):

\[v^{\Delta}_{mn} = v_{mn}\, \frac{\varepsilon_m - \varepsilon_n \pm \Delta}{\varepsilon_m - \varepsilon_n},\]

while intraband and within-manifold elements (e.g. the free-carrier velocities) are unchanged. The direct absorption then shifts rigidly.

PAOFLOW.elphon.phonon_assisted_absorption.scissor_shift_dielectric(omega_ev, eps1, eps2, scissor_ev, mode='renormalized', onset_ev=None)[source]#

Apply a scissor to an independent-particle dielectric function.

Parameters:
  • omega_ev (ndarray, shape (nomega,)) – Uniform photon-energy grid (eV).

  • eps1 (ndarray, shape (nomega,)) – Real (vacuum 1 included) and imaginary parts.

  • eps2 (ndarray, shape (nomega,)) – Real (vacuum 1 included) and imaginary parts.

  • scissor_ev (float) – Rigid conduction-band shift (eV).

  • mode ({'renormalized', 'ks'}, optional) – Velocity convention of scissor_velocities().

  • onset_ev (float, optional) – Absorption onset (direct gap) of the unshifted spectrum, used with mode='ks' and a negative scissor (default dielectric_onset_ev() of eps2).

Returns:

eps1, eps2 – Scissor-corrected real and imaginary parts.

Return type:

ndarray, shape (nomega,)

Raises:

ValueError – For an unknown mode, or a negative scissor that closes the direct gap (mode='ks').

Notes

With renormalized velocities the interband spectrum shifts rigidly, \(\varepsilon_2^\Delta(\omega) = \varepsilon_2(\omega - \Delta)\); with Kohn-Sham velocities it is also scaled by \((\omega - \Delta)^2/\omega^2\). The real part changes by the Kramers-Kronig transform of the change of \(\varepsilon_2\) (so the contribution of the spectrum beyond the grid is kept); weight shifted past the end of the grid is dropped.

The Kohn-Sham factor is the ratio of the transition energies before and after the shift, exact for the transitions themselves. Below the onset only the broadening tail of the spectrum remains (Drude-Lorentz delta of dielectric_tensor); for a negative scissor the factor would diverge there as \(\omega \to 0\), so below the shifted onset \(E_{on} + \Delta\) the tail is scaled like the edge transitions that produce it, by \(E_{on}^2/(E_{on} + \Delta)^2\). Positive scissors keep the plain factor (it is bounded).

PAOFLOW.elphon.phonon_assisted_absorption.pao_band_gaps(HRs, at, nk_dense, nelec, orbital_positions=None, spin_degeneracy=2.0, ispin=0)[source]#

Indirect and direct gaps of a PAO Hamiltonian on a dense k-grid.

Parameters:
  • HRs (ndarray, shape (nawf, nawf, n1, n2, n3, nspin), complex) – PAO Hamiltonian (eV), e.g. of an eACBN0 (DFT+U+V, ortho-atomic) run.

  • at (ndarray, shape (3, 3)) – Direct lattice vectors (rows, alat units).

  • nk_dense (int) – Dense grid per axis (Wigner-Seitz interpolation, as the absorption).

  • nelec (float) – Valence electrons.

  • orbital_positions (ndarray, shape (nawf, 3), optional) – PAO orbital centres (pair-resolved Wigner-Seitz sums).

  • spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.

  • ispin (int, optional) – Spin channel.

Returns:

indirect_gap_ev, direct_gap_ev, vbm_ev, cbm_ev (on the energy scale of HRs). The target_gap_ev of a scissor-corrected phonon_assisted_absorption_dense_q() is indirect_gap_ev of the reference Hamiltonian.

Return type:

dict

PAOFLOW.elphon.phonon_assisted_absorption.absorption_coefficient(photon_energy_ev, eps2, refractive_index=3.4)[source]#

Absorption coefficient alpha = omega Im eps / (n_r c) in cm^-1.

Parameters:
  • photon_energy_ev (ndarray, shape (nomega,)) – Photon energies (eV).

  • eps2 (ndarray, shape (..., nomega)) – Imaginary part of the dielectric function.

  • refractive_index (float or ndarray, shape (nomega,), optional) – Real refractive index (default 3.4, the constant of the EPW tutorial for Si).

Returns:

Absorption coefficient (cm^-1).

Return type:

ndarray, shape (..., nomega)

PAOFLOW.elphon.phonon_assisted_absorption.phonon_assisted_absorption_dense_q(A, HRs, kpts_cryst, bg, at, alat, cell_volume, coupling_dir, qgrid_coarse, ng, *, masses_amu, nelec, nk_dense=12, nq_dense=6, omega_ev=(0.05, 3.0, 0.05), temps_k=(300.0,), degauss_ev=0.05, adaptive_smearing=None, min_degauss_ev=0.001, fsthick_ev=4.0, fermi_energy_ev=None, etas_ev=EPW_ETAS_EV, eps_acoustic_cm=0.1, refractive_index=3.4, nonlocal_velocity=None, position_dipoles=None, position_dipole_level='full', kk_omega_max_ev=None, kk_degauss_ev=0.1, scissor_ev=None, target_gap_ev=None, scissor_velocity='renormalized', screening_eps=None, screening_eps_dft=None, spin_degeneracy=2.0, sym_rots=None, tau_cryst=None, species=None, orbital_positions=None, ispin=0, kblock=512, comm=None, allow_missing_long_range=False, coupling_source='epw', save_dir=None, pseudo_dir=None, prefix=None, basis='auto', unfold='full', basis_shells=None, unfold_tol=1e-06, cache_dir=None, cache_tag=None, long_range=None)[source]#

Phonon-assisted and direct optical absorption with dense k and q interpolation.

Parameters:
  • A (ndarray, shape (nbnd, nawf, nk), complex) – PAO projections on the coarse (EPW nscf) k-grid.

  • HRs (ndarray, shape (nawf, nawf, n1, n2, n3, nspin), complex) – PAO Hamiltonian (eV).

  • kpts_cryst (ndarray, shape (nk, 3)) – Coarse k-points (crystal coordinates).

  • bg (ndarray, shape (3, 3)) – Reciprocal (rows, 2 pi/alat) and direct (rows, alat) lattice vectors.

  • at (ndarray, shape (3, 3)) – Reciprocal (rows, 2 pi/alat) and direct (rows, alat) lattice vectors.

  • alat (float) – Lattice parameter (bohr).

  • cell_volume (float) – Unit-cell volume (bohr^3).

  • coupling_dir (str) – EPW directory with the .epb files.

  • qgrid_coarse (sequence of int) – Coarse (ph.x) q-grid.

  • ng (sequence of int) – Coarse k-grid.

  • masses_amu (ndarray, shape (nat,)) – Atomic masses (amu), one per atom.

  • nelec (float) – Valence electrons (locates the gap for the mid-gap Fermi level).

  • nk_dense (int, optional) – Dense k- and q-grids per axis; nk_dense must be a multiple of nq_dense (EPW tutorial: 12 and 6).

  • nq_dense (int, optional) – Dense k- and q-grids per axis; nk_dense must be a multiple of nq_dense (EPW tutorial: 12 and 6).

  • omega_ev (tuple(float, float, float), optional) – Photon energies (min, max, step) (eV), EPW omegamin/omegamax/omegastep.

  • temps_k (sequence of float, optional) – Temperatures (K).

  • degauss_ev (float, optional) – Smearing of the energy-conserving delta (eV), EPW degaussw.

  • adaptive_smearing (float, optional) – Adaptive smearing (Yates et al.; 0.7 is the usual Gaussian prefactor): the width of every (k, i, j) pair is adaptive_smearing * sqrt(|v_i(k) - v_j(k+q)|^2 dk^2 + |v_j(k+q)|^2 dq^2), floored at min_degauss_ev, from the group velocities and the spacings of the dense k- and q-grids (pair_widths()); the direct term uses the k part alone. None keeps the fixed degauss_ev; the Kramers-Kronig direct term keeps kk_degauss_ev.

  • min_degauss_ev (float, optional) – Floor of the adaptive widths (eV).

  • fsthick_ev (float, optional) – Window around the Fermi level for initial, final and intermediate states (eV), EPW fsthick.

  • fermi_energy_ev (float or 'intrinsic', optional) – Fermi level on the energy scale of HRs (eV); None puts it mid-gap (EPW efermi_read) and 'intrinsic' uses the charge-neutral level of each temperature (intrinsic_fermi_levels()), which sets the density of thermally excited carriers (free-carrier absorption). The fsthick window stays centred mid-gap either way.

  • etas_ev (sequence of float, optional) – Intermediate-state broadenings (eV); EPW’s nine values by default.

  • eps_acoustic_cm (float, optional) – Phonons below this energy (cm^-1) are skipped (EPW eps_acoustic).

  • refractive_index (float, ndarray, (omega_ev, n) pair or None, optional) – Real refractive index of alpha = omega Im eps / (n c): a constant (default 3.4, the EPW tutorial value for Si; None means the same), n on the photon grid, or a pair (omega_ev, n) interpolated on it, e.g. external_refractive_index() of the dielectric_tensor run that provides direct_dielectric. The emissivity does not use it (it works with the full dielectric function).

  • nonlocal_velocity (None) – Removed (October 2026): the non-local pseudopotential term double counts \(V_{\rm NL}\), which the PAO Hamiltonian already contains; any value other than None raises.

  • position_dipoles (DataController, optional) – When given, adds the position dipoles of the PAO orbitals to the velocity operator, \(i[H, \mathbf d(\mathbf k)]\) (position_dipole_operator()): the intra-atomic \(s\)-\(p\), \(p\)-\(d\) dipoles that \(\partial_{\mathbf k} H\) lacks, e.g. the direct transitions between the conduction bands of doped Si.

  • position_dipole_level ({'full', 'intra-atomic'}, optional) – Löwdin-orthogonalised dipoles of the whole basis (default) or the on-site blocks of the atomic orbitals only.

  • kk_omega_max_ev (float, optional) – Also compute the direct Im eps over all PAO bands on [0, kk_omega_max_ev] (same step), the input of the Kramers-Kronig real part used by thermal_emissivity(). About 10 eV: the PAO spectrum above that includes transitions into poorly projected (shifted) bands that violate the f-sum rule (check f_sum_ratio of thermal_emissivity()).

  • kk_degauss_ev (float, optional) – Smearing (eV) of that wide-range direct term (default 0.1). The real part is smooth, but the Kramers-Kronig transform of an under-sampled, weakly smeared spectrum oscillates (even below zero) and spoils the reflectivity; it also smooths the direct term the emissivity uses above the gap.

  • scissor_ev (float or callable, optional) – Rigid shift (eV) of the conduction bands (scissor operator), or T (K) -> Delta(T) (varshni_shift()): the Varshni temperature dependence on top of the Hamiltonian’s own gap, for a HRs that already has the 0 K gap (eACBN0 electrons, see Notes).

  • target_gap_ev (float or callable, optional) – Indirect gap (eV) to reproduce instead of the DFT one: a number (e.g. the experimental gap, or the dense-grid gap of an eACBN0 PAO Hamiltonian from pao_band_gaps()) or T (K) -> E_g(T) (varshni_gap()). The scissor is \(\Delta(T) = E_g^{target}(T) - E_g^{DFT}\); the coupling and the wavefunctions stay those of the DFT (DFPT) calculation.

  • scissor_velocity ({'renormalized', 'ks'}, optional) – Velocities of the scissor-corrected Hamiltonian (scissor_velocities()): Levine-Allan renormalized (default) or the Kohn-Sham ones (EPW’s scissor).

  • screening_eps (float, optional) – Static dielectric constant that should screen the coupling (e.g. the measured one, 11.94 for Si). When given, every matrix element is rescaled by \(\epsilon^{DFT}(|q|)/\epsilon^{target}(|q|)\) (Poncé et al. 2018, Resta model; coupling_screening). None (default) keeps the DFPT screening.

  • screening_eps_dft (float, optional) – Dielectric constant of the DFPT run that screened the coupling; None takes the isotropic average of the tensor in the .epb files.

  • spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.

  • sym_rots (optional) – Point-group rotations (read_nscf 's_cryst'), atomic positions and labels; fold the dense q-grid to its irreducible wedge. Only the polarisation average is then exact, and it is returned in all three components of eps2_indirect; pass sym_rots=None for the resolved diagonal components.

  • tau_cryst (optional) – Point-group rotations (read_nscf 's_cryst'), atomic positions and labels; fold the dense q-grid to its irreducible wedge. Only the polarisation average is then exact, and it is returned in all three components of eps2_indirect; pass sym_rots=None for the resolved diagonal components.

  • species (optional) – Point-group rotations (read_nscf 's_cryst'), atomic positions and labels; fold the dense q-grid to its irreducible wedge. Only the polarisation average is then exact, and it is returned in all three components of eps2_indirect; pass sym_rots=None for the resolved diagonal components.

  • orbital_positions (ndarray, shape (nawf, 3), optional) – PAO orbital centres (pair-resolved Wigner-Seitz sums and the intersite position term of the velocity); tau_cryst is then required.

  • ispin (int, optional) – Spin channel of HRs.

  • kblock (int, optional) – Dense k-points per task.

  • comm (mpi4py communicator, optional) – MPI.COMM_WORLD by default; the (q, k-block) tasks are distributed over its ranks.

  • allow_missing_long_range (bool, optional) – Run a polar material without the long-range dipole term instead of raising.

  • coupling_source ({'epw', 'dfpt'}, optional) – 'epw' reads EPW’s .epb files from coupling_dir; 'dfpt' computes the coarse vertex from the ph.x outputs in coupling_dir and the nscf wavefunctions of save_dir (prepare_dense_vertex()).

  • save_dir – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • pseudo_dir – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • prefix – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • basis – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • unfold – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • basis_shells – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • unfold_tol – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • cache_dir – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • cache_tag – coupling_source='dfpt' and cache options of prepare_dense_vertex().

  • long_range (LongRangeModel, optional) – Polar crystals: subtract the analytic dipole/quadrupole coupling on the coarse grid and restore it at every dense q (LongRangeModel); the phonons must be built with the same model (phonon_at_q=None or phonon_interp_from_dyn() with long_range).

Returns:

omega_ev (nomega,); eps2_indirect and eps2_indirect_lorentz (ntemp, neta, 3, nomega); eps2_direct and eps2_direct_lorentz (ntemp, 3, nomega); alpha_cm (ntemp, neta, nomega) (direct + indirect, polarisation averaged, Gaussian delta); fermi_energy_ev, indirect_gap_ev, direct_gap_ev, etas_ev, temps_k, nk_dense, nq_dense, bands (window band indices), fermi_levels_ev (ntemp,), scissor_ev, indirect_gap_ev_t, direct_gap_ev_t (ntemp,) (scissor-corrected; the scalar indirect_gap_ev/direct_gap_ev are those of the first temperature and *_gap_dft_ev the uncorrected ones), scissor_velocity, coupling_screening ('none' or 'ponce-resta', then also the screening_* constants and factors of summary()); with kk_omega_max_ev also omega_kk_ev and eps2_direct_wide (ntemp, 3, nomega_kk).

Return type:

dict

Raises:

ValueError – If the grids are incommensurate or no gap is found for the mid-gap Fermi level, or screening_eps is given for couplings without a dielectric tensor and no screening_eps_dft.

Notes

The workflow mirrors EPW’s lindabs:

  1. build g(R_e, R_p) and the phonon interpolator from the coarse EPW data;

  2. diagonalise the PAO Hamiltonian on the dense k-grid and evaluate the band velocities there (one copy per node);

  3. for every irreducible dense q (star-weighted) and every block of dense k, interpolate the coupling, take k+q on the grid, and accumulate indirect_absorption_kernel();

  4. add the direct term, direct_absorption_kernel(), once.

The irreducible-q reduction leaves the polarisation-averaged spectrum unchanged, but not the individual components (each star is represented by a single orientation of q), so with sym_rots the indirect components are replaced by their average.

With screening_eps the coupling at each dense q is multiplied by \(\epsilon^{DFT}(|\mathbf q|)/\epsilon^{target}(|\mathbf q|)\), with \(|\mathbf q|\) the shortest image of q. The factor depends on \(|\mathbf q|\) only, so the irreducible-q reduction stays exact. For Si (12.97 -> 11.94) \(|g|^2\) grows by 18 % at \(\Gamma\) and 2 % at X.

PAOFLOW.elphon.phonon_assisted_absorption.thermal_emissivity(results, thickness_m, angles_deg=(0.0, 30.0, 60.0), ntheta=90, eta_ev=0.05, taper_ev=0.1, direct_dielectric=None, direct_scissor='same')[source]#

Spectral and total hemispherical emissivity of a slab at each temperature.

Parameters:
  • results (dict) – Output of phonon_assisted_absorption_dense_q(), run with fermi_energy_ev='intrinsic' and either kk_omega_max_ev (keys omega_kk_ev, eps2_direct_wide) or together with direct_dielectric.

  • thickness_m (float) – Slab thickness (m); inf gives the opaque half-space.

  • angles_deg (sequence of float, optional) – Emission angles (degrees) of the directional spectra.

  • ntheta (int, optional) – Polar-angle samples of the hemispherical integral.

  • eta_ev (float, optional) – Intermediate-state broadening of the phonon-assisted term (closest computed value).

  • taper_ev (float, optional) – Width (eV) of the cosine taper that switches the phonon-assisted term off just below the direct gap.

  • direct_dielectric (tuple of ndarray, optional) – (omega_ev, eps1, eps2) of the direct (independent-particle) dielectric function from a separate, better-converged calculation: PAOFLOW’s dielectric_tensor on the extended basis with the non-local velocity (read_direct_dielectric()). eps1/eps2 have shape (nomega_d,) or (ncomp, nomega_d) (averaged); eps1 includes the vacuum 1 and the grid (uniform) must cover results['omega_ev']. When given, the wide-range direct term of results is not used. A scissor of results (scissor_ev, scissor_velocity) is applied to it too (scissor_shift_dielectric()), as set by direct_scissor.

  • direct_scissor ({'same', 'thermal', 'none'}, float or sequence of float, optional) –

    Rigid shift of direct_dielectric at each temperature:

    • 'same' (default): the scissor Delta(T) of the run, when the external spectrum shares the gap error of the Hamiltonian (PBE optics with PBE electrons);

    • 'thermal': only its temperature-dependent part Delta(T) - Delta(0) (results['scissor_0k_ev']), when the external spectrum already has the right 0 K direct gap and the scissor corrects the indirect gap only (eACBN0 Si: direct gap 3.44 eV, indirect gap 0.22 eV too high);

    • 'none': no shift;

    • explicit shifts (eV), one value or one per temperature.

    The taper below the direct gap always follows the run’s own (scissor-corrected) direct gap direct_gap_ev_t, where its phonon-assisted term diverges.

Returns:

omega_ev (nomega,), temps_k (ntemp,), eps1, eps2, hemispherical_slab, hemispherical_opaque (ntemp, nomega), directional_slab (ntemp, nangle, nomega), total_slab, total_opaque, planck_coverage (ntemp,), thickness_m, angles_deg, eta_ev, direct_source ('external' or 'kramers-kronig'), with direct_dielectric also direct_scissor (the mode) and direct_scissor_ev (ntemp,) (the shifts applied to it), direct_onset_ev, direct_gap_h_ev, and, when results carries nelec and cell_volume_bohr3, f_sum_ratio (ntemp,): the f-sum \(\int \omega\, \varepsilon_2\, d\omega\) of the direct spectrum divided by \(\pi \omega_p^2 / 2\) of all valence electrons (close to 1 for a complete, physical spectrum).

Return type:

dict

Raises:
  • NotImplementedError – For a metal (no gap): the intraband (Drude) term is not included.

  • KeyError – If neither a wide-range direct term nor direct_dielectric is given, or direct_scissor='thermal' without results['scissor_0k_ev'].

  • ValueError – If direct_dielectric does not cover the photon-energy grid, or for an unknown direct_scissor.

Notes

For every temperature \(T\) the polarisation-averaged dielectric function is assembled from a direct part and the phonon-assisted \(\varepsilon_2^{ind}(\omega, T)\), which is tapered off by \(w(\omega)\) just below the direct gap, where its second-order amplitude diverges.

  • Without direct_dielectric: \(\varepsilon_2 = \varepsilon_2^{dir} + w\,\varepsilon_2^{ind}\), with the direct term over all PAO bands, and \(\varepsilon_1\) by Kramers-Kronig (kramers_kronig_eps1()).

  • With direct_dielectric (\(\varepsilon^{ext} = \varepsilon_1^{ext} + i\varepsilon_2^{ext}\)):

    \[\begin{split}\varepsilon_2 &= w\,(\varepsilon_2^{dir} + \varepsilon_2^{ind}) + (1 - w)\,\varepsilon_2^{ext}, \\ \varepsilon_1 &= \varepsilon_1^{ext} + \mathrm{KK}[w\,\varepsilon_2^{ind}] - 1,\end{split}\]

    i.e. the external spectrum above the direct gap and for the real part, and this run’s direct term (Gaussian, window bands) plus the phonon-assisted term below it. The broadening tails of the external spectrum (Drude-Lorentz, delta of dielectric_tensor) would otherwise add a sub-gap absorption orders of magnitude larger than the phonon-assisted and free-carrier one; \(\varepsilon_1\) is insensitive to that broadening.

The slab absorptance (slab_directional_absorptance()) is the emissivity by Kirchhoff’s law; its hemispherical average and the Planck-weighted total at the same temperature,

\[\varepsilon(T) = \frac{\int \varepsilon(\omega, T)\, B(\omega, T)\, d\omega} {\int B(\omega, T)\, d\omega},\]

are taken over the photon-energy grid; planck_coverage is the fraction of the blackbody spectrum that the grid covers.

PAOFLOW.elphon.phonon_assisted_absorption.direct_scissor_shifts(results, direct_scissor='same', scissors=None)[source]#

Shift (eV) of an external direct dielectric function at each temperature.

Parameters:
Returns:

Shifts (eV); 'same' returns the run’s scissor unchanged.

Return type:

ndarray, shape (ntemp,)

Raises:
  • KeyError – For 'thermal' when results has no scissor_0k_ev (outputs of older runs: pass the shifts explicitly, scissor_ev - Delta(0)).

  • ValueError – For an unknown mode or a wrong number of explicit shifts.

PAOFLOW.elphon.phonon_assisted_absorption.dielectric_onset_ev(omega_ev, eps2, fraction=0.05)[source]#

Onset of an absorption spectrum: lowest energy where eps2 reaches a fraction of its maximum.

Parameters:
  • omega_ev (ndarray, shape (nomega,)) – Photon energies (eV).

  • eps2 (ndarray, shape (nomega,)) – Imaginary part of the dielectric function.

  • fraction (float, optional) – Threshold relative to max(eps2) (default 5 %: on PAOFLOW’s Si spectra, Drude-Lorentz delta = 0.1 eV, it lands on the direct gap within 0.04 eV).

Returns:

The onset energy (eV); nan if eps2 has no positive value.

Return type:

float

PAOFLOW.elphon.phonon_assisted_absorption.check_direct_dielectric_gap(results, direct_dielectric, tol_ev=0.3, fraction=0.05)[source]#

Warn when an external direct dielectric function does not match the Hamiltonian’s direct gap.

Parameters:
  • results (dict) – Output of phonon_assisted_absorption_dense_q() (uses direct_gap_dft_ev, the unshifted direct gap of the Hamiltonian, or direct_gap_ev when the former is absent).

  • direct_dielectric (tuple of ndarray) – (omega_ev, eps1, eps2) as read by read_direct_dielectric() (eps2 may be (ncomp, nomega); its average is used).

  • tol_ev (float, optional) – Largest accepted difference between the onset of eps2 and the gap.

  • fraction (float, optional) – Onset threshold of dielectric_onset_ev() (5 % of the maximum: on PAOFLOW’s Si spectrum, Drude-Lorentz delta = 0.1 eV, this lands on the direct gap within 0.01 eV).

Returns:

onset_ev, direct_gap_ev and consistent (bool).

Return type:

dict

Notes

The external spectrum is shifted only by the scissor \(\Delta(T)\) of the run. A dielectric_tensor run of another functional than the one behind HRs (PBE optics with eACBN0 electrons, or the reverse) would be placed at the wrong energy: the gap difference between the two functionals is not a scissor of the run. The Drude-Lorentz tails of the external spectrum make the onset approximate, hence the generous tolerance and a warning rather than an error.

PAOFLOW.elphon.phonon_assisted_absorption.external_refractive_index(direct_dielectric)[source]#

Real refractive index of a dielectric function, (omega_ev, n).

Parameters:

direct_dielectric (tuple of ndarray) – (omega_ev, eps1, eps2) as read by read_direct_dielectric() (eps1/eps2 of shape (nomega,) or (ncomp, nomega), averaged).

Returns:

omega_ev, n – Photon energies and \(n = \mathrm{Re}\sqrt{\varepsilon_1 + i\varepsilon_2}\), the refractive_index input of phonon_assisted_absorption_dense_q().

Return type:

ndarray, shape (nomega,)

PAOFLOW.elphon.phonon_assisted_absorption.read_direct_dielectric(outdir, components=('xx', 'yy', 'zz'))[source]#

Read the diagonal dielectric function written by PAOFLOW’s dielectric_tensor.

Parameters:
  • outdir (str) – Output directory of the dielectric_tensor run (files epsr_<c>.dat and epsi_<c>.dat, photon energy in eV in the first column). Typically a separate run on the extended basis with gradient_and_momenta(position_dipoles=True).

  • components (sequence of str, optional) – Diagonal components to read (default xx, yy, zz).

Returns:

omega_ev, eps1, eps2 – Photon energies (nomega,) and the real (vacuum 1 included) and imaginary parts (ncomp, nomega), the direct_dielectric input of thermal_emissivity().

Return type:

ndarray

Raises:

ValueError – If the components use different energy grids.

PAOFLOW.elphon.phonon_assisted_absorption.write_emissivity_outputs(emissivity, outdir)[source]#

Write the thermal-emissivity spectra and totals.

Parameters:
Returns:

Paths written: per temperature eps_<T>K.dat (photon energy, Re and Im eps), emish_<T>K.dat (photon energy, slab and opaque hemispherical emissivity) and emis_th<deg>_<T>K.dat (photon energy, directional slab emissivity), plus emist.dat (temperature, total slab and opaque emissivity, Planck coverage) and emissivity.npz.

Return type:

list of str

PAOFLOW.elphon.phonon_assisted_absorption.write_absorption_outputs(results, outdir)[source]#

Write the absorption spectra in EPW’s file layout plus an .npz archive.

Parameters:
Returns:

Paths written: per temperature epsilon2_indabs_<T>K.dat and epsilon2_indabs_lorenz<T>K.dat (photon energy, polarisation-averaged Im eps for each eta), epsilon2_dirabs_<T>K.dat (photon energy, Im eps along x, y, z and their average, Gaussian and Lorentzian) and alpha_<T>K.dat (photon energy, absorption coefficient in cm^-1 for each eta), plus absorption.npz.

Return type:

list of str